@fgv/ts-extras 5.1.0-54 → 5.1.0-56

package/lib/packlets/ai-assist/promptCacheRoutingAbHarness.js

@@ -0,0 +1,163 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRoutingAbPrefix = buildRoutingAbPrefix;
+exports.describeRoutingAbUsage = describeRoutingAbUsage;
+exports.runPromptCacheRoutingAbArm = runPromptCacheRoutingAbArm;
+exports.runPromptCacheRoutingAbHarness = runPromptCacheRoutingAbHarness;
+exports.formatRoutingAbVerdict = formatRoutingAbVerdict;
+/**
+ * Pure logic and injectable transport for `perf/promptCacheRoutingAb.js` — the A/B that measures
+ * whether `IAiCacheRequest.cacheKey` actually improves the xAI cache-hit rate (design.md §2's
+ * 2026-09-19 measurement note, and result.md's "gating defect in C3").
+ *
+ * @remarks
+ * Extracted for the same reason as `promptCacheObservabilityHarness.ts`: the verdict this harness
+ * prints (CONFIRMS / MISSES / AMBIGUOUS) "has already been used to justify a merge," per this
+ * stream's follow-up task, and had no test checking it classifies correctly.
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const promptCacheUsageMath_1 = require("./promptCacheUsageMath");
+/**
+ * Builds one arm's stable system prefix. Ported verbatim from the harness's `stablePrefix(arm)`.
+ * `salt` and `arm` both feed the text so the two arms — and two separate runs — never warm each
+ * other's cache.
+ * @internal
+ */
+function buildRoutingAbPrefix(salt, arm) {
+    const lines = [];
+    for (let i = 0; i < 400; i++) {
+        lines.push(`Directive ${salt}-${arm}-${i}: when asked about topic ${i}, respond precisely and cite source ${i}-${i * 7}.`);
+    }
+    return `You are a careful assistant operating under the following fixed policy document.\n\n${lines.join('\n')}`;
+}
+/**
+ * One line describing a usage block. Ported from `describeUsage`, now computing the ratio via
+ * {@link computeCacheUsageRatio} instead of an inline calculation that coalesced a missing
+ * `cachedInputTokens` or `uncachedInputTokens` to `0` (see that function's remarks).
+ * @internal
+ */
+function describeRoutingAbUsage(usage) {
+    if (usage === undefined) {
+        return 'usage absent from response';
+    }
+    const { cachedInputTokens, uncachedInputTokens } = usage;
+    const { totalInputTokens, cachedRatio } = (0, promptCacheUsageMath_1.computeCacheUsageRatio)(usage);
+    if (cachedRatio === undefined) {
+        return `reports=${usage.reports} cached=${cachedInputTokens} uncached=${uncachedInputTokens} (ratio not computable)`;
+    }
+    return `reports=${usage.reports} cached=${cachedInputTokens} of ${totalInputTokens} input (${(0, promptCacheUsageMath_1.formatCacheRatioPercent)(cachedRatio)})`;
+}
+/**
+ * Runs one arm: a cold call, then a warm call sharing the same {@link buildRoutingAbPrefix} system
+ * prompt and differing only in the final user turn — optionally supplying `cacheKey`. Ported from
+ * `runArm`, with the network call injected.
+ * @internal
+ */
+async function runPromptCacheRoutingAbArm(deps, params) {
+    const { descriptor, apiKey, label, salt, arm, cacheKey } = params;
+    const system = buildRoutingAbPrefix(salt, arm);
+    const cache = cacheKey !== undefined ? { cacheKey } : undefined;
+    const call = (content) => deps.callCompletion({
+        descriptor,
+        apiKey,
+        system,
+        messages: [{ role: 'user', content }],
+        cache
+    });
+    const cold = await call('In one sentence, what is directive 12 about?');
+    if (cold.isFailure()) {
+        return (0, ts_utils_1.fail)(`${label}: cold call failed: ${cold.message}`);
+    }
+    // Only the tail differs from the cold call — the prefix is byte-identical.
+    const warm = await call('In one sentence, what is directive 99 about?');
+    if (warm.isFailure()) {
+        return (0, ts_utils_1.fail)(`${label}: warm call failed: ${warm.message}`);
+    }
+    return (0, ts_utils_1.succeed)({ label, coldUsage: cold.value.usage, warmUsage: warm.value.usage });
+}
+/**
+ * Runs both arms of the routing-key A/B and classifies the result.
+ *
+ * @remarks
+ * The verdict compares each arm's **warm** call against the other's — not an arm's own cold vs.
+ * warm call — because the question is whether the routing key changes the warm hit rate relative
+ * to the no-key baseline, exactly as `promptCacheRoutingAb.js`'s original `main()` computed it
+ * (`pct(withoutKey)` / `pct(withKey)`, both taken from each arm's warm response).
+ * @internal
+ */
+async function runPromptCacheRoutingAbHarness(deps, params) {
+    const { descriptor, apiKey, salt } = params;
+    const withoutKeyResult = await runPromptCacheRoutingAbArm(deps, {
+        descriptor,
+        apiKey,
+        label: 'arm 1: WITHOUT cacheKey (behaviour before this change)',
+        salt,
+        arm: 'a'
+    });
+    if (withoutKeyResult.isFailure()) {
+        return (0, ts_utils_1.fail)(withoutKeyResult.message);
+    }
+    const withKeyResult = await runPromptCacheRoutingAbArm(deps, {
+        descriptor,
+        apiKey,
+        label: 'arm 2: WITH cacheKey (this change)',
+        salt,
+        arm: 'b',
+        cacheKey: `routing-ab-${salt}`
+    });
+    if (withKeyResult.isFailure()) {
+        return (0, ts_utils_1.fail)(withKeyResult.message);
+    }
+    const comparison = (0, promptCacheUsageMath_1.compareCacheHitRatios)(withoutKeyResult.value.warmUsage, withKeyResult.value.warmUsage);
+    return (0, ts_utils_1.succeed)({
+        withoutKey: withoutKeyResult.value,
+        withKey: withKeyResult.value,
+        verdict: comparison.verdict,
+        withoutKeyWarmRatio: comparison.baselineRatio,
+        withKeyWarmRatio: comparison.candidateRatio
+    });
+}
+/**
+ * Formats the A/B's closing verdict line(s), matching the original harness's console output.
+ * @internal
+ */
+function formatRoutingAbVerdict(result) {
+    const a = (0, promptCacheUsageMath_1.formatCacheRatioPercent)(result.withoutKeyWarmRatio);
+    const b = (0, promptCacheUsageMath_1.formatCacheRatioPercent)(result.withKeyWarmRatio);
+    switch (result.verdict) {
+        case 'confirms':
+            return (`arm 1 warm ${a} -> arm 2 warm ${b}\n` +
+                'CONFIRMS the prediction: the routing key materially improves the hit rate.');
+        case 'misses':
+            return (`arm 1 warm ${a} -> arm 2 warm ${b}\n` +
+                'MISSES the prediction: arm 2 did not jump. The routing key is not buying what this ' +
+                'change claims — revise the change or the claim, do not re-run for a better number. ' +
+                '(Re-run once with a fresh SALT first, to rule out a TTL-tainted reading.)');
+        case 'ambiguous':
+            return (`arm 1 warm ${a} -> arm 2 warm ${b}\n` +
+                'AMBIGUOUS: arm 1 may have hit by routing luck. Re-run with a fresh SALT.');
+        case 'inconclusive':
+            return 'inconclusive: cache-hit ratio not computable for at least one arm.';
+    }
+}
+//# sourceMappingURL=promptCacheRoutingAbHarness.js.map

