@amalgm/chat 0.1.0

package/dist/turns/replay.js

@@ -0,0 +1,163 @@
+/**
+ * The replay grammar — engine `chat-core/streams.js` (160 lines), with the
+ * host I/O peeled off. streams.js mixes SSE response plumbing (headers,
+ * heartbeat timers, `res.write`) with the replay LAW: which payloads a tail
+ * emits, in what order, and when the stream closes. This module is the law
+ * as pure functions; the host owns the socket, the timer, and the actual
+ * subscription wiring.
+ *
+ * Host contract (mirrors streams.js:97-117):
+ *   1. `createTurnTail(entry, options)` — apply `tail.initial` writes; if
+ *      `initial.end`, close.
+ *   2. `store.subscribe(entry.turnId, (chunk, current) => ...)` — feed each
+ *      emission through `tail.next(chunk, current)`; write its writes; close
+ *      on `end`. (Subscribe before applying `initial` to match the engine;
+ *      the cursor guard makes duplicate delivery harmless.)
+ *   3. Every `HEARTBEAT_INTERVAL_MS`, write `KEEP_ALIVE_FRAME` while open.
+ */
+import { isTerminalStatus } from './status.js';
+/** Heartbeat cadence (streams.js:5). */
+export const HEARTBEAT_INTERVAL_MS = 15_000;
+/** The comment frame the heartbeat writes (streams.js:31), byte-exact. */
+export const KEEP_ALIVE_FRAME = ': keep-alive\n\n';
+/**
+ * The SSE response headers the host must send before any tail write
+ * (sse.js:198-204). Documented contract — writing them is host work.
+ */
+export const SSE_HEADERS = {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+};
+/** Anonymous SSE data frame (streams.js:7-9). */
+export function jsonSse(data) {
+    return `data: ${JSON.stringify(data)}\n\n`;
+}
+/** Named SSE event frame (streams.js:11-13). */
+export function namedSse(event, data) {
+    return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+/** Cursor normalization (streams.js:58-60): any non-finite value → -1. */
+export function normalizeAfterIndex(afterIndex) {
+    return Number.isFinite(afterIndex) ? afterIndex : -1;
+}
+/**
+ * Route-layer cursor parse (server.js:43):
+ * `Number(searchParams.get('afterIndex') ?? -1)`. A missing param is -1; a
+ * garbage param becomes NaN, which {@link normalizeAfterIndex} folds to -1
+ * inside the tail. An empty-string param is 0 — engine-faithful quirk.
+ */
+export function parseAfterIndexParam(value) {
+    return Number(value ?? -1);
+}
+/**
+ * Tail selection (streams.js:120-122): the id is tried as a session first —
+ * active turn, else latest-by-session — then as a literal turn id.
+ */
+export function findTurn(store, id) {
+    return store.latest(id) || store.get(id);
+}
+/**
+ * The core of `writeTurnTail` (streams.js:62-118) as a cursor-holding pure
+ * state machine. No sockets, no timers: each call returns the exact payload
+ * strings the engine would have written.
+ */
+export function createTurnTail(entry, options = {}) {
+    const format = options.format || 'frame';
+    let lastSent = normalizeAfterIndex(options.afterIndex);
+    // streams.js:66-78 — the guarded chunk write; advances the cursor.
+    const writeChunk = (writes, chunk, current) => {
+        if (!chunk || chunk.index <= lastSent)
+            return;
+        if (format === 'raw-temp') {
+            writes.push(namedSse('chunk', {
+                codeSessionId: current.sessionId,
+                chunk,
+                total: current.chunks.length,
+            }));
+        }
+        else {
+            writes.push(chunk.data);
+        }
+        lastSent = chunk.index;
+    };
+    // streams.js:80-95 — the completion rule. raw-temp always writes the
+    // `complete` event and closes. frame format writes nothing and closes —
+    // UNLESS the status is `save_failed`: the /chat route still owes the tail
+    // an error frame after runTurn rejects, so the stream must stay open for
+    // it (streams.js:90-94; the frames themselves are chatErrorWrites()).
+    const complete = (writes, current) => {
+        if (format === 'raw-temp') {
+            writes.push(namedSse('complete', {
+                codeSessionId: current.sessionId,
+                total: current.chunks.length,
+            }));
+            return true;
+        }
+        return current.status !== 'save_failed';
+    };
+    // streams.js:104-117 — the backlog pass.
+    const initial = { writes: [], end: false };
+    const existing = entry.chunks.filter((chunk) => chunk.index > lastSent);
+    if (format === 'raw-temp') {
+        initial.writes.push(namedSse('existing', {
+            codeSessionId: entry.sessionId,
+            assistantMessageId: entry.assistantMessageId,
+            chunks: existing,
+            total: existing.length,
+        }));
+        if (existing.length)
+            lastSent = existing[existing.length - 1].index;
+    }
+    else {
+        for (const chunk of existing)
+            writeChunk(initial.writes, chunk, entry);
+    }
+    if (isTerminalStatus(entry.status))
+        initial.end = complete(initial.writes, entry);
+    return {
+        initial,
+        next(chunk, current) {
+            const out = { writes: [], end: false };
+            if (chunk)
+                writeChunk(out.writes, chunk, current);
+            else if (isTerminalStatus(current.status))
+                out.end = complete(out.writes, current);
+            return out;
+        },
+    };
+}
+/**
+ * `writeRawTempStream` selection (streams.js:124-134): resolve the id via
+ * {@link findTurn}; `null` means the host answers 404 (no tail exists).
+ */
+export function createRawTempTail(store, id, afterIndex) {
+    const entry = findTurn(store, id);
+    if (!entry)
+        return null;
+    return {
+        entry,
+        tail: createTurnTail(entry, {
+            format: 'raw-temp',
+            afterIndex: normalizeAfterIndex(afterIndex),
+        }),
+    };
+}
+/**
+ * Default error message when a failed turn carries none (streams.js:148).
+ */
+export const CHAT_STREAM_FALLBACK_ERROR = 'Internal server error';
+/**
+ * The frames `/chat` writes when `runTurn` rejects (streams.js:148-152):
+ * an error frame, then a complete frame with `stopReason: 'error'`. After
+ * writing these the host closes the stream — this is the second half of the
+ * save_failed rule: the tail held the socket open so these bytes land first.
+ */
+export function chatErrorWrites(message) {
+    const resolved = message || CHAT_STREAM_FALLBACK_ERROR;
+    return [
+        jsonSse({ _type: 'error', message: resolved }),
+        jsonSse({ _type: 'complete', stopReason: 'error' }),
+    ];
+}
+//# sourceMappingURL=replay.js.map

package/dist/turns/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/turns/replay.ts"],"names":[],"mappings":"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"}

package/dist/turns/status.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Turn status vocabulary and predicates — the turn machine's state alphabet,
+ * extracted from engine `chat-core`. Every value is anchored to the engine
+ * line that produces it; nothing here is invented.
+ */
+/**
+ * Every status a stored turn can hold:
+ * - `streaming`   — set at start (stores.js:19)
+ * - `cancelling`  — stop path (engine.js:124); still counted active (stores.js:40)
+ * - `complete`    — terminal, clean end (engine.js:302)
+ * - `error`       — terminal (engine.js:302, safety net engine.js:337)
+ * - `cancelled`   — terminal (engine.js:302)
+ * - `aborted`     — prior turn of the same session displaced by a new start (stores.js:13)
+ * - `save_failed` — persistence failed after the raw stream completed (engine.js:327)
+ */
+export declare const TURN_STATUSES: readonly ["streaming", "cancelling", "complete", "error", "cancelled", "aborted", "save_failed"];
+export type TurnStatus = (typeof TURN_STATUSES)[number];
+/**
+ * Synthesized status reported by `GET /active` when a session has no active
+ * turn entry (engine.js:107 `entry?.status || 'idle'`). Never stored on a turn.
+ */
+export declare const IDLE_STATUS: "idle";
+/** A queried status: a real turn status, or the synthesized 'idle'. */
+export type QueryStatus = TurnStatus | typeof IDLE_STATUS;
+/**
+ * Statuses that hold a tempstore slot / count as active. Engine repeats the
+ * literal array at stores.js:40 (activeCount), stores.js:55 (addChunk guard)
+ * and engine.js:104, engine.js:336.
+ */
+export declare const ACTIVE_STATUSES: readonly ["streaming", "cancelling"];
+export type ActiveStatus = (typeof ACTIVE_STATUSES)[number];
+/** The active predicate — `['streaming', 'cancelling'].includes(status)`. */
+export declare function isActiveStatus(status: string): status is ActiveStatus;
+/**
+ * Terminal predicate as the replay law states it (streams.js:54-56):
+ * anything that is not streaming and not cancelling is terminal. Note this
+ * includes `save_failed`, which is terminal but does NOT close a frame-format
+ * tail (streams.js:90-94).
+ */
+export declare function isTerminalStatus(status: string): boolean;
+/**
+ * Stop-reason vocabulary carried on the `complete` frame:
+ * - `end_turn`  — default (engine.js:251)
+ * - `error`     — stream error path (engine.js:289; streams.js:151)
+ * - `cancelled` — cancelling turn finished without its own done (engine.js:285)
+ */
+export declare const STOP_REASONS: readonly ["end_turn", "error", "cancelled"];
+export type StopReason = (typeof STOP_REASONS)[number];
+//# sourceMappingURL=status.d.ts.map

package/dist/turns/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/turns/status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,kGAQhB,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAG,MAAe,CAAC;AAE3C,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,WAAW,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,eAAe,sCAAuC,CAAC;AAEpE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,YAAY,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,6CAA8C,CAAC;AAExE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/turns/status.js

@@ -0,0 +1,56 @@
+/**
+ * Turn status vocabulary and predicates — the turn machine's state alphabet,
+ * extracted from engine `chat-core`. Every value is anchored to the engine
+ * line that produces it; nothing here is invented.
+ */
+/**
+ * Every status a stored turn can hold:
+ * - `streaming`   — set at start (stores.js:19)
+ * - `cancelling`  — stop path (engine.js:124); still counted active (stores.js:40)
+ * - `complete`    — terminal, clean end (engine.js:302)
+ * - `error`       — terminal (engine.js:302, safety net engine.js:337)
+ * - `cancelled`   — terminal (engine.js:302)
+ * - `aborted`     — prior turn of the same session displaced by a new start (stores.js:13)
+ * - `save_failed` — persistence failed after the raw stream completed (engine.js:327)
+ */
+export const TURN_STATUSES = [
+    'streaming',
+    'cancelling',
+    'complete',
+    'error',
+    'cancelled',
+    'aborted',
+    'save_failed',
+];
+/**
+ * Synthesized status reported by `GET /active` when a session has no active
+ * turn entry (engine.js:107 `entry?.status || 'idle'`). Never stored on a turn.
+ */
+export const IDLE_STATUS = 'idle';
+/**
+ * Statuses that hold a tempstore slot / count as active. Engine repeats the
+ * literal array at stores.js:40 (activeCount), stores.js:55 (addChunk guard)
+ * and engine.js:104, engine.js:336.
+ */
+export const ACTIVE_STATUSES = ['streaming', 'cancelling'];
+/** The active predicate — `['streaming', 'cancelling'].includes(status)`. */
+export function isActiveStatus(status) {
+    return ACTIVE_STATUSES.includes(status);
+}
+/**
+ * Terminal predicate as the replay law states it (streams.js:54-56):
+ * anything that is not streaming and not cancelling is terminal. Note this
+ * includes `save_failed`, which is terminal but does NOT close a frame-format
+ * tail (streams.js:90-94).
+ */
+export function isTerminalStatus(status) {
+    return status !== 'streaming' && status !== 'cancelling';
+}
+/**
+ * Stop-reason vocabulary carried on the `complete` frame:
+ * - `end_turn`  — default (engine.js:251)
+ * - `error`     — stream error path (engine.js:289; streams.js:151)
+ * - `cancelled` — cancelling turn finished without its own done (engine.js:285)
+ */
+export const STOP_REASONS = ['end_turn', 'error', 'cancelled'];
+//# sourceMappingURL=status.js.map

package/dist/turns/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/turns/status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,WAAW;IACX,YAAY;IACZ,UAAU;IACV,OAAO;IACP,WAAW;IACX,SAAS;IACT,aAAa;CACL,CAAC;AAIX;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAe,CAAC;AAK3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,WAAW,EAAE,YAAY,CAAU,CAAC;AAIpE,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAQ,eAAqC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,YAAY,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,WAAW,CAAU,CAAC"}

package/dist/turns/turn-store.d.ts

@@ -0,0 +1,109 @@
+/**
+ * TurnStore — engine `chat-core/stores.js` (113 lines), ported in full.
+ * The in-memory raw-stream tempstore: one entry per turn, indexed chunks,
+ * seal-on-done, per-turn pub-sub, and the active/latest session maps.
+ *
+ * `Date.now()` is replaced by an injected {@link ClockMsPort} (constructor
+ * argument); everything else is byte-parity with the engine working tree.
+ */
+import type { ClockMsPort } from '../ports.js';
+import { type TurnStatus } from './status.js';
+/** One indexed raw-stream chunk (stores.js:59). */
+export interface TurnChunk {
+    index: number;
+    /** The SSE frame bytes, written verbatim to frame-format tails. */
+    data: string;
+    timestamp: number;
+}
+/** A stored turn (stores.js:14-24). Hosts may attach extra bookkeeping. */
+export interface TurnEntry {
+    sessionId: string;
+    turnId: string;
+    assistantMessageId: string | null;
+    userMessageId: string | null;
+    status: TurnStatus;
+    chunks: TurnChunk[];
+    parts: unknown[];
+    createdAt: number;
+    updatedAt: number;
+    /** Set when a chunk was added with `{ seal: true }` (stores.js:61). */
+    sealedIndex?: number;
+    /**
+     * Engine-side augmentation slots (engine.js:230-235, engine.js:311-314).
+     * The store never reads these; they ride along on the entry object.
+     */
+    [extra: string]: unknown;
+}
+export interface StartTurnInput {
+    sessionId: string;
+    turnId: string;
+    assistantMessageId: string | null;
+    userMessageId: string | null;
+}
+/** A frame, or a frame factory receiving the assigned index (stores.js:58). */
+export type ChunkFrame = string | ((index: number) => string);
+export interface AddChunkOptions {
+    /** `true` seals the log at this chunk's index (stores.js:61). */
+    seal?: boolean;
+}
+export type TurnListener = (chunk: TurnChunk | null, entry: TurnEntry) => void;
+export declare class TurnStore {
+    readonly turns: Map<string, TurnEntry>;
+    readonly activeBySession: Map<string, string>;
+    readonly latestBySession: Map<string, string>;
+    readonly listeners: Map<string, Set<TurnListener>>;
+    private readonly clockMs;
+    constructor(clockMs: ClockMsPort);
+    /**
+     * Open a new turn. A different active turn on the same session is marked
+     * `aborted` first — the abort-on-restart law (stores.js:12-13).
+     */
+    start({ sessionId, turnId, assistantMessageId, userMessageId }: StartTurnInput): TurnEntry;
+    /** The session's active turn entry, if any (stores.js:31-34). */
+    active(sessionId: string): TurnEntry | null;
+    /**
+     * Number of turns still holding a tempstore slot — status in
+     * `['streaming', 'cancelling']` (stores.js:36-43).
+     */
+    activeCount(): number;
+    /**
+     * Selection law (stores.js:45-47): the session's active turn wins; else the
+     * most recently started turn for the session, even after it went terminal.
+     */
+    latest(sessionId: string): TurnEntry | null;
+    get(turnId: string | undefined): TurnEntry | null;
+    /**
+     * Append a chunk (stores.js:53-65). Returns `null` — a rejected write —
+     * when the turn is missing, no longer active, or already sealed. The engine
+     * converts that `null` into the thrown "Raw stream write failed before
+     * event application" (engine.js:262); see {@link addChunkOrThrow}.
+     */
+    addChunk(turnId: string, frame: ChunkFrame, options?: AddChunkOptions): TurnChunk | null;
+    setParts(turnId: string, parts: unknown[]): void;
+    /**
+     * Set a turn's status (stores.js:72-79). Any status other than
+     * `cancelling` releases the session's active slot; listeners get a
+     * `(null, entry)` status notification.
+     */
+    mark(turnId: string, status: TurnStatus): void;
+    /** Drop the turn and its listeners; release both session maps (stores.js:81-87). */
+    clear(turnId: string): void;
+    /** Chunks strictly after the cursor (stores.js:89-92); `[]` for unknown turns. */
+    chunksAfter(turnId: string, afterIndex?: number): TurnChunk[];
+    /** Subscribe to a turn's chunk/status emissions; returns unsubscribe (stores.js:94-102). */
+    subscribe(turnId: string, callback: TurnListener): () => void;
+    /** Fan out to listeners; listener errors are swallowed (stores.js:104-110). */
+    emit(turnId: string, chunk: TurnChunk | null, entry: TurnEntry): void;
+}
+/**
+ * The sealed/rejected-write error, byte-exact from engine.js:262. Thrown by
+ * the engine's `append()` whenever `addChunk` returns `null` (turn missing,
+ * terminal, or sealed).
+ */
+export declare const RAW_STREAM_WRITE_FAILED_MESSAGE = "Raw stream write failed before event application";
+/**
+ * The engine's write law as a helper: append, and convert a rejected write
+ * into the exact engine throw (engine.js:261-262).
+ */
+export declare function addChunkOrThrow(store: TurnStore, turnId: string, frame: ChunkFrame, options?: AddChunkOptions): TurnChunk;
+//# sourceMappingURL=turn-store.d.ts.map

package/dist/turns/turn-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-store.d.ts","sourceRoot":"","sources":["../../src/turns/turn-store.ts"],"names":[],"mappings":"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"}

package/dist/turns/turn-store.js

@@ -0,0 +1,169 @@
+/**
+ * TurnStore — engine `chat-core/stores.js` (113 lines), ported in full.
+ * The in-memory raw-stream tempstore: one entry per turn, indexed chunks,
+ * seal-on-done, per-turn pub-sub, and the active/latest session maps.
+ *
+ * `Date.now()` is replaced by an injected {@link ClockMsPort} (constructor
+ * argument); everything else is byte-parity with the engine working tree.
+ */
+import { isActiveStatus } from './status.js';
+export class TurnStore {
+    turns = new Map();
+    activeBySession = new Map();
+    latestBySession = new Map();
+    listeners = new Map();
+    clockMs;
+    constructor(clockMs) {
+        this.clockMs = clockMs;
+    }
+    /**
+     * Open a new turn. A different active turn on the same session is marked
+     * `aborted` first — the abort-on-restart law (stores.js:12-13).
+     */
+    start({ sessionId, turnId, assistantMessageId, userMessageId }) {
+        const previous = this.activeBySession.get(sessionId);
+        if (previous && previous !== turnId)
+            this.mark(previous, 'aborted');
+        const entry = {
+            sessionId,
+            turnId,
+            assistantMessageId,
+            userMessageId,
+            status: 'streaming',
+            chunks: [],
+            parts: [],
+            createdAt: this.clockMs(),
+            updatedAt: this.clockMs(),
+        };
+        this.turns.set(turnId, entry);
+        this.activeBySession.set(sessionId, turnId);
+        this.latestBySession.set(sessionId, turnId);
+        return entry;
+    }
+    /** The session's active turn entry, if any (stores.js:31-34). */
+    active(sessionId) {
+        const turnId = this.activeBySession.get(sessionId);
+        return turnId ? this.turns.get(turnId) || null : null;
+    }
+    /**
+     * Number of turns still holding a tempstore slot — status in
+     * `['streaming', 'cancelling']` (stores.js:36-43).
+     */
+    activeCount() {
+        let count = 0;
+        for (const turnId of this.activeBySession.values()) {
+            const entry = this.turns.get(turnId);
+            if (entry && isActiveStatus(entry.status))
+                count += 1;
+        }
+        return count;
+    }
+    /**
+     * Selection law (stores.js:45-47): the session's active turn wins; else the
+     * most recently started turn for the session, even after it went terminal.
+     */
+    latest(sessionId) {
+        return this.active(sessionId) || this.get(this.latestBySession.get(sessionId));
+    }
+    get(turnId) {
+        return (turnId === undefined ? null : this.turns.get(turnId)) || null;
+    }
+    /**
+     * Append a chunk (stores.js:53-65). Returns `null` — a rejected write —
+     * when the turn is missing, no longer active, or already sealed. The engine
+     * converts that `null` into the thrown "Raw stream write failed before
+     * event application" (engine.js:262); see {@link addChunkOrThrow}.
+     */
+    addChunk(turnId, frame, options = {}) {
+        const entry = this.turns.get(turnId);
+        if (!entry || !isActiveStatus(entry.status))
+            return null;
+        if (Number.isInteger(entry.sealedIndex))
+            return null;
+        const index = entry.chunks.length;
+        const data = typeof frame === 'function' ? frame(index) : frame;
+        const chunk = { index, data, timestamp: this.clockMs() };
+        entry.chunks.push(chunk);
+        if (options.seal === true)
+            entry.sealedIndex = index;
+        entry.updatedAt = this.clockMs();
+        this.emit(turnId, chunk, entry);
+        return chunk;
+    }
+    setParts(turnId, parts) {
+        const entry = this.turns.get(turnId);
+        if (entry)
+            entry.parts = parts;
+    }
+    /**
+     * Set a turn's status (stores.js:72-79). Any status other than
+     * `cancelling` releases the session's active slot; listeners get a
+     * `(null, entry)` status notification.
+     */
+    mark(turnId, status) {
+        const entry = this.turns.get(turnId);
+        if (!entry)
+            return;
+        entry.status = status;
+        entry.updatedAt = this.clockMs();
+        if (status !== 'cancelling' && this.activeBySession.get(entry.sessionId) === turnId)
+            this.activeBySession.delete(entry.sessionId);
+        this.emit(turnId, null, entry);
+    }
+    /** Drop the turn and its listeners; release both session maps (stores.js:81-87). */
+    clear(turnId) {
+        const entry = this.turns.get(turnId);
+        if (entry && this.activeBySession.get(entry.sessionId) === turnId)
+            this.activeBySession.delete(entry.sessionId);
+        if (entry && this.latestBySession.get(entry.sessionId) === turnId)
+            this.latestBySession.delete(entry.sessionId);
+        this.turns.delete(turnId);
+        this.listeners.delete(turnId);
+    }
+    /** Chunks strictly after the cursor (stores.js:89-92); `[]` for unknown turns. */
+    chunksAfter(turnId, afterIndex = -1) {
+        const entry = this.turns.get(turnId);
+        return entry ? entry.chunks.filter((chunk) => chunk.index > afterIndex) : [];
+    }
+    /** Subscribe to a turn's chunk/status emissions; returns unsubscribe (stores.js:94-102). */
+    subscribe(turnId, callback) {
+        if (!this.listeners.has(turnId))
+            this.listeners.set(turnId, new Set());
+        const set = this.listeners.get(turnId);
+        set.add(callback);
+        return () => {
+            set.delete(callback);
+            if (set.size === 0)
+                this.listeners.delete(turnId);
+        };
+    }
+    /** Fan out to listeners; listener errors are swallowed (stores.js:104-110). */
+    emit(turnId, chunk, entry) {
+        const set = this.listeners.get(turnId);
+        if (!set)
+            return;
+        for (const callback of set) {
+            try {
+                callback(chunk, entry);
+            }
+            catch { }
+        }
+    }
+}
+/**
+ * The sealed/rejected-write error, byte-exact from engine.js:262. Thrown by
+ * the engine's `append()` whenever `addChunk` returns `null` (turn missing,
+ * terminal, or sealed).
+ */
+export const RAW_STREAM_WRITE_FAILED_MESSAGE = 'Raw stream write failed before event application';
+/**
+ * The engine's write law as a helper: append, and convert a rejected write
+ * into the exact engine throw (engine.js:261-262).
+ */
+export function addChunkOrThrow(store, turnId, frame, options = {}) {
+    const chunk = store.addChunk(turnId, frame, options);
+    if (!chunk)
+        throw new Error(RAW_STREAM_WRITE_FAILED_MESSAGE);
+    return chunk;
+}
+//# sourceMappingURL=turn-store.js.map

package/dist/turns/turn-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-store.js","sourceRoot":"","sources":["../../src/turns/turn-store.ts"],"names":[],"mappings":"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"}

package/dist/usage/finalize.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Turn-usage finalization — engine `chat-core/usage.js:208-323`, ported
+ * byte-exact. A turn accumulates per-step usage records; finalization
+ * collapses them into the single record that gets billed:
+ *
+ * - pi: sum of exact billable steps, native provider USD cost preserved.
+ * - codex: cumulative-meter delta (last cumulative − first baseline,
+ *   clamped per bucket so compaction resets never go negative), falling
+ *   back to summing exact steps.
+ * - everyone else: prefer an exact `chat_turn` record, else sum the exact
+ *   billable steps.
+ */
+import { type TokenList } from './tokens.js';
+import { type NormalizedUsage, type UsageInput } from './normalize.js';
+/**
+ * The slice of the turn contract the usage law reads. Hosts pass their
+ * full contract object; only these fields are consulted.
+ */
+export interface UsageContract {
+    authMethod?: string | undefined;
+    harness?: string | undefined;
+    userId?: string | undefined;
+    sessionId?: string | undefined;
+    assistantMessageId?: string | undefined;
+    agentId?: string | undefined;
+    modelId?: string | undefined;
+    usageModelId?: string | undefined;
+    cliModel?: string | undefined;
+    usageOwner?: string | undefined;
+    contextWindow?: number | null | undefined;
+    maxTokens?: number | null | undefined;
+    cwd?: string | undefined;
+    mcpServers?: unknown;
+}
+/** A per-step usage record; normally a `NormalizedUsage`, tolerated partial. */
+export type TurnUsageRecord = Partial<NormalizedUsage>;
+/**
+ * Engine `usageFromTokenList()`: promote a token list to an exact,
+ * billable `chat_turn` usage record.
+ */
+export declare function usageFromTokenList(tokenList: Partial<TokenList> | null | undefined, base?: UsageInput): NormalizedUsage;
+/**
+ * Engine `summedTurnUsage()`: bucket-wise sum of the records' token lists,
+ * or null when the sum carries no tokens.
+ */
+export declare function summedTurnUsage(records: readonly TurnUsageRecord[], base?: UsageInput): NormalizedUsage | null;
+/** Arguments to `finalizeTurnUsage` — engine call shape preserved. */
+export interface FinalizeTurnUsageArgs {
+    contract?: UsageContract | undefined;
+    /** The latest live usage snapshot (context limit / footprint source). */
+    usage?: NormalizedUsage | null | undefined;
+    /** All per-step records observed during the turn. */
+    usageRecords?: readonly TurnUsageRecord[] | null | undefined;
+}
+/** Engine `finalizeTurnUsage()`, byte-exact. Null = nothing billable. */
+export declare function finalizeTurnUsage({ contract, usage, usageRecords }?: FinalizeTurnUsageArgs): NormalizedUsage | null;
+//# sourceMappingURL=finalize.d.ts.map

package/dist/usage/finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.d.ts","sourceRoot":"","sources":["../../src/usage/finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAkB,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAChD,IAAI,GAAE,UAAe,GACpB,eAAe,CAejB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,IAAI,GAAE,UAAe,GACpB,eAAe,GAAG,IAAI,CAOxB;AA0CD,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACrC,yEAAyE;IACzE,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,qDAAqD;IACrD,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;CAC9D;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,GAAE,qBAA0B,GAAG,eAAe,GAAG,IAAI,CA4DvH"}