gavio 0.1.0 → 0.2.0

package/dist/esm/config.js

@@ -0,0 +1,102 @@
+/**
+ * Config loader (F-DX-05) — build a Gateway from an object or a JSON file.
+ *
+ *   const gw = await Gateway.fromConfig('gateway.json')
+ *
+ * JSON is supported out of the box; string values expand ${ENV_VAR}.
+ */
+import { readFileSync } from 'node:fs';
+import { ConfigurationError } from './errors.js';
+import { Gateway } from './gateway.js';
+import { auditInterceptor } from './interceptors/audit/index.js';
+import { hashingEmbedder, semanticCache } from './interceptors/cache/index.js';
+import { costControl, modelPolicy, rateLimiter } from './interceptors/governance/index.js';
+import { promptInjectionGuard } from './interceptors/injection.js';
+import { piiGuard } from './interceptors/pii/index.js';
+import { retryInterceptor, timeoutPolicy } from './interceptors/reliability/index.js';
+export function loadConfig(path) {
+    const text = readFileSync(path, 'utf8');
+    if (!path.endsWith('.json')) {
+        throw new ConfigurationError('JS config loader supports JSON only (use .json)');
+    }
+    return expand(JSON.parse(text));
+}
+function expand(obj) {
+    if (Array.isArray(obj))
+        return obj.map(expand);
+    if (obj && typeof obj === 'object') {
+        return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expand(v)]));
+    }
+    if (typeof obj === 'string') {
+        return obj.replace(/\$\{(\w+)\}/g, (_, v) => process.env[v] ?? '');
+    }
+    return obj;
+}
+export function buildFromConfig(config) {
+    const gatewayOptions = {};
+    if (config['provider'])
+        gatewayOptions['provider'] = config['provider'];
+    if (config['model'])
+        gatewayOptions['model'] = config['model'];
+    if (config['devMode'] ?? config['dev_mode'])
+        gatewayOptions['devMode'] = true;
+    if (config['dryRun'] ?? config['dry_run'])
+        gatewayOptions['dryRun'] = true;
+    let gw = new Gateway(gatewayOptions);
+    const ic = config['interceptors'] ?? {};
+    const cfg = (name) => {
+        const entry = ic[name];
+        return entry && entry['enabled'] !== false ? entry : null;
+    };
+    let c;
+    if ((c = cfg('audit'))) {
+        gw = gw.use(auditInterceptor({
+            sink: c['sink'] ?? 'stdout',
+            hashChain: Boolean(c['hashChain'] ?? c['hash_chain']),
+        }));
+    }
+    if ((c = cfg('prompt_injection'))) {
+        gw = gw.use(promptInjectionGuard({ action: c['action'] ?? 'block' }));
+    }
+    if ((c = cfg('pii_guard'))) {
+        gw = gw.use(piiGuard({
+            sensitivity: c['sensitivity'] ?? 'strict',
+            mode: c['mode'] ?? 'redact',
+        }));
+    }
+    if ((c = cfg('cost_control'))) {
+        gw = gw.use(costControl({
+            hardCapUsd: Number(c['hardCapUsd'] ?? c['hard_cap_usd']),
+            softCapUsd: (c['softCapUsd'] ?? c['soft_cap_usd']),
+            scope: c['scope'] ?? 'global',
+            window: c['window'] ?? 'day',
+        }));
+    }
+    if ((c = cfg('rate_limiter'))) {
+        gw = gw.use(rateLimiter({
+            maxRequestsPerMinute: (c['maxRequestsPerMinute'] ?? c['max_requests_per_minute']),
+            maxTokensPerMinute: (c['maxTokensPerMinute'] ?? c['max_tokens_per_minute']),
+            scope: c['scope'] ?? 'global',
+        }));
+    }
+    if ((c = cfg('model_policy'))) {
+        gw = gw.use(modelPolicy({ roles: c['roles'] ?? {} }));
+    }
+    if ((c = cfg('semantic_cache'))) {
+        const embedder = (c['enableSemantic'] ?? c['enable_semantic']) ? hashingEmbedder() : undefined;
+        gw = gw.use(semanticCache({
+            embedder,
+            similarityThreshold: Number(c['similarityThreshold'] ?? c['similarity_threshold'] ?? 0.95),
+        }));
+    }
+    if ((c = cfg('timeout'))) {
+        gw = gw.use(timeoutPolicy({ timeoutSeconds: Number(c['timeoutSeconds'] ?? c['timeout_seconds'] ?? 30) }));
+    }
+    if ((c = cfg('retry'))) {
+        gw = gw.use(retryInterceptor({
+            maxAttempts: Number(c['maxAttempts'] ?? c['max_attempts'] ?? 3),
+            baseDelayMs: Number(c['baseDelayMs'] ?? c['base_delay_ms'] ?? 500),
+        }));
+    }
+    return gw;
+}

