@kolisachint/hoocode-agent 0.5.2 → 0.5.4

package/dist/core/capabilities/deferral.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Is deferring a tool's schema actually worth it?
+ *
+ * §6.3 said the threshold should be measurable rather than asserted, and until
+ * now it was neither. The question turns out not to be "how many tokens do the
+ * schemas cost" — `--print-token-surface` already answered that — but a
+ * trade-off with a term nobody had priced:
+ *
+ *   Deferring withholds D tokens of schema from every request. But those tokens
+ *   would have sat in the *cached* prefix, so what deferral saves per request is
+ *   D at the cache-read rate, not at full price — an order of magnitude less
+ *   than it looks. And the moment the model resolves a deferred tool, the
+ *   harness adds it to `tools`, which renders at position 0 and invalidates the
+ *   whole prefix P — so the next request pays P at the cache-*write* rate
+ *   instead of the cache-read rate it would otherwise have paid.
+ *
+ * Break-even is therefore the number of requests before the first resolve:
+ *
+ *   N = P × (cacheWrite − cacheRead) / (D × cacheRead)
+ *
+ * The counterintuitive consequence is worth stating plainly: **P grows with the
+ * conversation, D does not.** Deferral gets *worse* the longer a session runs,
+ * which is the opposite of the intuition that motivated it.
+ *
+ * See docs/plugin-system-architecture.md §6.3 and §8.6 item 6.
+ */
+/** Per-million-token prices, as carried on a model. */
+export interface TokenPrices {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+export interface DeferralInput {
+    /** Tokens of schema that would be withheld (the deferrable tools). */
+    deferredTokens: number;
+    /**
+     * Tokens in the cached prefix a resolve would invalidate: system prompt plus
+     * every tool schema, and in a live session the conversation too. Callers that
+     * only know the startup surface are supplying a floor — see `prefixIsFloor`.
+     */
+    prefixTokens: number;
+    prices: TokenPrices;
+}
+export type DeferralVerdict = {
+    kind: "no-cache";
+    reason: string;
+} | {
+    kind: "nothing-deferred";
+    reason: string;
+} | {
+    kind: "unpriced";
+    reason: string;
+} | {
+    kind: "break-even";
+    requestsBeforeResolve: number;
+    savingPerRequest: number;
+    resolvePenalty: number;
+};
+/**
+ * Price the deferral trade-off for one model.
+ *
+ * Deliberately returns a discriminated verdict rather than a bare number: three
+ * of the four outcomes mean "the break-even question does not apply here", and
+ * collapsing them into a number would invite reading 0 or Infinity as an answer.
+ */
+export declare function analyzeDeferral(input: DeferralInput): DeferralVerdict;
+/**
+ * Render the verdict for `--print-token-surface`.
+ *
+ * `prefixIsFloor` marks the common case where the caller measured the startup
+ * surface only. The number is then a lower bound in the direction that matters:
+ * the real prefix is larger, so the real break-even is higher and deferral looks
+ * worse than printed, never better.
+ */
+export declare function formatDeferral(verdict: DeferralVerdict, options?: {
+    prefixIsFloor?: boolean;
+}): string;
+//# sourceMappingURL=deferral.d.ts.map

package/dist/core/capabilities/deferral.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferral.d.ts","sourceRoot":"","sources":["../../../src/core/capabilities/deferral.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC7B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GACxB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,qBAAqB,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAO3G;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CA4BrE;AAQD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAsB1G","sourcesContent":["/**\n * Is deferring a tool's schema actually worth it?\n *\n * §6.3 said the threshold should be measurable rather than asserted, and until\n * now it was neither. The question turns out not to be \"how many tokens do the\n * schemas cost\" — `--print-token-surface` already answered that — but a\n * trade-off with a term nobody had priced:\n *\n *   Deferring withholds D tokens of schema from every request. But those tokens\n *   would have sat in the *cached* prefix, so what deferral saves per request is\n *   D at the cache-read rate, not at full price — an order of magnitude less\n *   than it looks. And the moment the model resolves a deferred tool, the\n *   harness adds it to `tools`, which renders at position 0 and invalidates the\n *   whole prefix P — so the next request pays P at the cache-*write* rate\n *   instead of the cache-read rate it would otherwise have paid.\n *\n * Break-even is therefore the number of requests before the first resolve:\n *\n *   N = P × (cacheWrite − cacheRead) / (D × cacheRead)\n *\n * The counterintuitive consequence is worth stating plainly: **P grows with the\n * conversation, D does not.** Deferral gets *worse* the longer a session runs,\n * which is the opposite of the intuition that motivated it.\n *\n * See docs/plugin-system-architecture.md §6.3 and §8.6 item 6.\n */\n\n/** Per-million-token prices, as carried on a model. */\nexport interface TokenPrices {\n\tinput: number;\n\tcacheRead: number;\n\tcacheWrite: number;\n}\n\nexport interface DeferralInput {\n\t/** Tokens of schema that would be withheld (the deferrable tools). */\n\tdeferredTokens: number;\n\t/**\n\t * Tokens in the cached prefix a resolve would invalidate: system prompt plus\n\t * every tool schema, and in a live session the conversation too. Callers that\n\t * only know the startup surface are supplying a floor — see `prefixIsFloor`.\n\t */\n\tprefixTokens: number;\n\tprices: TokenPrices;\n}\n\nexport type DeferralVerdict =\n\t| { kind: \"no-cache\"; reason: string }\n\t| { kind: \"nothing-deferred\"; reason: string }\n\t| { kind: \"unpriced\"; reason: string }\n\t| { kind: \"break-even\"; requestsBeforeResolve: number; savingPerRequest: number; resolvePenalty: number };\n\n/** Dollars for `tokens` at a per-million-token price. */\nfunction priceOf(tokens: number, perMillion: number): number {\n\treturn (tokens / 1_000_000) * perMillion;\n}\n\n/**\n * Price the deferral trade-off for one model.\n *\n * Deliberately returns a discriminated verdict rather than a bare number: three\n * of the four outcomes mean \"the break-even question does not apply here\", and\n * collapsing them into a number would invite reading 0 or Infinity as an answer.\n */\nexport function analyzeDeferral(input: DeferralInput): DeferralVerdict {\n\tconst { deferredTokens, prefixTokens, prices } = input;\n\n\tif (deferredTokens <= 0) {\n\t\treturn { kind: \"nothing-deferred\", reason: \"no deferrable tools in this configuration\" };\n\t}\n\tif (prices.input <= 0 && prices.cacheRead <= 0 && prices.cacheWrite <= 0) {\n\t\treturn { kind: \"unpriced\", reason: \"model carries no pricing, so the trade-off cannot be costed\" };\n\t}\n\t// A provider that does not price caching separately never had a cached prefix\n\t// to lose, so a resolve costs nothing extra and deferral is unambiguously\n\t// good — the saving is the full input rate on every request.\n\tif (prices.cacheRead <= 0 || prices.cacheWrite <= 0) {\n\t\treturn {\n\t\t\tkind: \"no-cache\",\n\t\t\treason: \"provider does not price prompt caching, so a resolve invalidates nothing — deferral is a pure saving\",\n\t\t};\n\t}\n\n\tconst savingPerRequest = priceOf(deferredTokens, prices.cacheRead);\n\tconst resolvePenalty = priceOf(prefixTokens, prices.cacheWrite - prices.cacheRead);\n\n\treturn {\n\t\tkind: \"break-even\",\n\t\trequestsBeforeResolve: resolvePenalty / savingPerRequest,\n\t\tsavingPerRequest,\n\t\tresolvePenalty,\n\t};\n}\n\nfunction usd(amount: number): string {\n\tif (amount === 0) return \"$0\";\n\tif (amount < 0.01) return `$${amount.toFixed(6)}`;\n\treturn `$${amount.toFixed(4)}`;\n}\n\n/**\n * Render the verdict for `--print-token-surface`.\n *\n * `prefixIsFloor` marks the common case where the caller measured the startup\n * surface only. The number is then a lower bound in the direction that matters:\n * the real prefix is larger, so the real break-even is higher and deferral looks\n * worse than printed, never better.\n */\nexport function formatDeferral(verdict: DeferralVerdict, options: { prefixIsFloor?: boolean } = {}): string {\n\tswitch (verdict.kind) {\n\t\tcase \"nothing-deferred\":\n\t\tcase \"unpriced\":\n\t\tcase \"no-cache\":\n\t\t\treturn `  deferral: ${verdict.reason}`;\n\t\tcase \"break-even\": {\n\t\t\tconst n = Math.ceil(verdict.requestsBeforeResolve);\n\t\t\tconst lines = [\n\t\t\t\t`  deferral saves ${usd(verdict.savingPerRequest)}/request (withheld schema at the cache-read rate)`,\n\t\t\t\t`  a resolve costs ${usd(verdict.resolvePenalty)} once (whole prefix re-written, not read)`,\n\t\t\t\t`  break-even: deferral pays off only if the model waits ${n}+ request(s) before resolving`,\n\t\t\t];\n\t\t\tif (options.prefixIsFloor) {\n\t\t\t\tlines.push(\n\t\t\t\t\t\"  (prefix measured at startup, so this is a floor — the conversation grows it,\",\n\t\t\t\t\t\"   and with it the resolve penalty, making deferral worse as a session runs on)\",\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn lines.join(\"\\n\");\n\t\t}\n\t}\n}\n"]}

