@salesforce/graphiti 11.34.0 → 11.34.2

package/package.json

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

package/src/commands/mcp-mirror/commands.ts

@@ -57,7 +57,12 @@ export interface MirrorCommand {
 function defineMirror<T>(
 	name: string,
 	summary: string,
-	schema: z.ZodType<T>,
+	// Input type is `unknown`, not `T`: the schema validates a raw parsed-JSON
+	// blob, and some fields wrap the value in a `z.preprocess` (jsonCoercible,
+	// enumStripControlChars) whose Zod input type is `unknown`. Only the OUTPUT
+	// must be `T`. Pinning the input to `T` (the default `z.ZodType<T>`) would
+	// reject those preprocess-wrapped schemas.
+	schema: z.ZodType<T, z.ZodTypeDef, unknown>,
 	build: (input: T) => Promise<unknown>,
 ): MirrorCommand {
 	return { name, summary, run: (jsonArg) => runMirror(jsonArg, schema, build) };

package/src/commands/mcp-mirror/run-mirror.ts

@@ -88,7 +88,10 @@ function emitError(code: MirrorErrorCode, message: string, details?: unknown): v
  */
 export async function runMirror<T>(
 	jsonArg: string | undefined,
-	schema: z.ZodType<T>,
+	// Input type is `unknown` (a raw parsed-JSON blob), not `T`: `z.preprocess`-
+	// wrapped fields (jsonCoercible, enumStripControlChars) have a Zod input type
+	// of `unknown`, so only the parsed OUTPUT is `T`. See defineMirror in commands.ts.
+	schema: z.ZodType<T, z.ZodTypeDef, unknown>,
 	build: (input: T) => Promise<unknown>,
 	deps: RunMirrorDeps = {},
 ): Promise<void> {

package/src/lib/__tests__/control-chars.spec.ts

@@ -0,0 +1,155 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+	CONTROL_CHAR_RE,
+	LINE_SEPARATOR_RE,
+	stripControlChars,
+	stripLineSeparators,
+} from "../control-chars.js";
+
+/**
+ * Single source of truth for the Unicode control (Cc) + format (Cf) class shared
+ * by the two host-visible-text sinks: the error-envelope escaper
+ * (schemas/tool-adapter.ts neutralizeControlChars) and the enum-rejection
+ * stripper (schemas/fields.ts enumStripControlChars, W-23336443). The exhaustive
+ * membership matrix lives here; each consumer's spec keeps just the cases that
+ * prove its DISPOSITION (escape vs strip). Every dangerous char is written as a
+ * \u escape (house style, matching tool-adapter.spec.ts) so the source carries
+ * no invisible bytes and stays reviewable; only printable Unicode that must be
+ * PRESERVED (accents, CJK) is written as a literal.
+ */
+describe("lib/control-chars", () => {
+	// One representative per sub-class. stripControlChars output carries no JSON
+	// pretty-printing, so a whole-class assertion over the RESULT is exact here
+	// (unlike an end-to-end SDK envelope, whose pretty-print newlines are
+	// themselves Cc -- there we must assert specific injected code points).
+	const MEMBERS: [string, string][] = [
+		["C0 LF", "\n"],
+		["C0 CR", "\r"],
+		["C0 TAB", "\t"],
+		["C0 NUL", "\x00"],
+		["C0 ESC", "\x1b"],
+		["DEL", "\x7f"],
+		["C1 low (PAD)", "\x80"],
+		["C1 CSI", "\x9b"],
+		["NEL", "\u{85}"],
+		["soft hyphen (Cf)", "\u{ad}"],
+		["Arabic Letter Mark (Cf, Bidi_Control)", "\u{61c}"],
+		["ZWSP", "\u{200b}"],
+		["ZWNJ", "\u{200c}"],
+		["ZWJ", "\u{200d}"],
+		["word joiner", "\u{2060}"],
+		["bidi RLO", "\u{202e}"],
+		["bidi LRI", "\u{2066}"],
+		["invisible times", "\u{2062}"],
+		["interlinear anchor", "\u{fff9}"],
+		["BOM/ZWNBSP", "\u{feff}"],
+		["tag block (astral)", "\u{e0001}"],
+	];
+
+	describe("CONTROL_CHAR_RE", () => {
+		it.each(MEMBERS)("matches %s", (_label, ch) => {
+			// CONTROL_CHAR_RE carries the `g` flag, so `.test()` is stateful --
+			// reset lastIndex before probing.
+			CONTROL_CHAR_RE.lastIndex = 0;
+			expect(CONTROL_CHAR_RE.test(ch)).toBe(true);
+		});
+
+		it.each([
+			["ASCII letter", "A"],
+			["digit", "7"],
+			["space", " "],
+			["accented", "café"],
+			["CJK", "日本語"],
+			["emoji (astral)", "\u{1f600}"],
+			["line separator U+2028 (Zl, not Cc/Cf)", "\u{2028}"],
+			["paragraph separator U+2029 (Zp, not Cc/Cf)", "\u{2029}"],
+		])("does NOT match %s", (_label, ch) => {
+			CONTROL_CHAR_RE.lastIndex = 0;
+			expect(CONTROL_CHAR_RE.test(ch)).toBe(false);
+		});
+
+		it("carries the g + u flags (required by both consumers' .replace)", () => {
+			expect(CONTROL_CHAR_RE.flags).toContain("g");
+			expect(CONTROL_CHAR_RE.flags).toContain("u");
+		});
+	});
+
+	describe("stripControlChars", () => {
+		it.each(MEMBERS)("deletes %s entirely", (_label, ch) => {
+			expect(stripControlChars(`a${ch}b`)).toBe("ab");
+		});
+
+		it("deletes every occurrence, not just the first", () => {
+			expect(stripControlChars("a\u{202e}b\u{200b}c\x7fd")).toBe("abcd");
+		});
+
+		it("leaves ordinary Unicode (accents, CJK, emoji) untouched", () => {
+			const ok = "plain ASCII café 日本語 naïve \u{1f600}";
+			expect(stripControlChars(ok)).toBe(ok);
+		});
+
+		it("leaves U+2028/U+2029 untouched (Zl/Zp are out of scope here)", () => {
+			expect(stripControlChars("a\u{2028}b\u{2029}c")).toBe("a\u{2028}b\u{2029}c");
+		});
+
+		it("strips a value to its intended enum member (the W-23336443 case)", () => {
+			// A bidi-poisoned-but-otherwise-valid enum value strips to the clean
+			// member, so validation ACCEPTS it (no reflected message at all).
+			expect(stripControlChars("describe_object\u{202e}")).toBe("describe_object");
+			// A genuinely-invalid poisoned value strips to an inert token -- the
+			// rejection message it produces downstream carries no raw control char.
+			expect(stripControlChars("\u{200b}bogus\x7f")).toBe("bogus");
+		});
+
+		it("output of any stripped string contains no Cc/Cf code point", () => {
+			// Whole-class assertion is valid on the RAW stripped output (no JSON
+			// pretty-print), so this locks round-trip completeness directly.
+			const poison = MEMBERS.map(([, ch]) => ch).join("x");
+			const cleaned = stripControlChars(poison);
+			expect(cleaned).not.toMatch(/[\p{Cc}\p{Cf}]/u);
+			expect(cleaned).toBe("x".repeat(MEMBERS.length - 1));
+		});
+	});
+
+	// U+2028/U+2029 are Zl/Zp -- NOT part of CONTROL_CHAR_RE (asserted above) --
+	// so they get their own primitive. Every host-visible sink strips them
+	// separately because raw, they trip a Claude.AI 408 (MCP TS SDK #2155): the
+	// envelope in tool-adapter.ts and, upstream of it, the enum-rejection path
+	// (fields.ts enumStripControlChars, W-23336443).
+	describe("LINE_SEPARATOR_RE / stripLineSeparators", () => {
+		it.each([
+			["line separator U+2028 (Zl)", "\u{2028}"],
+			["paragraph separator U+2029 (Zp)", "\u{2029}"],
+		])("matches + deletes %s", (_label, ch) => {
+			LINE_SEPARATOR_RE.lastIndex = 0;
+			expect(LINE_SEPARATOR_RE.test(ch)).toBe(true);
+			expect(stripLineSeparators(`a${ch}b`)).toBe("ab");
+		});
+
+		it.each([
+			["ASCII newline (a Cc, handled by the other primitive)", "\n"],
+			["ordinary space", " "],
+			["accented", "café"],
+			["bidi RLO (a Cf, handled by the other primitive)", "\u{202e}"],
+		])("does NOT match %s (out of the Zl/Zp scope)", (_label, ch) => {
+			LINE_SEPARATOR_RE.lastIndex = 0;
+			expect(LINE_SEPARATOR_RE.test(ch)).toBe(false);
+		});
+
+		it("deletes every occurrence, leaving ordinary text intact", () => {
+			expect(stripLineSeparators("a\u{2028}b\u{2029}c\u{2028}d")).toBe("abcd");
+			const ok = "plain café 日本語";
+			expect(stripLineSeparators(ok)).toBe(ok);
+		});
+
+		it("carries the g flag (required by .replace to hit every occurrence)", () => {
+			expect(LINE_SEPARATOR_RE.flags).toContain("g");
+		});
+	});
+});

package/src/lib/control-chars.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Canonical Unicode control (Cc: C0/C1/DEL) + format (Cf) character class
+ * (W-23148363, OWASP LLM01). Left raw in host-visible MCP text, these code
+ * points let caller-supplied input forge structure or hide/reorder content:
+ * newlines/CR fabricate "SYSTEM:"-style lines, ESC (U+001B) opens ANSI/SGR
+ * sequences, NEL (U+0085) and the C1 8-bit CSI (U+009B) are alternate
+ * line/escape introducers, and the Cf set (bidi overrides/marks/isolates incl
+ * U+061C, zero-width joiners/spaces, word joiner, BOM, invisible-math
+ * operators, soft hyphen, and the U+E0000–E007F "tag" smuggling block)
+ * reorders or hides text.
+ *
+ * Matched by Unicode property escape so the set tracks future Cc/Cf additions
+ * rather than a hand-enumerated range that drifts (an earlier explicit range
+ * silently missed U+061C / ZWNJ / ZWJ / tag chars — all Cf). This is the SINGLE
+ * SOURCE OF TRUTH for the class: the error-envelope escaper
+ * (`schemas/tool-adapter.ts` `neutralizeControlChars`) and the enum-rejection
+ * stripper (`schemas/fields.ts` `enumStripControlChars`, W-23336443) both
+ * consume it so the two sinks cannot diverge.
+ *
+ * NOTE the two consumers differ in DISPOSITION, deliberately:
+ *  - the error envelope ESCAPES (each char → a visible `\xNN`/`\uNNNN` literal)
+ *    so a reflected byte stays debuggable but inert;
+ *  - the enum-rejection path STRIPS (deletes the char) — a z.enum only ever
+ *    reflects the invalid value verbatim inside its own message, so there is
+ *    nothing to preserve, and stripping keeps the advertised allowed-value list
+ *    (which contains no control chars) an exact round-trip.
+ * U+2028/U+2029 are intentionally OUT of this Cc/Cf class (they are Zl/Zp, not
+ * Cc/Cf); every host-visible sink strips them SEPARATELY via the sibling
+ * {@link LINE_SEPARATOR_RE} / {@link stripLineSeparators} below.
+ */
+export const CONTROL_CHAR_RE = /[\p{Cc}\p{Cf}]/gu;
+
+/**
+ * Delete every {@link CONTROL_CHAR_RE} code point from `s`. Used to sanitize a
+ * value BEFORE it can be reflected verbatim into a validation-rejection message
+ * that the MCP SDK emits UPSTREAM of the tool adapter (W-23336443), where the
+ * adapter's escaping neutralizer never runs. Ordinary Unicode (accented names,
+ * CJK labels) is untouched.
+ */
+export function stripControlChars(s: string): string {
+	return s.replace(CONTROL_CHAR_RE, "");
+}
+
+/**
+ * Unicode line/paragraph separators (U+2028 Zl / U+2029 Zp). These are legal in
+ * JSON strings and are NOT escaped by `JSON.stringify`, and left raw in
+ * host-visible MCP text they trip a Claude.AI 408 timeout (MCP TS SDK #2155).
+ * They are NOT part of {@link CONTROL_CHAR_RE} (that class is Cc/Cf, and its
+ * escaper consumer emits `\xNN`/`\uNNNN` — a disposition that would be wrong for
+ * these). Every host-visible sink therefore strips them separately: the error/
+ * success envelopes (`schemas/tool-adapter.ts`) and the enum-rejection path
+ * (`schemas/fields.ts` `enumStripControlChars`, W-23336443), which reaches the
+ * host UPSTREAM of the envelope's own strip. Shared here so those sinks agree.
+ */
+export const LINE_SEPARATOR_RE = /[\u2028\u2029]/g;
+
+/** Delete every {@link LINE_SEPARATOR_RE} code point from `s`. */
+export function stripLineSeparators(s: string): string {
+	return s.replace(LINE_SEPARATOR_RE, "");
+}

package/src/mcp/tools/__tests__/sf-gql-aggregate.spec.ts

@@ -413,3 +413,112 @@ describe("mcp/tools/sf-gql-aggregate", () => {
 		}
 	});
 });
