@deepseek-ai/dsh-session 0.0.1-rc.1

package/lib/types/repair.js

@@ -0,0 +1,144 @@
+/**
+ * Crash-recovery repair for an interrupted session log. It preserves a fully
+ * written final turn and supplies the missing tool, step, and turn boundaries
+ * needed to resume with a provider-valid transcript, plus the activity-time
+ * read that must skip the end-seed boundary — which this module does
+ * not write (`Session`'s constructor does) but whose synthetic closers can
+ * inherit that boundary's timestamp, the one real coupling between the two.
+ * @module @deepseek-ai/dsh-session/repair
+ */
+import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm';
+/**
+ * The `time` of the log's last event representing actual work, skipping the
+ * `session/end-seed` boundary — picking a session up is not activity, so
+ * activity ordering must exclude it.
+ *
+ * Excluded by type, so a pickup time still leaks when a boundary is the last
+ * event of an open turn: {@link interruptedTurnClosers} copies it onto the
+ * synthetic `turn/end`, which this counts as work. Reachable only by seeding an
+ * unbalanced log directly — `load()` balances first.
+ * @param events - the log to scan, in seq order.
+ * @returns the latest non-boundary event's `time`, or undefined when there is none.
+ */
+export function lastActivityTime(events) {
+    return events.findLast(event => event.type !== 'session/end-seed')?.time;
+}
+/** 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';
+/**
+ * Return deterministic synthetic events that close an open tail turn. Unmatched
+ * calls receive error results first, followed by an open `step/end` and an
+ * interrupted `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).
+ * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
+ */
+export function interruptedTurnClosers(events) {
+    let openTurn = null;
+    let openStep = null;
+    // Reset at each turn boundary so earlier calls cannot leak into tail repair.
+    // Assistant blocks register calls; later `tool/call` events add their seqs to `sourceEventSeqs`.
+    const pendingCalls = new Map();
+    for (const event of events) {
+        switch (event.type) {
+            case 'turn/start':
+                openTurn = event.data.turn;
+                openStep = null;
+                pendingCalls.clear();
+                break;
+            case 'turn/end':
+                openTurn = null;
+                openStep = null;
+                pendingCalls.clear();
+                break;
+            case 'step/start':
+                openStep = event.data.step;
+                break;
+            case 'step/end':
+                pendingCalls.clear();
+                openStep = null;
+                break;
+            case 'assistant/message':
+                // The assistant message carries the tool-call blocks; each is pending
+                // until a tool/result event with the same callId is logged.
+                for (const block of event.data.message.content) {
+                    if (block.type === 'tool-call')
+                        pendingCalls.set(block.id, { step: event.data.step });
+                }
+                break;
+            case 'tool/call':
+                // Cite the `tool/call` seq from the synthetic result.
+                {
+                    const entry = pendingCalls.get(event.data.callId);
+                    if (entry) {
+                        entry.callSeq = event.seq;
+                    }
+                }
+                break;
+            case 'tool/result':
+                pendingCalls.delete(event.data.message.source.callId);
+                break;
+            // Other event types do not move the turn/step boundary cursor.
+            default:
+                break;
+        }
+    }
+    // Balanced log (no crash mid-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).
+    let seq = last.seq + 1;
+    const time = last.time;
+    const closers = [];
+    // Close calls before their step: providers reject dangling assistant calls,
+    // and Map insertion order preserves their transcript order.
+    for (const [callId, { step, callSeq }] of pendingCalls) {
+        const started = callSeq !== undefined;
+        const message = freezeMessage({
+            id: MessageId(`interrupted-tool-result-${callId}-${seq}`),
+            role: 'user',
+            source: { kind: 'tool', callId },
+            content: [{
+                    type: 'tool-result',
+                    toolCallId: callId,
+                    isError: true,
+                    content: [{
+                            type: 'text',
+                            text: 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.'
+                                : 'The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed.',
+                        }],
+                }],
+        });
+        closers.push({
+            type: 'tool/result',
+            seq: seq++,
+            time,
+            data: {
+                turn: openTurn,
+                step,
+                message,
+                error: started
+                    ? { name: 'ToolOutcomeUnknownError', code: TOOL_OUTCOME_UNKNOWN }
+                    : { name: 'ToolNotStartedError', code: TOOL_NOT_STARTED },
+            },
+            surfaceOp: 'append',
+            ...started ? { sourceEventSeqs: [callSeq] } : {},
+        });
+    }
+    // Close an open step next — a turn/end while a step is open is an invariant
+    // violation, so the step's boundary must be synthesized before the turn's.
+    if (openStep !== null) {
+        closers.push({ type: 'step/end', seq: seq++, time, data: { turn: openTurn, step: openStep } });
+    }
+    closers.push({ type: 'turn/end', seq: seq++, time, data: { turn: openTurn, reason: { kind: 'interrupted' } } });
+    return closers;
+}
+//# sourceMappingURL=repair.js.map