package/dist/core/capabilities/deferral.js

@@ -0,0 +1,99 @@
+/**
+ * Is deferring a tool's schema actually worth it?
+ *
+ * §6.3 said the threshold should be measurable rather than asserted, and until
+ * now it was neither. The question turns out not to be "how many tokens do the
+ * schemas cost" — `--print-token-surface` already answered that — but a
+ * trade-off with a term nobody had priced:
+ *
+ *   Deferring withholds D tokens of schema from every request. But those tokens
+ *   would have sat in the *cached* prefix, so what deferral saves per request is
+ *   D at the cache-read rate, not at full price — an order of magnitude less
+ *   than it looks. And the moment the model resolves a deferred tool, the
+ *   harness adds it to `tools`, which renders at position 0 and invalidates the
+ *   whole prefix P — so the next request pays P at the cache-*write* rate
+ *   instead of the cache-read rate it would otherwise have paid.
+ *
+ * Break-even is therefore the number of requests before the first resolve:
+ *
+ *   N = P × (cacheWrite − cacheRead) / (D × cacheRead)
+ *
+ * The counterintuitive consequence is worth stating plainly: **P grows with the
+ * conversation, D does not.** Deferral gets *worse* the longer a session runs,
+ * which is the opposite of the intuition that motivated it.
+ *
+ * See docs/plugin-system-architecture.md §6.3 and §8.6 item 6.
+ */
+/** Dollars for `tokens` at a per-million-token price. */
+function priceOf(tokens, perMillion) {
+    return (tokens / 1_000_000) * perMillion;
+}
+/**
+ * Price the deferral trade-off for one model.
+ *
+ * Deliberately returns a discriminated verdict rather than a bare number: three
+ * of the four outcomes mean "the break-even question does not apply here", and
+ * collapsing them into a number would invite reading 0 or Infinity as an answer.
+ */
+export function analyzeDeferral(input) {
+    const { deferredTokens, prefixTokens, prices } = input;
+    if (deferredTokens <= 0) {
+        return { kind: "nothing-deferred", reason: "no deferrable tools in this configuration" };
+    }
+    if (prices.input <= 0 && prices.cacheRead <= 0 && prices.cacheWrite <= 0) {
+        return { kind: "unpriced", reason: "model carries no pricing, so the trade-off cannot be costed" };
+    }
+    // A provider that does not price caching separately never had a cached prefix
+    // to lose, so a resolve costs nothing extra and deferral is unambiguously
+    // good — the saving is the full input rate on every request.
+    if (prices.cacheRead <= 0 || prices.cacheWrite <= 0) {
+        return {
+            kind: "no-cache",
+            reason: "provider does not price prompt caching, so a resolve invalidates nothing — deferral is a pure saving",
+        };
+    }
+    const savingPerRequest = priceOf(deferredTokens, prices.cacheRead);
+    const resolvePenalty = priceOf(prefixTokens, prices.cacheWrite - prices.cacheRead);
+    return {
+        kind: "break-even",
+        requestsBeforeResolve: resolvePenalty / savingPerRequest,
+        savingPerRequest,
+        resolvePenalty,
+    };
+}
+function usd(amount) {
+    if (amount === 0)
+        return "$0";
+    if (amount < 0.01)
+        return `$${amount.toFixed(6)}`;
+    return `$${amount.toFixed(4)}`;
+}
+/**
+ * Render the verdict for `--print-token-surface`.
+ *
+ * `prefixIsFloor` marks the common case where the caller measured the startup
+ * surface only. The number is then a lower bound in the direction that matters:
+ * the real prefix is larger, so the real break-even is higher and deferral looks
+ * worse than printed, never better.
+ */
+export function formatDeferral(verdict, options = {}) {
+    switch (verdict.kind) {
+        case "nothing-deferred":
+        case "unpriced":
+        case "no-cache":
+            return `  deferral: ${verdict.reason}`;
+        case "break-even": {
+            const n = Math.ceil(verdict.requestsBeforeResolve);
+            const lines = [
+                `  deferral saves ${usd(verdict.savingPerRequest)}/request (withheld schema at the cache-read rate)`,
+                `  a resolve costs ${usd(verdict.resolvePenalty)} once (whole prefix re-written, not read)`,
+                `  break-even: deferral pays off only if the model waits ${n}+ request(s) before resolving`,
+            ];
+            if (options.prefixIsFloor) {
+                lines.push("  (prefix measured at startup, so this is a floor — the conversation grows it,", "   and with it the resolve penalty, making deferral worse as a session runs on)");
+            }
+            return lines.join("\n");
+        }
+    }
+}
+//# sourceMappingURL=deferral.js.map

