@salimassili/ai-costguard 1.2.0 → 2.0.0

package/dist/core/similarity.js

@@ -0,0 +1,51 @@
+const TRIGRAM_SIZE = 3;
+/**
+ * Builds a character trigram frequency vector for a prompt.
+ */
+export function characterTrigrams(input) {
+    const normalized = normalizeForSimilarity(input);
+    const vector = new Map();
+    if (normalized.length === 0)
+        return vector;
+    if (normalized.length < TRIGRAM_SIZE) {
+        vector.set(normalized, 1);
+        return vector;
+    }
+    for (let index = 0; index <= normalized.length - TRIGRAM_SIZE; index++) {
+        const trigram = normalized.slice(index, index + TRIGRAM_SIZE);
+        vector.set(trigram, (vector.get(trigram) ?? 0) + 1);
+    }
+    return vector;
+}
+/**
+ * Calculates cosine similarity between two strings using character trigrams.
+ */
+export function cosineSimilarity(left, right) {
+    const leftVector = characterTrigrams(left);
+    const rightVector = characterTrigrams(right);
+    if (leftVector.size === 0 || rightVector.size === 0)
+        return 0;
+    let dotProduct = 0;
+    let leftMagnitude = 0;
+    let rightMagnitude = 0;
+    for (const [key, leftValue] of leftVector) {
+        dotProduct += leftValue * (rightVector.get(key) ?? 0);
+        leftMagnitude += leftValue * leftValue;
+    }
+    for (const rightValue of rightVector.values()) {
+        rightMagnitude += rightValue * rightValue;
+    }
+    if (leftMagnitude === 0 || rightMagnitude === 0)
+        return 0;
+    return dotProduct / (Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude));
+}
+/**
+ * Returns the highest trigram cosine similarity between a prompt and a prompt history.
+ */
+export function maxCosineSimilarity(prompt, history) {
+    return history.reduce((max, candidate) => Math.max(max, cosineSimilarity(prompt, candidate)), 0);
+}
+function normalizeForSimilarity(input) {
+    return input.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+//# sourceMappingURL=similarity.js.map

package/dist/core/similarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.js","sourceRoot":"","sources":["../../src/core/similarity.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,MAAM,UAAU,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAC3C,IAAI,UAAU,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QAC1B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,UAAU,CAAC,MAAM,GAAG,YAAY,EAAE,KAAK,EAAE,EAAE,CAAC;QACvE,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,KAAa;IAC1D,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,WAAW,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAE7C,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE9D,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,cAAc,GAAG,CAAC,CAAC;IAEvB,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,UAAU,EAAE,CAAC;QAC1C,UAAU,IAAI,SAAS,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACtD,aAAa,IAAI,SAAS,GAAG,SAAS,CAAC;IACzC,CAAC;IAED,KAAK,MAAM,UAAU,IAAI,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;QAC9C,cAAc,IAAI,UAAU,GAAG,UAAU,CAAC;IAC5C,CAAC;IAED,IAAI,aAAa,KAAK,CAAC,IAAI,cAAc,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1D,OAAO,UAAU,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAA0B;IAC5E,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACnG,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzD,CAAC"}

package/dist/core/tokenizer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Estimates tokens for a plain text string using a small inline BPE approximation.
+ */
+export declare function estimateTokensFromText(input: string): number;
+/**
+ * Extracts text from OpenAI-like or Anthropic-like message content.
+ */
+export declare function extractText(value: unknown): string;
+/**
+ * Estimates the input, output, and total token counts for an AI request payload.
+ */
+export declare function estimateRequestTokens(params: unknown): {
+    inputTokens: number;
+    outputTokens: number;
+    tokens: number;
+    prompt: string;
+};
+//# sourceMappingURL=tokenizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../../src/core/tokenizer.ts"],"names":[],"mappings":"AA+CA;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO5D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWlD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAiBA"}

package/dist/core/tokenizer.js

@@ -0,0 +1,137 @@
+const TOKEN_PATTERN = /'s|'t|'re|'ve|'m|'ll|'d| ?[\p{L}]+| ?\p{N}{1,3}| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+/gu;
+const BPE_RANKS = new Map([
+    't h',
+    'h e',
+    'i n',
+    'e r',
+    'a n',
+    'r e',
+    'o n',
+    'a t',
+    'e n',
+    'n d',
+    's t',
+    'o r',
+    'a l',
+    'i t',
+    'i s',
+    't i',
+    'n g',
+    'c o',
+    'd e',
+    'l l',
+    'm e',
+    'p r',
+    'o m',
+    'p t',
+    'r e',
+    'e s',
+    's i',
+    'o u',
+    'a r',
+    'a i',
+    'g p',
+    'p t',
+    'c l',
+    'a u',
+    'u d',
+    'd e',
+    'm o',
+    'o d',
+    'e l',
+].map((pair, index) => [pair, index]));
+/**
+ * Estimates tokens for a plain text string using a small inline BPE approximation.
+ */
+export function estimateTokensFromText(input) {
+    if (input.length === 0)
+        return 0;
+    const pieces = input.match(TOKEN_PATTERN) ?? [];
+    const count = pieces.reduce((total, piece) => total + estimatePieceTokens(piece), 0);
+    return Math.max(1, count);
+}
+/**
+ * Extracts text from OpenAI-like or Anthropic-like message content.
+ */
+export function extractText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(extractText).filter(Boolean).join(' ');
+    if (isRecord(value)) {
+        const typedText = value.text ?? value.content ?? value.input ?? value.message;
+        if (typedText !== undefined)
+            return extractText(typedText);
+    }
+    return '';
+}
+/**
+ * Estimates the input, output, and total token counts for an AI request payload.
+ */
+export function estimateRequestTokens(params) {
+    const record = isRecord(params) ? params : {};
+    const prompt = extractPrompt(record);
+    const modelOverhead = Array.isArray(record.messages) ? record.messages.length * 3 + 3 : 0;
+    const inputTokens = estimateTokensFromText(prompt) + modelOverhead;
+    const outputTokens = readPositiveNumber(record.max_tokens) ??
+        readPositiveNumber(record.max_completion_tokens) ??
+        readPositiveNumber(record.maxTokens) ??
+        readPositiveNumber(record.max_output_tokens) ??
+        1000;
+    return {
+        inputTokens,
+        outputTokens,
+        tokens: inputTokens + outputTokens,
+        prompt,
+    };
+}
+function estimatePieceTokens(piece) {
+    if (/^\s+$/u.test(piece))
+        return 1;
+    if (/^\p{N}{1,3}$/u.test(piece.trim()))
+        return 1;
+    const normalized = piece.normalize('NFKC');
+    if (/^[\p{P}\p{S}\s]+$/u.test(normalized)) {
+        return Math.max(1, Math.ceil([...normalized].length / 2));
+    }
+    const symbols = applyApproximateBpe([...normalized.toLowerCase()]);
+    return Math.max(1, symbols.length);
+}
+function applyApproximateBpe(initialSymbols) {
+    const symbols = [...initialSymbols];
+    while (symbols.length > 1) {
+        let bestIndex = -1;
+        let bestRank = Number.POSITIVE_INFINITY;
+        for (let index = 0; index < symbols.length - 1; index++) {
+            const rank = BPE_RANKS.get(`${symbols[index]} ${symbols[index + 1]}`);
+            if (rank !== undefined && rank < bestRank) {
+                bestRank = rank;
+                bestIndex = index;
+            }
+        }
+        if (bestIndex === -1)
+            break;
+        symbols.splice(bestIndex, 2, `${symbols[bestIndex]}${symbols[bestIndex + 1]}`);
+    }
+    return symbols;
+}
+function extractPrompt(record) {
+    if (Array.isArray(record.messages)) {
+        return record.messages
+            .map((message) => (isRecord(message) ? extractText(message.content) : extractText(message)))
+            .filter(Boolean)
+            .join(' ');
+    }
+    return extractText(record.prompt ?? record.input ?? record.content ?? record.message);
+}
+function readPositiveNumber(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return undefined;
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=tokenizer.js.map

package/dist/core/tokenizer.js.map

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

package/dist/core/types.d.ts

@@ -1,24 +1,172 @@
+import type { ModelPricing } from '../pricing/index.js';
 /**
- * AI CostGuard — Simplified types for 10/10 experience
+ * Stable machine-readable reasons for blocked requests.
+ */
+export type GuardErrorCode = 'UNKNOWN_MODEL' | 'BUDGET_EXCEEDED' | 'MAX_STEPS_EXCEEDED' | 'LOOP_DETECTED' | 'RETRY_STORM_DETECTED'
+/** Reserved for compatibility; current GuardPro does not enforce local licenses. */
+ | 'INVALID_LICENSE';
+/**
+ * Webhook destinations used by the guard when a request is blocked.
+ */
+export interface GuardWebhookConfig {
+    /** Slack incoming webhook URL. */
+    slack?: string;
+    /** Discord incoming webhook URL. */
+    discord?: string;
+    /** Number of retry attempts after the first failed POST. Defaults to 2. */
+    retries?: number;
+    /** Per-request timeout in milliseconds. Defaults to 1500. */
+    timeoutMs?: number;
+}
+/**
+ * Scope used to isolate budgets and behavior history.
+ */
+export interface GuardScope {
+    /** Product, tenant, or application project identifier. */
+    projectId?: string;
+    /** End-user identifier. */
+    userId?: string;
+    /** Agent run, workflow, request, or conversation identifier. */
+    sessionId?: string;
+}
+/**
+ * Runtime configuration for the free process-local guard.
  */
 export interface GuardConfig {
-    /** Daily budget in USD */
-    budget: number;
-    /** Enable behavioral analysis */
+    /** Process-local budget in USD for each scope. Defaults to 10. */
+    budget?: number;
+    /** Enables loop, retry-storm, and step-count checks. Defaults to true. */
     behaviorAnalysis?: boolean;
+    /** Maximum prompt history retained for similarity checks. Defaults to 32. */
+    maxHistory?: number;
+    /** Prompt/retry history TTL in milliseconds. Defaults to 5 minutes. */
+    historyTtlMs?: number;
+    /** Optional maximum number of allowed guarded calls in the current process. */
+    maxSteps?: number;
+    /** Cosine similarity threshold for trigram loop detection. Defaults to 0.85. */
+    loopSimilarityThreshold?: number;
+    /** Number of prior similar prompts required before loop blocking. Defaults to 2. */
+    loopMinRepeats?: number;
+    /** Number of retry/failure prompts allowed before a retry storm is blocked. Defaults to 2. */
+    retryThreshold?: number;
+    /** Known AI SDK method paths to guard. Defaults to common OpenAI/Anthropic create methods. */
+    guardedMethods?: string[];
+    /** How unknown model pricing is handled. Defaults to "block". */
+    unknownModelPolicy?: 'block' | 'fallback';
+    /** Fallback pricing used only when unknownModelPolicy is "fallback". */
+    unknownModelPricing?: ModelPricing;
+    /** Default scope for requests that do not provide one. */
+    scope?: GuardScope;
+    /** Optional runtime pricing entries that take precedence over built-ins. */
+    pricingOverrides?: ModelPricing[];
+    /** Slack and Discord webhook destinations for block events. */
+    webhooks?: GuardWebhookConfig;
+    /** Optional JSONL file path for local dashboard/event history. Disabled by default. */
+    eventLogPath?: string;
+    /** Prompt logging mode for eventLogPath. Defaults to "none". */
+    eventLogPrompt?: 'none' | 'preview';
+    /** Convenience Slack webhook URL. Equivalent to webhooks.slack. */
+    slackWebhook?: string;
+    /** Convenience Discord webhook URL. Equivalent to webhooks.discord. */
+    discordWebhook?: string;
 }
+/**
+ * Normalized request data evaluated before an AI API call is allowed.
+ */
 export interface RequestContext {
+    /** Model name supplied by the request, or "unknown" when missing. */
     model: string;
+    /** True when pricing came from the registry, overrides, or configured fallback. */
+    pricingKnown?: boolean;
+    /** Pricing entry used for estimation, when available. */
+    pricing?: ModelPricing;
+    /** Estimated total tokens, input plus reserved output. */
     tokens: number;
+    /** Estimated input tokens. */
+    inputTokens?: number;
+    /** Reserved or requested output tokens. */
+    outputTokens?: number;
+    /** Estimated USD cost for the request. */
     estimatedCost: number;
+    /** Actual USD cost reconciled from a provider usage response, when available. */
+    actualCost?: number;
+    /** Unix timestamp in milliseconds when the context was created. */
     timestamp: number;
+    /** Prompt text used for loop and retry detection. */
     prompt: string;
+    /** Client method name being guarded, when known. */
+    method?: string;
+    /** Scope used for budget and history isolation. */
+    scope?: GuardScope;
+    /** Stable normalized key derived from scope. */
+    scopeKey?: string;
+}
+/**
+ * Prompt history entry retained by the process-local guard.
+ */
+export interface PromptHistoryEntry {
+    /** Prompt text retained for trigram similarity comparison. */
+    prompt: string;
+    /** Unix timestamp in milliseconds when the prompt was recorded. */
+    timestamp: number;
 }
-export interface GuardState {
+/**
+ * Mutable process-local state for one scope.
+ */
+export interface GuardScopeState {
+    /** Number of allowed requests. */
     requestCount: number;
+    /** Estimated allowed spend in USD. */
     totalCost: number;
+    /** Estimated cost of all guarded attempts, including blocked attempts. */
+    attemptedCost: number;
+    /** Estimated cost blocked before provider execution. */
+    blockedCost: number;
+    /** Actual provider-reported spend reconciled from usage fields when available. */
+    actualCost: number;
+    /** Unix timestamp in milliseconds for the last allowed request. */
     lastRequestTime: number;
+    /** Number of blocked requests. */
     blockedCount: number;
+    /** Recent prompts retained for cosine similarity loop detection. */
+    recentPrompts?: PromptHistoryEntry[];
+    /** Recent retry/failure prompts retained for retry-storm detection. */
+    recentRetries?: PromptHistoryEntry[];
+    /** Optional session expiry timestamp used by stateful guards. */
+    sessionExpiresAt?: number;
 }
+/**
+ * Mutable aggregate process-local guard state.
+ */
+export interface GuardState extends GuardScopeState {
+    /** Per-scope state keyed by project/user/session. */
+    scopes?: Record<string, GuardScopeState>;
+}
+/**
+ * Guard decision returned by the core evaluator.
+ */
 export type GuardDecision = 'allow' | 'block';
+/**
+ * Supported event names emitted by guarded clients.
+ */
+export type GuardEventName = 'block' | 'allow' | 'cost';
+/**
+ * Event payload emitted by a guard instance.
+ */
+export interface GuardEvent {
+    /** Event name. */
+    type: GuardEventName;
+    /** Request context associated with the event. */
+    context: RequestContext;
+    /** Machine-readable block reason, present for block events. */
+    code?: GuardErrorCode;
+    /** Human-readable block reason, present for block events. */
+    reason?: string;
+    /** Snapshot of state at emit time. */
+    state: Readonly<GuardState>;
+}
+/**
+ * Callback invoked when a guard event is emitted.
+ */
+export type GuardEventHandler = (event: GuardEvent) => void;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -1,5 +1,2 @@
-/**
- * AI CostGuard — Simplified types for 10/10 experience
- */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":""}

package/dist/core/webhooks.d.ts

@@ -0,0 +1,15 @@
+import type { GuardWebhookConfig, RequestContext } from './types.js';
+/**
+ * Payload sent to configured block webhooks.
+ */
+export interface GuardWebhookPayload {
+    /** Human-readable reason the request was blocked. */
+    reason: string;
+    /** Request context associated with the block. */
+    context: RequestContext;
+}
+/**
+ * Posts a block notification to Slack and Discord webhooks with exponential backoff.
+ */
+export declare function notifyBlockWebhooks(config: GuardWebhookConfig | undefined, payload: GuardWebhookPayload): Promise<void>;
+//# sourceMappingURL=webhooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/core/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/core/webhooks.js

@@ -0,0 +1,58 @@
+/**
+ * Posts a block notification to Slack and Discord webhooks with exponential backoff.
+ */
+export async function notifyBlockWebhooks(config, payload) {
+    if (!config?.slack && !config?.discord)
+        return;
+    await Promise.all([
+        config.slack ? postWithBackoff(config.slack, slackBody(payload), config) : Promise.resolve(),
+        config.discord ? postWithBackoff(config.discord, discordBody(payload), config) : Promise.resolve(),
+    ]);
+}
+function slackBody(payload) {
+    return JSON.stringify({
+        text: `[AI CostGuard] Blocked request: ${payload.reason}\n` +
+            `Model: ${payload.context.model}\n` +
+            `Estimated cost: $${payload.context.estimatedCost.toFixed(6)}`,
+    });
+}
+function discordBody(payload) {
+    return JSON.stringify({
+        content: `[AI CostGuard] Blocked request: ${payload.reason}\n` +
+            `Model: ${payload.context.model}\n` +
+            `Estimated cost: $${payload.context.estimatedCost.toFixed(6)}`,
+    });
+}
+async function postWithBackoff(url, body, config) {
+    const retries = Math.max(0, config.retries ?? 2);
+    const timeoutMs = Math.max(100, config.timeoutMs ?? 1500);
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body,
+                    signal: controller.signal,
+                });
+                if (response.ok)
+                    return;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch {
+            // Webhooks are observability only; guard enforcement must remain independent.
+        }
+        if (attempt < retries) {
+            await delay(100 * 2 ** attempt);
+        }
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/core/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/core/webhooks.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAsC,EACtC,OAA4B;IAE5B,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,MAAM,EAAE,OAAO;QAAE,OAAO;IAE/C,MAAM,OAAO,CAAC,GAAG,CAAC;QAChB,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE;QAC5F,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE;KACnG,CAAC,CAAC;AACL,CAAC;AAED,SAAS,SAAS,CAAC,OAA4B;IAC7C,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,IAAI,EACF,mCAAmC,OAAO,CAAC,MAAM,IAAI;YACrD,UAAU,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI;YACnC,oBAAoB,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;KACjE,CAAC,CAAC;AACL,CAAC;AAED,SAAS,WAAW,CAAC,OAA4B;IAC/C,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,OAAO,EACL,mCAAmC,OAAO,CAAC,MAAM,IAAI;YACrD,UAAU,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI;YACnC,oBAAoB,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;KACjE,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,GAAW,EAAE,IAAY,EAAE,MAA0B;IAClF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;IAE1D,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;YAEhE,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;oBAChC,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;oBAC/C,IAAI;oBACJ,MAAM,EAAE,UAAU,CAAC,MAAM;iBAC1B,CAAC,CAAC;gBAEH,IAAI,QAAQ,CAAC,EAAE;oBAAE,OAAO;YAC1B,CAAC;oBAAS,CAAC;gBACT,YAAY,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,8EAA8E;QAChF,CAAC;QAED,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;YACtB,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/dashboard.d.ts

@@ -0,0 +1,73 @@
+import { type Server } from 'node:http';
+import type { GuardErrorCode, GuardEventName } from './core/types.js';
+/**
+ * Parsed dashboard event from a JSONL event log.
+ */
+export interface DashboardEvent {
+    version: 1;
+    timestamp: string;
+    type: GuardEventName;
+    code?: GuardErrorCode;
+    reason?: string;
+    model: string;
+    method?: string;
+    scopeKey: string;
+    estimatedCost: number;
+    actualCost?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    tokens: number;
+    promptPreview?: string;
+}
+/**
+ * Aggregated local dashboard metrics.
+ */
+export interface DashboardSummary {
+    eventLogPath: string;
+    generatedAt: string;
+    budgetUsd?: number;
+    budgetUsedPercent?: number;
+    requestsAllowed: number;
+    requestsBlocked: number;
+    estimatedSpendUsd: number;
+    estimatedSavingsUsd: number;
+    attemptedSpendUsd: number;
+    actualSpendUsd: number;
+    loopDetections: number;
+    retryDetections: number;
+    recentEvents: DashboardEvent[];
+}
+/**
+ * Options for local dashboard summary/server commands.
+ */
+export interface DashboardOptions {
+    eventLogPath?: string;
+    budgetUsd?: number;
+    host?: string;
+    port?: number;
+    recentLimit?: number;
+}
+/**
+ * Returns the default local event log path.
+ */
+export declare function getDefaultEventLogPath(): string;
+/**
+ * Reads dashboard events from a local JSONL event log.
+ */
+export declare function readDashboardEvents(eventLogPath?: string): DashboardEvent[];
+/**
+ * Builds dashboard metrics from a local event log.
+ */
+export declare function summarizeDashboard(options?: DashboardOptions): DashboardSummary;
+/**
+ * Formats a dashboard summary for terminal output.
+ */
+export declare function formatDashboardSummary(summary: DashboardSummary): string;
+/**
+ * Starts a local-only HTTP dashboard server.
+ */
+export declare function startDashboardServer(options?: DashboardOptions): Promise<{
+    server: Server;
+    url: string;
+}>;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMtE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,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;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,SAAyB,GAAG,cAAc,EAAE,CAe3F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,gBAAqB,GAAG,gBAAgB,CA8BnF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAuBxE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB7G"}