@salesforce/graphiti 11.14.0 → 11.16.0

package/src/lib/query-builder.ts

@@ -4,12 +4,24 @@
  * 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 type { QuerySession, ProjectionNode, DirectiveNode } from "./session.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: QuerySession): string {
 	const parts: string[] = [];
@@ -19,14 +31,41 @@ export function renderQuery(session: QuerySession): string {
 		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}`;
-						if (v.defaultValue !== undefined) def += ` = ${v.defaultValue}`;
+						// 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 += ` = ${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) {
@@ -40,6 +79,63 @@ export function renderQuery(session: QuerySession): string {
 	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: string, emitter: string): void {
+	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: string, emitter: string): void {
+	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: QuerySession, parentId: string | null, depth: number): string {
 	const _indent = "  ".repeat(depth);
 	const lines: string[] = [];
@@ -63,17 +159,31 @@ function renderField(
 	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(", ")})`;
@@ -102,6 +212,9 @@ function renderInlineFragment(
 	depth: number,
 ): string {
 	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) {
@@ -119,11 +232,19 @@ function renderInlineFragment(
 }
 
 function renderDirective(dir: DirectiveNode): string {
+	// 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(", ")})`;
 }
 
@@ -153,8 +274,21 @@ function formatArgValue(value: string): string {
 		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
@@ -169,13 +303,35 @@ function formatArgValue(value: string): string {
  * GraphQL uses unquoted keys: { Status: { ne: "Closed" } }
  */
 function jsonToGraphQL(jsonStr: string): string {
+	let parsed: unknown;
 	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: unknown): string {
@@ -199,7 +355,16 @@ function valueToGraphQL(value: unknown): string {
 	}
 	if (typeof value === "object") {
 		const entries = Object.entries(value as Record<string, unknown>);
-		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/src/mcp/tools/__tests__/error-surface.contract.spec.ts

@@ -224,7 +224,8 @@ describe("mcp/tools error surface — category prefixes (contract)", () => {
 
 	it("Schema: an introspection/priming failure surfaces with the Schema prefix", async () => {
 		// No prior disk cache (fresh GRAPHITI_HOME) + a download that throws an
-		// untyped error → primeSchemaWithLock wraps it as SchemaError.
+		// untyped error WITH NO structured cause → primeSchemaWithLock wraps it as
+		// SchemaError and classifyCause(undefined) → "no", so no retry token.
 		const primeDeps: PrimeDeps = {
 			...makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA),
 			downloadSchema: async () => {
@@ -239,6 +240,54 @@ describe("mcp/tools error surface — category prefixes (contract)", () => {
 			});
 			expect(result.isError).toBe(true);
 			expect(errorText(result)).toMatch(/^Schema: /);
+			// An untyped cause-less failure is treated as permanent (no token).
+			expect(errorText(result)).not.toMatch(/\[retry=/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("Schema (retry=backoff): a transient network cause surfaces a backoff token end-to-end", async () => {
+		// W-23148365: a download failure whose cause carries a transient errno is
+		// wrapped as SchemaError({ retry: classifyCause(cause) }) → "backoff".
+		const primeDeps: PrimeDeps = {
+			...makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA),
+			downloadSchema: async () => {
+				throw Object.assign(new Error("socket hang up"), { code: "ECONNRESET" });
+			},
+		};
+		const { client, server } = await connectWith(primeDeps);
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"] },
+			});
+			expect(result.isError).toBe(true);
+			expect(errorText(result)).toMatch(/^Schema: /);
+			expect(errorText(result)).toMatch(/ \[retry=backoff\]$/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("Schema (permanent): a 4xx cause surfaces NO retry token end-to-end", async () => {
+		const primeDeps: PrimeDeps = {
+			...makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA),
+			downloadSchema: async () => {
+				throw Object.assign(new Error("not found"), { statusCode: 404 });
+			},
+		};
+		const { client, server } = await connectWith(primeDeps);
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"] },
+			});
+			expect(result.isError).toBe(true);
+			expect(errorText(result)).toMatch(/^Schema: /);
+			expect(errorText(result)).not.toMatch(/\[retry=/);
 		} finally {
 			await client.close();
 			await server.close();

package/src/mcp/tools/sf-gql-connect.ts

@@ -21,7 +21,7 @@ export function registerSfGqlConnectTool(
 		"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.",
+				"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/src/schemas/__tests__/tool-adapter.spec.ts

@@ -6,7 +6,7 @@
 
 import os from "node:os";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { AuthError, SchemaError, UserInputError } from "../../lib/errors.js";
+import { AuthError, classifyCause, SchemaError, UserInputError } from "../../lib/errors.js";
 import { SchemaRefreshError } from "../../lib/prime-schema.js";
 import { MutationContextError } from "../../lib/walker.js";
 import { classifyError, neutralizeControlChars, PATH_MARKERS, runTool } from "../tool-adapter.js";
@@ -49,6 +49,21 @@ describe("schemas/tool-adapter — classifyError", () => {
 			const r = classifyError(new SchemaError("buildList: is not a valid GraphQL Name"));
 			expect(r.category).toBe("Schema");
 		});
+
+		// W-23204027 (PR #694 review, Round 3): the render-layer jsonToGraphQL
+		// catch-sink fix throws a *typed* UserInputError. This pins WHY it must be
+		// typed and not a bare Error: its message ("… is not valid JSON and cannot
+		// be rendered as a GraphQL literal") is NOT anchored by USER_INPUT_RE, so a
+		// bare Error carrying it would fall through to Internal — misclassifying a
+		// user-input mistake and hiding an injection attempt in the operator log.
+		it("routes the jsonToGraphQL literal-rejection UserInputError to UserInput", () => {
+			const msg =
+				"jsonToGraphQL: value beginning with '{' or '[' is not valid JSON and cannot be rendered as a GraphQL literal: { minRevenue: 0 })";
+			expect(classifyError(new UserInputError(msg)).category).toBe("UserInput");
+			// The same message on a BARE Error is NOT anchored by USER_INPUT_RE —
+			// this is the exact trap the typed throw avoids.
+			expect(classifyError(new Error(msg)).category).toBe("Internal");
+		});
 	});
 
 	describe("heuristic routing (untyped fallbacks)", () => {
@@ -443,3 +458,149 @@ describe("schemas/tool-adapter — runTool", () => {
 		expect(spy).not.toHaveBeenCalled();
 	});
 });
+
+describe("schemas/tool-adapter — Schema retryability hint (W-23148365)", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	describe("classifyCause — the new cause-inspection logic", () => {
+		it("maps transient HTTP statuses to backoff", () => {
+			for (const statusCode of [420, 429, 500, 502, 503, 504]) {
+				expect(classifyCause({ statusCode })).toBe("backoff");
+			}
+		});
+
+		it("maps deterministic 4xx statuses to no", () => {
+			for (const statusCode of [400, 401, 403, 404, 409, 422]) {
+				expect(classifyCause({ statusCode })).toBe("no");
+			}
+		});
+
+		it("maps transient network errnos (org round-trip failures) to backoff", () => {
+			for (const code of ["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN", "ECONNREFUSED", "EPIPE"]) {
+				expect(classifyCause({ code })).toBe("backoff");
+			}
+		});
+
+		it("maps permanent errnos (wrong host, no perms) to no", () => {
+			for (const code of ["ENOTFOUND", "EACCES", "EROFS", "ENOENT"]) {
+				expect(classifyCause({ code })).toBe("no");
+			}
+		});
+
+		// Review #2: local resource-exhaustion errnos come from the cache write
+		// (atomicWriteJson), which shares the download try — they are NOT org
+		// round-trips, so a `backoff` ("org unreachable, wait 1-2s") hint would be
+		// wrong and mask an ops problem. They must classify as `no`.
+		it("maps local resource-exhaustion errnos (disk full / fd exhaustion) to no", () => {
+			for (const code of ["ENOSPC", "EMFILE", "EAGAIN"]) {
+				expect(classifyCause({ code })).toBe("no");
+			}
+		});
+
+		it("parses ERROR_HTTP_<nnn> from errorCode/name and REQUEST_LIMIT_EXCEEDED", () => {
+			expect(classifyCause({ errorCode: "ERROR_HTTP_502" })).toBe("backoff");
+			expect(classifyCause({ name: "ERROR_HTTP_503" })).toBe("backoff");
+			expect(classifyCause({ errorCode: "ERROR_HTTP_404" })).toBe("no");
+			expect(classifyCause({ errorCode: "REQUEST_LIMIT_EXCEEDED" })).toBe("backoff");
+		});
+
+		it("defaults to no for an absent/unrecognized cause (never invents retryability)", () => {
+			expect(classifyCause(undefined)).toBe("no");
+			expect(classifyCause(null)).toBe("no");
+			expect(classifyCause("a bare string")).toBe("no");
+			expect(classifyCause({ unrelated: true })).toBe("no");
+			expect(classifyCause({ statusCode: 418 })).toBe("no");
+		});
+
+		// Defensive: a cause with a throwing accessor must not escape (classifyCause
+		// runs inside runTool's catch; an escaped throw would drop the sanitized
+		// envelope). It falls back to the conservative "no" default.
+		it("returns no for a cause whose property accessor throws (no escape)", () => {
+			const booby = {};
+			Object.defineProperty(booby, "statusCode", {
+				get() {
+					throw new Error("boom");
+				},
+				enumerable: true,
+			});
+			expect(() => classifyCause(booby)).not.toThrow();
+			expect(classifyCause(booby)).toBe("no");
+		});
+	});
+
+	describe("classifyError().retry", () => {
+		it("reads the stamped retry off a typed SchemaError", () => {
+			expect(classifyError(new SchemaError("lock timeout", { retry: "now" })).retry).toBe("now");
+			expect(classifyError(new SchemaError("priming failed", { retry: "backoff" })).retry).toBe(
+				"backoff",
+			);
+			expect(classifyError(new SchemaError("no cache", { retry: "no" })).retry).toBe("no");
+		});
+
+		it("falls back to the cause chain for an untyped throw routed to Schema", () => {
+			// Untyped Error whose message matches SCHEMA_RE, carrying a transient cause.
+			const e = new Error("No cached schema after socket hang up");
+			(e as { cause?: unknown }).cause = { statusCode: 503 };
+			const r = classifyError(e);
+			expect(r.category).toBe("Schema");
+			expect(r.retry).toBe("backoff");
+		});
+
+		it("a bare SchemaError (no stamp, no cause) defaults to no — regression guard for existing cases", () => {
+			expect(classifyError(new SchemaError("No cached schema for org")).retry).toBe("no");
+		});
+
+		it("a SchemaRefreshError carries its stamped disposition", () => {
+			const transient = new SchemaRefreshError("refresh failed; keeping cache", {
+				instanceUrl: "https://x.my.salesforce.com",
+				staleSince: "2026-06-29T00:00:00.000Z",
+				retry: "backoff",
+			});
+			expect(classifyError(transient).retry).toBe("backoff");
+		});
+
+		it("non-Schema categories are uniformly no", () => {
+			expect(classifyError(new AuthError("Failed to get org info")).retry).toBe("no");
+			expect(classifyError(new UserInputError("bad input")).retry).toBe("no");
+			expect(classifyError(new Error("kaboom")).retry).toBe("no"); // Internal
+		});
+	});
+
+	describe("runTool token suffix", () => {
+		it("appends [retry=backoff] to a transient Schema error, after the Schema: prefix", async () => {
+			const result = await runTool(async () => {
+				throw new SchemaError("priming failed", { retry: "backoff" });
+			});
+			const text = result.content[0]?.text ?? "";
+			expect(text.startsWith("Schema: ")).toBe(true);
+			expect(text).toMatch(/ \[retry=backoff\]$/);
+		});
+
+		it("appends [retry=now] to a retry-now Schema error", async () => {
+			const result = await runTool(async () => {
+				throw new SchemaError("lock timeout", { retry: "now" });
+			});
+			expect(result.content[0]?.text).toMatch(/ \[retry=now\]$/);
+		});
+
+		it("appends NO token to a permanent Schema error (regression: bare 'No cached schema')", async () => {
+			const result = await runTool(async () => {
+				throw new SchemaError("No cached schema");
+			});
+			const text = result.content[0]?.text ?? "";
+			expect(text).toBe("Schema: No cached schema");
+			expect(text).not.toMatch(/\[retry=/);
+		});
+
+		it("never appends a token to a non-Schema category", async () => {
+			const result = await runTool(async () => {
+				throw new AuthError("Failed to get org info");
+			});
+			const text = result.content[0]?.text ?? "";
+			expect(text.startsWith("Auth: ")).toBe(true);
+			expect(text).not.toMatch(/\[retry=/);
+		});
+	});
+});

package/src/schemas/tool-adapter.ts

@@ -5,7 +5,13 @@
  */
 
 import os from "node:os";
-import { AuthError, SchemaError, UserInputError } from "../lib/errors.js";
+import {
+	AuthError,
+	classifyCause,
+	type RetryHint,
+	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";
@@ -27,6 +33,17 @@ import { MutationContextError } from "../lib/walker.js";
  * 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";
@@ -178,19 +195,42 @@ function categoryOf(e: unknown, message: string): ErrorCategory {
 	return "Internal";
 }
 
-/** Classify a thrown error into a category + sanitized message text. */
-export function classifyError(e: unknown): { category: ErrorCategory; text: string } {
+/**
+ * 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: unknown): RetryHint {
+	if (e instanceof SchemaError || e instanceof SchemaRefreshError) return e.retry;
+	if (typeof e === "object" && e !== null && "cause" in e) {
+		return classifyCause((e as { cause?: unknown }).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: unknown): {
+	category: ErrorCategory;
+	retry: RetryHint;
+	text: string;
+} {
 	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 };
+	if (category !== "Internal") 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 };
 }
 
 /**
@@ -206,13 +246,17 @@ export async function runTool(fn: () => Promise<unknown>): Promise<ToolTextResul
 		// carry them and JSON.stringify won't escape them (MCP TS SDK #2155).
 		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}`) }],
 		};
 	}
 }