package/dist/core/capabilities/deferral.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferral.js","sourceRoot":"","sources":["../../../src/core/capabilities/deferral.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA2BH,yDAAyD;AACzD,SAAS,OAAO,CAAC,MAAc,EAAE,UAAkB,EAAU;IAC5D,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,UAAU,CAAC;AAAA,CACzC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB,EAAmB;IACtE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAEvD,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,IAAI,CAAC,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;QAC1E,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,6DAA6D,EAAE,CAAC;IACpG,CAAC;IACD,8EAA8E;IAC9E,0EAA0E;IAC1E,+DAA6D;IAC7D,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;QACrD,OAAO;YACN,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,wGAAsG;SAC9G,CAAC;IACH,CAAC;IAED,MAAM,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IACnE,MAAM,cAAc,GAAG,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAEnF,OAAO;QACN,IAAI,EAAE,YAAY;QAClB,qBAAqB,EAAE,cAAc,GAAG,gBAAgB;QACxD,gBAAgB;QAChB,cAAc;KACd,CAAC;AAAA,CACF;AAED,SAAS,GAAG,CAAC,MAAc,EAAU;IACpC,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,MAAM,GAAG,IAAI;QAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAClD,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AAAA,CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB,EAAE,OAAO,GAAgC,EAAE,EAAU;IAC3G,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,kBAAkB,CAAC;QACxB,KAAK,UAAU,CAAC;QAChB,KAAK,UAAU;YACd,OAAO,eAAe,OAAO,CAAC,MAAM,EAAE,CAAC;QACxC,KAAK,YAAY,EAAE,CAAC;YACnB,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;YACnD,MAAM,KAAK,GAAG;gBACb,oBAAoB,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,mDAAmD;gBACpG,qBAAqB,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,2CAA2C;gBAC3F,2DAA2D,CAAC,+BAA+B;aAC3F,CAAC;YACF,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;gBAC3B,KAAK,CAAC,IAAI,CACT,kFAAgF,EAChF,iFAAiF,CACjF,CAAC;YACH,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;IACF,CAAC;AAAA,CACD","sourcesContent":["/**\n * Is deferring a tool's schema actually worth it?\n *\n * §6.3 said the threshold should be measurable rather than asserted, and until\n * now it was neither. The question turns out not to be \"how many tokens do the\n * schemas cost\" — `--print-token-surface` already answered that — but a\n * trade-off with a term nobody had priced:\n *\n *   Deferring withholds D tokens of schema from every request. But those tokens\n *   would have sat in the *cached* prefix, so what deferral saves per request is\n *   D at the cache-read rate, not at full price — an order of magnitude less\n *   than it looks. And the moment the model resolves a deferred tool, the\n *   harness adds it to `tools`, which renders at position 0 and invalidates the\n *   whole prefix P — so the next request pays P at the cache-*write* rate\n *   instead of the cache-read rate it would otherwise have paid.\n *\n * Break-even is therefore the number of requests before the first resolve:\n *\n *   N = P × (cacheWrite − cacheRead) / (D × cacheRead)\n *\n * The counterintuitive consequence is worth stating plainly: **P grows with the\n * conversation, D does not.** Deferral gets *worse* the longer a session runs,\n * which is the opposite of the intuition that motivated it.\n *\n * See docs/plugin-system-architecture.md §6.3 and §8.6 item 6.\n */\n\n/** Per-million-token prices, as carried on a model. */\nexport interface TokenPrices {\n\tinput: number;\n\tcacheRead: number;\n\tcacheWrite: number;\n}\n\nexport interface DeferralInput {\n\t/** Tokens of schema that would be withheld (the deferrable tools). */\n\tdeferredTokens: number;\n\t/**\n\t * Tokens in the cached prefix a resolve would invalidate: system prompt plus\n\t * every tool schema, and in a live session the conversation too. Callers that\n\t * only know the startup surface are supplying a floor — see `prefixIsFloor`.\n\t */\n\tprefixTokens: number;\n\tprices: TokenPrices;\n}\n\nexport type DeferralVerdict =\n\t| { kind: \"no-cache\"; reason: string }\n\t| { kind: \"nothing-deferred\"; reason: string }\n\t| { kind: \"unpriced\"; reason: string }\n\t| { kind: \"break-even\"; requestsBeforeResolve: number; savingPerRequest: number; resolvePenalty: number };\n\n/** Dollars for `tokens` at a per-million-token price. */\nfunction priceOf(tokens: number, perMillion: number): number {\n\treturn (tokens / 1_000_000) * perMillion;\n}\n\n/**\n * Price the deferral trade-off for one model.\n *\n * Deliberately returns a discriminated verdict rather than a bare number: three\n * of the four outcomes mean \"the break-even question does not apply here\", and\n * collapsing them into a number would invite reading 0 or Infinity as an answer.\n */\nexport function analyzeDeferral(input: DeferralInput): DeferralVerdict {\n\tconst { deferredTokens, prefixTokens, prices } = input;\n\n\tif (deferredTokens <= 0) {\n\t\treturn { kind: \"nothing-deferred\", reason: \"no deferrable tools in this configuration\" };\n\t}\n\tif (prices.input <= 0 && prices.cacheRead <= 0 && prices.cacheWrite <= 0) {\n\t\treturn { kind: \"unpriced\", reason: \"model carries no pricing, so the trade-off cannot be costed\" };\n\t}\n\t// A provider that does not price caching separately never had a cached prefix\n\t// to lose, so a resolve costs nothing extra and deferral is unambiguously\n\t// good — the saving is the full input rate on every request.\n\tif (prices.cacheRead <= 0 || prices.cacheWrite <= 0) {\n\t\treturn {\n\t\t\tkind: \"no-cache\",\n\t\t\treason: \"provider does not price prompt caching, so a resolve invalidates nothing — deferral is a pure saving\",\n\t\t};\n\t}\n\n\tconst savingPerRequest = priceOf(deferredTokens, prices.cacheRead);\n\tconst resolvePenalty = priceOf(prefixTokens, prices.cacheWrite - prices.cacheRead);\n\n\treturn {\n\t\tkind: \"break-even\",\n\t\trequestsBeforeResolve: resolvePenalty / savingPerRequest,\n\t\tsavingPerRequest,\n\t\tresolvePenalty,\n\t};\n}\n\nfunction usd(amount: number): string {\n\tif (amount === 0) return \"$0\";\n\tif (amount < 0.01) return `$${amount.toFixed(6)}`;\n\treturn `$${amount.toFixed(4)}`;\n}\n\n/**\n * Render the verdict for `--print-token-surface`.\n *\n * `prefixIsFloor` marks the common case where the caller measured the startup\n * surface only. The number is then a lower bound in the direction that matters:\n * the real prefix is larger, so the real break-even is higher and deferral looks\n * worse than printed, never better.\n */\nexport function formatDeferral(verdict: DeferralVerdict, options: { prefixIsFloor?: boolean } = {}): string {\n\tswitch (verdict.kind) {\n\t\tcase \"nothing-deferred\":\n\t\tcase \"unpriced\":\n\t\tcase \"no-cache\":\n\t\t\treturn `  deferral: ${verdict.reason}`;\n\t\tcase \"break-even\": {\n\t\t\tconst n = Math.ceil(verdict.requestsBeforeResolve);\n\t\t\tconst lines = [\n\t\t\t\t`  deferral saves ${usd(verdict.savingPerRequest)}/request (withheld schema at the cache-read rate)`,\n\t\t\t\t`  a resolve costs ${usd(verdict.resolvePenalty)} once (whole prefix re-written, not read)`,\n\t\t\t\t`  break-even: deferral pays off only if the model waits ${n}+ request(s) before resolving`,\n\t\t\t];\n\t\t\tif (options.prefixIsFloor) {\n\t\t\t\tlines.push(\n\t\t\t\t\t\"  (prefix measured at startup, so this is a floor — the conversation grows it,\",\n\t\t\t\t\t\"   and with it the resolve penalty, making deferral worse as a session runs on)\",\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn lines.join(\"\\n\");\n\t\t}\n\t}\n}\n"]}