+
+// W-23336443: the groupBy `function` enum is a PLAIN z.union member, so it is
+// wrapped in enumStripControlChars (a plain enum's invalid_enum_value echoes the
+// received value verbatim through the SDK's upstream validation). The aggregate
+// `function` DISCRIMINATOR is deliberately NOT wrapped — a bad discriminator
+// raises invalid_union_discriminator, which lists only the expected options and
+// does NOT echo the input, so there is no reflection channel to close. Both
+// claims are proven end-to-end through the real client.callTool channel below.
+// Oracle: assert the specific injected code points absent, not a whole-class
+// scan (the SDK pretty-prints issues with \p{Cc} newlines). See
+// sf-gql-discover.spec.ts for the full rationale.
+describe("mcp/tools/sf-gql-aggregate — control-char neutralization (W-23336443)", () => {
+	const BIDI = "\u{202e}";
+	const ZWSP = "\u{200b}";
+	const DEL = "\x7f";
+
+	it("a poisoned-but-valid groupBy function strips to the member and is ACCEPTED", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_aggregate",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					groupBy: [{ field: "Industry", function: `CALENDAR_MONTH${BIDI}` }],
+					aggregations: [{ function: "count" }],
+				},
+			});
+			expect(result.isError).toBeFalsy();
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}") as { query: string };
+			// Stripped to CALENDAR_MONTH, which renders as the date-bucket function.
+			expect(parsed.query).toMatch(/function\s*:\s*CALENDAR_MONTH\b/s);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("a genuinely-invalid poisoned groupBy function rejects with NO raw injected code point", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_aggregate",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					groupBy: [{ field: "Industry", function: `${BIDI}bo${ZWSP}gus${DEL}` }],
+					aggregations: [{ function: "count" }],
+				},
+			});
+			expect(result.isError).toBe(true);
+			const text = (result.content as { text?: string }[])[0]?.text ?? "";
+			expect(text).not.toContain(BIDI);
+			expect(text).not.toContain(ZWSP);
+			expect(text).not.toContain(DEL);
+			expect(text).toContain("bogus");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("the un-wrapped aggregate function DISCRIMINATOR leaks no injected code point either", async () => {
+		const { client, server } = await connect();
+		try {
+			// Negative control: a poisoned discriminator is NOT stripped (the
+			// discriminator is intentionally left un-wrapped), yet the SDK's
+			// invalid_union_discriminator issue lists only the expected options and
+			// never echoes the received value — so nothing leaks regardless.
+			const result = await client.callTool({
+				name: "sf_gql_aggregate",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					aggregations: [{ function: `count${BIDI}${ZWSP}${DEL}`, field: "Amount" }],
+				},
+			});
+			expect(result.isError).toBe(true);
+			const text = (result.content as { text?: string }[])[0]?.text ?? "";
+			expect(text).not.toContain(BIDI);
+			expect(text).not.toContain(ZWSP);
+			expect(text).not.toContain(DEL);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/list still advertises the groupBy function enum after wrapping", async () => {
+		const { client, server } = await connect();
+		try {
+			const list = await client.listTools();
+			const tool = list.tools.find((t) => t.name === "sf_gql_aggregate");
+			// groupBy is an array whose items are a union; the object branch carries
+			// the wrapped `function` enum. Assert the enum survives somewhere in the
+			// advertised groupBy schema (converter shape varies: anyOf/items).
+			const groupBy = (tool!.inputSchema as { properties: Record<string, unknown> }).properties
+				.groupBy;
+			const serialized = JSON.stringify(groupBy);
+			for (const fn of ["CALENDAR_MONTH", "FISCAL_YEAR", "WEEK_IN_YEAR"]) {
+				expect(serialized).toContain(fn);
+			}
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+});

package/src/mcp/tools/__tests__/sf-gql-discover.spec.ts

@@ -318,3 +318,82 @@ describe("mcp/tools/sf-gql-discover", () => {
 		}
 	});
 });
