Merge branch 'master' into feat/website-docs

2026-07-17 21:19:33 +08:00
parent 1b102b7279 cf872d002f
commit d447a7efb8
256 changed files with 11039 additions and 2634 deletions
--- a/website/.vitepress/config/api-sidebar.json
+++ b/website/.vitepress/config/api-sidebar.json
@@ -38,6 +38,10 @@
      "text": "ctx.bash",
      "link": "/zh-CN/api/harness/bash"
    },
+    {
+      "text": "ctx.bashEnv",
+      "link": "/zh-CN/api/harness/bash-env"
+    },
    {
      "text": "ctx.codeRuntime",
      "link": "/zh-CN/api/harness/code-runtime"
@@ -78,6 +82,10 @@
      "text": "ctx.skills",
      "link": "/zh-CN/api/harness/skills"
    },
+    {
+      "text": "ctx.spillStore",
+      "link": "/zh-CN/api/harness/spill-store"
+    },
    {
      "text": "ctx.subagents",
      "link": "/zh-CN/api/harness/subagents"
--- a/website/zh-CN/api/harness/bash-env.md
+++ b/website/zh-CN/api/harness/bash-env.md
@@ -0,0 +1,49 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.bashEnv
+
+`BashEnvRegistry` — provided by `@deepseek-ai/dsh-tool-bash`.
+
+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)
+
+### ctx.bashEnv.register(contributor)
+
+```ts website-api
+register(contributor: BashEnvContributor): () => void
+```
+
+Register one environment contributor. Names and keys are unique; built-in keys are reserved. Registration is disposed with the calling plugin fiber.
+
+- `contributor` — declared key ownership and per-execution resolver.
+
+**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)
+
+### ctx.bashEnv.collect(execution)
+
+```ts website-api
+collect(execution: ToolExecution): DshEnvironment
+```
+
+Build the trusted `DSH_*` snapshot for one bash tool execution.
+
+- `execution` — the current 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)
+
+### ctx.bashEnv.list()
+
+```ts website-api
+list(): BashEnvVariableInfo[]
+```
+
+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)
--- 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#L46)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L49)

 ### ctx.bash.sandboxMode

@@ -21,7 +21,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#L56)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L59)

 ### ctx.bash.resolve(request)

@@ -35,7 +35,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#L66)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L69)

 ### ctx.bash.run(spec)

@@ -49,7 +49,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#L74)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L77)

 ### ctx.bash.start(spec)

@@ -63,4 +63,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#L81)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L84)
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -18,7 +18,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#L139)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L151)

 ### agent/disposed

@@ -32,7 +32,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#L148)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L160)

 ### agent/error

@@ -49,7 +49,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#L283)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L295)

 ### agent/pre-step

@@ -68,7 +68,7 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and
 - `sessionPrefix` — the frozen request prefix.
 - `signal` — the turn abort signal.

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

 ### agent/prompt-submit

@@ -84,7 +84,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca
 - `content` — the drained 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#L212)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L224)

 ### agent/queued

@@ -100,7 +100,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#L167)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L179)

 ### agent/request

@@ -117,7 +117,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#L224)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L236)

 ### agent/session-prefix

@@ -133,7 +133,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#L239)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L251)

 ### agent/session-start

@@ -148,7 +148,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#L180)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L192)

 ### agent/status

@@ -163,7 +163,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#L157)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L169)

 ### agent/step-result

@@ -180,7 +180,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#L250)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L262)

 ### agent/turn-continuation

@@ -196,7 +196,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#L260)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L272)

 ### agent/turn-stop

@@ -211,7 +211,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#L270)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L282)

 ## approval/*

@@ -244,7 +244,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#L59)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L61)

 ### fs/observed

@@ -260,7 +260,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#L68)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L70)

 ### fs/write-intent

