Files
orca/src/shared/plugins/workers/plugin-host-api-workspace-methods.ts
T

182 lines
6.2 KiB
TypeScript

import { z } from 'zod'
import { isTuiAgent } from '../../agent-launch/catalog/tui-agent-config'
import { PLUGIN_COMMAND_ALIAS_ACTION_IDS } from '../contributions/plugin-command-actions'
import { spec, WORKER_ONLY } from './plugin-host-method-spec'
/**
* Orca state and actions a full-access worker cannot reach from Node: its workspaces, terminals
* and agents. Each runs the runtime method the `orca` CLI runs, on the host that owns the
* workspace (local, WSL or SSH), so a mod acts exactly as `orca terminal create` would.
*/
export const PLUGIN_WORKSPACE_LIST_LIMIT = 500
export const PLUGIN_TERMINAL_READ_MAX_LINES = 2000
const ID_MAX = 1024
const TEXT_MAX = 4096
const workspaceId = z.string().min(1).max(ID_MAX)
const terminalId = z.string().min(1).max(ID_MAX)
const workspaceListParams = z.strictObject({}).optional()
const workspaceListResult = z.object({
workspaces: z
.array(
z.object({
/** What every other workspace method takes; it names the host too, so a workspace that two
* hosts both have is never ambiguous. */
id: workspaceId,
/** `folder`: a plain folder, with no Git branch. */
kind: z.enum(['worktree', 'folder']),
name: z.string().max(512),
/** The path on the host that owns it, which may be WSL or an SSH machine. */
path: z.string().max(ID_MAX),
branch: z.string().max(512).nullable(),
/** The execution host; null for this machine on hosts that do not record one. */
hostId: z.string().max(ID_MAX).nullable()
})
)
.max(PLUGIN_WORKSPACE_LIST_LIMIT),
/** More workspaces exist than the list holds. */
truncated: z.boolean()
})
const workspaceOpenParams = z.strictObject({ workspaceId })
const workspaceOpenResult = z.object({ opened: z.literal(true) })
const terminalCreateParams = z.strictObject({
workspaceId,
title: z.string().min(1).max(512).optional(),
/** Run in the new terminal's shell once it starts. */
command: z.string().min(1).max(TEXT_MAX).optional()
})
const terminalCreateResult = z.object({ terminalId })
const terminalReadParams = z.strictObject({
terminalId,
/** The newest lines to return; default 200. */
maxLines: z.number().int().min(1).max(PLUGIN_TERMINAL_READ_MAX_LINES).optional()
})
const terminalReadResult = z.object({
/** Plain text, oldest first, without escape sequences. */
lines: z.array(z.string()).max(PLUGIN_TERMINAL_READ_MAX_LINES),
/** Older output exists beyond `lines`. */
truncated: z.boolean()
})
const agentLaunchParams = z.strictObject({
workspaceId,
/** An agent Orca knows: `claude`, `codex`, `gemini`, ... */
agent: z.string().min(1).max(64).refine(isTuiAgent, 'unknown agent'),
/** Sent to the agent as its first message. */
prompt: z.string().min(1).max(TEXT_MAX).optional()
})
const agentLaunchResult = z.object({
/** The agent's terminal, as `terminal.read` and `terminal.sendText` take it. */
terminalId
})
/** A `/`-separated path inside the workspace: not absolute, no `..`, no drive letter. */
export function isPluginWorkspaceRelativePath(path: string): boolean {
const segments = path.split(/[\\/]/)
return (
!/^[a-z]:/i.test(path) &&
segments[0] !== '' &&
segments.every((segment) => segment !== '..') &&
segments.some((segment) => segment !== '' && segment !== '.')
)
}
const editorOpenParams = z.strictObject({
workspaceId,
/** Relative to the workspace, `/`-separated; it must stay inside it. */
path: z
.string()
.min(1)
.max(ID_MAX)
.refine(isPluginWorkspaceRelativePath, 'path must be relative and inside the workspace')
})
const editorOpenResult = z.object({ opened: z.literal(true) })
const commandsRunParams = z.strictObject({
/** A built-in action, the same list `contributes.commands[].action` takes. */
action: z.enum(PLUGIN_COMMAND_ALIAS_ACTION_IDS)
})
const commandsRunResult = z.object({ ran: z.literal(true) })
export const PLUGIN_WORKSPACE_ACTIONS_API = {
'workspace.list': spec({
summary: 'Lists every workspace, Git worktrees and folders, on every host Orca reaches.',
since: 3,
scope: 'any-workspace',
capability: 'workspace:read',
mutation: false,
surfaces: WORKER_ONLY,
params: workspaceListParams,
result: workspaceListResult
}),
'workspace.open': spec({
summary:
'Shows a workspace in Orca, as clicking it in the sidebar does; a folder workspace needs the desktop app.',
since: 3,
scope: 'any-workspace',
capability: 'workspace:write',
mutation: true,
surfaces: WORKER_ONLY,
params: workspaceOpenParams,
result: workspaceOpenResult
}),
'terminal.create': spec({
summary: 'Opens a terminal in a workspace, optionally running a command, in the background.',
since: 3,
scope: 'any-workspace',
capability: 'terminal:send',
mutation: true,
surfaces: WORKER_ONLY,
params: terminalCreateParams,
result: terminalCreateResult
}),
'terminal.read': spec({
summary: `Reads a terminal's newest output as plain text, at most ${PLUGIN_TERMINAL_READ_MAX_LINES} lines.`,
since: 3,
scope: 'explicit-terminal',
capability: 'terminal:read',
mutation: false,
surfaces: WORKER_ONLY,
params: terminalReadParams,
result: terminalReadResult
}),
'agent.launch': spec({
summary:
"Starts an agent's CLI in a new terminal of a workspace, in the background, and returns as soon as it starts; a `prompt` is sent once the agent is ready.",
since: 3,
scope: 'any-workspace',
capability: 'agent:launch',
mutation: true,
surfaces: WORKER_ONLY,
params: agentLaunchParams,
result: agentLaunchResult
}),
'editor.open': spec({
summary:
"Opens a file of a workspace in an editor tab of Orca's window; desktop app only. `workspace.open` shows the workspace.",
since: 3,
scope: 'any-workspace',
capability: 'workspace:write',
mutation: true,
surfaces: WORKER_ONLY,
params: editorOpenParams,
result: editorOpenResult
}),
'commands.run': spec({
summary:
"Runs one of Orca's built-in actions in its window, never a plugin's replacement of it; desktop app only.",
since: 3,
scope: 'desktop',
capability: 'workspace:write',
mutation: true,
surfaces: WORKER_ONLY,
params: commandsRunParams,
result: commandsRunResult
})
}