Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align prose with runtime contracts

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-14 16:21:41 +08:00
parent 26b4b036fc
commit f0fc20ca42
84 changed files with 162 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/cordis-catalog/events.md
View File

@@ -27,7 +27,7 @@ Source: [`packages/core/agent/src/types.ts:139`](../../packages/core/agent/src/t
### `agent/disposed` — emit
An agent left the registry. AgentLoop emits this after driver quiescence; custom registry users own their driver-ordering contract.
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.
```ts cordis-catalog
'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
@@ -35,7 +35,7 @@ An agent left the registry. AgentLoop emits this after driver quiescence; custom
Types: [Agent](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:147`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:148`](../../packages/core/agent/src/types.ts)
### `agent/error` — emit
@@ -47,11 +47,11 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
Types: [Agent](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:280`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:283`](../../packages/core/agent/src/types.ts)
### `agent/pre-step` — serial
Awaited serial checkpoint after prompt assembly and before `step/start`. Listeners may mutate the session surface 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.
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.
```ts cordis-catalog
'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
@@ -59,7 +59,7 @@ Awaited serial checkpoint after prompt assembly and before `step/start`. Listene
Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:200`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:202`](../../packages/core/agent/src/types.ts)
### `agent/prompt-submit` — waterfall
@@ -71,7 +71,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca
Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:210`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:212`](../../packages/core/agent/src/types.ts)
### `agent/queued` — emit
@@ -83,7 +83,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already
Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:166`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
### `agent/request` — waterfall
@@ -95,7 +95,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha
Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:222`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:224`](../../packages/core/agent/src/types.ts)
### `agent/session-prefix` — waterfall
@@ -107,7 +107,7 @@ Compose request-only messages placed before derived history. The frozen result i
Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:237`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts)
### `agent/session-start` — emit
@@ -119,7 +119,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
Types: [Agent](../core-data-structures/core.md) · [SessionStartSource](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:179`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:180`](../../packages/core/agent/src/types.ts)
### `agent/status` — emit
@@ -131,7 +131,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no
Types: [Agent](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:156`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:157`](../../packages/core/agent/src/types.ts)
### `agent/step-result` — waterfall
@@ -143,7 +143,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:248`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:250`](../../packages/core/agent/src/types.ts)
### `agent/turn-continuation` — waterfall
@@ -155,11 +155,11 @@ Override whether the turn continues. The default continues after tool calls or s
Types: [Agent](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:258`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:260`](../../packages/core/agent/src/types.ts)
### `agent/turn-stop` — serial
Monotonic terminal-stop checkpoint after continuation and steering are folded. A stop discards pending steering.
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.
```ts cordis-catalog
'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined
@@ -167,7 +167,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded. A
Types: [Agent](../core-data-structures/core.md)
Source: [`packages/core/agent/src/types.ts:267`](../../packages/core/agent/src/types.ts)
Source: [`packages/core/agent/src/types.ts:270`](../../packages/core/agent/src/types.ts)
## `approval/*`

2
docs/cordis-catalog/services.md
View File

@@ -42,7 +42,7 @@ Source: [`packages/core/agent/src/index.ts:133`](../../packages/core/agent/src/i
## `ctx.approval` — `ApprovalService`
Approval request and policy service. It logs each ask/outcome pair, applies session policy before answerers, and exposes deterministic policy changes to the model through prompt and pre-step notices.
Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through prompt and pre-step notices.
```ts cordis-catalog
async request(req: ApprovalRequest): Promise<ApprovalOutcome>