package/dist/esm/errors.d.ts

@@ -31,6 +31,23 @@ export declare class PiiBlockedError extends GavioError {
 /** A hard budget cap was exceeded. Never swallow this — surface to user. */
 export declare class BudgetExceededError extends GavioError {
 }
+/** The circuit breaker is open; the call was rejected without hitting the provider. */
+export declare class CircuitOpenError extends ProviderUnavailableError {
+}
+/** A local rate limit (requests/tokens per minute) was exceeded. */
+export declare class RateLimitExceededError extends GavioError {
+}
+/** The caller's role is not permitted to use the requested model (RBAC). */
+export declare class ModelNotAllowedError extends GavioError {
+    readonly role: string;
+    readonly model: string;
+    constructor(role: string, model: string);
+}
 /** Output failed a guardrail validator with onFailure='error'. */
 export declare class GuardrailViolationError extends GavioError {
 }
+/** A prompt-injection attempt was detected and the guard is in block mode. */
+export declare class PromptInjectionError extends GavioError {
+    readonly patterns: string[];
+    constructor(patterns: string[]);
+}

package/dist/esm/errors.js

@@ -39,6 +39,30 @@ export class PiiBlockedError extends GavioError {
 /** A hard budget cap was exceeded. Never swallow this — surface to user. */
 export class BudgetExceededError extends GavioError {
 }
+/** The circuit breaker is open; the call was rejected without hitting the provider. */
+export class CircuitOpenError extends ProviderUnavailableError {
+}
+/** A local rate limit (requests/tokens per minute) was exceeded. */
+export class RateLimitExceededError extends GavioError {
+}
+/** The caller's role is not permitted to use the requested model (RBAC). */
+export class ModelNotAllowedError extends GavioError {
+    role;
+    model;
+    constructor(role, model) {
+        super(`role ${JSON.stringify(role)} may not use model ${JSON.stringify(model)}`);
+        this.role = role;
+        this.model = model;
+    }
+}
 /** Output failed a guardrail validator with onFailure='error'. */
 export class GuardrailViolationError extends GavioError {
 }
+/** A prompt-injection attempt was detected and the guard is in block mode. */
+export class PromptInjectionError extends GavioError {
+    patterns;
+    constructor(patterns) {
+        super(`prompt injection detected: ${patterns.join(', ')}`);
+        this.patterns = patterns;
+    }
+}

package/dist/esm/gateway.d.ts

@@ -39,6 +39,11 @@ export declare class Gateway {
     private readonly pricing;
     private readonly interceptors;
     constructor(options?: GatewayOptions);
+    /**
+     * 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 fromConfig(config: string | Record<string, unknown>): Promise<Gateway>;
     /** Register an interceptor or executor policy. First-registered = outermost. */
     use(interceptor: Interceptor): this;
     /** Supply a provider adapter explicitly (overrides `provider`). */

package/dist/esm/gateway.js

@@ -37,6 +37,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);

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

@@ -15,8 +15,11 @@ 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());
@@ -45,6 +48,10 @@ class AuditInterceptor {
             guardrailOutcome: ctx.guardrailOutcome,
             riskScore: ctx.riskScore,
         });
+        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/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;

package/dist/esm/interceptors/governance/model-policy.js

@@ -0,0 +1,15 @@
+/** modelPolicy (F-GOV-04) — per-role model allowlists (RBAC). */
+import { ModelNotAllowedError } from '../../errors.js';
+export function modelPolicy(options) {
+    const { roles, defaultRole = 'default', roleKey = 'role' } = options;
+    return {
+        name: 'model_policy',
+        before(request, _ctx) {
+            const role = String(request.metadata?.[roleKey] ?? defaultRole);
+            const allowed = roles[role] ?? [];
+            if (allowed.includes('*') || allowed.includes(request.model))
+                return request;
+            throw new ModelNotAllowedError(role, request.model);
+        },
+    };
+}

package/dist/esm/interceptors/governance/rate-limit.d.ts

@@ -0,0 +1,9 @@
+/** rateLimiter (F-GOV-03) — fixed-window requests/tokens per minute per scope. */
+import type { Interceptor } from '../base.js';
+import type { Scope } from './budget.js';
+export interface RateLimiterOptions {
+    maxRequestsPerMinute?: number;
+    maxTokensPerMinute?: number;
+    scope?: Scope;
+}
+export declare function rateLimiter(options?: RateLimiterOptions): Interceptor;