Merge origin/master into codex/send-one-turn

# Conflicts: # docs/cordis-catalog/events.md # docs/event-producer-consumer.md # docs/persistence-catalog.md # packages/core/agent-loop/src/loop.ts # packages/core/agent/README.md # website/zh-CN/api/harness/events.md
2026-07-20 17:41:06 +08:00
parent f899b857a6 b8826c9e9a
commit ec0a2bb623
209 changed files with 7781 additions and 1509 deletions
--- a/website/.vitepress/config/api-sidebar.json
+++ b/website/.vitepress/config/api-sidebar.json
@@ -66,6 +66,10 @@
      "text": "ctx.sandbox",
      "link": "/zh-CN/api/harness/sandbox"
    },
+    {
+      "text": "ctx.sandboxPolicy",
+      "link": "/zh-CN/api/harness/sandbox-policy"
+    },
    {
      "text": "ctx.sessionPersistence",
      "link": "/zh-CN/api/harness/session-persistence"
@@ -102,6 +106,10 @@
      "text": "ctx.tokenMeter",
      "link": "/zh-CN/api/harness/token-meter"
    },
+    {
+      "text": "ctx.toolResultPrune",
+      "link": "/zh-CN/api/harness/tool-result-prune"
+    },
    {
      "text": "ctx.tools",
      "link": "/zh-CN/api/harness/tools"
--- a/website/zh-CN/api/harness/bash-env.md
+++ b/website/zh-CN/api/harness/bash-env.md
@@ -6,7 +6,7 @@

 Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model bash call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L102)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L103)

 ### ctx.bashEnv.register(contributor)

@@ -26,7 +26,7 @@ Register one environment contributor. Names and keys are unique; built-in keys a

 **Returns** the disposer that unregisters the contribution.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L123)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L124)

 ### ctx.bashEnv.collect(execution)

@@ -45,7 +45,7 @@ Build the trusted `DSH_*` snapshot for one bash tool execution.

 **Returns** an immutable environment overlay containing built-ins and current contributions.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L165)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L166)

 ### ctx.bashEnv.list()

@@ -61,4 +61,4 @@ Enumerate plugin-contributed variables without executing their resolvers.

 **Returns** declarations sorted by environment variable name.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L197)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L198)
--- a/website/zh-CN/api/harness/bash.md
+++ b/website/zh-CN/api/harness/bash.md
@@ -11,7 +11,7 @@ Implementations must honor these semantics:
 - BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
 - Disposal kills all running background processes and awaits their exit.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L49)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L48)

 ### ctx.bash.sandboxMode

@@ -26,7 +26,7 @@ get sandboxMode(): SandboxMode | undefined

 The sandbox mode this executor applies by default, or `undefined` when it does not sandbox commands.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L59)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L58)

 ### ctx.bash.resolve(request)

@@ -46,7 +46,7 @@ Apply implementation-owned defaults and caps to a request before execution.

 **Returns** the fully-specified spec to hand to `run`/`start`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L69)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L68)

 ### ctx.bash.run(spec)

@@ -66,7 +66,7 @@ Run a command in the foreground; resolves when it finishes.

 **Returns** the outcome; nonzero exits, timeout kills, and abort kills resolve with a descriptive result rather than reject.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L77)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L76)

 ### ctx.bash.start(spec)

@@ -85,4 +85,4 @@ Start a background process and return its handle immediately.

 **Returns** the live process handle (reads, kill, quiescence promise).

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L84)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L83)
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -28,7 +28,7 @@ A fully configured agent and live session were published. Setup is composition-o

 - `agent` — the newly registered agent with its live session and completed setup. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L154)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L150)

 ### agent/disposed

@@ -50,7 +50,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef

 - `agent` — the exact agent removed from the registry. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L163)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L159)

 ### agent/error

@@ -77,7 +77,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 - `step` — the step at which the failure surfaced.
 - `error` — the failure, verbatim. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L318)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L314)

 ### agent/post-step

@@ -105,7 +105,7 @@ Awaited serial checkpoint after the response, real or synthetic tool results, in
 - `step` — the open step number.
 - `signal` — the turn abort signal. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L271)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L267)

 ### agent/pre-step