package/dist/core/capabilities/dense.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Optional dense leg for capability retrieval.
+ *
+ * A separate embsearch store from the repo index, for two reasons that both had
+ * to hold. The repo service goes **dormant below a byte threshold**, and a
+ * capability index that stops working in a small repo is worse than none — the
+ * whole point is finding tools, which have nothing to do with how much code is
+ * checked out. And the lifecycles do not line up: the repo index invalidates on
+ * file edits, this one on a server appearing or a plugin being installed.
+ *
+ * Everything here is best-effort. It never downloads the binary — it uses one
+ * already on disk, and if there is none, retrieval is lexical-only and says so
+ * rather than waiting. Nothing on this path may block a session or a tool call.
+ *
+ * See docs/plugin-system-architecture.md §6.2.
+ */
+import { type CapabilityDoc } from "./registry.js";
+/** Where a capability index for a given capability-set hash lives. */
+export declare function capabilityStoreDir(hash: string, agentDir?: string): string;
+export interface DenseHit {
+    id: string;
+    score: number;
+}
+/**
+ * State of the dense leg, as reported to callers so they can say *why* a search
+ * was lexical-only rather than silently returning fewer results.
+ */
+export type DenseState = {
+    status: "off";
+    reason: string;
+} | {
+    status: "building";
+} | {
+    status: "ready";
+    count: number;
+};
+export declare function denseState(): DenseState;
+/**
+ * Bring the dense index up for `docs`, if it can be. Idempotent, and a no-op
+ * when the same capability set is already indexed.
+ *
+ * Returns once the index is usable or has been ruled out. Callers that must not
+ * wait should not await it — {@link denseSearch} works the moment it is ready
+ * and returns nothing before that.
+ */
+export declare function ensureDenseIndex(docs: readonly CapabilityDoc[], agentDir?: string): Promise<void>;
+/** Top `k` dense hits, or nothing when the leg is not ready. Never throws. */
+export declare function denseSearch(query: string, k?: number): Promise<DenseHit[]>;
+/** Shut the daemon down and forget the index. Session teardown, and tests. */
+export declare function disposeDenseIndex(): Promise<void>;
+//# sourceMappingURL=dense.d.ts.map

package/dist/core/capabilities/dense.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dense.d.ts","sourceRoot":"","sources":["../../../src/core/capabilities/dense.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,eAAe,CAAC;AAKtE,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAEzF;AAED,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GACnB;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAOtC,wBAAgB,UAAU,IAAI,UAAU,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDvG;AAED,8EAA8E;AAC9E,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,SAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAO5E;AAQD,8EAA8E;AAC9E,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvD","sourcesContent":["/**\n * Optional dense leg for capability retrieval.\n *\n * A separate embsearch store from the repo index, for two reasons that both had\n * to hold. The repo service goes **dormant below a byte threshold**, and a\n * capability index that stops working in a small repo is worse than none — the\n * whole point is finding tools, which have nothing to do with how much code is\n * checked out. And the lifecycles do not line up: the repo index invalidates on\n * file edits, this one on a server appearing or a plugin being installed.\n *\n * Everything here is best-effort. It never downloads the binary — it uses one\n * already on disk, and if there is none, retrieval is lexical-only and says so\n * rather than waiting. Nothing on this path may block a session or a tool call.\n *\n * See docs/plugin-system-architecture.md §6.2.\n */\n\nimport { join } from \"node:path\";\nimport { getAgentDir } from \"../../config.js\";\nimport { getToolPath } from \"../../utils/tools-manager.js\";\nimport { EmbSearchClient } from \"../embsearch/client.js\";\nimport { type CapabilityDoc, capabilitySetHash } from \"./registry.js\";\n\n/** The Rust mock backend's model id — semantically meaningless, never index with it. */\nconst MOCK_MODEL_ID = \"mock-hash-v1\";\n\n/** Where a capability index for a given capability-set hash lives. */\nexport function capabilityStoreDir(hash: string, agentDir: string = getAgentDir()): string {\n\treturn join(agentDir, \"capability-index\", hash);\n}\n\nexport interface DenseHit {\n\tid: string;\n\tscore: number;\n}\n\n/**\n * State of the dense leg, as reported to callers so they can say *why* a search\n * was lexical-only rather than silently returning fewer results.\n */\nexport type DenseState =\n\t| { status: \"off\"; reason: string }\n\t| { status: \"building\" }\n\t| { status: \"ready\"; count: number };\n\nlet client: EmbSearchClient | undefined;\nlet state: DenseState = { status: \"off\", reason: \"not started\" };\nlet building: Promise<void> | undefined;\nlet indexedHash: string | undefined;\n\nexport function denseState(): DenseState {\n\treturn state;\n}\n\n/**\n * Bring the dense index up for `docs`, if it can be. Idempotent, and a no-op\n * when the same capability set is already indexed.\n *\n * Returns once the index is usable or has been ruled out. Callers that must not\n * wait should not await it — {@link denseSearch} works the moment it is ready\n * and returns nothing before that.\n */\nexport async function ensureDenseIndex(docs: readonly CapabilityDoc[], agentDir?: string): Promise<void> {\n\tconst hash = capabilitySetHash(docs);\n\tif (indexedHash === hash && state.status === \"ready\") return;\n\tif (building) return building;\n\n\tbuilding = (async () => {\n\t\ttry {\n\t\t\tconst binary = getToolPath(\"embsearch\");\n\t\t\tif (!binary) {\n\t\t\t\t// Deliberately not `ensureTool`: downloading a model runtime because\n\t\t\t\t// someone has MCP servers installed is not a trade the user agreed to.\n\t\t\t\tstate = { status: \"off\", reason: \"embsearch binary not installed\" };\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (docs.length === 0) {\n\t\t\t\tstate = { status: \"off\", reason: \"no capabilities registered\" };\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tstate = { status: \"building\" };\n\t\t\tawait closeClient();\n\t\t\tconst next = new EmbSearchClient({\n\t\t\t\tbinaryPath: binary,\n\t\t\t\tstorePath: capabilityStoreDir(hash, agentDir),\n\t\t\t\thybrid: false, // The lexical leg is ours; the daemon only provides dense.\n\t\t\t});\n\t\t\tconst info = await next.info();\n\t\t\tif (info.modelId === MOCK_MODEL_ID) {\n\t\t\t\t// The mock embedder returns hashes, not semantics. Indexing with it\n\t\t\t\t// would produce a store that looks healthy and ranks at random.\n\t\t\t\tawait next.close().catch(() => {});\n\t\t\t\tstate = { status: \"off\", reason: \"embsearch is using the mock embedder\" };\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// The store is keyed on the content hash, so a hit means these exact\n\t\t\t// documents were embedded before and nothing needs re-embedding.\n\t\t\tif (info.count < docs.length) {\n\t\t\t\tawait next.bulk(docs.map((d) => ({ id: d.id, text: `${d.name}. ${d.description}` })));\n\t\t\t\tawait next.save();\n\t\t\t}\n\t\t\tclient = next;\n\t\t\tindexedHash = hash;\n\t\t\tstate = { status: \"ready\", count: docs.length };\n\t\t} catch (error) {\n\t\t\tstate = { status: \"off\", reason: `embsearch unavailable: ${(error as Error).message}` };\n\t\t\tawait closeClient();\n\t\t} finally {\n\t\t\tbuilding = undefined;\n\t\t}\n\t})();\n\treturn building;\n}\n\n/** Top `k` dense hits, or nothing when the leg is not ready. Never throws. */\nexport async function denseSearch(query: string, k = 10): Promise<DenseHit[]> {\n\tif (!client || state.status !== \"ready\") return [];\n\ttry {\n\t\treturn await client.query(query, k, \"dense\");\n\t} catch {\n\t\treturn [];\n\t}\n}\n\nasync function closeClient(): Promise<void> {\n\tconst current = client;\n\tclient = undefined;\n\tif (current) await current.close().catch(() => {});\n}\n\n/** Shut the daemon down and forget the index. Session teardown, and tests. */\nexport async function disposeDenseIndex(): Promise<void> {\n\tawait closeClient();\n\tindexedHash = undefined;\n\tbuilding = undefined;\n\tstate = { status: \"off\", reason: \"not started\" };\n}\n"]}

