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

session: the request header becomes logged state — request/header events + fold/diff/apply

Browse Source 
Every conversation request's non-content half (system prompt, tool
schemas, call config — the EpochHeader) is now recorded in the session
log: a 'request/header' full snapshot (reason 'initial' | 'resume' |
'fallback') anchors the fold at conversation birth and process
boundaries, and 'request/header-delta' events (system line-trim,
name-keyed tools delta, whole config) encode mid-run changes. The pure
trio — foldRequestHeader / diffHeader / applyHeaderDelta — reconstructs
the header any request was built under from the log alone; the writer
contract round-trip-verifies every delta with a 'fallback' snapshot
when the encoding cannot express a change (pure tool reordering), so a
well-formed log always folds cleanly. Canonical absence: empty system
and empty tools normalize to absent fields, matching request builds.

Persistence and cordis catalogs regenerated; SessionEventMap paste and
EpochHeader added to the core-data-structures session page.
This commit is contained in:
Tianyi Cui
2026-07-06 02:42:51 +08:00
parent 3f09159ab8
commit a7b569850b
12 changed files with 491 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -197,7 +197,7 @@ Waterfall around every streaming model call (retry, caching, routing). Bound to
Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
Source: [`packages/llm/llm/src/index.ts:33`](../../packages/llm/llm/src/index.ts)
Source: [`packages/llm/llm/src/index.ts:35`](../../packages/llm/llm/src/index.ts)
## `session/*`
@@ -209,7 +209,7 @@ A session was created in the store.
'session/created'(session: Session): void
```
Source: [`packages/core/session/src/index.ts:36`](../../packages/core/session/src/index.ts)
Source: [`packages/core/session/src/index.ts:37`](../../packages/core/session/src/index.ts)
### `session/event` — emit
@@ -221,7 +221,7 @@ An event was appended to a session log (sync, fire-and-forget). This is the per-
Types: [SessionEvent](../core-data-structures/core.md)
Source: [`packages/core/session/src/index.ts:44`](../../packages/core/session/src/index.ts)
Source: [`packages/core/session/src/index.ts:45`](../../packages/core/session/src/index.ts)
### `session/flush` — parallel
@@ -231,7 +231,7 @@ Awaited durability checkpoint. The agent loop awaits `ctx.parallel('session/flus
'session/flush'(session: Session): Promise<void> | void
```
Source: [`packages/core/session/src/index.ts:54`](../../packages/core/session/src/index.ts)
Source: [`packages/core/session/src/index.ts:55`](../../packages/core/session/src/index.ts)
## `subagent/*`

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

@@ -124,7 +124,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
Source: [`packages/llm/llm/src/index.ts:78`](../../packages/llm/llm/src/index.ts)
Source: [`packages/llm/llm/src/index.ts:80`](../../packages/llm/llm/src/index.ts)
## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
@@ -163,7 +163,7 @@ get(id: SessionId): Session | undefined
list(): Session[]
```
Source: [`packages/core/session/src/index.ts:327`](../../packages/core/session/src/index.ts)
Source: [`packages/core/session/src/index.ts:328`](../../packages/core/session/src/index.ts)
## `ctx.subagents` — `SubagentService`

2
docs/core-data-structures/core.md
View File

@@ -211,7 +211,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
}[T]
```
The thirteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `context/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the turn-enclosure invariant are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
The fifteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `context/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`, `request/header-delta`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the turn-enclosure invariant are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
## The agent handle

41
docs/core-data-structures/session.md
View File

@@ -60,6 +60,30 @@ interface SessionEventMap {
* cordis-catalog row.
*/
'todo/write': { todos: TodoItem[] }
/**
* Full snapshot of the {@link EpochHeader} the NEXT request is built under,
* with the {@link RequestHeaderReason} it was recorded whole. Appended by
* the loop inside the step, before dispatch, on a loop instance's first
* request-building step (`'initial'`/`'resume'`) or when a delta failed its
* round-trip guard (`'fallback'`); always records what the request actually
* used, post-`agent/request`. Anchors the header fold: reconstruction reads
* the latest snapshot and applies the deltas after it. NOT a
* {@link SurfaceEventType}: it produces no LLM message — it is the request
* envelope, logged so every request is a pure function of the session log
* (the reconstructability RFC).
*/
'request/header': { header: EpochHeader; reason: RequestHeaderReason }
/**
* Amendment to the folded {@link EpochHeader}: at least one of a
* {@link SystemDelta}, a {@link ToolsDelta}, or a whole replacement
* {@link LlmCallConfig} (four scalars — not worth diffing). Appended by the
* loop inside the step, before dispatch, when the header for this request
* differs from the fold of the log so far; the writer verifies
* `applyHeaderDelta(previous, delta)` reproduces the new header exactly and
* falls back to a `'fallback'` `request/header` snapshot when it cannot, so
* a logged delta ALWAYS round-trips. NOT a {@link SurfaceEventType}.
*/
'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
}
```
@@ -74,6 +98,23 @@ export interface TodoItem {
}
```
### The request header events: `request/header` and `request/header-delta`
The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A `request/header` snapshot (reason `'initial' | 'resume' | 'fallback'`) anchors the fold at conversation birth, process boundaries, and delta-encoding fallbacks; `request/header-delta` events amend it mid-run. `foldRequestHeader(events)` reconstructs the header any request was built under; the writer round-trip-verifies every delta before logging it, so a well-formed log always folds. Neither is a `SurfaceEventType` — they produce no LLM message.
```ts type-equiv
export interface EpochHeader {
/** The conversation's call configuration (model + sampling scalars). */
config: LlmCallConfig
/** Rendered system prompt text; absent for a system-less request. */
system?: string
/** Assembled tool schemas; absent for a tool-less request. */
tools?: ToolSchema[]
}
```
Canonical form: an empty system prompt and an empty tool list are ABSENT fields, matching how requests are built. The delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts).
## `SessionEvent<T>` — one log entry
A proper discriminated union over `type` (not independent `type`/`data` unions), so `switch (event.type)` narrows `event.data` without casts. `seq` is the monotonic position in the log (`seq = log.length`); `time` is epoch ms.

