@lucascouts/claude-agent-tui 0.1.0

package/dist/engine-watcher.d.ts

@@ -0,0 +1,83 @@
+import type { SessionWatcher } from "./engine-lifecycle.js";
+import type { TranscriptTail, TailOptions } from "./jsonl.js";
+/**
+ * A conversation message as returned by `getSessionMessages`. We rely ONLY on `.uuid` here (the
+ * dedupe key); everything else is forwarded opaque. Typed as an optional `uuid` superset so the
+ * injectable seam structurally accepts both the real SDK `SessionMessage` (whose `uuid` is a
+ * required `string`) and lightweight test fixtures.
+ */
+export type SessionMessage = {
+    uuid?: string;
+    [k: string]: unknown;
+};
+/**
+ * Injectable seam matching the SDK `getSessionMessages` signature (the pure, billing-free reader).
+ * May be sync or async — the orchestrator awaits the result either way and then performs the
+ * check-add-emit synchronously (see {@link createJsonlWatcher}). Defaults to the SDK function.
+ */
+export type GetMessages = (sessionId: string, opts?: {
+    dir?: string;
+}) => Promise<SessionMessage[]> | SessionMessage[];
+/** Default debounce window (ms) coalescing a burst of live write signals into one re-read. */
+export declare const DEFAULT_WATCHER_DEBOUNCE_MS = 50;
+/** Construction options for {@link createJsonlWatcher}. */
+export interface JsonlWatcherOptions {
+    /** The session id; equals the transcript filename basename. Passed to `getSessionMessages`. */
+    sessionId: string;
+    /** Resolved transcript path (from Task 1 `locateTranscript`) — the file the tail watches. */
+    transcriptPath: string;
+    /** Runtime cwd (from Task 1 `readCwdFromInside`) → passed as `{ dir }` to `getSessionMessages`. */
+    dir?: string;
+    /** Sink: invoked once per NEW (not-yet-seen-by-uuid) message, in `getSessionMessages` order. */
+    onEvent: (message: SessionMessage) => void;
+    /** Injected for tests; defaults to the SDK `getSessionMessages`. */
+    getMessages?: GetMessages;
+    /** Injected for tests; defaults to {@link tailTranscript} from ./jsonl.js. */
+    tail?: (path: string, opts: TailOptions) => TranscriptTail;
+    /** Debounce window (ms) for the live write signal; defaults to {@link DEFAULT_WATCHER_DEBOUNCE_MS}. */
+    debounceMs?: number;
+    /**
+     * Injected for deterministic debounce in tests; returns a CANCEL fn. Defaults to a
+     * setTimeout/clearTimeout pair. Tests pass a controllable scheduler (capture fn + manual flush)
+     * so the debounce never depends on real timer timing.
+     */
+    schedule?: (fn: () => void, ms: number) => () => void;
+}
+/**
+ * The concrete per-session watcher: it satisfies the story-014 {@link SessionWatcher} seam (so a
+ * {@link SessionEngine} can tear it down on cleanup) AND exposes the story-024 end-of-turn hook.
+ */
+export interface JsonlWatcher extends SessionWatcher {
+    /**
+     * Tear down the tail, cancel any pending debounce, and set a stopped flag so an in-flight async
+     * re-read does not emit after stop. Idempotent (the {@link SessionWatcher} contract).
+     */
+    stop(): void;
+    /**
+     * Story-024 end-of-turn signal: cancel any pending debounce and force ONE final re-read
+     * IMMEDIATELY so the just-completed turn is fully ingested. This watcher only CONSUMES the
+     * signal — it does NOT detect end-of-turn (that is story 024).
+     */
+    notifyEndOfTurn(): void;
+}
+/**
+ * Create the read-only JSONL tail watcher for one session (story 015, R4 + R5).
+ *
+ * Wiring: `tailTranscript(transcriptPath, { onRecord: () => scheduleReread() })`. Each complete
+ * line the tail forwards is treated PURELY as a debounced write signal — never as the event source.
+ * After `debounceMs` of quiet, exactly one re-read runs: it calls `getMessages(sessionId, { dir })`,
+ * then SYNCHRONOUSLY (no `await` between messages) walks the returned array and, for each message
+ * whose `uuid` is not yet in `seen`, adds it to `seen` and forwards it to `onEvent` — in the SDK's
+ * chronological order, unchanged (R5.3). `notifyEndOfTurn()` bypasses the debounce and forces one
+ * immediate final re-read.
+ *
+ * Re-reads are SERIALIZED (never concurrent): a `reading` flag plus a coalesced `pendingReread`
+ * flag guarantee that a signal arriving mid-read schedules exactly one more re-read after the
+ * current one settles. Because the check-add-emit runs synchronously after the await, exactly-once
+ * holds even if re-reads overlap logically (R4.1, R4.2, R5.2).
+ *
+ * @param opts session id, transcript path, dir, the onEvent sink, and injectable seams.
+ * @returns a {@link JsonlWatcher} (a {@link SessionWatcher} plus `notifyEndOfTurn`).
+ */
+export declare function createJsonlWatcher(opts: JsonlWatcherOptions): JsonlWatcher;
+//# sourceMappingURL=engine-watcher.d.ts.map

