@orboto/mcp 0.193.0 → 0.194.0

package/dist/response-budget.js

@@ -1,44 +1,5 @@
 /**
  * ORB-1697 - the central MCP response budget.
- *
- * WHY THIS EXISTS
- * ---------------
- * An MCP tool result is not paid once. The client re-sends the whole
- * conversation on every subsequent request, so a result costs its size
- * TIMES the number of turns that follow it. The 2026-08-09 transcript
- * audit (6.453 real calls, 32 transcripts - see doc ORB-D20) measured
- * `list_agent_instructions` at 238 Mtok of carry cost from only THREE
- * calls, because 37k characters landed 15 % into a session and rode
- * along for the remaining 85 %.
- *
- * Two facts from that audit shape this module:
- *
- *  1. In Claude Code, only `structuredContent` reaches the model - the
- *     Markdown `content` block the handlers also build is dropped. So
- *     the budget MUST measure and cut the structured payload; cutting
- *     only the text would look like a fix and change nothing. Other
- *     clients do the opposite, so both are measured and both are cut.
- *  2. Per-tool discipline does not hold across 168 registered tools.
- *     The cap is applied once, in `with-metrics.ts`, which every tool
- *     is already registered through.
- *
- * CONTRACT
- * --------
- * Truncation is never silent. An over-budget result comes back with a
- * `__truncation` block naming every cut path, plus a handle, and the
- * omitted remainder stays fetchable via `orboto_response_expand` for
- * as long as the handle lives (in-process, 15 min, 16 payloads).
- *
- * Shrinking is shape-preserving: keys never disappear, arrays stay
- * arrays, and strings stay strings. That matters because 7 tools
- * declare an `outputSchema` the SDK validates the payload against.
- * Adding `__truncation` is safe (no schema uses `.strict()`, and Zod v3
- * accepts unknown keys), and identifier-shaped strings are protected by
- * MIN_STRING_CUT - a uuid (36) or a ticket key is far below it, so
- * `.uuid()` / `.url()` fields are never cut in half.
- *
- * This module never throws. A malformed payload returns unbudgeted
- * rather than failing the tool call.
  */
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
@@ -47,21 +8,7 @@ export const DEFAULT_BUDGET_CHARS = 4000;
 /**
  * Per-tool overrides.
  *
- * The default (4k) suits cards and lists: a response that answers
- * "which of these do I open?" does not need more. Two categories
- * legitimately need more and are raised deliberately:
- *
- *  - CONTENT READS. The caller explicitly asked for a document, a
- *    generated report or a primer. Cutting those to 4k would break the
- *    tool's purpose rather than remove waste.
- *
- * `orboto_session_start` used to be the third category at 48.000
- * characters, and ORB-1818 removed that exemption: the digest now
- * answers with a rules INDEX plus a hash instead of the full rule text,
- * so the default answer fits the 4k default like every other tool. The
- * two answers that DO carry the full rules (`forceRules: true`,
- * `rulesOnly: true`) protect them instead of buying size - see
- * PROTECTED_PATHS and PROTECT_TEXT_META below.
+ * @see ORB-1818
  */
 export const TOOL_BUDGET_CHARS = {
     orboto_get_project_primer: 16_000,
@@ -73,57 +20,18 @@ export const TOOL_BUDGET_CHARS = {
     orboto_customer_report: 16_000,
     orboto_requirements_spec: 16_000,
     orboto_get_attachment: 16_000,
-    // The continuation tool itself: a chunk is served AT the budget, so a
-    // cap equal to the default would truncate the chunk it just sized.
     orboto_response_expand: 8_000,
-    // ORB-1518 - detail mode returns a full endpoint schema (parameters +
-    // request body + responses), which is the content the caller asked
-    // for; 4k would cut most real schemas in half.
     orboto_api_search: 8_000,
-    // ORB-1519 - the proxy envelope IS the content the caller asked for
-    // (an arbitrary endpoint's response); the proxy already caps it, this
-    // budget keeps the MCP-side carry cost bounded on top.
     orboto_api_call: 8_000,
 };
 /**
  * Paths the shrinker must never touch, per tool.
- *
- * The shrinker cuts the LARGEST leaf first, which is the right default and
- * exactly wrong for one case: in `session_start` the largest string is the
- * workspace's binding rules. Truncating a mandatory rule to save context is
- * worse than paying for it - an agent that never sees the second half of a
- * rule breaks it silently. Measured on 2026-08-09: a cold
- * `session_start({ ticketKey })` is 47.694 characters, and without this
- * list the budget cut 2.917 characters out of the rules block.
- *
- * A protected path is not exempt from the budget - the shrinker moves on to
- * the next-largest cuttable leaf (for that call: the project primer, which
- * is a digest with its own server-side budget and is safe to cut
- * explicitly). If nothing else can be cut, the response reports
- * `atFloor: true` and stays whole.
  */
 export const PROTECTED_PATHS = {
     orboto_session_start: ['rules'],
 };
 /**
  * ORB-1818 - per-call protection of the TEXT half.
- *
- * PROTECTED_PATHS covers the structured half, which is what Claude Code
- * pays for; a text-only client pays the Markdown block instead, and that
- * half is cut on a line boundary with no notion of protected paths. For
- * an answer whose whole payload IS the binding rules (`session_start`
- * with `forceRules` or `rulesOnly`), cutting either half truncates a
- * mandatory rule - the exact thing the protection above exists to
- * prevent, just for the other client class.
- *
- * A handler marks such a result by setting `result._meta[PROTECT_TEXT_META]
- * = true`. The flag is READ AND REMOVED here, so it never reaches the
- * wire. It protects; it does not exempt: unprotected structured leaves in
- * the same result are still cut normally.
- *
- * This is deliberately not a general "skip the budget" escape hatch -
- * `protect-text-usage.test.ts` fails the build if a file other than the
- * session-start tool sets it.
  */
 export const PROTECT_TEXT_META = 'orboto/protectText';
 function takeProtectTextFlag(result) {
@@ -151,9 +59,6 @@ const MIN_ARRAY_CUT = 3;
 const MAX_CUT_PASSES = 64;
 export const HANDLE_TTL_MS = 15 * 60 * 1000;
 export const MAX_HANDLES = 16;
-// ---------------------------------------------------------------------------
-// Configuration
-// ---------------------------------------------------------------------------
 /**
  * `ORBOTO_MCP_RESPONSE_BUDGET=off` disables the cap entirely (escape
  * hatch for a client that genuinely wants everything);
@@ -170,9 +75,6 @@ export function budgetFor(toolName, env = process.env) {
     const raw = Number(env.ORBOTO_MCP_RESPONSE_BUDGET_CHARS);
     return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_BUDGET_CHARS;
 }
-// ---------------------------------------------------------------------------
-// Measurement - what the client actually pays for
-// ---------------------------------------------------------------------------
 function textOf(part) {
     if (part && typeof part === 'object' && 'text' in part) {
         const t = part.text;
@@ -183,14 +85,6 @@ function textOf(part) {
 }
 /**
  * The two halves a result is made of, measured separately.
- *
- * A handler returns the SAME data twice: `structuredContent` for
- * schema-aware clients and a Markdown text block for the rest. No known
- * client charges for both - Claude Code stores only the structured JSON
- * in its transcript (verified 2026-08-09), text-only clients see just the
- * text - so summing them would double-count and cut twice as hard as the
- * cost justifies. The budget is therefore enforced on each half, and the
- * reported cost is the larger of the two: what one client actually pays.
  */
 export function measureHalves(result) {
     let textChars = 0;
@@ -222,7 +116,6 @@ function pruneHandles(now) {
         if (now - value.storedAt > HANDLE_TTL_MS)
             handles.delete(key);
     }
-    // Map iteration order is insertion order, so the oldest entries go first.
     while (handles.size > MAX_HANDLES) {
         const oldest = handles.keys().next();
         if (oldest.done)
@@ -250,14 +143,10 @@ export function annotatePayload(handle, omitted) {
 export function resetPayloadStore() {
     handles.clear();
 }
-// ---------------------------------------------------------------------------
-// Path addressing - `ticketBundle.primer.markdown`, `comments[3].body`
-// ---------------------------------------------------------------------------
 export function resolvePath(root, path) {
     if (path === '' || path === '$')
         return root;
     let current = root;
-    // Split on `.` and `[i]` in one pass so both forms address the same tree.
     for (const token of path.split(/\.|(?=\[)/)) {
         if (current === null || current === undefined)
             return undefined;
@@ -290,7 +179,6 @@ function collectCandidates(root, protectedPaths = []) {
         if (!node || typeof node !== 'object')
             return;
         for (const [key, value] of Object.entries(node)) {
-            // Never cut the truncation metadata itself - it is the way back.
             if (key === '__truncation')
                 continue;
             const childPath = path ? `${path}.${key}` : key;
@@ -321,11 +209,6 @@ function collectCandidates(root, protectedPaths = []) {
     walk(root, '');
     return out.sort((a, b) => b.size - a.size);
 }
-// ORB-1738 - the ADVERTISED zod shape of the marker, consumed centrally in
-// registerWithMetrics: every declared outputSchema is extended with an
-// optional `__truncation` so strict clients (which validate structured
-// content against the advertised JSON schema, additionalProperties:false)
-// accept over-budget responses. Keep in lockstep with TruncationBlock.
 export const TruncationBlockSchema = z.object({
     handle: z.string(),
     budgetChars: z.number(),
@@ -344,17 +227,7 @@ export const TruncationBlockSchema = z.object({
 /**
  * ORB-1805 - what registerWithMetrics actually advertises.
  *
- * `TruncationBlockSchema` above is the exact runtime shape (and stays the
- * validator the tests assert against), but serialising all eight of its
- * fields costs ~620 characters in EVERY tool that declares an
- * outputSchema - 14 tools in the full manifest, 5 in the curated one -
- * for a block a caller only ever reads. The advertised form declares the
- * one field a caller acts on (`handle`) and stays open for the rest, so
- * a strict client still accepts an over-budget payload (ORB-1738, the
- * reason the marker is advertised at all) at a third of the bytes.
- *
- * Strictly more permissive than TruncationBlockSchema, so nothing that
- * validated before can fail now.
+ * @see ORB-1738
  */
 export const TruncationBlockAdvertisedSchema = z.object({ handle: z.string() })
     .passthrough()
@@ -369,9 +242,6 @@ function stringMarker(omitted, handle, path) {
  * admin MCP-usage panel instead of needing another transcript audit.
  */
 export function applyResponseBudget(toolName, result, env = process.env) {
-    // ORB-1818 - read (and strip) the per-call text protection before
-    // anything else, so the flag never rides the wire even on the
-    // under-budget path.
     const protectText = takeProtectTextFlag(result);
     const originalChars = measureResult(result);
     if (!budgetEnabled(env)) {
@@ -385,8 +255,6 @@ export function applyResponseBudget(toolName, result, env = process.env) {
         return shrink(toolName, result, budget, originalChars, protectText);
     }
     catch {
-        // A budget must never break a tool call. Report the real size so the
-        // panel still shows the pressure, and hand back the untouched result.
         return { result, responseChars: originalChars, originalChars, truncatedChars: 0 };
     }
 }
@@ -402,14 +270,9 @@ function shrink(toolName, result, budget, originalChars, protectText = false) {
     const structured = result.structuredContent === undefined
         ? undefined
         : JSON.parse(safeStringify(result.structuredContent));
-    // Reserve room for the truncation block and the text notice so the
-    // final measurement lands under budget, not just near it.
     const RESERVE = 700;
     const target = Math.max(MIN_STRING_KEEP, budget - RESERVE);
-    // Each half is capped against the same target - see measureHalves().
     const measure = () => (structured === undefined ? 0 : safeStringify(structured).length);
-    // The text half: cut on a line boundary so a reader never gets half a
-    // sentence, and record how much was dropped.
     let currentTextLength = fullText.length;
     let textOmitted = 0;
     if (!protectText && fullText.length > target) {
@@ -438,8 +301,6 @@ function shrink(toolName, result, budget, originalChars, protectText = false) {
             continue;
         }
         const items = largest.value;
-        // Drop from the tail: list tools order by relevance, so the head is
-        // the part a caller reads first.
         let keptItems = items.length;
         while (keptItems > MIN_ARRAY_KEEP) {
             const trial = items.slice(0, keptItems - 1);
@@ -462,10 +323,6 @@ function shrink(toolName, result, budget, originalChars, protectText = false) {
         : omitted;
     annotatePayload(handle, allOmitted);
     const atFloor = measure() > target;
-    // ORB-1818 - the floor case gets its OWN notice. Telling an agent its
-    // response was truncated when nothing was cut sends it hunting for a
-    // remainder that does not exist - and that is exactly what a protected
-    // answer (the binding rules) produces every time.
     const notice = allOmitted.length > 0
         ? `[Response truncated to the MCP response budget (${budget} chars) - it would otherwise cost `
             + `${originalChars} chars on EVERY later request in this session. Omitted content is not lost: `
@@ -484,20 +341,15 @@ function shrink(toolName, result, budget, originalChars, protectText = false) {
             ...(atFloor ? { atFloor: true } : {}),
         };
         structured.__truncation = block;
-        // The cost model is per-half (see measureHalves), so what was omitted
-        // is the shrinkage of the half that dominates the price.
         const finalChars = Math.max(safeStringify(structured).length, currentTextLength + notice.length + 2);
         block.omittedChars = Math.max(0, originalChars - finalChars);
     }
-    // Rebuild the content parts: the (possibly shortened) text plus the notice.
     const shortenedText = currentTextLength >= fullText.length
         ? fullText
         : fullText.slice(0, currentTextLength);
     const content = fullText.length > 0
         ? [{ type: 'text', text: `${shortenedText}\n\n${notice}` }]
         : [{ type: 'text', text: notice }];
-    // Non-text parts (images, resources) are never cut - they are not the
-    // bloat this budget is about, and slicing their payload would corrupt them.
     const nonText = (result.content ?? []).filter((part) => textOf(part) === null);
     const shrunk = {
         ...result,

package/dist/response-budget.test.js

@@ -1,15 +1,5 @@
 /**
  * ORB-1697 - the central response budget.
- *
- * The contract under test, in the order it matters:
- *   1. a result inside its budget is returned byte-identical;
- *   2. an over-budget result is CUT, and the cut is explicit;
- *   3. the cut preserves the payload SHAPE (keys stay, arrays stay
- *      arrays, identifier-shaped strings stay whole) - 7 tools declare an
- *      outputSchema the SDK validates the payload against;
- *   4. nothing is lost: the omitted remainder is fetchable via the handle;
- *   5. text and structured content are budgeted as separate halves, since
- *      no known client charges for both.
  */
 import { describe, it, expect, beforeEach } from 'vitest';
 import { applyResponseBudget, budgetFor, budgetEnabled, measureHalves, measureResult, readPayload, resetPayloadStore, resolvePath, DEFAULT_BUDGET_CHARS, MAX_HANDLES, HANDLE_TTL_MS, storePayload, PROTECT_TEXT_META, } from './response-budget.js';
@@ -34,11 +24,7 @@ beforeEach(() => {
 describe('budget configuration', () => {
     it('defaults to 4k and honours per-tool overrides', () => {
         expect(budgetFor('orboto_whatever', {})).toBe(DEFAULT_BUDGET_CHARS);
-        // A content read is deliberately higher.
         expect(budgetFor('orboto_get_doc', {})).toBeGreaterThan(DEFAULT_BUDGET_CHARS);
-        // ORB-1818 - session_start lost its 48k exemption: its default answer
-        // carries a rules INDEX plus a hash, not the rule text, so it lives on
-        // the plain default like every other tool.
         expect(budgetFor('orboto_session_start', {})).toBe(DEFAULT_BUDGET_CHARS);
     });
     it('reads a custom default from the env, per-tool overrides still win', () => {
@@ -65,7 +51,6 @@ describe('measurement', () => {
         const { textChars, structuredChars } = measureHalves(r);
         expect(textChars).toBe(300);
         expect(structuredChars).toBeGreaterThan(1000);
-        // Not the sum: no known client pays for both halves.
         expect(measureResult(r)).toBe(structuredChars);
     });
 });
@@ -95,8 +80,6 @@ describe('over budget', () => {
         expect(block.omittedChars).toBeGreaterThan(0);
         expect(String(block.howToGetTheRest)).toContain('orboto_response_expand');
         expect(block.omitted).toEqual(expect.arrayContaining([expect.objectContaining({ path: 'description', kind: 'string' })]));
-        // The text half carries the notice too, for clients that ignore
-        // structuredContent entirely.
         const text = out.result.content[0].text;
         expect(text).toContain('orboto_response_expand');
         expect(text).toContain(out.handle);
@@ -144,7 +127,6 @@ describe('shape preservation (outputSchema tools must still validate)', () => {
         const sc = out.result.structuredContent;
         expect(sc.items.length).toBeLessThan(60);
         expect(sc.items.length).toBeGreaterThan(0);
-        // Head-first: the first row survives, the tail is what goes.
         expect(sc.items[0].key).toBe('ORB-0');
         const entry = truncationOf(out.result).omitted
             .find((e) => e.path === 'items');
@@ -181,17 +163,13 @@ describe('shape preservation (outputSchema tools must still validate)', () => {
 });
 describe('the floor case - a payload made only of uncuttable leaves', () => {
     it('reports atFloor instead of looping or mangling identifiers', () => {
-        // 500 short strings: every one is below MIN_STRING_CUT, so there is
-        // nothing safe to cut. The budget must give up loudly, not spin.
         const structured = Object.fromEntries(Array.from({ length: 500 }, (_, i) => [`field_${i}`, `v${i}`.padEnd(90, 'x')]));
         const out = applyResponseBudget(TOOL, result(structured));
         expect(out.originalChars).toBeGreaterThan(budgetFor(TOOL));
         const block = truncationOf(out.result);
         expect(block.atFloor).toBe(true);
-        // Every field survived intact - a cut that cannot be made safely is
-        // not made at all.
         const sc = out.result.structuredContent;
-        expect(Object.keys(sc)).toHaveLength(501); // 500 fields + __truncation
+        expect(Object.keys(sc)).toHaveLength(501);
         expect(sc.field_0).toBe(structured.field_0);
     });
 });
@@ -262,10 +240,6 @@ describe('the handle store is bounded', () => {
 });
 describe('protected paths - a mandatory rule is never cut (ORB-1697)', () => {
     it('cuts the primer, not the rules, on an over-budget session_start', () => {
-        // The real shape: rules are the LARGEST string, so the default
-        // largest-first rule would have cut exactly the wrong thing. Measured
-        // on 2026-08-09 before this guard existed: 2.917 characters gone from
-        // the binding rules of a cold session_start({ ticketKey }).
         const rules = 'R'.repeat(24_000);
         const out = applyResponseBudget('orboto_session_start', result({
             rules,
@@ -289,12 +263,9 @@ describe('protected paths - a mandatory rule is never cut (ORB-1697)', () => {
     it('protects the subtree, not just the exact key', () => {
         const out = applyResponseBudget('orboto_session_start', result({
             rules: 'short rules',
-            // A hypothetical nested shape under a protected root stays protected.
             ticketBundle: { note: 'N'.repeat(80_000) },
         }));
         const sc = out.result.structuredContent;
-        // ticketBundle is NOT protected, so this one does get cut - the guard is
-        // path-scoped, not a blanket exemption.
         expect(sc.ticketBundle.note.length).toBeLessThan(80_000);
     });
 });
@@ -315,10 +286,8 @@ describe('per-call text protection (ORB-1818)', () => {
         expect(out.result.structuredContent.rules).toBe(rules);
         const text = out.result.content[0].text;
         expect(text).toContain(rules);
-        // The floor notice must not claim a truncation that did not happen.
         expect(text).not.toContain('Response truncated');
         expect(text).toContain('NOTHING was omitted');
-        // The marker is transport-internal - it never reaches the client.
         expect(out.result._meta).toBeUndefined();
     });
     it('protects the text half only - unprotected structured leaves are still cut', () => {