+
+// W-23336443: the `mode` enum is wrapped in enumStripControlChars. A z.enum
+// rejection is reflected VERBATIM by the MCP SDK's input validation, which runs
+// UPSTREAM of runTool — so the tool adapter's neutralizeControlChars never sees
+// it. These tests exercise the REAL SDK channel (client.callTool round-trip),
+// which is the actual vulnerable path, not a bare schema.safeParse.
+//
+// Oracle discipline: the SDK pretty-prints zod issues with JSON.stringify(_, 2),
+// which inserts real newlines (themselves \p{Cc}) into the envelope, so a
+// whole-class /[\p{Cc}\p{Cf}]/ scan false-positives. We assert instead that the
+// SPECIFIC injected code points (U+202E bidi, U+200B ZWSP, U+007F DEL — the trio
+// the SDK's JSON.stringify leaves raw, since it escapes only C0) are absent.
+describe("mcp/tools/sf-gql-discover — control-char neutralization (W-23336443)", () => {
+	// One representative per surviving class. C0 (e.g. \n) is escaped by the SDK's
+	// JSON.stringify already; these three are the ones that survived raw pre-fix.
+	const BIDI = "\u{202e}";
+	const ZWSP = "\u{200b}";
+	const DEL = "\x7f";
+
+	it("a poisoned-but-otherwise-valid mode strips to the member and is ACCEPTED", async () => {
+		const { client, server } = await connect();
+		try {
+			// "describe_object" + trailing bidi override. Pre-fix this rejected and
+			// reflected the raw U+202E; post-fix it strips to the valid member and
+			// proceeds (the Account fixture describe succeeds).
+			const result = await client.callTool({
+				name: "sf_gql_discover",
+				arguments: { org: ORG, mode: `describe_object${BIDI}`, object: "Account" },
+			});
+			expect(result.isError).toBeFalsy();
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}") as { mode: string };
+			expect(parsed.mode).toBe("describe_object");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("a genuinely-invalid poisoned mode rejects with NO raw injected code point", async () => {
+		const { client, server } = await connect();
+		try {
+			// "bogus" wrapped in bidi + zero-width + DEL. Strips to "bogus", which is
+			// not a member, so the SDK rejects — but the reflected value is stripped.
+			const result = await client.callTool({
+				name: "sf_gql_discover",
+				arguments: { org: ORG, mode: `${BIDI}bo${ZWSP}gus${DEL}` },
+			});
+			expect(result.isError).toBe(true);
+			const text = (result.content as { text?: string }[])[0]?.text ?? "";
+			expect(text).not.toContain(BIDI);
+			expect(text).not.toContain(ZWSP);
+			expect(text).not.toContain(DEL);
+			// It still reflects the stripped token so the LLM can self-correct.
+			expect(text).toContain("bogus");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/list still advertises the mode enum + description after wrapping", async () => {
+		const { client, server } = await connect();
+		try {
+			const list = await client.listTools();
+			const tool = list.tools.find((t) => t.name === "sf_gql_discover");
+			const mode = (tool!.inputSchema as { properties: Record<string, unknown> }).properties
+				.mode as { enum?: string[]; description?: string };
+			expect(mode.enum).toEqual(["list_objects", "describe_object", "describe_field"]);
+			expect(mode.description).toMatch(/Discovery mode/);
+			// mode stays REQUIRED through the preprocess wrapper.
+			const required = (tool!.inputSchema as { required?: string[] }).required ?? [];
+			expect(required).toContain("mode");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+});

package/src/mcp/tools/__tests__/sf-gql-raw.spec.ts

@@ -158,3 +158,94 @@ describe("mcp/server registers sf_gql_raw", () => {
 		}
 	});
 });
+
+// W-23336443: the OPTIONAL `operation` enum is wrapped in enumStripControlChars.
+// A z.enum rejection is reflected verbatim by the MCP SDK's input validation,
+// upstream of runTool. These exercise the real client.callTool channel; the
+// oracle asserts the specific injected code points (U+202E/U+200B/U+007F) are
+// absent, not a whole-class scan (the SDK's JSON.stringify(issues, 2) inserts
+// \p{Cc} newlines that would false-positive). See sf-gql-discover.spec.ts.
+describe("mcp/tools/sf-gql-raw — control-char neutralization (W-23336443)", () => {
+	const BIDI = "\u{202e}";
+	const ZWSP = "\u{200b}";
+	const DEL = "\x7f";
+
+	it("a poisoned-but-otherwise-valid operation strips to the member and is ACCEPTED", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_raw",
+				arguments: {
+					org: ORG,
+					commands: ["select uiapi/query/Case/edges/node/Subject/value"],
+					operation: `query${BIDI}`,
+				},
+			});
+			// "query" is the default root anyway, so a strip-to-"query" renders the
+			// same query a clean call would — the value passed validation cleanly.
+			expect(result.isError).toBeFalsy();
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}") as { query: string };
+			expect(parsed.query).toMatch(/Subject\s+@optional\s*\{\s*value\s*\}/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("a genuinely-invalid poisoned operation rejects with NO raw injected code point", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_raw",
+				arguments: {
+					org: ORG,
+					commands: ["select uiapi/query/Case/edges/node/Id"],
+					operation: `${BIDI}bo${ZWSP}gus${DEL}`,
+				},
+			});
+			expect(result.isError).toBe(true);
+			const text = (result.content as { text?: string }[])[0]?.text ?? "";
+			expect(text).not.toContain(BIDI);
+			expect(text).not.toContain(ZWSP);
+			expect(text).not.toContain(DEL);
+			expect(text).toContain("bogus");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("omitting operation still validates (the wrapper preserves .optional())", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_raw",
+				arguments: { org: ORG, commands: ["select uiapi/query/Case/edges/node/Id"] },
+			});
+			expect(result.isError).toBeFalsy();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/list advertises the operation enum and keeps it OPTIONAL", async () => {
+		const { client, server } = await connect();
+		try {
+			const list = await client.listTools();
+			const tool = list.tools.find((t) => t.name === "sf_gql_raw");
+			const schema = tool!.inputSchema as {
+				properties: Record<string, unknown>;
+				required?: string[];
+			};
+			const op = schema.properties.operation as { enum?: string[]; description?: string };
+			expect(op.enum).toEqual(["query", "mutation", "aggregate"]);
+			expect(op.description).toMatch(/Operation root/);
+			expect(schema.required ?? []).not.toContain("operation");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+});