Merge branch 'codex/canonical-tool-output' into codex/code-mode-typed-results

scripts/gen-cordis-catalog.ts

@@ -35,6 +35,7 @@ export const LINK_MAP: Record<string, string> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  HookContext: 'core.md',
   LlmCallConfig: 'core.md',
   LlmModelContext: 'core.md',
   LlmFailure: 'llm-streaming.md',
@@ -45,9 +46,13 @@ export const LINK_MAP: Record<string, string> = {
   PromptDecision: 'core.md',
   RequestError: 'core.md',
   RequestErrorDecision: 'core.md',
+  PreparedReferencedMessage: 'session-reference.md',
+  SessionReferenceCandidate: 'session-reference.md',
+  SessionReferenceInput: 'session-reference.md',
   SessionEvent: 'core.md',
   SessionId: 'core.md',
   SessionStartSource: 'core.md',
+  SessionSurfaceSnapshot: 'session-query.md',
   ApprovalOutcome: 'approval.md',
   ApprovalPolicy: 'approval.md',
   ApprovalRequest: 'approval.md',
@@ -93,6 +98,17 @@ export const LINK_MAP: Record<string, string> = {
   SandboxExecutionPolicy: 'sandbox.md',
   SandboxMode: 'sandbox.md',
   SandboxPolicy: 'sandbox.md',
+  PtyBackend: 'pty.md',
+  PtyReadRequest: 'pty.md',
+  PtyReadResult: 'pty.md',
+  PtySendOperation: 'pty.md',
+  PtySendRequest: 'pty.md',
+  PtySessionId: 'pty.md',
+  PtySessionSnapshot: 'pty.md',
+  PtySignal: 'pty.md',
+  PtySignalResult: 'pty.md',
+  PtySpawnRequest: 'pty.md',
+  PtySpawnResult: 'pty.md',
   SandboxPolicyRequest: 'sandbox.md',
   ScopeKey: 'scope.md',
   Scoped: 'scope.md',

scripts/gen-doc-graphs.ts

@@ -60,6 +60,7 @@ const GROUP_ORDER = [
   'core',
   'goal',
   'bash',
+  'pty',
   'sandbox',
   'fs',
   'skill',
@@ -136,8 +137,17 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session-query',
     title: 'Exact session-history reads and traces',
     mode: 'seam',
+    consumers: ['session-reference'],
     note: 'Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces.',
   },
+  {
+    key: 'sessionReferences',
+    pkg: 'session-reference',
+    title: 'Cross-session snapshot preparation',
+    mode: 'core',
+    consumers: ['tui', 'acp'],
+    note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
+  },
   {
     key: 'sessionTitle',
     pkg: 'session-title',
@@ -151,7 +161,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'system-prompt',
     title: 'System prompt assembly registry',
     mode: 'core',
-    consumers: ['agent-loop', 'tools', 'tool-fs', 'tool-web'],
+    consumers: ['agent-loop', 'tools', 'tool-fs', 'tool-pty', 'tool-web'],
     note: 'Collects prompt sections and model-facing tool schemas for each step.',
   },
   {
@@ -159,7 +169,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'tools',
     title: 'Tool registry and guarded execution pipeline',
     mode: 'core',
-    consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-skill', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'],
+    consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-pty', 'tool-skill', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'],
     note: 'Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation.',
   },
   {
@@ -235,13 +245,22 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'core',
     note: 'Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace.',
   },