@@ -133,7 +133,7 @@ Awaited serial checkpoint before `step/start`; appends land outside the pending
 - `step` — the pending step number.
 - `signal` — the turn abort signal.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L211)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L207)

 ### agent/prompt-submit

@@ -158,7 +158,7 @@ Allow, rewrite, or block one claimed prompt before it becomes a user message. Ca
 - `content` — the claimed message's blocks, as queued.
 - `source` — the message's resolved source. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L221)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L217)

 ### agent/queued

@@ -183,7 +183,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already
 - `content` — the accepted content blocks retained by the inbox.
 - `info` — the accepted source plus whether it entered as steering. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L182)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L178)

 ### agent/request

@@ -211,7 +211,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha
 - `step` — the step whose request this is.
 - `config` — the config the loop would use (frozen); return a replacement to switch. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L233)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L229)

 ### agent/request-error

@@ -243,7 +243,7 @@ Recover a model-request failure after its failed step has closed. `retry` opens
 - `retryAttempt` — zero-based number of prior recovery retries.
 - `signal` — the turn abort signal. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L285)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L281)

 ### agent/session-prefix

@@ -273,7 +273,7 @@ Compose request-only messages placed before derived history. The frozen result i
 - `prefix` — the frozen seed; return an extended replacement.
 - `signal` — aborts composition when the step is torn down.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L248)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L244)

 ### agent/session-start

@@ -298,7 +298,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 - `agent` — the agent whose session lifecycle began.
 - `source` — why the session started (fresh startup, resume, …). Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L195)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L191)

 ### agent/status

@@ -321,7 +321,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no
 - `agent` — the agent whose status flipped.
 - `status` — the status just entered (the transition's destination). Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L172)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L168)

 ### agent/step-result

@@ -348,7 +348,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
 - `step` — the step that produced the message.
 - `message` — the assistant message as assembled from the stream. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L259)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L255)

 ### agent/turn-continuation

@@ -373,7 +373,7 @@ Override whether the turn continues. The default continues after tool calls or s
 - `turn` — the turn being continued or stopped.
 - `defaultDecision` — what the loop would do absent an override. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L295)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L291)

 ### agent/turn-stop

@@ -397,7 +397,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a
 - `agent` — the agent whose composed continuation outcome may be stopped.
 - `turn` — the turn at its terminal-stop checkpoint. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L305)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L301)

 ## agent-loop/*

@@ -470,7 +470,7 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 - `target` — the resolved target about to be edited.
 - `actor` — the opaque tool-execution context the decider keys off.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L61)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L62)

 ### fs/observed

@@ -494,7 +494,7 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 - `version` — the version the actor now holds as its observation.
 - `actor` — the observing tool-execution context; undefined records nothing useful.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L70)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L71)

 ### fs/write-intent

@@ -517,7 +517,7 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 - `target` — the resolved target about to be written.
 - `actor` — the opaque tool-execution context the decider keys off.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L53)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L54)

 ## llm/*

--- a/website/zh-CN/api/harness/fs.md
+++ b/website/zh-CN/api/harness/fs.md
@@ -6,7 +6,30 @@

 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L80)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L81)
