@salimassili/ai-costguard 1.2.0 → 2.0.0

package/benchmarks/run.mjs

@@ -0,0 +1,229 @@
+import { performance } from 'node:perf_hooks';
+import { guardFunction } from '../dist/index.js';
+import { GuardCore, GuardError } from '../dist/core/GuardCore.js';
+import { estimateRequestTokens } from '../dist/core/tokenizer.js';
+
+const iterations = readIterations(process.argv.slice(2));
+
+const result = {
+  generatedAt: new Date().toISOString(),
+  node: process.version,
+  platform: process.platform,
+  iterations,
+  runtimeOverhead: await measureRuntimeOverhead(iterations),
+  memoryOverhead: await measureMemoryOverhead(Math.max(250, Math.min(iterations, 2000))),
+  falsePositiveScenarios: measureFalsePositiveScenarios(),
+  loopDetectionBehavior: measureLoopDetectionBehavior(),
+  costEstimationBoundaries: measureCostEstimationBoundaries(),
+};
+
+console.log(JSON.stringify(result, null, 2));
+
+async function measureRuntimeOverhead(count) {
+  async function directCall(request) {
+    return { ok: true, usage: { prompt_tokens: 12, completion_tokens: request.max_tokens ?? 8 } };
+  }
+
+  const guardedCall = guardFunction(directCall, {
+    budget: 1_000,
+    behaviorAnalysis: false,
+    scope: { projectId: 'benchmark' },
+  });
+
+  const request = {
+    model: 'gpt-4o-mini',
+    prompt: 'benchmark request',
+    max_tokens: 8,
+  };
+
+  await warmup(directCall, guardedCall, request);
+
+  const directMs = await timeAsync(count, () => directCall(request));
+  const guardedMs = await timeAsync(count, () => guardedCall(request));
+  const directPerCallMs = directMs / count;
+  const guardedPerCallMs = guardedMs / count;
+
+  return {
+    directTotalMs: round(directMs, 3),
+    guardedTotalMs: round(guardedMs, 3),
+    directPerCallMs: round(directPerCallMs, 6),
+    guardedPerCallMs: round(guardedPerCallMs, 6),
+    addedPerCallMs: round(guardedPerCallMs - directPerCallMs, 6),
+  };
+}
+
+async function measureMemoryOverhead(count) {
+  const guardedCall = guardFunction(
+    async (request) => ({ ok: true, usage: { prompt_tokens: 12, completion_tokens: request.max_tokens ?? 8 } }),
+    {
+      budget: 1_000,
+      maxHistory: count,
+      loopMinRepeats: count + 1,
+      scope: { projectId: 'memory-benchmark' },
+    }
+  );
+
+  collectGarbageIfAvailable();
+  const beforeBytes = process.memoryUsage().heapUsed;
+
+  for (let index = 0; index < count; index++) {
+    await guardedCall({
+      model: 'gpt-4o-mini',
+      prompt: `memory benchmark unique prompt ${index}`,
+      max_tokens: 8,
+    });
+  }
+
+  collectGarbageIfAvailable();
+  const afterBytes = process.memoryUsage().heapUsed;
+
+  return {
+    calls: count,
+    heapDeltaBytes: afterBytes - beforeBytes,
+    heapDeltaPerCallBytes: round((afterBytes - beforeBytes) / count, 2),
+    gcAvailable: typeof globalThis.gc === 'function',
+    note: 'Heap measurements are process-local and noisy unless Node is run with --expose-gc.',
+  };
+}
+
+function measureFalsePositiveScenarios() {
+  const core = new GuardCore({
+    budget: 1,
+    retryThreshold: 2,
+    loopSimilarityThreshold: 0.9,
+    scope: { projectId: 'false-positive-benchmark' },
+  });
+  const prompts = [
+    'again compare the two product options',
+    'again summarize the second option with different tradeoffs',
+    'again write a new title for the launch note',
+  ];
+  let blocked = 0;
+
+  for (const prompt of prompts) {
+    try {
+      core.check(context(prompt));
+    } catch (error) {
+      if (error instanceof GuardError) blocked += 1;
+      else throw error;
+    }
+  }
+
+  return {
+    scenario: 'Repeated benign "again" prompts without failure/error language',
+    prompts: prompts.length,
+    blocked,
+  };
+}
+
+function measureLoopDetectionBehavior() {
+  const core = new GuardCore({
+    budget: 1,
+    loopSimilarityThreshold: 0.9,
+    loopMinRepeats: 2,
+    scope: { projectId: 'loop-benchmark' },
+  });
+  const prompt = 'summarize the same tool observation and continue the agent plan';
+
+  for (let step = 1; step <= 5; step++) {
+    try {
+      core.check(context(prompt));
+    } catch (error) {
+      if (error instanceof GuardError) {
+        return {
+          repeatedPrompt: prompt,
+          blockedAtStep: step,
+          code: error.code,
+          reason: error.message,
+        };
+      }
+
+      throw error;
+    }
+  }
+
+  return {
+    repeatedPrompt: prompt,
+    blockedAtStep: null,
+  };
+}
+
+function measureCostEstimationBoundaries() {
+  const samples = [
+    { label: 'short chat', request: { messages: [{ role: 'user', content: 'hello' }], max_tokens: 32 } },
+    {
+      label: 'long instruction',
+      request: {
+        messages: [{ role: 'user', content: 'Summarize the following requirements. '.repeat(120) }],
+        max_tokens: 256,
+      },
+    },
+    {
+      label: 'code-heavy prompt',
+      request: {
+        prompt: 'function example(value) { return value.map((item) => item.id).join(","); }\n'.repeat(40),
+        max_tokens: 128,
+      },
+    },
+  ];
+
+  return {
+    tokenizer: 'dependency-free estimator',
+    doesNotClaimProviderExactness: true,
+    samples: samples.map((sample) => {
+      const estimate = estimateRequestTokens(sample.request);
+      return {
+        label: sample.label,
+        inputTokens: estimate.inputTokens,
+        outputTokens: estimate.outputTokens,
+        totalTokens: estimate.tokens,
+      };
+    }),
+  };
+}
+
+async function warmup(directCall, guardedCall, request) {
+  for (let index = 0; index < 100; index++) {
+    await directCall(request);
+    await guardedCall(request);
+  }
+}
+
+async function timeAsync(count, fn) {
+  const start = performance.now();
+  for (let index = 0; index < count; index++) {
+    await fn();
+  }
+  return performance.now() - start;
+}
+
+function context(prompt) {
+  return {
+    model: 'gpt-4o-mini',
+    pricingKnown: true,
+    tokens: 100,
+    inputTokens: 40,
+    outputTokens: 60,
+    estimatedCost: 0.0001,
+    timestamp: Date.now(),
+    prompt,
+  };
+}
+
+function collectGarbageIfAvailable() {
+  if (typeof globalThis.gc === 'function') {
+    globalThis.gc();
+  }
+}
+
+function readIterations(args) {
+  const index = args.indexOf('--iterations');
+  if (index === -1) return 5000;
+  const value = Number(args[index + 1]);
+  return Number.isFinite(value) && value > 0 ? Math.trunc(value) : 5000;
+}
+
+function round(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}