package/dist/engine-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-watcher.d.ts","sourceRoot":"","sources":["../src/engine-watcher.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACpB,OAAO,CAAC,cAAc,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC;AAElD,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,+FAA+F;IAC/F,SAAS,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,cAAc,EAAE,MAAM,CAAC;IACvB,mGAAmG;IACnG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAC3C,oEAAoE;IACpE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,cAAc,CAAC;IAC3D,uGAAuG;IACvG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,IAAI,CAAC;CACvD;AAED;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;IACb;;;;OAIG;IACH,eAAe,IAAI,IAAI,CAAC;CACzB;AAQD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAyH1E"}

package/dist/engine-watcher.js

@@ -0,0 +1,173 @@
+// === §6 JSONL tail watcher orchestrator (story 015, Task Group 3) =============================
+//
+// BINDING DECISION E5 "REUSE-live" (story.md R5, constraint 1): this watcher does NOT hand-parse
+// `message.content`. It WRAPS the SDK's pure, billing-free reader `getSessionMessages(sessionId,
+// { dir })` and RE-INVOKES it (a) on a debounced write SIGNAL (live streaming) and (b) on a forced
+// final re-read when the story-024 end-of-turn signal fires. There is exactly ONE parser — the
+// SDK's — and we surface its parentUuid-linked chronological order UNCHANGED (R5.3; linearization
+// of sidechains/forks is deferred to story 017).
+//
+// Division of labour:
+//   - `tailTranscript` (Task 2, jsonl.ts) is the TRIGGER: its newline-atomic line reader + residue
+//     buffer decide *when* a new COMPLETE line has landed. We use each forwarded record only as a
+//     write SIGNAL — never as the event source. A torn ~630 KB image append is therefore withheld
+//     by the residue buffer until its `\n` arrives, so no signal fires for a half-written line.
+//   - `getSessionMessages` is the SOURCE: every re-read returns the full monotonic ordered superset.
+//   - the per-`uuid` `Set` is the EMIT-ONCE guard: across re-reads of the growing superset, each
+//     message is forwarded to `onEvent` at most once, preserving the SDK array order (R4.1, R4.2).
+//
+// The story-024 end-of-turn detector (terminal `stop_reason` + 200 ms quiescence) is NOT
+// implemented here — this watcher only CONSUMES its signal via `notifyEndOfTurn()` as the
+// forced-final-re-read cadence.
+import { tailTranscript } from "./jsonl.js";
+/** Default debounce window (ms) coalescing a burst of live write signals into one re-read. */
+export const DEFAULT_WATCHER_DEBOUNCE_MS = 50;
+/** Default debounce scheduler: fire `fn` after `ms` via setTimeout; the returned fn clears it. */
+function defaultSchedule(fn, ms) {
+    const handle = setTimeout(fn, ms);
+    return () => clearTimeout(handle);
+}
+/**
+ * Create the read-only JSONL tail watcher for one session (story 015, R4 + R5).
+ *
+ * Wiring: `tailTranscript(transcriptPath, { onRecord: () => scheduleReread() })`. Each complete
+ * line the tail forwards is treated PURELY as a debounced write signal — never as the event source.
+ * After `debounceMs` of quiet, exactly one re-read runs: it calls `getMessages(sessionId, { dir })`,
+ * then SYNCHRONOUSLY (no `await` between messages) walks the returned array and, for each message
+ * whose `uuid` is not yet in `seen`, adds it to `seen` and forwards it to `onEvent` — in the SDK's
+ * chronological order, unchanged (R5.3). `notifyEndOfTurn()` bypasses the debounce and forces one
+ * immediate final re-read.
+ *
+ * Re-reads are SERIALIZED (never concurrent): a `reading` flag plus a coalesced `pendingReread`
+ * flag guarantee that a signal arriving mid-read schedules exactly one more re-read after the
+ * current one settles. Because the check-add-emit runs synchronously after the await, exactly-once
+ * holds even if re-reads overlap logically (R4.1, R4.2, R5.2).
+ *
+ * @param opts session id, transcript path, dir, the onEvent sink, and injectable seams.
+ * @returns a {@link JsonlWatcher} (a {@link SessionWatcher} plus `notifyEndOfTurn`).
+ */
+export function createJsonlWatcher(opts) {
+    const { sessionId, transcriptPath, dir, onEvent, getMessages, tail = tailTranscript, debounceMs = DEFAULT_WATCHER_DEBOUNCE_MS, schedule = defaultSchedule, } = opts;
+    // The SINGLE source of events: the SDK reader (or an injected stub). No second parser exists.
+    const readMessages = getMessages ?? defaultGetMessages;
+    // The emit-once guard. Dedupe key is `message.uuid`; survives across every live re-read so the
+    // growing superset re-emits nothing already forwarded (R4.1).
+    const seen = new Set();
+    // Lifecycle / serialization flags.
+    let stopped = false; // set by stop(): suppress any further (incl. in-flight) emits + re-reads.
+    let reading = false; // a re-read's async body is in flight — do not start a second concurrently.
+    let pendingReread = false; // a signal arrived mid-read — run exactly ONE more re-read after.
+    let cancelDebounce; // cancels the armed debounce timer, if any.
+    /**
+     * Run ONE re-read: await the SDK reader, then SYNCHRONOUSLY (no await between messages) emit each
+     * not-yet-seen message in array order. The post-await synchrony is what makes exactly-once hold
+     * even if two re-reads were logically requested — only the FIRST `seen.add(uuid)` lets `onEvent`
+     * fire for that uuid. Serialized by the `reading` flag; a mid-read signal sets `pendingReread`
+     * and we loop once more after settling.
+     */
+    const runReread = async () => {
+        if (stopped)
+            return;
+        if (reading) {
+            // A re-read is already in flight; coalesce this request into a single follow-up pass.
+            pendingReread = true;
+            return;
+        }
+        reading = true;
+        try {
+            do {
+                pendingReread = false;
+                // The ONLY parse of the transcript — the SDK's pure reader. May be sync or async; await
+                // handles both. After this await we must NOT await again before the emit loop, so the
+                // check-add-emit stays atomic w.r.t. the microtask queue (no dedupe race across re-reads).
+                let messages;
+                try {
+                    messages = await readMessages(sessionId, { dir });
+                }
+                catch {
+                    // Transient SDK read failure — SWALLOW it (as the scheduleReread comment promises): emit
+                    // nothing this cycle, so a failing read never rejects an unhandled promise nor tears the
+                    // watcher down. A later write/end-of-turn signal triggers a fresh re-read; if a signal
+                    // arrived mid-read (`pendingReread`), the loop condition retries once, else we settle.
+                    continue;
+                }
+                // stop() may have fired during the await — do not emit after teardown (R: stop is final).
+                if (stopped)
+                    return;
+                for (const message of messages) {
+                    const { uuid } = message;
+                    if (typeof uuid === "string") {
+                        // Already forwarded on an earlier (sub)superset re-read → skip (R4.1, R4.2).
+                        if (seen.has(uuid))
+                            continue;
+                        seen.add(uuid);
+                    }
+                    // No `uuid` (should not happen in-corpus): we cannot dedupe it, so we emit it rather than
+                    // silently drop a real event. Documented fallback — prefer emit-once-if-keyed over loss.
+                    onEvent(message);
+                }
+                // If a write/end-of-turn signal arrived mid-read, `pendingReread` is set: loop ONE more
+                // time (coalesced) so we never miss the latest superset, but never run two reads at once.
+            } while (pendingReread && !stopped);
+        }
+        finally {
+            reading = false;
+        }
+    };
+    /**
+     * Debounced live path: (re)arm the debounce timer; after `debounceMs` of quiet it fires exactly
+     * one re-read. Coalesces a burst of write signals into a single read. A no-op once stopped.
+     */
+    const scheduleReread = () => {
+        if (stopped)
+            return;
+        cancelDebounce?.();
+        cancelDebounce = schedule(() => {
+            cancelDebounce = undefined;
+            // Fire-and-forget: runReread serializes internally; errors are swallowed so a transient SDK
+            // read failure never rejects an unhandled promise nor tears the watcher down.
+            void runReread();
+        }, debounceMs);
+    };
+    // Wire the tail. Each complete-line record is ONLY a write signal (its payload is unused as the
+    // event source) — the event source is `getMessages`. The tail's residue buffer guarantees a torn
+    // append fires no signal until its `\n` lands (so no re-read sees a half-written line).
+    const transcriptTail = tail(transcriptPath, {
+        onRecord: () => scheduleReread(),
+    });
+    return {
+        notifyEndOfTurn() {
+            if (stopped)
+                return;
+            // Forced FINAL re-read: bypass the debounce (cancel any pending live timer) and read NOW so
+            // the just-completed turn is fully ingested. runReread serializes with any in-flight read.
+            cancelDebounce?.();
+            cancelDebounce = undefined;
+            void runReread();
+        },
+        stop() {
+            if (stopped)
+                return; // idempotent (SessionWatcher contract).
+            stopped = true; // suppress emits from any in-flight async re-read past this point.
+            cancelDebounce?.();
+            cancelDebounce = undefined;
+            pendingReread = false;
+            try {
+                transcriptTail.stop();
+            }
+            catch {
+                /* tail already stopped / transient — ignore */
+            }
+        },
+    };
+}
+/**
+ * Default {@link GetMessages}: the SDK's pure, billing-free `getSessionMessages`. Imported lazily
+ * (dynamic import) so this module — and the deterministic unit tests, which always inject a stub —
+ * never force-loads the SDK at module-eval time. Returns `[]` if the SDK import fails (defer rather
+ * than throw); in production the seam is the real SDK function.
+ */
+async function defaultGetMessages(sessionId, opts) {
+    const sdk = await import("@anthropic-ai/claude-agent-sdk");
+    return sdk.getSessionMessages(sessionId, opts);
+}

