@seanhogg/builderforce-memory 2026.9.28 → 2026.9.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.9.28",
+  "version": "2026.9.30",
   "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, enterprise RAG (ingestion pipelines, vector-store adapters, tenant/ACL-scoped hybrid retrieval), multi-agent graph orchestration, LLM telemetry and cost accounting, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -14,6 +14,14 @@
       "types": "./dist/retrieval/index.d.ts",
       "import": "./dist/retrieval/index.js"
     },
+    "./wire": {
+      "types": "./dist/wire/index.d.ts",
+      "import": "./dist/wire/index.js"
+    },
+    "./distillation": {
+      "types": "./dist/distillation/index.d.ts",
+      "import": "./dist/distillation/index.js"
+    },
     "./telemetry": {
       "types": "./dist/telemetry/index.d.ts",
       "import": "./dist/telemetry/index.js"
@@ -87,7 +95,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.9.28"
+    "@seanhogg/builderforce-memory-engine": "^2026.9.30"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -101,7 +109,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory-engine": "2026.9.28"
+    "@seanhogg/builderforce-memory-engine": "2026.9.30"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/bridges/AnthropicBridge.ts

@@ -8,6 +8,7 @@
 import { SSMError } from '../errors/SSMError.js';
 import type { LlmUsage } from '../telemetry/types.js';
 import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
+import { readSseDataFrames, readUsageFields, AnthropicStreamUsage } from '../wire/index.js';
 
 export interface AnthropicBridgeOptions {
     /** Anthropic API key. */
@@ -110,30 +111,26 @@ export class AnthropicBridge implements TransformerBridge {
             throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Anthropic streaming response has no body.');
         }
 
-        const model = opts.model ?? this._model;
-        let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, reportedModel = model;
-
-        yield* parseAnthropicStream(res.body, (event) => {
-            // `message_start` carries the input split; `message_delta` the running
-            // output count. Both are folded so the final usage is provider-measured.
-            const start = (event as any).message?.usage;
-            const delta = (event as any).usage;
-            const usage = start ?? delta;
-            if (!usage) return;
-            if (typeof (event as any).message?.model === 'string') reportedModel = (event as any).message.model;
-            input      = Math.max(input,      Number(usage.input_tokens) || 0);
-            output     = Math.max(output,     Number(usage.output_tokens) || 0);
-            cacheRead  = Math.max(cacheRead,  Number(usage.cache_read_input_tokens) || 0);
-            cacheWrite = Math.max(cacheWrite, Number(usage.cache_creation_input_tokens) || 0);
-        });
+        // `message_start` carries the input split; `message_delta` the running
+        // output count. Both are folded so the final usage is provider-measured.
+        const usage = new AnthropicStreamUsage();
+        for await (const frame of readSseDataFrames(res.body)) {
+            usage.observe(frame);
+            const ev = frame as { type?: unknown; delta?: { text?: unknown } };
+            // content_block_delta events carry the streamed text
+            if (ev.type === 'content_block_delta' && typeof ev.delta?.text === 'string' && ev.delta.text.length > 0) {
+                yield ev.delta.text;
+            }
+        }
 
+        const totals = usage.result();
         this._lastCall = {
             usage: {
-                model: reportedModel,
-                inputTokens: input,
-                outputTokens: output,
-                cachedInputTokens: cacheRead,
-                cacheWriteTokens: cacheWrite,
+                model: totals.model ?? opts.model ?? this._model,
+                inputTokens: totals.inputTokens,
+                outputTokens: totals.outputTokens,
+                cachedInputTokens: totals.cacheReadTokens,
+                cacheWriteTokens: totals.cacheCreationTokens,
             },
         };
     }
@@ -171,48 +168,6 @@ export class AnthropicBridge implements TransformerBridge {
     }
 }
 
-// ── SSE parser (Anthropic event format) ──────────────────────────────────────
-
-async function* parseAnthropicStream(
-    body: ReadableStream<Uint8Array>,
-    onEvent?: (event: Record<string, unknown>) => void,
-): AsyncIterable<string> {
-    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 → never undefined
-
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed.startsWith('data: ')) continue;
-
-                const data = trimmed.slice(6);
-                try {
-                    const event = JSON.parse(data) as Record<string, unknown>;
-                    onEvent?.(event);
-                    // content_block_delta events carry the streamed text
-                    if (event['type'] === 'content_block_delta') {
-                        const text = (event as any).delta?.text;
-                        if (typeof text === 'string' && text.length > 0) yield text;
-                    }
-                } catch {
-                    // Skip malformed SSE lines
-                }
-            }
-        }
-    } finally {
-        reader.releaseLock();
-    }
-}
-
 /**
  * Maps an Anthropic `usage` object onto the canonical {@link LlmUsage} shape.
  * Absent when the response omits usage (an older gateway shim), in which case
@@ -220,12 +175,13 @@ async function* parseAnthropicStream(
  */
 function readAnthropicUsage(usage: unknown, model: string): LlmUsage | undefined {
     if (!usage || typeof usage !== 'object') return undefined;
-    const u = usage as Record<string, unknown>;
+    // Anthropic's `input_tokens` already excludes both cache counts.
+    const u = readUsageFields(usage);
     return {
         model,
-        inputTokens: Number(u['input_tokens']) || 0,
-        outputTokens: Number(u['output_tokens']) || 0,
-        cachedInputTokens: Number(u['cache_read_input_tokens']) || 0,
-        cacheWriteTokens: Number(u['cache_creation_input_tokens']) || 0,
+        inputTokens: u.promptTokens ?? 0,
+        outputTokens: u.completionTokens ?? 0,
+        cachedInputTokens: u.cacheReadTokens ?? 0,
+        cacheWriteTokens: u.cacheCreationTokens ?? 0,
     };
 }

