@seanhogg/builderforce-memory 2026.7.14 → 2026.9.28

package/src/bridges/CachingBridge.ts

@@ -16,7 +16,7 @@
  * consumed once and caching it would defeat its purpose.
  */
 
-import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
 import { ResponseCache, buildCacheKey, type ResponseCacheOptions } from './ResponseCache.js';
 
 export interface CachingBridgeOptions extends ResponseCacheOptions {
@@ -32,6 +32,8 @@ export class CachingBridge implements TransformerBridge {
     private readonly _inner : TransformerBridge;
     private readonly _cache : ResponseCache;
 
+    private _lastCall: BridgeCallInfo | undefined;
+
     constructor(inner: TransformerBridge, opts: CachingBridgeOptions = {}) {
         this._inner = inner;
         this._cache = opts.cache ?? new ResponseCache(opts);
@@ -47,6 +49,16 @@ export class CachingBridge implements TransformerBridge {
         return this._cache;
     }
 
+    /**
+     * A hit is declared here rather than inferred downstream, which is what turns
+     * the cache-hit rate into a measured metric. On a miss the inner bridge's own
+     * provider-reported usage is passed through unchanged, so decorating a bridge
+     * never downgrades its cost accounting to an estimate.
+     */
+    get lastCall(): BridgeCallInfo | undefined {
+        return this._lastCall;
+    }
+
     async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
         const key = buildCacheKey({
             prompt,
@@ -58,10 +70,24 @@ export class CachingBridge implements TransformerBridge {
         });
 
         const cached = this._cache.get(key);
-        if (cached !== undefined) return cached;
+        if (cached !== undefined) {
+            this._lastCall = {
+                cacheHit : true,
+                cacheTier: 'exact',
+                usage    : {
+                    model            : opts.model ?? 'unknown',
+                    inputTokens      : 0,
+                    outputTokens     : 0,
+                    localCacheHit    : true,
+                },
+            };
+            return cached;
+        }
 
         const value = await this._inner.generate(prompt, opts);
         this._cache.set(key, value, Date.now());
+        const inner = this._inner.lastCall;
+        this._lastCall = { cacheHit: false, ...(inner?.usage ? { usage: inner.usage } : {}) };
         return value;
     }
 

package/src/bridges/OpenAIBridge.ts

@@ -6,7 +6,8 @@
  */
 
 import { SSMError } from '../errors/SSMError.js';
-import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+import type { LlmUsage } from '../telemetry/types.js';
+import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
 
 export interface OpenAIBridgeOptions {
     /** OpenAI API key (or compatible service key). */
@@ -22,6 +23,8 @@ export interface OpenAIBridgeOptions {
 }
 
 export class OpenAIBridge implements TransformerBridge {
+    private _lastCall: BridgeCallInfo | undefined;
+
     readonly supportsStreaming = true as const;
 
     private readonly _apiKey      : string;
@@ -38,6 +41,11 @@ export class OpenAIBridge implements TransformerBridge {
         this._maxTokens    = opts.maxTokens    ?? 512;
     }
 
+    /** Provider-reported usage for the last call — see {@link BridgeCallInfo}. */
+    get lastCall(): BridgeCallInfo | undefined {
+        return this._lastCall;
+    }
+
     async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
         const body = this._buildBody(prompt, opts, false);
         const res  = await this._fetch(body);
@@ -55,6 +63,9 @@ export class OpenAIBridge implements TransformerBridge {
         if (typeof content !== 'string') {
             throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Unexpected OpenAI response shape.');
         }
+        this._lastCall = {
+            usage: readOpenAIUsage((json as any).usage, (json as any).model ?? opts.model ?? this._model),
+        };
         return content;
     }
 
@@ -74,7 +85,17 @@ export class OpenAIBridge implements TransformerBridge {
             throw new SSMError('BRIDGE_RESPONSE_INVALID', 'OpenAI streaming response has no body.');
         }
 
-        yield* parseOpenAIStream(res.body);
+        const model = opts.model ?? this._model;
+        let usage: LlmUsage | undefined;
+
+        yield* parseOpenAIStream(res.body, (event) => {
+            // 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);
+            if (reported) usage = reported;
+        });
+
+        this._lastCall = usage ? { usage } : {};
     }
 
     private _buildBody(prompt: string, opts: BridgeGenerateOptions, stream: boolean): string {
@@ -90,6 +111,10 @@ export class OpenAIBridge implements TransformerBridge {
             temperature: opts.temperature ?? 0.7,
             top_p      : opts.topP        ?? 0.9,
             stream,
+            // Without this the streaming response carries no usage block, so
+            // cost-per-request on streamed calls would silently fall back to an
+            // estimate. Non-streaming requests reject the field, hence the guard.
+            ...(stream ? { stream_options: { include_usage: true } } : {}),
         });
     }
 
@@ -107,7 +132,10 @@ export class OpenAIBridge implements TransformerBridge {
 
 // ── SSE parser ────────────────────────────────────────────────────────────────
 
-async function* parseOpenAIStream(body: ReadableStream<Uint8Array>): AsyncIterable<string> {
+async function* parseOpenAIStream(
+    body: ReadableStream<Uint8Array>,
+    onEvent?: (event: Record<string, unknown>) => void,
+): AsyncIterable<string> {
     const reader  = body.getReader();
     const decoder = new TextDecoder();
     let buffer    = '';
@@ -130,6 +158,7 @@ async function* parseOpenAIStream(body: ReadableStream<Uint8Array>): AsyncIterab
 
                 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 {
@@ -141,3 +170,19 @@ async function* parseOpenAIStream(body: ReadableStream<Uint8Array>): AsyncIterab
         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;
+    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,
+        cachedInputTokens: cached,
+    };
+}

package/src/bridges/SemanticCachingBridge.ts

@@ -12,7 +12,7 @@
  * Streaming is delegated straight through and never cached.
  */
 
-import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
 import { SemanticCache, type SemanticCacheOptions } from '../cache/SemanticCache.js';
 
 export interface SemanticCachingBridgeOptions extends Omit<SemanticCacheOptions, never> {
@@ -24,6 +24,8 @@ export class SemanticCachingBridge implements TransformerBridge {
     private readonly _inner : TransformerBridge;
     private readonly _cache : SemanticCache;
 
+    private _lastCall: BridgeCallInfo | undefined;
+
     constructor(inner: TransformerBridge, opts: SemanticCachingBridgeOptions) {
         this._inner = inner;
         this._cache = opts.cache ?? new SemanticCache(opts);
@@ -38,15 +40,40 @@ export class SemanticCachingBridge implements TransformerBridge {
         return this._cache;
     }
 
+    /**
+     * Reports which tier answered (`l1` local vector scan, `l2` shared backend, or
+     * a miss), so the saving from paraphrase reuse is attributable per tier rather
+     * than lumped into one "cache" number.
+     */
+    get lastCall(): BridgeCallInfo | undefined {
+        return this._lastCall;
+    }
+
     async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
         // Match on system + prompt meaning so different system contexts don't
         // cross-hit; partition further by model via the stored meta.
         const queryText = opts.systemPrompt ? `${opts.systemPrompt}\n${prompt}` : prompt;
-        const { response } = await this._cache.getOrGenerate(
+        const { response, cached, tier } = await this._cache.getOrGenerate(
             queryText,
             () => this._inner.generate(prompt, opts),
             opts.model ? { model: opts.model } : undefined,
         );
+
+        if (cached) {
+            this._lastCall = {
+                cacheHit : true,
+                ...(tier ? { cacheTier: tier } : {}),
+                usage    : {
+                    model        : opts.model ?? 'unknown',
+                    inputTokens  : 0,
+                    outputTokens : 0,
+                    localCacheHit: true,
+                },
+            };
+        } else {
+            const inner = this._inner.lastCall;
+            this._lastCall = { cacheHit: false, ...(inner?.usage ? { usage: inner.usage } : {}) };
+        }
         return response;
     }
 

package/src/bridges/TransformerBridge.ts

@@ -7,6 +7,10 @@
  * shape works, no base class required.
  */
 
+import type { BridgeCallInfo } from '../telemetry/types.js';
+
+export type { BridgeCallInfo };
+
 export interface BridgeGenerateOptions {
     /** Max tokens to generate. Default per-adapter (typically 512). */
     maxTokens?    : number;
@@ -27,6 +31,18 @@ export interface TransformerBridge {
      */
     generate(prompt: string, opts?: BridgeGenerateOptions): Promise<string>;
 
+    /**
+     * Usage and cache outcome of the most recent `generate()`/`stream()`.
+     *
+     * Optional so third-party bridges stay valid, but every bridge in this package
+     * populates it: it is what lets `InstrumentedBridge` report *provider-measured*
+     * tokens and cost instead of a character-count estimate, and what lets the
+     * caching decorators declare a hit so the cache-hit rate is a fact rather than
+     * an inference. Not concurrency-safe by design — read it immediately after the
+     * call, or use `InstrumentedBridge`, which does.
+     */
+    readonly lastCall?: BridgeCallInfo;
+
     /**
      * Streaming variant — yields tokens incrementally.
      * Check `supportsStreaming` before calling.

package/src/bridges/VertexAIBridge.ts

@@ -0,0 +1,297 @@
+/**
+ * VertexAIBridge — TransformerBridge for Google Cloud Vertex AI.
+ *
+ * GCP is where a large share of enterprise AI actually runs, usually because the
+ * customer's data already lives in BigQuery and Cloud Storage and moving it is a
+ * procurement problem, not a technical one. This bridge lets Evermind serve those
+ * deployments without changing anything above the port.
+ *
+ * Two deliberate choices:
+ *
+ *   • **Auth is injected, never owned.** `getAccessToken` is supplied by the
+ *     caller, which is what lets the same code run under Application Default
+ *     Credentials locally, a Workload Identity service account on GKE, and an
+ *     impersonated token in CI — and keeps this package free of the Google auth
+ *     library (and of any credential lifecycle it has no business managing).
+ *   • **Raw HTTP, like every other bridge here.** The package is zero-dependency
+ *     and runs in a browser, a Worker and Node; adding a Node-only vendor SDK to
+ *     one bridge would cost that portability for the whole package.
+ *
+ * Usage is reported from `usageMetadata`, so cost accounting on Vertex is measured
+ * rather than estimated — with the caveat that Vertex is partner-billed at rates
+ * that differ from the first-party API, so supply a matching `PriceBook`.
+ */
+
+import { SSMError } from '../errors/SSMError.js';
+import type { LlmUsage } from '../telemetry/types.js';
+import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
+
+export interface VertexAIBridgeOptions {
+    /** GCP project id. */
+    projectId: string;
+    /** Region, or `'global'`. Default `'us-central1'`. */
+    location?: string;
+    /**
+     * Publisher model id, e.g. `'gemini-2.5-pro'`, or a Claude model served through
+     * Vertex. Default `'gemini-2.5-flash'`.
+     */
+    model?: string;
+    /** Publisher owning the model. Default `'google'`; use `'anthropic'` for Claude. */
+    publisher?: string;
+    /**
+     * Returns a current OAuth access token. Called per request, so the caller's
+     * token source owns caching and refresh.
+     */
+    getAccessToken: () => Promise<string> | string;
+    systemPrompt?: string;
+    maxTokens?: number;
+    /** Override the API host — for a private endpoint or a test double. */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+
+export class VertexAIBridge implements TransformerBridge {
+    readonly supportsStreaming = true as const;
+
+    private readonly _projectId: string;
+    private readonly _location: string;
+    private readonly _model: string;
+    private readonly _publisher: string;
+    private readonly _getToken: () => Promise<string> | string;
+    private readonly _systemPrompt: string;
+    private readonly _maxTokens: number;
+    private readonly _baseUrl: string;
+    private readonly _fetch: typeof fetch;
+
+    private _lastCall: BridgeCallInfo | undefined;
+
+    constructor(opts: VertexAIBridgeOptions) {
+        this._projectId = opts.projectId;
+        this._location = opts.location ?? 'us-central1';
+        this._model = opts.model ?? 'gemini-2.5-flash';
+        this._publisher = opts.publisher ?? 'google';
+        this._getToken = opts.getAccessToken;
+        this._systemPrompt = opts.systemPrompt ?? '';
+        this._maxTokens = opts.maxTokens ?? 1024;
+        this._baseUrl = opts.baseUrl ?? defaultHost(this._location);
+        this._fetch = opts.fetchImpl ?? ((...args) => fetch(...args));
+    }
+
+    get lastCall(): BridgeCallInfo | undefined {
+        return this._lastCall;
+    }
+
+    async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
+        const res = await this._send(prompt, opts, false);
+        const json = await res.json() as Record<string, unknown>;
+
+        const text = readCandidateText(json);
+        if (text === undefined) {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Unexpected Vertex AI response shape.');
+        }
+
+        this._lastCall = { usage: readVertexUsage(json['usageMetadata'], opts.model ?? this._model) };
+        return text;
+    }
+
+    async *stream(prompt: string, opts: BridgeGenerateOptions = {}): AsyncIterable<string> {
+        const res = await this._send(prompt, opts, true);
+        if (!res.body) {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Vertex AI streaming response has no body.');
+        }
+
+        let usage: LlmUsage | undefined;
+        for await (const event of parseSseJson(res.body)) {
+            const text = readCandidateText(event);
+            if (text) yield text;
+            // Vertex repeats cumulative usage on each chunk; the last one wins.
+            const reported = readVertexUsage(event['usageMetadata'], opts.model ?? this._model);
+            if (reported) usage = reported;
+        }
+        this._lastCall = usage ? { usage } : {};
+    }
+
+    private async _send(prompt: string, opts: BridgeGenerateOptions, stream: boolean): Promise<Response> {
+        const model = opts.model ?? this._model;
+        const method = stream ? 'streamGenerateContent?alt=sse' : 'generateContent';
+        const url =
+            `${this._baseUrl}/v1/projects/${this._projectId}/locations/${this._location}` +
+            `/publishers/${this._publisher}/models/${model}:${method}`;
+
+        const system = opts.systemPrompt ?? this._systemPrompt;
+        const body: Record<string, unknown> = {
+            contents: [{ role: 'user', parts: [{ text: prompt }] }],
+            generationConfig: {
+                maxOutputTokens: opts.maxTokens ?? this._maxTokens,
+                temperature: opts.temperature ?? 0.7,
+                topP: opts.topP ?? 0.9,
+            },
+        };
+        if (system) body['systemInstruction'] = { parts: [{ text: system }] };
+
+        const token = await this._getToken();
+        const res = await this._fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${token}`,
+            },
+            body: JSON.stringify(body),
+        });
+
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new SSMError(
+                'BRIDGE_REQUEST_FAILED',
+                `Vertex AI returned ${res.status}: ${detail}`,
+            );
+        }
+        return res;
+    }
+}
+
+/**
+ * Vertex AI text embeddings — the `:predict` surface on a publisher model.
+ *
+ * Exposed as a {@link BatchEmbedder}-shaped function so it drops straight into the
+ * ingestion pipeline: on GCP the embedder, the vector index and the generator can
+ * all be Vertex, and nothing above the ports changes.
+ */
+export interface VertexAIEmbedderOptions {
+    projectId: string;
+    location?: string;
+    /** Embedding model. Default `'text-embedding-005'`. */
+    model?: string;
+    getAccessToken: () => Promise<string> | string;
+    /**
+     * Task type hint. `RETRIEVAL_DOCUMENT` when indexing, `RETRIEVAL_QUERY` when
+     * searching — using the same hint for both measurably degrades recall, because
+     * the model embeds questions and passages into deliberately different regions.
+     */
+    taskType?: 'RETRIEVAL_DOCUMENT' | 'RETRIEVAL_QUERY' | 'SEMANTIC_SIMILARITY' | 'CLASSIFICATION';
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+
+export class VertexAIEmbedder {
+    private readonly _projectId: string;
+    private readonly _location: string;
+    private readonly _model: string;
+    private readonly _getToken: () => Promise<string> | string;
+    private readonly _taskType: string | undefined;
+    private readonly _baseUrl: string;
+    private readonly _fetch: typeof fetch;
+
+    constructor(opts: VertexAIEmbedderOptions) {
+        this._projectId = opts.projectId;
+        this._location = opts.location ?? 'us-central1';
+        this._model = opts.model ?? 'text-embedding-005';
+        this._getToken = opts.getAccessToken;
+        this._taskType = opts.taskType;
+        this._baseUrl = opts.baseUrl ?? defaultHost(this._location);
+        this._fetch = opts.fetchImpl ?? ((...args) => fetch(...args));
+    }
+
+    /** Embeds a batch. Shape matches `BatchEmbedder`, for the ingestion pipeline. */
+    embedBatch = async (texts: string[]): Promise<Float32Array[]> => {
+        if (texts.length === 0) return [];
+
+        const url =
+            `${this._baseUrl}/v1/projects/${this._projectId}/locations/${this._location}` +
+            `/publishers/google/models/${this._model}:predict`;
+
+        const token = await this._getToken();
+        const res = await this._fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+            body: JSON.stringify({
+                instances: texts.map((content) => ({
+                    content,
+                    ...(this._taskType ? { task_type: this._taskType } : {}),
+                })),
+            }),
+        });
+
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new SSMError('BRIDGE_REQUEST_FAILED', `Vertex AI embeddings returned ${res.status}: ${detail}`);
+        }
+
+        const json = await res.json() as { predictions?: Array<{ embeddings?: { values?: number[] } }> };
+        const predictions = json.predictions ?? [];
+        if (predictions.length !== texts.length) {
+            // A short batch would silently misalign vectors with their chunks — the
+            // worst kind of RAG bug, because retrieval still "works" and is wrong.
+            throw new SSMError(
+                'BRIDGE_RESPONSE_INVALID',
+                `Vertex AI returned ${predictions.length} embeddings for ${texts.length} inputs.`,
+            );
+        }
+        return predictions.map((p) => Float32Array.from(p.embeddings?.values ?? []));
+    };
+
+    /** Single-text convenience, for the retriever's query embedding. */
+    embed = async (text: string): Promise<Float32Array> => {
+        const [vector] = await this.embedBatch([text]);
+        return vector ?? new Float32Array();
+    };
+}
+
+function defaultHost(location: string): string {
+    return location === 'global'
+        ? 'https://aiplatform.googleapis.com'
+        : `https://${location}-aiplatform.googleapis.com`;
+}
+
+function readCandidateText(json: Record<string, unknown>): string | undefined {
+    const candidates = json['candidates'];
+    if (!Array.isArray(candidates) || candidates.length === 0) return undefined;
+    const parts = (candidates[0] as { content?: { parts?: Array<{ text?: string }> } }).content?.parts;
+    if (!Array.isArray(parts)) return undefined;
+    // Multi-part responses are concatenated; taking only parts[0] silently truncates.
+    return parts.map((p) => p.text ?? '').join('');
+}
+
+function readVertexUsage(usage: unknown, model: string): LlmUsage | undefined {
+    if (!usage || typeof usage !== 'object') return undefined;
+    const u = usage as Record<string, unknown>;
+    const cached = Number(u['cachedContentTokenCount']) || 0;
+    const prompt = Number(u['promptTokenCount']) || 0;
+    return {
+        model,
+        inputTokens: Math.max(0, prompt - cached),
+        outputTokens: Number(u['candidatesTokenCount']) || 0,
+        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();
+    }
+}

package/src/bridges/index.ts

@@ -1,13 +1,15 @@
-export type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+export type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
 export { OpenAIBridge }    from './OpenAIBridge.js';
 export { AnthropicBridge } from './AnthropicBridge.js';
 export { FetchBridge }     from './FetchBridge.js';
 export { CachingBridge }   from './CachingBridge.js';
 export { SemanticCachingBridge } from './SemanticCachingBridge.js';
+export { VertexAIBridge, VertexAIEmbedder } from './VertexAIBridge.js';
 export { ResponseCache, buildCacheKey } from './ResponseCache.js';
 export type { OpenAIBridgeOptions }    from './OpenAIBridge.js';
 export type { AnthropicBridgeOptions } from './AnthropicBridge.js';
 export type { FetchBridgeOptions }     from './FetchBridge.js';
 export type { CachingBridgeOptions }   from './CachingBridge.js';
 export type { SemanticCachingBridgeOptions } from './SemanticCachingBridge.js';
+export type { VertexAIBridgeOptions, VertexAIEmbedderOptions } from './VertexAIBridge.js';
 export type { ResponseCacheOptions }   from './ResponseCache.js';