@deepseek-ai/dsh-session 0.2.2-rc.1 → 0.2.2-rc.3

package/src/known-event-types.ts

@@ -0,0 +1,91 @@
+/**
+ * GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+ * `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+ * `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+ * @module @deepseek-ai/dsh-session/known-event-types
+ */
+
+/**
+ * Every `SessionEventMap` member declared in this repository — the event
+ * vocabulary this build understands. The persistence read path refuses to
+ * interpret a log containing a type outside this set unless the event
+ * carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+ * in `./types.ts`): such a log was likely written by a newer harness, and
+ * silently skipping a required event would reconstruct a wrong session.
+ * Downstream (out-of-repo) plugin events are outside this list by
+ * construction. The persisted `SessionEvent.ignorable` marker is the
+ * compatibility mechanism; event-name registration was rejected because
+ * it does not classify omission safety and would make reads
+ * composition-dependent. The rationale is in
+ * `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
+ */
+export const KNOWN_SESSION_EVENT_TYPES: ReadonlySet<string> = new Set([
+  'agent-preset/selected',
+  'agent/inbox/spliced',
+  'approval/asked',
+  'approval/decided',
+  'approval/policy',
+  'assistant/attempt',
+  'assistant/message',
+  'command/done',
+  'command/run',
+  'compaction/end',
+  'compaction/prune',
+  'compaction/start',
+  'compaction/summary',
+  'deliverables/presented',
+  'developer/message',
+  'feedback/message-delete',
+  'feedback/message-put',
+  'feedback/record',
+  'goal/change',
+  'hook/invoked',
+  'hook/result',
+  'image/offload',
+  'job/registered',
+  'job/settled',
+  'llm/retry',
+  'llm/retry-started',
+  'model/selection',
+  'permission/preset',
+  'plan/mode',
+  'request/context',
+  'request/header',
+  'sandbox/mode',
+  'schedule/change',
+  'session-log-deepseek/delivery-accepted',
+  'session/end-seed',
+  'session/title',
+  'session/title-llm-request',
+  'step/end',
+  'step/start',
+  'subagent/catalog',
+  'subagent/descriptor',
+  'subagent/model-selection-policy',
+  'system/message',
+  'team/member',
+  'team/message/delivered',
+  'team/message/queued',
+  'team/mode',
+  'team/task',
+  'todo/write',
+  'tool-workflow/agent-end',
+  'tool-workflow/agent-start',
+  'tool-workflow/run-end',
+  'tool-workflow/run-start',
+  'tool/call',
+  'tool/ptc-dispatch',
+  'tool/ptc-dispatch-start',
+  'tool/result',
+  'turn/end',
+  'turn/start',
+  'user/message',
+  'web/deepseek-search-llm-request',
+  'working-directory/change',
+  'workspace/changes',
+])
+
+/** Event types whose model-visible effects require an explicit pure interpreter. */
+export const MESSAGE_PROJECTION_EVENT_TYPES: ReadonlySet<string> = new Set([
+  'image/offload',
+])

package/src/preparation.ts

@@ -0,0 +1,49 @@
+/**
+ * Ownership of one unpublished Session before registry publication.
+ * @module @deepseek-ai/dsh-session/preparation
+ */
+
+import type { Session } from './index.ts'
+
+/** Options for a preparation whose provider retains unpublished state. */
+export interface SessionPreparationOptions {
+  /** Release provider-owned state when the Session was not published. */
+  readonly release?: () => void
+}
+
+/**
+ * One exact unpublished Session and the provider state that keeps it usable.
+ * Disposal is synchronous and idempotent. Providers decide whether release
+ * returns the Session to a cache or discards it; publication may consume that
+ * state before disposal, making the callback a no-op.
+ */
+export class SessionPreparation implements Disposable {
+  private released = false
+
+  /** The exact Session to use for setup and publication. */
+  readonly session: Session
+
+  private constructor(
+    session: Session,
+    private readonly options: SessionPreparationOptions,
+  ) {
+    this.session = session
+  }
+
+  /**
+   * Wrap an unpublished Session in one preparation lifetime.
+   * @param session - exact unpublished Session.
+   * @param options - optional provider release behavior.
+   * @returns a preparation disposed after publication or rollback.
+   */
+  static create(session: Session, options?: SessionPreparationOptions): SessionPreparation {
+    return new SessionPreparation(session, options ?? {})
+  }
+
+  /** Release provider state once when this preparation leaves its caller. */
+  [Symbol.dispose](): void {
+    if (this.released) return
+    this.released = true
+    this.options.release?.()
+  }
+}

package/src/repair.ts

