@seanhogg/builderforce-memory 2026.6.18

package/dist/agent/SSMAgent.d.ts

@@ -0,0 +1,146 @@
+/**
+ * SSMAgent – high-level orchestration primitive.
+ *
+ * Combines SSMRuntime (inference + adaptation), MemoryStore (persistent facts),
+ * and a conversation history manager into a single agent interface.
+ *
+ * Prompt format matches MambaChatbot so the SSM model can follow the same
+ * token patterns it was trained on:
+ *
+ *   System: <systemPrompt>
+ *   [Fact (<key>): <content>  ← injected by importance desc, filtered by tag/key]
+ *   User: <message>
+ *   Assistant: <message>
+ *   ...
+ *   User: <current input>
+ *   Assistant:
+ */
+import type { AdaptOptions, AdaptResult } from '../session/index.js';
+import type { SSMRuntime, GenerateOptions } from '../runtime/SSMRuntime.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+export type MessageRole = 'user' | 'assistant' | 'system';
+export interface AgentMessage {
+    role: MessageRole;
+    content: string;
+}
+export interface SSMAgentOptions {
+    /** The runtime to use for inference and adaptation. */
+    runtime: SSMRuntime;
+    /** Optional memory store for persistent fact retrieval. */
+    memory?: MemoryStore;
+    /** Default system prompt. Default: 'You are a helpful assistant.' */
+    systemPrompt?: string;
+    /**
+     * Max user+assistant turn pairs to include in context.
+     * Oldest turns are dropped first.
+     * Default: 20
+     */
+    maxHistoryTurns?: number;
+    /**
+     * When true, the agent serialises its conversation history to memory
+     * under the `__history__` key on `destroy()`, and loads it back on
+     * construction if the key is present.
+     * Default: true
+     */
+    persistHistory?: boolean;
+    /**
+     * How facts are picked from the MemoryStore for injection each turn:
+     *   - 'semantic'  (default): top-`maxFacts` by SSM-embedding similarity to
+     *     the input (`recallSimilar`) — injects the few *relevant* facts, which
+     *     keeps the prompt small and is paraphrase-robust.
+     *   - 'substring': legacy behaviour — only facts whose key literally appears
+     *     in the input.
+     * `injectAllFacts` on a turn overrides this and injects everything.
+     */
+    factSelection?: 'semantic' | 'substring';
+    /** Max facts injected in 'semantic' mode. Default: 8. */
+    maxFacts?: number;
+}
+export interface ThinkOptions extends GenerateOptions {
+    /** Override the system prompt for this single turn only. */
+    systemPrompt?: string;
+    /**
+     * Inject all recalled facts into the context for this turn.
+     * Default: false — only facts whose keys appear in the input are injected.
+     */
+    injectAllFacts?: boolean;
+}
+export declare class SSMAgent {
+    private readonly _runtime;
+    private readonly _memory;
+    private readonly _systemPrompt;
+    private readonly _maxHistoryTurns;
+    private readonly _persistHistory;
+    private readonly _factSelection;
+    private readonly _maxFacts;
+    private _history;
+    constructor(opts: SSMAgentOptions);
+    /**
+     * Initialises the agent, loading persisted history from memory if available.
+     * Call this after construction when `persistHistory` is enabled and a memory
+     * store is present.
+     */
+    init(): Promise<void>;
+    /**
+     * Sends a user message and returns the full assistant response.
+     * Routes through InferenceRouter — may use SSM or transformer bridge.
+     * Appends both user and assistant turns to history.
+     */
+    think(input: string, opts?: ThinkOptions): Promise<string>;
+    /**
+     * Streaming variant of `think()`.
+     * Always uses the SSM path (consistent low-latency streaming).
+     * Appends history after the stream completes.
+     */
+    thinkStream(input: string, opts?: ThinkOptions): AsyncIterable<string>;
+    /**
+     * Fine-tunes the SSM on the provided text.
+     * Pass-through to runtime.adapt().
+     */
+    learn(data: string, opts?: AdaptOptions): Promise<AdaptResult>;
+    /**
+     * Stores a fact in the MemoryStore.
+     * Throws SSMError('MEMORY_UNAVAILABLE') if no MemoryStore was provided.
+     */
+    remember(key: string, fact: string): Promise<void>;
+    /**
+     * Retrieves a fact from the MemoryStore.
+     * Returns `undefined` if key not found or no MemoryStore was provided.
+     */
+    recall(key: string): Promise<string | undefined>;
+    /** Clears all conversation history. Does not affect MemoryStore. */
+    clearHistory(): void;
+    /** Number of complete user+assistant turn pairs. */
+    get turnCount(): number;
+    /** Read-only snapshot of the current conversation history. */
+    get history(): readonly AgentMessage[];
+    /**
+     * Persists conversation history to memory (if `persistHistory` is true and
+     * a MemoryStore is available) and destroys the underlying runtime.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Selects which stored facts to inject for this turn:
+     *   - injectAllFacts → every fact
+     *   - 'semantic'     → top-`maxFacts` by SSM-embedding similarity to the input
+     *                      (recallSimilar; falls back to lexical overlap when the
+     *                      runtime can't embed) — small, relevant, paraphrase-robust
+     *   - 'substring'    → legacy key-substring match
+     */
+    private _selectFacts;
+    /**
+     * Builds the prompt as two parts split at the cache boundary:
+     *   - `system`       : the System line + injected Facts — stable across a
+     *                      turn, so the transformer can cache it (see
+     *                      SSMRuntime.GenerateOptions.system).
+     *   - `conversation` : trimmed history + the current User turn — volatile,
+     *                      regenerated every turn.
+     *
+     * Joining them with a newline (which SSMRuntime does on the SSM path)
+     * reproduces the original single-string MambaChatbot format exactly, so the
+     * SSM sees an unchanged prompt.
+     */
+    private _buildPrompt;
+    private _appendHistory;
+}
+//# sourceMappingURL=SSMAgent.d.ts.map

