Merge branch 'codex/tool-json-schema-dsl' into codex/canonical-tool-output

scripts/gen-cordis-catalog.ts

@@ -93,6 +93,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',
@@ -151,7 +152,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 +160,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 +236,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 +260,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 +323,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',

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

@@ -729,6 +729,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",