Merge remote-tracking branch 'origin/master' into session-surface

Reconcile the session-surface feature with master's package reorg and simplifications: - Adopt master's folded usage (assistant/message.usage; standalone `usage` event dropped) and re-attach surface metadata (surfaceOp/sourceEventSeqs). - Add surface opts to master's new max-tokens assistant/message append. - Port surface columns onto the coordinator-refactored SQLite backend at its new path; drop the dead v1->v2 migration (bump-and-reject, no migration per pre-release policy). - Move the session-surface RFC into implemented/architecture/ and refresh its stale body (no migration, SESSION_FORMAT_VERSION=0, renamed package paths). - Update the core-data-structures catalog SessionEvent blocks for the two new surface fields; regenerate the cordis catalog. - Re-harvest ACP snapshot fixtures (keyless replay) to carry surface metadata.
2026-06-22 10:35:59 +08:00
parent 0279cf09d6 6b4dc48fbd
commit 0298f5c6f0
388 changed files with 22901 additions and 6944 deletions
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -0,0 +1,298 @@
+# Core Data Structures
+
+This folder catalogs the **data structures** of the DeepSeek Harness — what each core type represents, its literal shape, and where the full detail lives. It complements [architecture.md](../architecture.md), which describes *behavior* (the service map, the session/turn/step lifecycle, the event taxonomy); this page describes the *vocabulary* that behavior moves around.
+
+## What counts as "core"
+
+The harness is a microkernel: a tiny core plus many plugins. Most types belong to one plugin or one capability. A handful, though, are the **spine** — the language the agent loop and its events traffic in on *every* turn, no matter which optional plugins are loaded. Those are "core".
+
+Precisely, a data structure is **core** if either:
+
+1. it flows through the agent-loop spine — the loop holds it, derives it, streams it, or logs it on every turn (a `Message`, a `StreamChunk`, a `SessionEvent`, the `Agent` handle itself), independent of which plugins are present; **or**
+2. it is the single headline type a plugin author writes against a pipeline — `ToolDefinition` (what every tool *is*).
+
+Everything else is documented on a **sub-page**, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a sub-page detail.* So `ToolDefinition` is core, but the `SchemaSpec`/`InferArgs` DSL that types it, the `ToolCallPresentation` vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on the sub-pages below.
+
+| Sub-page | Owns |
+|---|---|
+| [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, the turn-enclosure invariant |
+| [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
+| [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, the `tools/execute` waterfall |
+| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashTask`s |
+
+> Type definitions on this page are pasted **verbatim** from source and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Inline JSDoc is omitted for readability; follow the source link for the full contracts.
+
+## The `…Map → derived-union` pattern
+
+Almost every extensible sum type in the harness follows one shape: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.
+
+```ts ignore-check
+// The pattern, schematically:
+interface ThingMap {
+  'a': { kind: 'a'; /* … */ }
+  'b': { kind: 'b'; /* … */ }
+}
+type ThingKind = keyof ThingMap          // 'a' | 'b'
+type Thing = ThingMap[keyof ThingMap]    // the discriminated union
+
+// A plugin extends it without touching the source package:
+declare module '@deepseek-ai/dsh-llm' {
+  interface ThingMap {
+    'c': { kind: 'c'; /* … */ }
+  }
+}
+```
+
+Six canonical maps use this pattern; a plugin author extends these:
+
+| Map | Package | Derives | Catalog |
+|---|---|---|---|
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [below](#content-blocks-and-messages) |
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [below](#content-blocks-and-messages) |
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [below](#the-model-request-and-result) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
+| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
+| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
+
+Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag — don't chain `if`s — so each arm narrows and a typo'd tag fails to compile.
+
+## Branded IDs
+
+IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (an `AgentId` can't be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
+
+The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package (e.g. dsh-bash brands `BashTaskId`/`OwnerToken` via dsh-brand alone, never pulling in dsh-llm).
+
+Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
+
+```ts type-equiv
+type Branded<B extends string> = string & { readonly [BRAND]: B }
+```
+
+The three core IDs: `CallId` (correlates a tool call with its result; dsh-llm), `SessionId` (dsh-session), `AgentId` (dsh-agent). Each is `Branded<'CallId'>` etc. plus a same-named factory function. Capability seams brand their own ids too — see `BashTaskId`/`OwnerToken` in [bash.md](bash.md).
+
+## Content blocks and messages
+
+A conversation is `Message`s; a message is an array of typed **content blocks**. The block union derives from `ContentBlockMap`.
+
+Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+```ts type-equiv
+interface ContentBlockMap {
+  'text': TextBlock
+  'reasoning': ReasoningBlock
+  'tool-call': ToolCallBlock
+  'tool-result': ToolResultBlock
+  'image': ImageBlock
+}
+```
+
+The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ToolCallBlock` (`id: CallId`, `name`, raw-JSON `arguments`), `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`), `ImageBlock` (`url`, `mimeType?`). `ContentBlock = ContentBlockMap[ContentBlockType]`.
+
+A `Message` is a role plus blocks:
+
+```ts type-equiv
+interface Message {
+  role: 'system' | 'user' | 'assistant'
+  content: ContentBlock[]
+}
+```
+
+Where a message came from is itself a merge-extensible sum type:
+
+```ts type-equiv
+interface MessageSourceMap {
+  user: { kind: 'user' }
+  plugin: { kind: 'plugin'; plugin: string }
+  agent: { kind: 'agent'; agentId: string }
+}
+```
+
+## Streaming
+
+Adapters emit a raw **chunk** protocol; the loop logs the chunks (replay fidelity) while feeding the same chunks through a `BlockAssembler` to rebuild blocks and messages. `StreamChunk` is a closed discriminated union over `type` — `block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`.
+
+The full union, the adapter contract (usage-before-finish, raw-JSON tool arguments, the two sanctioned error paths), and `BlockAssembler` live on **[llm-streaming.md](llm-streaming.md)**.
+
+## The model request
+
+One model call is a fully-assembled `GenerateOptions`. The adapter answers with a raw `StreamChunk` stream; the consumer assembles it with `BlockAssembler` (see [llm-streaming.md](llm-streaming.md)).
+
+Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+```ts type-equiv
+interface GenerateOptions {
+  model: string
+  messages: Message[]
+  /** System prompt text (adapters map to the provider's system slot). */
+  system?: string
+  /** Tool schemas (adapters map to the provider's `tools` field). */
+  tools?: ToolSchema[]
+  /** Assistant prefix continuation (prefill). */
+  prefill?: ContentBlock[]
+  temperature?: number
+  maxTokens?: number
+  /**
+   * Stop sequences: generation halts as soon as the model produces any one of
+   * these strings (adapters map to the provider's stop field, e.g. OpenAI
+   * `stop`). The stop string itself is not included in the output.
+   */
+  stop?: string[]
+  signal?: AbortSignal
+}
+```
+
+Why a model response stopped is a merge-extensible reason:
+
+```ts type-equiv
+interface FinishReasonMap {
+  'stop': { kind: 'stop' }
+  'tool-calls': { kind: 'tool-calls' }
+  'max-tokens': { kind: 'max-tokens' }
+  'aborted': { kind: 'aborted' }
+  'error': { kind: 'error'; message: string; code?: string }
+}
+```
+
+`FinishReason = FinishReasonMap[keyof FinishReasonMap]`. `TokenUsage` (per-call accounting with disjoint cache fields) is detailed on [llm-streaming.md](llm-streaming.md).
+
+`GenerateOptions.tools` carries `ToolSchema` — the JSON-schema description of a tool, as sent to the model. It is declared in dsh-llm (not dsh-tools) precisely because it is part of the request the loop assembles every step:
+
+```ts type-equiv
+interface ToolSchema {
+  name: string
+  description: string
+  /** JSON Schema object for the arguments. */
+  parameters: Record<string, unknown>
+  strict?: boolean
+}
+```
+
+The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` that produces it (schema + `execute`) is on [tools.md](tools.md).
+
+## Sessions
+
+A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. The event vocabulary derives from `SessionEventMap`:
+
+Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
+
+```ts type-equiv
+type SessionEvent<T extends SessionEventType = SessionEventType> = {
+  [K in SessionEventType]: {
+    type: K
+    /** Monotonic sequence number within the session. */
+    seq: number
+    /** Unix epoch milliseconds. */
+    time: number
+    data: SessionEventMap[K]
+  } & (K extends SurfaceEventType ? {
+    /**
+     * Seq numbers of events that are provenance sources of this event
+     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
+     * or the surface nodes shadowed by a compaction marker).
+     */
+    sourceEventSeqs?: number[]
+    /** How this event entered the surface; absent for non-surface events. */
+    surfaceOp?: SurfaceOp
+  } : object)
+}[T]
+```
+
+The eleven event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `context/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`), 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
+
+`Agent` is the surface every plugin (UI, hooks, orchestrators) programs against. The concrete implementation is `ReactLoopAgent` in dsh-agent-loop; nothing outside the loop depends on the implementation.
+
+Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
+
+```ts type-equiv
+interface Agent {
+  readonly id: AgentId
+  readonly options: AgentOptions
+  readonly session: Session
+  readonly status: AgentStatus
+
+  /** Queue a user message. Starts a turn when idle; otherwise waits for the next turn. */
+  send(content: ContentBlock[], options?: SendOptions): void
+
+  /**
+   * Steer a running turn: content is injected between steps of the current
+   * turn. When idle, behaves like {@link send}.
+   */
+  steer(content: ContentBlock[], options?: SendOptions): void
+
+  /**
+   * Inject in-session context (file-change notices, skill content, cron
+   * notifications, …): appends a `context/message` session event the next model
+   * request sees at its chronological position, rendered as tagged synthetic
+   * context rather than a user prompt. Does not run the model.
+   *
+   * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn;
+   * an inject while idle wraps its `context/message` in a one-shot `injection`
+   * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for
+   * durability, so every event stays inside a turn and a persistence backend
+   * never loses a between-turn notice. The idle checkpoint is fire-and-forget
+   * (inject is synchronous): a failing flush is reported via `agent/error`
+   * (step `0`) and the logger, never thrown into the caller.
+   *
+   * Live-adapter review has validated the tagged-envelope rendering against
+   * current DeepSeek behavior; provider-specific mismatches belong in that
+   * adapter, not in the canonical session vocabulary.
+   */
+  inject(content: ContentBlock[], options?: SendOptions): void
+
+  /**
+   * Cancel ALL pending work for the agent. `cancel()`:
+   *
+   * - clears the queued FIFO (un-started prompts never run) and the steering
+   *   FIFO (steering for the cancelled turn is dropped, not re-enqueued);
+   * - aborts the in-flight step if one is running (the turn ends `aborted`);
+   * - drops a turn that is about to start (a `cancel()` landing in the
+   *   pre-step window — after a `send()` queued but before the loop flips to
+   *   `running`, or after `running` is emitted but before the first step) so
+   *   that queued prompt does not run and cannot be batched into the cancelled
+   *   turn.
+   *
+   * After `cancel()`, `whenIdle()` resolves on the post-cancel quiescent state.
+   * `cancel()` on an idle agent with nothing queued or running is a safe no-op
+   * — it does NOT arm anything that would drop a later legitimate prompt.
+   */
+  cancel(reason?: string): void
+
+  /**
+   * Resolve once the agent has reached quiescence after settling out of
+   * `running`, or immediately if it is already idle with no queued work. A
+   * non-owner's quiescence-observation hook: a consumer that does NOT own the
+   * agent's lifecycle awaits this to proceed only after queued/running work has
+   * fully stopped, rather than returning while the driver is still streaming or
+   * about to start a queued turn — without itself tearing the agent down. (A
+   * lifecycle OWNER does not need it: `AgentHandle.dispose()` already awaits the
+   * loop-exit promise directly as part of stopping and unregistering. So this is
+   * for a non-owning observer — e.g. a test awaiting a turn to settle, or a
+   * monitor — that wants the settle signal but must not dispose the agent.)
+   *
+   * "Quiescence", not merely "status changed": a disposed agent emits
+   * `agent/status('disposed')` from inside its disposer, BEFORE the driver loop
+   * has unwound — so `whenIdle()` resolving on `disposed` must wait for the loop
+   * to actually exit (the implementation chains the loop-exit promise), not just
+   * observe the status flip. A mid-step disposal that never reaches `idle` still
+   * unblocks the await this way.
+   */
+  whenIdle(): Promise<void>
+
+  // TODO(sub-agents): spawn/fork seams — semantics deliberately deferred.
+  // The intended shape: a creation option referencing a parent agent
+  // (fork = seed the child Session with the parent's event log; spawn =
+  // fresh Session), with the child returned as an Agent handle so steer()
+  // and event subscription work uniformly. See docs/architecture.md.
+}
+```
+
+`AgentStatus` is `'idle' | 'running' | 'disposed'`. `AgentId` is a branded string. `AgentOptions` (`model?`, `systemPrompt?`) is merge-extensible — plugins add creation options by declaration merging. The `agent/*` event taxonomy (lifecycle, turn/step boundaries, the `agent/request`/`agent/step-result`/`agent/turn-continuation` waterfalls) is in [architecture.md § Event taxonomy](../architecture.md#event-taxonomy).
+
+## `ToolDefinition`
+
+The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional UI presenters. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed args), but it is the contract the registry holds and the loop dispatches through.
+
+Its full fields, the `defineTool`/`SchemaSpec`/`InferArgs` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall shapes, and the tool-presentation UI vocabulary are on **[tools.md](tools.md)**.