gavio 0.1.0 → 0.3.0

package/dist/esm/gateway.js

@@ -4,6 +4,7 @@ import { ConfigurationError } from './errors.js';
 import { auditInterceptor, isAuditInterceptor } from './interceptors/audit/index.js';
 import { isExecutorPolicy } from './interceptors/base.js';
 import { InterceptorChain } from './interceptors/chain.js';
+import { StreamBuffer } from './interceptors/reliability/stream-buffer.js';
 import { PricingProvider } from './pricing.js';
 import { buildAdapter } from './providers/index.js';
 import { mockProvider } from './providers/mock.js';
@@ -37,6 +38,15 @@ export class Gateway {
         this.dryRunMode = options.dryRun ?? false;
         this.pricing = options.pricing ?? new PricingProvider();
     }
+    /**
+     * Build a Gateway from a config object or a JSON file path (F-DX-05).
+     * Async so the config module loads lazily (avoids a circular import).
+     */
+    static async fromConfig(config) {
+        const mod = await import('./config.js');
+        const data = typeof config === 'string' ? mod.loadConfig(config) : config;
+        return mod.buildFromConfig(data);
+    }
     /** Register an interceptor or executor policy. First-registered = outermost. */
     use(interceptor) {
         this.interceptors.push(interceptor);
@@ -65,6 +75,7 @@ export class Gateway {
             sessionId: opts.sessionId ?? null,
             options: opts.options ?? {},
             metadata: opts.metadata ?? {},
+            lineage: opts.lineage ?? null,
         });
         const ctx = new InterceptorContext({
             traceId: request.traceId,
@@ -76,6 +87,50 @@ export class Gateway {
         const { chain, executor } = this.buildPipeline(adapter, ctx);
         return chain.execute(request, ctx, executor);
     }
+    /**
+     * Stream a completion, buffering the provider stream (F-REL-06).
+     *
+     * The provider stream is buffered in full so the post-interceptor pipeline
+     * (guardrails, PII restore, audit) runs on the complete response before any
+     * chunk reaches the caller. Pre/post interceptors run via the chain; executor
+     * policies (retry, circuit breaker, cache) are not applied to the streaming
+     * path.
+     */
+    async *stream(opts) {
+        const adapter = this.resolveAdapter();
+        if (adapter.stream === undefined || adapter.buildStreamResponse === undefined) {
+            throw new ConfigurationError(`${adapter.providerName} does not support streaming`);
+        }
+        const model = opts.model ?? this.modelHint ?? this.resolveModel(adapter);
+        const request = new GavioRequest({
+            messages: opts.messages,
+            model,
+            provider: coerceProvider(adapter.providerName),
+            agentId: opts.agentId ?? null,
+            parentTraceId: opts.parentTraceId ?? null,
+            sessionId: opts.sessionId ?? null,
+            options: opts.options ?? {},
+            metadata: opts.metadata ?? {},
+        });
+        const ctx = new InterceptorContext({
+            traceId: request.traceId,
+            agentId: request.agentId,
+            parentTraceId: request.parentTraceId,
+            sessionId: request.sessionId,
+            dryRun: this.dryRunMode,
+        });
+        const startedAt = performance.now();
+        const buffer = new StreamBuffer();
+        const { chain } = this.buildPipeline(adapter, ctx);
+        const bufferingExecutor = async (req) => {
+            for await (const chunk of adapter.stream(req))
+                buffer.append(chunk);
+            return adapter.buildStreamResponse(req, buffer.text(), startedAt);
+        };
+        const response = await chain.execute(request, ctx, bufferingExecutor);
+        // Post-interceptors have run on the fully buffered response; emit it now.
+        yield response.content;
+    }
     async healthCheck() {
         return this.resolveAdapter().healthCheck();
     }

package/dist/esm/index.d.ts

@@ -7,7 +7,7 @@
  *
  * See https://gavio.io for documentation. MIT licensed.
  */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.3.0";
 export { Gateway } from './gateway.js';
 export type { GatewayOptions, CompleteOptions } from './gateway.js';
 export { GavioRequest } from './request.js';
@@ -18,8 +18,8 @@ export { InterceptorContext } from './context.js';
 export type { InterceptorContextInit } from './context.js';
 export { uuid7, newTraceId } from './ids.js';
 export { PricingProvider, estimateTokens } from './pricing.js';
-export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, coerceProvider, } from './types.js';
-export type { Message } from './types.js';
+export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, PromptLineage, RagChunk, coerceProvider, } from './types.js';
+export type { Message, PromptLineageInit, RagChunkInit } from './types.js';
 export type { Interceptor, Executor, ExecutorPolicy } from './interceptors/base.js';
 export { InterceptorChain } from './interceptors/chain.js';
 export { GavioError, ConfigurationError, ProviderError, ProviderUnavailableError, RateLimitError, ServerError, TimeoutError, PiiBlockedError, BudgetExceededError, GuardrailViolationError, } from './errors.js';