package/src/bridges/OpenAIBridge.ts

@@ -8,6 +8,7 @@
 import { SSMError } from '../errors/SSMError.js';
 import type { LlmUsage } from '../telemetry/types.js';
 import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
+import { readSseDataFrames, readUsageFields } from '../wire/index.js';
 
 export interface OpenAIBridgeOptions {
     /** OpenAI API key (or compatible service key). */
@@ -88,12 +89,14 @@ export class OpenAIBridge implements TransformerBridge {
         const model = opts.model ?? this._model;
         let usage: LlmUsage | undefined;
 
-        yield* parseOpenAIStream(res.body, (event) => {
-            // Only emitted because `_buildBody` sets `stream_options.include_usage`;
+        for await (const chunk of readSseDataFrames(res.body)) {
+            // Usage is only emitted because `_buildBody` sets `stream_options.include_usage`;
             // without it OpenAI streams no usage at all and cost would be a guess.
-            const reported = readOpenAIUsage((event as any).usage, (event as any).model ?? model);
+            const reported = readOpenAIUsage((chunk as any).usage, (chunk as any).model ?? model);
             if (reported) usage = reported;
-        });
+            const delta = (chunk as any).choices?.[0]?.delta?.content;
+            if (typeof delta === 'string' && delta.length > 0) yield delta;
+        }
 
         this._lastCall = usage ? { usage } : {};
     }
@@ -130,59 +133,17 @@ export class OpenAIBridge implements TransformerBridge {
     }
 }
 
-// ── SSE parser ────────────────────────────────────────────────────────────────
-
-async function* parseOpenAIStream(
-    body: ReadableStream<Uint8Array>,
-    onEvent?: (event: Record<string, unknown>) => void,
-): AsyncIterable<string> {
-    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;   // keep the last (possibly partial) line; split() always yields ≥1 element
-
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed.startsWith('data: ')) continue;
-
-                const data = trimmed.slice(6);
-                if (data === '[DONE]') return;
-
-                try {
-                    const chunk = JSON.parse(data) as Record<string, unknown>;
-                    onEvent?.(chunk);
-                    const delta = (chunk as any).choices?.[0]?.delta?.content;
-                    if (typeof delta === 'string' && delta.length > 0) yield delta;
-                } catch {
-                    // Malformed JSON in stream — skip silently
-                }
-            }
-        }
-    } finally {
-        reader.releaseLock();
-    }
-}
-
 /** Maps an OpenAI `usage` object onto the canonical {@link LlmUsage} shape. */
 function readOpenAIUsage(usage: unknown, model: string): LlmUsage | undefined {
     if (!usage || typeof usage !== 'object') return undefined;
-    const u = usage as Record<string, unknown>;
-    const cached = Number((u['prompt_tokens_details'] as Record<string, unknown> | undefined)?.['cached_tokens']) || 0;
-    const prompt = Number(u['prompt_tokens']) || 0;
+    const u = readUsageFields(usage);
+    const cached = u.cacheReadTokens ?? 0;
     return {
         model,
         // OpenAI reports `prompt_tokens` INCLUSIVE of cached tokens; the canonical
         // shape keeps them disjoint so the two rates are applied exactly once each.
-        inputTokens: Math.max(0, prompt - cached),
-        outputTokens: Number(u['completion_tokens']) || 0,
+        inputTokens: Math.max(0, (u.promptTokens ?? 0) - cached),
+        outputTokens: u.completionTokens ?? 0,
         cachedInputTokens: cached,
     };
 }

package/src/bridges/VertexAIBridge.ts

@@ -25,6 +25,7 @@
 import { SSMError } from '../errors/SSMError.js';
 import type { LlmUsage } from '../telemetry/types.js';
 import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
+import { readSseDataFrames } from '../wire/index.js';
 
 export interface VertexAIBridgeOptions {
     /** GCP project id. */
@@ -101,7 +102,8 @@ export class VertexAIBridge implements TransformerBridge {
         }
 
         let usage: LlmUsage | undefined;
-        for await (const event of parseSseJson(res.body)) {
+        for await (const frame of readSseDataFrames(res.body)) {
+            const event = frame as Record<string, unknown>;
             const text = readCandidateText(event);
             if (text) yield text;
             // Vertex repeats cumulative usage on each chunk; the last one wins.
@@ -264,34 +266,3 @@ function readVertexUsage(usage: unknown, model: string): LlmUsage | undefined {
         cachedInputTokens: cached,
     };
 }
-
-/** Parses an `alt=sse` stream into JSON events. */
-async function* parseSseJson(body: ReadableStream<Uint8Array>): AsyncIterable<Record<string, unknown>> {
-    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;
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed.startsWith('data:')) continue;
-                const payload = trimmed.slice(5).trim();
-                if (!payload || payload === '[DONE]') continue;
-                try {
-                    yield JSON.parse(payload) as Record<string, unknown>;
-                } catch {
-                    // Skip malformed SSE frames rather than failing the stream.
-                }
-            }
-        }
-    } finally {
-        reader.releaseLock();
-    }
-}