diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index acb74c0c26..4840b88192 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -82,6 +82,20 @@ jobs: - name: Install (immutable) run: pnpm install --frozen-lockfile + # The snapshot lane REPLAYS the sandbox example's recorded scenarios, + # re-executing their bash calls under a real runner. ubuntu-latest has + # no bubblewrap preinstalled and no built Landlock launcher, so without + # this the confined executions fail closed (SANDBOX_UNAVAILABLE). Same + # install as sandbox.yml's bwrap leg (incl. the Ubuntu 24.04 AppArmor + # userns knob). + - name: Install bubblewrap (unrestrict userns) + if: matrix.lane == 'snapshot' + run: | + sudo apt-get update -q + sudo apt-get install -yq bubblewrap + sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \ + || echo "apparmor userns knob absent — the functional probe decides" + - uses: actions/cache@v4 if: matrix.lane == 'lint' with: diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index c0371947fd..e06fb025bd 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -82,6 +82,20 @@ jobs: - name: Install (immutable) run: pnpm install --frozen-lockfile + # The with-key escalation e2e (examples/sandbox-acp-agent/tests/ + # escalation.e2e.ts) self-skips without a usable runner — without this + # step it would never actually execute anywhere (CI had no bwrap, dev + # macs run Seatbelt instead), which is exactly how a broken harness + # composition once survived unseen. Same recipe as ci.yml's bwrap + # steps; the userns knob is best-effort (absent on pre-24.04 kernels, + # the probe decides). + - name: Install bubblewrap (unrestrict userns) + run: | + sudo apt-get update -q + sudo apt-get install -yq bubblewrap + sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \ + || echo "apparmor userns knob absent — the functional probe decides" + # Guard against a false green: the e2e suites self-skip when the key is # absent, so a missing/misconfigured secret would otherwise pass as # "all skipped". This job only runs on trusted events (the `if:` above diff --git a/.github/workflows/sandbox.yml b/.github/workflows/sandbox.yml new file mode 100644 index 0000000000..561d74b587 --- /dev/null +++ b/.github/workflows/sandbox.yml @@ -0,0 +1,124 @@ +# Sandbox CI: the keyless real-kernel confinement proofs. A separate workflow +# from ci.yml because the axis is different — these jobs fan out over +# OS×runner (kernel capabilities), not node versions. The Landlock launcher +# arrives from the registry with `pnpm install` (the npm package family +# `node-addon-landlock-run`, built and released from its own repository), so +# these legs exercise the true consumer path — nothing is compiled here. +name: Sandbox + +on: + push: + branches: [main, master] + pull_request: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + # Keyless real-kernel sandbox proofs (sandbox RFC § Testing): each ladder + # rung is only provable on a host where it enforces, so this job fans out + # an OS×runner matrix — bwrap and Landlock on Linux (separate legs: the + # Landlock files force the bwrap rung off, so each leg proves exactly one + # rung; Landlock twice, once per architecture, each confining through the + # registry-installed launcher), Seatbelt on macOS (sandbox-exec ships with + # the OS). One node + # version only: kernel confinement does not vary by node, and ci.yml's + # node matrix already covers the node axis. + # + # The e2e files self-skip where their runner is absent, so a leg that lost + # its runner (no bwrap, kernel without Landlock, macOS without + # sandbox-exec) would otherwise pass as a false green — the same trap + # e2e.yml's key preflight guards against. Each leg therefore asserts BOTH + # its platform files actually ran: `Test Files 2 passed (2)`, no skips. + sandbox-e2e: + strategy: + fail-fast: false + matrix: + include: + - os: ubuntu-latest + runner: bwrap + - os: ubuntu-24.04 + runner: landlock + - os: ubuntu-24.04-arm + runner: landlock + - os: macos-latest + runner: seatbelt + name: sandbox e2e (${{ matrix.runner }}, ${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 20 + steps: + - uses: actions/checkout@v6 + + - uses: actions/setup-node@v6 + with: + node-version: 24 + + - name: Enable corepack (pnpm) + run: corepack enable + + - name: Install (immutable) + run: pnpm install --frozen-lockfile + + # The bwrap rung needs bubblewrap on PATH and unprivileged user + # namespaces. Ubuntu 24.04 gates the latter behind an AppArmor knob; + # lift it best-effort — on images where the knob is absent the + # functional probe (and the run-guard below) is the arbiter anyway. + - name: Install bubblewrap (unrestrict userns) + if: matrix.runner == 'bwrap' + run: | + sudo apt-get update -q + sudo apt-get install -yq bubblewrap + sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \ + || echo "apparmor userns knob absent — the functional probe decides" + + # The unit suite runs on ubuntu in `checks`; this is the one darwin leg + # in the workflow, so run it here too — the platform-dependent unit + # expectations (Seatbelt path canonicalization: /tmp IS /private/tmp) + # take their darwin branch only on this runner. + - name: Unit tests (darwin parity) + if: matrix.runner == 'seatbelt' + run: pnpm run test + + - name: Sandbox e2e (real kernel confinement, world-verified) + # NO_COLOR: vitest force-enables ANSI color under GITHUB_ACTIONS even + # without a TTY, which would thread escape codes through the summary + # line the run-guard greps. + env: + NO_COLOR: 1 + run: | + set -u +e -o pipefail + out=$(pnpm exec vitest run --config vitest.e2e.config.ts \ + packages/sandbox/sandbox-local/tests/${{ matrix.runner }}.e2e.ts \ + packages/bash/bash-sandbox/tests/${{ matrix.runner }}.e2e.ts 2>&1); status=$? + echo "$out" + [ "$status" -eq 0 ] + # Both platform files must have RUN — a self-skip (runner missing on + # the very platform that exists to prove it) is a failure, not a pass. + echo "$out" | grep -qE 'Test Files[[:space:]]+2 passed \(2\)' + + # Publish-path rehearsal, Landlock legs only (the pack gates need built + # lib/). The e2e packs the workspace closure, installs the tarballs + # into a throwaway consumer — npm pulling `node-addon-landlock-run` + # and its platform package from the registry, the true consumer path — + # and confines through the INSTALLED launcher, asserting it executable + # apart (a mode-stripped binary must not masquerade as a non-enforcing + # kernel). Same no-silent-skip guard as above. + - name: Build packages (lib/ for the pack rehearsal) + if: matrix.runner == 'landlock' + run: pnpm run build + + - name: Packed-distribution e2e (pack → install → confine) + if: matrix.runner == 'landlock' + env: + NO_COLOR: 1 + run: | + set -u +e -o pipefail + out=$(pnpm exec vitest run --config vitest.e2e.config.ts \ + packages/sandbox/sandbox-local/tests/packed-install.e2e.ts 2>&1); status=$? + echo "$out" + [ "$status" -eq 0 ] + echo "$out" | grep -qE 'Test Files[[:space:]]+1 passed \(1\)' diff --git a/AGENTS.md b/AGENTS.md index 20abf56c87..843e09e8b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai llm/ LLM seam + the DeepSeek adapters (hand-rolled + pi-ai design twin) bash/ bash executor seam + local impl + model-facing bash tools fs/ filesystem seam + local impl + policy gate + read/write/edit tools + skill/ skill provider registry + local impl + catalog/loader tool web/ web seam + search/fetch providers + model-facing web tools compact/ compaction seam + basic backend subagent/ subagent seam + spawn/fork/ACP backends + delegation tool @@ -24,7 +25,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai cordis/ self-referential toolset: the agent inspects/mounts plugins in its own runtime hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends - ui/ ACP bridge, app-boot glue, stdio/ACP app bins, user-interaction seam, ask-user tool + ui/ ACP bridge, app-boot glue, stdio/ACP app bins, user-approval and user-interaction seams, ask-user tool support/ dev/test infrastructure packages util/ zero-dependency utilities examples/ Runnable demos: thin cordis.yml leaves over the app packages (see examples/AGENTS.md) @@ -71,7 +72,7 @@ pnpm run hygiene out=$(printf 'echo ci smoke\n' | pnpm run demo:echo 2>&1) printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})' printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE' -ls .sessions/_no-cwd/main-session-*.jsonl >/dev/null +test -n "$(find .sessions -path '.sessions/cwd-*/main-session-*.jsonl' -type f -print -quit)" rm -rf .sessions pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts ``` diff --git a/docs/architecture.md b/docs/architecture.md index 01ae6ef7cb..c1755dc815 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # DeepSeek Harness Architecture -The project is an SDK for building agent harnesses. The idea is to have **everything as a plugin**. For example, the agent loop is just one plugin shipped by default. +The **DeepSeek Harness SDK** builds agent harnesses on Cordis. The principle is simple: **everything is a plugin**. The shipped loop is one plugin, not a privileged kernel. ## Overview @@ -26,8 +26,10 @@ Composition is preferred over inheritance. `packages/core/` is a repository grou |---|---|---| | `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry and streaming model calls | | `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution | +| `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement (argv wrapping, per-call policy) | | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution | | `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events | +| `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill provider registry and progressive disclosure | | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries | | `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-log compaction | | `ctx.subagents` | [`subagent/`](../packages/subagent/README.md) | named delegation providers | @@ -127,11 +129,11 @@ Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAs A swappable capability usually splits into **interface / implementation / consumer**: the interface owns the `ctx` key and event names; an implementation registers a backend; a consumer exposes model-facing behavior through `ctx.tools` or prompt assembly. The bash trio is the reference shape, and the [capability graph](capability-seams.md) shows the current package families. -Some cases bend the template deliberately. LLM keeps interface and consumer event names together because adapters are the implementations. Filesystem adds policy checks around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Subagents use a named provider registry because multiple delegation backends can coexist; `spawn` starts fresh, `fork` seeds from the parent's completed-turn prefix, and ACP can drive an out-of-process child ([subagent.md](core-data-structures/subagent.md)). +Some seams bend the template deliberately. LLM keeps interface and consumer vocabulary together because adapters are the implementations. Filesystem adds policy gates around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Skills and subagents use named provider registries; local skills scan project/user roots, and other providers can add embedded or remote catalogs without registry/tool changes. Subagents spawn fresh, fork from the parent's completed-turn prefix, or use ACP children ([subagent.md](core-data-structures/subagent.md)). ### Bundles And Apps -`dsh-agent-core` is the default bundle: one plugin loading the agent loop ([README](../packages/core/agent-core/README.md)). App packages compose it with a front end and own the entrypoint `bin`: `dsh-stdio-agent` for the terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)). +`dsh-agent-core` is the default composition bundle: one plugin loading the shared spine ([README](../packages/core/agent-core/README.md)). App packages compose it with a front door and boot `bin`: `dsh-stdio-agent` for terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)). ### Where New Behavior Goes @@ -143,6 +145,7 @@ New behavior should attach to a documented extension point; changing the shipped | Add a model-facing capability | register a tool on `ctx.tools`; schemas flow into prompt assembly | | Add command execution | implement and register a `ctx.bash` backend | | Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events | +| Confine spawned processes | a `ctx.sandbox` backend; consumers wrap their argv before spawning | | Intercept prompts, requests, tool use, or continuation | listen on the relevant `agent/*` or `tools/*` waterfall | | Add a session-stable request prefix outside history | compose it on `agent/session-prefix`, once per loop instance; logged on the request header | | Add UI or editor integration | drive `ctx.agents` and render from `session/event` | @@ -156,4 +159,4 @@ The [extension cookbook](cookbook/extension-cookbook.md) carries plugin skeleton - Exact event and service signatures in [events](cordis-catalog/events.md) - [services](cordis-catalog/services.md) catalogs - package contracts in the [package map](../packages/README.md) -- [RFCs](rfc/README.md) \ No newline at end of file +- [RFCs](rfc/README.md) diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 1c24a2916e..7b84133cbc 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -33,19 +33,29 @@ flowchart LR pkg_tool_ask_user["tool-ask-user"] pkg_tool_bash["tool-bash"] pkg_tool_cordis["tool-cordis"] + pkg_tool_skill["tool-skill"] pkg_tool_subagent["tool-subagent"] pkg_tool_todo["tool-todo"] pkg_user_interaction["user-interaction"] svc_userInteraction["ctx.userInteraction
Human question/answer seam"] pkg_stdio_agent["stdio-agent"] + pkg_skill["skill"] + svc_skills["ctx.skills
Skill provider registry"] + pkg_skill_local["skill-local"] svc_agents["ctx.agents
Agent registry"] svc_agentLoop["ctx.agentLoop
Concrete loop driver"] pkg_agent_core["agent-core"] pkg_bash["bash"] svc_bash["ctx.bash
Bash executor seam"] pkg_bash_local["bash-local"] + pkg_bash_sandbox["bash-sandbox"] pkg_hooks_claude["hooks-claude"] pkg_hooks_codex["hooks-codex"] + pkg_sandbox["sandbox"] + svc_sandbox["ctx.sandbox
Process-sandbox seam"] + pkg_sandbox_local["sandbox-local"] + pkg_approval["approval"] + svc_approval["ctx.approval
Approval seam"] pkg_code_runtime["code-runtime"] svc_codeRuntime["ctx.codeRuntime
Code-execution seam"] pkg_code_runtime_worker["code-runtime-worker"] @@ -71,11 +81,14 @@ flowchart LR svc_workflows["ctx.workflows
Workflow script engine"] pkg_workflow_workerthread["workflow-workerthread"] pkg_tool_workflow["tool-workflow"] + pkg_acp --> svc_approval pkg_acp --> svc_userInteraction pkg_agent --> svc_agents pkg_agent_loop --> svc_agentLoop + pkg_approval --> svc_approval pkg_bash --> svc_bash pkg_bash_local --> svc_bash + pkg_bash_sandbox --> svc_bash pkg_code_runtime --> svc_codeRuntime pkg_code_runtime_worker --> svc_codeRuntime pkg_compact --> svc_compact @@ -86,10 +99,14 @@ flowchart LR pkg_llm_deepseek --> svc_llm pkg_llm_pi_ai --> svc_llm pkg_llm_replay --> svc_llm + pkg_sandbox --> svc_sandbox + pkg_sandbox_local --> svc_sandbox pkg_session --> svc_sessions pkg_session_persistence --> svc_sessionPersistence pkg_session_persistence_jsonl --> svc_sessionPersistence pkg_session_persistence_sqlite --> svc_sessionPersistence + pkg_skill --> svc_skills + pkg_skill_local --> svc_skills pkg_stdio_agent --> svc_userInteraction pkg_subagent --> svc_subagents pkg_subagent_acp --> svc_subagents @@ -112,6 +129,8 @@ flowchart LR svc_agents --> pkg_invariants svc_agents --> pkg_stdio_agent svc_agents --> pkg_subagent_inprocess + svc_approval --> pkg_tool_bash + svc_approval --> pkg_tools svc_bash --> pkg_hooks_claude svc_bash --> pkg_hooks_codex svc_bash --> pkg_tool_bash @@ -120,6 +139,7 @@ flowchart LR svc_fs --> pkg_tool_fs svc_llm --> pkg_agent_loop svc_llm --> pkg_compact_basic + svc_sandbox --> pkg_bash_sandbox svc_sessionPersistence --> pkg_acp svc_sessionPersistence --> pkg_agent_loop svc_sessions --> pkg_agent @@ -127,6 +147,7 @@ flowchart LR svc_sessions --> pkg_invariants svc_sessions --> pkg_session_persistence svc_sessions --> pkg_subagent_inprocess + svc_skills --> pkg_tool_skill svc_subagents --> pkg_tool_subagent svc_systemPrompt --> pkg_agent_loop svc_systemPrompt --> pkg_tool_fs @@ -138,6 +159,7 @@ flowchart LR svc_tools --> pkg_tool_bash svc_tools --> pkg_tool_cordis svc_tools --> pkg_tool_fs + svc_tools --> pkg_tool_skill svc_tools --> pkg_tool_subagent svc_tools --> pkg_tool_todo svc_tools --> pkg_tool_web @@ -155,11 +177,14 @@ flowchart LR | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. | | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. | | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. | -| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. | +| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. | | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. | +| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. | | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. | -| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. | +| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. | +| `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. | +| `ctx.approval` | `seam` | `approval` | [`acp`](../packages/ui/acp) | [`tools`](../packages/core/tools), [`tool-bash`](../packages/bash/tool-bash) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. | | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). | | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate. | | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index ce1518066b..8bafb4aef1 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -31,7 +31,7 @@ export interface AcpConfig { Depends on: `Stream` (`@agentclientprotocol/sdk`) -Source: [`packages/ui/acp/src/index.ts:236`](../packages/ui/acp/src/index.ts) +Source: [`packages/ui/acp/src/index.ts:248`](../packages/ui/acp/src/index.ts) ## `@deepseek-ai/dsh-acp-agent` @@ -56,10 +56,12 @@ export interface Config { tools?: ToolsConfig /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string + /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */ + skills?: agentCore.SkillConfig } ``` -Depends on: [`ToolsConfig`](#deepseek-aidsh-tools) +Depends on: [`agentCore`](../packages/core/agent-core/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) Source: [`packages/ui/acp-agent/src/index.ts:52`](../packages/ui/acp-agent/src/index.ts) @@ -71,12 +73,12 @@ Source: [`packages/ui/acp-agent/src/index.ts:52`](../packages/ui/acp-agent/src/i * `agents` to the agent loop (an app that pre-creates no agents, like the ACP * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt * plugin (the deployment's persona section and the explicit model-facing tool - * order), the `tools` object to the tool registry (its presentation `mode`). - * Every field is optional INPUT here because each owner's schema - * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the - * schema is the INTERSECTION of the owners' own schemas (the registry's - * nested under its `tools` key), so validation and defaulting can never - * drift from them. + * order), the `tools` object to the tool registry (its presentation `mode`), + * and `skills` to the skill registry/local provider/tool consumer. Every field + * is optional INPUT here because each owner's schema supplies the default; + * the schema is the INTERSECTION of the owners' own schemas (with registry + * schemas nested under their bundle keys), so validation and defaulting can + * never drift from them. */ export interface Config { /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */ @@ -87,12 +89,24 @@ export interface Config { toolOrder?: SystemPromptConfig['toolOrder'] /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */ tools?: ToolsConfig + /** Skill registry, local provider, and model-facing consumer config. */ + skills?: SkillConfig +} + +/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */ +export interface SkillConfig { + /** Registry-level discovery cache settings. */ + registry?: SkillRegistryConfig + /** Local filesystem skill provider settings. */ + local?: SkillLocal.Config + /** Model-facing skill catalog and tool settings. */ + tool?: toolSkill.Config } ``` -Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`ToolsConfig`](#deepseek-aidsh-tools) +Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) -Source: [`packages/core/agent-core/src/index.ts:71`](../packages/core/agent-core/src/index.ts) +Source: [`packages/core/agent-core/src/index.ts:87`](../packages/core/agent-core/src/index.ts) ## `@deepseek-ai/dsh-agent-loop` @@ -108,6 +122,8 @@ export interface Config { agents: (AgentOptions & { /** Agent id to register under; also seeds the fresh per-run session id (`${id}-session-`). */ id: AgentId + /** Optional workspace cwd for the config-created fresh session. */ + cwd?: string /** * If set, the config agent RESUMES this persisted session id instead of * starting a fresh `${id}-session-`. Sourced from an env var in @@ -150,6 +166,33 @@ export interface Config { Source: [`packages/bash/bash-local/src/index.ts:29`](../packages/bash/bash-local/src/index.ts) +## `@deepseek-ai/dsh-bash-sandbox` + +Requires: `sandbox` + +```ts config-catalog +/** + * Plugin config: the local executor's knobs plus the sandbox policy. All + * optional — `static Config` supplies the defaults (`mode: 'read-only'` is the + * fail-safe default; an example that wants a workspace-writable agent opts in + * explicitly). The runner choice is NOT configured here: which platform + * backend confines the command is the `ctx.sandbox` provider's config. + */ +export interface Config extends LocalConfig { + /** File-sandbox mode commands run under (default: `read-only`). */ + mode?: SandboxMode + /** + * Root directory `workspace-write` mode may write under (default: the + * executor's default working directory — `cwd`, else `process.cwd()`). + */ + workspaceRoot?: string +} +``` + +Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local) · [`SandboxMode`](core-data-structures/sandbox.md) + +Source: [`packages/bash/bash-sandbox/src/index.ts:60`](../packages/bash/bash-sandbox/src/index.ts) + ## `@deepseek-ai/dsh-code-runtime-worker` ```ts config-catalog @@ -430,6 +473,53 @@ export interface Config { Source: [`packages/guard/repeat-tool-guard/src/index.ts:55`](../packages/guard/repeat-tool-guard/src/index.ts) +## `@deepseek-ai/dsh-sandbox-local` + +```ts config-catalog +/** Plugin config. All optional — `static Config` supplies the defaults. */ +export interface Config { + /** + * Override the sandbox runner argv (the bwrap-shaped profile arguments are + * appended). A NON-EMPTY argv is the operator's assertion that this runner + * exists and FULLY enforces the profile (confinement reports + * `enforcement: 'full'`, and — the runner's kernel mechanism being unknown + * — carries both Linux file-denial dialects as its denial signatures) — + * the runner chain and its probes are skipped, + * and a broken runner fails loudly at execution time. The operator also + * supplies {@link runnerFailureSignatures}, which distinguish the runner + * refusing its profile from the wrapped command failing normally. + * Absent (or empty — the schema normalizes an omitted array to `[]`): the + * built-in platform chains — Linux `bwrap` then the Landlock launcher + * (probed in that order), darwin `sandbox-exec` (the sole candidate, + * selected without a probe). Used for custom/alternative runners and + * for deterministic fake runners in keyless test tiers. + */ + runnerCommand?: string[] + /** + * Case-insensitive stderr substrings emitted when a configured + * {@link runnerCommand} refuses its profile before executing the wrapped + * command. Required and non-empty with `runnerCommand`; rejected without + * it. Missing/unexecutable runner errors are added automatically from + * `runnerCommand[0]`, while these signatures cover an executable runner's + * own failure dialect. + */ + runnerFailureSignatures?: string[] + /** + * Per-probe timeout in milliseconds for the chain's functional probes + * (default: 5000; must be a positive finite number — Node treats a 0 + * `spawnSync` timeout as UNBOUNDED, so 0 is rejected at construction). A + * probe that exceeds it reads as an unusable rung, so a + * host slow enough to trip the default — cold NFS mounts, heavily loaded + * CI — would otherwise be misclassified `SANDBOX_UNAVAILABLE` with no + * config escape. Bounds ONE probe, and the chain walk runs each at most once + * per provider lifetime. + */ + probeTimeoutMs?: number +} +``` + +Source: [`packages/sandbox/sandbox-local/src/index.ts:36`](../packages/sandbox/sandbox-local/src/index.ts) + ## `@deepseek-ai/dsh-session-persistence-jsonl` Requires: `sessions` @@ -483,6 +573,36 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist' Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:51`](../packages/session-persistence/session-persistence-sqlite/src/index.ts) +## `@deepseek-ai/dsh-skill` + +```ts config-catalog +/** Skill registry configuration. */ +export interface Config { + /** Maximum number of completed cwd/provider catalog snapshots kept in memory. */ + collectCacheMaxEntries?: number +} +``` + +Source: [`packages/skill/skill/src/index.ts:112`](../packages/skill/skill/src/index.ts) + +## `@deepseek-ai/dsh-skill-local` + +Requires: `skills` + +```ts config-catalog +/** Local filesystem skill provider configuration. */ +export interface Config { + /** DeepSeek Harness config root. Defaults to `$DSH_HOME` or `~/.dsh`. */ + dshHome?: string + /** Shared agent config root. Defaults to `$DSH_AGENTS_HOME` or `~/.agents`. */ + agentsHome?: string + /** Additional skill roots scanned after project roots and before user roots. */ + customSkillDirs?: string[] +} +``` + +Source: [`packages/skill/skill-local/src/index.ts:39`](../packages/skill/skill-local/src/index.ts) + ## `@deepseek-ai/dsh-stdio-agent` ```ts config-catalog @@ -492,7 +612,9 @@ Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:5 * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is * the deployment persona (forwarded to the system-prompt plugin); `toolOrder` * is the explicit model-facing tool order (forwarded to the system-prompt plugin); - * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner. + * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions + * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory; + * `welcome` is the UI banner. */ export interface Config { /** Model name for the `main` agent (must have a registered adapter). */ @@ -507,6 +629,8 @@ export interface Config { persistenceRoot?: string /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */ welcome?: string + /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */ + skills?: agentCore.SkillConfig /** * If set, the `main` agent RESUMES this persisted session id instead of * starting fresh. Sourced from an env var in the leaf `cordis.yml` @@ -516,9 +640,9 @@ export interface Config { } ``` -Depends on: [`ToolsConfig`](#deepseek-aidsh-tools) +Depends on: [`agentCore`](../packages/core/agent-core/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) -Source: [`packages/ui/stdio-agent/src/index.ts:63`](../packages/ui/stdio-agent/src/index.ts) +Source: [`packages/ui/stdio-agent/src/index.ts:65`](../packages/ui/stdio-agent/src/index.ts) ## `@deepseek-ai/dsh-subagent-acp` @@ -721,6 +845,20 @@ export interface Config { Source: [`packages/fs/tool-fs/src/index.ts:48`](../packages/fs/tool-fs/src/index.ts) +## `@deepseek-ai/dsh-tool-skill` + +Requires: `tools` · `skills` + +```ts config-catalog +/** Model-facing skill catalog configuration. */ +export interface Config { + /** Maximum normalized description length rendered in the session catalog; minimum 3. */ + catalogDescriptionMaxLength?: number +} +``` + +Source: [`packages/skill/tool-skill/src/index.ts:19`](../packages/skill/tool-skill/src/index.ts) + ## `@deepseek-ai/dsh-tool-subagent` Requires: `tools` · `subagents` @@ -818,7 +956,38 @@ export interface Config { export type ToolPresentationMode = 'native' | 'code' | 'both' ``` -Source: [`packages/core/tools/src/index.ts:319`](../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:323`](../packages/core/tools/src/index.ts) + +## `@deepseek-ai/dsh-user-approval` + +```ts config-catalog +/** Plugin config. All optional — `static Config` supplies the defaults. */ +export interface Config { + /** + * The deployment's default {@link ApprovalPolicy} for sessions without an + * `approval/policy` override — `'ask'` delegates to the composed answerers + * (fail-closed with none); `'never'` auto-rejects every ask without + * prompting (the deterministic CI/unattended stance). + */ + policy?: ApprovalPolicy +} + +/** + * A session's approval policy — what happens to an {@link ApprovalService} + * ask BEFORE any interactive answerer sees it: + * + * - `'ask'` (the default) — delegate to the composed answerers; with none + * composed the chain falls through to the fail-closed `'unavailable'` + * (exactly today's behavior). + * - `'never'` — never prompt anyone: every ask resolves `'rejected'` + * deterministically. The strict headless stance (CI, unattended runs) and + * the only policy value stated in the system prompt — unlike `'ask'`, its + * outcome is knowable without asking, so stating it cannot overclaim. + */ +export type ApprovalPolicy = 'ask' | 'never' +``` + +Source: [`packages/ui/user-approval/src/index.ts:258`](../packages/ui/user-approval/src/index.ts) ## `@deepseek-ai/dsh-web` @@ -984,6 +1153,7 @@ Abstract service classes — a deployment loads a concrete implementation packag - `@deepseek-ai/dsh-code-runtime` — abstract `CodeRuntime` ([`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)) - `@deepseek-ai/dsh-compact` — abstract `CompactService` ([`packages/compact/compact/src/index.ts`](../packages/compact/compact/src/index.ts)) - `@deepseek-ai/dsh-fs` — abstract `FileSystem` ([`packages/fs/fs/src/index.ts`](../packages/fs/fs/src/index.ts)) +- `@deepseek-ai/dsh-sandbox` — abstract `SandboxProvider` ([`packages/sandbox/sandbox/src/index.ts`](../packages/sandbox/sandbox/src/index.ts)) - `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session-persistence/session-persistence/src/index.ts`](../packages/session-persistence/session-persistence/src/index.ts)) - `@deepseek-ai/dsh-workflow` — abstract `WorkflowService` ([`packages/workflow/workflow/src/index.ts`](../packages/workflow/workflow/src/index.ts)) diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md index de21ece7b1..a773fee6e9 100644 --- a/docs/cookbook/extension-cookbook.md +++ b/docs/cookbook/extension-cookbook.md @@ -56,7 +56,7 @@ export function apply(ctx: Context) { A *client driver* is a UI plugin whose "user" is another program speaking a wire protocol rather than a human at a terminal. It owns the process's stdio (so it must run with **no stdout logger** — every non-protocol byte corrupts the stream), creates/resumes agents on demand through the `dsh-agent` factory seam, translates harness events (`session/event`, `agent/*`) into outbound protocol messages, and translates inbound requests back into `agent.send()` / `agent.cancel()`. Two harness-specific contracts make it correct: resolve each request exactly once off a settle signal (settle from the durable `turn/end` session event — the boundary is a session event, not an `agent/*` mirror — with `agent/status` as the fallback if a peer listener starved yours), and tear each agent down through its `AgentHandle.dispose()` (which stops the loop, `await`s its exit, and unregisters), not just `cancel()` — disposal must *reach* quiescence, not merely request it. -`packages/ui/acp` is the worked example: it bridges the agent to the Agent Client Protocol (JSON-RPC over stdio) so Zed and other ACP editors can drive it. See its README for the full method surface and the deferred-permission-gate note. +`packages/ui/acp` is the worked example: it bridges the agent to the Agent Client Protocol (JSON-RPC over stdio) so Zed and other ACP editors can drive it. See its README for the full method surface and the permission-prompt answerer it registers on the approval seam. ```ts import type { Context } from 'cordis' @@ -100,7 +100,7 @@ Every product feature maps to a listener on a documented extension seam — the | AGENTS.md (subdir, on-touch) + file-change notices | `agent.inject()` from a watcher / tool-result listener | | Built-in tools | `ctx.tools.register()`; schemas flow into the assembly automatically — the `dsh-tool-*` families (bash, fs, web, subagent, todo) are the shipped examples | | ToolSearch / progressive disclosure | filter tools at `system-prompt/assemble` (the assembly carries the schemas; the loop logs the result as the request header, so disclosure stays reconstructable) | -| Tool sandbox (landlock / sandbox-exec) | `tools/pre-execute` (deny), or a sandboxing `BashExecutor` on the `dsh-bash` seam | +| Subprocess sandbox (landlock / sandbox-exec) | `tools/pre-execute` (deny), or a sandboxing `BashExecutor` on the `dsh-bash` seam | | Permission system / AskUserQuestion | `tools/pre-execute` (deny/ask); register an ask tool | | Plan mode | `tools/pre-execute` (deny writes) + a mode prompt section via `ctx.systemPrompt.section()` or `agent.inject()` (model-visible ⟺ logged: `agent/request` shapes call config only) | | Sub-agent delegation | the `ctx.subagents` provider registry (`dsh-subagent-spawn`/`-fork`/`-acp`) + `dsh-tool-subagent` exposing one configured provider to the model | diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index a9dfb7e05c..332f85368d 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -163,6 +163,20 @@ Types: [Agent](../core-data-structures/core.md) Source: [`packages/core/agent/src/types.ts:464`](../../packages/core/agent/src/types.ts) +## `approval/*` + +### `approval/request` — waterfall + +Waterfall asking the composed answerers to decide one approval request. Dispatched only from ApprovalService.request — callers go through the service (which owns cancellation and the audit events), never through `ctx.waterfall` directly. A listener that can answer for this request's agent returns an outcome WITHOUT calling `next()` (the decision slot is single-occupancy, first listener to answer wins); a listener that does not recognize the agent MUST call `next()` so another answerer — or the fail-closed default `'unavailable'` — gets the question. Throwing is contained by the service and yields `'unavailable'`. + +```ts cordis-catalog +'approval/request'(this: ApprovalService, req: ApprovalRequest, next: () => Promise): Promise +``` + +Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) + +Source: [`packages/ui/user-approval/src/index.ts:64`](../../packages/ui/user-approval/src/index.ts) + ## `fs/*` ### `fs/edit-intent` — waterfall @@ -249,6 +263,28 @@ Awaited durability checkpoint. The agent loop awaits `ctx.parallel('session/flus Source: [`packages/core/session/src/index.ts:57`](../../packages/core/session/src/index.ts) +## `skill/*` + +### `skill/provider-added` — emit + +A skill provider became resolvable in the `ctx.skills` registry. Consumers can observe this instead of depending on Cordis plugin load order, which is concurrent for sibling plugins. + +```ts cordis-catalog +'skill/provider-added'(provider: SkillProvider): void +``` + +Source: [`packages/skill/skill/src/index.ts:130`](../../packages/skill/skill/src/index.ts) + +### `skill/provider-removed` — emit + +A skill provider left the registry because its plugin fiber was disposed. + +```ts cordis-catalog +'skill/provider-removed'(name: string): void +``` + +Source: [`packages/skill/skill/src/index.ts:136`](../../packages/skill/skill/src/index.ts) + ## `subagent/*` ### `subagent/end` — emit @@ -323,7 +359,7 @@ A tool was registered or unregistered (the available tool set changed). 'tools/change'(): void ``` -Source: [`packages/core/tools/src/index.ts:132`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:135`](../../packages/core/tools/src/index.ts) ### `tools/execute` — waterfall @@ -335,7 +371,7 @@ Around-dispatch waterfall wrapping the registry's core tool dispatch, between th Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:111`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:114`](../../packages/core/tools/src/index.ts) ### `tools/post-execute` — waterfall @@ -347,11 +383,11 @@ Waterfall AFTER a tool runs — where hook plugins inspect the result and accept Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:127`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:130`](../../packages/core/tools/src/index.ts) ### `tools/pre-execute` — waterfall -Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code's `PreToolUse`). Listeners receive `(exec, next)`: call `next()` to delegate to the default (allow), or return a PreToolDecision without calling `next()` to short-circuit. A `deny` skips dispatch and yields an `isError` result; the tool body never runs. Input rewrite is deliberately NOT offered here (see PreToolDecision); `ask` degrades to deny until the permission system lands (`FIXME(permissions)`). +Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code's `PreToolUse`). Listeners receive `(exec, next)`: call `next()` to delegate to the default (allow), or return a PreToolDecision without calling `next()` to short-circuit. A `deny` skips dispatch and yields an `isError` result; the tool body never runs. Input rewrite is deliberately NOT offered here (see PreToolDecision); `ask` is serviced by the `ctx.approval` seam when one is mounted, and degrades to deny otherwise. ```ts cordis-catalog 'tools/pre-execute'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise @@ -359,7 +395,7 @@ Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook pl Types: [ToolExecution](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:91`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:94`](../../packages/core/tools/src/index.ts) ## `workflow/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index a21a80fb77..d60dc13128 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -16,12 +16,12 @@ The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loo The loop itself is deliberately thin — every behavior beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy declared in @deepseek-ai/dsh-agent. ```ts cordis-catalog -create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent +create(id: AgentId, options: AgentOptions = {}, meta: Pick = {}): ReactLoopAgent createAgent(options: CreateAgentOptions): AgentHandle async resume(options: ResumeAgentOptions): Promise ``` -Source: [`packages/core/agent-loop/src/index.ts:68`](../../packages/core/agent-loop/src/index.ts) +Source: [`packages/core/agent-loop/src/index.ts:70`](../../packages/core/agent-loop/src/index.ts) ## `ctx.agents` — `AgentRegistry` @@ -40,6 +40,20 @@ Types: [Agent](../core-data-structures/core.md) Source: [`packages/core/agent/src/index.ts:117`](../../packages/core/agent/src/index.ts) +## `ctx.approval` — `ApprovalService` + +The `ctx.approval` service: dispatches ApprovalRequests to the `approval/request` waterfall and audits every ask/outcome pair to the requesting agent's session log. Stateless between requests — grants are returned to the caller, never stored here. + +Owns the policy tier too (`effective = fold(the session's 'approval/policy' events) ?? config.policy`): `request()` resolves `'never'` to `'rejected'` before dispatching any interactive answerer, a per-agent prompt section states a `'never'` policy (and only that one in prose — an `'ask'` promise could overclaim an answerer that headless compositions do not have), and an `agent/pre-step` narrator injects at most one coalesced notice when a session's effective policy moved past what the model was last told. + +```ts cordis-catalog +async request(req: ApprovalRequest): Promise +``` + +Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) + +Source: [`packages/ui/user-approval/src/index.ts:282`](../../packages/ui/user-approval/src/index.ts) + ## `ctx.bash` — `BashExecutor` (abstract seam) Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). @@ -65,7 +79,7 @@ onTaskDone(listener: BashTaskListener): () => void Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) · [BashTask](../core-data-structures/bash.md) · [BashTaskRead](../core-data-structures/bash.md) -Source: [`packages/bash/bash/src/index.ts:59`](../../packages/bash/bash/src/index.ts) +Source: [`packages/bash/bash/src/index.ts:62`](../../packages/bash/bash/src/index.ts) ## `ctx.codeRuntime` — `CodeRuntime` (abstract seam) @@ -147,6 +161,24 @@ Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../co Source: [`packages/llm/llm/src/index.ts:88`](../../packages/llm/llm/src/index.ts) +## `ctx.sandbox` — `SandboxProvider` (abstract seam) + +Abstract process-sandbox service. Subclass, implement confine, and load the subclass as a plugin — it registers as `ctx.sandbox` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). + +Semantics every implementation must honor: + +- confine either returns an argv whose runner ENFORCES the policy or fails closed — at `confine` time with SandboxUnavailableError (no backend for this host), or at EXECUTION time by the runner itself refusing to run the command (exiting without exec'ing it, identified by ConfinedArgv.runnerFailureSignatures). A silent unconfined passthrough is never a legal outcome on either path. +- Probing exists to ARBITRATE between multiple candidate backends and may be skipped when a platform has exactly one: the sole candidate is selected directly and the runner's exec-time fail-closed refusal carries the safety property. When probing does run, it is functional (actually enforcing a profile, not a version check), at most once per provider lifetime; `confine` itself spawns nothing beyond that one-time probing. +- The returned ConfinedArgv.enforcement states the backend's actual completeness for THIS host; `partial` is reported, never silently upgraded to `full`. + +```ts cordis-catalog +abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv +``` + +Types: [ConfinedArgv](../core-data-structures/sandbox.md) · [SandboxPolicy](../core-data-structures/sandbox.md) + +Source: [`packages/sandbox/sandbox/src/index.ts:180`](../../packages/sandbox/sandbox/src/index.ts) + ## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam) Abstract durable session-persistence service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.sessionPersistence` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). @@ -188,6 +220,19 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Source: [`packages/core/session/src/index.ts:405`](../../packages/core/session/src/index.ts) +## `ctx.skills` — `SkillService` + +Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted model-visible summaries, and loads full skill bodies on demand. + +```ts cordis-catalog +registerProvider(provider: SkillProvider): () => void +register(skill: SkillRegistration): () => void +async list(options: SkillLookupOptions = {}): Promise +async get(name: string, options: SkillLookupOptions = {}): Promise +``` + +Source: [`packages/skill/skill/src/index.ts:157`](../../packages/skill/skill/src/index.ts) + ## `ctx.subagents` — `SubagentService` The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface. @@ -227,7 +272,7 @@ async execute(exec: ToolExecution): Promise Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:345`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:349`](../../packages/core/tools/src/index.ts) ## `ctx.userInteraction` — `UserInteractionService` diff --git a/docs/core-data-structures/approval.md b/docs/core-data-structures/approval.md new file mode 100644 index 0000000000..997f4e7ab2 --- /dev/null +++ b/docs/core-data-structures/approval.md @@ -0,0 +1,64 @@ +# User Approval + +The user-approval seam of [dsh-user-approval](../../packages/ui/user-approval) answers one question: may this specific action proceed? It owns the shared request/outcome vocabulary, the `ctx.approval` dispatch service, the `approval/request` answerer waterfall, the log-only audit pair, and the per-session `ask`/`never` policy. UI channels such as [dsh-acp](../../packages/ui/acp) provide answerers; callers such as [dsh-tools](../../packages/core/tools) and [dsh-tool-bash](../../packages/bash/tool-bash) consume the closed outcome and fail closed unless it is `allowed-once`. + +Source: [`packages/ui/user-approval/src/index.ts`](../../packages/ui/user-approval/src/index.ts) + +## Identity and outcome + +Every request receives a fresh `ApprovalRequestId`. The brand pairs the `approval/asked` and `approval/decided` audit events without making approval ids interchangeable with tool-call, session, or agent ids. + +```ts type-equiv +type ApprovalRequestId = Branded<'ApprovalRequestId'> +``` + +`ApprovalOutcome` is closed and fail-closed. `allowed-once` grants only the asked-about action; callers deny on `rejected`, `cancelled`, and `unavailable`. A missing, non-owning, throwing, or non-conforming answerer becomes `unavailable` rather than opening the gate. + +```ts type-equiv +type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable' +``` + +## Per-session policy + +`ApprovalPolicy` determines what happens before interactive answerers run. `ask` delegates to the composed answerer chain, whose no-answer default is `unavailable`; `never` deterministically returns `rejected` without dispatching any answerer. The effective value is the last `approval/policy` event in the session log, falling back to the service config. `setApprovalPolicy(session, policy)` is the single write path, so replay reconstructs the override. + +```ts type-equiv +type ApprovalPolicy = 'ask' | 'never' +``` + +The prompt section states the deterministic `never` behavior and records either policy with a source-owned marker. The pre-step narrator reads that marker from the logged request header after restart; it does not infer state from deployment persona prose. An idle ACP switch is held in the bridge until the next `turn/start`, because approval audit and policy events must remain turn-enclosed for durable replay. + +## Approval request + +`ApprovalRequest` identifies the agent and tool action closely enough to route and audit the question. It deliberately omits tool arguments: an answerer attaches the prompt to the already-streamed tool call through `callId` instead of rendering a second copy that could drift. + +```ts type-equiv +interface ApprovalRequest { + /** + * The agent on whose behalf the question is asked. Routes the question (a + * UI answerer only answers for agents it owns) and receives the audit + * events on its session log. + */ + agent: Agent + /** The tool the question is about (presentation and audit). */ + toolName: string + /** + * The exact tool call being decided, when the asker has one — lets a UI + * attach the prompt to the tool call it already streamed. + */ + callId?: CallId + /** The asker's human-readable explanation of WHY it is asking. */ + reason?: string + /** + * Aborting withdraws the question: the request settles `'cancelled'` + * immediately and a late answer from a still-pending answerer is discarded. + */ + signal?: AbortSignal +} +``` + +## Dispatch and audit + +`ctx.approval.request(req)` requires the requesting session to be inside an open turn. It appends `approval/asked`, obtains one outcome, appends the matching `approval/decided`, and resolves with that outcome. The `never` policy is enforced inside the service before waterfall dispatch, so even an answerer registered later with `prepend` cannot bypass it. Answerers return an outcome when they own the request or call `next()` to delegate; the first answer occupies the single decision slot. + +The audit events are log-only and do not enter the model transcript. Model-visible behavior is the caller's derived tool result, while the request header records the prompt policy that the model actually saw. Service disposal removes its prompt section and pre-step narrator together; answerer listeners are independently effect-bound to their owning plugins. diff --git a/docs/core-data-structures/bash.md b/docs/core-data-structures/bash.md index 273ba5ebe8..51f7cb0696 100644 --- a/docs/core-data-structures/bash.md +++ b/docs/core-data-structures/bash.md @@ -44,6 +44,20 @@ interface BashExecRequest { * ownerless background start (a non-agent caller). */ owner?: OwnerToken | undefined + /** + * Explicit per-call sandbox-policy input, overriding the executor's + * configured default mode for THIS call. Never a silent default: a + * consumer sets it only from an explicit policy source — an + * `'allowed-once'` grant a human just issued through `ctx.approval` (the + * escalation flow in the sandbox RFC § Escalation, which outranks), or the + * session's standing override folded from its own `bash/sandbox-mode` + * events (the sandbox RFC § Per-session mode switching — the user's recorded per-session + * choice). A sandboxing executor confines THIS call under the given mode; + * a non-sandboxing executor carries the field and confines nothing (the + * tool layer stamps neither escalation nor overrides without a sandboxing + * executor — see {@link BashExecutor.sandboxMode}). + */ + sandboxMode?: SandboxMode | undefined } ``` @@ -79,6 +93,16 @@ interface BashExecSpec { * task. `start()` stores it; `run()` (foreground) ignores it. */ owner: OwnerToken | undefined + /** + * The sandbox mode this call executes under, REQUIRED-but-nullable for the + * same visibility reason as `owner`. A sandboxing executor's `resolve()` + * stamps the effective mode (the request's explicit override, else its + * configured default) so `run()`/`start()` read the spec, never the config; + * a non-sandboxing executor carries the request value through verbatim and + * ignores it (`undefined` under such an executor means what its README says: + * unconfined execution). + */ + sandboxMode: SandboxMode | undefined } ``` @@ -106,6 +130,12 @@ interface BashRunResult { timeoutMs: number stdout: CollectedOutput stderr: CollectedOutput + /** + * Sandbox facts, present iff a sandboxing executor ran the command — an + * unsandboxed executor (e.g. `dsh-bash-local`) never sets it. See + * {@link BashSandboxInfo} for the `denied` classification semantics. + */ + sandbox?: BashSandboxInfo } ``` @@ -122,9 +152,52 @@ interface CollectedOutput { } ``` +## File sandbox: `BashSandboxInfo` + +A sandbox-consuming executor (`dsh-bash-sandbox`) exposes its configured fallback through `BashExecutor.sandboxMode`. The tool layer folds each agent session's durable `bash/sandbox-mode` override, stamps the effective mode onto the request, states it in the per-agent prompt, and may replace it for one user-approved strictly wider call. The mode/enforcement vocabulary is owned and cataloged by the [`@deepseek-ai/dsh-sandbox` seam](sandbox.md), whose provider wraps the executor's argv; modes govern FILE effects only, not network or process visibility. + +A sandboxed run always reports the facts it executed under on `BashRunResult.sandbox`: `denied` is the executor's conservative classification of a failure as sandbox-caused (a failed exit whose stderr carries a filesystem-permission signature — never a clean exit or a signal kill), read from the collected stderr tail; `enforcement` reports how completely the selected backend governs the mode's file effects (`SandboxEnforcement = 'full' | 'partial'` — `partial` when an older Landlock ABI governs only a subset of the requested accesses; absent under `danger-full-access`, where nothing is confined); `runnerFailed` marks the opposite of a denial — the sandbox RUNNER itself failed and the command never ran (stamped only on settled background tasks; a foreground run surfaces the same condition as the thrown `SANDBOX_UNAVAILABLE` error): + +```ts type-equiv +interface BashSandboxInfo { + /** The mode the command actually ran under. */ + mode: SandboxMode + /** + * True when the executor classifies this run's failure as the sandbox + * denying a file operation. The classification is CONSERVATIVE (a failed + * exit whose stderr carries a filesystem-permission signature) and reads + * the COLLECTED stderr — the bounded in-memory tail per + * {@link CollectedOutput} semantics, so a signature that survives only in a + * spill file is missed toward `denied: false`. A plain command failure + * keeps `denied: false` even under a sandboxed mode. + */ + denied: boolean + /** + * How completely the runner enforced `mode`'s file effects — see + * {@link SandboxEnforcement}. Absent exactly when `mode` is + * `danger-full-access`: nothing is confined, so there is no enforcement to + * report. + */ + enforcement?: SandboxEnforcement + /** + * True when the executor classifies this failure as the SANDBOX RUNNER + * itself failing (missing binary, refused profile, fail-closed refusal + * before exec) — the command NEVER RAN; this is a sandbox failure, not a + * task failure, and it outranks `denied` (a runner's own error text can + * contain denial words). Only ever stamped on settled BACKGROUND tasks: a + * foreground run surfaces the same condition as the thrown + * `SANDBOX_UNAVAILABLE` error instead (the foreground path has an error + * channel; a settled task's facts are its only channel). + */ + runnerFailed?: boolean +} +``` + +One more piece completes the vocabulary: the `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws — and the executor propagates — when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background task records `runnerFailed`. The model sees the current effective mode in the prompt, receives denial/runner facts in results, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox RFC](../rfc/implemented/feature/2026-07-06-sandbox.md). + ## Background tasks: `BashTask` -A long-running command started with `start()` is tracked as a `BashTask`. `BashTaskStatus` is `'running' | 'completed' | 'killed'`; `done` resolves when the underlying process closes and never rejects. +A long-running command started with `start()` is tracked as a `BashTask`. `BashTaskStatus` is `'running' | 'completed' | 'killed'`; `done` resolves when the underlying process closes and never rejects. A sandboxing executor stamps `sandbox` once the task settles — classification runs against the settled task's collected stderr — so the field is absent while running and under an unsandboxed executor. ```ts type-equiv interface BashTask { @@ -137,6 +210,16 @@ interface BashTask { signal: NodeJS.Signals | null /** Resolves when the underlying process closes (never rejects). */ readonly done: Promise + /** + * Sandbox facts for this task's execution, stamped by a sandboxing executor + * once the task settles and BEFORE completion listeners are notified — an + * `onTaskDone` consumer and a `done` awaiter both see it. Denial + * classification runs against the settled task's collected stderr, so the + * field cannot exist earlier: absent while the task is running and under an + * executor that does not sandbox. See {@link BashSandboxInfo} for the + * `denied` semantics. + */ + sandbox?: BashSandboxInfo } ``` diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 9611adab6f..bdcb66d6bb 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -20,9 +20,12 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` | | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, the `tools/pre-execute`/`tools/post-execute` pipeline | | [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy | +| [approval.md](approval.md) | the one-shot user-approval seam: `ApprovalRequest`, `ApprovalOutcome`, per-session policy, audit and answerer contracts | | [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashTask`s | +| [sandbox.md](sandbox.md) | the process-confinement seam: file-effect modes, `SandboxPolicy`, `ConfinedArgv`, enforcement and fail-closed errors | | [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy | | [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` | +| [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading | | [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface | | [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split | | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider/capability status, `WebError` | diff --git a/docs/core-data-structures/sandbox.md b/docs/core-data-structures/sandbox.md new file mode 100644 index 0000000000..6b7b212373 --- /dev/null +++ b/docs/core-data-structures/sandbox.md @@ -0,0 +1,82 @@ +# Process Sandbox + +The process-sandbox seam of [dsh-sandbox](../../packages/sandbox/sandbox) wraps a same-world subprocess argv in a file-effect policy without coupling consumers to a platform runner. [dsh-sandbox-local](../../packages/sandbox/sandbox-local) supplies the Linux bwrap/Landlock and macOS Seatbelt backends; [dsh-bash-sandbox](../../packages/bash/bash-sandbox) is the first consumer. Containers, microVMs, and remote execution are sibling implementations of whole capability seams, not providers of `ctx.sandbox`. + +Source: [`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox/src/index.ts) + +## Modes and enforcement + +`SandboxMode` governs filesystem effects only. `read-only` denies writes except the required `/dev/null` sink; `workspace-write` permits writes under the workspace root and the backend's promised temp area; `danger-full-access` bypasses confinement. Network and process visibility are outside this vocabulary. + +```ts type-equiv +type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access' +``` + +Only the first two modes can be sent to a provider. A `danger-full-access` consumer spawns its original argv and does not call `ctx.sandbox`. + +```ts type-equiv +type ConfinedSandboxMode = Exclude +``` + +Enforcement is a reported fact. `full` means the backend governs every file effect promised by the mode; `partial` means an active backend or older kernel ABI governs only a subset, so consumers that require the absolute promise must reject or surface that distinction. + +```ts type-equiv +type SandboxEnforcement = 'full' | 'partial' +``` + +## Per-call policy + +The policy is fully resolved and carried per call. This permits concurrent consumers and one-shot escalated retries to ask the same provider for different boundaries without mutating provider state. + +```ts type-equiv +interface SandboxPolicy { + /** The file-effect mode this execution runs under. */ + mode: ConfinedSandboxMode + /** Absolute root directory `workspace-write` may write under. */ + workspaceRoot: string +} +``` + +## Wrapped argv and classification dialects + +`ConfinedArgv` is what the consumer spawns. Besides the replacement argv, it carries the backend's enforcement fact and two orthogonal stderr dialects. `denialSignatures` identify the confined command being blocked while the sandbox works correctly. `runnerFailureSignatures` identify the sandbox runner refusing or failing before it executes the command; consumers check these first and surface a sandbox infrastructure failure, never an ordinary task failure. + +```ts type-equiv +interface ConfinedArgv { + /** The wrapped argv (runner, profile, separator, then the caller's argv). */ + argv: string[] + /** How completely the selected backend enforces the policy's file effects. */ + enforcement: SandboxEnforcement + /** + * The selected backend's denial DIALECT: the case-insensitive stderr + * substrings a file effect denied by THIS backend produces (EROFS text + * under bwrap's read-only binds, EACCES under Landlock, EPERM under + * Seatbelt). A consumer that infers denials from a failed run's stderr + * matches against exactly these rather than a cross-backend union — the + * union claims denials a given backend never produces. + */ + denialSignatures: readonly string[] + /** + * How the RUNNER ITSELF failing identifies itself: case-insensitive stderr + * substrings produced when the sandbox binary is missing, refuses its + * profile, or fails closed before exec'ing the command (`bwrap: `, + * `landlock-run: `, `sandbox-exec: ` — each covers both the runner's own + * error prefix and the shell's runner-not-found message). ORTHOGONAL to + * {@link denialSignatures}: a denial is the confined COMMAND being blocked + * (the sandbox working as designed); a runner failure means the command + * NEVER RAN and must surface as a sandbox failure, not a task failure — + * consumers check these signatures FIRST (a runner's own error text may + * contain denial words, e.g. an unopenable grant root reporting + * `Permission denied`). + */ + runnerFailureSignatures: readonly string[] +} +``` + +An operator-configured local runner must supply at least one `runnerFailureSignatures` entry for its own pre-exec refusal dialect; the provider adds outer-shell missing and unexecutable forms automatically. This makes an executable custom runner rejecting its profile distinguishable from the wrapped command exiting with the same status. + +## Provider and fail-closed errors + +`ctx.sandbox.confine(argv, policy)` returns a `ConfinedArgv` or throws `SandboxUnavailableError` with code `SANDBOX_UNAVAILABLE` when no usable backend exists. A selected runner can also fail closed at execution time, in which case its failure signature carries the same infrastructure meaning. Silent unconfined passthrough is never legal for a confined policy. + +Provider probing arbitrates between multiple candidates and is cached for the provider lifetime. A platform with one candidate may select it directly; execution-time refusal retains the safety property. The local provider reports bwrap and Seatbelt as full and preserves the Landlock launcher's full/partial kernel verdict. diff --git a/docs/core-data-structures/skills.md b/docs/core-data-structures/skills.md new file mode 100644 index 0000000000..b356aba720 --- /dev/null +++ b/docs/core-data-structures/skills.md @@ -0,0 +1,116 @@ +# Skills + +The [skill capability family](../../packages/skill) is split across three packages: the registry ([dsh-skill](../../packages/skill/skill), `ctx.skills`) merges provider catalogs; the local provider ([dsh-skill-local](../../packages/skill/skill-local)) scans project/custom/user directories; the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)) owns the session-prefix catalog and model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md). + +Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts). + +## Provider registry + +`ctx.skills` is a multi-provider registry. Providers can represent local directories, embedded plugin data, HTTP catalogs, or another source. Provider plugins register synchronously during `apply()`; remote initialization, authentication, and discovery are awaited by `list()`. The registry validates candidates, resolves duplicate skill names first-wins by rank/provider order/local order, and sorts the final summaries by `name` for deterministic consumers. A provider `list()` rejection is logged and skipped without caching the degraded catalog; malformed candidates still fail fast because they violate the provider contract. + +```ts type-equiv +interface SkillProvider { + name: string + list(options: SkillLookupOptions): Promise + get(candidate: SkillCandidate, options: SkillLookupOptions): Promise +} +``` + +## Local discovery priority + +The shipped local provider scans roots in rank order: + +| Rank | Source | Root | +|---|---|---| +| 100 | `project-dsh` | `/.dsh/skills` | +| 200 | `project-agents` | `/.agents/skills` | +| 300 | `custom` | `Config.customSkillDirs` | +| 400 | `user-dsh` | `/skills` | +| 500 | `user-agents` | `/skills` | + +The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child, and DeepSeek Harness no longer ships built-in system skills from the local provider. Additional built-ins can be supplied later by another provider. + +## Skill identity + +Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`/SKILL.md`) and flat Markdown files (`.md`). Nested recursive `**/SKILL.md` discovery is intentionally outside v1. + +```ts type-equiv +type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | (string & {}) +``` + +## Summaries, candidates, and complete definitions + +`SkillSummary` is the registry's model-invocable summary shape. Consumers choose which fields to render; the session catalog uses only `name` and `description`, never the body or absolute file path. `disableModelInvocation` hides a skill from model listings while allowing trusted code to load it by name. + +```ts type-equiv +interface SkillSummary { + name: string + description: string + whenToUse?: string + disableModelInvocation?: boolean + source: SkillSource + provider: string + resourceBase?: SkillResourceBase +} +``` + +`SkillCandidate` is the provider-to-registry shape. `locator` is opaque provider state; the registry only stores it and gives it back to the winning provider's `get()`. + +```ts type-equiv +interface SkillCandidate extends SkillSummary { + rank: number + locator: unknown + path?: string + metadata?: Record +} +``` + +`SkillDefinition` is the complete parsed result returned by `ctx.skills.get()` and used by the `skill` tool. `resourceBase` tells the tool how to render relative-resource guidance for local, URL, or provider-managed skills. + +```ts type-equiv +type SkillResourceBase = + | { kind: 'directory'; path: string } + | { kind: 'url'; url: string } + | { kind: 'opaque'; description: string } +``` + +```ts type-equiv +interface SkillDefinition extends SkillSummary { + content: string + path?: string + metadata?: Record +} +``` + +Runtime skills use the same complete shape and participate in the same first-wins collection order. The returned disposer removes the contribution and invalidates discovery caches. + +```ts type-equiv +type SkillRegistration = Omit & { + provider?: string +} +``` + +## Lookup and configuration + +Skill lookup is cwd-sensitive because providers may expose workspace-local skills, and its optional signal cancels provider work for the caller. If no git root is found, the local provider treats the supplied cwd itself as the project root. + +```ts type-equiv +interface SkillLookupOptions { + cwd?: string | undefined + signal?: AbortSignal | undefined +} +``` + +The registry owns only its discovery-cache bound. The local provider owns filesystem roots (`dshHome`, `agentsHome`, and `customSkillDirs`). The consumer owns its catalog description bound. + +```ts type-equiv +interface Config { + collectCacheMaxEntries?: number +} +``` + +## Session catalog and tool contract + +`dsh-tool-skill` contributes a user-role `` through `agent/session-prefix`. The catalog contains sorted skill `name` and normalized, XML-escaped `description` only; it omits bodies, paths, sources, providers, and routing hints. Prefix discovery forwards the caller's abort signal through `SkillLookupOptions`. `catalogDescriptionMaxLength` is the consumer config for the description bound, with default `500` and integer minimum `3`. Its request-only, header-logged lifecycle is defined by the [session-prefix RFC](../rfc/implemented/feature/2026-07-07-session-prefix.md). + +The model-facing `skill({ name })` tool validates the kebab-case name, loads the complete definition for the calling agent cwd, reports an unresolved skill as unknown or no longer available, rejects `disableModelInvocation` skills, and returns a tool result containing ``, ``, and ``. `resourceBase` resolves explicitly referenced scripts, references, and assets only as needed; the loaded result does not enumerate a skill directory. The tool result is the model-visible path for complete instructions. diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index acbe700965..2515b24801 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -10,15 +10,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/error` | `emit` | [`packages/core/agent/src/types.ts:476`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:357`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:370`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:357`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`user-approval`](../packages/ui/user-approval) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:370`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | | `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:290`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:394`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:441`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:441`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill) | | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:305`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/types.ts:281`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:451`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | | `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:464`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:64`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | @@ -26,16 +27,18 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `session/created` | `emit` | [`packages/core/session/src/index.ts:39`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence) | | `session/event` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`parallel`) | [`session-persistence`](../packages/session-persistence/session-persistence) | +| `skill/provider-added` | `emit` | [`packages/skill/skill/src/index.ts:130`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`emit`) | - | +| `skill/provider-removed` | `emit` | [`packages/skill/skill/src/index.ts:136`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`emit`) | - | | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:98`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) | | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) | | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:83`](../packages/subagent/subagent/src/index.ts) | - | [`tool-subagent`](../packages/subagent/tool-subagent) | | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:91`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:132`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | -| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:111`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) | -| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:127`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | -| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:91`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:135`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | +| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:114`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) | +| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:130`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | +| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:94`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:96`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:85`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:106`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | diff --git a/docs/module-graph.md b/docs/module-graph.md index bab33bdddd..56c3a64f95 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -27,6 +27,7 @@ flowchart TD subgraph group_bash["packages/bash"] pkg_bash["bash"] pkg_bash_local["bash-local"] + pkg_bash_sandbox["bash-sandbox"] pkg_tool_bash["tool-bash"] end subgraph group_fs["packages/fs"] @@ -35,6 +36,11 @@ flowchart TD pkg_fs_policy["fs-policy"] pkg_tool_fs["tool-fs"] end + subgraph group_skill["packages/skill"] + pkg_skill["skill"] + pkg_skill_local["skill-local"] + pkg_tool_skill["tool-skill"] + end subgraph group_compact["packages/compact"] pkg_compact["compact"] pkg_compact_basic["compact-basic"] @@ -87,6 +93,7 @@ flowchart TD pkg_app_boot["app-boot"] pkg_stdio_agent["stdio-agent"] pkg_tool_ask_user["tool-ask-user"] + pkg_user_approval["user-approval"] pkg_user_interaction["user-interaction"] end subgraph group_code_runtime["packages/code-runtime"] @@ -96,30 +103,37 @@ flowchart TD subgraph group_guard["packages/guard"] pkg_repeat_tool_guard["repeat-tool-guard"] end + subgraph group_sandbox["packages/sandbox"] + pkg_sandbox["sandbox"] + pkg_sandbox_local["sandbox-local"] + end subgraph group_workflow["packages/workflow"] pkg_tool_workflow["tool-workflow"] pkg_workflow["workflow"] pkg_workflow_workerthread["workflow-workerthread"] end pkg_llm --> pkg_brand - pkg_bash --> pkg_brand pkg_code_runtime_worker --> pkg_code_runtime pkg_llm_deepseek --> pkg_llm pkg_llm_pi_ai --> pkg_llm pkg_session --> pkg_brand pkg_session --> pkg_llm pkg_system_prompt --> pkg_llm - pkg_bash_local --> pkg_bash - pkg_bash_local --> pkg_timeout pkg_fs --> pkg_brand pkg_fs --> pkg_llm pkg_web --> pkg_llm + pkg_sandbox --> pkg_llm pkg_agent --> pkg_brand pkg_agent --> pkg_llm pkg_agent --> pkg_session pkg_agent --> pkg_system_prompt + pkg_bash --> pkg_brand + pkg_bash --> pkg_sandbox + pkg_bash --> pkg_session pkg_fs_local --> pkg_fs pkg_fs_policy --> pkg_fs + pkg_skill_local --> pkg_fs + pkg_skill_local --> pkg_skill pkg_compact --> pkg_llm pkg_compact --> pkg_session pkg_web_fetch_local --> pkg_timeout @@ -127,20 +141,19 @@ flowchart TD pkg_web_search_deepseek --> pkg_web pkg_web_search_exa --> pkg_web pkg_web_search_perplexity --> pkg_web - pkg_hook_protocol --> pkg_bash - pkg_hook_protocol --> pkg_session pkg_session_persistence --> pkg_session pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session - pkg_tools --> pkg_agent - pkg_tools --> pkg_code_runtime - pkg_tools --> pkg_llm - pkg_tools --> pkg_session - pkg_tools --> pkg_system_prompt + pkg_sandbox_local --> pkg_llm + pkg_sandbox_local --> pkg_sandbox + pkg_bash_local --> pkg_bash + pkg_bash_local --> pkg_timeout pkg_compact_basic --> pkg_agent pkg_compact_basic --> pkg_compact pkg_compact_basic --> pkg_llm pkg_compact_basic --> pkg_session + pkg_hook_protocol --> pkg_bash + pkg_hook_protocol --> pkg_session pkg_session_persistence_jsonl --> pkg_session pkg_session_persistence_jsonl --> pkg_session_persistence pkg_session_persistence_sqlite --> pkg_session @@ -148,11 +161,25 @@ flowchart TD pkg_invariants --> pkg_agent pkg_invariants --> pkg_llm pkg_invariants --> pkg_session + pkg_user_approval --> pkg_agent + pkg_user_approval --> pkg_brand + pkg_user_approval --> pkg_llm + pkg_user_approval --> pkg_session + pkg_user_approval --> pkg_system_prompt pkg_user_interaction --> pkg_agent pkg_user_interaction --> pkg_llm pkg_workflow --> pkg_agent pkg_workflow --> pkg_brand pkg_workflow --> pkg_llm + pkg_tools --> pkg_agent + pkg_tools --> pkg_code_runtime + pkg_tools --> pkg_llm + pkg_tools --> pkg_session + pkg_tools --> pkg_system_prompt + pkg_tools --> pkg_user_approval + pkg_bash_sandbox --> pkg_bash + pkg_bash_sandbox --> pkg_bash_local + pkg_bash_sandbox --> pkg_sandbox pkg_agent_loop --> pkg_agent pkg_agent_loop --> pkg_llm pkg_agent_loop --> pkg_session @@ -162,14 +189,20 @@ flowchart TD pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_bash pkg_tool_bash --> pkg_llm + pkg_tool_bash --> pkg_sandbox pkg_tool_bash --> pkg_session_persistence pkg_tool_bash --> pkg_system_prompt pkg_tool_bash --> pkg_tools + pkg_tool_bash --> pkg_user_approval pkg_tool_fs --> pkg_fs pkg_tool_fs --> pkg_llm pkg_tool_fs --> pkg_session pkg_tool_fs --> pkg_system_prompt pkg_tool_fs --> pkg_tools + pkg_tool_skill --> pkg_agent + pkg_tool_skill --> pkg_llm + pkg_tool_skill --> pkg_skill + pkg_tool_skill --> pkg_tools pkg_subagent --> pkg_agent pkg_subagent --> pkg_llm pkg_subagent --> pkg_tools @@ -191,10 +224,13 @@ flowchart TD pkg_hooks_codex --> pkg_session_persistence pkg_hooks_codex --> pkg_tools pkg_acp --> pkg_agent + pkg_acp --> pkg_bash pkg_acp --> pkg_llm + pkg_acp --> pkg_sandbox pkg_acp --> pkg_session pkg_acp --> pkg_session_persistence pkg_acp --> pkg_tools + pkg_acp --> pkg_user_approval pkg_acp --> pkg_user_interaction pkg_tool_ask_user --> pkg_agent pkg_tool_ask_user --> pkg_tools @@ -211,8 +247,11 @@ flowchart TD pkg_agent_core --> pkg_invariants pkg_agent_core --> pkg_llm pkg_agent_core --> pkg_session + pkg_agent_core --> pkg_skill + pkg_agent_core --> pkg_skill_local pkg_agent_core --> pkg_system_prompt pkg_agent_core --> pkg_tool_bash + pkg_agent_core --> pkg_tool_skill pkg_agent_core --> pkg_tools pkg_subagent_acp --> pkg_agent pkg_subagent_acp --> pkg_llm @@ -271,52 +310,59 @@ flowchart TD | --- | --- | --- | | [`brand`](../packages/util/brand) | `util` | — | | [`timeout`](../packages/util/timeout) | `util` | — | +| [`skill`](../packages/skill/skill) | `skill` | — | | [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | `subagent` | — | | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — | | [`app-boot`](../packages/ui/app-boot) | `ui` | — | | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — | | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) | -| [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand) | | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime) | | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) | | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm) | | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`system-prompt`](../packages/core/system-prompt) | `core` | [`llm`](../packages/llm/llm) | -| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`timeout`](../packages/util/timeout) | | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`web`](../packages/web/web) | `web` | [`llm`](../packages/llm/llm) | +| [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`llm`](../packages/llm/llm) | | [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | +| [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) | | [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs) | +| [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`skill`](../packages/skill/skill) | | [`compact`](../packages/compact/compact) | `compact` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) | | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`web`](../packages/web/web) | | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`web`](../packages/web/web) | | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`web`](../packages/web/web) | -| [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`session`](../packages/core/session) | | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) | | [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | +| [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | +| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`timeout`](../packages/util/timeout) | | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | +| [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | | [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | +| [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) | | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | +| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) | +| [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`sandbox`](../packages/sandbox/sandbox) | | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | -| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) | | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) | | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) | | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) | | [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`tools`](../packages/core/tools) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) | -| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | +| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) | | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | -| [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) | +| [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 917386af9b..289b3c4755 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -11,6 +11,40 @@ The on-disk envelope around every payload is `SessionEvent` — `type`, monotoni ## Events +### `approval/*` + +#### `approval/asked` — log-only + +An approval question was put to the answerer chain — log-only audit (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs it with the `approval/decided` that always follows; `toolName` is the tool the question is about, `callId` the exact tool call when the asker had one, `reason` the asker's human-readable explanation (e.g. a hook's permission-decision reason). + +```ts persistence-catalog +'approval/asked': { id: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string } +``` + +Types: [CallId](core-data-structures/core.md) + +Source: [`packages/ui/user-approval/src/index.ts:78`](../packages/ui/user-approval/src/index.ts) + +#### `approval/decided` — log-only + +The outcome of a prior `approval/asked` (same `id`) — log-only audit. Exactly one per ask, appended when the outcome is known: a decision, a cancellation, or the fail-closed `'unavailable'`. + +```ts persistence-catalog +'approval/decided': { id: ApprovalRequestId; outcome: ApprovalOutcome } +``` + +Source: [`packages/ui/user-approval/src/index.ts:89`](../packages/ui/user-approval/src/index.ts) + +#### `approval/policy` — log-only + +The session's approval policy was switched — log-only, durable, replayable, never in the model transcript (the model learns the policy from the prompt section and the narrator's notices). The LAST such event is the session's override (effectiveApprovalPolicy); who asked for it is derivable from position (an event after the log's last `request/header*` was a runtime switch by the user). + +```ts persistence-catalog +'approval/policy': { policy: ApprovalPolicy } +``` + +Source: [`packages/ui/user-approval/src/index.ts:101`](../packages/ui/user-approval/src/index.ts) + ### `assistant/*` #### `assistant/chunk` — log-only @@ -37,6 +71,18 @@ Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-st Source: [`packages/core/session/src/types.ts:320`](../packages/core/session/src/types.ts) +### `bash/*` + +#### `bash/sandbox-mode` — log-only + +The session's sandbox mode was switched — log-only (like `approval/*`; NOT a surface event, carries no `surfaceOp`): durable and replayable, never in the model transcript. The LAST such event is the session's override (effectiveSandboxMode); who asked for it is derivable from position (an event after the log's last `request/header*` was a runtime switch by the user; see the tool layer's narrator). + +```ts persistence-catalog +'bash/sandbox-mode': { mode: SandboxMode } +``` + +Source: [`packages/bash/bash/src/session-mode.ts:31`](../packages/bash/bash/src/session-mode.ts) + ### `compact/*` #### `compact/end` — log-only diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index 603ccdbf26..e809880129 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -8,8 +8,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | Title | First proposed | |---|---| -| [Agent Client Protocol (ACP) support — drive the coding agent from external editors](proposed/feature/2026-06-14-acp-agent-client-protocol.md) | 2026-06-14 | -| [Multiplex concurrent ACP sessions over one connection](proposed/feature/2026-06-14-acp-multi-session.md) | 2026-06-14 | | [Pre-tool input rewrite — a consistent design](proposed/feature/2026-06-30-pre-tool-input-rewrite.md) | 2026-06-30 | | [Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)](proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md) | 2026-07-07 | @@ -49,6 +47,8 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | Title | First proposed | |---|---| +| [Agent Client Protocol (ACP) support — drive the coding agent from external editors](implemented/feature/2026-06-14-acp-agent-client-protocol.md) | 2026-06-14 | +| [Multiplex concurrent ACP sessions over one connection](implemented/feature/2026-06-14-acp-multi-session.md) | 2026-06-14 | | [Code Mode — the model writes TypeScript against the tool registry](implemented/feature/2026-06-15-code-mode.md) | 2026-06-15 | | [Filesystem tool schemas — model-facing read/write/edit shapes](implemented/feature/2026-06-17-filesystem-tool-schemas.md) | 2026-06-17 | | [Rich ACP bash rendering — the terminal card via the `_meta` convention](implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) | 2026-06-18 | @@ -63,7 +63,10 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [SessionStore fork API](implemented/feature/2026-06-30-session-store-fork-api.md) | 2026-06-30 | | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 | | [Dynamic workflows — a script-driven multi-agent orchestration seam](implemented/feature/2026-07-05-dynamic-workflows.md) | 2026-07-05 | +| [Skill system — progressive disclosure instructions for agents](implemented/feature/2026-07-05-skill-system.md) | 2026-07-05 | +| [The approval seam — one-shot permission decisions over a waterfall of answerers](implemented/feature/2026-07-06-approval-seam.md) | 2026-07-06 | | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 | +| [The subprocess sandbox — confinement seam, native runners, escalation, and per-session modes](implemented/feature/2026-07-06-sandbox.md) | 2026-07-06 | | [The session prefix — request-only messages in front of the derived history](implemented/feature/2026-07-07-session-prefix.md) | 2026-07-07 | | [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 | | [The self-referential cordis toolset](implemented/feature/2026-07-08-self-referential-cordis-toolset.md) | 2026-07-08 | diff --git a/docs/rfc/implemented/architecture/2026-06-14-session-persistence.md b/docs/rfc/implemented/architecture/2026-06-14-session-persistence.md index 135c1671f6..1d3ce8929c 100644 --- a/docs/rfc/implemented/architecture/2026-06-14-session-persistence.md +++ b/docs/rfc/implemented/architecture/2026-06-14-session-persistence.md @@ -6,7 +6,7 @@ Status: implemented ## Problem -Sessions lived only in memory. The example `session-jsonl.ts` plugin (duplicated byte-for-byte in both examples) was write-only telemetry: it buffered `session/event` and appended JSON lines, with no read/replay path, no crash-safety (no fsync, no atomic write, a fire-and-forget dispose drain), no listing, and no format versioning. Nothing could rehydrate a past session from disk into a live agent, so durable resume ("continue yesterday's task"), durable forking, and the ACP `session/load` method ([ACP support](../../proposed/feature/2026-06-14-acp-agent-client-protocol.md)) were all impossible. +Sessions lived only in memory. The example `session-jsonl.ts` plugin (duplicated byte-for-byte in both examples) was write-only telemetry: it buffered `session/event` and appended JSON lines, with no read/replay path, no crash-safety (no fsync, no atomic write, a fire-and-forget dispose drain), no listing, and no format versioning. Nothing could rehydrate a past session from disk into a live agent, so durable resume ("continue yesterday's task"), durable forking, and the ACP `session/load` method ([ACP support](../../implemented/feature/2026-06-14-acp-agent-client-protocol.md)) were all impossible. The [event-sourced model](2026-06-11-event-sourced-sessions.md) makes the append-only log the single source of truth and derives LLM history from it. Persistence had to stay faithful to that: persist the existing `SessionEvent` directly, with no parallel "persisted message" type that the log is converted to and from. The backend also had to be swappable — a file store now, a database store later — behind one interface. @@ -33,4 +33,4 @@ Format versioning: the header carries a `version`; `load` rejects any non-curren ## Consequences -Two new packages and the metadata seam in `dsh-session` (`session.header`, the `create(id?, options?)` signature). Bought: durable resume/fork, a read/replay path, crash tolerance, and the foundation the ACP `session/load` ([ACP support](../../proposed/feature/2026-06-14-acp-agent-client-protocol.md)) needs — all over the existing event-sourced log, with the backend swappable behind one interface. The reusable `runPersistenceContract` suite holds every backend to the same append-only / contiguous-seq / lazy-materialization / serializability semantics. This completes [event-sourced sessions](2026-06-11-event-sourced-sessions.md)'s deferred "real persistence backend" and resolves its `TODO(review)` on the event vocabulary: persisting the log freezes its shape, and the `assistant/chunk` fidelity question is answered above (persist verbatim). +Two new packages and the metadata seam in `dsh-session` (`session.header`, the `create(id?, options?)` signature). Bought: durable resume/fork, a read/replay path, crash tolerance, and the foundation the ACP `session/load` ([ACP support](../../implemented/feature/2026-06-14-acp-agent-client-protocol.md)) needs — all over the existing event-sourced log, with the backend swappable behind one interface. The reusable `runPersistenceContract` suite holds every backend to the same append-only / contiguous-seq / lazy-materialization / serializability semantics. This completes [event-sourced sessions](2026-06-11-event-sourced-sessions.md)'s deferred "real persistence backend" and resolves its `TODO(review)` on the event vocabulary: persisting the log freezes its shape, and the `assistant/chunk` fidelity question is answered above (persist verbatim). diff --git a/docs/rfc/implemented/feature/2026-06-14-acp-agent-client-protocol.md b/docs/rfc/implemented/feature/2026-06-14-acp-agent-client-protocol.md new file mode 100644 index 0000000000..293b1bbde6 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-06-14-acp-agent-client-protocol.md @@ -0,0 +1,57 @@ +# RFC: Agent Client Protocol (ACP) support — drive the coding agent from external editors + +Status: implemented + +## Problem + +The harness originally exposed agents only through a readline loop. That surface could carry text, but it gave an editor no structured way to create or resume sessions, correlate prompt completion, stream reasoning and tool activity, render tool-specific UI, ask for permission, or cancel one conversation without disturbing another. ACP defines those interactions as JSON-RPC over stdio, and Zed is the target client used to make concrete compatibility decisions. + +The bridge must preserve the harness's existing ownership boundaries. It cannot depend on the concrete agent loop, bypass the tool registry, execute shell commands in the editor, or invent a second source of session truth. stdout is also the protocol transport, so any accidental log output corrupts the connection. + +## Decision + +`@deepseek-ai/dsh-acp` is a UI/client-driver plugin under `packages/ui/acp`. It uses `@agentclientprotocol/sdk`'s `AgentSideConnection` over stdin/stdout and programs only interface services: the agent create/resume factory, session persistence, tool registry, user interaction, and optional approval/bash capabilities. It does not change the agent loop and is not a capability-seam implementation. + +The bridge implements the following stable session path: + +- `initialize` negotiates the protocol version, advertises text plus `resource_link` prompts, and advertises `loadSession`. +- `session/new` validates an absolute `cwd`, stores it in `SessionHeader`, creates an agent through `ctx.agents`, and returns any composition-backed config options. +- `session/load` validates the requested cwd against persisted metadata before constructing an agent, reserves the id across the asynchronous resume, replays user/assistant/tool events as ACP updates, and reports the resumed config-option fold. +- `session/prompt` accepts text and resource links, rejects unsupported or empty content, allows one in-flight prompt per session, and settles against that prompt's owning `turn/end`. An error turn rejects the RPC; other closed turn reasons map through a total ACP stop-reason codec. +- `session/cancel` calls the queue-aware agent cancel path and settles only the addressed session's prompt. + +Tool-call presentation remains tool-owned. A tool's `presentCall` and `presentResult` return the `generic`, `terminal`, or `diff` render-intent variants; the bridge switches on that union and maps it to ACP. Presenter-less tools receive a generic fallback. Bash terminal cards use Zed's capability-gated `_meta.terminal_info`, `_meta.terminal_output`, and `_meta.terminal_exit` convention; the harness still executes the command through `ctx.bash`, preserving sandbox, environment scrub, ownership, and cwd. Clients without that extension receive ordinary text content. Filesystem tools provide diff cards and file locations without hard-coded tool-name branches in the bridge. + +Permission handling is an answerer on the [user-approval seam](2026-07-06-approval-seam.md), not an ask-every-tool policy in ACP. An `approval/request` for a bridge-owned agent with a call id becomes `session/request_permission` on that agent's editor session, with one-shot allow/reject choices. Foreign or call-less requests delegate; a missing or failed answerer remains fail-closed. The plugin that asks—such as a pre-execute policy or bash escalation—owns the decision to ask. + +The bridge advertises ACP config options instead of session modes. `sandbox-mode` exists only when the mounted bash executor reports sandbox capability, and `approval-policy` exists only when `ctx.approval` is composed. Each option is an independent select whose current value is the session event fold over the composition default. `session/set_config_option` validates against the owning domain vocabulary and writes through `setSandboxMode` or `setApprovalPolicy`. An open-turn switch appends immediately; an idle switch is overlaid in the response and anchored at the next turn start. Until that anchor it is memory-only and a crash reverts to the durable fold. ACP session modes are deliberately not modeled because one mode list cannot represent these orthogonal knobs and config options are the forward protocol surface. Runtime model selection remains outside this decision; `AcpConfig.model` is connection-wide. + +The bridge also provides the ACP-backed `UserInteractionProvider`: `ask_user_question` requests become form elicitations on the owning session. Select, multi-select, option descriptions, and custom-answer override semantics are preserved. + +Lifecycle ownership is explicit. The bridge holds an `AgentHandle` per live session. Disconnect and Cordis disposal cancel pending prompts, dispose every handle in parallel, await loop quiescence and persistence flush, and then remove the records. Stream notification failures are contained so a vanished client cannot corrupt an agent turn. The ACP app composition loads no stdout logger; a test guards stdout as framed JSON-RPC only. + +The precise supported and deferred protocol rows live in [`packages/ui/acp/acp-feature-support.md`](../../../../packages/ui/acp/acp-feature-support.md); the package README is the operational contract. + +## Alternatives considered + +**A prepended `tools/execute` listener that asks on every ACP-owned call** — rejected. It would hard-code permission policy into the UI bridge, ask even when no policy requires it, and could not serve approval requests that arise after execution begins. The shared user-approval seam keeps mechanism, asking policy, and UI answerer separate. + +**Inject the concrete `agentLoop`** — rejected. Agent creation, resume, idle observation, and disposal are interface-level ownership operations on `dsh-agent`; a UI plugin does not need a dependency-rule exception. + +**Execute bash through ACP `terminal/*`** — rejected. That would move execution outside the harness and bypass its sandbox, credential scrub, task ownership, cwd resolution, and session log. Terminal metadata is presentation only. + +**Represent sandbox and approval as ACP session modes** — rejected. They are independent composable settings, while a single current mode is mutually exclusive. ACP config options represent both without a cross-product and match the protocol's forward direction. + +**Hijack stdout defensively** — rejected. Process-wide monkey-patching is outside Cordis effect ownership and races the protocol transport. The app composition owns stdout purity. + +## Consequences + +Editors can create, load, prompt, cancel, render, ask, and reconfigure multiple harness sessions over one ACP connection without a loop-specific dependency. The session event log remains the durable source for replay, prompt settlement, cwd, and per-session configuration. Tool presentation and human-answer channels remain extensible plugin contracts instead of ACP-specific behavior. + +The bridge deliberately does not implement session list/delete/resume/close capabilities, MCP passthrough, additional directories, image/audio/embedded-resource prompts, runtime model selection, plans, slash commands, usage updates, editor filesystem delegation, or the ACP terminal execution sub-protocol. The feature checklist records these as unsupported rather than silently accepting them. + +An idle config selection is truthful in the live response but not durable until the next turn anchors it. Crashing before that boundary loses the pending selection; this is the cost of keeping session events turn-enclosed and replay-safe. + +## Verification + +The ACP suites cover the in-memory protocol codec, create/load replay, exact prompt settlement, cancellation races, unsupported content, tool presentation, terminal capability fallback, permission outcome mapping, config-option validation and persistence, multi-session isolation, disconnect/disposal quiescence, and HMR cleanup. Snapshot and built-bin tests exercise the app composition, while the real-API e2e self-skips without a key. diff --git a/docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md b/docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md new file mode 100644 index 0000000000..77fa2b4669 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md @@ -0,0 +1,37 @@ +# RFC: Multiplex concurrent ACP sessions over one connection + +Status: implemented + +## Problem + +An ACP editor can keep several conversations alive over one agent subprocess. A single-active-session bridge would force extra processes and would not match Zed's client model, which tracks multiple session ids and concurrent loads. Multiplexing introduces isolation risks: events, prompt completion, cancellation, permission prompts, config selections, and predictable background-task ids must never cross session boundaries. + +## Decision + +The ACP bridge stores live sessions in `Map` and keeps a `WeakMap` reverse index for agent-scoped callbacks. A record owns its agent handle, in-flight prompt, live tool-call presentation state, pending idle config switches, session cwd, and client capability snapshot. A separate loading-id set reserves each id before asynchronous resume so two pipelined loads cannot construct duplicate agents; distinct ids may load concurrently. + +Every `session/event` and `agent/status` callback resolves the owning record before sending or settling anything. Each session permits one in-flight prompt independently. The prompt records a log watermark, captures its own `turn/start`, and settles only on the matching `turn/end`; a late end from a cancelled prior turn cannot resolve a newer prompt. `session/cancel` addresses one record and calls only that agent's queue-aware cancel path. + +Permission ownership uses the same reverse index. The ACP `approval/request` answerer prompts only the editor session that owns the requesting agent and delegates foreign requests. User-interaction elicitations likewise route by agent ownership. Per-session sandbox and approval config values fold only that session's events, with pending idle switches stored on that record until the next turn anchors them. + +Background bash tasks carry an opaque owner token equal to the owning session id. `bash_output` and `bash_kill` compare the caller's token with the executor's task ownership before reading or killing; a predictable task id alone grants no access. Ownership is stored with the executor task, so a tool plugin reload does not erase it. + +Connection teardown clears the live map, settles each pending prompt as cancelled, and disposes all `AgentHandle`s in parallel. Each handle stops and awaits its loop, flushes the session while attached, unregisters the agent, and removes the session. Teardown is memoized and shared by client disconnect and plugin disposal. + +## Alternatives considered + +**One live session per connection** — rejected. It adds process overhead and contradicts the target client's multi-session shape without removing multiplexing needs from the editor. + +**A per-session `ctx.extend()`** — rejected. A child context does not by itself create a child plugin fiber, so listeners would still belong to the bridge fiber. The implemented bridge instead uses global listeners with explicit O(1) demultiplexing and per-session owned records; agent lifecycle is owned by `AgentHandle`. + +**Agent object identity as bash-task ownership** — rejected. A resumed or replaced agent object may legitimately represent the same durable session. The opaque session token is the cross-boundary identity that should survive plugin reloads. + +## Consequences + +N sessions can stream, prompt, request permission, switch config, and run background tasks concurrently without interleaving or cross-settling. A cancel or dispose in one session does not affect its neighbors. The bridge pays for explicit maps and isolation tests, but it does not add one listener set per session and therefore avoids listener fan-out during long-lived connections. + +The bridge still exposes no protocol method to close one live session independently. Today records leave together on connection teardown; session close/resume lifecycle capabilities remain deferred in the ACP feature checklist. + +## Verification + +The multi-session suite drives concurrent sessions through interleaved updates, independent in-flight prompts, targeted cancellation, same-id and distinct-id load races, permission routing, config isolation, and teardown. Tool-bash tests prove one session cannot read or kill another session's background task. diff --git a/docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md b/docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md index bca351e906..5eb38f1f99 100644 --- a/docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md +++ b/docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md @@ -4,7 +4,7 @@ Status: implemented ## Problem -The ACP bridge lets each tool own its call rendering via `presentCall`/`presentResult` (see [tool-call UI presentation](../../proposed/feature/2026-06-14-acp-agent-client-protocol.md) and `packages/core/tools`). For `bash` we surface the exact command as the `tool_call` title, the model's `description` as a content text block, `kind: 'execute'`, and the completed output wrapped in a fenced ` ```console ` text block. +The ACP bridge lets each tool own its call rendering via `presentCall`/`presentResult` (see [tool-call UI presentation](../../implemented/feature/2026-06-14-acp-agent-client-protocol.md) and `packages/core/tools`). For `bash` we surface the exact command as the `tool_call` title, the model's `description` as a content text block, `kind: 'execute'`, and the completed output wrapped in a fenced ` ```console ` text block. That is a correct, capability-free baseline, but not how the reference editors render a *terminal* tool at its best. An editor like Zed has a dedicated terminal tool-call card — a header showing the working directory, the command as the label, the command output rendered as a terminal, and an exit-status pill — but it only builds that card when the `tool_call` carries terminal metadata (below). With a plain text block the output appears as static markdown and there is no cwd header. (Zed also HIDES `rawInput` for `kind: 'execute'`, which is why the command IS the title — both reference adapters do the same. The human-readable description rides as a separate content block above the card; note this is a DELIBERATE divergence — claude-agent-acp DROPS the description in terminal mode and renders only the card — we keep the summary visible alongside.) diff --git a/docs/rfc/implemented/feature/2026-06-30-hook-bridges.md b/docs/rfc/implemented/feature/2026-06-30-hook-bridges.md index 431166e932..48bdb2b75b 100644 --- a/docs/rfc/implemented/feature/2026-06-30-hook-bridges.md +++ b/docs/rfc/implemented/feature/2026-06-30-hook-bridges.md @@ -53,7 +53,7 @@ Two different cwds, kept distinct on purpose. The hooks **themselves** run in th - **Tool-input rewrite.** A CC/Codex `updatedInput` is logged + warned, not honored — input rewrite is a deferred consistency-design problem ([the pre-tool-input-rewrite RFC](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)), because the pre-execution args are read by `tool/call` audit + `assistant/message` history + ACP/tool-bash presentation, so an honest rewrite is a design unit, not a field. - **Stop loop-guard** (`TODO(stop-loop-guard)`). CC/Codex break an infinite force-continue with `stop_hook_active` (true once a Stop hook fired this run) plus a max-consecutive cap; both are deferred. Today `stop_hook_active` is always `false`, so a Stop hook that unconditionally blocks would force-continue every step — a hook author must self-limit until the guard lands. -- **Permission `ask`** degrades to `deny` at the `tools/pre-execute` seam (`FIXME(permissions)` in the interception-seams RFC) — there is no interactive permission prompt yet. +- **Permission `ask`** — deferred at landing, since serviced: the [approval seam](2026-07-06-approval-seam.md) resolves `ask` through `ctx.approval` (ACP prompts over `session/request_permission`), degrading to `deny` only where no approval service is composed. - **Hook `continue:false` (hard halt).** A hook can ask to halt the whole run (CC/Codex `continue:false`); the shared merge folds it into `MergedHookOutcome.stop`/`stopReason`, but no bridge acts on it (`TODO(hook-continue-false)`) — the interception seams have no "hard-halt the agent" primitive yet (a Decision blocks/steers a single point, not the run). Deferred with the loop-guard work; the halt request is recorded in the `hook/result` log, and the hook keeps its per-point effect (decision/context) meanwhile. - **Config discovery.** The path is explicit in `cordis.yml` and process-level (see above); the full multi-layer CC/Codex precedence walk, per-session project-local discovery, and the trust/hash model are not reimplemented (`TODO(per-session-hook-config)`). - **Session-start / subagent-start context is best-effort, not gated (`TODO(session-start-gating)`).** `agent/session-start` is a synchronous emit and the bridge runs its hook on a detached `.then`, so the injected `additionalContext` is not guaranteed to land before the first turn reaches the model — a slow hook can miss the first request (the context then arrives as a later injection). `subagent/start` is sharper: an in-process provider may have already queued the child's prompt before the listener runs, and a short-lived child can finish before the detached inject fires. Making startup context a gated/awaited primitive is a loop-level change deferred to the interception seams; today the contract is "injected as soon as the hook resolves", not "before the first request". The bridge tests do NOT wait on the injection where they assert the guaranteed-timing behavior, so they document the real (best-effort) timing rather than masking it. diff --git a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md index 7795b044f6..5b2bb839b3 100644 --- a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md +++ b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md @@ -36,7 +36,7 @@ Add/​reshape the interception seams so every one returns a small, seam-specifi ### What this PR does NOT do -It does **not** declare `hook/*` SessionEvents (the durable hook-invocation log) — those belong to the `dsh-hook-protocol` library, because a native plugin can already use the typed Decisions without a durable hook log. A worked native-plugin example/test in this PR (`packages/core/agent-loop/tests/interception.spec.ts`) proves all the seams compose end-to-end through the REAL loop with NO `hook/*` involved — the concrete proof that "native hooks are just a plugin". Compaction (`PreCompact`/`PostCompact`), the Notification hook, Codex `PermissionRequest`, the permission/`ask` system, and the Stop loop-guard remain deferred (`FIXME(permissions)` marks the `ask`→deny degrade). +It does **not** declare `hook/*` SessionEvents (the durable hook-invocation log) — those belong to the `dsh-hook-protocol` library, because a native plugin can already use the typed Decisions without a durable hook log. A worked native-plugin example/test in this PR (`packages/core/agent-loop/tests/interception.spec.ts`) proves all the seams compose end-to-end through the REAL loop with NO `hook/*` involved — the concrete proof that "native hooks are just a plugin". Compaction (`PreCompact`/`PostCompact`), the Notification hook, Codex `PermissionRequest`, and the Stop loop-guard remain deferred; the permission/`ask` system has since landed as the [approval seam](2026-07-06-approval-seam.md), whose `ctx.approval` services the `ask` this PR shipped degraded to deny. ## Alternatives considered diff --git a/docs/rfc/implemented/feature/2026-07-05-skill-system.md b/docs/rfc/implemented/feature/2026-07-05-skill-system.md new file mode 100644 index 0000000000..b3007529cd --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-05-skill-system.md @@ -0,0 +1,53 @@ +# RFC: Skill system — progressive disclosure instructions for agents + +Status: implemented + +## Problem + +Agent products have converged on a skill pattern: keep the request prompt small by listing only available instruction bundles, then load the full body when the model decides a task matches. Codex, Claude Code, OpenCode, and Kimi Code differ in details, but all separate discovery metadata from complete instructions so a workspace can carry reusable behavior without paying the full prompt cost on every turn. + +DeepSeek Harness uses the same primitive so project-specific review, plugin-authoring, and tool-usage guidance lives next to the workspace or the user's agent configuration instead of being hard-coded into the loop. + +## Decision + +`@deepseek-ai/dsh-skill` is the pure provider registry (`ctx.skills`), `@deepseek-ai/dsh-skill-local` is the shipped local filesystem provider, and `@deepseek-ai/dsh-tool-skill` owns the session-prefix catalog and model-facing loader tool. `dsh-agent-core` loads the registry, local provider, and consumer by default so stdio and ACP apps get the same behavior while embedded or remote providers contribute skills without changing the registry or consumer. Its `skills` config forwards `registry`, `local`, and `tool` branches to those owners. + +Provider plugins register synchronously during `apply()`. Provider catalogs return ranked candidates from awaited `list()` calls, where remote providers perform initialization, authentication, and discovery while honoring the lookup abort signal. The registry validates each candidate, resolves same-name skills first-wins by rank, provider registration order, and provider-local order, then sorts summaries by skill name for deterministic consumers. It caches only completed catalog snapshots and retries when a provider/runtime revision changes during discovery, so an unload cannot freeze a stale, unresolvable skill into a session prefix. Runtime `ctx.skills.register(...)` remains a convenience for embedded in-process skills and uses project-over-user priority; `runtime` is reserved as the registry-owned provider name. + +The local provider scans cwd-sensitive project roots, custom roots, and user roots in first-wins rank order: project `.dsh`, project `.agents`, `customSkillDirs`, user `.dsh`, then user `.agents`. The user `.dsh/skills` scan skips `.system` so a system-owned directory is not treated as normal user content. DeepSeek Harness does not ship built-in system skills; embedded or remote providers supply additional skills when configured. + +Each skill is either `/SKILL.md` or `.md` with YAML frontmatter. `name` and `description` are required; `whenToUse`, `disableModelInvocation`, and `metadata` are optional. Names are kebab-case. YAML frontmatter is parsed with the `yaml` package instead of `js-yaml` or a hand-written parser: `yaml` is the already-declared modern parser for this package's limited frontmatter needs, and a narrow parser would either reject valid YAML users expect to work or grow into an unreviewed YAML subset. + +Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is loaded: project-root lookup probes `.git` with `resolve` and `stat`, root discovery uses `listDir`, and skill reads use `readText`. The Node filesystem remains a fallback for minimal contexts that mount `dsh-skill-local` without the fs seam. Missing roots, unreadable or malformed skill files, and transient provider `list()` failures degrade to warn-and-skip so one bad source does not make every agent request fail; malformed candidates still fail fast because they are provider contract violations. + +`dsh-tool-skill` contributes one user-role `` catalog through [`agent/session-prefix`](2026-07-07-session-prefix.md). The catalog contains sorted skill name and description only; it excludes bodies, paths, sources, providers, and routing hints. Descriptions are whitespace-normalized, XML-escaped, and capped by `catalogDescriptionMaxLength`, whose default is `500` and minimum is `3`. The session-prefix seam freezes the request-only catalog per loop instance and records it in the request header, preserving reconstructability without adding it to durable history. Full skill bodies are never included in the catalog. + +The `skill({ name })` tool loads one full skill for the current agent cwd and returns a tool result containing ``, ``, and ``. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills marked `disableModelInvocation` retain distinct tool errors. The tool result is the model-visible disclosure path. + +The data structures and catalog/tool contract are documented in [skills.md](../../../core-data-structures/skills.md), with service signatures in the generated [services catalog](../../../cordis-catalog/services.md). + +## Alternatives considered + +**Inject full skill bodies into every system prompt.** Rejected because it destroys progressive disclosure and makes every request pay for instructions that may not apply. + +**Expose skills only as slash commands.** Rejected because model-initiated loading is the core capability; slash/ACP command advertisement does not change discovery. + +**Put local filesystem scanning directly inside `ctx.skills`.** Rejected because coding agents, web agents, and future plugin ecosystems need different skill sources. A provider registry mirrors the subagent seam: the registry owns conflict resolution and consumers, while implementations own loading. + +**Use a system-prompt section.** Rejected because the rendered system prompt is a single string, while the catalog is a user-role `` message with request-only lifecycle requirements. [`agent/session-prefix`](2026-07-07-session-prefix.md) is the selected mechanism: it places the catalog ahead of derived history and records the composed message in the request header. + +**Materialize built-in DSH authoring skills under `~/.dsh/skills/.system`.** Rejected because bundled skills do not write user home on startup, and embedded or remote providers supply configured skills. + +**Recursively discover nested `**/SKILL.md`.** Rejected. Flat files and one-level directory bundles cover the configured roots while keeping duplicate handling and catalog order easy to reason about. + +**Hand-parse frontmatter.** Rejected because the accepted schema includes an open `metadata` object. A narrow parser would either reject valid YAML users expect to work or grow into an unreviewed YAML subset. + +## Consequences + +The agent-core spine includes one session-prefix contributor, one local provider, and one model-facing tool. Skill discovery is cwd-sensitive, so callers that create agents with different session cwd values can observe different project skill overrides by design. + +The catalog is deterministic for a fixed root set and runtime registration revision, but disk changes are not watched; discovery is memoized until runtime registration invalidates the cache or the process restarts. + +## Deferred + +Forked skill contexts (`context: fork`), direct user/slash invocation (`user-invocable`), parameter declarations and hints (`arguments` and `argument-hint`), and per-skill tool constraints (`allowed-tools` and `disallowed-tools`) are outside the shipped contract. The registry, local provider, and model-facing tool do not parse, advertise, or enforce these fields. diff --git a/docs/rfc/implemented/feature/2026-07-06-approval-seam.md b/docs/rfc/implemented/feature/2026-07-06-approval-seam.md new file mode 100644 index 0000000000..eddb3ba733 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-06-approval-seam.md @@ -0,0 +1,141 @@ +# RFC: The approval seam — one-shot permission decisions over a waterfall of answerers + +Status: implemented + +## Problem + +Two callers need to put one question — "may this specific action proceed?" — to a human, and neither has a channel. `tools/pre-execute`'s `ask` decision (produced today by the Claude-Code hook bridge's `permissionDecision: ask`) degrades to deny because nothing services it. The [sandbox RFC](2026-07-06-sandbox.md)'s escalation phase needs the same channel for its post-denial one-shot retry. Without a shared seam, each would invent its own outcome vocabulary, UI routing, cancellation, and audit trail — and a deployment with no UI at all needs a guarantee that an unanswerable question can never grant anything. + +The routing problem is ownership: an approval prompt must reach the editor session that owns the asking agent (the ACP bridge multiplexes N sessions over one connection), fail closed for agents nobody owns (in-process subagents, tests), and stay out of deployments that compose no UI (headless, CI). + +## Decision + +One package, `dsh-user-approval` (`packages/ui/user-approval`), owning the vocabulary and the `ctx.approval` service — the MECHANISM. The POLICY — who answers, and whether a session is asked at all — lives outside it: answerers are `approval/request` waterfall listeners registered by the plugins that own the channel (the ACP bridge; future terminal UIs; test scripts), and a per-session policy tier can decide before any human is involved. Consumers (`dsh-tools`' ask routing, the sandbox escalation gate) resolve a question to a closed outcome and derive their own tool results from it. Deliberately ONE package, not the capability-seam three (see Alternatives). + +### How a deployment uses it + +One `cordis.yml` entry mounts the seam; not loading it is the opt-out — consumers degrade to their historical fail-closed behavior with zero approval code registered: + +```yaml +- id: approval + name: '@deepseek-ai/dsh-user-approval' + # config: + # policy: never # deployment default for sessions without an override; 'ask' when omitted +``` + +The entry alone provides mechanism, not a channel: with no answerer composed, every ask resolves `unavailable` and the asking tool call denies — fail-closed needs no configuration. Composing the ACP app (`@deepseek-ai/dsh-acp-agent`, as in [the sandbox example](../../../../examples/sandbox-acp-agent/README.md)) completes the loop: its bridge registers an answerer that prompts the owning editor session via `session/request_permission`, so a hook's `ask` or an escalation request surfaces as a one-shot Allow/Reject prompt attached to the already-streamed tool call. `policy: never` is the unattended stance — every ask auto-rejects deterministically, stated in the system prompt, no human in the loop. `policy` is validated against the closed list at plugin load; anything else throws. + +What a composed deployment observes: `allowed-once` lets exactly that call proceed; rejection, dismissal, and channel absence deny with three distinct reasons the model can tell apart; every ask lands a durable `approval/asked`/`approval/decided` pair on the asking agent's session log; nothing about a grant persists past the call that asked. + +One ask under this composition, verbatim from the sandbox example's recorded `escalation-approved` scenario — the model requests a sandbox escalation, the gate asks, the bridge prompts the owning editor, the user clicks Allow once: + +``` +tool/call bash {"command": "printf 'escalated\n' > escalated.txt && cat escalated.txt", + "sandbox_permissions": "workspace-write", + "justification": "the user asked to write escalated.txt in the workspace"} +approval/asked {"toolName": "bash", "callId": "call_00_…", + "reason": "escalate sandbox to workspace-write: the user asked to write escalated.txt in the workspace"} + → session/request_permission {"toolCall": {"toolCallId": "call_00_…"}, + "options": [{"optionId": "allow-once", "name": "Allow once", "kind": "allow_once"}, + {"optionId": "reject-once", "name": "Reject", "kind": "reject_once"}]} + ← the user picks "Allow once" on the prompt the editor attaches to the streamed bash call +approval/decided {"outcome": "allowed-once"} +tool/result "escalated" — this one call ran under the wider mode; the grant died with it +``` + +The `escalation-rejected` twin ends in `{"outcome": "rejected"}` instead: nothing executes, and the model's result carries the asker's verbatim fail-closed text (`the user rejected escalating this command to "workspace-write"`). A hook's `permissionDecision: ask` rides the identical wire; only the asker and its deny texts differ (§ Ask routing in dsh-tools). Headless, the same request skips the prompt entirely and settles `unavailable`. + +### Design detail + +#### The seam: mechanism and policy split + +`ApprovalService.request(req)` always resolves to a closed `ApprovalOutcome` — `allowed-once` / `rejected` / `cancelled` / `unavailable` — and never rejects. The service is the mechanism: it dispatches the `approval/request` waterfall, races the request's `AbortSignal` (abort settles `cancelled`; a late answer is discarded, never double-audited), contains a throwing answerer as `unavailable`, normalizes a rogue non-vocabulary return to `unavailable`, and lands the log-only audit pair `approval/asked`/`approval/decided` (paired by the branded `ApprovalRequestId`) on the requesting agent's session log. Grants are one-shot by definition: `allowed-once` authorizes the single asked-about action, never a class of future ones, and the service stores nothing between requests. The one precondition: `request()` throws (before appending anything) when the agent's session has no open turn — the audit pair must be turn-enclosed, the turn being the durable log's commit/replay boundary (a bare event between turns is dropped as crash tail on reload); every shipped ask path runs mid-turn already, and idle asks are a deferred design. + +Answerers are the policy, and they are `approval/request` waterfall listeners. The waterfall buys exactly what the seam needs: with zero listeners the dispatch falls through to the caller-supplied default — `unavailable`, so fail-closed needs no configuration and no code in any deployment; a listener that recognizes the request's agent answers by returning an outcome without calling `next()` (the decision slot is single-occupancy, first answer wins — the same documented semantics as the `fs/write-intent` gate); a listener that does not recognize the agent MUST delegate via `next()` so another answerer or the default gets the question; and listeners dispose with their owning fiber, so an unloaded UI plugin degrades the next ask to `unavailable` instead of leaving a dangling channel. Registration order across sibling plugins is not load-order deterministic (the loader starts siblings concurrently), so a deployment composes ONE terminal answerer and reserves `prepend` listeners for decide-or-delegate gates. + +`ApprovalRequest` carries the asking `agent` (routes the question; receives the audit events), the `toolName`, the optional exact `callId`, the asker's human-readable `reason`, and the optional `signal`. The vocabulary is deliberately self-contained — it names the tool-call by the `CallId` brand from `dsh-llm` and never imports `dsh-tools` — because `dsh-tools` depends on `dsh-user-approval` (the ask routing) and a `ToolCallView` import would close a package cycle. It deliberately does NOT carry tool arguments: a UI answerer attaches the prompt to the already-streamed tool call via `callId` instead of re-rendering the call. + +#### Ask routing in dsh-tools + +`ToolRegistry.execute()` resolves an `ask` decision through the seam before the shared deny path: `allowed-once` proceeds to dispatch, and the three non-grants deny with distinct reasons — "the user rejected…", "…was cancelled", "…no approval channel is available" — so the model can tell a human "no" from an absent channel. The seam is consumed opportunistically (`ctx.get('approval')`, the `tool-bash`/`agent-loop` pattern), not statically injected: a deployment that composes no ApprovalService keeps the historical ask→deny degrade verbatim, an unmount mid-session degrades the same way on the next ask, and the registry's fiber never gates on the seam's presence. An agent-less execution also degrades — without an agent there is no session to audit to and no UI to route to. + +#### The per-session policy tier + +The seam also owns the session-scoped approval policy — the approval knob of the two-knob per-session switching design ([the sandbox RFC](2026-07-06-sandbox.md) § Per-session modes is the pattern's home: one log-only event per knob, a pure fold, THE write path, ACP config-option advertisement, and turn-anchoring). `ApprovalPolicy` is `'ask' | 'never'`, and `effectiveApprovalPolicy(events) ?? Config.policy` (default `'ask'`) decides every request BEFORE any interactive answerer: the service resolves a `'never'` session to `'rejected'` INSIDE `request()`, before dispatching the waterfall at all — no listener registration, including a later `prepend`, can sit ahead of it — while `'ask'` dispatches unchanged (fail-closed `'unavailable'` with nobody composed, exactly the prior behavior). Visibility follows the switching design's two layers with one asymmetry: the prompt section states ONLY `'never'` (deterministic, availability-independent — "you will be prompted" would overclaim in a composition with no answerer, and absence under a logged header is exactly how the narrator reads `'ask'` back), the narrator injects at most one coalesced notice per switch, and the audit pair still lands on every ask, including the policy's auto-rejections. + +#### The ACP answerer + +The bridge registers the first real answerer: it resolves the owning session through its existing `WeakMap` reverse map, issues `session/request_permission` with the request's `callId` as the `toolCall` reference and the one-shot options `allow_once`/`reject_once`, and maps the response — selected `allow-once` → `allowed-once`, any other selection → `rejected` (an unknown optionId from a non-conforming client never grants), client `cancelled` → `cancelled`. A request for a foreign agent — or one without a `callId`, since the protocol prompt must attach to a tool call — delegates via `next()`. A rejected RPC (client gone mid-prompt) propagates to the service, which contains it as `unavailable`. Whether a call ASKS at all is policy — a hook or `tools/pre-execute` plugin returning `ask` — never the bridge's own judgment. + +The reverse-map ownership seam [the ACP support RFC](../../implemented/feature/2026-06-14-acp-agent-client-protocol.md) laid down is exactly what the answerer routes through, and per-session permission ownership (the blocker recorded in [the multi-session RFC](../../implemented/feature/2026-06-14-acp-multi-session.md)) is what it implements. + +#### Audit, and what the model sees + +`approval/asked` / `approval/decided` are log-only session events (the `hook/invoked`/`hook/result` precedent): durable, replayable, never in the model transcript. The model's entire view of an approval is the tool result the asker derives from the outcome — reconstructability holds because that result is an ordinary logged `tool/result`. One `decided` per `asked`, whatever the outcome, including an already-aborted signal (settled `cancelled` without dispatching) and a contained answerer failure. + +#### Entities and dependencies + +One package, no cycles: `dsh-user-approval` peers on `cordis`, `dsh-session` (event-map merge + append), `dsh-agent` (the `Agent` type), `dsh-llm` (`CallId`, via `dsh-brand`). `dsh-tools` and `dsh-acp` each peer on it; the escalation phase's asker lives in `dsh-tool-bash` (see [the sandbox RFC](2026-07-06-sandbox.md) § Escalation), so the sandbox family keeps its ZERO-edge relation (the executor contributes the per-call override mechanism, and transport seams never ask humans questions). The seam is one package, not the capability-seam three: the service body (dispatch + audit) has no replaceable implementation — the replaceable part is the answerer listeners, and those live with their owners (the bridge; future terminal UIs; test scripts). `@cordisjs/plugin-capability` stays orthogonal (a static grant registry answers "is this already authorized", not "ask the user now"), and `subagent-acp`'s child-side `permission` auto-answer is untouched — routing a child's approvals to the parent session is deferred (§ Deferred). + +### Testing + +Unit tier: the service's outcome branches (fail-closed default, first-wins slot, delegation, containment, rogue-value normalization, abort-before and abort-during with late-answer discard, fresh ids, fiber-disposal degradation) and the policy tier (both values × dispatch/decide, a `'never'` decision unbypassable even by an answerer prepended AFTER the service, audit pair intact) in `dsh-user-approval`; the ask routing matrix (grant dispatches; three non-grant reasons pinned verbatim; unmounted and agent-less degrades; the registry's own exhaustiveness backstop against a non-conforming stand-in) in `dsh-tools`; the answerer (wire shape of the prompt, outcome mapping, unknown-option conservatism, foreign-agent and call-less delegation) driven through a real bridge + scripted client in `dsh-acp`. + +Snapshot tier: the harness accepts scripted permission answers (`permissionAnswers` in a scenario's `input.json`, consumed FIFO; an unscripted prompt answers `cancelled`, fail closed). The seam's wire is recorded end to end in the sandbox example's suite: both escalation branches drive `session/request_permission` through this seam over scripted answers (grant and rejection), and the recorded `mode-switching` scenario pins the `'never'` prompt sentence and the policy-switch notice ([the sandbox RFC](2026-07-06-sandbox.md) § Testing). + +## Deferred + +- **`allow_always` grant storage** — honoring a persistent grant means designing storage, scope identity (call? path? prefix? session? time window?), and revocation; until designed, only the one-shot options are advertised ([the sandbox RFC](2026-07-06-sandbox.md) § Escalation records the open scope question). +- **A recorded hook-driven `ask` scenario** — the wire is recorded via the sandbox example's escalation branches; the hook-producer variant stays on the unit tier and the hook matrix's `hook-cc-pretool-ask`, with its deny texts pinned verbatim there. +- **Routing a child agent's approvals to the parent session** — `subagent-acp`'s child today auto-answers its own `permission` requests; surfacing them to the parent's editor is its own design. + +## Alternatives considered + +- **A single registered provider instead of waterfall listeners** — rejected: a `registerProvider()` surface forces every composition question — allowlist pre-filters, external hook deciders, scripted test answers, a policy gate in front of a human — inside one provider implementation. The waterfall gets composition, fail-closed absence, and HMR disposal from machinery the runtime already has; the seam's JSDoc pins the single-decision-slot convention instead of inventing a provider registry. +- **[The ACP support RFC](../../implemented/feature/2026-06-14-acp-agent-client-protocol.md)'s inline `tools/pre-execute` permission gate** — rejected, and superseded by this seam: prompting for every bridge-owned call hardwires the asking POLICY into the UI plugin, cannot serve a second asker (sandbox escalation happens after execution starts, with no pre-execute moment), and leaves hooks' `ask` — the vocabulary the interception seams already ship — unserviced. +- **A generic user-interaction seam (`ctx.userInteraction`) instead** — rejected: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. The generic seam has since shipped (`packages/ui/user-interaction`, the `ask_user_question` tool over ACP elicitation) and approval deliberately still does not ride it — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge. +- **Static optional injection in `dsh-tools`** — rejected: the vendored cordis `Inject` type has no optional flag — the object form maps service names to intercept config, and a declared inject gates the fiber. `ctx.get('approval')` is the documented opportunistic-consumption pattern (the `tool-bash` owner-token lookup, the loop's persistence probe), reads presence per call, and degrades correctly across HMR without extra machinery. +- **The capability-seam three-package split** — rejected: interface/implementation/consumer fits a seam whose implementation is swappable (bash-local vs bash-sandbox). Here the service body is fixed mechanism and the variable part is listeners that live with their owners — splitting would manufacture an implementation package with nothing in it ("don't split preemptively"). +- **Offering `allow_always` now** — rejected: the protocol can express it, but honoring it means designing grant storage, scope identity, and revocation (§ Deferred). Advertising an option the harness cannot honor manufactures doomed grants. + +## Consequences + +What shipped pins — the suites in Testing hold each: + +- With an ApprovalService and an answerer composed, a hook's `ask` reaches a human and `allowed-once` dispatches the tool; every other outcome denies with its distinct reason. +- A `'never'` session auto-rejects every ask without prompting anyone, states the policy in its prompt, and narrates switches (the shared switching mechanics are pinned in [the sandbox RFC](2026-07-06-sandbox.md)). +- Every unanswerable path fails closed to `unavailable`: no service (degrade, verbatim historical text), no listener, a foreign or agent-less request, a throwing answerer, a rogue return value, a dead client connection. +- Every `request()` lands exactly one `approval/asked`/`approval/decided` pair on the asking agent's log, replayable, invisible to the model transcript. +- Prompts route per-session through the bridge's ownership map; one session's prompt can never reach another session's editor. +- A deployment that composes nothing new behaves byte-identically (the snapshot suite's goldens are unchanged). + +Costs and accepted limits: + +- **Two decide-eager answerers race for the slot.** Sibling-plugin listener order is not deterministic, so the seam cannot referee competing terminal answerers — mitigated by convention (one terminal answerer per deployment; `prepend` only for decide-or-delegate gates) rather than a priority mechanism the event bus does not have. +- **Production exercise rests on one composition.** `ask` has two producer families — the hook bridges through `tools/pre-execute`, and sandbox escalation through its own gate — with the wire recorded in the sandbox example's snapshot suite, so the seam's real-world coverage is that one composition until more deployments compose it. +- **Ownership keys on `Agent` object identity.** The answerer resolves sessions through the bridge's existing WeakMap; every current path hands the same object through the loop and the seams, but a future boundary that clones or proxies agents would make the bridge delegate and fail closed — safe, but silently UI-less — and would need session-id matching instead. + +## FAQ + +Behavioral and usage questions only — every "why not X?" design question lives in [Alternatives considered](#alternatives-considered), whose job is exactly that. + +- **What happens in a deployment with no answerer at all (headless, CI)?** Every ask falls through the empty waterfall to `unavailable` and the tool call denies with the "no approval channel is available" reason. Fail-closed is the zero-listener default, not a configuration. +- **Can a grant persist — "always allow this"?** No. `allowed-once` authorizes the single asked-about action and the service stores nothing between requests; `allow_always` is deliberately not advertised until grant storage is designed (§ Deferred). +- **What does the model see of an approval?** Only the tool result the asker derives from the outcome — the audit pair never enters the transcript. The three non-grant reasons are distinct, so the model can tell a human "no" from a dismissed prompt from a missing channel. +- **Who decides whether a call asks in the first place?** Policy producers: a hook returning `permissionDecision: ask`, any `tools/pre-execute` listener, or the sandbox escalation gate. The seam and the bridge only route and answer; neither injects its own judgment about what deserves a prompt. +- **What happens when the user dismisses the prompt, or the turn aborts mid-ask?** Dismissal maps to `cancelled` with its own deny text. An already-aborted signal settles `cancelled` without dispatching; an abort during the ask discards the late answer — one audit pair either way, never two. +- **What if the client answers with an option the harness never offered?** Any selection other than the offered `allow_once` maps to `rejected` — an unknown optionId from a non-conforming client can never grant. +- **How do subagents' approvals route?** An agent no answerer owns delegates through the whole waterfall and fails closed — in-process subagents are unanswerable today by design. `subagent-acp`'s child-side auto-answer is untouched; routing a child's asks to the parent's editor is deferred (§ Deferred). +- **What does `policy: 'never'` actually change at runtime?** The service resolves every ask for that session to `rejected` before dispatching any answerer (in-service, so no registration order can bypass it); the system prompt states the policy; switches are narrated at boundaries; the audit pair still lands for every auto-rejection. +- **What happens across a hot reload, or when the UI plugin unloads mid-session?** Answerers dispose with their owning fiber, so the next ask degrades to `unavailable` instead of hanging on a dead channel; remounting re-registers the answerer with no catch-up state. +- **Where does the user see what they are approving?** On the tool call itself: the prompt attaches to the already-streamed call via `callId` — arguments included — and adds the asker's human-readable `reason`; the request carries no argument copy of its own. + +## Prior art + +In-repo precedents this design copies or contrasts with: + +- The `fs/write-intent` gate (`packages/fs/fs/`) — the documented single-occupancy decision-slot waterfall semantics (first answer wins, delegate via `next()`) the answerer contract reuses. +- `hook/invoked`/`hook/result` — the log-only audit-pair precedent `approval/asked`/`approval/decided` follows; [the hook-bridges RFC](2026-06-30-hook-bridges.md) ships `permissionDecision: ask`, the first producer. +- [The interception-seams RFC](2026-06-30-interception-seams.md) — the `tools/pre-execute` `allow`/`deny`/`ask` vocabulary whose `ask` this seam services. +- [The ACP support RFC](../../implemented/feature/2026-06-14-acp-agent-client-protocol.md) — the `WeakMap` ownership seam the answerer routes through; [the multi-session RFC](../../implemented/feature/2026-06-14-acp-multi-session.md) — the per-session permission-ownership blocker this implements. +- The opportunistic `ctx.get()` consumption pattern (`tool-bash`'s owner-token lookup, the loop's persistence probe) — how `dsh-tools` consumes the seam without gating its fiber on it. diff --git a/docs/rfc/implemented/feature/2026-07-06-sandbox.md b/docs/rfc/implemented/feature/2026-07-06-sandbox.md new file mode 100644 index 0000000000..e3e740b31c --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-06-sandbox.md @@ -0,0 +1,225 @@ +# RFC: The subprocess sandbox — confinement seam, native runners, escalation, and per-session modes + +Status: implemented + +## Problem + +A coding agent needs this product path: bash subprocesses — and the hook commands that ride them — execute under a restricted file sandbox by default; if and only if the sandbox actually denies an operation, the model may request one user approval for that same operation and, once granted, retry it once with wider permissions. An every-tool boundary is deliberately NOT the claim: fs/web/todo execute in-process where an `execve` wrapper is meaningless (§ In-process tools), and the cross-family boundary is staged follow-up work (§ Deferred phases). Without a shared vocabulary, every tool reinvents approval fields, denial parsing, retry matching, and permission-state hints. + +The harness is an SDK, so confinement must be a capability developers COMPOSE: whether to sandbox, and which backend per platform, belongs in the leaf `cordis.yml` as a first-class entry — not inside one executor's private machinery. And the first-choice runner, `bwrap`, is unusable on exactly the hosts a sandbox matters most (minimal containers, disabled unprivileged userns, LSMs that deny `mount`), so a fallback runner has to ship with the SDK rather than be assumed on the host. + +Confinement alone leaves two gaps. A denial with no escalation path is terminal — the model can only give up, which pressure-cooks operators into configuring `workspace-write` or `danger-full-access` globally and defeats the sandbox. And the model-visible knobs (the sandbox mode, the approval policy) change over an agent's lifetime — an ACP user flips a per-session setting, an operator edits `cordis.yml` while the process is down — while the model must never act on a stale belief about them: what IS the state on every request, what changed while the agent lives, and what changed while nobody was watching all need answers. + +## Decision + +One seam, one per-platform chain of local backends, one consumer, and two levers on top: a per-call escalation path and per-session runtime modes. Everything below composes from the leaf `cordis.yml`; nothing touches `agent-loop`. The scope is deliberately bounded: the phases this RFC names but does not design — per-session workspace root, cross-family fs enforcement, the `subagent-acp` consumer, more environments, a Windows chain — are listed under § Deferred phases, each a follow-up design, not a config knob. + +### How a deployment uses it + +Three `cordis.yml` entries turn an unconfined coding agent into the sandboxed product path; [`examples/sandbox-acp-agent`](../../../../examples/sandbox-acp-agent/README.md) is this composition, live: + +```yaml +- id: sandbox + name: '@deepseek-ai/dsh-sandbox-local' # the per-platform runner provider (ctx.sandbox) +- id: bash + name: '@deepseek-ai/dsh-bash-sandbox' # the confined executor, replacing dsh-bash-local behind ctx.bash + config: + mode: read-only # the deployment default every session starts from + workspaceRoot: !!js process.cwd() # the boundary workspace-write may write under +- id: approval + name: '@deepseek-ai/dsh-user-approval' # the escalation gate's channel (the approval RFC) +``` + +The swap is invisible to every consumer of `ctx.bash`: the bash tools, hook commands, and background tasks run exactly as before, spawned through the wrapped argv the provider returns. Deleting the `sandbox` and `bash` entries and loading `@deepseek-ai/dsh-bash-local` instead is the opt-out — execution is unconfined again and the escalation fields vanish from the tool schema, because they are capability-gated on the mounted executor, not on configuration. Omitting only `approval` keeps confinement but fails every escalation closed with its own error text. + +Misconfiguration fails loud: `mode` outside the closed vocabulary is rejected at plugin load, and a host with no usable backend throws the structured `SANDBOX_UNAVAILABLE` — at `confine()` before the command ever spawns — rather than degrading to unconfined execution. `runnerCommand` on `dsh-sandbox-local` is the operator's explicit assertion of a bwrap-compatible runner (chain and probes skipped); it doubles as the deterministic fake-runner seam for keyless tests. + +What the model then experiences: denied file effects come back as result facts with a `[sandbox: file access denied under mode]` marker plus standing instructions not to retry around them; under a confining executor the schema offers `sandbox_permissions` + `justification` for the one-approval escalated retry (validated strictly wider than the session's effective mode at execution); the system prompt deliberately does NOT state the sandbox mode — the model learns the boundary from the marker (which names the mode) when it hits it, instead of preemptively refusing work a standing declaration discourages. What an ACP editor experiences: a `sandbox-mode` and an `approval-policy` config-option select per session (each advertised only when its knob is composable), switchable at runtime; a sandbox switch simply changes what subsequent commands may do, while an approval-policy switch to `'never'` is stated in the prompt and narrated. + +The product path, concretely (the escalation arc is verbatim from the recorded `escalation-approved` scenario; the denial leg is pinned on the real-kernel e2e tier): + +``` +tool/result … [sandbox: file access denied under read-only mode] ← the write RAN; the kernel refused it +tool/call bash {"command": "printf 'escalated\n' > escalated.txt && cat escalated.txt", + "sandbox_permissions": "workspace-write", + "justification": "the user asked to write escalated.txt in the workspace"} + → the editor is prompted on this very call (session/request_permission through the approval seam); Allow once +tool/result "escalated" — THIS call ran under workspace-write and its result facts say so; the session stays read-only +``` + +Reject instead and nothing executes: the result is the verbatim `the user rejected escalating this command to "workspace-write"`, and the teaching makes that final — no re-ask. + +### Design detail + +#### Grounding — verified against the code + +- Runtime OS subprocesses exist at exactly two sites: the `ctx.bash` seam's single spawn (`packages/bash/bash-local/src/run.ts`; hook commands flow through `ctx.bash`, so bash confinement covers them transitively) and `subagent-acp`'s child agents (`packages/subagent/subagent-acp/src/run.ts`) — the second consumer that makes a shared seam due rather than preemptive under the [capability seams RFC](../architecture/2026-06-13-capability-seams.md)'s "don't split preemptively" rule. +- Everything else executes inside the harness process (fs is in-process `node:fs`, web is in-process `fetch`, every `ToolDefinition.execute()` closes over `ctx`): an OS sandbox wraps `execve` and cannot wrap an in-process function call, so "sandbox any tool" is policy at each tool's seam, never a mechanical transport change. +- `tools/pre-execute` (`allow`/`deny`/`ask`) exists, with `ask` serviced by [the approval seam](2026-07-06-approval-seam.md); the fs intent gates are version guards with no mode input yet. +- `dsh-bash`'s request/spec split (`BashExecRequest` → `resolve()` → `BashExecSpec`) carries per-call fields the way escalation needs — `owner` is the template: request-optional, spec required-but-nullable, carried verbatim — and the result types already speak `SandboxMode`, so a per-call policy field adds no dependency edge. +- The pinned-header snapshot design means a schema/description change churns at most one pinning fixture per suite, and the escalation fields are advertised only under a sandboxing executor — so they live in exactly one pinned header, the sandbox example suite's `mode-switching` fixture. + +#### The seam: `ctx.sandbox` + +`dsh-sandbox` owns the vocabulary and the `SandboxProvider` contract: `confine(argv, policy)` returns the argv to spawn INSTEAD of the caller's own — wrapped so the process and everything it spawns run confined — plus the `enforcement` completeness the selected backend achieves, its denial dialect (`denialSignatures`, the stderr substrings that backend's kernel prints on a denied file effect), and its runner-failure dialect (`runnerFailureSignatures`, how the runner ITSELF failing — and therefore the command never running — identifies itself); with no usable backend it throws the fail-closed `SANDBOX_UNAVAILABLE` error, never a silent unconfined passthrough. The vocabulary: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, FILE effects only — network and process visibility are not claimed), `SandboxEnforcement` (`full` / `partial`), `SandboxPolicy` (mode + workspace root). + +Policy rides each CALL, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is a new call with a wider policy — inexpressible under a config-fixed provider mode. + +The seam confines SAME-WORLD subprocesses only: a backend shares the host's filesystem and kernel. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups, because an agent whose bash runs in a container while its fs tools write the host lives in two split worlds. + +Left open, for the phase that needs them: whether network restriction arrives as a separate `network_mode` or merges into `sandbox_mode` once a runner enforces both, and whether `SandboxPolicy` grows extra writable-root grants now (the launcher already speaks `--rw `) or only when escalation needs them. + +#### Local backends and the shipped launcher + +`dsh-sandbox-local` selects BY PLATFORM, once per lifetime, and caches the verdict: each platform names its runner chain, a chain of one is selected directly — probing arbitrates between candidates, and a sole candidate leaves nothing to arbitrate — and a chain of several is probed FUNCTIONALLY in preference order (build and enforce a real profile, never `--version` — a present-but-unusable `bwrap` must fail its probe). Linux: `bwrap` first (its mount profile is closest to the mode vocabulary: whole tree read-only, fresh `/dev`+`/proc`, `workspace-write` adds an ephemeral `/tmp` and rebinds the workspace root; deliberately no `--unshare-pid` and no network claim), else the npm-distributed `landlock-run` Landlock launcher. darwin: `sandbox-exec` speaking a Seatbelt (SBPL) profile — allow-default with `(deny file-write*)` plus write allow-lists, every granted root canonicalized because Seatbelt matches resolved paths (`/tmp` IS `/private/tmp`) — unprobed, the sole candidate. A platform with no chain fails closed at `confine()`; an unprobed runner that turns out unusable fails closed at EXECUTION instead — it refuses to run the command, and every wrap carries `runnerFailureSignatures` (the runner's own error prefix, which also matches the shell's runner-not-found message) so the consumer classifies that as a SANDBOX failure, never a task failure: on either path the command neither runs unconfined nor slips through as a plain failure. A non-empty `runnerCommand` config is the operator's assertion of a runner that fully enforces the bwrap-shaped profile — chain and probes skipped; it doubles as the deterministic fake-runner seam for keyless tests. It is not exempt from fail-closed execution: its wrap carries argv0-scoped outer-shell failure shapes (`exec: : not found`, `: No such file or directory`, `: Permission denied`) as its runner-failure dialect, so a missing or unexecutable configured runner classifies as a sandbox failure like every other rung — never as a failing command, and never as a denial. + +The launcher is a ~300-line C program (plain C11 over the raw Landlock UAPI — no libraries beyond a statically linked musl, so the audit surface is that one file plus the kernel's stable syscall contract): `--ro ` / `--rw ` grants, `--`, the wrapped argv; it installs the ruleset on itself and `exec`s (rulesets are inherited across `execve`, and it sets `no_new_privs` before restricting); `--probe` enforces a maximal ruleset in a short-lived child and exits 0 only when the kernel actually enforces; launcher failures exit 125 without exec'ing. + +The launcher lives in its own repository and reaches the harness as the npm package family [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) (the per-platform-package pattern of `node-addon-require-builtin` and esbuild): an entry package — `dsh-sandbox-local`'s one runtime dependency — plus per-platform binary packages selected at install time by npm's `os`/`cpu` fields. The entry package owns the launcher's CLI contract end to end (`launcherPath()` resolution with a never-existing fallback, the functional `probe()`, `grantArgs()` flag spelling), versioned together with the binary so probe-report parsing can never drift against it; the harness keeps only the policy side, `landlockProfileArgs()` mapping the mode vocabulary to grants. Native-only per-architecture builds, pack gates (binary presence, executability, ELF architecture), and the byte-pinned publish rehearsal are that repository's release pipeline; this repo's Landlock CI legs install the published family from the registry — the true consumer path — and prove real-kernel confinement through it. + +FIXME: Revisit the separate-repository boundary and try to maintain the launcher source and its platform package family inside this monorepo, so the native release surface and harness contract evolve together. + +Profile parity is honest rather than identical: under Landlock, `read-only` grants `--ro /` plus `--rw /dev/null` (the node, not `/dev` — the host's `/dev/shm` is a persistent shared tmpfs), and `workspace-write` grants the HOST `/tmp` where bwrap's is ephemeral; under Seatbelt, `read-only` likewise grants only the `/dev/null` literal, and `workspace-write` grants the host `/tmp` plus the per-user darwin temp dir (`os.tmpdir()` — the platform's real temp area for mkstemp-family tools; omitting it would deny what the mode promises). Every wrap carries the rung's denial dialect (`denialSignatures`: EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) so consumers match the active backend rather than a cross-runner union. Enforcement is honest per ABI level: an older kernel enforces the subset its ABI governs (path truncate is ungoverned before ABI v3), the probe's report line distinguishes the cases, and every confined result carries the structured `enforcement: 'full' | 'partial'` fact — refusing partial enforcement would deny the fallback to precisely the older-kernel hosts that need it. The bwrap and Seatbelt profiles govern every promised file effect by construction, so their passing probes always report `full`. + +#### The bash consumer + +`dsh-bash-sandbox` extends `LocalBashExecutor` (spawn mechanics, process-group kills, spill files, background tasks, credential scrub inherited verbatim) and hands `ctx.sandbox` the exact `['bash', '-c', command]` argv it is about to spawn. A sandbox denial is a RESULT FACT, not an error: the command RAN and the kernel refused a file operation, so `result.sandbox.denied` is orthogonal to `exitCode`/`signal`. Classification is conservative text inference over the collected stderr tail against the WRAP's own dialect, so a backend is never credited with a denial text its kernel does not speak (bare EPERM under a Linux runner names non-file boundaries the mode vocabulary does not govern); the known residual false positive is non-sandbox text in the active dialect (an ssh auth failure under Landlock, a refused `kill` under Seatbelt), and a structured runner signal wins once one exists. A RUNNER failure is the opposite of a denial and outranks it in classification (a runner's error text can itself contain denial words): the wrap's `runnerFailureSignatures` matching a failed run means the sandbox broke and the command NEVER RAN — the foreground path re-throws it as the structured `SANDBOX_UNAVAILABLE` error (the late twin of the confine-time throw, carrying the runner's first stderr line), a settled background task stamps `sandbox.runnerFailed` and `bash_output` renders its own marker — so a broken sandbox can never read as a failing command. + +The model's view is result facts only: the static tool description explains the denial marker (`[sandbox: file access denied under mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). No prompt section states the sandbox mode (§ Per-session modes). + +#### Escalation: one approved wider retry after a denial + +The seam level is mechanism only. `BashExecRequest` carries `sandboxMode?: SandboxMode`, an explicit per-call policy input; `BashExecSpec` carries it required-but-nullable (the `owner` pattern: a forgotten field is a visible `undefined`, and `resolve()` is the one explicit defaulting step); `BashExecutor` exposes the capability fact `get sandboxMode(): SandboxMode | undefined` — `undefined` in the base class, the configured mode in `SandboxBashExecutor` — so the tool layer can advertise only what the mounted executor honors: composition truth, not configuration. The seam honors ANY explicit mode, including a narrower one; the wider-only ladder is escalation policy and lives in the tool. A non-sandboxing executor (`dsh-bash-local`) carries the field verbatim and confines nothing — the field reaching it means the caller bypassed the tool's gate, and its honest behavior stays unconfined execution, not a guess at enforcement it does not have. + +`SandboxBashExecutor.resolve()` stamps the effective mode — escalation grant > session override > configured default — so `run()`/`start()` read the spec, never the config. The `danger-full-access` branch, the confine call, and the result facts all key off the spec's mode, and the per-task facts map carries each task's mode alongside its wrap facts (`notifyTaskDone()` stamps from the map entry): one escalated call — foreground or background — reports the mode it ACTUALLY ran under while every neighbor keeps its own. + +The tool gate advertises two extra parameters exactly when `ctx.bash.sandboxMode` reports a confining mode at registration: `sandbox_permissions`, an enum of the closed escalation-target vocabulary — `workspace-write`/`danger-full-access`, every mode a session could ever escalate TO — and `justification`, required together with it. The enum is deliberately NOT cut down to the modes wider than the executor's DEFAULT: schemas are registry-global while the effective mode is per-session and switchable, so a default-relative ladder strands a session overridden NARROWER than the default (with a `danger-full-access` default and a `read-only` override it would advertise nothing at all — confined, but with no lever). Strict widening is instead enforced at EXECUTION against the call's effective mode (session override ?? executor default): a request that is not strictly wider fails closed with its own text and prompts no one. An escalating call resolves approval BEFORE anything executes — no `ctx.approval` composed, or no agent on the execution, fails closed with its own text; otherwise `ctx.approval.request({ agent, toolName: 'bash', callId, reason, signal })` with the audit-self-contained reason `escalate sandbox to ${mode}: ${justification}`, while the UI attaches the prompt to the already-streamed call (the command is visible there; the approval RFC's no-arguments rule holds). The four outcomes map to distinct results: `allowed-once` stamps `sandboxMode` onto the bash request and proceeds; `rejected`, `cancelled`, and `unavailable` each produce their own error text, so the model can tell a human "no" from a dismissed prompt from a missing channel. The grant is consumed by the very call that asked; nothing is stored. + +The tool description teaches — and a denied result itself prompts — the SAME-TURN flow when the fields exist: on a denial a wider mode would cure, escalate immediately in that turn by retrying the exact command once with `sandbox_permissions` (the narrowest mode that suffices) + `justification`, without detouring through chat to ask first — the approval prompt raised by the retry IS how the user consents. Never speculatively: an escalation is grounded in a real denial — normally the one the command just hit, up front only when the session already denied the same access — and a prompt stating approvals are disabled turns the exception off entirely; a rejected escalation is final for that command. Denial-grounding is deliberately model discipline plus human judgment, not harness bookkeeping — the human sees the exact command and justification on the prompt (see Alternatives for why hard-matching is rejected). No new session events anywhere: the attempt is an ordinary `tool/call` whose logged arguments carry the two fields, the decision is the approval seam's `approval/asked`/`approval/decided` pair, the outcome is an ordinary `tool/result` whose sandbox facts name the mode it ran under. The asker lives in `dsh-tool-bash`, NOT the executor: a transport seam has no `agent`, no `callId`, and no business asking humans questions. + +Left open, recorded for the phase that picks them up: what a grant's scope identity is beyond the sandbox mode — the exact call, a path, a command prefix, the session, a time window — the question `allow_always` grant storage must answer before that option can be advertised; how cancellation behaves while an approval prompt is pending; and how escalation is defined for `run_in_background` denials that arrive via `bash_output`. + +#### Per-session modes: the session log as the store + +``` +effective(session) = findLast(the session's own knob events)?.value ?? the composition-config default +``` + +The default is composition config (`cordis.yml`) — operator-owned, process-wide. A runtime switch is a SESSION-SCOPED override recorded as one log-only event in that session's own log. Restart immunity (resuming a session replays its log, so overrides come back with zero catch-up machinery) and multi-session isolation (one editor tab's `workspace-write` cannot disturb another's `read-only`) both fall out by construction, and no external config store exists anywhere. + +**One event per knob, owned by its domain** — the merge-extensible `SessionEventMap` idiom every existing event family already follows (`approval/*` in `dsh-user-approval`, `hook/*` in the hooks packages): + +```ts +interface SessionEventMap { + 'bash/sandbox-mode': { mode: 'read-only' | 'workspace-write' | 'danger-full-access' } + 'approval/policy': { policy: 'ask' | 'never' } +} +``` + +Each owner exports the same three-piece kit: the event declaration, a pure fold (`effectiveSandboxMode(events)` / `effectiveApprovalPolicy(events)` — a `findLast`, typed to the domain's closed union), and THE write path (`setSandboxMode(session, mode)` / `setApprovalPolicy(session, policy)` — a switch IS its event; nothing mutates state out of band). No shared owner service, no generic facts map, no registry: a third knob copies the ~40-line pattern into its own package. Execution follows the fold on both sides — the bash tool's per-call stamp reads it as the middle rung of the § Escalation precedence chain, and the approval seam's `'never'` gate is [the approval RFC](2026-07-06-approval-seam.md)'s side of the same pattern. + +**Visibility is deliberately asymmetric between the knobs.** The SANDBOX mode is stated nowhere and its switches are not narrated: a standing "you are read-only" declaration teaches the model to refuse preemptively (observed live: sessions where the model would not even attempt a write it could have escalated), while the denial marker already names the mode the command ran under at exactly the moment the boundary matters — behavior, not belief, carries the state, and a switch simply changes what the next command does. The APPROVAL policy keeps both layers, because its failure mode is the opposite: an auto-rejected ask under `'never'` returns "the user rejected …" wording no behavior can disambiguate, so the prompt states `'never'` (and ONLY `'never'` — an `'ask'` promise is unknowable without asking, and absence under a logged header is how the narrator reads `'ask'` back), and an `agent/pre-step` narrator injects at most one coalesced notice per policy switch: idle flip-flops collapse to one notice at the next turn's first step, a net-zero round trip to none, and a mid-turn change is narrated no later than the next step. Its "last told" is in-memory with a log-derived fallback (the folded header's system text parsed against the closed candidate sentence; LAST occurrence wins, so a persona quoting it cannot shadow the real section), so restarts lose nothing; attribution is positional (a knob event after the log's last `request/header*` reads `changed by the user`, a drift with no such event reads `changed by the operator/config`). + +**The editor surface** is protocol-native [Session Config Options](https://agentclientprotocol.com/protocol/session-config-options) — the spec's replacement for session modes (slated for removal in ACP v2), already SDK-typed. The bridge advertises one independent `select` per composable knob — `sandbox-mode` (category `mode`) iff the mounted executor confines, `approval-policy` iff the approval seam is composed — with `currentValue` folded from each session's own log, in `session/new` and `session/load` responses. `session/set_config_option` validates against the same closed lists, routes to the domain setter, and returns the complete refreshed state (the spec contract). + +**Anchoring: turn-enclosure is the commit boundary.** The turn-enclosure contract makes a bare between-turns append invalid (the JSONL backend treats a post-`turn/end` tail as crash garbage; dev invariants throw). A switch while a turn is open appends immediately — openness read from the LOG (last boundary event is `turn/start`), not `agent.status`, which stays `running` between queued turns. An idle switch is held on the bridge's session record and anchored at the next turn's `agent/prompt-submit` — inside the turn, before anything in it assembles or executes, last write per knob, and OUTSIDE any `session/event` emit (appending from inside that feed reorders events for later-registered listeners — a bug the dev invariants caught live). Until anchored, the switch exists only in bridge memory: responses overlay it truthfully, and a crash before the next turn reverts it — `session/load` then reports the fold's truth, so the editor UI self-corrects rather than lies. + +#### In-process tools + +fs/web/todo execute in-process, so their sandbox semantics are policy at their seams: the fs intent gates deciding by the shared mode vocabulary (§ Deferred phases, cross-family) make `read-only` a real boundary instead of a bash-only approximation — until then the contract says so honestly. No generic per-tool sandbox runtime: a host-mediated tool leaves the process only by returning declarative effects the host validates, which is a rewrite, not a wrapper. + +FIXME: Revisit this tool-local boundary. The follow-up design needs to determine whether sandboxing becomes a global harness capability that applies uniformly to every tool, instead of expressing in-process enforcement independently at each tool seam. + +### Testing + +- Unit tier (no real runner anywhere): profile dialects, per-platform chain selection (sole candidate unprobed, no chain fails closed, multi-candidate probe order), verdict caching, the fail-closed end, probe-report parsing, and the launcher/`sandbox-exec` CLI contracts via fake runner scripts in `dsh-sandbox-local`; wrapping, policy hand-off, fact stamping, and runner-failure-outranks-denial classification (foreground throw, background `runnerFailed` fact) against a fake provider in `dsh-bash-sandbox`; the error's structured identity in `dsh-sandbox`. The escalation matrix spans the three bash packages: verbatim carry-through in `dsh-bash-local`, stamp/branch/per-task-facts in `dsh-bash-sandbox`, and the capability gate, `justification` pairing, fail-closed texts (pinned verbatim), and grant stamping in `dsh-tool-bash`. The switching surface pins the folds, the stamping precedence, the `'never'` gate, per-session section rendering, the full narrator matrix (cold start, coalescing, net-zero, resume drift with operator wording, positional attribution, persona-shadow hardening), and the bridge's advertisement gating, validation rejections, idle-vs-mid-turn anchoring (dev invariants mounted), and `session/load` reporting over a real two-process JSONL round trip. +- Keyless real-runner e2e, split along the seam and per rung: CI's `sandbox-e2e` matrix runs bwrap and Landlock on Linux (the Landlock leg once per architecture, each confining through the registry-installed launcher) and Seatbelt on macOS against real kernels, failing on a silent all-skip. World-proofs live in `dsh-sandbox-local` (denied writes absent on disk, workspace writes landing, temp-area grants pinned, kernel denial text matching the advertised dialect) and `dsh-bash-sandbox` (the through-`ctx.bash` consumer proofs, including denied-then-overridden-write-lands). This package's own publish path is rehearsed without publishing (`packed-install.e2e.ts`): `pnpm pack`, tarballs installed into a throwaway consumer with the launcher family resolving from the registry, plain `node` confining through the INSTALLED launcher — asserted executable apart, so a mode-stripped binary can never masquerade as a non-enforcing kernel. The switching surface has its own keyless e2e (`examples/sandbox-acp-agent`): the real `cordis.yml` tree advertises both options, honors switches end to end, and rejects out-of-vocabulary values. +- With-key e2e (`examples/sandbox-acp-agent/tests/escalation.e2e.ts`): real model + real runner + the REAL bridge answerer, world-verified — denied under `read-only`, escalates with justification, the scripted editor grants and the retried write lands on disk, while a rejected escalation leaves no write. Self-skips without `DEEPSEEK_API_KEY` or a usable runner (e2e.yml installs bubblewrap so it actually executes in CI). +- Snapshot tier (`examples/sandbox-acp-agent/tests/acp.snapshot.ts`): the keyless config-option wire; the recorded mode-switching arc as the suite's pinned header — necessarily, since mid-session switches emit the `request/header-delta`s the uniformity guard licenses only in the pin — committing both switches, the prompt-section delta and one "changed by the user" notice per knob, and a confined write landing under the switched mode; and both recorded escalation branches over scripted `permissionAnswers` (grant runs confined under `workspace-write`; rejection executes nothing and pins the fail-closed text). Replay re-executes every fixture's bash calls under the host's real runner (ci.yml's snapshot lane installs bubblewrap). Deliberately absent: a fixture carrying a real DENIAL — denial stderr is the backend's dialect and would pin a fixture to its recording platform; the escalation prompts assert the prior denial instead, and the denial→marker path stays on the tiers above. + +## Deferred phases + +Each phase gets its full design when picked up, validated against the code at that time, and lands with unit, real-API e2e, and snapshot coverage at the tiers it touches. + +- **Per-session workspace root** — the executor's write boundary stays config-fixed for its lifetime while each ACP session has its own cwd; a per-session root rides the same per-call policy carrier once designed. +- **Cross-family boundary** — the fs intent gates decide by the shared mode, making `read-only`/`workspace-write` real boundaries beyond bash. +- **Second consumer** — `subagent-acp` optionally confines child agents (per-call policy; unconfined default — a child agent must write its own persistence). +- **More environments** — an environment-coherent capability group example (e.g. bash+fs against one container). +- **Windows chain** — `PLATFORM_CHAINS.win32` is reserved and empty (fail-closed); filling it means a confinement runner from the AppContainer/restricted-token family, shipped from its own repository on the `node-addon-landlock-run` template, plus its profile dialect and denial/runner-failure signatures. + +## Alternatives considered + +- **Command-string heuristic preflight** — rejected: cannot understand expansion/subprocesses/symlinks; the strict attempt (run it, let the kernel decide) is the only trustworthy denial signal. +- **Functionally probe even a platform's sole backend** — rejected: probing arbitrates between candidates; with one there is nothing to decide, and probe cost taxes the first confined command of every session (prohibitive for heavy future backends). The runner's own exec-time fail-closed refusal plus `runnerFailureSignatures` classification carries the safety property instead. +- **Commit the built launcher binaries** — rejected: a binary in a diff is unreviewable and churns history; reviewed source + native CI builds + the launcher repo's byte-pinned publish rehearsal keep bytes out of every tree. +- **Compile the launcher on install** — rejected: pushes a C toolchain onto every consumer; a fallback that exists only where a compiler happens to be is not a fallback. +- **Cross-compile both architectures from one builder** — rejected: requires carrying a pinned cross toolchain (rustup targets, zig, or a container image) solely to rebuild two ~70 KB binaries; per-architecture native runners already exist and each builds its own platform package (the `node-addon-require-builtin` model, the launcher repo's own pipeline). +- **No fallback (bwrap or fail closed)** — rejected: concentrates failure on the hosts a sandbox matters most, degrading to `danger-full-access` by resignation. +- **Keep the mechanism inside `dsh-bash-sandbox`** — rejected: blocks the existing second consumer, makes future phases read mode out of a bash plugin's config, and cannot express escalation. +- **Config-fixed mode on the provider** — rejected: one mode per process; cannot serve concurrent consumers with different policies nor the one-shot widened retry. +- **One interface spanning containers/VMs too** — rejected: `confine(argv)` presupposes a shared filesystem; environment isolation is capability-sibling backends deployed as coherent groups. +- **Generic ToolRuntime wrapping any tool** — rejected: mechanically false for in-process tools (closures over `ctx`); the declarative-effects rewrite is unjustified for fs/web/todo. +- **Ask inside the executor (`dsh-bash-sandbox`)** — rejected: no `agent` to route through, no `callId` to attach the prompt to; adding them teaches a transport seam about sessions and UIs — the tool layer holds both and owns the model-facing vocabulary. +- **Auto-retry inside the same tool call** — rejected: a hidden re-entry the log cannot reconstruct: one `tool/call` would have produced two executions with different policies — the retry is a NEW logged call with its own arguments and result facts. +- **Advertise the escalation fields unconditionally** — rejected: under `dsh-bash-local` they are a dead lever — advertising an option the harness cannot honor manufactures doomed grants; capability-gating costs one registration-time read. +- **A default-relative escalation ladder (advertise only the modes wider than the executor's registration-time default)** — rejected: per-session overrides make the default the wrong baseline — a session switched narrower than the default loses exactly the lever it needs, and under a `danger-full-access` default the fields vanish entirely while a `read-only`-overridden session stays confined with no escalation path. The enum pins the closed target vocabulary; strict widening is a per-call execution check against the session's effective mode. +- **Per-session dynamic tool schemas** — rejected: schemas are registry-global by design (one assembly vocabulary, the pinned-header snapshot contract), and re-registering per session would buy only what the execution-time strict-wider check already guarantees, at the cost of a per-session schema surface and header churn on every switch. +- **Hard-match the retry to a prior denial** — rejected: command-string identity is fragile (quoting, `workdir`, env prefixes, a pipeline retried as its failing stage) — false-rejects honest retries or is trivially satisfied; the real boundary is the human seeing command + justification. Revisit only if `allow_always` grant storage ever needs machine-checkable scopes. +- **A generic `env/state` facts map with an owner service** — rejected: approval and sandbox compose independently, so neither's state may drag in a third package; single-key folds are one `findLast` each, dissolving the owner service; no invariant spans the knobs, so atomic multi-key patches bought nothing. +- **Narrate via `agent/user-message` + a bus event** — rejected: it presupposes a turn-entry seam that does not exist (the real seam is `agent/prompt-submit`), and pre-step's position serves both the coalesced turn-entry notice and the mid-turn immediacy bound with one listener. +- **A standing prompt statement of the sandbox mode (+ a switch narrator)** — shipped first, then removed on live evidence: with `Bash commands run under the "read-only" file sandbox.` in every request, the model refused to ATTEMPT denied-then-escalatable work (five of twelve turns in the first manual session ended with zero tool calls), turning the sandbox into a soft lockout. The denial marker names the mode at the moment it matters and the escalation fields carry the recovery; the approval knob keeps its statement because an auto-rejection is behaviorally indistinguishable from a human "no". +- **Track "last told" with its own bookkeeping events** — rejected: the `request/header*` fold already records the exact prompt the model saw; parsing the closed candidate sentences back replaces a second bookkeeping stream — events are needed only where they ARE the store. +- **ACP session modes instead of config options** — rejected: one mode list cannot carry two orthogonal knobs; config options are the spec's designed surface and modes are slated for removal in ACP v2. + +## Consequences + +What shipped pins — the tiers in Testing hold each: + +- A denied command retried with `sandbox_permissions` + `justification` prompts the user through the composed answerer chain; a grant runs THAT call under the wider mode (result facts say so) while every other call keeps its own effective mode; every non-grant outcome produces its distinct error text and executes nothing. +- The escalation fields exist exactly when the mounted executor confines; a request that is not strictly wider than the call's effective mode fails closed with its own text and prompts no one; a deployment with no ApprovalService fails escalating calls closed and leaves plain calls untouched. +- The system prompt never states the sandbox mode (an approval `'never'` policy is the one stated knob), and the whole exchange — headers, knob events, notices, approvals, results — reconstructs from the session log alone, with no event types beyond the two knob events. +- N idle-time flips produce at most one anchored event per knob (a net-zero sequence anchors none — a no-op push from a client echoing current selections records nothing); an approval-policy switch is narrated in at most one coalesced notice; a mid-turn sandbox switch is honored by the next call's stamp. +- A resumed session's overrides apply and are reported to the editor with no special-casing; a default changed while the process was down is narrated before the session's first new request, attributed to the operator. +- Two concurrent sessions never see each other's state, notices, or config options. +- `agent-loop` is untouched — everything rides `systemPrompt.section`, `SessionEventMap` merging, `agent.inject()`, `agent/pre-step`, `agent/prompt-submit`, and the ACP handler surface. + +Costs and accepted limits: + +- **The one-wrapper illusion is given up knowingly.** A `tools/pre-execute` wrapper plus prompt conventions does not solve sandbox approval — the correct design costs structured denials, native runner probes, per-call policy carriage, and consistent cross-family enforcement, and this design pays it. +- **`read-only` is not yet a cross-family boundary.** Until the fs intent gates decide by the shared mode, the claim holds for bash only; the contract says so honestly (§ In-process tools). +- **Windows has no backend.** Its chain slot is reserved empty — fail-closed, never a fallthrough; filling it is a deferred phase. +- **The Seatbelt rung leans on Apple's deprecated-but-shipped `sandbox-exec` CLI.** As darwin's sole candidate it is selected without probing, so a future removal surfaces at execution as the runner-failure classification — re-thrown `SANDBOX_UNAVAILABLE`, the command never runs; fail closed, never open. +- **Landlock confinement is only as complete as the running kernel's ABI.** Reported as `enforcement: 'partial'` rather than refused — the deliberate trade that keeps the fallback available on older-kernel hosts. +- **The launcher arrives as a registry dependency.** Trusted through its own repository's release pipeline (reviewed C source, native CI builders, byte-pinned publish rehearsal) plus this repo's version pin — the real-kernel e2e legs are what vouch for behavior through the installed bytes. +- **The model may over-ask.** Escalating without denial grounding, or picking `danger-full-access` where `workspace-write` suffices: the description steers and the enum forces the ladder, but the human prompt is the actual gate; the `approval/asked` reasons make over-asking auditable, and a `prepend` policy answerer can auto-reject patterns a deployment never wants. +- **The advertised target set is static while the effective mode is per-session** (schemas are registry-global) — a session already at the widest mode is still offered the fields. Harmless by construction: the strict-wider check at execution, not the enum, is the safety boundary — a non-widening request fails with its own text and never prompts anyone. +- **A granted escalation is not a working sandbox.** An unavailable backend still fails closed even for a granted escalation to a confining mode — at `confine()` when the platform has no chain or every probe fails, at execution when an unprobed sole runner refuses (classified as a sandbox failure, not a command failure) — while a granted `danger-full-access` run never touches the provider at all: there the grant, not the probe, is the authority. +- **An idle switch lives in bridge memory until the next turn anchors it.** A crash in that window reverts it (reported honestly on `session/load`), and a session that never runs another turn never persists it — accepted, with the loop-owned idle commit turn named as future work if durability becomes a requirement. +- **The approval narrator's restart baseline parses prompt prose.** The closed candidate sentence is owned by the writing module itself, so a wording change is a coordinated writer+parser edit in one file; a session whose headers predate the section silently adopts the current policy without a notice. +- **The approval section is still a dynamic prompt surface** (a `'never'` switch breaks provider prompt-prefix caching for that session). Accepted: policy switches are rare, and a model acting on a stale `'never'` is worse. The sandbox knob no longer touches the prompt at all. +- **The model may hold a stale belief about the sandbox mode** (nothing announces a switch). Accepted deliberately: the next attempt's marker or success corrects it, and the observed failure mode of announcing — preemptive refusal — is worse than one wasted retry. + +## FAQ + +Behavioral and usage questions only — every "why not X?" design question lives in [Alternatives considered](#alternatives-considered), whose job is exactly that. + +- **A command came back with `[sandbox: file access denied under read-only mode]` — did it fail?** It RAN, and the kernel refused a file effect: the denial is a result fact orthogonal to exit code. The teaching forbids retrying around it; the one sanctioned move is the same command retried once with an escalation request. +- **How is a BROKEN sandbox told apart from a failing command?** Runner failure outranks denial in classification: a failed run matching the wrap's `runnerFailureSignatures` means the command NEVER ran — foreground re-throws the structured `SANDBOX_UNAVAILABLE` with the runner's stderr line, a background task stamps `sandbox.runnerFailed` and renders its own marker. A broken sandbox can never read as a failing command, and the command never runs unconfined. +- **What happens on a platform with no backend — Windows today?** `confine()` throws the fail-closed `SANDBOX_UNAVAILABLE` and the command never spawns; `win32` is a reserved EMPTY chain, pinned by test to fail closed identically until a Windows runner fills it (§ Deferred phases). +- **`bwrap` is installed on my host but unusable (disabled unprivileged userns, an LSM denying `mount`) — what happens?** The chain probe is functional — it builds and enforces a real profile rather than checking `--version` — so a present-but-unusable `bwrap` fails its probe, selection falls to the registry-installed Landlock launcher, and the verdict is cached for the provider's lifetime. +- **Does the sandbox restrict network or process visibility?** No — `SandboxMode` claims FILE effects only; the bwrap profile deliberately does not unshare pid, and no backend claims network. Whether network restriction becomes its own knob is left open in § The seam. +- **Which tools actually run confined?** OS subprocesses through `ctx.bash` — the bash tools, and hook commands transitively. fs/web/todo execute in-process, where an `execve` wrapper is mechanically meaningless; their `read-only` semantics arrive with the cross-family deferred phase, and until then the contract says bash-only honestly. +- **Does a granted escalation persist, or cover background tasks?** Neither: the grant is consumed by the very call that asked (foreground or background), that one call reports the mode it actually ran under, and every neighbor keeps its own. How escalation should be DEFINED for a background denial that only surfaces later via `bash_output` is left open in § Escalation. +- **When does an editor's mode switch take effect?** Mid-turn: appended immediately, honored by the very next call's stamp. Idle: held on the bridge's session record, anchored at the next turn's `agent/prompt-submit`, with N flips coalescing to at most one event (none if net-zero); a crash before anchoring reverts it and `session/load` reports the truth. The model is not told — its next command simply behaves under the new mode. +- **What survives a restart — and what if the operator changed the config default while the process was down?** Overrides replay from the session log (`effective = fold ?? config`), so a resumed session keeps its modes with zero catch-up machinery; a default that drifted offline changes behavior the same way a switch does (the approval policy, being stated, is additionally narrated with operator/config attribution). +- **What does `enforcement: 'partial'` on a result mean?** The selected backend enforces the subset its kernel ABI governs — e.g. Landlock before ABI v3 does not govern path truncate — and says so structurally instead of refusing the host; the probe's report line distinguishes the cases. The bwrap and Seatbelt profiles govern every promised file effect by construction, so they always report `full`. + +## Prior art + +In-repo precedents this design copies or contrasts with: + +- [The capability-seams RFC](../architecture/2026-06-13-capability-seams.md) — the interface/implementation/consumer split and the "don't split preemptively" timing rule the second consumer satisfied. +- The `dsh-bash` request/spec split and its `owner` field ([the bash vocabulary catalog](../../../core-data-structures/bash.md)) — the per-call carrier template `sandboxMode` rides, and the explicit-`resolve()` defaulting convention. +- [The approval seam RFC](2026-07-06-approval-seam.md) — the channel escalation asks through; its answerer waterfall, audit pair, and one-package rationale are recorded there. +- [Event-sourced sessions](../architecture/2026-06-11-event-sourced-sessions.md) and [the turn-enclosure invariant](../architecture/2026-06-15-turn-enclosure-invariant.md) — the log-as-store foundation the per-session modes fold over, and the commit boundary the anchoring design obeys. +- [The interception-seams RFC](2026-06-30-interception-seams.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own). diff --git a/docs/rfc/proposed/feature/2026-06-14-acp-agent-client-protocol.md b/docs/rfc/proposed/feature/2026-06-14-acp-agent-client-protocol.md deleted file mode 100644 index c321c56d53..0000000000 --- a/docs/rfc/proposed/feature/2026-06-14-acp-agent-client-protocol.md +++ /dev/null @@ -1,84 +0,0 @@ -# RFC: Agent Client Protocol (ACP) support — drive the coding agent from external editors - -Status: proposed - -> **Implementation status (MVP landed):** steps 1, 2, 3, 4, 6, 7, 8 are implemented in `packages/ui/acp` + `examples/acp-agent`. **Step 5 (the `session/request_permission` permission gate) is deferred** — the bridge ships a pass-through (tools run with the executor's full authority) marked `TODO(rfc010-permission-gate)`, and lays down only the `WeakMap` ownership seam the gate will build on. Status stays `proposed` until the gate lands. `session/cancel` is the queue-aware `agent.cancel()`: it aborts a running step, clears queued + steering work, and drops a turn that is about to start, so a queued-but-not-yet-started prompt never runs and a later prompt cannot be batched into the cancelled turn. **Per-session `cwd` is now honored** (lifting the original "launch the server in the workspace root" restriction — see § Deferred): `session/new` accepts any absolute `cwd`, and `session/load` requires the request `cwd` to match the persisted session `cwd` so the editor and bash executor agree on the workspace. - -## Problem - -The coding agent is reachable only through the readline `stdio-chat` plugin: it reads lines from stdin, calls `agent.send()`, and prints the assistant token stream (`session/event` `assistant/chunk`) to stdout. There is no structured protocol, so the agent cannot be embedded in an editor — no streaming render, no tool-call display, no permission UI, no resumable sessions. - -Editors are converging on the Agent Client Protocol (ACP), which Zed and others speak: JSON-RPC 2.0 over newline-delimited stdio, modeled on the Language Server Protocol. An editor boots the agent as a subprocess and exchanges `initialize` / `session/new` / `session/prompt`, rendering streamed `session/update` notifications and `session/request_permission` prompts. The goal is for the agent to be a drop-in ACP server — implement the protocol once and run in any ACP client, with no per-editor glue. - -This RFC has a hard prerequisite on [session persistence](../../implemented/architecture/2026-06-14-session-persistence.md): it assumes durable session persistence (the `SessionPersistence` service and the async `AgentLoop.resume` seam) is implemented, so resuming a session via `session/load` is in scope. None of those APIs exist yet — `AgentLoop` currently exposes only the synchronous `create` — so ACP must land after, or in the same change as, [session persistence](../../implemented/architecture/2026-06-14-session-persistence.md), and pins to its `resume(agentId, resumeSessionId)` contract. Session persistence persists every `SessionEvent` verbatim (including `assistant/chunk`), so a loaded session has the stream chunks needed to replay turns to the client. - -## Proposal - -A new plugin package `@deepseek-ai/dsh-acp` — a client-driver / UI plugin, the structured analogue of `stdio-chat`. It is NOT a change to the loop and NOT an [capability seams](../../implemented/architecture/2026-06-13-capability-seams.md) interface/implementation/consumer capability split; it consumes the existing `agent/*` event taxonomy and the `tools/pre-execute`/`tools/post-execute` waterfalls. - -It depends on the official `@agentclientprotocol/sdk` (the `AgentSideConnection` class) — Apache-2.0, actively versioned. The SDK declares a `zod` peer dependency and imports `zod/v4` at runtime, so `packages/ui/acp` must declare `zod` itself (per the workspace dependency constraints). This is the renamed successor to `@zed-industries/agent-client-protocol`, which is now deprecated on npm. - -The mapping between ACP and existing harness seams — each row names the seam and any required extension: - -| ACP (client ⇄ agent) | Harness seam | Notes | -|---|---|---| -| `initialize` | static handler | negotiate `protocolVersion` (echo the supported version, else error); advertise text-only `promptCapabilities` and `loadSession: true`; report agent name/version | -| `session/new {cwd, mcpServers, additionalDirectories}` → `{sessionId}` | the `dsh-agent` create factory (see Dependency note + Plan) | the seam must accept `{ sessionId, meta }` so the ACP-generated `sessionId` becomes the live/persisted session id and the validated `cwd` is attached as the `SessionHeader` (today `AgentLoop.create(id)` hardcodes `${id}-session` and takes no metadata); reject a 2nd session (single-session MVP, see [ACP multi-session](2026-06-14-acp-multi-session.md)); `cwd` validated (require absolute) — any absolute cwd is honored: it becomes the session's `SessionHeader.cwd` and the default bash workdir (per-session cwd, see § Deferred → RESOLVED), so the server need not launch in the workspace; non-empty `mcpServers` and `additionalDirectories` are rejected for the MVP because silently ignoring requested servers/roots would desync the client's tool and filesystem-scope UI | -| `session/load {sessionId, cwd, mcpServers, additionalDirectories}` | the `dsh-agent` resume factory ([session persistence](../../implemented/architecture/2026-06-14-session-persistence.md) + Dependency note) | load `{ meta, events }`, seed the session, re-derive history via `deriveMessages()`, replay prior turns to the client as `session/update` per the ACP load contract; `mcpServers` and `additionalDirectories` rejected as in `session/new` | -| `session/prompt {prompt}` | `agent.send()` (idle) | text blocks → `TextBlock`; reject image/audio per advertised capabilities; one in-flight prompt per session | -| resolve `session/prompt` → `{stopReason}` | the `turn/end` `session/event` (its `reason`) | map the harness kebab `TurnEndReason` to the ACP snake_case `StopReason` wire enum: `completed`→`end_turn`, `max-tokens`→`max_tokens`, `aborted`(cancel)→`cancelled`, plus `refusal`/`max_turn_requests` when applicable; honor the batch-into-one-turn and send-not-synchronously-running settle semantics | -| `session/update: agent_message_chunk` | `session/event` `assistant/chunk` `text-delta` only | do NOT also emit on `block-end(TextBlock)` — it carries the fully-assembled block and would duplicate the streamed text | -| `session/update: agent_thought_chunk` | `session/event` `assistant/chunk` `reasoning-delta` | | -| `session/update: tool_call` (pending→in_progress) | `session/event` `tool/call` | demux via a Session→sessionId map; `kind` inferred from the tool name | -| `session/update: tool_call_update` (completed/failed) | `session/event` `tool/result` | a throwing `tools/execute` yields NO `tool/result` → fail the pending tool UI from `agent/error`/turn-end | -| `session/request_permission {sessionId, toolCall, options}` | prepended `tools/execute` listener | no-op unless `exec.agent` is ACP-owned; await the outcome; `selected/allow_*` → `next()`; `reject_*`/`cancelled` → veto `ToolExecutionResult{isError}` | -| `session/cancel` (notification) | `agent.cancel(reason)` | the queue-aware cancel (abort running step, clear queued + steering, drop an about-to-start turn); settle the in-flight prompt as `cancelled`; resolve any pending permission as `cancelled` exactly once | - -The permission gate is the first real consumer of the `tools/execute` veto seam (the documented "single veto/sandbox/permission seam" plus the deferred "Permission system" TODO in [docs/architecture.md](../../../architecture.md)). It is a single global listener registered with `prepend: true` so it runs before any other tool wrapper. `ToolExecution.agent` is optional and the `Agent` interface carries no origin marker, so the bridge tracks ownership itself: it records each agent it creates in a `WeakMap` and the gate no-ops (calls `next()` immediately) for any `exec.agent` it does not own — non-ACP agents and the no-agent case pass straight through. For an owned agent it resolves the session, issues `session/request_permission`, and stores the pending resolver on that session's record so the outcome — or a `session/cancel`/connection-close — settles it exactly once. - -Lifecycle and disposal: the connection, listeners, and in-flight permission promises register via `ctx.effect`/`ctx.on`; teardown is async and must *reach* quiescence, not just request it — close the connection, settle/reject pending permissions, and dispose each owned agent through its `AgentHandle.dispose()` (which stops the loop, `await`s its exit, and unregisters). Owner teardown goes through that handle seam, not the loop's concrete `agent.done` (which exists only on `ReactLoopAgent`); a non-owner that merely wants to *observe* the current work settling without tearing the agent down awaits the interface-level `agent.whenIdle()`. Every listener contains its `send()` exceptions (log, never reject the turn) because stream chunks are emitted inside the model step, so a throwing listener would corrupt the turn. - -**Dependency note (architecture rule).** [docs/architecture.md](../../../architecture.md) states "plugins depend on interface packages, never on `dsh-agent-loop`." Creating and resuming agents is currently only on the concrete `AgentLoop` (`ctx.agentLoop`), so this RFC proposes adding an **abstract create/resume factory** to the `dsh-agent` interface (registry-level `create({ sessionId, meta })` / `resume(...)`), implemented by the loop, so `dsh-acp` injects only `agents` (the interface) and the dependency rule holds. The alternative — injecting the concrete `agentLoop` and recording a documented exception in the architecture doc — is explicitly the non-preferred fallback. - -## Plan - -1. Package scaffold `packages/ui/acp/` per [the cookbook](../../../cookbook/adding-a-package.md); add `@agentclientprotocol/sdk` and `zod`. Add the abstract create/resume factory to `dsh-agent` (the interface) so the bridge can `inject: ['agents', 'sessions', 'tools', 'sessionPersistence']` without depending on the concrete loop; `sessionPersistence` is required because `session/load` advertises `loadSession: true`. (Fallback only if the factory is judged not worth it: inject `agentLoop` directly and record the architecture-rule exception in `docs/architecture.md`.) -2. Connection plus `initialize`/`session/new`: wire `AgentSideConnection` to stdin/stdout; protocolVersion negotiation; the single-session guard; create the live session through the new `{ sessionId, meta }` factory seam (so the ACP `sessionId` and validated `cwd` become the session's id and header); the `sessionId↔agent` and `Session↔sessionId` maps. -3. Internal edit — turn-end reason fidelity (sanctioned: edit internals to fit ACP). Extend `TurnEndReasonMap` in the proper places: (a) declaration-merge a `max-tokens` variant in the owning package (`packages/core/session/src/types.ts`, alongside `completed|aborted|error|disposed`) — add `max-tokens` because `FinishReasonMap` produces it (DeepSeek maps `length` → `max-tokens`); do not add `refusal`, since no current adapter produces it (unknown DeepSeek finish reasons collapse to `error`), but leave a comment in `TurnEndReasonMap` noting `refusal` should be added when an adapter first emits it (`FinishReasonMap` is merge-extensible); (b) make `agent-loop`'s `loop.ts` populate the reason from the model `finish` chunk — `assembler.finish` lives inside `runStep`, so `runStep` must return it up to `runTurn`, and the rule is "the last step's finish reason wins, but any `max-tokens` in the turn surfaces as `max-tokens`"; (c) no consumer exhaustively switches over `TurnEndReason` today (the invariants plugin switches on `SessionEventType`, and `deriveMessages` ignores `turn/end`), so adding `max-tokens` is a non-breaking extension — but recheck before landing; (d) update [docs/architecture.md](../../../architecture.md) (the CI-verified loop-lifecycle/event-taxonomy doc) and the affected package READMEs/JSDoc (`dsh-session`, `dsh-agent`, `dsh-agent-loop`) per the repo doc-sync policy. This replaces a fragile "observe the finish chunk in the bridge" hack with a real, documented contract. -4. Prompt-turn streaming plus load: translate `session/event` (the `assistant/chunk` token stream plus boundaries and tool activity) into `session/update`; resolve `session/prompt` on settle, mapping the harness `TurnEndReason` to the ACP `StopReason` wire enum (`completed`→`end_turn`, `max-tokens`→`max_tokens`, `aborted`→`cancelled`) — a small total function with a test asserting the exact wire strings, since the SDK rejects an unknown `stopReason`. Concrete correlation, since the loop batches queued messages into one turn and `send()` does not synchronously flip to running: install the `session/event` listener before `send()`; capture the prompt's owning turn from its `turn/start` record, then resolve on that turn's `turn/end` (with `agent/status` idle/disposed as a fallback); reject an empty/whitespace prompt up front rather than calling `send()` (no turn would ever start, so the RPC would hang). Implement `session/load` on the session-persistence resume seam. -5. Permission gate: a single `tools/execute` listener registered with `prepend: true`, owning a `WeakMap` of bridge-created agents; no-op (`next()`) for unowned/no-agent calls; for owned calls → `session/request_permission` → allow (`next()`) / veto; settle the stored resolver exactly once on outcome, cancel, or connection close. -6. Example wiring (extract a shared base). `@cordisjs/plugin-include` is itself a plugin entry that resets `ctx.baseUrl` and loads a path, so a child `cordis.yml` can nest-include a shared base; the extraction is safe because every dependent plugin declares `inject` (loader groups initialize via `Promise.all`, so YAML order is NOT the dependency mechanism — never rely on it). Extract the provider/tool core (`llm, sessions, system-prompt, tools, agents, invariants, llm-deepseek, bash-local, tool-bash`) into `examples/base.yml`; have both `coding-agent` and a new `examples/acp-agent/` include it and add their own UI plugin plus logger. Keep `agent-loop` per-example (NOT in the base): `AgentLoop` creates its configured agents in its constructor, and the two examples disagree — `coding-agent` needs a pre-created `main` (its `stdio-chat` calls `ctx.agents.get('main')`), while `acp-agent` must pre-create none (ACP `session/new` creates agents). So `coding-agent` declares `agent-loop` with `agents: [{ id: main, … }]` and `acp-agent` with `agents: []`. `acp-agent` loads `dsh-session-persistence-jsonl` (from [session persistence](../../implemented/architecture/2026-06-14-session-persistence.md) — required for `session/load`), omits the stdout logger (see Risks), and adds `pnpm run demo:acp` plus the Zed `agent_servers` snippet. -7. Tests (the repo cares a lot here): a property-based test for the protocol shape (precedent: [property-based testing](../../implemented/testing/2026-06-11-property-based-testing.md)) — fuzz arbitrary harness event sequences and assert ACP-stream invariants (never a `tool_call_update` before its `tool_call`; exactly one `session/prompt` resolution per prompt; monotonic, well-formed ordering; `stopReason` in the legal set); codec unit tests over an in-memory `Duplex` pair (drive `AgentSideConnection` without a subprocess; assert exact frames for `initialize`, `session/new`, a full prompt turn); the mandatory HMR-safety test (dispose the fiber; assert the connection closed, all `ctx.on` listeners gone, any in-flight `request_permission` settled); failure-path tests (connection closes mid-stream; closes with a permission pending; a notification `send()` rejects but the turn survives; `finish{kind:'error'|'aborted'}`; a `tools/execute` throw with no `tool/result`; a second `session/new` rejected; a `session/prompt` while one is in flight; an empty prompt rejected without hanging; a `session/load` re-derives identical history and replays it); and an e2e (`*.e2e.ts`, self-skips without `DEEPSEEK_API_KEY`) that boots `examples/acp-agent`, connects a `ClientSideConnection`, sends a real prompt, owns and disposes the harness in `afterEach`, and verifies the world (files on disk), not the agent's self-report. -8. Docs: module/JSDoc plus a package README; extend [the extension cookbook](../../../cookbook/extension-cookbook.md) with the client-driver pattern. Flip Status to `implemented` on landing; record a decision in this RFC only if it proves durable, contested, and surprising (candidates: the `tools/execute` permission-ownership rule, the npm-dependency choice) — not auto-required. - -Deferred (each names its owning future work): - -- Multiplexing concurrent sessions → [ACP multi-session](2026-06-14-acp-multi-session.md). -- ~~`cwd` honoring.~~ **RESOLVED.** Originally there was no path from `session/new.cwd` to the bash workdir (`tool-bash` forwarded only an explicit `args.workdir`; `LocalBashExecutor.resolve` defaulted to its own config or `process.cwd()`), so the MVP validated `cwd` (require absolute) AND required the server to launch in the workspace root, erroring on a mismatch. This is now lifted: the validated `cwd` is stored as `SessionHeader.cwd`, and `dsh-tool-bash` defaults the bash workdir to the calling agent's `session.header.cwd` (an explicit model `workdir` still wins; a relative one resolves against it). Any absolute `cwd` is honored — the server need not launch in the workspace, and N sessions can each target a different directory. Widening scope beyond the single cwd (`additionalDirectories`) remains deferred. -- Client `terminal/*` proxying (a live editor terminal) and `fs/*` (editor-rendered diffs) — a future `BashExecutor` over the [capability seams](../../implemented/architecture/2026-06-13-capability-seams.md) bash seam, gated on `clientCapabilities.terminal`. -- Image/audio prompts (blocked on the DeepSeek adapter, which skips `image` blocks today), modes, auth, `available_commands`/slash-commands, `plan`, and `usage_update`. - -## Alternatives considered - -- **A process-wide stdout hijack inside `dsh-acp`** (defensively monkey-patching `console.log` / `process.stdout.write`) — rejected: it lives outside Cordis' effect-scoped, HMR-friendly plugin model, races the connection's own stdout handoff, and fights the logger. The stdout guarantee is config-only. -- **Injecting `agentLoop` directly instead of the abstract create/resume factory** — the recorded fallback, taken only if the factory seam is judged not worth it, with the architecture-rule exception recorded in `docs/architecture.md`. - -## Acceptance criteria - -- The `acp-agent` example speaks ACP over stdio end-to-end: `initialize`, `session/new` with a validated absolute `cwd` honored as the session workspace, streamed `session/update` frames per prompt turn, `session/load` re-deriving identical history, and `session/prompt` resolving with the correct wire `stopReason`. -- stdout carries only framed JSON-RPC (asserted by test); the permission gate settles every `session/request_permission` exactly once — on outcome, cancel, or connection close. -- The plan's test set runs green: the property-based protocol invariants, the codec unit tests over an in-memory duplex pair, the HMR-safety test, the failure-path matrix, and the self-skipping real-API e2e that verifies the world. - -## Risks - -stdout is the protocol — guaranteed by config, not by monkey-patching. The console logger writes through `console.log` to stdout, so any stdout UI/logger plugin corrupts JSON-RPC. The guarantee is config-only: the `acp-agent` example loads no stdout plugin (no console logger, no `stdio-chat`) and, if logging is wanted, uses a stderr exporter. A defensive process-wide `process.stdout.write`/`console.log` hijack inside `dsh-acp` is explicitly rejected — it lives outside Cordis' effect-scoped, HMR-friendly plugin model, races the connection's own stdout handoff, and fights the logger. A test asserts the example emits only framed JSON-RPC on stdout. - -New third-party runtime dependency plus protocol drift: `@agentclientprotocol/sdk` is young (0.25.x, recently renamed) and evolving. Pin the version and isolate churn to the one bridge package. This is not a vendoring-policy violation — [vendoring Cordis as source](../../implemented/process/2026-06-11-vendor-cordis-as-source.md) vendors the framework; genuine third-party deps already live on npm (`@earendil-works/pi-ai`). - -Turn-settle and prompt-correlation hazards: honor "queued messages batch into one turn" and "`send()` does not synchronously flip to running" (see `stdio-chat.ts` and the defensive-patterns section of [docs/architecture.md](../../../architecture.md)); gate resolution on an observed running→idle transition and handle the empty-prompt / no-work branch so an RPC can't hang. - -Permission-await and disposal hangs: a pending `request_permission` whose connection closes or whose turn aborts must settle exactly once; disposal must reach quiescence — tear each owned agent down through `AgentHandle.dispose()` (which stops the loop and awaits its exit), rather than orphaning awaits on a closed pipe. - -The 100% per-file coverage gate (repo policy) makes a branch-heavy protocol bridge real work. Accepted deliberately, surfaced so it isn't a surprise at PR time. - -ACP protocol-shape details (exact method names, `session/update` variants, permission option kinds, stop reasons) are taken from the ACP spec and the `@agentclientprotocol/sdk` types; they are not independently verifiable until the dependency is added, so the implementation pins the SDK version and conforms to its types rather than to this RFC's prose where they differ. diff --git a/docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md b/docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md deleted file mode 100644 index a65f6b67eb..0000000000 --- a/docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md +++ /dev/null @@ -1,48 +0,0 @@ -# RFC: Multiplex concurrent ACP sessions over one connection - -Status: proposed - -> **Implementation status:** the multi-session bridge (steps 1, 3, 4) and the bash task-ownership isolation are implemented in `packages/ui/acp` + `packages/bash/tool-bash`. **Per-session *permission* ownership is deferred** — it depends on [the ACP support permission gate](2026-06-14-acp-agent-client-protocol.md) (`TODO(rfc010-permission-gate)`), which is itself deferred; the `agent→sessionId` reverse map the gate will route through is in place. Step 2's per-session disposer scope is now implemented (see [agent lifecycle & ownership seams](../../implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md)): the factory returns a per-agent `AgentHandle` whose `dispose()` stops the loop, awaits quiescence, unregisters the agent, and removes its session, so a bare client disconnect leaves no registered agent or session-store entry. Status stays `proposed` until per-session permission ownership lands. - -> **Target-client note:** Zed is the current target ACP client, and its ACP client maintains a `HashMap` plus `pending_sessions` for concurrent `session/load` calls. The competing simplification to return to one live session per connection was rejected after checking that target-client shape; this RFC remains the path for finishing multiplexing and per-session permission ownership. See [the rejected simplification](../../rejected/simplification/2026-06-20-single-session-acp-bridge.md). - -## Problem - -[ACP support](2026-06-14-acp-agent-client-protocol.md) ships with a single active session per connection: a second `session/new` is rejected. Editors expect to run several conversations over one agent subprocess — a user opens multiple threads, or a client pre-warms sessions. The single-session guard is a deliberate MVP scope cut, not an architectural limit; this RFC lifts it. - -This paragraph is historical: the multi-session bridge has landed. The remaining proposed work is per-session permission ownership plus the lifecycle seams now tracked in [agent lifecycle and ownership seams](../../implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md). - -## Proposal - -The harness core already supports many agents (`AgentRegistry.list()` and `AgentLoop.create` impose no count limit), so multiplexing is a bridge-layer change in `@deepseek-ai/dsh-acp`, not a loop or core change. - -- Lift the single-session guard in `session/new`; allow N live sessions, each mapped to its own `ReactLoopAgent`. -- The bridge's `sessionId→agent` and `Session→sessionId` maps (introduced single-entry by [the ACP support RFC](2026-06-14-acp-agent-client-protocol.md)) become true multi-entry, plus a third `agent→sessionId` reverse map: the `tools/execute` permission gate receives only `exec.agent` (no sessionId), so it needs an O(1) reverse lookup to find the owning session. Every `agent/*` event and every `session/event` is demuxed strictly by id, so two sessions streaming at once never interleave their `session/update` notifications. -- Per-session prompt queues: [the ACP support RFC](2026-06-14-acp-agent-client-protocol.md)'s single-entry in-flight-prompt state becomes multi-entry — one in-flight prompt *per session*, tracked per `sessionId`. -- Per-session cancel routing: `session/cancel` cancels only its own session's agent (via the queue-aware `agent.cancel()`) and settles only that session's in-flight prompt. The cancel is scoped to that one agent — a per-agent `AbortController` for the running step plus the agent's own queued/steering FIFOs — so it never touches another session's stream or pending prompt. -- Per-session permission ownership: a `session/request_permission` and its outcome are bound to the originating session via the reverse map, so a permission prompt or a cancel in one session can never resolve another session's pending permission. - -## Plan - -1. Generalize the two id maps to multi-entry and add the `agent→sessionId` reverse map; add a per-session record holding the agent, the in-flight-prompt state, the pending-permission registry, and the session's disposer scope (see step 2). -2. Give each session a real per-session disposer scope, NOT `ctx.extend()` — in Cordis `ctx.extend()` only creates a child context/prototype, but `ctx.on()` registered on it is still owned by the current plugin fiber, so disposing it would not remove that session's listeners. Use a genuine child fiber (load a per-session sub-plugin, e.g. `ctx.plugin(...)` returning a fork, or collect each session's `ctx.on` disposers in its session record and call them on teardown). Demux every `agent/*` and `session/event` by id into the right session record. Note the single global `tools/execute` listener stays on the bridge root (it must see all agents) and routes via the reverse map. -3. Lift the `session/new` guard; keep `session/load` ([from ACP support](2026-06-14-acp-agent-client-protocol.md)) working per session. -4. Tests for cross-session isolation: two sessions streaming and permission-prompting concurrently never interleave; a cancel/abort in one session leaves the other's stream and pending permission untouched; per-session in-flight-prompt enforcement holds independently; disposing one session leaves the others running. - -## Alternatives considered - -**A per-session `ctx.extend()` scope** — rejected: in Cordis, `ctx.extend()` only creates a child context/prototype, and `ctx.on()` registered on it is still owned by the current plugin fiber, so disposing it would not remove that session's listeners. A genuine child fiber (or a per-session collection of disposers) is required. - -## Acceptance criteria - -- N concurrent sessions stream and permission-prompt without interleaving their `session/update` notifications; a cancel in one session leaves every other session's stream, queued prompts, and pending permissions untouched. -- Disposing one session removes exactly its own listeners; connection teardown reaches quiescence across all sessions. -- One session's agent cannot read or kill another session's background bash task. - -## Risks - -Listener fan-out cost: each session adds listeners; ensure disposal of one session removes exactly its own and the connection teardown ([from ACP support](2026-06-14-acp-agent-client-protocol.md)) still reaches quiescence across all sessions. - -The subtle correctness trap is cross-session leakage — a cancel or abort on one session settling another session's pending permission. The per-session permission ownership rule (routed via the `agent→sessionId` reverse map) and its isolation test are the guard. - -Shared background-task state: the bash executor's task ids are global and predictable (`bash-1`, `bash-2`, …), and `bash_output`/`bash_kill` look up by id without checking the caller. Under one session this is benign; under N sessions one session's agent could read or kill another's background task. This is a pre-existing `tool-bash` gap that multi-session turns into a real isolation hole — fixing it (validate the caller against the task owner) belongs with this RFC or a companion `tool-bash` change. diff --git a/docs/rfc/rejected/simplification/2026-06-20-single-session-acp-bridge.md b/docs/rfc/rejected/simplification/2026-06-20-single-session-acp-bridge.md index e68cd24346..8f1d4e4531 100644 --- a/docs/rfc/rejected/simplification/2026-06-20-single-session-acp-bridge.md +++ b/docs/rfc/rejected/simplification/2026-06-20-single-session-acp-bridge.md @@ -4,7 +4,7 @@ Status: rejected — Zed is the current target ACP client and its ACP implementa ## Problem -The ACP bridge now supports multiple live sessions on one JSON-RPC connection. That capability brings multi-entry session maps, reverse session/agent lookups, per-session prompt state, loading ids, demux for every event, cross-session teardown, and isolation concerns for future permission prompts and background tasks. The older [multi-session ACP proposal](../../proposed/feature/2026-06-14-acp-multi-session.md) still tracks the unfinished permission-ownership piece; this RFC is the competing simplification path. +The ACP bridge now supports multiple live sessions on one JSON-RPC connection. That capability brings multi-entry session maps, reverse session/agent lookups, per-session prompt state, loading ids, demux for every event, cross-session teardown, and isolation concerns for future permission prompts and background tasks. The older [multi-session ACP proposal](../../implemented/feature/2026-06-14-acp-multi-session.md) still tracks the unfinished permission-ownership piece; this RFC is the competing simplification path. The product target has proven it needs concurrent editor conversations over one harness process: Zed's ACP connection owns multiple sessions and load states. The snapshot replay tier still avoids concurrent model streams because its replay entries are positional; that is a test-fixture limitation, not a reason to remove bridge multiplexing. @@ -20,7 +20,7 @@ Remove the multi-session maps and demux where a single `SessionRecord | undefine - `session/new` and `session/load` reject while that record exists. - Event handlers no longer demux across a `Map`. - Multi-session tests are removed or moved under the proposal that continues to defend multiplexing. -- The existing [multi-session ACP proposal](../../proposed/feature/2026-06-14-acp-multi-session.md) is updated to link this RFC and remains the live direction. +- The existing [multi-session ACP proposal](../../implemented/feature/2026-06-14-acp-multi-session.md) is updated to link this RFC and remains the live direction. ## What we give up diff --git a/docs/testing.md b/docs/testing.md index a4a77c9d0c..62989a1096 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,17 +1,17 @@ # Testing policy -How this repo tests, tier by tier, and the rules that keep a green suite meaning something. Commands live in the root [AGENTS.md](../AGENTS.md) § Commands; the RFCs linked per tier carry the design rationale. +How this repo tests, tier by tier, and the rules that keep a green suite meaningful. Commands live in root [AGENTS.md](../AGENTS.md); linked RFCs carry the rationale. ## Tiers -- **Unit** (`pnpm run test`): vitest over `packages|examples/*/tests/**/*.spec.ts`, colocated with what they test. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Excessive tests are welcome — err toward covering edge cases, error paths, event ordering, and concurrency races; review findings get regression tests (see `packages/core/agent-loop/tests/review-fixes.spec.ts`). +- **Unit** (`pnpm run test`): vitest over `packages|examples/*/tests/**/*.spec.ts`, colocated with what they test. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Prefer edge cases, error paths, event ordering, and concurrency races; review findings get regression tests (see `packages/core/agent-loop/tests/review-fixes.spec.ts`). - **Coverage gate** (`pnpm run test:coverage`): the gating run, per-file 100% on `packages/*/*/src`. An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped. - **Real-API e2e** (`pnpm run test:e2e`): with-key tests against live provider APIs — the DeepSeek model plus provider-specific smokes that gate on their own keys (`EXA_API_KEY`, `PERPLEXITY_API_KEY`, …); each suite self-skips without its key so keyless CI stays green ([real-API e2e RFC](rfc/implemented/testing/2026-06-19-real-api-e2e-ci.md)). -- **Snapshot** (`pnpm run test:snapshot`): boots the real example subprocess, replays a recorded session keyless, diffs normalized stdout + the re-persisted log against committed goldens ([snapshot RFC](rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)). Re-record with `pnpm run test:snapshot:record`; reviewing the golden diff is part of the review. System-prompt/tool-schema content is pinned by ONE scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header RFC](rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). +- **Snapshot** (`pnpm run test:snapshot`): boots the real example subprocess, replays a recorded session keyless, diffs normalized stdout + the re-persisted log against committed goldens ([snapshot RFC](rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)). Use `pnpm run test:snapshot:record` when the model transcript should change; use `pnpm run test:snapshot:refresh` when the committed transcript is still the right mock LLM input and replay goldens need keyless rewrite. Review the golden diff. System-prompt/tool-schema content is pinned by ONE scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header RFC](rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). ## The with-key policy: inference is cheap here -We are DeepSeek — do not ration real-API tests. A no-key test proves the plumbing; only a with-key run proves the agent works against a real model. Write many: real prompts that write files, multi-turn conversations, tool use, cancellation mid-stream. Cheapest and highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal. Every example ships a keyless smoke and — unless keyless-by-nature — a with-key smoke ([examples/AGENTS.md](../examples/AGENTS.md)). +We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Write many: file-writing prompts, multi-turn conversations, tool use, cancellation mid-stream. Highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal. Every example ships a keyless smoke and — unless keyless-by-nature — a with-key smoke ([examples/AGENTS.md](../examples/AGENTS.md)). ## Prefer the real implementation over a mock diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index dc7dcd3d71..dab5c38c6d 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -20,6 +20,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. | | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. | | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. | +| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - | | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. | | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflows`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - | @@ -124,7 +125,7 @@ Registered by the tool registry itself under `mode: code` / `mode: both` (see th ### `bash` -Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. +Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. ```json { @@ -370,6 +371,29 @@ Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. +## `@deepseek-ai/dsh-tool-skill` + +### `skill` + +Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. + +```json +{ + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The exact skill name from the available skills list." + } + }, + "required": [ + "name" + ] +} +``` + +Source: [`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/src/index.ts) + ## `@deepseek-ai/dsh-tool-subagent` ### `subagent` diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md index 09a863badc..28eee043c4 100644 --- a/docs/tool-execution-pipeline.md +++ b/docs/tool-execution-pipeline.md @@ -11,7 +11,8 @@ flowchart TD toolCall["Session event: tool/call
logged before execution"] presentCall["UI pending card
presentCall(args)"] pre["tools/pre-execute waterfall
hooks, permission, sandbox"] - denied["deny or ask
tool body skipped"] + denied["denied
tool body skipped"] + approval["ctx.approval one-shot prompt
absent or unanswerable: deny"] around["tools/execute waterfall
timeout, retry, metrics (around dispatch)"] toolBody["Registered tool execute() body"] fsGate["fs/write-intent or fs/edit-intent
tool-fs mutations only"] @@ -25,7 +26,10 @@ flowchart TD toolCall --> pre pre -->|allow| around around --> toolBody - pre -->|deny or ask| denied + pre -->|deny| denied + pre -->|ask| approval + approval -->|allowed-once| around + approval -->|rejected, cancelled, unavailable| denied denied --> post toolBody --> fsGate fsGate --> toolBody @@ -37,6 +41,6 @@ flowchart TD toolResult --> presentResult ``` -Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate; hook bridges and future permission prompts live on the generic pre/post tool waterfalls; and around-dispatch concerns like the tool-call timeout policy (`@deepseek-ai/dsh-timeout-policy`) wrap core dispatch on `tools/execute`. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. Code Mode rides the same pipeline twice over: `run_code` is itself a registered tool body, and each tool call its program makes re-enters `ctx.tools.execute()` through BOTH waterfalls — serialized one at a time, logged as a `tool/code-dispatch` session event, with a deny surfacing to the program as a binding rejection (a sub-call's `additionalContext` is deliberately dropped — no safe outlet mid-run preserves call/result adjacency). +Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate; hook bridges and the approval seam's permission prompts live on the generic pre/post tool waterfalls; and around-dispatch concerns like the tool-call timeout policy (`@deepseek-ai/dsh-timeout-policy`) wrap core dispatch on `tools/execute`. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs. diff --git a/eslint.config.mjs b/eslint.config.mjs index cbb696bccb..c62d3e9739 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -22,6 +22,7 @@ export default tseslint.config( '**/lib/**', '**/node_modules/**', '**/.sessions/**', + '.claude/**', // harness-local state (worktrees, skills) — other checkouts, not this one's sources '**/.doc-typecheck-*/**', 'vendor/**', // vendored source keeps upstream style and idioms '**/*.js', @@ -38,7 +39,14 @@ export default tseslint.config( ], languageOptions: { parserOptions: { - project: ['./packages/*/*/tsconfig.json', './tsconfig.json'], + // One shared tsserver-style project service instead of 60+ standalone + // per-package programs: the old `project` glob built every package's + // full dependency closure (sibling sources via the dev `paths` map + + // the vendored Cordis stack) as its own program and kept them all + // resident — ~5 GB peak, an OOM past node's default heap. The service + // resolves each file to its nearest owning tsconfig and shares the + // graph. + projectService: true, tsconfigRootDir: import.meta.dirname, }, }, @@ -89,7 +97,9 @@ export default tseslint.config( ], languageOptions: { parserOptions: { - project: ['./tsconfig.json'], + // Same shared project service as the src block: test files resolve + // through the root tsconfig (its include covers every tests/ tree). + projectService: true, tsconfigRootDir: import.meta.dirname, }, }, diff --git a/examples/AGENTS.md b/examples/AGENTS.md index 3d2a700ca0..d54104a189 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -2,7 +2,7 @@ Runnable demos showing how the harness is wired. **Examples are NOT workspaces** — each `examples/*/package.json` is a private, dependency-free stub, never built. They are booted as unbuilt `tsx` subprocesses via the cordis Loader reading a `cordis.yml`; the `@deepseek-ai/dsh-*` plugin names in those YAML files resolve through the root `tsconfig.json` `paths` map, not through `node_modules`. -Because examples are not under the `packages/*/src` coverage gate, an example that grows real, reusable *logic* should extract it into a `packages/` package (where it gets the per-file 100% gate and a README). Keep only example-specific glue here: the `cordis.yml` wiring, demo-only mocks/teaching artifacts, and the e2e/snapshot scenarios. There is no `start.ts` — the boot glue (Loader tail, `.env` load, snapshot-mode selection, stdin-dispose lifecycle) lives in each app package's `bin` (`@deepseek-ai/dsh-stdio-agent`, `@deepseek-ai/dsh-acp-agent`), which the `demo:*` scripts invoke against the leaf `cordis.yml`. +Because examples are not under the `packages/*/src` coverage gate, an example that grows real, reusable *logic* should extract it into a `packages/` package (where it gets the per-file 100% gate and a README). Keep only example-specific glue here: the `cordis.yml` wiring, demo-only mocks/teaching artifacts, and the e2e/snapshot scenarios. There is no `start.ts` — the boot glue lives in each app package's `bin` (`@deepseek-ai/dsh-stdio-agent`, `@deepseek-ai/dsh-acp-agent`), which the `demo:*` scripts invoke against the leaf `cordis.yml`. ## Every example ships e2e smokes (keyless + with-key) @@ -13,7 +13,7 @@ Each example must have **both** kinds of end-to-end smoke, because they catch di **Exception — keyless-by-nature examples.** An example whose model is itself a mock/deterministic stand-in (no real provider) has no meaningful with-key smoke; the keyless smoke is the complete requirement. State the exception inline in the test. -A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_PATH` to the repo-root tsconfig — the unbuilt `paths` map is found by searching UP from cwd, so a temp cwd outside the repo would otherwise fall back to stale built `lib/`. Pass `--expose-internals` when the example's `cordis.yml` loads the HMR plugin (mirror the `demo:*` script). +A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_PATH` to the repo-root tsconfig (the unbuilt `paths` map is found by searching UP from cwd), and pass `--expose-internals` when the `cordis.yml` loads the HMR plugin (mirror the `demo:*` script). ## Current state @@ -22,6 +22,7 @@ A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_P | `echo-agent` | `tests/echo.e2e.ts` — boots the real `cordis.yml`, drives the echo tool round-trip and the direct canned reply | **N/A — keyless by nature** (the `mock-echo` model has no real provider) | | `coding-agent` | `tests/keyless-smoke.e2e.ts` — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit; `tests/code-mode-keyless-smoke.e2e.ts` — the same boot guard for the Code Mode overlay | `tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts` — real model + real bash + real todo_write, world-verified; `tests/code-mode.e2e.ts` — a real model composes two bash calls in one `run_code` program; collapsed header, dispatch events, written file all verified | | `cordis-agent` | `tests/keyless-smoke.e2e.ts` — boots the real tree incl. `@deepseek-ai/dsh-tool-cordis` by package name; the tool logic is unit-tested in `packages/cordis/tool-cordis` | `tests/cordis-tools.e2e.ts` — real model mounts a listener (tagged line fires), builds+calls its own tool, composes two mounts via provide/inject | +| `sandbox-acp-agent` | `escalation.e2e.ts` — boots the real tree (sandbox + approval + bridge) keyless: initialize + `session/new` | same file — denied → escalates → a scripted client grants (the write must land) or rejects (it must not); skips without key/runner | | `acp-agent` | `pnpm run test:snapshot` — boots the real ACP subprocess and replays a recorded session keyless (incl. the hook matrix: a scenario per hook point × outcome for BOTH the Claude and Codex bridges — block, deny, ask, context-fold, force-continue); `tests/acp.e2e.ts` also asserts stdout purity without a key | `tests/acp.e2e.ts` — real ACP prompt, verifies a file the agent wrote; `tests/hooks.e2e.ts` — a real `PreToolUse` hook blocks bash, verifies the file is NOT written | See [the root AGENTS.md](../AGENTS.md) for repo-wide conventions and [docs/architecture.md](../docs/architecture.md) for the design. diff --git a/examples/README.md b/examples/README.md index e8a41a366b..de7a907785 100644 --- a/examples/README.md +++ b/examples/README.md @@ -32,3 +32,9 @@ Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/R An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests. Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`); `pnpm run demo:code-mode acp` boots the same server in Code Mode via the `code-mode.cordis.yml` overlay. See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design. + +## sandbox-acp-agent + +The coding agent with its bash executor swapped for the sandbox stack ([`@deepseek-ai/dsh-sandbox-local`](../packages/sandbox/sandbox-local) + [`@deepseek-ai/dsh-bash-sandbox`](../packages/bash/bash-sandbox) — the one-entry executor swap the `ctx.bash` capability seam exists for), served over ACP with [`@deepseek-ai/dsh-user-approval`](../packages/ui/user-approval) mounted — the first composition where the approval loop is LIVE: a sandbox denial escalated by the model becomes a `session/request_permission` prompt in the editor, and "Allow once" runs exactly that command under the wider mode. + +Run with: `pnpm run demo:sandbox-acp` (needs `DEEPSEEK_API_KEY`; bwrap, a Landlock-enforcing kernel, or macOS for confined runs). See [sandbox-acp-agent/README.md](sandbox-acp-agent/README.md). diff --git a/examples/acp-agent/README.md b/examples/acp-agent/README.md index 5b3c936651..e3d8542efd 100644 --- a/examples/acp-agent/README.md +++ b/examples/acp-agent/README.md @@ -33,8 +33,8 @@ The editor sets each session's `cwd` to the project it opens; both the agent's b ## Snapshot tests (record-once / replay-deterministic) -This example is the home of the harness's **snapshot tests** — they boot this server as a real subprocess, drive it with a deterministic input script, and diff its normalized output against committed golden files. The model is made deterministic by `@deepseek-ai/dsh-llm-replay`, a function/namespace plugin that installs an `llm/stream` waterfall listener and short-circuits it, serving model streams reconstructed from a recorded **session JSONL** fixture (`/session.jsonl`) — so replay needs no API key. The fixture IS the persisted session log: its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each `stream()` call (one model call per loop step). Recording is therefore "run the real agent once and harvest the `.jsonl`". The two failure modes not expressible as logged chunks — a pure throw before any chunk, and cancel/hang — use an optional `/replay.override.json` sidecar (a `ReplayEntry[]` that replaces the derived script). A scenario that needs the agent to operate on existing files ships an optional `/workspace/` directory — the harness copies its contents into the temp cwd before the run (see `workspace-edit`). See [the ACP snapshot tests RFC](../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md) for the full design. +This example is the home of the harness's **snapshot tests** — they boot this server as a real subprocess, drive it with a deterministic input script, and diff its normalized output against committed golden files. The model is made deterministic by `@deepseek-ai/dsh-llm-replay`, a function/namespace plugin that installs an `llm/stream` waterfall listener and short-circuits it, serving model streams reconstructed from a recorded **session JSONL** fixture (`/session.jsonl`) — so replay needs no API key. The fixture IS the persisted session log: its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each `stream()` call (one model call per loop step). Recording is therefore "run the real agent once and harvest the `.jsonl`"; use `pnpm run test:snapshot:record` when the model transcript itself should change, and `pnpm run test:snapshot:refresh` when the committed model transcript is still the right mock input and only the current replay output/goldens need to be rewritten. The two failure modes not expressible as logged chunks — a pure throw before any chunk, and cancel/hang — use an optional `/replay.override.json` sidecar (a `ReplayEntry[]` that replaces the derived script). A scenario that needs the agent to operate on existing files ships an optional `/workspace/` directory — the harness copies its contents into the temp cwd before the run (see `workspace-edit`). See [the ACP snapshot tests RFC](../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md) for the full design. ## MVP limitations -The bridge supports N concurrent sessions per connection, each in its own workspace `cwd` (RFC 011). Remaining limits: prompts support ACP's baseline `text` and `resource_link` blocks only, `additionalDirectories` and `mcpServers` are rejected, and the tool-permission gate is deferred (`TODO(rfc010-permission-gate)` — tools run with the executor's full authority). See `packages/ui/acp/README.md` for the full contract. +The bridge supports N concurrent sessions per connection, each in its own workspace `cwd` (RFC 011). Remaining limits: prompts support ACP's baseline `text` and `resource_link` blocks only, and `additionalDirectories` and `mcpServers` are rejected. Permission prompts (`session/request_permission`) are wired through the approval seam, but this example composes no ask-producing policy, so tools run with the executor's full authority. See `packages/ui/acp/README.md` for the full contract. diff --git a/examples/acp-agent/tests/acp.e2e.ts b/examples/acp-agent/tests/acp.e2e.ts index 714791fa3e..8ff012c2c3 100644 --- a/examples/acp-agent/tests/acp.e2e.ts +++ b/examples/acp-agent/tests/acp.e2e.ts @@ -63,7 +63,16 @@ function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawn const child = spawn( process.execPath, ['--import', tsxLoader, binScript, configPath], - { cwd, env: { ...env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] }, + { + cwd, + env: { + ...env, + TSX_TSCONFIG_PATH: repoTsconfig, + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), + }, + stdio: ['pipe', 'pipe', 'pipe'], + }, ) const stderr: string[] = [] child.stderr.setEncoding('utf8') @@ -80,8 +89,9 @@ function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawn return Promise.resolve() }, requestPermission(_params: RequestPermissionRequest): Promise { - // Permission gate is deferred (TODO(rfc010-permission-gate)); the bridge - // never requests permission yet, so just allow if it ever does. + // This example composes no ask-producing policy (no hooks), so the + // bridge never prompts here; answer cancelled (fail closed) if it ever + // does — an unexpected prompt must not grant anything. return Promise.resolve({ outcome: { outcome: 'cancelled' } }) }, }) @@ -150,7 +160,13 @@ describe('acp-agent over real stdio (no key required)', () => { // which this purity test never triggers). So this runs WITHOUT real creds. const child = spawn(process.execPath, ['--import', tsxLoader, binScript, configPath], { cwd: workdir, - env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', TSX_TSCONFIG_PATH: repoTsconfig }, + env: { + ...process.env, + DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', + TSX_TSCONFIG_PATH: repoTsconfig, + DSH_HOME: join(workdir, '.dsh'), + DSH_AGENTS_HOME: join(workdir, '.agents'), + }, stdio: ['pipe', 'pipe', 'pipe'], }) const out: string[] = [] diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index d45ddf8591..4fc13f8bed 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -1,15 +1,16 @@ import { fileURLToPath } from 'node:url' import { dirname, join } from 'node:path' -import { defineAcpSnapshotSuite, type Scenario } from '@deepseek-ai/dsh-acp-snapshot' +import { defineAcpSnapshotSuite, type Scenario, type SnapshotSuiteOptions } from '@deepseek-ai/dsh-acp-snapshot' /** * The acp-agent example's snapshot suite: the scenario table for * `dsh-acp-snapshot`'s suite factory, which owns every compare/guard mechanic - * (golden + re-persisted-log diffs, record write-back, the pinned-header + * (golden + re-persisted-log diffs, record/refresh write-back, the pinned-header * uniformity guard, the fixture guards). Fixtures live under `snapshots//`; - * `pnpm run test:snapshot:record` re-records the `recorded` scenarios against - * the real API. See the package README (packages/support/acp-snapshot) and the - * snapshot RFC, docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md. + * `pnpm run test:snapshot:record` re-records model transcripts against the real + * API; `pnpm run test:snapshot:refresh` rewrites current replay goldens keyless. + * See the package README (packages/support/acp-snapshot) and the snapshot RFC, + * docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md. */ // The dsh-acp-agent bin (the demo:acp entry), this example's cordis.yml, and @@ -26,6 +27,21 @@ const AGENT = { const CODE_MODE_CONFIG = fileURLToPath(new URL('../code-mode.cordis.yml', import.meta.url)) const BOTH_MODE_CONFIG = fileURLToPath(new URL('../both-mode.cordis.yml', import.meta.url)) +function snapshotModeFromEnv(value: string | undefined): SnapshotSuiteOptions['mode'] { + switch (value) { + case undefined: + case '': + case 'replay': + return 'replay' + case 'record': + return 'record' + case 'refresh': + return 'refresh' + default: + throw new Error(`unknown DSH_SNAPSHOT mode: ${value}`) + } +} + const SCENARIOS: Scenario[] = [ { name: 'handshake', hasModelTurn: false, recorded: false }, { name: 'reject-extra-dirs', hasModelTurn: false, recorded: false }, @@ -36,6 +52,7 @@ const SCENARIOS: Scenario[] = [ { name: 'tool-call-turn', hasModelTurn: true, recorded: true }, { name: 'fs-terminal-card', hasModelTurn: true, recorded: true }, { name: 'todo-plan', hasModelTurn: true, recorded: true }, + { name: 'skill-load', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'skill' }, { name: 'workspace-edit', hasModelTurn: true, recorded: true }, { name: 'fs-read', hasModelTurn: true, recorded: true }, { name: 'fs-write', hasModelTurn: true, recorded: true }, @@ -111,5 +128,5 @@ defineAcpSnapshotSuite({ agent: AGENT, snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'), scenarios: SCENARIOS, - mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay', + mode: snapshotModeFromEnv(process.env.DSH_SNAPSHOT), }) diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl index b8cf737a02..0d3bf0b095 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783611774323,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783611774323,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783611774324,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783611774325,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-52lrTl.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n workflow(args: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: {\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n }[];\n };\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783611774325,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-52lrTl.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill(args: {\n /** The exact skill name from the available skills list. */\n name: string;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n workflow(args: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: {\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n }[];\n };\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783611774792,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783611774792,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783611774879,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl index 3d6e65d390..c8ad60cbb9 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783611771394,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783611771394,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783611771396,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783611771396,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-BteTVR.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n workflow(args: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: {\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n }[];\n };\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783611771396,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-BteTVR.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill(args: {\n /** The exact skill name from the available skills list. */\n name: string;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n workflow(args: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: {\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n }[];\n };\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783611771978,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/skill-load/input.json b/examples/acp-agent/tests/snapshots/skill-load/input.json new file mode 100644 index 0000000000..a5ee78bff6 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/skill-load/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Load the snapshot-skill skill with the skill tool, then reply DONE." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/skill-load/session.jsonl b/examples/acp-agent/tests/snapshots/skill-load/session.jsonl new file mode 100644 index 0000000000..bf24150ed2 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/skill-load/session.jsonl @@ -0,0 +1,29 @@ +{"type":"session","version":0,"id":"9eb4181f-2d05-49d3-98fc-3711fe2f5664","createdAt":1783654655599,"cwd":"/var/folders/_g/59jgff8x2gqd39f5vy1wnbfc0000gn/T/acp-snap-cwd-DhYwNW"} +{"type":"turn/start","seq":0,"time":1783654655602,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783654655603,"data":{"content":[{"type":"text","text":"Load the snapshot-skill skill with the skill tool, then reply DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783654655608,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783654655608,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/_g/59jgff8x2gqd39f5vy1wnbfc0000gn/T/acp-snap-cwd-DhYwNW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}],"messagePrefix":[{"role":"user","content":[{"type":"text","text":"\nA skill is a reusable set of task-specific instructions. The following skills are available in this session:\n\n\n- `snapshot-skill`: Exercise project skill discovery and loading in snapshot tests.\n\n\nIf the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.\n"}]}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Load the requested skill."}}} +{"type":"assistant/chunk","seq":6,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":7,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_skill_load","name":"skill","argumentsDelta":"{\"name\":\"snapshot-skill\"}"}}} +{"type":"assistant/chunk","seq":8,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Load the requested skill."}}}} +{"type":"assistant/chunk","seq":9,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"snapshot-skill\"}"}}}} +{"type":"assistant/chunk","seq":10,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5}}}} +{"type":"assistant/chunk","seq":11,"time":1783654655609,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":12,"time":1783654655609,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"Load the requested skill."},{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"snapshot-skill\"}"}],"usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5}},"sourceEventSeqs":[4,5,6,7,8,9,10,11],"surfaceOp":"append"} +{"type":"tool/call","seq":13,"time":1783654655609,"data":{"turn":1,"step":1,"callId":"call_skill_load","name":"skill","arguments":"{\"name\":\"snapshot-skill\"}"}} +{"type":"tool/result","seq":14,"time":1783654655610,"data":{"turn":1,"step":1,"callId":"call_skill_load","content":[{"type":"text","text":"\n\nBase directory for this skill: /var/folders/_g/59jgff8x2gqd39f5vy1wnbfc0000gn/T/acp-snap-cwd-DhYwNW/.dsh/skills/snapshot-skill\nResolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.\n\n\n\nFollow these snapshot-only instructions.\nResolve referenced resources relative to this skill directory.\n\n"}],"isError":false},"sourceEventSeqs":[13],"surfaceOp":"append"} +{"type":"step/end","seq":15,"time":1783654655610,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":16,"time":1783654655610,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":17,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":18,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The skill is loaded."}}} +{"type":"assistant/chunk","seq":19,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":20,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"DONE"}}} +{"type":"assistant/chunk","seq":21,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The skill is loaded."}}}} +{"type":"assistant/chunk","seq":22,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","seq":23,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4}}}} +{"type":"assistant/chunk","seq":24,"time":1783654655611,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":25,"time":1783654655611,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The skill is loaded."},{"type":"text","text":"DONE"}],"usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4}},"sourceEventSeqs":[17,18,19,20,21,22,23,24],"surfaceOp":"append"} +{"type":"step/end","seq":26,"time":1783654655611,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":27,"time":1783654655611,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/skill-load/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/skill-load/stdout.golden.jsonl new file mode 100644 index 0000000000..00e707088e --- /dev/null +++ b/examples/acp-agent/tests/snapshots/skill-load/stdout.golden.jsonl @@ -0,0 +1,8 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Load the requested skill."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_skill_load","title":"Load skill snapshot-skill","kind":"read","status":"in_progress","rawInput":"snapshot-skill"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_skill_load","status":"completed","content":[{"type":"content","content":{"type":"text","text":"\n\nBase directory for this skill: {{cwd}}/.dsh/skills/snapshot-skill\nResolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.\n\n\n\nFollow these snapshot-only instructions.\nResolve referenced resources relative to this skill directory.\n\n"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The skill is loaded."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/acp-agent/tests/snapshots/skill-load/workspace/.dsh/skills/snapshot-skill/SKILL.md b/examples/acp-agent/tests/snapshots/skill-load/workspace/.dsh/skills/snapshot-skill/SKILL.md new file mode 100644 index 0000000000..b0816d6bee --- /dev/null +++ b/examples/acp-agent/tests/snapshots/skill-load/workspace/.dsh/skills/snapshot-skill/SKILL.md @@ -0,0 +1,7 @@ +--- +name: snapshot-skill +description: Exercise project skill discovery and loading in snapshot tests. +--- + +Follow these snapshot-only instructions. +Resolve referenced resources relative to this skill directory. diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl index 5f49c4295d..6e6119fb69 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783600629541,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783600629541,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783600629542,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783600629542,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-ka5r8w.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783600629542,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-ka5r8w.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783600630819,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783600630820,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783600630822,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/coding-agent/tests/keyless-smoke.e2e.ts b/examples/coding-agent/tests/keyless-smoke.e2e.ts index dba8b140c7..b4d73f4d90 100644 --- a/examples/coding-agent/tests/keyless-smoke.e2e.ts +++ b/examples/coding-agent/tests/keyless-smoke.e2e.ts @@ -62,6 +62,8 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> { // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots. // No prompt is sent, so the adapter never streams — no network call. DEEPSEEK_API_KEY: 'keyless-smoke-no-call', + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), }, stdio: ['pipe', 'pipe', 'pipe'], }, diff --git a/examples/echo-agent/README.md b/examples/echo-agent/README.md index de42234ef1..dad0ce348a 100644 --- a/examples/echo-agent/README.md +++ b/examples/echo-agent/README.md @@ -31,4 +31,4 @@ node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples Type a message and press Enter. "echo " triggers a tool call round-trip (the mock model requests the `echo` tool, which echoes the text uppercased, and the next model step acknowledges it). -The session is persisted under `.sessions/` relative to the directory you launch the demo from. `pnpm run demo:echo` runs from the repo root, so the logs land in `/.sessions/` (a session with no cwd goes in the `_no-cwd/` bucket, one `.jsonl` log per session). Clean up with: `rm -rf .sessions` +The session is persisted under `.sessions/` relative to the directory you launch the demo from. `pnpm run demo:echo` runs from the repo root, so the logs land in `/.sessions/cwd-/` (one `.jsonl` log per session). Clean up with: `rm -rf .sessions` diff --git a/examples/echo-agent/tests/echo.e2e.ts b/examples/echo-agent/tests/echo.e2e.ts index 01bb34bff0..b446b2b191 100644 --- a/examples/echo-agent/tests/echo.e2e.ts +++ b/examples/echo-agent/tests/echo.e2e.ts @@ -63,7 +63,16 @@ async function runEcho(lines: string[]): Promise<{ stdout: string; code: number // requires it (mirrors the `demo:echo` script). The whole point is to boot // the example EXACTLY as it really runs, through the bin + Loader. ['--expose-internals', '--import', tsxLoader, binScript, configPath], - { cwd, env: { ...process.env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] }, + { + cwd, + env: { + ...process.env, + TSX_TSCONFIG_PATH: repoTsconfig, + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), + }, + stdio: ['pipe', 'pipe', 'pipe'], + }, ) child = proc let stdout = '' diff --git a/examples/sandbox-acp-agent/README.md b/examples/sandbox-acp-agent/README.md new file mode 100644 index 0000000000..bada288bde --- /dev/null +++ b/examples/sandbox-acp-agent/README.md @@ -0,0 +1,16 @@ +# sandbox-acp-agent + +The coding agent with its bash executor swapped for the sandbox stack ([`@deepseek-ai/dsh-sandbox-local`](../../packages/sandbox/sandbox-local/) + [`@deepseek-ai/dsh-bash-sandbox`](../../packages/bash/bash-sandbox/) — the one-entry executor swap the `ctx.bash` capability seam exists for), served over the **Agent Client Protocol**, plus [`@deepseek-ai/dsh-user-approval`](../../packages/ui/user-approval/) — which makes this the first composition where the approval loop is LIVE end to end: bash runs under `read-only`, a denial comes back as the structured marker, the model retries once with `sandbox_permissions` + `justification`, the ACP bridge's answerer turns that ask into a `session/request_permission` prompt in your editor, and "Allow once" runs exactly that command under the wider mode ([sandbox RFC § Escalation](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)). + +```sh +pnpm run demo:sandbox-acp # needs DEEPSEEK_API_KEY; drive it from Zed or any ACP client +``` + +Zed setup is the same as [acp-agent](../acp-agent/README.md) with this example's command; only the leaf `cordis.yml` differs (the sandbox stack + the approval entry in place of the local bash executor and the extra tool stacks). + +- **Every approval is one-shot** (`Allow once` / `Reject` — no `allow_always`: the harness has no grant storage yet), and a dismissed prompt or a rejected ask fails closed with its own error text; so does every ask when no editor is attached to answer. +- **Two session config options are live** ([sandbox RFC § Per-session mode switching](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): a capable client shows `Sandbox` (`read-only`/`workspace-write`/`danger-full-access`) and `Approvals` (`ask`/`never`) selectors per session — a switch is one log-only event on that session's log and execution follows it; the sandbox mode is deliberately NOT stated in the prompt or narrated (the model learns the boundary from the denial marker — behavior, not belief), while an approval switch to `never` is stated and narrated; a resumed session reports its overrides back on `session/load`. +- **The write boundary is config-fixed**: an escalated `workspace-write` run may write under the launch directory (`workspaceRoot: process.cwd()`) plus the platform temp area — a per-session root is config-phase future work in the [sandbox RFC](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md). +- **No usable runner fails closed per command** (structured `SANDBOX_UNAVAILABLE`), and the filesystem tools stay unloaded for the same reason as `sandbox-agent`: they would bypass the bash sandbox. + +Tests: `tests/escalation.e2e.ts` — keyless, it boots the real `cordis.yml` through the Loader as an ACP subprocess, proves the whole tree (sandbox executor + approval service + bridge) initializes and opens a session, and drives the config options end to end (both advertised with composition currents, switches honored and echoed as complete state, out-of-vocabulary values rejected); with a key and a usable runner, a scripted ACP client plays the human — the real model gets denied, escalates, the client answers `allow-once`, and the retried write must land on disk. `tests/acp.snapshot.ts` (the [shared snapshot kit](../../packages/support/acp-snapshot/) over this composition's `cordis.snapshot.yml` replay overlay) pins four scenarios as committed wire bytes: the keyless config-option exchange, the recorded `mode-switching` arc (the suite's pinned header — both switches, their prompt-section deltas, one "changed by the user" notice per knob, and a confined write landing under the switched mode), and both recorded escalation branches (`session/request_permission` answered allow-once / reject-once). Replay re-executes every recorded bash call under the host's real runner — Seatbelt works out of the box on macOS; on Linux install bubblewrap (or build the Landlock launcher) first, exactly what ci.yml's snapshot lane does. No fixture carries a real denial: denial stderr is backend dialect and would pin a fixture to its recording platform (the rationale comment atop the suite file). diff --git a/examples/sandbox-acp-agent/cordis.snapshot.yml b/examples/sandbox-acp-agent/cordis.snapshot.yml new file mode 100644 index 0000000000..b5f8ac73ed --- /dev/null +++ b/examples/sandbox-acp-agent/cordis.snapshot.yml @@ -0,0 +1,30 @@ +# Snapshot-test REPLAY overlay for the sandboxed composition: the SAME app +# tree as cordis.yml, derived from it by an include — the one difference is +# the model backend. A keyless replay run cannot boot the real adapter +# (llm-deepseek's apply() throws without DEEPSEEK_API_KEY), so the include +# patches the live tree at load time: the llm-deepseek entry is disabled by +# id, and the llm-replay entry (which serves a recorded session JSONL — no +# API key, no network) is inserted. Every other entry — the sandbox provider, +# the confined bash executor, the approval seam, the app — IS the live tree. +# The sandbox provider probes for a platform runner per EXECUTION, not at +# boot, so a protocol-only scenario (session config options) replays on hosts +# with no runner at all. +# +# The dsh-acp-agent bin selects this file for DSH_SNAPSHOT=replay (the +# sibling-swap of whatever config path it was handed). The replay fixture +# path comes from $DSH_SNAPSHOT_FILE, set by the snapshot harness. stdout +# stays reserved for the ACP JSON-RPC protocol. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ./cordis.yml + patches: + # The name is an assertion, not an override: the include skips the patch + # (warning) when the id points at a different plugin, so this can never + # disable the wrong entry. + - id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + disabled: true + - insert: + - id: llm-replay + name: '@deepseek-ai/dsh-llm-replay' diff --git a/examples/sandbox-acp-agent/cordis.yml b/examples/sandbox-acp-agent/cordis.yml new file mode 100644 index 0000000000..69ba9fb6c3 --- /dev/null +++ b/examples/sandbox-acp-agent/cordis.yml @@ -0,0 +1,63 @@ +# The sandbox-acp-agent plugin tree: the sandboxed coding agent served over the +# Agent Client Protocol, with the approval seam composed — the first LIVE +# approval composition. A sandbox denial escalated by the model +# (sandbox_permissions + justification) reaches the EDITOR as a +# session/request_permission prompt through the ACP bridge's answerer, and an +# "Allow once" runs exactly that command under the wider mode. +# +# CRITICAL: this tree loads NO stdout logger and NO hmr — stdout is reserved +# for the ACP JSON-RPC protocol (a property of @deepseek-ai/dsh-acp-agent, +# same as examples/acp-agent). +# +# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) — the +# dsh-acp-agent bin loads the gitignored repo-root .env first (on STDERR only). + +# The DeepSeek adapter. +- id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + config: + apiKey: !!js process.env.DEEPSEEK_API_KEY + baseURL: !!js process.env.DEEPSEEK_BASE_URL + models: + - deepseek-v4-flash + +# The sandbox stack: the platform-runner provider (bwrap → per-platform +# Landlock launcher → Seatbelt, functionally probed), then the confined bash executor. +# read-only is the fail-safe default; the write boundary for an escalated +# workspace-write run is workspaceRoot + the platform's temp area. NOTE: the +# workspace root is CONFIG-FIXED for the executor's lifetime (the launch dir +# here), while each ACP session has its own cwd — a per-session root is config- +# phase future work in the sandbox RFC. +- id: sandbox + name: '@deepseek-ai/dsh-sandbox-local' +- id: bash + name: '@deepseek-ai/dsh-bash-sandbox' + config: + mode: read-only + workspaceRoot: !!js process.cwd() + +# The approval seam (ctx.approval — mechanism only, no config): with it +# mounted, the bash tool's escalation gate has a channel, and the ACP bridge +# inside dsh-acp-agent answers for the sessions it owns by prompting the +# editor. Without an editor attached nothing can answer, and every ask fails +# closed. +- id: approval + name: '@deepseek-ai/dsh-user-approval' + +# The ACP server app: the agent-core spine + JSONL persistence + the ACP +# bridge (whose approval answerer completes the loop). +- id: acp-agent + name: '@deepseek-ai/dsh-acp-agent' + config: + model: deepseek-v4-flash + # Persistence root: $DSH_SNAPSHOT_SESSIONS_ROOT when the snapshot harness + # sets it (so a record run's logs land where the harness harvests them), + # else the local ./.sessions default. + persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persona: | + You are a coding assistant powered by the {{model}} model. Your working + directory is {{cwd}}. Your bash tool runs under a file sandbox — a + `[sandbox: file access denied …]` result is policy, not a command bug. + + Verify your work by running the code or tests. Keep answers brief and + factual. diff --git a/examples/sandbox-acp-agent/package.json b/examples/sandbox-acp-agent/package.json new file mode 100644 index 0000000000..5a4c9a989e --- /dev/null +++ b/examples/sandbox-acp-agent/package.json @@ -0,0 +1,7 @@ +{ + "name": "sandbox-acp-agent-example", + "description": "Runnable demo: the sandboxed coding agent as an ACP server, with sandbox-escalation approval prompts answered by the editor", + "private": true, + "version": "0.0.1", + "type": "module" +} diff --git a/examples/sandbox-acp-agent/tests/acp.snapshot.ts b/examples/sandbox-acp-agent/tests/acp.snapshot.ts new file mode 100644 index 0000000000..418b8068d3 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/acp.snapshot.ts @@ -0,0 +1,82 @@ +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { defineAcpSnapshotSuite, type Scenario, type SnapshotSuiteOptions } from '@deepseek-ai/dsh-acp-snapshot' + +/** + * Snapshot suite for the SANDBOXED composition (`../cordis.yml`, swapped to + * the sibling `cordis.snapshot.yml` replay overlay by the bin under + * `DSH_SNAPSHOT=replay`). Replay swaps only the MODEL for the recorded + * transcript — every bash call re-executes for real under the host's actual + * runner (Seatbelt on macOS, bwrap on Linux CI: ci.yml's snapshot lane + * installs bubblewrap for exactly this), so the recorded scenarios double as + * cross-backend confinement regression: an allowed command a runner change + * starts denying fails replay outright. Their commands are limited to + * `cat`/`printf` shapes whose bytes are identical across those backends and + * across GNU/BSD userlands. + * + * Deliberately ABSENT: a scenario whose transcript carries a real sandbox + * DENIAL. The harness-authored `[sandbox: file access denied …]` marker is + * byte-stable, but the denied command's own stderr is the backend's dialect + * (bwrap EROFS "Read-only file system", Landlock EACCES "Permission + * denied", Seatbelt EPERM "Operation not permitted", GNU vs BSD phrasing on + * top), and stderr reaches both compared surfaces — such a fixture replays + * only on the platform that recorded it. The denial→marker path stays on + * dsh-tool-bash's unit tests and the real-kernel sandbox e2e legs + * (.github/workflows/sandbox.yml); the escalation scenarios below sidestep + * it by having the USER assert the prior denial, so the recorded model + * escalates without a platform-variant denial in the log. + */ +const SCENARIOS: Scenario[] = [ + // Protocol-only (keyless, authored): the session config-option surface + // this composition adds — both advertised selects on session/new, the + // complete refreshed state every session/set_config_option answers with, + // and both rejection shapes — as committed wire bytes. No bash runs, so + // this one still replays on runner-less hosts. + { name: 'config-options', hasModelTurn: false, recorded: false }, + // The runtime mode-switching arc, and NECESSARILY the pinned-header + // scenario: an approval-policy switch rewrites its prompt section, and the + // resulting request/header-delta is legal only in the pinning scenario + // (the factory's uniformity guard). The pin commits this composition's + // full header — persona, tool schemas WITH the escalation fields — plus + // the approval delta and its "changed by the user" notice verbatim. The + // SANDBOX switch is deliberately silent (no section, no notice — the + // sandbox RFC's visibility asymmetry): the recorded arc proves it by + // BEHAVIOR, a confined write landing under the switched mode with no + // header change. + { name: 'mode-switching', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderDeltas: 1 }, + // The approval wire end-to-end, under the DEFAULT read-only/ask (a switch + // would emit a header-delta the uniformity guard forbids here): the + // escalating bash call streams, session/request_permission attaches to it + // (allow-once / reject-once), and the scripted answer drives each branch — + // an approved run executes CONFINED under the granted workspace-write; a + // rejected one executes nothing and fails with the deterministic + // rejection text. + { name: 'escalation-approved', hasModelTurn: true, recorded: true }, + { name: 'escalation-rejected', hasModelTurn: true, recorded: true }, +] + +function snapshotModeFromEnv(value: string | undefined): SnapshotSuiteOptions['mode'] { + switch (value) { + case undefined: + case '': + case 'replay': + return 'replay' + case 'record': + return 'record' + case 'refresh': + return 'refresh' + default: + throw new Error(`unknown DSH_SNAPSHOT mode: ${value}`) + } +} + +defineAcpSnapshotSuite({ + agent: { + binScript: fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)), + configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)), + tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)), + }, + snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'), + scenarios: SCENARIOS, + mode: snapshotModeFromEnv(process.env.DSH_SNAPSHOT), +}) diff --git a/examples/sandbox-acp-agent/tests/escalation.e2e.ts b/examples/sandbox-acp-agent/tests/escalation.e2e.ts new file mode 100644 index 0000000000..93915717a1 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/escalation.e2e.ts @@ -0,0 +1,213 @@ +import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from 'node:child_process' +import { Readable, Writable } from 'node:stream' +import { mkdtemp, readFile, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { afterEach, describe, expect, it } from 'vitest' +import { + ClientSideConnection, + ndJsonStream, + PROTOCOL_VERSION, + type Agent as AcpAgent, + type Client, + type RequestPermissionRequest, + type RequestPermissionResponse, + type SessionNotification, +} from '@agentclientprotocol/sdk' + +/** + * examples/sandbox-acp-agent end to end. + * + * Keyless smoke: boot the REAL `cordis.yml` through the `dsh-acp-agent` bin as + * an ACP subprocess and drive initialize + session/new — the real-Loader-path + * guard (postmortem 0001) for THIS tree's export shapes, which now include the + * sandbox executor AND the approval service. No prompt is sent, so neither the + * model nor a sandbox runner is ever exercised. + * + * With-key escalation flow (self-skips without DEEPSEEK_API_KEY or a usable + * platform runner): a scripted ACP client plays the human. The real model is + * denied under `read-only`, escalates with `sandbox_permissions` + + * `justification`, the bridge prompts THIS client over + * `session/request_permission`, the client answers `allow-once`, and the + * retried write must land ON DISK (world-verified). The session cwd is a temp + * dir under the platform temp area, which `workspace-write` grants — so either + * escalation target the model picks can land the write. + */ + +const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)) +const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +// The subprocess runs from a temp cwd OUTSIDE the repo; point tsx at the repo +// tsconfig so the unbuilt `paths` map resolves (see examples/AGENTS.md). +const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) + +// A usable confining runner, probed the same way the executor suites do: +// bwrap on Linux, Seatbelt's sandbox-exec on macOS. Without one the strict +// attempt would fail closed (SANDBOX_UNAVAILABLE) instead of producing the +// denial this flow starts from. +const hasBwrap = spawnSync('bwrap', ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent', '--', 'true'], { + timeout: 5_000, + stdio: 'ignore', +}).status === 0 +const hasSeatbelt = process.platform === 'darwin' && spawnSync('sandbox-exec', ['-p', '(version 1)(allow default)', 'true'], { + timeout: 5_000, + stdio: 'ignore', +}).status === 0 +const hasRunner = hasBwrap || hasSeatbelt + +interface Spawned { + child: ChildProcessWithoutNullStreams + client: ClientSideConnection + updates: SessionNotification['update'][] + permissionRequests: RequestPermissionRequest[] + stderr: string[] +} + +/** Boot the example as an ACP subprocess; the scripted client answers every permission prompt with `answer`. */ +function spawnSandboxAcpAgent(cwd: string, answer: 'allow-once' | 'reject-once'): Spawned { + const child = spawn( + process.execPath, + ['--import', tsxLoader, binScript, configPath], + { + cwd, + // A dummy key lets the deepseek adapter boot keyless (presence-checked at + // apply, used only on a real model call); the with-key tests carry the + // real key, so the fallback is inert there. + env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', TSX_TSCONFIG_PATH: repoTsconfig }, + stdio: ['pipe', 'pipe', 'pipe'], + }, + ) + const stderr: string[] = [] + child.stderr.setEncoding('utf8') + child.stderr.on('data', (chunk: string) => stderr.push(chunk)) + + const updates: SessionNotification['update'][] = [] + const permissionRequests: RequestPermissionRequest[] = [] + const stream = ndJsonStream( + Writable.toWeb(child.stdin) as WritableStream, + Readable.toWeb(child.stdout) as ReadableStream, + ) + const makeClient = (_agent: AcpAgent): Client => ({ + sessionUpdate(params: SessionNotification): Promise { + updates.push(params.update) + return Promise.resolve() + }, + requestPermission(params: RequestPermissionRequest): Promise { + permissionRequests.push(params) + const option = params.options.find(o => o.optionId === answer) + // The scripted human: pick the requested option when the prompt offers + // it; an unexpected prompt shape cancels (fail closed, never grants). + if (option === undefined) return Promise.resolve({ outcome: { outcome: 'cancelled' } }) + return Promise.resolve({ outcome: { outcome: 'selected', optionId: option.optionId } }) + }, + }) + const client = new ClientSideConnection(makeClient, stream) + return { child, client, updates, permissionRequests, stderr } +} + +let spawned: Spawned | undefined +let workdir: string | undefined + +afterEach(async () => { + if (spawned !== undefined && spawned.child.exitCode === null) spawned.child.kill('SIGKILL') + spawned = undefined + if (workdir !== undefined) await rm(workdir, { recursive: true, force: true }) + workdir = undefined +}) + +describe('sandbox-acp-agent keyless smoke (real cordis.yml via the Loader)', () => { + it('boots the tree — sandbox executor + approval service + bridge — and opens a session', async () => { + workdir = await mkdtemp(join(tmpdir(), 'sandbox-acp-smoke-')) + spawned = spawnSandboxAcpAgent(workdir, 'reject-once') + const { client } = spawned + // A dummy key boots the adapter; no prompt is ever sent, so no model call + // and no sandbox runner probe happen. This drives the fiber tree the same + // way an editor would, which is what catches a broken export/inject shape. + const init = await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + expect(init.protocolVersion).toBe(PROTOCOL_VERSION) + const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] }) + expect(sessionId.length).toBeGreaterThan(0) + }, 30_000) + + it('advertises both session config options and honors a switch end to end (no key, no model)', async () => { + workdir = await mkdtemp(join(tmpdir(), 'sandbox-acp-config-')) + spawned = spawnSandboxAcpAgent(workdir, 'reject-once') + const { client } = spawned + await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + // This tree composes bash-sandbox (mode: read-only) + approval → both + // knobs advertise, currents from composition config. + const created = await client.newSession({ cwd: workdir, mcpServers: [] }) + const advertised = created.configOptions ?? [] + expect(advertised.map(option => [option.id, 'currentValue' in option ? option.currentValue : undefined])) + .toEqual([['sandbox-mode', 'read-only'], ['approval-policy', 'ask']]) + // A switch responds with the COMPLETE refreshed state (the spec contract), + // and the new currents survive in the response of a second switch. + const afterSandbox = await client.setSessionConfigOption({ + sessionId: created.sessionId, configId: 'sandbox-mode', value: 'workspace-write', + }) + const afterApproval = await client.setSessionConfigOption({ + sessionId: created.sessionId, configId: 'approval-policy', value: 'never', + }) + const currents = (afterApproval.configOptions ?? []).map(option => + [option.id, 'currentValue' in option ? option.currentValue : undefined]) + expect(afterSandbox.configOptions?.find(option => option.id === 'sandbox-mode')) + .toMatchObject({ currentValue: 'workspace-write' }) + expect(currents).toEqual([['sandbox-mode', 'workspace-write'], ['approval-policy', 'never']]) + // An out-of-vocabulary value is a protocol error, never a silent default. + await expect(client.setSessionConfigOption({ + sessionId: created.sessionId, configId: 'sandbox-mode', value: 'yolo', + })).rejects.toThrow(/unknown sandbox-mode value/) + }, 30_000) +}) + +describe.skipIf(!process.env.DEEPSEEK_API_KEY || !hasRunner)('sandbox-acp-agent e2e: the live approval loop', () => { + it('denial → model escalation → editor prompt → allow-once → the retried write lands on disk', async () => { + workdir = await mkdtemp(join(tmpdir(), 'sandbox-acp-e2e-')) + spawned = spawnSandboxAcpAgent(workdir, 'allow-once') + const { client, permissionRequests } = spawned + + await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] }) + const res = await client.prompt({ + sessionId, + prompt: [{ type: 'text', text: `Use the bash tool to create the file ${workdir}/escalated.txt containing exactly "ACP_ESCALATION_OK". ` + + 'If the sandbox denies it, retry once with sandbox_permissions and a one-sentence justification, then stop.' }], + }) + expect(['end_turn', 'max_tokens']).toContain(res.stopReason) + + // The WORLD: the approved escalated retry landed the write read-only denied. + const proof = await readFile(join(workdir, 'escalated.txt'), 'utf8') + expect(proof).toContain('ACP_ESCALATION_OK') + + // The CHANNEL: the grant came through a real session/request_permission + // prompt attached to the escalating tool call, offering exactly the + // one-shot options. + expect(permissionRequests.length).toBeGreaterThan(0) + const prompt = permissionRequests[0] + if (prompt === undefined) throw new Error('expected a permission request') + expect(prompt.sessionId).toBe(sessionId) + expect(typeof prompt.toolCall.toolCallId).toBe('string') + expect(prompt.options.map(o => o.optionId).sort()).toEqual(['allow-once', 'reject-once']) + }, 240_000) + + it('a rejected escalation stays denied: no write lands, the turn still ends', async () => { + workdir = await mkdtemp(join(tmpdir(), 'sandbox-acp-e2e-')) + spawned = spawnSandboxAcpAgent(workdir, 'reject-once') + const { client, permissionRequests } = spawned + + await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] }) + const res = await client.prompt({ + sessionId, + prompt: [{ type: 'text', text: `Use the bash tool to create the file ${workdir}/refused.txt containing "NO". ` + + 'If the sandbox denies it, retry once with sandbox_permissions and a one-sentence justification. If that is rejected, stop and say so.' }], + }) + expect(['end_turn', 'max_tokens']).toContain(res.stopReason) + + // The WORLD: rejected means the file never appeared. + await expect(readFile(join(workdir, 'refused.txt'), 'utf8')).rejects.toThrow() + // And the rejection really flowed through a prompt (not a missing channel). + expect(permissionRequests.length).toBeGreaterThan(0) + }, 240_000) +}) diff --git a/examples/sandbox-acp-agent/tests/snapshots/config-options/input.json b/examples/sandbox-acp-agent/tests/snapshots/config-options/input.json new file mode 100644 index 0000000000..043019b659 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/config-options/input.json @@ -0,0 +1,10 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "setConfigOption", "configId": "sandbox-mode", "value": "workspace-write" }, + { "op": "setConfigOption", "configId": "approval-policy", "value": "never" }, + { "op": "setConfigOptionExpectError", "configId": "sandbox-mode", "value": "yolo" }, + { "op": "setConfigOptionExpectError", "configId": "reasoning-effort", "value": "max" } + ] +} diff --git a/examples/sandbox-acp-agent/tests/snapshots/config-options/session.jsonl b/examples/sandbox-acp-agent/tests/snapshots/config-options/session.jsonl new file mode 100644 index 0000000000..a6f73319bc --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/config-options/session.jsonl @@ -0,0 +1 @@ +{"type":"session","version":0,"id":"00000000-0000-0000-0000-000000000000","createdAt":0} diff --git a/examples/sandbox-acp-agent/tests/snapshots/config-options/stdout.golden.jsonl b/examples/sandbox-acp-agent/tests/snapshots/config-options/stdout.golden.jsonl new file mode 100644 index 0000000000..3fab1e81fa --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/config-options/stdout.golden.jsonl @@ -0,0 +1,6 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"read-only","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"ask","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","id":3,"result":{"configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"ask","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","id":4,"result":{"configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"never","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","id":5,"error":{"code":-32602,"message":"Invalid params: unknown sandbox-mode value \"yolo\""}} +{"jsonrpc":"2.0","id":6,"error":{"code":-32602,"message":"Invalid params: unknown config option \"reasoning-effort\""}} diff --git a/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/input.json b/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/input.json new file mode 100644 index 0000000000..4cfa610f55 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/input.json @@ -0,0 +1,10 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "The sandbox already denied writing escalated.txt in this workspace earlier. Retry it now exactly once: one single bash call with the command printf 'escalated\\n' > escalated.txt && cat escalated.txt, with sandbox_permissions set to workspace-write and the justification 'the user asked to write escalated.txt in the workspace'. Do not run it without sandbox_permissions first. I will approve the permission prompt. After the result, reply with the single word DONE and stop." } + ], + "permissionAnswers": [ + { "kind": "allow_once" } + ] +} diff --git a/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/session.jsonl b/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/session.jsonl new file mode 100644 index 0000000000..a754c516c9 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/session.jsonl @@ -0,0 +1,149 @@ +{"type":"session","version":0,"id":"8f399407-f505-45e5-9058-0994ff7b0865","createdAt":1783486769425,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-xKPr5d"} +{"type":"turn/start","seq":0,"time":1783486769426,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783486769426,"data":{"content":[{"type":"text","text":"The sandbox already denied writing escalated.txt in this workspace earlier. Retry it now exactly once: one single bash call with the command printf 'escalated\\n' > escalated.txt && cat escalated.txt, with sandbox_permissions set to workspace-write and the justification 'the user asked to write escalated.txt in the workspace'. Do not run it without sandbox_permissions first. I will approve the permission prompt. After the result, reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783486769427,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783486769427,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783486770051,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783486770052,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783486770179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783486770212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783486770213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783486770214,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783486770214,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ret"}}} +{"type":"assistant/chunk","seq":11,"time":1783486770215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ry"}}} +{"type":"assistant/chunk","seq":12,"time":1783486770215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":13,"time":1783486770242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}} +{"type":"assistant/chunk","seq":14,"time":1783486770243,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":15,"time":1783486770277,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sand"}}} +{"type":"assistant/chunk","seq":16,"time":1783486770278,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"box"}}} +{"type":"assistant/chunk","seq":17,"time":1783486770278,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_per"}}} +{"type":"assistant/chunk","seq":18,"time":1783486770306,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"missions"}}} +{"type":"assistant/chunk","seq":19,"time":1783486770307,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" set"}}} +{"type":"assistant/chunk","seq":20,"time":1783486770335,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":21,"time":1783486770337,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" workspace"}}} +{"type":"assistant/chunk","seq":22,"time":1783486770338,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"-w"}}} +{"type":"assistant/chunk","seq":23,"time":1783486770338,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"rite"}}} +{"type":"assistant/chunk","seq":24,"time":1783486770338,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":25,"time":1783486770368,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" They"}}} +{"type":"assistant/chunk","seq":26,"time":1783486770369,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" explicitly"}}} +{"type":"assistant/chunk","seq":27,"time":1783486770430,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" said"}}} +{"type":"assistant/chunk","seq":28,"time":1783486770431,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" they"}}} +{"type":"assistant/chunk","seq":29,"time":1783486770431,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" will"}}} +{"type":"assistant/chunk","seq":30,"time":1783486770458,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" approve"}}} +{"type":"assistant/chunk","seq":31,"time":1783486770459,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":32,"time":1783486770459,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" permission"}}} +{"type":"assistant/chunk","seq":33,"time":1783486770474,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" prompt"}}} +{"type":"assistant/chunk","seq":34,"time":1783486770474,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":35,"time":1783486770475,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":36,"time":1783486770475,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":37,"time":1783486770475,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" proceed"}}} +{"type":"assistant/chunk","seq":38,"time":1783486770518,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":39,"time":1783486770606,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":40,"time":1783486770606,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":41,"time":1783486770606,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":42,"time":1783486770606,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":43,"time":1783486770634,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"command"}}} +{"type":"assistant/chunk","seq":44,"time":1783486770634,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":45,"time":1783486770634,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":46,"time":1783486770634,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":47,"time":1783486770682,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"printf"}}} +{"type":"assistant/chunk","seq":48,"time":1783486770683,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" '"}}} +{"type":"assistant/chunk","seq":49,"time":1783486770683,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"es"}}} +{"type":"assistant/chunk","seq":50,"time":1783486770683,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"cal"}}} +{"type":"assistant/chunk","seq":51,"time":1783486770694,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"ated"}}} +{"type":"assistant/chunk","seq":52,"time":1783486770694,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\\\\n"}}} +{"type":"assistant/chunk","seq":53,"time":1783486770694,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"'"}}} +{"type":"assistant/chunk","seq":54,"time":1783486770695,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" >"}}} +{"type":"assistant/chunk","seq":55,"time":1783486770697,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":56,"time":1783486770697,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":57,"time":1783486770740,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" &&"}}} +{"type":"assistant/chunk","seq":58,"time":1783486770740,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" cat"}}} +{"type":"assistant/chunk","seq":59,"time":1783486770740,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":60,"time":1783486770740,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":61,"time":1783486770740,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":62,"time":1783486770802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":63,"time":1783486770802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":64,"time":1783486770802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"description"}}} +{"type":"assistant/chunk","seq":65,"time":1783486770802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":66,"time":1783486770803,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":67,"time":1783486770820,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":68,"time":1783486770821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"Write"}}} +{"type":"assistant/chunk","seq":69,"time":1783486770821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":70,"time":1783486770909,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":71,"time":1783486770910,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" and"}}} +{"type":"assistant/chunk","seq":72,"time":1783486770910,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" cat"}}} +{"type":"assistant/chunk","seq":73,"time":1783486770910,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" its"}}} +{"type":"assistant/chunk","seq":74,"time":1783486770924,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" content"}}} +{"type":"assistant/chunk","seq":75,"time":1783486770925,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":76,"time":1783486770953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":77,"time":1783486770953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":78,"time":1783486770953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"sand"}}} +{"type":"assistant/chunk","seq":79,"time":1783486770953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"box"}}} +{"type":"assistant/chunk","seq":80,"time":1783486770981,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"_per"}}} +{"type":"assistant/chunk","seq":81,"time":1783486770983,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"missions"}}} +{"type":"assistant/chunk","seq":82,"time":1783486770983,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":83,"time":1783486770983,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":84,"time":1783486771018,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":85,"time":1783486771018,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"works"}}} +{"type":"assistant/chunk","seq":86,"time":1783486771018,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"pace"}}} +{"type":"assistant/chunk","seq":87,"time":1783486771019,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"-w"}}} +{"type":"assistant/chunk","seq":88,"time":1783486771019,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"rite"}}} +{"type":"assistant/chunk","seq":89,"time":1783486771050,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":90,"time":1783486771083,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":91,"time":1783486771083,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":92,"time":1783486771083,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"just"}}} +{"type":"assistant/chunk","seq":93,"time":1783486771083,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"ification"}}} +{"type":"assistant/chunk","seq":94,"time":1783486771083,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":95,"time":1783486771084,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":96,"time":1783486771113,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":97,"time":1783486771114,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"the"}}} +{"type":"assistant/chunk","seq":98,"time":1783486771114,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" user"}}} +{"type":"assistant/chunk","seq":99,"time":1783486771114,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" asked"}}} +{"type":"assistant/chunk","seq":100,"time":1783486771142,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" to"}}} +{"type":"assistant/chunk","seq":101,"time":1783486771142,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" write"}}} +{"type":"assistant/chunk","seq":102,"time":1783486771142,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":103,"time":1783486771142,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":104,"time":1783486771142,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" in"}}} +{"type":"assistant/chunk","seq":105,"time":1783486771216,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" the"}}} +{"type":"assistant/chunk","seq":106,"time":1783486771217,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":" workspace"}}} +{"type":"assistant/chunk","seq":107,"time":1783486771217,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":108,"time":1783486771219,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":109,"time":1783486771231,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to retry the command with sandbox_permissions set to workspace-write. They explicitly said they will approve the permission prompt. Let me proceed."}}}} +{"type":"assistant/chunk","seq":110,"time":1783486771232,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > escalated.txt && cat escalated.txt\", \"description\": \"Write escalated.txt and cat its content\", \"sandbox_permissions\": \"workspace-write\", \"justification\": \"the user asked to write escalated.txt in the workspace\"}"}}}} +{"type":"assistant/chunk","seq":111,"time":1783486771232,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1255,"outputTokens":160,"cacheReadTokens":0,"reasoningTokens":34}}}} +{"type":"assistant/chunk","seq":112,"time":1783486771232,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":113,"time":1783486771236,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to retry the command with sandbox_permissions set to workspace-write. They explicitly said they will approve the permission prompt. Let me proceed."},{"type":"tool-call","id":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > escalated.txt && cat escalated.txt\", \"description\": \"Write escalated.txt and cat its content\", \"sandbox_permissions\": \"workspace-write\", \"justification\": \"the user asked to write escalated.txt in the workspace\"}"}],"usage":{"inputTokens":1255,"outputTokens":160,"cacheReadTokens":0,"reasoningTokens":34}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112],"surfaceOp":"append"} +{"type":"tool/call","seq":114,"time":1783486771236,"data":{"turn":1,"step":1,"callId":"call_00_ZSEIrZNdgQhL2QJgVHww8689","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > escalated.txt && cat escalated.txt\", \"description\": \"Write escalated.txt and cat its content\", \"sandbox_permissions\": \"workspace-write\", \"justification\": \"the user asked to write escalated.txt in the workspace\"}"}} +{"type":"approval/asked","seq":115,"time":1783486771238,"data":{"id":"4766a1b9-6cf5-4504-a6cc-97037b478964","toolName":"bash","callId":"call_00_ZSEIrZNdgQhL2QJgVHww8689","reason":"escalate sandbox to workspace-write: the user asked to write escalated.txt in the workspace"}} +{"type":"approval/decided","seq":116,"time":1783486771243,"data":{"id":"4766a1b9-6cf5-4504-a6cc-97037b478964","outcome":"allowed-once"}} +{"type":"tool/result","seq":117,"time":1783486771442,"data":{"turn":1,"step":1,"callId":"call_00_ZSEIrZNdgQhL2QJgVHww8689","content":[{"type":"text","text":"escalated\n"}],"isError":false},"sourceEventSeqs":[114],"surfaceOp":"append"} +{"type":"step/end","seq":118,"time":1783486771443,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":119,"time":1783486771443,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":120,"time":1783486771965,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":121,"time":1783486771965,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":122,"time":1783486772052,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}} +{"type":"assistant/chunk","seq":123,"time":1783486772113,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" succeeded"}}} +{"type":"assistant/chunk","seq":124,"time":1783486772113,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":125,"time":1783486772113,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}} +{"type":"assistant/chunk","seq":126,"time":1783486772114,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":127,"time":1783486772115,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}} +{"type":"assistant/chunk","seq":128,"time":1783486772115,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":129,"time":1783486772141,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":130,"time":1783486772142,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":131,"time":1783486772142,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":132,"time":1783486772185,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":133,"time":1783486772186,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} +{"type":"assistant/chunk","seq":134,"time":1783486772186,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} +{"type":"assistant/chunk","seq":135,"time":1783486772186,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" D"}}} +{"type":"assistant/chunk","seq":136,"time":1783486772204,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":137,"time":1783486772205,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":138,"time":1783486772205,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":139,"time":1783486772205,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}} +{"type":"assistant/chunk","seq":140,"time":1783486772205,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":141,"time":1783486772228,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The command succeeded. The user asked me to reply with the single word DONE."}}}} +{"type":"assistant/chunk","seq":142,"time":1783486772229,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","seq":143,"time":1783486772229,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":23,"outputTokens":20,"cacheReadTokens":1408,"reasoningTokens":17}}}} +{"type":"assistant/chunk","seq":144,"time":1783486772229,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":145,"time":1783486772230,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The command succeeded. The user asked me to reply with the single word DONE."},{"type":"text","text":"DONE"}],"usage":{"inputTokens":23,"outputTokens":20,"cacheReadTokens":1408,"reasoningTokens":17}},"sourceEventSeqs":[120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144],"surfaceOp":"append"} +{"type":"step/end","seq":146,"time":1783486772230,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":147,"time":1783486772230,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/stdout.golden.jsonl b/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/stdout.golden.jsonl new file mode 100644 index 0000000000..88fe79c0ce --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/escalation-approved/stdout.golden.jsonl @@ -0,0 +1,59 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"read-only","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"ask","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ret"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ry"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sand"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"box"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_per"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"missions"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" set"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" workspace"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"-w"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"rite"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" They"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" explicitly"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" said"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" they"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" will"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" approve"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" permission"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" prompt"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" proceed"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_ZSEIrZNdgQhL2QJgVHww8689","title":"printf 'escalated\\n' > escalated.txt && cat escalated.txt","kind":"execute","status":"in_progress","rawInput":"printf 'escalated\\n' > escalated.txt && cat escalated.txt","content":[{"type":"content","content":{"type":"text","text":"Write escalated.txt and cat its content"}}]}}} +{"jsonrpc":"2.0","id":1,"method":"session/request_permission","params":{"sessionId":"{{sessionId}}","toolCall":{"toolCallId":"call_00_ZSEIrZNdgQhL2QJgVHww8689"},"options":[{"optionId":"allow-once","name":"Allow once","kind":"allow_once"},{"optionId":"reject-once","name":"Reject","kind":"reject_once"}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_ZSEIrZNdgQhL2QJgVHww8689","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\nescalated\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" succeeded"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" asked"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/input.json b/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/input.json new file mode 100644 index 0000000000..d645402478 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/input.json @@ -0,0 +1,10 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "The sandbox already denied writing escalated.txt in this workspace earlier. Retry it now exactly once: one single bash call with the command printf 'escalated\\n' > escalated.txt && cat escalated.txt, with sandbox_permissions set to workspace-write and the justification 'the user asked to write escalated.txt in the workspace'. Do not run it without sandbox_permissions first. I will reject the permission prompt; after the rejection, do not retry and do not work around it — explain in one short sentence that the escalation was rejected, then stop." } + ], + "permissionAnswers": [ + { "kind": "reject_once" } + ] +} diff --git a/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/session.jsonl b/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/session.jsonl new file mode 100644 index 0000000000..cef751596e --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/session.jsonl @@ -0,0 +1,202 @@ +{"type":"session","version":0,"id":"46ee90bb-006b-477c-9c56-04dd4923aeb6","createdAt":1783486772550,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-OivXMN"} +{"type":"turn/start","seq":0,"time":1783486772551,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783486772551,"data":{"content":[{"type":"text","text":"The sandbox already denied writing escalated.txt in this workspace earlier. Retry it now exactly once: one single bash call with the command printf 'escalated\\n' > escalated.txt && cat escalated.txt, with sandbox_permissions set to workspace-write and the justification 'the user asked to write escalated.txt in the workspace'. Do not run it without sandbox_permissions first. I will reject the permission prompt; after the rejection, do not retry and do not work around it — explain in one short sentence that the escalation was rejected, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783486772552,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783486772552,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783486773136,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783486773136,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783486773275,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783486773326,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783486773328,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783486773328,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783486773328,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ret"}}} +{"type":"assistant/chunk","seq":11,"time":1783486773347,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ry"}}} +{"type":"assistant/chunk","seq":12,"time":1783486773348,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":13,"time":1783486773349,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exact"}}} +{"type":"assistant/chunk","seq":14,"time":1783486773381,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}} +{"type":"assistant/chunk","seq":15,"time":1783486773382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":16,"time":1783486773412,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"printf"}}} +{"type":"assistant/chunk","seq":17,"time":1783486773413,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" '"}}} +{"type":"assistant/chunk","seq":18,"time":1783486773413,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"es"}}} +{"type":"assistant/chunk","seq":19,"time":1783486773413,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"cal"}}} +{"type":"assistant/chunk","seq":20,"time":1783486773414,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ated"}}} +{"type":"assistant/chunk","seq":21,"time":1783486773414,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\\n"}}} +{"type":"assistant/chunk","seq":22,"time":1783486773445,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"'"}}} +{"type":"assistant/chunk","seq":23,"time":1783486773446,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" >"}}} +{"type":"assistant/chunk","seq":24,"time":1783486773446,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" escalated"}}} +{"type":"assistant/chunk","seq":25,"time":1783486773446,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".txt"}}} +{"type":"assistant/chunk","seq":26,"time":1783486773446,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" &&"}}} +{"type":"assistant/chunk","seq":27,"time":1783486773447,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" cat"}}} +{"type":"assistant/chunk","seq":28,"time":1783486773473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" escalated"}}} +{"type":"assistant/chunk","seq":29,"time":1783486773473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".txt"}}} +{"type":"assistant/chunk","seq":30,"time":1783486773473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":31,"time":1783486773473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":32,"time":1783486773474,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":33,"time":1783486773500,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"sand"}}} +{"type":"assistant/chunk","seq":34,"time":1783486773501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"box"}}} +{"type":"assistant/chunk","seq":35,"time":1783486773501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_per"}}} +{"type":"assistant/chunk","seq":36,"time":1783486773501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"missions"}}} +{"type":"assistant/chunk","seq":37,"time":1783486773501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":38,"time":1783486773542,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" set"}}} +{"type":"assistant/chunk","seq":39,"time":1783486773543,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":40,"time":1783486773543,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":41,"time":1783486773543,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"works"}}} +{"type":"assistant/chunk","seq":42,"time":1783486773543,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"pace"}}} +{"type":"assistant/chunk","seq":43,"time":1783486773543,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"-w"}}} +{"type":"assistant/chunk","seq":44,"time":1783486773568,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"rite"}}} +{"type":"assistant/chunk","seq":45,"time":1783486773569,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":46,"time":1783486773569,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":47,"time":1783486773569,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":48,"time":1783486773597,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" justification"}}} +{"type":"assistant/chunk","seq":49,"time":1783486773632,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" they"}}} +{"type":"assistant/chunk","seq":50,"time":1783486773667,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" specified"}}} +{"type":"assistant/chunk","seq":51,"time":1783486773668,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":52,"time":1783486773669,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" They"}}} +{"type":"assistant/chunk","seq":53,"time":1783486773685,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" explicitly"}}} +{"type":"assistant/chunk","seq":54,"time":1783486773716,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" say"}}} +{"type":"assistant/chunk","seq":55,"time":1783486773731,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" they"}}} +{"type":"assistant/chunk","seq":56,"time":1783486773732,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" will"}}} +{"type":"assistant/chunk","seq":57,"time":1783486773732,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reject"}}} +{"type":"assistant/chunk","seq":58,"time":1783486773746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":59,"time":1783486773746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" permission"}}} +{"type":"assistant/chunk","seq":60,"time":1783486773747,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" prompt"}}} +{"type":"assistant/chunk","seq":61,"time":1783486773773,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}} +{"type":"assistant/chunk","seq":62,"time":1783486773773,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" so"}}} +{"type":"assistant/chunk","seq":63,"time":1783486773774,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" after"}}} +{"type":"assistant/chunk","seq":64,"time":1783486773774,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" rejection"}}} +{"type":"assistant/chunk","seq":65,"time":1783486773806,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":66,"time":1783486773807,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" should"}}} +{"type":"assistant/chunk","seq":67,"time":1783486773833,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" explain"}}} +{"type":"assistant/chunk","seq":68,"time":1783486773834,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" in"}}} +{"type":"assistant/chunk","seq":69,"time":1783486773861,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" one"}}} +{"type":"assistant/chunk","seq":70,"time":1783486773862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" short"}}} +{"type":"assistant/chunk","seq":71,"time":1783486773862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sentence"}}} +{"type":"assistant/chunk","seq":72,"time":1783486773862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":73,"time":1783486773862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} +{"type":"assistant/chunk","seq":74,"time":1783486773900,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":75,"time":1783486773978,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":76,"time":1783486773979,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":77,"time":1783486774009,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":78,"time":1783486774011,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":79,"time":1783486774012,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"command"}}} +{"type":"assistant/chunk","seq":80,"time":1783486774012,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":81,"time":1783486774012,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":82,"time":1783486774049,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":83,"time":1783486774050,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"printf"}}} +{"type":"assistant/chunk","seq":84,"time":1783486774051,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" '"}}} +{"type":"assistant/chunk","seq":85,"time":1783486774051,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"es"}}} +{"type":"assistant/chunk","seq":86,"time":1783486774068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"cal"}}} +{"type":"assistant/chunk","seq":87,"time":1783486774068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"ated"}}} +{"type":"assistant/chunk","seq":88,"time":1783486774069,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\\\\n"}}} +{"type":"assistant/chunk","seq":89,"time":1783486774069,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"'"}}} +{"type":"assistant/chunk","seq":90,"time":1783486774069,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" >"}}} +{"type":"assistant/chunk","seq":91,"time":1783486774069,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":92,"time":1783486774107,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":93,"time":1783486774108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" &&"}}} +{"type":"assistant/chunk","seq":94,"time":1783486774108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" cat"}}} +{"type":"assistant/chunk","seq":95,"time":1783486774108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":96,"time":1783486774108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":97,"time":1783486774138,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":98,"time":1783486774162,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":99,"time":1783486774162,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":100,"time":1783486774162,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"description"}}} +{"type":"assistant/chunk","seq":101,"time":1783486774162,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":102,"time":1783486774163,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":103,"time":1783486774194,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":104,"time":1783486774194,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"Write"}}} +{"type":"assistant/chunk","seq":105,"time":1783486774194,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":106,"time":1783486774194,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":107,"time":1783486774194,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" with"}}} +{"type":"assistant/chunk","seq":108,"time":1783486774221,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" workspace"}}} +{"type":"assistant/chunk","seq":109,"time":1783486774221,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"-w"}}} +{"type":"assistant/chunk","seq":110,"time":1783486774283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"rite"}}} +{"type":"assistant/chunk","seq":111,"time":1783486774283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" permission"}}} +{"type":"assistant/chunk","seq":112,"time":1783486774283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":113,"time":1783486774283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":114,"time":1783486774283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":115,"time":1783486774283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"sand"}}} +{"type":"assistant/chunk","seq":116,"time":1783486774303,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"box"}}} +{"type":"assistant/chunk","seq":117,"time":1783486774303,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"_per"}}} +{"type":"assistant/chunk","seq":118,"time":1783486774303,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"missions"}}} +{"type":"assistant/chunk","seq":119,"time":1783486774304,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":120,"time":1783486774304,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":121,"time":1783486774339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":122,"time":1783486774339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"works"}}} +{"type":"assistant/chunk","seq":123,"time":1783486774339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"pace"}}} +{"type":"assistant/chunk","seq":124,"time":1783486774339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"-w"}}} +{"type":"assistant/chunk","seq":125,"time":1783486774339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"rite"}}} +{"type":"assistant/chunk","seq":126,"time":1783486774368,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":127,"time":1783486774392,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":128,"time":1783486774395,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":129,"time":1783486774395,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"just"}}} +{"type":"assistant/chunk","seq":130,"time":1783486774395,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"ification"}}} +{"type":"assistant/chunk","seq":131,"time":1783486774395,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":132,"time":1783486774440,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":133,"time":1783486774441,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":134,"time":1783486774441,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"the"}}} +{"type":"assistant/chunk","seq":135,"time":1783486774441,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" user"}}} +{"type":"assistant/chunk","seq":136,"time":1783486774469,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" asked"}}} +{"type":"assistant/chunk","seq":137,"time":1783486774469,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" to"}}} +{"type":"assistant/chunk","seq":138,"time":1783486774469,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" write"}}} +{"type":"assistant/chunk","seq":139,"time":1783486774469,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" escalated"}}} +{"type":"assistant/chunk","seq":140,"time":1783486774469,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":141,"time":1783486774470,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" in"}}} +{"type":"assistant/chunk","seq":142,"time":1783486774480,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" the"}}} +{"type":"assistant/chunk","seq":143,"time":1783486774480,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":" workspace"}}} +{"type":"assistant/chunk","seq":144,"time":1783486774481,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":145,"time":1783486774510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":146,"time":1783486774568,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to retry the exact command `printf 'escalated\\n' > escalated.txt && cat escalated.txt` with `sandbox_permissions` set to `workspace-write` and the justification they specified. They explicitly say they will reject the permission prompt, so after rejection I should explain in one short sentence and stop."}}}} +{"type":"assistant/chunk","seq":147,"time":1783486774569,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > escalated.txt && cat escalated.txt\", \"description\": \"Write escalated.txt with workspace-write permission\", \"sandbox_permissions\": \"workspace-write\", \"justification\": \"the user asked to write escalated.txt in the workspace\"}"}}}} +{"type":"assistant/chunk","seq":148,"time":1783486774569,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1269,"outputTokens":197,"cacheReadTokens":0,"reasoningTokens":70}}}} +{"type":"assistant/chunk","seq":149,"time":1783486774569,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":150,"time":1783486774572,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to retry the exact command `printf 'escalated\\n' > escalated.txt && cat escalated.txt` with `sandbox_permissions` set to `workspace-write` and the justification they specified. They explicitly say they will reject the permission prompt, so after rejection I should explain in one short sentence and stop."},{"type":"tool-call","id":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > escalated.txt && cat escalated.txt\", \"description\": \"Write escalated.txt with workspace-write permission\", \"sandbox_permissions\": \"workspace-write\", \"justification\": \"the user asked to write escalated.txt in the workspace\"}"}],"usage":{"inputTokens":1269,"outputTokens":197,"cacheReadTokens":0,"reasoningTokens":70}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149],"surfaceOp":"append"} +{"type":"tool/call","seq":151,"time":1783486774572,"data":{"turn":1,"step":1,"callId":"call_00_ODln9LCQtuvTw4FDZEfe3479","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > escalated.txt && cat escalated.txt\", \"description\": \"Write escalated.txt with workspace-write permission\", \"sandbox_permissions\": \"workspace-write\", \"justification\": \"the user asked to write escalated.txt in the workspace\"}"}} +{"type":"approval/asked","seq":152,"time":1783486774574,"data":{"id":"774d5e97-a3af-4fc9-ae83-25dc2617909b","toolName":"bash","callId":"call_00_ODln9LCQtuvTw4FDZEfe3479","reason":"escalate sandbox to workspace-write: the user asked to write escalated.txt in the workspace"}} +{"type":"approval/decided","seq":153,"time":1783486774578,"data":{"id":"774d5e97-a3af-4fc9-ae83-25dc2617909b","outcome":"rejected"}} +{"type":"tool/result","seq":154,"time":1783486774579,"data":{"turn":1,"step":1,"callId":"call_00_ODln9LCQtuvTw4FDZEfe3479","content":[{"type":"text","text":"Error: the user rejected escalating this command to \"workspace-write\""}],"isError":true},"sourceEventSeqs":[151],"surfaceOp":"append"} +{"type":"step/end","seq":155,"time":1783486774579,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":156,"time":1783486774580,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":157,"time":1783486775719,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":158,"time":1783486775719,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":159,"time":1783486775820,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":160,"time":1783486775856,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" rejected"}}} +{"type":"assistant/chunk","seq":161,"time":1783486775857,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":162,"time":1783486775857,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" escalation"}}} +{"type":"assistant/chunk","seq":163,"time":1783486775857,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":164,"time":1783486775879,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":165,"time":1783486775879,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} +{"type":"assistant/chunk","seq":166,"time":1783486775921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":167,"time":1783486775922,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" explain"}}} +{"type":"assistant/chunk","seq":168,"time":1783486775922,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" in"}}} +{"type":"assistant/chunk","seq":169,"time":1783486775934,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" one"}}} +{"type":"assistant/chunk","seq":170,"time":1783486775934,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" short"}}} +{"type":"assistant/chunk","seq":171,"time":1783486775935,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" sentence"}}} +{"type":"assistant/chunk","seq":172,"time":1783486775935,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":173,"time":1783486775935,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} +{"type":"assistant/chunk","seq":174,"time":1783486775935,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":175,"time":1783486775977,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":176,"time":1783486775978,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"The"}}} +{"type":"assistant/chunk","seq":177,"time":1783486775978,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" escalation"}}} +{"type":"assistant/chunk","seq":178,"time":1783486775978,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" request"}}} +{"type":"assistant/chunk","seq":179,"time":1783486776011,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" to"}}} +{"type":"assistant/chunk","seq":180,"time":1783486776026,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" write"}}} +{"type":"assistant/chunk","seq":181,"time":1783486776027,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" to"}}} +{"type":"assistant/chunk","seq":182,"time":1783486776027,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" the"}}} +{"type":"assistant/chunk","seq":183,"time":1783486776057,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" workspace"}}} +{"type":"assistant/chunk","seq":184,"time":1783486776057,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" was"}}} +{"type":"assistant/chunk","seq":185,"time":1783486776057,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" rejected"}}} +{"type":"assistant/chunk","seq":186,"time":1783486776058,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":","}}} +{"type":"assistant/chunk","seq":187,"time":1783486776128,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" so"}}} +{"type":"assistant/chunk","seq":188,"time":1783486776128,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" the"}}} +{"type":"assistant/chunk","seq":189,"time":1783486776129,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" command"}}} +{"type":"assistant/chunk","seq":190,"time":1783486776129,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" was"}}} +{"type":"assistant/chunk","seq":191,"time":1783486776145,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" not"}}} +{"type":"assistant/chunk","seq":192,"time":1783486776146,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" executed"}}} +{"type":"assistant/chunk","seq":193,"time":1783486776184,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"."}}} +{"type":"assistant/chunk","seq":194,"time":1783486776185,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user rejected the escalation. I need to explain in one short sentence and stop."}}}} +{"type":"assistant/chunk","seq":195,"time":1783486776185,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"The escalation request to write to the workspace was rejected, so the command was not executed."}}}} +{"type":"assistant/chunk","seq":196,"time":1783486776185,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":341,"outputTokens":36,"cacheReadTokens":1152,"reasoningTokens":17}}}} +{"type":"assistant/chunk","seq":197,"time":1783486776185,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":198,"time":1783486776186,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The user rejected the escalation. I need to explain in one short sentence and stop."},{"type":"text","text":"The escalation request to write to the workspace was rejected, so the command was not executed."}],"usage":{"inputTokens":341,"outputTokens":36,"cacheReadTokens":1152,"reasoningTokens":17}},"sourceEventSeqs":[157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197],"surfaceOp":"append"} +{"type":"step/end","seq":199,"time":1783486776186,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":200,"time":1783486776186,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/stdout.golden.jsonl b/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/stdout.golden.jsonl new file mode 100644 index 0000000000..f8b292e4c3 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/stdout.golden.jsonl @@ -0,0 +1,111 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"read-only","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"ask","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ret"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ry"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exact"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"printf"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" '"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"es"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"cal"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ated"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" >"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" escalated"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".txt"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" &&"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" escalated"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".txt"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"sand"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"box"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_per"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"missions"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" set"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"works"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"pace"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"-w"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"rite"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" justification"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" they"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" specified"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" They"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" explicitly"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" say"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" they"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" will"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reject"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" permission"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" prompt"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" so"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" after"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" rejection"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" should"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" explain"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" in"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" one"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" short"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sentence"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_ODln9LCQtuvTw4FDZEfe3479","title":"printf 'escalated\\n' > escalated.txt && cat escalated.txt","kind":"execute","status":"in_progress","rawInput":"printf 'escalated\\n' > escalated.txt && cat escalated.txt","content":[{"type":"content","content":{"type":"text","text":"Write escalated.txt with workspace-write permission"}}]}}} +{"jsonrpc":"2.0","id":1,"method":"session/request_permission","params":{"sessionId":"{{sessionId}}","toolCall":{"toolCallId":"call_00_ODln9LCQtuvTw4FDZEfe3479"},"options":[{"optionId":"allow-once","name":"Allow once","kind":"allow_once"},{"optionId":"reject-once","name":"Reject","kind":"reject_once"}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_ODln9LCQtuvTw4FDZEfe3479","status":"failed","content":[{"type":"content","content":{"type":"text","text":"```console\nError: the user rejected escalating this command to \"workspace-write\"\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" rejected"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" escalation"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" explain"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" in"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" one"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" short"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sentence"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" escalation"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" request"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" write"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" workspace"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" was"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" rejected"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" so"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" command"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" was"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" not"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" executed"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/sandbox-acp-agent/tests/snapshots/mode-switching/input.json b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/input.json new file mode 100644 index 0000000000..e11cec253e --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/input.json @@ -0,0 +1,11 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Use the bash tool to run exactly: cat notes.txt. Then reply with the single word DONE and stop." }, + { "op": "setConfigOption", "configId": "sandbox-mode", "value": "workspace-write" }, + { "op": "prompt", "text": "Use the bash tool to run exactly this one command in a single call: printf 'switched\\n' > out.txt && cat out.txt. Then reply with the single word DONE and stop." }, + { "op": "setConfigOption", "configId": "approval-policy", "value": "never" }, + { "op": "prompt", "text": "Without using any tools, state your current approval policy in one short sentence and stop." } + ] +} diff --git a/examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl new file mode 100644 index 0000000000..bf173f1b67 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl @@ -0,0 +1,245 @@ +{"type":"session","version":0,"id":"eee406bd-e76b-4d87-8fb7-0ffa2dc94fe6","createdAt":1783613224994,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-mNdf7I"} +{"type":"turn/start","seq":0,"time":1783613224997,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783613224997,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: cat notes.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783613224997,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783613224997,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-mNdf7I. Your bash tool runs under a file sandbox — a\n`[sandbox: file access denied …]` result is policy, not a command bug.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, `$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command IS denied and a wider mode would let it succeed, escalate immediately in the SAME turn — the ONE sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry IS how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one THIS command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for THAT command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."},"sandbox_permissions":{"type":"string","description":"The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.","enum":["workspace-write","danger-full-access"]},"justification":{"type":"string","description":"Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783613225437,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783613225438,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783613225658,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783613225687,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783613225687,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783613225687,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783613225687,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":11,"time":1783613225688,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":12,"time":1783613225717,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"cat"}}} +{"type":"assistant/chunk","seq":13,"time":1783613225718,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" notes"}}} +{"type":"assistant/chunk","seq":14,"time":1783613225718,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".txt"}}} +{"type":"assistant/chunk","seq":15,"time":1783613225718,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":16,"time":1783613225718,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" using"}}} +{"type":"assistant/chunk","seq":17,"time":1783613225746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":18,"time":1783613225747,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} +{"type":"assistant/chunk","seq":19,"time":1783613225747,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} +{"type":"assistant/chunk","seq":20,"time":1783613225747,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":21,"time":1783613225832,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":22,"time":1783613225832,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":23,"time":1783613225859,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":24,"time":1783613225860,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":25,"time":1783613225860,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"command"}}} +{"type":"assistant/chunk","seq":26,"time":1783613225860,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":27,"time":1783613225860,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":28,"time":1783613225888,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":29,"time":1783613225888,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"cat"}}} +{"type":"assistant/chunk","seq":30,"time":1783613225889,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":" notes"}}} +{"type":"assistant/chunk","seq":31,"time":1783613225889,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":32,"time":1783613225889,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":33,"time":1783613225945,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":34,"time":1783613225945,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":35,"time":1783613225945,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"description"}}} +{"type":"assistant/chunk","seq":36,"time":1783613225945,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":37,"time":1783613225946,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":38,"time":1783613225979,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":39,"time":1783613225979,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"Show"}}} +{"type":"assistant/chunk","seq":40,"time":1783613225979,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":" contents"}}} +{"type":"assistant/chunk","seq":41,"time":1783613225979,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":" of"}}} +{"type":"assistant/chunk","seq":42,"time":1783613225980,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":" notes"}}} +{"type":"assistant/chunk","seq":43,"time":1783613226003,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":44,"time":1783613226004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":45,"time":1783613226031,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":46,"time":1783613226061,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to run `cat notes.txt` using the bash tool."}}}} +{"type":"assistant/chunk","seq":47,"time":1783613226061,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","arguments":"{\"command\": \"cat notes.txt\", \"description\": \"Show contents of notes.txt\"}"}}}} +{"type":"assistant/chunk","seq":48,"time":1783613226061,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1202,"outputTokens":81,"cacheReadTokens":0,"reasoningTokens":16}}}} +{"type":"assistant/chunk","seq":49,"time":1783613226061,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":50,"time":1783613226064,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run `cat notes.txt` using the bash tool."},{"type":"tool-call","id":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","arguments":"{\"command\": \"cat notes.txt\", \"description\": \"Show contents of notes.txt\"}"}],"usage":{"inputTokens":1202,"outputTokens":81,"cacheReadTokens":0,"reasoningTokens":16}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49],"surfaceOp":"append"} +{"type":"tool/call","seq":51,"time":1783613226064,"data":{"turn":1,"step":1,"callId":"call_00_I9sT0gKlfz9YP4dlf2pA3899","name":"bash","arguments":"{\"command\": \"cat notes.txt\", \"description\": \"Show contents of notes.txt\"}"}} +{"type":"tool/result","seq":52,"time":1783613226148,"data":{"turn":1,"step":1,"callId":"call_00_I9sT0gKlfz9YP4dlf2pA3899","content":[{"type":"text","text":"hello from the sandboxed workspace\n"}],"isError":false},"sourceEventSeqs":[51],"surfaceOp":"append"} +{"type":"step/end","seq":53,"time":1783613226148,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":54,"time":1783613226148,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":55,"time":1783613226790,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":56,"time":1783613226791,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":57,"time":1783613226970,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}} +{"type":"assistant/chunk","seq":58,"time":1783613227003,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" ran"}}} +{"type":"assistant/chunk","seq":59,"time":1783613227025,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}} +{"type":"assistant/chunk","seq":60,"time":1783613227025,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":61,"time":1783613227025,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}} +{"type":"assistant/chunk","seq":62,"time":1783613227025,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":63,"time":1783613227052,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}} +{"type":"assistant/chunk","seq":64,"time":1783613227053,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":65,"time":1783613227053,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":66,"time":1783613227053,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":67,"time":1783613227053,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":68,"time":1783613227053,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":69,"time":1783613227082,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} +{"type":"assistant/chunk","seq":70,"time":1783613227082,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} +{"type":"assistant/chunk","seq":71,"time":1783613227083,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" D"}}} +{"type":"assistant/chunk","seq":72,"time":1783613227110,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":73,"time":1783613227110,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":74,"time":1783613227140,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":75,"time":1783613227140,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}} +{"type":"assistant/chunk","seq":76,"time":1783613227141,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":77,"time":1783613227141,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The command ran successfully. The user asked me to reply with the single word DONE."}}}} +{"type":"assistant/chunk","seq":78,"time":1783613227141,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","seq":79,"time":1783613227141,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":23,"outputTokens":21,"cacheReadTokens":1280,"reasoningTokens":18}}}} +{"type":"assistant/chunk","seq":80,"time":1783613227141,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":81,"time":1783613227142,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The command ran successfully. The user asked me to reply with the single word DONE."},{"type":"text","text":"DONE"}],"usage":{"inputTokens":23,"outputTokens":21,"cacheReadTokens":1280,"reasoningTokens":18}},"sourceEventSeqs":[55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80],"surfaceOp":"append"} +{"type":"step/end","seq":82,"time":1783613227142,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":83,"time":1783613227142,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"turn/start","seq":84,"time":1783613227169,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"bash/sandbox-mode","seq":85,"time":1783613227169,"data":{"mode":"workspace-write"}} +{"type":"user/message","seq":86,"time":1783613227169,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly this one command in a single call: printf 'switched\\n' > out.txt && cat out.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":87,"time":1783613227169,"data":{"turn":2,"step":1}} +{"type":"assistant/chunk","seq":88,"time":1783613227737,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":89,"time":1783613227738,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":90,"time":1783613227839,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":91,"time":1783613227858,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":92,"time":1783613227859,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":93,"time":1783613227859,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":94,"time":1783613227859,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":95,"time":1783613227859,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":96,"time":1783613227859,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" specific"}}} +{"type":"assistant/chunk","seq":97,"time":1783613227888,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}} +{"type":"assistant/chunk","seq":98,"time":1783613227888,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":99,"time":1783613227888,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":100,"time":1783613227916,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":101,"time":1783613227916,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" execute"}}} +{"type":"assistant/chunk","seq":102,"time":1783613227917,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}} +{"type":"assistant/chunk","seq":103,"time":1783613227917,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":104,"time":1783613228006,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":105,"time":1783613228006,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":106,"time":1783613228034,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":107,"time":1783613228035,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":108,"time":1783613228035,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"description"}}} +{"type":"assistant/chunk","seq":109,"time":1783613228035,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":110,"time":1783613228035,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":111,"time":1783613228063,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":112,"time":1783613228063,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"Write"}}} +{"type":"assistant/chunk","seq":113,"time":1783613228063,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" and"}}} +{"type":"assistant/chunk","seq":114,"time":1783613228100,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" read"}}} +{"type":"assistant/chunk","seq":115,"time":1783613228100,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":116,"time":1783613228100,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":117,"time":1783613228121,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":118,"time":1783613228150,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":119,"time":1783613228150,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":120,"time":1783613228151,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"command"}}} +{"type":"assistant/chunk","seq":121,"time":1783613228151,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":122,"time":1783613228151,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":123,"time":1783613228179,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":124,"time":1783613228179,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"printf"}}} +{"type":"assistant/chunk","seq":125,"time":1783613228179,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" '"}}} +{"type":"assistant/chunk","seq":126,"time":1783613228179,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"sw"}}} +{"type":"assistant/chunk","seq":127,"time":1783613228209,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"itched"}}} +{"type":"assistant/chunk","seq":128,"time":1783613228209,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\\\\n"}}} +{"type":"assistant/chunk","seq":129,"time":1783613228209,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"'"}}} +{"type":"assistant/chunk","seq":130,"time":1783613228209,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" >"}}} +{"type":"assistant/chunk","seq":131,"time":1783613228209,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":132,"time":1783613228209,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":133,"time":1783613228237,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" &&"}}} +{"type":"assistant/chunk","seq":134,"time":1783613228237,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" cat"}}} +{"type":"assistant/chunk","seq":135,"time":1783613228237,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":136,"time":1783613228237,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":".txt"}}} +{"type":"assistant/chunk","seq":137,"time":1783613228237,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":138,"time":1783613228265,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":139,"time":1783613228325,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to run a specific command. Let me execute it."}}}} +{"type":"assistant/chunk","seq":140,"time":1783613228325,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","arguments":"{\"description\": \"Write and read out.txt\", \"command\": \"printf 'switched\\\\n' > out.txt && cat out.txt\"}"}}}} +{"type":"assistant/chunk","seq":141,"time":1783613228325,"data":{"turn":2,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":70,"outputTokens":90,"cacheReadTokens":1280,"reasoningTokens":15}}}} +{"type":"assistant/chunk","seq":142,"time":1783613228325,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":143,"time":1783613228325,"data":{"turn":2,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a specific command. Let me execute it."},{"type":"tool-call","id":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","arguments":"{\"description\": \"Write and read out.txt\", \"command\": \"printf 'switched\\\\n' > out.txt && cat out.txt\"}"}],"usage":{"inputTokens":70,"outputTokens":90,"cacheReadTokens":1280,"reasoningTokens":15}},"sourceEventSeqs":[88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142],"surfaceOp":"append"} +{"type":"tool/call","seq":144,"time":1783613228325,"data":{"turn":2,"step":1,"callId":"call_00_htXcbtvwTFK0NqfclLWL7784","name":"bash","arguments":"{\"description\": \"Write and read out.txt\", \"command\": \"printf 'switched\\\\n' > out.txt && cat out.txt\"}"}} +{"type":"tool/result","seq":145,"time":1783613228412,"data":{"turn":2,"step":1,"callId":"call_00_htXcbtvwTFK0NqfclLWL7784","content":[{"type":"text","text":"switched\n"}],"isError":false},"sourceEventSeqs":[144],"surfaceOp":"append"} +{"type":"step/end","seq":146,"time":1783613228412,"data":{"turn":2,"step":1}} +{"type":"step/start","seq":147,"time":1783613228412,"data":{"turn":2,"step":2}} +{"type":"assistant/chunk","seq":148,"time":1783613228863,"data":{"turn":2,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":149,"time":1783613228864,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"Command"}}} +{"type":"assistant/chunk","seq":150,"time":1783613228966,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" executed"}}} +{"type":"assistant/chunk","seq":151,"time":1783613228994,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}} +{"type":"assistant/chunk","seq":152,"time":1783613228994,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":153,"time":1783613228994,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}} +{"type":"assistant/chunk","seq":154,"time":1783613228995,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":155,"time":1783613228995,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":156,"time":1783613229020,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":157,"time":1783613229020,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"sw"}}} +{"type":"assistant/chunk","seq":158,"time":1783613229020,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"itched"}}} +{"type":"assistant/chunk","seq":159,"time":1783613229020,"data":{"turn":2,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":160,"time":1783613229020,"data":{"turn":2,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":161,"time":1783613229020,"data":{"turn":2,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}} +{"type":"assistant/chunk","seq":162,"time":1783613229048,"data":{"turn":2,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":163,"time":1783613229048,"data":{"turn":2,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Command executed successfully. The output is \"switched\"."}}}} +{"type":"assistant/chunk","seq":164,"time":1783613229048,"data":{"turn":2,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","seq":165,"time":1783613229048,"data":{"turn":2,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":47,"outputTokens":14,"cacheReadTokens":1408,"reasoningTokens":11}}}} +{"type":"assistant/chunk","seq":166,"time":1783613229048,"data":{"turn":2,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":167,"time":1783613229049,"data":{"turn":2,"step":2,"content":[{"type":"reasoning","text":"Command executed successfully. The output is \"switched\"."},{"type":"text","text":"DONE"}],"usage":{"inputTokens":47,"outputTokens":14,"cacheReadTokens":1408,"reasoningTokens":11}},"sourceEventSeqs":[148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166],"surfaceOp":"append"} +{"type":"step/end","seq":168,"time":1783613229049,"data":{"turn":2,"step":2}} +{"type":"turn/end","seq":169,"time":1783613229049,"data":{"turn":2,"reason":{"kind":"completed"}}} +{"type":"turn/start","seq":170,"time":1783613229056,"data":{"turn":3,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"approval/policy","seq":171,"time":1783613229056,"data":{"policy":"never"}} +{"type":"user/message","seq":172,"time":1783613229056,"data":{"content":[{"type":"text","text":"Without using any tools, state your current approval policy in one short sentence and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"context/message","seq":173,"time":1783613229057,"data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"}},"surfaceOp":"append"} +{"type":"step/start","seq":174,"time":1783613229057,"data":{"turn":3,"step":1}} +{"type":"request/header-delta","seq":175,"time":1783613229057,"data":{"system":{"keepStart":12,"keepEnd":0,"insert":["Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).",""]}}} +{"type":"assistant/chunk","seq":176,"time":1783613230100,"data":{"turn":3,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":177,"time":1783613230100,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":178,"time":1783613230192,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":179,"time":1783613230221,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":180,"time":1783613230249,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":181,"time":1783613230250,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":182,"time":1783613230250,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" state"}}} +{"type":"assistant/chunk","seq":183,"time":1783613230250,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" my"}}} +{"type":"assistant/chunk","seq":184,"time":1783613230250,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" current"}}} +{"type":"assistant/chunk","seq":185,"time":1783613230278,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" approval"}}} +{"type":"assistant/chunk","seq":186,"time":1783613230279,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" policy"}}} +{"type":"assistant/chunk","seq":187,"time":1783613230279,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" without"}}} +{"type":"assistant/chunk","seq":188,"time":1783613230279,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" using"}}} +{"type":"assistant/chunk","seq":189,"time":1783613230306,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" any"}}} +{"type":"assistant/chunk","seq":190,"time":1783613230307,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} +{"type":"assistant/chunk","seq":191,"time":1783613230307,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":192,"time":1783613230307,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" From"}}} +{"type":"assistant/chunk","seq":193,"time":1783613230335,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":194,"time":1783613230335,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" context"}}} +{"type":"assistant/chunk","seq":195,"time":1783613230335,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}} +{"type":"assistant/chunk","seq":196,"time":1783613230335,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":197,"time":1783613230363,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" approval"}}} +{"type":"assistant/chunk","seq":198,"time":1783613230363,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" policy"}}} +{"type":"assistant/chunk","seq":199,"time":1783613230364,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":200,"time":1783613230392,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":201,"time":1783613230393,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"never"}}} +{"type":"assistant/chunk","seq":202,"time":1783613230393,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":203,"time":1783613230393,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" —"}}} +{"type":"assistant/chunk","seq":204,"time":1783613230393,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" meaning"}}} +{"type":"assistant/chunk","seq":205,"time":1783613230423,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" actions"}}} +{"type":"assistant/chunk","seq":206,"time":1783613230450,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":207,"time":1783613230451,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" require"}}} +{"type":"assistant/chunk","seq":208,"time":1783613230451,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" approval"}}} +{"type":"assistant/chunk","seq":209,"time":1783613230451,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" are"}}} +{"type":"assistant/chunk","seq":210,"time":1783613230451,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" rejected"}}} +{"type":"assistant/chunk","seq":211,"time":1783613230478,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" automatically"}}} +{"type":"assistant/chunk","seq":212,"time":1783613230479,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}} +{"type":"assistant/chunk","seq":213,"time":1783613230479,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":214,"time":1783613230507,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":215,"time":1783613230507,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" should"}}} +{"type":"assistant/chunk","seq":216,"time":1783613230507,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" not"}}} +{"type":"assistant/chunk","seq":217,"time":1783613230508,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" request"}}} +{"type":"assistant/chunk","seq":218,"time":1783613230508,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sand"}}} +{"type":"assistant/chunk","seq":219,"time":1783613230536,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"box"}}} +{"type":"assistant/chunk","seq":220,"time":1783613230536,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" escalation"}}} +{"type":"assistant/chunk","seq":221,"time":1783613230536,"data":{"turn":3,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":222,"time":1783613230537,"data":{"turn":3,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":223,"time":1783613230537,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":"Appro"}}} +{"type":"assistant/chunk","seq":224,"time":1783613230564,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":"vals"}}} +{"type":"assistant/chunk","seq":225,"time":1783613230564,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" are"}}} +{"type":"assistant/chunk","seq":226,"time":1783613230564,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" never"}}} +{"type":"assistant/chunk","seq":227,"time":1783613230565,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" asked"}}} +{"type":"assistant/chunk","seq":228,"time":1783613230605,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":";"}}} +{"type":"assistant/chunk","seq":229,"time":1783613230606,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" any"}}} +{"type":"assistant/chunk","seq":230,"time":1783613230625,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" action"}}} +{"type":"assistant/chunk","seq":231,"time":1783613230626,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" requiring"}}} +{"type":"assistant/chunk","seq":232,"time":1783613230626,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" approval"}}} +{"type":"assistant/chunk","seq":233,"time":1783613230653,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" is"}}} +{"type":"assistant/chunk","seq":234,"time":1783613230654,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" automatically"}}} +{"type":"assistant/chunk","seq":235,"time":1783613230654,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":" rejected"}}} +{"type":"assistant/chunk","seq":236,"time":1783613230654,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":1,"text":"."}}} +{"type":"assistant/chunk","seq":237,"time":1783613230689,"data":{"turn":3,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to state my current approval policy without using any tools. From the context, the approval policy is \"never\" — meaning actions that require approval are rejected automatically, and I should not request sandbox escalation."}}}} +{"type":"assistant/chunk","seq":238,"time":1783613230689,"data":{"turn":3,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"Approvals are never asked; any action requiring approval is automatically rejected."}}}} +{"type":"assistant/chunk","seq":239,"time":1783613230689,"data":{"turn":3,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1530,"outputTokens":60,"cacheReadTokens":0,"reasoningTokens":45}}}} +{"type":"assistant/chunk","seq":240,"time":1783613230689,"data":{"turn":3,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":241,"time":1783613230690,"data":{"turn":3,"step":1,"content":[{"type":"reasoning","text":"The user wants me to state my current approval policy without using any tools. From the context, the approval policy is \"never\" — meaning actions that require approval are rejected automatically, and I should not request sandbox escalation."},{"type":"text","text":"Approvals are never asked; any action requiring approval is automatically rejected."}],"usage":{"inputTokens":1530,"outputTokens":60,"cacheReadTokens":0,"reasoningTokens":45}},"sourceEventSeqs":[176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240],"surfaceOp":"append"} +{"type":"step/end","seq":242,"time":1783613230690,"data":{"turn":3,"step":1}} +{"type":"turn/end","seq":243,"time":1783613230690,"data":{"turn":3,"reason":{"kind":"completed"}}} diff --git a/examples/sandbox-acp-agent/tests/snapshots/mode-switching/stdout.golden.jsonl b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/stdout.golden.jsonl new file mode 100644 index 0000000000..e6b16698af --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/stdout.golden.jsonl @@ -0,0 +1,134 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"read-only","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"ask","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" notes"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".txt"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" using"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_I9sT0gKlfz9YP4dlf2pA3899","title":"cat notes.txt","kind":"execute","status":"in_progress","rawInput":"cat notes.txt","content":[{"type":"content","content":{"type":"text","text":"Show contents of notes.txt"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_I9sT0gKlfz9YP4dlf2pA3899","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\nhello from the sandboxed workspace\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ran"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" successfully"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" asked"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} +{"jsonrpc":"2.0","id":4,"result":{"configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"ask","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" specific"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" execute"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_htXcbtvwTFK0NqfclLWL7784","title":"printf 'switched\\n' > out.txt && cat out.txt","kind":"execute","status":"in_progress","rawInput":"printf 'switched\\n' > out.txt && cat out.txt","content":[{"type":"content","content":{"type":"text","text":"Write and read out.txt"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_htXcbtvwTFK0NqfclLWL7784","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\nswitched\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Command"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" executed"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" successfully"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"sw"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"itched"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","id":5,"result":{"stopReason":"end_turn"}} +{"jsonrpc":"2.0","id":6,"result":{"configOptions":[{"id":"sandbox-mode","name":"Sandbox","description":"The file sandbox mode bash commands in this session run under.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"read-only","name":"read-only"},{"value":"workspace-write","name":"workspace-write"},{"value":"danger-full-access","name":"danger-full-access"}]},{"id":"approval-policy","name":"Approvals","description":"ask: permission prompts reach you; never: they are rejected automatically.","type":"select","currentValue":"never","options":[{"value":"ask","name":"ask"},{"value":"never","name":"never"}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" state"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" my"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" current"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" approval"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" policy"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" without"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" using"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" any"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" From"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" context"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" approval"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" policy"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"never"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" —"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" meaning"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" actions"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" require"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" approval"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" are"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" rejected"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" automatically"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" should"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" not"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" request"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sand"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"box"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" escalation"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Appro"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"vals"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" are"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" never"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" asked"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":";"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" any"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" action"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" requiring"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" approval"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" is"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" automatically"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":" rejected"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","id":7,"result":{"stopReason":"end_turn"}} diff --git a/examples/sandbox-acp-agent/tests/snapshots/mode-switching/workspace/notes.txt b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/workspace/notes.txt new file mode 100644 index 0000000000..a6eda7f939 --- /dev/null +++ b/examples/sandbox-acp-agent/tests/snapshots/mode-switching/workspace/notes.txt @@ -0,0 +1 @@ +hello from the sandboxed workspace diff --git a/knip.json b/knip.json index 1c5b0f6b6f..cf43b90e34 100644 --- a/knip.json +++ b/knip.json @@ -1,6 +1,7 @@ { "$schema": "https://unpkg.com/knip@5/schema.json", "exclude": ["duplicates"], + "ignoreBinaries": ["bwrap", "sandbox-exec"], "ignoreWorkspaces": ["vendor/*"], "workspaces": { ".": { @@ -18,6 +19,14 @@ "entry": ["tests/**/*.spec.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, + "packages/bash/bash-sandbox": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, + "packages/sandbox/sandbox-local": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, "packages/util/brand": { "project": ["src/**/*.ts"], "ignoreDependencies": ["cordis"] diff --git a/package.json b/package.json index c4cc307893..0fc57b7db5 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "test:e2e": "vitest run --config vitest.e2e.config.ts", "test:snapshot": "vitest run --config vitest.snapshot.config.ts", "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update", + "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts", "check:ci": "tsx scripts/run-gates.ts ci-primary", "check:ci:static": "tsx scripts/run-gates.ts ci-static", "check:ci:lint": "tsx scripts/run-gates.ts ci-lint", @@ -68,6 +69,7 @@ "demo:code-mode": "node scripts/demo-code-mode.mjs", "demo:cordis": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/cordis-agent/cordis.yml", "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml", + "demo:sandbox-acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/sandbox-acp-agent/cordis.yml", "postinstall": "node scripts/install-lefthook.mjs" }, "devDependencies": { diff --git a/packages/README.md b/packages/README.md index a656812253..35c4652a1f 100644 --- a/packages/README.md +++ b/packages/README.md @@ -1,10 +1,10 @@ # Packages -Harness packages, all under the `@deepseek-ai/dsh-*` scope. Each package is a Cordis plugin (microkernel-style): it exports either a default `Service` subclass or a functional plugin, declares its ctx key/events through declaration merging, and exposes extension points through `ctx.effect()`, `ctx.on()`, and `ctx.waterfall()`. Authoring conventions: [AGENTS.md](AGENTS.md) (subtree) and the root [AGENTS.md](../AGENTS.md) § Conventions. +Harness packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis plugin: a default `Service` subclass or functional plugin declaring ctx keys/events through declaration merging and contributing through `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring conventions: [AGENTS.md](AGENTS.md) and root [AGENTS.md](../AGENTS.md) § Conventions. ## Hierarchy -Packages are grouped by modular role at `packages///`. The group directory is a pure container (no `package.json` of its own); the package name stays `@deepseek-ai/dsh-` regardless of group. **Each group README is the canonical per-package map** — package roles, ctx keys, and the product-vs-support split live there, next to the code. +Packages are grouped by modular role at `packages///`. The group directory is a pure container (no `package.json`); the package name stays `@deepseek-ai/dsh-` regardless of group. **Each group README is the canonical per-package map** — package roles, ctx keys, and the product-vs-support split live there, next to the code. | Group | Role | Release expectation | |---|---|---| @@ -12,7 +12,9 @@ Packages are grouped by modular role at `packages///`. The group dir | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface | | [`bash/`](bash/README.md) | Bash capability family: the executor seam, a local impl, and the model-facing tool | Product — stable surface | | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface | +| [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface | | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface | +| [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface | | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface | | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface | | [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` tool | Product — stable surface | @@ -23,7 +25,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | -| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, app packages, user-interaction seam, ask-user tool | Product — stable surface | +| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, app packages, user-approval and user-interaction seams, ask-user tool | Product — stable surface | | [`support/`](support/README.md) | Dev/test/example infrastructure (invariants, replay adapter, subagent mock) | Support — lower compatibility expectations | | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded` primitive) | Support — small, stable, harness-dep-free | diff --git a/packages/bash/README.md b/packages/bash/README.md index 9a9dba88d5..4072998f3e 100644 --- a/packages/bash/README.md +++ b/packages/bash/README.md @@ -1,11 +1,12 @@ # bash/ — bash capability family -The canonical three-package capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract executor interface, a concrete local implementation, and the model-facing tool that consumes it. All **product** packages. +The canonical three-package capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract executor interface, concrete implementations, and the model-facing tool that consumes it. All **product** packages. | Package | Role | ctx key | |---|---|---| -| `bash/` | Abstract bash executor seam (interface + vocabulary) | `ctx.bash` | +| `bash/` | Abstract bash executor seam (interface + vocabulary; sandbox result facts carry the [`sandbox/`](../sandbox/README.md) seam's mode/enforcement vocabulary) | `ctx.bash` | | `bash-local/` | Local-subprocess `BashExecutor` implementation | (registers `ctx.bash`) | +| `bash-sandbox/` | Sandbox-consuming `BashExecutor` (wraps every command argv via `ctx.sandbox`, stamps denial/enforcement facts; extends `bash-local`'s mechanics) | (registers `ctx.bash`) | | `tool-bash/` | Model-facing `bash`/`bash_output`/`bash_kill` tool schemas | (registers on `ctx.tools`) | -The interface lives at `bash/bash/`. A sandboxed executor would replace `bash-local` without touching the interface or the tool — the split is what makes that possible. +The interface lives at `bash/bash/`. `bash-sandbox` replacing `bash-local` without touching the interface or the tool is the split doing exactly what it exists for — a leaf `cordis.yml` picks one executor entry, plus a `ctx.sandbox` provider entry for the confined one (see [examples/sandbox-acp-agent](../../examples/sandbox-acp-agent/)). diff --git a/packages/bash/bash-local/README.md b/packages/bash/bash-local/README.md index dec29ce93b..1ac8a7d06b 100644 --- a/packages/bash/bash-local/README.md +++ b/packages/bash/bash-local/README.md @@ -27,4 +27,4 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi; ## Sandboxing -`TODO(permissions/sandbox)`: execution policy does NOT belong in this package. Use the `tools/pre-execute` deny/ask gate or implement a sandboxing `BashExecutor` — see docs/architecture.md § Extending The Harness. Reference points: Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies seatbelt/landlock plus an execpolicy prefix-rule engine. +Execution policy does NOT belong in this package: this executor always runs commands unconfined. Confinement is [`dsh-bash-sandbox`](../bash-sandbox/README.md), which extends this executor verbatim and confines commands under the `ctx.sandbox` seam's bwrap/Landlock/Seatbelt backends ([sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)); per-call allow/deny/ask policy belongs on the `tools/pre-execute` gate. diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts index 3e09d7e35b..6903c06e32 100644 --- a/packages/bash/bash-local/src/index.ts +++ b/packages/bash/bash-local/src/index.ts @@ -133,6 +133,10 @@ export class LocalBashExecutor extends BashExecutor { // Carry the owner through verbatim (required-but-nullable on the spec): // the executor never interprets it — the consumer's access policy does. owner: request.owner, + // Carry a sandbox-mode override through verbatim: this executor never + // confines, so the field is inert here (the seam contract) — a + // sandboxing subclass overrides resolve() to stamp its default instead. + sandboxMode: request.sandboxMode, } } @@ -212,6 +216,18 @@ export class LocalBashExecutor extends BashExecutor { return this.tasks.get(id) } + /** + * Full collected stderr of a tracked task from stream start (bounded by the + * in-memory cap; bytes only in the spill file are not re-read). A protected + * seam for subclasses that classify a settled task's outcome — reading here + * does NOT advance the consumer's {@link readOutput} cursor. An unknown id + * (a task already dropped by disposal) reads as empty. + */ + protected collectedStderr(id: BashTaskId): string { + const task = this.tasks.get(id) + return task === undefined ? '' : task.running.stderr.readFrom(0).text + } + ownerOf(id: BashTaskId): OwnerToken | undefined { // Unknown id and known-but-ownerless both read as undefined — the consumer // treats undefined as "open" and a truly unknown id fails at readOutput/kill. diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md new file mode 100644 index 0000000000..2a5ae63b8e --- /dev/null +++ b/packages/bash/bash-sandbox/README.md @@ -0,0 +1,33 @@ +# @deepseek-ai/dsh-bash-sandbox + +Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) — the model-facing tool layer (`dsh-tool-bash`) is untouched; that swap is exactly what the seams exist for. + +Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned (wrapped) argv instead. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only. + +| Mode | File effects | +|---|---| +| `read-only` (default) | No writes anywhere (of `/dev`, only the `/dev/null` node is writable, so `>/dev/null` keeps working) | +| `workspace-write` | Writes only under `workspaceRoot` + `/tmp` (ephemeral under bwrap, the host `/tmp` under Landlock, `/private/tmp` plus the per-user temp dir under Seatbelt) | +| `danger-full-access` | No confinement; the provider is never consulted. Execution is `dsh-bash-local`'s verbatim — foreground results still carry `sandbox: { mode, denied: false }` (no `enforcement`: nothing was confined), background tasks carry no sandbox facts | + +Semantics: + +- **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI). +- **Runner failures are sandbox failures, never task failures.** A failed run matching the wrap's `runnerFailureSignatures` (the runner's own error prefix — also what the shell prints for a missing runner) means the sandbox itself broke and the command NEVER RAN; the check outranks denial classification because a runner's error text can contain denial words. The foreground path re-throws it as the structured fail-closed `SANDBOX_UNAVAILABLE` error, with the runner's first stderr line as the cause; a settled background task stamps `task.sandbox.runnerFailed` instead (no error channel remains after settle), which `bash_output` renders as its own marker. +- **Config-time default, per-call policy.** The DEFAULT mode is fixed by this entry's config for the executor's lifetime; `resolve()` stamps it onto every spec, and an explicit request-level `sandboxMode` override — set by the tool layer only for a call whose wider mode a human granted through `ctx.approval` ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)) — makes THAT call run, classify, and report under its own mode while every neighbor keeps the default (background facts are stamped per task at settle). The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted. The model learns of the sandbox only through result facts — the static bash tool description explains the denial marker; there is no current-mode statement in the system prompt. +- **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce. +- Process mechanics (spawn, process-group kills, output collection/spill, background tasks, credential scrub) are inherited verbatim from [`dsh-bash-local`](../bash-local/); the runner ladder, probes, and the per-platform Landlock launcher packages live with [`dsh-sandbox-local`](../../sandbox/sandbox-local/). + +Deny-only at the seam: a denial is a reported fact, and this executor never negotiates permissions itself — the approval question lives in the tool layer (`dsh-tool-bash`), which drives the override this package honors. + +```yaml +- id: sandbox + name: '@deepseek-ai/dsh-sandbox-local' +- id: bash + name: '@deepseek-ai/dsh-bash-sandbox' + config: + mode: read-only + workspaceRoot: !!js process.cwd() +``` + +The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, and `tests/seatbelt.e2e.ts` (the real provider + real runner driven through `ctx.bash`, world-verified, each self-skipping where its runner is absent); see [`examples/sandbox-acp-agent`](../../../examples/sandbox-acp-agent/) for the runnable demo. diff --git a/packages/bash/bash-sandbox/package.json b/packages/bash/bash-sandbox/package.json new file mode 100644 index 0000000000..0077511946 --- /dev/null +++ b/packages/bash/bash-sandbox/package.json @@ -0,0 +1,41 @@ +{ + "name": "@deepseek-ai/dsh-bash-sandbox", + "description": "Sandbox-consuming implementation of the DeepSeek Harness bash executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-bash": "^0.0.1", + "@deepseek-ai/dsh-bash-local": "^0.0.1", + "@deepseek-ai/dsh-sandbox": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-bash": "workspace:^", + "@deepseek-ai/dsh-bash-local": "workspace:^", + "@deepseek-ai/dsh-sandbox": "workspace:^", + "@deepseek-ai/dsh-sandbox-local": "workspace:^", + "node-addon-landlock-run": "0.0.0-test.0", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts new file mode 100644 index 0000000000..090d06b2fe --- /dev/null +++ b/packages/bash/bash-sandbox/src/index.ts @@ -0,0 +1,302 @@ +/** + * `SandboxBashExecutor`: the sandbox-consuming implementation of the + * `@deepseek-ai/dsh-bash` executor seam. Every spawned command is wrapped by + * the `ctx.sandbox` provider (`@deepseek-ai/dsh-sandbox`) according to the + * configured {@link SandboxMode}: the executor hands the provider the exact + * `['bash', '-c', command]` argv it is about to spawn and spawns the wrapped + * argv instead. WHICH platform runner confines it — and whether one is + * usable at all (the provider fails CLOSED with a structured + * `SANDBOX_UNAVAILABLE` error rather than passing the argv through) — is the + * provider's concern (`@deepseek-ai/dsh-sandbox-local` first). + * + * Extends `LocalBashExecutor` so all process mechanics — spawn, process-group + * kills, timeout escalation, output collection and spill files, background + * tasks, the credential scrub — are the local implementation's, verbatim. + * This package adds only the seam consumption and the result facts, which is + * exactly the split the capability seam was designed for (a sandboxing + * executor replaces `dsh-bash-local` without touching `dsh-tool-bash`, and + * swapping the confinement backend never touches this package). + * + * A failed run whose stderr carries the selected backend's own denial + * dialect (the signatures the provider stamps on every wrap) is classified + * as a sandbox denial on `BashRunResult.sandbox`, and every confined result + * also carries how completely the selected runner enforces the mode + * (`sandbox.enforcement`, from the provider's wrap). A failure carrying the + * backend's RUNNER-FAILURE signature instead means the sandbox itself broke + * and the command never ran: the foreground path re-throws it as the + * structured fail-closed `SANDBOX_UNAVAILABLE` error (late twin of the + * provider's confine-time throw), a settled background task stamps + * `sandbox.runnerFailed` — either way a broken sandbox can never read as a + * failing command, and the command never slips through unconfined. + * + * Deny-only at the seam, escalation at the tool: a denial is a reported FACT + * here, and the one-shot user-approved escalated retry of a denied action + * (docs/rfc/implemented/feature/2026-07-06-sandbox.md) is driven by + * `dsh-tool-bash` through `ctx.approval` — this executor's contribution is the + * per-call `sandboxMode` override it honors in {@link resolve}: an escalated + * call runs (and classifies, and reports) under ITS granted mode while every + * neighboring call keeps its session's standing mode (or the configured + * default when that session has no override). + * + * @module @deepseek-ai/dsh-bash-sandbox + */ + +import { resolve } from 'node:path' +import { Context } from 'cordis' +import z from 'schemastery' +import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId } from '@deepseek-ai/dsh-bash' +import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox' +import type { ConfinedSandboxMode, SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox' +import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' +import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local' + +/** + * Plugin config: the local executor's knobs plus the sandbox policy. All + * optional — `static Config` supplies the defaults (`mode: 'read-only'` is the + * fail-safe default; an example that wants a workspace-writable agent opts in + * explicitly). The runner choice is NOT configured here: which platform + * backend confines the command is the `ctx.sandbox` provider's config. + */ +export interface Config extends LocalConfig { + /** File-sandbox mode commands run under (default: `read-only`). */ + mode?: SandboxMode + /** + * Root directory `workspace-write` mode may write under (default: the + * executor's default working directory — `cwd`, else `process.cwd()`). + */ + workspaceRoot?: string +} + +/** + * Quote one string as a single-quoted POSIX shell word (embedded single + * quotes become `'\''`), so a wrapped argv element survives the outer + * `bash -c` re-parse byte-for-byte. + * @param text - the raw argv element to quote. + * @returns the single-quoted shell word. + */ +export function shellQuote(text: string): string { + return `'${text.replaceAll("'", String.raw`'\''`)}'` +} + +/** + * Conservative sandbox-denial classifier: a run counts as denied only when it + * FAILED (nonzero exit — a signal kill is not a denial) and its stderr + * carries one of the SELECTED BACKEND's own denial signatures — the dialect + * the provider stamps on every wrap (`ConfinedArgv.denialSignatures`: + * `Read-only file system` under bwrap's EROFS mounts, `Permission denied` + * under Landlock's EACCES, `Operation not permitted` under Seatbelt's + * EPERM). Matching the backend's dialect rather than a cross-backend union + * keeps the classifier from claiming denials the active backend never + * produces (bare EPERM text under a Linux runner names non-file boundaries — + * mount, kill, ptrace — that fail the same way unsandboxed). Text inference + * is the fallback signal until a runner provides a structured one (which + * wins once it exists); it errs toward NOT claiming a denial, and its known + * residual imprecision is non-sandbox text in the active dialect (an ssh + * auth failure reads as a denial under Landlock, a refused `kill` under + * Seatbelt). + * @param result - the settled foreground run to classify. + * @param signatures - the active wrap's denial dialect, case-insensitive + * stderr substrings. + * @returns whether the run's failure reads as a sandbox denial. + */ +export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean { + return matchesSignature(result.exitCode, result.stderr.text, signatures) +} + +/** + * Runner-failure classifier: a failed run whose stderr carries the SELECTED + * BACKEND's own runner-failure signature (`ConfinedArgv. + * runnerFailureSignatures`: the runner's error prefix, which also matches + * the shell's runner-not-found message) means the SANDBOX itself failed and + * the command never ran. Checked BEFORE {@link classifyDenial} — a runner's + * error text can contain denial words (an unopenable grant root reports + * `Permission denied`) — and surfaced as the fail-closed + * `SANDBOX_UNAVAILABLE` error on the foreground path, `sandbox.runnerFailed` + * on a settled background task. Same conservative-text-inference stance and + * residual imprecision as the denial classifier (a failing task that itself + * prints the runner's prefix reads as a runner failure). + * @param result - the settled foreground run to classify. + * @param signatures - the active wrap's runner-failure signatures, + * case-insensitive stderr substrings. + * @returns whether the run's failure reads as the runner itself failing. + */ +export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean { + return matchesSignature(result.exitCode, result.stderr.text, signatures) +} + +/** + * The classifier core shared by foreground results and settled background + * tasks: failed AND signature present. Lowercases BOTH sides — the seam + * declares its signatures case-insensitive, and producers compose them from + * runtime data of any case (an `argv0` path, `No such file or directory`). + */ +function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean { + if (exitCode === null || exitCode === 0) return false + const lowered = stderr.toLowerCase() + return signatures.some(signature => lowered.includes(signature.toLowerCase())) +} + +/** + * Sandbox-consuming bash executor. Registers as `ctx.bash` (loading it + * INSTEAD OF `dsh-bash-local`, together with a `ctx.sandbox` provider, is + * the whole swap — the tool layer is untouched). Its configured mode is the + * fallback exposed by {@link sandboxMode}; `dsh-tool-bash` folds a session's + * durable `bash/sandbox-mode` override and stamps the effective mode onto each + * request, while an approved escalation may stamp a strictly wider mode for + * one call. The tool's per-agent prompt section states that same effective + * mode, and each run's `result.sandbox` reports what actually executed plus + * enforcement completeness. + */ +export class SandboxBashExecutor extends LocalBashExecutor { + static inject = ['sandbox'] + + // The sandbox-specific fields intersect the local executor's Config as an + // inline schema call: the config catalog walks `static Config` statically. + static override Config: z = z.intersect([ + LocalBashExecutor.Config, + z.object({ + mode: z.union(['read-only', 'workspace-write', 'danger-full-access'] as const).default('read-only'), + workspaceRoot: z.string(), + }), + ]) + + private readonly mode: SandboxMode + private readonly workspaceRoot: string + /** + * Per-task facts, keyed by task id from `start()` until the settle stamp + * consumes them: the mode the task runs under (per-call — an escalated task + * differs from its neighbors) plus its wrap facts. The seam returns facts + * PER WRAP — a provider may legally vary enforcement or dialect between + * calls — so overlapping background tasks must each classify against their + * OWN wrap; a single latest-wrap field would let a later `start()` clobber + * an earlier task's facts before it settles. A `danger-full-access` task + * has NO entry (nothing confined it), which is what the settle stamp keys + * off. + */ + private readonly taskFacts = new Map() + + constructor(ctx: Context, config: Config) { + super(ctx, config) + // schemastery (static Config) already filled the defaulted fields — the + // cast records that runtime fact (mirrors LocalBashExecutor's config + // cast). `workspaceRoot` and `cwd` have NO schema default, so their + // fallback chain is real branching. + this.mode = config.mode as SandboxMode + this.workspaceRoot = resolve(config.workspaceRoot ?? config.cwd ?? process.cwd()) + } + + /** The configured default mode — the capability fact the tool layer reads. */ + override get sandboxMode(): SandboxMode { + return this.mode + } + + /** + * Stamp the effective mode onto the spec — the request's explicit override + * (an approved escalation), else this executor's configured default — so + * defaulting stays an explicit resolve step and `run()`/`start()` read the + * spec, never the config. + */ + override resolve(request: BashExecRequest): BashExecSpec { + return { ...super.resolve(request), sandboxMode: request.sandboxMode ?? this.mode } + } + + override async run(spec: BashExecSpec): Promise { + // resolve() always stamps the mode; the cast records that invariant + // (mirrors the constructor's config casts). + const mode = spec.sandboxMode as SandboxMode + if (mode === 'danger-full-access') { + const result = await super.run(spec) + return { ...result, sandbox: { mode, denied: false } } + } + const confined = this.confine(spec.command, mode) + const result = await super.run({ ...spec, command: confined.command }) + // Runner failure outranks denial: the sandbox itself failed and the + // command NEVER RAN — surface the same structured fail-closed error a + // confine-time discovery throws (late detection, same outcome), with + // the runner's own first stderr line as the cause. Returning it as a + // task result would let a broken sandbox read as a failing command. + if (classifyRunnerFailure(result, confined.runnerFailureSignatures)) { + throw new SandboxUnavailableError(mode, result.stderr.text.trim().split('\n')[0]) + } + return { ...result, sandbox: { mode, denied: classifyDenial(result, confined.denialSignatures), enforcement: confined.enforcement } } + } + + override start(spec: BashExecSpec): BashTask { + // Same stamped-by-resolve invariant as run(). + const mode = spec.sandboxMode as SandboxMode + if (mode === 'danger-full-access') return super.start(spec) + // Sandbox facts are stamped at settle time by {@link notifyTaskDone} + // (denial classification runs against the settled task's collected + // stderr). The map entry lands synchronously after spawn, strictly + // before the earliest possible settle (a process exit reaches us no + // sooner than the next tick). + const confined = this.confine(spec.command, mode) + const task = super.start({ ...spec, command: confined.command }) + const { enforcement, denialSignatures, runnerFailureSignatures } = confined + this.taskFacts.set(task.id, { mode, enforcement, denialSignatures, runnerFailureSignatures }) + return task + } + + /** + * Stamp the sandbox facts BEFORE completion listeners run: the base + * executor notifies from inside the task's settle path, so overriding the + * notification point is what makes `task.sandbox` visible to `onTaskDone` + * consumers and `done` awaiters alike. Each task classifies against the + * facts of ITS OWN wrap and reports ITS OWN mode (consumed from the + * per-task map here — settle is the entry's end of life): with per-call + * escalation, tasks under different modes settle side by side, so keying + * anything off the configured default would misreport them. A + * `danger-full-access` task has no map entry and carries no facts (nothing + * confined it); a signal-killed task (null exit code) is never a denial, + * mirroring the foreground classifier. + */ + protected override notifyTaskDone(task: BashTask): void { + const facts = this.taskFacts.get(task.id) + if (facts !== undefined) { + this.taskFacts.delete(task.id) + const stderr = this.collectedStderr(task.id) + // Runner failure outranks denial (the command never ran; the runner's + // own error text can contain denial words). A settled task has no + // error channel left, so the fact IS the surface here — the foreground + // path throws instead. + const runnerFailed = matchesSignature(task.exitCode, stderr, facts.runnerFailureSignatures) + task.sandbox = { + mode: facts.mode, + denied: !runnerFailed && matchesSignature(task.exitCode, stderr, facts.denialSignatures), + enforcement: facts.enforcement, + ...(runnerFailed ? { runnerFailed } : {}), + } + } + super.notifyTaskDone(task) + } + + /** + * Wrap one shell command via the `ctx.sandbox` provider: hand over the + * exact `['bash', '-c', command]` argv this executor would spawn, get back + * the confined argv, and re-assemble it into the `exec …` command string + * the inherited spawn path runs (the outer `bash -c` that `runBash` spawns + * `exec`s into the runner, so no extra shell lingers). Provider errors + * (fail-closed `SANDBOX_UNAVAILABLE`) propagate to the caller unchanged. + */ + private confine(command: string, mode: ConfinedSandboxMode): { + command: string + enforcement: SandboxEnforcement + denialSignatures: readonly string[] + runnerFailureSignatures: readonly string[] + } { + const confined = this.ctx.sandbox.confine(['bash', '-c', command], { mode, workspaceRoot: this.workspaceRoot }) + return { + command: `exec ${confined.argv.map(shellQuote).join(' ')}`, + enforcement: confined.enforcement, + denialSignatures: confined.denialSignatures, + runnerFailureSignatures: confined.runnerFailureSignatures, + } + } +} + +export default SandboxBashExecutor diff --git a/packages/bash/bash-sandbox/tests/bwrap.e2e.ts b/packages/bash/bash-sandbox/tests/bwrap.e2e.ts new file mode 100644 index 0000000000..6a748bc389 --- /dev/null +++ b/packages/bash/bash-sandbox/tests/bwrap.e2e.ts @@ -0,0 +1,101 @@ +import { spawnSync } from 'node:child_process' +import { existsSync, readFileSync } from 'node:fs' +import { mkdtemp, rm } from 'node:fs/promises' +import { homedir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local' +import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox' + +/** + * KEYLESS consumer-integration proof under bwrap: the REAL + * `LocalSandboxProvider` (nothing forced — bwrap is the ladder's first rung, + * so a passing probe selects it) underneath the REAL `SandboxBashExecutor`, + * driven through the executor's public run/start paths. Verifies the WORLD + * (files exist or don't) plus the stamped result facts — in particular that + * bwrap's EROFS denial text classifies as `denied: true` through the + * wrap-carried dialect; the backend-only confinement proofs live with + * `@deepseek-ai/dsh-sandbox-local`. + * + * Self-skips wherever the functional probe fails — no `bwrap` on PATH, or a + * host that denies unprivileged user namespaces. + * + * HOME-based dirs on purpose: bwrap's `/tmp` is an ephemeral mount, so only + * paths outside it prove the workspace-root boundary. + */ + +const probe = spawnSync('bwrap', [...bwrapProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' }) +const bwrapUsable = probe.status === 0 + +let ctx: Context | undefined +const tempDirs: string[] = [] + +afterEach(async () => { + await ctx?.fiber.dispose() + ctx = undefined + await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) +}) + +async function tempDir(base: string): Promise { + const dir = await mkdtemp(join(base, 'dsh-bwrap-e2e-')) + tempDirs.push(dir) + return dir +} + +async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-write'): Promise { + ctx = new Context() + await ctx.plugin(LocalSandboxProvider, {}) + await ctx.plugin(SandboxBashExecutor, { mode, cwd: workspace, workspaceRoot: workspace, timeoutMs: 30_000 }) + return ctx.bash as SandboxBashExecutor +} + +describe.skipIf(!bwrapUsable)('bash-sandbox: real bwrap confinement through ctx.bash', () => { + it('read-only denies a write — the file must NOT exist, and EROFS text classifies as a denial', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const result = await bash.run(bash.resolve({ command: `echo hi > ${workdir}/denied.txt` })) + expect(result.exitCode).not.toBe(0) + expect(result.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + expect(existsSync(join(workdir, 'denied.txt'))).toBe(false) + }) + + it('workspace-write lands a write inside the workspace root and still denies one beside it', async () => { + const workdir = await tempDir(homedir()) + const outside = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'workspace-write') + + const inside = await bash.run(bash.resolve({ command: `printf bwrap-ok > ${workdir}/allowed.txt` })) + expect(inside.exitCode).toBe(0) + expect(inside.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' }) + expect(readFileSync(join(workdir, 'allowed.txt'), 'utf8')).toBe('bwrap-ok') + + const denied = await bash.run(bash.resolve({ command: `echo hi > ${outside}/denied.txt` })) + expect(denied.exitCode).not.toBe(0) + expect(denied.sandbox).toEqual({ mode: 'workspace-write', denied: true, enforcement: 'full' }) + expect(existsSync(join(outside, 'denied.txt'))).toBe(false) + }) + + it('classifies a background denial once the task settles', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const task = bash.start(bash.resolve({ command: `echo hi > ${workdir}/bg-denied.txt` })) + await task.done + expect(task.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + expect(existsSync(join(workdir, 'bg-denied.txt'))).toBe(false) + }) + + it('an approved escalated retry — the spec-level workspace-write override — lands the exact write read-only denied', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const command = `printf escalated > ${workdir}/escalated.txt` + const strict = await bash.run(bash.resolve({ command })) + expect(strict.exitCode).not.toBe(0) + expect(strict.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + expect(existsSync(join(workdir, 'escalated.txt'))).toBe(false) + const retried = await bash.run(bash.resolve({ command, sandboxMode: 'workspace-write' })) + expect(retried.exitCode).toBe(0) + expect(retried.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' }) + expect(readFileSync(join(workdir, 'escalated.txt'), 'utf8')).toBe('escalated') + }) +}) diff --git a/packages/bash/bash-sandbox/tests/landlock.e2e.ts b/packages/bash/bash-sandbox/tests/landlock.e2e.ts new file mode 100644 index 0000000000..8263dad6fe --- /dev/null +++ b/packages/bash/bash-sandbox/tests/landlock.e2e.ts @@ -0,0 +1,100 @@ +import { spawnSync } from 'node:child_process' +import { existsSync, readFileSync } from 'node:fs' +import { mkdtemp, rm } from 'node:fs/promises' +import { homedir, tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import { launcherPath } from 'node-addon-landlock-run' +import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local' +import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox' + +/** + * KEYLESS consumer-integration proof: the REAL `LocalSandboxProvider` (bwrap + * rung forced off, so the npm-distributed `landlock-run` confines) underneath the + * REAL `SandboxBashExecutor`, driven through the executor's public run/start + * paths. Verifies the WORLD (files exist or don't) plus the stamped result + * facts; the backend-only confinement proofs live with + * `@deepseek-ai/dsh-sandbox-local`. + * + * Self-skips when the running kernel does not enforce Landlock; the + * launcher binary itself arrives with `pnpm install` (`node-addon-landlock-run`). + */ + +const probe = spawnSync(launcherPath(), ['--probe'], { timeout: 5_000, encoding: 'utf8' }) +const landlockUsable = probe.status === 0 +/** The kernel's enforcement level from the probe report — stamped facts below must match it. */ +const enforcement = /partially enforced/.test(probe.stdout ?? '') ? 'partial' : 'full' + +let ctx: Context | undefined +const tempDirs: string[] = [] + +afterEach(async () => { + await ctx?.fiber.dispose() + ctx = undefined + await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) +}) + +async function tempDir(base: string): Promise { + const dir = await mkdtemp(join(base, 'dsh-landlock-e2e-')) + tempDirs.push(dir) + return dir +} + +async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-write'): Promise { + ctx = new Context() + await ctx.plugin(LocalSandboxProvider, {}) + ;(ctx.sandbox as LocalSandboxProvider).internals = { probeBwrap: () => false } + await ctx.plugin(SandboxBashExecutor, { mode, cwd: workspace, workspaceRoot: workspace, timeoutMs: 30_000 }) + return ctx.bash as SandboxBashExecutor +} + +describe.skipIf(!landlockUsable)('bash-sandbox: real Landlock confinement through ctx.bash', () => { + it('read-only denies a write — the file must NOT exist, the result carries denial + enforcement facts', async () => { + const workdir = await tempDir(tmpdir()) + const bash = await sandboxedBash(workdir, 'read-only') + const result = await bash.run(bash.resolve({ command: `echo hi > ${workdir}/denied.txt` })) + expect(result.exitCode).not.toBe(0) + expect(result.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement }) + expect(existsSync(join(workdir, 'denied.txt'))).toBe(false) + }) + + it('workspace-write lands a write inside the workspace root and still denies one beside it', async () => { + const workdir = await tempDir(homedir()) + const outside = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'workspace-write') + + const inside = await bash.run(bash.resolve({ command: `printf landlock-ok > ${workdir}/allowed.txt` })) + expect(inside.exitCode).toBe(0) + expect(inside.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement }) + expect(readFileSync(join(workdir, 'allowed.txt'), 'utf8')).toBe('landlock-ok') + + const denied = await bash.run(bash.resolve({ command: `echo hi > ${outside}/denied.txt` })) + expect(denied.exitCode).not.toBe(0) + expect(denied.sandbox).toEqual({ mode: 'workspace-write', denied: true, enforcement }) + expect(existsSync(join(outside, 'denied.txt'))).toBe(false) + }) + + it('classifies a background denial once the task settles', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const task = bash.start(bash.resolve({ command: `echo hi > ${workdir}/bg-denied.txt` })) + await task.done + expect(task.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement }) + expect(existsSync(join(workdir, 'bg-denied.txt'))).toBe(false) + }) + + it('an approved escalated retry — the spec-level workspace-write override — lands the exact write read-only denied', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const command = `printf escalated > ${workdir}/escalated.txt` + const strict = await bash.run(bash.resolve({ command })) + expect(strict.exitCode).not.toBe(0) + expect(strict.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: enforcement }) + expect(existsSync(join(workdir, 'escalated.txt'))).toBe(false) + const retried = await bash.run(bash.resolve({ command, sandboxMode: 'workspace-write' })) + expect(retried.exitCode).toBe(0) + expect(retried.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: enforcement }) + expect(readFileSync(join(workdir, 'escalated.txt'), 'utf8')).toBe('escalated') + }) +}) diff --git a/packages/bash/bash-sandbox/tests/sandbox.spec.ts b/packages/bash/bash-sandbox/tests/sandbox.spec.ts new file mode 100644 index 0000000000..4f92ba38f0 --- /dev/null +++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts @@ -0,0 +1,327 @@ +/** + * SandboxBashExecutor tests: the CONSUMER side of the sandbox seam. A fake + * `ctx.sandbox` provider (injected as a real cordis service) makes wrapping, + * policy hand-off, fail-closed propagation, classification, and fact + * stamping all deterministic without any real runner; the real-provider + * integration proof lives in `tests/landlock.e2e.ts`. Denials are produced + * with plain unix permissions (a 0555 directory), which exercises the same + * stderr signature the classifier keys on. + */ + +import { chmodSync, mkdirSync, mkdtempSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join, resolve } from 'node:path' +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash' +import { SANDBOX_UNAVAILABLE, SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox' +import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox' +import { classifyDenial, classifyRunnerFailure, SandboxBashExecutor, shellQuote } from '@deepseek-ai/dsh-bash-sandbox' +import type { Config } from '@deepseek-ai/dsh-bash-sandbox' + +const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-sandbox-spec-')) + +/** One recorded provider call: the argv handed over and the policy it rode with. */ +interface ConfineCall { + argv: string[] + policy: SandboxPolicy +} + +/** The Linux file-denial dialects the fake wraps carry — matches the unix-permission denials the tests below produce. */ +const UNIX_SIGNATURES = ['read-only file system', 'permission denied'] as const + +/** The runner-failure prefix the fake wraps carry (a fake-runner: error line marks the sandbox itself failing). */ +const RUNNER_FAILURE = ['fake-runner: '] as const + +/** A passthrough wrap: the caller's argv unchanged, asserted full — commands run unconfined, deterministically. */ +const passthrough = (argv: readonly string[]): ConfinedArgv => + ({ argv: [...argv], enforcement: 'full', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE }) + +/** + * Boot a context with a recording fake `ctx.sandbox` (behavior injectable + * per test) and the executor under test on top of it. + */ +async function setup(config: Config = {}, behavior: (argv: readonly string[], policy: SandboxPolicy) => ConfinedArgv = passthrough) { + const calls: ConfineCall[] = [] + class FakeSandboxProvider extends SandboxProvider { + confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv { + calls.push({ argv: [...argv], policy }) + return behavior(argv, policy) + } + } + const ctx = new Context() + await ctx.plugin(FakeSandboxProvider) + await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...config }) + const bash = ctx.bash as SandboxBashExecutor + bash.internals = { spillDir } + return { ctx, bash, calls } +} + +function output(text: string): CollectedOutput { + return { text, truncated: false } +} + +function runResult(exitCode: number | null, stderr: string): BashRunResult { + return { exitCode, signal: null, timedOut: false, aborted: false, timeoutMs: 1000, stdout: output(''), stderr: output(stderr) } +} + +describe('the provider hand-off', () => { + it('hands the provider the exact bash argv and the per-call policy, and runs the returned argv', async () => { + const { bash, calls } = await setup() + const result = await bash.run(bash.resolve({ command: 'echo \'a b\' "c\'d"' })) + expect(result.stdout.text).toBe('a b c\'d\n') + expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' }) + expect(calls).toEqual([{ + argv: ['bash', '-c', 'echo \'a b\' "c\'d"'], + policy: { mode: 'read-only', workspaceRoot: resolve(process.cwd()) }, + }]) + }) + + it('a wrapped argv from the provider is what actually spawns (prefix survives, quoting round-trips)', async () => { + // The fake wraps with `env MARKER=...` — a real (if tiny) runner prefix: + // the sentinel only prints if the executor spawned the WRAPPED argv. + const { bash } = await setup({}, argv => ({ argv: ['env', 'DSH_WRAP=1', ...argv], enforcement: 'full', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE })) + const result = await bash.run(bash.resolve({ command: 'printf "%s" "$DSH_WRAP"' })) + expect(result.stdout.text).toBe('1') + expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' }) + }) + + it('workspace-write rides the policy, workspaceRoot falling back to cwd when not configured', async () => { + const { bash, calls } = await setup({ mode: 'workspace-write', cwd: tmpdir() }) + const result = await bash.run(bash.resolve({ command: 'true' })) + expect(result.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' }) + expect(calls[0]?.policy).toEqual({ mode: 'workspace-write', workspaceRoot: resolve(tmpdir()) }) + }) + + it('an explicit workspaceRoot wins over cwd', async () => { + const { calls, bash } = await setup({ mode: 'workspace-write', workspaceRoot: '/ws', cwd: tmpdir() }) + await bash.run(bash.resolve({ command: 'true' })) + expect(calls[0]?.policy.workspaceRoot).toBe(resolve('/ws')) + }) + + it('the provider is consulted per wrap (no caching in the consumer): run and start each hand off', async () => { + const { bash, calls } = await setup() + await bash.run(bash.resolve({ command: 'true' })) + const task = bash.start(bash.resolve({ command: 'true' })) + await task.done + expect(calls).toHaveLength(2) + }) + + it('shellQuote survives embedded single quotes (the argv re-assembly primitive)', () => { + expect(shellQuote('a\'b')).toBe(String.raw`'a'\''b'`) + }) +}) + +describe('fail closed', () => { + it('propagates the provider\'s structured SANDBOX_UNAVAILABLE on run() and start()', async () => { + const { bash } = await setup({}, () => { throw new SandboxUnavailableError('read-only') }) + const spec = bash.resolve({ command: 'echo hi' }) + await expect(bash.run(spec)).rejects.toMatchObject({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE }) + expect(() => bash.start(spec)).toThrow(SandboxUnavailableError) + }) +}) + +describe('danger-full-access', () => { + it('runs unwrapped: the provider is never consulted, facts carry no enforcement', async () => { + const { bash, calls } = await setup({ mode: 'danger-full-access' }) + const result = await bash.run(bash.resolve({ command: 'echo free' })) + expect(result.stdout.text).toBe('free\n') + expect(result.sandbox).toEqual({ mode: 'danger-full-access', denied: false }) + expect(calls).toHaveLength(0) + }) + + it('start() passes through unwrapped and stamps nothing at settle', async () => { + const { bash, calls } = await setup({ mode: 'danger-full-access' }) + const task = bash.start(bash.resolve({ command: 'echo free-bg' })) + await task.done + expect(task.sandbox).toBeUndefined() + expect(bash.readOutput(task.id).delta).toContain('free-bg') + expect(calls).toHaveLength(0) + }) +}) + +describe('per-call sandboxMode override (the escalation mechanism)', () => { + it('exposes the configured default as the capability fact, and resolve() stamps it', async () => { + const { bash } = await setup() + expect(bash.sandboxMode).toBe('read-only') + expect(bash.resolve({ command: 'true' }).sandboxMode).toBe('read-only') + }) + + it('an explicit override outranks the default at resolve(), and the wrap policy follows it', async () => { + const { bash, calls } = await setup() + expect(bash.resolve({ command: 'true', sandboxMode: 'workspace-write' }).sandboxMode).toBe('workspace-write') + await bash.run(bash.resolve({ command: 'true', sandboxMode: 'workspace-write' })) + await bash.run(bash.resolve({ command: 'true' })) + expect(calls.map(call => call.policy.mode)).toEqual(['workspace-write', 'read-only']) + }) + + it('an escalated run reports the mode it ACTUALLY ran under', async () => { + const { bash } = await setup() + const result = await bash.run(bash.resolve({ command: 'true', sandboxMode: 'workspace-write' })) + expect(result.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' }) + }) + + it('escalating to danger-full-access bypasses the provider entirely — the grant, not a probe, is the authority there', async () => { + const { bash, calls } = await setup() + const result = await bash.run(bash.resolve({ command: 'echo free', sandboxMode: 'danger-full-access' })) + expect(result.stdout.text).toBe('free\n') + expect(result.sandbox).toEqual({ mode: 'danger-full-access', denied: false }) + expect(calls).toHaveLength(0) + }) + + it('overlapping background tasks settle with their OWN modes (an escalated task next to a default one)', async () => { + // With per-call policy, tasks under different modes are in flight at + // once — anything keyed off the configured default would misreport the + // escalated one at its settle stamp. + const { bash } = await setup() + const escalated = bash.start(bash.resolve({ command: 'sleep 0.3; echo "x: Permission denied" >&2; exit 1', sandboxMode: 'workspace-write' })) + const plain = bash.start(bash.resolve({ command: 'true' })) + await plain.done + await escalated.done + expect(escalated.sandbox).toEqual({ mode: 'workspace-write', denied: true, enforcement: 'full' }) + expect(plain.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' }) + }) + + it('an escalated danger-full-access background task carries no facts (nothing confined it)', async () => { + const { bash, calls } = await setup() + const task = bash.start(bash.resolve({ command: 'echo bg-free', sandboxMode: 'danger-full-access' })) + await task.done + expect(task.sandbox).toBeUndefined() + expect(bash.readOutput(task.id).delta).toContain('bg-free') + expect(calls).toHaveLength(0) + }) +}) + +describe('classifyDenial', () => { + it('never classifies a clean exit or a signal kill as a denial', () => { + expect(classifyDenial(runResult(0, 'Permission denied'), UNIX_SIGNATURES)).toBe(false) + expect(classifyDenial(runResult(null, 'Permission denied'), UNIX_SIGNATURES)).toBe(false) + }) + + it('classifies failed runs by the wrap\'s own dialect, conservatively', () => { + expect(classifyDenial(runResult(1, 'touch: cannot touch /x: Read-only file system'), UNIX_SIGNATURES)).toBe(true) + expect(classifyDenial(runResult(1, 'sh: /x: Permission denied'), UNIX_SIGNATURES)).toBe(true) + // Bare EPERM is not a Linux runner's dialect: mount/kill/ptrace fail with + // it unsandboxed too, and the mode vocabulary governs file effects only — + // claiming a file denial here would tell the model the sandbox blocked + // something it never governed. + expect(classifyDenial(runResult(1, 'mount: Operation not permitted'), UNIX_SIGNATURES)).toBe(false) + expect(classifyDenial(runResult(1, 'No such file or directory'), UNIX_SIGNATURES)).toBe(false) + }) + + it('matches exactly the active backend\'s dialect: EPERM classifies under Seatbelt, EACCES does not under bwrap', () => { + // The same stderr flips meaning with the backend: under Seatbelt, EPERM + // text IS how the kernel refuses a governed file write; under bwrap's + // EROFS-only dialect, `Permission denied` is ordinary DAC, not the + // sandbox — per-wrap signatures are what keep both classifications honest. + expect(classifyDenial(runResult(1, 'bash: /etc/x: Operation not permitted'), ['operation not permitted'])).toBe(true) + expect(classifyDenial(runResult(1, 'sh: /x: Permission denied'), ['read-only file system'])).toBe(false) + }) +}) + +describe('classifyRunnerFailure', () => { + it('matches the dialect case-insensitively on BOTH sides — the seam declares it so, and producers compose signatures from runtime data (an argv0 path, the shell\'s `No such file or directory`)', () => { + const signatures = ['exec: /Opt/Runners/bwrap: not found', '/Opt/Runners/bwrap: No such file or directory'] + expect(classifyRunnerFailure(runResult(127, 'bash: /Opt/Runners/bwrap: No such file or directory'), signatures)).toBe(true) + expect(classifyRunnerFailure(runResult(127, 'BASH: LINE 1: EXEC: /OPT/RUNNERS/BWRAP: NOT FOUND'), signatures)).toBe(true) + }) +}) + +describe('result facts', () => { + it('reports a real permission failure as a sandbox denial with the mode it ran under', async () => { + const { bash } = await setup() + const lockedDir = join(mkdtempSync(join(tmpdir(), 'dsh-sandbox-denied-')), 'locked') + mkdirSync(lockedDir) + chmodSync(lockedDir, 0o555) + const result = await bash.run(bash.resolve({ command: `echo x > ${lockedDir}/f` })) + expect(result.exitCode).not.toBe(0) + expect(result.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + }) + + it('carries the provider\'s partial-enforcement fact through unchanged', async () => { + const { bash } = await setup({}, argv => ({ argv: [...argv], enforcement: 'partial', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE })) + const result = await bash.run(bash.resolve({ command: 'true' })) + expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' }) + }) +}) + +describe('background sandbox facts', () => { + it('stamps a settled denial: nonzero exit + permission stderr under a confined mode', async () => { + const { bash } = await setup() + const task = bash.start(bash.resolve({ command: 'echo "x: Permission denied" >&2; exit 1' })) + await task.done + expect(task.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + }) + + it('a foreground runner failure throws the fail-closed error, never a task result', async () => { + // The wrap's runner prefix on a failed run means the SANDBOX broke and + // the command never ran — the late twin of the confine-time throw, with + // the runner's own first stderr line carried as the cause. + const { bash } = await setup() + const run = bash.run(bash.resolve({ command: 'echo "fake-runner: ruleset rejected" >&2; exit 125' })) + await expect(run).rejects.toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) + await expect(run).rejects.toThrow('fake-runner: ruleset rejected') + }) + + it('a foreground runner failure outranks denial: runner error text may contain denial words', async () => { + const { bash } = await setup() + await expect(bash.run(bash.resolve({ command: 'echo "fake-runner: cannot open rule path: /x: Permission denied" >&2; exit 125' }))) + .rejects.toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) + }) + + it('a settled background runner failure stamps runnerFailed (no error channel remains), not denied', async () => { + const { bash } = await setup() + const task = bash.start(bash.resolve({ command: 'echo "fake-runner: cannot open rule path: /x: Permission denied" >&2; exit 125' })) + await task.done + expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full', runnerFailed: true }) + }) + + it('completion listeners already see the stamped facts (stamp precedes notify)', async () => { + const { ctx, bash } = await setup({}, argv => ({ argv: [...argv], enforcement: 'partial', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE })) + const seen: unknown[] = [] + ctx.bash.onTaskDone((task) => { seen.push(task.sandbox) }) + const task = bash.start(bash.resolve({ command: 'echo "x: Permission denied" >&2; exit 1' })) + await task.done + expect(seen).toEqual([{ mode: 'read-only', denied: true, enforcement: 'partial' }]) + }) + + it('overlapping background tasks keep their OWN wrap facts (per-task, not latest-wrap)', async () => { + // The seam returns facts PER WRAP — a legal provider may vary them + // between calls. The slow task settles AFTER the quick one started, so a + // latest-wrap field would classify its denial against the quick task's + // dialect (missing it) and stamp the wrong enforcement. + const wraps: Array> = [ + { enforcement: 'partial', denialSignatures: ['permission denied'] }, + { enforcement: 'full', denialSignatures: ['read-only file system'] }, + ] + let call = 0 + const { bash } = await setup({}, (argv) => { + const wrap = wraps[Math.min(call++, wraps.length - 1)] as Pick + return { argv: [...argv], ...wrap, runnerFailureSignatures: RUNNER_FAILURE } + }) + const slow = bash.start(bash.resolve({ command: 'sleep 0.4; echo "x: Permission denied" >&2; exit 1' })) + const quick = bash.start(bash.resolve({ command: 'true' })) + await quick.done + await slow.done + expect(slow.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'partial' }) + expect(quick.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' }) + }) + + it('a signal-killed task is never a denial (null exit code)', async () => { + const { bash } = await setup() + const task = bash.start(bash.resolve({ command: 'echo "Permission denied" >&2; sleep 30' })) + // Let the stderr land before the kill so the classifier sees the + // signature and must still refuse it on the null exit code alone. + await vi.waitFor(() => { expect(bash.readOutput(task.id).delta).toContain('Permission denied') }) + bash.kill(task.id) + await task.done + expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' }) + }) + + it('disposal kills wrapped background tasks (inherited HMR safety)', async () => { + const { ctx, bash } = await setup() + const task = bash.start(bash.resolve({ command: 'sleep 30' })) + await ctx.fiber.dispose() + expect(task.status).toBe('killed') + }) +}) diff --git a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts new file mode 100644 index 0000000000..8ae25a8d39 --- /dev/null +++ b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts @@ -0,0 +1,101 @@ +import { spawnSync } from 'node:child_process' +import { existsSync, readFileSync } from 'node:fs' +import { mkdtemp, rm } from 'node:fs/promises' +import { homedir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local' +import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox' + +/** + * KEYLESS consumer-integration proof on macOS: the REAL `LocalSandboxProvider` + * (Linux rungs forced off, so `sandbox-exec`/Seatbelt confines) underneath + * the REAL `SandboxBashExecutor`, driven through the executor's public + * run/start paths. Verifies the WORLD (files exist or don't) plus the + * stamped result facts — in particular that Seatbelt's EPERM denial text + * classifies as `denied: true` through the wrap-carried dialect; the + * backend-only confinement proofs live with `@deepseek-ai/dsh-sandbox-local`. + * + * Self-skips wherever the functional probe fails — every non-macOS host, or + * a macOS whose `sandbox-exec` refuses the profile. + */ + +const probe = spawnSync('sandbox-exec', [...seatbeltProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' }) +const seatbeltUsable = probe.status === 0 + +let ctx: Context | undefined +const tempDirs: string[] = [] + +afterEach(async () => { + await ctx?.fiber.dispose() + ctx = undefined + await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) +}) + +async function tempDir(base: string): Promise { + const dir = await mkdtemp(join(base, 'dsh-seatbelt-e2e-')) + tempDirs.push(dir) + return dir +} + +async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-write'): Promise { + ctx = new Context() + await ctx.plugin(LocalSandboxProvider, {}) + ;(ctx.sandbox as LocalSandboxProvider).internals = { probeBwrap: () => false, probeLandlock: () => 'unusable' } + await ctx.plugin(SandboxBashExecutor, { mode, cwd: workspace, workspaceRoot: workspace, timeoutMs: 30_000 }) + return ctx.bash as SandboxBashExecutor +} + +describe.skipIf(!seatbeltUsable)('bash-sandbox: real Seatbelt confinement through ctx.bash', () => { + it('read-only denies a write — the file must NOT exist, and EPERM text classifies as a denial', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const result = await bash.run(bash.resolve({ command: `echo hi > ${workdir}/denied.txt` })) + expect(result.exitCode).not.toBe(0) + expect(result.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + expect(existsSync(join(workdir, 'denied.txt'))).toBe(false) + }) + + it('workspace-write lands a write inside the workspace root and still denies one beside it', async () => { + // HOME-based dirs on purpose: workspace-write grants /tmp and the + // per-user temp dir wholesale, so only paths outside both prove the + // workspace-root boundary. + const workdir = await tempDir(homedir()) + const outside = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'workspace-write') + + const inside = await bash.run(bash.resolve({ command: `printf seatbelt-ok > ${workdir}/allowed.txt` })) + expect(inside.exitCode).toBe(0) + expect(inside.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' }) + expect(readFileSync(join(workdir, 'allowed.txt'), 'utf8')).toBe('seatbelt-ok') + + const denied = await bash.run(bash.resolve({ command: `echo hi > ${outside}/denied.txt` })) + expect(denied.exitCode).not.toBe(0) + expect(denied.sandbox).toEqual({ mode: 'workspace-write', denied: true, enforcement: 'full' }) + expect(existsSync(join(outside, 'denied.txt'))).toBe(false) + }) + + it('classifies a background denial once the task settles', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const task = bash.start(bash.resolve({ command: `echo hi > ${workdir}/bg-denied.txt` })) + await task.done + expect(task.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + expect(existsSync(join(workdir, 'bg-denied.txt'))).toBe(false) + }) + + it('an approved escalated retry — the spec-level workspace-write override — lands the exact write read-only denied', async () => { + const workdir = await tempDir(homedir()) + const bash = await sandboxedBash(workdir, 'read-only') + const command = `printf escalated > ${workdir}/escalated.txt` + const strict = await bash.run(bash.resolve({ command })) + expect(strict.exitCode).not.toBe(0) + expect(strict.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) + expect(existsSync(join(workdir, 'escalated.txt'))).toBe(false) + const retried = await bash.run(bash.resolve({ command, sandboxMode: 'workspace-write' })) + expect(retried.exitCode).toBe(0) + expect(retried.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' }) + expect(readFileSync(join(workdir, 'escalated.txt'), 'utf8')).toBe('escalated') + }) +}) diff --git a/packages/bash/bash-sandbox/tsconfig.json b/packages/bash/bash-sandbox/tsconfig.json new file mode 100644 index 0000000000..6dad98d54f --- /dev/null +++ b/packages/bash/bash-sandbox/tsconfig.json @@ -0,0 +1,36 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../sandbox/sandbox" + }, + { + "path": "../../bash/bash" + }, + { + "path": "../../bash/bash-local" + } + ] +} diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md index 39318ae371..ac7e00c3a3 100644 --- a/packages/bash/bash/README.md +++ b/packages/bash/bash/README.md @@ -2,15 +2,16 @@ The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run commands, manage background tasks — without saying HOW. -This package is one third of the bash capability, split so each concern can evolve (and be swapped) independently: +This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently: | Package | Role | |---|---| | `@deepseek-ai/dsh-bash` (this) | the interface: abstract service + vocabulary types | | `@deepseek-ai/dsh-bash-local` | an implementation: local subprocesses | +| `@deepseek-ai/dsh-bash-sandbox` | an implementation: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts | | `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` | -The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. A future sandboxed, containerized, or remote executor implements this interface and the tool schemas don't change. +The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same interface, tool schemas untouched; a containerized or remote executor slots in the same way. ## Service API (`ctx.bash`) @@ -19,6 +20,7 @@ The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool su | `run(spec)` | Foreground execution. Resolves when the command finishes. **Rejects only for infrastructure failures** (unusable workdir, missing shell, pre-aborted signal); nonzero exits, timeout kills, and abort kills resolve with a descriptive `BashRunResult`. | | `start(spec)` | Background execution. Returns a `BashTask` handle immediately; **no timeout applies** (stop tasks via `kill`). | | `get(id)` / `list()` | Task lookup. | +| `sandboxMode` | The capability fact for the tool layer: the default mode a SANDBOXING executor confines under (`undefined` in the base class — "this executor does not sandbox"). `dsh-tool-bash` reads it at registration to advertise the escalation fields only when the composition honors them. | | `ownerOf(id)` | The opaque OWNER token recorded for a background task at `start` (from the spec's `owner`), or `undefined` for an unknown id OR a known-but-ownerless task. The executor stores/returns it verbatim and NEVER interprets it — the access POLICY lives in the consumer (`dsh-tool-bash`), which compares `ownerOf(id)` to the caller's token. Storing ownership here (disposed with the executor's fiber) is what makes it survive a consumer HMR reload. | | `readOutput(id)` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. Throws for unknown ids. | | `kill(id)` | Kill a running task. Returns `false` when it already finished; throws for unknown ids. | @@ -28,6 +30,8 @@ Implementations subclass `BashExecutor`, implement the abstract methods, and cal ## Vocabulary -`BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, owner?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, owner) before execution; `owner` is optional on the request and **required-but-nullable** (`OwnerToken | undefined`) on the resolved spec, so a forgotten owner is a visible `undefined` rather than a silently-absent property. The task id (`BashTaskId`) and the `owner` token (`OwnerToken`) are [branded](../../util/brand) — `OwnerToken` is a DISTINCT brand from `SessionId` (the seam never imports `dsh-session`; the `dsh-tool-bash` consumer is the single boundary that casts its `SessionId` into one). `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. See `src/types.ts` for the full contracts. +`BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, owner?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, owner, sandboxMode) before execution; `owner` and `sandboxMode` are optional on the request and **required-but-nullable** on the resolved spec, so a forgotten one is a visible `undefined` rather than a silently-absent property. `sandboxMode` is the explicit per-call sandbox-policy input: an escalation grant a human just issued ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md), which outranks) or the session's standing override ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)); a sandboxing executor's `resolve()` stamps its configured default when the request carries none, and a non-sandboxing executor carries the field verbatim and confines nothing. + +The seam also owns the per-session mode override vocabulary (the sandbox RFC § Per-session mode switching): the log-only `'bash/sandbox-mode'` session event, the pure fold `effectiveSandboxMode(events)` (last event wins; `undefined` means "apply the executor default"), and THE write path `setSandboxMode(session, mode)` — the session log is the store, so an override survives restart by replay and two sessions can never see each other's mode. Writers must respect turn-enclosure: the ACP bridge anchors an idle switch at the next turn rather than appending between turns. The task id (`BashTaskId`) and the `owner` token (`OwnerToken`) are [branded](../../util/brand) — `OwnerToken` is a DISTINCT brand from `SessionId` (the seam never imports `dsh-session`; the `dsh-tool-bash` consumer is the single boundary that casts its `SessionId` into one). `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. A sandboxing executor additionally stamps `sandbox` result facts on results and settled tasks (`BashSandboxInfo`: the mode it executed under, the conservative `denied` classification, and — for confined modes — the backend's `enforcement` completeness); the mode/enforcement vocabulary is owned by the [`dsh-sandbox`](../../sandbox/sandbox/) seam, and the facts are documented in [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md). See `src/types.ts` for the full contracts. `stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so they would be redundant tool params. This is not a security boundary: the implementation's credential scrub (not these fields) is what keeps the harness's ambient secrets out of a spawned command. They are plain optionals on the resolved spec (unlike `owner`'s required-but-nullable): a missing one means "none", the safe default. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md). diff --git a/packages/bash/bash/package.json b/packages/bash/bash/package.json index f1bc43c2b4..bfa71d73e3 100644 --- a/packages/bash/bash/package.json +++ b/packages/bash/bash/package.json @@ -23,10 +23,14 @@ "license": "BSD-3-Clause", "peerDependencies": { "@deepseek-ai/dsh-brand": "^0.0.1", + "@deepseek-ai/dsh-sandbox": "^0.0.1", + "@deepseek-ai/dsh-session": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "devDependencies": { "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-sandbox": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", "cordis": "^4.0.0-rc.6" } } diff --git a/packages/bash/bash/src/index.ts b/packages/bash/bash/src/index.ts index b629f10e4d..63c5757175 100644 --- a/packages/bash/bash/src/index.ts +++ b/packages/bash/bash/src/index.ts @@ -15,13 +15,16 @@ */ import { Context, Service } from 'cordis' +import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId, BashTaskListener, BashTaskRead, OwnerToken } from './types.ts' export { BashTaskId, OwnerToken } from './types.ts' +export { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from './session-mode.ts' export type { BashExecRequest, BashExecSpec, BashRunResult, + BashSandboxInfo, BashTask, BashTaskListener, BashTaskRead, @@ -70,6 +73,22 @@ export abstract class BashExecutor extends Service { }, 'bash listener teardown') } + /** + * The sandbox mode this executor confines commands under BY DEFAULT, or + * `undefined` when it does not sandbox at all — the capability fact the + * tool and ACP layers read to advertise sandbox controls honestly. The + * getter proves a sandboxing executor is mounted and supplies its fallback + * mode; a session override may make the effective mode narrower or wider, + * so strict escalation widening is checked per call rather than encoded in + * this default-relative capability fact. The base class reports + * `undefined`; a sandboxing implementation overrides the getter. + * @returns the configured default mode of a sandboxing executor; + * `undefined` for an executor that never confines. + */ + get sandboxMode(): SandboxMode | undefined { + return undefined + } + /** * Resolve a caller's {@link BashExecRequest} into a fully-specified * {@link BashExecSpec}, applying this implementation's config defaults and diff --git a/packages/bash/bash/src/session-mode.ts b/packages/bash/bash/src/session-mode.ts new file mode 100644 index 0000000000..03ad6e3d7c --- /dev/null +++ b/packages/bash/bash/src/session-mode.ts @@ -0,0 +1,65 @@ +/** + * Per-session sandbox-mode override: the session log as the store. A runtime + * switch (an ACP `session/set_config_option`, a test scenario) is recorded as + * one `bash/sandbox-mode` event on the session it applies to; + * `effective = fold(events) ?? the executor's configured default`, so an + * override survives restart by replay, two sessions can never see each + * other's state, and there is no external config store. The event is + * log-only (the `approval/*` precedent): the model learns the mode from the + * prompt section and the boundary notices in `@deepseek-ai/dsh-tool-bash`, + * never from the event itself. EXECUTION honors the fold in the tool layer — + * it stamps the effective mode onto each call's `BashExecRequest.sandboxMode` + * (weakest-precedence: an escalation grant for the call outranks it) — the + * executor itself stays a config-fixed default plus per-call overrides. + * + * @module dsh-bash/session-mode + */ + +import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' +import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' + +declare module '@deepseek-ai/dsh-session' { + interface SessionEventMap { + /** + * The session's sandbox mode was switched — log-only (like `approval/*`; + * NOT a surface event, carries no `surfaceOp`): durable and replayable, + * never in the model transcript. The LAST such event is the session's + * override ({@link effectiveSandboxMode}); who asked for it is derivable + * from position (an event after the log's last `request/header*` was a + * runtime switch by the user; see the tool layer's narrator). + */ + 'bash/sandbox-mode': { mode: SandboxMode } + } +} + +/** Every {@link SandboxMode}, for option advertisement and runtime validation of untrusted mode strings. */ +export const SANDBOX_MODES: readonly SandboxMode[] = ['read-only', 'workspace-write', 'danger-full-access'] + +/** + * The session's sandbox-mode override: the last `bash/sandbox-mode` event in + * the log, or undefined when the session never switched (callers apply the + * executor's configured default). The pure fold — resume needs no catch-up + * machinery because replaying the log IS the state. + * @param events - session events in log order (other event types are skipped). + * @returns the mode of the last switch event, or undefined without one. + */ +export function effectiveSandboxMode(events: readonly SessionEvent[]): SandboxMode | undefined { + for (let index = events.length - 1; index >= 0; index -= 1) { + const event = events[index] as SessionEvent + if (event.type === 'bash/sandbox-mode') return event.data.mode + } + return undefined +} + +/** + * THE write path for a session's sandbox-mode override: appends exactly one + * `bash/sandbox-mode` event — the switch IS its event; nothing mutates mode + * state out of band. Takes effect on the session's next bash call and next + * prompt assembly (the consumers fold on every read). + * @param session - the session the override belongs to. + * @param mode - the mode every subsequent bash call in this session runs + * under (until the next switch). + */ +export function setSandboxMode(session: Session, mode: SandboxMode): void { + session.append('bash/sandbox-mode', { mode }) +} diff --git a/packages/bash/bash/src/types.ts b/packages/bash/bash/src/types.ts index 4715ace318..39dbc162c6 100644 --- a/packages/bash/bash/src/types.ts +++ b/packages/bash/bash/src/types.ts @@ -7,6 +7,7 @@ */ import type { Branded } from '@deepseek-ai/dsh-brand' +import type { SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox' /** Identifies one background task within an executor (generated `bash-N`). */ export type BashTaskId = Branded<'BashTaskId'> @@ -40,6 +41,48 @@ export function OwnerToken(id: string): OwnerToken { return id as OwnerToken } +/** + * Sandbox facts for one foreground run — present on {@link BashRunResult} iff + * a sandboxing executor ran the command (an unsandboxed executor reports no + * `sandbox` field at all). Reported independently of `exitCode`/`signal` + * (orthogonal outcomes), so a caller can tell "the command failed on its own" + * from "the sandbox blocked a file operation". The mode/enforcement + * vocabulary lives on the `@deepseek-ai/dsh-sandbox` seam; this shape is the + * bash seam's result-fact carrier for it. + */ +export interface BashSandboxInfo { + /** The mode the command actually ran under. */ + mode: SandboxMode + /** + * True when the executor classifies this run's failure as the sandbox + * denying a file operation. The classification is CONSERVATIVE (a failed + * exit whose stderr carries a filesystem-permission signature) and reads + * the COLLECTED stderr — the bounded in-memory tail per + * {@link CollectedOutput} semantics, so a signature that survives only in a + * spill file is missed toward `denied: false`. A plain command failure + * keeps `denied: false` even under a sandboxed mode. + */ + denied: boolean + /** + * How completely the runner enforced `mode`'s file effects — see + * {@link SandboxEnforcement}. Absent exactly when `mode` is + * `danger-full-access`: nothing is confined, so there is no enforcement to + * report. + */ + enforcement?: SandboxEnforcement + /** + * True when the executor classifies this failure as the SANDBOX RUNNER + * itself failing (missing binary, refused profile, fail-closed refusal + * before exec) — the command NEVER RAN; this is a sandbox failure, not a + * task failure, and it outranks `denied` (a runner's own error text can + * contain denial words). Only ever stamped on settled BACKGROUND tasks: a + * foreground run surfaces the same condition as the thrown + * `SANDBOX_UNAVAILABLE` error instead (the foreground path has an error + * channel; a settled task's facts are its only channel). + */ + runnerFailed?: boolean +} + /** * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and * filled by {@link BashExecutor.resolve} from the implementation's config. @@ -81,6 +124,20 @@ export interface BashExecRequest { * ownerless background start (a non-agent caller). */ owner?: OwnerToken | undefined + /** + * Explicit per-call sandbox-policy input, overriding the executor's + * configured default mode for THIS call. Never a silent default: a + * consumer sets it only from an explicit policy source — an + * `'allowed-once'` grant a human just issued through `ctx.approval` (the + * escalation flow in the sandbox RFC § Escalation, which outranks), or the + * session's standing override folded from its own `bash/sandbox-mode` + * events (the sandbox RFC § Per-session mode switching — the user's recorded per-session + * choice). A sandboxing executor confines THIS call under the given mode; + * a non-sandboxing executor carries the field and confines nothing (the + * tool layer stamps neither escalation nor overrides without a sandboxing + * executor — see {@link BashExecutor.sandboxMode}). + */ + sandboxMode?: SandboxMode | undefined } /** @@ -122,6 +179,16 @@ export interface BashExecSpec { * task. `start()` stores it; `run()` (foreground) ignores it. */ owner: OwnerToken | undefined + /** + * The sandbox mode this call executes under, REQUIRED-but-nullable for the + * same visibility reason as `owner`. A sandboxing executor's `resolve()` + * stamps the effective mode (the request's explicit override, else its + * configured default) so `run()`/`start()` read the spec, never the config; + * a non-sandboxing executor carries the request value through verbatim and + * ignores it (`undefined` under such an executor means what its README says: + * unconfined execution). + */ + sandboxMode: SandboxMode | undefined } /** One captured stream: the (possibly truncated) text plus recovery info. */ @@ -148,6 +215,12 @@ export interface BashRunResult { timeoutMs: number stdout: CollectedOutput stderr: CollectedOutput + /** + * Sandbox facts, present iff a sandboxing executor ran the command — an + * unsandboxed executor (e.g. `dsh-bash-local`) never sets it. See + * {@link BashSandboxInfo} for the `denied` classification semantics. + */ + sandbox?: BashSandboxInfo } /** Lifecycle of a background task. */ @@ -164,6 +237,16 @@ export interface BashTask { signal: NodeJS.Signals | null /** Resolves when the underlying process closes (never rejects). */ readonly done: Promise + /** + * Sandbox facts for this task's execution, stamped by a sandboxing executor + * once the task settles and BEFORE completion listeners are notified — an + * `onTaskDone` consumer and a `done` awaiter both see it. Denial + * classification runs against the settled task's collected stderr, so the + * field cannot exist earlier: absent while the task is running and under an + * executor that does not sandbox. See {@link BashSandboxInfo} for the + * `denied` semantics. + */ + sandbox?: BashSandboxInfo } /** One incremental {@link BashExecutor.readOutput} read. */ diff --git a/packages/bash/bash/tests/service.spec.ts b/packages/bash/bash/tests/service.spec.ts index 81530843ed..94d299f175 100644 --- a/packages/bash/bash/tests/service.spec.ts +++ b/packages/bash/bash/tests/service.spec.ts @@ -15,6 +15,7 @@ class StubExecutor extends BashExecutor { timeoutMs: request.timeoutMs ?? 1000, ...request.signal ? { signal: request.signal } : {}, owner: request.owner, + sandboxMode: request.sandboxMode, } } @@ -96,6 +97,11 @@ describe('BashExecutor service seam', () => { expect(result.exitCode).toBe(0) }) + it('reports no default sandbox mode (composition truth: the base never confines)', async () => { + const { bash } = await setup() + expect(bash.sandboxMode).toBeUndefined() + }) + it('onTaskDone delivers completions to registered listeners', async () => { const { bash } = await setup() const seen: string[] = [] diff --git a/packages/bash/bash/tsconfig.json b/packages/bash/bash/tsconfig.json index 342f636170..13d297a292 100644 --- a/packages/bash/bash/tsconfig.json +++ b/packages/bash/bash/tsconfig.json @@ -16,6 +16,12 @@ }, { "path": "../../util/brand" + }, + { + "path": "../../sandbox/sandbox" + }, + { + "path": "../../core/session" } ] } diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md index 40918ccefb..4bbfff2f6a 100644 --- a/packages/bash/tool-bash/README.md +++ b/packages/bash/tool-bash/README.md @@ -4,7 +4,7 @@ The model-facing bash tools — `bash`, `bash_output`, `bash_kill` — registere Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`). -The plugin also contributes the `tool:bash` prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the `[exit code: N]` marker on every result and investigate failures before moving on. +The plugin also contributes the `tool:bash` prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the `[exit code: N]` marker on every result and investigate failures before moving on. Under a sandboxing executor it additionally contributes the per-agent `env:bash-sandbox` section (order 110) stating each session's EFFECTIVE mode, and the pre-step narrator — see [Per-session mode](#per-session-mode-switching-and-visibility). ## Tools @@ -17,6 +17,8 @@ The plugin also contributes the `tool:bash` prompt section (order 105) — the c | `timeoutMs` | number | Timeout override in milliseconds. The executor applies its configured default and cap. | | `workdir` | string | Working directory for this call. Defaults to the calling agent's session cwd (`session.header.cwd`) so each session runs in its own workspace; a relative `workdir` is resolved against that session cwd. | | `run_in_background` | boolean | Return a task id immediately; no timeout applies. | +| `sandbox_permissions` | string enum | ADVERTISED ONLY when the mounted executor sandboxes (`ctx.bash.sandboxMode` reports a confining default): the wider mode a denied command needs, from the closed target vocabulary `workspace-write`/`danger-full-access` (never cut down to the executor's default — the effective mode is per-session; strict widening is checked at execution against it, and a non-widening request fails without prompting anyone). | +| `justification` | string | Required together with `sandbox_permissions` (each without the other is a validation error): one sentence for the user explaining why this exact command needs the wider access. | `command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the executor seam (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer (from the calling agent's `session.header.cwd`) BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`. @@ -26,11 +28,11 @@ Every foreground and background call made for an agent receives `DSH_SESSION_ID= The overlay is computed from `ToolExecution.agent` for each call and passed through `BashExecRequest.env`; `process.env` is never modified, so concurrent parent/child agents keep separate values. The tool description names both variables so the model can inspect them without a permanent system-prompt section. -Result text: stdout, then a `[stderr]` section, then status markers — `[timed out after Nms]` whenever the executor's timer fired (reported independently of how the process ended, so a command that traps SIGTERM and exits 0 still shows it), `[killed by signal: …]` for a signal death, `[exit code: N]` for a non-zero exit (reported, **not** `isError`: the model decides how to react), and `[output truncated; full output: ]` when the tail was kept and a safe spill file is available. If the executor knows output was dropped but cannot safely advertise a complete spill file, the path is reported as `(unavailable)`. Only infrastructure failures (spawn errors, aborts) surface as `isError` results. +Result text: stdout, then a `[stderr]` section, then status markers — `[sandbox: file access denied under mode]` when a sandboxing executor classified the failure as a policy denial (reported first so `[exit code: N]` stays the last line; the static description tells the model a denial is policy, not a command bug, and forbids retrying around it), `[timed out after Nms]` whenever the executor's timer fired (reported independently of how the process ended, so a command that traps SIGTERM and exits 0 still shows it), `[killed by signal: …]` for a signal death, `[exit code: N]` for a non-zero exit (reported, **not** `isError`: the model decides how to react), and `[output truncated; full output: ]` when the tail was kept and a safe spill file is available. If the executor knows output was dropped but cannot safely advertise a complete spill file, the path is reported as `(unavailable)`. Only infrastructure failures (spawn errors, aborts) surface as `isError` results. ### `bash_output` -`task_id` → output produced **since the previous `bash_output` call** plus a status line (`running` / `completed, exit code: N` / `killed`). Reads that lost data to buffer bounds say so and point at the full-output spill file when one is safely available, otherwise `(unavailable)`. +`task_id` → output produced **since the previous `bash_output` call** plus a status line (`running` / `completed, exit code: N` / `killed`). A settled task classified as a sandbox denial carries the same `[sandbox: file access denied under mode]` marker on every read that sees it (denials are only classifiable once the whole stderr has been collected). Reads that lost data to buffer bounds say so and point at the full-output spill file when one is safely available, otherwise `(unavailable)`. ### `bash_kill` @@ -52,6 +54,12 @@ When a background task finishes, a short notice is injected into the owning agen The `BashExecRequest` seam carries optional `stdin` and `env`, used by trusted consumers. This tool does **not** expose them as model parameters: it builds the request from named schema fields and adds only the session overlay above, so model-supplied `env`/`stdin` keys are ignored and cannot replace the trusted values. This is not a trust boundary — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), and the real defense against leaking ambient secrets is `dsh-bash-local`'s credential scrub. Regression guards assert extra model fields never enter the request while the trusted overlay still does. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md). -## Permissions +## Permissions and escalation -`TODO(permissions)`: commands run with the executor's full authority. The permission/sandbox seam is the `tools/pre-execute` waterfall (deny or ask) plus sandboxing `BashExecutor` implementations — see docs/architecture.md. `@cordisjs/plugin-capability` (a named-permission service with a session `test()`) is a candidate building block for that work. +Commands run with the executor's full authority unless a sandboxing executor ([`dsh-bash-sandbox`](../bash-sandbox/)) confines them — the deny-only sandbox reports denials as result facts, rendered here as the denial marker; per-call allow/deny/ask policy is the `tools/pre-execute` waterfall (see docs/architecture.md). + +On top of a denial sits the escalation gate ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): an escalating call (`sandbox_permissions` + `justification`) resolves [`ctx.approval`](../../ui/user-approval/README.md) BEFORE anything executes — `allowed-once` stamps the granted mode onto the bash request as the seam-level `sandboxMode` override (that one call runs, classifies, and reports under the wider mode; its neighbors keep the session's effective mode), while `rejected`/`cancelled`/`unavailable` and the no-service / no-agent paths each fail closed with their own error text and execute nothing. The seam is consumed opportunistically (`ctx.get('approval')`, the dsh-tools ask-routing pattern); the grant is consumed by the very call that asked, and nothing is stored. The static description teaches — and a denied result itself prompts, via the escalation-available marker appended exactly when the fields are advertised — the SAME-TURN flow: on a denial a wider mode would cure, retry the exact command once with `sandbox_permissions` (the narrowest mode that suffices) + `justification` immediately, without detouring through chat (the approval prompt IS the user's consent); never speculatively — an escalation is grounded in a real denial (up-front only when the session already denied the same access), a prompt-stated approvals-disabled policy turns the exception off entirely, and a rejected escalation is final for that command. + +## Per-session mode switching + +Under a sandboxing executor this plugin makes the session's standing mode override ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md); the `bash/sandbox-mode` fold owned by [`dsh-bash`](../bash/README.md)) real at EXECUTION: every call is stamped `escalation grant > session override > undefined` onto `BashExecRequest.sandboxMode`; without either, the executor's `resolve()` applies its configured default. Nothing is stamped under a non-sandboxing executor (nothing would honor it) or for an agent-less caller (no session to fold). The prompt deliberately does NOT state the mode and a switch is not narrated: a standing declaration teaches the model to refuse preemptively, while the denial marker already names the mode the command ran under exactly when the boundary is hit — behavior, not belief, carries the state. diff --git a/packages/bash/tool-bash/package.json b/packages/bash/tool-bash/package.json index fabbdea076..d4d24aa098 100644 --- a/packages/bash/tool-bash/package.json +++ b/packages/bash/tool-bash/package.json @@ -23,9 +23,11 @@ "license": "BSD-3-Clause", "peerDependencies": { "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-user-approval": "^0.0.1", "@deepseek-ai/dsh-bash": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-session-persistence": "^0.0.1", + "@deepseek-ai/dsh-sandbox": "^0.0.1", "@deepseek-ai/dsh-system-prompt": "^0.0.1", "@deepseek-ai/dsh-tools": "^0.0.1", "cordis": "^4.0.0-rc.6" @@ -33,9 +35,13 @@ "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", + "@deepseek-ai/dsh-user-approval": "workspace:^", "@deepseek-ai/dsh-bash": "workspace:^", "@deepseek-ai/dsh-bash-local": "workspace:^", + "@deepseek-ai/dsh-bash-sandbox": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-sandbox": "workspace:^", + "@deepseek-ai/dsh-sandbox-local": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts index 777332b7c3..b76e2478c8 100644 --- a/packages/bash/tool-bash/src/index.ts +++ b/packages/bash/tool-bash/src/index.ts @@ -30,10 +30,27 @@ * completion landing during the reload gap still drops its one notice — the * pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.) * - * TODO(permissions): commands run with the executor's full authority. The - * permission/sandbox seam is the `tools/pre-execute` waterfall (deny/ask) plus - * sandboxing `BashExecutor` implementations — see docs/architecture.md - * § Extending The Harness. + * Commands run with the executor's full authority unless a sandboxing + * executor (`@deepseek-ai/dsh-bash-sandbox`) confines them; per-call + * allow/deny/ask policy is the `tools/pre-execute` waterfall — see + * docs/architecture.md § Extension And Composition. Under a sandboxing + * executor this plugin also advertises the ESCALATION surface + * (`sandbox_permissions`/`justification` — the sandbox RFC § Escalation, + * docs/rfc/implemented/feature/2026-07-06-sandbox.md): a command the + * sandbox denied may be retried once under a strictly wider mode, resolved + * through `ctx.approval` BEFORE anything executes and failing closed on every + * unanswerable path. The fields exist only when the mounted executor reports + * a confining default (`ctx.bash.sandboxMode`) — a lever is never advertised + * that the composition cannot honor. + * + * Per-session mode switching (the sandbox RFC § Per-session mode switching): a session may carry a + * standing sandbox-mode override — the `bash/sandbox-mode` event fold from + * `@deepseek-ai/dsh-bash` — which this plugin makes real at EXECUTION: each + * call is stamped `escalation grant > session override > executor default`. + * The prompt deliberately does NOT state the mode and no switch is narrated: + * the model learns the boundary from the denial marker (which names the mode + * it ran under) exactly when it matters, instead of preemptively refusing + * work a standing declaration would discourage. * * @module @deepseek-ai/dsh-tool-bash */ @@ -41,11 +58,17 @@ import type { Context } from 'cordis' import { isAbsolute, resolve as resolvePath } from 'node:path' import { defineTool } from '@deepseek-ai/dsh-tools' -import type { GenericCallView, TerminalCallView, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools' +import type { GenericCallView, TerminalCallView, ToolExecution, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools' import type { Agent } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-session-persistence' +import { assertNever } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-system-prompt' -import { BashTaskId, OwnerToken } from '@deepseek-ai/dsh-bash' +// Side-effect type import: declaration-merges `ctx.approval`, consumed +// opportunistically by the escalation gate (`ctx.get('approval')` — the seam +// stays optional at runtime, same pattern as dsh-tools' ask routing). +import type {} from '@deepseek-ai/dsh-user-approval' +import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' +import { BashTaskId, OwnerToken, effectiveSandboxMode } from '@deepseek-ai/dsh-bash' import type { BashRunResult, BashTask, CollectedOutput } from '@deepseek-ai/dsh-bash' export const name = 'tool-bash' @@ -56,16 +79,12 @@ export const inject = ['tools', 'bash', 'systemPrompt'] * validates parsed args against the SchemaSpec before `execute` runs (the * arg-validation RFC), so type/required/enum checks are already done and `args` * is the validated `InferArgs` shape here. What remains are value constraints - * the DSL has no vocabulary for: non-empty strings and a positive, finite - * timeout. + * the DSL has no vocabulary for: non-empty strings, a positive finite timeout, + * and the escalation pairing (`sandbox_permissions` and `justification` travel + * together — an approval prompt without a reason, or a reason driving nothing, + * is a malformed ask). */ -function validateBashArgs(args: { - command: string - description: string - timeoutMs?: number - workdir?: string - run_in_background?: boolean -}): void { +function validateBashArgs(args: BashToolArgs): void { if (args.command.trim().length === 0) { throw new Error('invalid command: expected a non-empty string') } @@ -75,6 +94,15 @@ function validateBashArgs(args: { if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) { throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`) } + if (args.sandbox_permissions !== undefined && args.justification === undefined) { + throw new Error('invalid escalation: sandbox_permissions requires a justification') + } + if (args.justification !== undefined && args.sandbox_permissions === undefined) { + throw new Error('invalid escalation: justification is only valid together with sandbox_permissions') + } + if (args.justification !== undefined && args.justification.trim().length === 0) { + throw new Error('invalid justification: expected a non-empty sentence') + } } /** @@ -89,6 +117,77 @@ function validateTaskId(value: string): BashTaskId { return BashTaskId(value) } +/** + * The bash tool's validated argument shape — the base parameters plus the two + * escalation fields, which are ADVERTISED only when the mounted executor + * reports a confining default mode (absent from the schema otherwise, so the + * SchemaSpec validator rejects them before `execute` ever sees one). + */ +interface BashToolArgs { + command: string + description: string + timeoutMs?: number + workdir?: string + run_in_background?: boolean + sandbox_permissions?: string + justification?: string +} + +/** + * The strictly-wider table: what a call whose effective mode is the key may + * escalate TO. Checked at EXECUTION, never baked into the schema — the + * schema's enum is {@link ESCALATION_TARGETS}, because schemas are + * registry-global while the effective mode is per-call truth. + */ +const WIDER_MODES: Record = { + 'read-only': ['workspace-write', 'danger-full-access'], + 'workspace-write': ['danger-full-access'], +} + +/** + * The closed escalation-target vocabulary — every mode a call could ever + * escalate TO (`read-only` is the floor; nothing escalates to it). Advertised + * whenever the mounted executor confines: cutting the enum down to the modes + * wider than the executor's DEFAULT would strand a session whose effective + * mode sits below it (a `danger-full-access` default would advertise nothing + * while a narrower-switched session stays confined with no lever). + */ +const ESCALATION_TARGETS: readonly SandboxMode[] = ['workspace-write', 'danger-full-access'] + +/** + * The bash tool's static description. The base text is byte-stable regardless + * of composition (it is part of the pinned snapshot header); the escalation + * teaching rides only when the mounted executor actually honors the fields — + * it names the ONE sanctioned exception to the base text's "do not retry + * another way" rule. Its deference clause ("If the session states approval + * prompts are disabled…") points at the approval plugin's never-policy prompt + * sentence by meaning, not by parsed wording — a rendezvous kept working by + * that sentence continuing to open with the approvals-disabled claim. + */ +function bashDescription(escalationModes: readonly SandboxMode[]): string { + const base = 'Execute a bash command (`bash -c`) and return its stdout/stderr. ' + + 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — ' + + 'pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. ' + + 'The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, ' + + '`$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. ' + + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). ' + + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. ' + + 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; ' + + 'poll it with `bash_output` and stop it with `bash_kill`.' + if (escalationModes.length === 0) return base + return base + ' Attempting a command the sandbox may deny is safe and expected: run it and read the ' + + 'marker rather than assuming the denial. When a command IS denied and a wider mode would let it ' + + 'succeed, escalate immediately in the SAME turn — the ONE sanctioned exception to a denial: retry ' + + 'the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) ' + + 'plus a one-sentence `justification`. Do not detour through chat to ask permission first — the ' + + 'approval prompt raised by that retry IS how the user consents. If the session states approval ' + + 'prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. ' + + 'Never escalate speculatively: ground the request in a real denial — normally the one THIS command ' + + 'just hit; escalating up front is fine only when this session already denied the same access. ' + + 'A rejected escalation is final for THAT command — stop and explain, never work around ' + + 'it — but it does not forbid attempting or escalating other commands later.' +} + /** Append the truncation notice (with the full-output spill path) to a stream's text. */ function streamText(output: CollectedOutput): string { if (!output.truncated) return output.text @@ -101,9 +200,15 @@ function streamText(output: CollectedOutput): string { * errored — the model decides how to react; only infrastructure failures * (spawn errors, aborts) surface as isError results. * @param result - the completed foreground run from the executor. + * @param escalationModes - the escalation targets this composition advertises; + * non-empty adds the same-turn escalation hint after a denial marker + * (default `[]`: no hint). * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line. */ -export function renderResult(result: BashRunResult): string { +export function renderResult( + result: BashRunResult, + escalationModes: readonly SandboxMode[] = [], +): string { const out = streamText(result.stdout) const err = streamText(result.stderr) @@ -116,6 +221,19 @@ export function renderResult(result: BashRunResult): string { if (body.length === 0) body = '(no output)' const markers: string[] = [] + // The sandbox marker precedes the exit-status markers so `[exit code: N]` + // stays the LAST line (exitStatus() anchors its parse there). Denial is a + // reported fact like timeout: the model decides how to react. + if (result.sandbox?.denied) { + markers.push(`[sandbox: file access denied under ${result.sandbox.mode} mode]`) + // The same-turn nudge lives at the decision point: only when this + // composition advertises the fields (a lever is never hinted that the + // schema does not offer), and inside the sandbox marker family so the + // exit-code marker stays the last line. + if (escalationModes.length > 0) { + markers.push('[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]') + } + } // Timeout is reported independently of how the process actually ended: a // command can trap SIGTERM and exit 0 after our timer fired (e.g. // `trap "exit 0" TERM; sleep 60`), giving timedOut:true / exitCode:0 / @@ -372,16 +490,87 @@ export function apply(ctx: Context): void { } }) + // The escalation surface exists whenever the mounted executor confines. + // Its enum is the closed target vocabulary, deliberately NOT cut down by + // the configured default: a session may switch to a narrower effective mode + // while sharing this globally registered schema. Strict widening therefore + // belongs to the per-call check below. An executor swap restarts this fiber + // (static inject) and re-registers the schema. + const defaultMode = ctx.bash.sandboxMode + const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS + + /** + * The session's standing mode override for an ordinary (non-escalating) + * call: the `bash/sandbox-mode` fold of the calling agent's log, stamped + * onto the request so EXECUTION follows the same effective mode the prompt + * section states. Weakest precedence — an escalation grant (freshly + * approved for exactly this call) outranks it, and without either the + * executor's `resolve()` applies its configured default. Undefined for a + * non-sandboxing executor (nothing honors it) and for agent-less callers + * (no session to fold). + */ + const sessionOverride = (exec: ToolExecution): SandboxMode | undefined => + defaultMode === undefined || exec.agent === undefined ? undefined : effectiveSandboxMode(exec.agent.session.events) + + /** + * Resolve a sandbox-escalation request through `ctx.approval` BEFORE + * anything executes. Returns the granted mode to stamp onto the bash + * request; throws the distinct fail-closed text for every other path (no + * service composed, an agent-less execution, a rejection, a cancellation, + * an unanswerable ask) — the registry turns the throw into this call's + * isError result, and nothing has run. The seam is consumed + * opportunistically (`ctx.get`, the dsh-tools ask-routing pattern), so a + * deployment without it degrades per call, never at registration. + */ + const approveEscalation = async (mode: string, justification: string, exec: ToolExecution): Promise => { + // Schema validation only checks ADVERTISED keys, so an unadvertised + // `sandbox_permissions` (no sandboxing executor) still reaches execute — reject it here so a + // human is never prompted to "escalate" a sandbox that is not there. When + // the fields ARE advertised, the registry's SchemaSpec enum has already + // pinned `mode` to this ladder for every caller. + if (escalationModes.length === 0) { + throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)') + } + // Strict widening is an EXECUTION check against the call's effective + // mode — session override ?? executor default, the same fold ordinary + // calls are stamped with — deliberately not a schema constraint (the + // enum is the closed target vocabulary; the effective mode is per-call + // truth). A non-widening request fails closed here and never prompts a + // human. + const effectiveMode = (sessionOverride(exec) ?? defaultMode) as SandboxMode + if (!(WIDER_MODES[effectiveMode] ?? []).includes(mode as SandboxMode)) { + throw new Error(`sandbox escalation to "${mode}" is not strictly wider than this call's current "${effectiveMode}" mode`) + } + const approval = ctx.get('approval') + if (approval === undefined) { + throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval service is composed`) + } + if (exec.agent === undefined) { + throw new Error(`sandbox escalation to "${mode}" requires approval, but the call has no agent to route it through`) + } + const outcome = await approval.request({ + agent: exec.agent, + toolName: 'bash', + callId: exec.callId, + // Self-contained for the audit trail: approval/asked stores this + // reason, and the target mode is part of the grant's identity. + reason: `escalate sandbox to ${mode}: ${justification}`, + ...exec.signal ? { signal: exec.signal } : {}, + }) + switch (outcome) { + // The SchemaSpec enum already pinned `mode` to the closed target + // vocabulary; the per-call check above proved it is strictly wider. + case 'allowed-once': return mode as SandboxMode + case 'rejected': throw new Error(`the user rejected escalating this command to "${mode}"`) + case 'cancelled': throw new Error(`approval for escalating to "${mode}" was cancelled`) + case 'unavailable': throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval channel is available`) + default: return assertNever(outcome, 'ApprovalOutcome') + } + } + ctx.tools.register(defineTool({ name: 'bash', - description: 'Execute a bash command (`bash -c`) and return its stdout/stderr. ' - + 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — ' - + 'pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. ' - + 'The current agent session id is available as `$DSH_SESSION_ID`; when JSONL persistence is configured, ' - + '`$DSH_SESSION_JSONL` is its absolute target path and may not exist or contain the current unflushed turn yet. ' - + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. ' - + 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; ' - + 'poll it with `bash_output` and stop it with `bash_kill`.', + description: bashDescription(escalationModes), parameters: { command: { type: 'string', required: true, description: 'The bash command to execute.' }, description: { @@ -394,12 +583,33 @@ export function apply(ctx: Context): void { timeoutMs: { type: 'number', description: 'Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry.' }, workdir: { type: 'string', description: 'Working directory for this command. Defaults to the session workspace; a relative path is resolved against it.' }, run_in_background: { type: 'boolean', description: 'Run in the background and return a task id immediately. No timeout applies.' }, + ...escalationModes.length > 0 ? { + sandbox_permissions: { + type: 'string' as const, + enum: [...escalationModes], + description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry ' + + 'of a command the sandbox just denied; requires justification and user approval.', + }, + justification: { + type: 'string' as const, + description: 'Required with sandbox_permissions: one sentence for the user explaining ' + + 'why this exact command needs the wider access.', + }, + } : {}, }, - async execute(args, exec) { + async execute(args: BashToolArgs, exec) { validateBashArgs(args) // `description` is display/logging metadata only (surfaced to UIs via // the tool/call session event); it is intentionally NOT forwarded to // ctx.bash and has no effect on execution. + // An escalating call resolves approval BEFORE anything executes; every + // non-grant outcome throws its distinct error text and runs nothing. + // (validateBashArgs pinned the pairing, so the double narrow is exact.) + // An ordinary call carries the session's standing override instead — + // grant > session override > executor default (see sessionOverride). + const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined + ? await approveEscalation(args.sandbox_permissions, args.justification, exec) + : sessionOverride(exec) // Default the workdir to the calling agent's session cwd so each ACP // session runs in its own workspace (see resolveWorkdir); an explicit // model workdir still wins. @@ -411,6 +621,7 @@ export function apply(ctx: Context): void { ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}, ...exec.signal ? { signal: exec.signal } : {}, ...env !== undefined ? { env } : {}, + ...sandboxMode !== undefined ? { sandboxMode } : {}, } if (args.run_in_background === true) { // Stamp the owner token (the agent's session id) onto the spec so the @@ -422,7 +633,7 @@ export function apply(ctx: Context): void { } const result = await ctx.bash.run(ctx.bash.resolve(request)) if (result.aborted) throw new Error('command aborted') - return [{ type: 'text', text: renderResult(result) }] + return [{ type: 'text', text: renderResult(result, escalationModes) }] }, presentCall: presentBashCall, presentResult: presentBashResult, @@ -449,6 +660,21 @@ export function apply(ctx: Context): void { text += `\n[some output was dropped from memory; full output: ${fullOutput}]` } text += `\n${statusLine(read.task)}` + if (read.task.sandbox?.runnerFailed) { + // The sandbox RUNNER itself failed — the command never ran. The + // foreground path surfaces this as the structured SANDBOX_UNAVAILABLE + // error; a settled task's read carries the marker instead. + text += `\n[sandbox: the sandbox runner itself failed under ${read.task.sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]` + } else if (read.task.sandbox?.denied) { + // Mirrors the foreground result marker (and its same-turn escalation + // hint). Background denials are only classifiable once the task + // settles (the classifier needs the whole stderr), so the marker + // rides every read that sees the settled task. + text += `\n[sandbox: file access denied under ${read.task.sandbox.mode} mode]` + if (escalationModes.length > 0) { + text += '\n[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]' + } + } return Promise.resolve([{ type: 'text', text }]) }, presentCall: args => presentTaskCall('Read output from', args), diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts index 5539787399..44eca86c0e 100644 --- a/packages/bash/tool-bash/tests/tools.spec.ts +++ b/packages/bash/tool-bash/tests/tools.spec.ts @@ -1,11 +1,12 @@ -import { mkdtempSync } from 'node:fs' +import { chmodSync, mkdirSync, mkdtempSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import { CallId } from '@deepseek-ai/dsh-llm' -import { BashExecutor, BashTaskId } from '@deepseek-ai/dsh-bash' +import { BashExecutor, BashTaskId, setSandboxMode } from '@deepseek-ai/dsh-bash' import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash' +import { Session, SessionId } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' @@ -13,11 +14,29 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import SessionStore from '@deepseek-ai/dsh-session' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' +import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox' +import { SandboxProvider } from '@deepseek-ai/dsh-sandbox' +import type { ConfinedArgv } from '@deepseek-ai/dsh-sandbox' +import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local' +import ApprovalService from '@deepseek-ai/dsh-user-approval' +import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval' import * as ToolBash from '@deepseek-ai/dsh-tool-bash' import { renderResult } from '@deepseek-ai/dsh-tool-bash' const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-spec-')) +// Pure-config passthrough runner (same knob the snapshot tier uses): skips the +// profile args up to `--` and execs the command unconfined — deterministic +// without a host bwrap. +const PASSTHROUGH_RUNNER = ['bash', '-c', 'while [ "$1" != "--" ]; do shift; done; shift; exec "$@"', 'passthrough-runner'] +const PASSTHROUGH_RUNNER_CONFIG = { + runnerCommand: PASSTHROUGH_RUNNER, + // The script has no pre-exec failure path; the provider still requires an + // explicit dialect so a future script change cannot silently turn runner + // failure into an ordinary command result. + runnerFailureSignatures: ['passthrough-runner: profile rejected'], +} + async function setup() { const ctx = new Context() await ctx.plugin(SystemPrompt) @@ -102,6 +121,7 @@ class LossyReadBashExecutor extends BashExecutor { timeoutMs: request.timeoutMs ?? 0, ...request.signal ? { signal: request.signal } : {}, owner: request.owner, + sandboxMode: request.sandboxMode, } } @@ -896,6 +916,7 @@ describe('the model-facing bash tool builds its request from named args only (no ...request.stdin !== undefined ? { stdin: request.stdin } : {}, ...request.env !== undefined ? { env: request.env } : {}, owner: request.owner, + sandboxMode: request.sandboxMode, } } run(): Promise { @@ -1067,3 +1088,512 @@ describe('the model-facing bash tool builds its request from named args only (no expect('owner' in request).toBe(true) }) }) + +describe('sandbox rendering', () => { + const sandboxResult = (denied: boolean, exitCode: number): BashRunResult => ({ + exitCode, + signal: null, + timedOut: false, + aborted: false, + timeoutMs: 1000, + stdout: { text: '', truncated: false }, + stderr: { text: denied ? 'bash: /x: Read-only file system' : 'boom', truncated: false }, + sandbox: { mode: 'read-only', denied }, + }) + + it('renders a denial marker BEFORE the exit-code marker (the $-anchored parse survives)', () => { + const text = renderResult(sandboxResult(true, 1)) + expect(text).toMatch(/\[sandbox: file access denied under read-only mode\]\n\[exit code: 1\]$/) + }) + + it('appends the same-turn escalation hint to a denial exactly when the fields are advertised', () => { + const hinted = renderResult(sandboxResult(true, 1), ['workspace-write', 'danger-full-access']) + expect(hinted).toMatch( + /denied under read-only mode\]\n\[sandbox: escalation available — retry this exact command once with sandbox_permissions [^\n]+\]\n\[exit code: 1\]$/, // eslint-disable-line @stylistic/max-len -- the hint sentence is pinned verbatim + ) + // Default (no advertisement): no hint — a lever the schema does not offer is never suggested. + expect(renderResult(sandboxResult(true, 1))).not.toContain('escalation available') + // A non-denied result never hints, advertised or not. + expect(renderResult(sandboxResult(false, 2), ['danger-full-access'])).not.toContain('escalation available') + }) + + it('renders no sandbox marker for a plain failure under a sandboxed mode', () => { + expect(renderResult(sandboxResult(false, 2))).not.toContain('[sandbox:') + }) + + it('bash_output reports a settled background denial with the same marker', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG) + await ctx.plugin(SandboxBashExecutor, { graceMs: 200 }) + const bash = ctx.bash as SandboxBashExecutor + bash.internals = { spillDir } + await ctx.plugin(ToolBash) + const started = await call(ctx, 'bash', { command: 'echo "x: Permission denied" >&2; exit 1', description: 'test command', run_in_background: true }) + const id = text(started).match(/started background task (bash-\d+)/)![1] + await bash.list().find(task => task.id === id)!.done + const read = await call(ctx, 'bash_output', { task_id: id }) + expect(text(read)).toMatch( + /\[status: completed, exit code: 1\]\n\[sandbox: file access denied under read-only mode\]\n\[sandbox: escalation available[^\n]+\]$/, + ) + }) + + it('a settled background denial renders no escalation hint without a confining executor (defensive arm)', async () => { + // Structurally near-unreachable through the real stack — every confining + // default advertises the static target set — but the read path guards + // it anyway: an executor that reports no sandboxMode (fields never + // advertised) whose task nonetheless carries denial facts must render + // the marker without suggesting a lever the schema does not offer. + class FactsOnlyExecutor extends BashExecutor { + private readonly task: BashTask = { + id: BashTaskId('bash-facts'), + command: 'fake', + status: 'completed', + exitCode: 1, + signal: null, + done: Promise.resolve(), + sandbox: { mode: 'read-only', denied: true }, + } + + resolve(request: BashExecRequest): BashExecSpec { + return { + command: request.command, + workdir: request.workdir ?? process.cwd(), + timeoutMs: request.timeoutMs ?? 0, + ...request.signal ? { signal: request.signal } : {}, + owner: request.owner, + sandboxMode: request.sandboxMode, + } + } + + run(): Promise { return Promise.reject(new Error('not used')) } + start(): BashTask { return this.task } + get(id: string): BashTask | undefined { return id === this.task.id ? this.task : undefined } + list(): BashTask[] { return [this.task] } + kill(): boolean { return false } + ownerOf(): OwnerToken | undefined { return undefined } + readOutput(): BashTaskRead { + return { task: this.task, delta: '', lossy: false } + } + } + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(FactsOnlyExecutor) + await ctx.plugin(ToolBash) + const read = await call(ctx, 'bash_output', { task_id: 'bash-facts' }) + expect(text(read)).toMatch(/\[sandbox: file access denied under read-only mode\]$/) + expect(text(read)).not.toContain('escalation available') + }) + + it('bash_output reports a settled background RUNNER failure as a sandbox problem, outranking the denial marker', async () => { + // A provider whose wrap carries a runner-failure signature: the settled + // task's stderr matching it means the sandbox itself broke and the + // command never ran — even though the same stderr also carries denial + // words (a runner's error text may contain them). + class FakeProvider extends SandboxProvider { + confine(argv: readonly string[]): ConfinedArgv { + return { argv: [...argv], enforcement: 'full', denialSignatures: ['permission denied'], runnerFailureSignatures: ['fake-runner: '] } + } + } + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(FakeProvider) + await ctx.plugin(SandboxBashExecutor, { graceMs: 200 }) + const bash = ctx.bash as SandboxBashExecutor + bash.internals = { spillDir } + await ctx.plugin(ToolBash) + const started = await call(ctx, 'bash', { command: 'echo "fake-runner: cannot open rule path: /x: Permission denied" >&2; exit 125', description: 'test command', run_in_background: true }) + const id = text(started).match(/started background task (bash-\d+)/)![1] + await bash.list().find(task => task.id === id)!.done + const read = await call(ctx, 'bash_output', { task_id: id }) + expect(text(read)).toMatch(/\[sandbox: the sandbox runner itself failed under read-only mode — the command did not run; /) + expect(text(read)).toMatch(/this is a sandbox problem, not a command failure\]$/) + expect(text(read)).not.toContain('file access denied') + }) + + it('classifies an executable configured runner that refuses its profile before the command runs', async () => { + const signature = 'custom-runner-rejected' + const ctx = new Context() + await ctx.plugin(LocalSandboxProvider, { + runnerCommand: ['bash', '-c', `printf '${signature}\\n' >&2; exit 125`, 'custom-runner'], + runnerFailureSignatures: [signature], + }) + await ctx.plugin(SandboxBashExecutor, { graceMs: 200 }) + const bash = ctx.bash as SandboxBashExecutor + bash.internals = { spillDir } + + await expect(bash.run(bash.resolve({ command: 'echo command-must-not-run' }))) + .rejects.toMatchObject({ code: 'SANDBOX_UNAVAILABLE' }) + + const task = bash.start(bash.resolve({ command: 'echo command-must-not-run' })) + await task.done + expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full', runnerFailed: true }) + }) + + it('reports a real denial end-to-end through the shipping sandbox executor', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG) + await ctx.plugin(SandboxBashExecutor, { graceMs: 200 }) + const bash = ctx.bash as SandboxBashExecutor + bash.internals = { spillDir } + await ctx.plugin(ToolBash) + const lockedDir = join(mkdtempSync(join(tmpdir(), 'dsh-tool-bash-denied-')), 'locked') + mkdirSync(lockedDir) + chmodSync(lockedDir, 0o555) + const result = await call(ctx, 'bash', { command: `echo x > ${lockedDir}/f`, description: 'Write into a locked directory' }) + expect(result.isError).toBe(false) + expect(text(result)).toMatch( + /denied under read-only mode\]\n\[sandbox: escalation available[^\n]+\]\n\[exit code: \d+\]$/, + ) + }) +}) + +describe('sandbox escalation (sandbox_permissions / justification)', () => { + /** Compose the real sandbox stack (passthrough runner) at a given default mode. */ + async function setupSandboxed(mode?: 'read-only' | 'workspace-write' | 'danger-full-access', opts: { approval?: boolean; policy?: 'ask' | 'never' } = {}) { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG) + await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...mode !== undefined ? { mode } : {} }) + const bash = ctx.bash as SandboxBashExecutor + bash.internals = { spillDir } + if (opts.approval === true) await ctx.plugin(ApprovalService, opts.policy !== undefined ? { policy: opts.policy } : {}) + await ctx.plugin(ToolBash) + return { ctx, bash } + } + + /** The registered bash tool's wire schema (what the model actually sees). */ + function bashSchema(ctx: Context) { + const schema = ctx.tools.schemas().find(s => s.name === 'bash') + if (!schema) throw new Error('bash tool not registered') + return schema as unknown as { description: string; parameters: { properties: Record } } + } + + /** + * A fake agent whose session records appends — the approval audit surface. + * Seeded mid-turn: an escalating call always runs inside one, and request() + * enforces the enclosure. + */ + function escalationAgent(events: Array<{ type: string; data: Record }>): Agent { + return { + id: 'agent-esc', + session: { + header: { version: 0, id: 'sess-esc', createdAt: 0 }, + events: [{ type: 'turn/start' }], + append: (type: string, data: Record) => { events.push({ type, data }) }, + }, + } as unknown as Agent + } + + let escCall = 0 + function callAs(ctx: Context, agent: Agent | undefined, args: unknown) { + return ctx.tools.execute({ callId: CallId(`call-esc-${++escCall}`), name: 'bash', arguments: args, ...agent ? { agent } : {} }) + } + + const ESCALATE = { command: 'true', description: 'test escalation', sandbox_permissions: 'workspace-write', justification: 'the test needs it' } + + it('advertises no escalation surface under a non-sandboxing executor', async () => { + const ctx = await setup() + expect(ctx.bash.sandboxMode).toBeUndefined() + const schema = bashSchema(ctx) + expect(schema.parameters.properties['sandbox_permissions']).toBeUndefined() + expect(schema.parameters.properties['justification']).toBeUndefined() + expect(schema.description).not.toContain('sanctioned exception') + }) + + it('advertises the full closed target vocabulary under any confining default', async () => { + // The enum is deliberately NOT default-relative: a session's effective + // mode is per-session and switchable, so every confining composition + // advertises every possible target — strict widening is checked at + // execution against the call's effective mode instead. + for (const mode of [undefined, 'workspace-write', 'danger-full-access'] as const) { + const { ctx } = await setupSandboxed(mode) + const schema = bashSchema(ctx) + expect(schema.parameters.properties['sandbox_permissions']?.enum).toEqual(['workspace-write', 'danger-full-access']) + expect(schema.parameters.properties['justification']).toBeDefined() + expect(schema.description).toContain('sanctioned exception') + } + }) + + it('a non-widening request fails at execution with its own text and prompts no one', async () => { + const { ctx } = await setupSandboxed('danger-full-access', { approval: true }) + const consulted = vi.fn() + ctx.on('approval/request', (_req, next) => { consulted(); return next() }) + const result = await callAs(ctx, escalationAgent([]), { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'already wider' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('not strictly wider than this call\'s current "danger-full-access" mode') + expect(consulted).not.toHaveBeenCalled() + }) + + it('rejects sandbox_permissions without a justification, and vice versa, and a blank justification', async () => { + const { ctx } = await setupSandboxed() + const missing = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write' }) + expect(missing.isError).toBe(true) + expect(text(missing)).toContain('sandbox_permissions requires a justification') + const orphan = await callAs(ctx, undefined, { command: 'true', description: 'd', justification: 'why not' }) + expect(orphan.isError).toBe(true) + expect(text(orphan)).toContain('only valid together with sandbox_permissions') + const blank = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: ' ' }) + expect(blank.isError).toBe(true) + expect(text(blank)).toContain('expected a non-empty sentence') + }) + + it('the schema enum rejects a mode outside the target vocabulary before execute (registry-level, any caller)', async () => { + const { ctx } = await setupSandboxed() + const result = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'read-only', justification: 'narrow' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('must be one of') + }) + + it('rejects an unadvertised sandbox_permissions injection under a non-sandboxing executor', async () => { + const ctx = await setup() + const result = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'sneaky' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('not available in this composition') + }) + + it('fails closed with its own text when no approval service is composed', async () => { + const { ctx } = await setupSandboxed() + const result = await callAs(ctx, escalationAgent([]), ESCALATE) + expect(result.isError).toBe(true) + expect(text(result)).toContain('no approval service is composed') + }) + + it('fails closed with its own text for an agent-less escalating call', async () => { + const { ctx } = await setupSandboxed('read-only', { approval: true }) + const result = await callAs(ctx, undefined, ESCALATE) + expect(result.isError).toBe(true) + expect(text(result)).toContain('no agent to route it through') + }) + + it('fails closed with its own text when the service has no answerer', async () => { + const { ctx } = await setupSandboxed('read-only', { approval: true }) + const result = await callAs(ctx, escalationAgent([]), ESCALATE) + expect(result.isError).toBe(true) + expect(text(result)).toContain('no approval channel is available') + }) + + it('a grant runs THAT call under the wider mode — the denial marker names it — and lands the audit pair', async () => { + const { ctx } = await setupSandboxed('read-only', { approval: true }) + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + const events: Array<{ type: string; data: Record }> = [] + // A real unix denial under the passthrough runner: the marker's mode can + // only say workspace-write if the override actually rode the spec. + const lockedDir = join(mkdtempSync(join(tmpdir(), 'dsh-esc-denied-')), 'locked') + mkdirSync(lockedDir) + chmodSync(lockedDir, 0o555) + const result = await callAs(ctx, escalationAgent(events), { + command: `echo x > ${lockedDir}/f`, + description: 'write into a locked directory', + sandbox_permissions: 'workspace-write', + justification: 'must write outside the workspace', + }) + expect(result.isError).toBe(false) + expect(text(result)).toMatch(/\[sandbox: file access denied under workspace-write mode\]/) + expect(events.map(e => e.type)).toEqual(['approval/asked', 'approval/decided']) + expect(events[0]?.data['toolName']).toBe('bash') + expect(events[0]?.data['reason']).toBe('escalate sandbox to workspace-write: must write outside the workspace') + expect(events[1]?.data['outcome']).toBe('allowed-once') + }) + + it('a granted background start settles with the wider mode\'s facts', async () => { + const { ctx, bash } = await setupSandboxed('read-only', { approval: true }) + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + const started = await callAs(ctx, escalationAgent([]), { ...ESCALATE, run_in_background: true }) + expect(started.isError).toBe(false) + const id = text(started).match(/started background task (bash-\d+)/)?.[1] + const task = bash.list().find(t => t.id === id) + if (!task) throw new Error('escalated task not tracked') + await task.done + expect(task.sandbox).toMatchObject({ mode: 'workspace-write', denied: false }) + }) + + it('a rejection denies with the user-said-no text and runs nothing', async () => { + const { ctx } = await setupSandboxed('read-only', { approval: true }) + ctx.on('approval/request', () => Promise.resolve('rejected')) + // A live (non-aborted) signal rides the execution: the gate threads it + // into the approval request so a turn cancellation can withdraw the ask. + const result = await ctx.tools.execute({ + callId: CallId(`call-esc-${++escCall}`), + name: 'bash', + arguments: ESCALATE, + agent: escalationAgent([]), + signal: new AbortController().signal, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('the user rejected escalating this command to "workspace-write"') + }) + + it('a cancellation denies with the cancelled text', async () => { + const { ctx } = await setupSandboxed('read-only', { approval: true }) + ctx.on('approval/request', () => Promise.resolve('cancelled')) + const result = await callAs(ctx, escalationAgent([]), ESCALATE) + expect(result.isError).toBe(true) + expect(text(result)).toContain('approval for escalating to "workspace-write" was cancelled') + }) + + it('a rogue approval stand-in returning a non-vocabulary outcome hits the exhaustiveness backstop', async () => { + const { ctx } = await setupSandboxed() + ctx.provide('approval', { request: () => Promise.resolve('yolo') } as unknown as InstanceType) + const result = await callAs(ctx, escalationAgent([]), ESCALATE) + expect(result.isError).toBe(true) + expect(text(result)).toContain('unreachable') + }) + + it('a never policy rejects an escalation deterministically without consulting any answerer', async () => { + // The live-session e.md case: the model requests escalation against a + // 'never' session — the prepend gate answers rejected before any + // interactive answerer, the fail-closed text is the ordinary rejection + // wording, and the audit pair still lands. + const { ctx } = await setupSandboxed('read-only', { approval: true, policy: 'never' }) + const consulted = vi.fn() + ctx.on('approval/request', (_req, next) => { consulted(); return next() }) + const events: Array<{ type: string; data: Record }> = [] + const result = await callAs(ctx, escalationAgent(events), ESCALATE) + expect(result.isError).toBe(true) + expect(text(result)).toContain('the user rejected escalating this command to "workspace-write"') + expect(consulted).not.toHaveBeenCalled() + expect(events.map(e => e.type)).toEqual(['approval/asked', 'approval/decided']) + expect(events[1]?.data).toMatchObject({ outcome: 'rejected' }) + }) + + it('a plain call under a sandboxing executor never consults approval', async () => { + const { ctx } = await setupSandboxed('read-only', { approval: true }) + const asked = vi.fn() + ctx.on('approval/request', (_req, next) => { asked(); return next() }) + const result = await callAs(ctx, escalationAgent([]), { command: 'echo plain', description: 'plain run' }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('plain') + expect(asked).not.toHaveBeenCalled() + }) +}) + +describe('per-session sandbox mode (the bash/sandbox-mode fold)', () => { + /** Compose the real sandbox stack (passthrough runner) at a given default mode. */ + async function setupModal(mode: 'read-only' | 'workspace-write' | 'danger-full-access' = 'read-only', opts: { approval?: boolean } = {}) { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG) + await ctx.plugin(SandboxBashExecutor, { graceMs: 200, mode }) + ;(ctx.bash as SandboxBashExecutor).internals = { spillDir } + if (opts.approval === true) await ctx.plugin(ApprovalService) + await ctx.plugin(ToolBash) + return ctx + } + + /** + * An agent stand-in over a REAL Session — the stamping folds real events; + * the opened turn satisfies approval's enclosure precondition on escalating + * calls. + */ + function sessionAgent(id: string): { agent: Agent; session: Session; injected: string[] } { + const session = new Session(SessionId(id)) + session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + const injected: string[] = [] + const agent = { + id, + session, + inject: (content: { type: string; text: string }[]) => { injected.push(content[0]?.text ?? '') }, + } as unknown as Agent + return { agent, session, injected } + } + + let modeCall = 0 + const callAs = (ctx: Context, agent: Agent | undefined, args: unknown) => + ctx.tools.execute({ callId: CallId(`call-mode-${++modeCall}`), name: 'bash', arguments: args, ...agent ? { agent } : {} }) + + + it('stamps calls with grant > session override > nothing (executor default)', async () => { + const ctx = await setupModal('read-only', { approval: true }) + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + const seen: (string | undefined)[] = [] + const original = ctx.bash.resolve.bind(ctx.bash) + vi.spyOn(ctx.bash, 'resolve').mockImplementation((req) => { + seen.push(req.sandboxMode) + return original(req) + }) + const { agent, session } = sessionAgent('sess-stamp-1') + const run = { command: 'true', description: 'stamp probe' } + await callAs(ctx, agent, run) // no override yet + setSandboxMode(session, 'workspace-write') + await callAs(ctx, agent, run) // standing override + await callAs(ctx, undefined, run) // agent-less caller: no session to fold + await callAs(ctx, agent, { ...run, sandbox_permissions: 'danger-full-access', justification: 'grant outranks override' }) + expect(seen).toEqual([undefined, 'workspace-write', undefined, 'danger-full-access']) + }) + + it('escalates relative to the session effective mode, not the executor default (narrower override)', async () => { + // The blocker scenario: a workspace-write default with a read-only + // override — the sensible escalation is workspace-write, which a + // default-relative ladder could not even express. The static target + // vocabulary advertises it and the execution check accepts it as + // strictly wider than the CALL's effective (overridden) mode. + const ctx = await setupModal('workspace-write', { approval: true }) + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + const seen: (string | undefined)[] = [] + const original = ctx.bash.resolve.bind(ctx.bash) + vi.spyOn(ctx.bash, 'resolve').mockImplementation((req) => { + seen.push(req.sandboxMode) + return original(req) + }) + const { agent, session } = sessionAgent('sess-esc-narrow') + setSandboxMode(session, 'read-only') + const result = await callAs(ctx, agent, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'the override is narrower than the default' }) + expect(result.isError).toBe(false) + expect(seen).toEqual(['workspace-write']) + }) + + it('a danger-full-access default still offers the lever to a narrower-switched session', async () => { + // Under the default-relative ladder these fields VANISHED (nothing is + // wider than the default), stranding a read-only-overridden session + // with no escalation path at all. + const ctx = await setupModal('danger-full-access', { approval: true }) + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + const schema = ctx.tools.schemas().find(t => t.name === 'bash') as unknown as { parameters: { properties: Record } } + expect(schema.parameters.properties['sandbox_permissions']?.enum).toEqual(['workspace-write', 'danger-full-access']) + const { agent, session } = sessionAgent('sess-esc-dfa') + setSandboxMode(session, 'read-only') + const result = await callAs(ctx, agent, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'confined by override under a wide default' }) + expect(result.isError).toBe(false) + }) + + it('rejects a non-widening request against the OVERRIDDEN effective mode without prompting', async () => { + const ctx = await setupModal('read-only', { approval: true }) + const consulted = vi.fn() + ctx.on('approval/request', (_req, next) => { consulted(); return next() }) + const { agent, session } = sessionAgent('sess-esc-nonwide') + setSandboxMode(session, 'danger-full-access') + const result = await callAs(ctx, agent, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'already wider via override' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('not strictly wider than this call\'s current "danger-full-access" mode') + expect(consulted).not.toHaveBeenCalled() + }) + + it('never stamps an override under a non-sandboxing executor (nothing honors it)', async () => { + const ctx = await setup() + const seen: (string | undefined)[] = [] + const original = ctx.bash.resolve.bind(ctx.bash) + vi.spyOn(ctx.bash, 'resolve').mockImplementation((req) => { + seen.push(req.sandboxMode) + return original(req) + }) + const { agent, session } = sessionAgent('sess-stamp-2') + setSandboxMode(session, 'danger-full-access') + await callAs(ctx, agent, { command: 'true', description: 'plain probe' }) + expect(seen).toEqual([undefined]) + }) + +}) diff --git a/packages/bash/tool-bash/tsconfig.json b/packages/bash/tool-bash/tsconfig.json index 6828cd1738..d3bd550386 100644 --- a/packages/bash/tool-bash/tsconfig.json +++ b/packages/bash/tool-bash/tsconfig.json @@ -28,6 +28,15 @@ }, { "path": "../../bash/bash" + }, + { + "path": "../../core/system-prompt" + }, + { + "path": "../../ui/user-approval" + }, + { + "path": "../../sandbox/sandbox" } ] } diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 667bf69fae..257ccc2267 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -56,7 +56,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ key: 'agentLoop', summary: 'The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`.', methods: [ - 'create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent', + 'create(id: AgentId, options: AgentOptions = {}, meta: Pick = {}): ReactLoopAgent', 'createAgent(options: CreateAgentOptions): AgentHandle', 'async resume(options: ResumeAgentOptions): Promise', ], @@ -73,6 +73,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ 'list(): Agent[]', ], }, + { + key: 'approval', + summary: 'The `ctx.approval` service: dispatches ApprovalRequests to the `approval/request` waterfall and audits every ask/outcome pair to the requesting agent\'s session log.', + methods: [ + 'async request(req: ApprovalRequest): Promise', + ], + }, { key: 'bash', summary: 'Abstract bash execution service.', @@ -125,6 +132,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ 'stream(options: GenerateOptions): AsyncIterable', ], }, + { + key: 'sandbox', + summary: 'Abstract process-sandbox service.', + methods: [ + 'abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv', + ], + }, { key: 'sessionPersistence', summary: 'Abstract durable session-persistence service.', @@ -149,6 +163,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ 'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session', ], }, + { + key: 'skills', + summary: 'Registry of skill providers.', + methods: [ + 'registerProvider(provider: SkillProvider): () => void', + 'register(skill: SkillRegistration): () => void', + 'async list(options: SkillLookupOptions = {}): Promise', + 'async get(name: string, options: SkillLookupOptions = {}): Promise', + ], + }, { key: 'subagents', summary: 'The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.', @@ -280,6 +304,12 @@ export const EVENT_API: readonly EventApiEntry[] = [ signature: '\'agent/turn-continuation\'(agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise): Promise', summary: 'Waterfall: override the turn-continuation decision via a typed ContinuationDecision.', }, + { + name: 'approval/request', + mode: 'waterfall', + signature: '\'approval/request\'(this: ApprovalService, req: ApprovalRequest, next: () => Promise): Promise', + summary: 'Waterfall asking the composed answerers to decide one approval request.', + }, { name: 'fs/edit-intent', mode: 'waterfall', @@ -322,6 +352,18 @@ export const EVENT_API: readonly EventApiEntry[] = [ signature: '\'session/flush\'(session: Session): Promise | void', summary: 'Awaited durability checkpoint.', }, + { + name: 'skill/provider-added', + mode: 'emit', + signature: '\'skill/provider-added\'(provider: SkillProvider): void', + summary: 'A skill provider became resolvable in the `ctx.skills` registry.', + }, + { + name: 'skill/provider-removed', + mode: 'emit', + signature: '\'skill/provider-removed\'(name: string): void', + summary: 'A skill provider left the registry because its plugin fiber was disposed.', + }, { name: 'subagent/end', mode: 'emit', @@ -446,6 +488,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'AgentStatus', declaration: 'export type AgentStatus = \'idle\' | \'running\' | \'disposed\';', }, + { + name: 'ApprovalOutcome', + declaration: 'export type ApprovalOutcome = \'allowed-once\' | \'rejected\' | \'cancelled\' | \'unavailable\';', + }, + { + name: 'ApprovalRequest', + declaration: 'export interface ApprovalRequest {\n agent: Agent;\n toolName: string;\n callId?: CallId;\n reason?: string;\n signal?: AbortSignal;\n}', + }, { name: 'AskUserQuestionAnswer', declaration: 'export interface AskUserQuestionAnswer {\n answers: AskUserQuestionAnswerItem[];\n}', @@ -476,19 +526,23 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'BashExecRequest', - declaration: 'export interface BashExecRequest {\n command: string;\n workdir?: string | undefined;\n timeoutMs?: number | undefined;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner?: OwnerToken | undefined;\n}', + declaration: 'export interface BashExecRequest {\n command: string;\n workdir?: string | undefined;\n timeoutMs?: number | undefined;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner?: OwnerToken | undefined;\n sandboxMode?: SandboxMode | undefined;\n}', }, { name: 'BashExecSpec', - declaration: 'export interface BashExecSpec {\n command: string;\n workdir: string;\n timeoutMs: number;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner: OwnerToken | undefined;\n}', + declaration: 'export interface BashExecSpec {\n command: string;\n workdir: string;\n timeoutMs: number;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner: OwnerToken | undefined;\n sandboxMode: SandboxMode | undefined;\n}', }, { name: 'BashRunResult', - declaration: 'export interface BashRunResult {\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: CollectedOutput;\n stderr: CollectedOutput;\n}', + declaration: 'export interface BashRunResult {\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: CollectedOutput;\n stderr: CollectedOutput;\n sandbox?: BashSandboxInfo;\n}', + }, + { + name: 'BashSandboxInfo', + declaration: 'export interface BashSandboxInfo {\n mode: SandboxMode;\n denied: boolean;\n enforcement?: SandboxEnforcement;\n runnerFailed?: boolean;\n}', }, { name: 'BashTask', - declaration: 'export interface BashTask {\n readonly id: BashTaskId;\n readonly command: string;\n status: BashTaskStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n}', + declaration: 'export interface BashTask {\n readonly id: BashTaskId;\n readonly command: string;\n status: BashTaskStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n sandbox?: BashSandboxInfo;\n}', }, { name: 'BashTaskId', @@ -550,6 +604,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'CompactionResult', declaration: 'export interface CompactionResult {\n startSeq: number;\n summarySeq: number;\n endSeq: number;\n summary: ContentBlock[];\n shadowedRange: {\n start: number;\n end: number;\n };\n shadowedSeqs: number[];\n shadowedTokenCount: number;\n}', }, + { + name: 'ConfinedArgv', + declaration: 'export interface ConfinedArgv {\n argv: string[];\n enforcement: SandboxEnforcement;\n denialSignatures: readonly string[];\n runnerFailureSignatures: readonly string[];\n}', + }, + { + name: 'ConfinedSandboxMode', + declaration: 'export type ConfinedSandboxMode = Exclude;', + }, { name: 'ContentBlockMap', declaration: 'export interface ContentBlockMap {\n \'text\': TextBlock;\n \'reasoning\': ReasoningBlock;\n \'tool-call\': ToolCallBlock;\n \'tool-result\': ToolResultBlock;\n}', @@ -674,6 +736,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ResumeAgentOptions', declaration: 'export interface ResumeAgentOptions {\n agentId: AgentId;\n resumeSessionId: SessionId;\n agentOptions?: AgentOptions;\n}', }, + { + name: 'SandboxEnforcement', + declaration: 'export type SandboxEnforcement = \'full\' | \'partial\';', + }, + { + name: 'SandboxMode', + declaration: 'export type SandboxMode = \'read-only\' | \'workspace-write\' | \'danger-full-access\';', + }, + { + name: 'SandboxPolicy', + declaration: 'export interface SandboxPolicy {\n mode: ConfinedSandboxMode;\n workspaceRoot: string;\n}', + }, { name: 'SendOptions', declaration: 'export interface SendOptions {\n source?: MessageSource;\n}', @@ -706,6 +780,38 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionLocation', declaration: 'export interface SessionLocation {\n readonly kind: string;\n readonly path: string;\n}', }, + { + name: 'SkillCandidate', + declaration: 'export interface SkillCandidate extends SkillSummary {\n rank: number;\n locator: unknown;\n path?: string;\n metadata?: Record;\n}', + }, + { + name: 'SkillDefinition', + declaration: 'export interface SkillDefinition extends SkillSummary {\n content: string;\n path?: string;\n metadata?: Record;\n}', + }, + { + name: 'SkillLookupOptions', + declaration: 'export interface SkillLookupOptions {\n cwd?: string | undefined;\n signal?: AbortSignal | undefined;\n}', + }, + { + name: 'SkillProvider', + declaration: 'export interface SkillProvider {\n name: string;\n list(options: SkillLookupOptions): Promise;\n get(candidate: SkillCandidate, options: SkillLookupOptions): Promise;\n}', + }, + { + name: 'SkillRegistration', + declaration: 'export type SkillRegistration = Omit & {\n provider?: string;\n};', + }, + { + name: 'SkillResourceBase', + declaration: 'export type SkillResourceBase = {\n kind: \'directory\';\n path: string;\n} | {\n kind: \'url\';\n url: string;\n} | {\n kind: \'opaque\';\n description: string;\n};', + }, + { + name: 'SkillSource', + declaration: 'export type SkillSource = \'project-dsh\' | \'project-agents\' | \'runtime\' | \'user-dsh\' | \'user-agents\' | \'custom\' | (string & {});', + }, + { + name: 'SkillSummary', + declaration: 'export interface SkillSummary {\n name: string;\n description: string;\n whenToUse?: string;\n disableModelInvocation?: boolean;\n source: SkillSource;\n provider: string;\n resourceBase?: SkillResourceBase;\n}', + }, { name: 'StreamChunk', declaration: 'export type StreamChunk = {\n type: \'block-start\';\n index: number;\n blockType: ContentBlockType;\n} | {\n type: \'text-delta\';\n index: number;\n text: string;\n} | {\n type: \'reasoning-delta\';\n index: number;\n text: string;\n} | {\n type: \'tool-call-delta\';\n index: number;\n id: CallId;\n name?: string;\n argumentsDelta: string;\n} | {\n type: \'block-end\';\n index: number;\n block: ContentBlock;\n} | {\n type: \'usage\';\n usage: TokenUsage;\n} | {\n type: \'finish\';\n reason: FinishReason;\n};', diff --git a/packages/core/README.md b/packages/core/README.md index eee8e3eed0..00b54f9fbc 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,6 +1,6 @@ # core/ — product API spine -The packages every harness build is assembled from: the session log, the system-prompt assembly, the tool registry, the agent vocabulary, and the one concrete loop that drives them. These are **product** packages — the stable surface plugins and consumers build against. +The session log, system-prompt assembly, tool registry, agent vocabulary, and concrete loop that form the harness's default control spine. These are **product** packages — the stable surface plugins and consumers build against. | Package | Role | ctx key | |---|---|---| @@ -9,8 +9,8 @@ The packages every harness build is assembled from: the session log, the system- | `tools/` | Tool registry + `tools/pre-execute`/`tools/post-execute` pipeline | `ctx.tools` | | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` | | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` | -| `agent-core/` | Bundle plugin: the providerless/executor-less/UI-less spine as code | (loads the spine) | +| `agent-core/` | Bundle plugin: the default executor-less/UI-less spine as code | (loads the spine) | `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable. -`agent-core` is the composition counterpart: one bundle plugin that loads the whole providerless spine (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds the swappable backends plus any optional product tools it wants to expose. It lives in `core/` because it composes exclusively `core/` + interface packages and ships no provider, executor, or UI of its own. +`agent-core` is the composition counterpart: one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds the swappable backends plus any optional product tools it wants to expose. It lives in `core/` because it composes the shared control spine while leaving executors, LLM adapters, alternate skill providers, and UI front doors outside the bundle. diff --git a/packages/core/agent-core/README.md b/packages/core/agent-core/README.md index 3f2ff08c0e..642b07b10d 100644 --- a/packages/core/agent-core/README.md +++ b/packages/core/agent-core/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-agent-core -The **providerless, executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends. +The **default executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs, including the local skill provider, and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends. This is the package to read to see **the whole plugin tree at once** — the teaching role the inlined `echo-agent` `cordis.yml` used to play before the spine moved behind this bundle. @@ -14,9 +14,12 @@ This is the package to read to see **the whole plugin tree at once** — the tea @deepseek-ai/dsh-session event-sourced session log + store @deepseek-ai/dsh-system-prompt prompt-section + tool-schema assembly @deepseek-ai/dsh-tools tool registry + tools/pre-execute/post-execute +@deepseek-ai/dsh-skill skill provider registry +@deepseek-ai/dsh-skill-local local filesystem skill provider @deepseek-ai/dsh-agent agent registry + agent/* event vocabulary @deepseek-ai/dsh-invariants dev-mode event-contract assertions @deepseek-ai/dsh-tool-bash the model-facing bash/bash_output/bash_kill schemas +@deepseek-ai/dsh-tool-skill session-prefix skill catalog + model-facing loader schema @deepseek-ai/dsh-agent-loop THE concrete loop (gets the forwarded `agents`) (dsh-system-prompt gets the forwarded `persona`) ``` @@ -27,6 +30,7 @@ The spine is everything COMMON to every front door. The swappable and front-door - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`). - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl). +- **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings. - **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-agent`](../../ui/stdio-agent/README.md), [`dsh-acp-agent`](../../ui/acp-agent/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC). This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door. @@ -35,11 +39,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement ```ts import type { Config } from '@deepseek-ai/dsh-agent-core' -// { agents?, persona?, toolOrder? } — the schema is z.intersect([AgentLoop.Config, SystemPrompt.Config]), -// so validation and defaulting can never drift from the owners'. +// { agents?, persona?, toolOrder?, tools?, skills? } — the schema intersects the owner schemas, +// so validation and defaulting can never drift from the owners. ``` -The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` to `dsh-system-prompt` (default `''`), the deployment's persona section — and `toolOrder` to `dsh-system-prompt` (absent — lexicographic), the explicit model-facing tool order. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure. +The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; and `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure. ## Why a code bundle, not a shared YAML include diff --git a/packages/core/agent-core/package.json b/packages/core/agent-core/package.json index 5b1eed413a..039a6ac505 100644 --- a/packages/core/agent-core/package.json +++ b/packages/core/agent-core/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-agent-core", - "description": "The providerless/executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + agents + invariants + tool-bash + agent-loop)", + "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + invariants + tool-bash + tool-skill + agent-loop)", "version": "0.0.1", "private": true, "type": "module", @@ -28,8 +28,11 @@ "@deepseek-ai/dsh-invariants": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", + "@deepseek-ai/dsh-skill": "^0.0.1", + "@deepseek-ai/dsh-skill-local": "^0.0.1", "@deepseek-ai/dsh-system-prompt": "^0.0.1", "@deepseek-ai/dsh-tool-bash": "^0.0.1", + "@deepseek-ai/dsh-tool-skill": "^0.0.1", "@deepseek-ai/dsh-tools": "^0.0.1", "cordis": "^4.0.0-rc.6" }, @@ -40,8 +43,11 @@ "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-skill": "workspace:^", + "@deepseek-ai/dsh-skill-local": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tool-bash": "workspace:^", + "@deepseek-ai/dsh-tool-skill": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "cordis": "^4.0.0-rc.6" }, diff --git a/packages/core/agent-core/src/index.ts b/packages/core/agent-core/src/index.ts index a3221bdf8f..d12ef3bad5 100644 --- a/packages/core/agent-core/src/index.ts +++ b/packages/core/agent-core/src/index.ts @@ -1,10 +1,10 @@ /** - * The providerless, executor-less, UI-less agent spine as ONE bundle plugin. + * The default executor-less, UI-less agent spine as ONE bundle plugin. * * Loads the fixed set of services every harness agent needs — `timer`, the LLM * service, the session store, system-prompt assembly, the tool registry, the - * agent registry, the dev-mode invariants, the model-facing `bash` tool - * schemas, and the concrete `agent-loop` — and forwards the loop's `agents` + * skill registry plus local skill provider, the agent registry, the dev-mode + * invariants, the model-facing `bash` and `skill` tool schemas, and the concrete `agent-loop` — and forwards the loop's `agents` * list as its OWN config (default `[]`), so each app supplies its own * pre-created agents. * @@ -19,6 +19,9 @@ * (a console logger, `hmr`) — these are the coupled "front-door cluster" the * app packages ({@link @deepseek-ai/dsh-stdio-agent}, * {@link @deepseek-ai/dsh-acp-agent}) bake in, NOT the shared spine. + * - additional SKILL PROVIDERS; the bundle ships the local filesystem provider + * because local skills are default agent behavior, while embedded or remote + * providers remain deployment choices. * * This is the interface/implementation/consumer seam at the composition level: * the bundle owns the shared spine, the leaf owns the backends, the app package @@ -49,24 +52,37 @@ import LlmService from '@deepseek-ai/dsh-llm' import SessionStore from '@deepseek-ai/dsh-session' import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' +import SkillService, { type Config as SkillRegistryConfig } from '@deepseek-ai/dsh-skill' +import * as SkillLocal from '@deepseek-ai/dsh-skill-local' import AgentRegistry from '@deepseek-ai/dsh-agent' import * as invariants from '@deepseek-ai/dsh-invariants' import * as toolBash from '@deepseek-ai/dsh-tool-bash' +import * as toolSkill from '@deepseek-ai/dsh-tool-skill' import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop' export const name = 'agent-core' +/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */ +export interface SkillConfig { + /** Registry-level discovery cache settings. */ + registry?: SkillRegistryConfig + /** Local filesystem skill provider settings. */ + local?: SkillLocal.Config + /** Model-facing skill catalog and tool settings. */ + tool?: toolSkill.Config +} + /** * Bundle config: each field forwarded verbatim to the child that owns it — * `agents` to the agent loop (an app that pre-creates no agents, like the ACP * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt * plugin (the deployment's persona section and the explicit model-facing tool - * order), the `tools` object to the tool registry (its presentation `mode`). - * Every field is optional INPUT here because each owner's schema - * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the - * schema is the INTERSECTION of the owners' own schemas (the registry's - * nested under its `tools` key), so validation and defaulting can never - * drift from them. + * order), the `tools` object to the tool registry (its presentation `mode`), + * and `skills` to the skill registry/local provider/tool consumer. Every field + * is optional INPUT here because each owner's schema supplies the default; + * the schema is the INTERSECTION of the owners' own schemas (with registry + * schemas nested under their bundle keys), so validation and defaulting can + * never drift from them. */ export interface Config { /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */ @@ -77,10 +93,23 @@ export interface Config { toolOrder?: SystemPromptConfig['toolOrder'] /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */ tools?: ToolsConfig + /** Skill registry, local provider, and model-facing consumer config. */ + skills?: SkillConfig } -/** Intersect the owners' schemas so validation + defaulting stay identical (the registry's nested under `tools`). */ -export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config, z.object({ tools: ToolRegistry.Config })]) as unknown as z +/** The skill config schema exported for app packages that forward `skills`. */ +export const SkillConfigSchema: z = z.object({ + registry: SkillService.Config, + local: SkillLocal.Config, + tool: toolSkill.Config, +}) + +/** Intersect the owners' schemas so validation + defaulting stay identical. */ +export const Config = z.intersect([ + AgentLoop.Config, + SystemPrompt.Config, + z.object({ tools: ToolRegistry.Config, skills: SkillConfigSchema }), +]) as unknown as z /** * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber; @@ -106,8 +135,11 @@ export function apply(ctx: Context, config: Config): void { ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {}, }) ctx.plugin(ToolRegistry, config.tools ?? {}) + ctx.plugin(SkillService, config.skills?.registry ?? {}) + ctx.plugin(SkillLocal, config.skills?.local ?? {}) ctx.plugin(AgentRegistry) ctx.plugin(invariants) ctx.plugin(toolBash) + ctx.plugin(toolSkill, config.skills?.tool ?? {}) ctx.plugin(AgentLoop, { agents: config.agents ?? [] }) } diff --git a/packages/core/agent-core/tests/agent-core.spec.ts b/packages/core/agent-core/tests/agent-core.spec.ts index 818da77311..fb1bc7e1bd 100644 --- a/packages/core/agent-core/tests/agent-core.spec.ts +++ b/packages/core/agent-core/tests/agent-core.spec.ts @@ -1,13 +1,25 @@ import { describe, expect, it } from 'vitest' +import { mkdir, mkdtemp, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { tmpdir } from 'node:os' import { Context } from 'cordis' import Loader from '@cordisjs/plugin-loader' import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt' import * as agentCore from '../src/index.ts' import { AgentId } from '@deepseek-ai/dsh-agent' +import type { Message } from '@deepseek-ai/dsh-llm' + +async function composePrefix(ctx: Context, cwd: string): Promise { + const empty: Message[] = [] + return await ctx.waterfall( + 'agent/session-prefix', { session: { header: { cwd } } } as never, + empty, new AbortController().signal, () => Promise.resolve(empty), + ) +} /** * Unit coverage for the @deepseek-ai/dsh-agent-core bundle: mounting it brings - * up the whole providerless spine in one `ctx.plugin`, and the forwarded + * up the whole default spine in one `ctx.plugin`, and the forwarded * `agents` config reaches the loop (default `[]`, or a pre-created agent). * * The bundle is exercised through `ctx.plugin(agentCore, …)` — the NAMESPACE @@ -16,16 +28,54 @@ import { AgentId } from '@deepseek-ai/dsh-agent' * bin smokes; here we assert the composition + config forwarding. */ async function mount(config?: agentCore.Config): Promise { + const oldDshHome = process.env.DSH_HOME + const oldAgentsHome = process.env.DSH_AGENTS_HOME + process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-')) + process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-')) const ctx = new Context() - await ctx.plugin(agentCore, config) - // The bundle mounts its children inside apply() (not awaited there); let their - // fibers settle so the spine services and any pre-created agent are ready. - await new Promise(resolve => setTimeout(resolve, 50)) - return ctx + try { + await ctx.plugin(agentCore, config) + // The bundle mounts its children inside apply() (not awaited there); let their + // fibers settle so the spine services and any pre-created agent are ready. + await new Promise(resolve => setTimeout(resolve, 50)) + return ctx + } finally { + if (oldDshHome === undefined) { + delete process.env.DSH_HOME + } else { + process.env.DSH_HOME = oldDshHome + } + if (oldAgentsHome === undefined) { + delete process.env.DSH_AGENTS_HOME + } else { + process.env.DSH_AGENTS_HOME = oldAgentsHome + } + } +} + +async function withIsolatedSkillHomes(run: () => Promise): Promise { + const oldDshHome = process.env.DSH_HOME + const oldAgentsHome = process.env.DSH_AGENTS_HOME + process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-')) + process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-')) + try { + return await run() + } finally { + if (oldDshHome === undefined) { + delete process.env.DSH_HOME + } else { + process.env.DSH_HOME = oldDshHome + } + if (oldAgentsHome === undefined) { + delete process.env.DSH_AGENTS_HOME + } else { + process.env.DSH_AGENTS_HOME = oldAgentsHome + } + } } describe('dsh-agent-core bundle', () => { - it('brings up the full providerless spine', async () => { + it('brings up the full default spine', async () => { const ctx = await mount() // One service from each layer of the spine proves the children loaded. expect(ctx.get('timer')).toBeDefined() @@ -33,11 +83,22 @@ describe('dsh-agent-core bundle', () => { expect(ctx.get('sessions')).toBeDefined() expect(ctx.get('systemPrompt')).toBeDefined() expect(ctx.get('tools')).toBeDefined() + expect(ctx.get('skills')).toBeDefined() expect(ctx.get('agents')).toBeDefined() expect(ctx.get('agentLoop')).toBeDefined() await ctx.fiber.dispose() }) + it('includes the skill registry, local provider, and skill tool without builtin skills', async () => { + const ctx = await mount() + + expect(ctx.skills).toBeDefined() + expect(ctx.tools.schemas().map(tool => tool.name)).toContain('skill') + expect(await ctx.skills.list()).toEqual([]) + + await ctx.fiber.dispose() + }) + it('defaults the agents list to empty (no pre-created agents)', async () => { const ctx = await mount() expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined() @@ -68,6 +129,40 @@ describe('dsh-agent-core bundle', () => { await ctx.fiber.dispose() }) + it('forwards skill config to the registry, local provider, and model-facing consumer', async () => { + const home = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-home-')) + const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-agents-')) + const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-custom-')) + await mkdir(custom, { recursive: true }) + await writeFile(join(custom, 'custom-skill.md'), '---\nname: custom-skill\ndescription: Custom skill\n---\n\nCustom body.\n') + const ctx = await mount({ + agents: [], + skills: { + registry: { collectCacheMaxEntries: 4 }, + local: { + dshHome: join(home, '.dsh'), + agentsHome: join(agentsHome, '.agents'), + customSkillDirs: [custom], + }, + tool: { catalogDescriptionMaxLength: 6 }, + }, + }) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['custom-skill']) + expect(JSON.stringify(await composePrefix(ctx, '/tmp'))).toContain('- `custom-skill`: Cus...') + await ctx.fiber.dispose() + }) + + it('uses the default skill config when apply is called directly without skills', async () => { + await withIsolatedSkillHomes(async () => { + const ctx = new Context() + agentCore.apply(ctx, { agents: [] }) + await new Promise(resolve => setTimeout(resolve, 50)) + expect(ctx.skills).toBeDefined() + expect(await ctx.skills.list()).toEqual([]) + await ctx.fiber.dispose() + }) + }) + it('forwards toolOrder to the system-prompt assembly', async () => { const ctx = await mount({ toolOrder: ['zulu', TOOL_ORDER_REST] }) // The bundle's own bash tools pend on the absent `ctx.bash` executor in @@ -81,7 +176,7 @@ describe('dsh-agent-core bundle', () => { }) } const assembly = await ctx.get('systemPrompt')!.assemble() - expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha']) + expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill']) await ctx.fiber.dispose() }) diff --git a/packages/core/agent-core/tsconfig.json b/packages/core/agent-core/tsconfig.json index 91e5ec894e..4fd0a81e97 100644 --- a/packages/core/agent-core/tsconfig.json +++ b/packages/core/agent-core/tsconfig.json @@ -17,6 +17,9 @@ { "path": "../../../vendor/timer" }, + { + "path": "../../../vendor/schemastery" + }, { "path": "../../llm/llm" }, @@ -29,6 +32,15 @@ { "path": "../../core/tools" }, + { + "path": "../../skill/skill" + }, + { + "path": "../../skill/skill-local" + }, + { + "path": "../../skill/tool-skill" + }, { "path": "../../core/agent" }, diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index 2af8ad29f6..6137737457 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -8,7 +8,7 @@ This is the only package in the harness that contains concrete loop logic. Every ### Public API -- `ctx.agentLoop.create(id: string, options?: AgentOptions): ReactLoopAgent` — config-driven create: an agent on a fresh per-run session id `${id}-session-` (no cwd). Used for `cordis.yml`-configured agents. The per-run uuid avoids colliding with the on-disk log a prior run materialized once a durable persistence backend is loaded; each run is a new session (a deliberate demo simplification — a real resume-or-create policy is a TODO). Disposed with the calling fiber. +- `ctx.agentLoop.create(id: string, options?: AgentOptions, meta?: { cwd?: string }): ReactLoopAgent` — config-driven create: an agent on a fresh per-run session id `${id}-session-` with optional session metadata. Used for `cordis.yml`-configured agents. The per-run uuid avoids colliding with the on-disk log a prior run materialized once a durable persistence backend is loaded; each run is a new session (a deliberate demo simplification — a real resume-or-create policy is a TODO). Disposed with the calling fiber. `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface): @@ -28,11 +28,12 @@ interface Config { agents: Array<{ id: string // required model?: string + cwd?: string // optional workspace cwd for the fresh session }> } ``` -Agents listed in config are auto-created at startup. (There is no per-agent persona: the deployment persona is `dsh-system-prompt`'s own `persona` config, shared by every agent in the context.) The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from the `assemble({ agent })` context — runtime facts of the agents THIS loop drives, unlike the `harness:identity`/`deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin. +Agents listed in config are auto-created at startup. `cwd` applies only to fresh config-created sessions; `resumeSessionId` keeps the persisted session header. There is no per-agent persona: the deployment persona is `dsh-system-prompt`'s own `persona` config, shared by every agent in the context. The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from the `assemble({ agent })` context — runtime facts of the agents THIS loop drives, unlike the `harness:identity`/`deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin. ### Classes diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts index e7e0e562d9..4af0d464ec 100644 --- a/packages/core/agent-loop/src/index.ts +++ b/packages/core/agent-loop/src/index.ts @@ -12,7 +12,7 @@ import { randomUUID } from 'node:crypto' import z from 'schemastery' import type { AgentFactory, AgentHandle, AgentId, AgentOptions, CreateAgentOptions, ResumeAgentOptions, SessionStartSource } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-llm' -import { SessionId } from '@deepseek-ai/dsh-session' +import { SessionId, type SessionHeader } from '@deepseek-ai/dsh-session' import type { Session } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-system-prompt' import type {} from '@deepseek-ai/dsh-tools' @@ -38,6 +38,8 @@ export interface Config { agents: (AgentOptions & { /** Agent id to register under; also seeds the fresh per-run session id (`${id}-session-`). */ id: AgentId + /** Optional workspace cwd for the config-created fresh session. */ + cwd?: string /** * If set, the config agent RESUMES this persisted session id instead of * starting a fresh `${id}-session-`. Sourced from an env var in @@ -77,6 +79,7 @@ export class AgentLoop extends Service implements AgentFactory { agents: z.array(z.object({ id: z.string().required(), model: z.string(), + cwd: z.string(), resumeSessionId: z.string(), })).default([]), }) as unknown as z @@ -96,7 +99,7 @@ export class AgentLoop extends Service implements AgentFactory { // (renderPrompt then rejects a persona that claims it — fail loud). ctx.systemPrompt.variable('model', context => context.agent?.options.model) ctx.systemPrompt.variable('cwd', context => context.agent?.session.header.cwd) - for (const { id, resumeSessionId, ...options } of config.agents) { + for (const { id, cwd, resumeSessionId, ...options } of config.agents) { if (resumeSessionId !== undefined && resumeSessionId !== '') { // Resume a prior session instead of starting fresh. resume() needs // `ctx.sessionPersistence`, which may load AFTER this plugin (cordis.yml @@ -115,15 +118,15 @@ export class AgentLoop extends Service implements AgentFactory { return () => void fiber.dispose() }, `agentLoop.resume(${id})`) } else { - this.create(id, options) + this.create(id, options, cwd === undefined ? {} : { cwd }) } } } /** * Config-driven create: an agent on a FRESH, non-colliding session id per run - * (`${id}-session-`, no cwd). Used for `cordis.yml`-configured agents - * and as the shared core for the programmatic factory {@link createAgent}. + * (`${id}-session-`). Used for `cordis.yml`-configured agents and as + * the shared core for the programmatic factory {@link createAgent}. * * Why a per-run id, not a fixed `${id}-session`: once a durable persistence * backend is loaded, a fixed id collides on the second run — the backend @@ -137,15 +140,16 @@ export class AgentLoop extends Service implements AgentFactory { * UI/ACP path owns session selection. * @param id - the agent id; also seeds the generated session id. * @param options - loop options (model, limits, …); defaults applied per option. + * @param meta - optional session metadata for the fresh session. * @returns the running agent, owned by the calling fiber (no handle). */ - create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent { + create(id: AgentId, options: AgentOptions = {}, meta: Pick = {}): ReactLoopAgent { this.assertAgentIdFree(id) // Config/programmatic path: prepare the session and let start() fold its // lifecycle into the agent's composite effect (so a fiber unload tears the // session + agent down as one ordered chain, capturing the loop's closing // flush). The whole effect is owned by THIS fiber; no AgentHandle is needed. - const session = this.ctx.sessions.prepare(SessionId(`${id}-session-${randomUUID()}`), { meta: {} }) + const session = this.ctx.sessions.prepare(SessionId(`${id}-session-${randomUUID()}`), { meta }) const { agent } = this.start(id, options, session, 'startup') return agent } diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index eebf56ee82..9dd38c5ae8 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -916,6 +916,21 @@ describe('agent loop', () => { expect(adapter.requests).toHaveLength(1) }) + it('attaches config agent cwd to the fresh session header', async () => { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { + agents: [{ id: AgentId('config-agent'), model: 'mock', cwd: '/work/project' }], + }) + + const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent + expect(agent.session.header.cwd).toBe('/work/project') + }) + it('replays a session log into an identical derived history', async () => { const adapter = new MockAdapter([ toolCallResponse('c1', 'echo', { text: 'x' }), diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index 7a383c5064..0bf1c4bf08 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -22,7 +22,7 @@ tools: ### Injected services -`SystemPrompt` — the registry automatically feeds its tool schemas into the system-prompt assembly via `ctx.systemPrompt.tools()`. +`SystemPrompt` — the registry automatically feeds its tool schemas into the system-prompt assembly via `ctx.systemPrompt.tools()`. The approval seam is consumed opportunistically instead (`ctx.get('approval')`, no static inject): a deployment without it keeps the ask→deny degrade, and the registry stays active either way. ### Events @@ -38,14 +38,14 @@ tools: - `ToolDefinition` — `ToolSchema` + `execute(args, exec): Promise` (the bare array is the model-facing content; the object form additionally attaches an opaque, JSON-serializable `meta` presentation payload persisted on the `tool/result` event and handed back to `presentResult`), plus optional `presentCall(args)` / `presentResult(args, result)` for tool-owned UI presentation (see below). It also carries an optional cooperative timeout budget `timeoutMs?: number` (ms) enforced by `@deepseek-ai/dsh-timeout-policy`, never sent to the model. - `ToolExecution` — one pending tool call: `{ callId, name, arguments, agent?, signal? }`. - `ToolExecutionResult` — outcome: `{ callId, content, isError, error?, additionalContext?, meta? }`. On failure with a `HarnessError`, `error: { name, code }` carries the structured failure class alongside the model-facing text (the loop forwards it onto the `tool/result` session event for retry/sandbox plugins and replay). `additionalContext` (a `HookContext`) ferries any `tools/post-execute` context up to the loop, which buffers it and appends it as a `context/message` after all `tool/result`s in the step. `meta` is the tool's opaque presentation payload from a successful `execute` (the object return form); the loop forwards it onto the `tool/result` session event for result-card rendering. -- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite (changing `arguments`) is deliberately NOT offered (it would desync the pre-execution audit/history/UI from what ran — its own proposed RFC); `ask` degrades to `deny` until the permission system lands. +- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite (changing `arguments`) is deliberately NOT offered (it would desync the pre-execution audit/history/UI from what ran — its own proposed RFC); `ask` is serviced by [`ctx.approval`](../../ui/user-approval/README.md) when a deployment mounts it (`allowed-once` proceeds to dispatch; `rejected`/`cancelled`/`unavailable` deny with distinct reasons) and degrades to `deny` when none is mounted or the execution carries no agent. - `PostToolDecision` — `{kind:'accept', content?, additionalContext?}` (keep the call successful, optionally replacing the model-facing content) | `{kind:'block', feedback, additionalContext?}` (turn it into an `isError` whose content is the corrective feedback). Output replacement is clean because `tool/result` is logged AFTER `execute()` returns. - `ToolCallView` / `ToolResultView` — provider-neutral `card`-tagged render intents a tool returns from `presentCall` / `presentResult` to own how a UI renders ITS calls (see "Tool-owned UI presentation"). ### Extension points - Tool plugins call `ctx.tools.register()` — schemas flow into the assembly automatically. -- `tools/pre-execute` is the allow/deny gate (sandbox, permission, hooks): listeners receive `(exec, next)` and call `next()` to delegate to the default (allow) or return a `PreToolDecision` to short-circuit; a `deny`/`ask` skips dispatch and yields an `isError` result. `tools/execute` is the around-dispatch seam (timeout, retry, metrics): listeners receive `(exec, next)` and call `next()` to delegate to core dispatch (returning its `ToolExecutionResult`, optionally wrapped), or return a replacement result to short-circuit dispatch; the base `next()` IS dispatch-with-normalization, so `await next()` already yields an `isError` result for a thrown/unknown tool (never a raw throw). A wrapper mutates `exec` in place before `next()` — e.g. replacing `exec.signal` with a per-call deadline — because cordis `next()` ignores passed arguments. `tools/post-execute` is the inspect/transform seam: `(exec, result, next)` → a `PostToolDecision` that can replace content, block with feedback, or attach `additionalContext`. Core dispatch is the base of the `tools/execute` waterfall; the tool body keeps its own try/catch so a thrown tool still reaches `post-execute` as an `isError`. All follow the typed-Decision idiom shared with the `agent/*` interception seams (see [`dsh-agent`](../agent/README.md)); `@deepseek-ai/dsh-timeout-policy` is the reference `tools/execute` wrapper. +- `tools/pre-execute` is the allow/deny gate (sandbox, permission, hooks): listeners receive `(exec, next)` and call `next()` to delegate to the default (allow) or return a `PreToolDecision` to short-circuit; a `deny` skips dispatch and yields an `isError` result, and an `ask` resolves through the approval seam first — only a grant dispatches (see `PreToolDecision` above). `tools/execute` is the around-dispatch seam (timeout, retry, metrics): listeners receive `(exec, next)` and call `next()` to delegate to core dispatch (returning its `ToolExecutionResult`, optionally wrapped), or return a replacement result to short-circuit dispatch; the base `next()` IS dispatch-with-normalization, so `await next()` already yields an `isError` result for a thrown/unknown tool (never a raw throw). A wrapper mutates `exec` in place before `next()` — e.g. replacing `exec.signal` with a per-call deadline — because cordis `next()` ignores passed arguments. `tools/post-execute` is the inspect/transform seam: `(exec, result, next)` → a `PostToolDecision` that can replace content, block with feedback, or attach `additionalContext`. Core dispatch is the base of the `tools/execute` waterfall; the tool body keeps its own try/catch so a thrown tool still reaches `post-execute` as an `isError`. All follow the typed-Decision idiom shared with the `agent/*` interception seams (see [`dsh-agent`](../agent/README.md)); `@deepseek-ai/dsh-timeout-policy` is the reference `tools/execute` wrapper. - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas. ### Typed tool parameter schemas diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json index f6425538b1..ff38e40ab2 100644 --- a/packages/core/tools/package.json +++ b/packages/core/tools/package.json @@ -23,6 +23,7 @@ "license": "BSD-3-Clause", "peerDependencies": { "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-user-approval": "^0.0.1", "@deepseek-ai/dsh-code-runtime": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", @@ -34,6 +35,7 @@ }, "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-user-approval": "workspace:^", "@deepseek-ai/dsh-code-runtime": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index e113a0c77c..b624f468bb 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -19,10 +19,13 @@ import { Context, Service } from 'cordis' import z from 'schemastery' import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm' -import { HarnessError } from '@deepseek-ai/dsh-llm' +import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm' import type { Agent, HookContext } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-system-prompt' import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime' +// Type-only: makes `ctx.get('approval')` resolve to the ApprovalService +// augmentation. The seam stays optional at runtime — see `serviceAsk`. +import type {} from '@deepseek-ai/dsh-user-approval' import type { ToolCallView, ToolResultView } from './presentation.ts' import { createRunCodeTool, RUN_CODE_NAME, SDK_SECTION_ORDER } from './code-mode.ts' import { renderToolsSdk } from './ts-types.ts' @@ -83,8 +86,8 @@ declare module 'cordis' { * or return a {@link PreToolDecision} without calling `next()` to * short-circuit. A `deny` skips dispatch and yields an `isError` result; the * tool body never runs. Input rewrite is deliberately NOT offered here (see - * {@link PreToolDecision}); `ask` degrades to deny until the permission - * system lands (`FIXME(permissions)`). + * {@link PreToolDecision}); `ask` is serviced by the `ctx.approval` seam + * when one is mounted, and degrades to deny otherwise. * @param exec - the pending call (name, parsed arguments, caller agent). * @mode waterfall */ @@ -268,8 +271,9 @@ export interface ToolExecutionResult { * would desync the UI from what RAN. That consistency redesign is its own * `proposed` RFC; `TODO(pre-tool-input-rewrite)` anchors it at the call site.) * - `deny` skips dispatch; the loop records an `isError` result carrying `reason`. - * - `ask` is the permission-prompt intent; until the permission system exists it - * degrades to `deny` (`FIXME(permissions)`). + * - `ask` is the permission-prompt intent: serviced as a one-shot decision by + * the `ctx.approval` seam when one is mounted (`allowed-once` proceeds to + * dispatch; every other outcome denies), degrading to `deny` when none is. */ export type PreToolDecision = | { kind: 'allow' } @@ -486,22 +490,17 @@ export class ToolRegistry extends Service { */ async execute(exec: ToolExecution): Promise { try { - // --- Gate: tools/pre-execute. A deny (or an ask, which degrades to deny - // until the permission system lands) skips dispatch entirely. --- - const decision = await this.ctx.waterfall( + // --- Gate: tools/pre-execute. An `ask` resolves through the approval + // seam (or degrades) to allow/deny before the shared deny path. --- + const gate = await this.ctx.waterfall( this, 'tools/pre-execute', exec, () => Promise.resolve({ kind: 'allow' }), ) + const decision = gate.kind === 'ask' ? await this.serviceAsk(exec, gate) : gate if (decision.kind !== 'allow') { - // deny → isError. ask has no permission UI yet, so degrade to deny - // (FIXME(permissions)): a forthcoming permission system turns `ask` into - // a real prompt; today it is the conservative "not allowed". - const reason = decision.kind === 'deny' - ? decision.reason - : decision.reason ?? `tool "${exec.name}" requires approval (not yet supported)` const denied: ToolExecutionResult = { callId: exec.callId, - content: [{ type: 'text', text: `Error: ${reason}` }], + content: [{ type: 'text', text: `Error: ${decision.reason}` }], isError: true, } return await this.postExecute(exec, denied) @@ -540,6 +539,44 @@ export class ToolRegistry extends Service { } } + /** + * Resolve an `ask` decision to allow/deny through the approval seam. The + * seam is consumed opportunistically with `ctx.get('approval')` — a + * deployment that composes no ApprovalService keeps the historical degrade + * to deny, and an unmount mid-session degrades the same way on the next ask. + * An agent-less execution also degrades: without an agent there is no + * session to audit to and no UI to route to. Otherwise the outcome maps + * one-to-one — `allowed-once` proceeds; the three non-grants deny with + * distinct reasons so the model can tell a human "no" from an absent + * approval channel. + */ + private async serviceAsk( + exec: ToolExecution, + ask: Extract, + ): Promise> { + const approval = this.ctx.get('approval') + if (approval === undefined) { + return { kind: 'deny', reason: ask.reason ?? `tool "${exec.name}" requires approval (not yet supported)` } + } + if (exec.agent === undefined) { + return { kind: 'deny', reason: `tool "${exec.name}" requires approval, but the call has no agent to route it through` } + } + const outcome = await approval.request({ + agent: exec.agent, + toolName: exec.name, + callId: exec.callId, + ...ask.reason !== undefined ? { reason: ask.reason } : {}, + ...exec.signal !== undefined ? { signal: exec.signal } : {}, + }) + switch (outcome) { + case 'allowed-once': return { kind: 'allow' } + case 'rejected': return { kind: 'deny', reason: `the user rejected tool "${exec.name}"` } + case 'cancelled': return { kind: 'deny', reason: `approval for tool "${exec.name}" was cancelled` } + case 'unavailable': return { kind: 'deny', reason: `tool "${exec.name}" requires approval, but no approval channel is available` } + default: return assertNever(outcome, 'ApprovalOutcome') + } + } + /** * Run the `tools/post-execute` waterfall over a dispatched `result` and apply * its {@link PostToolDecision}: `accept` keeps the call successful (replacing diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index 5c03a69fc4..8bab060a5d 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => { it('boots every shipped tool package and harvests its model-facing schemas', async () => { const catalog = await collectToolCatalog() const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort() - expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write']) + expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'skill', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write']) // Every tool carries a JSON-Schema `parameters` object (what the model sees). for (const entry of catalog) { for (const schema of entry.schemas) { diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts index cad484640b..ca0ab58206 100644 --- a/packages/core/tools/tests/tools.spec.ts +++ b/packages/core/tools/tests/tools.spec.ts @@ -2,6 +2,8 @@ import { describe, expect, expectTypeOf, it } from 'vitest' import { Context } from 'cordis' import { CallId, HarnessError } from '@deepseek-ai/dsh-llm' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import type { Agent } from '@deepseek-ai/dsh-agent' +import ApprovalService, { type ApprovalOutcome, type ApprovalRequest } from '@deepseek-ai/dsh-user-approval' import ToolRegistry, { defineTool, schemaSpecToJsonSchema, validateArgs, ToolArgsError, ToolNotFoundError, type InferArgs, type SchemaSpec, type PreToolDecision, type PostToolDecision, @@ -158,7 +160,7 @@ describe('ToolRegistry', () => { expect(result.content[0]).toMatchObject({ text: 'Error: denied by policy' }) }) - it('an ask decision degrades to deny until the permission system lands', async () => { + it('an ask decision degrades to deny when no approval seam is mounted', async () => { const ctx = await setup() ctx.tools.register(echoTool) @@ -181,6 +183,107 @@ describe('ToolRegistry', () => { expect(result.content[0]).toMatchObject({ text: 'Error: tool "echo" requires approval (not yet supported)' }) }) + describe('ask routing through ctx.approval', () => { + /** + * A minimal Agent stand-in — the approval seam reaches + * `agent.session.append` and folds `.events`; the seeded open turn + * satisfies request()'s enclosure precondition. + */ + function fakeAgent(): Agent { + return { + session: { events: [{ type: 'turn/start' }], append: () => ({}) }, + } as unknown as Agent + } + + async function approvalSetup() { + const ctx = await setup() + await ctx.plugin(ApprovalService) + ctx.tools.register(echoTool) + return ctx + } + + it('dispatches the tool when the answerer grants allowed-once, forwarding the ask fields', async () => { + const ctx = await approvalSetup() + const agent = fakeAgent() + const controller = new AbortController() + const seen: ApprovalRequest[] = [] + ctx.on('approval/request', (req) => { + seen.push(req) + return Promise.resolve('allowed-once') + }) + ctx.on('tools/pre-execute', async (_exec, _next): Promise => + ({ kind: 'ask', reason: 'hook wants a human' })) + + const result = await ctx.tools.execute({ + callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' }, agent, signal: controller.signal, + }) + + expect(result).toMatchObject({ isError: false, content: [{ type: 'text', text: 'hi' }] }) + expect(seen).toHaveLength(1) + expect(seen[0]).toMatchObject({ agent, toolName: 'echo', callId: 'c1', reason: 'hook wants a human' }) + expect(seen[0]?.signal).toBe(controller.signal) + }) + + it('denies with the user-rejection reason on rejected', async () => { + const ctx = await approvalSetup() + ctx.on('approval/request', () => Promise.resolve('rejected')) + ctx.on('tools/pre-execute', async (_exec, _next): Promise => ({ kind: 'ask' })) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: {}, agent: fakeAgent() }) + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ text: 'Error: the user rejected tool "echo"' }) + }) + + it('denies with the cancellation reason on cancelled', async () => { + const ctx = await approvalSetup() + ctx.on('approval/request', () => Promise.resolve('cancelled')) + ctx.on('tools/pre-execute', async (_exec, _next): Promise => ({ kind: 'ask' })) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: {}, agent: fakeAgent() }) + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ text: 'Error: approval for tool "echo" was cancelled' }) + }) + + it('denies with the no-channel reason when the seam is mounted but nobody answers', async () => { + const ctx = await approvalSetup() + ctx.on('tools/pre-execute', async (_exec, _next): Promise => ({ kind: 'ask' })) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: {}, agent: fakeAgent() }) + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ text: 'Error: tool "echo" requires approval, but no approval channel is available' }) + }) + + it('denies an agent-less execution without asking — nothing to route or audit through', async () => { + const ctx = await approvalSetup() + let asked = false + ctx.on('approval/request', () => { + asked = true + return Promise.resolve('allowed-once') + }) + ctx.on('tools/pre-execute', async (_exec, _next): Promise => ({ kind: 'ask' })) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: {} }) + expect(asked).toBe(false) + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ text: 'Error: tool "echo" requires approval, but the call has no agent to route it through' }) + }) + + it('turns a rogue outcome from a NON-conforming approval stand-in into an isError result', async () => { + // ApprovalService normalizes rogue answers itself; this pins the + // registry's own exhaustiveness backstop by shadowing the service with a + // stand-in that violates the outcome contract. + const ctx = await setup() + ctx.tools.register(echoTool) + ctx.provide('approval', { request: () => Promise.resolve('yolo') } as unknown as ApprovalService) + ctx.on('tools/pre-execute', async (_exec, _next): Promise => ({ kind: 'ask' })) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: {}, agent: fakeAgent() }) + expect(result.isError).toBe(true) + const text = result.content[0]?.type === 'text' ? result.content[0].text : '' + expect(text).toContain('unreachable') + }) + }) + it('a tools/post-execute listener can replace the result content (accept) ', async () => { const ctx = await setup() ctx.tools.register(echoTool) diff --git a/packages/core/tools/tsconfig.json b/packages/core/tools/tsconfig.json index 68edd3b003..95835b38e9 100644 --- a/packages/core/tools/tsconfig.json +++ b/packages/core/tools/tsconfig.json @@ -28,6 +28,9 @@ }, { "path": "../../core/agent" + }, + { + "path": "../../ui/user-approval" } ] } diff --git a/packages/hooks/hook-protocol/tests/runner.spec.ts b/packages/hooks/hook-protocol/tests/runner.spec.ts index 1972a39c99..6f52198a93 100644 --- a/packages/hooks/hook-protocol/tests/runner.spec.ts +++ b/packages/hooks/hook-protocol/tests/runner.spec.ts @@ -26,6 +26,7 @@ function recordingBash(run: (spec: BashExecSpec) => Promise): { ...request.stdin !== undefined ? { stdin: request.stdin } : {}, ...request.env !== undefined ? { env: request.env } : {}, owner: request.owner, + sandboxMode: request.sandboxMode, } }, async run(spec: BashExecSpec): Promise { diff --git a/packages/sandbox/README.md b/packages/sandbox/README.md new file mode 100644 index 0000000000..9e104192d1 --- /dev/null +++ b/packages/sandbox/README.md @@ -0,0 +1,12 @@ +# sandbox/ — process-sandbox capability family + +The confinement half of the [capability-seam split](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md): an abstract provider interface and platform backends. Consumers hand `ctx.sandbox` the exact argv they are about to spawn and spawn the returned (wrapped) argv instead; policy (`SandboxPolicy`: mode + workspace root) rides each call, so different consumers confine under different policies at the same instant. All **product** packages. + +| Package | Role | ctx key | +|---|---|---| +| `sandbox/` | Abstract process-sandbox seam (the `SandboxProvider` contract + the mode/enforcement/policy vocabulary) | `ctx.sandbox` | +| `sandbox-local/` | Local backends by platform chain: Linux `bwrap` else the `landlock-run` launcher (the npm-distributed [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) family, built and released from its own repository), darwin `sandbox-exec`/Seatbelt — multi-candidate chains functionally probed, sole candidates selected directly, verdict cached, fail-closed | (registers `ctx.sandbox`) | + +The seam confines SAME-WORLD subprocesses only (shared filesystem and kernel). Containers, microVMs, and remote executors are NOT backends here — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups; the boundary is recorded in [the sandbox RFC](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md). + +Consumers today: [`bash/bash-sandbox`](../bash/bash-sandbox/) (wraps `['bash', '-c', command]`; see [examples/sandbox-acp-agent](../../examples/sandbox-acp-agent/) for the composed leaf). In-process tools (fs/web) cannot be confined by an OS wrapper — their sandbox semantics are policy at their own seams (the sandbox RFC's cross-family phase). diff --git a/packages/sandbox/sandbox-local/README.md b/packages/sandbox/sandbox-local/README.md new file mode 100644 index 0000000000..abf7511438 --- /dev/null +++ b/packages/sandbox/sandbox-local/README.md @@ -0,0 +1,18 @@ +# @deepseek-ai/dsh-sandbox-local + +Local implementation of the [`@deepseek-ai/dsh-sandbox`](../sandbox/) seam: wraps a caller's argv in a platform confinement runner. Selection is BY PLATFORM, resolved once and cached: each platform names its runner chain, a chain of one is selected directly (probing arbitrates between candidates — a sole candidate leaves nothing to arbitrate), and a chain of several is probed functionally in preference order. Linux: [`bwrap`](https://github.com/containers/bubblewrap) when its probe passes, else the [`landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) Landlock launcher (kernel confinement that needs no userns/mount privileges — see the [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md) for the prebuilt-binary decision and profile-parity notes); darwin: `sandbox-exec` speaking a Seatbelt (SBPL) profile, unprobed. A platform with no chain means `confine()` FAILS CLOSED with the seam's structured `SANDBOX_UNAVAILABLE` error (win32 today: a reserved, deliberately empty chain awaiting an AppContainer-family runner); an unprobed runner that turns out unusable fails closed at EXECUTION instead — it refuses to run the command, and every wrap's `runnerFailureSignatures` let the consumer classify that as a sandbox failure rather than a task failure. Never a silent unconfined passthrough on any path. + +Policy is per call (`SandboxPolicy`: mode + workspace root); the provider holds only the mechanism and the cached ladder verdict. Every wrap reports the selected runner's `enforcement` (`full`, or `partial` on an older Landlock ABI that governs only a subset of accesses — read from the launcher's `--probe` report line) and its `denialSignatures` — the stderr dialect that rung's kernel speaks on a denied file effect (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt), which stderr-inferring consumers match instead of a cross-runner union. A non-empty `runnerCommand` config is the operator's assertion of a runner that fully enforces the bwrap-shaped profile: the ladder and probes are skipped (the wrap carries both Linux denial dialects, the mechanism being unknown) — also the deterministic fake-runner seam for keyless test tiers. Its runner-failure dialect is the OUTER shell's argv0-scoped failure shapes (`exec: : not found`, `: No such file or directory`, `: Permission denied`) — the consumer re-joins the wrap through `bash -c 'exec …'`, so a missing or unexecutable configured runner classifies as a sandbox failure (fail closed at execution), never as a failing command or a denial. `probeTimeoutMs` (default 5000) bounds each functional probe, the escape hatch for hosts slow enough that a timed-out probe would otherwise misread as `SANDBOX_UNAVAILABLE`. + +The Seatbelt profile is allow-default with `(deny file-write*)` plus write allow-lists, so exactly the mode's promised file effects are governed: `read-only` grants the `/dev/null` literal alone; `workspace-write` adds the workspace root, `/tmp`, and the per-user darwin temp dir (`os.tmpdir()` — the platform's real temp area for mkstemp-family tools), every root canonicalized because Seatbelt matches resolved paths (`/tmp` IS `/private/tmp`). Apple marks the `sandbox-exec` CLI deprecated but ships it on every macOS; the functional probe is what fails closed if that ever changes. + +The Landlock launcher comes from the npm package family [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) — an entry package (this package's one runtime dependency) plus per-platform binary packages selected by npm's `os`/`cpu` fields, built and released from [its own repository](https://github.com/deepseek-harness/node-addon-landlock-run). The entry package owns the launcher's CLI contract: `launcherPath()` resolution (a host with no platform package yields a never-existing path whose probe fails exactly like an unenforcing kernel), the functional `probe()`, and `grantArgs()` flag spelling — versioned together with the binary, so probe-report parsing can never drift against it. This provider keeps only the policy side: the mode → grants mapping (`landlockProfileArgs`) and the ladder. The consumer path is rehearsed by `tests/packed-install.e2e.ts`: pack THIS package's closure, install into a throwaway consumer with the launcher family coming from the registry, assert the installed binary executable (a stripped mode bit must not masquerade as a non-enforcing kernel), and confine through it under plain `node`. + +Every rung has its keyless world-proof (`tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, `tests/seatbelt.e2e.ts`), each self-skipping where its runner is absent; CI's `sandbox-e2e` matrix runs all of them against real kernels (bwrap plus one Landlock leg per architecture on Linux, Seatbelt on macOS) and fails on a silent all-skip. + +```yaml +- id: sandbox + name: '@deepseek-ai/dsh-sandbox-local' +``` + +Consumers: [`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/); see [`examples/sandbox-acp-agent`](../../../examples/sandbox-acp-agent/) for the runnable composition. diff --git a/packages/sandbox/sandbox-local/package.json b/packages/sandbox/sandbox-local/package.json new file mode 100644 index 0000000000..d2f8b34161 --- /dev/null +++ b/packages/sandbox/sandbox-local/package.json @@ -0,0 +1,38 @@ +{ + "name": "@deepseek-ai/dsh-sandbox-local", + "description": "Local process-sandbox backends for the DeepSeek Harness sandbox seam: bwrap, the npm-distributed landlock-run launcher, or macOS Seatbelt — functionally probed, fail-closed", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-sandbox": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "node-addon-landlock-run": "0.0.0-test.0", + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-sandbox": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts new file mode 100644 index 0000000000..66f3077319 --- /dev/null +++ b/packages/sandbox/sandbox-local/src/index.ts @@ -0,0 +1,478 @@ +/** + * `LocalSandboxProvider`: the local implementation of the + * `@deepseek-ai/dsh-sandbox` seam. Wraps a caller's argv in a platform + * confinement runner selected BY PLATFORM: each platform names its runner + * chain ({@link PLATFORM_CHAINS}), a chain of one is selected directly (no + * probe — there is nothing to arbitrate), and a chain of several is probed + * FUNCTIONALLY in preference order (build and enforce a real profile once, + * not `--version`), the verdict cached for the provider's lifetime. Linux: + * `bwrap`, else the `landlock-run` Landlock launcher (kernel confinement + * that needs no userns/mount privileges; distributed as the npm package + * family `node-addon-landlock-run` — the decision recorded in + * docs/rfc/implemented/feature/2026-07-06-sandbox.md); darwin: macOS + * `sandbox-exec` speaking a Seatbelt (SBPL) profile, unprobed. + * When the platform has no chain or no candidate passes, + * {@link LocalSandboxProvider.confine} FAILS CLOSED with the seam's + * structured `SANDBOX_UNAVAILABLE` error instead of passing the argv + * through unconfined; an unusable runner selected WITHOUT a probe fails + * closed at execution time instead (it refuses to run the command), which + * the wrap's `runnerFailureSignatures` let consumers classify as a sandbox + * failure rather than a task failure. + * + * @module @deepseek-ai/dsh-sandbox-local + */ + +import { spawnSync } from 'node:child_process' +import { realpathSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { grantArgs as landlockGrantArgs, LAUNCHER_BIN, launcherPath as landlockLauncherPath, probe as defaultProbeLandlock } from 'node-addon-landlock-run' +import { Context } from 'cordis' +import z from 'schemastery' +import { assertNever } from '@deepseek-ai/dsh-llm' +import { SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox' +import type { ConfinedArgv, ConfinedSandboxMode, SandboxEnforcement, SandboxPolicy } from '@deepseek-ai/dsh-sandbox' + +/** Plugin config. All optional — `static Config` supplies the defaults. */ +export interface Config { + /** + * Override the sandbox runner argv (the bwrap-shaped profile arguments are + * appended). A NON-EMPTY argv is the operator's assertion that this runner + * exists and FULLY enforces the profile (confinement reports + * `enforcement: 'full'`, and — the runner's kernel mechanism being unknown + * — carries both Linux file-denial dialects as its denial signatures) — + * the runner chain and its probes are skipped, + * and a broken runner fails loudly at execution time. The operator also + * supplies {@link runnerFailureSignatures}, which distinguish the runner + * refusing its profile from the wrapped command failing normally. + * Absent (or empty — the schema normalizes an omitted array to `[]`): the + * built-in platform chains — Linux `bwrap` then the Landlock launcher + * (probed in that order), darwin `sandbox-exec` (the sole candidate, + * selected without a probe). Used for custom/alternative runners and + * for deterministic fake runners in keyless test tiers. + */ + runnerCommand?: string[] + /** + * Case-insensitive stderr substrings emitted when a configured + * {@link runnerCommand} refuses its profile before executing the wrapped + * command. Required and non-empty with `runnerCommand`; rejected without + * it. Missing/unexecutable runner errors are added automatically from + * `runnerCommand[0]`, while these signatures cover an executable runner's + * own failure dialect. + */ + runnerFailureSignatures?: string[] + /** + * Per-probe timeout in milliseconds for the chain's functional probes + * (default: 5000; must be a positive finite number — Node treats a 0 + * `spawnSync` timeout as UNBOUNDED, so 0 is rejected at construction). A + * probe that exceeds it reads as an unusable rung, so a + * host slow enough to trip the default — cold NFS mounts, heavily loaded + * CI — would otherwise be misclassified `SANDBOX_UNAVAILABLE` with no + * config escape. Bounds ONE probe, and the chain walk runs each at most once + * per provider lifetime. + */ + probeTimeoutMs?: number +} + +/** + * The `bwrap` profile arguments for one policy. The whole host tree is bound + * read-only; a fresh `/dev` keeps `>/dev/null` redirects working and a fresh + * `/proc` keeps process-inspecting tools working. `workspace-write` + * additionally mounts an ephemeral writable `/tmp` and rebinds the workspace + * root read-write (bind order matters: later binds overlay earlier ones). + * Deliberately NO `--unshare-pid` (it would break the process-group kill + * semantics shell consumers rely on) and NO network unsharing (the seam's + * mode vocabulary promises file effects only). + * @param policy - the file-effect policy to express as bwrap arguments. + * @returns the bwrap profile arguments (before the trailing `--` + argv). + */ +export function bwrapProfileArgs(policy: SandboxPolicy): string[] { + const args = ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent'] + if (policy.mode === 'workspace-write') { + args.push('--tmpfs', '/tmp') + args.push('--bind', policy.workspaceRoot, policy.workspaceRoot) + } + return args +} + +/** + * The `landlock-run` grant arguments for one policy — the bwrap + * profile's file-effect semantics expressed as a Landlock allow-list + * (Landlock cannot mount, so there are no fresh/ephemeral filesystems). The + * whole tree is readable and executable; of `/dev`, ONLY `/dev/null` is + * writable — a whole-`/dev` grant would expose real host paths beneath it + * (`/dev/shm`, a shared tmpfs) to persistent writes, which `read-only` + * promises never happen. bwrap can hand out a fresh ephemeral `/dev`; on the + * host's own `/dev` the write grant must be node-by-node, and `>/dev/null` + * is the one redirects need. `workspace-write` adds the HOST `/tmp` (shared + * and persistent, where bwrap's is ephemeral — the honest difference, + * recorded in the sandbox RFC's runner notes) plus the workspace + * root read-write. The flag spelling belongs to `node-addon-landlock-run`'s + * `grantArgs`; this function owns only the policy → grants mapping. + * @param policy - the file-effect policy to express as launcher grants. + * @returns the launcher grant arguments (before `--` + argv). + */ +export function landlockProfileArgs(policy: SandboxPolicy): string[] { + const readWrite = ['/dev/null'] + if (policy.mode === 'workspace-write') { + readWrite.push('/tmp', policy.workspaceRoot) + } + return landlockGrantArgs({ readOnly: ['/'], readWrite }) +} + +/** + * Resolve a granted root to the path the kernel actually sees. Seatbelt path + * filters match the CANONICAL path (symlinks resolved), and the roots this + * profile grants are symlinked on every macOS: `/tmp` is `/private/tmp` and + * the user temp dir lives under `/var` → `/private/var` — an as-spelled + * grant would match nothing. + */ +function canonicalPath(path: string): string { + try { + return realpathSync(path) + } catch { + // realpathSync failed: the path (or a prefix) is missing or unreadable. + // Grant the spelling as-is — an unresolvable root matches nothing until + // it exists, which is the conservative outcome, and inventing a fallback + // resolution here would grant a path the caller never named. + return path + } +} + +/** Quote one path as an SBPL string literal (backslashes and double quotes escaped). */ +function sbplString(path: string): string { + return `"${path.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`)}"` +} + +/** + * The `sandbox-exec` arguments for one policy: `-p` plus a Seatbelt (SBPL) + * profile with the same file-effect semantics as the other dialects, built + * as allow-default → `(deny file-write*)` → write allow-list (later rules + * win), so exactly the mode's promised file effects are governed — network + * and process visibility stay unrestricted, which is all the seam's mode + * vocabulary claims. Of `/dev`, ONLY the `/dev/null` literal is writable + * (the same node-not-directory reasoning as the Landlock grant). + * `workspace-write` adds the workspace root, the host `/tmp`, and the + * per-user darwin temp dir (`os.tmpdir()`, launchd's `TMPDIR`, inherited by + * the confined child) — on darwin that directory IS the platform's `/tmp` + * for every mkstemp-family tool, so omitting it would deny the mode's + * promised temp area. All granted roots are canonicalized because Seatbelt + * matches resolved paths ({@link canonicalPath}); duplicates after + * resolution collapse. + * @param policy - the file-effect policy to express as an SBPL profile. + * @returns the `sandbox-exec` arguments (`-p` + profile, before `--` + argv). + */ +export function seatbeltProfileArgs(policy: SandboxPolicy): string[] { + const forms = ['(version 1)', '(allow default)', '(deny file-write*)', `(allow file-write* (literal ${sbplString('/dev/null')}))`] + if (policy.mode === 'workspace-write') { + const roots = [...new Set([policy.workspaceRoot, '/tmp', tmpdir()].map(canonicalPath))] + forms.push(`(allow file-write* ${roots.map(root => `(subpath ${sbplString(root)})`).join(' ')})`) + } + return ['-p', forms.join(' ')] +} + +/** + * Functional `bwrap` probe: can it actually build the read-only profile on + * this host? (`--version` alone would miss a disabled unprivileged user + * namespace.) Synchronous by design — it runs once, lazily, before the first + * confined wrap, and the chain's verdict is cached for the provider's + * lifetime. `timeoutMs` bounds the probe (the `probeTimeoutMs` config). + * The Landlock rung needs no such helper: resolution (`launcherPath`) and + * the functional probe (`probe`) come from `node-addon-landlock-run`, the + * package family that ships the launcher binary itself, so the probe-report + * parsing can never drift against the binary. + */ +function defaultProbeBwrap(timeoutMs: number): boolean { + const probe = spawnSync('bwrap', ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent', '--', 'true'], { + timeout: timeoutMs, + stdio: 'ignore', + }) + return probe.status === 0 +} + +/** + * Functional Seatbelt probe: apply the real `read-only` profile through + * `sandbox-exec -p` and run `true` under it — exit 0 means the kernel + * accepted and enforced the profile (`sandbox-exec` exits non-zero when + * `sandbox_init` refuses it). A missing `sandbox-exec` (every non-macOS + * host) fails the spawn and probes `unusable`, exactly like the other + * rungs' absent binaries. Apple marks the CLI deprecated but ships it on + * every macOS; if it ever disappears, this probe is what fails closed. + */ +function defaultProbeSeatbelt(seatbeltExec: string, timeoutMs: number): boolean { + const probe = spawnSync(seatbeltExec, [...seatbeltProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { + timeout: timeoutMs, + stdio: 'ignore', + }) + return probe.status === 0 +} + +/** Test seam: inject probe verdicts / a fake launcher / a platform without real runners. */ +export interface SandboxInternals { + /** Replaces `process.platform` for chain selection (exercise any platform's chain from any host). */ + platform?: string + /** Replaces the platform's chain wholesale (walk mechanics — e.g. probing a rung the product chains only reach unprobed). */ + chain?: readonly SelectedRunner['runner'][] + /** Replaces the functional `bwrap` probe (the Linux chain's first rung). */ + probeBwrap?: () => boolean + /** Replaces the functional Landlock launcher probe (the Linux chain's second rung). */ + probeLandlock?: (launcher: string) => SandboxEnforcement | 'unusable' + /** Replaces the functional Seatbelt probe (the darwin chain's sole rung — only consulted if that chain ever grows). */ + probeSeatbelt?: (seatbeltExec: string) => boolean + /** Replaces the resolved `landlock-run` launcher path (a fake launcher script). */ + landlockLauncher?: string + /** Replaces the `sandbox-exec` executable the probe and wraps invoke (a fake script). */ + seatbeltExec?: string +} + +/** The chain's verdict: which runner confines, and how completely it enforces. */ +type SelectedRunner = { runner: 'bwrap' | 'landlock' | 'seatbelt'; enforcement: SandboxEnforcement } + +/** + * The runner chain per platform — selection is BY PLATFORM first, probes + * second: a platform's chain is probed in preference order only when it has + * MORE than one candidate (probing arbitrates; it does not re-validate a + * choice that has no alternative). A platform with no chain fails closed at + * `confine()`. Linux prefers `bwrap` (its mount profile is closest to the + * mode vocabulary) over the Landlock launcher; darwin has exactly one + * candidate, selected without any probe. + */ +const PLATFORM_CHAINS: Record = { + linux: ['bwrap', 'landlock'], + darwin: ['seatbelt'], + // Reserved slot, deliberately empty: Windows support fills it with a + // confinement runner (AppContainer / restricted-token family, shipped from + // its own repository on the landlock-run template) plus a + // SelectedRunner['runner'] union member — the switches' assertNever guards + // then walk the implementer to every site. An empty chain fails closed at + // confine(), identical to an unlisted platform: reserving the slot never + // weakens the fail-closed end. + win32: [], +} + +/** + * Enforcement completeness a rung claims when selected WITHOUT a probe (a + * chain of one). `bwrap` and Seatbelt govern every promised file effect by + * construction, so the claim is a profile fact; `landlock` is listed for the + * table's totality but is unreachable unprobed today (the Linux chain has + * two rungs, so it is only ever selected through its probe, whose report is + * what distinguishes full from per-ABI-partial — and the launcher additionally + * self-reports partial enforcement on stderr at every confined run). + */ +const STATIC_ENFORCEMENT: Record = { + bwrap: 'full', + landlock: 'full', + seatbelt: 'full', +} + +/** + * A probe bound must be a positive finite number: Node treats + * `spawnSync({ timeout: 0 })` as NO timeout, so an unvalidated 0 would + * silently mean "unbounded" — the opposite of what the field promises. + */ +function assertPositiveFinite(name: string, value: number): void { + if (!Number.isFinite(value) || value <= 0) { + throw new Error(`sandbox-local: ${name} must be a positive finite number`) + } +} + +/** + * The denial dialect each runner's kernel speaks — the case-insensitive + * stderr substrings a denied file effect produces under it, carried on every + * wrap (the seam's `ConfinedArgv.denialSignatures`). Kernel facts, not + * tunables: bwrap denies through its read-only bind mounts (EROFS), Landlock + * refuses with EACCES, Seatbelt with EPERM — whose text is also what + * non-file EPERM boundaries print, the residual imprecision the consumer's + * conservative classifier documents. An operator-configured `runnerCommand` + * has an unknown kernel mechanism, so its wraps carry both Linux file-denial + * dialects; bare EPERM stays excluded there (it names non-file boundaries + * the mode vocabulary does not govern). + */ +const DENIAL_SIGNATURES = { + bwrap: ['read-only file system'], + landlock: ['permission denied'], + seatbelt: ['operation not permitted'], + runnerCommand: ['read-only file system', 'permission denied'], +} as const satisfies Record + +/** + * How each runner's OWN failure identifies itself on stderr (the seam's + * `ConfinedArgv.runnerFailureSignatures`): every runner prefixes its error + * lines with its program name, and the shell's runner-not-found message + * carries the same `name: ` shape (`bash: bwrap: command not found`, + * `bash: …/bin/landlock-run: No such file or directory`) — so one substring + * per runner covers both "runner broke" and "runner missing". Consumers + * match these BEFORE the denial dialect: a runner's error text can contain + * denial words (an unopenable grant root reports `Permission denied`), and + * a runner failure means the command never ran at all. + */ +const RUNNER_FAILURE_SIGNATURES = { + bwrap: ['bwrap: '], + landlock: [`${LAUNCHER_BIN}: `], + seatbelt: ['sandbox-exec: '], +} as const satisfies Record + +/** + * Local process-sandbox provider. Registers as `ctx.sandbox`. Stateless + * apart from the cached chain verdict — it spawns nothing but the one-time + * probes, so there is no disposal work beyond cordis' own. + */ +export class LocalSandboxProvider extends SandboxProvider { + // Inline schema call: the config catalog walks `static Config` statically. + static Config: z = z.object({ + runnerCommand: z.array(z.string()).default([]), + runnerFailureSignatures: z.array(z.string()).default([]), + probeTimeoutMs: z.natural().default(5_000), + }) + + /** Test seam (mirrors the bash executors' `internals`). */ + internals: SandboxInternals = {} + + private readonly runnerCommand: string[] | undefined + private readonly configuredRunnerFailureSignatures: string[] + private readonly probeTimeoutMs: number + /** Cached chain verdict; undefined until the first confined wrap needs it. */ + private selectedRunner: SelectedRunner | 'unavailable' | undefined + + constructor(ctx: Context, config: Config) { + super(ctx) + // The schema (static Config) defaults every field — the casts record + // those runtime facts. An empty runnerCommand means "not configured": + // use the platform chain. + const runner = config.runnerCommand as string[] + const runnerFailureSignatures = config.runnerFailureSignatures as string[] + if (runner.length === 0 && runnerFailureSignatures.length > 0) { + throw new Error('sandbox-local: runnerFailureSignatures requires runnerCommand') + } + if (runner.length > 0 && runnerFailureSignatures.length === 0) { + throw new Error('sandbox-local: runnerCommand requires at least one runnerFailureSignatures entry') + } + if (runnerFailureSignatures.some(signature => signature.trim().length === 0)) { + throw new Error('sandbox-local: runnerFailureSignatures entries must be non-empty') + } + this.runnerCommand = runner.length > 0 ? runner : undefined + this.configuredRunnerFailureSignatures = runnerFailureSignatures + this.probeTimeoutMs = config.probeTimeoutMs as number + assertPositiveFinite('probeTimeoutMs', this.probeTimeoutMs) + } + + /** + * Wrap `argv` in the selected runner's invocation for `policy` — the + * configured `runnerCommand` when present (the operator's assertion, no + * probe), else the platform chain's runner speaking its own profile + * dialect. Every wrap carries the runner's enforcement completeness, its + * denial dialect, and its runner-failure signatures. + * @param argv - the exact argv the caller is about to spawn. + * @param policy - the file-effect policy this execution runs under. + * @returns the wrapped argv plus the selected backend's enforcement + * completeness, denial signatures, and runner-failure signatures; + * throws the fail-closed `SANDBOX_UNAVAILABLE` error when the platform + * has no usable runner. + */ + confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv { + if (this.runnerCommand !== undefined) { + const argv0 = this.runnerCommand[0] as string + return { + argv: [...this.runnerCommand, ...bwrapProfileArgs(policy), '--', ...argv], + enforcement: 'full', + denialSignatures: DENIAL_SIGNATURES.runnerCommand, + // The operator names the configured runner's OWN pre-exec refusal + // dialect; the consumer additionally re-joins the wrap through an + // outer `bash -c 'exec …'`, so we can add the missing/unexecutable + // outer-shell shapes ourselves. Scoping every automatic shape to + // argv0 keeps in-command errors out (a bare `exec:`/`Permission + // denied` prefix would claim tool output; `exec: : not found` + // cannot). The residual text-collision trade is documented by the + // seam's conservative classifier contract. + runnerFailureSignatures: [ + ...this.configuredRunnerFailureSignatures, + `exec: ${argv0}: not found`, + `${argv0}: No such file or directory`, + `${argv0}: Permission denied`, + ], + } + } + const selected = this.selectRunner(policy.mode) + return { + argv: [...this.runnerArgv(selected.runner, policy), '--', ...argv], + enforcement: selected.enforcement, + denialSignatures: DENIAL_SIGNATURES[selected.runner], + runnerFailureSignatures: RUNNER_FAILURE_SIGNATURES[selected.runner], + } + } + + /** The selected rung's runner invocation (program + profile arguments) for one policy. */ + private runnerArgv(runner: SelectedRunner['runner'], policy: SandboxPolicy): string[] { + switch (runner) { + case 'bwrap': return ['bwrap', ...bwrapProfileArgs(policy)] + case 'landlock': return [this.landlockLauncher(), ...landlockProfileArgs(policy)] + case 'seatbelt': return [this.seatbeltExec(), ...seatbeltProfileArgs(policy)] + default: return assertNever(runner) + } + } + + /** + * Resolve which runner confines commands, once, for the provider's + * lifetime: this platform's chain ({@link PLATFORM_CHAINS}), its sole + * candidate selected directly, multiple candidates arbitrated by + * functional probes in chain order. Fail closed when the platform has no + * chain or no candidate passes — the command never runs. + */ + private selectRunner(mode: ConfinedSandboxMode): SelectedRunner { + this.selectedRunner ??= this.chainVerdict() + if (this.selectedRunner === 'unavailable') throw new SandboxUnavailableError(mode) + return this.selectedRunner + } + + /** Walk this platform's chain: sole candidate unprobed, several probed in order, none usable → unavailable. */ + private chainVerdict(): SelectedRunner | 'unavailable' { + const chain = this.internals.chain ?? PLATFORM_CHAINS[this.internals.platform ?? process.platform] ?? [] + const [first, ...rest] = chain + if (first === undefined) return 'unavailable' + // One candidate = nothing to arbitrate: select it without probing. Its + // runner fails closed at EXECUTION time if unusable (refuses to run the + // command), and the wrap's runnerFailureSignatures let the consumer + // classify that as a sandbox failure — never a silent unconfined run, + // never a plain task failure. + if (rest.length === 0) return { runner: first, enforcement: STATIC_ENFORCEMENT[first] } + for (const runner of chain) { + const enforcement = this.probeRunner(runner) + if (enforcement !== 'unusable') return { runner, enforcement } + } + return 'unavailable' + } + + /** One rung's functional probe (each at most once, via the chain walk). */ + private probeRunner(runner: SelectedRunner['runner']): SandboxEnforcement | 'unusable' { + // bwrap's mount profile and Seatbelt's deny-file-write* profile govern + // every promised file effect by construction, so their passing probes + // are always full enforcement; only the Landlock launcher's probe report + // distinguishes full from per-ABI-partial. + switch (runner) { + case 'bwrap': { + const probe = this.internals.probeBwrap ?? (() => defaultProbeBwrap(this.probeTimeoutMs)) + return probe() ? 'full' : 'unusable' + } + case 'landlock': { + const probe = this.internals.probeLandlock ?? (launcher => defaultProbeLandlock(launcher, { timeoutMs: this.probeTimeoutMs })) + return probe(this.landlockLauncher()) + } + case 'seatbelt': { + const probe = this.internals.probeSeatbelt ?? (exec => defaultProbeSeatbelt(exec, this.probeTimeoutMs)) + return probe(this.seatbeltExec()) ? 'full' : 'unusable' + } + default: return assertNever(runner) + } + } + + /** The Landlock launcher to probe and exec (test seam over the resolved one). */ + private landlockLauncher(): string { + return this.internals.landlockLauncher ?? landlockLauncherPath() + } + + /** The `sandbox-exec` executable to probe and exec (test seam over the system one). */ + private seatbeltExec(): string { + return this.internals.seatbeltExec ?? 'sandbox-exec' + } +} + +export default LocalSandboxProvider diff --git a/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts b/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts new file mode 100644 index 0000000000..da6e683da1 --- /dev/null +++ b/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts @@ -0,0 +1,118 @@ +import { spawnSync } from 'node:child_process' +import { existsSync, readFileSync, rmSync } from 'node:fs' +import { mkdtemp, rm } from 'node:fs/promises' +import { homedir, tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox' +import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local' + +/** + * KEYLESS bwrap integration proof for the BACKEND: the REAL `bwrap` confining + * REAL processes through `confine()` + a direct spawn of the returned argv. + * Nothing is forced off: bwrap is the ladder's FIRST rung, so a passing probe + * selects it naturally — the wrap shape assertion pins that. Verifies the + * WORLD (files exist or don't) and that the kernel's denial text matches the + * dialect the wrap advertises; the through-`ctx.bash` consumer proof lives + * with `@deepseek-ai/dsh-bash-sandbox`. + * + * Self-skips wherever the functional probe fails — no `bwrap` on PATH, or a + * host that denies unprivileged user namespaces (the probe is the same + * profile the provider enforces, so skip conditions match runtime exactly). + * + * Workspaces for the workspace-write tests live under the HOME directory on + * purpose: bwrap's `/tmp` is an EPHEMERAL mount (the documented + * bwrap-profile difference — pinned by its own test below), so only a + * workspace OUTSIDE `/tmp` proves the workspace-root rebind itself. + */ + +const probe = spawnSync('bwrap', [...bwrapProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' }) +const bwrapUsable = probe.status === 0 + +let ctx: Context | undefined +const tempDirs: string[] = [] +const tempFiles: string[] = [] + +afterEach(async () => { + await ctx?.fiber.dispose() + ctx = undefined + await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) + for (const file of tempFiles.splice(0)) rmSync(file, { force: true }) +}) + +async function tempDir(base: string): Promise { + const dir = await mkdtemp(join(base, 'dsh-bwrap-e2e-')) + tempDirs.push(dir) + return dir +} + +async function provider(): Promise { + ctx = new Context() + await ctx.plugin(LocalSandboxProvider, {}) + return ctx.sandbox as LocalSandboxProvider +} + +/** Confine a shell command under `policy` and run it for real; returns the spawn result and the wrap's facts. */ +function runConfined(sandbox: LocalSandboxProvider, command: string, policy: SandboxPolicy) { + const confined = sandbox.confine(['bash', '-c', command], policy) + const result = spawnSync(confined.argv[0] as string, confined.argv.slice(1), { timeout: 30_000, encoding: 'utf8' }) + return { result, confined } +} + +describe.skipIf(!bwrapUsable)('sandbox-local: real bwrap confinement', () => { + it('the passing probe selects the bwrap rung naturally — first in the ladder, full enforcement, EROFS dialect', async () => { + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const confined = sandbox.confine(['true'], { mode: 'read-only', workspaceRoot: workdir }) + expect(confined.argv[0]).toBe('bwrap') + expect(confined.enforcement).toBe('full') + expect(confined.denialSignatures).toEqual(['read-only file system']) + }) + + it('read-only denies a write — the file must NOT exist, and the kernel speaks the advertised dialect', async () => { + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const { result } = runConfined(sandbox, `echo hi > ${workdir}/denied.txt`, { mode: 'read-only', workspaceRoot: workdir }) + expect(result.status).not.toBe(0) + // The wrap's denialSignatures must be what the kernel actually prints. + expect(result.stderr.toLowerCase()).toContain('read-only file system') + expect(existsSync(join(workdir, 'denied.txt'))).toBe(false) + }) + + it('read-only keeps the tree readable/executable and the fresh /dev/null writable', async () => { + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const { result } = runConfined(sandbox, 'ls / > /dev/null && echo dev-ok', { mode: 'read-only', workspaceRoot: workdir }) + expect(result.status).toBe(0) + expect(result.stdout).toBe('dev-ok\n') + }) + + it('workspace-write lands a write inside the workspace root and still denies one beside it', async () => { + const workdir = await tempDir(homedir()) + const outside = await tempDir(homedir()) + const sandbox = await provider() + + const inside = runConfined(sandbox, `printf bwrap-ok > ${workdir}/allowed.txt`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(inside.result.status).toBe(0) + expect(readFileSync(join(workdir, 'allowed.txt'), 'utf8')).toBe('bwrap-ok') + + const denied = runConfined(sandbox, `echo hi > ${outside}/denied.txt`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(denied.result.status).not.toBe(0) + expect(existsSync(join(outside, 'denied.txt'))).toBe(false) + }) + + it('workspace-write mounts an EPHEMERAL /tmp: the write succeeds inside, the host /tmp stays untouched', async () => { + // The documented bwrap-profile difference: Landlock and Seatbelt grant + // the HOST temp areas, bwrap swaps in a fresh tmpfs that dies with the + // process — the strongest of the three temp semantics. + const workdir = await tempDir(homedir()) + const target = `/tmp/dsh-bwrap-e2e-ephemeral-${process.pid}.txt` + tempFiles.push(target) + const sandbox = await provider() + const { result } = runConfined(sandbox, `printf tmp-ok > ${target} && cat ${target}`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(result.status).toBe(0) + expect(result.stdout).toBe('tmp-ok') + expect(existsSync(target)).toBe(false) + }) +}) diff --git a/packages/sandbox/sandbox-local/tests/landlock.e2e.ts b/packages/sandbox/sandbox-local/tests/landlock.e2e.ts new file mode 100644 index 0000000000..104d3b318a --- /dev/null +++ b/packages/sandbox/sandbox-local/tests/landlock.e2e.ts @@ -0,0 +1,118 @@ +import { spawnSync } from 'node:child_process' +import { existsSync, readFileSync } from 'node:fs' +import { mkdtemp, rm } from 'node:fs/promises' +import { homedir, tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox' +import { launcherPath } from 'node-addon-landlock-run' +import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local' + +/** + * KEYLESS Landlock integration proof for the BACKEND: the REAL npm-distributed + * `landlock-run` launcher (`node-addon-landlock-run`) confining REAL processes through `confine()` + a direct + * spawn of the returned argv, with the bwrap rung forced off so the ladder + * lands on the launcher. Verifies the WORLD (files exist or don't), not the + * wrapper argv alone; the through-`ctx.bash` consumer proof lives with + * `@deepseek-ai/dsh-bash-sandbox`. + * + * Self-skips when the running kernel does not enforce Landlock (or this + * platform has no launcher package — the probe cannot pass then). The + * binary itself arrives with `pnpm install`, so absence is not a checkout + * state. + * + * Workspaces live under the HOME directory on purpose: `workspace-write` + * grants the host `/tmp` wholesale (the documented Landlock-profile + * difference), so only a workspace OUTSIDE `/tmp` proves the workspace-root + * grant itself. + */ + +const probe = spawnSync(launcherPath(), ['--probe'], { timeout: 5_000, encoding: 'utf8' }) +const landlockUsable = probe.status === 0 +/** The running kernel's enforcement level, from the launcher's probe report — every wrap below must carry exactly this. */ +const enforcement = /partially enforced/.test(probe.stdout ?? '') ? 'partial' : 'full' + +let ctx: Context | undefined +const tempDirs: string[] = [] + +afterEach(async () => { + await ctx?.fiber.dispose() + ctx = undefined + await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) +}) + +async function tempDir(base: string): Promise { + const dir = await mkdtemp(join(base, 'dsh-landlock-e2e-')) + tempDirs.push(dir) + return dir +} + +async function provider(): Promise { + ctx = new Context() + await ctx.plugin(LocalSandboxProvider, {}) + const sandbox = ctx.sandbox as LocalSandboxProvider + sandbox.internals = { probeBwrap: () => false } + return sandbox +} + +/** Confine a shell command under `policy` and run it for real; returns the spawn result and the wrap's enforcement. */ +function runConfined(sandbox: LocalSandboxProvider, command: string, policy: SandboxPolicy) { + const confined = sandbox.confine(['bash', '-c', command], policy) + const result = spawnSync(confined.argv[0] as string, confined.argv.slice(1), { timeout: 30_000, encoding: 'utf8' }) + return { result, enforcement: confined.enforcement } +} + +describe.skipIf(!landlockUsable)('sandbox-local: real Landlock confinement through the bundled launcher', () => { + it('read-only denies a write — the file must NOT exist, the wrap reports the probed enforcement', async () => { + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const { result, enforcement: wrapped } = runConfined(sandbox, `echo hi > ${workdir}/denied.txt`, { mode: 'read-only', workspaceRoot: workdir }) + expect(result.status).not.toBe(0) + expect(wrapped).toBe(enforcement) + expect(existsSync(join(workdir, 'denied.txt'))).toBe(false) + }) + + it('read-only keeps the tree readable/executable and /dev/null writable', async () => { + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const { result } = runConfined(sandbox, 'ls / > /dev/null && echo dev-ok', { mode: 'read-only', workspaceRoot: workdir }) + expect(result.status).toBe(0) + expect(result.stdout).toBe('dev-ok\n') + }) + + it('read-only denies a write beneath the host /dev (the /dev/shm tmpfs must stay untouched)', async () => { + // The grant is /dev/null the FILE, not /dev the directory: /dev/shm is a + // world-writable host tmpfs, and a write landing there would be exactly + // the persistent host effect read-only promises never happen. + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const target = `/dev/shm/dsh-landlock-e2e-${process.pid}` + const { result } = runConfined(sandbox, `echo hi > ${target}`, { mode: 'read-only', workspaceRoot: workdir }) + expect(result.status).not.toBe(0) + expect(existsSync(target)).toBe(false) + }) + + it('workspace-write lands a write inside the workspace root and still denies one beside it', async () => { + const workdir = await tempDir(homedir()) + const outside = await tempDir(homedir()) + const sandbox = await provider() + + const inside = runConfined(sandbox, `printf landlock-ok > ${workdir}/allowed.txt`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(inside.result.status).toBe(0) + expect(readFileSync(join(workdir, 'allowed.txt'), 'utf8')).toBe('landlock-ok') + + const denied = runConfined(sandbox, `echo hi > ${outside}/denied.txt`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(denied.result.status).not.toBe(0) + expect(existsSync(join(outside, 'denied.txt'))).toBe(false) + }) + + it('workspace-write grants the host /tmp (the documented Landlock-profile difference)', async () => { + const workdir = await tempDir(homedir()) + const scratch = await tempDir(tmpdir()) + const sandbox = await provider() + const { result } = runConfined(sandbox, `printf tmp-ok > ${scratch}/scratch.txt`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(result.status).toBe(0) + expect(readFileSync(join(scratch, 'scratch.txt'), 'utf8')).toBe('tmp-ok') + }) +}) diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts new file mode 100644 index 0000000000..852a50e1e9 --- /dev/null +++ b/packages/sandbox/sandbox-local/tests/local.spec.ts @@ -0,0 +1,371 @@ +/** + * LocalSandboxProvider tests. No real runner is assumed to exist on the test + * host: `runnerCommand` injects deterministic runner argvs, and `internals` + * injects probe verdicts plus fake Landlock launcher / `sandbox-exec` + * scripts, so profile dialects, ladder selection, verdict caching, + * probe-report parsing, per-rung denial signatures, and fail-closed behavior + * are all exercised through the real `confine()` path. + */ + +import { mkdtempSync, realpathSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox' +import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox' +import { + bwrapProfileArgs, + landlockProfileArgs, + LocalSandboxProvider, + seatbeltProfileArgs, +} from '@deepseek-ai/dsh-sandbox-local' +import type { Config } from '@deepseek-ai/dsh-sandbox-local' + +const RO: SandboxPolicy = { mode: 'read-only', workspaceRoot: '/ws' } +const WW: SandboxPolicy = { mode: 'workspace-write', workspaceRoot: '/ws' } + +async function setup(config: Config = {}, internals: LocalSandboxProvider['internals'] = {}) { + const ctx = new Context() + await ctx.plugin(LocalSandboxProvider, config) + const sandbox = ctx.sandbox as LocalSandboxProvider + sandbox.internals = internals + return { ctx, sandbox } +} + +/** Write an executable fake `landlock-run` that answers `--probe` with `report`. */ +function fakeLauncher(report = 'landlock: fully enforced'): string { + const dir = mkdtempSync(join(tmpdir(), 'dsh-fake-landlock-')) + const launcher = join(dir, 'landlock-run') + writeFileSync(launcher, `#!/bin/sh\nif [ "$1" = "--probe" ]; then echo "${report}"; exit 0; fi\nexit 125\n`, { mode: 0o755 }) + return launcher +} + +/** Write an executable fake `sandbox-exec` that exits `status` for any invocation. */ +function fakeSeatbeltExec(status: number): string { + const dir = mkdtempSync(join(tmpdir(), 'dsh-fake-seatbelt-')) + const exec = join(dir, 'sandbox-exec') + writeFileSync(exec, `#!/bin/sh\nexit ${status}\n`, { mode: 0o755 }) + return exec +} + +/** The seatbelt read-only profile — every seatbelt profile starts with these forms. */ +const SEATBELT_RO_PROFILE = '(version 1) (allow default) (deny file-write*) (allow file-write* (literal "/dev/null"))' + +describe('profile dialects', () => { + it('bwrap read-only: whole tree read-only with fresh /dev and /proc, no writable mounts', () => { + expect(bwrapProfileArgs(RO)).toEqual(['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent']) + }) + + it('bwrap workspace-write: adds an ephemeral /tmp and rebinds the workspace root', () => { + expect(bwrapProfileArgs(WW)).toEqual([ + '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent', + '--tmpfs', '/tmp', '--bind', '/ws', '/ws', + ]) + }) + + it('landlock read-only: readable tree plus a writable /dev/null, nothing else', () => { + // /dev/null specifically, NOT /dev: a whole-/dev grant would let confined + // commands write real host paths beneath it (/dev/shm) under read-only. + expect(landlockProfileArgs(RO)).toEqual(['--ro', '/', '--rw', '/dev/null']) + }) + + it('landlock workspace-write: adds the host /tmp and the workspace root', () => { + expect(landlockProfileArgs(WW)).toEqual(['--ro', '/', '--rw', '/dev/null', '--rw', '/tmp', '--rw', '/ws']) + }) + + it('seatbelt read-only: allow-default with every file write denied except the /dev/null literal', () => { + expect(seatbeltProfileArgs(RO)).toEqual(['-p', SEATBELT_RO_PROFILE]) + }) + + it('seatbelt workspace-write: one more allow for the canonicalized workspace root, /tmp, and the user temp dir', () => { + // `/ws` does not exist, so it is granted as spelled (the canonicalization + // fallback); `/tmp` and `os.tmpdir()` exist everywhere and are granted + // CANONICALIZED — Seatbelt matches resolved paths (`/tmp` IS + // `/private/tmp` on macOS), and both collapse to one grant on hosts + // where they resolve to the same directory. + const roots = [...new Set(['/ws', realpathSync('/tmp'), realpathSync(tmpdir())])] + const allow = `(allow file-write* ${roots.map(root => `(subpath "${root}")`).join(' ')})` + expect(seatbeltProfileArgs(WW)).toEqual(['-p', `${SEATBELT_RO_PROFILE} ${allow}`]) + }) + + it('seatbelt workspace-write dedups a workspace root that already IS the temp dir', () => { + const profile = seatbeltProfileArgs({ mode: 'workspace-write', workspaceRoot: tmpdir() })[1] as string + const grant = `(subpath "${realpathSync(tmpdir())}")` + expect(profile).toContain(grant) + expect(profile.split(grant)).toHaveLength(2) + }) +}) + +describe('runnerCommand config', () => { + it('a non-empty runnerCommand skips the chain: runner argv + bwrap-shaped profile + -- + caller argv, asserted full', async () => { + const probeBwrap = vi.fn(() => false) + const probeLandlock = vi.fn(() => 'unusable' as const) + const probeSeatbelt = vi.fn(() => false) + const { sandbox } = await setup({ + runnerCommand: ['fake-runner', '--flag'], + runnerFailureSignatures: ['fake-runner: profile rejected'], + }, { probeBwrap, probeLandlock, probeSeatbelt }) + const confined = sandbox.confine(['bash', '-c', 'echo hi'], WW) + expect(confined).toEqual({ + argv: ['fake-runner', '--flag', ...bwrapProfileArgs(WW), '--', 'bash', '-c', 'echo hi'], + enforcement: 'full', + // An operator runner's kernel mechanism is unknown: both Linux + // file-denial dialects, never bare EPERM. + denialSignatures: ['read-only file system', 'permission denied'], + // The runner's own dialect is unknown, but the consumer re-joins the + // wrap through an outer `bash -c 'exec …'` — a missing or + // unexecutable runner fails with the OUTER shell's argv0-scoped + // shapes, and those classify as sandbox failures like any rung. + runnerFailureSignatures: [ + 'fake-runner: profile rejected', + 'exec: fake-runner: not found', + 'fake-runner: No such file or directory', + 'fake-runner: Permission denied', + ], + }) + expect(probeBwrap).not.toHaveBeenCalled() + expect(probeLandlock).not.toHaveBeenCalled() + expect(probeSeatbelt).not.toHaveBeenCalled() + }) + + it('an EMPTY runnerCommand means unconfigured: the platform chain still gates the wrap', async () => { + const probeBwrap = vi.fn(() => false) + const { sandbox } = await setup({ runnerCommand: [] }, { platform: 'linux', probeBwrap, probeLandlock: () => 'unusable' }) + expect(() => sandbox.confine(['true'], RO)).toThrow(SandboxUnavailableError) + expect(probeBwrap).toHaveBeenCalledTimes(1) + }) + + it('requires an operator-owned failure dialect for every configured runner', async () => { + await expect(setup({ runnerCommand: ['fake-runner'] })).rejects.toThrow( + 'runnerCommand requires at least one runnerFailureSignatures entry', + ) + }) + + it('rejects runner failure signatures when no custom runner consumes them', async () => { + await expect(setup({ runnerFailureSignatures: ['profile rejected'] })).rejects.toThrow( + 'runnerFailureSignatures requires runnerCommand', + ) + }) + + it('rejects blank configured-runner failure signatures', async () => { + await expect(setup({ runnerCommand: ['fake-runner'], runnerFailureSignatures: [' '] })).rejects.toThrow( + 'runnerFailureSignatures entries must be non-empty', + ) + }) +}) + +describe('the platform chains', () => { + it('linux probes bwrap first: a passing probe wraps with the bwrap dialect at full enforcement', async () => { + const probeBwrap = vi.fn(() => true) + const probeLandlock = vi.fn(() => 'full' as const) + const { sandbox } = await setup({}, { platform: 'linux', probeBwrap, probeLandlock }) + const confined = sandbox.confine(['true'], RO) + expect(confined).toEqual({ + argv: ['bwrap', ...bwrapProfileArgs(RO), '--', 'true'], + enforcement: 'full', + denialSignatures: ['read-only file system'], + runnerFailureSignatures: ['bwrap: '], + }) + expect(probeLandlock).not.toHaveBeenCalled() + }) + + it('linux falls back to the launcher when the bwrap probe fails, speaking the landlock dialect', async () => { + const probeBwrap = vi.fn(() => false) + const probeLandlock = vi.fn(() => 'full' as const) + const launcher = fakeLauncher() + const { sandbox } = await setup({}, { platform: 'linux', probeBwrap, probeLandlock, landlockLauncher: launcher }) + const confined = sandbox.confine(['bash', '-c', 'echo hi'], WW) + expect(confined).toEqual({ + argv: [launcher, ...landlockProfileArgs(WW), '--', 'bash', '-c', 'echo hi'], + enforcement: 'full', + denialSignatures: ['permission denied'], + runnerFailureSignatures: ['landlock-run: '], + }) + expect(probeLandlock).toHaveBeenCalledWith(launcher) + }) + + it('darwin selects its sole candidate WITHOUT probing: nothing to arbitrate', async () => { + // The safety property moves to execution time: an unusable sandbox-exec + // refuses to run the command, and the wrap's runnerFailureSignatures let + // the consumer classify that as a sandbox failure, not a task failure. + const probeSeatbelt = vi.fn(() => true) + const { sandbox } = await setup({}, { platform: 'darwin', probeSeatbelt }) + const confined = sandbox.confine(['bash', '-c', 'echo hi'], RO) + expect(confined).toEqual({ + argv: ['sandbox-exec', ...seatbeltProfileArgs(RO), '--', 'bash', '-c', 'echo hi'], + enforcement: 'full', + denialSignatures: ['operation not permitted'], + runnerFailureSignatures: ['sandbox-exec: '], + }) + expect(probeSeatbelt).not.toHaveBeenCalled() + }) + + it('a platform with no chain fails closed without a single probe: the command never runs', async () => { + const probeBwrap = vi.fn(() => true) + const probeLandlock = vi.fn(() => 'full' as const) + const probeSeatbelt = vi.fn(() => true) + const { sandbox } = await setup({}, { platform: 'freebsd', probeBwrap, probeLandlock, probeSeatbelt }) + expect(() => sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE })) + expect(probeBwrap).not.toHaveBeenCalled() + expect(probeLandlock).not.toHaveBeenCalled() + expect(probeSeatbelt).not.toHaveBeenCalled() + }) + + it('win32 is a reserved EMPTY chain: fails closed identically until a Windows runner fills it', async () => { + // The slot exists so Windows support is an additive fill-in (chain entry + // + runner union member), never a redesign — and reserving it must not + // weaken the fail-closed end in the meantime. + const { sandbox } = await setup({}, { platform: 'win32' }) + expect(() => sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) + }) + + it('caches the verdict for the provider lifetime: one chain walk across wraps', async () => { + const probeBwrap = vi.fn(() => true) + const { sandbox } = await setup({}, { platform: 'linux', probeBwrap }) + sandbox.confine(['true'], RO) + sandbox.confine(['true'], WW) + expect(probeBwrap).toHaveBeenCalledTimes(1) + }) + + it('the unavailable verdict is cached too, and the error is structured', async () => { + const probeBwrap = vi.fn(() => false) + const probeLandlock = vi.fn(() => 'unusable' as const) + const { sandbox } = await setup({}, { platform: 'linux', probeBwrap, probeLandlock }) + expect(() => sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE })) + expect(() => sandbox.confine(['true'], RO)).toThrow(SandboxUnavailableError) + expect(probeBwrap).toHaveBeenCalledTimes(1) + expect(probeLandlock).toHaveBeenCalledTimes(1) + }) + + it('a multi-rung chain probes a seatbelt rung like any other (the walk, not the platform table, decides)', async () => { + // The product chains reach seatbelt only as darwin's sole (unprobed) + // candidate; the chain seam exercises the probing path it would take in + // a grown chain, keeping the default seatbelt probe honest. + const exec = fakeSeatbeltExec(0) + const probeBwrap = vi.fn(() => false) + const { sandbox } = await setup({}, { chain: ['bwrap', 'seatbelt'], probeBwrap, seatbeltExec: exec }) + const confined = sandbox.confine(['true'], RO) + expect(confined.argv[0]).toBe(exec) + expect(confined.enforcement).toBe('full') + expect(probeBwrap).toHaveBeenCalledTimes(1) + }) + + it('a rogue chain entry throws via the probe walk\'s exhaustiveness guard (closed union)', async () => { + // Same convention as the wrap switch below: the union is closed, so a + // runner added later fails to compile at the probe switch instead of + // silently selecting without a probe. Only a cast can reach the guard. + const { sandbox } = await setup({}, { chain: ['chroot', 'bwrap'] as unknown as readonly ['bwrap'] }) + expect(() => sandbox.confine(['true'], RO)).toThrow('unreachable variant') + }) + + it('a rogue cached runner tag throws via the exhaustiveness guard (closed union)', async () => { + // The wrap switches on the chain verdict's runner tag and ends with + // assertNever: a rogue tag (only reachable by a cast — the union is + // closed and chainVerdict writes only its own literals) must throw, so a + // runner added later fails to compile at the switch instead of silently + // wrapping with another runner's dialect. + const { sandbox } = await setup() + ;(sandbox as unknown as { selectedRunner: unknown }).selectedRunner = { runner: 'chroot', enforcement: 'full' } + expect(() => sandbox.confine(['true'], RO)).toThrow('unreachable variant') + }) + + it('runs the real default probes on the linux chain when none are injected (usable here or fail closed there)', async () => { + // Pinning the platform (not the probes) makes the REAL defaultProbeBwrap + // spawn run on every host: bwrap answers on a Linux box, ENOENT reads as + // an unusable rung anywhere else — either way the walk is genuine. + const { sandbox } = await setup({}, { platform: 'linux' }) + const verdict = (() => { + try { + sandbox.confine(['true'], RO) + return 'usable' + } catch (error: unknown) { + if (error instanceof SandboxUnavailableError) return 'unavailable' + throw error + } + })() + expect(['usable', 'unavailable']).toContain(verdict) + }) + + it('walks the real platform chain when nothing is injected (usable here or fail closed there)', async () => { + const { sandbox } = await setup({}, {}) + const verdict = (() => { + try { + sandbox.confine(['true'], RO) + return 'usable' + } catch (error: unknown) { + if (error instanceof SandboxUnavailableError) return 'unavailable' + throw error + } + })() + expect(['usable', 'unavailable']).toContain(verdict) + }) +}) + +describe('the default landlock probe (launcher CLI contract)', () => { + it('parses a fully-enforced probe report as full enforcement', async () => { + const { sandbox } = await setup({}, { platform: 'linux', probeBwrap: () => false, landlockLauncher: fakeLauncher() }) + expect(sandbox.confine(['true'], RO).enforcement).toBe('full') + }) + + it('parses a partially-enforced (older-ABI) probe report as partial enforcement', async () => { + const launcher = fakeLauncher('landlock: partially enforced (older ABI)') + const { sandbox } = await setup({}, { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }) + expect(sandbox.confine(['true'], RO).enforcement).toBe('partial') + }) + + it('reads a failing launcher as unusable: the chain ends and fails closed', async () => { + const dir = mkdtempSync(join(tmpdir(), 'dsh-fake-landlock-')) + const launcher = join(dir, 'landlock-run') + writeFileSync(launcher, '#!/bin/sh\nexit 125\n', { mode: 0o755 }) + const { sandbox } = await setup({}, { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }) + expect(() => sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) + }) +}) + +describe('probeTimeoutMs config', () => { + it('rejects 0 at construction: Node treats a 0 spawnSync timeout as UNBOUNDED, the opposite of the field', async () => { + const ctx = new Context() + await expect(ctx.plugin(LocalSandboxProvider, { probeTimeoutMs: 0 })) + .rejects.toThrow(/probeTimeoutMs must be a positive finite number/) + }) + + it('bounds the default probes: a launcher slower than the configured timeout reads as unusable', async () => { + // The same sleeping launcher passes under the default 5000ms budget and + // fails under a 250ms one — the config demonstrably reaches spawnSync. + const dir = mkdtempSync(join(tmpdir(), 'dsh-slow-landlock-')) + const launcher = join(dir, 'landlock-run') + writeFileSync(launcher, '#!/bin/sh\nsleep 1\necho "landlock: fully enforced"\nexit 0\n', { mode: 0o755 }) + + const patient = await setup({}, { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }) + expect(patient.sandbox.confine(['true'], RO).enforcement).toBe('full') + + const impatient = await setup( + { probeTimeoutMs: 250 }, + { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }, + ) + expect(() => impatient.sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) + }) +}) + +describe('the default seatbelt probe (sandbox-exec contract)', () => { + // The product chains reach seatbelt only unprobed (darwin's sole + // candidate), so the default probe's contract is pinned through the chain + // seam: a grown chain must probe it like any other rung. + it('selects the rung when the executable applies the read-only profile and exits 0', async () => { + const exec = fakeSeatbeltExec(0) + const { sandbox } = await setup({}, { chain: ['bwrap', 'seatbelt'], probeBwrap: () => false, seatbeltExec: exec }) + const confined = sandbox.confine(['true'], RO) + expect(confined).toEqual({ + argv: [exec, ...seatbeltProfileArgs(RO), '--', 'true'], + enforcement: 'full', + denialSignatures: ['operation not permitted'], + runnerFailureSignatures: ['sandbox-exec: '], + }) + }) + + it('reads a failing executable as unusable: the chain ends and fails closed', async () => { + const { sandbox } = await setup({}, { chain: ['bwrap', 'seatbelt'], probeBwrap: () => false, seatbeltExec: fakeSeatbeltExec(1) }) + expect(() => sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) + }) +}) diff --git a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts new file mode 100644 index 0000000000..9d0e8ade4f --- /dev/null +++ b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts @@ -0,0 +1,173 @@ +import { spawnSync } from 'node:child_process' +import { accessSync, constants, existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs' +import { rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { afterAll, beforeAll, describe, expect, it } from 'vitest' + +/** + * KEYLESS publish-path rehearsal for this package's own distribution: the + * provider must work from its PACKED tarball plus its REGISTRY launcher + * dependency, not the git checkout. `pnpm pack` produces the EXACT bytes + * `pnpm publish` would upload; this suite packs the workspace closure + * (`dsh-sandbox-local` + its `@deepseek-ai` peers), installs the tarballs + * into a throwaway consumer OUTSIDE the repo — npm resolving the + * `node-addon-landlock-run` dependency (and its os/cpu-selected platform + * package) from the public registry, the real consumer path — and drives + * the INSTALLED packages under plain `node`: no tsx, no tsconfig paths, no + * workspace resolution, so a `files`-list omission, a broken launcher + * dependency, or a mode-stripped binary fails here instead of at the first + * real install. + * + * World-proofs: the registry-installed launcher carries this host's ELF + * architecture and IS executable (a tarball that loses the mode bit would + * otherwise masquerade as a non-enforcing kernel — the fail-closed branch + * below must never absorb that), and the installed provider confines a real + * process THROUGH it (bwrap forced off) — or fails closed when the running + * kernel does not enforce Landlock, which is itself the installed + * fail-closed contract. Byte provenance of the launcher is the + * `node-addon-landlock-run` repository's own release-pipeline concern. + * + * Self-skips off Linux or when the built `lib/` is absent (run + * `pnpm run build` first — CI's landlock legs do). + */ + +const packageDir = fileURLToPath(new URL('..', import.meta.url)) +const repoRoot = fileURLToPath(new URL('../../../..', import.meta.url)) + +/** The closure the consumer needs: the package and its transitive `@deepseek-ai` peers; the launcher family arrives from the registry. */ +const WORKSPACE_CLOSURE = [ + 'packages/sandbox/sandbox-local', + 'packages/sandbox/sandbox', + 'packages/llm/llm', + 'packages/util/brand', +] + +/** ELF `e_machine` (offset 18, LE) for this host: x86-64 = 62, AArch64 = 183. */ +const E_MACHINE = { x64: 62, arm64: 183 }[process.arch as 'x64' | 'arm64'] + +const packable = process.platform === 'linux' + && E_MACHINE !== undefined + && existsSync(join(packageDir, 'lib', 'index.js')) + +let consumerDir = '' +let workDir = '' +/** The consumer script's JSON verdict (see its source below). */ +let verdict: { + launcher: string + launcherExists: boolean + enforcing: boolean + wrapArgv0?: string + enforcement?: string + exitCode?: number | null + stderrHasDialect?: boolean + confineOutcome?: string +} = { launcher: '', launcherExists: false, enforcing: false } + +describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-path rehearsal)', () => { + beforeAll(async () => { + const packDest = mkdtempSync(join(tmpdir(), 'dsh-pack-')) + consumerDir = mkdtempSync(join(tmpdir(), 'dsh-packed-consumer-')) + workDir = mkdtempSync(join(tmpdir(), 'dsh-packed-work-')) + + // Pack each closure member with the exact bytes publish would upload. + const tarballs: string[] = [] + for (const pkg of WORKSPACE_CLOSURE) { + const pack = spawnSync('pnpm', ['pack', '--pack-destination', packDest], { + cwd: join(repoRoot, pkg), + encoding: 'utf8', + timeout: 120_000, + }) + expect(pack.status, `pnpm pack failed for ${pkg}:\n${pack.stdout}\n${pack.stderr}`).toBe(0) + const lines = pack.stdout.trim().split('\n') + tarballs.push(lines[lines.length - 1] as string) + } + + // A real consumer: plain ESM project, tarballs installed by npm — the + // peer ranges (^0.0.1) resolve to the tarball versions, cordis pins to + // the peer range's rc, and `node-addon-landlock-run` (with its + // os/cpu-selected platform package, an OPTIONAL dependency of the entry + // — so no `--omit=optional` here) comes from the public registry. + writeFileSync(join(consumerDir, 'package.json'), JSON.stringify({ name: 'dsh-packed-consumer', private: true, type: 'module' })) + const install = spawnSync('npm', ['install', '--no-audit', '--no-fund', ...tarballs, 'cordis@4.0.0-rc.6'], { + cwd: consumerDir, + encoding: 'utf8', + timeout: 300_000, + }) + expect(install.status, `npm install failed:\n${install.stdout}\n${install.stderr}`).toBe(0) + + // The consumer script runs under PLAIN node against the installed + // packages and reports a JSON verdict; every assertion happens back in + // the test. bwrap is forced off so the wrap must select the INSTALLED + // launcher; a non-enforcing kernel must surface the fail-closed error. + writeFileSync(join(consumerDir, 'consumer.mjs'), ` + import { spawnSync } from 'node:child_process' + import { existsSync } from 'node:fs' + import { Context } from 'cordis' + import { launcherPath } from 'node-addon-landlock-run' + import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local' + const ctx = new Context() + await ctx.plugin(LocalSandboxProvider, {}) + const sandbox = ctx.sandbox + sandbox.internals = { probeBwrap: () => false } + const launcher = launcherPath() + const probe = spawnSync(launcher, ['--probe'], { encoding: 'utf8', timeout: 5000 }) + const out = { launcher, launcherExists: existsSync(launcher), enforcing: probe.status === 0 } + const workdir = process.argv[2] + if (out.enforcing) { + const confined = sandbox.confine(['bash', '-c', \`echo hi > \${workdir}/denied.txt\`], { mode: 'read-only', workspaceRoot: workdir }) + out.wrapArgv0 = confined.argv[0] + out.enforcement = confined.enforcement + const run = spawnSync(confined.argv[0], confined.argv.slice(1), { encoding: 'utf8', timeout: 30000 }) + out.exitCode = run.status + out.stderrHasDialect = /permission denied/i.test(run.stderr) + } else { + try { + sandbox.confine(['true'], { mode: 'read-only', workspaceRoot: workdir }) + out.confineOutcome = 'wrapped' + } catch (error) { + out.confineOutcome = error?.code === 'SANDBOX_UNAVAILABLE' ? 'fail-closed' : String(error) + } + } + console.log(JSON.stringify(out)) + `) + const consumer = spawnSync('node', ['consumer.mjs', workDir], { cwd: consumerDir, encoding: 'utf8', timeout: 60_000 }) + expect(consumer.status, `consumer script failed:\n${consumer.stdout}\n${consumer.stderr}`).toBe(0) + verdict = JSON.parse(consumer.stdout.trim().split('\n').pop() as string) as typeof verdict + }, 480_000) + + afterAll(async () => { + await Promise.all([consumerDir, workDir].filter(Boolean).map(dir => rm(dir, { recursive: true, force: true }))) + }) + + it('installs the registry launcher for this host: present, EXECUTABLE, right ELF arch', () => { + const installed = join(consumerDir, 'node_modules', `node-addon-landlock-run-linux-${process.arch}`, 'bin', 'landlock-run') + expect(existsSync(installed), 'platform package missing from the installed tree').toBe(true) + // A tarball or extraction step that strips the mode bit would leave the + // probe failing exactly like a non-enforcing kernel — assert it apart. + expect(() => { accessSync(installed, constants.X_OK) }, 'installed launcher is not executable').not.toThrow() + expect(readFileSync(installed).readUInt16LE(18), 'ELF e_machine').toBe(E_MACHINE) + }) + + it('the installed provider resolves the launcher INSIDE the consumer node_modules platform package', () => { + expect(verdict.launcher) + .toBe(join(consumerDir, 'node_modules', `node-addon-landlock-run-linux-${process.arch}`, 'bin', 'landlock-run')) + }) + + it('confines through the installed launcher (enforcing kernel) or fails closed (non-enforcing) — never unconfined', async () => { + // Fail-closed is only the acceptable outcome when the installed binary + // IS present and executable and the kernel merely does not enforce — + // the first test pins that apart, so nothing hides behind this branch. + expect(verdict.launcherExists, 'installed launcher missing').toBe(true) + if (verdict.enforcing) { + expect(verdict.wrapArgv0).toBe(verdict.launcher) + expect(['full', 'partial']).toContain(verdict.enforcement) + expect(verdict.exitCode).not.toBe(0) + expect(verdict.stderrHasDialect, 'kernel denial text must match the advertised dialect').toBe(true) + expect(existsSync(join(workDir, 'denied.txt'))).toBe(false) + } else { + expect(verdict.confineOutcome).toBe('fail-closed') + } + }) +}) diff --git a/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts b/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts new file mode 100644 index 0000000000..7136e4e524 --- /dev/null +++ b/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts @@ -0,0 +1,120 @@ +import { spawnSync } from 'node:child_process' +import { existsSync, readFileSync } from 'node:fs' +import { mkdtemp, rm } from 'node:fs/promises' +import { homedir, tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox' +import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local' + +/** + * KEYLESS Seatbelt integration proof for the BACKEND: the REAL macOS + * `sandbox-exec` confining REAL processes through `confine()` + a direct + * spawn of the returned argv, with the Linux rungs forced off so the ladder + * lands on Seatbelt. Verifies the WORLD (files exist or don't) and that the + * kernel's denial text matches the dialect the wrap advertises; the + * through-`ctx.bash` consumer proof lives with `@deepseek-ai/dsh-bash-sandbox`. + * + * Self-skips wherever the functional probe fails — every non-macOS host, or + * a macOS whose `sandbox-exec` refuses the profile. + * + * Workspaces for the workspace-write tests live under the HOME directory on + * purpose: `workspace-write` grants `/tmp` and the per-user temp dir + * wholesale (the documented Seatbelt-profile temp areas), so only a + * workspace OUTSIDE both proves the workspace-root grant itself. + */ + +const probe = spawnSync('sandbox-exec', [...seatbeltProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' }) +const seatbeltUsable = probe.status === 0 + +let ctx: Context | undefined +const tempDirs: string[] = [] + +afterEach(async () => { + await ctx?.fiber.dispose() + ctx = undefined + await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) +}) + +async function tempDir(base: string): Promise { + const dir = await mkdtemp(join(base, 'dsh-seatbelt-e2e-')) + tempDirs.push(dir) + return dir +} + +async function provider(): Promise { + ctx = new Context() + await ctx.plugin(LocalSandboxProvider, {}) + const sandbox = ctx.sandbox as LocalSandboxProvider + sandbox.internals = { probeBwrap: () => false, probeLandlock: () => 'unusable' } + return sandbox +} + +/** Confine a shell command under `policy` and run it for real; returns the spawn result and the wrap's facts. */ +function runConfined(sandbox: LocalSandboxProvider, command: string, policy: SandboxPolicy) { + const confined = sandbox.confine(['bash', '-c', command], policy) + const result = spawnSync(confined.argv[0] as string, confined.argv.slice(1), { timeout: 30_000, encoding: 'utf8' }) + return { result, confined } +} + +describe.skipIf(!seatbeltUsable)('sandbox-local: real Seatbelt confinement through sandbox-exec', () => { + it('read-only denies a write — the file must NOT exist, and the kernel speaks the advertised dialect', async () => { + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const { result, confined } = runConfined(sandbox, `echo hi > ${workdir}/denied.txt`, { mode: 'read-only', workspaceRoot: workdir }) + expect(result.status).not.toBe(0) + expect(confined.enforcement).toBe('full') + // The wrap's denialSignatures must be what the kernel actually prints. + expect(result.stderr.toLowerCase()).toContain('operation not permitted') + expect(existsSync(join(workdir, 'denied.txt'))).toBe(false) + }) + + it('read-only keeps the tree readable/executable and /dev/null writable', async () => { + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const { result } = runConfined(sandbox, 'ls / > /dev/null && echo dev-ok', { mode: 'read-only', workspaceRoot: workdir }) + expect(result.status).toBe(0) + expect(result.stdout).toBe('dev-ok\n') + }) + + it('read-only grants no temp area: a write under the user temp dir is denied too', async () => { + // The per-user darwin temp dir is a workspace-write grant, not a + // read-only one — under read-only the only write-shaped path is /dev/null. + const workdir = await tempDir(tmpdir()) + const sandbox = await provider() + const target = join(workdir, 'tmp-denied.txt') + const { result } = runConfined(sandbox, `echo hi > ${target}`, { mode: 'read-only', workspaceRoot: await tempDir(homedir()) }) + expect(result.status).not.toBe(0) + expect(existsSync(target)).toBe(false) + }) + + it('workspace-write lands a write inside the workspace root and still denies one beside it', async () => { + const workdir = await tempDir(homedir()) + const outside = await tempDir(homedir()) + const sandbox = await provider() + + const inside = runConfined(sandbox, `printf seatbelt-ok > ${workdir}/allowed.txt`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(inside.result.status).toBe(0) + expect(readFileSync(join(workdir, 'allowed.txt'), 'utf8')).toBe('seatbelt-ok') + + const denied = runConfined(sandbox, `echo hi > ${outside}/denied.txt`, { mode: 'workspace-write', workspaceRoot: workdir }) + expect(denied.result.status).not.toBe(0) + expect(existsSync(join(outside, 'denied.txt'))).toBe(false) + }) + + it('workspace-write grants /tmp and the user temp dir (the documented Seatbelt-profile temp areas)', async () => { + const workdir = await tempDir(homedir()) + const hostTmp = await tempDir('/tmp') + const userTmp = await tempDir(tmpdir()) + const sandbox = await provider() + const { result } = runConfined( + sandbox, + `printf tmp-ok > ${hostTmp}/scratch.txt && printf user-tmp-ok > ${userTmp}/scratch.txt`, + { mode: 'workspace-write', workspaceRoot: workdir }, + ) + expect(result.status).toBe(0) + expect(readFileSync(join(hostTmp, 'scratch.txt'), 'utf8')).toBe('tmp-ok') + expect(readFileSync(join(userTmp, 'scratch.txt'), 'utf8')).toBe('user-tmp-ok') + }) +}) diff --git a/packages/sandbox/sandbox-local/tsconfig.json b/packages/sandbox/sandbox-local/tsconfig.json new file mode 100644 index 0000000000..c756b6af69 --- /dev/null +++ b/packages/sandbox/sandbox-local/tsconfig.json @@ -0,0 +1,27 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../sandbox" + } + ] +} diff --git a/packages/sandbox/sandbox/README.md b/packages/sandbox/sandbox/README.md new file mode 100644 index 0000000000..ef381625b2 --- /dev/null +++ b/packages/sandbox/sandbox/README.md @@ -0,0 +1,11 @@ +# @deepseek-ai/dsh-sandbox + +Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxPolicy` (per-CALL policy — mode + workspace root), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend. + +The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus two facts about the selected backend: the enforcement completeness it achieves and its denial dialect (`denialSignatures`, the stderr substrings its kernel prints on a denied file effect — what stderr-inferring consumers match instead of a cross-backend union); when no backend is usable it throws rather than passing the argv through unconfined. + +Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy. + +**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names a real host path. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md). + +Implementations: [`@deepseek-ai/dsh-sandbox-local`](../sandbox-local/) (Linux: `bwrap`, else the per-platform Landlock launcher; macOS: `sandbox-exec`/Seatbelt). Consumers: [`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/) (wraps `['bash', '-c', command]`). diff --git a/packages/sandbox/sandbox/package.json b/packages/sandbox/sandbox/package.json new file mode 100644 index 0000000000..b37ef714ea --- /dev/null +++ b/packages/sandbox/sandbox/package.json @@ -0,0 +1,32 @@ +{ + "name": "@deepseek-ai/dsh-sandbox", + "description": "Abstract process-sandbox seam (ctx.sandbox) for the DeepSeek Harness: same-world confinement vocabulary and the SandboxProvider contract", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-llm": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "devDependencies": { + "@deepseek-ai/dsh-llm": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/sandbox/sandbox/src/index.ts b/packages/sandbox/sandbox/src/index.ts new file mode 100644 index 0000000000..55b9da4540 --- /dev/null +++ b/packages/sandbox/sandbox/src/index.ts @@ -0,0 +1,199 @@ +/** + * The process-sandbox seam (`ctx.sandbox`): an abstract service defining WHAT + * platform confinement does — wrap a subprocess argv so it executes under a + * file-effect policy — without saying HOW. Implementations subclass + * {@link SandboxProvider} and register as the `sandbox` service; + * `@deepseek-ai/dsh-sandbox-local` (per-platform chains: Linux `bwrap` then the + * npm-distributed `landlock-run` launcher, macOS `sandbox-exec`/Seatbelt) is + * the first. + * Consumers hand over the exact argv they are about to spawn + * (`@deepseek-ai/dsh-bash-sandbox` wraps `['bash', '-c', command]`; a + * subagent backend wraps its child-agent argv) and spawn the returned argv + * instead. + * + * The seam confines SAME-WORLD subprocesses only: a backend shares the + * host's filesystem and kernel, and the policy's `workspaceRoot` names a + * real host path. Containers, microVMs, and remote executors are NOT + * backends of this seam — they are sibling implementations of whole + * capability seams (`ctx.bash`, `ctx.fs`), deployed as environment-coherent + * groups; the boundary is recorded in + * docs/rfc/implemented/feature/2026-07-06-sandbox.md. + * + * @module @deepseek-ai/dsh-sandbox + */ + +import { Context, Service } from 'cordis' +import { HarnessError } from '@deepseek-ai/dsh-llm' + +/** + * File-effect policy a sandbox backend enforces on confined processes. + * + * - `read-only` — the process cannot write the filesystem anywhere; a + * write-shaped `/dev/null` sink stays available so `>/dev/null` redirects + * keep working (HOW is the backend's choice: bwrap mounts a fresh `/dev`, + * the Landlock launcher and Seatbelt grant the single `/dev/null` node). + * - `workspace-write` — writes are allowed only under the policy's + * workspace root and `/tmp`; everything else stays read-only. Which `/tmp` + * is backend-specific — an ephemeral mount under bwrap, the HOST `/tmp` + * under the Landlock launcher, the host `/private/tmp` plus the per-user + * darwin temp dir under Seatbelt: the seam promises the write boundary, + * not the mount's nature. + * - `danger-full-access` — no confinement; a consumer configured with it + * spawns its argv unwrapped and never calls the provider. + * + * The mode governs FILE effects only: network and process visibility are not + * restricted (a backend that cannot honestly enforce them must not pretend + * to). How completely the file effects themselves are enforced is likewise a + * reported fact, not an assumption — see {@link SandboxEnforcement}. + */ +export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access' + +/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */ +export type ConfinedSandboxMode = Exclude + +/** + * How completely the selected backend enforces a confined mode's file + * effects. + * + * - `full` — every file effect the mode promises to block is governed: the + * `bwrap` mount profile, a Landlock kernel enforcing the launcher's whole + * ruleset, or an operator-configured runner (configuring one asserts full + * enforcement along with existence). + * - `partial` — the backend is active but the kernel governs only the subset + * of accesses its ABI knows (an older Landlock ABI: path-based truncate is + * ungoverned before ABI v3), so a file effect the mode promises to block + * may still land. A caller that needs the mode's promise to be absolute + * must treat `partial` as outside that promise. + */ +export type SandboxEnforcement = 'full' | 'partial' + +/** + * What one confined execution is allowed to touch — carried PER CALL, not + * fixed on the provider: two consumers may confine under different policies + * at the same instant (bash under `read-only` while a confined child agent + * needs its state directory writable), and an approved escalated retry is a + * new call with a wider policy. Defaulting/resolution is the consumer's + * explicit step (its config owns the fallback chain); the provider treats + * the policy as fully specified. + */ +export interface SandboxPolicy { + /** The file-effect mode this execution runs under. */ + mode: ConfinedSandboxMode + /** Absolute root directory `workspace-write` may write under. */ + workspaceRoot: string +} + +/** + * A {@link SandboxProvider.confine} result: the argv to spawn in place of + * the caller's own, plus the enforcement completeness the selected backend + * achieves for it. + */ +export interface ConfinedArgv { + /** The wrapped argv (runner, profile, separator, then the caller's argv). */ + argv: string[] + /** How completely the selected backend enforces the policy's file effects. */ + enforcement: SandboxEnforcement + /** + * The selected backend's denial DIALECT: the case-insensitive stderr + * substrings a file effect denied by THIS backend produces (EROFS text + * under bwrap's read-only binds, EACCES under Landlock, EPERM under + * Seatbelt). A consumer that infers denials from a failed run's stderr + * matches against exactly these rather than a cross-backend union — the + * union claims denials a given backend never produces. + */ + denialSignatures: readonly string[] + /** + * How the RUNNER ITSELF failing identifies itself: case-insensitive stderr + * substrings produced when the sandbox binary is missing, refuses its + * profile, or fails closed before exec'ing the command (`bwrap: `, + * `landlock-run: `, `sandbox-exec: ` — each covers both the runner's own + * error prefix and the shell's runner-not-found message). ORTHOGONAL to + * {@link denialSignatures}: a denial is the confined COMMAND being blocked + * (the sandbox working as designed); a runner failure means the command + * NEVER RAN and must surface as a sandbox failure, not a task failure — + * consumers check these signatures FIRST (a runner's own error text may + * contain denial words, e.g. an unopenable grant root reporting + * `Permission denied`). + */ + runnerFailureSignatures: readonly string[] +} + +/** + * Error `code` carried by the infrastructure error a provider throws when a + * confined policy is requested but no backend is available or usable on this + * host: confinement FAILS CLOSED (refuses to run) rather than silently + * executing unconfined. Thrown as a `HarnessError`, it reaches the model + * through the structured `{ name, code }` error channel on `tool/result`, so + * callers can distinguish "the sandbox is missing" from a failing command. + */ +export const SANDBOX_UNAVAILABLE = 'SANDBOX_UNAVAILABLE' + +/** + * Thrown by {@link SandboxProvider.confine} when a confined policy is + * requested but no backend is usable on this host: confinement fails closed. + * Carries the {@link SANDBOX_UNAVAILABLE} code through the structured + * `{ name, code }` error channel. + */ +export class SandboxUnavailableError extends HarnessError { + constructor(mode: ConfinedSandboxMode, detail?: string) { + super( + `sandbox mode "${mode}" is requested but no sandbox backend is usable on this host; ` + + 'refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing ' + + 'kernel (Linux), ensure sandbox-exec is usable (macOS) — Windows has no confinement ' + + 'backend yet — or switch the consumer to danger-full-access.' + + (detail === undefined ? '' : ` Runner failure: ${detail}`), + SANDBOX_UNAVAILABLE, + ) + this.name = 'SandboxUnavailableError' + } +} + +declare module 'cordis' { + interface Context { + sandbox: SandboxProvider + } +} + +/** + * Abstract process-sandbox service. Subclass, implement {@link confine}, and + * load the subclass as a plugin — it registers as `ctx.sandbox` (one + * implementation per context; loading a second throws, cordis' standard + * duplicate-service behavior). + * + * Semantics every implementation must honor: + * - {@link confine} either returns an argv whose runner ENFORCES the policy + * or fails closed — at `confine` time with {@link SandboxUnavailableError} + * (no backend for this host), or at EXECUTION time by the runner itself + * refusing to run the command (exiting without exec'ing it, identified by + * {@link ConfinedArgv.runnerFailureSignatures}). A silent unconfined + * passthrough is never a legal outcome on either path. + * - Probing exists to ARBITRATE between multiple candidate backends and may + * be skipped when a platform has exactly one: the sole candidate is + * selected directly and the runner's exec-time fail-closed refusal carries + * the safety property. When probing does run, it is functional (actually + * enforcing a profile, not a version check), at most once per provider + * lifetime; `confine` itself spawns nothing beyond that one-time probing. + * - The returned {@link ConfinedArgv.enforcement} states the backend's + * actual completeness for THIS host; `partial` is reported, never silently + * upgraded to `full`. + */ +export abstract class SandboxProvider extends Service { + constructor(ctx: Context) { + super(ctx, 'sandbox') + } + + /** + * Wrap `argv` so it executes confined under `policy` on this host; the + * caller spawns the returned argv in place of its own. + * @param argv - the exact argv the caller is about to spawn (program plus + * arguments), NOT a shell string — a shell-shaped consumer passes + * `['bash', '-c', command]`. + * @param policy - the file-effect policy this execution runs under, + * carried per call (see {@link SandboxPolicy}). + * @returns the argv to spawn instead, plus the enforcement completeness + * the selected backend achieves for it. + */ + abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv +} + +export default SandboxProvider diff --git a/packages/sandbox/sandbox/tests/vocabulary.spec.ts b/packages/sandbox/sandbox/tests/vocabulary.spec.ts new file mode 100644 index 0000000000..caba42b2a7 --- /dev/null +++ b/packages/sandbox/sandbox/tests/vocabulary.spec.ts @@ -0,0 +1,35 @@ +/** + * Vocabulary-contract tests for the sandbox seam: the fail-closed error's + * structured identity is what tool results and consumers key on, so its + * shape is pinned here, next to the vocabulary that owns it. Provider + * behavior is each implementation's suite (`dsh-sandbox-local`); consumer + * behavior is each consumer's (`dsh-bash-sandbox`). + */ + +import { describe, expect, it } from 'vitest' +import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox' + +describe('SandboxUnavailableError', () => { + it('carries the structured { name, code } identity consumers key on', () => { + const error = new SandboxUnavailableError('read-only') + expect(error.name).toBe('SandboxUnavailableError') + expect(error.code).toBe(SANDBOX_UNAVAILABLE) + expect(error).toBeInstanceOf(Error) + }) + + it('names the refused mode and the operator escape hatches in its message', () => { + const error = new SandboxUnavailableError('workspace-write') + expect(error.message).toContain('"workspace-write"') + expect(error.message).toContain('danger-full-access') + expect(error.message).not.toContain('Runner failure') + }) + + it('carries the runner detail when the failure is discovered at execution time', () => { + // The late twin of the confine-time throw: an unprobed sole candidate + // that fails closed at exec surfaces the SAME error, with the runner's + // own first stderr line as the cause. + const error = new SandboxUnavailableError('read-only', 'landlock-run: landlock is not enforced by this kernel') + expect(error.code).toBe(SANDBOX_UNAVAILABLE) + expect(error.message).toContain('Runner failure: landlock-run: landlock is not enforced by this kernel') + }) +}) diff --git a/packages/sandbox/sandbox/tsconfig.json b/packages/sandbox/sandbox/tsconfig.json new file mode 100644 index 0000000000..9f687793d7 --- /dev/null +++ b/packages/sandbox/sandbox/tsconfig.json @@ -0,0 +1,21 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../llm/llm" + } + ] +} diff --git a/packages/skill/README.md b/packages/skill/README.md new file mode 100644 index 0000000000..447b82fc47 --- /dev/null +++ b/packages/skill/README.md @@ -0,0 +1,11 @@ +# skill/ - skill capability family + +The canonical three-package capability seam for reusable agent instructions: a provider registry, a local implementation, and the model-facing catalog/loader consumer. All are **product** packages. + +| Package | Role | ctx key | +|---|---|---| +| `skill/` | Provider registry, precedence resolution, stable catalog snapshots, and full-definition lookup | `ctx.skills` | +| `skill-local/` | Project/custom/user filesystem provider | (registers on `ctx.skills`) | +| `tool-skill/` | Session-prefix catalog and model-facing `skill` loader | (registers on `ctx.tools`) | + +The interface lives at `skill/skill/`. Providers register synchronously and perform asynchronous discovery through `ctx.skills`; `tool-skill` consumes only that interface, so an embedded or remote provider can replace or complement `skill-local` without changing the model-facing contract. `agent-core` loads this family by default, but it remains a capability outside the core control spine, parallel to [`bash/`](../bash/README.md), [`fs/`](../fs/README.md), [`web/`](../web/README.md), and [`subagent/`](../subagent/README.md). diff --git a/packages/skill/skill-local/README.md b/packages/skill/skill-local/README.md new file mode 100644 index 0000000000..c885416ff5 --- /dev/null +++ b/packages/skill/skill-local/README.md @@ -0,0 +1,37 @@ +# @deepseek-ai/dsh-skill-local + +Local filesystem provider for the `ctx.skills` registry. + +This package implements one skill source. It scans local project, custom, and user skill roots, parses `SKILL.md` or flat Markdown skill files, and registers the provider on `ctx.skills`. The registry remains in `@deepseek-ai/dsh-skill`; the session-prefix catalog and model-facing loader tool remain in `@deepseek-ai/dsh-tool-skill`. + +## Plugin + +Requires `ctx.skills` (`inject: ['skills']`). + +### Config + +| Field | Default | Meaning | +|---|---|---| +| `dshHome` | `$DSH_HOME` or `~/.dsh` | DeepSeek Harness config root; scans `skills` under this directory. | +| `agentsHome` | `$DSH_AGENTS_HOME` or `~/.agents` | Shared agent config root scanned for compatible skills. | +| `customSkillDirs` | `[]` | Additional local skill roots scanned after project roots and before user roots. | + +## Discovery + +Default roots are resolved in this provider's rank order: + +| Rank | Source | Path | +|---|---|---| +| 100 | `project-dsh` | `/.dsh/skills` | +| 200 | `project-agents` | `/.agents/skills` | +| 300 | `custom` | `Config.customSkillDirs` | +| 400 | `user-dsh` | `/skills` | +| 500 | `user-agents` | `/skills` | + +The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. The user DSH root skips its `.system` child so system-owned directories are not accidentally treated as normal user skills. DeepSeek Harness no longer ships built-in system skills from this provider; additional built-ins can be supplied later by another provider. + +When `ctx.fs` is available, discovery lists roots through `ctx.fs.listDir`, reads skill files through `ctx.fs.readText`, and probes `.git` through the filesystem service. Full skill loads forward the lookup abort signal to filesystem metadata and content reads. Without a filesystem service, the provider falls back to abortable Node filesystem I/O so minimal local contexts can still load skills. Missing, unreadable, or malformed skill files warn and skip instead of failing the whole request. + +## Skill Format + +Skills can be single-level directory bundles (`/SKILL.md`) or flat Markdown files (`.md`). Nested `**/SKILL.md` discovery is intentionally not part of v1. Frontmatter is parsed as YAML with the `yaml` package; it requires `name` and `description`, while `whenToUse`, `disableModelInvocation`, and `metadata` are optional. Names must be kebab-case. diff --git a/packages/skill/skill-local/package.json b/packages/skill/skill-local/package.json new file mode 100644 index 0000000000..dcacc5960a --- /dev/null +++ b/packages/skill/skill-local/package.json @@ -0,0 +1,38 @@ +{ + "name": "@deepseek-ai/dsh-skill-local", + "description": "Local filesystem skill provider for the DeepSeek Harness", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-fs": "^0.0.1", + "@deepseek-ai/dsh-skill": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0", + "yaml": "^2.4.2" + }, + "devDependencies": { + "@deepseek-ai/dsh-fs": "workspace:^", + "@deepseek-ai/dsh-skill": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts new file mode 100644 index 0000000000..19a15f1de8 --- /dev/null +++ b/packages/skill/skill-local/src/index.ts @@ -0,0 +1,424 @@ +/** + * Local filesystem skill provider. + * + * This package is one implementation of the `ctx.skills` provider registry. It + * discovers directory-bundle and flat Markdown skills from project, custom, and + * user roots, parses YAML frontmatter, and loads bodies through `ctx.fs` when a + * filesystem service is present. + * + * @module @deepseek-ai/dsh-skill-local + */ + +import { access, readdir, readFile, stat } from 'node:fs/promises' +import { dirname, join, resolve } from 'node:path' +import { homedir } from 'node:os' +import type { Context } from 'cordis' +import z from 'schemastery' +import type Schema from 'schemastery' +import { parse as parseYaml } from 'yaml' +import type { FileSystem, FsDirEntry, FsTarget } from '@deepseek-ai/dsh-fs' +import { + isSkillName, + type SkillCandidate, + type SkillDefinition, + type SkillLookupOptions, + type SkillProvider, + type SkillSource, +} from '@deepseek-ai/dsh-skill' + +const PROJECT_DSH_RANK = 100 +const PROJECT_AGENTS_RANK = 200 +const CUSTOM_RANK = 300 +const USER_DSH_RANK = 400 +const USER_AGENTS_RANK = 500 + +export const name = 'skill-local' +export const inject = ['skills'] + +/** Local filesystem skill provider configuration. */ +export interface Config { + /** DeepSeek Harness config root. Defaults to `$DSH_HOME` or `~/.dsh`. */ + dshHome?: string + /** Shared agent config root. Defaults to `$DSH_AGENTS_HOME` or `~/.agents`. */ + agentsHome?: string + /** Additional skill roots scanned after project roots and before user roots. */ + customSkillDirs?: string[] +} + +export const Config: Schema = z.object({ + dshHome: z.string(), + agentsHome: z.string(), + customSkillDirs: z.array(z.string()).default([]), +}) + +interface SkillRoot { + path: string + source: SkillSource + rank: number + skipSystem?: boolean +} + +interface SkillRootEntry { + name: string + type: 'directory' | 'file' | 'other' + path: string +} + +interface ParsedSkill { + name: string + description: string + whenToUse?: string + disableModelInvocation?: boolean + metadata?: Record + content: string +} + +interface LocalLocator { + path: string + directory: string +} + +/** Register the local filesystem skill provider on `ctx.skills`. */ +export function apply(ctx: Context, config: Config = {}): void { + const provider = new LocalSkillProvider(ctx, config) + ctx.skills.registerProvider(provider) +} + +/** Provider that maps local project/user skill roots into `ctx.skills`. */ +export class LocalSkillProvider implements SkillProvider { + readonly name = 'local' + private readonly dshHome: string + private readonly agentsHome: string + private readonly customSkillDirs: string[] + + constructor(private readonly ctx: Context, config: Config = {}) { + this.dshHome = resolve(config.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh')) + this.agentsHome = resolve(config.agentsHome ?? process.env.DSH_AGENTS_HOME ?? join(homedir(), '.agents')) + this.customSkillDirs = (config.customSkillDirs ?? []).map(root => resolve(root)) + } + + /** + * Discover local skill summaries for a cwd-sensitive workspace. + * @param options - lookup options; `cwd` selects the project roots to scan. + * @returns local provider candidates with stable root ranks. + */ + async list(options: SkillLookupOptions): Promise { + const roots = await this.roots(options.cwd) + const candidates: SkillCandidate[] = [] + for (const root of roots) { + for (const skill of await discoverRoot(root, this.ctx)) { + candidates.push(skill) + } + } + return candidates + } + + /** + * Load a complete local skill body from the candidate's file locator. + * @param candidate - the winning candidate returned by this provider. + * @param options - lookup options whose signal cancels filesystem reads. + * @returns the full local skill, or `undefined` if the file disappeared. + */ + async get(candidate: SkillCandidate, options: SkillLookupOptions): Promise { + const locator = candidate.locator as LocalLocator + const parsed = await parseSkillFile(locator.path, this.ctx, options.signal) + if (parsed === undefined) return undefined + return { + name: parsed.name, + description: parsed.description, + ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}, + ...parsed.disableModelInvocation !== undefined ? { disableModelInvocation: parsed.disableModelInvocation } : {}, + source: candidate.source, + provider: this.name, + resourceBase: { kind: 'directory', path: locator.directory }, + path: locator.path, + ...parsed.metadata !== undefined ? { metadata: parsed.metadata } : {}, + content: parsed.content, + } + } + + private async roots(cwd: string | undefined): Promise { + const roots: SkillRoot[] = [] + if (cwd !== undefined) { + const projectRoot = await findProjectRoot(resolve(cwd), optionalFileSystem(this.ctx)) + roots.push( + { path: join(projectRoot, '.dsh/skills'), source: 'project-dsh', rank: PROJECT_DSH_RANK }, + { path: join(projectRoot, '.agents/skills'), source: 'project-agents', rank: PROJECT_AGENTS_RANK }, + ) + } + roots.push( + ...this.customSkillDirs.map(path => ({ path, source: 'custom' as const, rank: CUSTOM_RANK })), + { path: join(this.dshHome, 'skills'), source: 'user-dsh', rank: USER_DSH_RANK, skipSystem: true }, + { path: join(this.agentsHome, 'skills'), source: 'user-agents', rank: USER_AGENTS_RANK }, + ) + return roots + } +} + +async function discoverRoot(root: SkillRoot, ctx: Context): Promise { + const skills: SkillCandidate[] = [] + const entries = await listSkillRootEntries(root, ctx) + for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) { + if (root.skipSystem && entry.name === '.system') continue + const locator = entry.type === 'directory' + ? { path: join(entry.path, 'SKILL.md'), directory: entry.path } + : entry.type === 'file' && entry.name.endsWith('.md') + ? { path: entry.path, directory: root.path } + : undefined + if (locator === undefined) continue + const parsed = await parseSkillFile(locator.path, ctx) + if (parsed === undefined) continue + skills.push({ + name: parsed.name, + description: parsed.description, + ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}, + ...parsed.disableModelInvocation !== undefined ? { disableModelInvocation: parsed.disableModelInvocation } : {}, + provider: 'local', + source: root.source, + rank: root.rank, + locator, + resourceBase: { kind: 'directory', path: locator.directory }, + path: locator.path, + ...parsed.metadata !== undefined ? { metadata: parsed.metadata } : {}, + }) + } + return skills +} + +async function listSkillRootEntries(root: SkillRoot, ctx: Context): Promise { + const fs = optionalFileSystem(ctx) + if (fs !== undefined) return await listSkillRootEntriesFromFileSystem(root, fs) + return await listSkillRootEntriesFromNode(root, ctx) +} + +async function listSkillRootEntriesFromFileSystem(root: SkillRoot, fs: FileSystem): Promise { + // Skill roots are optional; an absent or unlistable root contributes no skills. + const entries = await fsListDir(fs, root.path).catch(() => undefined) + return entries === undefined ? [] : entries.map(entryFromFs) +} + +async function fsListDir(fs: FileSystem, path: string): Promise { + const target = await fs.resolve(path) + return await fs.listDir(target) +} + +function entryFromFs(entry: FsDirEntry): SkillRootEntry { + return { name: entry.name, type: entry.type, path: entry.target.displayPath } +} + +async function listSkillRootEntriesFromNode(root: SkillRoot, ctx: Context): Promise { + let entries + try { + entries = await readdir(root.path, { withFileTypes: true, encoding: 'utf8' }) + } catch { + // Missing or unreadable local skill roots are expected in most deployments. + return [] + } + + const result: SkillRootEntry[] = [] + for (const entry of entries) { + const path = join(root.path, entry.name) + const type = await nodeEntryKind(path, entry, ctx) + result.push({ name: entry.name, type: type ?? 'other', path }) + } + return result +} + +async function parseSkillFile(path: string, ctx: Context, signal?: AbortSignal): Promise { + const raw = await readSkillText(ctx, path, signal) + signal?.throwIfAborted() + if (raw === undefined) { + return undefined + } + let parsed + try { + parsed = parseFrontmatter(raw) + } catch (error) { + ctx.logger.warn(`skill file ${path} ignored: invalid YAML frontmatter: ${errorMessage(error)}`) + return undefined + } + if (!parsed) { + ctx.logger.warn(`skill file ${path} ignored: missing YAML frontmatter`) + return undefined + } + const name = stringField(parsed.data, 'name') + const description = stringField(parsed.data, 'description') + if (name === undefined || description === undefined) { + ctx.logger.warn(`skill file ${path} ignored: frontmatter requires name and description`) + return undefined + } + if (!isSkillName(name)) { + ctx.logger.warn(`skill file ${path} ignored: invalid skill name "${name}"`) + return undefined + } + return { + name, + description, + ...optionalString(parsed.data, 'whenToUse'), + ...optionalBoolean(parsed.data, 'disableModelInvocation'), + ...optionalMetadata(parsed.data), + content: parsed.body.trim(), + } +} + +function optionalFileSystem(ctx: Context): FileSystem | undefined { + return ctx.get('fs') +} + +async function readSkillText(ctx: Context, path: string, signal?: AbortSignal): Promise { + signal?.throwIfAborted() + const fs = optionalFileSystem(ctx) + if (fs !== undefined) { + return await readSkillTextFromFileSystem(ctx, fs, path, signal) + } + try { + return await readFile(path, { encoding: 'utf8', signal }) + } catch { + signal?.throwIfAborted() + return undefined + } +} + +async function readSkillTextFromFileSystem(ctx: Context, fs: FileSystem, path: string, signal?: AbortSignal): Promise { + // A missing or temporarily inaccessible skill file is not fatal to discovery. + signal?.throwIfAborted() + const target = await fs.resolve(path).catch(() => undefined) + signal?.throwIfAborted() + if (target === undefined) return undefined + let info + try { + info = await fs.stat(target, signal) + } catch (error) { + signal?.throwIfAborted() + ctx.logger.warn(`skill file ${path} ignored: failed to stat through filesystem service: ${errorMessage(error)}`) + return undefined + } + if (info === undefined || info.type !== 'file') return undefined + try { + return await fs.readText(target, signal) + } catch (error) { + signal?.throwIfAborted() + ctx.logger.warn(`skill file ${path} ignored: ${fsReadErrorMessage(target, error)}`) + return undefined + } +} + +function fsReadErrorMessage(target: FsTarget, error: unknown): string { + return `failed to read text file at ${target.displayPath}: ${errorMessage(error)}` +} + +async function nodeEntryKind(fullPath: string, entry: { isDirectory(): boolean; isFile(): boolean; isSymbolicLink(): boolean }, ctx: Context): Promise<'directory' | 'file' | undefined> { + if (entry.isDirectory()) return 'directory' + if (entry.isFile()) return 'file' + /* v8 ignore next -- Non-file directory entries such as FIFOs are platform-specific and intentionally skipped. */ + if (!entry.isSymbolicLink()) return undefined + try { + const info = await stat(fullPath) + if (info.isDirectory()) return 'directory' + if (info.isFile()) return 'file' + return undefined + } catch (error) { + ctx.logger.warn(`skill entry ${fullPath} ignored: failed to follow symbolic link: ${errorMessage(error)}`) + return undefined + } +} + +function parseFrontmatter(raw: string): { data: Record; body: string } | undefined { + const firstLineEnd = raw.indexOf('\n') + if (firstLineEnd < 0) return undefined + const firstLine = raw.slice(0, firstLineEnd).replace(/\r$/, '') + if (firstLine !== '---') return undefined + const start = firstLineEnd + 1 + const closing = findClosingFrontmatter(raw, start) + if (closing === undefined) return undefined + const yaml = raw.slice(start, closing.start) + const parsed = parseYaml(yaml) as unknown + if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined + return { data: parsed as Record, body: raw.slice(closing.bodyStart) } +} + +function findClosingFrontmatter(raw: string, start: number): { start: number; bodyStart: number } | undefined { + let lineStart = start + while (lineStart <= raw.length) { + const nextNewline = raw.indexOf('\n', lineStart) + const lineEnd = nextNewline < 0 ? raw.length : nextNewline + const line = raw.slice(lineStart, lineEnd).replace(/\r$/, '') + if (line === '---') { + return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 } + } + if (nextNewline < 0) return undefined + lineStart = nextNewline + 1 + } +} + +async function findProjectRoot(cwd: string, fs: FileSystem | undefined): Promise { + let current = cwd + while (true) { + if (await pathExists(join(current, '.git'), fs)) { + return current + } + const parent = dirname(current) + if (parent === current) return cwd + current = parent + } +} + +async function pathExists(path: string, fs: FileSystem | undefined): Promise { + if (fs !== undefined) { + return await pathExistsInFileSystem(path, fs) + } + return await pathExistsInNode(path) +} + +async function pathExistsInFileSystem(path: string, fs: FileSystem): Promise { + let target + try { + target = await fs.resolve(path) + } catch { + // A backend may reject or hide this candidate; continue walking upward. + return false + } + try { + return await fs.stat(target) !== undefined + } catch { + // Transient stat failures make only this git-root candidate unusable. + return false + } +} + +async function pathExistsInNode(path: string): Promise { + try { + await access(path) + return true + } catch { + // Missing host paths are expected while walking toward the filesystem root. + return false + } +} + +function stringField(data: Record, key: string): string | undefined { + const value = data[key] + return typeof value === 'string' && value.length > 0 ? value : undefined +} + +function optionalString(data: Record, key: string): { [K in typeof key]?: string } { + const value = data[key] + return typeof value === 'string' && value.length > 0 ? { [key]: value } : {} +} + +function optionalBoolean(data: Record, key: string): { [K in typeof key]?: boolean } { + const value = data[key] + return typeof value === 'boolean' ? { [key]: value } : {} +} + +function optionalMetadata(data: Record): { metadata?: Record } { + const value = data.metadata + if (typeof value === 'object' && value !== null && !Array.isArray(value)) { + return { metadata: value as Record } + } + return {} +} + +function errorMessage(error: unknown): string { + return String(error) +} diff --git a/packages/skill/skill-local/tests/skill-local.spec.ts b/packages/skill/skill-local/tests/skill-local.spec.ts new file mode 100644 index 0000000000..94a48ce53f --- /dev/null +++ b/packages/skill/skill-local/tests/skill-local.spec.ts @@ -0,0 +1,393 @@ +import { describe, expect, it } from 'vitest' +import { mkdir, readdir, readFile, stat, symlink, writeFile } from 'node:fs/promises' +import { dirname, join } from 'node:path' +import { tmpdir } from 'node:os' +import { Context } from 'cordis' +import SkillService from '@deepseek-ai/dsh-skill' +import { FileSystem, FsVersion, type FsDirEntry, type FsEditOutcome, type FsEditRequest, type FsInfo, type FsTarget, type FsWriteOutcome } from '@deepseek-ai/dsh-fs' +import * as SkillLocal from '../src/index.ts' + +async function tempDir(name: string): Promise { + return await import('node:fs/promises').then(fs => fs.mkdtemp(join(tmpdir(), `dsh-${name}-`))) +} + +async function writeSkill(root: string, name: string, description: string, body = 'Use the skill.'): Promise { + const dir = join(root, name) + await mkdir(dir, { recursive: true }) + await writeFile(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`) +} + +async function writeFlatSkill(root: string, name: string, description: string, body = 'Flat body.'): Promise { + await mkdir(root, { recursive: true }) + await writeFile(join(root, `${name}.md`), `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`) +} + +class TestFileSystem extends FileSystem { + listDirCalls = 0 + failResolvePaths = new Set() + failStatPaths = new Set() + statOverrides = new Map() + statSignals: Array = [] + readTextSignals: Array = [] + readTextOverride?: (target: FsTarget, signal?: AbortSignal) => Promise + + override async resolve(path: string): Promise { + if (this.failResolvePaths.has(path)) throw new Error('resolve failed') + return { targetKey: path as never, displayPath: path } + } + + override async stat(target: FsTarget, signal?: AbortSignal): Promise { + this.statSignals.push(signal) + if (this.failStatPaths.has(target.displayPath)) throw new Error('stat failed') + if (this.statOverrides.has(target.displayPath)) return this.statOverrides.get(target.displayPath) + try { + const fs = await import('node:fs/promises') + const info = await fs.stat(target.displayPath) + return { + version: FsVersion(String(info.mtimeMs)), + type: info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other', + size: info.size, + } + } catch { + return undefined + } + } + + override async readText(target: FsTarget, signal?: AbortSignal): Promise { + this.readTextSignals.push(signal) + if (this.readTextOverride !== undefined) return await this.readTextOverride(target, signal) + const text = await readFile(target.displayPath, 'utf8') + if (text.includes('\uFFFD')) throw new Error('not text') + return text + } + + override async streamText(_target: FsTarget): Promise> { + throw new Error('not needed in skill tests') + } + + override async listDir(target: FsTarget): Promise { + this.listDirCalls += 1 + const entries = await readdir(target.displayPath, { withFileTypes: true, encoding: 'utf8' }) + const result: FsDirEntry[] = [] + for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) { + const childPath = join(target.displayPath, entry.name) + let type: FsInfo['type'] = 'other' + let size: number | undefined + try { + const info = await stat(childPath) + type = info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other' + size = info.isFile() ? info.size : undefined + } catch { + type = 'other' + } + result.push({ + name: entry.name, + type, + target: { targetKey: childPath as never, displayPath: childPath }, + version: FsVersion('test'), + ...(size !== undefined ? { size } : {}), + }) + } + return result + } + + override async writeText(target: FsTarget, content: string): Promise { + await mkdir(dirname(target.displayPath), { recursive: true }) + await writeFile(target.displayPath, content) + return { operation: 'create', version: FsVersion('test'), before: null, after: content } + } + + override async editText(_target: FsTarget, _request: FsEditRequest): Promise { + throw new Error('not needed in skill tests') + } +} + +async function setupLocal(home: string, config: Partial = {}): Promise { + const ctx = new Context() + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal, { + dshHome: join(home, '.dsh'), + agentsHome: join(home, '.agents'), + ...config, + }) + return ctx +} + +describe('dsh-skill-local plugin exports', () => { + it('declares stable plugin metadata', () => { + expect(SkillLocal.name).toBe('skill-local') + expect(SkillLocal.inject).toEqual(['skills']) + }) +}) + +describe('LocalSkillProvider', () => { + it('discovers project, custom, user, and agents skill roots in priority order', async () => { + const home = await tempDir('skill-home') + const project = await tempDir('skill-project') + const custom = await tempDir('skill-custom') + await mkdir(join(project, '.git'), { recursive: true }) + + await writeSkill(join(home, '.agents/skills'), 'same', 'user agents skill') + await writeSkill(join(home, '.dsh/skills'), 'same', 'user dsh skill') + await writeSkill(custom, 'same', 'custom skill') + await writeSkill(join(project, '.agents/skills'), 'same', 'project agents skill') + await writeSkill(join(project, '.dsh/skills'), 'same', 'project dsh skill') + await writeSkill(custom, 'custom-only', 'custom only') + await writeSkill(join(home, '.dsh/skills/.system'), 'hidden-system', 'hidden system') + + const ctx = await setupLocal(home, { customSkillDirs: [custom] }) + + const skills = await ctx.skills.list({ cwd: join(project, 'src') }) + expect(skills.map(skill => [skill.name, skill.description])).toEqual([ + ['custom-only', 'custom only'], + ['same', 'project dsh skill'], + ]) + expect(skills.find(skill => skill.name === 'same')?.source).toBe('project-dsh') + expect(skills.find(skill => skill.name === 'hidden-system')).toBeUndefined() + + const noGit = await tempDir('skill-no-git') + await writeSkill(join(noGit, '.dsh/skills'), 'fallback-root', 'Fallback root') + expect((await ctx.skills.list({ cwd: noGit })).map(skill => skill.name)).toContain('fallback-root') + }) + + it('lets project skills override runtime while runtime overrides custom and user skills', async () => { + const home = await tempDir('skill-runtime-priority') + const project = await tempDir('skill-runtime-project') + const custom = await tempDir('skill-runtime-custom') + await mkdir(join(project, '.git'), { recursive: true }) + + await writeSkill(join(project, '.dsh/skills'), 'project-name', 'Project wins') + await writeSkill(custom, 'runtime-name', 'Custom loses') + await writeSkill(join(home, '.dsh/skills'), 'runtime-name', 'User loses') + + const ctx = await setupLocal(home, { customSkillDirs: [custom] }) + ctx.skills.register({ + name: 'project-name', + description: 'Runtime loses to project', + content: 'Runtime body.', + source: 'runtime', + }) + ctx.skills.register({ + name: 'runtime-name', + description: 'Runtime wins', + content: 'Runtime body.', + source: 'runtime', + }) + + expect((await ctx.skills.get('project-name', { cwd: project }))?.description).toBe('Project wins') + expect((await ctx.skills.get('runtime-name', { cwd: project }))?.description).toBe('Runtime wins') + }) + + it('parses flat skills and filters invalid or model-disabled skills from listing', async () => { + const home = await tempDir('skill-flat') + const root = join(home, '.dsh/skills') + await writeFlatSkill(root, 'flat-skill', 'flat description', 'Flat instructions.') + await writeFile(join(root, 'rich-skill.md'), [ + '---', + 'name: rich-skill', + 'description: rich description', + 'whenToUse: For richer local parsing', + 'disableModelInvocation: false', + 'metadata:', + ' owner: tests', + '---', + '', + 'Rich body.', + ].join('\n')) + await writeFile(join(root, 'bad.md'), '---\nname: Bad_Name\ndescription: bad\n---\n\nbad') + await writeFile(join(root, 'missing-description.md'), '---\nname: missing-description\n---\n\nbad') + await writeFile(join(root, 'no-frontmatter.md'), 'No frontmatter.') + await writeFile(join(root, 'plain-markdown.md'), '# Notes\nNot a skill.') + await writeFile(join(root, 'open-frontmatter.md'), '---\nname: open-frontmatter') + await writeFile(join(root, 'non-object.md'), '---\n[]\n---\n\nbad') + await writeFile(join(root, 'no-trailing-body.md'), '---\nname: no-trailing-body\ndescription: No trailing body\n---') + await writeFile(join(root, 'notes.txt'), 'ignored') + await mkdir(join(root, 'not-a-skill'), { recursive: true }) + await writeSkill(root, 'hidden-skill', 'hidden description', 'Hidden.') + await writeFile(join(root, 'hidden-skill/SKILL.md'), '---\nname: hidden-skill\ndescription: hidden description\ndisableModelInvocation: true\n---\n\nHidden.\n') + + const ctx = await setupLocal(home) + const listedBeforeDelete = await ctx.skills.list() + const flatSummary = listedBeforeDelete.find(skill => skill.name === 'flat-skill') + if (flatSummary === undefined) throw new Error('expected flat-skill') + await writeFile(join(root, 'flat-skill.md'), '') + + expect(listedBeforeDelete.map(skill => skill.name)).toEqual(['flat-skill', 'no-trailing-body', 'rich-skill']) + expect(await ctx.skills.get('flat-skill')).toBeUndefined() + expect((await ctx.skills.get('hidden-skill'))?.content).toContain('Hidden.') + expect(await ctx.skills.get('rich-skill')).toMatchObject({ + whenToUse: 'For richer local parsing', + disableModelInvocation: false, + metadata: { owner: 'tests' }, + }) + expect(await ctx.skills.get('Bad_Name')).toBeUndefined() + }) + + it('supports CRLF frontmatter and ignores delimiter-looking text inside YAML values', async () => { + const home = await tempDir('skill-frontmatter-crlf') + const root = join(home, '.dsh/skills') + await mkdir(root, { recursive: true }) + await writeFile(join(root, 'crlf-skill.md'), [ + '---', + 'name: crlf-skill', + 'description: CRLF skill', + 'metadata:', + ' marker: "----"', + '---', + '', + 'CRLF body.', + ].join('\r\n')) + await writeFile(join(root, 'block-skill.md'), [ + '---', + 'name: block-skill', + 'description: |', + ' Includes a ---- marker that is not a delimiter.', + '---', + '', + 'Block body.', + ].join('\n')) + + const ctx = await setupLocal(home) + + expect((await ctx.skills.get('crlf-skill'))?.content).toBe('CRLF body.') + expect((await ctx.skills.get('crlf-skill'))?.metadata).toEqual({ marker: '----' }) + expect((await ctx.skills.get('block-skill'))?.description).toBe('Includes a ---- marker that is not a delimiter.\n') + expect((await ctx.skills.get('block-skill'))?.content).toBe('Block body.') + }) + + it('skips invalid YAML skill files without hiding valid siblings', async () => { + const home = await tempDir('skill-invalid-yaml') + const root = join(home, '.dsh/skills') + await writeSkill(root, 'good-skill', 'Good skill') + await writeFile(join(root, 'bad-yaml.md'), '---\nname: bad-yaml\ndescription: [unclosed\n---\n\nBad body.\n') + + const ctx = await setupLocal(home) + + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['good-skill']) + }) + + it('discovers symlinked skill directories and flat files', async () => { + const home = await tempDir('skill-symlink-home') + const external = await tempDir('skill-symlink-external') + await writeSkill(external, 'linked-dir', 'Linked directory') + await writeFlatSkill(external, 'linked-flat', 'Linked flat') + await mkdir(join(home, '.dsh/skills'), { recursive: true }) + await symlink(join(external, 'linked-dir'), join(home, '.dsh/skills/linked-dir')) + await symlink(join(external, 'linked-flat.md'), join(home, '.dsh/skills/linked-flat.md')) + await symlink(join(external, 'missing'), join(home, '.dsh/skills/broken-link')) + await symlink('/dev/null', join(home, '.dsh/skills/device-link')) + + const ctx = await setupLocal(home) + + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['linked-dir', 'linked-flat']) + }) + + it('uses the filesystem service for discovery, reads, and project-root lookup', async () => { + const home = await tempDir('skill-read-fs') + const project = await tempDir('skill-project-root-backend') + const nestedCwd = join(project, 'packages/app') + const root = join(home, '.dsh/skills') + await mkdir(nestedCwd, { recursive: true }) + await writeFlatSkill(root, 'text-skill', 'Text skill', 'Text body.') + await writeFlatSkill(root, 'resolve-fail', 'Resolve fail', 'Resolve body.') + await writeFlatSkill(root, 'stat-fail', 'Stat fail', 'Stat body.') + await mkdir(join(root, 'empty-dir'), { recursive: true }) + await mkdir(join(root, 'directory-skill/SKILL.md'), { recursive: true }) + await writeFile(join(root, 'binary-skill.md'), Buffer.concat([ + Buffer.from('---\nname: binary-skill\ndescription: Binary skill\n---\n\n'), + Buffer.from([0xff]), + Buffer.from('\n'), + ])) + await writeSkill(join(project, '.agents/skills'), 'backend-root', 'Backend root skill') + + const ctx = new Context() + await ctx.plugin(TestFileSystem) + const fs = ctx.fs as TestFileSystem + fs.failResolvePaths.add(join(root, 'resolve-fail.md')) + fs.failStatPaths.add(join(root, 'stat-fail.md')) + fs.failResolvePaths.add(join(nestedCwd, '.git')) + fs.failStatPaths.add(join(project, 'packages/.git')) + fs.statOverrides.set(join(project, '.git'), { + version: FsVersion('virtual-git'), + type: 'directory', + size: 0, + }) + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }) + + expect((await ctx.skills.list({ cwd: nestedCwd })).map(skill => [skill.name, skill.source])).toEqual([ + ['backend-root', 'project-agents'], + ['text-skill', 'user-dsh'], + ]) + expect(fs.listDirCalls).toBeGreaterThan(0) + expect(await ctx.skills.get('binary-skill')).toBeUndefined() + }) + + it('forwards cancellation to filesystem reads while loading a skill', async () => { + const home = await tempDir('skill-read-abort') + await writeSkill(join(home, '.dsh/skills'), 'abortable-skill', 'Abortable skill') + + const ctx = new Context() + await ctx.plugin(TestFileSystem) + const fs = ctx.fs as TestFileSystem + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['abortable-skill']) + + fs.statSignals = [] + fs.readTextSignals = [] + const started = Promise.withResolvers() + fs.readTextOverride = async (_target, signal) => { + if (signal === undefined) throw new Error('expected the skill lookup signal') + started.resolve(undefined) + return await new Promise((_resolve, reject) => { + signal.addEventListener('abort', () => { + const abortReason = signal.reason as unknown + reject(abortReason instanceof Error ? abortReason : new Error(String(abortReason))) + }, { once: true }) + }) + } + const controller = new AbortController() + const reason = new Error('turn cancelled') + const loading = ctx.skills.get('abortable-skill', { signal: controller.signal }) + await started.promise + controller.abort(reason) + + await expect(loading).rejects.toBe(reason) + expect(fs.statSignals).toEqual([controller.signal]) + expect(fs.readTextSignals).toEqual([controller.signal]) + }) + + it('uses default home root resolution without exposing builtin skills', async () => { + const previousDshHome = process.env.DSH_HOME + const previousAgentsHome = process.env.DSH_AGENTS_HOME + const envHome = await tempDir('skill-env-home') + try { + process.env.DSH_HOME = join(envHome, '.dsh') + process.env.DSH_AGENTS_HOME = join(envHome, '.agents') + await writeSkill(join(envHome, '.dsh/skills'), 'env-skill', 'Env skill') + const ctx = new Context() + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['env-skill']) + + process.env.DSH_HOME = join(envHome, 'empty-dsh') + process.env.DSH_AGENTS_HOME = join(envHome, 'empty-agents') + const empty = new Context() + await empty.plugin(SkillService) + SkillLocal.apply(empty, {}) + expect(await empty.skills.list()).toEqual([]) + } finally { + if (previousDshHome === undefined) { + delete process.env.DSH_HOME + } else { + process.env.DSH_HOME = previousDshHome + } + if (previousAgentsHome === undefined) { + delete process.env.DSH_AGENTS_HOME + } else { + process.env.DSH_AGENTS_HOME = previousAgentsHome + } + } + }) +}) diff --git a/packages/skill/skill-local/tsconfig.json b/packages/skill/skill-local/tsconfig.json new file mode 100644 index 0000000000..018f0a4a50 --- /dev/null +++ b/packages/skill/skill-local/tsconfig.json @@ -0,0 +1,15 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": ["src"], + "references": [ + { "path": "../../../vendor/cosmokit" }, + { "path": "../../../vendor/cordis" }, + { "path": "../../../vendor/schemastery" }, + { "path": "../../fs/fs" }, + { "path": "../skill" } + ] +} diff --git a/packages/skill/skill/README.md b/packages/skill/skill/README.md new file mode 100644 index 0000000000..98f787dbc7 --- /dev/null +++ b/packages/skill/skill/README.md @@ -0,0 +1,34 @@ +# @deepseek-ai/dsh-skill + +Pure agent skill provider registry. + +This package owns the `ctx.skills` interface. It does not know whether skills come from local files, embedded plugin data, HTTP, or another backend; providers register those sources with `ctx.skills.registerProvider(...)`. The shipped local implementation is [`@deepseek-ai/dsh-skill-local`](../skill-local). + +## Service: `SkillService` (ctx key: `skills`) + +### Public API + +- `ctx.skills.registerProvider(provider): () => void` Registers a provider by unique `provider.name`. Duplicate provider names throw, and `runtime` is reserved for `ctx.skills.register(...)`. The registration is effect-scoped and HMR-safe. +- `ctx.skills.list({ cwd?, signal? })` Returns model-invocable skill summaries for the current workspace, merged across providers and sorted by name. +- `ctx.skills.get(name, { cwd?, signal? })` Returns the full winning skill, including disabled-for-model skills. +- `ctx.skills.register(skill): () => void` Registers a runtime embedded skill. Same-name runtime registrations are first-wins: a duplicate logs a warning and gets a no-op disposer. + +### Config + +| Field | Default | Meaning | +|---|---|---| +| `collectCacheMaxEntries` | `128` | Maximum completed cwd/provider catalog snapshots kept in memory. | + +## Provider Contract + +A provider registers synchronously from its `apply()` and returns `SkillCandidate[]` from `list(options)` when discovery is requested. Remote setup, authentication, and discovery belong in the awaited `list()` call rather than plugin registration. Providers should stop promptly when `options.signal` aborts; the registry also stops awaiting an uncooperative provider so agent cancellation cannot hang prefix composition. The provider later receives the winning candidate back in `get(candidate, options)`. The candidate's `locator` is opaque to the registry, so a local provider can store a file path while a remote provider can store a URL, id, or version token. + +The registry validates candidate names, descriptions, ranks, and provider ownership. Candidate contract violations fail fast because the provider plugin is malformed; a provider `list()` rejection is treated as a transient source failure, logged, skipped for that request, and not cached. Only completed catalogs are cached, and a provider/runtime revision change during discovery discards the stale result and retries. Duplicate skill names are resolved first-wins by `rank`, provider registration order, then the provider's own local order. The final summary list is sorted by skill `name` for deterministic consumers. + +## Runtime Skills + +`ctx.skills.register(...)` is a convenience for embedded runtime skills. Runtime skills use rank `250`: project providers can override them, while they override the shipped local provider's custom and user roots. Runtime registration is also first-wins within runtime contributions, so a duplicate contribution cannot remove the active one through its disposer. + +## Consumer boundary + +The registry does not render model guidance or register model-facing tools. [`@deepseek-ai/dsh-tool-skill`](../tool-skill) consumes `ctx.skills` to provide the session-prefix catalog and `skill` tool, so providers remain independent of the model surface. diff --git a/packages/skill/skill/package.json b/packages/skill/skill/package.json new file mode 100644 index 0000000000..b303e16bed --- /dev/null +++ b/packages/skill/skill/package.json @@ -0,0 +1,33 @@ +{ + "name": "@deepseek-ai/dsh-skill", + "description": "Agent skill provider registry for the DeepSeek Harness", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/skill/skill/src/index.ts b/packages/skill/skill/src/index.ts new file mode 100644 index 0000000000..50a8b5d0d0 --- /dev/null +++ b/packages/skill/skill/src/index.ts @@ -0,0 +1,461 @@ +/** + * Agent skill provider registry. + * + * This package is the interface third of the skill capability seam. Concrete + * providers such as `@deepseek-ai/dsh-skill-local` decide where skills come + * from; this service only merges provider catalogs, resolves the winning skill + * for a name, and exposes the winning summaries and definitions to consumers. + * + * @module @deepseek-ai/dsh-skill + */ + +import { Context, Service } from 'cordis' +import z from 'schemastery' +import type Schema from 'schemastery' + +const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/ +const DEFAULT_COLLECT_CACHE_ENTRIES = 128 +const RUNTIME_PROVIDER = 'runtime' +const RUNTIME_RANK = 250 + +/** + * Return whether a string is a valid kebab-case skill name. + * @param name - candidate skill name to validate. + * @returns whether the name matches the public skill-name grammar. + */ +export function isSkillName(name: string): boolean { + return SKILL_NAME.test(name) +} + +/** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */ +export type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | (string & {}) + +/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */ +export type SkillResourceBase = + | { kind: 'directory'; path: string } + | { kind: 'url'; url: string } + | { kind: 'opaque'; description: string } + +/** Model-visible skill metadata returned by `ctx.skills.list()` and rendered into request guidance. */ +export interface SkillSummary { + /** Kebab-case identifier used with the `skill` tool. */ + name: string + /** Short routing description shown to the model. */ + description: string + /** Optional extra routing guidance shown to the model. */ + whenToUse?: string + /** Whether the skill is hidden from model listings while remaining loadable by trusted callers. */ + disableModelInvocation?: boolean + /** Discovery source that produced this winning skill. */ + source: SkillSource + /** Provider that owns this skill body. */ + provider: string + /** Provider-specific base for relative resources. */ + resourceBase?: SkillResourceBase +} + +/** Provider catalog entry used by the registry to merge and later load skills. */ +export interface SkillCandidate extends SkillSummary { + /** Lower ranks win duplicate skill names before provider registration order is considered. */ + rank: number + /** Opaque provider-owned handle passed back to `provider.get()`. */ + locator: unknown + /** Absolute file path when the provider has one. */ + path?: string + /** Parsed optional metadata object from provider-specific skill frontmatter. */ + metadata?: Record +} + +/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */ +export interface SkillDefinition extends SkillSummary { + /** Markdown instruction body after any provider-specific metadata removal. */ + content: string + /** Absolute file path when the skill came from disk. */ + path?: string + /** Parsed optional metadata object from frontmatter. */ + metadata?: Record +} + +/** Runtime skill contribution accepted by `ctx.skills.register()`. */ +export type SkillRegistration = Omit & { provider?: string } + +/** Caller context used for cwd-sensitive and abortable provider work. */ +export interface SkillLookupOptions { + cwd?: string | undefined + /** Abort discovery or loading work for the current caller. */ + signal?: AbortSignal | undefined +} + +/** Provider interface for one source of skills, such as local directories or a remote registry. */ +export interface SkillProvider { + /** Unique provider name in the `ctx.skills` registry. */ + name: string + /** + * List available skill candidates for the current lookup context. Provider + * plugins register synchronously during `apply()`; remote initialization, + * authentication, and discovery are awaited inside this method. Implementations + * should settle promptly when `options.signal` aborts. + * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work. + * @returns provider candidates with precedence ranks and opaque locators. + */ + list(options: SkillLookupOptions): Promise + /** + * Load a complete skill body for a previously listed candidate. + * @param candidate - the winning candidate originally returned by this provider. + * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work. + * @returns the full skill body, or `undefined` if it is no longer loadable. + */ + get(candidate: SkillCandidate, options: SkillLookupOptions): Promise +} + +/** Skill registry configuration. */ +export interface Config { + /** Maximum number of completed cwd/provider catalog snapshots kept in memory. */ + collectCacheMaxEntries?: number +} + +declare module 'cordis' { + interface Context { + skills: SkillService + } + + interface Events { + /** + * A skill provider became resolvable in the `ctx.skills` registry. + * Consumers can observe this instead of depending on Cordis plugin load + * order, which is concurrent for sibling plugins. + * @param provider - the provider that just registered. + * @mode emit + */ + 'skill/provider-added'(provider: SkillProvider): void + /** + * A skill provider left the registry because its plugin fiber was disposed. + * @param name - the registry name that no longer resolves. + * @mode emit + */ + 'skill/provider-removed'(name: string): void + } +} + +interface IndexedCandidate { + candidate: SkillCandidate + provider: SkillProvider + providerOrder: number + localOrder: number +} + +interface CollectResult { + entries: IndexedCandidate[] + cacheable: boolean +} + +/** + * Registry of skill providers. It merges provider catalogs with stable + * first-wins duplicate handling, exposes sorted model-visible summaries, and + * loads full skill bodies on demand. + */ +export class SkillService extends Service { + static Config: Schema = z.object({ + collectCacheMaxEntries: z.number().default(DEFAULT_COLLECT_CACHE_ENTRIES), + }) + + private readonly collectCacheMaxEntries: number + private readonly providers = new Map() + private readonly runtime = new Map() + private readonly collectCache = new Map() + private providerRevision = 0 + private nextProviderOrder = 0 + private runtimeRevision = 0 + + constructor(ctx: Context, config: Config = {}) { + super(ctx, 'skills') + this.collectCacheMaxEntries = config.collectCacheMaxEntries ?? DEFAULT_COLLECT_CACHE_ENTRIES + assertPositiveInteger('collectCacheMaxEntries', this.collectCacheMaxEntries) + } + + /** + * Register a skill provider synchronously during the provider plugin's + * `apply()`. Throws if another provider already owns the same provider name, + * including the reserved runtime provider name. Providers that need remote + * initialization do that work inside `list()` after registration. Effect- + * scoped and HMR-safe: disposing the caller's fiber unregisters the provider + * and invalidates cached catalogs. + * @param provider - the provider to register by `provider.name`. + * @returns a disposer that unregisters this provider. + */ + registerProvider(provider: SkillProvider): () => void { + const dispose = this.ctx.effect(function* (this: SkillService) { + if (provider.name === RUNTIME_PROVIDER) { + throw new Error(`"${RUNTIME_PROVIDER}" is reserved for runtime skill registrations`) + } + if (this.providers.has(provider.name)) { + throw new Error(`a skill provider named "${provider.name}" is already registered`) + } + this.providers.set(provider.name, { provider, order: this.nextProviderOrder }) + this.nextProviderOrder += 1 + this.invalidateCache() + yield () => { + this.providers.delete(provider.name) + this.invalidateCache() + this.ctx.emit('skill/provider-removed', provider.name) + } + this.ctx.emit('skill/provider-added', provider) + }.bind(this), 'skills.registerProvider()') + return () => void dispose() + } + + /** + * Register a runtime skill contribution. Runtime registrations are treated as + * embedded provider entries with project-over-user priority. Same-name runtime + * registrations are first-wins: a duplicate logs a warning and gets a no-op + * disposer so it cannot remove the active contribution. + * @param skill - the complete skill definition to expose for discovery. + * @returns a disposer that removes this runtime contribution and invalidates caches. + */ + register(skill: SkillRegistration): () => void { + const normalized = normalizeRuntimeSkill(skill) + const existing = this.runtime.get(normalized.name) + if (existing !== undefined) { + this.ctx.logger.warn(`runtime skill "${normalized.name}" ignored because it is already registered`) + return () => {} + } + const dispose = this.ctx.effect(function* (this: SkillService) { + this.runtime.set(normalized.name, normalized) + this.runtimeRevision += 1 + this.invalidateCache() + yield () => { + this.runtime.delete(normalized.name) + this.runtimeRevision += 1 + this.invalidateCache() + } + }.bind(this), 'skills.register()') + return () => void dispose() + } + + /** + * List model-invocable skill summaries for a workspace. + * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery. + * @returns sorted summaries, excluding skills disabled for model invocation. + */ + async list(options: SkillLookupOptions = {}): Promise { + return (await this.collect(options)) + .map(entry => entry.candidate) + .filter(skill => skill.disableModelInvocation !== true) + .map(toSummary) + .sort(compareSkillSummary) + } + + /** + * Load one full skill definition by name. + * @param name - kebab-case skill name. + * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work. + * @returns the full skill, including body content, or `undefined`. + */ + async get(name: string, options: SkillLookupOptions = {}): Promise { + if (!isSkillName(name)) return undefined + const match = (await this.collect(options)).find(entry => entry.candidate.name === name) + if (match === undefined) return undefined + return await match.provider.get(match.candidate, options) + } + + private async collect(options: SkillLookupOptions): Promise { + options.signal?.throwIfAborted() + while (true) { + const providerRevision = this.providerRevision + const runtimeRevision = this.runtimeRevision + const key = collectCacheKey(options, providerRevision, runtimeRevision) + const cached = this.collectCache.get(key) + if (cached !== undefined) return cached + + const result = await this.collectFresh(options) + options.signal?.throwIfAborted() + if (providerRevision !== this.providerRevision || runtimeRevision !== this.runtimeRevision) continue + if (result.cacheable) { + this.collectCache.set(key, result.entries) + if (this.collectCache.size > this.collectCacheMaxEntries) { + const oldest = this.collectCache.keys().next() as IteratorYieldResult + this.collectCache.delete(oldest.value) + } + } + return result.entries + } + } + + private async collectFresh(options: SkillLookupOptions): Promise { + const collected = await this.listAllCandidates(options) + collected.entries.sort(compareIndexedCandidates) + const seen = new Set() + const result: IndexedCandidate[] = [] + for (const entry of collected.entries) { + const skill = entry.candidate + if (seen.has(skill.name)) { + this.ctx.logger.warn(`skill "${skill.name}" from ${skill.source} ignored because a higher-priority skill already exists`) + continue + } + seen.add(skill.name) + result.push(entry) + } + return { entries: result, cacheable: collected.cacheable } + } + + private async listAllCandidates(options: SkillLookupOptions): Promise { + options.signal?.throwIfAborted() + const candidates: IndexedCandidate[] = [] + let cacheable = true + let runtimeOrder = 0 + for (const skill of [...this.runtime.values()].sort((a, b) => compareCodePoints(a.name, b.name))) { + candidates.push({ + candidate: runtimeCandidate(skill), + provider: RUNTIME_SKILL_PROVIDER, + providerOrder: -1, + localOrder: runtimeOrder, + }) + runtimeOrder += 1 + } + for (const { provider, order } of [...this.providers.values()]) { + let localOrder = 0 + let listed: SkillCandidate[] | undefined + try { + listed = await waitWithAbort(provider.list(options), options.signal) + } catch (error) { + if (options.signal?.aborted === true) throw toError(options.signal.reason) + cacheable = false + this.ctx.logger.warn(`skill provider "${provider.name}" skipped: ${errorMessage(error)}`) + } + if (listed === undefined) continue + for (const candidate of listed) { + validateCandidate(candidate, provider.name) + candidates.push({ candidate, provider, providerOrder: order, localOrder }) + localOrder += 1 + } + } + return { entries: candidates, cacheable } + } + + private invalidateCache(): void { + this.providerRevision += 1 + this.collectCache.clear() + } +} + +const RUNTIME_SKILL_PROVIDER: SkillProvider = { + name: RUNTIME_PROVIDER, + /* v8 ignore next -- Runtime skills are injected directly by the registry; this provider only owns `get()`. */ + list() { + return Promise.resolve([]) + }, + get(candidate) { + const skill = candidate.locator as SkillDefinition + return Promise.resolve({ ...skill }) + }, +} + +function runtimeCandidate(skill: SkillDefinition): SkillCandidate { + return { + ...toSummary(skill), + rank: RUNTIME_RANK, + locator: skill, + ...skill.path !== undefined ? { path: skill.path } : {}, + ...skill.metadata !== undefined ? { metadata: skill.metadata } : {}, + } +} + +function validateCandidate(candidate: SkillCandidate, providerName: string): void { + if (!SKILL_NAME.test(candidate.name)) { + throw new Error(`skill provider "${providerName}" returned invalid skill name "${candidate.name}"`) + } + if (candidate.description.length === 0) { + throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" without a description`) + } + if (!Number.isFinite(candidate.rank)) { + throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" with an invalid rank`) + } + if (candidate.provider !== providerName) { + throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" for provider "${candidate.provider}"`) + } +} + +function normalizeRuntimeSkill(skill: SkillRegistration): SkillDefinition { + if (!SKILL_NAME.test(skill.name)) throw new Error(`invalid skill name "${skill.name}"`) + if (skill.description.length === 0) throw new Error(`skill "${skill.name}" requires a description`) + return { + ...skill, + provider: skill.provider ?? RUNTIME_PROVIDER, + source: skill.source, + } +} + +function toSummary(skill: SkillDefinition | SkillCandidate): SkillSummary { + const { name, description, whenToUse, disableModelInvocation, source, provider, resourceBase } = skill + return { + name, + description, + ...whenToUse !== undefined ? { whenToUse } : {}, + ...disableModelInvocation !== undefined ? { disableModelInvocation } : {}, + source, + provider, + ...resourceBase !== undefined ? { resourceBase } : {}, + } +} + +function compareSkillSummary(left: SkillSummary, right: SkillSummary): number { + return compareCodePoints(left.name, right.name) +} + +function compareCodePoints(left: string, right: string): number { + if (left < right) return -1 + if (left > right) return 1 + return 0 +} + +function compareIndexedCandidates(left: IndexedCandidate, right: IndexedCandidate): number { + return left.candidate.rank - right.candidate.rank + || left.providerOrder - right.providerOrder + || left.localOrder - right.localOrder +} + +function assertPositiveInteger(name: string, value: number, minimum = 1): void { + if (!Number.isInteger(value) || value < minimum) { + throw new Error(`skill: ${name} must be an integer greater than or equal to ${minimum}`) + } +} + +function collectCacheKey(options: SkillLookupOptions, providerRevision: number, runtimeRevision: number): string { + return JSON.stringify({ cwd: options.cwd, providerRevision, runtimeRevision }) +} + +function waitWithAbort(promise: Promise, signal: AbortSignal | undefined): Promise { + if (signal === undefined) return promise + signal.throwIfAborted() + return new Promise((resolve, reject) => { + const cleanup = (): void => { + signal.removeEventListener('abort', onAbort) + } + const onAbort = (): void => { + cleanup() + reject(toError(signal.reason)) + } + signal.addEventListener('abort', onAbort, { once: true }) + void promise.then( + (value) => { + cleanup() + resolve(value) + }, + (error: unknown) => { + cleanup() + reject(toError(error)) + }, + ) + if (signal.aborted) onAbort() + }) +} + +function toError(error: unknown): Error { + return error instanceof Error ? error : new Error(String(error)) +} + +function errorMessage(error: unknown): string { + return String(error) +} + +export default SkillService diff --git a/packages/skill/skill/tests/skill.spec.ts b/packages/skill/skill/tests/skill.spec.ts new file mode 100644 index 0000000000..010d161039 --- /dev/null +++ b/packages/skill/skill/tests/skill.spec.ts @@ -0,0 +1,344 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import SkillService, { type SkillCandidate, type SkillDefinition, type SkillLookupOptions, type SkillProvider } from '@deepseek-ai/dsh-skill' + +function memorySkill(name: string, description: string, rank: number, body = `${name} body.`): SkillCandidate { + return { + name, + description, + provider: 'memory', + source: 'memory', + rank, + locator: { content: body }, + } +} + +class MemoryProvider implements SkillProvider { + readonly name = 'memory' + listCalls = 0 + + constructor(private candidates: SkillCandidate[]) {} + + async list(_options: SkillLookupOptions): Promise { + this.listCalls += 1 + return this.candidates + } + + async get(candidate: SkillCandidate): Promise { + const locator = candidate.locator as { content: string } + return { ...candidate, content: locator.content } + } + + replace(candidates: SkillCandidate[]): void { + this.candidates = candidates + } +} + +describe('SkillService registry', () => { + it('registers providers, resolves duplicates first-wins, and disposes providers', async () => { + const ctx = new Context() + await ctx.plugin(SkillService) + const provider = new MemoryProvider([ + memorySkill('z-skill', 'Z skill', 20), + memorySkill('a-skill', 'A skill', 10), + memorySkill('shadowed', 'Lower priority', 20), + ]) + const overrideProvider: SkillProvider = { + name: 'override', + async list() { + return [{ + name: 'shadowed', + description: 'Higher priority', + provider: 'override', + source: 'override', + rank: 5, + locator: { content: 'Override body.' }, + }] + }, + async get(candidate) { + return { ...candidate, content: (candidate.locator as { content: string }).content } + }, + } + const disposeMemory = ctx.skills.registerProvider(provider) + ctx.skills.registerProvider(overrideProvider) + + expect((await ctx.skills.list()).map(skill => [skill.name, skill.description, skill.provider])).toEqual([ + ['a-skill', 'A skill', 'memory'], + ['shadowed', 'Higher priority', 'override'], + ['z-skill', 'Z skill', 'memory'], + ]) + expect((await ctx.skills.get('shadowed'))?.content).toBe('Override body.') + const sameRankProvider: SkillProvider = { + name: 'same-rank', + async list() { + return [{ + name: 'same-rank-skill', + description: 'Same rank', + provider: 'same-rank', + source: 'same-rank', + rank: 10, + locator: { content: 'Same rank body.' }, + }] + }, + async get(candidate) { + return { ...candidate, content: (candidate.locator as { content: string }).content } + }, + } + ctx.skills.registerProvider(sameRankProvider) + expect((await ctx.skills.list()).find(skill => skill.name === 'same-rank-skill')?.provider).toBe('same-rank') + await expect(ctx.plugin({ + name: 'duplicate-memory', + inject: ['skills'], + apply(pluginCtx: Context) { + pluginCtx.skills.registerProvider(new MemoryProvider([])) + }, + })).rejects.toThrow('already registered') + expect(() => ctx.skills.registerProvider({ + name: 'runtime', + async list() { + return [] + }, + async get() { + return undefined + }, + })).toThrow('reserved') + + disposeMemory() + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['same-rank-skill', 'shadowed']) + }) + + it('validates provider candidates and invalid registry caps', async () => { + const defaultedService = new SkillService(new Context()) + expect(await defaultedService.list()).toEqual([]) + + const ctx = new Context() + await ctx.plugin(SkillService) + ctx.skills.registerProvider({ + name: 'bad', + async list() { + return [memorySkill('Bad_Name', 'bad', 1)] + }, + async get() { + return undefined + }, + }) + await expect(ctx.skills.list()).rejects.toThrow('invalid skill name') + + const invalidCandidates = [ + { ...memorySkill('empty-description', '', 1), provider: 'empty-description' }, + { ...memorySkill('bad-rank', 'Bad rank', Number.NaN), provider: 'bad-rank' }, + { ...memorySkill('wrong-provider', 'Wrong provider', 1), provider: 'different' }, + ] + for (const candidate of invalidCandidates) { + const invalid = new Context() + await invalid.plugin(SkillService) + invalid.skills.registerProvider({ + name: candidate.name, + async list() { + return [candidate] + }, + async get() { + return undefined + }, + }) + await expect(invalid.skills.list()).rejects.toThrow('skill provider') + } + + await expect(new Context().plugin(SkillService, { collectCacheMaxEntries: 1.5 })).rejects.toThrow('collectCacheMaxEntries') + }) + + it('sorts model-visible summaries without locale-sensitive collation', async () => { + const ctx = new Context() + await ctx.plugin(SkillService) + ctx.skills.registerProvider(new MemoryProvider([ + memorySkill('z-skill', 'Z skill', 10), + memorySkill('a-skill', 'A skill', 10), + ])) + const localeCompare = vi.spyOn(String.prototype, 'localeCompare') + const sort = vi.spyOn(Array.prototype, 'sort') + + try { + const skills = await ctx.skills.list() + expect(skills.map(skill => skill.name)).toEqual(['a-skill', 'z-skill']) + expect(localeCompare).not.toHaveBeenCalled() + + const summaryComparator = sort.mock.calls.at(-1)?.[0] + expect(summaryComparator).toBeTypeOf('function') + expect(summaryComparator?.(skills[0], skills[0])).toBe(0) + } finally { + sort.mockRestore() + localeCompare.mockRestore() + } + }) + + it('caches provider discovery, skips failing providers, and invalidates on runtime skills', async () => { + const ctx = new Context() + await ctx.plugin(SkillService, { collectCacheMaxEntries: 1 }) + const provider = new MemoryProvider([memorySkill('first-skill', 'First', 10)]) + ctx.skills.registerProvider(provider) + + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['first-skill']) + provider.replace([memorySkill('second-skill', 'Second', 10)]) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['first-skill']) + + const disposeRuntime = ctx.skills.register({ + name: 'runtime-skill', + description: 'Runtime', + source: 'runtime', + resourceBase: { kind: 'opaque', description: 'runtime memory' }, + path: 'memory://runtime-skill', + metadata: { owner: 'tests' }, + content: 'Runtime body.', + }) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['runtime-skill', 'second-skill']) + expect(await ctx.skills.get('runtime-skill')).toMatchObject({ + content: 'Runtime body.', + path: 'memory://runtime-skill', + metadata: { owner: 'tests' }, + }) + disposeRuntime() + await ctx.skills.list({ cwd: '/tmp/first-cache-key' }) + await ctx.skills.list({ cwd: '/tmp/second-cache-key' }) + + let fail = true + let flakyCalls = 0 + ctx.skills.registerProvider({ + name: 'flaky', + async list() { + flakyCalls += 1 + if (fail) throw new Error('transient discovery failure') + return [{ ...memorySkill('flaky-skill', 'Flaky', 10), provider: 'flaky' }] + }, + async get() { + return undefined + }, + }) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['second-skill']) + expect(flakyCalls).toBe(1) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['second-skill']) + expect(flakyCalls).toBe(2) + fail = false + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['flaky-skill', 'second-skill']) + expect(flakyCalls).toBe(3) + expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['flaky-skill', 'second-skill']) + expect(flakyCalls).toBe(3) + }) + + it('abandons an in-flight catalog when provider registrations change', async () => { + const ctx = new Context() + await ctx.plugin(SkillService) + let markStarted: (() => void) | undefined + let release: (() => void) | undefined + const started = new Promise((resolve) => { markStarted = resolve }) + const gate = new Promise((resolve) => { release = resolve }) + const dispose = ctx.skills.registerProvider({ + name: 'delayed', + async list() { + markStarted?.() + await gate + return [{ ...memorySkill('stale-skill', 'Stale', 10), provider: 'delayed' }] + }, + async get(candidate) { + return { ...candidate, content: 'Stale body.' } + }, + }) + + const pending = ctx.skills.list() + await started + dispose() + release?.() + + expect(await pending).toEqual([]) + }) + + it('stops waiting for discovery when its lookup signal aborts', async () => { + const ctx = new Context() + await ctx.plugin(SkillService) + let markStarted: (() => void) | undefined + let release: (() => void) | undefined + let seenSignal: AbortSignal | undefined + const started = new Promise((resolve) => { markStarted = resolve }) + const held = new Promise((resolve) => { + release = () => { resolve([]) } + }) + ctx.skills.registerProvider({ + name: 'uncooperative', + list(options) { + seenSignal = options.signal + markStarted?.() + return held + }, + async get() { + return undefined + }, + }) + const controller = new AbortController() + const reason = 'discovery cancelled' + const pending = ctx.skills.list({ signal: controller.signal }) + const outcome = pending.then( + () => 'resolved', + (error: unknown) => error instanceof Error && error.message === reason ? 'aborted' : 'other-error', + ) + await started + controller.abort(reason) + + const settled = await Promise.race([ + outcome, + new Promise<'timeout'>(resolve => setTimeout(() => { resolve('timeout') }, 25)), + ]) + release?.() + await pending.catch(() => undefined) + + expect(seenSignal).toBe(controller.signal) + expect(settled).toBe('aborted') + }) + + it('does not miss an abort racing listener installation', async () => { + const ctx = new Context() + await ctx.plugin(SkillService) + const reason = new Error('racing abort') + let aborted = false + const signal = { + get aborted() { + return aborted + }, + reason, + throwIfAborted() { + if (aborted) throw reason + }, + addEventListener(_type: string, listener: () => void) { + aborted = true + listener() + }, + removeEventListener() {}, + } as unknown as AbortSignal + ctx.skills.registerProvider({ + name: 'racing-abort', + list() { + return Promise.reject(new Error('late provider failure')) + }, + async get() { + return undefined + }, + }) + + await expect(ctx.skills.list({ signal })).rejects.toBe(reason) + await Promise.resolve() + }) + + it('rejects invalid runtime skill registrations and ignores duplicates', async () => { + const ctx = new Context() + await ctx.plugin(SkillService) + expect(() => ctx.skills.register({ name: 'Bad_Name', description: 'Bad', source: 'runtime', content: 'bad' })).toThrow('invalid skill name') + expect(() => ctx.skills.register({ name: 'no-description', description: '', source: 'runtime', content: 'bad' })).toThrow('requires a description') + expect(await ctx.skills.get('missing-skill')).toBeUndefined() + expect(await ctx.skills.get('Bad_Name')).toBeUndefined() + + const disposeFirst = ctx.skills.register({ name: 'same-skill', description: 'First', source: 'runtime', content: 'first' }) + const disposeSecond = ctx.skills.register({ name: 'same-skill', description: 'Second', source: 'runtime', content: 'second' }) + disposeSecond() + expect((await ctx.skills.get('same-skill'))?.description).toBe('First') + disposeFirst() + expect(await ctx.skills.get('same-skill')).toBeUndefined() + }) +}) diff --git a/packages/skill/skill/tsconfig.json b/packages/skill/skill/tsconfig.json new file mode 100644 index 0000000000..1b1855dcc4 --- /dev/null +++ b/packages/skill/skill/tsconfig.json @@ -0,0 +1,13 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": ["src"], + "references": [ + { "path": "../../../vendor/cosmokit" }, + { "path": "../../../vendor/cordis" }, + { "path": "../../../vendor/schemastery" } + ] +} diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md new file mode 100644 index 0000000000..c55bc3693d --- /dev/null +++ b/packages/skill/tool-skill/README.md @@ -0,0 +1,21 @@ +# @deepseek-ai/dsh-tool-skill + +The model-facing skill catalog and `skill` tool. + +Requires `ctx.tools` and `ctx.skills` (`inject: ['tools', 'skills']`). + +## Session-prefix catalog + +The plugin contributes one user-role `` catalog through `agent/session-prefix`. It resolves skills for the calling session's cwd, forwards the prefix abort signal to discovery, and lists only sorted `name` and `description` entries; skill bodies, paths, sources, providers, and `whenToUse` hints remain outside the catalog. The catalog is omitted when no model-invocable skills are available. + +`catalogDescriptionMaxLength` controls normalized, XML-escaped catalog descriptions. Its default is `500` and values must be integers of at least `3`, which reserves room for a truncation ellipsis. The [session-prefix RFC](../../../docs/rfc/implemented/feature/2026-07-07-session-prefix.md) defines the request-only, header-logged lifecycle of this message. + +## Tool: `skill` + +| Arg | Type | Notes | +|---|---|---| +| `name` | string (required) | Exact kebab-case skill name from the available skills listing. | + +Execution uses the calling agent's `session.header.cwd` so workspace-sensitive providers can resolve the right winning skill. A successful call returns one text tool result with ``, containing `` followed by ``. Resource guidance resolves paths or URLs explicitly referenced by the loaded instructions against `resourceBase`; referenced scripts, references, and assets load only when needed, and the tool does not enumerate a skill directory. Local filesystem skills provide a base directory, while remote or embedded providers can provide a URL or opaque provider-managed guidance. A name that cannot be resolved reports that the skill is unknown or no longer available; invalid names and skills marked `disableModelInvocation: true` retain distinct `isError` results. + +The tool does not call `agent.inject()` in v1. Its result is already recorded as the tool result and becomes available to the next model step without duplicating the content as synthetic context. diff --git a/packages/skill/tool-skill/package.json b/packages/skill/tool-skill/package.json new file mode 100644 index 0000000000..f0d97eb3d8 --- /dev/null +++ b/packages/skill/tool-skill/package.json @@ -0,0 +1,42 @@ +{ + "name": "@deepseek-ai/dsh-tool-skill", + "description": "Model-facing skill loading tool for the DeepSeek Harness", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-skill": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-skill": "workspace:^", + "@deepseek-ai/dsh-skill-local": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts new file mode 100644 index 0000000000..dc3232a13f --- /dev/null +++ b/packages/skill/tool-skill/src/index.ts @@ -0,0 +1,152 @@ +/** + * Session-prefix skill catalog and model-facing `skill` loader tool. + * + * @module @deepseek-ai/dsh-tool-skill + */ + +import type { Context } from 'cordis' +import z from 'schemastery' +import { defineTool } from '@deepseek-ai/dsh-tools' +import { assertNever, type Message } from '@deepseek-ai/dsh-llm' +import { isSkillName, type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill' + +export const name = 'tool-skill' +export const inject = ['tools', 'skills'] + +const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500 + +/** Model-facing skill catalog configuration. */ +export interface Config { + /** Maximum normalized description length rendered in the session catalog; minimum 3. */ + catalogDescriptionMaxLength?: number +} + +/** Validate and default the model-facing skill catalog configuration. */ +export const Config: z = z.object({ + catalogDescriptionMaxLength: z.number().default(DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH), +}) + +/** Register the session-prefix skill catalog and the model-facing skill loader. */ +export function apply(ctx: Context, config: Config = {}): void { + const catalogDescriptionMaxLength = config.catalogDescriptionMaxLength ?? DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH + assertPositiveInteger('catalogDescriptionMaxLength', catalogDescriptionMaxLength, 3) + + ctx.on('agent/session-prefix', async (agent, _prefix, signal, next): Promise => { + const skills = await ctx.skills.list({ cwd: agent.session.header.cwd, signal }) + const rest = await next() + if (skills.length === 0) return rest + return [renderCatalogMessage(skills, catalogDescriptionMaxLength), ...rest] + }) + + const skillTool = defineTool({ + name: 'skill', + description: 'Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.', + parameters: { + name: { type: 'string', required: true, description: 'The exact skill name from the available skills list.' }, + }, + async execute(args, exec) { + if (!isSkillName(args.name)) { + throw new Error(`invalid skill name "${args.name}"`) + } + const skill = await ctx.skills.get(args.name, { cwd: exec.agent?.session.header.cwd, signal: exec.signal }) + if (!skill) { + throw new Error(`skill "${args.name}" is unknown or no longer available`) + } + if (skill.disableModelInvocation === true) { + throw new Error(`skill "${args.name}" is not available for model invocation`) + } + return [{ type: 'text', text: renderSkillContent(skill) }] + }, + presentCall(args) { + return { card: 'generic', title: `Load skill ${args.name}`, kind: 'read', rawInput: args.name } + }, + }) + ctx.tools.register(skillTool) +} + +function renderSkillContent(skill: SkillDefinition): string { + const resourceHint = renderResourceHint(skill) + return [ + ``, + '', + ...resourceHint, + '', + '', + '', + skill.content, + '', + '', + ].join('\n') +} + +function renderResourceHint(skill: SkillDefinition): string[] { + const base = skill.resourceBase + if (base === undefined) { + return [ + `Resources for this skill are managed by provider "${escapeText(skill.provider)}".`, + 'Load referenced resources only as needed.', + ] + } + switch (base.kind) { + case 'directory': + return [ + `Base directory for this skill: ${escapeText(base.path)}`, + 'Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.', + ] + case 'url': + return [ + `Base URL for this skill: ${escapeText(base.url)}`, + 'Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.', + ] + case 'opaque': + return [ + `Resources for this skill: ${escapeText(base.description)}`, + 'Load referenced resources only as needed.', + ] + default: + return assertNever(base, 'SkillResourceBase.kind') + } +} + +function renderCatalogMessage(skills: SkillSummary[], descriptionMaxLength: number): Message { + const entries = skills.map(skill => `- \`${skill.name}\`: ${catalogDescription(skill.description, descriptionMaxLength)}`) + return { + role: 'user', + content: [{ + type: 'text', + text: [ + '', + 'A skill is a reusable set of task-specific instructions. The following skills are available in this session:', + '', + '', + ...entries, + '', + '', + "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.", + '', + ].join('\n'), + }], + } +} + +function catalogDescription(value: string, maxLength: number): string { + const normalized = value.replaceAll(/\s+/g, ' ').trim() + const truncated = normalized.length <= maxLength + ? normalized + : `${normalized.slice(0, maxLength - 3)}...` + return escapeText(truncated) +} + +function assertPositiveInteger(name: string, value: number, minimum = 1): void { + if (!Number.isInteger(value) || value < minimum) { + throw new Error(`tool-skill: ${name} must be an integer greater than or equal to ${minimum}`) + } +} + +function escapeAttr(value: string): string { + return value.replaceAll('&', '&').replaceAll('"', '"').replaceAll('<', '<') +} + +function escapeText(value: string): string { + return value.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>') +} diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts new file mode 100644 index 0000000000..c7b843258c --- /dev/null +++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts @@ -0,0 +1,275 @@ +import { describe, expect, it } from 'vitest' +import { mkdir, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { tmpdir } from 'node:os' +import { Context } from 'cordis' +import { CallId, type Message } from '@deepseek-ai/dsh-llm' +import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import SkillService from '@deepseek-ai/dsh-skill' +import * as SkillLocal from '@deepseek-ai/dsh-skill-local' +import * as toolSkill from '@deepseek-ai/dsh-tool-skill' + +async function tempDir(name: string): Promise { + return await import('node:fs/promises').then(fs => fs.mkdtemp(join(tmpdir(), `dsh-${name}-`))) +} + +async function writeSkill(root: string, name: string, description: string, body: string): Promise { + const dir = join(root, name) + await mkdir(dir, { recursive: true }) + await writeFile(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`) +} + +async function setup(home: string, config: toolSkill.Config = {}): Promise { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }) + await ctx.plugin(toolSkill, config) + return ctx +} + +function agentForCwd(cwd: string): never { + return { session: { header: { cwd } } } as never +} + +async function composePrefix(ctx: Context, cwd: string, signal = new AbortController().signal): Promise { + const empty: Message[] = [] + return await ctx.waterfall( + 'agent/session-prefix', agentForCwd(cwd), empty, signal, + () => Promise.resolve(empty), + ) +} + +describe('dsh-tool-skill', () => { + it('registers the skill tool schema and removes it on dispose', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const home = await tempDir('tool-schema') + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }) + ctx.skills.register({ name: 'lifecycle-skill', description: 'Lifecycle', source: 'runtime', content: 'body' }) + + const fiber = await ctx.plugin(toolSkill) + expect(ctx.tools.schemas().map(tool => tool.name)).toEqual(['skill']) + expect(await composePrefix(ctx, '/workspace')).toHaveLength(1) + expect(ctx.tools.get('skill')?.presentCall?.({ name: 'project-skill' })).toEqual({ + card: 'generic', + title: 'Load skill project-skill', + kind: 'read', + rawInput: 'project-skill', + }) + await fiber.dispose() + expect(ctx.tools.schemas()).toEqual([]) + expect(await composePrefix(ctx, '/workspace')).toEqual([]) + + toolSkill.apply(ctx) + expect(ctx.tools.schemas().map(tool => tool.name)).toEqual(['skill']) + }) + + it('forwards the session-prefix abort signal to skill discovery', async () => { + const home = await tempDir('tool-prefix-signal') + const ctx = await setup(home) + let seenSignal: AbortSignal | undefined + ctx.skills.registerProvider({ + name: 'signal-probe', + async list(options) { + seenSignal = options.signal + return [] + }, + async get() { + return undefined + }, + }) + const controller = new AbortController() + + await composePrefix(ctx, '/workspace', controller.signal) + + expect(seenSignal).toBe(controller.signal) + }) + + it('contributes a stable name-and-description catalog through the session prefix', async () => { + const home = await tempDir('tool-catalog') + const ctx = await setup(home, { catalogDescriptionMaxLength: 50 }) + ctx.skills.register({ + name: 'z-skill', + description: 'Long description '.repeat(5), + whenToUse: 'Never render this routing hint.', + source: 'secret-source', + provider: 'runtime', + resourceBase: { kind: 'directory', path: '/secret/path' }, + content: 'Secret body.', + }) + ctx.skills.register({ + name: 'a-skill', + description: 'Use {{placeholder}} & carefully.', + source: 'runtime', + provider: 'runtime', + content: 'A body.', + }) + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => [ + { role: 'user', content: [{ type: 'text', text: 'later contribution' }] }, + ...await next(), + ]) + + const prefix = await composePrefix(ctx, '/workspace') + + expect(prefix).toEqual([ + { + role: 'user', + content: [{ + type: 'text', + text: [ + '', + 'A skill is a reusable set of task-specific instructions. The following skills are available in this session:', + '', + '', + '- `a-skill`: Use {{placeholder}} <safely> & carefully.', + '- `z-skill`: Long description Long description Long descript...', + '', + '', + "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.", + '', + ].join('\n'), + }], + }, + { role: 'user', content: [{ type: 'text', text: 'later contribution' }] }, + ]) + const rendered = JSON.stringify(prefix[0]) + expect(rendered).not.toContain('whenToUse') + expect(rendered).not.toContain('secret-source') + expect(rendered).not.toContain('/secret/path') + expect(rendered).not.toContain('Secret body') + expect(renderPrompt(await ctx.systemPrompt.assemble({ agent: agentForCwd('/workspace') }))).not.toContain('') + }) + + it('does not contribute a session-prefix message when no skills are available', async () => { + const home = await tempDir('tool-empty-catalog') + const ctx = await setup(home) + + expect(await composePrefix(ctx, '/workspace')).toEqual([]) + }) + + it('validates the catalog description cap', async () => { + const home = await tempDir('tool-invalid-catalog-cap') + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }) + + await expect(ctx.plugin(toolSkill, { catalogDescriptionMaxLength: 2 })).rejects.toThrow('greater than or equal to 3') + }) + + it('loads a skill for the calling agent cwd', async () => { + const home = await tempDir('tool-load') + const project = await tempDir('tool-project') + await mkdir(join(project, '.git'), { recursive: true }) + await writeSkill(join(project, '.dsh/skills'), 'project-skill', 'Project skill', 'Project instructions.') + const ctx = await setup(home) + + const result = await ctx.tools.execute({ + callId: CallId('c1'), + name: 'skill', + arguments: { name: 'project-skill' }, + agent: { session: { header: { cwd: project } } } as never, + }) + + expect(result.isError).toBe(false) + const block = result.content[0] + expect(block?.type).toBe('text') + if (block?.type !== 'text') throw new Error('expected text skill result') + expect(block.text).toBe([ + '', + '', + `Base directory for this skill: ${join(project, '.dsh/skills/project-skill')}`, + 'Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.', + '', + '', + '', + 'Project instructions.', + '', + '', + ].join('\n')) + expect(block.text).not.toContain('# Skill:') + }) + + it('renders provider-managed resource hints for non-local skills', async () => { + const home = await tempDir('tool-resource-hints') + const ctx = await setup(home) + ctx.skills.register({ + name: 'opaque-skill', + description: 'Opaque skill', + source: 'runtime', + provider: 'runtime', + resourceBase: { kind: 'opaque', description: 'runtime memory' }, + content: 'Opaque instructions.', + }) + ctx.skills.register({ + name: 'url-skill', + description: 'URL skill', + source: 'runtime', + provider: 'runtime', + resourceBase: { kind: 'url', url: 'https://skills.example.test/url-skill' }, + content: 'URL instructions.', + }) + ctx.skills.register({ + name: 'provider-skill', + description: 'Provider skill', + source: 'runtime', + provider: 'runtime', + content: 'Provider instructions.', + }) + + const opaque = await ctx.tools.execute({ callId: CallId('c2'), name: 'skill', arguments: { name: 'opaque-skill' } }) + const url = await ctx.tools.execute({ callId: CallId('c3'), name: 'skill', arguments: { name: 'url-skill' } }) + const provider = await ctx.tools.execute({ callId: CallId('c4'), name: 'skill', arguments: { name: 'provider-skill' } }) + + if (opaque.content[0]?.type !== 'text' || url.content[0]?.type !== 'text' || provider.content[0]?.type !== 'text') { + throw new Error('expected text tool results') + } + expect(opaque.content[0].text).toContain('\nResources for this skill: runtime memory\nLoad referenced resources only as needed.\n') + expect(url.content[0].text).toContain('\nBase URL for this skill: https://skills.example.test/url-skill\nResolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.\n') + expect(provider.content[0].text).toContain('\nResources for this skill are managed by provider "runtime".\nLoad referenced resources only as needed.\n') + }) + + it('fails loud on an unknown resource base kind', async () => { + const home = await tempDir('tool-resource-assert-never') + const ctx = await setup(home) + ctx.skills.register({ + name: 'rogue-resource-skill', + description: 'Rogue resource skill', + source: 'runtime', + provider: 'runtime', + resourceBase: { kind: 'future' } as never, + content: 'Rogue instructions.', + }) + + const result = await ctx.tools.execute({ callId: CallId('c5'), name: 'skill', arguments: { name: 'rogue-resource-skill' } }) + + expect(result.isError).toBe(true) + const block = result.content[0] + if (block?.type !== 'text') throw new Error('expected text tool result') + expect(block.text).toContain('unreachable variant') + }) + + it('returns isError for unknown, invalid, and model-disabled skills', async () => { + const home = await tempDir('tool-errors') + await writeSkill(join(home, '.dsh/skills'), 'hidden-skill', 'Hidden skill', 'Hidden instructions.') + await writeFile(join(home, '.dsh/skills/hidden-skill/SKILL.md'), '---\nname: hidden-skill\ndescription: Hidden skill\ndisableModelInvocation: true\n---\n\nHidden instructions.\n') + const ctx = await setup(home) + + const unknown = await ctx.tools.execute({ callId: CallId('c1'), name: 'skill', arguments: { name: 'missing' } }) + const invalid = await ctx.tools.execute({ callId: CallId('c2'), name: 'skill', arguments: { name: 'Bad_Name' } }) + const disabled = await ctx.tools.execute({ callId: CallId('c3'), name: 'skill', arguments: { name: 'hidden-skill' } }) + + expect(unknown.isError).toBe(true) + expect(invalid.isError).toBe(true) + expect(disabled.isError).toBe(true) + const unknownBlock = unknown.content[0] + if (unknownBlock?.type !== 'text') throw new Error('expected text tool result') + expect(unknownBlock.text).toContain('skill "missing" is unknown or no longer available') + }) +}) diff --git a/packages/skill/tool-skill/tsconfig.json b/packages/skill/tool-skill/tsconfig.json new file mode 100644 index 0000000000..039fc641c0 --- /dev/null +++ b/packages/skill/tool-skill/tsconfig.json @@ -0,0 +1,17 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": ["src"], + "references": [ + { "path": "../../../vendor/cosmokit" }, + { "path": "../../../vendor/cordis" }, + { "path": "../../../vendor/schemastery" }, + { "path": "../../llm/llm" }, + { "path": "../../core/agent" }, + { "path": "../skill" }, + { "path": "../../core/tools" } + ] +} diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts index a9fefba27c..9d5b17cb9a 100644 --- a/packages/subagent/subagent-acp/src/run.ts +++ b/packages/subagent/subagent-acp/src/run.ts @@ -89,6 +89,7 @@ export interface AcpRunSpec { * (the seam contract forbids `result` rejecting). The driver calls this with * the original error and the chosen stop reason so the fault is preserved * rather than silently lost; the provider wires it to `ctx.logger.warn`. + * A throw from the sink itself is contained — it cannot reject `result`. * Optional — omitted in a unit test that asserts the stop reason directly. */ onError?: (error: Error, stopReason: SubagentStopReason) => void @@ -336,7 +337,13 @@ export function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpec): Su // (initialize/newSession/prompt transport/RPC errors, or ENOENT), not a // local bug. Flatten to `error` and surface the original via onError so a // real fault is preserved rather than silently lost. - spec.onError?.(toError(error), 'error') + try { + spec.onError?.(toError(error), 'error') + } catch { + // Swallows only the caller-supplied sink's OWN throw: an unguarded + // sink exception would reject `result` and break the contract above. + // The child-level failure being reported still settles as `error`. + } return { output: collectOutput(), stopReason: 'error' } } })() diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index 92c025077a..4d8a586c63 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -483,6 +483,28 @@ describe('dsh-subagent-acp', () => { await run.dispose() }) + it('resolves error (never rejects) even when the onError sink itself throws', async () => { + // onError is a caller-supplied callback boundary: its own exception must be + // contained, or it would reject `result` and break the seam's "result never + // rejects" contract that the flattening above exists to uphold. + const run = startAcpRun( + { prompt: [{ type: 'text', text: 'p' }], parent: fakeParent }, + { + command: '/nonexistent/acp-agent-binary', + args: [], + cwd: process.cwd(), + permission: 'reject', + env: {}, + disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, + disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, + onError: () => { throw new Error('sink boom') }, + }, + ) + const result = await run.result + expect(result.stopReason).toBe('error') + await run.dispose() + }) + it('settles aborted when the child crashes (tears the pipe) AFTER a cancel', async () => { // The child hangs, we cancel, and instead of answering the child exits hard // — the pending prompt RPC rejects. With a cancel already requested, the diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 209b1a81cb..002dbf8a19 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -6,7 +6,7 @@ Three layers, importable separately: - **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden + purity check, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo). - **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), and the composable `scrubRequestHeaders` (header bulk → `{{system}}`/`{{tools}}`, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). -- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record-mode fixture write-back, the per-header-class pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, pinning fixtures well-formed, non-pinning fixtures header-scrubbed). Must be called at vitest collection time. +- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record/refresh fixture write-back, the per-header-class pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, pinning fixtures well-formed, non-pinning fixtures header-scrubbed). Must be called at vitest collection time. A consuming `*.snapshot.ts` is the scenario table plus one factory call: @@ -27,12 +27,16 @@ defineAcpSnapshotSuite({ }, snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'), scenarios: SCENARIOS, // exactly one entry per header class sets pinsHeader - mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay', + mode: process.env.DSH_SNAPSHOT === 'record' + ? 'record' + : process.env.DSH_SNAPSHOT === 'refresh' + ? 'refresh' + : 'replay', }) ``` A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode scenarios are the template. -The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config RFC](../../../docs/rfc/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. Fixture roles, record/replay semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). +The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config RFC](../../../docs/rfc/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout plus comparable session-log goldens from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). -Constraints: `suite.ts` imports vitest, so the package is importable only inside a vitest run (the harness and normalizers have no such dependency but ship from the same entry). ACP-specific by design — the harness speaks the SDK's `ClientSideConnection`. Permission round-trips are scriptable: `InputScript.permissionAnswers` is a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) the client maps to the agent-issued `optionId` at answer time; an absent or exhausted queue answers `cancelled`, and a kind the request never offered rejects the run (the agent is answered `cancelled`, so a tolerant agent cannot absorb the scenario bug). +Constraints: `suite.ts` imports vitest, so the package is importable only inside a vitest run (the harness and normalizers have no such dependency but ship from the same entry). ACP-specific by design — the harness speaks the SDK's `ClientSideConnection`. Permission round-trips are scriptable: `InputScript.permissionAnswers` is a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) the client maps to the agent-issued `optionId` at answer time; an absent or exhausted queue answers `cancelled`, and a kind the request never offered rejects the run (the agent is answered `cancelled`, so a tolerant agent cannot absorb the scenario bug). Session config options are scriptable too: the `setConfigOption` step switches a knob over `session/set_config_option`, and `setConfigOptionExpectError` asserts the bridge rejects an unknown id or out-of-vocabulary value (the error frame stays in the transcript). diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts index c0f5788fca..491d3ea884 100644 --- a/packages/support/acp-snapshot/src/harness.ts +++ b/packages/support/acp-snapshot/src/harness.ts @@ -85,6 +85,8 @@ export type InputStep = | { op: 'promptExpectError'; text: string } | { op: 'promptAndCancel'; text: string } | { op: 'cancel' } + | { op: 'setConfigOption'; configId: string; value: string } + | { op: 'setConfigOptionExpectError'; configId: string; value: string } /** A scenario's `input.json`: an ordered list of input steps. */ export interface InputScript { @@ -210,6 +212,8 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise DSH_SNAPSHOT: opts.mode, DSH_SNAPSHOT_FILE: opts.fixtureFile, DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot, + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {}, ...opts.childFiles !== undefined && opts.childFiles.length > 0 ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) } @@ -406,6 +410,24 @@ async function runStep( await client.cancel({ sessionId }) return } + case 'setConfigOption': { + const sessionId = getSessionId() + if (sessionId === undefined) throw new Error('snapshot-harness: setConfigOption before newSession') + await client.setSessionConfigOption({ sessionId, configId: step.configId, value: step.value }) + return + } + case 'setConfigOptionExpectError': { + const sessionId = getSessionId() + if (sessionId === undefined) throw new Error('snapshot-harness: setConfigOptionExpectError before newSession') + // The bridge rejects an unknown id / out-of-vocabulary value; the SDK + // surfaces that as a rejected RPC — swallow it so the run completes and + // the error frame is captured in the transcript. + await client.setSessionConfigOption({ sessionId, configId: step.configId, value: step.value }).then( + () => { throw new Error('snapshot-harness: expected set_config_option to be rejected but it succeeded') }, + () => { /* expected: the bridge rejected the id or value */ }, + ) + return + } default: throw new Error(`snapshot-harness: unknown input op ${JSON.stringify(step)}`) } diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts index 53e05d7876..6e0058ebce 100644 --- a/packages/support/acp-snapshot/src/suite.ts +++ b/packages/support/acp-snapshot/src/suite.ts @@ -23,8 +23,11 @@ * * `pnpm run test:snapshot:record` (DSH_SNAPSHOT=record + -u) re-records the * `session.jsonl` fixtures against the real API and refreshes the stdout golden - * in one pass; the caller resolves that env into {@link SnapshotSuiteOptions} - * (env reading stays at the suite edge, not in this library). + * in one pass. `pnpm run test:snapshot:refresh` (DSH_SNAPSHOT=refresh) instead + * replays the committed model scripts keylessly and writes the current stdout + * + persisted-log goldens back without calling a live LLM. The caller resolves + * that env into {@link SnapshotSuiteOptions} (env reading stays at the suite + * edge, not in this library). * * @module @deepseek-ai/dsh-acp-snapshot/suite */ @@ -95,6 +98,15 @@ export interface Scenario { * Defaults to false. */ pinsHeader?: boolean + /** + * How many `request/header-delta` events this PINNING scenario's fixture + * legitimately carries (default 0). A recorded mid-run header change — a + * config-option switch rewriting a prompt section — is part of the pinned + * surface, committed verbatim like the header itself; any OTHER count + * still fails, so fixture rot stays caught. Meaningless off the pin (the + * live uniformity guard keeps non-pinning scenarios delta-free). + */ + expectedHeaderDeltas?: number /** * Which header-composition class this scenario belongs to. Scenarios that * boot the same config compose the same header; each class has exactly one @@ -124,12 +136,13 @@ export interface SnapshotSuiteOptions { /** The scenario table; exactly one entry must set `pinsHeader`. */ scenarios: Scenario[] /** - * `replay` (keyless, the default tier) or `record` (live API; re-records the - * `recorded` scenarios' fixtures and refreshes the vitest goldens under - * `--update`). The caller derives this from `$DSH_SNAPSHOT` — env reading - * stays outside this library. + * `replay` (keyless, the default tier), `record` (live API; re-records the + * `recorded` scenarios' fixtures and refreshes the Vitest goldens under + * `--update`), or `refresh` (keyless replay that rewrites stdout goldens and + * comparable session fixtures from the replay run). The caller derives this + * from `$DSH_SNAPSHOT` — env reading stays outside this library. */ - mode: 'replay' | 'record' + mode: 'replay' | 'record' | 'refresh' } /** @@ -201,6 +214,86 @@ export function headerDeltaCount(rawLog: string): number { .length } +/** A literal string replacement used to carry an existing fixture's volatile value into a refreshed log. */ +export interface FixtureReplacement { + /** The fresh replay-run value to replace. */ + from: string + /** The existing fixture value to keep. */ + to: string +} + +function parseJsonlRecords(text: string): Record[] { + return text.split('\n') + .filter(line => line.trim().length > 0) + .map(line => JSON.parse(line) as Record) +} + +/** + * Build the cross-log id/cwd replacements used by refresh write-back. + * + * @param logs The freshly harvested logs, in fixture order. + * @param fixtures The existing fixture contents, in matching order. + * @returns Literal replacements from fresh volatile values to the fixture's old values. + */ +export function refreshFixtureReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[] { + const replacements: FixtureReplacement[] = [] + for (let i = 0; i < logs.length; i++) { + const fresh = parseJsonlRecords((logs[i] as HarvestedLog).content)[0] + const existing = parseJsonlRecords(fixtures[i] ?? '')[0] + for (const field of ['id', 'cwd'] as const) { + const from = fresh?.[field] + const to = existing?.[field] + if (typeof from === 'string' && typeof to === 'string' && from.length > 0 && from !== to) { + replacements.push({ from, to }) + } + } + } + return replacements +} + +function preserveFixtureVolatiles(record: Record, existing: Record | undefined): void { + if (existing === undefined || existing.type !== record.type) return + if (record.type === 'session') { + for (const field of ['id', 'createdAt', 'cwd', 'parentSession'] as const) { + if (field in record && field in existing) record[field] = existing[field] + } + return + } + if ('time' in record && 'time' in existing) record.time = existing.time + if (record.type !== 'hook/result') return + const data = record.data + const existingData = existing.data + if ( + data !== null && typeof data === 'object' + && existingData !== null && typeof existingData === 'object' + && 'durationMs' in data && 'durationMs' in existingData + ) { + (data as Record).durationMs = (existingData as Record).durationMs + } +} + +/** + * Rewrite a fresh replay-produced log so repeated refreshes do not churn + * volatile fixture fields. Meaningful event payloads come from `fresh`; the + * existing fixture lends session ids, cwd, creation times, event times, and + * hook durations where the record shape still matches. + * + * @param fresh The newly harvested session JSONL. + * @param existing The committed fixture JSONL being refreshed. + * @param replacements Cross-log literal replacements from {@link refreshFixtureReplacements}. + * @returns The stabilized JSONL content to write back. + */ +export function stabilizeRefreshLog(fresh: string, existing: string, replacements: FixtureReplacement[]): string { + let stable = fresh + for (const { from, to } of replacements) stable = stable.split(from).join(to) + const existingRecords = parseJsonlRecords(existing) + const records = parseJsonlRecords(stable) + for (let i = 0; i < records.length; i++) { + preserveFixtureVolatiles(records[i] as Record, existingRecords[i]) + } + return records.map(record => JSON.stringify(record)).join('\n') + '\n' +} + /** * Register the suite: one `describe` per scenario (the golden/log compares and * the header-uniformity guard) plus the fixture guard block (no orphan @@ -215,6 +308,8 @@ export function headerDeltaCount(rawLog: string): number { export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { const { agent, snapshotsDir, scenarios, mode } = options const RECORDING = mode === 'record' + const REFRESHING = mode === 'refresh' + const childMode: 'replay' | 'record' = RECORDING ? 'record' : 'replay' /** The class a scenario's header composition belongs to (see {@link Scenario.headerClass}). */ const classOf = (scenario: Scenario): string => scenario.headerClass ?? 'default' @@ -238,15 +333,18 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { describe(`snapshot: ${scenario.name}`, () => { // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the // `authored` ones (sidecar-driven errors/cancel) are never re-recorded. + // REFRESH mode is replay-backed and deterministic, so it runs every + // scenario and rewrites the comparable fixtures from that replay run. it.skipIf(RECORDING && !scenario.recorded)('matches the goldens', async () => { const dir = join(snapshotsDir, scenario.name) const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript const overrideFile = join(dir, 'replay.override.json') const workspaceDir = join(dir, 'workspace') const childSessions = scenario.childSessions ?? 0 + const comparesLog = scenario.comparesLog ?? scenario.hasModelTurn const result = await runScenario(input, { agent, - mode, + mode: childMode, fixtureFile: join(dir, 'session.jsonl'), ...existsSync(overrideFile) ? { overrideFile } : {}, // In REPLAY, forward the recorded child fixtures so each subagent session @@ -271,30 +369,47 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { } // RECORD mode (recorded model scenarios only): persist the freshly-harvested - // logs back to their fixtures — the primary to session.jsonl, each child to - // session..jsonl in harvest order. `--update` refreshes the Vitest - // goldens but NOT these fixtures, so write them here. A non-pinning - // scenario's fixtures are written header-scrubbed, so a re-record can - // never smuggle the full prompt/schema content back into every fixture. + // live logs back to their fixtures. REFRESH mode does the same from a + // keyless replay run for every comparable log, including authored + // scenarios that live record deliberately skips. The primary goes to + // session.jsonl, each child to session..jsonl in harvest order. A + // non-pinning scenario's fixtures are written header-scrubbed, so a + // re-record/refresh can never smuggle the full prompt/schema content + // back into every fixture. const scrub = scenario.pinsHeader === true ? (log: string): string => log : scrubRequestHeaders - if (RECORDING && scenario.recorded && scenario.hasModelTurn) { - expect(result.sessionLogs.length, 'record produced no session log to harvest').toBeGreaterThan(0) + const fixtureFiles = ['session.jsonl', ...Array.from({ length: childSessions }, (_, i) => `session.${i + 1}.jsonl`)] + const existingFixtures = REFRESHING + ? await Promise.all(fixtureFiles.map(file => readFile(join(dir, file), 'utf8'))) + : [] + const replacements = REFRESHING ? refreshFixtureReplacements(result.sessionLogs, existingFixtures) : [] + const writesSessionFixtures = (RECORDING && scenario.recorded && scenario.hasModelTurn) + || (REFRESHING && comparesLog) + if (writesSessionFixtures) { + expect(result.sessionLogs.length, `${mode} produced no session log to harvest`).toBeGreaterThan(0) expect(result.sessionLogs.length, `expected ${childSessions + 1} session logs (parent + children)`) .toBe(childSessions + 1) - await writeFile(join(dir, 'session.jsonl'), scrub((result.sessionLogs[0] as HarvestedLog).content)) + const primary = (result.sessionLogs[0] as HarvestedLog).content + await writeFile(join(dir, 'session.jsonl'), scrub( + REFRESHING ? stabilizeRefreshLog(primary, existingFixtures[0] as string, replacements) : primary, + )) for (let i = 1; i < result.sessionLogs.length; i++) { - await writeFile(join(dir, `session.${i}.jsonl`), scrub((result.sessionLogs[i] as HarvestedLog).content)) + const child = (result.sessionLogs[i] as HarvestedLog).content + await writeFile(join(dir, `session.${i}.jsonl`), scrub( + REFRESHING ? stabilizeRefreshLog(child, existingFixtures[i] as string, replacements) : child, + )) } } - await expect(normalizeStdout(result.rawStdout, ctx)) - .toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl')) + const stdout = normalizeStdout(result.rawStdout, ctx) + if (REFRESHING) { + await writeFile(join(dir, 'stdout.golden.jsonl'), stdout) + } + await expect(stdout).toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl')) // A model turn always produces a log worth comparing; a hook scenario can // produce one without a model turn (a `rejected` turn carrying `hook/*`). - const comparesLog = scenario.comparesLog ?? scenario.hasModelTurn if (comparesLog) { // The harvested logs (primary-first) must match their committed fixtures // 1:1. Each side passes through normalizeSessionLog, scrubbed against ITS @@ -307,7 +422,6 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { // reason, and config, but not its bulk content (pinned once, in the // `pinsHeader` scenario). expect(result.sessionLogs.length, 'this scenario must persist a session log').toBe(childSessions + 1) - const fixtureFiles = ['session.jsonl', ...Array.from({ length: childSessions }, (_, i) => `session.${i + 1}.jsonl`)] for (let i = 0; i < fixtureFiles.length; i++) { const harvested = scrub((result.sessionLogs[i] as HarvestedLog).content) const fixture = scrub(await readFile(join(dir, fixtureFiles[i] as string), 'utf8')) @@ -406,17 +520,19 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { } }) - it('every pinning fixture carries exactly one request/header and no deltas', async () => { + it('every pinning fixture carries exactly one request/header and its declared deltas', async () => { // The live uniformity guard runs only in NON-pinning scenarios, so a // class made of just its pinning scenario would otherwise accept a - // re-recorded pin with several headers or a mid-run header-delta — - // shapes the pin design cannot represent. Assert the committed pins - // directly. + // re-recorded pin with several headers or an undeclared mid-run + // header-delta — shapes the pin design cannot represent. Assert the + // committed pins directly; a scenario whose arc legitimately rewrites + // a prompt section declares the exact count via expectedHeaderDeltas. for (const scenario of pinningByClass.values()) { const fixture = await readFile(join(snapshotsDir, scenario.name, 'session.jsonl'), 'utf8') const headers = normalizedHeaders(fixture, fixtureContext(fixture)) expect(headers.length, `${scenario.name}: a pinning fixture must carry exactly one request/header`).toBe(1) - expect(headerDeltaCount(fixture), `${scenario.name}: a pinning fixture must carry no request/header-delta`).toBe(0) + expect(headerDeltaCount(fixture), `${scenario.name}: a pinning fixture must carry exactly its declared request/header-deltas`) + .toBe(scenario.expectedHeaderDeltas ?? 0) } }) diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts index cf41412046..861c9d2b04 100644 --- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts +++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts @@ -58,6 +58,13 @@ interface Behavior { strayBucketFile?: boolean /** Delete the sessions root entirely (harvest must yield no logs). */ deleteSessionsRoot?: boolean + /** + * Vocabulary for `session/set_config_option`: allowed values per config id. + * A set naming an unknown id or an out-of-vocabulary value rejects (the + * real bridge's rule); a valid set answers with the complete refreshed + * option state, `currentValue` updated. Absent: every set rejects. + */ + configOptions?: Record } const sessionsRoot = process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? '' @@ -81,6 +88,8 @@ let sessionCwd = '' let parkedPromptId: number | string | null = null /** Resolvers for permission-probe responses, keyed by outbound request id. */ const pendingPermission = new Map void>() +/** Per-run `session/set_config_option` state: config id → current value (first vocabulary entry until set). */ +const currentConfig: Record = {} function send(frame: Record): void { process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...frame })}\n`) @@ -195,6 +204,32 @@ function handleFrame(frame: Record): void { case 'session/prompt': void handlePrompt(id as number | string) return + case 'session/set_config_option': { + const vocabulary = behavior.configOptions + const configId = params.configId as string + const value = params.value as string + const values = vocabulary?.[configId] + if (values === undefined) { + respondError(id as number | string, `unknown config option ${configId}`) + return + } + if (!values.includes(value)) { + respondError(id as number | string, `unknown ${configId} value ${value}`) + return + } + currentConfig[configId] = value + // The real bridge's contract: every set answers with the COMPLETE + // refreshed option state, not just the changed entry. + respond(id as number | string, { + configOptions: Object.entries(vocabulary as Record).map(([cid, vs]) => ({ + id: cid, + type: 'select', + currentValue: currentConfig[cid] ?? vs[0], + options: vs.map(v => ({ value: v, name: v })), + })), + }) + return + } case 'session/cancel': if (parkedPromptId !== null) { const parked = parkedPromptId diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 683d2aaf80..b0817a8d04 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -168,6 +168,8 @@ describe('runScenario', () => { [{ op: 'promptExpectError', text: 'x' }, /promptExpectError before newSession/], [{ op: 'promptAndCancel', text: 'x' }, /promptAndCancel before newSession/], [{ op: 'cancel' }, /cancel before newSession/], + [{ op: 'setConfigOption', configId: 'sandbox-mode', value: 'read-only' }, /setConfigOption before newSession/], + [{ op: 'setConfigOptionExpectError', configId: 'sandbox-mode', value: 'yolo' }, /setConfigOptionExpectError before newSession/], ] as [InputStep, RegExp][])('rejects %j before newSession', { timeout: 20_000 }, async (step, message) => { const { fixtureFile } = await scenario({}) await expect(runScenario( @@ -176,6 +178,53 @@ describe('runScenario', () => { )).rejects.toThrow(message) }) + it('setConfigOption switches a value and receives the complete refreshed option state', { timeout: 20_000 }, async () => { + const { fixtureFile } = await scenario({ + configOptions: { 'sandbox-mode': ['read-only', 'workspace-write'], 'approval-policy': ['ask', 'never'] }, + }) + const result = await runScenario( + { + steps: [...boot, + { op: 'setConfigOption', configId: 'sandbox-mode', value: 'workspace-write' }, + { op: 'setConfigOption', configId: 'approval-policy', value: 'never' }], + }, + { agent: AGENT, mode: 'replay', fixtureFile }, + ) + // Every set answers with the FULL state: the second response carries the + // first switch's value too — the complete-refreshed-state contract. + const frames = result.rawStdout.trim().split('\n').map(line => JSON.parse(line) as { result?: { configOptions?: { id: string; currentValue: string }[] } }) + const states = frames + .map(f => f.result?.configOptions) + .filter(options => options !== undefined) + .map(options => Object.fromEntries((options as { id: string; currentValue: string }[]).map(o => [o.id, o.currentValue]))) + expect(states).toEqual([ + { 'sandbox-mode': 'workspace-write', 'approval-policy': 'ask' }, + { 'sandbox-mode': 'workspace-write', 'approval-policy': 'never' }, + ]) + }) + + it('setConfigOptionExpectError swallows the rejection for unknown ids and out-of-vocabulary values', { timeout: 20_000 }, async () => { + const { fixtureFile } = await scenario({ configOptions: { 'sandbox-mode': ['read-only'] } }) + const result = await runScenario( + { + steps: [...boot, + { op: 'setConfigOptionExpectError', configId: 'sandbox-mode', value: 'yolo' }, + { op: 'setConfigOptionExpectError', configId: 'reasoning-effort', value: 'max' }], + }, + { agent: AGENT, mode: 'replay', fixtureFile }, + ) + expect(result.rawStdout).toContain('unknown sandbox-mode value yolo') + expect(result.rawStdout).toContain('unknown config option reasoning-effort') + }) + + it('setConfigOptionExpectError throws when the set unexpectedly succeeds', { timeout: 20_000 }, async () => { + const { fixtureFile } = await scenario({ configOptions: { 'sandbox-mode': ['read-only'] } }) + await expect(runScenario( + { steps: [...boot, { op: 'setConfigOptionExpectError', configId: 'sandbox-mode', value: 'read-only' }] }, + { agent: AGENT, mode: 'replay', fixtureFile }, + )).rejects.toThrow(/expected set_config_option to be rejected/) + }) + it('rejects an unknown input op', { timeout: 20_000 }, async () => { const { fixtureFile } = await scenario({}) const bogus = { op: 'reticulate' } as unknown as InputStep diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index 0f47010a19..ae01190c01 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -1,11 +1,18 @@ -import { cpSync, mkdtempSync } from 'node:fs' +import { cpSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs' import { rm } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { afterAll, describe, expect, it } from 'vitest' -import { defineAcpSnapshotSuite, type Scenario } from '../src/index.ts' -import { childFixturePaths, fixtureContext, headerDeltaCount, normalizedHeaders } from '../src/suite.ts' +import { defineAcpSnapshotSuite, type HarvestedLog, type Scenario } from '../src/index.ts' +import { + childFixturePaths, + fixtureContext, + headerDeltaCount, + normalizedHeaders, + refreshFixtureReplacements, + stabilizeRefreshLog, +} from '../src/suite.ts' /** * Unit tests for the suite factory, by running it: two synthetic suites over @@ -55,16 +62,40 @@ const RECORD_SCENARIOS: Scenario[] = [ { name: 'rec-skip', hasModelTurn: true, recorded: false, overridden: true }, ] -// Record mode mutates its snapshots dir, so run it on a throwaway copy — -// except under the documented bootstrap knob, which regenerates the committed -// fixtures/goldens in place. +// Record/refresh modes mutate their snapshots dir, so run them on throwaway +// copies — except record's documented bootstrap knob, which regenerates the +// committed record fixtures/goldens in place. const BOOTSTRAP = process.env.ACP_SNAPSHOT_SPEC_BOOTSTRAP === '1' const recordDir = BOOTSTRAP ? RECORD_SRC : mkdtempSync(join(tmpdir(), 'acp-snap-record-suite-')) if (!BOOTSTRAP) cpSync(RECORD_SRC, recordDir, { recursive: true }) +const refreshDir = mkdtempSync(join(tmpdir(), 'acp-snap-refresh-suite-')) +cpSync(REPLAY_DIR, refreshDir, { recursive: true }) +staleRefreshFixtures(refreshDir) afterAll(async () => { if (!BOOTSTRAP) await rm(recordDir, { recursive: true, force: true }) + await rm(refreshDir, { recursive: true, force: true }) }) +function staleRefreshFixtures(dir: string): void { + writeFileSync(join(dir, 'plain-turn', 'stdout.golden.jsonl'), 'stale stdout\n') + + const plainBehaviorFile = join(dir, 'plain-turn', 'behavior.json') + const plainBehavior = JSON.parse(readFileSync(plainBehaviorFile, 'utf8')) as Record + plainBehavior.echoEnv = true + writeFileSync(plainBehaviorFile, `${JSON.stringify(plainBehavior, null, 2)}\n`) + + writeFileSync(join(dir, 'blocked-log', 'session.jsonl'), [ + '{"type":"session","id":"99999999-8888-4777-8666-555555555555","createdAt":13,"cwd":"/rec/blocked-cwd"}', + '{"type":"hook/result","seq":1,"time":13,"data":{"decision":"stale","durationMs":99}}', + '', + ].join('\n')) + writeFileSync(join(dir, 'authored-error', 'session.jsonl'), [ + '{"type":"session","id":"77777777-8888-4777-8666-555555555555","createdAt":13,"cwd":"/rec/error-cwd"}', + '{"type":"turn/end","seq":1,"time":9,"data":{"error":"stale"}}', + '', + ].join('\n')) +} + describe('defineAcpSnapshotSuite: replay mode', () => { defineAcpSnapshotSuite({ agent: AGENT, snapshotsDir: REPLAY_DIR, scenarios: REPLAY_SCENARIOS, mode: 'replay' }) }) @@ -75,6 +106,27 @@ describe('defineAcpSnapshotSuite: record mode', () => { defineAcpSnapshotSuite({ agent: AGENT, snapshotsDir: recordDir, scenarios: RECORD_SCENARIOS, mode: 'record' }) }) +describe('defineAcpSnapshotSuite: refresh mode', () => { + defineAcpSnapshotSuite({ agent: AGENT, snapshotsDir: refreshDir, scenarios: REPLAY_SCENARIOS, mode: 'refresh' }) +}) + +describe('defineAcpSnapshotSuite: refresh write-back', () => { + it('rewrites stdout and comparable logs from a replay-mode child run', () => { + const stdout = readFileSync(join(refreshDir, 'plain-turn', 'stdout.golden.jsonl'), 'utf8') + expect(stdout).not.toContain('stale stdout') + expect(stdout).toContain('env:{\\"mode\\":\\"replay\\"') + expect(stdout).not.toContain('\\"mode\\":\\"refresh\\"') + + const blocked = readFileSync(join(refreshDir, 'blocked-log', 'session.jsonl'), 'utf8') + expect(blocked).toContain('"decision":"block"') + expect(blocked).not.toContain('"decision":"stale"') + + const authored = readFileSync(join(refreshDir, 'authored-error', 'session.jsonl'), 'utf8') + expect(authored).toContain('"error":"model exploded"') + expect(authored).not.toContain('"error":"stale"') + }) +}) + describe('defineAcpSnapshotSuite: registration contract', () => { it("throws when a scenario's header class has no pinning scenario", () => { expect(() => { @@ -175,3 +227,56 @@ describe('headerDeltaCount', () => { expect(headerDeltaCount(`${other}\n`)).toBe(0) }) }) + +describe('refreshFixtureReplacements', () => { + it('maps fresh ids and cwd values to the existing fixture values, skipping non-replacements', () => { + const log = (content: string): HarvestedLog => ({ id: 'diagnostic', createdAt: 1, content }) + const logs = [ + log('{"type":"session","id":"","cwd":"/same"}\n'), + log('{"type":"session","id":"new-parent","cwd":"/new"}\n'), + log('{"type":"session","id":"new-child","cwd":"/new"}\n'), + ] + const fixtures = [ + '{"type":"session","id":"","cwd":"/same"}\n', + '{"type":"session","id":"old-parent","cwd":"/old"}\n', + ] + expect(refreshFixtureReplacements(logs, fixtures)).toEqual([ + { from: 'new-parent', to: 'old-parent' }, + { from: '/new', to: '/old' }, + ]) + }) +}) + +describe('stabilizeRefreshLog', () => { + it('keeps volatile fixture fields while preserving fresh meaningful payloads', () => { + const fresh = [ + '{"type":"session","id":"new-child","createdAt":200,"cwd":"/new","parentSession":"new-parent","seedLength":1}', + '{"type":"hook/result","seq":1,"time":22,"data":{"decision":"block","durationMs":37}}', + '{"type":"turn/end","seq":2,"time":33,"data":{"error":"fresh error"}}', + '{"type":"tool/result","seq":3,"time":44,"data":{"text":"new-parent in /new"}}', + '{"type":"hook/result","seq":4,"time":55,"data":{"decision":"allow","durationMs":5}}', + '', + ].join('\n') + const existing = [ + '{"type":"session","id":"old-child","createdAt":100,"cwd":"/old","parentSession":"old-parent","seedLength":5}', + '{"type":"hook/result","seq":1,"time":11,"data":{"decision":"stale","durationMs":99}}', + '{"type":"turn/end","seq":2,"data":{"error":"stale"}}', + '{"type":"assistant/message","seq":3,"time":12,"data":{"text":"different type"}}', + '{"type":"hook/result","seq":4,"time":13,"data":{"decision":"stale"}}', + '', + ].join('\n') + + expect(stabilizeRefreshLog(fresh, existing, [ + { from: 'new-parent', to: 'old-parent' }, + { from: 'new-child', to: 'old-child' }, + { from: '/new', to: '/old' }, + ])).toBe([ + '{"type":"session","id":"old-child","createdAt":100,"cwd":"/old","parentSession":"old-parent","seedLength":1}', + '{"type":"hook/result","seq":1,"time":11,"data":{"decision":"block","durationMs":99}}', + '{"type":"turn/end","seq":2,"time":33,"data":{"error":"fresh error"}}', + '{"type":"tool/result","seq":3,"time":44,"data":{"text":"old-parent in /old"}}', + '{"type":"hook/result","seq":4,"time":13,"data":{"decision":"allow","durationMs":5}}', + '', + ].join('\n')) + }) +}) diff --git a/packages/ui/README.md b/packages/ui/README.md index e87a5e4a10..604eff6521 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -5,6 +5,7 @@ Integrations that expose the agent to an external editor or client. These are ** | Package | Role | ctx key | |---|---|---| | `acp/` | Agent Client Protocol bridge: serves the agent to an ACP editor (Zed) over JSON-RPC stdio | (drives `ctx.agents`/`ctx.sessions`) | +| `user-approval/` | One-shot user-approval mechanism, closed outcome vocabulary, audit events, and per-session approval policy | `ctx.approval` | | `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` | | `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) | | `stdio-agent/` | Terminal stdio chat APP: the agent-core spine + console logger + readline UI + a pre-created `main` agent, with a `bin` | (composition + `bin`) | @@ -13,6 +14,6 @@ Integrations that expose the agent to an external editor or client. These are ** A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The readline UI is the unstructured analogue of the `acp` bridge and lives INSIDE the stdio app (the `stdio-chat` module of [`stdio-agent/`](stdio-agent/README.md)): it is scaffolding for that one front door, not an independently swappable integration, so it carries no package boundary of its own. -`user-interaction` and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. The seam remains provider-neutral (`ctx.userInteraction`), while the tool is the model-facing consumer and the app/bridge packages provide concrete providers. +`user-approval`, `user-interaction`, and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. `user-approval` owns the one-shot `ctx.approval` decision mechanism and its policy tier; answerers remain with their UI channel owners. `user-interaction` remains provider-neutral (`ctx.userInteraction`), while `tool-ask-user` is its model-facing consumer and the app/bridge packages provide concrete providers. `stdio-agent` and `acp-agent` are the two **app packages**: each composes the [`core/agent-core`](../core/agent-core/README.md) spine with its coupled front-door cluster (and owns the boot `bin`), so a leaf `cordis.yml` is the swappable backends plus one app entry plus any optional product tools. They live in `ui/` because each IS a user-facing front door; the stdout-purity coupling (logger vs. no logger) becomes a property of the artifact rather than a leaf convention. diff --git a/packages/ui/acp-agent/README.md b/packages/ui/acp-agent/README.md index ee3a995eaa..d81c9cc091 100644 --- a/packages/ui/acp-agent/README.md +++ b/packages/ui/acp-agent/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-acp-agent -The **ACP server app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster an [Agent Client Protocol](../acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio. +The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster an [Agent Client Protocol](../acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio. It is the structured counterpart to [`@deepseek-ai/dsh-stdio-agent`](../stdio-agent/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster. diff --git a/packages/ui/acp-agent/src/index.ts b/packages/ui/acp-agent/src/index.ts index 4a0242e8c7..27b919f756 100644 --- a/packages/ui/acp-agent/src/index.ts +++ b/packages/ui/acp-agent/src/index.ts @@ -1,5 +1,5 @@ /** - * The ACP server app: the providerless agent spine ({@link + * The ACP server app: the default agent spine ({@link * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster an ACP * server needs — JSONL session persistence and the {@link @deepseek-ai/dsh-acp} * bridge, and DELIBERATELY NOTHING that writes to stdout. @@ -60,6 +60,8 @@ export interface Config { tools?: ToolsConfig /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string + /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */ + skills?: agentCore.SkillConfig } export const Config: z = z.object({ @@ -71,6 +73,7 @@ export const Config: z = z.object({ toolOrder: z.array(z.string()).default(undefined as unknown as string[]), tools: ToolRegistry.Config, persistenceRoot: z.string().default('./.sessions'), + skills: agentCore.SkillConfigSchema, }) /** @@ -85,6 +88,7 @@ export function apply(ctx: Context, config: Config): void { ...config.persona !== undefined ? { persona: config.persona } : {}, ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {}, ...config.tools !== undefined ? { tools: config.tools } : {}, + ...config.skills !== undefined ? { skills: config.skills } : {}, }) ctx.plugin(UserInteractionService) ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' }) diff --git a/packages/ui/acp-agent/tests/acp-agent.spec.ts b/packages/ui/acp-agent/tests/acp-agent.spec.ts index 6e2f202859..47cc399dfc 100644 --- a/packages/ui/acp-agent/tests/acp-agent.spec.ts +++ b/packages/ui/acp-agent/tests/acp-agent.spec.ts @@ -1,7 +1,11 @@ import { describe, expect, it } from 'vitest' +import { mkdtemp } from 'node:fs/promises' +import { join } from 'node:path' +import { tmpdir } from 'node:os' import { Context } from 'cordis' import Loader from '@cordisjs/plugin-loader' import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt' +import type { Message } from '@deepseek-ai/dsh-llm' import * as acpAgent from '../src/index.ts' /** @@ -23,9 +27,47 @@ async function mount(config: acpAgent.Config): Promise { return ctx } +async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise> { + const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-skills-')) + return { + local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }, + ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {}, + } +} + +async function composePrefix(ctx: Context): Promise { + const empty: Message[] = [] + return await ctx.waterfall( + 'agent/session-prefix', { session: { header: { cwd: '/tmp' } } } as never, + empty, new AbortController().signal, () => Promise.resolve(empty), + ) +} + +async function withIsolatedSkillHomes(run: () => Promise): Promise { + const oldDshHome = process.env.DSH_HOME + const oldAgentsHome = process.env.DSH_AGENTS_HOME + const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-default-skills-')) + process.env.DSH_HOME = join(home, '.dsh') + process.env.DSH_AGENTS_HOME = join(home, '.agents') + try { + return await run() + } finally { + if (oldDshHome === undefined) { + delete process.env.DSH_HOME + } else { + process.env.DSH_HOME = oldDshHome + } + if (oldAgentsHome === undefined) { + delete process.env.DSH_AGENTS_HOME + } else { + process.env.DSH_AGENTS_HOME = oldAgentsHome + } + } +} + describe('dsh-acp-agent composition', () => { it('brings up the spine + persistence + the ACP bridge', async () => { - const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test' }) + const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test', skills: await isolatedSkillsConfig() }) expect(ctx.get('agents')).toBeDefined() expect(ctx.get('sessions')).toBeDefined() expect(ctx.get('sessionPersistence')).toBeDefined() @@ -44,12 +86,30 @@ describe('dsh-acp-agent composition', () => { // persistenceRoot, so the runtime fallback is the one that fires. const ctx = new Context() // No persona: covers the omitted-persona forwarding branch too. - acpAgent.apply(ctx, { model: 'mock' }) + acpAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() }) await new Promise(resolve => setTimeout(resolve, 50)) expect(ctx.get('sessionPersistence')).toBeDefined() await ctx.fiber.dispose() }) + it('uses default skill config when apply is called directly without skills', async () => { + await withIsolatedSkillHomes(async () => { + const ctx = new Context() + acpAgent.apply(ctx, { model: 'mock' }) + await new Promise(resolve => setTimeout(resolve, 50)) + expect(ctx.skills).toBeDefined() + expect(await ctx.skills.list()).toEqual([]) + await ctx.fiber.dispose() + }) + }) + + it('forwards skill config into agent-core', async () => { + const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) }) + ctx.skills.register({ name: 'acp-skill', description: 'ACP skill', source: 'runtime', content: 'body' }) + expect(JSON.stringify(await composePrefix(ctx))).toContain('- `acp-skill`: ACP...') + await ctx.fiber.dispose() + }) + it('exposes its plugin shape', () => { expect(acpAgent.name).toBe('acp-agent') expect(acpAgent.Config).toBeDefined() @@ -72,7 +132,7 @@ describe('dsh-acp-agent composition', () => { }) } const assembly = await ctx.get('systemPrompt')!.assemble() - expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha']) + expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill']) await ctx.fiber.dispose() }) diff --git a/packages/ui/acp-agent/tests/built-bin.e2e.ts b/packages/ui/acp-agent/tests/built-bin.e2e.ts index d900c14152..de4612a40a 100644 --- a/packages/ui/acp-agent/tests/built-bin.e2e.ts +++ b/packages/ui/acp-agent/tests/built-bin.e2e.ts @@ -99,7 +99,7 @@ async function makeConsumer(): Promise { ' name: \'@deepseek-ai/dsh-acp-agent\'', ' config:', ' model: deepseek-v4-flash', - ' systemPrompt: \'test agent\'', + ' persona: \'test agent\'', '', ].join('\n')) return dir @@ -120,7 +120,12 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-agent BUILT bin (node lib/bin.js, child = spawn(process.execPath, ['--expose-internals', acpBin, './cordis.yml'], { cwd: consumer, // Dummy key: initialize never reaches the model, so it is never used. - env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot' }, + env: { + ...process.env, + DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', + DSH_HOME: join(consumer, '.dsh'), + DSH_AGENTS_HOME: join(consumer, '.agents'), + }, stdio: ['pipe', 'pipe', 'pipe'], }) const stderr: string[] = [] @@ -180,7 +185,12 @@ function runBinExpectingExit(configArg: string, cwd: string = tmpdir()): Promise return new Promise((resolve, reject) => { const proc = spawn(process.execPath, ['--expose-internals', acpBin, configArg], { cwd, - env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot' }, + env: { + ...process.env, + DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), + }, stdio: ['pipe', 'pipe', 'pipe'], }) child = proc diff --git a/packages/ui/acp-agent/tests/load-path.e2e.ts b/packages/ui/acp-agent/tests/load-path.e2e.ts index fd559d99bf..ec251a6e6b 100644 --- a/packages/ui/acp-agent/tests/load-path.e2e.ts +++ b/packages/ui/acp-agent/tests/load-path.e2e.ts @@ -54,7 +54,7 @@ const CORDIS_YML = ` name: '@deepseek-ai/dsh-acp-agent' config: model: deepseek-v4-flash - systemPrompt: 'You are a test agent.' + persona: 'You are a test agent.' ` interface Spawned { @@ -90,6 +90,8 @@ async function boot(): Promise { TSX_TSCONFIG_PATH: repoTsconfig, // Key-present check only; no prompt is sent, so the model is never called. DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'keyless-acp-agent-smoke', + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), }, stdio: ['pipe', 'pipe', 'pipe'], }, diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md index 49abfbff6a..2f1f35adc4 100644 --- a/packages/ui/acp/README.md +++ b/packages/ui/acp/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-acp -The **Agent Client Protocol (ACP)** bridge: exposes DeepSeek Harness SDK agents as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive them — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave. +The **Agent Client Protocol (ACP)** bridge: exposes DeepSeek Harness SDK agents as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive them — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave. It is a **client-driver / UI plugin**, the structured analogue of the readline `stdio-chat` plugin — NOT a loop change and NOT a [capability seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`. @@ -31,10 +31,16 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name: | `session/cancel` | `agent.cancel()` | the queue-aware cancel: aborts a running step, clears queued + steering work, and drops a turn about to start, then settles the prompt `cancelled` — for ONLY that session (a cancel never touches another session's stream or prompt) | | `session/update` | `session/event` | `agent_message_chunk` (text-delta), `agent_thought_chunk` (reasoning-delta), `user_message_chunk` (load replay), `tool_call`/`tool_call_update` (the render intent — a `card`-tagged `ToolCallView`/`ToolResultView` — owned by the TOOL via `presentCall`/`presentResult`, which the bridge switches on to build the wire shape — see Tool-call presentation) | | `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` questions to ACP form elicitations; option descriptions are shown in enum titles, `multi_select` uses ACP array enums, optionless requests use a required `custom` field, and a non-empty custom answer overrides any selected choice | +| `session/request_permission` | `approval/request` listener | the bridge is the [`ctx.approval`](../user-approval/README.md) answerer for the agents it owns: an `ask` (a hook or `tools/pre-execute` plugin) becomes an editor prompt attached to the streamed tool call, offering one-shot `allow_once`/`reject_once` options only; a foreign or call-less request delegates down the answerer chain (fail-closed `unavailable` default). See "Permission prompts" | +| `session/set_config_option` | `setSandboxMode` / `setApprovalPolicy` | per-session knob switching over [session config options](https://agentclientprotocol.com/protocol/session-config-options) — see "Session config options" | ## Multi-session -The bridge multiplexes N sessions over one connection. Live sessions are held in a `Map` (forward) with a `WeakMap` reverse map so `agent/*` events — which carry only the `Agent` — demux in O(1). Every `session/event` and `agent/status` is routed strictly to its owning record, so concurrent sessions never cross-settle or interleave their `session/update` notifications. State is per session: one in-flight prompt each, `session/cancel` aborts and settles only its own agent/prompt, and disposal drains every live session in parallel to quiescence. (Per-session *permission* ownership is reserved for the deferred permission gate — `TODO(rfc010-permission-gate)`.) +The bridge multiplexes N sessions over one connection. Live sessions are held in a `Map` (forward) with a `WeakMap` reverse map so `agent/*` events — which carry only the `Agent` — demux in O(1). Every `session/event` and `agent/status` is routed strictly to its owning record, so concurrent sessions never cross-settle or interleave their `session/update` notifications. State is per session: one in-flight prompt each, `session/cancel` aborts and settles only its own agent/prompt, and disposal drains every live session in parallel to quiescence. Permission prompts follow the same ownership: the `approval/request` answerer resolves the owning session through the reverse map and prompts only there. + +## Session config options + +The bridge advertises one independent `select` per composable knob in the `session/new`/`session/load` responses — `sandbox-mode` (`read-only`/`workspace-write`/`danger-full-access`, category `mode`) iff the mounted executor confines (`ctx.get('bash')?.sandboxMode` defined), `approval-policy` (`ask`/`never`) iff the approval seam is composed — with each session's `currentValue` folded from its OWN log (`effectiveSandboxMode`/`effectiveApprovalPolicy` ?? the composition default), so `session/load` reports a resumed session's overrides with no catch-up machinery. `session/set_config_option` validates the value against the same closed vocabulary, routes to the domain's write path (`setSandboxMode`/`setApprovalPolicy` — ONE log-only event on that session's log), and returns the complete refreshed state per the spec. Anchoring honors turn-enclosure: a switch while a turn is open appends immediately (openness read from the LOG — `agent.status` stays `running` between queued turns); an idle switch is held on the session record and anchored at the next turn's `agent/prompt-submit` (inside the turn, before anything assembles, last write per knob — an idle flip-flop anchors as one event), because appending from inside a `session/event` listener would reorder events for later-registered peers. Until anchored the switch lives in bridge memory only: responses overlay it truthfully, and a crash before the next turn reverts it — `session/load` then reports the fold's truth. Design: [the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md); protocol matrix: [acp-feature-support.md](acp-feature-support.md) § 6. Background-task isolation rides on `dsh-tool-bash`: bash task ids are global and predictable, so each task carries an opaque owner token — the owning agent's `session.header.id` — stored on the task inside the executor (`dsh-bash`'s `ownerOf(id)` seam). `bash_output`/`bash_kill` reject a task whose token differs from the caller's session token, so one session's agent can't read or kill another's task. Ownership is by session TOKEN, not `Agent` object identity — a different `Agent` object on the same session may access the task — and because the token lives on the executor's task it survives a `tool-bash` HMR reload. @@ -67,18 +73,21 @@ When the client does NOT advertise the capability, none of the `_meta`/terminal A `session/prompt` resolves (or rejects) exactly once, keyed off the canonical session log (the `session/event` stream). One listener captures the prompt's owning turn from the log's `turn/start` and settles on the matching `turn/end` — the durable boundary event (`closeTurn` appends it unconditionally; there is no `agent/*` turn mirror). A prompt settles only on ITS OWN turn (`inflight.turn === turn/end.turn`), so a stale `turn/end` for a previously-cancelled turn whose end arrives late can never settle the wrong prompt. A turn that ends `error` REJECTS the RPC with an internal error carrying the failure message (ACP has no error stop reason); every other reason resolves via the codec. As a fallback, when the agent settles to `idle`/`disposed` with a prompt still pending — e.g. a peer `session/event` listener registered before the bridge threw and starved the bridge's listener — an `agent/status` handler reconciles the prompt from the log (the owning turn's `turn/end`, or `cancelled` if the turn was torn down without one). An empty/whitespace prompt is rejected up front — it would queue no work, so no turn would start and the RPC would hang. +## Permission prompts + +The bridge registers an `approval/request` waterfall listener — the ACP answerer of the [user-approval seam](../user-approval/README.md). When `ctx.approval` routes an `ask` for an agent the bridge owns, the listener resolves the owning session through the reverse map and issues `session/request_permission` with the request's `callId` as the `toolCall` reference (the editor attaches the prompt to the already-streamed call) and the one-shot options `allow_once`/`reject_once` (`allow_always` is deferred to the approval RFC's grant-storage question). Outcomes map `allow-once → allowed-once`, any other selection → `rejected` (an unknown optionId from a non-conforming client never grants), client `cancelled → cancelled`. A request for an agent the bridge does NOT own — or one without a `callId` to attach to — delegates via `next()` so another answerer or the seam's fail-closed `unavailable` default takes it. A rejected `requestPermission` RPC (client gone mid-prompt) propagates to the ApprovalService, which contains it as `unavailable`. Whether a call asks at all is policy — a hook or `tools/pre-execute` plugin returning `ask` — never the bridge's own judgment; without such policy, tools keep the executor's full authority. + ## Disposal & disconnect Teardown reaches quiescence: for EVERY live session settle any pending prompt as `cancelled`, then run that session's [`AgentHandle`](../../core/agent/README.md) `dispose()` — which stops the loop (sets `disposed` + aborts the in-flight step), `await`s the loop's exit (the final `turn/end` + `session/flush` are captured while the session is still attached), unregisters the agent, and removes its session from the store. A turn cut off mid-flight by teardown ends with reason `disposed` (not `aborted` — `dispose()` uses the disposed path, not `session/cancel`'s queue-aware `cancel()`). The per-session disposes run in parallel. The same teardown runs on a **client disconnect** (`conn.closed` resolves when the editor quits / the transport EOFs), so a vanished client never leaves an orphaned running — or idled-but-still-registered — agent whose `session/update` writes are silently swallowed. The two paths are idempotent and memoized (the first clears the `sessions` map; a second caller awaits the same teardown promise). ## Known limitations (tracked TODOs) -- **`TODO(rfc010-permission-gate)`** — the `tools/pre-execute` permission gate (`session/request_permission`) is NOT implemented; tools run with the executor's full authority. The `agent→sessionId` reverse map is in place so the gate can route a permission request (which receives only `exec.agent`) back to its originating session. [ACP support](../../../docs/rfc/proposed/feature/2026-06-14-acp-agent-client-protocol.md) and [ACP multi-session](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md) stay `proposed` until the gate (and per-session permission ownership) land. - **`additionalDirectories`** — rejected. A session operates in its single `cwd` (see Per-session cwd); widening the tool/filesystem scope to extra roots is a separate sandbox concern, not yet implemented. ## stdout is the protocol -The JSON-RPC frames go on stdout, so this plugin MUST run in an example that loads **no stdout logger** (the console logger writes to stdout and would corrupt the frames). The guarantee is config-only — see `examples/acp-agent` (no console logger) and [ACP support risks](../../../docs/rfc/proposed/feature/2026-06-14-acp-agent-client-protocol.md#risks). A stderr exporter is fine for logging. +The JSON-RPC frames go on stdout, so this plugin MUST run in an example that loads **no stdout logger** (the console logger writes to stdout and would corrupt the frames). The guarantee is config-only — see `examples/acp-agent` (no console logger) and [ACP support risks](../../../docs/rfc/implemented/feature/2026-06-14-acp-agent-client-protocol.md#risks). A stderr exporter is fine for logging. ## Running diff --git a/packages/ui/acp/acp-feature-support.md b/packages/ui/acp/acp-feature-support.md index 6162fae137..be14fe6237 100644 --- a/packages/ui/acp/acp-feature-support.md +++ b/packages/ui/acp/acp-feature-support.md @@ -10,7 +10,7 @@ Legend: ✅ supported · ⚠️ partial / fallback · ❌ not yet · — n/a. Th ## At a glance -The bridge implements the **core prompt-turn loop** for N concurrent sessions: initialize, session new/load, prompt, cancel, streamed assistant/thought chunks, tool-call rendering (including Zed terminal cards), and resumable session replay. The largest **unbuilt** areas are the **permission gate** (`session/request_permission`), **MCP passthrough**, **session modes / config options / model selection**, **slash commands**, and **agent plans** — all of which both reference adapters ship — plus the client **filesystem** and **terminal** method families (which the adapters mostly do NOT drive either — see rows 43-49). See [Gap summary](#gap-summary). +The bridge implements the **core prompt-turn loop** for N concurrent sessions: initialize, session new/load, prompt, cancel, streamed assistant/thought chunks, tool-call rendering (including Zed terminal cards), resumable session replay, one-shot permission prompts, and per-session sandbox/approval config options. The largest **unbuilt** areas are **MCP passthrough**, runtime model selection, **slash commands**, and **agent plans**, plus the client **filesystem** and **terminal** method families (which the adapters mostly do NOT drive either — see rows 43-49). See [Gap summary](#gap-summary). ## 1. Agent methods (client → agent) @@ -25,8 +25,8 @@ The bridge implements the **core prompt-turn loop** for N concurrent sessions: i | `session/close` | S | ❌ | ✅ | ✅ | No `session/close` handler — the SDK dispatch returns `method_not_found`. The bridge tears sessions down on client disconnect / Cordis disposal (cross-cutting, see [§8](#8-cross-cutting)), but that is not the on-demand per-session method. | | `session/prompt` | S | ✅ | ✅ | ✅ | Maps to `agent.send`; one in-flight prompt per session; settles on the owning turn's end. | | `session/cancel` | S | ✅ | ✅ | ✅ | Queue-aware `agent.cancel`; settles the in-flight prompt `cancelled`, scoped to the one session. | -| `session/set_mode` | S | ❌ | ✅ | ✅ | Session modes not modeled (see [§6 Modes](#6-session-modes--config-options--models)). | -| `session/set_config_option` | S | ❌ | ✅ | ✅ | Config options not modeled. | +| `session/set_mode` | S | ❌ | ✅ | ✅ | Session modes deliberately skipped: config options are the spec's replacement (modes are slated for removal in ACP v2), and one mode list cannot carry the two orthogonal knobs (see [§6](#6-session-modes--config-options--models)). | +| `session/set_config_option` | S | ✅ | ✅ | ✅ | Two capability-gated selects — `sandbox-mode` (confining executor mounted) and `approval-policy` (approval seam composed); values validated against the domain vocabularies, one log-only event per switch on the session's own log, complete refreshed state in the response ([sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)). | | model selection | S | ❌ | ✅ | ✅ | No distinct stable `session/set_model` — model is the `model`-category `session/set_config_option`. The bridge fixes the model per-bridge via config; no runtime switch. Codex still uses the legacy `unstable_setSessionModel` ext method. | | `session/list` | S | ❌ | ✅ | ✅ | Gated by `sessionCapabilities.list`. The harness HAS `sessionPersistence.list()` (used internally for load-cwd validation) but does not expose it over ACP. | | `session/delete` | S | ❌ | ✅ | ✅ | Gated by `sessionCapabilities.delete`. | @@ -39,7 +39,7 @@ These are capabilities the bridge would *drive* on the editor. The harness runs | Method | Stable | Bridge | Claude | Codex | Notes | |---|---|---|---|---|---| | `session/update` | S | ✅ | ✅ | ✅ | The bridge's primary output channel (see [§4](#4-sessionupdate-variants)). | -| `session/request_permission` | S | ❌ | ✅ | ✅ | **The biggest gap.** Tools run with the executor's full authority; no user authorization round-trip. The `agent→sessionId` reverse map is already in place to route a future permission request. Tracked `TODO(rfc010-permission-gate)`. | +| `session/request_permission` | S | ✅ | ✅ | ✅ | The bridge answers the [`ctx.approval`](../user-approval/README.md) seam for the agents it owns: an `ask` from a hook/plugin becomes an editor prompt attached to the streamed tool call, one-shot `allow_once`/`reject_once` options only. Whether a call asks is policy (nothing asks by default); `allow_always` is deferred (grant storage). | | `fs/read_text_file` | S | ❌ | ✅ | ❌ | The harness reads files directly (it does not see the editor's unsaved buffer state). Claude delegates; Codex does not. | | `fs/write_text_file` | S | ❌ | ✅ | ❌ | Same — direct writes, no editor delegation. | | `terminal/create` | S | ❌ | ❌ | ❌ | Neither reference adapter drives the client terminal API either — both, like the bridge, render shell output as tool-call content + a `_meta` channel (see [§5 Terminal](#terminal-rendering)). | @@ -86,7 +86,7 @@ These are capabilities the bridge would *drive* on the editor. The harness runs | `plan` | S | ❌ | ✅ | ✅ | No agent plan emitted. Both adapters emit real plan entries (Codex's `CodexEventHandler.updatePlan` maps `turn/plan/updated` → `{ sessionUpdate: 'plan', entries }`). | | `available_commands_update` | S | ❌ | ✅ | ✅ | No slash commands advertised. | | `current_mode_update` | S | ❌ | ✅ | ✅ | No session modes. | -| `config_option_update` | S | ❌ | ✅ | ✅ | No config options. | +| `config_option_update` | S | ❌ | ✅ | ✅ | Config options exist (advertised in `session/new`/`session/load`, switched via `session/set_config_option`), but the bridge never pushes agent-initiated changes — an operator default drift is narrated to the MODEL, not echoed to the editor. Future work in the [sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md). | | `usage_update` | S | ❌ | ✅ | ✅ | Token/cost reporting not surfaced (the harness records token usage internally on `assistant/message`). | | `session_info_update` | S | ❌ | ⚠️ | ⚠️ | Session title/metadata not pushed. | @@ -111,7 +111,7 @@ Tool-call presentation is **owned by each tool** (`presentCall` / `presentResult ## 6. Session modes / config options / models -❌ None modeled. Both reference adapters ship modes (Claude: a "plan" auto-mode; Codex: read-only / agent / agent-full-access mapping to its approval+sandbox policy), the newer config-option surface, and runtime model selection. The harness fixes the model per-bridge via `AcpConfig.model`. These are coupled to the unbuilt **permission gate** (a mode often selects an approval policy), so they are natural follow-ups to it. +Config options ✅ (the [sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): the bridge advertises one independent `select` per composable knob — `sandbox-mode` iff the mounted executor confines, `approval-policy` iff the approval seam is composed — with per-session current values folded from each session's own log, and honors `session/set_config_option` end to end (idle switches anchor at the next turn under the turn-enclosure contract). Session MODES stay deliberately unmodeled: config options are the spec's replacement (modes are slated for removal in ACP v2), and one mode list cannot carry two orthogonal knobs. Runtime model selection is still not modeled — the harness fixes the model per-bridge via `AcpConfig.model` (both reference adapters ship a model selector). ## 7. Content blocks @@ -130,7 +130,7 @@ The bridge rejects unsupported prompt blocks rather than silently dropping them | Feature | Stable | Bridge | Notes | |---|---|---|---| | `StopReason` mapping | S | ✅ | `turnEndToStopReason` is total over harness turn-end reasons → `end_turn`/`max_tokens`/`cancelled`. | -| Multi-session (N per connection) | S | ✅ | Strict per-session demux; concurrent streams never interleave. See the [multi-session RFC](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md). | +| Multi-session (N per connection) | S | ✅ | Strict per-session demux; concurrent streams never interleave. See the [multi-session RFC](../../../docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md). | | Disconnect / disposal teardown | S | ✅ | Quiesces every live session on client disconnect or Cordis disposal. | | `_meta` extensibility | S | ⚠️ | Consumed (Zed terminal cap) and emitted (terminal `_meta`); no other custom extensions. | | Background-task ownership isolation | — | ✅ | `bash_output`/`bash_kill` reject another session's task via an opaque owner token. | @@ -140,15 +140,14 @@ The bridge rejects unsupported prompt blocks rather than silently dropping them Ranked by how commonly the reference adapters ship them and how much UX they unlock: -1. **Permission gate** — `session/request_permission` + permission options. Tracked `TODO(rfc010-permission-gate)`; the reverse map is already wired and shared with `ask_user_question` routing. Foundational, and a prerequisite for modes. -2. **Session lifecycle** — `session/list` + `session/delete` (the persistence layer already lists), then `session/resume` / `session/close`. -3. **Modes / config options / model selection** — coupled to the permission gate. -4. **Agent plan** (`sessionUpdate: 'plan'`) — surface the loop's plan as structured entries. -5. **Slash commands** (`available_commands_update`). -6. **MCP passthrough** (`mcpServers` on `session/new` + `mcpCapabilities`). -7. **Richer prompt content** — image / embedded `resource` blocks (needs a multimodal model path). -9. **Usage reporting** (`usage_update`) — the harness already records token usage internally (on `assistant/message`). -10. **Editor filesystem delegation** (`fs/read_text_file` / `fs/write_text_file`) — lets the agent see unsaved buffers; lower priority since the harness has direct disk access. +1. **Session lifecycle** — `session/list` + `session/delete` (the persistence layer already lists), then `session/resume` / `session/close`. +2. **Model selection** — sandbox and approval config options are implemented; selecting the bridge's model at runtime remains open. +3. **Agent plan** (`sessionUpdate: 'plan'`) — surface the loop's plan as structured entries. +4. **Slash commands** (`available_commands_update`). +5. **MCP passthrough** (`mcpServers` on `session/new` + `mcpCapabilities`). +6. **Richer prompt content** — image / embedded `resource` blocks (needs a multimodal model path). +7. **Usage reporting** (`usage_update`) — the harness already records token usage internally (on `assistant/message`). +8. **Editor filesystem delegation** (`fs/read_text_file` / `fs/write_text_file`) — lets the agent see unsaved buffers; lower priority since the harness has direct disk access. ## Out of scope diff --git a/packages/ui/acp/package.json b/packages/ui/acp/package.json index 4ebc8485ce..a916722c52 100644 --- a/packages/ui/acp/package.json +++ b/packages/ui/acp/package.json @@ -28,7 +28,10 @@ }, "peerDependencies": { "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-user-approval": "^0.0.1", + "@deepseek-ai/dsh-bash": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-sandbox": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", "@deepseek-ai/dsh-session-persistence": "^0.0.1", "@deepseek-ai/dsh-tools": "^0.0.1", @@ -38,10 +41,14 @@ "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", + "@deepseek-ai/dsh-user-approval": "workspace:^", + "@deepseek-ai/dsh-bash": "workspace:^", "@deepseek-ai/dsh-bash-local": "workspace:^", "@deepseek-ai/dsh-fs-local": "workspace:^", "@deepseek-ai/dsh-fs-policy": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", diff --git a/packages/ui/acp/src/index.ts b/packages/ui/acp/src/index.ts index 928ab7da77..253bfb9b13 100644 --- a/packages/ui/acp/src/index.ts +++ b/packages/ui/acp/src/index.ts @@ -22,8 +22,10 @@ * `agent→sessionId` reverse map for O(1) demux of `agent/*` events; every * `session/event` and `agent/*` event is routed strictly to its owning session * record, so two sessions streaming at once never interleave their - * `session/update` notifications. The `tools/pre-execute` permission gate is - * deferred — see the TODO(rfc010-permission-gate) note below. + * `session/update` notifications. Permission prompts ride the same ownership + * map: the bridge answers `approval/request` for its own agents over + * `session/request_permission` (see the approval answerer below) — whether a + * call ASKS is policy (a hook or plugin returning `ask`), not the bridge's. * * stdout is the protocol: this plugin must run in an example that loads NO * stdout logger (the console logger writes to stdout and would corrupt the @@ -60,7 +62,10 @@ import { type PlanEntry, type PromptRequest, type PromptResponse, + type SessionConfigOption, type SessionNotification, + type SetSessionConfigOptionRequest, + type SetSessionConfigOptionResponse, type Stream, type StopReason, } from '@agentclientprotocol/sdk' @@ -69,11 +74,18 @@ import { assertNever, CallId } from '@deepseek-ai/dsh-llm' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import { AgentId } from '@deepseek-ai/dsh-agent' import { SessionId } from '@deepseek-ai/dsh-session' +import { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-bash' +import { APPROVAL_POLICIES, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-user-approval' +import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' +import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval' import type { SessionEvent, TodoItem, TurnEndReason } from '@deepseek-ai/dsh-session' import type { ToolCallView, ToolRegistry, ToolResultView, TerminalResultView } from '@deepseek-ai/dsh-tools' // Side-effect type import: declaration-merges `ctx.sessionPersistence` onto // Context (the bridge injects it and reads `list()` for load cwd validation). import type {} from '@deepseek-ai/dsh-session-persistence' +// Side-effect type import: declaration-merges the `approval/request` waterfall +// the bridge answers for its own agents (see the approval answerer below). +import type {} from '@deepseek-ai/dsh-user-approval' import { UserInteractionError, type AskUserQuestionAnswer, @@ -308,6 +320,19 @@ interface SessionRecord { turn: number | undefined logWatermark: number } | undefined + /** + * Config switches accepted while the session was IDLE, not yet anchored in + * its log. The turn-enclosure contract makes a bare between-turns append + * invalid (the JSONL backend treats a post-`turn/end` tail as crash + * garbage, and dev invariants throw), so an idle switch waits here and is + * anchored at the next turn's prompt-submit — before anything in that + * turn assembles a prompt or runs a call, and last write + * per knob wins (an idle flip-flop anchors as one event). Until anchored, + * the switch lives only in bridge memory: the set/new/load responses + * overlay it truthfully, and a restart before the next turn reverts it — + * which `session/load` then reports honestly from the log's fold. + */ + pendingSwitches: { sandboxMode?: SandboxMode; approvalPolicy?: ApprovalPolicy } } /** @@ -555,8 +580,136 @@ export function apply(ctx: Context, config: AcpConfig): void { if (status === 'idle' || status === 'disposed') settleFromLog(rec) }) + // --- Approval answerer ----------------------------------------------------- + // The bridge is the approval channel for the agents it owns: an `ask` routed + // through `ctx.approval` (dsh-tools asks and sandbox escalation) becomes + // an editor permission prompt attached to the already-streamed tool call. The + // listener occupies the single decision slot ONLY for its own agents — a + // foreign or call-less request delegates via next() so another answerer (or + // the fail-closed `unavailable` default) takes the question. A rejected + // `requestPermission` (client gone, bridge torn down) propagates and the + // ApprovalService contains it as `unavailable`. Options are one-shot only: + // allow_always is a grant-storage design the approval RFC defers, so the + // prompt never offers a durable grant the harness could not honor. + ctx.on('approval/request', (req, next) => { + const sessionId = bySession.get(req.agent) + // The protocol requires `toolCall` (the prompt renders attached to it), so + // a request without a callId has nothing to attach to — delegate. + if (sessionId === undefined || req.callId === undefined) return next() + return conn.requestPermission({ + sessionId, + toolCall: { toolCallId: req.callId }, + options: [ + { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' }, + { optionId: 'reject-once', name: 'Reject', kind: 'reject_once' }, + ], + }).then(({ outcome }) => { + if (outcome.outcome === 'cancelled') return 'cancelled' + // Only the two advertised options exist; an unknown optionId from a + // non-conforming client counts as a rejection, never a grant. + return outcome.optionId === 'allow-once' ? 'allowed-once' : 'rejected' + }) + }) + // --- The ACP Agent method surface ----------------------------------------- + /** + * The session config options this composition can honor, with current + * values folded from the AGENT'S OWN session log (`effectiveSandboxMode` / + * `effectiveApprovalPolicy` — the log is the per-session store, so a + * `session/load` reports a resumed session's overrides with no catch-up + * machinery), overlaid with the record's not-yet-anchored pending switches + * (see {@link SessionRecord.pendingSwitches}). Capability-gated like every + * advertised lever: the sandbox option exists only when the mounted + * executor confines (`ctx.get('bash')?.sandboxMode` defined), the approval + * option only when the approval seam is composed — both read + * opportunistically so this bridge keeps working in compositions without + * them. + */ + const configOptionsFor = (agent: Agent, pending: SessionRecord['pendingSwitches'] = {}): SessionConfigOption[] => { + const options: SessionConfigOption[] = [] + const defaultMode = ctx.get('bash')?.sandboxMode + if (defaultMode !== undefined) { + options.push({ + id: 'sandbox-mode', + name: 'Sandbox', + description: 'The file sandbox mode bash commands in this session run under.', + category: 'mode', + type: 'select', + currentValue: pending.sandboxMode ?? effectiveSandboxMode(agent.session.events) ?? defaultMode, + options: SANDBOX_MODES.map(mode => ({ value: mode, name: mode })), + }) + } + const approval = ctx.get('approval') + if (approval !== undefined) { + options.push({ + id: 'approval-policy', + name: 'Approvals', + description: 'ask: permission prompts reach you; never: they are rejected automatically.', + type: 'select', + // `?? 'ask'` also shields against a provided stand-in whose config + // never went through the plugin schema (tests do this). + currentValue: pending.approvalPolicy ?? effectiveApprovalPolicy(agent.session.events) ?? approval.config.policy ?? 'ask', + options: APPROVAL_POLICIES.map(policy => ({ value: policy, name: policy })), + }) + } + return options + } + + /** + * Whether the session's log currently has an open turn — the last boundary + * event is a `turn/start`. Decides whether a config switch may append NOW + * (enclosed) or must wait for the next turn (see + * {@link SessionRecord.pendingSwitches}). Read from the LOG, not + * `agent.status`: status stays `running` across the gap between two queued + * turns, where a bare append would still land outside any turn. + */ + const isTurnOpen = (agent: Agent): boolean => { + const events = agent.session.events + for (let index = events.length - 1; index >= 0; index -= 1) { + const type = (events[index] as SessionEvent).type + if (type === 'turn/start') return true + if (type === 'turn/end') return false + } + return false + } + + /** + * Anchor a record's pending switches into its (just-opened) turn, last + * write per knob — skipping a value the session already effectively has, + * so a net-zero idle flip-flop anchors NOTHING (the log records switches, + * not select clicks). + */ + const flushPendingSwitches = (rec: SessionRecord): void => { + const pending = rec.pendingSwitches + rec.pendingSwitches = {} + const events = rec.agent.session.events + if (pending.sandboxMode !== undefined + && pending.sandboxMode !== (effectiveSandboxMode(events) ?? ctx.get('bash')?.sandboxMode)) { + setSandboxMode(rec.agent.session, pending.sandboxMode) + } + if (pending.approvalPolicy !== undefined + && pending.approvalPolicy !== (effectiveApprovalPolicy(events) ?? ctx.get('approval')?.config.policy ?? 'ask')) { + setApprovalPolicy(rec.agent.session, pending.approvalPolicy) + } + } + + // Idle-accepted switches anchor at the next turn's prompt-submit: the turn + // is open (the seam fires inside it, per drained message — the first flush + // empties the slot, later ones no-op), the loop has not yet assembled + // anything for it, and — unlike appending from inside a `session/event` + // listener — this seam fires OUTSIDE any log emit, so peer listeners + // (the dev invariants, persistence) observe the anchored events in strict + // log order. A turn with no prompt (an idle inject's one-shot injection + // turn) leaves the switch pending — it runs no step, so nothing executes + // or assembles under a stale value. + ctx.on('agent/prompt-submit', (agent, _content, _source, next) => { + const sessionId = bySession.get(agent) + const rec = sessionId === undefined ? undefined : sessions.get(sessionId) + if (rec !== undefined) flushPendingSwitches(rec) + return next() + }) + const makeAgent = (connection: AgentSideConnection): AcpAgent => { conn = connection return { @@ -610,8 +763,10 @@ export function apply(ctx: Context, config: AcpConfig): void { presenter: makePresenter(), terminalEnabled: terminalOutputCap, inflight: undefined, + pendingSwitches: {}, }) - return Promise.resolve({ sessionId }) + const configOptions = configOptionsFor(handle.agent) + return Promise.resolve({ sessionId, ...configOptions.length > 0 ? { configOptions } : {} }) }, async loadSession(params: LoadSessionRequest): Promise { @@ -687,6 +842,7 @@ export function apply(ctx: Context, config: AcpConfig): void { presenter: makePresenter(), terminalEnabled, inflight: undefined, + pendingSwitches: {}, } sessions.set(sessionId, record) // Replay the persisted event log to the client as session/update. Use @@ -710,7 +866,8 @@ export function apply(ctx: Context, config: AcpConfig): void { for (const event of agent.session.events) { streamSessionEventUpdate(sessionId, event, notify, replayPresenter, replayTerminal) } - return {} + const configOptions = configOptionsFor(agent) + return configOptions.length > 0 ? { configOptions } : {} } finally { loadingIds.delete(sessionId) } @@ -765,6 +922,62 @@ export function apply(ctx: Context, config: AcpConfig): void { settlePrompt(rec, 'cancelled') return Promise.resolve() }, + + setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise { + assertOpen() + const rec = requireSession(SessionId(params.sessionId)) + // Both advertised options are selects, so the boolean-shaped variant of + // the request is a protocol misuse regardless of configId. + if (typeof params.value !== 'string') { + throw invalidParams(`config option ${params.configId} is a select; boolean values are not accepted`) + } + // The setters append ONE log-only event on this session's own log — + // the log is the store (the sandbox RFC § Per-session mode switching): execution, the + // prompt section, and the narrator all fold it from there, and a + // resumed session reports the override back through + // configOptionsFor. A switch while a turn is OPEN anchors + // immediately (the next step sees it); an IDLE switch waits in + // pendingSwitches for the next `turn/start` (turn-enclosure: a bare + // between-turns append would be dropped as crash tail on reload). + // Values are validated against the same closed lists the options + // advertised; an id this composition never advertised (or an unknown + // one) rejects. + switch (params.configId) { + case 'sandbox-mode': { + const defaultMode = ctx.get('bash')?.sandboxMode + if (defaultMode === undefined || !SANDBOX_MODES.includes(params.value as SandboxMode)) { + throw invalidParams(`unknown sandbox-mode value ${JSON.stringify(params.value)}`) + } + const value = params.value as SandboxMode + // A no-op switch (the value the session already shows — pending, + // else fold, else default) is acknowledged without recording + // anything: clients that re-push current selections on session + // start must not mint override events out of thin air. + const current = rec.pendingSwitches.sandboxMode ?? effectiveSandboxMode(rec.agent.session.events) ?? defaultMode + if (value === current) break + if (isTurnOpen(rec.agent)) setSandboxMode(rec.agent.session, value) + else rec.pendingSwitches.sandboxMode = value + break + } + case 'approval-policy': { + const approval = ctx.get('approval') + if (approval === undefined || !APPROVAL_POLICIES.includes(params.value as ApprovalPolicy)) { + throw invalidParams(`unknown approval-policy value ${JSON.stringify(params.value)}`) + } + const value = params.value as ApprovalPolicy + const current = rec.pendingSwitches.approvalPolicy ?? effectiveApprovalPolicy(rec.agent.session.events) ?? approval.config.policy ?? 'ask' + if (value === current) break + if (isTurnOpen(rec.agent)) setApprovalPolicy(rec.agent.session, value) + else rec.pendingSwitches.approvalPolicy = value + break + } + default: + throw invalidParams(`unknown config option ${JSON.stringify(params.configId)}`) + } + // The spec requires the COMPLETE refreshed config state in the response + // (a change may cascade); ours are independent, but the contract holds. + return Promise.resolve({ configOptions: configOptionsFor(rec.agent, rec.pendingSwitches) }) + }, } } diff --git a/packages/ui/acp/tests/approval.spec.ts b/packages/ui/acp/tests/approval.spec.ts new file mode 100644 index 0000000000..ed035aaf80 --- /dev/null +++ b/packages/ui/acp/tests/approval.spec.ts @@ -0,0 +1,108 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk' +import { CallId } from '@deepseek-ai/dsh-llm' +import { AgentId, type Agent } from '@deepseek-ai/dsh-agent' +import ApprovalService, { type ApprovalRequest } from '@deepseek-ai/dsh-user-approval' +import { makeBridgeHarness, type BridgeHarness } from './harness.ts' + +/** + * The bridge's `approval/request` answerer: an ask for an agent the bridge + * owns becomes a `session/request_permission` prompt attached to the tool + * call; foreign or call-less requests delegate down to the fail-closed + * default. Driven through `ctx.approval` — the same path dsh-tools' ask + * routing takes — against the harness's scriptable client. + */ +describe('acp bridge — approval answerer', () => { + let storageDir: string + let harness: BridgeHarness | undefined + + beforeEach(async () => { storageDir = await mkdtemp(join(tmpdir(), 'acp-approval-')) }) + afterEach(async () => { + await harness?.dispose() + harness = undefined + await rm(storageDir, { recursive: true, force: true }) + }) + + async function ownedAgentRequest( + h: BridgeHarness, overrides: Partial = {}, + ): Promise<{ agent: Agent; request: ApprovalRequest }> { + await h.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const agent = h.ctx.agents.get(AgentId(sessionId)) + if (agent === undefined) throw new Error('newSession created no agent') + // In production an ask always fires mid-turn (tool execution); open one so + // request()'s turn-enclosure precondition holds for the direct drive below. + agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + return { agent, request: { agent, toolName: 'echo', callId: CallId('call-9'), ...overrides } } + } + + it('prompts the editor for an owned agent and maps allow-once → allowed-once', async () => { + harness = await makeBridgeHarness({ storageDir }) + await harness.ctx.plugin(ApprovalService) + harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } }) + + const { request } = await ownedAgentRequest(harness) + await expect(harness.ctx.approval.request(request)).resolves.toBe('allowed-once') + + expect(harness.permissionRequests).toHaveLength(1) + const wire = harness.permissionRequests[0] + expect(wire?.toolCall).toEqual({ toolCallId: 'call-9' }) + expect(wire?.options.map(o => ({ optionId: o.optionId, kind: o.kind }))).toEqual([ + { optionId: 'allow-once', kind: 'allow_once' }, + { optionId: 'reject-once', kind: 'reject_once' }, + ]) + }) + + it('maps reject-once → rejected', async () => { + harness = await makeBridgeHarness({ storageDir }) + await harness.ctx.plugin(ApprovalService) + harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'reject-once' } }) + + const { request } = await ownedAgentRequest(harness) + await expect(harness.ctx.approval.request(request)).resolves.toBe('rejected') + }) + + it('maps a client cancellation → cancelled', async () => { + harness = await makeBridgeHarness({ storageDir }) + await harness.ctx.plugin(ApprovalService) + harness.onPermission = () => ({ outcome: { outcome: 'cancelled' } }) + + const { request } = await ownedAgentRequest(harness) + await expect(harness.ctx.approval.request(request)).resolves.toBe('cancelled') + }) + + it('treats an unknown optionId from a non-conforming client as a rejection, never a grant', async () => { + harness = await makeBridgeHarness({ storageDir }) + await harness.ctx.plugin(ApprovalService) + harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-always-i-insist' } }) + + const { request } = await ownedAgentRequest(harness) + await expect(harness.ctx.approval.request(request)).resolves.toBe('rejected') + }) + + it('delegates a foreign agent down to the fail-closed default', async () => { + harness = await makeBridgeHarness({ storageDir }) + await harness.ctx.plugin(ApprovalService) + harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } }) + + // Not created through the bridge: no bySession entry, so the answerer must + // call next() — nobody else answers, so the seam fails closed. + const foreign = { session: { events: [{ type: 'turn/start' }], append: () => ({}) } } as unknown as Agent + await expect(harness.ctx.approval.request({ agent: foreign, toolName: 'echo', callId: CallId('c') })) + .resolves.toBe('unavailable') + expect(harness.permissionRequests).toHaveLength(0) + }) + + it('delegates a call-less request — the protocol prompt must attach to a tool call', async () => { + harness = await makeBridgeHarness({ storageDir }) + await harness.ctx.plugin(ApprovalService) + harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } }) + + const { agent } = await ownedAgentRequest(harness) + await expect(harness.ctx.approval.request({ agent, toolName: 'echo' })).resolves.toBe('unavailable') + expect(harness.permissionRequests).toHaveLength(0) + }) +}) diff --git a/packages/ui/acp/tests/config-options.spec.ts b/packages/ui/acp/tests/config-options.spec.ts new file mode 100644 index 0000000000..1202e44bd3 --- /dev/null +++ b/packages/ui/acp/tests/config-options.spec.ts @@ -0,0 +1,260 @@ +/** + * Session config options over the bridge: the two per-session knobs + * (`sandbox-mode`, `approval-policy`) advertised from composition capability, + * their current values folded from each session's own log, switching via + * `session/set_config_option` (one log-only event per switch — the log is the + * store), and a resumed session reporting its overrides back on + * `session/load` with no catch-up machinery. + */ + +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk' +import * as Invariants from '@deepseek-ai/dsh-invariants' +import ApprovalService from '@deepseek-ai/dsh-user-approval' +import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval' +import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' +import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' +import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts' + +/** + * The REAL local executor reporting a confining default — `sandboxMode` is + * the documented capability override point (`dsh-bash-sandbox` overrides it + * the same way), so the bridge sees exactly what a sandboxing composition + * advertises without this suite dragging in a kernel sandbox stack. + */ +class SandboxedLocalExecutor extends LocalBashExecutor { + override get sandboxMode(): SandboxMode { + return 'read-only' + } +} + +/** The exact option payloads the bridge advertises (pinned verbatim). */ +function sandboxOption(currentValue: SandboxMode): object { + return { + id: 'sandbox-mode', + name: 'Sandbox', + description: 'The file sandbox mode bash commands in this session run under.', + category: 'mode', + type: 'select', + currentValue, + options: [ + { value: 'read-only', name: 'read-only' }, + { value: 'workspace-write', name: 'workspace-write' }, + { value: 'danger-full-access', name: 'danger-full-access' }, + ], + } +} + +function approvalOption(currentValue: ApprovalPolicy): object { + return { + id: 'approval-policy', + name: 'Approvals', + description: 'ask: permission prompts reach you; never: they are rejected automatically.', + type: 'select', + currentValue, + options: [ + { value: 'ask', name: 'ask' }, + { value: 'never', name: 'never' }, + ], + } +} + +describe('acp bridge — session config options', () => { + let storageDir: string + let h: BridgeHarness | undefined + let loader: BridgeHarness | undefined + + beforeEach(async () => { storageDir = await mkdtemp(join(tmpdir(), 'acp-config-')) }) + afterEach(async () => { + if (h) await h.dispose() + if (loader) await loader.dispose() + h = loader = undefined + await rm(storageDir, { recursive: true, force: true }) + }) + + /** A harness whose composition can honor both knobs (sandboxed executor + approval seam). */ + async function bothKnobs(options: { policy?: ApprovalPolicy; script?: NonNullable[0]>['script'] } = {}): Promise { + const harness = await makeBridgeHarness({ storageDir, ...options.script !== undefined ? { script: options.script } : {} }) + // The dev invariants police turn-enclosure: an idle switch that appended + // outside a turn would throw right here in the suite, not in production. + await harness.ctx.plugin(Invariants) + await harness.ctx.plugin(SandboxedLocalExecutor, { timeoutMs: 10_000 }) + await harness.ctx.plugin(ApprovalService, options.policy !== undefined ? { policy: options.policy } : {}) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + return harness + } + + it('advertises no configOptions in a composition with neither knob', async () => { + h = await makeBridgeHarness({ storageDir }) + await h.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const res = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + expect(res.configOptions).toBeUndefined() + }) + + it('a non-confining executor advertises no sandbox option (nothing would honor it)', async () => { + h = await makeBridgeHarness({ storageDir, withBash: true }) + await h.ctx.plugin(ApprovalService) + await h.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const res = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + expect(res.configOptions).toEqual([approvalOption('ask')]) + }) + + it('advertises both knobs with capability-derived currents (config default included)', async () => { + h = await bothKnobs({ policy: 'never' }) + const res = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + expect(res.configOptions).toEqual([sandboxOption('read-only'), approvalOption('never')]) + }) + + it('an idle switch is pending (overlaid, not yet logged), then anchors INSIDE the next turn', async () => { + h = await bothKnobs({ script: [textResponse('ok')] }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + + const afterSandbox = await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'workspace-write' }) + expect(afterSandbox.configOptions).toEqual([sandboxOption('workspace-write'), approvalOption('ask')]) + const afterApproval = await h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', value: 'never' }) + expect(afterApproval.configOptions).toEqual([sandboxOption('workspace-write'), approvalOption('never')]) + + // Idle: nothing in the log yet — turn-enclosure forbids a bare append + // (the dev invariants in this suite would throw), so the switch lives on + // the record until a turn opens. + const session = h.ctx.agents.list()[0]?.session + expect(session?.events.some(e => e.type === 'bash/sandbox-mode' || e.type === 'approval/policy')).toBe(false) + + // The next turn anchors both switches inside itself, one event per knob. + await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] }) + const events = session?.events ?? [] + expect(events.filter(e => e.type === 'bash/sandbox-mode').map(e => e.data)).toEqual([{ mode: 'workspace-write' }]) + expect(events.filter(e => e.type === 'approval/policy').map(e => e.data)).toEqual([{ policy: 'never' }]) + const turnStart = events.findIndex(e => e.type === 'turn/start') + const anchored = events.findIndex(e => e.type === 'bash/sandbox-mode') + expect(turnStart).toBeGreaterThanOrEqual(0) + expect(anchored).toBeGreaterThan(turnStart) + }) + + it('an idle flip-flop anchors as ONE event (last write per knob wins)', async () => { + h = await bothKnobs({ script: [textResponse('ok')] }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'workspace-write' }) + await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'danger-full-access' }) + await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] }) + const events = h.ctx.agents.list()[0]?.session.events ?? [] + expect(events.filter(e => e.type === 'bash/sandbox-mode').map(e => e.data)).toEqual([{ mode: 'danger-full-access' }]) + // Idle again AFTER a completed turn (the log now ends in turn/end): a new + // switch pends rather than appending outside the closed turn. + const again = await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'read-only' }) + expect(again.configOptions?.find(option => option.id === 'sandbox-mode')).toMatchObject({ currentValue: 'read-only' }) + expect(events.filter(e => e.type === 'bash/sandbox-mode')).toHaveLength(1) + }) + + it('a no-op switch (the value already shown) records nothing and keeps a live pending', async () => { + h = await bothKnobs({ script: [textResponse('ok')] }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + // Re-pushing the composition default (what clients that echo current + // selections on session start do) must not mint an override event. + const echo = await h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', value: 'ask' }) + expect(echo.configOptions?.find(option => option.id === 'approval-policy')).toMatchObject({ currentValue: 'ask' }) + // Re-sending a PENDING value keeps the pending switch alive (it is what + // the session shows), rather than cancelling it. + await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'workspace-write' }) + const repeat = await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'workspace-write' }) + expect(repeat.configOptions?.find(option => option.id === 'sandbox-mode')).toMatchObject({ currentValue: 'workspace-write' }) + await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] }) + const events = h.ctx.agents.list()[0]?.session.events ?? [] + expect(events.filter(e => e.type === 'approval/policy')).toHaveLength(0) + expect(events.filter(e => e.type === 'bash/sandbox-mode').map(e => e.data)).toEqual([{ mode: 'workspace-write' }]) + }) + + it('a net-zero idle flip-flop anchors NOTHING (switches are recorded, select clicks are not)', async () => { + h = await bothKnobs({ script: [textResponse('ok')] }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'workspace-write' }) + const back = await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'read-only' }) + expect(back.configOptions?.find(option => option.id === 'sandbox-mode')).toMatchObject({ currentValue: 'read-only' }) + await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] }) + const events = h.ctx.agents.list()[0]?.session.events ?? [] + expect(events.filter(e => e.type === 'bash/sandbox-mode')).toHaveLength(0) + }) + + it('a mid-turn switch anchors immediately (the open turn encloses it)', async () => { + h = await bothKnobs({ script: ['hang'] }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const hung = h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }) + // Give the loop a tick to open the turn (the turns.spec hang idiom). + await new Promise(resolve => setTimeout(resolve, 30)) + await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'workspace-write' }) + await h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', value: 'never' }) + const events = h.ctx.agents.list()[0]?.session.events ?? [] + const turnStart = events.findIndex(e => e.type === 'turn/start') + const anchored = events.findIndex(e => e.type === 'bash/sandbox-mode') + expect(turnStart).toBeGreaterThanOrEqual(0) + expect(anchored).toBeGreaterThan(turnStart) + expect(events.some(e => e.type === 'approval/policy')).toBe(true) + await h.client.cancel({ sessionId }) + await hung + }) + + it('tolerates a provided approval stand-in whose config skipped the plugin schema', async () => { + h = await makeBridgeHarness({ storageDir, script: [textResponse('ok')] }) + h.ctx.provide('approval', { config: {} } as unknown as InstanceType) + await h.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const res = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + expect(res.configOptions).toEqual([approvalOption('ask')]) + const sessionId = res.sessionId + // The schema-less config also shields the no-op guard ('ask' by the ?? fallback)… + const echo = await h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', value: 'ask' }) + expect(echo.configOptions).toEqual([approvalOption('ask')]) + // …and the anchor-time comparison: a real switch under the stand-in still anchors. + await h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', value: 'never' }) + await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] }) + const events = h.ctx.agents.list()[0]?.session.events ?? [] + expect(events.filter(e => e.type === 'approval/policy').map(e => e.data)).toEqual([{ policy: 'never' }]) + }) + + it('rejects unknown ids, unadvertised ids, boolean values, and out-of-vocabulary values', async () => { + h = await makeBridgeHarness({ storageDir }) + await h.ctx.plugin(ApprovalService) + await h.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + + await expect(h.client.setSessionConfigOption({ sessionId, configId: 'reasoning-effort', value: 'max' })) + .rejects.toThrow(/unknown config option/) + // sandbox-mode exists as a concept but THIS composition never advertised it. + await expect(h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'workspace-write' })) + .rejects.toThrow(/unknown sandbox-mode value/) + await expect(h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', type: 'boolean', value: true })) + .rejects.toThrow(/select; boolean values are not accepted/) + await expect(h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', value: 'always' })) + .rejects.toThrow(/unknown approval-policy value/) + }) + + it('a switch in one session never leaks into a concurrent one (state and pending both per-session)', async () => { + h = await bothKnobs() + const a = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const b = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + await h.client.setSessionConfigOption({ sessionId: a.sessionId, configId: 'sandbox-mode', value: 'danger-full-access' }) + // B sees its own composition defaults, not A's pending switch... + const bAfter = await h.client.setSessionConfigOption({ sessionId: b.sessionId, configId: 'approval-policy', value: 'never' }) + expect(bAfter.configOptions).toEqual([sandboxOption('read-only'), approvalOption('never')]) + // ...and A keeps its own state, untouched by B's. + const aAfter = await h.client.setSessionConfigOption({ sessionId: a.sessionId, configId: 'sandbox-mode', value: 'danger-full-access' }) + expect(aAfter.configOptions).toEqual([sandboxOption('danger-full-access'), approvalOption('ask')]) + }) + + it('session/load reports a resumed session\'s overrides from its own log', async () => { + h = await bothKnobs({ script: [textResponse('ok')] }) + const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + await h.client.setSessionConfigOption({ sessionId, configId: 'sandbox-mode', value: 'danger-full-access' }) + await h.client.setSessionConfigOption({ sessionId, configId: 'approval-policy', value: 'never' }) + // One turn checkpoints the log (the switch events flush with it). + await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'persist me' }] }) + await h.dispose() + h = undefined + + loader = await bothKnobs() + const res = await loader.client.loadSession({ sessionId, cwd: process.cwd(), mcpServers: [] }) + expect(res.configOptions).toEqual([sandboxOption('danger-full-access'), approvalOption('never')]) + }) +}) diff --git a/packages/ui/acp/tsconfig.json b/packages/ui/acp/tsconfig.json index 9c2358c455..0c82438277 100644 --- a/packages/ui/acp/tsconfig.json +++ b/packages/ui/acp/tsconfig.json @@ -34,6 +34,15 @@ }, { "path": "../../session-persistence/session-persistence" + }, + { + "path": "../user-approval" + }, + { + "path": "../../sandbox/sandbox" + }, + { + "path": "../../bash/bash" } ] } diff --git a/packages/ui/stdio-agent/README.md b/packages/ui/stdio-agent/README.md index a299e2a94a..27f0d20be7 100644 --- a/packages/ui/stdio-agent/README.md +++ b/packages/ui/stdio-agent/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-stdio-agent -The **terminal stdio chat app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`. +The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`. It is the readline counterpart to [`@deepseek-ai/dsh-acp-agent`](../acp-agent/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster. @@ -11,7 +11,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha | Plugin | Why it is here | |---|---| | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) | -| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` and carrying its `persona` | +| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` | | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` | | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools | | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool | @@ -32,6 +32,8 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte | `welcome` | `ready.` | the stdin-chat banner | | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) | +Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-agent` was started. Resumed sessions keep the cwd stored in the persisted session header. + ## The bin `dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`: the cordis Loader resolves the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages) through its internal module loader, which is only active under that flag. The `demo:echo` / `demo:repl` scripts invoke it that way. diff --git a/packages/ui/stdio-agent/src/index.ts b/packages/ui/stdio-agent/src/index.ts index 2617cbc87b..1037c28112 100644 --- a/packages/ui/stdio-agent/src/index.ts +++ b/packages/ui/stdio-agent/src/index.ts @@ -1,5 +1,5 @@ /** - * The stdio chat app: the providerless agent spine ({@link + * The stdio chat app: the default agent spine ({@link * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal * chat needs — a console logger, the readline UI (the in-package `stdio-chat` * module), JSONL session @@ -58,7 +58,9 @@ export const name = 'stdio-agent' * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is * the deployment persona (forwarded to the system-prompt plugin); `toolOrder` * is the explicit model-facing tool order (forwarded to the system-prompt plugin); - * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner. + * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions + * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory; + * `welcome` is the UI banner. */ export interface Config { /** Model name for the `main` agent (must have a registered adapter). */ @@ -73,6 +75,8 @@ export interface Config { persistenceRoot?: string /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */ welcome?: string + /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */ + skills?: agentCore.SkillConfig /** * If set, the `main` agent RESUMES this persisted session id instead of * starting fresh. Sourced from an env var in the leaf `cordis.yml` @@ -91,6 +95,7 @@ export const Config: z = z.object({ tools: ToolRegistry.Config, persistenceRoot: z.string().default('./.sessions'), welcome: z.string().default('ready.'), + skills: agentCore.SkillConfigSchema, resumeSessionId: z.string(), }) @@ -110,8 +115,10 @@ export function apply(ctx: Context, config: Config): void { agents: [{ id: AgentId('main'), model: config.model, + cwd: process.cwd(), ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {}, }], + ...config.skills !== undefined ? { skills: config.skills } : {}, }) ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' }) ctx.plugin(UserInteractionService) diff --git a/packages/ui/stdio-agent/tests/built-bin.e2e.ts b/packages/ui/stdio-agent/tests/built-bin.e2e.ts index 7b84fad65b..31cdf3eb08 100644 --- a/packages/ui/stdio-agent/tests/built-bin.e2e.ts +++ b/packages/ui/stdio-agent/tests/built-bin.e2e.ts @@ -92,7 +92,7 @@ async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promi ' name: \'@deepseek-ai/dsh-stdio-agent\'', ' config:', ' model: mock-echo', - ' systemPrompt: \'demo\'', + ' persona: \'demo\'', ` welcome: '${welcome}'`, ...disabledBrokenEntry ? ['- id: off', ' name: \'./src/does-not-exist.ts\'', ' disabled: true'] @@ -111,7 +111,7 @@ function runBuiltBin(cwd: string, configArg: string, line: string): Promise<{ st const child = spawn(process.execPath, ['--expose-internals', stdioBin, configArg], { cwd, // Mock model: never calls the network, so no key needed. - env: { ...process.env }, + env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') }, stdio: ['pipe', 'pipe', 'pipe'], }) let stdout = '' diff --git a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts index 1f5a01a5b6..c08115526f 100644 --- a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts +++ b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts @@ -1,7 +1,11 @@ import { describe, it, expect } from 'vitest' +import { mkdtemp } from 'node:fs/promises' +import { join } from 'node:path' +import { tmpdir } from 'node:os' import { Context } from 'cordis' import Loader from '@cordisjs/plugin-loader' import { AgentId } from '@deepseek-ai/dsh-agent' +import type { Message } from '@deepseek-ai/dsh-llm' import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt' import * as stdioAgent from '../src/index.ts' @@ -30,9 +34,47 @@ async function mount(config: stdioAgent.Config): Promise { return ctx } +async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise> { + const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-skills-')) + return { + local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }, + ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {}, + } +} + +async function composePrefix(ctx: Context): Promise { + const empty: Message[] = [] + return await ctx.waterfall( + 'agent/session-prefix', { session: { header: { cwd: '/tmp' } } } as never, + empty, new AbortController().signal, () => Promise.resolve(empty), + ) +} + +async function withIsolatedSkillHomes(run: () => Promise): Promise { + const oldDshHome = process.env.DSH_HOME + const oldAgentsHome = process.env.DSH_AGENTS_HOME + const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-default-skills-')) + process.env.DSH_HOME = join(home, '.dsh') + process.env.DSH_AGENTS_HOME = join(home, '.agents') + try { + return await run() + } finally { + if (oldDshHome === undefined) { + delete process.env.DSH_HOME + } else { + process.env.DSH_HOME = oldDshHome + } + if (oldAgentsHome === undefined) { + delete process.env.DSH_AGENTS_HOME + } else { + process.env.DSH_AGENTS_HOME = oldAgentsHome + } + } +} + describe('dsh-stdio-agent app', () => { it('composes the spine + front-door cluster and pre-creates the main agent', async () => { - const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec' }) + const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec', skills: await isolatedSkillsConfig() }) // The spine services (brought up by the agent-core bundle) are all present. expect(ctx.get('agents')).toBeDefined() expect(ctx.get('agentLoop')).toBeDefined() @@ -40,7 +82,9 @@ describe('dsh-stdio-agent app', () => { expect(ctx.get('userInteraction')).toBeDefined() expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined() // The pre-created `main` agent the UI drives. - expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined() + const agent = ctx.get('agents')?.get(AgentId('main')) + expect(agent).toBeDefined() + expect(agent?.session.header.cwd).toBe(process.cwd()) await ctx.fiber.dispose() }) @@ -51,13 +95,24 @@ describe('dsh-stdio-agent app', () => { // schema-bypassing direct-mount caller. const ctx = new Context() // No persona: covers the omitted-persona forwarding branch too. - stdioAgent.apply(ctx, { model: 'mock' }) + stdioAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() }) await new Promise(resolve => setTimeout(resolve, 80)) expect(ctx.get('sessionPersistence')).toBeDefined() expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined() await ctx.fiber.dispose() }) + it('uses default skill config when apply is called directly without skills', async () => { + await withIsolatedSkillHomes(async () => { + const ctx = new Context() + stdioAgent.apply(ctx, { model: 'mock' }) + await new Promise(resolve => setTimeout(resolve, 80)) + expect(ctx.skills).toBeDefined() + expect(await ctx.skills.list()).toEqual([]) + await ctx.fiber.dispose() + }) + }) + it('forwards resumeSessionId onto the pre-created agent when set', async () => { // A resume id defers agent creation until persistence loads; with no backing // session the resume is contained + logged, so no `main` agent registers — @@ -67,11 +122,19 @@ describe('dsh-stdio-agent app', () => { persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec-resume', resumeSessionId: 'no-such-session', + skills: await isolatedSkillsConfig(), }) expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined() await ctx.fiber.dispose() }) + it('forwards skill config into agent-core', async () => { + const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) }) + ctx.skills.register({ name: 'stdio-skill', description: 'Stdio skill', source: 'runtime', content: 'body' }) + expect(JSON.stringify(await composePrefix(ctx))).toContain('- `stdio-skill`: Std...') + await ctx.fiber.dispose() + }) + it('exposes its name and Config schema', () => { expect(stdioAgent.name).toBe('stdio-agent') expect(stdioAgent.Config).toBeDefined() @@ -94,7 +157,7 @@ describe('dsh-stdio-agent app', () => { }) } const assembly = await ctx.get('systemPrompt')!.assemble() - expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question']) + expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question', 'skill']) await ctx.fiber.dispose() }) diff --git a/packages/ui/user-approval/README.md b/packages/ui/user-approval/README.md new file mode 100644 index 0000000000..3973dd5029 --- /dev/null +++ b/packages/ui/user-approval/README.md @@ -0,0 +1,13 @@ +# @deepseek-ai/dsh-user-approval + +User-approval seam. Owns the `ctx.approval` service ([`ApprovalService`](src/index.ts)) and the one-shot permission vocabulary the harness shares: `ApprovalRequest` (agent + tool identity + reason + abort signal), the closed `ApprovalOutcome` union (`allowed-once` / `rejected` / `cancelled` / `unavailable`), the `ApprovalRequestId` brand pairing the two log-only audit events (`approval/asked` / `approval/decided`), and the `approval/request` waterfall the answerers listen on. It lives in the UI group because its purpose is human permission, while remaining channel-neutral: it depends only on Cordis and core vocabulary packages, never on a concrete UI. + +The contract in one line: `ctx.approval.request(req)` puts exactly one question — "may this specific action proceed?" — to whatever answerers the deployment composed, and always resolves to an outcome, never rejects: an aborted signal yields `cancelled`, a throwing or missing answerer yields `unavailable`, and `allowed-once` is a grant for the single asked-about action, never a class of future ones. The one precondition: ask from inside an open turn — the audit pair is turn-enclosed by contract (the turn is the durable log's commit/replay boundary; a bare event between turns is crash-tail garbage on reload), so an idle ask throws before appending anything. + +The service is the mechanism, answerers are the policy. Answerers are `approval/request` waterfall listeners occupying a single decision slot: answer for an agent you own by returning an outcome without calling `next()`, or delegate an agent you don't recognize by calling `next()` — the chain's built-in default is `unavailable`, so a deployment with no answerer (headless, CI) fails closed with zero configuration. Registration order across sibling plugins is not load-order deterministic; compose one terminal answerer per deployment and use `prepend` listeners only for decide-or-delegate gates. + +The seam also owns the per-session POLICY tier ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): `ApprovalPolicy` is `'ask'` (delegate to the answerers) or `'never'` (deterministically reject without prompting anyone; the strict CI/unattended stance), with `effective = fold(the session's 'approval/policy' events, last one wins) ?? Config.policy` — the session log is the store, written only through `setApprovalPolicy(session, policy)`. The service decides `'never'` inside `request()` itself, before dispatching the waterfall (`'never'` → `'rejected'` with the audit pair still landing; no listener registration, including a later `prepend`, can precede it), states `'never'` — and only `'never'` in prose — in a per-agent prompt section, records either value with a source-owned header marker, and narrates a policy switch to the model in at most one coalesced `agent/pre-step` notice. The restart fallback reads the marker rather than deployment-controlled persona prose; attribution is positional (an override event after the last `request/header*` reads `changed by the user`, otherwise `changed by the operator/config`). + +One seam serves both ask paths of [the sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md): the `tools/pre-execute` `ask` decision (routed by [`@deepseek-ai/dsh-tools`](../../core/tools/) when this service is mounted; degrading to deny when it is not), and the sandbox post-denial escalated retry (the bash tool's `sandbox_permissions` gate in [`@deepseek-ai/dsh-tool-bash`](../../bash/tool-bash/) — [the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)). The full design: [the approval-seam RFC](../../../docs/rfc/implemented/feature/2026-07-06-approval-seam.md). + +Answerers today: the ACP bridge ([`@deepseek-ai/dsh-acp`](../../ui/acp/)) forwards to the editor's `session/request_permission` prompt for agents it owns. The audit events are log-only session records — the model only ever sees the tool result the asker derives from the outcome. diff --git a/packages/ui/user-approval/package.json b/packages/ui/user-approval/package.json new file mode 100644 index 0000000000..619339fde3 --- /dev/null +++ b/packages/ui/user-approval/package.json @@ -0,0 +1,43 @@ +{ + "name": "@deepseek-ai/dsh-user-approval", + "description": "User-approval seam (ctx.approval) for the DeepSeek Harness: one-shot permission decisions dispatched to composed answerers over the approval/request waterfall, fail-closed by default", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-brand": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-session": "^0.0.1", + "@deepseek-ai/dsh-system-prompt": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/ui/user-approval/src/index.ts b/packages/ui/user-approval/src/index.ts new file mode 100644 index 0000000000..064875a86a --- /dev/null +++ b/packages/ui/user-approval/src/index.ts @@ -0,0 +1,437 @@ +/** + * Approval seam: `ctx.approval` answers exactly one question — "may this + * specific action proceed?" — by dispatching the `approval/request` waterfall + * to whatever answerers the deployment composed (an ACP editor prompt, an + * auto-decide policy, a scripted test listener) and returning a closed + * {@link ApprovalOutcome}. With no answerer the waterfall falls through to the + * built-in default `'unavailable'`: absence of a UI can never grant anything. + * + * The service is the MECHANISM (dispatch, cancellation, audit); answerers are + * the POLICY. It serves both ask paths the sandbox RFC names — the + * `tools/pre-execute` `ask` decision and the sandbox post-denial escalation — + * so every asker shares one outcome + * vocabulary and one audit trail. Grants are one-shot by design: an + * `'allowed-once'` outcome authorizes the single action it was asked about, + * never a class of future actions. + * + * Every request lands two log-only session events on the requesting agent's + * log (`approval/asked` / `approval/decided`, paired by + * {@link ApprovalRequestId}) — an audit trail, deliberately NOT part of the + * model-visible transcript: the model only ever sees the tool result the + * caller derives from the outcome. + * + * The seam also owns the per-session POLICY tier (the sandbox RFC § Per-session mode switching): + * `effective = fold(the session's 'approval/policy' events, last one wins) + * ?? config.policy` — the session log is the store, so an override survives + * restart by replay. The service resolves `'never'` sessions to + * `'rejected'` inside `request()` before dispatching any answerer (no + * registration order, including a later `prepend`, can precede it); a prompt section states `'never'` + * (and only `'never'` — an availability promise is unknowable without + * asking); an `agent/pre-step` narrator explains a switch to the model in at + * most one coalesced notice per step. + * + * @module @deepseek-ai/dsh-user-approval + */ + +import { randomUUID } from 'node:crypto' +import { Context, Service } from 'cordis' +import z from 'schemastery' +import type { Branded } from '@deepseek-ai/dsh-brand' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { CallId } from '@deepseek-ai/dsh-llm' +import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' +import type {} from '@deepseek-ai/dsh-system-prompt' + +declare module 'cordis' { + interface Context { + approval: ApprovalService + } + + interface Events { + /** + * Waterfall asking the composed answerers to decide one approval request. + * Dispatched only from {@link ApprovalService.request} — callers go through + * the service (which owns cancellation and the audit events), never through + * `ctx.waterfall` directly. A listener that can answer for this request's + * agent returns an outcome WITHOUT calling `next()` (the decision slot is + * single-occupancy, first listener to answer wins); a listener that does + * not recognize the agent MUST call `next()` so another answerer — or the + * fail-closed default `'unavailable'` — gets the question. Throwing is + * contained by the service and yields `'unavailable'`. + * @param req - the pending decision (agent, tool identity, reason, signal). + * @mode waterfall + */ + 'approval/request'(this: ApprovalService, req: ApprovalRequest, next: () => Promise): Promise + } +} + +declare module '@deepseek-ai/dsh-session' { + interface SessionEventMap { + /** + * An approval question was put to the answerer chain — log-only audit + * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs + * it with the `approval/decided` that always follows; `toolName` is the + * tool the question is about, `callId` the exact tool call when the asker + * had one, `reason` the asker's human-readable explanation (e.g. a hook's + * permission-decision reason). + */ + 'approval/asked': { + id: ApprovalRequestId + toolName: string + callId?: CallId + reason?: string + } + /** + * The outcome of a prior `approval/asked` (same `id`) — log-only audit. + * Exactly one per ask, appended when the outcome is known: a decision, a + * cancellation, or the fail-closed `'unavailable'`. + */ + 'approval/decided': { + id: ApprovalRequestId + outcome: ApprovalOutcome + } + /** + * The session's approval policy was switched — log-only, durable, + * replayable, never in the model transcript (the model learns the policy + * from the prompt section and the narrator's notices). The LAST such + * event is the session's override ({@link effectiveApprovalPolicy}); + * who asked for it is derivable from position (an event after the log's + * last `request/header*` was a runtime switch by the user). + */ + 'approval/policy': { policy: ApprovalPolicy } + } +} + +/** + * Pairs one `approval/asked` audit event with its `approval/decided`. + * Service-issued (one fresh id per {@link ApprovalService.request} call). + */ +export type ApprovalRequestId = Branded<'ApprovalRequestId'> + +/** + * Brand a string as an {@link ApprovalRequestId}. + * @param id - the raw id string to brand. + * @returns the same string carrying the brand. + */ +export function ApprovalRequestId(id: string): ApprovalRequestId { + return id as ApprovalRequestId +} + +/** + * The closed outcome vocabulary of one approval request. + * + * - `'allowed-once'` — a one-shot grant for exactly the asked-about action; + * consumed by proceeding, never a durable authorization. + * - `'rejected'` — an answerer (human or policy) said no. + * - `'cancelled'` — the question was withdrawn: the prompt was dismissed, or + * the requesting execution aborted while the question was pending. + * - `'unavailable'` — nobody composed could answer (no listener, none that + * recognizes the agent, or an answerer failed). Callers MUST fail closed on + * it, exactly like `'rejected'` — the two differ only for audit and wording. + */ +export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable' + +/** Every {@link ApprovalOutcome}, for runtime normalization of answerer returns. */ +const OUTCOMES: readonly ApprovalOutcome[] = ['allowed-once', 'rejected', 'cancelled', 'unavailable'] + +/** + * A session's approval policy — what happens to an {@link ApprovalService} + * ask BEFORE any interactive answerer sees it: + * + * - `'ask'` (the default) — delegate to the composed answerers; with none + * composed the chain falls through to the fail-closed `'unavailable'` + * (exactly today's behavior). + * - `'never'` — never prompt anyone: every ask resolves `'rejected'` + * deterministically. The strict headless stance (CI, unattended runs) and + * the only policy value stated in the system prompt — unlike `'ask'`, its + * outcome is knowable without asking, so stating it cannot overclaim. + */ +export type ApprovalPolicy = 'ask' | 'never' + +/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */ +export const APPROVAL_POLICIES: readonly ApprovalPolicy[] = ['ask', 'never'] + +/** + * The prompt sentence stating a `'never'` policy — visibility for the one + * deterministic policy (see {@link ApprovalPolicy}). Narrator persistence + * does NOT parse this prose: deployments can quote it in a persona or another + * section, so the section also emits a source-owned marker. + */ +const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).' + +/** Source-owned prompt markers used to reconstruct the policy in a logged header. */ +const POLICY_MARKERS = { + ask: '', + never: '', +} as const satisfies Record + +/** + * Read the policy fact emitted by this service from a logged system prompt. + * The section is ordered after deployment persona text, and the last marker + * wins so a persona quoting an earlier marker cannot shadow the service's own + * contribution. Ordinary policy prose is deliberately ignored. + */ +function toldApprovalPolicy(system: string | undefined): ApprovalPolicy | undefined { + if (system === undefined) return undefined + const ask = system.lastIndexOf(POLICY_MARKERS.ask) + const never = system.lastIndexOf(POLICY_MARKERS.never) + if (ask < 0 && never < 0) return undefined + return never > ask ? 'never' : 'ask' +} + +/** + * The session's approval-policy override: the last `approval/policy` event in + * the log, or undefined when the session never switched (callers apply the + * plugin's configured default). The pure fold — resume needs no catch-up + * machinery because replaying the log IS the state. + * @param events - session events in log order (other event types are skipped). + * @returns the policy of the last switch event, or undefined without one. + */ +export function effectiveApprovalPolicy(events: readonly SessionEvent[]): ApprovalPolicy | undefined { + for (let index = events.length - 1; index >= 0; index -= 1) { + const event = events[index] as SessionEvent + if (event.type === 'approval/policy') return event.data.policy + } + return undefined +} + +/** + * Whether the log currently sits inside an open turn (a `turn/start` not yet + * closed by a `turn/end`) — the {@link ApprovalService.request} precondition. + * The audit pair must be turn-enclosed: the turn is the durable log's + * commit/replay boundary, so a bare event appended between turns is + * indistinguishable from a crash tail and silently dropped on reload. + */ +function hasOpenTurn(events: readonly SessionEvent[]): boolean { + for (let index = events.length - 1; index >= 0; index -= 1) { + const type = (events[index] as SessionEvent).type + if (type === 'turn/start') return true + if (type === 'turn/end') return false + } + return false +} + +/** + * THE write path for a session's approval-policy override: appends exactly + * one `approval/policy` event — the switch IS its event; nothing mutates + * policy state out of band. Takes effect on the session's next ask and next + * prompt assembly (the consumers fold on every read). + * @param session - the session the override belongs to. + * @param policy - the policy every subsequent ask for this session resolves + * under (until the next switch). + */ +export function setApprovalPolicy(session: Session, policy: ApprovalPolicy): void { + session.append('approval/policy', { policy }) +} + +/** + * One concrete permission question. Identifies the action precisely enough + * for an answerer to present it and for the audit events to reconstruct what + * was asked — it deliberately does NOT carry tool arguments: a UI answerer + * attaches the prompt to the already-streamed tool call via `callId` instead + * of re-rendering the call. + */ +export interface ApprovalRequest { + /** + * The agent on whose behalf the question is asked. Routes the question (a + * UI answerer only answers for agents it owns) and receives the audit + * events on its session log. + */ + agent: Agent + /** The tool the question is about (presentation and audit). */ + toolName: string + /** + * The exact tool call being decided, when the asker has one — lets a UI + * attach the prompt to the tool call it already streamed. + */ + callId?: CallId + /** The asker's human-readable explanation of WHY it is asking. */ + reason?: string + /** + * Aborting withdraws the question: the request settles `'cancelled'` + * immediately and a late answer from a still-pending answerer is discarded. + */ + signal?: AbortSignal +} + +/** Plugin config. All optional — `static Config` supplies the defaults. */ +export interface Config { + /** + * The deployment's default {@link ApprovalPolicy} for sessions without an + * `approval/policy` override — `'ask'` delegates to the composed answerers + * (fail-closed with none); `'never'` auto-rejects every ask without + * prompting (the deterministic CI/unattended stance). + */ + policy?: ApprovalPolicy +} + +/** + * The `ctx.approval` service: dispatches {@link ApprovalRequest}s to the + * `approval/request` waterfall and audits every ask/outcome pair to the + * requesting agent's session log. Stateless between requests — grants are + * returned to the caller, never stored here. + * + * Owns the policy tier too (`effective = fold(the session's 'approval/policy' + * events) ?? config.policy`): `request()` resolves `'never'` to `'rejected'` + * before dispatching any interactive answerer, a per-agent prompt section + * states a `'never'` policy (and only that one in prose — an `'ask'` promise + * could overclaim an answerer that headless compositions do not have), and an + * `agent/pre-step` narrator injects at most one coalesced notice when a + * session's effective policy moved past what the model was last told. + */ +export class ApprovalService extends Service { + static Config: z = z.object({ + policy: z.union(['ask', 'never'] as const).default('ask'), + }) + + constructor(ctx: Context, public config: Config) { + super(ctx, 'approval') + + const effective = (agent: Agent): ApprovalPolicy => this.effectivePolicy(agent) + + // Visibility layer 1, scoped on the prompt registry so headless + // compositions mount the seam without it: state the one deterministic + // policy per session. 'ask' renders only a source-owned state marker — + // stating "you will be asked" would overclaim in a composition with no + // answerer. The marker, not deployment-controlled prose, is what the + // restart narrator reads back from the logged request header. + ctx.inject(['systemPrompt'], (scope: Context) => { + scope.systemPrompt.section({ + name: 'approval:policy', + order: 115, + text: (context) => { + const agent = context.agent + // A bare assemble() (tests, diagnostics) has no session to state. + if (agent === undefined) return '' + const policy = effective(agent) + return policy === 'never' ? `${NEVER_SENTENCE}\n${POLICY_MARKERS.never}` : POLICY_MARKERS.ask + }, + }) + }) + + // Visibility layer 2: the boundary narrator. pre-step runs after prompt + // assembly but before the request history is derived, so the notice is + // seen by THIS step's request: idle-time flip-flops coalesce at the + // turn's first step (net-zero → nothing), and a mid-turn switch is + // narrated no later than the next step. What each session was last told + // is in-memory with a log-derived fallback (the folded header's system + // text), so restarts lose nothing. Attribution is positional: an + // override event after the log's last `request/header*` was a runtime + // switch by the user; otherwise the configured default moved under the + // session (operator/config). + const narrated = new WeakMap() + ctx.on('agent/pre-step', (agent) => { + const session = agent.session + const events = session.events + let overrideIndex = -1 + let headerIndex = -1 + for (let index = events.length - 1; index >= 0 && (overrideIndex < 0 || headerIndex < 0); index -= 1) { + const event = events[index] as (typeof events)[number] + if (overrideIndex < 0 && event.type === 'approval/policy') { + overrideIndex = index + } else if (headerIndex < 0 && (event.type === 'request/header' || event.type === 'request/header-delta')) { + headerIndex = index + } + } + // Same fold effectivePolicy performs — override is scanned here anyway + // for POSITIONAL attribution; the default lives once, in the method. + const current = this.effectivePolicy(agent) + const header = session.requestHeader() + const told = narrated.get(session) ?? toldApprovalPolicy(header?.system) + narrated.set(session, current) + // Cold start (nothing ever told) narrates nothing — the section about + // to go out states the truth, and there is no delta to explain. + if (told === undefined || told === current) return + const cause = overrideIndex > headerIndex ? 'changed by the user' : 'changed by the operator/config' + agent.inject( + [{ type: 'text', text: `The approval policy changed from "${told}" to "${current}" (${cause}).` }], + { source: { kind: 'plugin', plugin: 'user-approval' } }, + ) + }) + } + + /** + * Ask the composed answerers to decide one request. Requires an open turn + * on the requesting agent's session — the audit pair below is turn-enclosed + * by contract (the turn is the log's commit/replay boundary; an idle append + * would be dropped as crash tail on reload) — and throws before appending + * anything when called idle; asking outside a turn is a deferred design. + * Within that precondition it always resolves to an outcome, never rejects: + * an aborted signal yields `'cancelled'`, a missing or throwing answerer + * yields `'unavailable'` (fail closed), and a rogue non-vocabulary return + * value is normalized to `'unavailable'`. Appends the + * `approval/asked`/`approval/decided` audit pair (log-only) around the + * decision regardless of outcome. + * @param req - the pending decision (agent, tool identity, reason, signal). + * @returns the closed outcome; `'allowed-once'` is the only grant. + */ + async request(req: ApprovalRequest): Promise { + if (!hasOpenTurn(req.agent.session.events)) { + throw new Error( + 'approval.request() outside an open turn: the approval/asked + approval/decided audit pair ' + + 'must be turn-enclosed (a bare event between turns is crash-tail garbage on reload). ' + + 'Ask from inside the turn that needs the decision.', + ) + } + const id = ApprovalRequestId(randomUUID()) + req.agent.session.append('approval/asked', { + id, + toolName: req.toolName, + ...req.callId !== undefined ? { callId: req.callId } : {}, + ...req.reason !== undefined ? { reason: req.reason } : {}, + }) + const outcome = await this.decide(req) + req.agent.session.append('approval/decided', { id, outcome }) + return outcome + } + + /** + * The session's effective policy: its own `approval/policy` fold, else the + * configured default (the schema already defaulted an omitted policy to + * `'ask'`; the `??` only narrows the optional-input TYPE). + * @param agent - the agent whose session's policy applies. + * @returns the policy every ask for this agent resolves under right now. + */ + private effectivePolicy(agent: Agent): ApprovalPolicy { + return effectiveApprovalPolicy(agent.session.events) ?? this.config.policy ?? 'ask' + } + + /** Dispatch the waterfall, contained and raced against `req.signal`. */ + private async decide(req: ApprovalRequest): Promise { + if (req.signal?.aborted) return 'cancelled' + // The 'never' policy is decided HERE, before any dispatch: a listener + // registered with `prepend: true` after this service mounts would sit + // ahead of any gate LISTENER, so a listener-shaped gate cannot keep the + // documented promise that 'never' rejects deterministically regardless + // of registration order — only the service's own request path can. + if (this.effectivePolicy(req.agent) === 'never') return 'rejected' + // Enter the promise chain BEFORE dispatching: a listener that throws + // SYNCHRONOUSLY (before its first await) must land in the same rejection + // path as an async one — `Promise.resolve(call())` would let it escape + // the containment into the caller. + const answer: Promise = Promise.resolve().then( + () => this.ctx.waterfall(this, 'approval/request', req, () => Promise.resolve('unavailable')), + ).then( + // Normalize a rogue (non-vocabulary) answerer return to the fail-closed + // outcome instead of leaking it into callers' closed-union switches. + outcome => OUTCOMES.includes(outcome) ? outcome : 'unavailable', + // A throwing answerer must fail the QUESTION closed, not the caller's + // tool call open — the seam contains its callbacks. + () => 'unavailable', + ) + const signal = req.signal + if (signal === undefined) return answer + return await new Promise((resolve) => { + const onAbort = () => { resolve('cancelled') } + signal.addEventListener('abort', onAbort, { once: true }) + void answer.then((outcome) => { + signal.removeEventListener('abort', onAbort) + // After an abort won the race this resolve is a settled-promise no-op: + // the late answer is discarded by construction. + resolve(outcome) + }) + }) + } +} + +export default ApprovalService diff --git a/packages/ui/user-approval/tests/approval.spec.ts b/packages/ui/user-approval/tests/approval.spec.ts new file mode 100644 index 0000000000..891f3eb4a1 --- /dev/null +++ b/packages/ui/user-approval/tests/approval.spec.ts @@ -0,0 +1,424 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { CallId } from '@deepseek-ai/dsh-llm' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ApprovalService, { ApprovalOutcome, ApprovalRequest, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-user-approval' + +/** + * A minimal Agent stand-in — the service only reaches `agent.session.append` + * and folds `.events`. Seeded inside an open turn by default (request()'s + * turn-enclosure precondition); pass `seed` to stage idle/closed logs. + * Returns the recorded audit appends alongside the fake. + */ +function fakeAgent(seed: Array<{ type: string }> = [{ type: 'turn/start' }, { type: 'user/message' }]): { agent: Agent; appended: Array<{ type: string; data: Record }> } { + const appended: Array<{ type: string; data: Record }> = [] + const agent = { + session: { + events: seed, + append: (type: string, data: Record) => { + appended.push({ type, data }) + return { type, data } as unknown as SessionEvent + }, + }, + } as unknown as Agent + return { agent, appended } +} + +async function mounted(): Promise { + const ctx = new Context() + await ctx.plugin(ApprovalService) + return ctx +} + +function requestOf(agent: Agent, overrides: Partial = {}): ApprovalRequest { + return { agent, toolName: 'echo', ...overrides } +} + +describe('ApprovalService.request', () => { + it('throws before appending anything when no turn has ever opened (idle ask)', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent([]) + + await expect(ctx.approval.request(requestOf(agent))).rejects.toThrow(/outside an open turn/) + expect(appended).toHaveLength(0) + }) + + it('throws between turns — a closed turn does not satisfy the enclosure precondition', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent([{ type: 'turn/start' }, { type: 'turn/end' }]) + + await expect(ctx.approval.request(requestOf(agent))).rejects.toThrow(/outside an open turn/) + expect(appended).toHaveLength(0) + }) + + it('fails closed to unavailable when nobody listens, auditing the asked/decided pair', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent() + + const outcome = await ctx.approval.request(requestOf(agent, { callId: CallId('call-1'), reason: 'hook says ask' })) + + expect(outcome).toBe('unavailable') + expect(appended.map(e => e.type)).toEqual(['approval/asked', 'approval/decided']) + const [asked, decided] = appended + expect(asked?.data).toMatchObject({ toolName: 'echo', callId: 'call-1', reason: 'hook says ask' }) + expect(decided?.data).toMatchObject({ outcome: 'unavailable' }) + expect(decided?.data['id']).toBe(asked?.data['id']) + }) + + it('omits absent optional fields from the asked audit event', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent() + + await ctx.approval.request(requestOf(agent)) + + expect(Object.keys(appended[0]?.data ?? {}).sort()).toEqual(['id', 'toolName']) + }) + + it('returns the first answering listener outcome (single decision slot)', async () => { + const ctx = await mounted() + const { agent } = fakeAgent() + let secondRan = false + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + ctx.on('approval/request', () => { + secondRan = true + return Promise.resolve('rejected') + }) + + await expect(ctx.approval.request(requestOf(agent))).resolves.toBe('allowed-once') + expect(secondRan).toBe(false) + }) + + it('lets a non-owning listener delegate via next() down to the fail-closed default', async () => { + const ctx = await mounted() + const { agent } = fakeAgent() + ctx.on('approval/request', (_req, next) => next()) + + await expect(ctx.approval.request(requestOf(agent))).resolves.toBe('unavailable') + }) + + it('contains a throwing answerer as unavailable', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent() + ctx.on('approval/request', () => Promise.reject(new Error('transport died'))) + + await expect(ctx.approval.request(requestOf(agent))).resolves.toBe('unavailable') + expect(appended[1]?.data).toMatchObject({ outcome: 'unavailable' }) + }) + + it('normalizes a rogue non-vocabulary answer to unavailable', async () => { + const ctx = await mounted() + const { agent } = fakeAgent() + // A JS answerer can return anything; the seam must not leak it into + // callers' closed-union switches. + ctx.on('approval/request', () => Promise.resolve('yolo' as ApprovalOutcome)) + + await expect(ctx.approval.request(requestOf(agent))).resolves.toBe('unavailable') + }) + + it('settles cancelled immediately on an already-aborted signal without asking anyone', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent() + let asked = false + ctx.on('approval/request', () => { + asked = true + return Promise.resolve('allowed-once') + }) + + const outcome = await ctx.approval.request(requestOf(agent, { signal: AbortSignal.abort() })) + + expect(outcome).toBe('cancelled') + expect(asked).toBe(false) + expect(appended.map(e => e.type)).toEqual(['approval/asked', 'approval/decided']) + expect(appended[1]?.data).toMatchObject({ outcome: 'cancelled' }) + }) + + it('resolves cancelled when the signal aborts mid-question and discards the late answer', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent() + let settleLate: ((outcome: ApprovalOutcome) => void) | undefined + ctx.on('approval/request', () => new Promise((resolve) => { settleLate = resolve })) + const controller = new AbortController() + + const pending = ctx.approval.request(requestOf(agent, { signal: controller.signal })) + controller.abort() + await expect(pending).resolves.toBe('cancelled') + + // The answerer settles after the fact: no second decided event appears. + settleLate?.('allowed-once') + await Promise.resolve() + expect(appended.filter(e => e.type === 'approval/decided')).toHaveLength(1) + expect(appended[1]?.data).toMatchObject({ outcome: 'cancelled' }) + }) + + it('discards a late REJECTION after abort without an unhandled rejection', async () => { + const ctx = await mounted() + const { agent } = fakeAgent() + let rejectLate: ((error: Error) => void) | undefined + ctx.on('approval/request', () => new Promise((_resolve, reject) => { rejectLate = reject })) + const controller = new AbortController() + + const pending = ctx.approval.request(requestOf(agent, { signal: controller.signal })) + controller.abort() + await expect(pending).resolves.toBe('cancelled') + + rejectLate?.(new Error('answered too late')) + // Drain microtasks: the contained rejection must not escape the seam. + await new Promise((resolve) => { setTimeout(resolve, 0) }) + }) + + it('resolves the answer when the signal never aborts', async () => { + const ctx = await mounted() + const { agent } = fakeAgent() + ctx.on('approval/request', () => Promise.resolve('rejected')) + const controller = new AbortController() + + await expect(ctx.approval.request(requestOf(agent, { signal: controller.signal }))).resolves.toBe('rejected') + }) + + it('issues a fresh id per request', async () => { + const ctx = await mounted() + const { agent, appended } = fakeAgent() + + await ctx.approval.request(requestOf(agent)) + await ctx.approval.request(requestOf(agent)) + + const ids = appended.filter(e => e.type === 'approval/asked').map(e => e.data['id']) + expect(ids).toHaveLength(2) + expect(ids[0]).not.toBe(ids[1]) + }) + + it('drops a disposed plugin listener from the chain (HMR safety)', async () => { + const ctx = await mounted() + const { agent } = fakeAgent() + const fiber = await ctx.plugin((inner: Context) => { + inner.on('approval/request', () => Promise.resolve('allowed-once')) + }) + await expect(ctx.approval.request(requestOf(agent))).resolves.toBe('allowed-once') + + await fiber.dispose() + await expect(ctx.approval.request(requestOf(agent))).resolves.toBe('unavailable') + }) +}) + +describe('approval policy (the approval/policy fold)', () => { + const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).' + const ASK_MARKER = '' + const NEVER_MARKER = '' + + /** + * An agent stand-in over a REAL Session — gate, section, and narrator fold + * real events; the opened turn satisfies request()'s enclosure precondition. + */ + function sessionAgent(id: string): { agent: Agent; session: Session; injected: string[] } { + const session = new Session(SessionId(id)) + session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + const injected: string[] = [] + const agent = { + id, + session, + inject: (content: { type: string; text: string }[]) => { injected.push(content[0]?.text ?? '') }, + } as unknown as Agent + return { agent, session, injected } + } + + const preStep = (ctx: Context, agent: Agent): Promise => + ctx.serial('agent/pre-step', agent, 1, 1, '', [], new AbortController().signal) + + /** Append a `request/header` snapshot whose system text is exactly `system`. */ + function appendHeader(session: Session, system: string): void { + session.append('request/header', { header: { config: { model: 'mock' }, system }, reason: 'initial' }) + } + + it('folds to the last event, or undefined without one', () => { + const { session } = sessionAgent('sess-fold') + expect(effectiveApprovalPolicy(session.events)).toBeUndefined() + setApprovalPolicy(session, 'never') + setApprovalPolicy(session, 'ask') + expect(effectiveApprovalPolicy(session.events)).toBe('ask') + expect(session.events.at(-1)).toMatchObject({ type: 'approval/policy', data: { policy: 'ask' } }) + }) + + it('defaults a schema-less construction to ask (the ?? narrows the optional TYPE)', async () => { + // Direct construction bypasses the plugin schema (the SystemPrompt-test + // precedent for covering a defaulted Config field's type-narrowing ??). + const ctx = new Context() + const service = new ApprovalService(ctx, {}) + const { agent } = sessionAgent('sess-bare-config') + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + await expect(service.request({ agent, toolName: 'echo' })).resolves.toBe('allowed-once') + }) + + it('contains an answerer that throws SYNCHRONOUSLY as unavailable', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService) + const { agent } = sessionAgent('sess-syncthrow') + ctx.on('approval/request', () => { throw new Error('sync bug') }) + await expect(ctx.approval.request({ agent, toolName: 'echo' })).resolves.toBe('unavailable') + }) + + it('a never config rejects deterministically without consulting any answerer', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService, { policy: 'never' }) + const consulted = vi.fn() + ctx.on('approval/request', (_req, next) => { consulted(); return next() }) + const { agent, session } = sessionAgent('sess-gate-1') + await expect(ctx.approval.request({ agent, toolName: 'bash' })).resolves.toBe('rejected') + expect(consulted).not.toHaveBeenCalled() + // The audit pair still lands on the session log. + expect(session.events.filter(e => e.type === 'approval/asked')).toHaveLength(1) + expect(session.events.filter(e => e.type === 'approval/decided')).toHaveLength(1) + }) + + it('the gate decides FIRST even against an answerer registered before the service (prepend)', async () => { + const ctx = new Context() + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + await ctx.plugin(ApprovalService, { policy: 'never' }) + const { agent } = sessionAgent('sess-gate-2') + await expect(ctx.approval.request({ agent, toolName: 'bash' })).resolves.toBe('rejected') + }) + + it('never is unbypassable even by an answerer PREPENDED after the service mounts', async () => { + // Cordis prepend unshifts ahead of every existing listener, including + // any gate LISTENER the service could register — which is exactly why + // the 'never' decision lives inside request() instead. The eager grant + // below must never be consulted. + const ctx = new Context() + await ctx.plugin(ApprovalService, { policy: 'never' }) + const consulted = vi.fn() + ctx.on('approval/request', () => { consulted(); return Promise.resolve('allowed-once') }, { prepend: true }) + const { agent, appended } = fakeAgent() + await expect(ctx.approval.request(requestOf(agent))).resolves.toBe('rejected') + expect(consulted).not.toHaveBeenCalled() + expect(appended.map(e => e.type)).toEqual(['approval/asked', 'approval/decided']) + }) + + it('a session override outranks the configured default, in both directions', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService, { policy: 'never' }) + ctx.on('approval/request', () => Promise.resolve('allowed-once')) + const { agent, session } = sessionAgent('sess-gate-3') + setApprovalPolicy(session, 'ask') + await expect(ctx.approval.request({ agent, toolName: 'bash' })).resolves.toBe('allowed-once') + setApprovalPolicy(session, 'never') + await expect(ctx.approval.request({ agent, toolName: 'bash' })).resolves.toBe('rejected') + }) + + it('states never (and only never) in prose while recording either policy with a source-owned marker', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ApprovalService) + const askAgent = sessionAgent('sess-sect-ask').agent + const { agent: neverAgent, session } = sessionAgent('sess-sect-never') + setApprovalPolicy(session, 'never') + const sectionFor = async (context: object) => + (await ctx.systemPrompt.assemble(context)).sections.find(s => s.name === 'approval:policy')?.text + expect(await sectionFor({ agent: askAgent })).toBe(ASK_MARKER) + expect(await sectionFor({ agent: neverAgent })).toBe(`${NEVER_SENTENCE}\n${NEVER_MARKER}`) + // A bare assemble (no agent) has no session to state. + expect(await sectionFor({})).toBe('') + }) + + it('narrates nothing cold, once per coalesced switch (user wording), and idempotently', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService) + const { agent, session, injected } = sessionAgent('sess-narr-1') + await preStep(ctx, agent) + expect(injected).toEqual([]) + setApprovalPolicy(session, 'never') + setApprovalPolicy(session, 'ask') + setApprovalPolicy(session, 'never') + await preStep(ctx, agent) + expect(injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).']) + await preStep(ctx, agent) + expect(injected).toHaveLength(1) + setApprovalPolicy(session, 'ask') + setApprovalPolicy(session, 'never') + await preStep(ctx, agent) + expect(injected).toHaveLength(1) + }) + + it('reads what the model was told back from the folded header text after a restart', async () => { + // A session whose last request carried the never sentence resumes under + // an ask default: the narrator attributes the change to the operator. + const ctx = new Context() + await ctx.plugin(ApprovalService) + const { agent, session, injected } = sessionAgent('sess-narr-2') + appendHeader(session, `persona\n\n${NEVER_SENTENCE}\n${NEVER_MARKER}`) + await preStep(ctx, agent) + expect(injected).toEqual(['The approval policy changed from "never" to "ask" (changed by the operator/config).']) + }) + + it('narrates a config default drift from the logged ask marker', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService, { policy: 'never' }) + const { agent, session, injected } = sessionAgent('sess-narr-3') + appendHeader(session, `persona only\n${ASK_MARKER}`) + await preStep(ctx, agent) + expect(injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the operator/config).']) + }) + + it('a pinned override survives a default change silently', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService, { policy: 'never' }) + const { agent, session, injected } = sessionAgent('sess-narr-4') + appendHeader(session, `persona only\n${ASK_MARKER}`) + setApprovalPolicy(session, 'ask') + appendHeader(session, `persona only\n${ASK_MARKER}`) + await preStep(ctx, agent) + expect(injected).toEqual([]) + }) + + it('does not infer never from deployment prose that quotes the never sentence', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService) + const { agent, session, injected } = sessionAgent('sess-narr-spoof-prose') + appendHeader(session, `persona quotes this warning: ${NEVER_SENTENCE}\n${ASK_MARKER}`) + await preStep(ctx, agent) + expect(injected).toEqual([]) + }) + + it('treats a legacy header with no source-owned marker as untold', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService, { policy: 'never' }) + const { agent, session, injected } = sessionAgent('sess-narr-unmarked-header') + appendHeader(session, 'legacy persona-only header') + await preStep(ctx, agent) + expect(injected).toEqual([]) + }) + + it('uses the service marker after an earlier persona marker', async () => { + const ctx = new Context() + await ctx.plugin(ApprovalService) + const { agent, session, injected } = sessionAgent('sess-narr-spoof-marker') + appendHeader(session, `persona quotes ${NEVER_MARKER}\n${ASK_MARKER}`) + await preStep(ctx, agent) + expect(injected).toEqual([]) + }) + + it('disposes the service prompt section and pre-step narrator together (HMR safety)', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + const fiber = await ctx.plugin(ApprovalService) + const live = sessionAgent('sess-hmr-service-live') + const afterDispose = sessionAgent('sess-hmr-service-disposed') + const sectionFor = async () => + (await ctx.systemPrompt.assemble({ agent: live.agent })).sections.find(section => section.name === 'approval:policy') + expect(await sectionFor()).toBeDefined() + + appendHeader(live.session, `persona\n${ASK_MARKER}`) + setApprovalPolicy(live.session, 'never') + await preStep(ctx, live.agent) + expect(live.injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).']) + + appendHeader(afterDispose.session, `persona\n${ASK_MARKER}`) + setApprovalPolicy(afterDispose.session, 'never') + await fiber.dispose() + + expect(await sectionFor()).toBeUndefined() + await preStep(ctx, afterDispose.agent) + expect(afterDispose.injected).toEqual([]) + }) +}) diff --git a/packages/ui/user-approval/tsconfig.json b/packages/ui/user-approval/tsconfig.json new file mode 100644 index 0000000000..2d834f075d --- /dev/null +++ b/packages/ui/user-approval/tsconfig.json @@ -0,0 +1,36 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../core/session" + }, + { + "path": "../../core/agent" + }, + { + "path": "../../core/system-prompt" + } + ] +} diff --git a/packages/workflow/workflow-workerthread/src/protocol.ts b/packages/workflow/workflow-workerthread/src/protocol.ts index ed6b54950a..f6e85ee509 100644 --- a/packages/workflow/workflow-workerthread/src/protocol.ts +++ b/packages/workflow/workflow-workerthread/src/protocol.ts @@ -112,4 +112,3 @@ export type WorkerToHostMessage = */ export type HostToWorkerMessage = { [K in T]: { type: K } & HostToWorkerPayloads[K] }[T] - diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index ecaeed61f6..75a0b5116e 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -15,6 +15,32 @@ function fakeParent(): Agent { return { id: AgentId('workflow-parent'), options: {} } as unknown as Agent } +// Worker-thread startup is CPU-bound (a fresh thread compiles the runtime on +// every start): on a contended CI runner it regularly blows past vitest's 5s +// default test timeout, observed repeatedly on the coverage lane. +vi.setConfig({ testTimeout: 30_000 }) + +/** + * `vi.waitFor` with a contention-proof default timeout: the 1s default + * flaked repeatedly on the CI coverage lane, where worker-thread cold start + * (CPU-bound — a fresh thread compiles the runtime) competes with three + * sibling vitest workers for CPU. The 10s default is for exactly those + * races — waiting for a worker to start, run its first script line, or + * deliver an async child-registration message to the host. It is NOT for a + * wait that asserts the HOST reacted PROMPTLY to something that already + * happened (a settled result, an observed worker death): those keep an + * explicit tight override below, or the generous default would silently + * accept a multi-second regression in host-side reap latency as passing + * (proven by injecting a 6s delay into one such reap and watching the + * un-overridden version of this helper still pass in ~6s). + * @param assertion - retried until it stops throwing or the timeout elapses. + * @param timeout - override for a wait that must stay deliberately tight. + * @returns resolves when the assertion passes. + */ +function waitFor(assertion: () => void, timeout = 10_000): Promise { + return vi.waitFor(assertion, { timeout, interval: 50 }) +} + /** The vm-context escape hatch, spelled once: real Worker tests use it to make the WORKER misbehave. */ const ESCAPE = "globalThis.constructor.constructor('return process')()" @@ -316,7 +342,7 @@ describe('dsh-workflow-workerthread', () => { const runEnds: WorkflowResultInfo[] = [] ctx.on('workflow/end', (_info, result) => { runEnds.push(result) }) const handle = ctx.workflows.start({ ...scripted("return await agent('long job')"), parent }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) handle.cancel('user stopped it') const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -357,7 +383,7 @@ describe('dsh-workflow-workerthread', () => { const controller = new AbortController() const second = ctx.workflows.start({ ...scripted("return await agent('job')"), parent, signal: controller.signal }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) controller.abort() expect((await second.result).stopReason).toBe('cancelled') await second.dispose() @@ -400,7 +426,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(narration).toContain('started') }) + await waitFor(() => { expect(narration).toContain('started') }) handle.cancel('raced the completion') const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -480,7 +506,7 @@ describe('dsh-workflow-workerthread', () => { }) const result = await handle.result expect(result.stopReason).toBe('completed') - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) await handle.dispose() // Not a waitFor: by the time dispose() returns, the slow child disposal // must already be complete (host-side registry quiescence). @@ -525,8 +551,11 @@ describe('dsh-workflow-workerthread', () => { const result = await handle.result expect(result.stopReason).toBe('completed') // BEFORE dispose(): the settlement itself must have aborted the signal — - // without it this child would stay live until dispose's terminate. - await vi.waitFor(() => { expect(aborted).toEqual(['workflow settled']) }) + // without it this child would stay live until dispose's terminate. This + // is a HOST-PROMPTNESS claim, not a cold-start race — a tight explicit + // bound (unlike the file default) so a multi-second reap regression + // cannot pass by outlasting the wait. + await waitFor(() => { expect(aborted).toEqual(['workflow settled']) }, 1000) await handle.dispose() }) @@ -572,9 +601,9 @@ describe('dsh-workflow-workerthread', () => { `), parent: fakeParent(), }) - await vi.waitFor(() => { expect(starts).toBe(1) }) + await waitFor(() => { expect(starts).toBe(1) }) handle.cancel('stop now') - await vi.waitFor(() => { expect(cancelled).toEqual(['stop now']) }, { timeout: 800 }) + await waitFor(() => { expect(cancelled).toEqual(['stop now']) }, 800) // The wedged worker's own completion loses to the in-flight cancel. const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -602,7 +631,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) const before = Date.now() await handle.dispose() // Bounded by the grace (plus the terminate), never by the 1.5s spin. @@ -625,7 +654,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) const handleDispose = handle.dispose() const result = await handle.result // The script itself settled (the wrapper's own dispose RPC found the @@ -663,7 +692,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) + await waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')! fast.settle(text('fast done')) handle.cancel('stop now') @@ -694,7 +723,7 @@ describe('dsh-workflow-workerthread', () => { ...scripted("await parallel([() => agent('a'), () => agent('b')])\nreturn 'unreachable'"), parent, }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) + await waitFor(() => { expect(provider.runs.length).toBe(2) }) handle.cancel('user stop') const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -749,7 +778,9 @@ describe('dsh-workflow-workerthread', () => { // A worker death is a stop reason like any other: workflow/end fires // with the error outcome — for a bus observer it is the only obituary. expect(runEnds).toEqual([{ stopReason: 'error', error: result.error, agentsStarted: 1 }]) - await vi.waitFor(() => { expect(cancelled.length).toBe(1) }) + // Result already settled — this is the reap's promptness, not a + // cold-start race; tight explicit bound (see the helper's doc comment). + await waitFor(() => { expect(cancelled.length).toBe(1) }, 1000) await handle.dispose() }, 15_000) @@ -770,10 +801,12 @@ describe('dsh-workflow-workerthread', () => { expect(result.stopReason).toBe('error') expect(result.error).toContain('worker blew up') // The reap wound the stray child down (cancel + a CLEAN dispose). - await vi.waitFor(() => { + // Result already settled — this is the reap's promptness, not a + // cold-start race; tight explicit bound (see the helper's doc comment). + await waitFor(() => { expect(provider.runs.length).toBe(1) expect(provider.runs[0]!.disposed).toBe(true) - }) + }, 1000) await handle.dispose() }, 15_000) @@ -802,7 +835,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) + await waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')! fast.settle(text('fast done')) const result = await handle.result @@ -837,7 +870,10 @@ describe('dsh-workflow-workerthread', () => { const result = await handle.result expect(result.stopReason).toBe('error') expect(result.error).toContain('exit code 5') - await vi.waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) }) + // Result already settled — this is the reap's promptness (bounded + // above the mock's fixed 300ms dispose delay, not a cold-start race); + // tight explicit bound (see the helper's doc comment). + await waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) }, 1000) await handle.dispose() }, 15_000) @@ -855,7 +891,7 @@ describe('dsh-workflow-workerthread', () => { }) const logs: string[] = [] ctx.on('workflow/log', (_info, message) => { logs.push(message) }) - await vi.waitFor(() => { expect(logs).toContain('armed') }) + await waitFor(() => { expect(logs).toContain('armed') }) handle.cancel('stop it') // The grace is deliberately huge: only the worker's own death (exit 3, // unreachable by the cancel — the script ignores hooks) settles this. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b42cd5dae0..236f2ec4af 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -75,11 +75,42 @@ importers: specifier: ^4.1.8 version: 4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)) + packages/ui/user-approval: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/bash/bash: devDependencies: '@deepseek-ai/dsh-brand': specifier: workspace:^ version: link:../../util/brand + '@deepseek-ai/dsh-sandbox': + specifier: workspace:^ + version: link:../../sandbox/sandbox + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -100,6 +131,31 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/bash/bash-sandbox: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-bash': + specifier: workspace:^ + version: link:../bash + '@deepseek-ai/dsh-bash-local': + specifier: workspace:^ + version: link:../bash-local + '@deepseek-ai/dsh-sandbox': + specifier: workspace:^ + version: link:../../sandbox/sandbox + '@deepseek-ai/dsh-sandbox-local': + specifier: workspace:^ + version: link:../../sandbox/sandbox-local + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + node-addon-landlock-run: + specifier: 0.0.0-test.0 + version: 0.0.0-test.0 + packages/bash/tool-bash: devDependencies: '@deepseek-ai/dsh-agent': @@ -108,15 +164,27 @@ importers: '@deepseek-ai/dsh-agent-loop': specifier: workspace:^ version: link:../../core/agent-loop + '@deepseek-ai/dsh-user-approval': + specifier: workspace:^ + version: link:../../ui/user-approval '@deepseek-ai/dsh-bash': specifier: workspace:^ version: link:../bash '@deepseek-ai/dsh-bash-local': specifier: workspace:^ version: link:../bash-local + '@deepseek-ai/dsh-bash-sandbox': + specifier: workspace:^ + version: link:../bash-sandbox '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm + '@deepseek-ai/dsh-sandbox': + specifier: workspace:^ + version: link:../../sandbox/sandbox + '@deepseek-ai/dsh-sandbox-local': + specifier: workspace:^ + version: link:../../sandbox/sandbox-local '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session @@ -273,12 +341,21 @@ importers: '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../session + '@deepseek-ai/dsh-skill': + specifier: workspace:^ + version: link:../../skill/skill + '@deepseek-ai/dsh-skill-local': + specifier: workspace:^ + version: link:../../skill/skill-local '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../system-prompt '@deepseek-ai/dsh-tool-bash': specifier: workspace:^ version: link:../../bash/tool-bash + '@deepseek-ai/dsh-tool-skill': + specifier: workspace:^ + version: link:../../skill/tool-skill '@deepseek-ai/dsh-tools': specifier: workspace:^ version: link:../tools @@ -354,6 +431,9 @@ importers: '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../agent + '@deepseek-ai/dsh-user-approval': + specifier: workspace:^ + version: link:../../ui/user-approval '@deepseek-ai/dsh-code-runtime': specifier: workspace:^ version: link:../../code-runtime/code-runtime @@ -623,6 +703,34 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/sandbox/sandbox: + devDependencies: + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + + packages/sandbox/sandbox-local: + dependencies: + node-addon-landlock-run: + specifier: 0.0.0-test.0 + version: 0.0.0-test.0 + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-sandbox': + specifier: workspace:^ + version: link:../sandbox + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/session-persistence/session-persistence: devDependencies: '@deepseek-ai/dsh-session': @@ -664,6 +772,60 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/skill/skill: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + + packages/skill/skill-local: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + yaml: + specifier: ^2.4.2 + version: 2.9.0 + devDependencies: + '@deepseek-ai/dsh-fs': + specifier: workspace:^ + version: link:../../fs/fs + '@deepseek-ai/dsh-skill': + specifier: workspace:^ + version: link:../skill + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + + packages/skill/tool-skill: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-skill': + specifier: workspace:^ + version: link:../skill + '@deepseek-ai/dsh-skill-local': + specifier: workspace:^ + version: link:../skill-local + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/subagent/subagent: devDependencies: '@deepseek-ai/dsh-agent': @@ -991,6 +1153,12 @@ importers: '@deepseek-ai/dsh-agent-loop': specifier: workspace:^ version: link:../../core/agent-loop + '@deepseek-ai/dsh-user-approval': + specifier: workspace:^ + version: link:../user-approval + '@deepseek-ai/dsh-bash': + specifier: workspace:^ + version: link:../../bash/bash '@deepseek-ai/dsh-bash-local': specifier: workspace:^ version: link:../../bash/bash-local @@ -1000,9 +1168,15 @@ importers: '@deepseek-ai/dsh-fs-policy': specifier: workspace:^ version: link:../../fs/fs-policy + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../support/invariants '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm + '@deepseek-ai/dsh-sandbox': + specifier: workspace:^ + version: link:../../sandbox/sandbox '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session @@ -3777,6 +3951,22 @@ packages: natural-compare@1.4.0: resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==} + node-addon-landlock-run-linux-arm64@0.0.0-test.0: + resolution: {integrity: sha512-oJsXcC33qKl9mWYx0n9YPJ2pUAoY39PoIX0Gx4lDrSCTEvENFrEaODAsQYNY+eEGpn9YMN7E+FOftvea3/1FqQ==} + engines: {node: '>=20'} + cpu: [arm64] + os: [linux] + + node-addon-landlock-run-linux-x64@0.0.0-test.0: + resolution: {integrity: sha512-eXvdfnH/UV55MTZzroKvM3CD68SP5OlCsuth908YOcJOnn0LPD5KJjmBz6ToDlBYjF52NNK62+g7TvmUWjbKWQ==} + engines: {node: '>=20'} + cpu: [x64] + os: [linux] + + node-addon-landlock-run@0.0.0-test.0: + resolution: {integrity: sha512-c5qopltRonjW6+VinXYMp4FVi9Sxf8eQEb/9G82EksQQ+JC4CDprv+ko5URWmtyZ3wD4GFdeRTyw1AG5yCwJhQ==} + engines: {node: '>=20'} + node-domexception@1.0.0: resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==} engines: {node: '>=10.5.0'} @@ -6783,6 +6973,17 @@ snapshots: natural-compare@1.4.0: {} + node-addon-landlock-run-linux-arm64@0.0.0-test.0: + optional: true + + node-addon-landlock-run-linux-x64@0.0.0-test.0: + optional: true + + node-addon-landlock-run@0.0.0-test.0: + optionalDependencies: + node-addon-landlock-run-linux-arm64: 0.0.0-test.0 + node-addon-landlock-run-linux-x64: 0.0.0-test.0 + node-domexception@1.0.0: {} node-fetch@3.3.2: diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index b2b731fc58..6407a99f52 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -19,3 +19,12 @@ allowBuilds: # need, so we deny them — install still succeeds. '@google/genai': false protobufjs: false + +# The Landlock launcher family is our own sibling-repo release, consumed +# fresh (hours old at each coordinated bump) — the release-age quarantine +# would block every such bump, so the family is exempted BY NAME, not by +# pinned version. +minimumReleaseAgeExclude: + - node-addon-landlock-run + - node-addon-landlock-run-linux-arm64 + - node-addon-landlock-run-linux-x64 diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index a5261698a2..2a6456eaf9 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,11 +1,11 @@ { "AGENTS.md": 1802, "docs/AGENTS.md": 1315, - "docs/architecture.md": 1642, + "docs/architecture.md": 1750, "docs/cordis-primer.md": 550, "docs/defensive-patterns.md": 550, "docs/testing.md": 800, - "examples/AGENTS.md": 653, + "examples/AGENTS.md": 705, "packages/AGENTS.md": 450, - "packages/README.md": 660 + "packages/README.md": 710 } diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts index eca36286ae..1cbcc007bd 100644 --- a/scripts/gen-config-catalog.ts +++ b/scripts/gen-config-catalog.ts @@ -633,11 +633,17 @@ export function collectConfigCatalog(scanRoot: string = root): CatalogEntry[] { const manifests: { dir: string; pkg: string }[] = [] for (const manifestRel of globSync('packages/*/*/package.json', { cwd: scanRoot }).sort()) { const dir = manifestRel.slice(0, -'/package.json'.length) - const pkg = (JSON.parse(readFileSync(resolve(scanRoot, manifestRel), 'utf8')) as { name?: string }).name + const manifest = JSON.parse(readFileSync(resolve(scanRoot, manifestRel), 'utf8')) as { name?: string; os?: string[]; cpu?: string[] } + const pkg = manifest.name if (!pkg) { violations.push(`${manifestRel} has no "name".`) continue } + if (manifest.os !== undefined && manifest.cpu !== undefined) { + // A per-platform native-binary package (npm os/cpu selection) ships no + // JavaScript at all — nothing to classify, no Config to catalog. + continue + } pkgDirByName.set(pkg, dir) manifests.push({ dir, pkg }) } diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 9b8141807e..7c6666542b 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -92,11 +92,17 @@ export const LINK_MAP: Record = { ToolDefinition: 'tools.md', ToolExecution: 'tools.md', ToolExecutionResult: 'tools.md', + ApprovalOutcome: 'approval.md', + ApprovalPolicy: 'approval.md', + ApprovalRequest: 'approval.md', BashExecRequest: 'bash.md', BashExecSpec: 'bash.md', BashRunResult: 'bash.md', BashTask: 'bash.md', BashTaskRead: 'bash.md', + ConfinedArgv: 'sandbox.md', + SandboxMode: 'sandbox.md', + SandboxPolicy: 'sandbox.md', CodeRunRequest: 'code-runtime.md', CodeRunResult: 'code-runtime.md', FsEditOutcome: 'filesystem.md', diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 610ff3f1ea..ec92045069 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -70,7 +70,9 @@ const GROUP_ORDER = [ 'llm', 'core', 'bash', + 'sandbox', 'fs', + 'skill', 'compact', 'subagent', 'web', @@ -122,7 +124,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'tools', title: 'Tool registry and execution waterfall', mode: 'core', - consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'], + consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-skill', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'], note: 'Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute.', }, { @@ -134,6 +136,15 @@ const SERVICE_ROLES: ServiceRole[] = [ consumers: ['tool-ask-user', 'stdio-agent', 'acp'], note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.', }, + { + key: 'skills', + pkg: 'skill', + title: 'Skill provider registry', + mode: 'seam', + implementations: ['skill-local'], + consumers: ['tool-skill'], + note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.', + }, { key: 'agents', pkg: 'agent', @@ -155,9 +166,27 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'bash', title: 'Bash executor seam', mode: 'seam', - implementations: ['bash-local'], + implementations: ['bash-local', 'bash-sandbox'], consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'], - note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local.', + note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them.', + }, + { + key: 'sandbox', + pkg: 'sandbox', + title: 'Process-sandbox seam', + mode: 'seam', + implementations: ['sandbox-local'], + consumers: ['bash-sandbox'], + 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.', + }, + { + key: 'approval', + pkg: 'approval', + title: 'Approval seam', + mode: 'seam', + implementations: ['acp'], + consumers: ['tools', 'tool-bash'], + note: 'One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`.', }, { key: 'codeRuntime', @@ -673,7 +702,8 @@ function renderToolPipeline(): string { ` toolCall["Session event: ${mermaidCode('tool/call')}
logged before execution"]`, ' presentCall["UI pending card
presentCall(args)"]', ` pre["${mermaidCode('tools/pre-execute')} waterfall
hooks, permission, sandbox"]`, - ' denied["deny or ask
tool body skipped"]', + ' denied["denied
tool body skipped"]', + ` approval["${mermaidCode('ctx.approval')} one-shot prompt
absent or unanswerable: deny"]`, ` around["${mermaidCode('tools/execute')} waterfall
timeout, retry, metrics (around dispatch)"]`, ' toolBody["Registered tool execute() body"]', ` fsGate["${mermaidCode('fs/write-intent')} or ${mermaidCode('fs/edit-intent')}
tool-fs mutations only"]`, @@ -687,7 +717,10 @@ function renderToolPipeline(): string { ' toolCall --> pre', ' pre -->|allow| around', ' around --> toolBody', - ' pre -->|deny or ask| denied', + ' pre -->|deny| denied', + ' pre -->|ask| approval', + ' approval -->|allowed-once| around', + ' approval -->|rejected, cancelled, unavailable| denied', ' denied --> post', ' toolBody --> fsGate', ' fsGate --> toolBody', @@ -699,7 +732,7 @@ function renderToolPipeline(): string { ' toolResult --> presentResult', '```', '', - 'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate; hook bridges and future permission prompts live on the generic pre/post tool waterfalls; and around-dispatch concerns like the tool-call timeout policy (`@deepseek-ai/dsh-timeout-policy`) wrap core dispatch on `tools/execute`. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. Code Mode rides the same pipeline twice over: `run_code` is itself a registered tool body, and each tool call its program makes re-enters `ctx.tools.execute()` through BOTH waterfalls — serialized one at a time, logged as a `tool/code-dispatch` session event, with a deny surfacing to the program as a binding rejection (a sub-call\'s `additionalContext` is deliberately dropped — no safe outlet mid-run preserves call/result adjacency).', + 'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate; hook bridges and the approval seam\'s permission prompts live on the generic pre/post tool waterfalls; and around-dispatch concerns like the tool-call timeout policy (`@deepseek-ai/dsh-timeout-policy`) wrap core dispatch on `tools/execute`. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service.', '', ...maintenanceFooter(maintenance), ].join('\n') diff --git a/scripts/gen-module-graph.ts b/scripts/gen-module-graph.ts index dc66dc843e..54dbcf2773 100644 --- a/scripts/gen-module-graph.ts +++ b/scripts/gen-module-graph.ts @@ -42,6 +42,7 @@ const GROUP_ORDER = [ 'core', 'bash', 'fs', + 'skill', 'compact', 'subagent', 'web', diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 62e40907b8..fddbd8867e 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -47,10 +47,13 @@ import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa' import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local' import SubagentService from '@deepseek-ai/dsh-subagent' import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock' +import SkillService from '@deepseek-ai/dsh-skill' +import * as SkillLocal from '@deepseek-ai/dsh-skill-local' import * as ToolAskUser from '@deepseek-ai/dsh-tool-ask-user' 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 ToolSkill from '@deepseek-ai/dsh-tool-skill' import * as ToolTodo from '@deepseek-ai/dsh-tool-todo' import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent' import * as ToolWeb from '@deepseek-ai/dsh-tool-web' @@ -180,6 +183,21 @@ const TOOL_PACKAGES: ToolPackage[] = [ note: 'The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin.', }, + { + pkg: '@deepseek-ai/dsh-tool-skill', + dir: 'tool-skill', + source: 'packages/skill/tool-skill/src/index.ts', + requires: ['ctx.tools', 'ctx.skills'], + writes: ['tool/call', 'tool/result'], + async mount(ctx) { + await ctx.plugin(SkillService) + await ctx.plugin(SkillLocal, { + dshHome: resolve(root, '.tmp/tool-catalog/.dsh'), + agentsHome: resolve(root, '.tmp/tool-catalog/.agents'), + }) + await ctx.plugin(ToolSkill) + }, + }, { pkg: '@deepseek-ai/dsh-tool-subagent', dir: 'tool-subagent', diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 9ee5a66ed6..ef1e07ea43 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -286,18 +286,28 @@ function demoSmokeGate(options: { needs?: string[] } = {}): Gate { ...dependencyOptions, verify: async (result) => { const output = result.stdout + result.stderr - if (!output.includes('[tool call] echo({"text":"ci smoke"})')) { - throw new Error('demo smoke did not show the echo tool call.') + const sessionsRoot = join(root, '.sessions') + try { + if (!output.includes('[tool call] echo({"text":"ci smoke"})')) { + throw new Error('demo smoke did not show the echo tool call.') + } + if (!output.includes('[tool result] ECHO: CI SMOKE')) { + throw new Error('demo smoke did not show the echo tool result.') + } + const buckets = await readdir(sessionsRoot, { withFileTypes: true }) + let found = false + for (const bucket of buckets) { + if (!bucket.isDirectory() || !bucket.name.startsWith('cwd-')) continue + const entries = await readdir(join(sessionsRoot, bucket.name)) + if (entries.some(entry => /^main-session-.+\.jsonl$/.test(entry))) { + found = true + break + } + } + if (!found) throw new Error('demo smoke did not create a main-session JSONL log in a cwd bucket.') + } finally { + await rm(sessionsRoot, { recursive: true, force: true }) } - if (!output.includes('[tool result] ECHO: CI SMOKE')) { - throw new Error('demo smoke did not show the echo tool result.') - } - const sessionDir = join(root, '.sessions', '_no-cwd') - const entries = await readdir(sessionDir) - if (!entries.some(entry => /^main-session-.+\.jsonl$/.test(entry))) { - throw new Error('demo smoke did not create a main-session JSONL log.') - } - await rm(join(root, '.sessions'), { recursive: true, force: true }) }, } } diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 937ca72a0d..df3bacd474 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -57,13 +57,25 @@ { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/ui/user-interaction/src/index.ts" }, { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/ui/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalRequestId", "source": "packages/ui/user-approval/src/index.ts" }, + { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalOutcome", "source": "packages/ui/user-approval/src/index.ts" }, + { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalPolicy", "source": "packages/ui/user-approval/src/index.ts" }, + { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalRequest", "source": "packages/ui/user-approval/src/index.ts" }, + { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" }, + { "doc": "docs/core-data-structures/bash.md", "symbol": "BashSandboxInfo", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "CollectedOutput", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTask", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTaskRead", "source": "packages/bash/bash/src/types.ts" }, + { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" }, + { "doc": "docs/core-data-structures/sandbox.md", "symbol": "ConfinedSandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" }, + { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxEnforcement", "source": "packages/sandbox/sandbox/src/index.ts" }, + { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxPolicy", "source": "packages/sandbox/sandbox/src/index.ts" }, + { "doc": "docs/core-data-structures/sandbox.md", "symbol": "ConfinedArgv", "source": "packages/sandbox/sandbox/src/index.ts" }, + { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunRequest", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunResult", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeBindingNamespace", "source": "packages/code-runtime/code-runtime/src/types.ts" }, @@ -84,6 +96,16 @@ { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsPolicyExec", "source": "packages/fs/fs-policy/src/types.ts" }, { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FileReadOutcome", "source": "packages/fs/tool-fs/src/read-render.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSource", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillResourceBase", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSummary", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillCandidate", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillDefinition", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillRegistration", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillLookupOptions", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillProvider", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/skills.md", "symbol": "Config", "source": "packages/skill/skill/src/index.ts" }, + { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" }, { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" }, diff --git a/tsconfig.base.json b/tsconfig.base.json index ddba51c53f..36401b77f7 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -45,6 +45,7 @@ "./packages/bash/*/src", "./packages/code-runtime/*/src", "./packages/fs/*/src", + "./packages/skill/*/src", "./packages/compact/*/src", "./packages/guard/*/src", "./packages/subagent/*/src", @@ -53,6 +54,7 @@ "./packages/timeout/*/src", "./packages/todo/*/src", "./packages/cordis/*/src", + "./packages/sandbox/*/src", "./packages/hooks/*/src", "./packages/session-persistence/*/src", "./packages/ui/*/src", diff --git a/tsconfig.build.json b/tsconfig.build.json index edbd2d742b..8b2967b2bf 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -20,7 +20,11 @@ { "path": "./packages/core/system-prompt" }, { "path": "./packages/core/agent" }, { "path": "./packages/ui/user-interaction" }, + { "path": "./packages/ui/user-approval" }, { "path": "./packages/core/tools" }, + { "path": "./packages/skill/skill" }, + { "path": "./packages/skill/skill-local" }, + { "path": "./packages/skill/tool-skill" }, { "path": "./packages/ui/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, { "path": "./packages/core/agent-core" }, @@ -32,6 +36,9 @@ { "path": "./packages/llm/llm-deepseek" }, { "path": "./packages/llm/llm-pi-ai" }, { "path": "./packages/bash/bash-local" }, + { "path": "./packages/sandbox/sandbox" }, + { "path": "./packages/sandbox/sandbox-local" }, + { "path": "./packages/bash/bash-sandbox" }, { "path": "./packages/bash/tool-bash" }, { "path": "./packages/fs/fs" }, { "path": "./packages/fs/fs-local" }, diff --git a/tsconfig.json b/tsconfig.json index 61d510437c..70780e1c17 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -31,7 +31,11 @@ { "path": "./packages/core/system-prompt" }, { "path": "./packages/core/agent" }, { "path": "./packages/ui/user-interaction" }, + { "path": "./packages/ui/user-approval" }, { "path": "./packages/core/tools" }, + { "path": "./packages/skill/skill" }, + { "path": "./packages/skill/skill-local" }, + { "path": "./packages/skill/tool-skill" }, { "path": "./packages/ui/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, { "path": "./packages/core/agent-core" }, @@ -41,6 +45,9 @@ { "path": "./packages/llm/llm-deepseek" }, { "path": "./packages/llm/llm-pi-ai" }, { "path": "./packages/bash/bash-local" }, + { "path": "./packages/sandbox/sandbox" }, + { "path": "./packages/sandbox/sandbox-local" }, + { "path": "./packages/bash/bash-sandbox" }, { "path": "./packages/bash/tool-bash" }, { "path": "./packages/fs/fs" }, { "path": "./packages/fs/fs-local" }, diff --git a/tsdown.config.ts b/tsdown.config.ts index 7b172180d1..9479c5c91d 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -12,7 +12,8 @@ import { defineConfig } from 'tsdown' export default defineConfig({ // Explicit globs: `workspace: true` would also discover examples (any // package.json), but only vendor and the packages hierarchy are pnpm - // workspaces. + // workspaces. The Landlock launcher platform packages ship a prebuilt + // native binary and no JavaScript — nothing to bundle. workspace: ['vendor/*', 'packages/*/*'], entry: ['lib/types/index.js'], outDir: 'lib', diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts index ecc8d911aa..d0a8ce6a54 100644 --- a/vitest.snapshot.config.ts +++ b/vitest.snapshot.config.ts @@ -7,10 +7,14 @@ import { defineConfig } from 'vitest/config' // normalized stdout transcript + re-persisted log against committed goldens. // `pnpm run test:snapshot:record` (DSH_SNAPSHOT=record + -u) re-records the // fixtures against the real API and refreshes the goldens. +// `pnpm run test:snapshot:refresh` (DSH_SNAPSHOT=refresh) stays keyless: it +// replays the committed model scripts and writes the current stdout/log goldens +// without calling the live LLM. // // Replay loads no .env (it must never reach the network — a recorded fixture -// drives the model). Record reads DEEPSEEK_API_KEY from the env or a gitignored -// repo-root .env, so a contributor with a key only in .env can still record. +// drives the model), and refresh uses that same keyless replay path. Record +// reads DEEPSEEK_API_KEY from the env or a gitignored repo-root .env, so a +// contributor with a key only in .env can still record. if (process.env.DSH_SNAPSHOT === 'record') { try { process.loadEnvFile(new URL('.env', import.meta.url).pathname)