Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into feat/send-unify

Browse Source 
# Conflicts:
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/context/time-context/tests/time-context.spec.ts
#	packages/cordis/tool-cordis/src/api-catalog.ts
This commit is contained in:
Turtle
2026-07-23 20:54:48 +08:00
parent 866b543700 8833fc2b58
commit a3ad5241ba
430 changed files with 20734 additions and 5783 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/pty/tool-pty/README.md
View File

@@ -44,7 +44,7 @@ Prefix-stable while tool visibility and definitions are unchanged.
#### What the model sees
Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic task id. Results remain in session history until compaction; incremental task reads do not repeat consumed output.
Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic task id. Results remain in session history until compaction; incremental task reads do not repeat consumed output. Programmatic callers receive typed session snapshots, bounded send/read DTOs, signal and close outcomes, or `{ kind: "background", taskId }`; Native rendering preserves the text above.
#### Token effect

164
packages/pty/tool-pty/src/index.ts
View File

@@ -6,12 +6,11 @@
import { Context } from 'cordis'
import type { Agent } from '@deepseek-ai/dsh-agent'
import type { ContentBlock } from '@deepseek-ai/dsh-llm'
import { PtySessionId } from '@deepseek-ai/dsh-pty'
import type { PtySendResult, PtySessionId as PtySessionIdType, PtySignal } from '@deepseek-ai/dsh-pty'
import type {} from '@deepseek-ai/dsh-tasks'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type { ToolExecutionResult, ToolResult } from '@deepseek-ai/dsh-tools'
import type { ToolResult } from '@deepseek-ai/dsh-tools'
import { renderList, renderRead, renderSend, renderSendRead, renderSpawn } from './render.ts'
declare module '@deepseek-ai/dsh-tasks' {
@@ -50,6 +49,50 @@ interface SignalArgs extends SessionArgs {
signal: PtySignal
}
const SESSION_STATUS_SCHEMA = {
oneOf: [
{
type: 'object',
additionalProperties: false,
properties: {
kind: { type: 'string', required: true, const: 'running' },
},
},
{
type: 'object',
additionalProperties: false,
properties: {
kind: { type: 'string', required: true, const: 'exited' },
exitCode: { required: true, oneOf: [{ type: 'integer' }, { type: 'null' }] },
signal: { required: true, oneOf: [{ type: 'string' }, { type: 'null' }] },
},
},
],
} as const
const SESSION_SNAPSHOT_PROPERTIES = {
sessionId: { type: 'string', required: true },
name: { type: 'string' },
type: { type: 'string', required: true },
pid: { type: 'integer' },
status: { ...SESSION_STATUS_SCHEMA, required: true },
} as const
const SESSION_SNAPSHOT_SCHEMA = {
type: 'object',
additionalProperties: false,
properties: SESSION_SNAPSHOT_PROPERTIES,
} as const
const BACKGROUND_TASK_OUTPUT_SCHEMA = {
type: 'object',
additionalProperties: false,
properties: {
kind: { type: 'string', required: true, const: 'background' },
taskId: { type: 'string', required: true },
},
} as const
function requireAgent(agent: Agent | undefined): Agent {
if (agent === undefined) throw new Error('terminal tools require an initiating agent')
return agent
@@ -62,10 +105,6 @@ function sessionId(args: SessionArgs): PtySessionIdType {
return PtySessionId(args.sessionId)
}
function textResult(text: string): ContentBlock[] {
return [{ type: 'text', text }]
}
function rawResultText(result: ToolResult): string | undefined {
if (result.content.length !== 1) return undefined
const block = result.content[0]
@@ -94,6 +133,17 @@ export function apply(ctx: Context): void {
name: { type: 'string', description: 'Optional owner-local display name such as "main" or "gdb".' },
cwd: { type: 'string', description: 'Initial working directory. Defaults to the deployment workspace root.' },
},
output: {
schema: {
type: 'object',
additionalProperties: false,
properties: {
...SESSION_SNAPSHOT_PROPERTIES,
motd: { type: 'string', required: true },
},
},
render: (_args, value) => [{ type: 'text', text: renderSpawn(value) }],
},
async execute(args: SpawnArgs, exec) {
if (args.type.length === 0) throw new Error('type must be a non-empty string')
const result = await ctx.pty.spawn(requireAgent(exec.agent), {
@@ -101,7 +151,7 @@ export function apply(ctx: Context): void {
...args.name !== undefined ? { name: args.name } : {},
...args.cwd !== undefined ? { cwd: args.cwd } : {},
}, exec.signal)
return textResult(renderSpawn(result))
return result
},
presentCall: (args) => {
const parsed = args
@@ -118,7 +168,43 @@ export function apply(ctx: Context): void {
submit: { type: 'boolean', description: 'Submit Enter after text (default true). Set false for control characters or incomplete REPL input.' },
run_in_background: { type: 'boolean', description: 'Return a task id immediately; collect with task_output or stop with task_kill.' },
},
async execute(args: SendArgs, exec): Promise<ToolExecutionResult> {
output: {
schema: {
oneOf: [
BACKGROUND_TASK_OUTPUT_SCHEMA,
{
type: 'object',
additionalProperties: false,
properties: {
kind: { type: 'string', required: true, const: 'foreground' },
viewport: { type: 'string', required: true },
waitReason: {
type: 'string',
required: true,
enum: ['stdin_read', 'inferred_idle', 'timeout', 'session_exit'],
},
sessionStatus: { ...SESSION_STATUS_SCHEMA, required: true },
truncated: { type: 'boolean', required: true },
},
},
],
},
render: (_args, value) => [{
type: 'text',
text: value.kind === 'background'
? `started background task ${value.taskId}`
: renderSend(value),
}],
presentationMeta: (_args, value) => value.kind === 'foreground'
? {
viewport: value.viewport,
waitReason: value.waitReason,
sessionStatus: value.sessionStatus,
truncated: value.truncated,
}
: null,
},
async execute(args: SendArgs, exec) {
const owner = requireAgent(exec.agent)
const id = sessionId(args)
const request = { text: args.text, submit: args.submit ?? true }
@@ -145,12 +231,12 @@ export function apply(ctx: Context): void {
}
},
})
return { content: textResult(`started background task ${taskId}`), isError: false }
return { kind: 'background' as const, taskId }
}
const operation = ctx.pty.startSend(owner, id, { ...request, signal: exec.signal })
const result = await operation.done
if (exec.signal.aborted) throw new Error('terminal send aborted')
return { content: textResult(renderSend(result)), isError: false, meta: result }
return { kind: 'foreground' as const, ...result }
},
presentCall(args) {
const parsed = args as Partial<SendArgs>
@@ -174,12 +260,26 @@ export function apply(ctx: Context): void {
offset: { type: 'number', description: 'Newest-relative line offset (default 0).' },
count: { type: 'number', description: 'Requested line count (default 500; backend caps apply).' },
},
output: {
schema: {
type: 'object',
additionalProperties: false,
properties: {
text: { type: 'string', required: true },
totalLines: { type: 'integer', required: true },
lineBegin: { type: 'integer', required: true },
lineEnd: { type: 'integer', required: true },
truncated: { type: 'boolean', required: true },
},
},
render: (_args, value) => [{ type: 'text', text: renderRead(value) }],
},
execute(args: ReadArgs, exec) {
const result = ctx.pty.read(requireAgent(exec.agent), sessionId(args), {
...args.offset !== undefined ? { offset: args.offset } : {},
...args.count !== undefined ? { count: args.count } : {},
})
return Promise.resolve(textResult(renderRead(result)))
return Promise.resolve(result)
},
presentCall: args => ({ card: 'generic', title: `Read terminal ${(args).sessionId}`, kind: 'read', rawInput: args }),
}))
@@ -191,11 +291,21 @@ export function apply(ctx: Context): void {
sessionId: { type: 'string', required: true, description: 'Terminal session id.' },
signal: { type: 'string', required: true, enum: ['SIGINT', 'SIGTERM', 'SIGKILL', 'SIGTSTP', 'SIGHUP'], description: 'Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.' },
},
async execute(args: SignalArgs, exec) {
const result = await ctx.pty.signal(requireAgent(exec.agent), sessionId(args), args.signal)
return textResult(`delivered ${args.signal} to foreground process group ${result.targetPgid}`)
output: {
schema: {
type: 'object',
additionalProperties: false,
properties: {
delivered: { type: 'boolean', required: true, const: true },
targetPgid: { type: 'integer', required: true },
},
},
render: (args, value) => [{ type: 'text', text: `delivered ${args.signal} to foreground process group ${value.targetPgid}` }],
},
presentCall: args => ({ card: 'generic', title: `Signal terminal ${(args as SignalArgs).sessionId}`, kind: 'execute', rawInput: args }),
async execute(args: SignalArgs, exec) {
return ctx.pty.signal(requireAgent(exec.agent), sessionId(args), args.signal)
},
presentCall: args => ({ card: 'generic', title: `Signal terminal ${args.sessionId}`, kind: 'execute', rawInput: args }),
}))
ctx.tools.register(defineTool({
@@ -204,10 +314,26 @@ export function apply(ctx: Context): void {
parameters: {
sessionId: { type: 'string', required: true, description: 'Terminal session id.' },
},
output: {
schema: {
type: 'object',
additionalProperties: false,
properties: {
sessionId: { type: 'string', required: true },
outcome: { type: 'string', required: true, enum: ['closed', 'already-closing'] },
},
},
render: (_args, value) => [{
type: 'text',
text: value.outcome === 'closed'
? `closed terminal session ${value.sessionId}`
: `terminal session ${value.sessionId} was already closing`,
}],
},
async execute(args: SessionArgs, exec) {
const id = sessionId(args)
const closed = await ctx.pty.kill(requireAgent(exec.agent), id)
return textResult(closed ? `closed terminal session ${id}` : `terminal session ${id} was already closing`)
return { sessionId: id, outcome: closed ? 'closed' as const : 'already-closing' as const }
},
presentCall: args => ({ card: 'generic', title: `Close terminal ${(args).sessionId}`, kind: 'delete' }),
}))
@@ -216,8 +342,12 @@ export function apply(ctx: Context): void {
name: 'terminal_list',
description: 'List persistent terminal sessions owned by the current agent.',
parameters: {},
output: {
schema: { type: 'array', items: SESSION_SNAPSHOT_SCHEMA },
render: (_args, value) => [{ type: 'text', text: renderList(value) }],
},
execute(_args: Record<string, never>, exec) {
return Promise.resolve(textResult(renderList(ctx.pty.list(requireAgent(exec.agent)))))
return Promise.resolve(ctx.pty.list(requireAgent(exec.agent)))
},
presentCall: () => ({ card: 'generic', title: 'List terminal sessions', kind: 'read' }),
}))

