Merge remote-tracking branch 'origin/master' into worktree/agent-execution-context-rfc

# Conflicts: # docs/architecture.md # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/module-graph.md # examples/coding-agent/tests/code-mode.e2e.ts # packages/context/workspace-context/tests/workspace-context.spec.ts # packages/core/README.md # packages/core/agent-loop/README.md # packages/core/agent-loop/tests/agent.spec.ts # packages/core/agent-loop/tests/cancel.spec.ts # packages/core/agent-loop/tests/config-session-id.spec.ts # packages/core/agent-loop/tests/contract-regressions.spec.ts # packages/core/agent-loop/tests/coverage-edges.spec.ts # packages/core/agent-loop/tests/interception.spec.ts # packages/core/agent-loop/tests/loop.spec.ts # packages/core/agent-loop/tests/properties.spec.ts # packages/core/agent-loop/tests/request-cache.e2e.ts # packages/core/agent-loop/tests/request-reconstruction.spec.ts # packages/core/agent-loop/tests/resume.spec.ts # packages/core/agent-loop/tests/scope-lifecycle.spec.ts # packages/core/agent-loop/tests/tool-calls.spec.ts # packages/core/agent-loop/tests/tool-order.spec.ts # packages/core/agent-loop/tests/turn-stop.spec.ts # packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts # website/zh-CN/api/harness/agent-loop.md
2026-07-19 11:44:50 +08:00
parent 0e4785cdb7 383a305bd4
commit cfe9b9617d
295 changed files with 5544 additions and 4182 deletions
--- a/website/zh-CN/api/harness/agent-loop.md
+++ b/website/zh-CN/api/harness/agent-loop.md
@@ -4,25 +4,25 @@

 `AgentLoop` — provided by `@deepseek-ai/dsh-agent-loop`.

-Concrete ReactLoopAgent factory and driver service.
+Concrete agent factory and driver service.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L353)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L408)

 ### ctx.agentLoop.create(id, options?, meta?)

 ```ts website-api
-create(id: AgentId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): ReactLoopAgent
+create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
 ```

-Create an agent on a fresh per-run session, owned by the accessing fiber. Constructor-driven config calls use the loop fiber itself.
+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.

- `id` — agent registry id.
+- `id` — shared agent/session identity.
 - `options` — concrete loop options.
 - `meta` — optional fresh-session workspace metadata.

 **Returns** the published running agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L413)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L543)

 ### ctx.agentLoop.createAgent(ownerCtx, options)

@@ -37,7 +37,7 @@ Create an owned agent on a caller-supplied session id.

 **Returns** the published handle.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L436)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L565)

 ### ctx.agentLoop.resume(ownerCtx, options)

@@ -52,4 +52,4 @@ Resume an owned agent from the configured persistence service.

 **Returns** the published handle.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L468)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L597)
--- a/website/zh-CN/api/harness/agents.md
+++ b/website/zh-CN/api/harness/agents.md
@@ -6,7 +6,7 @@

 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.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L133)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L201)

 ### ctx.agents.setFactory(factory)

@@ -14,13 +14,13 @@ Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator
 setFactory(factory: AgentFactory): () => void
 ```

-Register the effect-scoped creation factory, rejecting a duplicate. Service factories are retraced through each create/resume caller for ownership.
+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.

 - `factory` — the loop-owned factory `create`/`resume` delegate to.

-**Returns** the exact Cordis effect disposer.
+**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#L152)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L228)

 ### ctx.agents.create(options)

@@ -28,13 +28,13 @@ Register the effect-scoped creation factory, rejecting a duplicate. Service fact
 async create(options: CreateAgentOptions): Promise<AgentHandle>
 ```

-Create and publish an owned agent and session through the active factory. Rejects if no factory is registered or creation, setup, or publication fails.
+Create and publish a new agent through the registered factory. Distinct from 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 AgentHandle lets the owner tear down exactly this agent.

- `options` — agent id, session id/seed/metadata, and agent options.
+- `options` — shared identity, session seed/metadata, and agent options.

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

 ### ctx.agents.resume(options)

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

 ### ctx.agents.register(agent)

@@ -56,27 +56,28 @@ Load a persisted session and resume an agent on it through the registered factor
 register(agent: Agent): () => void
 ```

-Register a live agent in the calling effect scope, with scope-filtered creation and disposal events. Duplicate ids throw.
+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.

 - `agent` — the already-constructed agent to record in the store.

-**Returns** the exact Cordis effect disposer for nested teardown ordering.
+**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#L207)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L306)

-### ctx.agents.enter(agent)
+### ctx.agents.enter(agent, owner)

 ```ts website-api
-enter(agent: Agent): () => void
+enter(agent: Agent, owner: Agent | undefined): () => void
 ```

-Insert an unpublished agent for an ordered factory transaction.
+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 announce. Ordinary callers use register.

 - `agent` — the prepared, unpublished agent.
+- `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 the paired disposal edge; detachment during creation dispatch is deferred.
+**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#L222)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L330)

 ### ctx.agents.announce(agent)

@@ -88,21 +89,36 @@ 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#L290)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L405)

 ### ctx.agents.get(id)

 ```ts website-api
-get(id: AgentId): Agent | undefined
+get(id: SessionId): Agent | undefined
 ```

 Look up a live agent.

- `id` — the agent id to look up.
+- `id` — the shared agent/session id to look up.

 **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#L324)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L439)
