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

# Conflicts: # .agents/notes/implemented/feature/2026-06-30-interception-seams.md # docs/config-catalog.md # docs/cookbook/adding-a-tool.i18n.yaml # docs/cookbook/adding-a-tool.md # docs/cookbook/adding-a-tool.zh.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/tools.md # docs/event-producer-consumer.md # docs/persistence-catalog.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl # packages/bash/tool-bash/src/index.ts # packages/core/agent-loop/src/tool-calls.ts # packages/core/agent-loop/tests/cancel.spec.ts # packages/core/agent-loop/tests/contract-regressions.spec.ts # packages/core/agent-loop/tests/tool-calls.spec.ts # packages/core/tools/README.md # packages/core/tools/src/index.ts # packages/core/tools/tests/code-mode.spec.ts # packages/core/tools/tests/tools.spec.ts # packages/fs/tool-fs-search/tests/integration.spec.ts # packages/fs/tool-fs-search/tests/tools.spec.ts # packages/fs/tool-fs/tests/integration.spec.ts # packages/mcp/mcp-client/src/tools.ts # packages/timeout/timeout-policy/tests/timeout-policy.spec.ts # packages/web/tool-web/tests/integration.spec.ts # packages/web/tool-web/tests/tool-web.spec.ts
2026-07-21 23:39:03 +08:00
parent ef697a12e7 5d514ccdb2
commit 7d3cb39047
194 changed files with 3387 additions and 1222 deletions
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -26,7 +26,7 @@ The plugin also contributes the `tool:bash` prompt section (order 105): check th

 ### Managed shell environment

-Every foreground and background model bash call receives a newly collected trusted `DSH_*` environment. `DSH_HOME` is the absolute Harness home resolved by [`@deepseek-ai/dsh-home`](../../util/home/README.md) (`dshHome` config, then ambient `$DSH_HOME`, then `~/.dsh`) and `DSH_SHELL=1` identifies the managed child. Agent calls additionally receive `DSH_SESSION_ID=agent.session.header.id`; when the active persistence seam locates a JSONL artifact they also receive `DSH_SESSION_JSONL=<absolute target path>`. The JSONL path is a location hint: it may not exist before the first flush or contain the current buffered turn, and it is not an authorization credential.
+Every foreground and background model bash call receives a newly collected trusted `DSH_*` environment. `DSH_HOME` is the absolute Harness home resolved by [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) (`dshHome` config, then ambient `$DSH_HOME`, then `~/.dsh`) and `DSH_SHELL=1` identifies the managed child. Agent calls additionally receive `DSH_SESSION_ID=agent.session.header.id`; when the active persistence seam locates a JSONL artifact they also receive `DSH_SESSION_JSONL=<absolute target path>`. The JSONL path is a location hint: it may not exist before the first flush or contain the current buffered turn, and it is not an authorization credential.

 `ctx.bashEnv` owns collection. Other plugins can register an effect-scoped contributor with a stable name, declared keys/descriptions, and `resolve(execution: ToolExecution)`; duplicate ownership and undeclared runtime keys fail loudly, while `list()` enumerates declarations without executing providers. Harness built-ins reserve `DSH_HOME`, `DSH_SHELL`, and `DSH_SESSION_ID`; tool-bash's persistence translator owns `DSH_SESSION_JSONL` by reading the backend-neutral `sessionPersistence.locate()` seam.

--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -29,12 +29,12 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-bash": "^0.0.1",
-    "@deepseek-ai/dsh-home": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-paths": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "@deepseek-ai/dsh-tasks": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
@@ -50,9 +50,9 @@
    "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
    "@deepseek-ai/dsh-bash": "workspace:^",
    "@deepseek-ai/dsh-bash-local": "workspace:^",
-    "@deepseek-ai/dsh-home": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-paths": "workspace:^",
    "@deepseek-ai/dsh-sandbox": "workspace:^",
    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -11,8 +11,9 @@
 import { Service, type Context } from 'cordis'
 import z from 'schemastery'
 import { isAbsolute, resolve as resolvePath } from 'node:path'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineTool, TOOL_ABORTED } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, TerminalCallView, ToolExecution, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools'