package/dist/core/capabilities/dense.js

@@ -0,0 +1,121 @@
+/**
+ * Optional dense leg for capability retrieval.
+ *
+ * A separate embsearch store from the repo index, for two reasons that both had
+ * to hold. The repo service goes **dormant below a byte threshold**, and a
+ * capability index that stops working in a small repo is worse than none — the
+ * whole point is finding tools, which have nothing to do with how much code is
+ * checked out. And the lifecycles do not line up: the repo index invalidates on
+ * file edits, this one on a server appearing or a plugin being installed.
+ *
+ * Everything here is best-effort. It never downloads the binary — it uses one
+ * already on disk, and if there is none, retrieval is lexical-only and says so
+ * rather than waiting. Nothing on this path may block a session or a tool call.
+ *
+ * See docs/plugin-system-architecture.md §6.2.
+ */
+import { join } from "node:path";
+import { getAgentDir } from "../../config.js";
+import { getToolPath } from "../../utils/tools-manager.js";
+import { EmbSearchClient } from "../embsearch/client.js";
+import { capabilitySetHash } from "./registry.js";
+/** The Rust mock backend's model id — semantically meaningless, never index with it. */
+const MOCK_MODEL_ID = "mock-hash-v1";
+/** Where a capability index for a given capability-set hash lives. */
+export function capabilityStoreDir(hash, agentDir = getAgentDir()) {
+    return join(agentDir, "capability-index", hash);
+}
+let client;
+let state = { status: "off", reason: "not started" };
+let building;
+let indexedHash;
+export function denseState() {
+    return state;
+}
+/**
+ * Bring the dense index up for `docs`, if it can be. Idempotent, and a no-op
+ * when the same capability set is already indexed.
+ *
+ * Returns once the index is usable or has been ruled out. Callers that must not
+ * wait should not await it — {@link denseSearch} works the moment it is ready
+ * and returns nothing before that.
+ */
+export async function ensureDenseIndex(docs, agentDir) {
+    const hash = capabilitySetHash(docs);
+    if (indexedHash === hash && state.status === "ready")
+        return;
+    if (building)
+        return building;
+    building = (async () => {
+        try {
+            const binary = getToolPath("embsearch");
+            if (!binary) {
+                // Deliberately not `ensureTool`: downloading a model runtime because
+                // someone has MCP servers installed is not a trade the user agreed to.
+                state = { status: "off", reason: "embsearch binary not installed" };
+                return;
+            }
+            if (docs.length === 0) {
+                state = { status: "off", reason: "no capabilities registered" };
+                return;
+            }
+            state = { status: "building" };
+            await closeClient();
+            const next = new EmbSearchClient({
+                binaryPath: binary,
+                storePath: capabilityStoreDir(hash, agentDir),
+                hybrid: false, // The lexical leg is ours; the daemon only provides dense.
+            });
+            const info = await next.info();
+            if (info.modelId === MOCK_MODEL_ID) {
+                // The mock embedder returns hashes, not semantics. Indexing with it
+                // would produce a store that looks healthy and ranks at random.
+                await next.close().catch(() => { });
+                state = { status: "off", reason: "embsearch is using the mock embedder" };
+                return;
+            }
+            // The store is keyed on the content hash, so a hit means these exact
+            // documents were embedded before and nothing needs re-embedding.
+            if (info.count < docs.length) {
+                await next.bulk(docs.map((d) => ({ id: d.id, text: `${d.name}. ${d.description}` })));
+                await next.save();
+            }
+            client = next;
+            indexedHash = hash;
+            state = { status: "ready", count: docs.length };
+        }
+        catch (error) {
+            state = { status: "off", reason: `embsearch unavailable: ${error.message}` };
+            await closeClient();
+        }
+        finally {
+            building = undefined;
+        }
+    })();
+    return building;
+}
+/** Top `k` dense hits, or nothing when the leg is not ready. Never throws. */
+export async function denseSearch(query, k = 10) {
+    if (!client || state.status !== "ready")
+        return [];
+    try {
+        return await client.query(query, k, "dense");
+    }
+    catch {
+        return [];
+    }
+}
+async function closeClient() {
+    const current = client;
+    client = undefined;
+    if (current)
+        await current.close().catch(() => { });
+}
+/** Shut the daemon down and forget the index. Session teardown, and tests. */
+export async function disposeDenseIndex() {
+    await closeClient();
+    indexedHash = undefined;
+    building = undefined;
+    state = { status: "off", reason: "not started" };
+}
+//# sourceMappingURL=dense.js.map