8
docs/event-producer-consumer.md
View File

@@ -21,10 +21,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:33`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`llm-replay`](../packages/support/llm-replay) |
| `session/created` | `emit` | [`packages/core/session/src/index.ts:36`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence) |
| `session/event` | `emit` | [`packages/core/session/src/index.ts:44`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:54`](../packages/core/session/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`parallel`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:35`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`llm-replay`](../packages/support/llm-replay) |
| `session/created` | `emit` | [`packages/core/session/src/index.ts:37`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence) |
| `session/event` | `emit` | [`packages/core/session/src/index.ts:45`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:55`](../packages/core/session/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`parallel`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:98`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:83`](../packages/subagent/subagent/src/index.ts) | - | [`tool-subagent`](../packages/subagent/tool-subagent) |

48
docs/persistence-catalog/log-events.md
View File

@@ -23,7 +23,7 @@ Raw stream chunk — token-level replay fidelity.
Types: [StreamChunk](../core-data-structures/llm-streaming.md)
Source: [`packages/core/session/src/types.ts:237`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:298`](../../packages/core/session/src/types.ts)
#### `assistant/message` — surface
@@ -35,7 +35,7 @@ Assembled assistant message for one step (derived history uses this). Carries th
Types: [ContentBlock](../core-data-structures/core.md) · [TokenUsage](../core-data-structures/llm-streaming.md)
Source: [`packages/core/session/src/types.ts:244`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:305`](../../packages/core/session/src/types.ts)
### `compact/*`
@@ -83,7 +83,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte
Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
Source: [`packages/core/session/src/types.ts:235`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:296`](../../packages/core/session/src/types.ts)
### `hook/*`
@@ -119,7 +119,29 @@ A queued prompt an `agent/prompt-submit` listener VETOED — the durable record
Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
Source: [`packages/core/session/src/types.ts:229`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:290`](../../packages/core/session/src/types.ts)
### `request/*`
#### `request/header` — log-only
Full snapshot of the EpochHeader the NEXT request is built under, with the RequestHeaderReason it was recorded whole. Appended by the loop inside the step, before dispatch, on a loop instance's first request-building step (`'initial'`/`'resume'`) or when a delta failed its round-trip guard (`'fallback'`); always records what the request actually used, post-`agent/request`. Anchors the header fold: reconstruction reads the latest snapshot and applies the deltas after it. NOT a SurfaceEventType: it produces no LLM message — it is the request envelope, logged so every request is a pure function of the session log (the reconstructability RFC).
```ts persistence-catalog
'request/header': { header: EpochHeader; reason: RequestHeaderReason }
```
Source: [`packages/core/session/src/types.ts:350`](../../packages/core/session/src/types.ts)
#### `request/header-delta` — log-only
Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta, or a whole replacement LlmCallConfig (four scalars — not worth diffing). Appended by the loop inside the step, before dispatch, when the header for this request differs from the fold of the log so far; the writer verifies `applyHeaderDelta(previous, delta)` reproduces the new header exactly and falls back to a `'fallback'` `request/header` snapshot when it cannot, so a logged delta ALWAYS round-trips. NOT a SurfaceEventType.
```ts persistence-catalog
'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
```
Source: [`packages/core/session/src/types.ts:361`](../../packages/core/session/src/types.ts)
### `steering/*`
@@ -133,7 +155,7 @@ Steering content injected between steps of a running turn.
Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
Source: [`packages/core/session/src/types.ts:262`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:323`](../../packages/core/session/src/types.ts)
### `step/*`
@@ -145,7 +167,7 @@ Closes step `step` of turn `turn`.
'step/end': { turn: number; step: number }
```
Source: [`packages/core/session/src/types.ts:216`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:277`](../../packages/core/session/src/types.ts)
#### `step/start` — log-only
@@ -155,7 +177,7 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it
'step/start': { turn: number; step: number }
```
Source: [`packages/core/session/src/types.ts:214`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:275`](../../packages/core/session/src/types.ts)
### `todo/*`
@@ -171,7 +193,7 @@ NOT a SurfaceEventType: it produces no LLM message and never reaches `deriveMess
Types: [TodoItem](../core-data-structures/session.md)
Source: [`packages/core/session/src/types.ts:276`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:337`](../../packages/core/session/src/types.ts)
### `tool/*`
@@ -185,7 +207,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st
Types: [CallId](../core-data-structures/core.md)
Source: [`packages/core/session/src/types.ts:250`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:311`](../../packages/core/session/src/types.ts)
#### `tool/result` — surface
@@ -197,7 +219,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta
Types: [CallId](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md)
Source: [`packages/core/session/src/types.ts:260`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:321`](../../packages/core/session/src/types.ts)
### `turn/*`
@@ -211,7 +233,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai
Types: [TurnEndReason](../core-data-structures/session.md)
Source: [`packages/core/session/src/types.ts:212`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:273`](../../packages/core/session/src/types.ts)
#### `turn/start` — log-only
@@ -223,7 +245,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch
Types: [TurnTrigger](../core-data-structures/session.md)
Source: [`packages/core/session/src/types.ts:206`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:267`](../../packages/core/session/src/types.ts)
### `user/*`
@@ -237,4 +259,4 @@ A user-visible prompt (queued message drained at turn start).
Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
Source: [`packages/core/session/src/types.ts:218`](../../packages/core/session/src/types.ts)
Source: [`packages/core/session/src/types.ts:279`](../../packages/core/session/src/types.ts)