package/dist/engine.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The engine boundary the ACP layer delegates session/turn work to. The methods
+ * mirror the CUT symbols in SEAM-MAP.md (`createSession`, `prompt` → 023). The
+ * real implementation (PTY spawn + JSONL tail) arrives in 013–015/023; story 011
+ * ships only this contract plus the no-op stub below. Params/returns are `unknown`
+ * on purpose — the concrete shapes are defined by the 023 rewrite, not pinned here.
+ */
+export interface Engine {
+    /** Discriminator for diagnostics/tests (e.g. "stub" vs the future "pty"). */
+    readonly kind: string;
+    /** Create an engine-backed session. CUT in 011 (→ 023). */
+    createSession(params: unknown): Promise<unknown>;
+    /** Run one prompt turn. CUT in 011 (→ 023). */
+    prompt(params: unknown): Promise<unknown>;
+}
+/** Error message thrown when 011's READ-ONLY stub is asked to do real engine work. */
+export declare const ENGINE_NOT_IMPLEMENTED_011 = "engine not implemented in 011 (read-only Degrau 1)";
+/**
+ * No-op engine: boots cleanly, performs no SDK/PTY work, and rejects any real engine
+ * call with a legible error. Temporary scaffolding — replaced by the PTY engine in
+ * stories 013–015/023.
+ */
+export declare class StubEngine implements Engine {
+    readonly kind = "stub";
+    createSession(): Promise<never>;
+    prompt(): Promise<never>;
+}
+/** Factory for the default story-011 engine (the no-op stub). */
+export declare function createStubEngine(): Engine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,+CAA+C;IAC/C,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3C;AAED,sFAAsF;AACtF,eAAO,MAAM,0BAA0B,uDAAuD,CAAC;AAE/F;;;;GAIG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,QAAQ,CAAC,IAAI,UAAU;IAEjB,aAAa,IAAI,OAAO,CAAC,KAAK,CAAC;IAI/B,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC;CAG/B;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}

