mirror of
https://github.com/stablyai/orca.git
synced 2026-11-16 10:58:10 +00:00
182 lines
6.2 KiB
TypeScript
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
|
|
})
|
|
}
|