package/dist/agent/SSMAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SSMAgent.d.ts","sourceRoot":"","sources":["../../src/agent/SSMAgent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,0BAA0B,CAAC;AAKzE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,YAAY;IACzB,IAAI,EAAK,WAAW,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC5B,uDAAuD;IACvD,OAAO,EAAY,UAAU,CAAC;IAC9B,2DAA2D;IAC3D,MAAM,CAAC,EAAY,WAAW,CAAC;IAC/B,qEAAqE;IACrE,YAAY,CAAC,EAAM,MAAM,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,EAAG,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,cAAc,CAAC,EAAI,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAK,UAAU,GAAG,WAAW,CAAC;IAC5C,yDAAyD;IACzD,QAAQ,CAAC,EAAU,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAa,SAAQ,eAAe;IACjD,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAOD,qBAAa,QAAQ;IACjB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAa;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAsB;gBAE1B,IAAI,EAAE,eAAe;IAUjC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBpE;;;;OAIG;IACI,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,aAAa,CAAC,MAAM,CAAC;IAuBjF;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAMpE;;;OAGG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQtD,oEAAoE;IACpE,YAAY,IAAI,IAAI;IAIpB,oDAAoD;IACpD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,8DAA8D;IAC9D,IAAI,OAAO,IAAI,SAAS,YAAY,EAAE,CAErC;IAID;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAa9B;;;;;;;OAOG;YACW,YAAY;IAS1B;;;;;;;;;;;OAWG;YACW,YAAY;IA6C1B,OAAO,CAAC,cAAc;CAIzB"}

package/dist/agent/SSMAgent.js

