@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/docker/trajectory-reassembler.d.ts

@@ -0,0 +1,286 @@
+/**
+ * SSE → final-message reassembly for streaming LLM API responses.
+ *
+ * The reassembler reads SSE wire bytes and produces a body that is
+ * byte-identical to the equivalent non-streaming response. The contract
+ * is byte fidelity, not structural equivalence: see §6 invariants in
+ * docs/designs/mitm-token-trajectory-capture.md.
+ *
+ * Critical invariant (§6 #1): the values concatenated into the assembled
+ * body must be raw wire substrings. JSON.parse is allowed only to read
+ * structural fields (`type`, `index`, `delta.type`); the values themselves
+ * are spliced from the wire. There is exactly one JSON.stringify-style
+ * serialization in this file — and even that is a substring extraction
+ * helper for header/usage fields, not a JSON round-trip on captured
+ * content.
+ */
+import type { CaptureProvider, Reassembler, ReassemblyResult } from './trajectory-types.js';
+/** Errors thrown by the reassemblers when the stream is unrecoverable. */
+export declare class ReassemblyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown by `finalize()` when the stream ended before the provider's
+ * terminal event was parsed. This is a transport truncation / upstream
+ * abort, NOT a reassembly bug — the caller should classify it as
+ * `mid-stream-abort` rather than `reassembly-failure` so disconnects don't
+ * pollute reassembly-failure metrics.
+ */
+export declare class TruncatedStreamError extends ReassemblyError {
+    constructor(message: string);
+}
+export interface RawEvent {
+    readonly eventType: string;
+    readonly dataUtf8: string;
+    readonly offsetMs: number;
+}
+/**
+ * Provider-agnostic SSE line splitter. Mirrors the line discipline in
+ * `sse-extractor.ts` (CRLF or LF treated as a single break) but emits
+ * `(eventType, dataPayload)` tuples instead of parsed events. The data
+ * payload is the exact bytes after `data: ` — no trim, no parse.
+ *
+ * Bytes are decoded through a `StringDecoder` so a multibyte UTF-8
+ * sequence split across two `feed()` chunks (zlib emits chunks on
+ * arbitrary boundaries) is held back until its continuation arrives,
+ * rather than each chunk decoding independently to a `U+FFFD`
+ * replacement and corrupting the captured body.
+ */
+export declare class SseLineSplitter {
+    private readonly decoder;
+    private buffer;
+    private currentEventType;
+    /** Pending `data:` payload for the in-flight event (multi-line dataspec). */
+    private currentData;
+    feed(chunk: Buffer, sink: (event: string, data: string) => void): void;
+    /** Force-flush a trailing line buffer (no terminator). */
+    flush(sink: (event: string, data: string) => void): void;
+    private processLine;
+}
+/**
+ * Reads a JSON object at `start` of `data`, returning the substring that
+ * makes up the value. Tracks brace depth while respecting string escapes
+ * — we never need the parsed value, only the raw substring.
+ */
+export declare function readJsonValueSubstring(data: string, start: number): string | undefined;
+/** Returns the index of the closing `"` of a JSON string starting at `start`. */
+export declare function findJsonStringEnd(data: string, start: number): number;
+/**
+ * Finds a top-level field by name in a JSON object and returns the raw
+ * substring of its value. Returns `undefined` if not found.
+ *
+ * Naïve scan that respects string escapes; sufficient for the
+ * well-formed Anthropic/OpenAI envelopes we capture.
+ */
+export declare function findFieldValueSubstring(data: string, fieldName: string): string | undefined;
+/**
+ * Replaces the value of a top-level field by substring. Locates
+ * `"fieldName"` followed by `:`, finds the existing value's substring,
+ * and splices in the new value. The new value MUST already be a valid
+ * JSON expression (string-with-quotes, object, array, primitive).
+ *
+ * A generic top-level-field splice — not provider-specific. Shared by
+ * the Anthropic envelope-splice (`content`/`stop_reason`/`usage`) and the
+ * Responses envelope-splice (`output`). Returns `body` unchanged if the
+ * field is absent.
+ */
+export declare function replaceTopLevelField(body: string, fieldName: string, newValue: string): string;
+/**
+ * Decodes a JSON string literal (the substring including surrounding
+ * quotes) into the raw string it represents. Used for `text` /
+ * `thinking` / `signature` payloads where the wire bytes carry escapes
+ * we must decode before appending to our concatenation buffer.
+ */
+export declare function decodeJsonString(literal: string): string;
+/**
+ * Re-encodes a string as a JSON string literal (including quotes).
+ * Used when assembling the final body — we accept JSON.stringify of a
+ * single string value because the captured `text` payload was decoded
+ * from the same wire encoding; re-encoding restores byte fidelity to
+ * the equivalent non-streaming response (which carries the standard
+ * JSON encoding).
+ *
+ * This is the ONE place strings are JSON-encoded in this file.
+ * `tool_use.input` and `tool_calls[].function.arguments` are NEVER
+ * encoded this way — they're spliced as raw wire substrings.
+ */
+export declare function encodeJsonString(value: string): string;
+/**
+ * Reads the `type` discriminator of an SSE data payload. The `type`
+ * field in `data` is the authoritative event identifier across both the
+ * Anthropic typed-event and OpenAI named-event streams; the SSE
+ * `event:` line is advisory.
+ */
+export declare function peekTypeField(data: string): string | undefined;
+/** Reads a top-level JSON string field, decoded. Returns `undefined` if absent or not a string. */
+export declare function peekStringField(data: string, name: string): string | undefined;
+/** Reads a top-level JSON number field. Returns `undefined` if absent or non-finite. */
+export declare function peekNumberField(data: string, name: string): number | undefined;
+/**
+ * Shared SSE reassembler skeleton. Owns the boilerplate every provider's
+ * state machine needs — splitter feeding, event log, started-at clock,
+ * fail latching, and the finalize gating — and exposes three seams the
+ * subclasses implement:
+ *
+ *   - `dispatch(eventType, data)`: route a single SSE event into provider
+ *     state. May throw to latch a fatal reassembly failure.
+ *   - `terminalSeen()`: true once the provider's terminal event was
+ *     parsed (`message_stop`, `[DONE]`, or `response.completed`). Gates
+ *     both finalize success and the `canFinalize()` lifecycle signal.
+ *   - `assembleResult()`: build the final body + structured fields. May
+ *     throw `ReassemblyError`; the base does NOT catch it so the tap can
+ *     distinguish a reassembly failure from success.
+ *
+ * The base intentionally holds NO envelope-splice machinery — the
+ * providers assemble differently (Anthropic splices a message envelope,
+ * the OpenAI Responses reassembler assembles from item-done payloads), so
+ * that logic stays subclass-private.
+ */
+export declare abstract class AbstractSseReassembler implements Reassembler {
+    protected readonly splitter: SseLineSplitter;
+    protected readonly events: RawEvent[];
+    protected readonly startedAt: number;
+    protected failed: boolean;
+    protected failureReason?: string;
+    push(chunk: Buffer): void;
+    finalize(): ReassemblyResult;
+    /**
+     * True once the terminal event has been parsed. Lets the tap finalize a
+     * complete-but-socket-aborted stream instead of poisoning it.
+     */
+    canFinalize(): boolean;
+    private onEvent;
+    protected abstract dispatch(eventType: string, data: string): void;
+    protected abstract terminalSeen(): boolean;
+    protected abstract assembleResult(): ReassemblyResult;
+}
+export declare class AnthropicReassembler extends AbstractSseReassembler {
+    /**
+     * Envelope captured from `message_start.message` — used to extract
+     * top-level fields (id, type, role, model, etc.). We splice the
+     * assembled content array between the message-envelope prefix and
+     * suffix so the assembled body is byte-identical to a non-streaming
+     * response.
+     */
+    private messageEnvelope?;
+    private blocks;
+    private stopReason?;
+    private stopSequence?;
+    private usageRaw?;
+    private providerRequestId?;
+    private modelFingerprint?;
+    private receivedMessageStop;
+    protected terminalSeen(): boolean;
+    protected assembleResult(): ReassemblyResult;
+    protected dispatch(eventType: string, data: string): void;
+    private onMessageStart;
+    private onContentBlockStart;
+    private onContentBlockDelta;
+    private onContentBlockStop;
+    private onMessageDelta;
+    /**
+     * Assembles the final non-streaming message body from the captured
+     * state. Constructed via raw substring concatenation — see §6 invariant
+     * #1.
+     *
+     * Strategy: the `message` envelope from `message_start` already has
+     * the shape of a non-streaming response, but with empty content,
+     * stop_reason: null, stop_sequence: null, and a partial usage. We
+     * mutate three fields by substring replacement:
+     *   - "content":[]  → "content":[<blocks>]
+     *   - "stop_reason":null → "stop_reason":"<reason>"
+     *   - "stop_sequence":null → "stop_sequence":<value>
+     *   - "usage":{<initial>} → "usage":<final-from-message_delta>
+     */
+    private assembleBody;
+    private assembleContentArray;
+    private assembleBlock;
+    private parseUsage;
+}
+/**
+ * Reassembler for the OpenAI Responses API stream that Codex emits on
+ * chatgpt.com. Named `response.*` events; an item tree addressed by
+ * `output_index` (and content parts by `content_index`).
+ *
+ * The terminal `response.completed` carries the FULL response envelope
+ * (~35 fields: status, usage, instructions, tools, ...) but with its
+ * `output` array EMPTY. So the final body is the VERBATIM terminal
+ * envelope (zero re-encode, all fields preserved) with its empty
+ * `"output":[]` spliced to the assembled `response.output_item.done`
+ * payloads (each a COMPLETE item JSON object on the wire, spliced
+ * VERBATIM, in output_index order). providerRequestId/stopReason/usage
+ * derive from that same envelope. The accumulated `output_text` deltas
+ * are cross-checked against the item-done text (delta-join must equal
+ * the item text) — a mismatch throws so the binary-session model poisons
+ * `reassembly-failure` rather than silently trusting item.done.
+ */
+export declare class ResponsesReassembler extends AbstractSseReassembler {
+    private completedSeen;
+    private status?;
+    private usageRaw?;
+    private providerRequestId?;
+    private modelFingerprint?;
+    /** Verbatim `response` envelope from the terminal event (output[] empty). */
+    private responseEnvelopeRaw?;
+    /**
+     * Stop reason for the record. Equals `status` for a completed response;
+     * for `incomplete`/`failed` prefers the more specific
+     * `incomplete_details.reason` / `error` reason when present (FIX 4).
+     */
+    private stopReasonValue?;
+    private readonly items;
+    protected terminalSeen(): boolean;
+    protected dispatch(eventType: string, data: string): void;
+    private onResponseCreated;
+    private getItem;
+    private onOutputItemAdded;
+    private onOutputTextDelta;
+    private onOutputTextDone;
+    private onOutputItemDone;
+    private onTerminal;
+    protected assembleResult(): ReassemblyResult;
+    /**
+     * Cross-check (FIX 3): the per-content-index delta-join must equal the
+     * text the provider reported in `response.output_text.done` and/or the
+     * `output_item.done` message content. The verbatim-item-splice strategy
+     * trusts `output_item.done` as self-contained; this guard fails LOUD
+     * (throws → the binary-session model poisons `reassembly-failure`)
+     * rather than silently emitting a body whose final text disagrees with
+     * the streamed deltas.
+     */
+    private crossCheckDeltasAgainstItems;
+    /**
+     * Byte-faithful body (FIX 2): the verbatim terminal `response` envelope
+     * with its empty `"output":[]` spliced to the assembled item array.
+     * Falls back to a minimal synthesized envelope only if the terminal
+     * event carried no `response` (defensive; the stream-without-terminal
+     * case is already gated by `terminalSeen()` before assembly).
+     */
+    private assembleBody;
+    private parseUsage;
+}
+/**
+ * Classify an upstream host into a capture provider. Single source of
+ * truth for host → provider mapping across the capture pipeline (the
+ * `ExchangeRecord.provider` field and reassembler selection).
+ *
+ * Note: `provider:'openai'` spans two wire formats — `api.openai.com`
+ * Chat Completions and `chatgpt.com` Responses — disambiguated by the
+ * record's `host` field. `auth.openai.com` intentionally stays
+ * `'unknown'`: it is an OAuth/identity host, not a completion host, so
+ * do NOT broaden this to map all `*.openai.com` to `'openai'` (that would
+ * route a non-completion host to a reassembler).
+ */
+export declare function providerForHost(host: string): CaptureProvider;
+/**
+ * Pick a reassembler by upstream host. Routing is BY HOST so a specific
+ * wire format maps to its state machine. Both OpenAI Responses surfaces —
+ * `chatgpt.com/backend-api/codex/responses` (Codex via ChatGPT OAuth) and
+ * `api.openai.com/v1/responses` (the platform Responses API, e.g. Codex
+ * authenticated with an API key) — share the same wire format, so both use
+ * `ResponsesReassembler`. Note: the classic Chat Completions API
+ * (`/v1/chat/completions`) is NOT a path any IronCurtain harness uses, so
+ * `openaiProvider` does not capture it. Unclassifiable hosts yield
+ * `undefined`; the caller falls back to capturing raw bytes verbatim.
+ */
+export declare function createReassembler(host: string): Reassembler | undefined;