package/dist/cli.d.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { type DashboardOptions } from './dashboard.js';
+/**
+ * IO streams used by the CLI runner.
+ */
+export interface CliIO {
+    /** Writes standard output. */
+    stdout(message: string): void;
+    /** Writes standard error. */
+    stderr(message: string): void;
+}
+/**
+ * Parsed options for the aifw check command.
+ */
+export interface CliCheckOptions {
+    /** Budget in USD. */
+    budget: number;
+    /** Model name used for pricing. */
+    model: string;
+    /** Estimated output tokens per step. */
+    tokens: number;
+    /** Estimated input tokens per step. Defaults to 0. */
+    inputTokens: number;
+    /** Maximum number of steps to budget for. */
+    maxSteps: number;
+    /** Custom input price in USD per 1,000 tokens. */
+    inputPricePer1k?: number;
+    /** Custom output price in USD per 1,000 tokens. */
+    outputPricePer1k?: number;
+}
+/**
+ * Parsed options for the local dashboard command.
+ */
+export interface CliDashboardOptions extends DashboardOptions {
+    once: boolean;
+    json: boolean;
+}
+/**
+ * Parses arguments for `aifw check`.
+ */
+export declare function parseCheckArgs(args: readonly string[]): CliCheckOptions;
+/**
+ * Parses arguments for `aifw dashboard`.
+ */
+export declare function parseDashboardArgs(args: readonly string[]): CliDashboardOptions;
+/**
+ * Runs the aifw CLI and returns a process exit code.
+ */
+export declare function runCli(args?: readonly string[], io?: CliIO): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAGA,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,8BAA8B;IAC9B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6BAA6B;IAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,CA0BvE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,mBAAmB,CAgC/E;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAiB,GAAG,MAAM,CA4ErG"}

