@salimassili/ai-costguard 1.2.0 → 2.0.0

package/dist/core/GuardPro.js

@@ -1,135 +1,198 @@
-/*
- * Usage:
- *
- * import { GuardPro } from '@salimassili/ai-costguard';
- *
- * const guard = new GuardPro({
- *   redisUrl: 'redis://localhost:6379',
- *   budget: 25,
- *   windowSeconds: 86400,
- *   slackWebhook: process.env.SLACK_WEBHOOK,
- *   licenseKey: process.env.COSTGUARD_LICENSE
- * });
- *
- * await guard.checkAndCharge('production', 0.0042);
- * await guard.shutdown();
- *
- * No Redis? Get a free one at https://upstash.com
- */
 import { Redis } from 'ioredis';
-import { GuardError } from './GuardFree.js';
+import { GuardError } from './GuardCore.js';
+import { notifyBlockWebhooks } from './webhooks.js';
+/**
+ * Redis-backed budget guard with local fallback when Redis is unavailable.
+ */
 export class GuardPro {
-    redis;
+    static pools = new Map();
+    redisUrl;
+    redisClient;
+    poolEntry;
     budget;
     windowSeconds;
-    slackWebhook;
-    connected = false;
+    webhooks;
+    localSpend = new Map();
+    directRedisFailed = false;
+    directRedisReady = false;
+    /**
+     * Creates a GuardPro instance and reuses a pooled Redis connection for the same URL.
+     */
     constructor(config) {
-        if (config.licenseKey && !validateLicense(config.licenseKey)) {
-            throw new GuardError('Invalid CostGuard Pro license key. ' +
-                'Your key must be at least 16 characters and pass checksum validation.');
+        this.redisUrl = config.redisUrl;
+        this.budget = config.budget;
+        this.windowSeconds = config.windowSeconds ?? 86_400;
+        this.webhooks = {
+            ...config.webhooks,
+            slack: config.webhooks?.slack ?? config.slackWebhook,
+            discord: config.webhooks?.discord ?? config.discordWebhook,
+        };
+        if (config.redisClient) {
+            this.redisClient = config.redisClient;
+            this.attachConnectionEvents(config.redisClient);
+            return;
         }
-        try {
-            this.redis = new Redis(config.redisUrl, {
-                lazyConnect: true,
-                enableOfflineQueue: false,
-                retryStrategy: () => null,
-            });
-            this.redis.on('ready', () => {
-                this.connected = true;
-            });
-            this.redis.on('error', () => {
-                this.connected = false;
-            });
-            this.redis.on('close', () => {
-                this.connected = false;
-            });
-            this.redis.connect().then(() => {
-                this.connected = true;
-            }).catch(() => {
-                throw new GuardError('GuardPro requires a Redis connection. ' +
-                    'Pass a valid redisUrl in GuardProConfig. ' +
-                    'Free option: create an Upstash account at https://upstash.com ' +
-                    'and paste your Redis URL.');
-            });
-        }
-        catch (error) {
-            if (error instanceof GuardError)
-                throw error;
-            throw new GuardError('GuardPro failed to initialize Redis. ' +
-                'Pass a valid redisUrl in GuardProConfig. ' +
-                'Free option: create an Upstash account at https://upstash.com ' +
-                'and paste your Redis URL.');
+        if (config.redisUrl.trim()) {
+            this.poolEntry = GuardPro.getPoolEntry(config.redisUrl);
+            this.redisClient = this.poolEntry.client;
         }
-        this.budget = config.budget;
-        this.windowSeconds = config.windowSeconds ?? 86400;
-        this.slackWebhook = config.slackWebhook;
     }
+    /**
+     * Atomically charges estimated spend for a project and throws GuardError when budget is exceeded.
+     */
     async checkAndCharge(projectId, estimatedCost) {
-        if (!this.connected) {
-            throw new GuardError('GuardPro lost Redis connection. ' +
-                'Spending is blocked until connection is restored.');
-        }
-        let total;
-        try {
-            const key = this.getSpendKey(projectId);
-            total = await this.incrementSpend(key, estimatedCost);
-        }
-        catch (error) {
-            if (error instanceof GuardError)
-                throw error;
-            throw new GuardError('GuardPro lost Redis connection. ' +
-                'Spending is blocked until connection is restored.');
-        }
+        const key = this.getSpendKey(projectId);
+        const redis = await this.getUsableRedis();
+        const total = redis
+            ? await this.incrementRedisOrFallback(redis, key, projectId, estimatedCost)
+            : this.incrementLocal(projectId, estimatedCost);
         if (total > this.budget) {
-            if (this.slackWebhook) {
-                try {
-                    await this.sendBudgetAlert(projectId, total);
-                }
-                catch {
-                    console.error('[CostGuard] Slack webhook failed — budget still enforced.');
-                }
-            }
-            throw new GuardError(`Project "${projectId}" exceeded budget. ` +
-                `Spend: $${total.toFixed(6)} / Budget: $${this.budget.toFixed(6)}`, this.createContext(projectId, estimatedCost));
+            const context = this.createContext(projectId, estimatedCost);
+            const reason = `Project "${projectId}" exceeded budget. ` +
+                `Spend: $${total.toFixed(6)} / Budget: $${this.budget.toFixed(6)}`;
+            await notifyBlockWebhooks(this.webhooks, { reason, context });
+            throw new GuardError(reason, context, 'BUDGET_EXCEEDED');
         }
     }
+    /**
+     * Returns current spend for a project from Redis when available, otherwise from local fallback state.
+     */
     async getSpend(projectId) {
-        if (!this.connected)
-            return 0;
-        try {
-            const value = await this.redis.get(this.getSpendKey(projectId));
-            return value ? Number(value) : 0;
-        }
-        catch {
-            return 0;
+        const redis = await this.getUsableRedis();
+        if (redis) {
+            try {
+                const value = await redis.get(this.getSpendKey(projectId));
+                return value ? Number(value) : 0;
+            }
+            catch {
+                this.markDisconnected();
+            }
         }
+        return this.getLocal(projectId).total;
     }
+    /**
+     * Resets spend for a project in Redis when available and always clears local fallback state.
+     */
     async resetSpend(projectId) {
-        if (!this.connected)
+        this.localSpend.delete(projectId);
+        const redis = await this.getUsableRedis();
+        if (!redis)
             return;
         try {
-            await this.redis.del(this.getSpendKey(projectId));
+            await redis.del(this.getSpendKey(projectId));
         }
         catch {
-            // silent — reset is best-effort
+            this.markDisconnected();
         }
     }
+    /**
+     * Returns true when the pooled or supplied Redis client is currently connected.
+     */
     isConnected() {
-        return this.connected;
+        if (this.poolEntry)
+            return this.poolEntry.connected;
+        return !this.directRedisFailed && (this.redisClient?.status === 'ready' || this.directRedisReady);
     }
+    /**
+     * Releases this instance's pooled Redis reference and closes the connection when unused.
+     */
     async shutdown() {
+        if (this.poolEntry) {
+            this.poolEntry.refs -= 1;
+            if (this.poolEntry.refs <= 0) {
+                GuardPro.pools.delete(this.redisUrl);
+                await this.safeQuit(this.poolEntry.client);
+            }
+            return;
+        }
+        if (this.redisClient) {
+            await this.safeQuit(this.redisClient);
+        }
+    }
+    static getPoolEntry(redisUrl) {
+        const existing = GuardPro.pools.get(redisUrl);
+        if (existing) {
+            existing.refs += 1;
+            return existing;
+        }
+        const entry = {
+            client: new Redis(redisUrl, {
+                lazyConnect: true,
+                enableOfflineQueue: false,
+                retryStrategy: () => null,
+            }),
+            refs: 1,
+            connected: false,
+        };
+        entry.client.on?.('ready', () => {
+            entry.connected = true;
+        });
+        entry.client.on?.('error', () => {
+            entry.connected = false;
+        });
+        entry.client.on?.('close', () => {
+            entry.connected = false;
+        });
+        GuardPro.pools.set(redisUrl, entry);
+        return entry;
+    }
+    attachConnectionEvents(client) {
+        client.on?.('ready', () => {
+            this.directRedisReady = true;
+            this.directRedisFailed = false;
+        });
+        client.on?.('error', () => {
+            this.directRedisReady = false;
+            this.directRedisFailed = true;
+        });
+        client.on?.('close', () => {
+            this.directRedisReady = false;
+        });
+    }
+    async getUsableRedis() {
+        const client = this.redisClient;
+        if (!client)
+            return null;
+        if (!this.poolEntry && this.directRedisFailed)
+            return null;
+        if (client.status === 'ready')
+            return client;
+        if (this.poolEntry) {
+            if (this.poolEntry.connected)
+                return client;
+            this.poolEntry.connectPromise ??= this.connect(client);
+            return this.poolEntry.connectPromise;
+        }
+        return this.connect(client);
+    }
+    async connect(client) {
         try {
-            await this.redis.quit();
+            await client.connect?.();
+            if (this.poolEntry) {
+                this.poolEntry.connected = client.status === undefined || client.status === 'ready';
+                this.poolEntry.connectPromise = undefined;
+            }
+            else {
+                this.directRedisFailed = false;
+                this.directRedisReady = true;
+            }
+            return client;
         }
         catch {
-            // ignore close errors
+            this.markDisconnected();
+            return null;
         }
-        finally {
-            this.connected = false;
+    }
+    async incrementRedisOrFallback(redis, key, projectId, estimatedCost) {
+        try {
+            return await this.incrementRedis(redis, key, estimatedCost);
+        }
+        catch {
+            this.markDisconnected();
+            return this.incrementLocal(projectId, estimatedCost);
         }
     }
-    async incrementSpend(key, estimatedCost) {
+    async incrementRedis(redis, key, estimatedCost) {
         const script = `
       local total = redis.call("INCRBYFLOAT", KEYS[1], ARGV[1])
       local ttl = redis.call("TTL", KEYS[1])
@@ -138,21 +201,44 @@ export class GuardPro {
       end
       return total
     `;
-        const total = await this.redis.eval(script, 1, key, estimatedCost.toString(), this.windowSeconds.toString());
+        const total = await redis.eval(script, 1, key, estimatedCost.toString(), this.windowSeconds.toString());
         return Number(total);
     }
-    async sendBudgetAlert(projectId, currentSpend) {
-        if (!this.slackWebhook)
-            return;
-        const response = await fetch(this.slackWebhook, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                text: `[CostGuard] 🚨 Project "${projectId}" exceeded budget.\nSpend: $${currentSpend.toFixed(6)} / Budget: $${this.budget.toFixed(6)}`
-            })
-        });
-        if (!response.ok) {
-            throw new Error(`Slack webhook responded with status ${response.status}`);
+    incrementLocal(projectId, estimatedCost) {
+        const record = this.getLocal(projectId);
+        record.total += estimatedCost;
+        this.localSpend.set(projectId, record);
+        return record.total;
+    }
+    getLocal(projectId) {
+        const now = Date.now();
+        const existing = this.localSpend.get(projectId);
+        if (existing && existing.expiresAt > now) {
+            return existing;
+        }
+        const fresh = {
+            total: 0,
+            expiresAt: now + this.windowSeconds * 1000,
+        };
+        this.localSpend.set(projectId, fresh);
+        return fresh;
+    }
+    markDisconnected() {
+        if (this.poolEntry) {
+            this.poolEntry.connected = false;
+            this.poolEntry.connectPromise = undefined;
+        }
+        else {
+            this.directRedisFailed = true;
+            this.directRedisReady = false;
+        }
+    }
+    async safeQuit(client) {
+        try {
+            await client.quit?.();
+        }
+        catch {
+            // Best-effort shutdown only.
         }
     }
     getSpendKey(projectId) {
@@ -162,21 +248,30 @@ export class GuardPro {
         return {
             model: 'unknown',
             tokens: 0,
+            inputTokens: 0,
+            outputTokens: 0,
             estimatedCost,
             timestamp: Date.now(),
-            prompt: `project:${projectId}`
+            prompt: `project:${projectId}`,
         };
     }
 }
+/**
+ * Deprecated compatibility helper.
+ *
+ * This is a format sanity check only. It is not license enforcement and should
+ * not be used for commercial access control.
+ */
 export function validateLicense(key) {
-    if (typeof key !== 'string' || key.length < 16)
-        return false;
-    const checksum = Array.from(key).reduce((sum, char) => sum + char.charCodeAt(0), 0);
-    return checksum % 7 === 0;
+    return typeof key === 'string' && key.trim().length >= 16;
 }
+/**
+ * Creates GuardPro.
+ *
+ * The return type remains nullable for backwards compatibility with older
+ * callers, but local license rejection has intentionally been removed.
+ */
 export function getProGuard(config) {
-    if (config.licenseKey && !validateLicense(config.licenseKey))
-        return null;
     return new GuardPro(config);
 }
 //# sourceMappingURL=GuardPro.js.map

package/dist/core/GuardPro.js.map

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

package/dist/core/event-log.d.ts

@@ -0,0 +1,37 @@
+import type { GuardEvent } from './types.js';
+/**
+ * Prompt retention mode for JSONL event logs.
+ */
+export type EventLogPromptMode = 'none' | 'preview';
+/**
+ * Stable JSONL record written for local dashboards and offline analysis.
+ */
+export interface GuardEventLogRecord {
+    version: 1;
+    timestamp: string;
+    type: GuardEvent['type'];
+    code?: GuardEvent['code'];
+    reason?: string;
+    model: string;
+    method?: string;
+    scopeKey: string;
+    estimatedCost: number;
+    actualCost?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    tokens: number;
+    promptPreview?: string;
+    state: {
+        requestCount: number;
+        blockedCount: number;
+        totalCost: number;
+        attemptedCost: number;
+        blockedCost: number;
+        actualCost: number;
+    };
+}
+/**
+ * Appends a redacted guard event to a local JSONL file.
+ */
+export declare function appendGuardEventLog(eventLogPath: string | undefined, event: GuardEvent, promptMode?: EventLogPromptMode): void;
+//# sourceMappingURL=event-log.d.ts.map

package/dist/core/event-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.d.ts","sourceRoot":"","sources":["../../src/core/event-log.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,KAAK,EAAE,UAAU,EACjB,UAAU,GAAE,kBAA2B,GACtC,IAAI,CASN"}

package/dist/core/event-log.js

@@ -0,0 +1,49 @@
+import { mkdirSync, appendFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Appends a redacted guard event to a local JSONL file.
+ */
+export function appendGuardEventLog(eventLogPath, event, promptMode = 'none') {
+    if (!eventLogPath)
+        return;
+    try {
+        mkdirSync(dirname(eventLogPath), { recursive: true });
+        appendFileSync(eventLogPath, JSON.stringify(toEventLogRecord(event, promptMode)) + '\n', 'utf8');
+    }
+    catch {
+        // Event logs are local observability only and must not affect guard decisions.
+    }
+}
+function toEventLogRecord(event, promptMode) {
+    const record = {
+        version: 1,
+        timestamp: new Date(event.context.timestamp).toISOString(),
+        type: event.type,
+        code: event.code,
+        reason: event.reason,
+        model: event.context.model,
+        method: event.context.method,
+        scopeKey: event.context.scopeKey ?? 'default',
+        estimatedCost: roundMoney(event.context.estimatedCost),
+        actualCost: event.context.actualCost === undefined ? undefined : roundMoney(event.context.actualCost),
+        inputTokens: event.context.inputTokens,
+        outputTokens: event.context.outputTokens,
+        tokens: event.context.tokens,
+        state: {
+            requestCount: event.state.requestCount,
+            blockedCount: event.state.blockedCount,
+            totalCost: roundMoney(event.state.totalCost),
+            attemptedCost: roundMoney(event.state.attemptedCost),
+            blockedCost: roundMoney(event.state.blockedCost),
+            actualCost: roundMoney(event.state.actualCost),
+        },
+    };
+    if (promptMode === 'preview' && event.context.prompt.trim()) {
+        record.promptPreview = event.context.prompt.slice(0, 160);
+    }
+    return record;
+}
+function roundMoney(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+//# sourceMappingURL=event-log.js.map

package/dist/core/event-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.js","sourceRoot":"","sources":["../../src/core/event-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoCpC;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,YAAgC,EAChC,KAAiB,EACjB,aAAiC,MAAM;IAEvC,IAAI,CAAC,YAAY;QAAE,OAAO;IAE1B,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,cAAc,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACnG,CAAC;IAAC,MAAM,CAAC;QACP,+EAA+E;IACjF,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAiB,EAAE,UAA8B;IACzE,MAAM,MAAM,GAAwB;QAClC,OAAO,EAAE,CAAC;QACV,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;QAC1D,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK;QAC1B,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;QAC5B,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,IAAI,SAAS;QAC7C,aAAa,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;QACtD,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACrG,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW;QACtC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,YAAY;QACxC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;QAC5B,KAAK,EAAE;YACL,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY;YACtC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY;YACtC,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC;YAC5C,aAAa,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC;YACpD,WAAW,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;YAChD,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC;SAC/C;KACF,CAAC;IAEF,IAAI,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5D,MAAM,CAAC,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;AACnD,CAAC"}

package/dist/core/events.d.ts

@@ -0,0 +1,20 @@
+import type { GuardEvent, GuardEventHandler, GuardEventName } from './types.js';
+/**
+ * Small synchronous event emitter used by guarded clients.
+ */
+export declare class GuardEventEmitter {
+    private readonly handlers;
+    /**
+     * Subscribes to a guard event and returns an unsubscribe function.
+     */
+    on(eventName: GuardEventName, handler: GuardEventHandler): () => void;
+    /**
+     * Removes one event handler from a guard event.
+     */
+    off(eventName: GuardEventName, handler: GuardEventHandler): void;
+    /**
+     * Emits an event to all current subscribers.
+     */
+    emit(event: GuardEvent): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/core/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEhF;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqD;IAE9E;;OAEG;IACH,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAUrE;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAUhE;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAY9B"}

package/dist/core/events.js

@@ -0,0 +1,46 @@
+/**
+ * Small synchronous event emitter used by guarded clients.
+ */
+export class GuardEventEmitter {
+    handlers = new Map();
+    /**
+     * Subscribes to a guard event and returns an unsubscribe function.
+     */
+    on(eventName, handler) {
+        const handlers = this.handlers.get(eventName) ?? new Set();
+        handlers.add(handler);
+        this.handlers.set(eventName, handlers);
+        return () => {
+            this.off(eventName, handler);
+        };
+    }
+    /**
+     * Removes one event handler from a guard event.
+     */
+    off(eventName, handler) {
+        const handlers = this.handlers.get(eventName);
+        if (!handlers)
+            return;
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+            this.handlers.delete(eventName);
+        }
+    }
+    /**
+     * Emits an event to all current subscribers.
+     */
+    emit(event) {
+        const handlers = this.handlers.get(event.type);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Event handlers are opt-in observability hooks and must not affect the guard decision.
+            }
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/core/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,iBAAiB;IACX,QAAQ,GAAG,IAAI,GAAG,EAA0C,CAAC;IAE9E;;OAEG;IACH,EAAE,CAAC,SAAyB,EAAE,OAA0B;QACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,GAAG,EAAqB,CAAC;QAC9E,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAEvC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,SAAyB,EAAE,OAA0B;QACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ;YAAE,OAAO;QAEtB,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,KAAiB;QACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ;YAAE,OAAO;QAEtB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;YAAC,MAAM,CAAC;gBACP,wFAAwF;YAC1F,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/core/similarity.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Builds a character trigram frequency vector for a prompt.
+ */
+export declare function characterTrigrams(input: string): Map<string, number>;
+/**
+ * Calculates cosine similarity between two strings using character trigrams.
+ */
+export declare function cosineSimilarity(left: string, right: string): number;
+/**
+ * Returns the highest trigram cosine similarity between a prompt and a prompt history.
+ */
+export declare function maxCosineSimilarity(prompt: string, history: readonly string[]): number;
+//# sourceMappingURL=similarity.d.ts.map

package/dist/core/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../src/core/similarity.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEtF"}