package/lib/packlets/ai-assist/promptCacheRoutingAbHarness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCacheRoutingAbHarness.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/promptCacheRoutingAbHarness.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Pure logic and injectable transport for `perf/promptCacheRoutingAb.js` — the A/B that measures\n * whether `IAiCacheRequest.cacheKey` actually improves the xAI cache-hit rate (design.md §2's\n * 2026-09-19 measurement note, and result.md's \"gating defect in C3\").\n *\n * @remarks\n * Extracted for the same reason as `promptCacheObservabilityHarness.ts`: the verdict this harness\n * prints (CONFIRMS / MISSES / AMBIGUOUS) \"has already been used to justify a merge,\" per this\n * stream's follow-up task, and had no test checking it classifies correctly.\n * @packageDocumentation\n */\n\nimport { fail, succeed, type Result } from '@fgv/ts-utils';\n\nimport { type IAiCacheRequest } from './cacheRequest';\nimport { type IProviderCompletionParams } from './completionClient';\nimport { type IAiCompletionResponse, type IAiProviderDescriptor } from './model';\nimport {\n  type CacheHitComparisonVerdict,\n  compareCacheHitRatios,\n  computeCacheUsageRatio,\n  formatCacheRatioPercent\n} from './promptCacheUsageMath';\nimport { type IAiCompletionUsage } from './usageTypes';\n\n/** Injected transport — only the network call needs a live key. @internal */\nexport interface IPromptCacheRoutingAbDeps {\n  readonly callCompletion: (params: IProviderCompletionParams) => Promise<Result<IAiCompletionResponse>>;\n}\n\n/**\n * Builds one arm's stable system prefix. Ported verbatim from the harness's `stablePrefix(arm)`.\n * `salt` and `arm` both feed the text so the two arms — and two separate runs — never warm each\n * other's cache.\n * @internal\n */\nexport function buildRoutingAbPrefix(salt: string, arm: string): string {\n  const lines: string[] = [];\n  for (let i = 0; i < 400; i++) {\n    lines.push(\n      `Directive ${salt}-${arm}-${i}: when asked about topic ${i}, respond precisely and cite source ${i}-${\n        i * 7\n      }.`\n    );\n  }\n  return `You are a careful assistant operating under the following fixed policy document.\\n\\n${lines.join(\n    '\\n'\n  )}`;\n}\n\n/**\n * One line describing a usage block. Ported from `describeUsage`, now computing the ratio via\n * {@link computeCacheUsageRatio} instead of an inline calculation that coalesced a missing\n * `cachedInputTokens` or `uncachedInputTokens` to `0` (see that function's remarks).\n * @internal\n */\nexport function describeRoutingAbUsage(usage: IAiCompletionUsage | undefined): string {\n  if (usage === undefined) {\n    return 'usage absent from response';\n  }\n  const { cachedInputTokens, uncachedInputTokens } = usage;\n  const { totalInputTokens, cachedRatio } = computeCacheUsageRatio(usage);\n  if (cachedRatio === undefined) {\n    return `reports=${usage.reports} cached=${cachedInputTokens} uncached=${uncachedInputTokens} (ratio not computable)`;\n  }\n  return `reports=${\n    usage.reports\n  } cached=${cachedInputTokens} of ${totalInputTokens} input (${formatCacheRatioPercent(cachedRatio)})`;\n}\n\n/** One arm's cold-then-warm outcome. @internal */\nexport interface IPromptCacheRoutingAbArmResult {\n  readonly label: string;\n  readonly coldUsage: IAiCompletionUsage | undefined;\n  readonly warmUsage: IAiCompletionUsage | undefined;\n}\n\n/**\n * Runs one arm: a cold call, then a warm call sharing the same {@link buildRoutingAbPrefix} system\n * prompt and differing only in the final user turn — optionally supplying `cacheKey`. Ported from\n * `runArm`, with the network call injected.\n * @internal\n */\nexport async function runPromptCacheRoutingAbArm(\n  deps: IPromptCacheRoutingAbDeps,\n  params: {\n    readonly descriptor: IAiProviderDescriptor;\n    readonly apiKey: string;\n    readonly label: string;\n    readonly salt: string;\n    readonly arm: string;\n    readonly cacheKey?: string;\n  }\n): Promise<Result<IPromptCacheRoutingAbArmResult>> {\n  const { descriptor, apiKey, label, salt, arm, cacheKey } = params;\n  const system = buildRoutingAbPrefix(salt, arm);\n  const cache: IAiCacheRequest | undefined = cacheKey !== undefined ? { cacheKey } : undefined;\n  const call = (content: string): Promise<Result<IAiCompletionResponse>> =>\n    deps.callCompletion({\n      descriptor,\n      apiKey,\n      system,\n      messages: [{ role: 'user', content }],\n      cache\n    });\n\n  const cold = await call('In one sentence, what is directive 12 about?');\n  if (cold.isFailure()) {\n    return fail(`${label}: cold call failed: ${cold.message}`);\n  }\n\n  // Only the tail differs from the cold call — the prefix is byte-identical.\n  const warm = await call('In one sentence, what is directive 99 about?');\n  if (warm.isFailure()) {\n    return fail(`${label}: warm call failed: ${warm.message}`);\n  }\n\n  return succeed({ label, coldUsage: cold.value.usage, warmUsage: warm.value.usage });\n}\n\n/** The full A/B: both arms' results and the routing-key verdict. @internal */\nexport interface IPromptCacheRoutingAbResult {\n  readonly withoutKey: IPromptCacheRoutingAbArmResult;\n  readonly withKey: IPromptCacheRoutingAbArmResult;\n  /** Baseline = `withoutKey`'s warm call; candidate = `withKey`'s warm call. */\n  readonly verdict: CacheHitComparisonVerdict;\n  readonly withoutKeyWarmRatio: number | undefined;\n  readonly withKeyWarmRatio: number | undefined;\n}\n\n/**\n * Runs both arms of the routing-key A/B and classifies the result.\n *\n * @remarks\n * The verdict compares each arm's **warm** call against the other's — not an arm's own cold vs.\n * warm call — because the question is whether the routing key changes the warm hit rate relative\n * to the no-key baseline, exactly as `promptCacheRoutingAb.js`'s original `main()` computed it\n * (`pct(withoutKey)` / `pct(withKey)`, both taken from each arm's warm response).\n * @internal\n */\nexport async function runPromptCacheRoutingAbHarness(\n  deps: IPromptCacheRoutingAbDeps,\n  params: {\n    readonly descriptor: IAiProviderDescriptor;\n    readonly apiKey: string;\n    readonly salt: string;\n  }\n): Promise<Result<IPromptCacheRoutingAbResult>> {\n  const { descriptor, apiKey, salt } = params;\n\n  const withoutKeyResult = await runPromptCacheRoutingAbArm(deps, {\n    descriptor,\n    apiKey,\n    label: 'arm 1: WITHOUT cacheKey (behaviour before this change)',\n    salt,\n    arm: 'a'\n  });\n  if (withoutKeyResult.isFailure()) {\n    return fail(withoutKeyResult.message);\n  }\n\n  const withKeyResult = await runPromptCacheRoutingAbArm(deps, {\n    descriptor,\n    apiKey,\n    label: 'arm 2: WITH cacheKey (this change)',\n    salt,\n    arm: 'b',\n    cacheKey: `routing-ab-${salt}`\n  });\n  if (withKeyResult.isFailure()) {\n    return fail(withKeyResult.message);\n  }\n\n  const comparison = compareCacheHitRatios(withoutKeyResult.value.warmUsage, withKeyResult.value.warmUsage);\n  return succeed({\n    withoutKey: withoutKeyResult.value,\n    withKey: withKeyResult.value,\n    verdict: comparison.verdict,\n    withoutKeyWarmRatio: comparison.baselineRatio,\n    withKeyWarmRatio: comparison.candidateRatio\n  });\n}\n\n/**\n * Formats the A/B's closing verdict line(s), matching the original harness's console output.\n * @internal\n */\nexport function formatRoutingAbVerdict(result: IPromptCacheRoutingAbResult): string {\n  const a = formatCacheRatioPercent(result.withoutKeyWarmRatio);\n  const b = formatCacheRatioPercent(result.withKeyWarmRatio);\n  switch (result.verdict) {\n    case 'confirms':\n      return (\n        `arm 1 warm ${a} -> arm 2 warm ${b}\\n` +\n        'CONFIRMS the prediction: the routing key materially improves the hit rate.'\n      );\n    case 'misses':\n      return (\n        `arm 1 warm ${a} -> arm 2 warm ${b}\\n` +\n        'MISSES the prediction: arm 2 did not jump. The routing key is not buying what this ' +\n        'change claims — revise the change or the claim, do not re-run for a better number. ' +\n        '(Re-run once with a fresh SALT first, to rule out a TTL-tainted reading.)'\n      );\n    case 'ambiguous':\n      return (\n        `arm 1 warm ${a} -> arm 2 warm ${b}\\n` +\n        'AMBIGUOUS: arm 1 may have hit by routing luck. Re-run with a fresh SALT.'\n      );\n    case 'inconclusive':\n      return 'inconclusive: cache-hit ratio not computable for at least one arm.';\n  }\n}\n"]}