@@ -275,7 +275,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#L51)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L53)

 ## llm/*

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

 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#L78)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L80)

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

 ```ts website-api
-abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>
+abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 ```

 Resolve a model/plugin-supplied path into a stable FsTarget. May perform I/O (a remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence async even though the local backend only normalizes + realpaths.

 - `path` — the path to resolve; relative paths resolve against `opts.cwd`.
- `opts` — `cwd` overrides the backend's default base for relative paths.
+- `opts` — optional cwd override and cancellation signal.

 **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#L92)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L94)

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

@@ -36,7 +36,24 @@ 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#L100)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L102)
+
+### ctx.fs.lstat(path, opts?, signal?)
+
+```ts website-api
+abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
+```
+
+Return path metadata without following the final path component when it is a symbolic link. This is intentionally path-shaped, not target-shaped: resolve follows symlinks to produce the stable identity used by normal reads/writes, while `lstat` lets a consumer reject the path itself before that follow happens.
+`opts.cwd` follows resolve's cwd rules. `undefined` means the path is absent.
+
+- `path` — the path to inspect; relative paths resolve against `opts.cwd`.
+- `opts` — `cwd` overrides the backend's default base for relative paths.
+- `signal` — aborts the metadata round-trip.
+
+**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)

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

@@ -51,7 +68,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#L108)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L126)

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

@@ -66,7 +83,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#L119)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L137)

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

@@ -81,7 +98,7 @@ 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#L128)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L146)

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

@@ -98,7 +115,7 @@ Atomically create or replace UTF-8 text. `expected` guards intent and staleness;

 **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#L139)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L157)

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

@@ -115,4 +132,4 @@ Atomically edit literal text. When supplied, the version guard is checked before

 **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#L151)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L169)
--- a/website/zh-CN/api/harness/session-persistence.md
+++ b/website/zh-CN/api/harness/session-persistence.md
@@ -6,7 +6,21 @@

 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L30)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L42)
+
+### ctx.sessionPersistence.locate(meta)
+
+```ts website-api
+abstract locate(meta: SessionHeader): SessionLocation | undefined
+```
+
+Resolve this backend's independent local artifact for a session without reading, creating, flushing, or otherwise materializing it. Backends such as SQLite that do not own one artifact per session return `undefined`.
+
+- `meta` — the immutable session header whose artifact is requested.
+
+**Returns** the backend-specific absolute location, when one exists.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L54)

 ### ctx.sessionPersistence.create(meta)

@@ -18,7 +32,7 @@ Register a new session's metadata. A backend MAY defer the physical write until

 - `meta` — the immutable header (id, version, cwd, lineage) to record.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L42)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L63)

 ### ctx.sessionPersistence.append(id, events)

