@seanhogg/builderforce-memory 2026.9.29 → 2026.9.31

package/src/wire/sse.ts

@@ -0,0 +1,96 @@
+/**
+ * Server-Sent-Events `data:` framing.
+ *
+ * Every consumer of an SSE LLM stream does the same line-level dance: trim the line,
+ * keep only `data:` frames, and stop at the `[DONE]` sentinel, which ends an
+ * OpenAI-style stream (anything after it is not part of the response). JSON streams
+ * then parse each payload and skip empty or malformed ones.
+ *
+ * The line rule is `slice(5).trim()`, which accepts both `data: {…}` and the
+ * spaceless `data:{…}` some providers emit — `slice(6)` silently drops the latter.
+ *
+ * Two levels, one rule: {@link readSseDataPayloads} yields payload TEXT (for callers
+ * whose frames are not all JSON, or that parse per wire shape), and
+ * {@link readSseDataFrames} yields parsed JSON on top of it.
+ *
+ * Pure and defensive: a malformed frame is skipped, never thrown.
+ */
+
+/** The payload text of a `data:` line, or `undefined` for any other line. */
+export function sseDataPayload(line: string): string | undefined {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('data:')) return undefined;
+    return trimmed.slice(5).trim();
+}
+
+/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
+export function isSseDoneLine(line: string): boolean {
+    return sseDataPayload(line) === '[DONE]';
+}
+
+/**
+ * One SSE line's decoded JSON payload, or `undefined` when the line is not a usable
+ * data frame (not a `data:` line, the `[DONE]` sentinel, empty, or malformed JSON).
+ */
+export function parseSseDataLine(line: string): unknown | undefined {
+    const data = sseDataPayload(line);
+    if (!data || data === '[DONE]') return undefined;
+    try {
+        return JSON.parse(data);
+    } catch {
+        return undefined;
+    }
+}
+
+/** Every parsed `data:` frame of a whole, already-buffered SSE body, up to `[DONE]`. */
+export function* parseSseDataFrames(raw: string): Generator<unknown> {
+    for (const line of raw.split('\n')) {
+        if (isSseDoneLine(line)) return;
+        const parsed = parseSseDataLine(line);
+        if (parsed !== undefined) yield parsed;
+    }
+}
+
+/**
+ * Every `data:` payload of a live SSE byte stream, as text, as it arrives, up to
+ * `[DONE]`. A line split across chunks is held until its newline arrives; the reader
+ * lock is released however iteration ends. A missing body yields nothing.
+ */
+export async function* readSseDataPayloads(body: ReadableStream<Uint8Array> | null | undefined): AsyncGenerator<string> {
+    if (!body) return;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() as string; // split() always yields ≥1 element
+            for (const line of lines) {
+                const data = sseDataPayload(line);
+                if (data === undefined) continue;
+                if (data === '[DONE]') return;
+                yield data;
+            }
+        }
+        buffer += decoder.decode();
+        const tail = sseDataPayload(buffer);
+        if (tail !== undefined && tail !== '[DONE]') yield tail;
+    } finally {
+        reader.releaseLock();
+    }
+}
+
+/** Every parsed JSON `data:` frame of a live SSE byte stream, up to `[DONE]`. */
+export async function* readSseDataFrames(body: ReadableStream<Uint8Array> | null | undefined): AsyncGenerator<unknown> {
+    for await (const data of readSseDataPayloads(body)) {
+        if (!data) continue;
+        try {
+            yield JSON.parse(data);
+        } catch {
+            // Skip malformed SSE frames rather than failing the stream.
+        }
+    }
+}

package/src/wire/usage.ts