package/lib/packlets/ai-assist/promptCacheUsageMath.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Cache-hit ratio arithmetic and cold/warm verdict classification shared by the two prompt-cache
+ * measurement harnesses under `perf/` (`promptCacheObservability.js`,
+ * `promptCacheRoutingAb.js`).
+ *
+ * @remarks
+ * Extracted per design.md §8's addendum ("Preferred remedy: keep `perf/` placement, add the
+ * seam") and `TESTING_GUIDELINES.md` § "Measurement Harnesses" — before this module existed,
+ * both harnesses computed this math inline, disagreed with each other on how to treat missing or
+ * zero-valued fields, and had no test of either version. See {@link computeCacheUsageRatio} and
+ * {@link compareCacheHitRatios} for what each inline version did and what changed.
+ * @packageDocumentation
+ */
+import { type IAiCompletionUsage } from './usageTypes';
+/**
+ * A cache-hit ratio derived from one completion's usage block.
+ * @internal
+ */
+export interface ICacheUsageRatio {
+    /** `cachedInputTokens + uncachedInputTokens`, when both are known. `0` is a valid value. */
+    readonly totalInputTokens: number | undefined;
+    /**
+     * `cachedInputTokens / totalInputTokens`, in `[0, 1]`.
+     *
+     * @remarks
+     * `undefined` whenever the ratio is not a meaningful number: the usage block itself is absent,
+     * either token count is unreported, or the total is `0` (there is no input to have a ratio
+     * over). Per design.md's governing rule R-c, unknown is reported as unknown, never defaulted to
+     * a number.
+     */
+    readonly cachedRatio: number | undefined;
+}
+/**
+ * Computes {@link ICacheUsageRatio} from a completion's usage block.
+ *
+ * @remarks
+ * The two harnesses this was extracted from each computed this ratio independently, inline, and
+ * disagreed with each other — and with this function — on edge cases that neither had a test for:
+ *
+ * - `promptCacheObservability.js`'s `summarizeUsage` divided by a `0` total without a guard,
+ *   printing `NaN%` whenever a response reported `uncachedInputTokens: 0, cachedInputTokens: 0`.
+ * - `promptCacheRoutingAb.js`'s inline `pct()` coalesced a missing `cachedInputTokens` **or**
+ *   `uncachedInputTokens` to `0` (`(u.cachedInputTokens ?? 0) + (u.uncachedInputTokens ?? 0)`,
+ *   `100 * (u.cachedInputTokens ?? 0) / total`) — and which field was missing decided the
+ *   direction of the fabrication: a missing `cachedInputTokens` fabricated a false low ratio
+ *   (feeding a false `MISSES`), while a missing `uncachedInputTokens` fabricated a false **100%**
+ *   (feeding a false `CONFIRMS`) — this is not a one-directional bug.
+ * - `promptCacheRoutingAb.js`'s `describeUsage` also special-cased a *genuinely reported*
+ *   `cachedInputTokens: 0, uncachedInputTokens: 0` (both fields present) as `0.0%`, and the
+ *   verdict's `pct()` scored that same input as a hard `0`, feeding `MISSES`. This function scores
+ *   a real zero-input total as not computable, same as observability's zero-total case above —
+ *   there were no bytes to have a ratio over, so `0.0%` claims more than the data supports.
+ *
+ * All three are fixed here rather than reproduced: this function returns `undefined` — never a
+ * fabricated number — whenever the ratio cannot honestly be computed, matching the same
+ * unknown-is-unknown rule the normalized {@link IAiCompletionUsage} type itself follows.
+ * @internal
+ */
+export declare function computeCacheUsageRatio(usage: IAiCompletionUsage | undefined): ICacheUsageRatio;
+/**
+ * Formats a cache-hit ratio as a percentage string, or `'n/a'` when {@link computeCacheUsageRatio}
+ * could not compute one.
+ * @internal
+ */
+export declare function formatCacheRatioPercent(ratio: number | undefined): string;
+/**
+ * Verdict for a baseline/candidate pair of cache-hit ratios.
+ *
+ * @remarks
+ * `'inconclusive'` has no equivalent in the original inline logic — see {@link compareCacheHitRatios}.
+ * @internal
+ */
+export type CacheHitComparisonVerdict = 'confirms' | 'misses' | 'ambiguous' | 'inconclusive';
+/** A candidate ratio at or below this percentage cannot count as a cache hit. @internal */
+export declare const CACHE_HIT_FLOOR_PERCENT: number;
+/**
+ * The candidate ratio must clear the baseline ratio by at least this multiple to be attributed to
+ * something other than routing luck.
+ * @internal
+ */
+export declare const CACHE_HIT_MIN_IMPROVEMENT_FACTOR: number;
+/** The outcome of comparing a baseline usage block against a candidate one. @internal */
+export interface ICacheHitComparison {
+    readonly baselineRatio: number | undefined;
+    readonly candidateRatio: number | undefined;
+    readonly verdict: CacheHitComparisonVerdict;
+}
+/**
+ * Classifies a baseline/candidate pair of usage blocks by their cache-hit ratio.
+ *
+ * @remarks
+ * Ported from `promptCacheRoutingAb.js`'s inline verdict —
+ * `if (b > 50 && b > a * 5) CONFIRMS; else if (b <= 50) MISSES; else AMBIGUOUS` — now driven off
+ * {@link computeCacheUsageRatio} rather than a hand-rolled `pct()` that coalesced missing fields
+ * to `0`. `'inconclusive'` is new: it is what an unclassifiable ratio (baseline or candidate
+ * `undefined`) reports now, in place of the original's silent `0`, which could otherwise produce
+ * a false `MISSES` verdict from data that never said "no cache hit" — it said nothing at all.
+ *
+ * The same classification also drives `promptCacheObservability.js`'s cold/warm comparison
+ * (baseline = cold call, candidate = warm call), which previously had no computed verdict of any
+ * kind — only two printed summaries and a static reminder for a human to judge by eye.
+ * @internal
+ */
+export declare function compareCacheHitRatios(baseline: IAiCompletionUsage | undefined, candidate: IAiCompletionUsage | undefined): ICacheHitComparison;
+//# sourceMappingURL=promptCacheUsageMath.d.ts.map

