```
@@ -23,6 +33,14 @@ Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback is unloade
### ctx.plugin(plugin, ...args)
```ts website-api
+/**
+ * Load a plugin in the current context.
+ *
+ * @param plugin — a function, class, or `{ apply }` object plugin.
+ * @param args — the plugin config, validated against its `Config` schema.
+ * @returns the fiber; awaiting it settles once loading finished
+ * (rejecting on config or startup errors).
+ */
plugin(plugin: P, ...args: Spread>): Fiber & PromiseLike
```
@@ -40,11 +58,13 @@ Load a plugin in the current context.
Supported plugin entrypoint shapes.
```ts website-api
+/** Supported plugin entrypoint shapes. */
type Plugin =
| Plugin.Function
| Plugin.Constructor
| Plugin.Object
+/** Types associated with plugin entrypoints and runtime records. */
namespace Plugin {
/** Shared metadata understood by the plugin registry and related tooling. */
export interface Base {
@@ -104,8 +124,16 @@ Service dependency declaration accepted by plugins and the `@Inject` decorator.
Array form requests services without intercept config. Object form maps each service name to optional intercept config for the plugin context.
```ts website-api
+/**
+ * Service dependency declaration accepted by plugins and the `@Inject`
+ * decorator.
+ *
+ * Array form requests services without intercept config. Object form maps each
+ * service name to optional intercept config for the plugin context.
+ */
type Inject = (keyof M)[] | { [K in keyof M]?: M[K] }
+/** Utilities for normalizing plugin dependency declarations. */
namespace Inject {
/**
* Convert array/object/class-inherited inject metadata into a plain map.
diff --git a/website/zh-CN/api/cordis/service.md b/website/zh-CN/api/cordis/service.md
index acd43163d6..13aa82a2ca 100644
--- a/website/zh-CN/api/cordis/service.md
+++ b/website/zh-CN/api/cordis/service.md
@@ -12,6 +12,7 @@ Subclasses call `super(ctx, name)` from their constructor. The service is regist
### service.name
```ts website-api
+/** The service name this instance is registered under. */
public name!: string
```
@@ -24,6 +25,7 @@ The service name this instance is registered under.
### Service.init
```ts website-api
+/** Symbol key of an instance method run after construction (class plugins). */
static readonly init: unique symbol
```
@@ -34,6 +36,7 @@ Symbol key of an instance method run after construction (class plugins).
### Service.check
```ts website-api
+/** Symbol key of the availability predicate passed to `ctx.provide()`. */
static readonly check: unique symbol
```
@@ -44,6 +47,7 @@ Symbol key of the availability predicate passed to `ctx.provide()`.
### Service.config
```ts website-api
+/** Symbol key of the phantom intercept-config type parameter. */
static readonly config: unique symbol
```
@@ -54,6 +58,7 @@ Symbol key of the phantom intercept-config type parameter.
### Service.invoke
```ts website-api
+/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
static readonly invoke: unique symbol
```
@@ -64,6 +69,7 @@ Symbol key of the call body making a service callable (e.g. `ctx.logger()`).
### Service.extend
```ts website-api
+/** Symbol key of the helper deriving an extended service instance. */
static readonly extend: unique symbol
```
@@ -74,6 +80,7 @@ Symbol key of the helper deriving an extended service instance.
### Service.tracker
```ts website-api
+/** Symbol key of the tracker metadata used for context tracing. */
static readonly tracker: unique symbol
```
@@ -84,6 +91,7 @@ Symbol key of the tracker metadata used for context tracing.
### Service.resolveConfig
```ts website-api
+/** Symbol key of the intercept-config resolution helper below. */
static readonly resolveConfig: unique symbol
```
diff --git a/website/zh-CN/api/harness/agent-loop.md b/website/zh-CN/api/harness/agent-loop.md
index 6401898e24..9a43a1ba14 100644
--- a/website/zh-CN/api/harness/agent-loop.md
+++ b/website/zh-CN/api/harness/agent-loop.md
@@ -11,6 +11,15 @@ Concrete agent factory and driver service.
### ctx.agentLoop.create(id, options?, meta?)
```ts website-api
+/**
+ * Create an agent and session under one caller-supplied identity, owned by
+ * the accessing fiber. Constructor-driven config calls mint a fresh combined
+ * id before entering this boundary.
+ * @param id - shared agent/session identity.
+ * @param options - concrete loop options.
+ * @param meta - optional fresh-session workspace metadata.
+ * @returns the published running agent.
+ */
create(id: SessionId, options: AgentOptions = {}, meta: Pick = {}): Agent
```
@@ -27,6 +36,12 @@ Create an agent and session under one caller-supplied identity, owned by the acc
### ctx.agentLoop.createAgent(ownerCtx, options)
```ts website-api
+/**
+ * Create an owned agent on a caller-supplied session id.
+ * @param ownerCtx - caller context that structurally owns the transaction.
+ * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise
```
@@ -42,6 +57,12 @@ Create an owned agent on a caller-supplied session id.
### ctx.agentLoop.resume(ownerCtx, options)
```ts website-api
+/**
+ * Resume an owned agent from the configured persistence service.
+ * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+ * @param options - persisted identity, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise
```
diff --git a/website/zh-CN/api/harness/agents.md b/website/zh-CN/api/harness/agents.md
index 8d6c84cc7a..bba6a7a5d4 100644
--- a/website/zh-CN/api/harness/agents.md
+++ b/website/zh-CN/api/harness/agents.md
@@ -4,13 +4,120 @@
`AgentRegistry` — provided by `@deepseek-ai/dsh-agent`.
-Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L201)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L217)
+
+### ctx.agents.currentInitiator()
+
+```ts website-api
+/**
+ * Read the Agent that initiated the inherited asynchronous driver chain.
+ * Use this optional form for logging, tracing, metrics, or host attribution
+ * that also supports agentless calls. When a parent creates a child, setup
+ * reports the causal parent while `agentCtx.agent` identifies the child.
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
+ * and inside an explicit clearing boundary.
+ * @throws when this service instance has been disposed.
+ */
+currentInitiator(): Agent | undefined
+```
+
+Read the Agent that initiated the inherited asynchronous driver chain. Use this optional form for logging, tracing, metrics, or host attribution that also supports agentless calls. When a parent creates a child, setup reports the causal parent while `agentCtx.agent` identifies the child.
+
+**Returns** the inherited Agent, or `undefined` outside an initiator boundary and inside an explicit clearing boundary.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L256)
+
+### ctx.agents.requireInitiator()
+
+```ts website-api
+/**
+ * Read the initiating Agent and fail when no initiator boundary is active.
+ * Use this for private helpers contractually below a driver, or for a
+ * deployment-owned outbound request whose contract forbids agentless calls.
+ * Generic or direct-call seams use optional lookup or explicit request fields.
+ * @returns the inherited Agent.
+ * @throws when no initiator is active or this service instance has been disposed.
+ */
+requireInitiator(): Agent
+```
+
+Read the initiating Agent and fail when no initiator boundary is active. Use this for private helpers contractually below a driver, or for a deployment-owned outbound request whose contract forbids agentless calls. Generic or direct-call seams use optional lookup or explicit request fields.
+
+**Returns** the inherited Agent.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L269)
+
+### ctx.agents.withInitiator(agent, operation)
+
+```ts website-api
+/**
+ * Run an operation with one exact Agent as its process-local initiator. The
+ * exact synchronous value or Promise returned by the operation is preserved.
+ * Custom drivers and test harnesses wrap their complete returned foreground
+ * lifetime.
+ * A queue or wire receiver may establish this boundary only after validating
+ * explicit identity and resolving the exact live Agent; this method does neither.
+ * Detached work remains owned by the subsystem that starts it.
+ * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
+ * @param operation - synchronous or asynchronous operation to invoke.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withInitiator(agent: Agent, operation: () => T): T
+```
+
+Run an operation with one exact Agent as its process-local initiator. The exact synchronous value or Promise returned by the operation is preserved. Custom drivers and test harnesses wrap their complete returned foreground lifetime. A queue or wire receiver may establish this boundary only after validating explicit identity and resolving the exact live Agent; this method does neither. Detached work remains owned by the subsystem that starts it.
+
+- `agent` — initiating Agent to inherit; presence is neither liveness proof nor authorization.
+- `operation` — synchronous or asynchronous operation to invoke.
+
+**Returns** the exact value returned by `operation`.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L288)
+
+### ctx.agents.withoutInitiator(operation)
+
+```ts website-api
+/**
+ * Run an operation inside a boundary that hides any inherited initiating
+ * Agent. The exact synchronous value or Promise is preserved.
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+ * watchers, or exporters so they do not inherit the first Agent that happens
+ * to initialize them. It clears only initiator attribution, not explicit
+ * fields, and does not own or drain detached resources.
+ * @param operation - synchronous or asynchronous operation to invoke without an initiator.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withoutInitiator(operation: () => T): T
+```
+
+Run an operation inside a boundary that hides any inherited initiating Agent. The exact synchronous value or Promise is preserved. Use this while creating lazy shared timers, queue pumps, pool maintenance, watchers, or exporters so they do not inherit the first Agent that happens to initialize them. It clears only initiator attribution, not explicit fields, and does not own or drain detached resources.
+
+- `operation` — synchronous or asynchronous operation to invoke without an initiator.
+
+**Returns** the exact value returned by `operation`.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L303)
### ctx.agents.setFactory(factory)
```ts website-api
+/**
+ * Register the agent-creation factory (the loop calls this on construction,
+ * effect-scoped). A traced Cordis service is canonicalized to its concrete
+ * target; each create/resume call is then traced through that caller's
+ * context so ownership follows the caller without stacking proxy layers.
+ * Throws if a factory is already registered. Returns the disposer; on
+ * dispose the factory slot is cleared.
+ * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
+ * @returns the disposer that clears the factory slot. The exact
+ * Cordis effect disposer (single-shot): composite (generator) effects may
+ * yield it directly — exact identity nests the teardown in order.
+ */
setFactory(factory: AgentFactory): () => void
```
@@ -20,11 +127,20 @@ Register the agent-creation factory (the loop calls this on construction, effect
**Returns** the disposer that clears the factory slot. The exact Cordis effect disposer (single-shot): composite (generator) effects may yield it directly — exact identity nests the teardown in order.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L228)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L319)
### ctx.agents.create(options)
```ts website-api
+/**
+ * Create and publish a new agent through the registered factory.
+ * Distinct from {@link register} (which records an already-constructed
+ * agent): this constructs the agent and its session. Rejects if no factory is
+ * registered or creation/setup fails. The resolved {@link AgentHandle} lets
+ * the owner tear down exactly this agent.
+ * @param options - shared identity, session seed/metadata, and agent options.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
async create(options: CreateAgentOptions): Promise
```
@@ -34,11 +150,18 @@ Create and publish a new agent through the registered factory. Distinct from reg
**Returns** the handle after setup, rollback-covered publication, and loop start complete.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L261)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L352)
### ctx.agents.resume(options)
```ts website-api
+/**
+ * Load a persisted session and resume an agent on it through the registered
+ * factory. Rejects if no factory is registered; the factory rejects if
+ * session persistence is not configured or persistence/setup fails.
+ * @param options - persisted identity, configuration, and optional setup.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
async resume(options: ResumeAgentOptions): Promise
```
@@ -48,11 +171,29 @@ Load a persisted session and resume an agent on it through the registered factor
**Returns** the handle after setup, rollback-covered publication, and loop start complete.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L280)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L371)
### ctx.agents.register(agent)
```ts website-api
+/**
+ * Register a live agent. Throws if an agent with the same id is already
+ * registered. Emits `agent/created` on registration and `agent/disposed`
+ * when the calling fiber is disposed — both with the agent's scope carrier
+ * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+ * emits are scope-filtered regardless of which context invoked `register`
+ * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+ * requires passing the carrier). Returns the disposer.
+ * @param agent - the already-constructed agent to record in the store.
+ * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
+ * returns undefined without awaiting an in-flight teardown). Exact
+ * identity is load-bearing: a composite (generator) effect that owns a
+ * teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+ * function so Cordis nests the unregistration at that yield position;
+ * yielding a wrapper would leave it disposing as a concurrent sibling on
+ * owner unload, unregistering the agent (and emitting `agent/disposed`)
+ * while its final turn is still draining.
+ */
register(agent: Agent): () => void
```
@@ -62,11 +203,26 @@ Register a live agent. Throws if an agent with the same id is already registered
**Returns** the EXACT Cordis effect disposer (single-shot; a repeat call returns undefined without awaiting an in-flight teardown). Exact identity is load-bearing: a composite (generator) effect that owns a teardown ORDER — the agent factory's lifecycle chain — must yield THIS function so Cordis nests the unregistration at that yield position; yielding a wrapper would leave it disposing as a concurrent sibling on owner unload, unregistering the agent (and emitting `agent/disposed`) while its final turn is still draining.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L306)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L397)
### ctx.agents.enter(agent, owner)
```ts website-api
+/**
+ * Insert an already-constructed agent without announcing it. This is the
+ * advanced ordered-lifecycle primitive used by the async agent factory: it
+ * first completes setup while the agent is unpublished, then assigns the
+ * returned detach closure into its pre-installed composite teardown before
+ * calling {@link announce}. Ordinary callers use {@link register}.
+ * @param agent - the prepared, unpublished agent.
+ * @param owner - live agent whose scoped context created this agent, or
+ * undefined for a top-level runtime root. This is runtime ownership, not
+ * the resumed session's durable parent lineage.
+ * @returns an idempotent closure that removes this exact entry and emits
+ * `agent/disposed` with listener failures contained. When called from a
+ * synchronous `agent/created` listener, removal and disposal wait until
+ * that creation dispatch unwinds.
+ */
enter(agent: Agent, owner: Agent | undefined): () => void
```
@@ -77,11 +233,18 @@ Insert an already-constructed agent without announcing it. This is the advanced
**Returns** an idempotent closure that removes this exact entry and emits `agent/disposed` with listener failures contained. When called from a synchronous `agent/created` listener, removal and disposal wait until that creation dispatch unwinds.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L330)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L421)
### ctx.agents.announce(agent)
```ts website-api
+/**
+ * Announce an agent previously inserted with {@link enter}.
+ * @param agent - the live inserted agent to announce.
+ * @throws if `agent` is not the exact live registry entry for its id, or its
+ * creation announcement already began (including a reentrant call from a
+ * creation listener).
+ */
announce(agent: Agent): void
```
@@ -89,11 +252,16 @@ Announce an agent previously inserted with enter.
- `agent` — the live inserted agent to announce.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L405)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L496)
### ctx.agents.get(id)
```ts website-api
+/**
+ * Look up a live agent.
+ * @param id - the shared agent/session id to look up.
+ * @returns the agent, or undefined when no live agent has that id.
+ */
get(id: SessionId): Agent | undefined
```
@@ -103,11 +271,19 @@ Look up a live agent.
**Returns** the agent, or undefined when no live agent has that id.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L439)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L530)
### ctx.agents.isOwnedBy(id, owner)
```ts website-api
+/**
+ * Test whether a live agent was created through one exact parent agent's
+ * scoped context. Runtime ownership is independent of durable session
+ * lineage and remains unambiguous when unrelated providers reuse an id.
+ * @param id - the candidate child agent's shared agent/session id.
+ * @param owner - the expected runtime creator agent.
+ * @returns true only while the exact child entry is live under that owner.
+ */
isOwnedBy(id: SessionId, owner: Agent): boolean
```
@@ -118,11 +294,15 @@ Test whether a live agent was created through one exact parent agent's scoped co
**Returns** true only while the exact child entry is live under that owner.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L451)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L542)
### ctx.agents.list()
```ts website-api
+/**
+ * All live agents, in registration order.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
list(): Agent[]
```
@@ -130,11 +310,17 @@ All live agents, in registration order.
**Returns** a fresh array; mutating it does not affect the registry.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L459)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L550)
### ctx.agents.roots()
```ts website-api
+/**
+ * All live top-level agents in registration order. A top-level agent was
+ * created without an owning agent context; durable session lineage does not
+ * affect this runtime relation, so a resumed fork may still be a root.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
roots(): Agent[]
```
@@ -142,4 +328,4 @@ All live top-level agents in registration order. A top-level agent was created w
**Returns** a fresh array; mutating it does not affect the registry.
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L469)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L560)
diff --git a/website/zh-CN/api/harness/approval.md b/website/zh-CN/api/harness/approval.md
index fe3b090016..4aa2b8ad2d 100644
--- a/website/zh-CN/api/harness/approval.md
+++ b/website/zh-CN/api/harness/approval.md
@@ -11,6 +11,24 @@ Approval service that applies session policy before answerers and logs every ask
### ctx.approval.request(req)
```ts website-api
+/**
+ * Ask the composed answerers to decide one readonly same-process request.
+ * The service borrows the request, agent, session, and live signal directly.
+ * The request requires an open turn because the audit pair must be enclosed
+ * by the durable log's commit/replay boundary; an idle ask rejects before
+ * appending anything. The answerer phase always produces an outcome: 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'`. A failure that prevents either audit append
+ * from committing still rejects because returning an unlogged decision would
+ * violate the pair. Session contains post-commit observer failures, so an
+ * authoritative append cannot reject the request or suppress its matching
+ * audit event.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @returns the closed outcome; `'allowed-once'` is the only grant.
+ * @throws when no turn is open or either audit event fails before the session
+ * append commit point.
+ */
async request(req: ApprovalRequest): Promise
```
diff --git a/website/zh-CN/api/harness/bash-env.md b/website/zh-CN/api/harness/bash-env.md
index f8baf32bac..906464080e 100644
--- a/website/zh-CN/api/harness/bash-env.md
+++ b/website/zh-CN/api/harness/bash-env.md
@@ -11,6 +11,12 @@ Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The names
### ctx.bashEnv.register(contributor)
```ts website-api
+/**
+ * Register one environment contributor. Names and keys are unique; built-in
+ * keys are reserved. Registration is disposed with the calling plugin fiber.
+ * @param contributor - declared key ownership and per-execution resolver.
+ * @returns the disposer that unregisters the contribution.
+ */
register(contributor: BashEnvContributor): () => void
```
@@ -25,6 +31,11 @@ Register one environment contributor. Names and keys are unique; built-in keys a
### ctx.bashEnv.collect(execution)
```ts website-api
+/**
+ * Build the trusted `DSH_*` snapshot for one bash tool execution.
+ * @param execution - the current tool execution.
+ * @returns an immutable environment overlay containing built-ins and current contributions.
+ */
collect(execution: ToolExecution): DshEnvironment
```
@@ -39,6 +50,10 @@ Build the trusted `DSH_*` snapshot for one bash tool execution.
### ctx.bashEnv.list()
```ts website-api
+/**
+ * Enumerate plugin-contributed variables without executing their resolvers.
+ * @returns declarations sorted by environment variable name.
+ */
list(): BashEnvVariableInfo[]
```
diff --git a/website/zh-CN/api/harness/bash.md b/website/zh-CN/api/harness/bash.md
index c3e4173763..f340697063 100644
--- a/website/zh-CN/api/harness/bash.md
+++ b/website/zh-CN/api/harness/bash.md
@@ -16,6 +16,11 @@ Implementations must honor these semantics:
### ctx.bash.sandboxMode
```ts website-api
+/**
+ * The sandbox mode this executor applies by default, or `undefined` when it
+ * does not sandbox commands.
+ * @returns the configured default sandbox mode, when supported.
+ */
get sandboxMode(): SandboxMode | undefined
```
@@ -26,6 +31,12 @@ The sandbox mode this executor applies by default, or `undefined` when it does n
### ctx.bash.resolve(request)
```ts website-api
+/**
+ * Apply implementation-owned defaults and caps to a request before execution.
+ * @param request - the caller's request; omitted fields get this
+ * implementation's defaults, capped fields are clamped.
+ * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+ */
abstract resolve(request: BashExecRequest): BashExecSpec
```
@@ -40,6 +51,12 @@ Apply implementation-owned defaults and caps to a request before execution.
### ctx.bash.run(spec)
```ts website-api
+/**
+ * Run a command in the foreground; resolves when it finishes.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the outcome; nonzero exits, timeout kills, and abort kills
+ * resolve with a descriptive result rather than reject.
+ */
abstract run(spec: BashExecSpec): Promise
```
@@ -54,6 +71,11 @@ Run a command in the foreground; resolves when it finishes.
### ctx.bash.start(spec)
```ts website-api
+/**
+ * Start a background process and return its handle immediately.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the live process handle (reads, kill, quiescence promise).
+ */
abstract start(spec: BashExecSpec): BashProcess
```
diff --git a/website/zh-CN/api/harness/code-runtime.md b/website/zh-CN/api/harness/code-runtime.md
index ee8300a9f0..fef72ce525 100644
--- a/website/zh-CN/api/harness/code-runtime.md
+++ b/website/zh-CN/api/harness/code-runtime.md
@@ -11,6 +11,13 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
### ctx.codeRuntime.language
```ts website-api
+/**
+ * The source language {@link run} expects `program` to be written in, as a
+ * lowercase identifier. Informational, not gating — a consumer that
+ * generates language-specific presentation (typed SDK stubs, usage
+ * instructions) switches on it and fails loud on a language it cannot
+ * present. Well-known value: `'typescript'`.
+ */
abstract readonly language: string
```
@@ -21,6 +28,12 @@ The source language run expects `program` to be written in, as a lowercase ident
### ctx.codeRuntime.isolation
```ts website-api
+/**
+ * The execution substrate, as a lowercase identifier. Informational, not
+ * gating — a descriptor so deployments and diagnostics can tell backends
+ * apart, not a security claim. Well-known values: `'worker-thread'`,
+ * `'process'`, `'container'`.
+ */
abstract readonly isolation: string
```
@@ -31,6 +44,15 @@ The execution substrate, as a lowercase identifier. Informational, not gating
### ctx.codeRuntime.run(request)
```ts website-api
+/**
+ * Execute one program against the request's bindings and capture what it
+ * emitted. See the class doc for the resolution contract (error is a result
+ * field; rejection means seam misuse only).
+ * @param request - the program, its bindings, and the abort signal; the
+ * request carries everything the runtime acts on, with no hidden defaults.
+ * @returns the run's outcome: completion value (when transferable), the
+ * ordered log capture, and the failure (if any).
+ */
abstract run(request: CodeRunRequest): Promise
```
diff --git a/website/zh-CN/api/harness/compact.md b/website/zh-CN/api/harness/compact.md
index 67f17cc941..e06188ee27 100644
--- a/website/zh-CN/api/harness/compact.md
+++ b/website/zh-CN/api/harness/compact.md
@@ -11,6 +11,21 @@ Abstract compaction service. Implementations own trigger policy, retention, and
### ctx.compact.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
```ts website-api
+/**
+ * Check token pressure and compact if the conversation is too large.
+ * Estimate the next request, including its session prefix, derived history,
+ * and system prompt. Above threshold, compact a head-anchored range ending at
+ * a balanced tool boundary and reconsolidate any prior automatic checkpoint.
+ * Return `null` when no compaction is needed or an open tail leaves no safe
+ * cutoff. A single oversized retained unit or prefix cannot be repaired here.
+ *
+ * @param agent - agent context owning the session surface and model options.
+ * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
+ * @param sessionPrefix - the instance's composed session prefix, counted toward the
+ * estimate.
+ * @param signal - cancellation signal; model-backed implementations must forward it.
+ * @returns the compaction result, or `null` if no compaction was needed.
+ */
abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise
```
@@ -28,6 +43,23 @@ Check token pressure and compact if the conversation is too large. Estimate the
### ctx.compact.compactRegion(start, end, agent, signal?)
```ts website-api
+/**
+ * Forcibly compact a range of surface nodes into a single summary node.
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
+ * balanced so assistant tool calls remain paired with their results. A model-
+ * backed implementation forwards cancellation and rejects active, missing,
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+ * for the edge checks.
+ *
+ * @param start - first surface seq, inclusive.
+ * @param end - last surface seq, inclusive.
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
+ * @param signal - optional cancellation; model-backed implementations must forward it.
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
+ */
abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise
```
diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md
index 8d494739ba..fcfa426a81 100644
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -11,6 +11,16 @@ Every event the harness packages declare on the cordis event bus (40 total), gro
**Mode:** `emit`
```ts website-api
+/**
+ * A fully configured agent and live session were published. Setup is
+ * composition-only; `agent/session-start` is the first startup-driving seam.
+ * Synchronous listener failure vetoes publication, while returned-promise
+ * rejection is reported. Detach requested during dispatch waits until every
+ * creation listener has observed the stable entry.
+ * @param 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.
+ * @mode emit
+ */
'agent/created'(this: Scoped, agent: Agent): void
```
@@ -25,6 +35,14 @@ A fully configured agent and live session were published. Setup is composition-o
**Mode:** `emit`
```ts website-api
+/**
+ * An agent left the registry; AgentLoop emits this after driver quiescence
+ * but before session detachment and scoped-registration unwind. Custom
+ * registry users own their driver-ordering contract.
+ * @param agent - the exact agent removed from the registry.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
'agent/disposed'(this: Scoped, agent: Agent): void
```
@@ -39,6 +57,16 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef
**Mode:** `emit`
```ts website-api
+/**
+ * A step or turn errored. The loop reports a failure here (plus the logger)
+ * even when the error has no in-turn position for a session `error` event.
+ * @param agent - the agent whose turn errored.
+ * @param turn - the turn in which the failure surfaced.
+ * @param step - the step at which the failure surfaced.
+ * @param error - the failure, verbatim.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
'agent/error'(this: Scoped, agent: Agent, turn: number, step: number, error: Error): void
```
@@ -56,6 +84,22 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
**Mode:** `serial`
```ts website-api
+/**
+ * Awaited serial checkpoint for session-surface mutation after prompt
+ * assembly and before `step/start`; appends land outside the pending step.
+ * The loop derives history once afterward, so compaction records and
+ * replacements are included without rewriting an assembled request. The
+ * prompt and prefix are the exact pressure inputs for that request, and
+ * `signal` cancels listener work.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param agent - the agent opening the step.
+ * @param turn - the open turn number.
+ * @param step - the pending step number.
+ * @param fullSystemPrompt - the assembled prompt.
+ * @param sessionPrefix - the frozen request prefix.
+ * @param signal - the turn abort signal.
+ * @mode serial
+ */
'agent/pre-step'(this: Scoped, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise | void
```
@@ -75,6 +119,15 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and
**Mode:** `waterfall`
```ts website-api
+/**
+ * Allow, rewrite, or block one drained prompt before it becomes a user
+ * message. Call `next()` for the unchanged default.
+ * @param agent - the agent draining its inbox.
+ * @param content - the drained message's blocks, as queued.
+ * @param source - the message's resolved source.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
'agent/prompt-submit'(this: Scoped, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise): Promise
```
@@ -91,6 +144,15 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca
**Mode:** `emit`
```ts website-api
+/**
+ * Detached, frozen content entered the agent's inbox. Source defaults have
+ * already been applied, so these are the exact values retained for the log.
+ * @param agent - the agent whose inbox received the message.
+ * @param content - the accepted content blocks retained by the inbox.
+ * @param info - the accepted source plus whether it entered as steering.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
'agent/queued'(this: Scoped, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
```
@@ -107,6 +169,17 @@ Detached, frozen content entered the agent's inbox. Source defaults have already
**Mode:** `waterfall`
```ts website-api
+/**
+ * Replace the frozen call configuration. Model-visible content must use
+ * logged channels; this seam cannot mutate messages. Injection here joins
+ * the next request because the current step boundary is already fixed.
+ * @param agent - the agent making the model call.
+ * @param turn - the open turn number.
+ * @param step - the step whose request this is.
+ * @param 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.
+ * @mode waterfall
+ */
'agent/request'(this: Scoped, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise
```
@@ -124,6 +197,20 @@ Replace the frozen call configuration. Model-visible content must use logged cha
**Mode:** `waterfall`
```ts website-api
+/**
+ * Compose request-only messages placed before derived history. The frozen
+ * result is computed once per loop instance, logged on its anchoring request
+ * header, and reused so the provider prefix remains stable. Interrupted
+ * composition is discarded. Composition precedes the first `agent/pre-step`
+ * and request boundary, so listener appends join the current request and
+ * pressure accounting sees the composed prefix. Changing context belongs in
+ * history; contributors should prepend to `await next()` to preserve registration order.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param agent - the agent whose session prefix is being composed.
+ * @param prefix - the frozen seed; return an extended replacement.
+ * @param signal - aborts composition when the step is torn down.
+ * @mode waterfall
+ */
'agent/session-prefix'(this: Scoped, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise): Promise
```
@@ -140,6 +227,16 @@ Compose request-only messages placed before derived history. The frozen result i
**Mode:** `emit`
```ts website-api
+/**
+ * The session lifecycle began, once before the first turn. Use
+ * `agent.inject()` to seed model-facing context. This is a notification, not
+ * a veto; disposal requested by a lifecycle owner is rechecked before the
+ * driver starts.
+ * @param agent - the agent whose session lifecycle began.
+ * @param source - why the session started (fresh startup, resume, …).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
'agent/session-start'(this: Scoped, agent: Agent, source: SessionStartSource): void
```
@@ -155,6 +252,14 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
**Mode:** `emit`
```ts website-api
+/**
+ * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does
+ * not enter `running` synchronously; drive lifecycle from this event.
+ * @param agent - the agent whose status flipped.
+ * @param status - the status just entered (the transition's destination).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
'agent/status'(this: Scoped, agent: Agent, status: AgentStatus): void
```
@@ -170,6 +275,16 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no
**Mode:** `waterfall`
```ts website-api
+/**
+ * Waterfall: post-process the assembled assistant {@link Message} before
+ * tool dispatch (validation, content rewriting, …).
+ * @param agent - the agent that received the step's response.
+ * @param turn - the open turn number.
+ * @param step - the step that produced the message.
+ * @param message - the assistant message as assembled from the stream.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
'agent/step-result'(this: Scoped, agent: Agent, turn: number, step: number, message: Message, next: () => Promise): Promise
```
@@ -187,6 +302,15 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
**Mode:** `waterfall`
```ts website-api
+/**
+ * Override whether the turn continues. The default continues after tool
+ * calls or steering and stops otherwise; a continue reason becomes steering.
+ * @param agent - the agent deciding whether to run another step.
+ * @param turn - the turn being continued or stopped.
+ * @param defaultDecision - what the loop would do absent an override.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
'agent/turn-continuation'(this: Scoped, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise): Promise
```
@@ -203,6 +327,15 @@ Override whether the turn continues. The default continues after tool calls or s
**Mode:** `serial`
```ts website-api
+/**
+ * Monotonic terminal-stop checkpoint after continuation and steering are
+ * folded; a stop remains authoritative through turn close and flush:
+ * steering queued in that window is discarded, while ordinary sends survive.
+ * @param agent - the agent whose composed continuation outcome may be stopped.
+ * @param turn - the turn at its terminal-stop checkpoint.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode serial
+ */
'agent/turn-stop'(this: Scoped, agent: Agent, turn: number): ContinuationStop | undefined
```
@@ -220,6 +353,15 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a
**Mode:** `emit`
```ts website-api
+/**
+ * A declarative agent entry failed before it could publish a live agent.
+ * Consumers that buffer work for the configured identity use this
+ * transient signal to reject that work instead of waiting forever. Normal
+ * factory teardown suppresses failures from the cancelled startup attempt.
+ * @param sessionId - exact shared agent/session identity that failed startup.
+ * @param error - persistence, setup, or publication failure.
+ * @mode emit
+ */
'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
```
@@ -237,6 +379,13 @@ A declarative agent entry failed before it could publish a live agent. Consumers
**Mode:** `waterfall`
```ts website-api
+/**
+ * Ask composed answerers for one decision. Return an outcome to claim the
+ * request or call `next()`; failure yields the fail-closed default.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @mode waterfall
+ */
'approval/request'(this: Scoped, req: ApprovalRequest, next: () => Promise): Promise
```
@@ -253,6 +402,13 @@ Ask composed answerers for one decision. Return an outcome to claim the request
**Mode:** `waterfall`
```ts website-api
+/**
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
+ * `next()` yields an unconditional edit; the first returned guard wins.
+ * @param target - the resolved target about to be edited.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
```
@@ -268,6 +424,14 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
**Mode:** `emit`
```ts website-api
+/**
+ * Record a successful observation. Listeners must be synchronous recorders:
+ * throws fail the tool call and returned promises are not awaited.
+ * @param target - the target that was read/written/edited.
+ * @param version - the version the actor now holds as its observation.
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
+ * @mode emit
+ */
'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
```
@@ -284,6 +448,14 @@ Record a successful observation. Listeners must be synchronous recorders: throws
**Mode:** `waterfall`
```ts website-api
+/**
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+ * `next()` yields the bare provider's unconditional write; the first listener
+ * that returns an intent owns the decision rather than composing with peers.
+ * @param target - the resolved target about to be written.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise): Promise
```
@@ -301,6 +473,17 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
**Mode:** `waterfall`
```ts website-api
+/**
+ * Waterfall around every streaming model call (retry, replay, routing).
+ * Bound to the {@link LlmService}; call `next()` to reach the resolved
+ * adapter's stream, or yield your own chunks to short-circuit.
+ * @param options - the full request. A LOOP-built request arrives
+ * deep-frozen (mutation throws): its content is a pure function of the
+ * session log (the reconstructability RFC), so listeners read it, never
+ * rewrite it. A hand-built one-shot (compaction summarize) is the
+ * caller's own object and stays mutable here.
+ * @mode waterfall
+ */
'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable): AsyncIterable
```
@@ -317,6 +500,17 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
**Mode:** `emit`
```ts website-api
+/**
+ * Creation announcement during session publication. A synchronous throw vetoes and rolls
+ * back with a paired disposal; detach requested during dispatch is deferred.
+ * A returned-promise rejection is logged but cannot retroactively veto this
+ * synchronous boundary.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only sessions entered through that agent's context.
+ * @param session - the session just entered and announced.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
'session/created'(this: Scoped, session: Session): void
```
@@ -331,6 +525,15 @@ Creation announcement during session publication. A synchronous throw vetoes and
**Mode:** `emit`
```ts website-api
+/**
+ * Emitted once when an announced session leaves the store, including
+ * publication rollback, but never for an entry whose creation announcement
+ * did not begin. Listener failures are logged and contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+ * @param session - the session that is no longer live in the store.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
'session/disposed'(this: Scoped, session: Session): void
```
@@ -345,6 +548,17 @@ Emitted once when an announced session leaves the store, including publication r
**Mode:** `emit`
```ts website-api
+/**
+ * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+ * before the log push, but callbacks run after it; observer failures are
+ * logged and contained without making the committed append fail.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only events from sessions entered through that agent's context.
+ * @param session - the session whose log grew.
+ * @param event - the appended event, exactly as recorded.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
'session/event'(this: Scoped, session: Session, event: SessionEvent): void
```
@@ -360,6 +574,15 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
**Mode:** `parallel`
```ts website-api
+/**
+ * Awaited parallel durability checkpoint: every listener runs and the
+ * caller awaits all of them, with no waterfall veto. Dispatch through
+ * {@link SessionStore.flush}. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @dshScopeScan unsupported
+ * @mode parallel
+ */
'session/flush'(this: Scoped, session: Session): Promise | void
```
@@ -376,6 +599,14 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
**Mode:** `emit`
```ts website-api
+/**
+ * A ready child settled. Scope-filtered dispatch uses the same delegating
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+ * same scoped audience.
+ * @param info - the run identity and terminal outcome.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
'subagent/end'(this: Scoped, info: SubagentRunEndInfo): void
```
@@ -390,6 +621,11 @@ A ready child settled. Scope-filtered dispatch uses the same delegating parent c
**Mode:** `emit`
```ts website-api
+/**
+ * A provider became resolvable in the registry.
+ * @param provider - the registered provider.
+ * @mode emit
+ */
'subagent/provider-added'(provider: SubagentProvider): void
```
@@ -404,6 +640,11 @@ A provider became resolvable in the registry.
**Mode:** `emit`
```ts website-api
+/**
+ * A provider left the registry. Accepted runs remain holder-owned.
+ * @param name - the provider name that no longer resolves.
+ * @mode emit
+ */
'subagent/provider-removed'(name: string): void
```
@@ -418,6 +659,16 @@ A provider left the registry. Accepted runs remain holder-owned.
**Mode:** `emit`
```ts website-api
+/**
+ * A provider established a ready child. For in-process providers,
+ * `ctx.agents.get(info.id)` resolves during this notification.
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
+ * parent-scoped listener observes only its own delegations. Paired with
+ * `subagent/end`.
+ * @param info - the provider and ready child identity.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
'subagent/start'(this: Scoped, info: SubagentRunInfo): void
```
@@ -434,6 +685,14 @@ A provider established a ready child. For in-process providers, `ctx.agents.get(
**Mode:** `waterfall`
```ts website-api
+/**
+ * Expert waterfall over the assembled sections, tools, and variables.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+ * receive only that scope's assemblies. The returned value is authoritative.
+ * @param assembly - the mutable assembly built from registered providers.
+ * @param context - the caller's per-assembly context.
+ * @mode waterfall
+ */
'system-prompt/assemble'(this: Scoped, assembly: PromptAssembly, context: AssembleContext, next: () => Promise): Promise
```
@@ -449,6 +708,11 @@ Expert waterfall over the assembled sections, tools, and variables. Scope-filter
**Mode:** `emit`
```ts website-api
+/**
+ * Emitted when any prompt provider changes. This registry notification is
+ * unfiltered because a global change affects every scope.
+ * @mode emit
+ */
'system-prompt/change'(): void
```
@@ -463,6 +727,15 @@ Emitted when any prompt provider changes. This registry notification is unfilter
**Mode:** `emit`
```ts website-api
+/**
+ * A tool was registered or unregistered, or a scoped restriction changed
+ * (the available tool set changed — possibly for one scope only). An
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
+ * dispatch: a global change concerns every agent's next assembly, so a
+ * scoped listener subscribing here sees every change, not just its own
+ * scope's.
+ * @mode emit
+ */
'tools/change'(): void
```
@@ -475,6 +748,14 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
**Mode:** `waterfall`
```ts website-api
+/**
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+ * a normalized result; wrappers may change only `exec.signal`, while call
+ * identity remains immutable.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+ * @mode waterfall
+ */
'tools/execute'(this: Scoped, exec: ToolExecution, next: () => Promise): Promise
```
@@ -489,6 +770,14 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
**Mode:** `waterfall`
```ts website-api
+/**
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+ * accepts it unchanged; thrown tools still reach this seam as errors.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
+ * @mode waterfall
+ */
'tools/post-execute'(this: Scoped, exec: ToolExecution, result: Readonly, next: () => Promise): Promise
```
@@ -504,6 +793,13 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
**Mode:** `waterfall`
```ts website-api
+/**
+ * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+ * approval support turns `ask` into denial.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the pending call (name, parsed arguments, caller agent).
+ * @mode waterfall
+ */
'tools/pre-execute'(this: Scoped, exec: ToolExecution, next: () => Promise): Promise
```
@@ -518,6 +814,13 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
**Mode:** `emit`
```ts website-api
+/**
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+ * @param exec - the execution object that traversed the pipeline.
+ * @param result - a deep-frozen snapshot of the final returned result.
+ * @mode emit
+ */
'tools/result'(this: Scoped, exec: Readonly