@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/sfcc/log-gate.js

@@ -11,20 +11,36 @@
  * (BM username + 40-char WebDAV access key) that lives entirely server-side; the
  * spike proved an AM bearer token 401s on `/Logs`. Readiness is resolved by the
  * backend `GET /jira/sfcc/logs/capability` probe, which never returns a secret.
+ *
+ * BAPI-766 changed only the *representation* of this gate's failures: they now
+ * use the universal SFCC envelope from `sfcc-result.ts`, so one detection rule
+ * (`result.isError === true`) and one parse path cover the log surface too. The
+ * gate itself remains operationally separate — the WebDAV Basic-auth boundary is
+ * still distinct from the OCAPI AM-OAuth boundary, and the two gates are not
+ * merged. A capability-probe failure is reported with source `"webdav"`, never
+ * `"ocapi"`, because that is where it actually originates.
  */
+import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Envelope helpers
 // ---------------------------------------------------------------------------
-function jsonResult(payload) {
-    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
-}
+/**
+ * Build the unified log-gate not-configured failure.
+ *
+ * The 503 is synthetic — Bridge's own status, not something WebDAV returned — so
+ * no upstream HTTP status is supplied. `source` is `"gate"`, matching the OCAPI
+ * gate: the rejection is the gate's decision, not an upstream response.
+ */
 function notConfigured(failureClass, message, limits) {
-    return jsonResult({
-        error: "NOT_CONFIGURED",
+    return formatSfccFailure({
+        code: "NOT_CONFIGURED",
         status: 503,
-        failure_class: failureClass,
         message,
-        ...(limits !== undefined ? { limits } : {}),
+        source: "gate",
+        details: {
+            failure_class: failureClass,
+            ...(limits !== undefined ? { limits } : {}),
+        },
     });
 }
 // ---------------------------------------------------------------------------
@@ -54,22 +70,33 @@ export function withSfccLogGate(deps, handler) {
             const resp = await fetch(url, { headers: await deps.getGetHeaders() });
             if (!resp.ok) {
                 // Distinguish a Bridge auth/connectivity failure from "not configured".
-                return jsonResult({
-                    error: resp.status === 401 || resp.status === 403 ? "UNAUTHORIZED" : "SERVICE_UNAVAILABLE",
+                // The reported status IS the upstream status, so the shared formatter
+                // rightly omits a duplicate `upstream_http_status`.
+                return formatSfccFailure({
+                    code: resp.status === 401 || resp.status === 403
+                        ? "UNAUTHORIZED"
+                        : "SERVICE_UNAVAILABLE",
                     status: resp.status,
                     message: "Could not read the SFCC log capability from Bridge API " +
                         "(/jira/sfcc/logs/capability). Ensure your Bridge API key is set and the " +
                         "repo is authorized. Run sfcc_setup_status for a full diagnostic.",
+                    source: "webdav",
+                    details: {},
+                    upstreamHttpStatus: resp.status,
                 });
             }
             body = (await resp.json());
         }
         catch {
-            return jsonResult({
-                error: "BAD_GATEWAY",
+            // A synthetic 502: no upstream responded at all, so no upstream status
+            // may be reported.
+            return formatSfccFailure({
+                code: "BAD_GATEWAY",
                 status: 502,
                 message: "Could not reach Bridge API to resolve the SFCC log capability. " +
                     "Check that BAPI_BASE_URL points to a running Bridge API instance.",
+                source: "webdav",
+                details: {},
             });
         }
         if (body?.configured !== true) {

package/build/sfcc/log-query.js

@@ -11,9 +11,17 @@
  * The backend response has already passed through the `RedactionPort`, so its JSON
  * is returned to the LLM unchanged; there is deliberately NO local retrieval
  * bypass in TypeScript.
+ *
+ * BAPI-766 moved this tool's failure representation onto the universal SFCC
+ * envelope (`sfcc-result.ts`), so `result.isError === true` and one parse path
+ * cover the log surface exactly as they cover reads and writes. Redaction is
+ * untouched: a non-OK backend response contributes only its Bridge-authored
+ * string `detail` to `error.details`, and never raw text or an unknown payload
+ * whose redaction cannot be established (see `safeBackendDetail`).
  */
 import { z } from "zod";
 import { withSfccLogGate } from "./log-gate.js";
+import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Bounds — mirror src/python/sfcc_monitor/log_query.py (kept in lock-step).
 // ---------------------------------------------------------------------------
@@ -24,11 +32,42 @@ const MAX_SELECTED_PREFIXES = 5;
 const MAX_MAX_ENTRIES = 2000;
 const SUPPORTED_ENVIRONMENTS = ["production", "staging", "development"];
 const PREFIX_RE = /^[a-z][a-z0-9]*$/;
-function jsonResult(payload) {
-    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+/** Bridge-authored message for a non-OK backend query response. */
+function backendFailureMessage(status) {
+    return (`The Bridge API SFCC log-query endpoint returned HTTP ${status}. ` +
+        `No log content is included in this response.`);
+}
+/**
+ * Project a non-OK backend response body down to what is provably safe.
+ *
+ * Every failure the backend raises (`api/routes/sfcc_log_query.py`) is an
+ * `HTTPException` whose `detail` is a fixed Bridge-authored string — never log
+ * content. Anything else (a request-validation 422's structured list, an
+ * unparsed body, an unexpected payload) has no redaction guarantee, so it is
+ * dropped rather than forwarded. Redaction is a shipped safety property
+ * (BAPI-554); reformatting must not become a way around it.
+ */
+function safeBackendDetail(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const detail = parsed.detail;
+    return typeof detail === "string" ? { detail } : {};
 }
 function validationError(message) {
-    return jsonResult({ error: "VALIDATION_ERROR", status: 400, message });
+    return formatSfccFailure({
+        code: "VALIDATION_ERROR",
+        status: 400,
+        message,
+        source: "tool",
+        details: {},
+    });
 }
 // ---------------------------------------------------------------------------
 // Zod input schema
@@ -118,26 +157,27 @@ function buildHandler(deps) {
             });
         }
         catch {
-            return jsonResult({
-                error: "BAD_GATEWAY",
+            // Synthetic 502: nothing responded, so no upstream status may be reported.
+            return formatSfccFailure({
+                code: "BAD_GATEWAY",
                 status: 502,
                 message: "Could not reach Bridge API to run the SFCC log query. Check that " +
                     "BAPI_BASE_URL points to a running Bridge API instance.",
+                source: "webdav",
+                details: {},
             });
         }
         const text = await resp.text();
         if (!resp.ok) {
-            let detail = text;
-            try {
-                detail = JSON.parse(text);
-            }
-            catch {
-                /* keep raw text detail */
-            }
-            return jsonResult({
-                error: resp.status >= 500 ? "SERVICE_UNAVAILABLE" : "REQUEST_FAILED",
+            // The reported status IS the upstream status, so the shared formatter
+            // rightly omits a duplicate `upstream_http_status`.
+            return formatSfccFailure({
+                code: resp.status >= 500 ? "SERVICE_UNAVAILABLE" : "REQUEST_FAILED",
                 status: resp.status,
-                detail,
+                message: backendFailureMessage(resp.status),
+                source: "webdav",
+                details: safeBackendDetail(text),
+                upstreamHttpStatus: resp.status,
             });
         }
         // The backend response has already passed through RedactionPort — return it

package/build/sfcc/ocapi-shape.js

@@ -5,13 +5,49 @@
  * envelope. This module provides a typed extractor for the `data` array so
  * sub-task read tools share one normalizer rather than each re-deriving the
  * shape.
+ *
+ * Collection metadata lives under a single `page` object rather than at the top
+ * level (BAPI-760). Two properties of that metadata are load-bearing:
+ *
+ *   - `returned` is the actual length of the `items` array this call produced.
+ *     It is never read from the upstream `count` field, because OCAPI's `count`
+ *     is a request-echo (the page size asked for) and not a guarantee about how
+ *     many records came back.
+ *   - `total` exists ONLY when OCAPI itself supplied a numeric `total`. It is
+ *     never inferred from `items.length`, and it is absent — not `null`, not
+ *     `0` — when OCAPI omitted it. A consumer that sees no `total` knows the
+ *     instance-wide count is genuinely unavailable rather than zero.
+ *
+ * Nesting the metadata under `page` also keeps it from colliding with fields
+ * that legitimately live inside the returned resources: an OCAPI attribute
+ * search document carries its own `count` and `hits`, and those stay untouched
+ * inside `items`.
+ */
+/**
+ * Single constructor for page metadata, shared by both normalizers.
+ *
+ * Centralizing it means `returned`, `total`, and `has_more` cannot be derived
+ * two different ways in the strict and permissive paths. `total` is attached
+ * conditionally so an unsupplied total is an absent property rather than an
+ * explicit `undefined` that would serialize as a present-but-empty field.
  */
+function buildPageMeta(items, rawTotal, rawNext) {
+    const page = {
+        returned: items.length,
+        has_more: rawNext != null,
+    };
+    if (typeof rawTotal === "number") {
+        page.total = rawTotal;
+    }
+    return page;
+}
 /**
  * Parse a raw OCAPI response body into a normalized envelope result.
  *
  * Returns `null` when `body` is not a valid OCAPI paging envelope (missing
  * `data` array or `count` field), allowing callers to surface a structured
- * error instead of crashing.
+ * error instead of crashing. Strict validation is unchanged; only the returned
+ * metadata shape moved under `page`.
  */
 export function normalizeOcapiPage(body) {
     if (body === null ||
@@ -23,9 +59,7 @@ export function normalizeOcapiPage(body) {
     const envelope = body;
     return {
         items: envelope.data,
-        count: envelope.count,
-        total: envelope.total,
-        hasMore: envelope.next != null,
+        page: buildPageMeta(envelope.data, envelope.total, envelope.next),
     };
 }
 /**
@@ -40,11 +74,16 @@ export function normalizeOcapiPage(body) {
  *
  * Unlike `normalizeOcapiPage`, this function never returns null and is
  * forward-compatible with future OCAPI envelope shapes.
+ *
+ * Items are passed through verbatim in every branch. A bare object — including
+ * an attribute-search document with its own `count` and `hits` — becomes the
+ * single item unchanged; its `count` is never promoted to collection metadata,
+ * and a missing `hits` is never synthesized.
  */
 export function normalizeOcapiBody(body) {
     // Bare array
     if (Array.isArray(body)) {
-        return { items: body, count: body.length, total: undefined, hasMore: false };
+        return { items: body, page: buildPageMeta(body, undefined, null) };
     }
     // Object forms
     if (body !== null && typeof body === "object") {
@@ -52,18 +91,16 @@ export function normalizeOcapiBody(body) {
         // Wrapped envelope: has a data array (with or without explicit count)
         if (Array.isArray(obj.data)) {
             const items = obj.data;
-            return {
-                items,
-                count: typeof obj.count === "number" ? obj.count : items.length,
-                total: typeof obj.total === "number" ? obj.total : undefined,
-                hasMore: obj.next != null,
-            };
+            return { items, page: buildPageMeta(items, obj.total, obj.next) };
         }
-        // Bare object (single resource, no wrapping envelope)
-        return { items: [body], count: 1, total: undefined, hasMore: false };
+        // Bare object (single resource, no wrapping envelope). A directly supplied
+        // numeric `total` and paging signal are honored; the object's own `count`
+        // is left inside the item and never reinterpreted as a total.
+        const items = [body];
+        return { items, page: buildPageMeta(items, obj.total, obj.next) };
     }
     // Non-object (null, string, number, etc.)
-    return { items: [], count: 0, total: undefined, hasMore: false };
+    return { items: [], page: buildPageMeta([], undefined, null) };
 }
 /**
  * SPEC §4.5 `value_type` mapper.

package/build/sfcc/output.js

@@ -4,23 +4,30 @@
  * Re-exports the truncation + docs-path utilities through a stable sfcc/
  * interface so sub-task read tools import from here instead of reaching into
  * the host module directly. This boundary makes a future extraction cheap.
+ *
+ * Oversized responses return a JSON descriptor rather than a sliced prefix
+ * (BAPI-760). Slicing a serialized JSON payload at a fixed character offset
+ * almost always cuts mid-token, so what reached the caller was neither the data
+ * nor valid JSON — and appending an English note made it unparseable by
+ * construction. Every branch here now emits JSON the caller can parse, and the
+ * collection metadata travels outside the omitted data so `returned`, `total`,
+ * and `has_more` survive truncation.
  */
 import path from "path";
 import { mkdir, writeFile } from "fs/promises";
 /** Maximum characters returned inline; content beyond this is saved locally. */
 export const SFCC_MAX_INLINE = 50_000;
-/** Truncation note appended to truncated payloads. */
-function truncationNote(savedPath) {
-    return `\n\n[Response truncated — full payload saved to ${savedPath}]`;
-}
 /**
  * If `text` exceeds `SFCC_MAX_INLINE`, save it to `dir/filename` and return a
- * truncated version with a local-path note. Otherwise returns `text` unchanged.
+ * JSON truncation descriptor naming the saved file and carrying `page`.
+ * Otherwise returns `text` unchanged.
  *
- * Write failures are non-fatal: the full (un-truncated) text is returned with
- * a warning rather than throwing.
+ * Write failures are non-fatal: a JSON save-failure descriptor carrying the
+ * complete payload is returned rather than throwing. This is deliberately kept
+ * on the successful-read path — the OCAPI read itself succeeded, so it does not
+ * route through `formatSfccReadFailure` and does not set `isError`.
  */
-export async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
+export async function truncateAndSaveIfNeeded(text, dir, filename, page, deps = {}) {
     if (text.length <= SFCC_MAX_INLINE) {
         return text;
     }
@@ -32,8 +39,31 @@ export async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
         await wf(filePath, text, "utf-8");
     }
     catch (err) {
-        return (text +
-            `\n\nWarning: response was NOT truncated because local save failed: ${err instanceof Error ? err.message : String(err)}`);
+        const message = err instanceof Error ? err.message : String(err);
+        const descriptor = {
+            truncated: false,
+            save_failed: true,
+            oversized: true,
+            warning: `Response was NOT truncated because the local save failed: ${message}. ` +
+                `The complete payload is returned inline.`,
+            page,
+        };
+        // Parse before embedding so callers receive JSON data rather than a
+        // JSON string containing escaped JSON. If the caller's text was never
+        // valid JSON, fall back to carrying it verbatim as a string — the helper
+        // itself must never emit invalid JSON.
+        try {
+            descriptor.data = JSON.parse(text);
+        }
+        catch {
+            descriptor.data_text = text;
+        }
+        return JSON.stringify(descriptor);
     }
-    return text.slice(0, SFCC_MAX_INLINE) + truncationNote(filePath);
+    const descriptor = {
+        truncated: true,
+        saved_path: filePath,
+        page,
+    };
+    return JSON.stringify(descriptor);
 }

package/build/sfcc/permissions.js

@@ -82,7 +82,6 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
     }
     if (result.ok) {
         const normalized = normalizeOcapiPage(result.body);
-        const itemCount = normalized ? normalized.count : "unknown";
         return {
             content: [
                 {
@@ -90,7 +89,7 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
                     text: `✓ OCAPI access confirmed.\n` +
                         `  Instance: ${credentials.hostname.split(".")[0]}\n` +
                         `  OCAPI version: ${ocapiVersion}\n` +
-                        `  GET /system_object_definitions: ${itemCount} items returned`,
+                        `  GET /system_object_definitions: ${formatProbeCount(normalized)}`,
                 },
             ],
         };
@@ -116,6 +115,29 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
         ],
     };
 }
+/**
+ * Render the probe's count line without overstating what OCAPI reported.
+ *
+ * The probe reads one page, so the number of records it got back is a page
+ * count, not the instance-wide total. Saying "N items returned" made a page of
+ * 25 look like an instance that owns exactly 25 system objects. Three distinct
+ * cases are now distinguishable:
+ *
+ *   - OCAPI supplied a total  → "25 of 73 items returned"
+ *   - OCAPI omitted the total → the number is labelled as the current page and
+ *     the missing instance total is stated outright
+ *   - strict normalization failed → neither number is claimed
+ */
+function formatProbeCount(normalized) {
+    if (!normalized) {
+        return "page count and instance total unavailable (unrecognized response envelope)";
+    }
+    const { returned, total } = normalized.page;
+    if (total !== undefined) {
+        return `${returned} of ${total} items returned`;
+    }
+    return `${returned} items returned on this page (OCAPI did not provide the instance total)`;
+}
 function ocapiSettingsInstructions(ocapiVersion) {
     return (`To grant OCAPI access, paste the JSON below in Business Manager:\n` +
         `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +

package/build/sfcc/read-projection.js

@@ -0,0 +1,181 @@
+/**
+ * SFCC read projection policy (BAPI-767).
+ *
+ * WHY THIS MODULE EXISTS
+ * ----------------------
+ * Before BAPI-767 no `select` was constructed anywhere in the SFCC read path.
+ * The only occurrence of the OCAPI full-projection expression in the tree was
+ * the *grant template* in `permissions.ts` (`read_attributes: "(**)"`) — a
+ * permission the tools were never actually exercising. The consequence was the
+ * headline finding of the 2026-08-11 introspection report: an agent could
+ * enumerate every attribute id on a type and learn nothing about any of them —
+ * not the `value_type`, not `mandatory`, `localizable`, `searchable`, or
+ * `site_specific`. The MCP could *write* a type it could not read back.
+ *
+ * The fix is a projection, and the reason it lives in one module rather than in
+ * each handler is that the *default* is the load-bearing part. "Complete by
+ * default on attribute reads, lean by default on broad lists" is a single
+ * ratified policy; six handlers each deciding their own default is how that
+ * policy silently drifts. Requirement 2 of the ticket asks for exactly one
+ * place with its own test, and this is it.
+ *
+ * THE `(**)` EXPRESSION IS PRIVATE
+ * --------------------------------
+ * Callers select a `projection` of `"full"` or `"lean"`. They never see or pass
+ * raw OCAPI select syntax. That keeps the tool surface stable if the expression
+ * ever changes, and — more importantly — stops an agent from constructing an
+ * arbitrary select expression against a live instance.
+ *
+ * EVERY CATEGORY HERE WAS VERIFIED LIVE
+ * -------------------------------------
+ * The category table is not documentation-sourced. Each entry was probed
+ * against a developer sandbox (OCAPI Data API v25_6) before it was written, and
+ * the observed key-count expansion is recorded next to it. This matters because
+ * an unverified projection flag is worse than no flag: it reads as a capability
+ * and delivers nothing.
+ *
+ * `system_object_get` is deliberately ABSENT from this policy. Its endpoint,
+ * GET /system_object_definitions/{type}, already returns its complete 13-field
+ * document and ignores `select` entirely (verified: 13 keys with and without).
+ * Giving it a `projection` flag would ship a parameter with no observable
+ * effect — the same defect BAPI-760 removed from that very tool when it deleted
+ * the no-op `expand_attribute_definitions` boolean. A tool that cannot honor a
+ * projection does not get a projection input.
+ */
+import { z } from "zod";
+/** The two projection values, as a runtime-checkable list. */
+export const SFCC_READ_PROJECTIONS = ["full", "lean"];
+// ---------------------------------------------------------------------------
+// The policy
+// ---------------------------------------------------------------------------
+/**
+ * OCAPI's full-projection expression.
+ *
+ * Intentionally NOT exported. Only `selectExpressionFor` may map a projection
+ * onto it, so there is exactly one place where an outbound `select` value can
+ * originate.
+ */
+const FULL_SELECT_EXPRESSION = "(**)";
+/**
+ * The single endpoint-category → projection policy table (Requirement 2).
+ *
+ * Verified live against a developer sandbox, 2026-08-13 (OCAPI v25_6). The
+ * key-count expansions below are observations, not estimates:
+ *
+ *   attribute_search      POST .../attribute_definition_search
+ *                         system_object:        4 → 25 keys
+ *                         custom_object_def:    4 → 26 keys
+ *   attribute_collection  GET  .../attribute_definitions
+ *                         custom_object_def:    4 → 26 keys
+ *   broad_list            GET  /system_object_definitions
+ *                                               4 → 13 keys
+ *                         GET  .../SitePreferences/attribute_groups
+ *                                               4 → 10 keys
+ *
+ * The ratified requirement these defaults encode: complete by default on
+ * attribute reads, lean by default on broad lists, caller can override in
+ * either direction. An opt-in-only flag was explicitly rejected — the caller
+ * who does not know to ask is precisely the caller the report described.
+ */
+const PROJECTION_POLICY = {
+    attribute_search: {
+        defaultProjection: "full",
+        placement: "body",
+        inputDescription: "Detail level. Default: full (value_type, mandatory, localizable, searchable, site_specific); lean returns ids only.",
+    },
+    attribute_collection: {
+        defaultProjection: "full",
+        placement: "query",
+        inputDescription: "Detail level. Default: full (value_type, mandatory, localizable, searchable, site_specific); lean returns ids only.",
+    },
+    broad_list: {
+        defaultProjection: "lean",
+        placement: "query",
+        inputDescription: "Detail level. Default: lean (ids only); full returns all fields.",
+    },
+};
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the effective projection for a category.
+ *
+ * An omitted / undefined request resolves to the category default. An explicit
+ * caller value always wins — including an explicit `"lean"` on a full-default
+ * category, which is the "override in either direction" half of the
+ * requirement and is easy to lose to a truthiness check.
+ */
+export function resolveReadProjection(category, requested) {
+    return requested ?? PROJECTION_POLICY[category].defaultProjection;
+}
+/** The wire placement (`body` or `query`) for a category. */
+export function projectionPlacementFor(category) {
+    return PROJECTION_POLICY[category].placement;
+}
+/**
+ * Map an effective projection onto an OCAPI `select` expression.
+ *
+ * Returns `undefined` for `lean` — deliberately, so `lean` means "send no
+ * `select` at all" rather than "send an empty one". OCAPI's unqualified
+ * response is the lean shape; there is no lean expression to construct.
+ */
+export function selectExpressionFor(projection) {
+    return projection === "full" ? FULL_SELECT_EXPRESSION : undefined;
+}
+// ---------------------------------------------------------------------------
+// Application helpers
+// ---------------------------------------------------------------------------
+/**
+ * Apply the resolved projection to an OCAPI search POST body.
+ *
+ * Mutates and returns `body` so a handler can build its body normally and then
+ * hand it here as the last step. A `lean` resolution leaves the body untouched
+ * — no `select` key is added.
+ *
+ * Throws if the category is not body-placed, rather than silently writing a
+ * `select` into a body OCAPI would ignore for that endpoint.
+ */
+export function applyProjectionToBody(body, category, requested) {
+    if (projectionPlacementFor(category) !== "body") {
+        throw new Error(`SFCC read category "${category}" carries its projection in the query string, not the POST body.`);
+    }
+    const expression = selectExpressionFor(resolveReadProjection(category, requested));
+    if (expression !== undefined) {
+        body.select = expression;
+    }
+    return body;
+}
+/**
+ * Query-string entries carrying the resolved projection.
+ *
+ * Returns an empty object for `lean`, so a caller can spread it unconditionally
+ * into its query params without a conditional at each call site.
+ *
+ * Throws if the category is body-placed, for the same reason as above.
+ */
+export function projectionQueryEntries(category, requested) {
+    if (projectionPlacementFor(category) !== "query") {
+        throw new Error(`SFCC read category "${category}" carries its projection in the POST body, not the query string.`);
+    }
+    const expression = selectExpressionFor(resolveReadProjection(category, requested));
+    return expression === undefined ? {} : { select: expression };
+}
+// ---------------------------------------------------------------------------
+// Input schema
+// ---------------------------------------------------------------------------
+/**
+ * The optional `projection` Zod field for a category's input schema.
+ *
+ * The description is category-specific because the default differs by category,
+ * and the default is decision-critical *before* invocation — an agent choosing
+ * whether to pass `projection` cannot learn the answer from the response. It is
+ * kept to the fewest words that convey the default and the override, because
+ * every tool description and schema competes for the same tools/list token
+ * budget (see `integration/budget-config.ts`).
+ */
+export function projectionInputFor(category) {
+    return z
+        .enum(["full", "lean"])
+        .optional()
+        .describe(PROJECTION_POLICY[category].inputDescription);
+}