package/lib/types/request-header.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 type { EpochHeader, SessionEvent } from './types.ts';
+/**
+ * Normalize a header to canonical form: an empty system prompt and empty tool
+ * list become absent fields, 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 declare function canonicalHeader(header: EpochHeader): EpochHeader;
+/**
+ * Field-wise equality over canonical headers. Tool schemas compare in order.
+ * @param a - one canonical header.
+ * @param b - the other.
+ * @returns whether config, system, and tools all match.
+ */
+export declare function headerEquals(a: EpochHeader, b: EpochHeader): boolean;
+/**
+ * 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 declare function foldRequestHeader(events: readonly SessionEvent[], from?: EpochHeader): EpochHeader | undefined;
+//# sourceMappingURL=request-header.d.ts.map

package/lib/types/request-header.js

@@ -0,0 +1,65 @@
+/**
+ * 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';
+/**
+ * Normalize a header to canonical form: an empty system prompt and empty tool
+ * list become absent fields, 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) {
+    const adapterDefaults = header.adapterDefaults;
+    return {
+        config: header.config,
+        ...adapterDefaults?.reasoningEffort === true || adapterDefaults?.maxTokens === true
+            ? { adapterDefaults }
+            : {},
+        ...header.system !== undefined && header.system.length > 0 ? { system: header.system } : {},
+        ...header.tools !== undefined && header.tools.length > 0 ? { tools: header.tools } : {},
+    };
+}
+/** Canonical JSON equality for tool schemas assembled through the same path. */
+function sameSchema(a, b) {
+    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, system, and tools all match.
+ */
+export function headerEquals(a, b) {
+    if (!callConfigEquals(a.config, b.config)
+        || a.adapterDefaults?.reasoningEffort !== b.adapterDefaults?.reasoningEffort
+        || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens
+        || a.system !== b.system)
+        return false;
+    const at = a.tools ?? [];
+    const bt = b.tools ?? [];
+    return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i]));
+}
+/**
+ * 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, from) {
+    let state = from;
+    for (const event of events) {
+        if (event.type === 'request/header')
+            state = canonicalHeader(event.data.header);
+    }
+    return state;
+}
+//# sourceMappingURL=request-header.js.map

package/lib/types/surface.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Surface layer on top of the session event log: an ordered view of events
+ * that produce LLM messages. The append-only log remains the source of truth.
+ *
+ * Browser-safe: web clients consume this subpath export, so it must stay free
+ * of `node:` imports (they break the vite bundle).
+ *
+ * @module @deepseek-ai/dsh-session/surface
+ */
+import type { Message } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SurfaceEvent, SurfaceOp } from './types.ts';
+/**
+ * Whether an event type can join the model-visible surface.
+ * @param type - event type to test.
+ * @returns true for one of the three message-producing event types.
+ */
+export declare function isSurfaceEligibleType(type: string): boolean;
+/**
+ * Narrow an event to a surface-eligible event carrying its required marker.
+ * @param event - event to test.
+ * @returns true when both the type and marker identify a surface event.
+ */
+export declare function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent;
+/**
+ * Narrow an event to an append-origin surface event: one that entered the
+ * surface at its own log position and was never itself a replacement copy.
+ *
+ * The model-visible surface deliberately shadows replaced ranges, so it is the
+ * wrong source for a human transcript — a landed replacement would erase
+ * conversation the user already saw. Append-origin events are that transcript's
+ * durable source material; replacement copies stay model-only.
+ * @param event - event to test.
+ * @returns true when the event appended to the surface tail.
+ */
+export declare function isAppendSurfaceEvent(event: SessionEvent): event is SurfaceEvent & {
+    surfaceOp: 'append';
+};
+/**
+ * Narrow an event to a surface replacement: a node that shadowed an existing
+ * surface range instead of appending to the tail. The counterpart of
+ * {@link isAppendSurfaceEvent} over the two {@link SurfaceOp} variants.
+ * @param event - event to test.
+ * @returns true when the event replaced a surface range.
+ */
+export declare function isReplacementSurfaceEvent(event: SessionEvent): event is SurfaceEvent & {
+    surfaceOp: Extract<SurfaceOp, {
+        op: 'replace';
+    }>;
+};
+/**
+ * Project a single event into the LLM message it derives to, or null when it
+ * produces none — a non-surface event (chunk, boundary, log-only record) or an
+ * empty-content assistant/message (which exists only to host usage). This is
+ * THE per-node projection rule: `Session.deriveMessages` folds it over the
+ * live surface, external reconstructors and pure projections fold the same
+ * function over a log prefix's surface to rebuild the exact messages any
+ * request was built from. The returned message is the already frozen message
+ * nested in the event wrapper and shared by delivery, durable history, and
+ * model requests.
+ * @param event - the event to project.
+ * @returns the derived message, or null when the event produces none.
+ */
+export declare function deriveEventMessage(event: SessionEvent): Message | null;
+/** One replacement operation observed while folding a session surface. */
+export interface SurfaceFoldReplacement {
+    /** Seq of the event that replaced the prior surface range. */
+    seq: number;
+    /** Declared inclusive start seq of the replaced surface range. */
+    start: number;
+    /** Declared inclusive end seq of the replaced surface range. */
+    end: number;
+    /** Actual surface entries removed by the operation, in surface order. */
+    shadowedSeqs: number[];
+}
+/** Complete result of replaying the surface operations in a session log. */
+export interface SurfaceFoldResult {
+    /** Current surface event sequences in model-visible order. */
+    nodes: number[];
+    /** Replacement operations in event order. */
+    replacements: SurfaceFoldReplacement[];
+}
+/** Readonly live projection of the message-producing session events. */
+export interface SessionSurface {
+    /** Current surface event sequences in model-visible order. */
+    readonly nodes: readonly number[];
+    /** Monotonic count of committed positional replacements. */
+    readonly replaceGeneration: number;
+}
+/**
+ * Replay a complete session log through the canonical surface fold.
+ * @param events - session events in contiguous seq order.
+ * @returns detached current sequences and replacement history.
+ * @throws when an event violates surface metadata, source-event references, range, or tool-result rewrite rules.
+ */
+export declare function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult;
+/** Incremental ordered surface view and append-boundary validator. */
+export declare class SurfaceManager implements SessionSurface {
+    private log;
+    private readonly baseSeq;
+    /** Shared transition state; replacement history is not retained. */
+    private _state;
+    /** Last processed absolute seq. */
+    private _lastProcessedSeq;
+    /** Candidate already validated by `validateNext`, pending exact log admission. */
+    private _pendingPlan;
+    /**
+     * @param log - Contiguous complete log or loaded event window.
+     * @param baseSeq - Absolute sequence of the window's first event.
+     */
+    constructor(log: readonly SessionEvent[], baseSeq?: number);
+    /**
+     * Validate the next candidate without mutating the committed surface.
+     * @param event - candidate event that has not entered the log yet.
+     */
+    validateNext(event: SessionEvent): void;
+    /** Monotonic count of folded positional replacements. */
+    get replaceGeneration(): number;
+    /** Surface event sequences in model-visible order. */
+    get nodes(): readonly number[];
+    /** Fold events appended since the previous access. */
+    private _processDelta;
+}
+//# sourceMappingURL=surface.d.ts.map