会话日志：Model-visible ⟺ logged

236export interface SessionEventMap {237  /**238   * Opens turn `turn` before the loop claims queued input or runs pre-step.239   * Rejection, empty input, cancellation, or failure may close it with no240   * step; otherwise the following identified `user/message` event or batch241   * records the messages entering the step.242   */243  'turn/start': { turn: number }244  /**245   * Closes turn `turn` with the {@link TurnEndReason} that ended it. A turn246   * with no entered step has no `step/start` or `step/end`. The loop does not await a247   * flush at turn boundaries: `dsh-session-checkpoint-policy` owns the248   * per-request durability checkpoint, and consumers that read storage after249   * `whenIdle()` flush themselves. Success commits the turn; rejection is250   * reported live and does not prevent later work.251   */252  'turn/end': { turn: number; reason: TurnEndReason }253  /** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */254  'step/start': { turn: number; step: number }255  /** Closes step `step` of turn `turn`. */256  'step/end': { turn: number; step: number }257  /**258   * A user-role message on the model-visible surface: a direct human prompt259   * (the queued message claimed for this turn), a synthetic `agent.inject()`260   * context (file-change notices, subdir AGENTS.md, skill content, cron261   * notifications, …), or an entered goal continuation round. All three262   * project their `content` verbatim; `source` tells them apart.263   */264  'user/message': UserMessage265  /** Raw stream chunk — token-level replay fidelity. */266  'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }267  /**268   * Assembled assistant message for one step (derived history uses this).269   * Carries the step's `usage` when the adapter reported token accounting, so270   * the model output and its accounting travel together (there is no separate271   * usage record). `usage` is absent when the adapter reported none. A turn272   * cancelled mid-stream finalizes its delivered text/reasoning prefix as this273   * event with `interrupted: true`; undispatched tool calls are absent. The274   * marker distinguishes that prefix without re-deriving interruption from turn275   * boundaries. An aborted turn with no such event streamed no visible content.276   */277  'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage; interrupted?: true }278  /**279   * The model requested one tool invocation: `name` with the raw `arguments`280   * JSON string exactly as the model produced it (unparsed). `callId` pairs the281   * call with its `tool/result`.282   */283  'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }284  /**285   * A completed tool call's model-facing result, optional internal failure286   * identity, and optional tool-private `meta` presentation payload. `meta` is287   * opaque to the core (the producing tool owns its shape and reads it back in288   * `presentResult`) but MUST be JSON-serializable: `Session.append`289   * runtime-validates all event data with `isJsonValue`, so a non-serializable290   * `meta` is rejected at the source, and the durable log reproduces the291   * identical card on replay. Absent292   * unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time293   * contextual diff here).294   */295  'tool/result': {296    turn: number297    step: number298    message: ToolResultMessage299    error?: { name: string; code: string }300    meta?: JsonValue301  }302  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */303  'todo/write': { todos: TodoItem[] }304  /**305   * Full header for the next request, appended inside its step before dispatch.306   * It is log-only; the latest snapshot reconstructs the request header.307   */308  'request/header': { header: EpochHeader; reason: RequestHeaderReason }309  /**310   * Route metadata for the next request, logged only when the route or capacity311   * changes. It does not participate in request reconstruction or header equality.312   */313  'request/context': RequestContext314  /**315   * Marks the end of a constructor seed. Events before it have smaller seq316   * values and came from the seed (resume, fork, or replay); this lifecycle317   * produced none of them. This log-only event is the durable projection of318   * {@link Session.firstLiveSeq}. Its payload is empty — position and `time`319   * carry the meaning.320   *321   * Locate the LAST one in stored history. A seed already ending in one is not322   * re-marked, so reopening an untouched session does not grow its log per323   * pickup and the event need not be at the current `firstLiveSeq`.324   *325   * `Session`'s constructor is the only legitimate writer. The invariant326   * companion deliberately constrains nothing here, so a plugin appending one327   * would silently classify every live bracket before it as seed history.328   *329   * An owner of a standalone open/close bracket (`compaction/start` …330   * `compaction/end`) reads it because seed history and live work are otherwise331   * byte-identical: an unmatched opening marker before this event belongs to332   * an ended lifecycle, whatever ended it. NOT a liveness signal about other333   * writers — a concurrently live session holds its own boundary elsewhere,334   * so tolerating concurrent writers needs a signal beyond the log.335   */336  'session/end-seed': Record<string, never>337}