package/dist/cli.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { getPricing } from './pricing/index.js';
+import { formatDashboardSummary, getDefaultEventLogPath, startDashboardServer, summarizeDashboard, } from './dashboard.js';
+/**
+ * Parses arguments for `aifw check`.
+ */
+export function parseCheckArgs(args) {
+    const options = new Map();
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (!arg.startsWith('--'))
+            continue;
+        const key = arg.slice(2);
+        const value = args[index + 1];
+        if (!value || value.startsWith('--')) {
+            throw new Error(`Missing value for --${key}`);
+        }
+        options.set(key, value);
+        index += 1;
+    }
+    return {
+        budget: readRequiredNumber(options, 'budget'),
+        model: readRequiredString(options, 'model'),
+        tokens: readRequiredNumber(options, 'tokens'),
+        inputTokens: readOptionalNumber(options, 'input-tokens') ?? 0,
+        maxSteps: Math.max(1, Math.trunc(readOptionalNumber(options, 'max-steps') ?? 1)),
+        inputPricePer1k: readOptionalNumber(options, 'input-price-per-1k'),
+        outputPricePer1k: readOptionalNumber(options, 'output-price-per-1k'),
+    };
+}
+/**
+ * Parses arguments for `aifw dashboard`.
+ */
+export function parseDashboardArgs(args) {
+    const options = new Map();
+    const flags = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (!arg.startsWith('--'))
+            continue;
+        const key = arg.slice(2);
+        if (key === 'once' || key === 'json') {
+            flags.add(key);
+            continue;
+        }
+        const value = args[index + 1];
+        if (!value || value.startsWith('--')) {
+            throw new Error(`Missing value for --${key}`);
+        }
+        options.set(key, value);
+        index += 1;
+    }
+    return {
+        eventLogPath: readOptionalString(options, 'events') ?? getDefaultEventLogPath(),
+        budgetUsd: readOptionalNumber(options, 'budget'),
+        host: readOptionalString(options, 'host'),
+        port: readOptionalNumber(options, 'port'),
+        recentLimit: readOptionalNumber(options, 'recent'),
+        once: flags.has('once'),
+        json: flags.has('json'),
+    };
+}
+/**
+ * Runs the aifw CLI and returns a process exit code.
+ */
+export function runCli(args = process.argv.slice(2), io = defaultIO) {
+    const command = args[0];
+    if (!command || command === '--help' || command === '-h') {
+        io.stdout(helpText());
+        return 0;
+    }
+    if (command !== 'check' && command !== 'dashboard') {
+        io.stderr(`Unknown command: ${command}\n\n${helpText()}`);
+        return 2;
+    }
+    try {
+        if (command === 'dashboard') {
+            const options = parseDashboardArgs(args.slice(1));
+            if (options.once || options.json) {
+                const summary = summarizeDashboard(options);
+                io.stdout(options.json ? JSON.stringify(summary, null, 2) + '\n' : formatDashboardSummary(summary));
+                return 0;
+            }
+            void startDashboardServer(options)
+                .then(({ url }) => {
+                io.stdout(`AI CostGuard dashboard running at ${url}\nReading events from ${options.eventLogPath}\n`);
+            })
+                .catch((error) => {
+                io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+                process.exitCode = 2;
+            });
+            return 0;
+        }
+        const options = parseCheckArgs(args.slice(1));
+        const pricing = getPricing(options.model);
+        const hasCustomPricing = options.inputPricePer1k !== undefined || options.outputPricePer1k !== undefined;
+        if (hasCustomPricing && (options.inputPricePer1k === undefined || options.outputPricePer1k === undefined)) {
+            io.stderr('--input-price-per-1k and --output-price-per-1k must be provided together.\n');
+            return 2;
+        }
+        if (!pricing && !hasCustomPricing) {
+            io.stderr(`No pricing found for model "${options.model}". Use a known model or pass --input-price-per-1k and --output-price-per-1k.\n`);
+            return 2;
+        }
+        const inputPer1kTokens = options.inputPricePer1k ?? pricing?.inputPer1kTokens ?? 0;
+        const outputPer1kTokens = options.outputPricePer1k ?? pricing?.outputPer1kTokens ?? 0;
+        const perStepCost = (options.inputTokens / 1000) * inputPer1kTokens + (options.tokens / 1000) * outputPer1kTokens;
+        const projectedCost = perStepCost * options.maxSteps;
+        const ok = projectedCost <= options.budget;
+        io.stdout(JSON.stringify({
+            ok,
+            model: options.model,
+            inputTokensPerStep: options.inputTokens,
+            outputTokensPerStep: options.tokens,
+            maxSteps: options.maxSteps,
+            estimatedCostUsd: roundMoney(projectedCost),
+            budgetUsd: options.budget,
+        }, null, 2) + '\n');
+        return ok ? 0 : 1;
+    }
+    catch (error) {
+        io.stderr(`${error instanceof Error ? error.message : String(error)}\n\n${helpText()}`);
+        return 2;
+    }
+}
+const defaultIO = {
+    stdout: (message) => process.stdout.write(message),
+    stderr: (message) => process.stderr.write(message),
+};
+if (isCliEntry()) {
+    process.exitCode = runCli();
+}
+function readRequiredNumber(options, key) {
+    const value = Number(options.get(key));
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`--${key} must be a non-negative number`);
+    }
+    return value;
+}
+function readOptionalNumber(options, key) {
+    if (!options.has(key))
+        return undefined;
+    return readRequiredNumber(options, key);
+}
+function readRequiredString(options, key) {
+    const value = options.get(key);
+    if (!value?.trim()) {
+        throw new Error(`--${key} is required`);
+    }
+    return value;
+}
+function roundMoney(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+function helpText() {
+    return [
+        'Usage:',
+        '  aifw check --budget <usd> --model <model> --tokens <output-tokens> --max-steps <n>',
+        '  aifw dashboard --events .ai-costguard/events.jsonl --budget <usd>',
+        '  ai-costguard dashboard --once --json',
+        '',
+        'Notes:',
+        '  --tokens is per-step output tokens. Use --input-tokens for input token estimates.',
+        '  For custom models, pass --input-price-per-1k and --output-price-per-1k.',
+        '  The dashboard is local-only and reads an opt-in JSONL event log.',
+        '  Exit code 0 means projected cost is within budget; 1 means over budget; 2 means usage/config error.',
+        '',
+    ].join('\n');
+}
+function readOptionalString(options, key) {
+    const value = options.get(key);
+    return value?.trim() ? value.trim() : undefined;
+}
+function isCliEntry() {
+    const entry = process.argv[1] ?? '';
+    return /(^|[/\\])cli\.js$/u.test(entry);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/core/CostGuard.d.ts

@@ -1,7 +1,6 @@
-export { guard, GuardError, middleware } from './GuardFree.js';
-export { GuardPro, validateLicense, getProGuard } from './GuardPro.js';
-export type { GuardProConfig } from './GuardPro.js';
+export { guard, guardFunction, GuardError, middleware } from './GuardFree.js';
+export type { GuardedClient, GuardEventControls } from './GuardFree.js';
 export { getPricing, registerPricing, listPricing } from '../pricing/index.js';
 export type { ModelPricing } from '../pricing/index.js';
-export type { GuardConfig } from './types.js';
+export type { GuardConfig, GuardErrorCode, GuardEvent, GuardEventHandler, GuardEventName, GuardScope, GuardState, GuardWebhookConfig, RequestContext, } from './types.js';
 //# sourceMappingURL=CostGuard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"CostGuard.d.ts","sourceRoot":"","sources":["../../src/core/CostGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/E,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"CostGuard.d.ts","sourceRoot":"","sources":["../../src/core/CostGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/E,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/core/CostGuard.js

@@ -1,4 +1,3 @@
-export { guard, GuardError, middleware } from './GuardFree.js';
-export { GuardPro, validateLicense, getProGuard } from './GuardPro.js';
+export { guard, guardFunction, GuardError, middleware } from './GuardFree.js';
 export { getPricing, registerPricing, listPricing } from '../pricing/index.js';
 //# sourceMappingURL=CostGuard.js.map

package/dist/core/CostGuard.js.map

@@ -1 +1 @@
-{"version":3,"file":"CostGuard.js","sourceRoot":"","sources":["../../src/core/CostGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"CostGuard.js","sourceRoot":"","sources":["../../src/core/CostGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE9E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/core/GuardCore.d.ts

@@ -1,22 +1,102 @@
+import type { GuardConfig, GuardErrorCode, GuardEventHandler, GuardEventName, GuardState, RequestContext } from './types.js';
 /**
- * GuardCore.ts - FREE CORE (VIRAL ENGINE)
- *
- * Maximum simplicity. Maximum virality. Zero complexity.
- * Instant safety layer every AI developer installs by default.
+ * Result returned by the guard evaluator.
  */
-import { GuardConfig, RequestContext, GuardState } from './types.js';
+export interface GuardCheckResult {
+    /** Final guard decision. */
+    decision: 'allow' | 'block';
+    /** Request context that was evaluated. */
+    context: RequestContext;
+    /** Human-readable block reason, present when decision is "block". */
+    reason?: string;
+    /** Highest prompt similarity seen during loop detection. */
+    similarity?: number;
+}
 /**
- * Guard your AI client from wasting money
- * FREE CORE: Local protection + viral logs + real-time risk warnings
+ * Extra structured metadata attached to GuardError.
  */
-export declare function guard(client: any, config: GuardConfig, sharedState?: GuardState): any;
+export interface GuardErrorMetadata {
+    /** Stable machine-readable block reason. */
+    code: GuardErrorCode;
+    /** Human-readable block reason. */
+    reason: string;
+    /** Evaluated request context. */
+    context: RequestContext;
+    /** Current scope key for budget/history isolation. */
+    scopeKey: string;
+    /** Highest prompt similarity involved in a loop/retry decision. */
+    similarity?: number;
+}
 /**
- * Express middleware (FREE CORE - LOCAL ONLY)
+ * Error thrown when a guarded request is blocked before reaching the AI provider.
  */
-export declare function middleware(config: GuardConfig): (req: any, res: any, next: any) => void;
 export declare class GuardError extends Error {
-    context: RequestContext;
-    constructor(message: string, context: RequestContext);
+    /** Stable machine-readable block reason. */
+    readonly code: GuardErrorCode;
+    /** Request context that caused the block. */
+    readonly context: RequestContext;
+    /** Structured error metadata for API responses and logging. */
+    readonly metadata: GuardErrorMetadata;
+    /**
+     * Creates a GuardError for a blocked request.
+     */
+    constructor(message: string, context?: RequestContext, code?: GuardErrorCode, metadata?: Partial<GuardErrorMetadata>);
+    toJSON(): GuardErrorMetadata;
 }
-export { getPricing } from '../pricing/index.js';
+/**
+ * Shared synchronous evaluator used by the free proxy guard and middleware.
+ */
+export declare class GuardCore {
+    private readonly config;
+    private readonly state;
+    private readonly emitter;
+    /**
+     * Creates a process-local guard evaluator.
+     */
+    constructor(config?: GuardConfig, sharedState?: GuardState);
+    /**
+     * Subscribes to guard events.
+     */
+    on(eventName: GuardEventName, handler: GuardEventHandler): () => void;
+    /**
+     * Removes a guard event handler.
+     */
+    off(eventName: GuardEventName, handler: GuardEventHandler): void;
+    /**
+     * Returns the mutable process-local state used by this evaluator.
+     */
+    getState(): GuardState;
+    /**
+     * Returns true when a proxied method path should be evaluated.
+     */
+    shouldGuardMethod(methodPath: string): boolean;
+    /**
+     * Extracts a normalized request context from OpenAI-like method arguments.
+     */
+    extractContext(args: readonly unknown[], method?: string): RequestContext;
+    /**
+     * Checks a request context, records allowed calls, emits events, and throws GuardError on block.
+     */
+    check(context: RequestContext): GuardCheckResult;
+    /**
+     * Reconciles actual provider usage from OpenAI/Anthropic-like response objects when available.
+     */
+    recordActualUsage(context: RequestContext, response: unknown): void;
+    private checkBudget;
+    private checkMaxSteps;
+    private findLoopSimilarity;
+    private checkRetryStorm;
+    private recordAttempt;
+    private recordAllowed;
+    private pushHistory;
+    private block;
+    private emit;
+    private getScopeState;
+    private pruneScope;
+    private extractScope;
+}
+/**
+ * Creates an empty process-local guard state.
+ */
+export declare function createGuardState(): GuardState;
 //# sourceMappingURL=GuardCore.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GuardCore.d.ts","sourceRoot":"","sources":["../../src/core/GuardCore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAErE;;;GAGG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,UAAU,OAgF/E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,IAGpC,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,UAiCtC;AAiED,qBAAa,UAAW,SAAQ,KAAK;IACnC,OAAO,EAAE,cAAc,CAAC;gBACZ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;CAKrD;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"GuardCore.d.ts","sourceRoot":"","sources":["../../src/core/GuardCore.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,cAAc,EAGd,UAAU,EACV,cAAc,EACf,MAAM,YAAY,CAAC;AAmBpB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5B,0CAA0C;IAC1C,OAAO,EAAE,cAAc,CAAC;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,IAAI,EAAE,cAAc,CAAC;IACrB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAEtC;;OAEG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,cAAqC,EAC9C,IAAI,GAAE,cAAkC,EACxC,QAAQ,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAe5C,MAAM,IAAI,kBAAkB;CAG7B;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAyBnB;IACJ,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAEnD;;OAEG;gBACS,MAAM,GAAE,WAAgB,EAAE,WAAW,GAAE,UAA+B;IA8BlF;;OAEG;IACH,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAIrE;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAIhE;;OAEG;IACH,QAAQ,IAAI,UAAU;IAItB;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI9C;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc;IA+BzE;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,gBAAgB;IAqChD;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAoBnE,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,eAAe;IAoBvB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,IAAI;IAaZ,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;CAOrB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAK7C"}