+  {
+    key: 'pty',
+    pkg: 'pty',
+    title: 'Persistent PTY session registry',
+    mode: 'seam',
+    implementations: ['pty-local'],
+    consumers: ['tool-pty'],
+    note: 'The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface.',
+  },
   {
     key: 'sandbox',
     pkg: 'sandbox',
     title: 'Process-sandbox seam',
     mode: 'seam',
     implementations: ['sandbox-local'],
-    consumers: ['bash-sandbox'],
+    consumers: ['bash-sandbox', 'pty-local'],
     note: 'Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement.',
   },
   {
@@ -250,7 +269,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Sandbox policy home',
     mode: 'core',
     implementations: [],
-    consumers: ['bash-sandbox', 'fs-sandbox'],
+    consumers: ['bash-sandbox', 'fs-sandbox', 'pty-local'],
     note: 'The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots.',
   },
   {
@@ -313,8 +332,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'tasks',
     title: 'Background task registry',
     mode: 'core',
-    consumers: ['tool-bash', 'tool-subagent', 'tool-tasks'],
-    note: 'Producers (tool-bash background commands, tool-subagent background delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it.',
+    consumers: ['tool-bash', 'tool-pty', 'tool-subagent', 'tool-tasks'],
+    note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it.',
   },
   {
     key: 'web',
@@ -897,7 +916,7 @@ function renderLifecycle(): string {
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
     `  Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
-    '  Hooks-->>Driver: allow, block, or add context',
+    '  Hooks-->>Driver: authoritative allow, block, or add context',
     `  Driver->>Session: ${mermaidCode('user/message')} or rejected ${mermaidCode('turn/end')}`,
     `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
     `  Driver-->>Driver: ${mermaidCode('agent/pre-step')} serial checkpoint`,
@@ -925,7 +944,7 @@ function renderLifecycle(): string {
     `      Driver->>Session: ${mermaidCode('tool/result')}`,
     '    end',
     '  end',
-    '  Driver->>Session: post-tool context and steering',
+    '  Driver->>Session: post-tool context and steering (no prompt-submit)',
     `  Driver->>Hooks: ${mermaidCode('agent/post-step')} serial checkpoint`,
     `  Driver->>Session: ${mermaidCode('step/end')}`,
     `  Driver->>Hooks: ${mermaidCode('agent/turn-continuation')} waterfall`,
@@ -940,6 +959,8 @@ function renderLifecycle(): string {
     '',
     '`dsh-compact-basic` uses `agent/post-step` for pressure after those durable facts and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and a fresh retry step, and returns retry only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
+    'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
+    '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
     ...maintenanceFooter(maintenance),

scripts/gen-tool-catalog.ts

@@ -33,6 +33,8 @@ import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
+import PtyService from '@deepseek-ai/dsh-pty'
+import * as ToolPty from '@deepseek-ai/dsh-tool-pty'
 import * as ToolGoal from '@deepseek-ai/dsh-tool-goal'
 import Lsp from '@deepseek-ai/dsh-lsp'
 import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp'
@@ -243,6 +245,19 @@ const TOOL_PACKAGES: ToolPackage[] = [
     note:
       'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.',
   },
+  {
+    pkg: '@deepseek-ai/dsh-tool-pty',
+    dir: 'tool-pty',
+    source: 'packages/pty/tool-pty/src/index.ts',
+    requires: ['ctx.tools', 'ctx.pty', 'ctx.systemPrompt', 'ctx.tasks at call time for run_in_background'],
+    writes: ['tool/call', 'tool/result'],
+    async mount(ctx) {
+      await ctx.plugin(PtyService)
+      await ctx.plugin(ToolPty)
+    },
+    note:
+      'The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema.',
+  },
   {
     pkg: '@deepseek-ai/dsh-tool-goal',
     dir: 'tool-goal',
@@ -327,7 +342,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolTasks)
     },
     note:
-      'The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers\' `ctx.tasks.start()`.',
+      'The kind-agnostic background-task control surface: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers\' `ctx.tasks.start()`.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-todo',

scripts/type-equiv.manifest.json

@@ -66,6 +66,11 @@
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "SendOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AgentCancelCause",
@@ -283,6 +288,11 @@
       "symbol": "TokenSurfaceNode",
       "source": "packages/llm/token-meter/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "PromptMessageData",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SessionEventMap",
@@ -379,6 +389,11 @@
       "symbol": "SessionRecord",
       "source": "packages/session-query/session-query/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionSurfaceSnapshot",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session-query.md",
       "symbol": "SessionEventRecord",
@@ -419,6 +434,26 @@
       "symbol": "SessionEventTrace",
       "source": "packages/session-query/session-query/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "SessionReferenceInput",
+      "source": "packages/context/session-reference/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "SessionReferenceCandidate",
+      "source": "packages/context/session-reference/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "PreparedReferencedMessage",
+      "source": "packages/context/session-reference/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "SessionReferenceErrorCode",
+      "source": "packages/context/session-reference/src/config.ts"
+    },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderId",
@@ -729,6 +764,36 @@
       "symbol": "TaskRead",
       "source": "packages/tasks/tasks/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/pty.md",
+      "symbol": "PtyWaitReason",
+      "source": "packages/pty/pty/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/pty.md",
+      "symbol": "PtySessionStatus",
+      "source": "packages/pty/pty/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/pty.md",
+      "symbol": "PtyBackend",
+      "source": "packages/pty/pty/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/pty.md",
+      "symbol": "PtyBackendSession",
+      "source": "packages/pty/pty/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/pty.md",
+      "symbol": "PtySendOperation",
+      "source": "packages/pty/pty/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/pty.md",
+      "symbol": "PtySendResult",
+      "source": "packages/pty/pty/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/sandbox.md",
       "symbol": "SandboxMode",