package/lib/packlets/ai-assist/promptCacheUsageMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCacheUsageMath.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/promptCacheUsageMath.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,GAAG,gBAAgB,CA8B9F;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEzE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,cAAc,CAAC;AAE7F,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,EAAE,MAAW,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAU,CAAC;AAE1D,yFAAyF;AACzF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,SAAS,EAAE,kBAAkB,GAAG,SAAS,GACxC,mBAAmB,CAkBrB"}

package/lib/packlets/ai-assist/promptCacheUsageMath.js

@@ -0,0 +1,130 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_HIT_MIN_IMPROVEMENT_FACTOR = exports.CACHE_HIT_FLOOR_PERCENT = void 0;
+exports.computeCacheUsageRatio = computeCacheUsageRatio;
+exports.formatCacheRatioPercent = formatCacheRatioPercent;
+exports.compareCacheHitRatios = compareCacheHitRatios;
+/**
+ * Computes {@link ICacheUsageRatio} from a completion's usage block.
+ *
+ * @remarks
+ * The two harnesses this was extracted from each computed this ratio independently, inline, and
+ * disagreed with each other — and with this function — on edge cases that neither had a test for:
+ *
+ * - `promptCacheObservability.js`'s `summarizeUsage` divided by a `0` total without a guard,
+ *   printing `NaN%` whenever a response reported `uncachedInputTokens: 0, cachedInputTokens: 0`.
+ * - `promptCacheRoutingAb.js`'s inline `pct()` coalesced a missing `cachedInputTokens` **or**
+ *   `uncachedInputTokens` to `0` (`(u.cachedInputTokens ?? 0) + (u.uncachedInputTokens ?? 0)`,
+ *   `100 * (u.cachedInputTokens ?? 0) / total`) — and which field was missing decided the
+ *   direction of the fabrication: a missing `cachedInputTokens` fabricated a false low ratio
+ *   (feeding a false `MISSES`), while a missing `uncachedInputTokens` fabricated a false **100%**
+ *   (feeding a false `CONFIRMS`) — this is not a one-directional bug.
+ * - `promptCacheRoutingAb.js`'s `describeUsage` also special-cased a *genuinely reported*
+ *   `cachedInputTokens: 0, uncachedInputTokens: 0` (both fields present) as `0.0%`, and the
+ *   verdict's `pct()` scored that same input as a hard `0`, feeding `MISSES`. This function scores
+ *   a real zero-input total as not computable, same as observability's zero-total case above —
+ *   there were no bytes to have a ratio over, so `0.0%` claims more than the data supports.
+ *
+ * All three are fixed here rather than reproduced: this function returns `undefined` — never a
+ * fabricated number — whenever the ratio cannot honestly be computed, matching the same
+ * unknown-is-unknown rule the normalized {@link IAiCompletionUsage} type itself follows.
+ * @internal
+ */
+function computeCacheUsageRatio(usage) {
+    if (usage === undefined) {
+        return { totalInputTokens: undefined, cachedRatio: undefined };
+    }
+    const { cachedInputTokens, uncachedInputTokens } = usage;
+    if (cachedInputTokens === undefined || uncachedInputTokens === undefined) {
+        return { totalInputTokens: undefined, cachedRatio: undefined };
+    }
+    // A *present but out-of-range* component is not the same hazard as an absent one, and the
+    // absent case above does not cover it. A token count cannot be negative or non-finite, so one
+    // that is means the usage block is malformed — and computing anyway yields a ratio outside
+    // [0, 1] that this function's own contract promises cannot happen. That ratio then reaches
+    // `compareCacheHitRatios`, where a skewed baseline can fabricate a favourable verdict from an
+    // unremarkable candidate. Reachable from real wire data, not just hand-built input:
+    // `usageNormalization.ts` derives `uncachedInputTokens` as `promptTokens - cachedInputTokens`
+    // on both the Chat Completions and Responses routes with no guard, so any provider reporting
+    // `cached_tokens > prompt_tokens` produces exactly this shape.
+    if (!Number.isFinite(cachedInputTokens) ||
+        !Number.isFinite(uncachedInputTokens) ||
+        cachedInputTokens < 0 ||
+        uncachedInputTokens < 0) {
+        return { totalInputTokens: undefined, cachedRatio: undefined };
+    }
+    const totalInputTokens = cachedInputTokens + uncachedInputTokens;
+    if (totalInputTokens <= 0) {
+        return { totalInputTokens, cachedRatio: undefined };
+    }
+    return { totalInputTokens, cachedRatio: cachedInputTokens / totalInputTokens };
+}
+/**
+ * Formats a cache-hit ratio as a percentage string, or `'n/a'` when {@link computeCacheUsageRatio}
+ * could not compute one.
+ * @internal
+ */
+function formatCacheRatioPercent(ratio) {
+    return ratio === undefined ? 'n/a' : `${(ratio * 100).toFixed(1)}%`;
+}
+/** A candidate ratio at or below this percentage cannot count as a cache hit. @internal */
+exports.CACHE_HIT_FLOOR_PERCENT = 50;
+/**
+ * The candidate ratio must clear the baseline ratio by at least this multiple to be attributed to
+ * something other than routing luck.
+ * @internal
+ */
+exports.CACHE_HIT_MIN_IMPROVEMENT_FACTOR = 5;
+/**
+ * Classifies a baseline/candidate pair of usage blocks by their cache-hit ratio.
+ *
+ * @remarks
+ * Ported from `promptCacheRoutingAb.js`'s inline verdict —
+ * `if (b > 50 && b > a * 5) CONFIRMS; else if (b <= 50) MISSES; else AMBIGUOUS` — now driven off
+ * {@link computeCacheUsageRatio} rather than a hand-rolled `pct()` that coalesced missing fields
+ * to `0`. `'inconclusive'` is new: it is what an unclassifiable ratio (baseline or candidate
+ * `undefined`) reports now, in place of the original's silent `0`, which could otherwise produce
+ * a false `MISSES` verdict from data that never said "no cache hit" — it said nothing at all.
+ *
+ * The same classification also drives `promptCacheObservability.js`'s cold/warm comparison
+ * (baseline = cold call, candidate = warm call), which previously had no computed verdict of any
+ * kind — only two printed summaries and a static reminder for a human to judge by eye.
+ * @internal
+ */
+function compareCacheHitRatios(baseline, candidate) {
+    const baselineRatio = computeCacheUsageRatio(baseline).cachedRatio;
+    const candidateRatio = computeCacheUsageRatio(candidate).cachedRatio;
+    if (baselineRatio === undefined || candidateRatio === undefined) {
+        return { baselineRatio, candidateRatio, verdict: 'inconclusive' };
+    }
+    const baselinePercent = baselineRatio * 100;
+    const candidatePercent = candidateRatio * 100;
+    if (candidatePercent > exports.CACHE_HIT_FLOOR_PERCENT &&
+        candidatePercent > baselinePercent * exports.CACHE_HIT_MIN_IMPROVEMENT_FACTOR) {
+        return { baselineRatio, candidateRatio, verdict: 'confirms' };
+    }
+    if (candidatePercent <= exports.CACHE_HIT_FLOOR_PERCENT) {
+        return { baselineRatio, candidateRatio, verdict: 'misses' };
+    }
+    return { baselineRatio, candidateRatio, verdict: 'ambiguous' };
+}
+//# sourceMappingURL=promptCacheUsageMath.js.map