+import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-session-persistence'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -23,7 +24,7 @@ import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-bash'
 import type { BashRunResult, DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-bash'
-import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-home'
+import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { processOutcome } from './background.ts'
 import { parseExitStatus, renderProcessRead, renderResult } from './render.ts'

@@ -389,7 +390,7 @@ export function apply(ctx: Context, config: Config = {}): void {
        agent: exec.agent,
        callId: exec.callId,
        toolName: 'bash',
-        ...exec.signal ? { signal: exec.signal } : {},
+        signal: exec.signal,
      },
    )
  }
@@ -513,8 +514,12 @@ export function apply(ctx: Context, config: Config = {}): void {
        if (tasks === undefined) {
          throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
        }
-        // Reject pre-start cancellation; returned tasks use their own lifecycle.
-        if (exec.signal?.aborted) throw new Error('command aborted')
+        // The caller owns cancellation until TaskService commits detached ownership.
+        if (exec.signal.aborted) {
+          const error = new HarnessError('tool call aborted', TOOL_ABORTED)
+          error.name = 'AbortError'
+          throw error
+        }
        // Task preflight finishes before the starter can spawn a process.
        const id = tasks.start({
          kind: 'bash',
@@ -533,7 +538,7 @@ export function apply(ctx: Context, config: Config = {}): void {
      }
      const result = await ctx.bash.run(ctx.bash.resolve({
        ...request,
-        ...exec.signal ? { signal: exec.signal } : {},
+        signal: exec.signal,
      }))
      if (result.aborted) throw new Error('command aborted')
      return { kind: 'foreground' as const, ...canonicalBashResult(result) }
--- a/packages/bash/tool-bash/tests/bash-env.spec.ts
+++ b/packages/bash/tool-bash/tests/bash-env.spec.ts
@@ -7,10 +7,13 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 import { BashEnvRegistry } from '@deepseek-ai/dsh-tool-bash'

+const testToolSignal = new AbortController().signal
+
 afterEach(() => vi.unstubAllEnvs())

 function execution(sessionId?: string): ToolExecution {
  return {
+    signal: testToolSignal,
    token: Symbol('bash-env-test') as ToolExecution['token'],
    callId: CallId('bash-env-call'),
    name: 'bash',
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -7,7 +7,7 @@ import { CallId } from '@deepseek-ai/dsh-llm'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
@@ -21,6 +21,8 @@ import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import { processOutcome } from '../src/background.ts'
 import { renderProcessRead, renderResult } from '../src/render.ts'

+const testToolSignal = new AbortController().signal
+
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-spec-'))

 /** Foreground-only harness: no task runtime (backgrounding fails loud here). */
@@ -67,7 +69,7 @@ function registerFakeAgent(ctx: Context, sessionId: string, inject: (...args: un
 }
 let callCounter = 0
 function call(ctx: Context, name: string, args: unknown, agent?: Agent) {
-  return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
+  return ctx.tools.execute({ signal: testToolSignal, callId: CallId(`call-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
 }

 function text(result: { content: { type: string; text?: string }[] }): string {
@@ -185,7 +187,11 @@ async function setupSandboxed(withApproval = false) {
  return { ctx, bash: ctx.bash as RecordingSandboxExecutor }
 }

-function sandboxAgent(mode?: 'read-only' | 'workspace-write' | 'danger-full-access', ctx?: Context): Agent {
+function sandboxAgent(
+  mode?: 'read-only' | 'workspace-write' | 'danger-full-access',
+  ctx?: Context,
+  onAppend?: (type: string) => void,
+): Agent {
  const events: Array<{ type: string; data?: Record<string, unknown> }> = [{ type: 'turn/start' }]
  if (mode !== undefined) events.push({ type: 'sandbox/mode', data: { mode } })
  const id = SessionId('sandbox-session')
@@ -199,6 +205,7 @@ function sandboxAgent(mode?: 'read-only' | 'workspace-write' | 'danger-full-acce
      append: (type: string, data: Record<string, unknown>) => {
        const event = { type, data }
        events.push(event)
+        onAppend?.(type)
        return event
      },
    },
@@ -469,7 +476,7 @@ describe('background execution through the task runtime', () => {
    expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
  })

-  it('a pre-aborted call refuses to start: isError, no process spawned', async () => {
+  it('a pre-aborted call is skipped before the process starts', async () => {
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
@@ -488,7 +495,11 @@ describe('background execution through the task runtime', () => {
      signal: controller.signal,
    })
    expect(result.isError).toBe(true)
-    expect(text(result)).toContain('command aborted')
+    expect(result.error).toEqual({
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    })
+    expect(text(result)).toBe('Error: tool call aborted before dispatch')
    expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
  })

@@ -615,6 +626,32 @@ describe('sandbox escalation through the generic task producer', () => {
    expect(bash.modes).toEqual(['workspace-write', 'workspace-write'])
  })

+  it('does not publish detached work when cancellation follows the escalation grant', async () => {
+    const { ctx, bash } = await setupSandboxed(true)
+    const controller = new AbortController()
+    const agent = sandboxAgent(undefined, ctx, (type) => {
+      if (type === 'approval/decided') controller.abort()
+    })
+    ctx.agents.register(agent)
+    ctx.on('approval/request', () => Promise.resolve<ApprovalOutcome>('allowed-once'))
+    const start = vi.spyOn(bash, 'start')
+
+    const result = await ctx.tools.execute({
+      callId: CallId('cancelled-escalation-background'),
+      name: 'bash',
+      arguments: { ...escalate, run_in_background: true },
+      agent,
+      signal: controller.signal,
+    })
+
+    expect(result.error).toEqual({
+      message: 'tool call aborted',
+      info: { name: 'AbortError', code: TOOL_ABORTED },
+    })
+    expect(text(result)).toBe('Error: tool call aborted')
+    expect(start).not.toHaveBeenCalled()
+  })
+
  it('uses the session override for ordinary calls and evaluates widening against it', async () => {
    const { ctx, bash } = await setupSandboxed(true)
    const agent = sandboxAgent('workspace-write')
@@ -764,7 +801,7 @@ describe('session-cwd routing (per-session workdir)', () => {
  it('falls back to the executor default when the agent has no session cwd', async () => {
    const ctx = await setup()
    // No exec.agent at all → executor uses its config/process.cwd() default.
-    const result = await ctx.tools.execute({ callId: CallId('cwd-noagent'), name: 'bash', arguments: { command: 'pwd', description: 'pwd' } })
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('cwd-noagent'), name: 'bash', arguments: { command: 'pwd', description: 'pwd' } })
    expect(result.isError).toBe(false)
    expect(text(result).trim().length).toBeGreaterThan(0)
  })
@@ -1046,6 +1083,7 @@ describe('the model-facing bash tool builds its request from named args only (no
    const path = ctx.sessionPersistence.locate(agent.session.header)?.path

    await ctx.tools.execute({
+      signal: testToolSignal,
      callId: CallId('session-env-fg'),
      name: 'bash',
      arguments: { command: 'true', description: 'run command' },
@@ -1066,6 +1104,7 @@ describe('the model-facing bash tool builds its request from named args only (no
    const path = ctx.sessionPersistence.locate(agent.session.header)?.path

    await ctx.tools.execute({
+      signal: testToolSignal,
      callId: CallId('session-env-bg'),
      name: 'bash',
      arguments: {
@@ -1092,6 +1131,7 @@ describe('the model-facing bash tool builds its request from named args only (no
    const ambient = process.env.DSH_SESSION_ID

    await ctx.tools.execute({
+      signal: testToolSignal,
      callId: CallId('session-env-id-only'),
      name: 'bash',
      arguments: { command: 'true', description: 'run command' },
@@ -1113,6 +1153,7 @@ describe('the model-facing bash tool builds its request from named args only (no

    for (const [callId, agent] of [['parent', parent], ['child', child]] as const) {
      await ctx.tools.execute({
+        signal: testToolSignal,
        callId: CallId(`session-env-${callId}`),
        name: 'bash',
        arguments: { command: 'true', description: 'run command' },
@@ -1143,6 +1184,7 @@ describe('the model-facing bash tool builds its request from named args only (no
    // This preserves the request shape; it is not a security boundary because shell syntax can
    // already set environment variables or feed stdin.
    await ctx.tools.execute({
+      signal: testToolSignal,
      callId: CallId('no-forward-1'),
      name: 'bash',
      arguments: {
@@ -1164,6 +1206,7 @@ describe('the model-facing bash tool builds its request from named args only (no
  it('a background bash call likewise carries no trusted-only fields', async () => {
    const { ctx, bash } = await setupRecording()
    const result = await ctx.tools.execute({
+      signal: testToolSignal,
      callId: CallId('no-forward-2'),
      name: 'bash',
      arguments: {
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -33,7 +33,7 @@
      "path": "../../bash/bash"
    },
    {
-      "path": "../../util/home"
+      "path": "../../util/paths"
    },
    {
      "path": "../../tasks/tasks"