@@ -0,0 +1,231 @@
+/**
+ * SSMAgent – high-level orchestration primitive.
+ *
+ * Combines SSMRuntime (inference + adaptation), MemoryStore (persistent facts),
+ * and a conversation history manager into a single agent interface.
+ *
+ * Prompt format matches MambaChatbot so the SSM model can follow the same
+ * token patterns it was trained on:
+ *
+ *   System: <systemPrompt>
+ *   [Fact (<key>): <content>  ← injected by importance desc, filtered by tag/key]
+ *   User: <message>
+ *   Assistant: <message>
+ *   ...
+ *   User: <current input>
+ *   Assistant:
+ */
+import { SSMError } from '../errors/SSMError.js';
+/** Key used to persist conversation history in the MemoryStore. */
+const HISTORY_KEY = '__history__';
+// ── SSMAgent ──────────────────────────────────────────────────────────────────
+export class SSMAgent {
+    _runtime;
+    _memory;
+    _systemPrompt;
+    _maxHistoryTurns;
+    _persistHistory;
+    _factSelection;
+    _maxFacts;
+    _history = [];
+    constructor(opts) {
+        this._runtime = opts.runtime;
+        this._memory = opts.memory;
+        this._systemPrompt = opts.systemPrompt ?? 'You are a helpful assistant.';
+        this._maxHistoryTurns = opts.maxHistoryTurns ?? 20;
+        this._persistHistory = opts.persistHistory ?? true;
+        this._factSelection = opts.factSelection ?? 'semantic';
+        this._maxFacts = opts.maxFacts ?? 8;
+    }
+    /**
+     * Initialises the agent, loading persisted history from memory if available.
+     * Call this after construction when `persistHistory` is enabled and a memory
+     * store is present.
+     */
+    async init() {
+        if (this._persistHistory && this._memory) {
+            try {
+                const entry = await this._memory.recall(HISTORY_KEY);
+                if (entry) {
+                    const parsed = JSON.parse(entry.content);
+                    if (Array.isArray(parsed)) {
+                        this._history = parsed;
+                    }
+                }
+            }
+            catch {
+                // Corrupted or missing history — start fresh
+                this._history = [];
+            }
+        }
+    }
+    // ── Inference ─────────────────────────────────────────────────────────────
+    /**
+     * Sends a user message and returns the full assistant response.
+     * Routes through InferenceRouter — may use SSM or transformer bridge.
+     * Appends both user and assistant turns to history.
+     */
+    async think(input, opts = {}) {
+        const { systemPrompt, injectAllFacts, ...generateOpts } = opts;
+        const { system, conversation } = await this._buildPrompt(input, systemPrompt, injectAllFacts);
+        const raw = await this._runtime.generate(conversation, {
+            maxNewTokens: 200,
+            temperature: 0.7,
+            topK: 50,
+            topP: 0.9,
+            system,
+            ...generateOpts,
+        });
+        // Trim any additional turns the model may have hallucinated
+        const response = raw.split('\nUser:')[0].trim();
+        this._appendHistory(input, response);
+        return response;
+    }
+    /**
+     * Streaming variant of `think()`.
+     * Always uses the SSM path (consistent low-latency streaming).
+     * Appends history after the stream completes.
+     */
+    async *thinkStream(input, opts = {}) {
+        const { systemPrompt, injectAllFacts, bridgeOpts: _b, ...completeOpts } = opts;
+        const { system, conversation } = await this._buildPrompt(input, systemPrompt, injectAllFacts);
+        let full = '';
+        for await (const token of this._runtime.stream(conversation, {
+            maxNewTokens: 200,
+            temperature: 0.7,
+            topK: 50,
+            topP: 0.9,
+            system,
+            ...completeOpts,
+        })) {
+            full += token;
+            yield token;
+        }
+        const response = full.split('\nUser:')[0].trim();
+        this._appendHistory(input, response);
+    }
+    // ── Adaptation ────────────────────────────────────────────────────────────
+    /**
+     * Fine-tunes the SSM on the provided text.
+     * Pass-through to runtime.adapt().
+     */
+    async learn(data, opts) {
+        return this._runtime.adapt(data, opts);
+    }
+    // ── Memory ────────────────────────────────────────────────────────────────
+    /**
+     * Stores a fact in the MemoryStore.
+     * Throws SSMError('MEMORY_UNAVAILABLE') if no MemoryStore was provided.
+     */
+    async remember(key, fact) {
+        if (!this._memory) {
+            throw new SSMError('MEMORY_UNAVAILABLE', 'SSMAgent was constructed without a MemoryStore. Pass `memory` in SSMAgentOptions.');
+        }
+        await this._memory.remember(key, fact);
+    }
+    /**
+     * Retrieves a fact from the MemoryStore.
+     * Returns `undefined` if key not found or no MemoryStore was provided.
+     */
+    async recall(key) {
+        if (!this._memory)
+            return undefined;
+        const entry = await this._memory.recall(key);
+        return entry?.content;
+    }
+    // ── History ───────────────────────────────────────────────────────────────
+    /** Clears all conversation history. Does not affect MemoryStore. */
+    clearHistory() {
+        this._history = [];
+    }
+    /** Number of complete user+assistant turn pairs. */
+    get turnCount() {
+        return Math.floor(this._history.length / 2);
+    }
+    /** Read-only snapshot of the current conversation history. */
+    get history() {
+        return this._history;
+    }
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+    /**
+     * Persists conversation history to memory (if `persistHistory` is true and
+     * a MemoryStore is available) and destroys the underlying runtime.
+     */
+    async destroy() {
+        if (this._persistHistory && this._memory && this._history.length > 0) {
+            try {
+                await this._memory.remember(HISTORY_KEY, JSON.stringify(this._history));
+            }
+            catch {
+                // Persistence failure is non-fatal
+            }
+        }
+        this._runtime.destroy();
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    /**
+     * Selects which stored facts to inject for this turn:
+     *   - injectAllFacts → every fact
+     *   - 'semantic'     → top-`maxFacts` by SSM-embedding similarity to the input
+     *                      (recallSimilar; falls back to lexical overlap when the
+     *                      runtime can't embed) — small, relevant, paraphrase-robust
+     *   - 'substring'    → legacy key-substring match
+     */
+    async _selectFacts(input, injectAllFacts) {
+        const memory = this._memory;
+        if (injectAllFacts)
+            return memory.recallAll();
+        if (this._factSelection === 'semantic') {
+            return memory.recallSimilar(input, this._maxFacts, this._runtime);
+        }
+        return (await memory.recallAll()).filter(f => input.includes(f.key));
+    }
+    /**
+     * Builds the prompt as two parts split at the cache boundary:
+     *   - `system`       : the System line + injected Facts — stable across a
+     *                      turn, so the transformer can cache it (see
+     *                      SSMRuntime.GenerateOptions.system).
+     *   - `conversation` : trimmed history + the current User turn — volatile,
+     *                      regenerated every turn.
+     *
+     * Joining them with a newline (which SSMRuntime does on the SSM path)
+     * reproduces the original single-string MambaChatbot format exactly, so the
+     * SSM sees an unchanged prompt.
+     */
+    async _buildPrompt(input, systemPromptOverride, injectAllFacts) {
+        const sys = systemPromptOverride ?? this._systemPrompt;
+        const systemLines = [`System: ${sys}`];
+        // Inject relevant facts from MemoryStore, sorted by importance descending
+        if (this._memory) {
+            const relevant = (await this._selectFacts(input, injectAllFacts))
+                // Never inject the serialised conversation-history blob as a fact.
+                .filter(f => f.key !== HISTORY_KEY);
+            // Sort by importance descending (missing importance defaults to 0.5)
+            const sorted = relevant.slice().sort((a, b) => (b.importance ?? 0.5) - (a.importance ?? 0.5));
+            for (const fact of sorted) {
+                systemLines.push(`Fact (${fact.key}): ${fact.content}`);
+            }
+        }
+        // Trim history to maxHistoryTurns pairs (oldest first)
+        const maxMessages = this._maxHistoryTurns * 2;
+        const trimmed = this._history.length > maxMessages
+            ? this._history.slice(this._history.length - maxMessages)
+            : this._history;
+        const convoLines = [];
+        for (const msg of trimmed) {
+            const speaker = msg.role === 'user' ? 'User' : 'Assistant';
+            convoLines.push(`${speaker}: ${msg.content}`);
+        }
+        convoLines.push(`User: ${input}`);
+        convoLines.push('Assistant:');
+        return {
+            system: systemLines.join('\n'),
+            conversation: convoLines.join('\n'),
+        };
+    }
+    _appendHistory(input, response) {
+        this._history.push({ role: 'user', content: input });
+        this._history.push({ role: 'assistant', content: response });
+    }
+}
+//# sourceMappingURL=SSMAgent.js.map

package/dist/agent/SSMAgent.js.map

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

package/dist/agent/index.d.ts

@@ -0,0 +1,3 @@
+export { SSMAgent } from './SSMAgent.js';
+export type { SSMAgentOptions, ThinkOptions, AgentMessage, MessageRole } from './SSMAgent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,2 @@
+export { SSMAgent } from './SSMAgent.js';
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/bridges/AnthropicBridge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AnthropicBridge – TransformerBridge implementation for the Anthropic Messages API.
+ *
+ * Uses the /v1/messages endpoint.  System prompts are passed as the top-level
+ * `system` field (not a message role), per the Anthropic spec.
+ */
+import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+export interface AnthropicBridgeOptions {
+    /** Anthropic API key. */
+    apiKey: string;
+    /**
+     * Model to use. Default: 'claude-haiku-4-5' (cheapest current model:
+     * $1/1M input, $5/1M output). The previous default `claude-3-5-haiku-*`
+     * was retired on 2026-02-19 and now 404s.
+     */
+    model?: string;
+    /** Anthropic API version header. Default: '2023-06-01'. */
+    apiVersion?: string;
+    /** Default system prompt. Default: none. */
+    systemPrompt?: string;
+    /** Default max tokens — required by Anthropic. Default: 1024. */
+    maxTokens?: number;
+    /**
+     * When true (default), the system prompt is sent as a cacheable content
+     * block (`cache_control: {type: 'ephemeral'}`). Prompt caching bills cache
+     * reads at ~10% of the input price, so a stable system prefix reused across
+     * turns is up to ~90% cheaper on its input tokens. Caching only engages once
+     * the cached prefix exceeds the model minimum (~4096 tokens for Haiku 4.5);
+     * below that it is a silent no-op, never an error. Set false to opt out.
+     */
+    cacheSystem?: boolean;
+}
+export declare class AnthropicBridge implements TransformerBridge {
+    readonly supportsStreaming: true;
+    private readonly _apiKey;
+    private readonly _model;
+    private readonly _apiVersion;
+    private readonly _systemPrompt;
+    private readonly _maxTokens;
+    private readonly _cacheSystem;
+    constructor(opts: AnthropicBridgeOptions);
+    generate(prompt: string, opts?: BridgeGenerateOptions): Promise<string>;
+    stream(prompt: string, opts?: BridgeGenerateOptions): AsyncIterable<string>;
+    private _buildBody;
+    private _fetch;
+}
+//# sourceMappingURL=AnthropicBridge.d.ts.map

package/dist/bridges/AnthropicBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnthropicBridge.d.ts","sourceRoot":"","sources":["../../src/bridges/AnthropicBridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEvF,MAAM,WAAW,sBAAsB;IACnC,yBAAyB;IACzB,MAAM,EAAU,MAAM,CAAC;IACvB;;;;OAIG;IACH,KAAK,CAAC,EAAU,MAAM,CAAC;IACvB,2DAA2D;IAC3D,UAAU,CAAC,EAAK,MAAM,CAAC;IACvB,4CAA4C;IAC5C,YAAY,CAAC,EAAG,MAAM,CAAC;IACvB,iEAAiE;IACjE,SAAS,CAAC,EAAM,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAI,OAAO,CAAC;CAC3B;AAID,qBAAa,eAAgB,YAAW,iBAAiB;IACrD,QAAQ,CAAC,iBAAiB,EAAG,IAAI,CAAU;IAE3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAY;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;gBAE5B,IAAI,EAAE,sBAAsB;IASlC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB1E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,aAAa,CAAC,MAAM,CAAC;IAmBtF,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,MAAM;CAWjB"}

package/dist/bridges/AnthropicBridge.js

@@ -0,0 +1,120 @@
+/**
+ * AnthropicBridge – TransformerBridge implementation for the Anthropic Messages API.
+ *
+ * Uses the /v1/messages endpoint.  System prompts are passed as the top-level
+ * `system` field (not a message role), per the Anthropic spec.
+ */
+import { SSMError } from '../errors/SSMError.js';
+const API_URL = 'https://api.anthropic.com/v1/messages';
+export class AnthropicBridge {
+    supportsStreaming = true;
+    _apiKey;
+    _model;
+    _apiVersion;
+    _systemPrompt;
+    _maxTokens;
+    _cacheSystem;
+    constructor(opts) {
+        this._apiKey = opts.apiKey;
+        this._model = opts.model ?? 'claude-haiku-4-5';
+        this._apiVersion = opts.apiVersion ?? '2023-06-01';
+        this._systemPrompt = opts.systemPrompt ?? '';
+        this._maxTokens = opts.maxTokens ?? 1024;
+        this._cacheSystem = opts.cacheSystem ?? true;
+    }
+    async generate(prompt, opts = {}) {
+        const body = this._buildBody(prompt, opts, false);
+        const res = await this._fetch(body);
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new SSMError('BRIDGE_REQUEST_FAILED', `Anthropic API returned ${res.status}: ${text}`);
+        }
+        const json = await res.json();
+        const content = json.content?.[0]?.text;
+        if (typeof content !== 'string') {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Unexpected Anthropic response shape.');
+        }
+        return content;
+    }
+    async *stream(prompt, opts = {}) {
+        const body = this._buildBody(prompt, opts, true);
+        const res = await this._fetch(body);
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new SSMError('BRIDGE_REQUEST_FAILED', `Anthropic streaming API returned ${res.status}: ${text}`);
+        }
+        if (!res.body) {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Anthropic streaming response has no body.');
+        }
+        yield* parseAnthropicStream(res.body);
+    }
+    _buildBody(prompt, opts, stream) {
+        const sys = opts.systemPrompt ?? this._systemPrompt;
+        const body = {
+            model: opts.model ?? this._model,
+            max_tokens: opts.maxTokens ?? this._maxTokens,
+            messages: [{ role: 'user', content: prompt }],
+        };
+        if (sys) {
+            // Caching is a prefix match: render the stable system prompt as a
+            // single cache-marked content block so reads on subsequent turns are
+            // billed at ~10% of input price. The volatile user message is sent
+            // unmarked after it, so it never enters the cached prefix.
+            body['system'] = this._cacheSystem
+                ? [{ type: 'text', text: sys, cache_control: { type: 'ephemeral' } }]
+                : sys;
+        }
+        if (stream)
+            body['stream'] = true;
+        return JSON.stringify(body);
+    }
+    _fetch(body) {
+        return fetch(API_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this._apiKey,
+                'anthropic-version': this._apiVersion,
+            },
+            body,
+        });
+    }
+}
+// ── SSE parser (Anthropic event format) ──────────────────────────────────────
+async function* parseAnthropicStream(body) {
+    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(); // 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);
+                    // content_block_delta events carry the streamed text
+                    if (event['type'] === 'content_block_delta') {
+                        const text = event.delta?.text;
+                        if (typeof text === 'string' && text.length > 0)
+                            yield text;
+                    }
+                }
+                catch {
+                    // Skip malformed SSE lines
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=AnthropicBridge.js.map

package/dist/bridges/AnthropicBridge.js.map

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

package/dist/bridges/CachingBridge.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CachingBridge – a read-through caching decorator for any TransformerBridge.
+ *
+ * Wraps an inner bridge and memoises `generate()` keyed on the full request
+ * shape (model, system, prompt, sampling). Identical completions are served
+ * from memory instead of re-billing the provider — the single most effective
+ * lever for cutting LLM spend on repeated prompts (distillation passes, retries,
+ * fan-out over duplicate inputs).
+ *
+ * Composes with every bridge, so the caching policy lives in one place rather
+ * than being reimplemented per provider:
+ *
+ *   const bridge = new CachingBridge(new AnthropicBridge({ apiKey }));
+ *
+ * Streaming is delegated straight through and never cached — a token stream is
+ * consumed once and caching it would defeat its purpose.
+ */
+import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+import { ResponseCache, type ResponseCacheOptions } from './ResponseCache.js';
+export interface CachingBridgeOptions extends ResponseCacheOptions {
+    /**
+     * Provide a shared ResponseCache instance instead of letting the bridge
+     * create its own. Use this to share one cache across multiple bridges, or
+     * to inspect/clear the cache from outside.
+     */
+    cache?: ResponseCache;
+}
+export declare class CachingBridge implements TransformerBridge {
+    private readonly _inner;
+    private readonly _cache;
+    constructor(inner: TransformerBridge, opts?: CachingBridgeOptions);
+    /** Mirrors the wrapped bridge so callers can still gate on streaming support. */
+    get supportsStreaming(): boolean;
+    /** The underlying cache — exposed for stats inspection and manual eviction. */
+    get cache(): ResponseCache;
+    generate(prompt: string, opts?: BridgeGenerateOptions): Promise<string>;
+    /**
+     * Streaming is delegated to the inner bridge unchanged and is never cached.
+     * Present only when the inner bridge supports it, so `supportsStreaming`
+     * stays an accurate gate.
+     */
+    stream(prompt: string, opts?: BridgeGenerateOptions): AsyncIterable<string>;
+}
+//# sourceMappingURL=CachingBridge.d.ts.map

package/dist/bridges/CachingBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachingBridge.d.ts","sourceRoot":"","sources":["../../src/bridges/CachingBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,EAAE,aAAa,EAAiB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE7F,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAC9D;;;;OAIG;IACH,KAAK,CAAC,EAAG,aAAa,CAAC;CAC1B;AAED,qBAAa,aAAc,YAAW,iBAAiB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAE5B,KAAK,EAAE,iBAAiB,EAAE,IAAI,GAAE,oBAAyB;IAKrE,iFAAiF;IACjF,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED,+EAA+E;IAC/E,IAAI,KAAK,IAAI,aAAa,CAEzB;IAEK,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBjF;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAAC,MAAM,CAAC;CAM9E"}