mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
25e02ae9a8
gen-cordis-catalog.ts now emits docs/cordis-catalog/events.md and docs/cordis-catalog/services.md instead of the combined events-and-services.md: a reader is either finding what to listen to or what to call, and each axis now scans and deep-links as its own page. Headings promote one level (scopes and ctx.<key> entries become H2), the dispatch-mode legend lives on the events page, and the inherited tier splits accordingly. --check verifies both files and names whichever is stale. Every reference updated in the same change (no compat redirects, pre-release stance): architecture.md, AGENTS.md, docs/AGENTS.md tier row, filesystem/subagent core-data-structures pages (the ctx.fs anchor survives — slugs are heading-level-independent), fs README, four RFCs, the tool-catalog and persistence-catalog generator intros (both regenerated), and the bilingual development.md pair (re-recorded).
241 lines
12 KiB
Markdown
241 lines
12 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:237`](../../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:244`](../../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:37`](../../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 }
|
|
```
|
|
|
|
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:235`](../../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)
|
|
|
|
### `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:229`](../../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:262`](../../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:216`](../../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:214`](../../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:276`](../../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:250`](../../packages/core/session/src/types.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:260`](../../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:212`](../../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:206`](../../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:218`](../../packages/core/session/src/types.ts)
|