package/dist/core/capabilities/dense.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dense.js","sourceRoot":"","sources":["../../../src/core/capabilities/dense.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Optional dense leg for capability retrieval.\n *\n * A separate embsearch store from the repo index, for two reasons that both had\n * to hold. The repo service goes **dormant below a byte threshold**, and a\n * capability index that stops working in a small repo is worse than none — the\n * whole point is finding tools, which have nothing to do with how much code is\n * checked out. And the lifecycles do not line up: the repo index invalidates on\n * file edits, this one on a server appearing or a plugin being installed.\n *\n * Everything here is best-effort. It never downloads the binary — it uses one\n * already on disk, and if there is none, retrieval is lexical-only and says so\n * rather than waiting. Nothing on this path may block a session or a tool call.\n *\n * See docs/plugin-system-architecture.md §6.2.\n */\n\nimport { join } from \"node:path\";\nimport { getAgentDir } from \"../../config.js\";\nimport { getToolPath } from \"../../utils/tools-manager.js\";\nimport { EmbSearchClient } from \"../embsearch/client.js\";\nimport { type CapabilityDoc, capabilitySetHash } from \"./registry.js\";\n\n/** The Rust mock backend's model id — semantically meaningless, never index with it. */\nconst MOCK_MODEL_ID = \"mock-hash-v1\";\n\n/** Where a capability index for a given capability-set hash lives. */\nexport function capabilityStoreDir(hash: string, agentDir: string = getAgentDir()): string {\n\treturn join(agentDir, \"capability-index\", hash);\n}\n\nexport interface DenseHit {\n\tid: string;\n\tscore: number;\n}\n\n/**\n * State of the dense leg, as reported to callers so they can say *why* a search\n * was lexical-only rather than silently returning fewer results.\n */\nexport type DenseState =\n\t| { status: \"off\"; reason: string }\n\t| { status: \"building\" }\n\t| { status: \"ready\"; count: number };\n\nlet client: EmbSearchClient | undefined;\nlet state: DenseState = { status: \"off\", reason: \"not started\" };\nlet building: Promise<void> | undefined;\nlet indexedHash: string | undefined;\n\nexport function denseState(): DenseState {\n\treturn state;\n}\n\n/**\n * Bring the dense index up for `docs`, if it can be. Idempotent, and a no-op\n * when the same capability set is already indexed.\n *\n * Returns once the index is usable or has been ruled out. Callers that must not\n * wait should not await it — {@link denseSearch} works the moment it is ready\n * and returns nothing before that.\n */\nexport async function ensureDenseIndex(docs: readonly CapabilityDoc[], agentDir?: string): Promise<void> {\n\tconst hash = capabilitySetHash(docs);\n\tif (indexedHash === hash && state.status === \"ready\") return;\n\tif (building) return building;\n\n\tbuilding = (async () => {\n\t\ttry {\n\t\t\tconst binary = getToolPath(\"embsearch\");\n\t\t\tif (!binary) {\n\t\t\t\t// Deliberately not `ensureTool`: downloading a model runtime because\n\t\t\t\t// someone has MCP servers installed is not a trade the user agreed to.\n\t\t\t\tstate = { status: \"off\", reason: \"embsearch binary not installed\" };\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (docs.length === 0) {\n\t\t\t\tstate = { status: \"off\", reason: \"no capabilities registered\" };\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tstate = { status: \"building\" };\n\t\t\tawait closeClient();\n\t\t\tconst next = new EmbSearchClient({\n\t\t\t\tbinaryPath: binary,\n\t\t\t\tstorePath: capabilityStoreDir(hash, agentDir),\n\t\t\t\thybrid: false, // The lexical leg is ours; the daemon only provides dense.\n\t\t\t});\n\t\t\tconst info = await next.info();\n\t\t\tif (info.modelId === MOCK_MODEL_ID) {\n\t\t\t\t// The mock embedder returns hashes, not semantics. Indexing with it\n\t\t\t\t// would produce a store that looks healthy and ranks at random.\n\t\t\t\tawait next.close().catch(() => {});\n\t\t\t\tstate = { status: \"off\", reason: \"embsearch is using the mock embedder\" };\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// The store is keyed on the content hash, so a hit means these exact\n\t\t\t// documents were embedded before and nothing needs re-embedding.\n\t\t\tif (info.count < docs.length) {\n\t\t\t\tawait next.bulk(docs.map((d) => ({ id: d.id, text: `${d.name}. ${d.description}` })));\n\t\t\t\tawait next.save();\n\t\t\t}\n\t\t\tclient = next;\n\t\t\tindexedHash = hash;\n\t\t\tstate = { status: \"ready\", count: docs.length };\n\t\t} catch (error) {\n\t\t\tstate = { status: \"off\", reason: `embsearch unavailable: ${(error as Error).message}` };\n\t\t\tawait closeClient();\n\t\t} finally {\n\t\t\tbuilding = undefined;\n\t\t}\n\t})();\n\treturn building;\n}\n\n/** Top `k` dense hits, or nothing when the leg is not ready. Never throws. */\nexport async function denseSearch(query: string, k = 10): Promise<DenseHit[]> {\n\tif (!client || state.status !== \"ready\") return [];\n\ttry {\n\t\treturn await client.query(query, k, \"dense\");\n\t} catch {\n\t\treturn [];\n\t}\n}\n\nasync function closeClient(): Promise<void> {\n\tconst current = client;\n\tclient = undefined;\n\tif (current) await current.close().catch(() => {});\n}\n\n/** Shut the daemon down and forget the index. Session teardown, and tests. */\nexport async function disposeDenseIndex(): Promise<void> {\n\tawait closeClient();\n\tindexedHash = undefined;\n\tbuilding = undefined;\n\tstate = { status: \"off\", reason: \"not started\" };\n}\n"]}

package/dist/core/capabilities/lexical.d.ts

@@ -0,0 +1,43 @@
+/**
+ * In-memory BM25 over the capability index — the leg that always works.
+ *
+ * Deliberately not the repo's lexical retriever: that one shells out to ripgrep
+ * over files on disk, and capabilities are a few hundred short strings held in
+ * memory. It is also not optional. The dense leg needs a binary that may not be
+ * installed and a store that may still be building, so if retrieval depended on
+ * it, "find me a tool that sends email" would work on some machines and not
+ * others. This leg makes the floor deterministic and dependency-free; dense is
+ * strictly additive on top.
+ *
+ * The tokenizer does the load-bearing work here. Tool names are the query terms
+ * that matter most and they arrive as `mcp_github_create_pull_request` or
+ * `createPullRequest`, so a naive whitespace split would make the single most
+ * common query shape — a name the model half-remembers — the one thing BM25
+ * cannot match.
+ */
+import type { CapabilityDoc } from "./registry.js";
+/**
+ * Split identifiers the way a person reads them: `mcp_github_create_pr` and
+ * `createPullRequest` both yield their parts, and the original token is kept so
+ * an exact name still scores as an exact match.
+ */
+export declare function tokenize(text: string): string[];
+export interface LexicalHit {
+    id: string;
+    score: number;
+}
+/**
+ * A built BM25 index. Cheap enough to rebuild whenever the capability set
+ * changes — a few hundred short documents — so there is no invalidation story
+ * to get wrong.
+ */
+export declare class LexicalIndex {
+    private readonly postings;
+    private readonly docFreq;
+    private readonly avgLength;
+    constructor(docs: readonly CapabilityDoc[]);
+    get size(): number;
+    /** Top `k` documents for `query`, best first. Documents scoring zero are omitted. */
+    search(query: string, k?: number): LexicalHit[];
+}
+//# sourceMappingURL=lexical.d.ts.map