package/dist/engine.js

@@ -0,0 +1,34 @@
+// === SEAM(011): engine boundary — temporary no-op stub ===
+// Story 011 inserts a TEMPORARY no-op engine at the reuse/rewrite seam mapped by
+// story 010 (SEAM-MAP.md): the SDK-coupled `createSession()` + the ~590-line
+// `prompt()` loop are CUT (→ story 023, the core rewrite). This module lets the ACP
+// agent boot end-to-end WITHOUT the credit-billing SDK `query()` path while the real
+// PTY + JSONL-tail engine is built in stories 013–015/023.
+//
+// It imports NOTHING — in particular nothing from `@anthropic-ai/claude-agent-sdk`
+// — so no billed path is reachable through the engine seam (story 011 Task 2.2).
+// Degrau 1 is READ-ONLY: `session/prompt` is not wired ACP-side, so the stub's work
+// methods are never reached in normal operation; if they ever are, they reject
+// loudly rather than silently no-op, keeping failures legible.
+/** Error message thrown when 011's READ-ONLY stub is asked to do real engine work. */
+export const ENGINE_NOT_IMPLEMENTED_011 = "engine not implemented in 011 (read-only Degrau 1)";
+/**
+ * No-op engine: boots cleanly, performs no SDK/PTY work, and rejects any real engine
+ * call with a legible error. Temporary scaffolding — replaced by the PTY engine in
+ * stories 013–015/023.
+ */
+export class StubEngine {
+    constructor() {
+        this.kind = "stub";
+    }
+    async createSession() {
+        throw new Error(ENGINE_NOT_IMPLEMENTED_011);
+    }
+    async prompt() {
+        throw new Error(ENGINE_NOT_IMPLEMENTED_011);
+    }
+}
+/** Factory for the default story-011 engine (the no-op stub). */
+export function createStubEngine() {
+    return new StubEngine();
+}