339/** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */340export type SessionEventType = keyof SessionEventMap

61declare module '@deepseek-ai/dsh-session/types' {62  interface SessionEventMap {63    /**64     * Complete post-mutation goal state or clear tombstone.65     */66    'goal/change': GoalChangeMeta67  }68}

408export type SessionEvent<T extends SessionEventType = SessionEventType> = {409  [K in SessionEventType]: {410    type: K411    /** Monotonic sequence number within the session. */412    seq: number413    /** Unix epoch milliseconds. */414    time: number415    data: SessionEventMap[K]416    /**417     * Marks an event a reader may safely skip when it does not recognize418     * `type`. Absent means required: a reader meeting an unrecognized type419     * without this marker MUST refuse to reconstruct the session instead of420     * silently dropping the event, because an unrecognized required event may421     * change how the rest of the log is interpreted. A writer sets `true` only422     * on purely informational records whose loss cannot affect reconstruction;423     * defaulting to required means a forgotten marker over-refuses (an424     * inconvenience) rather than silently resuming a gutted session.425     */426    ignorable?: true427  } & (K extends SurfaceEventType ? {428    /**429     * Seq numbers of earlier events that this event cites as sources430     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,431     * or the surface nodes shadowed by a compaction replace node). An432     * `assistant/message` may carry a present empty array for a known empty433     * provider stream; when the field is absent, the event does not record which434     * earlier events produced the message.435     */436    sourceEventSeqs?: number[]437    /** How this event entered the surface; absent for non-surface events. */438    surfaceOp?: SurfaceOp439  } : object)440}[T]