+
+### ctx.fs.sandboxMode
+
+```ts website-api
+/**
+/**
+ * The sandbox mode this backend enforces on mutations BY DEFAULT, or
+ * `undefined` when it does not confine at all — the capability fact the tool
+ * layer reads to advertise the escalation fields honestly (mirrors
+ * `BashExecutor.sandboxMode`). The base class and the bare local backend
+ * report `undefined`; a sandboxing backend (`@deepseek-ai/dsh-fs-sandbox`)
+ * overrides it with the deployment default. 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 fact.
+ * @returns the configured default mode of a sandboxing backend; `undefined`
+ *   for a backend that never confines.
+ */
+get sandboxMode(): SandboxMode | undefined
+```
+
+/** The sandbox mode this backend enforces on mutations BY DEFAULT, or `undefined` when it does not confine at all — the capability fact the tool layer reads to advertise the escalation fields honestly (mirrors `BashExecutor.sandboxMode`). The base class and the bare local backend report `undefined`; a sandboxing backend (`@deepseek-ai/dsh-fs-sandbox`) overrides it with the deployment default. 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 fact.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L99)

 ### ctx.fs.resolve(path, opts?)

@@ -30,7 +53,7 @@ Resolve a model/plugin-supplied path into a stable FsTarget. May perform I/O (a

 **Returns** the stable target; the same file yields the same `targetKey`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L94)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L112)

 ### ctx.fs.stat(target, signal?)

@@ -51,7 +74,7 @@ Return target metadata, or `undefined` when the target does not exist.

 **Returns** metadata only, never content; undefined for an absent target.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L102)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L120)

 ### ctx.fs.lstat(path, opts?, signal?)

@@ -82,7 +105,7 @@ Return path metadata without following the final path component when it is a sym

 **Returns** metadata only, never content; undefined for an absent path.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L118)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L136)

 ### ctx.fs.readText(target, signal?)

@@ -103,7 +126,7 @@ Read the whole regular text file as a single decoded string.

 **Returns** the full decoded UTF-8 content.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L126)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L144)

 ### ctx.fs.streamText(target, signal?)

@@ -127,7 +150,7 @@ Stream the whole regular text file as decoded text chunks (same text semantics a

 **Returns** the chunk iterable, decoded and validated like `readText`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L137)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L155)

 ### ctx.fs.listDir(target, signal?)

@@ -149,9 +172,9 @@ List direct children of a directory in stable name order. Returns resolved child

 **Returns** one entry per direct child, in stable name order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L146)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L164)

-### ctx.fs.writeText(target, content, expected?, signal?)
+### ctx.fs.writeText(target, content, expected?, signal?, sandboxMode?)

 ```ts website-api
 /**
@@ -161,9 +184,12 @@ List direct children of a directory in stable name order. Returns resolved child
 * @param content - the full new file content.
 * @param expected - the write intent guarding the write; omit for unconditional.
 * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxMode - the per-call sandbox mode this write runs under; a
+ *   sandboxing backend fences the write by it, the bare backend ignores it.
+ *   Omit to leave the backend its own default.
 * @returns the outcome, including the version the write produced.
 */
-abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
+abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxMode?: SandboxMode, ): Promise<FsWriteOutcome>
 ```

 Atomically create or replace UTF-8 text. `expected` guards intent and staleness; omission allows unconditional overwrite.
@@ -172,12 +198,13 @@ Atomically create or replace UTF-8 text. `expected` guards intent and staleness;
 - `content` — the full new file content.
 - `expected` — the write intent guarding the write; omit for unconditional.
 - `signal` — aborts before the atomic rename takes effect.
+- `sandboxMode` — the per-call sandbox mode this write runs under; a sandboxing backend fences the write by it, the bare backend ignores it. Omit to leave the backend its own default.

 **Returns** the outcome, including the version the write produced.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L157)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L178)

-### ctx.fs.editText(target, edit, expected?, signal?)
+### ctx.fs.editText(target, edit, expected?, signal?, sandboxMode?)

 ```ts website-api
 /**
@@ -188,9 +215,12 @@ Atomically create or replace UTF-8 text. `expected` guards intent and staleness;
 * @param edit - the literal search/replace request.
 * @param expected - the version guard; omit for an unconditional edit.
 * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxMode - the per-call sandbox mode this edit runs under; a
+ *   sandboxing backend fences the edit by it, the bare backend ignores it.
+ *   Omit to leave the backend its own default.
 * @returns the outcome, including the version the edit produced.
 */
-abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
+abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxMode?: SandboxMode, ): Promise<FsEditOutcome>
 ```

 Atomically edit literal text. When supplied, the version guard is checked before matching so stale content reports `FS_STALE_VERSION`; omission edits the current content without a freshness precondition.
@@ -199,7 +229,8 @@ Atomically edit literal text. When supplied, the version guard is checked before
 - `edit` — the literal search/replace request.
 - `expected` — the version guard; omit for an unconditional edit.
 - `signal` — aborts before the atomic rename takes effect.
+- `sandboxMode` — the per-call sandbox mode this edit runs under; a sandboxing backend fences the edit by it, the bare backend ignores it. Omit to leave the backend its own default.

 **Returns** the outcome, including the version the edit produced.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L169)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L199)
--- a/website/zh-CN/api/harness/permission.md
+++ b/website/zh-CN/api/harness/permission.md
@@ -6,7 +6,7 @@

 Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L94)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L97)

 ### ctx.permission.names

@@ -20,7 +20,7 @@ get names(): readonly string[]

 The advertised preset names, in the preset table's declaration order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L134)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L137)

 ### ctx.permission.current(events)

@@ -41,7 +41,7 @@ Resolve the preset matching the effective knob values. A still-matching last sel

 **Returns** the effective preset name, or `custom` when nothing matches.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L145)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L148)

 ### ctx.permission.resolve(name)

@@ -61,7 +61,7 @@ Resolve a preset's knob bundle.

 **Returns** the configured bundle.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L166)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L169)

 ### ctx.permission.optionOf(name)

@@ -82,7 +82,7 @@ Build the client option for a table entry or CUSTOM_PRESET. A missing label fall

 **Returns** the option a client renders.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L181)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L184)

 ### ctx.permission.set(session, name)

@@ -101,4 +101,4 @@ Record a changed preset, then update each changed knob through its own setter. S
 - `session` — the session the switch belongs to.
 - `name` — the preset to switch to; unknown names throw.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L195)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L198)
--- a/website/zh-CN/api/harness/sandbox-policy.md
+++ b/website/zh-CN/api/harness/sandbox-policy.md
@@ -0,0 +1,31 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.sandboxPolicy
+
+`SandboxPolicyService` — provided by `@deepseek-ai/dsh-sandbox-policy`.
+
+The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode and workspace root; enforcing implementations read defaultMode and workspaceRoot, and the tool layers fold each session's `sandbox/mode` override with effectiveSandboxMode on top.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/src/index.ts#L60)
+
+### ctx.sandboxPolicy.defaultMode
+
+```ts website-api
+/** The deployment default mode — the fallback beneath a session override. */
+readonly defaultMode: SandboxMode
+```
+
+The deployment default mode — the fallback beneath a session override.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/src/index.ts#L70)
+
+### ctx.sandboxPolicy.workspaceRoot
+
+```ts website-api
+/** The absolute `workspace-write` boundary root both families fence against. */
+readonly workspaceRoot: string
+```
+
+The absolute `workspace-write` boundary root both families fence against.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/src/index.ts#L72)
--- a/website/zh-CN/api/harness/sandbox.md
+++ b/website/zh-CN/api/harness/sandbox.md
@@ -6,7 +6,7 @@

 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L111)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L122)

 ### ctx.sandbox.confine(argv, policy)

@@ -32,4 +32,4 @@ Wrap `argv` so it executes confined under `policy` on this host; the caller spaw

 **Returns** the argv to spawn instead, plus the enforcement completeness the selected backend achieves for it.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L127)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L138)
--- a/website/zh-CN/api/harness/sessions.md
+++ b/website/zh-CN/api/harness/sessions.md
@@ -7,7 +7,7 @@
 In-memory session store (`ctx.sessions`).
 Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L577)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L549)

 ### ctx.sessions.create(id?, options?)

@@ -44,7 +44,7 @@ For an agent whose session must be torn down IN ORDER with its loop (so the loop

 **Returns** the live session, already entered and announced.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L606)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L578)

 ### ctx.sessions.prepare(id?, options?)

@@ -75,7 +75,7 @@ Build a session WITHOUT entering it into the store — validate the id/cwd and c

 **Returns** the constructed session, NOT yet in the store.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L635)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L607)

 ### ctx.sessions.enter(session)

@@ -112,7 +112,7 @@ Re-checks the id for a duplicate: `prepare` and `enter` are public cross-package

 **Returns** the detach disposer (publication hooks + store removal). When called from a synchronous `session/created` listener, removal and disposal wait until that creation dispatch unwinds.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L679)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L651)

 ### ctx.sessions.announce(session)

@@ -131,7 +131,7 @@ Emit `session/created` exactly once for an entered session (with the carrier ent

 - `session` — the entered session to announce to listeners.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L734)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L706)

 ### ctx.sessions.flush(session)

@@ -156,7 +156,7 @@ Dispatch the awaited `session/flush` durability checkpoint for `session`, with t

 **Returns** resolves when every flush listener has settled; after all settle, rejects with the first registered listener failure if any listener failed.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L786)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L758)

 ### ctx.sessions.get(id)

@@ -175,7 +175,7 @@ Look up a live session.

 **Returns** the session, or undefined when no live session has that id.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L818)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L790)

 ### ctx.sessions.list()

@@ -191,7 +191,7 @@ All live sessions, in creation order.

 **Returns** a fresh array; mutating it does not affect the store.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L826)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L798)

 ### ctx.sessions.fork(source, boundary?, childSessionId?)

@@ -220,4 +220,4 @@ Create a live child session from a turn-enclosed prefix of a live source. `bound

 **Returns** The created live child session.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L843)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L815)