package/dist/core/capabilities/lexical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical.d.ts","sourceRoot":"","sources":["../../../src/core/capabilities/lexical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMnD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAc/C;AAOD,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACd;AAQD;;;;GAIG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,IAAI,EAAE,SAAS,aAAa,EAAE,EAWzC;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,qFAAqF;IACrF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,SAAK,GAAG,UAAU,EAAE,CA2B1C;CACD","sourcesContent":["/**\n * In-memory BM25 over the capability index — the leg that always works.\n *\n * Deliberately not the repo's lexical retriever: that one shells out to ripgrep\n * over files on disk, and capabilities are a few hundred short strings held in\n * memory. It is also not optional. The dense leg needs a binary that may not be\n * installed and a store that may still be building, so if retrieval depended on\n * it, \"find me a tool that sends email\" would work on some machines and not\n * others. This leg makes the floor deterministic and dependency-free; dense is\n * strictly additive on top.\n *\n * The tokenizer does the load-bearing work here. Tool names are the query terms\n * that matter most and they arrive as `mcp_github_create_pull_request` or\n * `createPullRequest`, so a naive whitespace split would make the single most\n * common query shape — a name the model half-remembers — the one thing BM25\n * cannot match.\n */\n\nimport type { CapabilityDoc } from \"./registry.js\";\n\n/** Standard Okapi BM25 parameters. Nothing here justifies tuning them. */\nconst K1 = 1.2;\nconst B = 0.75;\n\n/**\n * Split identifiers the way a person reads them: `mcp_github_create_pr` and\n * `createPullRequest` both yield their parts, and the original token is kept so\n * an exact name still scores as an exact match.\n */\nexport function tokenize(text: string): string[] {\n\tconst out: string[] = [];\n\tfor (const raw of text.toLowerCase().match(/[a-z0-9]+(?:[_-][a-z0-9]+)*/gi) ?? []) {\n\t\tconst token = raw.toLowerCase();\n\t\tout.push(token);\n\t\t// Split on separators, then on camelCase boundaries in the source text.\n\t\tconst parts = token.split(/[_-]+/).filter(Boolean);\n\t\tif (parts.length > 1) out.push(...parts);\n\t}\n\tfor (const camel of text.match(/[a-z][a-z0-9]*|[A-Z][a-z0-9]*|[A-Z]+(?![a-z])/g) ?? []) {\n\t\tconst lower = camel.toLowerCase();\n\t\tif (lower.length > 1) out.push(lower);\n\t}\n\treturn out;\n}\n\n/** The text a document is matched on: name first, since that is what queries name. */\nfunction documentText(doc: CapabilityDoc): string {\n\treturn `${doc.name} ${doc.name} ${doc.source ?? \"\"} ${doc.description}`;\n}\n\nexport interface LexicalHit {\n\tid: string;\n\tscore: number;\n}\n\ninterface Posting {\n\tid: string;\n\tlength: number;\n\tcounts: Map<string, number>;\n}\n\n/**\n * A built BM25 index. Cheap enough to rebuild whenever the capability set\n * changes — a few hundred short documents — so there is no invalidation story\n * to get wrong.\n */\nexport class LexicalIndex {\n\tprivate readonly postings: Posting[] = [];\n\tprivate readonly docFreq = new Map<string, number>();\n\tprivate readonly avgLength: number;\n\n\tconstructor(docs: readonly CapabilityDoc[]) {\n\t\tlet total = 0;\n\t\tfor (const doc of docs) {\n\t\t\tconst tokens = tokenize(documentText(doc));\n\t\t\tconst counts = new Map<string, number>();\n\t\t\tfor (const t of tokens) counts.set(t, (counts.get(t) ?? 0) + 1);\n\t\t\tfor (const t of counts.keys()) this.docFreq.set(t, (this.docFreq.get(t) ?? 0) + 1);\n\t\t\tthis.postings.push({ id: doc.id, length: tokens.length, counts });\n\t\t\ttotal += tokens.length;\n\t\t}\n\t\tthis.avgLength = this.postings.length > 0 ? total / this.postings.length : 0;\n\t}\n\n\tget size(): number {\n\t\treturn this.postings.length;\n\t}\n\n\t/** Top `k` documents for `query`, best first. Documents scoring zero are omitted. */\n\tsearch(query: string, k = 10): LexicalHit[] {\n\t\tconst terms = tokenize(query);\n\t\tif (terms.length === 0 || this.postings.length === 0) return [];\n\t\tconst n = this.postings.length;\n\n\t\tconst hits: LexicalHit[] = [];\n\t\tfor (const posting of this.postings) {\n\t\t\tlet score = 0;\n\t\t\tfor (const term of new Set(terms)) {\n\t\t\t\tconst tf = posting.counts.get(term);\n\t\t\t\tif (!tf) continue;\n\t\t\t\tconst df = this.docFreq.get(term) ?? 0;\n\t\t\t\t// Okapi IDF, floored at zero: a term in every document carries no\n\t\t\t\t// signal, and the raw formula would make it actively negative.\n\t\t\t\tconst idf = Math.max(0, Math.log(1 + (n - df + 0.5) / (df + 0.5)));\n\t\t\t\tconst norm = tf * (K1 + 1);\n\t\t\t\tconst denom = tf + K1 * (1 - B + (B * posting.length) / (this.avgLength || 1));\n\t\t\t\tscore += idf * (norm / denom);\n\t\t\t}\n\t\t\tif (score > 0) hits.push({ id: posting.id, score });\n\t\t}\n\n\t\t// Ties break by id so the same query always returns the same order — a\n\t\t// retrieval tool that reshuffles equal-scoring results is a reproducibility\n\t\t// problem disguised as a ranking one.\n\t\thits.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));\n\t\treturn hits.slice(0, k);\n\t}\n}\n"]}

package/dist/core/capabilities/lexical.js

@@ -0,0 +1,104 @@
+/**
+ * In-memory BM25 over the capability index — the leg that always works.
+ *
+ * Deliberately not the repo's lexical retriever: that one shells out to ripgrep
+ * over files on disk, and capabilities are a few hundred short strings held in
+ * memory. It is also not optional. The dense leg needs a binary that may not be
+ * installed and a store that may still be building, so if retrieval depended on
+ * it, "find me a tool that sends email" would work on some machines and not
+ * others. This leg makes the floor deterministic and dependency-free; dense is
+ * strictly additive on top.
+ *
+ * The tokenizer does the load-bearing work here. Tool names are the query terms
+ * that matter most and they arrive as `mcp_github_create_pull_request` or
+ * `createPullRequest`, so a naive whitespace split would make the single most
+ * common query shape — a name the model half-remembers — the one thing BM25
+ * cannot match.
+ */
+/** Standard Okapi BM25 parameters. Nothing here justifies tuning them. */
+const K1 = 1.2;
+const B = 0.75;
+/**
+ * Split identifiers the way a person reads them: `mcp_github_create_pr` and
+ * `createPullRequest` both yield their parts, and the original token is kept so
+ * an exact name still scores as an exact match.
+ */
+export function tokenize(text) {
+    const out = [];
+    for (const raw of text.toLowerCase().match(/[a-z0-9]+(?:[_-][a-z0-9]+)*/gi) ?? []) {
+        const token = raw.toLowerCase();
+        out.push(token);
+        // Split on separators, then on camelCase boundaries in the source text.
+        const parts = token.split(/[_-]+/).filter(Boolean);
+        if (parts.length > 1)
+            out.push(...parts);
+    }
+    for (const camel of text.match(/[a-z][a-z0-9]*|[A-Z][a-z0-9]*|[A-Z]+(?![a-z])/g) ?? []) {
+        const lower = camel.toLowerCase();
+        if (lower.length > 1)
+            out.push(lower);
+    }
+    return out;
+}
+/** The text a document is matched on: name first, since that is what queries name. */
+function documentText(doc) {
+    return `${doc.name} ${doc.name} ${doc.source ?? ""} ${doc.description}`;
+}
+/**
+ * A built BM25 index. Cheap enough to rebuild whenever the capability set
+ * changes — a few hundred short documents — so there is no invalidation story
+ * to get wrong.
+ */
+export class LexicalIndex {
+    postings = [];
+    docFreq = new Map();
+    avgLength;
+    constructor(docs) {
+        let total = 0;
+        for (const doc of docs) {
+            const tokens = tokenize(documentText(doc));
+            const counts = new Map();
+            for (const t of tokens)
+                counts.set(t, (counts.get(t) ?? 0) + 1);
+            for (const t of counts.keys())
+                this.docFreq.set(t, (this.docFreq.get(t) ?? 0) + 1);
+            this.postings.push({ id: doc.id, length: tokens.length, counts });
+            total += tokens.length;
+        }
+        this.avgLength = this.postings.length > 0 ? total / this.postings.length : 0;
+    }
+    get size() {
+        return this.postings.length;
+    }
+    /** Top `k` documents for `query`, best first. Documents scoring zero are omitted. */
+    search(query, k = 10) {
+        const terms = tokenize(query);
+        if (terms.length === 0 || this.postings.length === 0)
+            return [];
+        const n = this.postings.length;
+        const hits = [];
+        for (const posting of this.postings) {
+            let score = 0;
+            for (const term of new Set(terms)) {
+                const tf = posting.counts.get(term);
+                if (!tf)
+                    continue;
+                const df = this.docFreq.get(term) ?? 0;
+                // Okapi IDF, floored at zero: a term in every document carries no
+                // signal, and the raw formula would make it actively negative.
+                const idf = Math.max(0, Math.log(1 + (n - df + 0.5) / (df + 0.5)));
+                const norm = tf * (K1 + 1);
+                const denom = tf + K1 * (1 - B + (B * posting.length) / (this.avgLength || 1));
+                score += idf * (norm / denom);
+            }
+            if (score > 0)
+                hits.push({ id: posting.id, score });
+        }
+        // Ties break by id so the same query always returns the same order — a
+        // retrieval tool that reshuffles equal-scoring results is a reproducibility
+        // problem disguised as a ranking one.
+        hits.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+        return hits.slice(0, k);
+    }
+}
+//# sourceMappingURL=lexical.js.map