604  append<T extends SessionEventType>(605    type: T,606    data: SessionEventMap[T],⋯    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []·  ): SessionEvent<T> {·    const surfaceOpts: SurfaceIntent | undefined = opts[0]·    const surfaceMetadata = {⋯      ...surfaceOpts?.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: surfaceOpts.sourceEventSeqs },⋯      ...surfaceOpts?.surfaceOp === undefined ? {} : { surfaceOp: surfaceOpts.surfaceOp },·    }·    const dataSnapshot = snapshotJsonValue(data)·    if (dataSnapshot === undefined) {·      throw new Error(`session event "${type}" carries non-JSON-serializable data`)·    }·    assertSupportedRequestHeader(type, dataSnapshot, `session event "${type}"`)·    const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata)·    if (surfaceMetadataSnapshot === undefined) {·      throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`)·    }·    const entry = attachments.get(this)·    if (entry?.appending) {·      throw new Error('session append cannot reenter while another append is being published')·    }·    const event = deepFreeze({·      type,·      seq: this.log.length,·      time: Date.now(),·      data: dataSnapshot,⋯      ...(surfaceMetadataSnapshot as { surfaceOp?: unknown; sourceEventSeqs?: unknown }),633    } as unknown as SessionEvent<T>)634    this.surfaceManager.validateNext(event as SessionEvent)635636    if (entry !== undefined) entry.appending = true637    try {638      let callbacks: SessionCallback[] | undefined639      const callbackArgs: unknown[] = [this, event]640      if (entry !== undefined) {641        callbacks = collectSessionCallbacks(entry.emitCtx, [entry.carrier, 'session/event', ...callbackArgs])642      }643      this.log.push(event as SessionEvent)644      this.eventsSnapshot = undefined645      if (callbacks !== undefined && entry !== undefined) {646        invokeContainedSessionObservers(entry.emitCtx, 'session/event', entry.id, callbackArgs, callbacks)647      }648      return event649    } finally {650      if (entry !== undefined) {651        entry.appending = false652        if (entry.detachRequested && !entry.announcing) entry.detach()653      }654    }655  }

83export function deriveEventMessage(event: SessionEvent): Message | null {84  // Intentionally non-exhaustive: only message-producing events derive85  // history; turn/step boundaries, chunks, usage, and errors are trace/replay86  // data.87  switch (event.type) {88    // Ordinary prompts and injected context project in user role: the event's89    // model-facing content stays verbatim. Do NOT re-add per-type framing90    // (e.g. `<context>`) here: framing is caller-owned — a producer bakes it91    // into `content`, as agent-instructions does with `<system-reminder>` — or,92    // if reintroduced, must be driven by the event `meta` map and a dedicated93    // renderer, keeping this projection a verbatim pass-through. See the94    // deferred design note in95    // ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md96    case 'user/message': {97      return event.data98    }99    case 'assistant/message': {100      // Skip an empty-content assistant/message: it exists only to host a101      // max-tokens step's usage and must not inject a content-less assistant102      // turn into the provider transcript.103      if (event.data.message.content.length === 0) return null104      return event.data.message105    }106    case 'tool/result': {107      return event.data.message108    }109    default:110      // A non-surface event (boundary, chunk, log-only record) projects to111      // no message. Merge-extensible union: no assertNever here.112      return null113  }114}

35export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {36  if (!SURFACE_EVENT_TYPES.has(event.type)) return false37  return (event as SessionEvent<SurfaceEventType>).surfaceOp !== undefined38}

708  /**709   * Derive the LLM message history by walking the ordered sequences of710   * message-producing events maintained by `surfaceOp` markers. The711   * surface is the single source of derived history: every message-producing712   * append records its `surfaceOp`, so a raw event with no marker (a chunk, a713   * turn boundary) is correctly absent, and a compaction `replace` deletes the714   * shadowed nodes from the derivation. The projection rules are715   * {@link deriveEventMessage}, folded per node.716   *717   * CACHED: each surface node is projected exactly once, when first seen — a718   * call costs O(new nodes), and a surface rewrite (a `replace`;719   * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is720   * a fresh snapshot per call (later appends never grow an array a caller721   * already holds); the `Message` objects in it are SHARED and **deep-frozen**.722   * Their content reuses the already frozen durable event data, so the cache723   * needs no second deep clone and consumers still cannot mutate the log.724   * @returns a fresh array of the shared, frozen derived history.725   */726  deriveMessages(): Message[] {727    const surface = this.surface728    const nodes = surface.nodes729    const generation = surface.replaceGeneration730    if (generation !== this.derivedGeneration) {731      this.derived = []732      this.derivedNodes = 0733      this.derivedGeneration = generation734    }735    for (const seq of nodes.slice(this.derivedNodes)) {736      // Surface sequences are built from this.log — seq is always a valid737      // index by construction. The non-null assertion expresses that invariant.738      // oxlint-disable-next-line typescript/no-non-null-assertion739      const msg = this.deriveEventMessage(this.log[seq]!)740      // A surface node is one of the five message-producing types, but an741      // empty-content assistant/message (a max-tokens step that hosts only742      // usage) derives to null and must not enter the transcript.743      if (msg) this.derived.push(msg)744    }745    this.derivedNodes = nodes.length746    return [...this.derived]747  }

64export type ChunkRow =65  | { type: 'text-chunks'; seq0: number; time0: number; data: TextRunData }66  | { type: 'reasoning-chunks'; seq0: number; time0: number; data: TextRunData }67  | { type: 'tool-call-chunks'; seq0: number; time0: number; data: ToolCallRunData }6869/** One durable log line's JSON value: a session event verbatim, or a packed chunk row. */70export type StorageRecord = SessionEvent | ChunkRow7172/**73 * Minimum members before a run packs. Below it a row's envelope rivals the74 * event lines it replaces. A format constant, not a tunable: both layouts75 * decode identically, so changing it never invalidates stored logs.76 */77const MIN_RUN = 3

192export function packChunkRuns(events: readonly SessionEvent[]): StorageRecord[] {193  const out: StorageRecord[] = []194  let kind: DeltaKind | undefined195  let run: DeltaEvent[] = []196  const flush = (): void => {197    if (kind !== undefined && run.length >= MIN_RUN) out.push(buildRow(kind, run))198    else out.push(...run)199    kind = undefined200    run = []201  }202  for (const event of events) {203    const k = classify(event)204    if (k === undefined) {205      flush()206      out.push(event)207      continue208    }209    const delta = event as DeltaEvent210    const last = run[run.length - 1]211    if (k === kind && last !== undefined && continues(last, delta, k)) {212      run.push(delta)213      continue214    }215    flush()216    kind = k217    run = [delta]218  }219  flush()220  return out221}

33/**34 * The on-disk session format version, stamped into every newly-written {@link SessionHeader}35 * and enforced by every persistence backend on load. The single source of truth for the36 * version — write sites and the load-time check all read it.37 * While the harness is unreleased it is pinned at `0`: no compatibility is38 * implied, incompatible logs are rejected, and no migration is provided.39 *40 * The version is a single monotonic integer with no major/minor split. Whether41 * a bump is needed is decided by what the WRITER emits, never by what a newer42 * reader can accept: bump exactly when an older runtime could no longer handle43 * a new log with full semantic correctness ("parses without error" is not44 * correctness — silently skipping content that shapes reconstruction is a45 * wrong read). Only structural changes reach that bar: the header shape, the46 * {@link SessionEvent} envelope, core event semantics, or the surface47 * mechanism (the {@link SurfaceEventType} set and {@link SurfaceOp} variants).48 * Adding an ordinary event type does not bump — the per-event49 * {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When50 * in doubt, bump: a near-identity upgrade step is almost free, a missed bump51 * makes older runtimes read new logs wrong silently. The full mechanism52 * (upgrade-step chain, in-memory view conversion, migrate-on-continue) is53 * recorded in the session-log-version-mechanism Agent Note54 * (`.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md`).55 */56export const SESSION_FORMAT_VERSION = 0

7**Remove this section at the first tagged release.** With no external consumers, prefer the correct foundation over compatibility shims: rename or repackage freely and update every reference together. Backends reject old on-disk formats. SQLite uses monotonic `SCHEMA_VERSION`; `dsh-session` keeps `SESSION_FORMAT_VERSION` at `0` with no compatibility promise.

1046  private assertVersion(meta: SessionHeader): void {1047    if (meta.version === SESSION_FORMAT_VERSION) return1048    throw this.unsupported(meta, sessionFormatVersionRefusal(meta.id, meta.version))1049  }10501051  /**1052   * Refuse a log containing an event type this build does not know, unless the1053   * writer marked the event ignorable: an unrecognized required event may1054   * change how the rest of the log must be interpreted, so silently skipping1055   * it would reconstruct a wrong session (the envelope contract on1056   * `SessionEvent.ignorable`). Runs on NORMALIZED events — after1057   * `snapshotStoredEvents`/`adoptStoredEvents` has upgraded the legacy shapes1058   * this build still reads and rejected the ones it does not, so those keep1059   * their specific diagnostics.1060   */1061  private assertEventsSupported(meta: SessionHeader, events: readonly SessionEvent[]): void {1062    for (const event of events) {1063      if (KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true) continue1064      throw this.unsupported(meta, `session "${meta.id}" contains event type "${event.type}" (seq ${event.seq}) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness`)1065    }1066  }

77export function sessionFormatVersionRefusal(id: string, version: number): string {78  return version > SESSION_FORMAT_VERSION79    ? `session "${id}" uses log format v${version}, but this harness reads only v${SESSION_FORMAT_VERSION}: the log was written by a newer harness — upgrade the harness to open it`80    : `session "${id}" uses log format v${version}, older than the supported v${SESSION_FORMAT_VERSION}, and this build ships no upgrade path for it`81}

1081  fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session {1082    if (childSessionId !== undefined && this.get(childSessionId) !== undefined) {1083      throw new SessionForkError(`session "${childSessionId}" already exists`, 'SESSION_ALREADY_EXISTS')1084    }1085    const liveSource = this._resolveForkSource(source)1086    const seed = this._forkSeed(liveSource, boundary)1087    return this.create(childSessionId, {1088      seed,1089      meta: {⋯        ...liveSource.header.cwd !== undefined ? { cwd: liveSource.header.cwd } : {},1091        parentSession: liveSource.id,1092        seedLength: seed.length,1093      },1094    })1095  }

13A `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()`); raw stream chunks are logged for token-level replay fidelity while the assembled `assistant/message` event is authoritative for derivation. Replay/fork = seed a new session with an existing log.⋯    // ... 同步追加与 session/flush 检查点的说明 ...·Appends are synchronous (the hot path never blocks on I/O); `session/event` is a sync notification; persistence plugins buffer write-behind and drain at the awaited `session/flush` checkpoint fired at every turn end.⋯    // ... 追加顺序契约的说明 ...17Ordering contract: the loop claims inbox messages before `agent/pre-step`, opens `step/start` only after an enter decision, then appends the returned `user/message` batch before request derivation. Provider output is assembled and appended as `assistant/message` before tool dispatch, so the durable log records the exact message the tools follow. Regression tests pin that ordering.

21**A mutable message array with events fired as notifications** — simpler, but state and log can diverge; with event-sourcing the log IS the state, so divergence is structurally impossible.

108- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.

94The session log is the source of the context the model sees. `deriveMessages()` projects model history from it, and raw `assistant/chunk` events preserve replay and UI fidelity. Fork, resume, transcripts, telemetry, and persistence all derive from this stream.9596**Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it. This is why a new model-visible input requires a new session event: extend `SessionEventMap` and render from the log.

19**A per-event `ignorable` marker covers vocabulary growth, so ordinary event additions never bump the version.** The event vocabulary is decided by which plugins are mounted, which a single version integer cannot describe. A reader meeting an unrecognized event type refuses to interpret the log unless the event carries `ignorable: true` in its envelope. The default is *required*: forgetting the marker over-refuses a resumable session (an inconvenience), while a default of ignorable would make the same mistake silently resume a gutted one (a safety failure). The architecture makes this sound: model-visible content flows only through the three `surfaceOp`-marked surface event types plus the `request/header`/`request/context` folds, so the dangerous unknowns are exactly the non-surface events that change how the rest of the log is read (`session/end-seed` is the existing example).

13**One monotonic integer, no major/minor split.** Whether a version step is auto-upgradable is a property of that step — expressed by whether its upgrader exists — not something a two-level numbering scheme should promise in advance (you rarely know at design time whether the next change will turn out "major"). This matches the SQLite backend's `SCHEMA_VERSION` precedent.⋯    // ... 升版判定的说明 ...15**The writer decides bumps, not the reader.** A bump is required exactly when an old runtime could no longer handle a new log with full semantic correctness. "Parses without error" is not the bar: silently skipping content that shapes reconstruction is a wrong read. Only structural changes qualify — header shape, event envelope, core event semantics, the surface mechanism (`SurfaceEventType` set, `SurfaceOp` variants). When unsure, bump: a near-identity upgrader is almost free, a missed bump silently corrupts old readers.

57# Get transcript path from hook input58TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')5960if [[ ! -f "$TRANSCRIPT_PATH" ]]; then61  echo "⚠️  Ralph loop: Transcript file not found" >&262  echo "   Expected: $TRANSCRIPT_PATH" >&263  echo "   This is unusual and may indicate a Claude Code internal issue." >&264  echo "   Ralph loop is stopping." >&265  rm "$RALPH_STATE_FILE"66  exit 067fi

69# Read last assistant message from transcript (JSONL format - one JSON per line)70# First check if there are any assistant messages71if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then72  echo "⚠️  Ralph loop: No assistant messages found in transcript" >&273  echo "   Transcript: $TRANSCRIPT_PATH" >&274  echo "   This is unusual and may indicate a transcript format issue" >&275  echo "   Ralph loop is stopping." >&276  rm "$RALPH_STATE_FILE"77  exit 078fi7980# Extract last assistant message with explicit error handling81LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)82if [[ -z "$LAST_LINE" ]]; then83  echo "⚠️  Ralph loop: Failed to extract last assistant message" >&284  echo "   Ralph loop is stopping." >&285  rm "$RALPH_STATE_FILE"86  exit 087fi8889# Parse JSON with error handling90LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '91  .message.content |92  map(select(.type == "text")) |93  map(.text) |94  join("\n")95' 2>&1)

3049- Fixed transcript chain breaks on `--resume` that could lose conversation history when async transcript writes fail silently

3431- Fixed `--resume` silently truncating recent conversation history due to a race between memory-extraction writes and the main transcript

591- Added warnings when transcript writes are failing (e.g. disk full) or when session saving is off due to an inherited environment variable, instead of losing transcripts silently