@salimassili/ai-costguard 2.1.1 → 2.1.4

package/CHANGELOG.md

@@ -1,34 +1,37 @@
 # Changelog
 
-## 2.1.1 - Unreleased
-
-### Changed
-
-- Recalibrated the built-in zero-dependency token estimator with simple model-family and text-shape heuristics.
-- Improved the fixed proxy token benchmark from `237.76%` average error to `9.68%` average error while keeping `registerTokenizer()` as the recommended exact-counting path.
-
-## 2.1.0 - 2026-06-09
-
-### Added
-
-- Added `registerTokenizer()` for exact/provider-specific token counting without adding production dependencies.
-- Added `getPricingMeta()` and `aifw pricing --check-stale --days <n>` for pricing freshness checks.
-- Added structured `loopDetection` config with `similarityThreshold`, `minHistorySize`, and `windowSize`.
-- Expanded the token accuracy benchmark to a 24-sample proxy corpus with per-sample output.
-
-### Changed
-
-- Removed obsolete license-related surfaces. AI CostGuard does not contain license-key checks or local commercial-license enforcement.
-- Added explicit built-in pricing freshness notice: `2026-06-07`.
-- Updated README loop detection tuning, pricing freshness, token accuracy, and trust guidance.
-- Documented that the built-in estimator materially overestimates the fixed proxy corpus and that production users can register exact tokenizers.
-
-## 2.0.0 - 2026-06-08
+## 2.1.1 - Unreleased
+
+### Changed
+
+- Recalibrated the built-in zero-dependency token estimator with simple model-family and text-shape heuristics.
+- Improved the fixed proxy token benchmark from `237.76%` average error to `9.68%` average error while keeping `registerTokenizer()` as the recommended exact-counting path.
+- Removed tracked generated coverage output, legacy artifacts, and archived pre-CostGuard concept docs from the active repository.
+- Renamed starter templates from `*-firewall` to `*-costguard` and updated template dependencies to `@salimassili/ai-costguard` `^2.1.1`.
+- Aligned Pro copy around the current $19/month or $199/year Lemon Squeezy plan and marked the `pro-v0.1` folder as a Redis-focused starter.
+
+## 2.1.0 - 2026-06-09
+
+### Added
+
+- Added `registerTokenizer()` for exact/provider-specific token counting without adding production dependencies.
+- Added `getPricingMeta()` and `aifw pricing --check-stale --days <n>` for pricing freshness checks.
+- Added structured `loopDetection` config with `similarityThreshold`, `minHistorySize`, and `windowSize`.
+- Expanded the token accuracy benchmark to a 24-sample proxy corpus with per-sample output.
+
+### Changed
+
+- Removed obsolete license-related surfaces. AI CostGuard does not contain license-key checks or local commercial-license enforcement.
+- Added explicit built-in pricing freshness notice: `2026-06-07`.
+- Updated README loop detection tuning, pricing freshness, token accuracy, and trust guidance.
+- Documented that the built-in estimator materially overestimates the fixed proxy corpus and that production users can register exact tokenizers.
+
+## 2.0.0 - 2026-06-08
 
 ### Changed
 
 - Moved Redis-backed `GuardPro` exports to `@salimassili/ai-costguard/pro` so the root import stays lightweight.
-- Removed fake local license enforcement from `GuardPro`.
+- Removed fake local license enforcement from `GuardPro`.
 - Unknown models now block by default unless runtime pricing, guard pricing overrides, or explicit fallback pricing is configured.
 - Guard proxy now checks known AI SDK method paths instead of charging every function call on the wrapped client.
 - Loop detection now requires repeated similar prompts in the same scope before blocking.

package/README.md