54
packages/pty/tool-pty/src/render.ts
View File

@@ -1,13 +1,55 @@
/** Model and ACP rendering for persistent terminal tool results. */
import type { PtyReadResult, PtySendRead, PtySendResult, PtySessionSnapshot, PtySpawnResult } from '@deepseek-ai/dsh-pty'
interface RenderedSessionStatusRunning {
kind: 'running'
}
interface RenderedSessionStatusExited {
kind: 'exited'
exitCode: number | null
signal: string | null
}
type RenderedSessionStatus = RenderedSessionStatusRunning | RenderedSessionStatusExited
interface RenderedSessionSnapshot {
sessionId: string
name?: string
type: string
pid?: number
status: RenderedSessionStatus
}
interface RenderedSpawnResult extends RenderedSessionSnapshot {
motd: string
}
interface RenderedSendResult {
viewport: string
waitReason: 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
sessionStatus: RenderedSessionStatus
truncated: boolean
}
interface RenderedSendRead {
delta: string
truncated: boolean
}
interface RenderedReadResult {
text: string
totalLines: number
lineBegin: number
lineEnd: number
truncated: boolean
}
/**
* Render one created session and its bounded MOTD.
* @param result - published spawn result.
* @returns Model-facing session acknowledgement.
*/
export function renderSpawn(result: PtySpawnResult): string {
export function renderSpawn(result: RenderedSpawnResult): string {
const label = result.name === undefined ? result.sessionId : `${result.sessionId} (${result.name})`
return `started terminal session ${label} [type: ${result.type}]\n${result.motd || '(no startup output)'}`
}
@@ -17,7 +59,7 @@ export function renderSpawn(result: PtySpawnResult): string {
* @param result - settled send outcome.
* @returns Terminal output plus wait/session markers.
*/
export function renderSend(result: PtySendResult): string {
export function renderSend(result: RenderedSendResult): string {
const output = result.viewport || '(no new output)'
const status = result.sessionStatus.kind === 'running'
? 'running'
@@ -30,7 +72,7 @@ export function renderSend(result: PtySendResult): string {
* @param read - consuming operation delta.
* @returns Delta plus truncation marker when needed.
*/
export function renderSendRead(read: PtySendRead): string {
export function renderSendRead(read: RenderedSendRead): string {
return `${read.delta}${read.truncated ? `${read.delta.endsWith('\n') || read.delta.length === 0 ? '' : '\n'}[output truncated]` : ''}`
}
@@ -39,7 +81,7 @@ export function renderSendRead(read: PtySendRead): string {
* @param result - retained scrollback page.
* @returns Page text plus pagination and truncation markers.
*/
export function renderRead(result: PtyReadResult): string {
export function renderRead(result: RenderedReadResult): string {
const output = result.text || '(no retained output)'
return `${output}\n[lines: ${result.lineBegin}-${result.lineEnd} of ${result.totalLines}]${result.truncated ? '\n[output truncated]' : ''}`
}
@@ -49,7 +91,7 @@ export function renderRead(result: PtyReadResult): string {
* @param sessions - fresh owner-scoped snapshots.
* @returns One line per session or the empty marker.
*/
export function renderList(sessions: PtySessionSnapshot[]): string {
export function renderList(sessions: readonly RenderedSessionSnapshot[]): string {
if (sessions.length === 0) return '(no terminal sessions)'
return sessions.map((session) => {
const name = session.name === undefined ? '' : ` (${session.name})`

141
packages/pty/tool-pty/tests/tools.spec.ts
View File

@@ -5,7 +5,8 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
import type { Agent } from '@deepseek-ai/dsh-agent'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
import ToolRegistry, { renderToolsSdk } from '@deepseek-ai/dsh-tools'
import type { ToolSdkSchema } from '@deepseek-ai/dsh-tools/src/ts-types.ts'
import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
import type { PtyBackend, PtyBackendSession, PtySendOperation, PtySendRequest, PtySessionStatus, PtySignal } from '@deepseek-ai/dsh-pty'
import TaskService from '@deepseek-ai/dsh-tasks'
@@ -104,6 +105,7 @@ async function setup(tasks: boolean) {
}
let callNumber = 0
const TOOL_NAMES = ['terminal_open', 'terminal_send', 'terminal_read', 'terminal_signal', 'terminal_close', 'terminal_list'] as const
const testToolSignal = new AbortController().signal
function call(ctx: Context, name: string, args: unknown, agent?: Agent) {
return ctx.tools.execute({ signal: testToolSignal, callId: CallId(`pty-call-${++callNumber}`), name, arguments: args, ...agent ? { agent } : {} })
@@ -120,17 +122,134 @@ function text(result: { content: { type: string; text?: string }[] }): string {
describe('tool-pty foreground surface', () => {
it('registers exactly six schemas and drives the full owner-scoped lifecycle', async () => {
const { ctx, agent } = await setup(false)
expect(['terminal_open', 'terminal_send', 'terminal_read', 'terminal_signal', 'terminal_close', 'terminal_list'].every(name => ctx.tools.get(name) !== undefined)).toBe(true)
expect(TOOL_NAMES.every(name => ctx.tools.get(name) !== undefined)).toBe(true)
const spawned = await call(ctx, 'terminal_open', { type: 'stub', name: 'main' }, agent)
expect(text(spawned)).toContain('started terminal session pty-1 (main)')
expect(text(await call(ctx, 'terminal_list', {}, agent))).toContain('pty-1 (main) [stub] running pid=42')
expect(text(await call(ctx, 'terminal_read', { sessionId: 'pty-1' }, agent))).toContain('history\n[lines: 0-1 of 1]')
expect(text(await call(ctx, 'terminal_signal', { sessionId: 'pty-1', signal: 'SIGINT' }, agent))).toBe('delivered SIGINT to foreground process group 10')
expect(spawned).toMatchObject({
isError: false,
value: {
sessionId: 'pty-1',
name: 'main',
type: 'stub',
pid: 42,
status: { kind: 'running' },
motd: 'stub prompt',
},
})
const listed = await call(ctx, 'terminal_list', {}, agent)
expect(text(listed)).toContain('pty-1 (main) [stub] running pid=42')
expect(listed).toMatchObject({ isError: false, value: [{ sessionId: 'pty-1', name: 'main', type: 'stub', pid: 42, status: { kind: 'running' } }] })
const read = await call(ctx, 'terminal_read', { sessionId: 'pty-1' }, agent)
expect(text(read)).toContain('history\n[lines: 0-1 of 1]')
expect(read).toMatchObject({ isError: false, value: { text: 'history', totalLines: 1, lineBegin: 0, lineEnd: 1, truncated: false } })
const signalled = await call(ctx, 'terminal_signal', { sessionId: 'pty-1', signal: 'SIGINT' }, agent)
expect(text(signalled)).toBe('delivered SIGINT to foreground process group 10')
expect(signalled).toMatchObject({ isError: false, value: { delivered: true, targetPgid: 10 } })
const sent = await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'echo hi' }, agent)
expect(text(sent)).toContain('command output\n[wait: stdin_read]\n[session: running]')
expect(text(await call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent))).toBe('closed terminal session pty-1')
expect(text(await call(ctx, 'terminal_list', {}, agent))).toBe('(no terminal sessions)')
expect(sent).toMatchObject({
isError: false,
value: {
kind: 'foreground',
viewport: 'command output',
waitReason: 'stdin_read',
sessionStatus: { kind: 'running' },
truncated: false,
},
meta: {
viewport: 'command output',
waitReason: 'stdin_read',
sessionStatus: { kind: 'running' },
truncated: false,
},
})
const closed = await call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent)
expect(text(closed)).toBe('closed terminal session pty-1')
expect(closed).toMatchObject({ isError: false, value: { sessionId: 'pty-1', outcome: 'closed' } })
const empty = await call(ctx, 'terminal_list', {}, agent)
expect(text(empty)).toBe('(no terminal sessions)')
expect(empty).toMatchObject({ isError: false, value: [] })
})
it('projects every terminal DTO into the generated Code Mode output map', async () => {
const { ctx } = await setup(false)
const schemas = TOOL_NAMES.map((toolName): ToolSdkSchema => {
const definition = ctx.tools.get(toolName)
if (definition === undefined) throw new Error(`missing terminal tool ${toolName}`)
return {
name: definition.name,
description: definition.description,
parameters: definition.parameters,
output: definition.output.schema,
}
})
const sdk = renderToolsSdk(schemas)
const outputMapStart = sdk.indexOf('interface ToolOutputMap')
const outputMapEnd = sdk.indexOf('\n\ntype ToolName', outputMapStart)
expect(sdk.slice(outputMapStart, outputMapEnd)).toMatchInlineSnapshot(`
"interface ToolOutputMap {
terminal_close: {
sessionId: string;
outcome: "closed" | "already-closing";
};
terminal_list: ({
sessionId: string;
name?: string;
type: string;
pid?: number;
status: {
kind: "running";
} | {
kind: "exited";
exitCode: number | null;
signal: string | null;
};
})[];
terminal_open: {
sessionId: string;
name?: string;
type: string;
pid?: number;
status: {
kind: "running";
} | {
kind: "exited";
exitCode: number | null;
signal: string | null;
};
motd: string;
};
terminal_read: {
text: string;
totalLines: number;
lineBegin: number;
lineEnd: number;
truncated: boolean;
};
terminal_send: {
kind: "background";
taskId: string;
} | {
kind: "foreground";
viewport: string;
waitReason: "stdin_read" | "inferred_idle" | "timeout" | "session_exit";
sessionStatus: {
kind: "running";
} | {
kind: "exited";
exitCode: number | null;
signal: string | null;
};
truncated: boolean;
};
terminal_signal: {
delivered: true;
targetPgid: number;
};
}"
`)
})
it('fails without an initiating agent and rejects background before writing', async () => {
@@ -178,7 +297,9 @@ describe('tool-pty task integration', () => {
it('registers a generic task and exposes incremental output', async () => {
const { ctx, agent } = await setup(true)
await call(ctx, 'terminal_open', { type: 'stub' }, agent)
expect(text(await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'build', run_in_background: true }, agent))).toBe('started background task pty-send-1')
const started = await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'build', run_in_background: true }, agent)
expect(text(started)).toBe('started background task pty-send-1')
expect(started).toMatchObject({ isError: false, value: { kind: 'background', taskId: 'pty-send-1' } })
const output = await call(ctx, 'task_output', { task_id: 'pty-send-1', wait: true }, agent)
expect(text(output)).toContain('live output')
expect(text(output)).toContain('[status: completed, wait: stdin_read]')
@@ -224,7 +345,9 @@ describe('tool-pty task integration', () => {
const second = call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent)
stub.sessions[0]!.closeGate?.resolve(undefined)
await first
expect(text(await second)).toBe('terminal session pty-1 was already closing')
const result = await second
expect(text(result)).toBe('terminal session pty-1 was already closing')
expect(result).toMatchObject({ isError: false, value: { sessionId: 'pty-1', outcome: 'already-closing' } })
})
it('renders an exited session detail for background completion', async () => {