package/dist/event-switch.d.ts

@@ -0,0 +1,164 @@
+import type { JsonlEvent } from "./jsonl.js";
+/** A §6 `text` block — the only block {@link normaliseContent} ever synthesises (from a raw string). */
+export interface TextBlock {
+    type: "text";
+    text: string;
+}
+/** A §6 `thinking` block. `signature` is optional (present on signed extended-thinking blocks). */
+export interface ThinkingBlock {
+    type: "thinking";
+    thinking: string;
+    signature?: string;
+}
+/**
+ * A §6 `tool_use` block. `caller` is the §6 extra story 019 reads to attribute the call; it is
+ * PRESERVED here (never dropped) and OPTIONAL — its absence is the normal case, not drift.
+ */
+export interface ToolUseBlock {
+    type: "tool_use";
+    id?: string;
+    name?: string;
+    input?: unknown;
+    caller?: unknown;
+}
+/**
+ * A §6 `tool_result` block. Two §6 facts story 019 depends on are modelled here:
+ *   - `content` is a raw STRING **or** an array of {@link ContentBlock}s — story 016 preserves
+ *     whichever form arrives UNTRANSFORMED (the nested `tool_reference` sub-block lives inside the
+ *     array form). Story 019's unmodified `toolUpdateFromToolResult` consumes both forms.
+ *   - `is_error` may be `null` (not just `boolean`), per §6/§7.
+ * `tool_reference` is the §6 extra that may also appear; it is PRESERVED and OPTIONAL.
+ */
+export interface ToolResultBlock {
+    type: "tool_result";
+    tool_use_id?: string;
+    content?: string | ContentBlock[];
+    is_error?: boolean | null;
+    tool_reference?: unknown;
+}
+/** A §6 `image` block. `source` is preserved opaquely (story 019 owns image handling). */
+export interface ImageBlock {
+    type: "image";
+    source?: unknown;
+}
+/**
+ * The §6 content-block union story 016 carries through {@link normaliseContent} to the §7
+ * translators. The trailing catch-all member keeps the union OPEN: any `{ type, ... }` object is
+ * structurally assignable, so the array form of `message.content` passes through as
+ * {@link ContentBlock}[] without losing unmodelled blocks or arbitrary extra fields (R6).
+ */
+export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | ImageBlock | {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * A drift-telemetry record handed to {@link ClassifyOptions.onDrift}. Two flavours, discriminated by
+ * {@link DriftRecord.kind}:
+ *   - `"unknown-type"`  — `event.type` is NOT a documented §6 type; it reached the DEFAULT branch and
+ *     was logged-and-ignored (no routing, no SessionUpdate). `fields` carries any unrecognised
+ *     top-level keys on the event (possibly empty).
+ *   - `"unknown-fields"` — a KNOWN (routed) type carried unexpected top-level field(s); `fields`
+ *     names them. Routing is UNCHANGED — this is observational only.
+ * Telemetry is billing-free and side-effect-free beyond logging.
+ */
+export interface DriftRecord {
+    /** Which flavour of drift this is — an unknown `.type`, or unknown field(s) on a known type. */
+    kind: "unknown-type" | "unknown-fields";
+    /** The event type — the unrecognised type (unknown-type) or the routed type (unknown-fields). */
+    type: string;
+    /** The unrecognised top-level keys on the event (possibly empty for an unknown-type with none). */
+    fields: string[];
+    /** The event's `version` when present (e.g. the `claude` version that introduced the drift). */
+    version?: string;
+    /** The source event that drifted, carried through for downstream diagnostics. */
+    event?: JsonlEvent;
+}
+/** Options for {@link classifyEvent}. */
+export interface ClassifyOptions {
+    /**
+     * Injectable drift sink — invoked (a) when an event's `.type` is NOT a documented type and falls
+     * through to the DEFAULT branch (an `unknown-type` record), and (b) when a KNOWN, routed type
+     * carries unexpected top-level field(s) (an `unknown-fields` record). The injectable-seam pattern
+     * mirrors ./jsonl.ts so the telemetry is unit-testable without globals.
+     *
+     * When omitted, drift is logged via {@link defaultDriftSink} to STDERR (never stdout — stdout is
+     * the ACP protocol channel). A fully-documented known event emits NOTHING.
+     */
+    onDrift?: (record: DriftRecord) => void;
+}
+/** The two content-bearing roles — the only `type`s routed to the §7 translator content path. */
+type ContentType = "assistant" | "user";
+/**
+ * Classification of a content-bearing event (`assistant` / `user`). Routed to the content-block
+ * dispatch path consumed by the §7 translators.
+ */
+export interface ContentClassification {
+    class: "content";
+    /** The content-bearing type, echoed for the consumer. */
+    type: ContentType;
+    /** The message role — equal to {@link ContentClassification.type} for these two types. */
+    role: ContentType;
+    /**
+     * The NORMALISED content-block array (Task 1.3): `message.content` verbatim when it is an array,
+     * a raw string wrapped as `[{ type: 'text', text }]`, else `[]`. Always a real array so the §7
+     * translators can `.map`/index without tripping on the string form. Typed as {@link ContentBlock}[]
+     * (Task 1.4) so stories 018/019 read modelled blocks; the open catch-all union member keeps the §6
+     * extras (`tool_use.caller`, `tool_result.tool_reference`) and any unmodelled block surviving.
+     */
+    content: ContentBlock[];
+    /** The source typed event, carried through (universal fields preserved for downstream §7). */
+    event: JsonlEvent;
+}
+/**
+ * Classification of a recognised lifecycle/metadata event — one of the 13 documented non-content
+ * types. Recognised and classified, but it NEVER reaches a content translator.
+ */
+export interface LifecycleClassification {
+    class: "lifecycle";
+    /** The lifecycle/metadata type, echoed for the consumer. */
+    type: string;
+    /** The source typed event, carried through. */
+    event: JsonlEvent;
+}
+/**
+ * Classification of an UNRECOGNISED event — one whose `.type` is not documented and fell through to
+ * the DEFAULT branch. The DEFAULT arm emits an `unknown-type` drift record through `onDrift` before
+ * returning this marker; the marker itself carries NO content, so it produces no ACP SessionUpdate.
+ */
+export interface DriftClassification {
+    class: "drift";
+    /** The unrecognised type, echoed for the consumer. */
+    type: string;
+    /** The source typed event, carried through. */
+    event: JsonlEvent;
+}
+/** Discriminated union over the `class` field — the result of {@link classifyEvent}. */
+export type EventClassification = ContentClassification | LifecycleClassification | DriftClassification;
+/**
+ * Route a story-015 typed {@link JsonlEvent} by its `.type` to the appropriate classification.
+ *
+ * The two content-bearing types are dispatched to the content-block path consumed by the §7
+ * translators; the 13 documented lifecycle/metadata types (`system`, `result`, `started`, `mode`,
+ * `permission-mode`, `file-history-snapshot`, `attachment`, `queue-operation`, `last-prompt`,
+ * `ai-title`, `pr-link`, `agent-name`, and the post-`/compact` `summary`) are classified as
+ * recognised, NON-content events that neither crash nor reach a content translator. Every documented
+ * type has its OWN explicit `case` arm (no membership check) so drift against the DEFAULT branch is
+ * observable.
+ *
+ * No custom parsing is performed — the event already arrives typed from story 015's `projectEvent`;
+ * this function ONLY dispatches on `event.type`.
+ *
+ * Drift telemetry (R1.2, R3, R6): an UNRECOGNISED `.type` is a LOGGED, NON-FATAL drop — it emits an
+ * `unknown-type` record through `onDrift`, then returns a `drift` classification WITHOUT throwing and
+ * WITHOUT producing any ACP SessionUpdate. A KNOWN, routed type carrying unexpected top-level field(s)
+ * additionally emits an `unknown-fields` record (its routing is UNCHANGED). When `opts.onDrift` is
+ * omitted, drift is logged to STDERR via {@link defaultDriftSink}. Telemetry is billing-free and
+ * side-effect-free beyond logging, so the read path never assumes a fixed `.type` set.
+ *
+ * @param event the typed event projected by story 015's `projectEvent`.
+ * @param opts injectable `onDrift` seam; defaults to the stderr {@link defaultDriftSink}.
+ * @returns the {@link EventClassification} for the event.
+ */
+export declare function classifyEvent(event: JsonlEvent, opts?: ClassifyOptions): EventClassification;
+export {};
+//# sourceMappingURL=event-switch.d.ts.map

package/dist/event-switch.d.ts.map

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