@@ -1,27 +1,28 @@
 # AI CostGuard
 [![npm version](https://img.shields.io/npm/v/@salimassili/ai-costguard)](https://www.npmjs.com/package/@salimassili/ai-costguard)
+[![AI CostGuard Pro](https://img.shields.io/badge/Pro-$19%2Fmo-orange)](https://salimassili.lemonsqueezy.com/buy/ai-costguard-pro)
 
 AI CostGuard is a local-first runtime safety layer for AI agents that prevents runaway costs, loops, retries, and budget explosions before API calls execute. It wraps OpenAI-compatible clients and function-style SDK calls, estimates request cost locally, blocks budget overruns, detects repeated prompts, emits structured events, and exposes CLI checks plus a local dashboard.
 
-It is local-first. It does not include a SaaS control plane, cloud dashboard, proxy gateway, telemetry service, billing reconciliation service, or hard security boundary.
-
-## What AI CostGuard Does
-
-- Checks selected AI SDK calls before they execute.
-- Estimates request cost from model pricing, prompt text, and reserved output tokens.
-- Blocks unknown models unless explicit pricing is supplied.
-- Blocks budget overruns, repeated prompt loops, retry storms, and max-step overruns.
-- Emits structured errors and local events your app can handle.
-
-## What AI CostGuard Does Not Do
-
-- It does not call providers for real-time pricing.
-- It does not reconcile provider invoices or replace provider billing alerts.
-- It does not provide auth, API-key security, or a hard security boundary.
-- It does not run a hosted dashboard, SaaS backend, or cloud telemetry service.
-- It does not guarantee exact tokenizer parity with OpenAI, Anthropic, or other providers.
-
-## Install
+It is local-first. It does not include a SaaS control plane, cloud dashboard, proxy gateway, telemetry service, billing reconciliation service, or hard security boundary.
+
+## What AI CostGuard Does
+
+- Checks selected AI SDK calls before they execute.
+- Estimates request cost from model pricing, prompt text, and reserved output tokens.
+- Blocks unknown models unless explicit pricing is supplied.
+- Blocks budget overruns, repeated prompt loops, retry storms, and max-step overruns.
+- Emits structured errors and local events your app can handle.
+
+## What AI CostGuard Does Not Do
+
+- It does not call providers for real-time pricing.
+- It does not reconcile provider invoices or replace provider billing alerts.
+- It does not provide auth, API-key security, or a hard security boundary.
+- It does not run a hosted dashboard, SaaS backend, or cloud telemetry service.
+- It does not guarantee exact tokenizer parity with OpenAI, Anthropic, or other providers.
+
+## Install
 
 ```bash
 npm install @salimassili/ai-costguard
@@ -53,30 +54,30 @@ try {
   } else {
     throw error;
   }
-}
-```
-
-## Before / After
-
-Without AI CostGuard:
-
-```ts
-await openai.chat.completions.create(request);
-```
-
-With AI CostGuard:
-
-```ts
-const openai = guard(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
-  budget: 5,
-  maxSteps: 50,
-  scope: { projectId: 'agent-api', sessionId: runId },
-});
-
-await openai.chat.completions.create(request);
-```
-
-## What It Guards
+}
+```
+
+## Before / After
+
+Without AI CostGuard:
+
+```ts
+await openai.chat.completions.create(request);
+```
+
+With AI CostGuard:
+
+```ts
+const openai = guard(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  budget: 5,
+  maxSteps: 50,
+  scope: { projectId: 'agent-api', sessionId: runId },
+});
+
+await openai.chat.completions.create(request);
+```
+
+## What It Guards
 
 By default AI CostGuard evaluates these SDK method paths:
 
@@ -143,21 +144,21 @@ Current runtime block codes:
 - `LOOP_DETECTED`
 - `RETRY_STORM_DETECTED`
 
-## Configuration
+## Configuration
 
 ```ts
 guard(client, {
   budget: 10,
   maxSteps: 100,
-  behaviorAnalysis: true,
-  maxHistory: 32,
-  historyTtlMs: 5 * 60 * 1000,
-  loopDetection: {
-    similarityThreshold: 0.85,
-    minHistorySize: 2,
-    windowSize: 5,
-  },
-  retryThreshold: 2,
+  behaviorAnalysis: true,
+  maxHistory: 32,
+  historyTtlMs: 5 * 60 * 1000,
+  loopDetection: {
+    similarityThreshold: 0.85,
+    minHistorySize: 2,
+    windowSize: 5,
+  },
+  retryThreshold: 2,
   scope: {
     projectId: 'production-api',
     userId: 'optional-user',
@@ -176,38 +177,38 @@ guard(client, {
 });
 ```
 
-`scope` isolates budgets and behavior history. If no scope is supplied, the guard uses one process-local default scope.
-
-## Loop Detection Tuning
-
-Default loop detection uses character trigram cosine similarity with:
-
-- `loopDetection.similarityThreshold: 0.85`
-- `loopDetection.minHistorySize: 2`
-- `loopDetection.windowSize: 5`
-
-- Higher threshold, such as `0.95`: fewer false positives, but near-duplicate loops can slip through.
-- Lower threshold, such as `0.75`: catches looser repeats, but unrelated prompts can be blocked.
-- Higher `minHistorySize`: waits for more repeated prompts before blocking.
-- Lower `minHistorySize`: blocks faster, but is more aggressive.
-- Smaller `windowSize`: compares fewer recent prompts, reducing old-history false positives.
-- Larger `windowSize`: compares more history, improving catch rate but increasing false-positive risk in repetitive workflows.
-
-```ts
-const openai = guard(client, {
-  budget: 5,
-  loopDetection: {
-    similarityThreshold: 0.9,
-    minHistorySize: 3,
-    windowSize: 6,
-  },
-  scope: { sessionId: 'agent-run-123' },
-});
-```
-
-Legacy `loopSimilarityThreshold` and `loopMinRepeats` config fields are still accepted, but `loopDetection` takes precedence. Loop detection is heuristic. Expect false positives and false negatives, especially for short prompts, templated prompts, and prompts that share a lot of boilerplate.
-
-## Accounting Semantics
+`scope` isolates budgets and behavior history. If no scope is supplied, the guard uses one process-local default scope.
+
+## Loop Detection Tuning
+
+Default loop detection uses character trigram cosine similarity with:
+
+- `loopDetection.similarityThreshold: 0.85`
+- `loopDetection.minHistorySize: 2`
+- `loopDetection.windowSize: 5`
+
+- Higher threshold, such as `0.95`: fewer false positives, but near-duplicate loops can slip through.
+- Lower threshold, such as `0.75`: catches looser repeats, but unrelated prompts can be blocked.
+- Higher `minHistorySize`: waits for more repeated prompts before blocking.
+- Lower `minHistorySize`: blocks faster, but is more aggressive.
+- Smaller `windowSize`: compares fewer recent prompts, reducing old-history false positives.
+- Larger `windowSize`: compares more history, improving catch rate but increasing false-positive risk in repetitive workflows.
+
+```ts
+const openai = guard(client, {
+  budget: 5,
+  loopDetection: {
+    similarityThreshold: 0.9,
+    minHistorySize: 3,
+    windowSize: 6,
+  },
+  scope: { sessionId: 'agent-run-123' },
+});
+```
+
+Legacy `loopSimilarityThreshold` and `loopMinRepeats` config fields are still accepted, but `loopDetection` takes precedence. Loop detection is heuristic. Expect false positives and false negatives, especially for short prompts, templated prompts, and prompts that share a lot of boilerplate.
+
+## Accounting Semantics
 
 AI CostGuard is a pre-call estimator, not a billing ledger.
 
@@ -218,14 +219,14 @@ AI CostGuard is a pre-call estimator, not a billing ledger.
 
 Budget decisions use estimated allowed cost. Actual usage is recorded for observability but does not rewrite earlier decisions.
 
-## Pricing
-
-Known model pricing comes from built-in registry entries, runtime registrations, or per-guard overrides. Unknown models are blocked by default.
-
-Pricing last updated: `2026-06-07`. Provider pricing changes; AI CostGuard does not fetch real-time pricing. Override pricing manually when provider pages or your contract pricing differ from the built-ins.
+## Pricing
+
+Known model pricing comes from built-in registry entries, runtime registrations, or per-guard overrides. Unknown models are blocked by default.
+
+Pricing last updated: `2026-06-07`. Provider pricing changes; AI CostGuard does not fetch real-time pricing. Override pricing manually when provider pages or your contract pricing differ from the built-ins.
 
 ```ts
-import { getPricingMeta, registerPricing } from '@salimassili/ai-costguard';
+import { getPricingMeta, registerPricing } from '@salimassili/ai-costguard';
 
 registerPricing([
   {
@@ -235,18 +236,18 @@ registerPricing([
     lastUpdated: '2026-06-07',
     source: 'internal',
   },
-]);
-
-console.log(getPricingMeta('gpt-4o-mini'));
-```
-
-Check built-in pricing freshness from CI or a release script:
-
-```bash
-aifw pricing --check-stale --days 30
-```
-
-The command exits `0` when all registry entries are within the threshold and `1` when one or more entries are stale.
+]);
+
+console.log(getPricingMeta('gpt-4o-mini'));
+```
+
+Check built-in pricing freshness from CI or a release script:
+
+```bash
+aifw pricing --check-stale --days 30
+```
+
+The command exits `0` when all registry entries are within the threshold and `1` when one or more entries are stale.
 
 If you intentionally want fallback pricing for unknown models:
 
@@ -264,31 +265,31 @@ guard(client, {
 });
 ```
 
-Pricing changes frequently. Verify provider pricing before production use and override entries when needed.
-
-## Token Counting Accuracy
-
-AI CostGuard ships with a dependency-free token estimator so the root package stays small. It warns once per model/scope when approximate counting is used:
-
-```text
-[ai-costguard] Using approximate token counting for model: gpt-4o-mini. Register an exact tokenizer via registerTokenizer() for production use.
-```
-
-For production budgets that need tighter input-token estimates, register a provider tokenizer:
-
-```ts
-import { registerTokenizer } from '@salimassili/ai-costguard';
-
-registerTokenizer('gpt-4o-mini', (text) => {
-  return myTokenizer.encode(text).length;
-});
-
-registerTokenizer(/^claude-/u, (text) => {
-  return myAnthropicTokenizer.count(text);
-});
-```
-
-String patterns match model-name substrings case-insensitively. `RegExp` patterns are tested against the original model string. If a registered tokenizer throws or returns an invalid count, AI CostGuard falls back to the built-in approximation and keeps guarding the call.
+Pricing changes frequently. Verify provider pricing before production use and override entries when needed.
+
+## Token Counting Accuracy
+
+AI CostGuard ships with a dependency-free token estimator so the root package stays small. It warns once per model/scope when approximate counting is used:
+
+```text
+[ai-costguard] Using approximate token counting for model: gpt-4o-mini. Register an exact tokenizer via registerTokenizer() for production use.
+```
+
+For production budgets that need tighter input-token estimates, register a provider tokenizer:
+
+```ts
+import { registerTokenizer } from '@salimassili/ai-costguard';
+
+registerTokenizer('gpt-4o-mini', (text) => {
+  return myTokenizer.encode(text).length;
+});
+
+registerTokenizer(/^claude-/u, (text) => {
+  return myAnthropicTokenizer.count(text);
+});
+```
+
+String patterns match model-name substrings case-insensitively. `RegExp` patterns are tested against the original model string. If a registered tokenizer throws or returns an invalid count, AI CostGuard falls back to the built-in approximation and keeps guarding the call.
 
 ## Events
 
@@ -400,7 +401,25 @@ await pro.shutdown();
 
 `ioredis` is an optional dependency and is not loaded by the root import.
 
-AI CostGuard does not include license-key checks or local commercial-license enforcement.
+AI CostGuard does not include license-key checks or local commercial-license enforcement.
+
+## AI CostGuard Pro
+
+AI CostGuard Free is the open-source npm package above — free forever, MIT licensed.
+
+**AI CostGuard Pro** is a $19/month or $199/year subscription for teams taking AI agents into production. Lemon Squeezy handles purchase, receipts, and subscription management. The npm package does not perform runtime license-key enforcement.
+
+Current `pro-v0.1` materials include:
+
+- Redis/GuardPro setup guide
+- Multi-process shared-budget example
+- Environment-variable based Redis/webhook configuration guidance
+
+Planned monthly updates include multi-tenant examples, tokenizer adapter recipes, `GuardError` handling patterns, pricing override guides, production checklists, and framework config starters as those files are completed.
+
+No runtime license-key enforcement. No private npm package. No SaaS backend. You get a downloadable folder of setup materials and examples that use the public package API. Use environment variables or your deployment secret manager for provider keys, `REDIS_URL`, and webhook URLs; never hardcode secrets.
+
+[Get AI CostGuard Pro →](https://salimassili.lemonsqueezy.com/buy/ai-costguard-pro)
 
 ## CLI
 
@@ -436,11 +455,11 @@ npm run build
 npm run benchmark
 ```
 
-The script reports runtime overhead, approximate heap delta, false-positive scenarios, loop detection behavior, and cost-estimation boundaries. Results are local measurements, not universal guarantees. See `docs/BENCHMARKS.md`.
-
-Latest local benchmark in this repo on Node `v24.14.1` / Windows measured `0.023937 ms` added per mocked guarded call over `5000` iterations. Re-run on your target runtime before using this number in performance-sensitive claims.
-
-Token accuracy benchmark, fixed proxy corpus: average error `9.68%`, median error `11.43%`, max error `28.57%`, `24` samples. The dependency-free estimator is a rough guardrail, not provider-tokenizer parity. Register an exact tokenizer for production use when token accuracy matters.
+The script reports runtime overhead, approximate heap delta, false-positive scenarios, loop detection behavior, and cost-estimation boundaries. Results are local measurements, not universal guarantees. See `docs/BENCHMARKS.md`.
+
+Latest local benchmark in this repo on Node `v24.14.1` / Windows measured `0.023937 ms` added per mocked guarded call over `5000` iterations. Re-run on your target runtime before using this number in performance-sensitive claims.
+
+Token accuracy benchmark, fixed proxy corpus: average error `9.68%`, median error `11.43%`, max error `28.57%`, `24` samples. The dependency-free estimator is a rough guardrail, not provider-tokenizer parity. Register an exact tokenizer for production use when token accuracy matters.
 
 ## Why Not 50 Lines Of Code?
 
@@ -463,18 +482,18 @@ npm ci
 npm run build
 npm run typecheck
 npm test
-npm run smoke
-npm run benchmark
-npm run benchmark:tokens
-npm audit --omit=dev
-npm pack --dry-run
+npm run smoke
+npm run benchmark
+npm run benchmark:tokens
+npm audit --omit=dev
+npm pack --dry-run
 ```
 
 ## Limitations
 
-- Token counting is approximate and dependency-free unless you register an exact tokenizer.
-- Token estimation is intentionally conservative and can overestimate materially; see the token accuracy benchmark.
-- Pricing entries can become stale; override them for production.
+- Token counting is approximate and dependency-free unless you register an exact tokenizer.
+- Token estimation is intentionally conservative and can overestimate materially; see the token accuracy benchmark.
+- Pricing entries can become stale; override them for production.
 - The free guard is process-local.
 - Loop detection uses character trigram similarity, not embeddings.
 - Retry detection is heuristic.

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

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

package/dist/core/GuardPro.js

@@ -41,6 +41,12 @@ export class GuardPro {
      * Atomically charges estimated spend for a project and throws GuardError when budget is exceeded.
      */
     async checkAndCharge(projectId, estimatedCost) {
+        if (!projectId.trim()) {
+            throw new Error('GuardPro projectId must be a non-empty string');
+        }
+        if (!Number.isFinite(estimatedCost) || estimatedCost < 0) {
+            throw new Error('GuardPro estimatedCost must be a finite non-negative number');
+        }
         const key = this.getSpendKey(projectId);
         const redis = await this.getUsableRedis();
         const total = redis
@@ -202,7 +208,11 @@ export class GuardPro {
       return total
     `;
         const total = await redis.eval(script, 1, key, estimatedCost.toString(), this.windowSeconds.toString());
-        return Number(total);
+        const numericTotal = Number(total);
+        if (!Number.isFinite(numericTotal) || numericTotal < 0) {
+            throw new Error('Redis returned an invalid spend total');
+        }
+        return numericTotal;
     }
     incrementLocal(projectId, estimatedCost) {
         const record = this.getLocal(projectId);

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/examples/integrations/slack-webhook-block-demo.mjs

@@ -0,0 +1,66 @@
+import { guard, GuardError, registerTokenizer } from '@salimassili/ai-costguard';
+
+const slackWebhook = process.env.COSTGUARD_SLACK_WEBHOOK;
+let providerCalls = 0;
+
+// Keeps this demo output quiet and deterministic. Production apps can keep the
+// default estimator or register a provider-specific tokenizer.
+registerTokenizer('gpt-4o-mini', (text) => Math.ceil(text.length / 4));
+
+const mockedOpenAI = {
+  chat: {
+    completions: {
+      create: async () => {
+        providerCalls += 1;
+        return {
+          id: 'mocked-provider-response',
+          choices: [{ message: { content: 'This should never execute in the demo.' } }],
+        };
+      },
+    },
+  },
+};
+
+const openai = guard(mockedOpenAI, {
+  budget: 0.0001,
+  scope: { projectId: 'sales-demo', sessionId: 'slack-webhook-block-demo' },
+  webhooks: {
+    slack: slackWebhook,
+    retries: 0,
+    timeoutMs: 1000,
+  },
+});
+
+console.log('AI CostGuard Slack webhook block demo');
+console.log('Scenario: an agent tries to start an expensive model call with almost no budget left.');
+console.log(`Slack alert: ${slackWebhook ? 'enabled from COSTGUARD_SLACK_WEBHOOK' : 'off by default'}`);
+
+try {
+  await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [
+      {
+        role: 'user',
+        content:
+          'Run a large analysis job, summarize every retry, and reserve enough output for a long report.',
+      },
+    ],
+    max_tokens: 800,
+  });
+
+  throw new Error('Expected AI CostGuard to block before the mocked provider ran.');
+} catch (error) {
+  if (!(error instanceof GuardError)) {
+    throw error;
+  }
+
+  console.log('Result: BLOCKED before provider execution');
+  console.log(`Reason: ${error.code}`);
+  console.log(`Estimated avoided spend: $${error.context.estimatedCost.toFixed(6)}`);
+  console.log(`Provider calls executed: ${providerCalls}`);
+  console.log('Webhook URL printed: no');
+}
+
+if (providerCalls !== 0) {
+  throw new Error(`Provider executed ${providerCalls} time(s); expected 0.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salimassili/ai-costguard",
-  "version": "2.1.1",
+  "version": "2.1.4",
   "description": "Local-first runtime safety layer for AI agents that blocks runaway costs, loops, retries, and budget overruns before API calls execute.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,11 +31,11 @@
   "files": [
     "dist",
     "docs/DASHBOARD.md",
-    "docs/INTEGRATIONS.md",
-    "docs/BENCHMARKS.md",
-    "examples/integrations",
-    "benchmarks/run.mjs",
-    "benchmarks/token-accuracy.mjs",
+    "docs/INTEGRATIONS.md",
+    "docs/BENCHMARKS.md",
+    "examples/integrations",
+    "benchmarks/run.mjs",
+    "benchmarks/token-accuracy.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -44,10 +44,10 @@
     "clean": "rimraf dist",
     "build": "npm run clean && tsc",
     "typecheck": "tsc --noEmit",
-    "test": "npm run build && node --test --experimental-test-coverage --test-coverage-include=dist/**/*.js --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=70 \"test/**/*.test.mjs\"",
+    "test": "npm run build && node scripts/run-tests.js",
     "smoke": "node test/smoke-examples.mjs",
-    "benchmark": "node benchmarks/run.mjs",
-    "benchmark:tokens": "node benchmarks/token-accuracy.mjs",
+    "benchmark": "node benchmarks/run.mjs",
+    "benchmark:tokens": "node benchmarks/token-accuracy.mjs",
     "preflight": "node scripts/preflight.js",
     "prepublishOnly": "npm run preflight"
   },