package/dist/esm/index.js

@@ -7,14 +7,14 @@
  *
  * See https://gavio.io for documentation. MIT licensed.
  */
-export const VERSION = '0.1.0';
+export const VERSION = '0.3.0';
 export { Gateway } from './gateway.js';
 export { GavioRequest } from './request.js';
 export { GavioResponse } from './response.js';
 export { InterceptorContext } from './context.js';
 export { uuid7, newTraceId } from './ids.js';
 export { PricingProvider, estimateTokens } from './pricing.js';
-export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, coerceProvider, } from './types.js';
+export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, PromptLineage, RagChunk, coerceProvider, } from './types.js';
 export { InterceptorChain } from './interceptors/chain.js';
 // errors
 export { GavioError, ConfigurationError, ProviderError, ProviderUnavailableError, RateLimitError, ServerError, TimeoutError, PiiBlockedError, BudgetExceededError, GuardrailViolationError, } from './errors.js';

package/dist/esm/interceptors/audit/index.d.ts

@@ -5,3 +5,5 @@ export type { AuditRecordInit } from './record.js';
 export type { AuditSink } from './sink.js';
 export { stdoutSink } from './sinks/stdout.js';
 export type { StdoutSinkOptions } from './sinks/stdout.js';
+export { verifyChain, buildCallGraph } from './trace.js';
+export type { TraceNode } from './trace.js';

package/dist/esm/interceptors/audit/index.js

@@ -1,3 +1,4 @@
 export { auditInterceptor, isAuditInterceptor, AUDIT_NAME } from './interceptor.js';
 export { AuditRecord, SCHEMA_VERSION } from './record.js';
 export { stdoutSink } from './sinks/stdout.js';
+export { verifyChain, buildCallGraph } from './trace.js';

package/dist/esm/interceptors/audit/interceptor.d.ts

@@ -4,6 +4,8 @@ import type { AuditSink } from './sink.js';
 export declare const AUDIT_NAME = "audit";
 export interface AuditInterceptorOptions {
     sink?: AuditSink | 'stdout';
+    /** F-OBS-02: link each record via previousHash into a tamper-evident chain. */
+    hashChain?: boolean;
 }
 /** Factory: build an audit interceptor. */
 export declare function auditInterceptor(options?: AuditInterceptorOptions): Interceptor;

package/dist/esm/interceptors/audit/interceptor.js

@@ -2,6 +2,7 @@
 import { AuditRecord } from './record.js';
 import { stdoutSink } from './sinks/stdout.js';
 const PROMPT_HASH_KEY = 'audit_prompt_hash';