package/lib/packlets/ai-assist/promptCacheUsageMath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCacheUsageMath.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/promptCacheUsageMath.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Cache-hit ratio arithmetic and cold/warm verdict classification shared by the two prompt-cache\n * measurement harnesses under `perf/` (`promptCacheObservability.js`,\n * `promptCacheRoutingAb.js`).\n *\n * @remarks\n * Extracted per design.md §8's addendum (\"Preferred remedy: keep `perf/` placement, add the\n * seam\") and `TESTING_GUIDELINES.md` § \"Measurement Harnesses\" — before this module existed,\n * both harnesses computed this math inline, disagreed with each other on how to treat missing or\n * zero-valued fields, and had no test of either version. See {@link computeCacheUsageRatio} and\n * {@link compareCacheHitRatios} for what each inline version did and what changed.\n * @packageDocumentation\n */\n\nimport { type IAiCompletionUsage } from './usageTypes';\n\n/**\n * A cache-hit ratio derived from one completion's usage block.\n * @internal\n */\nexport interface ICacheUsageRatio {\n  /** `cachedInputTokens + uncachedInputTokens`, when both are known. `0` is a valid value. */\n  readonly totalInputTokens: number | undefined;\n  /**\n   * `cachedInputTokens / totalInputTokens`, in `[0, 1]`.\n   *\n   * @remarks\n   * `undefined` whenever the ratio is not a meaningful number: the usage block itself is absent,\n   * either token count is unreported, or the total is `0` (there is no input to have a ratio\n   * over). Per design.md's governing rule R-c, unknown is reported as unknown, never defaulted to\n   * a number.\n   */\n  readonly cachedRatio: number | undefined;\n}\n\n/**\n * Computes {@link ICacheUsageRatio} from a completion's usage block.\n *\n * @remarks\n * The two harnesses this was extracted from each computed this ratio independently, inline, and\n * disagreed with each other — and with this function — on edge cases that neither had a test for:\n *\n * - `promptCacheObservability.js`'s `summarizeUsage` divided by a `0` total without a guard,\n *   printing `NaN%` whenever a response reported `uncachedInputTokens: 0, cachedInputTokens: 0`.\n * - `promptCacheRoutingAb.js`'s inline `pct()` coalesced a missing `cachedInputTokens` **or**\n *   `uncachedInputTokens` to `0` (`(u.cachedInputTokens ?? 0) + (u.uncachedInputTokens ?? 0)`,\n *   `100 * (u.cachedInputTokens ?? 0) / total`) — and which field was missing decided the\n *   direction of the fabrication: a missing `cachedInputTokens` fabricated a false low ratio\n *   (feeding a false `MISSES`), while a missing `uncachedInputTokens` fabricated a false **100%**\n *   (feeding a false `CONFIRMS`) — this is not a one-directional bug.\n * - `promptCacheRoutingAb.js`'s `describeUsage` also special-cased a *genuinely reported*\n *   `cachedInputTokens: 0, uncachedInputTokens: 0` (both fields present) as `0.0%`, and the\n *   verdict's `pct()` scored that same input as a hard `0`, feeding `MISSES`. This function scores\n *   a real zero-input total as not computable, same as observability's zero-total case above —\n *   there were no bytes to have a ratio over, so `0.0%` claims more than the data supports.\n *\n * All three are fixed here rather than reproduced: this function returns `undefined` — never a\n * fabricated number — whenever the ratio cannot honestly be computed, matching the same\n * unknown-is-unknown rule the normalized {@link IAiCompletionUsage} type itself follows.\n * @internal\n */\nexport function computeCacheUsageRatio(usage: IAiCompletionUsage | undefined): ICacheUsageRatio {\n  if (usage === undefined) {\n    return { totalInputTokens: undefined, cachedRatio: undefined };\n  }\n  const { cachedInputTokens, uncachedInputTokens } = usage;\n  if (cachedInputTokens === undefined || uncachedInputTokens === undefined) {\n    return { totalInputTokens: undefined, cachedRatio: undefined };\n  }\n  // A *present but out-of-range* component is not the same hazard as an absent one, and the\n  // absent case above does not cover it. A token count cannot be negative or non-finite, so one\n  // that is means the usage block is malformed — and computing anyway yields a ratio outside\n  // [0, 1] that this function's own contract promises cannot happen. That ratio then reaches\n  // `compareCacheHitRatios`, where a skewed baseline can fabricate a favourable verdict from an\n  // unremarkable candidate. Reachable from real wire data, not just hand-built input:\n  // `usageNormalization.ts` derives `uncachedInputTokens` as `promptTokens - cachedInputTokens`\n  // on both the Chat Completions and Responses routes with no guard, so any provider reporting\n  // `cached_tokens > prompt_tokens` produces exactly this shape.\n  if (\n    !Number.isFinite(cachedInputTokens) ||\n    !Number.isFinite(uncachedInputTokens) ||\n    cachedInputTokens < 0 ||\n    uncachedInputTokens < 0\n  ) {\n    return { totalInputTokens: undefined, cachedRatio: undefined };\n  }\n  const totalInputTokens = cachedInputTokens + uncachedInputTokens;\n  if (totalInputTokens <= 0) {\n    return { totalInputTokens, cachedRatio: undefined };\n  }\n  return { totalInputTokens, cachedRatio: cachedInputTokens / totalInputTokens };\n}\n\n/**\n * Formats a cache-hit ratio as a percentage string, or `'n/a'` when {@link computeCacheUsageRatio}\n * could not compute one.\n * @internal\n */\nexport function formatCacheRatioPercent(ratio: number | undefined): string {\n  return ratio === undefined ? 'n/a' : `${(ratio * 100).toFixed(1)}%`;\n}\n\n/**\n * Verdict for a baseline/candidate pair of cache-hit ratios.\n *\n * @remarks\n * `'inconclusive'` has no equivalent in the original inline logic — see {@link compareCacheHitRatios}.\n * @internal\n */\nexport type CacheHitComparisonVerdict = 'confirms' | 'misses' | 'ambiguous' | 'inconclusive';\n\n/** A candidate ratio at or below this percentage cannot count as a cache hit. @internal */\nexport const CACHE_HIT_FLOOR_PERCENT: number = 50;\n\n/**\n * The candidate ratio must clear the baseline ratio by at least this multiple to be attributed to\n * something other than routing luck.\n * @internal\n */\nexport const CACHE_HIT_MIN_IMPROVEMENT_FACTOR: number = 5;\n\n/** The outcome of comparing a baseline usage block against a candidate one. @internal */\nexport interface ICacheHitComparison {\n  readonly baselineRatio: number | undefined;\n  readonly candidateRatio: number | undefined;\n  readonly verdict: CacheHitComparisonVerdict;\n}\n\n/**\n * Classifies a baseline/candidate pair of usage blocks by their cache-hit ratio.\n *\n * @remarks\n * Ported from `promptCacheRoutingAb.js`'s inline verdict —\n * `if (b > 50 && b > a * 5) CONFIRMS; else if (b <= 50) MISSES; else AMBIGUOUS` — now driven off\n * {@link computeCacheUsageRatio} rather than a hand-rolled `pct()` that coalesced missing fields\n * to `0`. `'inconclusive'` is new: it is what an unclassifiable ratio (baseline or candidate\n * `undefined`) reports now, in place of the original's silent `0`, which could otherwise produce\n * a false `MISSES` verdict from data that never said \"no cache hit\" — it said nothing at all.\n *\n * The same classification also drives `promptCacheObservability.js`'s cold/warm comparison\n * (baseline = cold call, candidate = warm call), which previously had no computed verdict of any\n * kind — only two printed summaries and a static reminder for a human to judge by eye.\n * @internal\n */\nexport function compareCacheHitRatios(\n  baseline: IAiCompletionUsage | undefined,\n  candidate: IAiCompletionUsage | undefined\n): ICacheHitComparison {\n  const baselineRatio = computeCacheUsageRatio(baseline).cachedRatio;\n  const candidateRatio = computeCacheUsageRatio(candidate).cachedRatio;\n  if (baselineRatio === undefined || candidateRatio === undefined) {\n    return { baselineRatio, candidateRatio, verdict: 'inconclusive' };\n  }\n  const baselinePercent = baselineRatio * 100;\n  const candidatePercent = candidateRatio * 100;\n  if (\n    candidatePercent > CACHE_HIT_FLOOR_PERCENT &&\n    candidatePercent > baselinePercent * CACHE_HIT_MIN_IMPROVEMENT_FACTOR\n  ) {\n    return { baselineRatio, candidateRatio, verdict: 'confirms' };\n  }\n  if (candidatePercent <= CACHE_HIT_FLOOR_PERCENT) {\n    return { baselineRatio, candidateRatio, verdict: 'misses' };\n  }\n  return { baselineRatio, candidateRatio, verdict: 'ambiguous' };\n}\n"]}

package/lib/packlets/ai-assist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/registry.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AAEH,OAAO,EAAQ,MAAM,EAAW,MAAM,eAAe,CAAC;AAEtD,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAE3B,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAkT7E;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,YAAY,CAAsC,CAAC;AAE9F;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,aAAa,CAAC,qBAAqB,CAAC,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAM/E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAElF;AAsCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,MAAM,GACd,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAE5E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,MAAM,GACd,6BAA6B,GAAG,SAAS,CAE3C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAEnF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,MAAM,GACd,2BAA2B,GAAG,SAAS,CAEzC;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,wBAyD7C,CAAC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/registry.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AAEH,OAAO,EAAQ,MAAM,EAAW,MAAM,eAAe,CAAC;AAEtD,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAE3B,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAgT7E;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,YAAY,CAAsC,CAAC;AAE9F;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,aAAa,CAAC,qBAAqB,CAAC,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAM/E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAElF;AAsCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,MAAM,GACd,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAE5E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,MAAM,GACd,6BAA6B,GAAG,SAAS,CAE3C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAEnF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,MAAM,GACd,2BAA2B,GAAG,SAAS,CAEzC;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,wBAyD7C,CAAC"}

package/lib/packlets/ai-assist/registry.js

@@ -53,8 +53,7 @@ const BUILTIN_PROVIDERS = [
         supportedTools: [],
         corsRestricted: false,
         streamingCorsRestricted: false,
-        acceptsImageInput: false,
-        thinkingMode: 'unsupported'
+        acceptsImageInput: false
     },
     {
         id: 'anthropic',
@@ -81,7 +80,6 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: true,
-        thinkingMode: 'optional',
         // Claude 5 family requires the adaptive thinking wire shape (thinking.type: 'adaptive' +
         // output_config.effort) and 400s on the legacy thinking.type: 'enabled' + budget_tokens
         // shape; see AiAssist.isAdaptiveThinkingModel.
@@ -116,10 +114,16 @@ const BUILTIN_PROVIDERS = [
             '@google-gemini:embedding': 'gemini-embedding-001' // NOT deprecated — aliased for uniformity only
         },
         supportedTools: ['web_search'],
+        // `generateContent` HTTP-400s (INVALID_ARGUMENT) when built-in grounding
+        // (`web_search` → `google_search`) and `function_declarations` are combined in
+        // one request. The only descriptor in the registry that declares an exclusion;
+        // keep it that way deliberately — a new entry here changes what a host gets
+        // back without the host changing anything, so it wants the same evidence a
+        // capability claim wants.
+        serverToolsExclusiveWithClientTools: ['web_search'],
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: true,
-        thinkingMode: 'optional',
         // Gemini carries the constraint inside `generationConfig`
         // (responseMimeType + responseSchema), uniform across the family.
         structuredOutput: [{ modelPrefix: '', format: 'gemini-response-schema' }],
@@ -156,8 +160,7 @@ const BUILTIN_PROVIDERS = [
         supportedTools: [],
         corsRestricted: false,
         streamingCorsRestricted: false,
-        acceptsImageInput: false,
-        thinkingMode: 'unsupported'
+        acceptsImageInput: false
     },
     {
         id: 'mistral',
@@ -171,7 +174,6 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: false,
-        thinkingMode: 'unsupported',
         structuredOutput: [{ modelPrefix: '', format: 'openai-json-schema' }],
         embedding: [{ modelPrefix: '', format: 'openai-embeddings' }]
     },
@@ -187,7 +189,6 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: false,
-        thinkingMode: 'unsupported',
         embedding: [{ modelPrefix: '', format: 'openai-embeddings' }]
     },
     {
@@ -221,7 +222,6 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: true,
-        thinkingMode: 'optional',
         responsesOnlyModelPrefixes: ['gpt-5.5-pro'],
         // Declared once for the whole line. The Chat-Completions-vs-Responses split is
         // NOT declared here on purpose: the route depends on whether the call carries
@@ -273,7 +273,6 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: false,
-        thinkingMode: 'unsupported',
         embedding: [{ modelPrefix: '', format: 'openai-embeddings' }]
     },
     {
@@ -298,7 +297,6 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: true,
         streamingCorsRestricted: true,
         acceptsImageInput: true,
-        thinkingMode: 'optional',
         structuredOutput: [{ modelPrefix: '', format: 'openai-json-schema' }],
         imageGeneration: [
             {