package/dist/core/capabilities/lexical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical.js","sourceRoot":"","sources":["../../../src/core/capabilities/lexical.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * In-memory BM25 over the capability index — the leg that always works.\n *\n * Deliberately not the repo's lexical retriever: that one shells out to ripgrep\n * over files on disk, and capabilities are a few hundred short strings held in\n * memory. It is also not optional. The dense leg needs a binary that may not be\n * installed and a store that may still be building, so if retrieval depended on\n * it, \"find me a tool that sends email\" would work on some machines and not\n * others. This leg makes the floor deterministic and dependency-free; dense is\n * strictly additive on top.\n *\n * The tokenizer does the load-bearing work here. Tool names are the query terms\n * that matter most and they arrive as `mcp_github_create_pull_request` or\n * `createPullRequest`, so a naive whitespace split would make the single most\n * common query shape — a name the model half-remembers — the one thing BM25\n * cannot match.\n */\n\nimport type { CapabilityDoc } from \"./registry.js\";\n\n/** Standard Okapi BM25 parameters. Nothing here justifies tuning them. */\nconst K1 = 1.2;\nconst B = 0.75;\n\n/**\n * Split identifiers the way a person reads them: `mcp_github_create_pr` and\n * `createPullRequest` both yield their parts, and the original token is kept so\n * an exact name still scores as an exact match.\n */\nexport function tokenize(text: string): string[] {\n\tconst out: string[] = [];\n\tfor (const raw of text.toLowerCase().match(/[a-z0-9]+(?:[_-][a-z0-9]+)*/gi) ?? []) {\n\t\tconst token = raw.toLowerCase();\n\t\tout.push(token);\n\t\t// Split on separators, then on camelCase boundaries in the source text.\n\t\tconst parts = token.split(/[_-]+/).filter(Boolean);\n\t\tif (parts.length > 1) out.push(...parts);\n\t}\n\tfor (const camel of text.match(/[a-z][a-z0-9]*|[A-Z][a-z0-9]*|[A-Z]+(?![a-z])/g) ?? []) {\n\t\tconst lower = camel.toLowerCase();\n\t\tif (lower.length > 1) out.push(lower);\n\t}\n\treturn out;\n}\n\n/** The text a document is matched on: name first, since that is what queries name. */\nfunction documentText(doc: CapabilityDoc): string {\n\treturn `${doc.name} ${doc.name} ${doc.source ?? \"\"} ${doc.description}`;\n}\n\nexport interface LexicalHit {\n\tid: string;\n\tscore: number;\n}\n\ninterface Posting {\n\tid: string;\n\tlength: number;\n\tcounts: Map<string, number>;\n}\n\n/**\n * A built BM25 index. Cheap enough to rebuild whenever the capability set\n * changes — a few hundred short documents — so there is no invalidation story\n * to get wrong.\n */\nexport class LexicalIndex {\n\tprivate readonly postings: Posting[] = [];\n\tprivate readonly docFreq = new Map<string, number>();\n\tprivate readonly avgLength: number;\n\n\tconstructor(docs: readonly CapabilityDoc[]) {\n\t\tlet total = 0;\n\t\tfor (const doc of docs) {\n\t\t\tconst tokens = tokenize(documentText(doc));\n\t\t\tconst counts = new Map<string, number>();\n\t\t\tfor (const t of tokens) counts.set(t, (counts.get(t) ?? 0) + 1);\n\t\t\tfor (const t of counts.keys()) this.docFreq.set(t, (this.docFreq.get(t) ?? 0) + 1);\n\t\t\tthis.postings.push({ id: doc.id, length: tokens.length, counts });\n\t\t\ttotal += tokens.length;\n\t\t}\n\t\tthis.avgLength = this.postings.length > 0 ? total / this.postings.length : 0;\n\t}\n\n\tget size(): number {\n\t\treturn this.postings.length;\n\t}\n\n\t/** Top `k` documents for `query`, best first. Documents scoring zero are omitted. */\n\tsearch(query: string, k = 10): LexicalHit[] {\n\t\tconst terms = tokenize(query);\n\t\tif (terms.length === 0 || this.postings.length === 0) return [];\n\t\tconst n = this.postings.length;\n\n\t\tconst hits: LexicalHit[] = [];\n\t\tfor (const posting of this.postings) {\n\t\t\tlet score = 0;\n\t\t\tfor (const term of new Set(terms)) {\n\t\t\t\tconst tf = posting.counts.get(term);\n\t\t\t\tif (!tf) continue;\n\t\t\t\tconst df = this.docFreq.get(term) ?? 0;\n\t\t\t\t// Okapi IDF, floored at zero: a term in every document carries no\n\t\t\t\t// signal, and the raw formula would make it actively negative.\n\t\t\t\tconst idf = Math.max(0, Math.log(1 + (n - df + 0.5) / (df + 0.5)));\n\t\t\t\tconst norm = tf * (K1 + 1);\n\t\t\t\tconst denom = tf + K1 * (1 - B + (B * posting.length) / (this.avgLength || 1));\n\t\t\t\tscore += idf * (norm / denom);\n\t\t\t}\n\t\t\tif (score > 0) hits.push({ id: posting.id, score });\n\t\t}\n\n\t\t// Ties break by id so the same query always returns the same order — a\n\t\t// retrieval tool that reshuffles equal-scoring results is a reproducibility\n\t\t// problem disguised as a ranking one.\n\t\thits.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));\n\t\treturn hits.slice(0, k);\n\t}\n}\n"]}