+const LINEAGE_KEY = 'audit_lineage';
 export const AUDIT_NAME = 'audit';
 /**
  * Build an AuditRecord per request and write it to a sink.
@@ -15,11 +16,16 @@ class AuditInterceptor {
     name = AUDIT_NAME;
     dryRunSafe = true; // auditing is observation-only, so it always runs
     sink;
+    hashChain;
+    lastHash = '';
     constructor(options = {}) {
         this.sink = resolveSink(options.sink);
+        this.hashChain = options.hashChain ?? false;
     }
     async before(request, ctx) {
         ctx.state[PROMPT_HASH_KEY] = AuditRecord.hashText(request.promptText());
+        if (request.lineage != null)
+            ctx.state[LINEAGE_KEY] = request.lineage;
         return request;
     }
     async after(response, ctx) {
@@ -44,7 +50,12 @@ class AuditInterceptor {
             cacheType: response.cacheType,
             guardrailOutcome: ctx.guardrailOutcome,
             riskScore: ctx.riskScore,
+            lineage: ctx.state[LINEAGE_KEY] ?? null,
         });
+        if (this.hashChain) {
+            record.previousHash = this.lastHash;
+            this.lastHash = record.contentHash();
+        }
         response.audit = record;
         try {
             await this.sink.write(record);

package/dist/esm/interceptors/audit/record.d.ts

@@ -1,5 +1,5 @@
 /** AuditRecord — the immutable, per-request audit entry. */