+
+### ctx.agents.isOwnedBy(id, owner)
+
+```ts website-api
+isOwnedBy(id: SessionId, owner: Agent): boolean
+```
+
+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.
+
+- `id` — the candidate child agent's shared agent/session id.
+- `owner` — the expected runtime creator agent.
+
+**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)

 ### ctx.agents.list()

@@ -114,4 +130,16 @@ 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#L332)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L459)
+
+### ctx.agents.roots()
+
+```ts website-api
+roots(): Agent[]
+```
+
+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.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L469)
--- a/website/zh-CN/api/harness/compact.md
+++ b/website/zh-CN/api/harness/compact.md
@@ -25,20 +25,19 @@ Check token pressure and compact if the conversation is too large. Estimate the

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

-### ctx.compact.compactRegion(session, start, end, agent, signal?)
+### ctx.compact.compactRegion(start, end, agent, signal?)

 ```ts website-api
-abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
+abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```

-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. The agent must own the exact target session object; implementations reject an ownership mismatch before model resolution, lock acquisition, summarization, or log mutation, and reject active, missing, reversed, or unbalanced ranges. Use toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks.
+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 toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks.

- `session` — session to mutate; must be identical to `agent.session`.
 - `start` — first surface seq, inclusive.
 - `end` — last surface seq, inclusive.
- `agent` — owner of the target session and summarizer context.
+- `agent` — context whose session is mutated and whose routing options guide summarization.
 - `signal` — optional cancellation; model-backed implementations must forward it.

-**Returns** the replaced range and summary.
+**Returns** the appended event seqs, summary, replaced range, and token accounting.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L85)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L82)
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -2,7 +2,7 @@

 # Harness events

-Every event the harness packages declare on the cordis event bus (39 total), grouped by scope. The **mode** is the dispatch semantics (`emit` fire-and-forget, `parallel` awaited, `serial` first-bail, `waterfall` veto-chain — a waterfall listener MUST call `next()` to delegate).
+Every event the harness packages declare on the cordis event bus (40 total), grouped by scope. The **mode** is the dispatch semantics (`emit` fire-and-forget, `parallel` awaited, `serial` first-bail, `waterfall` veto-chain — a waterfall listener MUST call `next()` to delegate).

 ## agent/*

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

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

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

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

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

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

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

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

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

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

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

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

 ### agent/turn-stop

@@ -211,7 +211,24 @@ 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#L285)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L272)
+
+## agent-loop/*
+
+### agent-loop/config-start-failed
+
+**Mode:** `emit`
+
+```ts website-api
+'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+```
+
+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.
+
+- `sessionId` — exact shared agent/session identity that failed startup.
+- `error` — persistence, setup, or publication failure.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L363)

 ## approval/*

@@ -366,7 +383,7 @@ A ready child settled. Scope-filtered dispatch uses the same delegating parent c

 - `info` — the run identity and terminal outcome.

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

 ### subagent/provider-added

@@ -380,7 +397,7 @@ A provider became resolvable in the registry.

 - `provider` — the registered provider.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L82)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L86)

 ### subagent/provider-removed

@@ -394,7 +411,7 @@ A provider left the registry. Accepted runs remain holder-owned.

 - `name` — the provider name that no longer resolves.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L88)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L92)

 ### subagent/start

@@ -408,7 +425,7 @@ A provider established a ready child. For in-process providers, `ctx.agents.get(

 - `info` — the provider and ready child identity.

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

 ## system-prompt/*

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

 The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.

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

 ### ctx.llm.registerAdapter(providers, adapter)

@@ -21,7 +21,7 @@ Register an adapter for the given provider routes. Throws `LlmError` with code `

 **Returns** the disposer that unregisters all of them.

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

 ### ctx.llm.listProviders()

@@ -33,7 +33,7 @@ Describe provider routes with a registered adapter.

 **Returns** detached provider metadata in registration order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L142)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L140)

 ### ctx.llm.listModels(provider)

@@ -47,7 +47,7 @@ Discover models advertised by one registered provider. Catalog membership is adv

 **Returns** detached model metadata in adapter-preferred order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L152)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L150)

 ### ctx.llm.stream(options)

@@ -61,4 +61,4 @@ Stream one model call as raw chunks (token-level deltas). Throws `LlmError` with

 **Returns** the chunk stream, possibly wrapped by `llm/stream` listeners.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L210)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L208)
--- 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#L580)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L585)

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

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

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

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

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

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

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

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

 Named provider registry and capability-checked start surface.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L141)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L153)

 ### ctx.subagents.registerProvider(provider)

@@ -20,7 +20,7 @@ Register a provider under its name. Registration is effect-scoped and HMR safe;

 **Returns** the exact Cordis effect disposer.

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

 ### ctx.subagents.getProvider(name)

@@ -34,7 +34,7 @@ Look up a provider by name.

 **Returns** the provider, or undefined when absent.

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

 ### ctx.subagents.list()

@@ -46,7 +46,7 @@ List registered provider names in insertion order.

 **Returns** the registered names.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L186)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L198)

 ### ctx.subagents.start(name, request)

@@ -61,4 +61,4 @@ Establish a ready child on the named provider. Capability and semantic checks ru

 **Returns** the ready holder-owned run.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L199)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/subagent/subagent/src/index.ts#L211)