Add model-agnostic prompt token estimator

ts/packages/benchmarks/README.AUTOGEN.md

@@ -3,7 +3,7 @@
 
 <!-- AUTOGEN:DOCS:START -->
 
-<!-- AUTOGEN:DOCS:HASH:sha256=4789b0b546809d399518b84ad3e00f70824d9c558a19931aa499099859de8dd0 -->
+<!-- AUTOGEN:DOCS:HASH:sha256=d44d146be9d637f265637a8290e184cf5485c4152b0a25777e2866945e1874ee -->
 <!-- AUTOGEN:DOCS:SOURCE: ./README.md (hand-written documentation; this file is the AI-generated companion) -->
 
 # @typeagent/benchmarks — AI-generated documentation
@@ -34,7 +34,7 @@ Workspace:
 - [agent-dispatcher](../../packages/dispatcher/dispatcher/README.md)
 - [default-agent-provider](../../packages/defaultAgentProvider/README.md)
 
-External: `commander`, `js-yaml`, `zod`
+External: `commander`, `gpt-tokenizer`, `js-yaml`, `zod`
 
 ### Used by
 
@@ -50,12 +50,12 @@ _None._
 - [./src/core/paths.ts](./src/core/paths.ts)
 - [./src/core/prices.ts](./src/core/prices.ts)
 - [./src/core/rateLimiter.ts](./src/core/rateLimiter.ts)
+- [./src/core/tokenEstimate.ts](./src/core/tokenEstimate.ts)
 - [./src/core/types.ts](./src/core/types.ts)
-- [./src/translationBench/action-parameters-grader.generated.json](./src/translationBench/action-parameters-grader.generated.json)
-- _…and 35 more under `./src/`._
+- _…and 36 more under `./src/`._
 
 ---
 
-_Auto-generated against commit `01feca686ce14ae8b00182f75c305cf40e92c415` on `2026-08-13T03:34:32.783Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/benchmarks docs:verify-links` to spot-check._
+_Auto-generated against commit `ced33869a1369ff7c998a3517bf17bc9739a05e5` on `2026-08-13T05:25:43.204Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/benchmarks docs:verify-links` to spot-check._
 
 <!-- AUTOGEN:DOCS:END -->

ts/packages/benchmarks/package.json

@@ -39,6 +39,7 @@
     "agent-dispatcher": "workspace:*",
     "commander": "^12.1.0",
     "default-agent-provider": "workspace:*",
+    "gpt-tokenizer": "^2.9.0",
     "js-yaml": "^4.3.1",
     "zod": "^4.1.13"
   },

ts/packages/benchmarks/src/core/tokenEstimate.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { countTokens } from "gpt-tokenizer/encoding/o200k_base";
+
+// o200k_base is a model-agnostic approximation of prompt-token cost for every
+// model the benchmark drives (GPT and non-GPT). It backs the rate limiter's
+// pre-flight reservation, which is later settled to actual reported usage; the
+// +5% overhead absorbs cross-tokenizer drift so we never underestimate.
+export const TOKEN_ESTIMATE_OVERHEAD = 0.05;
+
+export function estimatePromptTokens(text: string): number {
+    const base = countTokens(text);
+    return Math.ceil(base * (1 + TOKEN_ESTIMATE_OVERHEAD));
+}

ts/packages/benchmarks/src/index.ts

@@ -6,3 +6,4 @@ export * from "./core/types.js";
 export * from "./core/prices.js";
 export * from "./core/rateLimiter.js";
 export * from "./translationBench/index.js";
+export * from "./core/tokenEstimate.js";

ts/packages/benchmarks/test/tokenEstimate.spec.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { describe, expect, it } from "@jest/globals";
+import { countTokens } from "gpt-tokenizer/encoding/o200k_base";
+
+import {
+    estimatePromptTokens,
+    TOKEN_ESTIMATE_OVERHEAD,
+} from "../src/core/tokenEstimate.js";
+
+describe("core tokenEstimate", () => {
+    it("adds the overhead offset over the raw o200k count", () => {
+        const text = "The quick brown fox jumps over the lazy dog.";
+        const raw = countTokens(text);
+        expect(estimatePromptTokens(text)).toBe(
+            Math.ceil(raw * (1 + TOKEN_ESTIMATE_OVERHEAD)),
+        );
+    });
+
+    it("never underestimates the raw token count", () => {
+        for (const text of ["", "a", "hello world", "x".repeat(2000)]) {
+            expect(estimatePromptTokens(text)).toBeGreaterThanOrEqual(
+                countTokens(text),
+            );
+        }
+    });
+
+    it("returns an integer token budget", () => {
+        const n = estimatePromptTokens(
+            "tokenization produces fractional overhead",
+        );
+        expect(Number.isInteger(n)).toBe(true);
+    });
+});