-import { TokenUsage } from '../../types.js';
+import { PromptLineage, TokenUsage } from '../../types.js';
 export declare const SCHEMA_VERSION = "1.0";
 export interface AuditRecordInit {
     traceId: string;
@@ -22,6 +22,7 @@ export interface AuditRecordInit {
     cacheType?: string | null;
     guardrailOutcome?: string | null;
     riskScore?: number | null;
+    lineage?: PromptLineage | null;
     previousHash?: string;
     schemaVersion?: string;
 }
@@ -53,13 +54,14 @@ export declare class AuditRecord {
     cacheType: string | null;
     guardrailOutcome: string | null;
     riskScore: number | null;
+    lineage: PromptLineage | null;
     previousHash: string;
     schemaVersion: string;
     constructor(init: AuditRecordInit);
     static nowUtc(): string;
     static hashText(text: string): string;
     toJSON(): Record<string, unknown>;
-    /** Stable JSON with sorted keys — used for the v0.2.0 hash chain. */
+    /** Stable JSON with recursively sorted keys — used for the v0.2.0 hash chain. */
     toCanonicalJson(): string;
     /** Hash of this record's content — used to build the v0.2.0 chain. */
     contentHash(): string;

package/dist/esm/interceptors/audit/record.js

@@ -1,10 +1,22 @@
 /** AuditRecord — the immutable, per-request audit entry. */
 import { createHash } from 'node:crypto';
-import { TokenUsage } from '../../types.js';
+import { PromptLineage, TokenUsage } from '../../types.js';
 export const SCHEMA_VERSION = '1.0';
 function sha256(text) {
     return createHash('sha256').update(text, 'utf-8').digest('hex');
 }
+/** Deterministic JSON with keys sorted at every nesting level. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const parts = Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return `{${parts.join(',')}}`;
+}
 /**
  * One append-only audit entry. Carries metadata only — never raw content.
  *
@@ -33,6 +45,7 @@ export class AuditRecord {
     cacheType;
     guardrailOutcome;
     riskScore;
+    lineage;
     previousHash;
     schemaVersion;
     constructor(init) {
@@ -56,6 +69,7 @@ export class AuditRecord {
         this.cacheType = init.cacheType ?? null;
         this.guardrailOutcome = init.guardrailOutcome ?? null;
         this.riskScore = init.riskScore ?? null;
+        this.lineage = init.lineage ?? null;
         this.previousHash = init.previousHash ?? '';
         this.schemaVersion = init.schemaVersion ?? SCHEMA_VERSION;
     }
@@ -87,14 +101,14 @@ export class AuditRecord {
             cacheType: this.cacheType,
             guardrailOutcome: this.guardrailOutcome,
             riskScore: this.riskScore,
+            lineage: this.lineage ? this.lineage.toJSON() : null,
             previousHash: this.previousHash,
             schemaVersion: this.schemaVersion,
         };
     }
-    /** Stable JSON with sorted keys — used for the v0.2.0 hash chain. */
+    /** Stable JSON with recursively sorted keys — used for the v0.2.0 hash chain. */
     toCanonicalJson() {
-        const data = this.toJSON();
-        return JSON.stringify(data, Object.keys(data).sort());
+        return stableStringify(this.toJSON());
     }
     /** Hash of this record's content — used to build the v0.2.0 chain. */
     contentHash() {

package/dist/esm/interceptors/audit/trace.d.ts

@@ -0,0 +1,19 @@
+/** Audit-chain verification (F-OBS-02) and multi-agent DAG trace (F-OBS-03). */
+import type { AuditRecord } from './record.js';
+/**
+ * Return true if the records form an intact hash chain. Each record's
+ * previousHash must equal the content hash of the record before it; the first
+ * must be empty. Any edit, reorder, or deletion breaks the chain.
+ */
+export declare function verifyChain(records: AuditRecord[]): boolean;
+export interface TraceNode {
+    traceId: string;
+    agentId: string | null;
+    parentTraceId: string | null;
+    children: TraceNode[];
+}
+/**
+ * Reconstruct the multi-agent DAG from audit records using parentTraceId +
+ * traceId. Returns the root nodes (those with no known parent).
+ */
+export declare function buildCallGraph(records: AuditRecord[]): TraceNode[];

package/dist/esm/interceptors/audit/trace.js

@@ -0,0 +1,39 @@
+/** Audit-chain verification (F-OBS-02) and multi-agent DAG trace (F-OBS-03). */
+/**
+ * Return true if the records form an intact hash chain. Each record's
+ * previousHash must equal the content hash of the record before it; the first
+ * must be empty. Any edit, reorder, or deletion breaks the chain.
+ */
+export function verifyChain(records) {
+    let prevHash = '';
+    for (const rec of records) {
+        if (rec.previousHash !== prevHash)
+            return false;
+        prevHash = rec.contentHash();
+    }
+    return true;
+}
+/**
+ * Reconstruct the multi-agent DAG from audit records using parentTraceId +
+ * traceId. Returns the root nodes (those with no known parent).
+ */
+export function buildCallGraph(records) {
+    const nodes = new Map();
+    for (const rec of records) {
+        nodes.set(rec.traceId, {
+            traceId: rec.traceId,
+            agentId: rec.agentId,
+            parentTraceId: rec.parentTraceId,
+            children: [],
+        });
+    }
+    const roots = [];
+    for (const node of nodes.values()) {
+        const parent = node.parentTraceId ? nodes.get(node.parentTraceId) : undefined;
+        if (parent)
+            parent.children.push(node);
+        else
+            roots.push(node);
+    }
+    return roots;
+}

package/dist/esm/interceptors/cache/embedding.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Embeddings for the semantic cache (F-CACHE-02).
+ *
+ * Zero-dependency hashed bag-of-words embedder (L2-normalised) — good enough to
+ * dedup near-identical prompts. Plug in a real embedder implementing `Embedder`
+ * for production semantic matching.
+ */
+export interface Embedder {
+    embed(text: string): number[];
+}
+/** Deterministic hashed bag-of-words embedder. */
+export declare function hashingEmbedder(dim?: number): Embedder;
+/** Cosine similarity; safe for zero vectors. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;

package/dist/esm/interceptors/cache/embedding.js

@@ -0,0 +1,49 @@
+/**
+ * Embeddings for the semantic cache (F-CACHE-02).
+ *
+ * Zero-dependency hashed bag-of-words embedder (L2-normalised) — good enough to
+ * dedup near-identical prompts. Plug in a real embedder implementing `Embedder`
+ * for production semantic matching.
+ */
+import { createHash } from 'node:crypto';
+const TOKEN = /[a-z0-9]+/g;
+/** Deterministic hashed bag-of-words embedder. */
+export function hashingEmbedder(dim = 256) {
+    return {
+        embed(text) {
+            const vec = new Array(dim).fill(0);
+            const tokens = text.toLowerCase().match(TOKEN) ?? [];
+            for (const token of tokens) {
+                // Parity note: Python uses blake2b(digest_size=8); here we take the
+                // first 8 bytes of blake2b512. Both are deterministic; the JS cache is
+                // per-process so cross-language byte-parity is not required.
+                const digest = createHash('blake2b512').update(token).digest();
+                let n = 0n;
+                for (let i = 0; i < 8; i++)
+                    n = (n << 8n) | BigInt(digest[i]);
+                const bucket = Number(n % BigInt(dim));
+                vec[bucket] += 1;
+            }
+            const norm = Math.sqrt(vec.reduce((s, x) => s + x * x, 0));
+            if (norm === 0)
+                return vec;
+            return vec.map((x) => x / norm);
+        },
+    };
+}
+/** Cosine similarity; safe for zero vectors. */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        throw new Error('vectors must have equal length');
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}

package/dist/esm/interceptors/cache/index.d.ts

@@ -1,7 +1,10 @@
-/**
- * Caching substrate. The SemanticCache interceptor ships in v0.2.0; v0.1.0
- * exposes the CacheBackend interface and the in-memory backend only.
- */
+/** Caching (F-CACHE-01 exact, F-CACHE-02 semantic, F-CACHE-03 in-memory). */
 export type { CacheBackend } from './backend.js';
 export { memoryCacheBackend } from './backends/memory.js';
 export type { MemoryCacheBackendOptions } from './backends/memory.js';
+export { semanticCache } from './interceptor.js';
+export type { SemanticCacheOptions } from './interceptor.js';
+export { hashingEmbedder, cosineSimilarity } from './embedding.js';
+export type { Embedder } from './embedding.js';
+export { inMemoryVectorBackend } from './vector.js';
+export type { VectorBackend } from './vector.js';

package/dist/esm/interceptors/cache/index.js

@@ -1,5 +1,5 @@
-/**
- * Caching substrate. The SemanticCache interceptor ships in v0.2.0; v0.1.0
- * exposes the CacheBackend interface and the in-memory backend only.
- */
+/** Caching (F-CACHE-01 exact, F-CACHE-02 semantic, F-CACHE-03 in-memory). */
 export { memoryCacheBackend } from './backends/memory.js';
+export { semanticCache } from './interceptor.js';
+export { hashingEmbedder, cosineSimilarity } from './embedding.js';
+export { inMemoryVectorBackend } from './vector.js';

package/dist/esm/interceptors/cache/interceptor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * semanticCache (F-CACHE-01, F-CACHE-02) — two-level cache as an ExecutorPolicy.
+ *
+ * Exact SHA-256 cache, then optional semantic cosine cache; a hit returns the
+ * cached response and skips the provider. Register outermost.
+ */
+import type { ExecutorPolicy } from '../base.js';
+import type { CacheBackend } from './backend.js';
+import type { Embedder } from './embedding.js';
+import { type VectorBackend } from './vector.js';
+export interface SemanticCacheOptions {
+    backend?: CacheBackend;
+    embedder?: Embedder;
+    vectorBackend?: VectorBackend;
+    exactTtlSeconds?: number;
+    semanticTtlSeconds?: number;
+    similarityThreshold?: number;
+}
+export declare function semanticCache(options?: SemanticCacheOptions): ExecutorPolicy;

package/dist/esm/interceptors/cache/interceptor.js

@@ -0,0 +1,77 @@
+/**
+ * semanticCache (F-CACHE-01, F-CACHE-02) — two-level cache as an ExecutorPolicy.
+ *
+ * Exact SHA-256 cache, then optional semantic cosine cache; a hit returns the
+ * cached response and skips the provider. Register outermost.
+ */
+import { createHash } from 'node:crypto';
+import { GavioResponse } from '../../response.js';
+import { CacheType, TokenUsage } from '../../types.js';
+import { memoryCacheBackend } from './backends/memory.js';
+import { inMemoryVectorBackend } from './vector.js';
+export function semanticCache(options = {}) {
+    const backend = options.backend ?? memoryCacheBackend();
+    const embedder = options.embedder;
+    const semantic = embedder != null;
+    const vector = options.vectorBackend ?? (semantic ? inMemoryVectorBackend() : null);
+    const exactTtl = options.exactTtlSeconds ?? 3600;
+    const semanticTtl = options.semanticTtlSeconds ?? 86400;
+    const threshold = options.similarityThreshold ?? 0.95;
+    function exactKey(request) {
+        const opts = request.options ?? {};
+        const sorted = {};
+        for (const k of Object.keys(opts).sort())
+            sorted[k] = opts[k];
+        const payload = JSON.stringify({
+            provider: String(request.provider),
+            model: request.model,
+            messages: request.messages,
+            options: sorted,
+        });
+        return 'gavio:exact:' + createHash('sha256').update(payload).digest('hex');
+    }
+    function hit(request, ctx, entry, type) {
+        ctx.cacheHit = true;
+        ctx.cacheType = type;
+        return new GavioResponse({
+            traceId: request.traceId,
+            content: entry.content,
+            model: request.model,
+            provider: String(request.provider),
+            modelVersion: entry.modelVersion,
+            usage: new TokenUsage(entry.promptTokens, entry.completionTokens),
+            costUsd: 0,
+            cacheHit: true,
+            cacheType: type,
+        });
+    }
+    return {
+        name: 'semantic_cache',
+        isExecutorPolicy: true,
+        async around(request, ctx, callNext) {
+            ctx.markFired('semantic_cache');
+            const key = exactKey(request);
+            const cached = (await backend.get(key));
+            if (cached)
+                return hit(request, ctx, cached, CacheType.EXACT);
+            let embedding = null;
+            if (semantic && vector && embedder) {
+                embedding = embedder.embed(request.promptText());
+                const semHit = (await vector.query(embedding, threshold));
+                if (semHit)
+                    return hit(request, ctx, semHit, CacheType.SEMANTIC);
+            }
+            const response = await callNext(request);
+            const entry = {
+                content: response.content,
+                modelVersion: response.modelVersion,
+                promptTokens: response.usage.promptTokens,
+                completionTokens: response.usage.completionTokens,
+            };
+            await backend.set(key, entry, exactTtl);
+            if (embedding && vector)
+                await vector.add(embedding, entry, semanticTtl);
+            return response;
+        },
+    };
+}

package/dist/esm/interceptors/cache/vector.d.ts

@@ -0,0 +1,9 @@
+/** VectorBackend — nearest-neighbour store for the semantic cache (F-CACHE-02). */
+export interface VectorBackend {
+    add(vector: number[], value: unknown, ttlSeconds?: number | null): Promise<void>;
+    /** Return the value of the nearest entry with similarity >= threshold. */
+    query(vector: number[], threshold: number): Promise<unknown | null>;
+    clear(): Promise<void>;
+}
+/** Bounded, brute-force in-memory vector store (default dev backend). */
+export declare function inMemoryVectorBackend(maxSize?: number): VectorBackend;

package/dist/esm/interceptors/cache/vector.js

@@ -0,0 +1,32 @@
+/** VectorBackend — nearest-neighbour store for the semantic cache (F-CACHE-02). */
+import { cosineSimilarity } from './embedding.js';
+/** Bounded, brute-force in-memory vector store (default dev backend). */
+export function inMemoryVectorBackend(maxSize = 1000) {
+    const items = [];
+    return {
+        async add(vector, value, ttlSeconds) {
+            const expiresAt = ttlSeconds ? Date.now() + ttlSeconds * 1000 : null;
+            items.push({ vector, value, expiresAt });
+            if (items.length > maxSize)
+                items.shift();
+        },
+        async query(vector, threshold) {
+            const now = Date.now();
+            let best = null;
+            let bestSim = threshold;
+            for (const item of items) {
+                if (item.expiresAt !== null && now > item.expiresAt)
+                    continue;
+                const sim = cosineSimilarity(vector, item.vector);
+                if (sim >= bestSim) {
+                    bestSim = sim;
+                    best = item.value;
+                }
+            }
+            return best;
+        },
+        async clear() {
+            items.length = 0;
+        },
+    };
+}

package/dist/esm/interceptors/governance/budget.d.ts

@@ -0,0 +1,11 @@
+/** costControl (F-GOV-02) — soft/hard budget caps per scope and window. */
+import type { Interceptor } from '../base.js';
+export type Scope = 'agent' | 'session' | 'global';
+export type Window = 'day' | 'month' | 'total';
+export interface CostControlOptions {
+    hardCapUsd: number;
+    softCapUsd?: number;
+    scope?: Scope;
+    window?: Window;
+}
+export declare function costControl(options: CostControlOptions): Interceptor;

package/dist/esm/interceptors/governance/budget.js

@@ -0,0 +1,42 @@
+/** costControl (F-GOV-02) — soft/hard budget caps per scope and window. */
+import { BudgetExceededError } from '../../errors.js';
+function scopeKey(scope, ctx) {
+    if (scope === 'agent')
+        return `agent:${ctx.agentId ?? 'unknown'}`;
+    if (scope === 'session')
+        return `session:${ctx.sessionId ?? 'unknown'}`;
+    return 'global';
+}
+function windowBucket(window) {
+    const now = new Date().toISOString();
+    if (window === 'day')
+        return now.slice(0, 10);
+    if (window === 'month')
+        return now.slice(0, 7);
+    return 'total';
+}
+export function costControl(options) {
+    const { hardCapUsd, softCapUsd, scope = 'global', window = 'day' } = options;
+    const spend = new Map();
+    const key = (ctx) => `${scopeKey(scope, ctx)}|${windowBucket(window)}`;
+    return {
+        name: 'cost_control',
+        before(request, ctx) {
+            const spent = spend.get(key(ctx)) ?? 0;
+            if (spent >= hardCapUsd) {
+                throw new BudgetExceededError(`budget hard cap $${hardCapUsd.toFixed(2)} reached (spent $${spent.toFixed(4)})`);
+            }
+            return request;
+        },
+        after(response, ctx) {
+            const k = key(ctx);
+            const total = (spend.get(k) ?? 0) + response.costUsd;
+            spend.set(k, total);
+            if (softCapUsd !== undefined && total >= softCapUsd) {
+                // eslint-disable-next-line no-console
+                console.warn(`[gavio:budget] soft cap: $${total.toFixed(4)} of $${softCapUsd} for ${k}`);
+            }
+            return response;
+        },
+    };
+}

package/dist/esm/interceptors/governance/index.d.ts

@@ -0,0 +1,7 @@
+/** Cost & governance (F-GOV-02 budget, F-GOV-03 rate limit, F-GOV-04 RBAC). */
+export { costControl } from './budget.js';
+export type { CostControlOptions, Scope, Window } from './budget.js';
+export { rateLimiter } from './rate-limit.js';
+export type { RateLimiterOptions } from './rate-limit.js';
+export { modelPolicy } from './model-policy.js';
+export type { ModelPolicyOptions } from './model-policy.js';

package/dist/esm/interceptors/governance/index.js

@@ -0,0 +1,4 @@
+/** Cost & governance (F-GOV-02 budget, F-GOV-03 rate limit, F-GOV-04 RBAC). */
+export { costControl } from './budget.js';
+export { rateLimiter } from './rate-limit.js';
+export { modelPolicy } from './model-policy.js';

package/dist/esm/interceptors/governance/model-policy.d.ts

@@ -0,0 +1,8 @@
+/** modelPolicy (F-GOV-04) — per-role model allowlists (RBAC). */
+import type { Interceptor } from '../base.js';
+export interface ModelPolicyOptions {
+    roles: Record<string, string[]>;
+    defaultRole?: string;
+    roleKey?: string;
+}
+export declare function modelPolicy(options: ModelPolicyOptions): Interceptor;