@@ -0,0 +1,211 @@
+/**
+ * Pending tool-result recovery shared by failed live steps, interrupted logs,
+ * and fork seeds. Tail repair preserves closed steps and supplies only missing
+ * tool results and lifecycle boundaries, with cause-specific retry guidance.
+ * @module @deepseek-ai/dsh-session/repair
+ */
+
+import { brandString } from '@deepseek-ai/dsh-brand'
+import type { MessageId, ToolCallId, ToolResultMessage } from '@deepseek-ai/dsh-llm'
+import { deepFreeze } from '@deepseek-ai/dsh-util-values'
+import { SessionSeq } from './types.ts'
+import type { SessionEvent, SessionSeq as SessionSeqType } from './types.ts'
+
+/** Recovery code for an assistant tool request that never reached a recorded call start. */
+export const TOOL_NOT_STARTED = 'TOOL_NOT_STARTED'
+
+/** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
+export const TOOL_OUTCOME_UNKNOWN = 'TOOL_OUTCOME_UNKNOWN'
+
+/**
+ * Why an open tail turn is closed with synthetic events: `interrupted` is
+ * crash recovery over a persisted log; `forked` is a fork seed cut inside the
+ * source's open turn. The cause selects the synthetic `turn/end` reason, the
+ * model-visible wording of synthetic error tool results, and the
+ * deterministic synthetic message-id prefix. The error codes
+ * ({@link TOOL_NOT_STARTED} / {@link TOOL_OUTCOME_UNKNOWN}) are shared: both
+ * causes state the same fact about the call's recorded lifecycle.
+ */
+export type OpenTurnCloseCause = { readonly kind: 'interrupted' } | { readonly kind: 'forked' }
+
+/** Model-visible wording of the synthetic error tool results, keyed by cause. */
+const CLOSER_TEXT = {
+  interrupted: {
+    started: 'The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.',
+    notStarted: 'The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed.',
+  },
+  forked: {
+    started: 'The history inherited by this branch records this tool call starting but does not include its result. The parent session may have completed it after the fork point. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.',
+    notStarted: 'The history inherited by this branch has no record of this tool call starting. The parent session may have executed it after the fork point. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.',
+  },
+} as const
+
+/**
+ * Return deterministic synthetic events that close an open tail turn. Unmatched
+ * calls receive error results first, followed by an open `step/end` and a
+ * cause-specific `turn/end`; sequences continue the log and timestamps reuse the
+ * last real event. A balanced or empty log returns no events.
+ *
+ * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+ * @param cause - the owning close operation: selects result wording and the turn-ending reason.
+ * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
+ */
+export function openTurnClosers(events: readonly SessionEvent[], cause: OpenTurnCloseCause): SessionEvent[] {
+  let openTurn: number | null = null
+  let openStep: number | null = null
+  const recovery = new ToolCallRecovery(cause)
+  for (const event of events) {
+    recovery.observe(event)
+    switch (event.type) {
+      case 'turn/start':
+        openTurn = event.data.turn
+        openStep = null
+        break
+      case 'turn/end':
+        openTurn = null
+        openStep = null
+        break
+      case 'step/start':
+        openStep = event.data.step
+        break
+      case 'step/end':
+        openStep = null
+        break
+      // Other event types do not move the turn/step boundary cursor.
+      default:
+        break
+    }
+  }
+
+  // Balanced log (no open tail turn): nothing to close. An open turn implies
+  // `events` is non-empty (its turn/start was logged), so `last` exists.
+  const last = events.at(-1)
+  if (openTurn === null || last === undefined) return []
+
+  // The last real event supplies the seq base and the timestamp for the
+  // synthetic closers (reusing the last timestamp keeps them deterministic and
+  // never invents a "future" time).
+  const closers: SessionEvent[] = recovery.results()
+  let seq = last.seq + closers.length + 1
+  const time = last.time
+
+  // Close an open step before its turn.
+  if (openStep !== null) {
+    closers.push({ type: 'step/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, step: openStep } })
+  }
+  closers.push({ type: 'turn/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, reason: { kind: cause.kind } } })
+  return closers
+}
+
+/**
+ * Track unanswered assistant tool requests from one Session's committed events.
+ * Observe from the start of the owned step or replay prefix, and recover before
+ * its step closes. This state retains pending identities, not event history.
+ */
+export class ToolCallRecovery {
+  private readonly pendingCalls = new Map<ToolCallId, { turn: number; step: number; callSeq?: SessionSeqType }>()
+  private last: Pick<SessionEvent, 'seq' | 'time'> | undefined
+
+  /** @param cause - defaults to interrupted live/crash recovery; fork-seed construction supplies its own cause. */
+  constructor(private readonly cause: OpenTurnCloseCause = { kind: 'interrupted' }) {}
+
+  /**
+   * Consume the next committed event; closed steps and turn boundaries discard pending requests.
+   * @param event - the next event from the same Session, in sequence order.
+   */
+  observe(event: SessionEvent): void {
+    this.last = { seq: event.seq, time: event.time }
+    switch (event.type) {
+      case 'turn/start':
+      case 'turn/end':
+      case 'step/end':
+        this.pendingCalls.clear()
+        break
+      case 'assistant/message':
+        for (const block of event.data.message.content) {
+          if (block.type === 'tool-call') {
+            this.pendingCalls.set(block.id, { turn: event.data.turn, step: event.data.step })
+          }
+        }
+        break
+      case 'tool/call': {
+        const entry = this.pendingCalls.get(event.data.callId)
+        if (entry) entry.callSeq = event.seq
+        break
+      }
+      case 'tool/result': {
+        const callId = event.data.message.source.callId
+        const entry = this.pendingCalls.get(callId)
+        if (event.surfaceOp === 'append' && entry !== undefined
+          && entry.turn === event.data.turn && entry.step === event.data.step) {
+          this.pendingCalls.delete(callId)
+        }
+        break
+      }
+      // SessionEvent is merge-extensible; unrelated events retain pending requests.
+      default:
+        break
+    }
+  }
+
+  /**
+   * Build conservative error results in assistant order without changing tracked state.
+   * Sequences follow the latest observed event and timestamps reuse its time.
+   * Callers commit the results and observe those commits before recovering again.
+   * @returns pending tool-result events, empty when no request remains unanswered.
+   */
+  results(): SessionEvent<'tool/result'>[] {
+    if (this.last === undefined) return []
+    let seq = this.last.seq + 1
+    const time = this.last.time
+    const results: SessionEvent<'tool/result'>[] = []
+
+    const text = CLOSER_TEXT[this.cause.kind]
+    // Close calls before their step: providers reject dangling assistant calls,
+    // and Map insertion order preserves their transcript order.
+    for (const [callId, { turn, step, callSeq }] of this.pendingCalls) {
+      const started = callSeq !== undefined
+      const message: ToolResultMessage = deepFreeze({
+        id: brandString<MessageId>(`${this.cause.kind}-tool-result-${callId}-${seq}`),
+        role: 'tool',
+        toolCallId: callId,
+        isError: true,
+        source: { kind: 'tool', callId },
+        content: [{
+          type: 'text',
+          text: started ? text.started : text.notStarted,
+        }],
+      })
+      results.push({
+        type: 'tool/result',
+        seq: SessionSeq(seq++),
+        time,
+        data: {
+          turn,
+          step,
+          message,
+          error: started
+            ? { name: 'ToolOutcomeUnknownError', code: TOOL_OUTCOME_UNKNOWN }
+            : { name: 'ToolNotStartedError', code: TOOL_NOT_STARTED },
+        },
+        surfaceOp: 'append',
+        ...started ? { sourceEventSeqs: [callSeq] } : {},
+      })
+    }
+
+    return results
+  }
+}
+
+/**
+ * Crash-recovery entry point: synthetic closers that balance a persisted log
+ * whose tail turn was interrupted. Used by crash-recovery callers; fork
+ * seeds receive their `forked`-cause closers through `buildForkSeed` in
+ * `./fork.ts`.
+ *
+ * @param events - the persisted log to scan, possibly ending inside an open turn.
+ * @returns the synthetic `interrupted` closer events to append after `events`; empty when the log is already balanced.
+ */
+export function interruptedTurnClosers(events: readonly SessionEvent[]): SessionEvent[] {
+  return openTurnClosers(events, { kind: 'interrupted' })
+}

package/src/request-header.ts

@@ -0,0 +1,69 @@
+/**
+ * Request-header reconstruction utilities over full `request/header` session
+ * events. Anyone holding a session log reconstructs the {@link EpochHeader}
+ * any request was built under by taking the latest canonical snapshot; the
+ * loop uses the same equality helper to avoid logging unchanged headers.
+ *
+ * @module dsh-session/request-header
+ */
+
+import { callConfigEquals } from '@deepseek-ai/dsh-llm'
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, SessionEvent } from './types.ts'
+
+/**
+ * Normalize a header to canonical form: an empty tool list becomes an absent
+ * field, matching how requests are built. Logging, folding, and comparison use
+ * this one representation.
+ * @param header - the header to normalize (not mutated).
+ * @returns the canonical header.
+ */
+export function canonicalHeader(header: EpochHeader): EpochHeader {
+  const adapterDefaults = header.adapterDefaults
+  return {
+    config: header.config,
+    ...adapterDefaults?.reasoningEffort === true || adapterDefaults?.maxTokens === true
+      ? { adapterDefaults }
+      : {},
+    ...header.tools !== undefined && header.tools.length > 0 ? { tools: header.tools } : {},
+  }
+}
+
+/** Canonical JSON equality for tool schemas assembled through the same path. */
+function sameSchema(a: ToolSchema, b: ToolSchema): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+/**
+ * Field-wise equality over canonical headers. Tool schemas compare in order.
+ * @param a - one canonical header.
+ * @param b - the other.
+ * @returns whether config, adapter defaults, and tools all match.
+ */
+export function headerEquals(a: EpochHeader, b: EpochHeader): boolean {
+  if (
+    !callConfigEquals(a.config, b.config)
+    || a.adapterDefaults?.reasoningEffort !== b.adapterDefaults?.reasoningEffort
+    || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens
+  ) return false
+  const at = a.tools ?? []
+  const bt = b.tools ?? []
+  return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema))
+}
+
+/**
+ * Fold the header events of a log (or any prefix) into the
+ * {@link EpochHeader} in force after the last snapshot. Non-header events are
+ * skipped. This is the pure offline reconstruction path; the live session
+ * tracks the same fold incrementally.
+ * @param events - session events in log order.
+ * @param from - a previously folded state to continue from.
+ * @returns the latest canonical header, or undefined when none exists yet.
+ */
+export function foldRequestHeader(events: readonly SessionEvent[], from?: EpochHeader): EpochHeader | undefined {
+  let state = from
+  for (const event of events) {
+    if (event.type === 'request/header') state = canonicalHeader(event.data.header)
+  }
+  return state
+}

package/src/seq-ranges.ts

@@ -0,0 +1,73 @@
+/** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
+
+import { SessionSeq } from './types.ts'
+import type { SessionSeq as SessionSeqType } from './types.ts'
+
+/** A stored source sequence or inclusive consecutive range. */
+export type EncodedSeq = number | [number, number]
+
+function isStrictlyIncreasing(values: readonly SessionSeqType[]): boolean {
+  return values.every((value, index) => index === 0 || value > (values[index - 1] as SessionSeqType))
+}
+
+/**
+ * Replace profitable consecutive runs with inclusive pairs.
+ * @param values - validated in-memory source sequences.
+ * @returns a lossless JSON storage form.
+ */
+export function encodeSeqRanges(values: readonly SessionSeqType[]): EncodedSeq[] {
+  if (!isStrictlyIncreasing(values)) return [...values]
+  const encoded: EncodedSeq[] = []
+  for (let start = 0; start < values.length;) {
+    let end = start
+    while (end + 1 < values.length && values[end + 1] === (values[end] as number) + 1) end += 1
+    if (end - start >= 2) encoded.push([values[start] as number, values[end] as number])
+    else for (let index = start; index <= end; index += 1) encoded.push(values[index] as number)
+    start = end + 1
+  }
+  return encoded
+}
+
+/**
+ * Expand a JSON storage-form source sequence array.
+ * @param value - parsed storage value.
+ * @param maxEntries - largest list permitted by the owning event.
+ * @returns the in-memory source sequences.
+ */
+export function decodeSeqRanges(value: unknown, maxEntries = Number.MAX_SAFE_INTEGER): SessionSeqType[] {
+  if (!Array.isArray(value)) throw new TypeError('sourceEventSeqs must be an array')
+  const decoded: SessionSeqType[] = []
+  let hasRange = false
+  for (const entry of value) {
+    if (typeof entry === 'number') {
+      assertSeq(entry)
+      if (decoded.length >= maxEntries) throw new TypeError('sourceEventSeqs exceeds its event sequence')
+      decoded.push(SessionSeq(entry))
+      continue
+    }
+    if (!Array.isArray(entry) || entry.length !== 2) {
+      throw new TypeError('sourceEventSeqs range entries must be [start, end] pairs')
+    }
+    const start: unknown = entry[0]
+    const end: unknown = entry[1]
+    assertSeq(start)
+    assertSeq(end)
+    if (end < start) throw new TypeError('sourceEventSeqs ranges require start <= end')
+    const length = end - start + 1
+    if (length > maxEntries - decoded.length) {
+      throw new TypeError('sourceEventSeqs range exceeds its event sequence')
+    }
+    for (let seq = start; seq <= end; seq += 1) decoded.push(SessionSeq(seq))
+    hasRange = true
+  }
+  if (hasRange && !isStrictlyIncreasing(decoded)) {
+    throw new TypeError('sourceEventSeqs ranges must be strictly increasing')
+  }
+  return decoded
+}
+
+function assertSeq(value: unknown): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new TypeError('sourceEventSeqs must contain non-negative safe integers')
+  }
+}