@@ -0,0 +1,95 @@
+/**
+ * Token-usage reading across vendor shapes.
+ *
+ * Two wire shapes reach a client: OpenAI-style `prompt_tokens`/`completion_tokens`
+ * (cached reads under `prompt_tokens_details.cached_tokens`, INCLUDED in
+ * `prompt_tokens`) and Anthropic-style `input_tokens`/`output_tokens` (cache reads
+ * and writes as separate top-level fields, EXCLUDED from `input_tokens`).
+ * {@link readUsageFields} reads either into one set of optional fields, keeping
+ * "absent" distinct from 0; each consumer then maps them to its own accounting.
+ *
+ * Streaming Anthropic responses split usage across events — input and cache on
+ * `message_start.message.usage`, output accumulating on `message_delta.usage` — and
+ * every count is cumulative, so {@link AnthropicStreamUsage} keeps the largest seen.
+ */
+
+/** A finite number, or `undefined` for null/undefined/non-numeric input. */
+export function finiteNumber(v: unknown): number | undefined {
+    if (v === null || v === undefined) return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+
+/** Usage as the vendor reported it. Every field is absent when the vendor omitted it. */
+export interface UsageFields {
+    /** `prompt_tokens`, else `input_tokens`. */
+    promptTokens?: number;
+    /** `completion_tokens`, else `output_tokens`. */
+    completionTokens?: number;
+    totalTokens?: number;
+    /** `cache_read_input_tokens`, else `prompt_tokens_details.cached_tokens`. */
+    cacheReadTokens?: number;
+    /** `cache_creation_input_tokens`. */
+    cacheCreationTokens?: number;
+}
+
+/** Reads a vendor `usage` object of either shape. Anything that is not an object reads as empty. */
+export function readUsageFields(u: unknown): UsageFields {
+    const out: UsageFields = {};
+    if (!u || typeof u !== 'object') return out;
+    const usage = u as Record<string, unknown>;
+    const prompt = finiteNumber(usage['prompt_tokens'] ?? usage['input_tokens']);
+    const completion = finiteNumber(usage['completion_tokens'] ?? usage['output_tokens']);
+    const total = finiteNumber(usage['total_tokens']);
+    if (prompt !== undefined) out.promptTokens = prompt;
+    if (completion !== undefined) out.completionTokens = completion;
+    if (total !== undefined) out.totalTokens = total;
+
+    const details = usage['prompt_tokens_details'];
+    const cachedFromDetails = details && typeof details === 'object'
+        ? finiteNumber((details as Record<string, unknown>)['cached_tokens'])
+        : undefined;
+    const cacheRead = finiteNumber(usage['cache_read_input_tokens']) ?? cachedFromDetails;
+    const cacheCreation = finiteNumber(usage['cache_creation_input_tokens']);
+    if (cacheRead !== undefined) out.cacheReadTokens = cacheRead;
+    if (cacheCreation !== undefined) out.cacheCreationTokens = cacheCreation;
+    return out;
+}
+
+/** The totals of one Anthropic stream. Input excludes both cache counts. */
+export interface AnthropicUsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    /** `message_start.message.model`, when the stream named it. */
+    model?: string;
+}
+
+/** Folds the usage events of one Anthropic Messages stream. Feed it every parsed frame. */
+export class AnthropicStreamUsage {
+    private readonly totals: AnthropicUsageTotals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+
+    observe(frame: unknown): void {
+        if (!frame || typeof frame !== 'object') return;
+        const ev = frame as { type?: unknown; message?: { usage?: unknown; model?: unknown }; usage?: unknown };
+        let usage: unknown;
+        if (ev.type === 'message_start') {
+            usage = ev.message?.usage;
+            if (typeof ev.message?.model === 'string') this.totals.model = ev.message.model;
+        } else if (ev.type === 'message_delta') {
+            usage = ev.usage;
+        }
+        if (!usage || typeof usage !== 'object') return;
+        const u = usage as Record<string, unknown>;
+        const keep = (current: number, v: unknown) => Math.max(current, finiteNumber(v) ?? 0);
+        this.totals.inputTokens = keep(this.totals.inputTokens, u['input_tokens']);
+        this.totals.outputTokens = keep(this.totals.outputTokens, u['output_tokens']);
+        this.totals.cacheReadTokens = keep(this.totals.cacheReadTokens, u['cache_read_input_tokens']);
+        this.totals.cacheCreationTokens = keep(this.totals.cacheCreationTokens, u['cache_creation_input_tokens']);
+    }
+
+    result(): AnthropicUsageTotals {
+        return { ...this.totals };
+    }
+}