mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
edc065666f
Plan mode's stage 2 (RFC 2026-07-07-plan-mode). The exit tool: one required plan argument (the durable log artifact), execute re-checks the folded mode, then conducts the review over the user-interaction seam — one single-select question (Approve / Keep planning) with free text open — so an approval appends mode/set back to default in-turn and every other outcome (keep-planning feedback verbatim, aborted, no provider) returns the corrective isError with the mode unchanged. presentCall is a generic card titled by the plan's first heading carrying the plan markdown; over ACP the review rides the ask_user elicitation flow, in the terminal the stdio prompt queue — no approval-seam dependency. The ACP bridge maps the picker 1:1 onto ctx.modes (opportunistic, a type-only peer edge): session/new + session/load advertise availableModes/currentModeId, session/set_mode validates through set() and echoes an optimistic current_mode_update (the pending mode IS the selection; the logged mode/set lands at the boundary and, matching, is not re-sent), and a session/event listener re-notifies on each logged flip that differs from the last sent — the tool-driven exit updates the picker. The feature matrix rows move from 'not modeled' to the picker-to-modes / knobs-to-config-options division, with the ACP v2 removal direction recorded as a mechanical-migration risk. The snapshot harness gains the setMode/setModeExpectError ops and a scripted elicitationAnswers FIFO (cancel on exhaustion; a stray choice string reaches the agent verbatim as a non-consenting custom answer, so a scenario bug fails safe). The suite factory's header-pin requirement now applies only to model-turn scenarios — a protocol-only suite has no header content to anchor. examples/plan-acp-agent is the live composition; its keyless modes-advertise scenario pins the wire surface (advertisement, both set_mode round-trips, unknown-id rejection). The recorded plan-mode approve/reject arc awaits a with-key recording session; its texts are pinned at the unit tier meanwhile. examples/AGENTS.md ceiling 653 → 680: the new example's required smoke row does not fit the old budget.
287 lines
15 KiB
Markdown
287 lines
15 KiB
Markdown
<!-- Generated by scripts/gen-persistence-catalog.ts — do not edit by hand.
|
|
Run `pnpm run gen-persistence-catalog` to regenerate. -->
|
|
|
|
# Persistence Log Event Catalog
|
|
|
|
Every event type that can appear in a session's durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
|
|
|
|
This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Payload blocks use a `ts persistence-catalog` fence (skipped by doc-typecheck, since a bare payload fragment is not standalone-compilable). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md).
|
|
|
|
The on-disk envelope around every payload is `SessionEvent` — `type`, monotonic `seq`, epoch-ms `time`, the `data` documented here, plus `surfaceOp`/`sourceEventSeqs` on **surface** events only ([envelope](core-data-structures/session.md#sessioneventt--one-log-entry)). **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
|
|
|
|
## Events
|
|
|
|
### `assistant/*`
|
|
|
|
#### `assistant/chunk` — log-only
|
|
|
|
Raw stream chunk — token-level replay fidelity.
|
|
|
|
```ts persistence-catalog
|
|
'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
|
|
```
|
|
|
|
Types: [StreamChunk](core-data-structures/llm-streaming.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:313`](../packages/core/session/src/types.ts)
|
|
|
|
#### `assistant/message` — surface
|
|
|
|
Assembled assistant message for one step (derived history uses this). Carries the step's `usage` when the adapter reported token accounting, so the model output and its accounting travel together (there is no separate usage record). `usage` is absent when the adapter reported none.
|
|
|
|
```ts persistence-catalog
|
|
'assistant/message': { turn: number; step: number; content: ContentBlock[]; usage?: TokenUsage }
|
|
```
|
|
|
|
Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:320`](../packages/core/session/src/types.ts)
|
|
|
|
### `compact/*`
|
|
|
|
#### `compact/end` — log-only
|
|
|
|
Marks the end of a compaction — log-only, releases the lock. `error` set if summarization failed.
|
|
|
|
```ts persistence-catalog
|
|
'compact/end': { turn: number; error?: string }
|
|
```
|
|
|
|
Source: [`packages/compact/compact/src/types.ts:46`](../packages/compact/compact/src/types.ts)
|
|
|
|
#### `compact/start` — log-only
|
|
|
|
Marks the start of a compaction — log-only, holds the lock until `compact/end`.
|
|
|
|
```ts persistence-catalog
|
|
'compact/start': { turn: number }
|
|
```
|
|
|
|
Source: [`packages/compact/compact/src/types.ts:23`](../packages/compact/compact/src/types.ts)
|
|
|
|
#### `compact/summary` — log-only
|
|
|
|
Provenance record of a completed summarization — log-only, no surfaceOp. The summary content is in `data.summary`; the actual surface replacement is performed by a subsequent `user/message` event that shadows the compacted range.
|
|
|
|
```ts persistence-catalog
|
|
'compact/summary': { summary: ContentBlock[]; shadowedRange: { start: number; end: number }; shadowedSeqs: number[]; shadowedTokenCount: number; model: string; maxTokens?: number }
|
|
```
|
|
|
|
Types: [ContentBlock](core-data-structures/core.md)
|
|
|
|
Source: [`packages/compact/compact/src/types.ts:30`](../packages/compact/compact/src/types.ts)
|
|
|
|
### `context/*`
|
|
|
|
#### `context/message` — surface
|
|
|
|
In-session context injection (file-change notices, subdir AGENTS.md, skill content, cron notifications, …). Rendered into the derived history as tagged synthetic context — NOT a user prompt.
|
|
|
|
```ts persistence-catalog
|
|
'context/message': { content: ContentBlock[]; source: MessageSource }
|
|
```
|
|
|
|
Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:311`](../packages/core/session/src/types.ts)
|
|
|
|
### `hook/*`
|
|
|
|
#### `hook/invoked` — log-only
|
|
|
|
A hook command was invoked at a hook point — log-only provenance (like `compact/*`; NOT a SurfaceEventType, carries no `surfaceOp`). `dialect` is the bridge that ran it (`claude`/`codex`), `point` the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group pattern that selected it (absent for match-all), `handlerId` a stable id for the command (so an invoked/result pair correlates). `turn` is the open turn the invocation lives inside.
|
|
|
|
```ts persistence-catalog
|
|
'hook/invoked': { turn: number; point: string; dialect: HookDialect; matcher?: string; handlerId: string }
|
|
```
|
|
|
|
Source: [`packages/hooks/hook-protocol/src/types.ts:27`](../packages/hooks/hook-protocol/src/types.ts)
|
|
|
|
#### `hook/result` — log-only
|
|
|
|
A hook command's outcome — log-only, paired with a prior `hook/invoked` (same `handlerId`). `decision` is the dialect-neutral outcome derived by `appendHookResult` (which owns the rule): the hook's parsed decision (`approve`/`allow`/`block`/`deny`/`ask`), else `'stop'` when it asked to halt via `continue:false`, else `'pass'`. `exitCode` is the process exit (absent if it never ran), `stderrSummary` the trimmed stderr truncated to the bridge's configured cap (the block reason source on exit 2), `durationMs` the wall-clock runtime (audit timing; snapshot replay normalizes it). `turn` matches the `hook/invoked`.
|
|
|
|
```ts persistence-catalog
|
|
'hook/result': { turn: number; point: string; handlerId: string; decision: string; exitCode?: number; stderrSummary?: string; durationMs: number }
|
|
```
|
|
|
|
Source: [`packages/hooks/hook-protocol/src/types.ts:45`](../packages/hooks/hook-protocol/src/types.ts)
|
|
|
|
### `mode/*`
|
|
|
|
#### `mode/set` — log-only
|
|
|
|
The session mode in force from this point on: log-only, non-surface, whole-value replace — the last `mode/set` in the log wins (see foldMode). A log with none folds to DEFAULT_MODE.
|
|
|
|
```ts persistence-catalog
|
|
'mode/set': { mode: string }
|
|
```
|
|
|
|
Source: [`packages/mode/mode/src/index.ts:41`](../packages/mode/mode/src/index.ts)
|
|
|
|
### `prompt/*`
|
|
|
|
#### `prompt/blocked` — log-only
|
|
|
|
A queued prompt an `agent/prompt-submit` listener VETOED — the durable record of a blocked prompt and why. Appended in place of the `user/message` the prompt would have become, so the block survives replay even in a MIXED batch where another queued prompt is allowed (there the turn does not end `rejected`, so the boundary reason alone would not preserve it). `content` is the original prompt the listener rejected; `reason` is the veto text (PromptDecision `block.reason`). NOT a SurfaceEventType: a blocked prompt produces no LLM message and never reaches `deriveMessages()`.
|
|
|
|
```ts persistence-catalog
|
|
'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string }
|
|
```
|
|
|
|
Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:305`](../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:365`](../packages/core/session/src/types.ts)
|
|
|
|
#### `request/header-delta` — log-only
|
|
|
|
Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta, a whole replacement LlmCallConfig (four scalars — not worth diffing), or a whole replacement session prefix (`messagePrefix` — small advisory content, replaced whole; an EMPTY array encodes the transition to "none", mirroring the canonical form's absent field — the loop never produces one in practice: the prefix is composed once per instance and anchored by that instance's snapshot, so this arm exists for codec totality). 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; messagePrefix?: Message[] }
|
|
```
|
|
|
|
Source: [`packages/core/session/src/types.ts:382`](../packages/core/session/src/types.ts)
|
|
|
|
### `steering/*`
|
|
|
|
#### `steering/message` — surface
|
|
|
|
Steering content injected between steps of a running turn.
|
|
|
|
```ts persistence-catalog
|
|
'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
|
|
```
|
|
|
|
Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:338`](../packages/core/session/src/types.ts)
|
|
|
|
### `step/*`
|
|
|
|
#### `step/end` — log-only
|
|
|
|
Closes step `step` of turn `turn`.
|
|
|
|
```ts persistence-catalog
|
|
'step/end': { turn: number; step: number }
|
|
```
|
|
|
|
Source: [`packages/core/session/src/types.ts:292`](../packages/core/session/src/types.ts)
|
|
|
|
#### `step/start` — log-only
|
|
|
|
Opens step `step` of turn `turn` — one model call plus the tool executions it requested.
|
|
|
|
```ts persistence-catalog
|
|
'step/start': { turn: number; step: number }
|
|
```
|
|
|
|
Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/types.ts)
|
|
|
|
### `todo/*`
|
|
|
|
#### `todo/write` — log-only
|
|
|
|
The agent's whole todo list, carried as a full snapshot and replaced wholesale on each write — the current list is the most recent `todo/write` (last-write-wins on replay, no fold). Appended by an owning agent via `session.append('todo/write', { todos })`.
|
|
|
|
NOT a SurfaceEventType: it produces no LLM message and never reaches `deriveMessages()`, so it carries no `surfaceOp` and stays off the surface — it is durable, replayable UI state, distinct from the conversation history. It is a `SessionEventMap` member riding the existing `session/event` emit, not a first-class Cordis `interface Events` notification, so it has no cordis-catalog row.
|
|
|
|
```ts persistence-catalog
|
|
'todo/write': { todos: TodoItem[] }
|
|
```
|
|
|
|
Types: [TodoItem](core-data-structures/session.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:352`](../packages/core/session/src/types.ts)
|
|
|
|
### `tool/*`
|
|
|
|
#### `tool/call` — log-only
|
|
|
|
The model requested one tool invocation: `name` with the raw `arguments` JSON string exactly as the model produced it (unparsed). `callId` pairs the call with its `tool/result`.
|
|
|
|
```ts persistence-catalog
|
|
'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
|
|
```
|
|
|
|
Types: [CallId](core-data-structures/core.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:326`](../packages/core/session/src/types.ts)
|
|
|
|
#### `tool/code-dispatch` — log-only
|
|
|
|
One bridged sub-dispatch from a `run_code` program: the parent `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`), the tool `name` with its JSON-normalized `arguments` — the exact value dispatched, normalized BEFORE dispatch, so this append can never fail on payload shape — whether the sub-call errored, and a bounded `resultSummary` of its model-facing text. Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter model context; persistence and UIs get every call. Appended inside the parent `run_code`'s execution (the bridge drains its queue before returning), so the turn-enclosure invariant holds by construction.
|
|
|
|
```ts persistence-catalog
|
|
'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; resultSummary: string }
|
|
```
|
|
|
|
Types: [CallId](core-data-structures/core.md)
|
|
|
|
Source: [`packages/core/tools/src/code-mode.ts:36`](../packages/core/tools/src/code-mode.ts)
|
|
|
|
#### `tool/result` — surface
|
|
|
|
A completed tool call's model-facing result, plus an optional tool-private `meta` presentation payload. `meta` is opaque to the core (`unknown` — the producing tool owns its shape and reads it back in `presentResult`) but MUST be JSON-serializable: `Session.append` runtime-validates all event data with `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the durable log reproduces the identical card on replay. Absent unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here).
|
|
|
|
```ts persistence-catalog
|
|
'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
|
|
```
|
|
|
|
Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:336`](../packages/core/session/src/types.ts)
|
|
|
|
### `turn/*`
|
|
|
|
#### `turn/end` — log-only
|
|
|
|
Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awaited `session/flush` checkpoint at every turn end, so the turn boundary is also the durable-commit boundary.
|
|
|
|
```ts persistence-catalog
|
|
'turn/end': { turn: number; reason: TurnEndReason }
|
|
```
|
|
|
|
Types: [TurnEndReason](core-data-structures/session.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:288`](../packages/core/session/src/types.ts)
|
|
|
|
#### `turn/start` — log-only
|
|
|
|
Opens turn `turn`. `trigger` records what started it — a drained message batch or an idle-time injection. The turn is the durability/replay boundary: every event sits between a `turn/start` and its matching `turn/end` (the turn-enclosure invariant).
|
|
|
|
```ts persistence-catalog
|
|
'turn/start': { turn: number; trigger: TurnTrigger }
|
|
```
|
|
|
|
Types: [TurnTrigger](core-data-structures/session.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:282`](../packages/core/session/src/types.ts)
|
|
|
|
### `user/*`
|
|
|
|
#### `user/message` — surface
|
|
|
|
A user-visible prompt (queued message drained at turn start).
|
|
|
|
```ts persistence-catalog
|
|
'user/message': { content: ContentBlock[]; source: MessageSource }
|
|
```
|
|
|
|
Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
|
|
|
|
Source: [`packages/core/session/src/types.ts:294`](../packages/core/session/src/types.ts)
|