@@ -31,7 +45,7 @@ Durably persist a batch of events (called from the write-behind drain at the `se
 - `id` — the session the batch belongs to.
 - `events` — the contiguous batch to persist, in seq order.

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

 ### ctx.sessionPersistence.load(id)

@@ -45,7 +59,7 @@ Load a header and balanced contiguous log. A complete interrupted final turn is

 **Returns** the header and a log ending on a balanced `turn/end`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L63)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L84)

 ### ctx.sessionPersistence.list()

@@ -57,4 +71,4 @@ Lightweight listing from metadata, without a full-log parse.

 **Returns** one header per materialized session.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L69)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-persistence/session-persistence/src/index.ts#L90)
--- a/website/zh-CN/api/harness/session-query.md
+++ b/website/zh-CN/api/harness/session-query.md
@@ -4,9 +4,9 @@

 `SessionQueryService` — provided by `@deepseek-ai/dsh-session-query`.

-Live-preferred logical-corpus and exact-event read service.
+Live-preferred logical-corpus exact-read and relationship-tracing service.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L35)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L38)

 ### ctx.sessionQuery.listSessions()

@@ -18,7 +18,7 @@ List the complete logical corpus using live-preferred records.

 **Returns** deterministic newest-first cloned session records.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L60)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L63)

 ### ctx.sessionQuery.listEvents(sessionId)

@@ -32,7 +32,35 @@ List lightweight raw-log event records for one logical session.

 **Returns** event records in ascending seq order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L69)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L72)
+
+### ctx.sessionQuery.traceSession(sessionId)
+
+```ts website-api
+async traceSession(sessionId: SessionId): Promise<SessionLineageTrace>
+```
+
+Trace known ancestry and descendants from one corpus observation.
+
+- `sessionId` — logical session id to trace.
+
+**Returns** a complete lineage or an explicit unresolved parent boundary.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L83)
+
+### ctx.sessionQuery.traceEvent(request)
+
+```ts website-api
+async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>
+```
+
+Trace one event's direct positional and provenance relationships.
+
+- `request` — target session id and event seq.
+
+**Returns** direct links plus the target's positional replacement chain.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L94)

 ### ctx.sessionQuery.readEvent(request)

@@ -46,4 +74,4 @@ Read one full event plus a bounded raw-log context window.

 **Returns** cloned target and neighboring events.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L79)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/session-query/session-query/src/index.ts#L104)
--- 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#L564)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L540)

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

@@ -23,7 +23,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#L593)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L569)

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

@@ -38,7 +38,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#L622)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L598)

 ### ctx.sessions.enter(session)

@@ -53,7 +53,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#L666)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L642)

 ### ctx.sessions.announce(session)

@@ -65,7 +65,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#L721)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L697)

 ### ctx.sessions.flush(session)

@@ -79,7 +79,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#L773)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L749)

 ### ctx.sessions.get(id)

@@ -93,7 +93,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#L805)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L781)

 ### ctx.sessions.list()

@@ -105,7 +105,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#L813)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L789)

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

@@ -121,4 +121,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#L830)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L806)
--- a/website/zh-CN/api/harness/spill-store.md
+++ b/website/zh-CN/api/harness/spill-store.md
@@ -0,0 +1,27 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.spillStore
+
+`SpillStore` (abstract seam) — provided by `@deepseek-ai/dsh-spill`.
+
+Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+Semantics every implementation must honor:
+- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
+- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
+- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/spill/spill/src/index.ts#L45)
+
+### ctx.spillStore.saveText(input)
+
+```ts website-api
+abstract saveText(input: SaveTextSpill): Promise<SpillRef>
+```
+
+Persist `input.content` to a session-scoped spill artifact.
+
+- `input` — the owner, provenance, suggested name, and full text to save.
+
+**Returns** the saved artifact's `SpillRef`; rejects on a storage failure.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/spill/spill/src/index.ts#L55)
--- a/website/zh-CN/api/harness/tools.md
+++ b/website/zh-CN/api/harness/tools.md
@@ -6,7 +6,7 @@

 Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L363)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L378)

 ### ctx.tools.register(definition)

@@ -20,7 +20,7 @@ Register globally or in the calling agent scope. Scoped tools shadow globals; du

 **Returns** the exact disposer that unregisters the tool.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L453)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L468)

 ### ctx.tools.restrict(filter)

@@ -34,7 +34,7 @@ Restrict global tools for the calling agent scope. Empty filters, unknown names,

 **Returns** the exact disposer that lifts this restriction.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L493)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L508)

 ### ctx.tools.guard(guard)

@@ -48,7 +48,7 @@ Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A

 **Returns** the exact disposer that unregisters the guard.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L544)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L559)

 ### ctx.tools.get(name, scope?)

@@ -63,7 +63,7 @@ Look up a tool as one scope sees it (scoped shadows global; a restricted-away gl

 **Returns** the definition the scope resolves, or undefined when none is visible.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L646)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L661)

 ### ctx.tools.schemas(scope?)

@@ -77,7 +77,7 @@ Project visible definitions onto the allowlisted model-facing schema fields, exc

 **Returns** one deep-cloned schema per visible tool.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L656)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L671)

 ### ctx.tools.execute(exec)

@@ -91,4 +91,4 @@ Execute through pre-policy, guards, around-dispatch, post-policy, and final noti

 **Returns** the materialized final result.

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