478 lines
22 KiB
TypeScript
478 lines
22 KiB
TypeScript
/**
|
||
* Eight model-facing tools for the agent-owned sidebar terminals (tmux
|
||
* semantics: spawn-and-detach, send-keys, read, wait-for, resize, signal,
|
||
* close, list). Each tool binds to the calling agent's session through
|
||
* `exec.agent.session.id`, so the model never passes a sessionId — the
|
||
* agent identity is the scope.
|
||
*
|
||
* Conventions (per plugin-development-guide.md §3):
|
||
* C1 — parameters schema-validated before `execute` runs.
|
||
* C4 — `execute` returns one canonical JSON value; `render` is a separate
|
||
* pure text projection.
|
||
* C6 — `exec.signal.throwIfAborted()` before any spawn.
|
||
* C10 — no UI/transport vocabulary in the canonical value.
|
||
*/
|
||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||
import type { ToolRunContext } from '@deepseek-ai/dsh-tools'
|
||
import type { ContentBlock } from '@deepseek-ai/dsh-llm'
|
||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||
import type { Context } from './context-types.ts'
|
||
import {
|
||
AgentPtyRegistry,
|
||
ALLOWED_SIGNALS,
|
||
type AgentTerminalSignal,
|
||
type AgentTerminalSnapshot,
|
||
} from './agent-pty.ts'
|
||
|
||
/** Maximum UTF-8 bytes of one `terminal_read` result text. */
|
||
const READ_BYTE_LIMIT = 256 * 1024
|
||
|
||
/**
|
||
* Bound a string to a byte limit, marking truncation. Truncation never
|
||
* splits a multi-byte UTF-8 sequence: when the byte cap lands inside one,
|
||
* the walk-back retreats to the sequence's leading byte so the retained
|
||
* prefix decodes cleanly (a split would decode to U+FFFD).
|
||
* @internal exported for the unit tests, like {@link snapshotOf}.
|
||
*/
|
||
export function boundBytes(text: string, maxBytes: number): { text: string; truncated: boolean } {
|
||
const buf = Buffer.from(text, 'utf8')
|
||
if (buf.byteLength <= maxBytes) return { text, truncated: false }
|
||
// The byte at `end` is a continuation byte (10xxxxxx) exactly when the
|
||
// character that started before `end` spills past the cap. Stop at the
|
||
// first non-continuation byte — the retained prefix is then intact.
|
||
let end = maxBytes
|
||
while (end > 0 && ((buf[end] ?? 0) & 0xc0) === 0x80) end -= 1
|
||
return { text: buf.subarray(0, end).toString('utf8'), truncated: true }
|
||
}
|
||
|
||
/** Pure text projection helper (the canonical value is already structured). */
|
||
function textRender<T>(fn: (value: T) => string): (_args: unknown, value: unknown) => ContentBlock[] {
|
||
return (_args, value) => [{ type: 'text', text: fn(value as T) }]
|
||
}
|
||
|
||
/** Extract the calling agent or throw the canonical "no agent" error. */
|
||
function requireAgent(agent: Agent | undefined): Agent {
|
||
if (agent === undefined) {
|
||
throw new Error('sidebar terminal tools require an initiating agent')
|
||
}
|
||
return agent
|
||
}
|
||
|
||
/** Resolve the calling agent's session id (the registry scope + ownership key). */
|
||
function sessionIdOf(exec: ToolRunContext): string {
|
||
return requireAgent(exec.agent).session.id
|
||
}
|
||
|
||
/**
|
||
* Register the eight terminal tools against the host tool registry. The
|
||
* `resolveCwd` callback threads the live session cwd (authoritative from the
|
||
* session store, falling back to the process cwd) so a freshly-created
|
||
* terminal lands in the right directory without the model passing it.
|
||
* Every uuid-keyed tool first asserts the terminal belongs to the calling
|
||
* session (`registry.assertOwned`), so one agent can never reach another
|
||
* session's terminals.
|
||
* @param ctx - host plugin context (carries the tools service).
|
||
* @param registry - the agent-owned terminal registry.
|
||
* @param resolveCwd - live cwd resolver for one session id.
|
||
* @returns a disposer that unregisters all eight tools (the caller gates
|
||
* registration on the side-card setting and calls this to turn them off).
|
||
*/
|
||
export function registerTools(
|
||
ctx: Context,
|
||
registry: AgentPtyRegistry,
|
||
resolveCwd: (sessionId: string) => string,
|
||
): () => void {
|
||
const disposers: Array<() => void> = []
|
||
const register = (tool: ReturnType<typeof defineTool>): void => {
|
||
disposers.push(ctx.tools.register(tool))
|
||
}
|
||
|
||
register(defineTool({
|
||
name: 'terminal_create',
|
||
description:
|
||
'Open a persistent terminal in the sidebar and run a command in it. '
|
||
+ 'Spawns an interactive shell, writes the command + Enter to its stdin, and returns a uuid handle. '
|
||
+ 'The terminal stays alive after the command exits — send more input with terminal_send (set submit=true to run a command), '
|
||
+ 'read output with terminal_read, send Ctrl+C with terminal_signal(signal="SIGINT"), '
|
||
+ 'and close it with terminal_close when done. '
|
||
+ 'Use this for interactive shells, REPLs, long-running dev servers, '
|
||
+ 'or any work that needs persistent terminal state across tool calls. '
|
||
+ 'The terminal appears as a new tab in the right sidebar (titled with the `title` you provide) so the user can watch and interact with it.',
|
||
parameters: {
|
||
title: {
|
||
type: 'string',
|
||
required: true,
|
||
description: 'Short human-readable label for the terminal tab (e.g. "dev server", "python repl").',
|
||
},
|
||
command: {
|
||
type: 'string',
|
||
required: true,
|
||
description: 'Shell command to run in the freshly spawned shell. The host appends an Enter key automatically — do NOT include a trailing newline. Pass "" to open a bare shell with no command.',
|
||
},
|
||
},
|
||
output: {
|
||
schema: {
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
uuid: { type: 'string', required: true, description: 'Opaque handle for the new terminal. Pass to terminal_send / terminal_read / terminal_resize / terminal_signal / terminal_close.' },
|
||
title: { type: 'string', required: true, description: 'The title you provided (echoed for confirmation).' },
|
||
},
|
||
},
|
||
render: textRender((v: { uuid: string; title: string }) =>
|
||
`Opened terminal "${v.title}" (uuid: ${v.uuid}). The sidebar tab appears automatically; use terminal_read to see output and terminal_send (with submit=true) to run more commands.`,
|
||
),
|
||
},
|
||
execute: (args: { title: string; command: string }, exec) => {
|
||
exec.signal.throwIfAborted()
|
||
const sessionId = sessionIdOf(exec)
|
||
const cwd = resolveCwd(sessionId)
|
||
const uuid = registry.create(sessionId, args.title, args.command, cwd, 80, 24)
|
||
return Promise.resolve({ uuid, title: args.title })
|
||
},
|
||
}))
|
||
|
||
register(defineTool({
|
||
name: 'terminal_list',
|
||
description:
|
||
'List every terminal the current agent has opened in this session. Returns each terminal\'s uuid, title, '
|
||
+ 'the command it was started with, and whether the top-level process has exited (with exit code/signal if so). '
|
||
+ 'Use this to recover state after a long sequence of tool calls or to find a terminal you forgot to close.',
|
||
parameters: {},
|
||
output: {
|
||
schema: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
uuid: { type: 'string', required: true },
|
||
title: { type: 'string', required: true },
|
||
command: { type: 'string', required: true },
|
||
exited: { type: 'boolean', required: true },
|
||
exitCode: { oneOf: [{ type: 'integer' }, { type: 'null' }] },
|
||
exitSignal: { oneOf: [{ type: 'string' }, { type: 'null' }] },
|
||
},
|
||
},
|
||
},
|
||
render: (_args, value) => {
|
||
const list = value as AgentTerminalSnapshot[]
|
||
if (list.length === 0) return [{ type: 'text', text: 'No agent terminals open in this session.' }]
|
||
const lines = list.map((t) => {
|
||
const status = t.exited
|
||
? `exited (code ${t.exitCode ?? '?'}, signal ${t.exitSignal ?? 'none'})`
|
||
: 'running'
|
||
return ` ${t.uuid} "${t.title}" [${status}] $ ${t.command}`
|
||
})
|
||
return [{ type: 'text', text: `Agent terminals in this session:\n${lines.join('\n')}` }]
|
||
},
|
||
},
|
||
execute: (_args, exec) => {
|
||
const sessionId = sessionIdOf(exec)
|
||
return Promise.resolve(registry.list(sessionId))
|
||
},
|
||
}))
|
||
|
||
register(defineTool({
|
||
name: 'terminal_send',
|
||
description:
|
||
'Send raw text (keystrokes) to a terminal opened with terminal_create — tmux send-keys semantics. '
|
||
+ 'The text is written verbatim to the pty stdin. '
|
||
+ 'To submit a command, set submit=true (appends an Enter key); do NOT put "\\n" or "\\r" in the text yourself. '
|
||
+ 'To send Ctrl+C (interrupt the running command), use the terminal_signal tool with signal="SIGINT" — do NOT try to send the control character "\\u0003" as text. '
|
||
+ 'Use terminal_signal with signal="SIGTSTP" for Ctrl+Z (suspend) as well. '
|
||
+ 'This tool does NOT wait for the command to finish or for output to settle — pair with terminal_read to observe the result. '
|
||
+ 'Throws if the terminal has exited.',
|
||
parameters: {
|
||
uuid: {
|
||
type: 'string',
|
||
required: true,
|
||
description: 'Terminal uuid from terminal_create or terminal_list.',
|
||
},
|
||
text: {
|
||
type: 'string',
|
||
required: true,
|
||
description: 'UTF-8 text to write to the terminal stdin (verbatim, no shell escaping). Do not include trailing newlines — use the submit flag instead.',
|
||
},
|
||
submit: {
|
||
type: 'boolean',
|
||
description: 'Append an Enter key (carriage return) after the text to submit a command. Default: false. Set to true when sending a command to run; leave false for partial input or control sequences.',
|
||
},
|
||
},
|
||
output: {
|
||
schema: {
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
uuid: { type: 'string', required: true },
|
||
bytes: { type: 'integer', required: true, description: 'Number of UTF-8 bytes written (including the Enter key if submit was true).' },
|
||
},
|
||
},
|
||
render: textRender((v: { uuid: string; bytes: number }) =>
|
||
`Sent ${v.bytes} byte(s) to terminal ${v.uuid}.`,
|
||
),
|
||
},
|
||
execute: (args: { uuid: string; text: string; submit?: boolean }, exec) => {
|
||
exec.signal.throwIfAborted()
|
||
const sessionId = sessionIdOf(exec)
|
||
registry.assertOwned(args.uuid, sessionId)
|
||
const payload = args.submit === true ? `${args.text}\r` : args.text
|
||
registry.send(args.uuid, payload)
|
||
return Promise.resolve({ uuid: args.uuid, bytes: Buffer.byteLength(payload, 'utf8') })
|
||
},
|
||
}))
|
||
|
||
register(defineTool({
|
||
name: 'terminal_read',
|
||
description:
|
||
'Read a bounded page of retained output from an agent terminal without sending input. '
|
||
+ 'The host keeps up to ~1 MiB of scrollback; this tool returns up to 500 lines per call. '
|
||
+ 'Use `offset` to paginate forward ( 0-based from the start of the retained transcript ) or backward ( negative reads from the end, e.g. -50 reads the last 50 lines ). '
|
||
+ 'Returns `totalLines` so you know how much scrollback remains. '
|
||
+ 'Output is bounded to 256 KiB per call; longer pages are truncated with the `truncated` flag.',
|
||
parameters: {
|
||
uuid: {
|
||
type: 'string',
|
||
required: true,
|
||
description: 'Terminal uuid from terminal_create or terminal_list.',
|
||
},
|
||
offset: {
|
||
type: 'number',
|
||
description: '0-based line offset from the start of the retained transcript (default 0). Negative reads from the end (e.g. -50 = last 50 lines).',
|
||
},
|
||
count: {
|
||
type: 'number',
|
||
description: 'Maximum lines to return (default 500, hard cap 500).',
|
||
},
|
||
},
|
||
output: {
|
||
schema: {
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
text: { type: 'string', required: true, description: 'The slice of transcript for the requested page.' },
|
||
totalLines: { type: 'integer', required: true, description: 'Total lines in the retained transcript.' },
|
||
lineBegin: { type: 'integer', required: true, description: '0-based index of the first line in `text` (inclusive).' },
|
||
lineEnd: { type: 'integer', required: true, description: '0-based index of the last line in `text` (exclusive).' },
|
||
truncated: { type: 'boolean', required: true, description: 'Whether `text` was truncated to fit the 256 KiB read cap.' },
|
||
},
|
||
},
|
||
render: (_args, value) => {
|
||
const v = value as { text: string; totalLines: number; lineBegin: number; lineEnd: number; truncated: boolean }
|
||
const head = `[lines ${v.lineBegin}..${v.lineEnd} of ${v.totalLines}${v.truncated ? '; truncated to 256KiB' : ''}]`
|
||
return [{ type: 'text', text: `${head}\n${v.text}` }]
|
||
},
|
||
},
|
||
execute: (args: { uuid: string; offset?: number; count?: number }, exec) => {
|
||
exec.signal.throwIfAborted()
|
||
const sessionId = sessionIdOf(exec)
|
||
registry.assertOwned(args.uuid, sessionId)
|
||
const result = registry.read(args.uuid, args.offset, args.count)
|
||
const bounded = boundBytes(result.text, READ_BYTE_LIMIT)
|
||
return Promise.resolve({
|
||
text: bounded.text,
|
||
totalLines: result.totalLines,
|
||
lineBegin: result.lineBegin,
|
||
lineEnd: result.lineEnd,
|
||
truncated: bounded.truncated,
|
||
})
|
||
},
|
||
}))
|
||
|
||
register(defineTool({
|
||
name: 'terminal_wait_for',
|
||
description:
|
||
'Block until a substring appears in a terminal\'s retained transcript, or until the timeout elapses, or until the terminal exits — whichever happens first. '
|
||
+ 'Use this to synchronize on command completion cues ( e.g. a shell prompt, "done", "Listening on", "Build successful" ) '
|
||
+ 'without busy-polling terminal_read. '
|
||
+ 'The wait scans the FULL retained transcript (up to ~1 MiB) on every poll, so a needle that scrolled past the most recent chunk is still a match. '
|
||
+ 'Returns `found` with the line/column of the first occurrence, `timeout` if the needle did not appear in time, or `exited` if the terminal process died before the needle appeared. '
|
||
+ 'Default timeout is 10 seconds; raise it for long-running commands ( dev servers, test suites ). '
|
||
+ 'The wait is cooperative: a tool-call cancel ( or agent turn end ) aborts it immediately.',
|
||
parameters: {
|
||
uuid: {
|
||
type: 'string',
|
||
required: true,
|
||
description: 'Terminal uuid from terminal_create or terminal_list.',
|
||
},
|
||
needle: {
|
||
type: 'string',
|
||
required: true,
|
||
description: 'Substring to wait for (case-sensitive, verbatim). Must be non-empty.',
|
||
},
|
||
timeout_ms: {
|
||
type: 'number',
|
||
description: 'Maximum wait in milliseconds (default 10000, i.e. 10s). Clamped to a minimum of 100ms.',
|
||
},
|
||
},
|
||
output: {
|
||
schema: {
|
||
oneOf: [
|
||
{
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
kind: { type: 'string', required: true, const: 'found' },
|
||
needle: { type: 'string', required: true },
|
||
line: { type: 'integer', required: true, description: '0-based line index in the retained transcript where the needle first appeared.' },
|
||
column: { type: 'integer', required: true, description: '0-based column index within that line where the match starts.' },
|
||
elapsedMs: { type: 'integer', required: true, description: 'Wall-clock milliseconds from wait start to match.' },
|
||
},
|
||
},
|
||
{
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
kind: { type: 'string', required: true, const: 'timeout' },
|
||
needle: { type: 'string', required: true },
|
||
timeoutMs: { type: 'integer', required: true, description: 'The configured timeout that elapsed.' },
|
||
totalLines: { type: 'integer', required: true, description: 'Total lines retained when the timeout fired. Call terminal_read to inspect the tail.' },
|
||
},
|
||
},
|
||
{
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
kind: { type: 'string', required: true, const: 'exited' },
|
||
needle: { type: 'string', required: true },
|
||
exitCode: { oneOf: [{ type: 'integer' }, { type: 'null' }], description: 'Exit code, if known.' },
|
||
exitSignal: { oneOf: [{ type: 'string' }, { type: 'null' }], description: 'Exit signal name, if killed by a signal.' },
|
||
},
|
||
},
|
||
],
|
||
},
|
||
render: (_args, value) => {
|
||
const v = value as { kind: 'found' | 'timeout' | 'exited'; needle: string; elapsedMs?: number; timeoutMs?: number; line?: number; column?: number; exitCode?: number | null; exitSignal?: string | null }
|
||
if (v.kind === 'found') {
|
||
return [{ type: 'text', text: `Found "${v.needle}" at line ${v.line}, column ${v.column} (after ${v.elapsedMs}ms).` }]
|
||
}
|
||
if (v.kind === 'timeout') {
|
||
return [{ type: 'text', text: `Timed out after ${v.timeoutMs}ms waiting for "${v.needle}". Call terminal_read to inspect the transcript.` }]
|
||
}
|
||
const exitInfo = v.exitCode !== undefined && v.exitCode !== null ? ` (exit code ${v.exitCode})` : ''
|
||
return [{ type: 'text', text: `Terminal exited before "${v.needle}" appeared${exitInfo}.` }]
|
||
},
|
||
},
|
||
async execute(args: { uuid: string; needle: string; timeout_ms?: number }, exec) {
|
||
exec.signal.throwIfAborted()
|
||
const sessionId = sessionIdOf(exec)
|
||
registry.assertOwned(args.uuid, sessionId)
|
||
// The registry validates the needle (empty → bad-request) and returns
|
||
// the camelCase result the schema above declares directly — no
|
||
// field-by-field projection.
|
||
const timeoutMs = args.timeout_ms ?? 10_000
|
||
return await registry.waitFor(args.uuid, args.needle, timeoutMs, exec.signal)
|
||
},
|
||
}))
|
||
|
||
register(defineTool({
|
||
name: 'terminal_resize',
|
||
description:
|
||
'Resize an agent terminal\'s pty ( cols × rows ). The host clamps both to a 2..1024 sane range. '
|
||
+ 'Most shells redraw their prompt and any full-screen TUI on the next output frame. '
|
||
+ 'No-op if the terminal has exited. Returns the dimensions actually applied.',
|
||
parameters: {
|
||
uuid: { type: 'string', required: true, description: 'Terminal uuid from terminal_create or terminal_list.' },
|
||
cols: { type: 'integer', required: true, description: 'New column count ( clamped to 2..1024 ).' },
|
||
rows: { type: 'integer', required: true, description: 'New row count ( clamped to 2..1024 ).' },
|
||
},
|
||
output: {
|
||
schema: {
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
uuid: { type: 'string', required: true },
|
||
cols: { type: 'integer', required: true },
|
||
rows: { type: 'integer', required: true },
|
||
},
|
||
},
|
||
render: textRender((v: { uuid: string; cols: number; rows: number }) =>
|
||
`Resized terminal ${v.uuid} to ${v.cols}×${v.rows}.`,
|
||
),
|
||
},
|
||
execute: (args: { uuid: string; cols: number; rows: number }, exec) => {
|
||
exec.signal.throwIfAborted()
|
||
const sessionId = sessionIdOf(exec)
|
||
registry.assertOwned(args.uuid, sessionId)
|
||
const dims = registry.resize(args.uuid, args.cols, args.rows)
|
||
return Promise.resolve({ uuid: args.uuid, ...dims })
|
||
},
|
||
}))
|
||
|
||
register(defineTool({
|
||
name: 'terminal_signal',
|
||
description:
|
||
'Send a POSIX signal to an agent terminal\'s foreground process — this is how you send Ctrl+C, Ctrl+Z, etc. '
|
||
+ 'Use signal="SIGINT" for Ctrl+C (interrupt the running command), signal="SIGTERM" to request termination, '
|
||
+ 'signal="SIGKILL" to force-kill the pty, signal="SIGHUP" to hang up (many shells exit), signal="SIGTSTP" for Ctrl+Z (suspend). '
|
||
+ 'Do NOT try to send control characters (like "\\u0003") through terminal_send — use this tool instead. '
|
||
+ 'On Windows, only SIGKILL and SIGTERM are effective — others are accepted but may no-op. '
|
||
+ 'No-op if the terminal has already exited. Use terminal_close to dispose of the terminal entirely.',
|
||
parameters: {
|
||
uuid: { type: 'string', required: true, description: 'Terminal uuid from terminal_create or terminal_list.' },
|
||
signal: {
|
||
type: 'string',
|
||
required: true,
|
||
enum: ALLOWED_SIGNALS as readonly string[],
|
||
description: 'Signal to deliver: SIGINT (Ctrl+C) | SIGTERM | SIGKILL | SIGHUP | SIGTSTP (Ctrl+Z).',
|
||
},
|
||
},
|
||
output: {
|
||
schema: {
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
uuid: { type: 'string', required: true },
|
||
signal: { type: 'string', required: true },
|
||
},
|
||
},
|
||
render: textRender((v: { uuid: string; signal: AgentTerminalSignal }) =>
|
||
`Sent ${v.signal} to terminal ${v.uuid}.`,
|
||
),
|
||
},
|
||
execute: (args: { uuid: string; signal: AgentTerminalSignal }, exec) => {
|
||
exec.signal.throwIfAborted()
|
||
const sessionId = sessionIdOf(exec)
|
||
registry.assertOwned(args.uuid, sessionId)
|
||
registry.signal(args.uuid, args.signal)
|
||
return Promise.resolve({ uuid: args.uuid, signal: args.signal })
|
||
},
|
||
}))
|
||
|
||
register(defineTool({
|
||
name: 'terminal_close',
|
||
description:
|
||
'Close an agent terminal and release its process. The uuid becomes invalid for all subsequent tool calls. '
|
||
+ 'Idempotent: closing an already-closed uuid is a no-op. '
|
||
+ 'The corresponding sidebar tab is removed automatically when the host pushes the updated terminal list. '
|
||
+ 'Always close terminals you no longer need — the host keeps the pty alive until you do.',
|
||
parameters: {
|
||
uuid: { type: 'string', required: true, description: 'Terminal uuid from terminal_create or terminal_list.' },
|
||
},
|
||
output: {
|
||
schema: {
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
uuid: { type: 'string', required: true },
|
||
closed: { type: 'boolean', required: true, description: 'Whether a live terminal was actually dropped (false if the uuid was already gone).' },
|
||
},
|
||
},
|
||
render: textRender((v: { uuid: string; closed: boolean }) =>
|
||
v.closed ? `Closed terminal ${v.uuid}.` : `Terminal ${v.uuid} was already closed.`,
|
||
),
|
||
},
|
||
execute: (args: { uuid: string }, exec) => {
|
||
exec.signal.throwIfAborted()
|
||
const sessionId = sessionIdOf(exec)
|
||
registry.assertOwned(args.uuid, sessionId)
|
||
const closed = registry.close(args.uuid)
|
||
return Promise.resolve({ uuid: args.uuid, closed })
|
||
},
|
||
}))
|
||
|
||
return () => {
|
||
for (const dispose of disposers) dispose()
|
||
}
|
||
}
|