@salesforce/graphiti 11.15.0 → 11.16.0

package/dist/lib/query-builder.js

@@ -3,10 +3,22 @@
  * All rights reserved.
  * For full license text, see the LICENSE.txt file
  */
-import { GRAPHQL_NAME_RE } from "./graphql-name.js";
+import { UserInputError } from "./errors.js";
+import { assertGraphqlName, GRAPHQL_NAME_RE } from "./graphql-name.js";
 import { getChildren, getEffectiveArgs } from "./session.js";
 /**
  * Renders a QuerySession's selection tree into a properly formatted GraphQL query string.
+ *
+ * @throws if any emitted GraphQL Name (operation name, variable name, field
+ * name, alias, inline-fragment type condition, or directive name) is not a
+ * valid GraphQL Name, if a variable's type reference has a non-Name innermost
+ * NamedType, or if a `{`/`[`-prefixed argument/default value is not valid JSON
+ * — the W-23204027 render-layer fail-safe. This fires only on a programmer
+ * error (a builder/CLI path that stored a raw identifier without its own guard)
+ * or a hostile input that slipped past the per-builder guards; every legitimate
+ * value passes. Name violations throw an `Error` whose message matches
+ * USER_INPUT_RE; the JSON-literal violation throws a typed `UserInputError` —
+ * both classify as UserInput at the MCP boundary (`runTool`).
  */
 export function renderQuery(session) {
     const parts = [];
@@ -14,14 +26,41 @@ export function renderQuery(session) {
     const varDefs = session.variables.length > 0
         ? `(${session.variables
             .map((v) => {
+            // Fail-safe: the variable NAME is a GraphQL Name position emitted
+            // verbatim as `$<name>`. The TYPE is also emitted verbatim, but it
+            // is not a bare Name — it carries type-reference syntax (`!`, `[]`)
+            // — so it is guarded structurally by assertGraphqlType, which walks
+            // the wrappers and asserts only the innermost NamedType.
+            assertGraphqlName(v.name, "renderQuery", "variableName");
+            assertGraphqlType(v.type, "renderQuery");
             let def = `$${v.name}: ${v.type}`;
+            // W-23204027 (PR #694 review): the default VALUE is a value position,
+            // not a Name — it must be formatted like any other arg value, not
+            // concatenated raw. Raw emission both breaks legitimate output (a
+            // multi-word string default renders `= Acme Corp`, which fails to
+            // parse) and is a live selection-set/operation injection sink: a
+            // default of `5) { stolen { Id } } query Decoy($z: Int` (reachable
+            // via `sf_gql_raw`'s `var $x <path> '<default>'`) would otherwise
+            // render a second, attacker-controlled operation. formatArgValue
+            // quotes strings, passes through numbers/enums/bools/`$refs`, and
+            // routes `{`/`[` defaults through jsonToGraphQL, which either emits
+            // an arg-key-guarded input-object literal (valid JSON) or throws
+            // (invalid JSON — see Round 3 fix in jsonToGraphQL). No variant
+            // reaches raw emission.
             if (v.defaultValue !== undefined)
-                def += ` = ${v.defaultValue}`;
+                def += ` = ${formatArgValue(v.defaultValue)}`;
             return def;
         })
             .join(", ")})`
         : "";
     const operationKeyword = session.operation === "aggregate" ? "query" : session.operation;
+    // Fail-safe: operationName is a GraphQL Name position emitted verbatim in the
+    // operation header. Guarded at every builder, but a deserialized/migrated
+    // session (loadSession reads it from disk with no re-validation) or a future
+    // builder could bypass that — so backstop it here too.
+    if (session.operationName) {
+        assertGraphqlName(session.operationName, "renderQuery", "operationName");
+    }
     const operationName = session.operationName ? ` ${session.operationName}` : "";
     const operationBody = renderChildren(session, null, 1);
     if (operationBody) {
@@ -34,6 +73,61 @@ export function renderQuery(session) {
     }
     return parts.join("\n");
 }
+/**
+ * W-23204027 render-layer fail-safe for GraphQL argument KEYS. An argument key
+ * is emitted verbatim as `<key>: <value>` in three places — a field's argument
+ * names (renderField), a directive's argument names (renderDirective), and the
+ * keys of a nested input-object literal (valueToGraphQL). The last is
+ * attacker-reachable today: `sf_gql_list` / `sf_gql_aggregate` accept a `filter`
+ * / `orderBy` typed as `z.record(z.unknown())` (no charset on keys), the builder
+ * `JSON.stringify`s it into an arg value, and valueToGraphQL then emits each
+ * input field name / operator as a key. A key such as
+ * `Name: {eq:"x"} }) { edges { node { Id } } } evilAlias: accounts(where: { Industry`
+ * would otherwise render a fully parseable, schema-valid second connection —
+ * a silent selection-set injection. Keys are NOT validated at the builder or
+ * zod layer, so this render-layer assert is the only universal choke point
+ * (everything funnels through the renderer). Every legitimate key — operators
+ * (eq/ne/and/or/not/…), SObject field API names incl. `Custom__c`, connection
+ * args — is a valid GraphQL Name, so this never fires on real input.
+ */
+function assertArgumentKey(key, emitter) {
+    assertGraphqlName(key, emitter, "argumentKey");
+}
+/**
+ * W-23204027 render-layer fail-safe for a variable's TYPE reference. Unlike a
+ * Name position, a type carries GraphQL type-reference syntax (`!` for
+ * non-null, `[...]` for lists) and so cannot be a bare `assertGraphqlName` —
+ * that would wrongly reject legitimate types like `Int!` or `[ID!]!`. Instead
+ * we walk the type-reference grammar structurally (October 2021 §2.11): strip a
+ * trailing non-null `!`, unwrap a `[ ... ]` list wrapper (recursing on the inner
+ * type), and finally assert the innermost NamedType is a valid GraphQL Name.
+ *
+ * This is a defense-in-depth backstop, not a live-reachable sink today: every
+ * `addVariable` call site derives the type from schema inference,
+ * `createInputTypeName`, or a hardcoded scalar — none accept a raw type from the
+ * agent (the CLI `var`/`define` verbs set only the NAME, never the type). It
+ * guards the residual paths a Name backstop would otherwise miss: a
+ * deserialized/migrated session (`loadSession` does no type re-validation) or a
+ * future builder that stores a raw type. Without it, a type such as
+ * `Int) { evil { id } } query Decoy($z: Int` emitted verbatim as `$v: <type>`
+ * breaks out into a second operation with no default value needed.
+ */
+function assertGraphqlType(type, emitter) {
+    let inner = type.trim();
+    // Peel any number of non-null / list wrappers from the outside in.
+    while (true) {
+        if (inner.endsWith("!")) {
+            inner = inner.slice(0, -1).trim();
+            continue;
+        }
+        if (inner.startsWith("[") && inner.endsWith("]")) {
+            inner = inner.slice(1, -1).trim();
+            continue;
+        }
+        break;
+    }
+    assertGraphqlName(inner, emitter, "variableType");
+}
 function renderChildren(session, parentId, depth) {
     const _indent = "  ".repeat(depth);
     const lines = [];
@@ -50,15 +144,29 @@ function renderChildren(session, parentId, depth) {
 function renderField(session, node, depth) {
     const indent = "  ".repeat(depth);
     let line = indent;
-    // Alias
+    // W-23204027 render-layer fail-safe: assert every emitted GraphQL Name is
+    // valid, making "the renderer never emits an injectable identifier" a
+    // system-wide invariant layered UNDER the per-builder guards (W-22735537),
+    // not replacing them. Fires only on a programmer error — a future builder
+    // that calls selectLeaf/selectDottedFieldPath and forgets its assert — so
+    // failing loud is correct. The message matches USER_INPUT_RE, so the MCP
+    // path classifies it as UserInput rather than crashing. Argument *keys* are
+    // covered too: they are emitted verbatim as `<key>: <value>` here and in
+    // renderDirective/valueToGraphQL, so a malicious filter/orderBy key (a
+    // z.record(z.unknown()) with no charset at the schema boundary — see
+    // assertArgumentKey) can otherwise break out of the argument object into
+    // the selection set. That sink is NOT closed at the builder or zod layer.
     if (node.alias) {
+        assertGraphqlName(node.alias, "renderField", "alias");
         line += `${node.alias}: `;
     }
+    assertGraphqlName(node.fieldName, "renderField", "fieldName");
     line += node.fieldName;
     // Arguments
     const argEntries = Object.entries(getEffectiveArgs(session, node));
     if (argEntries.length > 0) {
         const argParts = argEntries.map(([name, value]) => {
+            assertArgumentKey(name, "renderField");
             return `${name}: ${formatArgValue(value)}`;
         });
         line += `(${argParts.join(", ")})`;
@@ -78,6 +186,9 @@ function renderField(session, node, depth) {
 }
 function renderInlineFragment(session, frag, depth) {
     const indent = "  ".repeat(depth);
+    // W-23204027 render-layer fail-safe (see renderField): a type condition is a
+    // GraphQL Name position emitted verbatim after `... on `.
+    assertGraphqlName(frag.onType, "renderInlineFragment", "onType");
     let line = `${indent}... on ${frag.onType}`;
     for (const dir of frag.directives) {
         line += ` ${renderDirective(dir)}`;
@@ -92,11 +203,19 @@ function renderInlineFragment(session, frag, depth) {
     return line;
 }
 function renderDirective(dir) {
+    // W-23204027 render-layer fail-safe (see renderField): a directive name is a
+    // GraphQL Name position emitted verbatim after `@`. The only directive the
+    // declarative/MCP surface adds is `@optional` (a valid Name), so this never
+    // fires on legitimate output.
+    assertGraphqlName(dir.name, "renderDirective", "directiveName");
     const argEntries = Object.entries(dir.args);
     if (argEntries.length === 0) {
         return `@${dir.name}`;
     }
-    const argParts = argEntries.map(([name, value]) => `${name}: ${formatArgValue(value)}`);
+    const argParts = argEntries.map(([name, value]) => {
+        assertArgumentKey(name, "renderDirective");
+        return `${name}: ${formatArgValue(value)}`;
+    });
     return `@${dir.name}(${argParts.join(", ")})`;
 }
 /**
@@ -123,9 +242,23 @@ function formatArgValue(value) {
     if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
         return jsonToGraphQL(trimmed);
     }
-    // Quoted string — pass through
-    if (trimmed.startsWith('"') && trimmed.endsWith('"'))
-        return trimmed;
+    // Quoted string — pass through ONLY when it is a single, well-formed string
+    // literal. W-23204027 (PR #694 review): a bare `startsWith('"') && endsWith('"')`
+    // check is an injection hole — a payload like
+    // `"a") { stolen } query Y($q: String = "b"` also starts and ends with a quote
+    // yet breaks out of the value into a second operation. JSON.parse yielding a
+    // string proves the whole token is ONE literal (interior quotes are escaped);
+    // anything else falls through to JSON.stringify, which re-encodes it as a safe
+    // single literal.
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            if (typeof JSON.parse(trimmed) === "string")
+                return trimmed;
+        }
+        catch {
+            // Not a single well-formed literal — re-encode below.
+        }
+    }
     // Default: a string literal. JSON.stringify produces a spec-valid GraphQL string
     // literal — it escapes line terminators and control chars (\n \r \t \b \f) and
     // quotes/backslashes — so values like "a\nb" don't render a raw newline that
@@ -138,14 +271,34 @@ function formatArgValue(value) {
  * GraphQL uses unquoted keys: { Status: { ne: "Closed" } }
  */
 function jsonToGraphQL(jsonStr) {
+    let parsed;
     try {
-        const parsed = JSON.parse(jsonStr);
-        return valueToGraphQL(parsed);
+        parsed = JSON.parse(jsonStr);
     }
     catch {
-        // If not valid JSON, return as-is (might already be in GraphQL format)
-        return jsonStr;
+        // W-23204027 (PR #694 review, Round 3): REJECT — do NOT return the raw
+        // string. `formatArgValue` only routes here when the value starts with `{`
+        // or `[`, so a JSON.parse failure means it is a `{`/`[`-prefixed string
+        // that is NOT well-formed JSON — never legitimate GraphQL. Every real
+        // producer of a `{`/`[` value delivers valid JSON (the builders
+        // `JSON.stringify` filter/orderBy; the CLI `set`/`assign` path
+        // JSON-validates `{`/`[` literals in `validateLiteralAssignment` before
+        // storing), so this rejects zero legitimate flows. Returning it verbatim
+        // bypassed valueToGraphQL's `assertArgumentKey`, making it a live
+        // selection-set/operation injection sink: a variable default of
+        // `{ minRevenue: 0 }) { edges { node { id } } } } query Decoy($z: Filter`
+        // (unquoted key ⇒ invalid JSON ⇒ this catch; reachable via `sf_gql_raw`'s
+        // `var $x <path> '<default>'`) rendered a second, attacker-controlled
+        // operation. Throw a typed UserInputError (NOT a bare Error whose text
+        // would miss USER_INPUT_RE and misclassify as Internal) so `runTool`
+        // classifies it UserInput.
+        throw new UserInputError(`jsonToGraphQL: value beginning with '{' or '[' is not valid JSON and cannot be rendered as a GraphQL literal: ${jsonStr.slice(0, 60)}`);
     }
+    // valueToGraphQL runs OUTSIDE the try: it enforces the W-23204027 arg-key
+    // fail-safe by throwing on a malicious input-object key, and that assertion
+    // must propagate — not be swallowed and fall back to emitting the raw
+    // (injectable) string.
+    return valueToGraphQL(parsed);
 }
 function valueToGraphQL(value) {
     if (value === null || value === undefined)
@@ -173,7 +326,16 @@ function valueToGraphQL(value) {
     }
     if (typeof value === "object") {
         const entries = Object.entries(value);
-        const parts = entries.map(([k, v]) => `${k}: ${valueToGraphQL(v)}`);
+        const parts = entries.map(([k, v]) => {
+            // The live arg-key injection sink: filter/orderBy objects are
+            // JSON.stringify'd into an arg value by the builders, so every input
+            // field name / operator here is an attacker-controllable key emitted
+            // verbatim into a GraphQL input-object literal. Guard it (see
+            // assertArgumentKey). Array elements never reach this branch as keys —
+            // the Array case above emits `[...]` with no `<key>:`.
+            assertArgumentKey(k, "valueToGraphQL");
+            return `${k}: ${valueToGraphQL(v)}`;
+        });
         return `{ ${parts.join(", ")} }`;
     }
     return String(value);

package/dist/lib/query-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-builder.js","sourceRoot":"","sources":["../../src/lib/query-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query-builder.js","sourceRoot":"","sources":["../../src/lib/query-builder.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/sf-gql-connect.js

@@ -9,7 +9,7 @@ import { runTool } from "../../schemas/tool-adapter.js";
 const inputSchema = CONNECT_INPUT.shape;
 export function registerSfGqlConnectTool(server, opts = {}) {
     server.registerTool("sf_gql_connect", {
-        description: "Connect to a Salesforce org and prime its GraphQL schema cache. With forceRefresh, re-download the schema and coherently clear all caches so subsequent tools see freshly-deployed metadata. Concurrent refreshes coalesce into a single introspection. Returns { org, instanceUrl, refreshed, cached, durationMs, warnings? } — not the standard ToolOutput envelope. If a refresh fails but a usable cached schema survives, returns refreshed:false with a staleness warning instead of erroring. Error convention (all sf_gql_* tools): on failure the isError text is prefixed with a category — `UserInput:` (fix the request), `Auth:` (re-authenticate the org), `Schema:` (introspection/cache problem), or `Internal:` (unexpected) — so you can decide whether to fix inputs, re-auth, or retry.",
+        description: "Connect to a Salesforce org and prime its GraphQL schema cache. With forceRefresh, re-download the schema and coherently clear all caches so subsequent tools see freshly-deployed metadata. Concurrent refreshes coalesce into a single introspection. Returns { org, instanceUrl, refreshed, cached, durationMs, warnings? } — not the standard ToolOutput envelope. If a refresh fails but a usable cached schema survives, returns refreshed:false with a staleness warning instead of erroring. Error convention (all sf_gql_* tools): on failure the isError text is prefixed with a category — `UserInput:` (fix the request), `Auth:` (re-authenticate the org), `Schema:` (introspection/cache problem), or `Internal:` (unexpected) — so you can decide whether to fix inputs, re-auth, or retry. A `Schema:` error additionally ends with a retryability token: `[retry=now]` (retry immediately — e.g. a priming-lock timeout, where no live org round-trip occurred) or `[retry=backoff]` (the org was unreachable and an automatic retry already failed — wait with increasing backoff, e.g. 2^n seconds capped around 8s, and retry serially; do not fan out concurrent retries against an org that is already failing, and note some conditions such as an org API rate limit may take longer than a few seconds to clear); ABSENCE of any `[retry=...]` token means the failure is permanent (404, missing/malformed `__schema`, GraphQL errors in the body, or no cached schema) — do not retry, fix the request or re-prime via sf_gql_connect. This token convention applies to every sf_gql_* tool, not just this one. Example error text: `Schema: introspection request failed [retry=backoff]`; extract the disposition with the end-anchored regex ` /\\s\\[retry=(now|backoff)\\]$/` (no match ⇒ permanent).",
         inputSchema,
     }, async (args) => runTool(() => buildConnect(args, opts)));
 }

package/dist/mcp/tools/sf-gql-connect.js.map

@@ -1 +1 @@
-{"version":3,"file":"sf-gql-connect.js","sourceRoot":"","sources":["../../../src/mcp/tools/sf-gql-connect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAIxD,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC;AAExC,MAAM,UAAU,wBAAwB,CACvC,MAAiB,EACjB,OAAgC,EAAE;IAElC,MAAM,CAAC,YAAY,CAClB,gBAAgB,EAChB;QACC,WAAW,EACV,6wBAA6wB;QAC9wB,WAAW;KACX,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CACvD,CAAC;AACH,CAAC"}
+{"version":3,"file":"sf-gql-connect.js","sourceRoot":"","sources":["../../../src/mcp/tools/sf-gql-connect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAIxD,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC;AAExC,MAAM,UAAU,wBAAwB,CACvC,MAAiB,EACjB,OAAgC,EAAE;IAElC,MAAM,CAAC,YAAY,CAClB,gBAAgB,EAChB;QACC,WAAW,EACV,wuDAAwuD;QACzuD,WAAW;KACX,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CACvD,CAAC;AACH,CAAC"}

package/dist/schemas/tool-adapter.d.ts

@@ -3,6 +3,7 @@
  * All rights reserved.
  * For full license text, see the LICENSE.txt file
  */
+import { type RetryHint } from "../lib/errors.js";
 /**
  * Shared MCP tool adapter (W-22697673). Wraps an intent invocation so that any
  * throw becomes a sanitized, category-prefixed error envelope instead of leaking
@@ -20,6 +21,17 @@
  * untyped throws. The sanitized message is returned for EVERY category — not
  * just Internal — because typed Auth/Schema errors embed cache/lock paths and
  * wrapped jsforce/@salesforce/core causes embed `~/.sfdx/...` paths.
+ *
+ * Retryability hint (W-23148365): a `Schema:` error — and ONLY a `Schema:` error —
+ * additionally ends with a closed-set token telling the host whether to retry:
+ * ` [retry=now]` (retry immediately; no live org round-trip occurred — a priming-
+ * lock timeout, or a refresh where a usable cached schema survives), ` [retry=backoff]`
+ * (the introspection request failed transiently AND already exhausted the
+ * connection layer's one built-in retry — wait briefly), or NO token (permanent:
+ * 4xx, malformed/absent `__schema`, GraphQL errors in the body, no cached schema —
+ * don't retry; fix the request, re-auth, or re-prime). The `<Category>: ` prefix is
+ * unchanged. The disposition comes from the typed error's stamped `retry` field,
+ * with a defensive `cause`-chain fallback (`classifyCause`) for untyped throws.
  */
 export type ErrorCategory = "UserInput" | "Auth" | "Schema" | "Internal";
 interface ToolTextResult {
@@ -51,9 +63,13 @@ export declare const PATH_MARKERS: {
  * carries the `u` flag so they match (and escape) as a single code point.
  */
 export declare function neutralizeControlChars(s: string): string;
-/** Classify a thrown error into a category + sanitized message text. */
+/**
+ * Classify a thrown error into a category, a Schema-only retry hint, and a
+ * sanitized message text. `retry` is `"no"` for every non-Schema category.
+ */
 export declare function classifyError(e: unknown): {
     category: ErrorCategory;
+    retry: RetryHint;
     text: string;
 };
 /**

package/dist/schemas/tool-adapter.js

@@ -4,7 +4,7 @@
  * For full license text, see the LICENSE.txt file
  */
 import os from "node:os";
-import { AuthError, SchemaError, UserInputError } from "../lib/errors.js";
+import { AuthError, classifyCause, SchemaError, UserInputError, } from "../lib/errors.js";
 import { graphitiHome, schemaDir } from "../lib/introspect.js";
 import { SchemaRefreshError } from "../lib/prime-schema.js";
 import { MutationContextError } from "../lib/walker.js";
@@ -141,19 +141,38 @@ function categoryOf(e, message) {
         return "Schema";
     return "Internal";
 }
-/** Classify a thrown error into a category + sanitized message text. */
+/**
+ * Retryability disposition for a Schema-category error (W-23148365). The typed
+ * SchemaError/SchemaRefreshError carry an authoritative `retry` stamped at the
+ * throw site; for an untyped throw that reached the Schema bucket via the
+ * SCHEMA_RE heuristic we fall back to inspecting its `cause`. Only ever called
+ * for the Schema category — Auth/UserInput/Internal are uniformly `"no"`.
+ */
+function retryHintFor(e) {
+    if (e instanceof SchemaError || e instanceof SchemaRefreshError)
+        return e.retry;
+    if (typeof e === "object" && e !== null && "cause" in e) {
+        return classifyCause(e.cause);
+    }
+    return "no";
+}
+/**
+ * Classify a thrown error into a category, a Schema-only retry hint, and a
+ * sanitized message text. `retry` is `"no"` for every non-Schema category.
+ */
 export function classifyError(e) {
     const message = e instanceof Error ? e.message : String(e);
     const category = categoryOf(e, message);
+    const retry = category === "Schema" ? retryHintFor(e) : "no";
     const safeMessage = sanitizePaths(message);
     if (category !== "Internal")
-        return { category, text: safeMessage };
+        return { category, retry, text: safeMessage };
     // Internal: unexpected. Attach a truncated, path-stripped stack for the host.
     const frames = truncatedStack(e);
     const text = frames.length
         ? `${safeMessage}\n${frames.map((f) => `  ${f}`).join("\n")}`
         : safeMessage;
-    return { category, text };
+    return { category, retry, text };
 }
 /**
  * Run an MCP tool's intent invocation. Returns the success envelope
@@ -169,13 +188,17 @@ export async function runTool(fn) {
         return { content: [{ type: "text", text: stripLineSeparators(JSON.stringify(output)) }] };
     }
     catch (e) {
-        const { category, text } = classifyError(e);
+        const { category, retry, text } = classifyError(e);
         if (category === "Internal") {
             console.error("[graphiti-mcp] Internal tool error:", e);
         }
+        // Append the retry hint as an end-anchored token (W-23148365). Only a
+        // Schema error ever carries a non-"no" hint; the `<Category>: ` prefix is
+        // unchanged so existing host parses (startsWith / split) still work.
+        const suffix = retry === "no" ? "" : ` [retry=${retry}]`;
         return {
             isError: true,
-            content: [{ type: "text", text: stripLineSeparators(`${category}: ${text}`) }],
+            content: [{ type: "text", text: stripLineSeparators(`${category}: ${text}${suffix}`) }],
         };
     }
 }

package/dist/schemas/tool-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-adapter.js","sourceRoot":"","sources":["../../src/schemas/tool-adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-adapter.js","sourceRoot":"","sources":["../../src/schemas/tool-adapter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/graphiti",
-  "version": "11.15.0",
+  "version": "11.16.0",
   "description": "Progressive GraphQL query builder CLI for Salesforce orgs",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",

package/src/intent/__tests__/build-aggregate.spec.ts

@@ -757,6 +757,30 @@ describe("intent/build-aggregate", () => {
 		},
 	);
 
+	// W-23204027: `aggregations[].field` was the second unguarded sink (the
+	// schema boundary types it as `z.string()` with no charset). It must be
+	// rejected at the builder layer like `alias`/`groupBy`, not just by the
+	// renderField fail-safe. `Amount } injectedAlias: Name { value` is the
+	// selection-set-breakout payload class from W-22735537.
+	it.each([
+		"Amount } injectedAlias: Name { value",
+		"}}__schema{types{name",
+		"1foo",
+		"foo bar",
+	] as const)("aggregation field '%s' is rejected as not a valid GraphQL Name", async (field) => {
+		await expect(
+			buildAggregate(
+				{
+					org: ORG,
+					object: "Order",
+					groupBy: [],
+					aggregations: [{ function: "sum", field }],
+				},
+				noopPrimeDeps(),
+			),
+		).rejects.toThrow(/buildAggregate: field .* is not a valid GraphQL Name/);
+	});
+
 	it("rejects an operationName that is not a valid GraphQL Name", async () => {
 		await expect(
 			buildAggregate(

package/src/intent/__tests__/build-output.spec.ts

@@ -6,13 +6,17 @@
 
 import { buildSchema } from "graphql";
 import { describe, expect, it } from "vitest";
-import { createSession, selectLeaf } from "../../lib/session.js";
+import { createSession, type FieldProjectionNode, selectLeaf } from "../../lib/session.js";
 import { buildOutput } from "../build-output.js";
 
 const schema = buildSchema(`
 	type Query { ping: String }
 `);
 
+const argSchema = buildSchema(`
+	type Query { accounts(first: Int): String }
+`);
+
 describe("intent/build-output", () => {
 	it("renders query, no warnings on valid query", () => {
 		const session = createSession("test", "query");
@@ -52,4 +56,23 @@ describe("intent/build-output", () => {
 		expect(out.types).toMatch(/\/\/ Type generation failed:/);
 		expect(out.warnings.some((w) => w.startsWith("Codegen:"))).toBe(true);
 	});
+
+	// W-23204027 (PR #694 review): buildOutput's docstring no longer claims "Never
+	// throws". renderQuery runs OUTSIDE the try/catch and enforces the render-layer
+	// fail-safe, so a hostile identifier/arg-key that slipped past the per-builder
+	// guards throws instead of emitting an injectable name. This is caught and
+	// classified UserInput at the MCP boundary (runTool), but direct callers must
+	// be prepared for it — and it must NOT be swallowed into warnings[], which would
+	// let an injected selection reach the output. This test pins that contract.
+	it("propagates the render-layer fail-safe throw (does not swallow it into warnings)", () => {
+		const session = createSession("test", "query");
+		selectLeaf(session, ["accounts"]);
+		const node = session.nodes.find(
+			(n): n is FieldProjectionNode => n.kind === "field" && n.fieldName === "accounts",
+		)!;
+		// A raw, injectable argument key (as sf_gql_raw's `set <path> @args/<key>`
+		// could plant) — never a valid GraphQL Name.
+		node.args["first) { stolen } evil("] = "1";
+		expect(() => buildOutput(session, argSchema)).toThrow(/is not a valid GraphQL Name/);
+	});
 });

package/src/intent/build-aggregate.ts

@@ -117,6 +117,12 @@ export async function buildAggregate(spec: AggregateSpec, deps?: PrimeDeps): Pro
 			assertGraphqlName(agg.alias, "buildAggregate", "alias");
 		}
 		const field = agg.field ?? "Id";
+		// W-23204027: `aggregations[].field` is `z.string()` with no charset at the
+		// schema boundary, so guard it per-builder like `alias`/`groupBy field` —
+		// it flows raw into createSiblingFieldInstance → node.fieldName → rendered
+		// verbatim. The renderField fail-safe backstops this; this is the matching
+		// builder-layer defense-in-depth (parity with W-22735537).
+		assertGraphqlName(field, "buildAggregate", "field");
 		const key = agg.alias ?? defaultKey(agg.function, field);
 		if (seenKeys.has(key)) {
 			throw new Error(

package/src/intent/build-output.ts

@@ -27,11 +27,25 @@ const OPTIONAL_DIRECTIVE_UNKNOWN_MARKER = 'Unknown directive "@optional"';
  * Render → validate → codegen → assemble. Shared finalizer for every typed
  * intent function (`buildList`, `buildDetail`, …).
  *
- * Never throws. Failure modes surface as entries in `warnings[]`:
+ * Validation and codegen never throw — their failure modes surface as entries in
+ * `warnings[]`:
  * - `Validation: <msg>` — non-schema-level errors from `graphql-js validate()`.
  * - `Validation: schema check skipped (<msg>)` — `validate()` itself crashed.
  * - `Codegen: <msg>` — `generateTypes()` threw; `types` becomes `// Type generation failed: <msg>`.
  *
+ * `renderQuery`, however, CAN throw — by design. It runs before (outside) the
+ * try/catch and enforces the W-23204027 render-layer fail-safe: if any emitted
+ * GraphQL Name (operation/variable/field name, alias, type condition, directive
+ * name) or argument key is not a valid GraphQL Name, it throws rather than emit
+ * an injectable identifier. This fires only on a programmer error or a hostile
+ * input that slipped past the per-builder guards (e.g. a `filter`/`orderBy` key —
+ * `z.record(z.unknown())` with no charset). At the MCP boundary `runTool`
+ * catches it and the message (`… is not a valid GraphQL Name`) is classified as
+ * `UserInput`, so failing loud is safe there. Direct callers (e.g. an eval
+ * harness) that bypass that boundary must be prepared for the throw. Do NOT move
+ * `renderQuery` into the try below — that would swallow the fail-safe and let an
+ * injected selection reach the output.
+ *
  * Schema-level errors (e.g. "Input Object type X must define one or more fields"
  * raised by malformed UIAPI schemas, not by the user's query) are filtered out
  * per FR-9.2.