--- a/website/zh-CN/api/harness/tool-result-prune.md
+++ b/website/zh-CN/api/harness/tool-result-prune.md
@@ -0,0 +1,83 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.toolResultPrune
+
+`ToolResultPruneService` — provided by `@deepseek-ai/dsh-compact-tool-result-prune`.
+
+Deterministic head/middle/tail pruning for current tool-result surface nodes.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact-tool-result-prune/src/index.ts#L39)
+
+### ctx.toolResultPrune.config
+
+```ts website-api
+/** Resolved and immutable character budgets. */
+readonly config: ResolvedConfig
+```
+
+Resolved and immutable character budgets.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact-tool-result-prune/src/index.ts#L47)
+
+### ctx.toolResultPrune.measureContent(blocks)
+
+```ts website-api
+/**
+ * Measure text content in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content to measure.
+ * @returns total Unicode code points across text blocks.
+ */
+measureContent(blocks: readonly ContentBlock[]): number
+```
+
+Measure text content in Unicode code points; non-text blocks cost zero.
+
+- `blocks` — tool-result content to measure.
+
+**Returns** total Unicode code points across text blocks.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact-tool-result-prune/src/index.ts#L59)
+
+### ctx.toolResultPrune.pruneContent(blocks)
+
+```ts website-api
+/**
+ * Replace an over-budget text middle while retaining rich-block order.
+ * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
+ * boundary cannot split a surrogate pair. Grapheme clusters may still split.
+ * @param blocks - original tool-result content.
+ * @returns pruned content, or `null` when the text is within budget.
+ */
+pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
+```
+
+Replace an over-budget text middle while retaining rich-block order. Text slicing is by Unicode code point, not UTF-16 code unit, so a retained boundary cannot split a surrogate pair. Grapheme clusters may still split.
+
+- `blocks` — original tool-result content.
+
+**Returns** pruned content, or `null` when the text is within budget.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact-tool-result-prune/src/index.ts#L74)
+
+### ctx.toolResultPrune.pruneSession(session)
+
+```ts website-api
+/**
+ * Prune every over-budget tool result from one stable current-surface snapshot.
+ * Each replacement preserves the complete event data except for `content`,
+ * and points at the shadowed node for durable provenance and replay.
+ * @param session - session whose current surface is rewritten.
+ * @returns landed replacements and aggregate Unicode-code-point savings.
+ * @throws when the session rejects a replacement; replacements committed
+ * earlier in the pass remain durable.
+ */
+pruneSession(session: Session): PruneResult
+```
+
+Prune every over-budget tool result from one stable current-surface snapshot. Each replacement preserves the complete event data except for `content`, and points at the shadowed node for durable provenance and replay.
+
+- `session` — session whose current surface is rewritten.
+
+**Returns** landed replacements and aggregate Unicode-code-point savings.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact-tool-result-prune/src/index.ts#L124)