@salesforce/graphiti 11.13.2 → 11.14.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.14.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.13.2...v11.14.0) (2026-07-09)
+
+### Features
+
+- **graphiti:** promote whole filter/orderBy argument to one optional $var ([#645](https://github.com/salesforce-experience-platform-emu/webapps/issues/645)) ([290c5be](https://github.com/salesforce-experience-platform-emu/webapps/commit/290c5be3e4249581e0f9050d42bb8c8ed9850d25))
+
 ## [11.13.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.13.1...v11.13.2) (2026-07-09)
 
 **Note:** Version bump only for package @salesforce/graphiti

package/dist/intent/build-list.js

@@ -9,7 +9,7 @@ import { selectChildRelationship } from "./select-child-relationship.js";
 import { assertGraphqlName } from "../lib/graphql-name.js";
 import { selectDottedFieldPath } from "../lib/path-selection.js";
 import { addVariable, createSession, deepSetArg, selectLeaf } from "../lib/session.js";
-import { normalizeOrderBy, promoteVariables } from "../lib/variable-promotion.js";
+import { normalizeOrderBy, promoteArg, promoteVariables } from "../lib/variable-promotion.js";
 /**
  * Build a UIAPI list query against a Salesforce org. Implements `sf_gql_list`
  * intent for the graphiti MCP server.
@@ -58,17 +58,18 @@ export async function buildList(spec, deps) {
         }
     }
     const first = spec.first ?? 10;
-    deepSetArg(session, connectionPath, "first", [], String(first));
+    const firstRendered = promoteArg(session, schema, connectionPath, "first", first).rendered;
+    deepSetArg(session, connectionPath, "first", [], firstRendered);
     selectLeaf(session, [...connectionPath, "pageInfo", "hasNextPage"]);
     selectLeaf(session, [...connectionPath, "pageInfo", "endCursor"]);
     if (spec.filter) {
-        promoteVariables(session, schema, connectionPath, "where", spec.filter, extraWarnings);
-        deepSetArg(session, connectionPath, "where", [], JSON.stringify(spec.filter));
+        const { rendered } = promoteArg(session, schema, connectionPath, "where", spec.filter, extraWarnings);
+        deepSetArg(session, connectionPath, "where", [], rendered);
     }
     const orderBy = normalizeOrderBy(spec.orderBy);
     if (orderBy) {
-        promoteVariables(session, schema, connectionPath, "orderBy", orderBy, extraWarnings);
-        deepSetArg(session, connectionPath, "orderBy", [], JSON.stringify(orderBy));
+        const { rendered } = promoteArg(session, schema, connectionPath, "orderBy", orderBy, extraWarnings);
+        deepSetArg(session, connectionPath, "orderBy", [], rendered);
     }
     if (spec.scope) {
         promoteVariables(session, schema, connectionPath, "scope", spec.scope, extraWarnings);

package/dist/intent/build-list.js.map

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

package/dist/intent/select-child-relationship.js

@@ -5,7 +5,7 @@
  */
 import { selectDottedFieldPath } from "../lib/path-selection.js";
 import { deepSetArg } from "../lib/session.js";
-import { normalizeOrderBy, promoteVariables } from "../lib/variable-promotion.js";
+import { normalizeOrderBy, promoteArg } from "../lib/variable-promotion.js";
 /**
  * Render a UIAPI child relationship onto an existing query session as
  * `<rel> { edges { node { ... } } }`, with optional `first` / `filter` /
@@ -23,16 +23,17 @@ export function selectChildRelationship(session, schema, parentNodePath, child,
         selectDottedFieldPath(session, schema, childNodePath, field);
     }
     if (child.first !== undefined) {
-        deepSetArg(session, childConnectionPath, "first", [], String(child.first));
+        const firstRendered = promoteArg(session, schema, childConnectionPath, "first", child.first).rendered;
+        deepSetArg(session, childConnectionPath, "first", [], firstRendered);
     }
     if (child.filter) {
-        promoteVariables(session, schema, childConnectionPath, "where", child.filter, warnings);
-        deepSetArg(session, childConnectionPath, "where", [], JSON.stringify(child.filter));
+        const { rendered } = promoteArg(session, schema, childConnectionPath, "where", child.filter, warnings);
+        deepSetArg(session, childConnectionPath, "where", [], rendered);
     }
     const childOrderBy = normalizeOrderBy(child.orderBy);
     if (childOrderBy) {
-        promoteVariables(session, schema, childConnectionPath, "orderBy", childOrderBy, warnings);
-        deepSetArg(session, childConnectionPath, "orderBy", [], JSON.stringify(childOrderBy));
+        const { rendered } = promoteArg(session, schema, childConnectionPath, "orderBy", childOrderBy, warnings);
+        deepSetArg(session, childConnectionPath, "orderBy", [], rendered);
     }
 }
 //# sourceMappingURL=select-child-relationship.js.map

package/dist/intent/select-child-relationship.js.map

@@ -1 +1 @@
-{"version":3,"file":"select-child-relationship.js","sourceRoot":"","sources":["../../src/intent/select-child-relationship.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,UAAU,EAAqB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAElF;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACtC,OAAqB,EACrB,MAAqB,EACrB,cAAwB,EACxB,KAA4B,EAC5B,QAAmB;IAEnB,MAAM,mBAAmB,GAAG,CAAC,GAAG,cAAc,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACxE,MAAM,aAAa,GAAG,CAAC,GAAG,mBAAmB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAEhE,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,UAAU,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACxF,UAAU,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,YAAY,EAAE,CAAC;QAClB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC1F,UAAU,CAAC,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IACvF,CAAC;AACF,CAAC"}
+{"version":3,"file":"select-child-relationship.js","sourceRoot":"","sources":["../../src/intent/select-child-relationship.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,UAAU,EAAqB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACtC,OAAqB,EACrB,MAAqB,EACrB,cAAwB,EACxB,KAA4B,EAC5B,QAAmB;IAEnB,MAAM,mBAAmB,GAAG,CAAC,GAAG,cAAc,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACxE,MAAM,aAAa,GAAG,CAAC,GAAG,mBAAmB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAEhE,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,aAAa,GAAG,UAAU,CAC/B,OAAO,EACP,MAAM,EACN,mBAAmB,EACnB,OAAO,EACP,KAAK,CAAC,KAAK,CACX,CAAC,QAAQ,CAAC;QACX,UAAU,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CAC9B,OAAO,EACP,MAAM,EACN,mBAAmB,EACnB,OAAO,EACP,KAAK,CAAC,MAAM,EACZ,QAAQ,CACR,CAAC;QACF,UAAU,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,YAAY,EAAE,CAAC;QAClB,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CAC9B,OAAO,EACP,MAAM,EACN,mBAAmB,EACnB,SAAS,EACT,YAAY,EACZ,QAAQ,CACR,CAAC;QACF,UAAU,CAAC,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;IACnE,CAAC;AACF,CAAC"}

package/dist/intent/types.d.ts

@@ -23,9 +23,9 @@ export interface VariableInfo {
 export interface ChildRelationshipSpec {
     relationshipName: string;
     fields: string[];
-    first?: number;
-    filter?: Record<string, unknown>;
-    orderBy?: Record<string, unknown> | Record<string, unknown>[];
+    first?: number | string;
+    filter?: Record<string, unknown> | string;
+    orderBy?: Record<string, unknown> | Record<string, unknown>[] | string;
 }
 export interface ListSpec {
     org: string;
@@ -33,9 +33,9 @@ export interface ListSpec {
     fields: string[];
     parentFields?: string[];
     childRelationships?: ChildRelationshipSpec[];
-    filter?: Record<string, unknown>;
-    orderBy?: Record<string, unknown> | Record<string, unknown>[];
-    first?: number;
+    filter?: Record<string, unknown> | string;
+    orderBy?: Record<string, unknown> | Record<string, unknown>[] | string;
+    first?: number | string;
     scope?: string;
     operationName?: string;
 }

package/dist/lib/variable-promotion.d.ts

@@ -56,6 +56,32 @@ import { type QuerySession } from "./session.js";
  *                        silently rendering the literal.
  */
 export declare function promoteVariables(session: QuerySession, schema: GraphQLSchema, fieldSchemaPath: string[], argName: string, value: unknown, warnings?: string[]): void;
+/**
+ * Result of promoting one whole argument. `rendered` is what the caller
+ * hands to `deepSetArg`: the raw `$var` reference when the entire argument
+ * was a single `$varName` string, or the JSON-stringified value otherwise.
+ */
+export interface ArgPromotion {
+    rendered: string;
+}
+/**
+ * Promote a `where` / `orderBy` argument that may be EITHER a normal
+ * object (whose `$varName` leaves promote via `promoteVariables`) OR a
+ * single top-level `$varName` string standing in for the whole argument.
+ *
+ * The whole-argument form is the idiomatic UIAPI pattern for an
+ * optionally-applied filter: a `null`-bound `where` means "no constraint →
+ * all rows", which a nullable leaf cannot express. When `value` is a
+ * whole-arg placeholder we infer the argument's own input type
+ * (e.g. `Case_Filter`, `Case_OrderBy`), declare one nullable variable, and
+ * return its `$ref` so the caller renders `where: $filter` directly.
+ *
+ * Type inference for a real `where`/`orderBy` argument effectively never
+ * fails, but if it does we still emit the variable as `String` and push a
+ * loud warning — a best-effort query the user can debug beats a hard error
+ * before they see anything.
+ */
+export declare function promoteArg(session: QuerySession, schema: GraphQLSchema, fieldSchemaPath: string[], argName: string, value: unknown, warnings?: string[]): ArgPromotion;
 /**
  * Collapses an array-shaped orderBy input to its first element, so
  * callers can pass either shape without knowing Salesforce's

package/dist/lib/variable-promotion.js

@@ -78,6 +78,49 @@ function walk(session, schema, fieldSchemaPath, argName, value, pathInsideArg, w
         }
     }
 }
+/**
+ * Promote a `where` / `orderBy` argument that may be EITHER a normal
+ * object (whose `$varName` leaves promote via `promoteVariables`) OR a
+ * single top-level `$varName` string standing in for the whole argument.
+ *
+ * The whole-argument form is the idiomatic UIAPI pattern for an
+ * optionally-applied filter: a `null`-bound `where` means "no constraint →
+ * all rows", which a nullable leaf cannot express. When `value` is a
+ * whole-arg placeholder we infer the argument's own input type
+ * (e.g. `Case_Filter`, `Case_OrderBy`), declare one nullable variable, and
+ * return its `$ref` so the caller renders `where: $filter` directly.
+ *
+ * Type inference for a real `where`/`orderBy` argument effectively never
+ * fails, but if it does we still emit the variable as `String` and push a
+ * loud warning — a best-effort query the user can debug beats a hard error
+ * before they see anything.
+ */
+export function promoteArg(session, schema, fieldSchemaPath, argName, value, warnings) {
+    if (typeof value === "string") {
+        const m = VAR_PLACEHOLDER_RE.exec(value);
+        if (m && m[1]) {
+            const varName = m[1];
+            try {
+                const { inferredType } = inferTypeFromArgsPath(schema, session.operation, fieldSchemaPath, [
+                    argName,
+                ]);
+                const declared = inferredType.endsWith("!") ? inferredType.slice(0, -1) : inferredType;
+                addVariable(session, varName, declared);
+            }
+            catch (err) {
+                addVariable(session, varName, "String");
+                const hint = err instanceof Error ? ` (${err.message})` : "";
+                warnings?.push(`Variable: could not infer the GraphQL type for whole-argument '${value}' on '${argName}'${hint}; declared as 'String'. The rendered query may be invalid — verify the variable type.`);
+            }
+            return { rendered: value };
+        }
+        // A `$`-prefixed string that is not a valid placeholder, or any other
+        // bare string: fall through to leaf handling, which emits the existing
+        // invalid-placeholder warning and renders the literal.
+    }
+    promoteVariables(session, schema, fieldSchemaPath, argName, value, warnings);
+    return { rendered: JSON.stringify(value) };
+}
 /**
  * Collapses an array-shaped orderBy input to its first element, so
  * callers can pass either shape without knowing Salesforce's

package/dist/lib/variable-promotion.js.map

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

package/dist/schemas/fields.d.ts

@@ -4,6 +4,28 @@
  * For full license text, see the LICENSE.txt file
  */
 import { z } from "zod";
+/**
+ * Some MCP clients/models JSON-stringify complex tool arguments (e.g. send
+ * `"25"` for a number or `'{"x":1}'` for an object). This coerces such a
+ * string back to its parsed value so the real value validates — lossless,
+ * and scoped to strings that LOOK like JSON (object/array/number) so `$var`
+ * placeholders and enum strings (e.g. scope "MINE") are left untouched.
+ * Same "tolerate predictable client encoding quirks" philosophy as the
+ * detailOrderBy array-collapse shim.
+ */
+export declare const coerceJsonArg: (v: unknown) => unknown;
+/** Wrap a schema so a JSON-stringified value is coerced before validation. */
+export declare const jsonCoercible: (schema: z.ZodTypeAny) => z.ZodEffects<z.ZodTypeAny, any, unknown>;
+/** A string that looks like a JSON object/array literal — used so the advertised
+ *  schema accepts a stringified object/array; coerceJsonArg then parses it. A
+ *  `{`/`[`-prefixed but invalid-JSON string is accepted as a literal (rare; the
+ *  model reliably sends valid JSON) rather than erroring. */
+export declare const jsonLiteralString: () => z.ZodString;
+/** A string of digits — a stringified positive integer for `first`. */
+export declare const intLiteralString: () => z.ZodString;
+/** A JSON-quoted string literal, e.g. "\"$first\"" or "\"25\"" — some models
+ *  double-encode args. coerceJsonArg unwraps it before validation. */
+export declare const quotedString: () => z.ZodString;
 /**
  * Zod string validator that enforces the GraphQL Name production. Returned
  * schema is `.describe()`-tagged with the supplied description so it appears
@@ -12,11 +34,18 @@ import { z } from "zod";
 export declare const graphqlName: (description: string) => z.ZodString;
 export declare const orgAlias: (description: string) => z.ZodString;
 /**
- * `<Object>_OrderBy` shape. UIAPI accepts a singleton object; tools may
- * additionally accept arrays as a compat shim depending on their advertised
- * schema policy (see `sf-gql-list.ts` vs `sf-gql-detail.ts`).
+ * `<Object>_OrderBy` shape. A FACTORY (not a shared instance): each call returns
+ * a fresh schema so the MCP SDK's zod-to-json-schema converter INLINES it at every
+ * use site instead of collapsing reuse into cross-`$ref`s (which intermittently
+ * dropped union branches in the advertised schema).
  */
-export declare const orderByObject: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const orderByObject: () => z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/**
+ * A bare top-level `$varName` string standing in for an entire `filter` /
+ * `orderBy` / `first` argument. A FACTORY (not a shared instance) so the advertised
+ * JSON Schema inlines it at every use site rather than emitting cross-`$ref`s.
+ */
+export declare const varPlaceholder: () => z.ZodString;
 /**
  * Build a `childRelationships[]` element schema. The `orderBy` schema is a
  * parameter because tools differ on whether they advertise the array shape
@@ -31,19 +60,19 @@ export declare const orderByObject: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 export declare const childRelationshipSchema: (orderBy: z.ZodTypeAny) => z.ZodObject<{
     relationshipName: z.ZodString;
     fields: z.ZodArray<z.ZodString, "many">;
-    first: z.ZodOptional<z.ZodNumber>;
-    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    orderBy: z.ZodOptional<z.ZodTypeAny>;
+    first: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+    filter: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+    orderBy: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
 }, "strip", z.ZodTypeAny, {
     relationshipName: string;
     fields: string[];
-    filter?: Record<string, unknown> | undefined;
+    filter?: any;
     orderBy?: any;
-    first?: number | undefined;
+    first?: any;
 }, {
     relationshipName: string;
     fields: string[];
-    filter?: Record<string, unknown> | undefined;
-    orderBy?: any;
-    first?: number | undefined;
+    filter?: unknown;
+    orderBy?: unknown;
+    first?: unknown;
 }>;

package/dist/schemas/fields.js

@@ -5,6 +5,49 @@
  */
 import { z } from "zod";
 import { GRAPHQL_NAME_RE } from "../lib/graphql-name.js";
+/**
+ * Some MCP clients/models JSON-stringify complex tool arguments (e.g. send
+ * `"25"` for a number or `'{"x":1}'` for an object). This coerces such a
+ * string back to its parsed value so the real value validates — lossless,
+ * and scoped to strings that LOOK like JSON (object/array/number) so `$var`
+ * placeholders and enum strings (e.g. scope "MINE") are left untouched.
+ * Same "tolerate predictable client encoding quirks" philosophy as the
+ * detailOrderBy array-collapse shim.
+ */
+export const coerceJsonArg = (v) => {
+    const once = coerceJsonOnce(v);
+    // Unwrapping a double-quoted string (e.g. '"25"' → "25", '"$first"' → "$first")
+    // can yield another coercible string; coerce one more level so '"25"' → 25.
+    if (typeof once === "string" && once !== v)
+        return coerceJsonOnce(once);
+    return once;
+};
+const coerceJsonOnce = (v) => {
+    if (typeof v !== "string")
+        return v;
+    const t = v.trim();
+    // object/array, bare number, OR a JSON-quoted string literal
+    if (!(t.startsWith("{") || t.startsWith("[") || /^-?\d+(\.\d+)?$/.test(t) || t.startsWith('"')))
+        return v;
+    try {
+        return JSON.parse(t);
+    }
+    catch {
+        return v;
+    }
+};
+/** Wrap a schema so a JSON-stringified value is coerced before validation. */
+export const jsonCoercible = (schema) => z.preprocess(coerceJsonArg, schema);
+/** A string that looks like a JSON object/array literal — used so the advertised
+ *  schema accepts a stringified object/array; coerceJsonArg then parses it. A
+ *  `{`/`[`-prefixed but invalid-JSON string is accepted as a literal (rare; the
+ *  model reliably sends valid JSON) rather than erroring. */
+export const jsonLiteralString = () => z.string().regex(/^\s*[{[]/);
+/** A string of digits — a stringified positive integer for `first`. */
+export const intLiteralString = () => z.string().regex(/^\d+$/);
+/** A JSON-quoted string literal, e.g. "\"$first\"" or "\"25\"" — some models
+ *  double-encode args. coerceJsonArg unwraps it before validation. */
+export const quotedString = () => z.string().regex(/^".*"$/s);
 /**
  * Zod string validator that enforces the GraphQL Name production. Returned
  * schema is `.describe()`-tagged with the supplied description so it appears
@@ -20,11 +63,18 @@ export const graphqlName = (description) => z.string().regex(GRAPHQL_NAME_RE, "m
 const ORG_ALIAS_RE = /^[A-Za-z0-9_][A-Za-z0-9_.+@-]{0,252}$/;
 export const orgAlias = (description) => z.string().regex(ORG_ALIAS_RE, "must be a valid org alias or username").describe(description);
 /**
- * `<Object>_OrderBy` shape. UIAPI accepts a singleton object; tools may
- * additionally accept arrays as a compat shim depending on their advertised
- * schema policy (see `sf-gql-list.ts` vs `sf-gql-detail.ts`).
+ * `<Object>_OrderBy` shape. A FACTORY (not a shared instance): each call returns
+ * a fresh schema so the MCP SDK's zod-to-json-schema converter INLINES it at every
+ * use site instead of collapsing reuse into cross-`$ref`s (which intermittently
+ * dropped union branches in the advertised schema).
+ */
+export const orderByObject = () => z.record(z.unknown());
+/**
+ * A bare top-level `$varName` string standing in for an entire `filter` /
+ * `orderBy` / `first` argument. A FACTORY (not a shared instance) so the advertised
+ * JSON Schema inlines it at every use site rather than emitting cross-`$ref`s.
  */
-export const orderByObject = z.record(z.unknown());
+export const varPlaceholder = () => z.string().regex(/^\$[A-Za-z_]\w*$/, "must be a $variable placeholder, e.g. $filter");
 /**
  * Build a `childRelationships[]` element schema. The `orderBy` schema is a
  * parameter because tools differ on whether they advertise the array shape
@@ -39,8 +89,8 @@ export const orderByObject = z.record(z.unknown());
 export const childRelationshipSchema = (orderBy) => z.object({
     relationshipName: graphqlName('Child relationship API name, e.g. "Contacts", "Opportunities". Must be a valid GraphQL Name.'),
     fields: z.array(z.string()),
-    first: z.number().int().positive().optional(),
-    filter: z.record(z.unknown()).optional(),
-    orderBy: orderBy.optional(),
+    first: jsonCoercible(z.union([z.number().int().positive(), varPlaceholder(), intLiteralString(), quotedString()])).optional(),
+    filter: jsonCoercible(z.union([z.record(z.unknown()), varPlaceholder(), jsonLiteralString(), quotedString()])).optional(),
+    orderBy: jsonCoercible(z.union([orderBy, varPlaceholder(), jsonLiteralString(), quotedString()])).optional(),
 });
 //# sourceMappingURL=fields.js.map

package/dist/schemas/fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../src/schemas/fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,WAAmB,EAAe,EAAE,CAC/D,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,eAAe,EAAE,8BAA8B,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAEzF;;;;;GAKG;AACH,MAAM,YAAY,GAAG,uCAAuC,CAAC;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,WAAmB,EAAe,EAAE,CAC5D,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,uCAAuC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAE/F;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,OAAqB,EAAE,EAAE,CAChE,CAAC,CAAC,MAAM,CAAC;IACR,gBAAgB,EAAE,WAAW,CAC5B,8FAA8F,CAC9F;IACD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE;CAC3B,CAAC,CAAC"}
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../src/schemas/fields.ts"],"names":[],"mappings":"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"}

package/dist/schemas/input-schemas.d.ts

@@ -23,60 +23,60 @@ export declare const LIST_INPUT: z.ZodObject<{
     childRelationships: z.ZodOptional<z.ZodArray<z.ZodObject<{
         relationshipName: z.ZodString;
         fields: z.ZodArray<z.ZodString, "many">;
-        first: z.ZodOptional<z.ZodNumber>;
-        filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        orderBy: z.ZodOptional<z.ZodTypeAny>;
+        first: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+        filter: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+        orderBy: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
     }, "strip", z.ZodTypeAny, {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
+        filter?: any;
         orderBy?: any;
-        first?: number | undefined;
+        first?: any;
     }, {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
-        orderBy?: any;
-        first?: number | undefined;
+        filter?: unknown;
+        orderBy?: unknown;
+        first?: unknown;
     }>, "many">>;
-    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    orderBy: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">]>>;
-    first: z.ZodOptional<z.ZodNumber>;
+    filter: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+    orderBy: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+    first: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
     scope: z.ZodOptional<z.ZodString>;
     operationName: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     object: string;
     org: string;
     fields: string[];
-    filter?: Record<string, unknown> | undefined;
+    filter?: any;
     operationName?: string | undefined;
-    orderBy?: Record<string, unknown> | Record<string, unknown>[] | undefined;
-    first?: number | undefined;
+    orderBy?: any;
+    first?: any;
     scope?: string | undefined;
     parentFields?: string[] | undefined;
     childRelationships?: {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
+        filter?: any;
         orderBy?: any;
-        first?: number | undefined;
+        first?: any;
     }[] | undefined;
 }, {
     object: string;
     org: string;
     fields: string[];
-    filter?: Record<string, unknown> | undefined;
+    filter?: unknown;
     operationName?: string | undefined;
-    orderBy?: Record<string, unknown> | Record<string, unknown>[] | undefined;
-    first?: number | undefined;
+    orderBy?: unknown;
+    first?: unknown;
     scope?: string | undefined;
     parentFields?: string[] | undefined;
     childRelationships?: {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
-        orderBy?: any;
-        first?: number | undefined;
+        filter?: unknown;
+        orderBy?: unknown;
+        first?: unknown;
     }[] | undefined;
 }>;
 export declare const DETAIL_INPUT: z.ZodObject<{
@@ -87,21 +87,21 @@ export declare const DETAIL_INPUT: z.ZodObject<{
     childRelationships: z.ZodOptional<z.ZodArray<z.ZodObject<{
         relationshipName: z.ZodString;
         fields: z.ZodArray<z.ZodString, "many">;
-        first: z.ZodOptional<z.ZodNumber>;
-        filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        orderBy: z.ZodOptional<z.ZodTypeAny>;
+        first: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+        filter: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+        orderBy: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
     }, "strip", z.ZodTypeAny, {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
+        filter?: any;
         orderBy?: any;
-        first?: number | undefined;
+        first?: any;
     }, {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
-        orderBy?: any;
-        first?: number | undefined;
+        filter?: unknown;
+        orderBy?: unknown;
+        first?: unknown;
     }>, "many">>;
     idVariable: z.ZodOptional<z.ZodString>;
     operationName: z.ZodOptional<z.ZodString>;
@@ -114,9 +114,9 @@ export declare const DETAIL_INPUT: z.ZodObject<{
     childRelationships?: {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
+        filter?: any;
         orderBy?: any;
-        first?: number | undefined;
+        first?: any;
     }[] | undefined;
     idVariable?: string | undefined;
 }, {
@@ -128,9 +128,9 @@ export declare const DETAIL_INPUT: z.ZodObject<{
     childRelationships?: {
         relationshipName: string;
         fields: string[];
-        filter?: Record<string, unknown> | undefined;
-        orderBy?: any;
-        first?: number | undefined;
+        filter?: unknown;
+        orderBy?: unknown;
+        first?: unknown;
     }[] | undefined;
     idVariable?: string | undefined;
 }>;

package/dist/schemas/input-schemas.js

@@ -15,12 +15,19 @@
  * schemas; behavior is unchanged — this is a pure extraction.
  */
 import { z } from "zod";
-import { childRelationshipSchema, graphqlName, orderByObject, orgAlias } from "./fields.js";
+import { childRelationshipSchema, graphqlName, intLiteralString, jsonCoercible, jsonLiteralString, orderByObject, orgAlias, quotedString, varPlaceholder, } from "./fields.js";
 import { GROUP_BY_FUNCTIONS } from "../intent/types.js";
 // --- sf_gql_list ------------------------------------------------------------
 // `sf_gql_list` advertises both shapes (singleton + array) for backward
 // compatibility with early MCP clients that learned the array form.
-const listOrderBySchema = z.union([orderByObject, z.array(orderByObject)]);
+// Factory function to avoid cross-$ref deduplication.
+const listOrderBySchema = () => z.union([
+    orderByObject(),
+    z.array(orderByObject()),
+    varPlaceholder(),
+    jsonLiteralString(),
+    quotedString(),
+]);
 export const LIST_INPUT = z.object({
     org: z.string().describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
     object: graphqlName('SObject API name, e.g. "Account", "Case". Must be a valid GraphQL Name.'),
@@ -31,20 +38,16 @@ export const LIST_INPUT = z.object({
         .array(z.string())
         .optional()
         .describe('Dotted parent-relationship paths, e.g. "Account.Name".'),
-    childRelationships: z.array(childRelationshipSchema(listOrderBySchema)).optional(),
-    filter: z
-        .record(z.unknown())
+    childRelationships: z.array(childRelationshipSchema(listOrderBySchema())).optional(),
+    filter: jsonCoercible(z.union([z.record(z.unknown()), varPlaceholder(), jsonLiteralString(), quotedString()]))
         .optional()
-        .describe("<Object>_Filter shape. String leaves matching $varName promote to typed query variables."),
-    orderBy: listOrderBySchema
+        .describe('<Object>_Filter shape — pass as a JSON OBJECT (e.g. {"Status":{"eq":"New"}}), not a JSON-stringified string. String leaves matching $varName promote to typed query variables. Pass a single "$varName" string to promote the WHOLE filter to one optional <Object>_Filter variable (bind it to null for "no filter → all rows").'),
+    orderBy: jsonCoercible(listOrderBySchema())
         .optional()
-        .describe("<Object>_OrderBy. Singleton object preferred; arrays are collapsed to the first entry."),
-    first: z
-        .number()
-        .int()
-        .positive()
+        .describe('<Object>_OrderBy — pass as a JSON OBJECT (e.g. {"CreatedDate":{"order":"DESC"}}), not a JSON-stringified string. Singleton object preferred; arrays are collapsed to the first entry. Pass a single "$varName" string to promote the whole orderBy to one optional <Object>_OrderBy variable.'),
+    first: jsonCoercible(z.union([z.number().int().positive(), varPlaceholder(), intLiteralString(), quotedString()]))
         .optional()
-        .describe("Top-level connection page size; defaults to 10."),
+        .describe('Top-level connection page size as a NUMBER (e.g. 25, not "25"); defaults to 10. Pass a single "$varName" string to promote it to an optional Int variable.'),
     scope: z.string().optional().describe('Scope enum (e.g. "MINE", "EVERYTHING") or $varName.'),
     operationName: graphqlName("Override the GraphQL operation name. Defaults to <Object>List.").optional(),
 });
@@ -53,7 +56,8 @@ export const LIST_INPUT = z.object({
 // arrays at runtime via `z.preprocess` (FR-6.2 compat shim for early MCP
 // clients that learned the array shape). The transform collapses to the first
 // element before validation, so downstream code sees a singleton.
-const detailOrderBySchema = z.preprocess((v) => (Array.isArray(v) ? v[0] : v), orderByObject);
+// Factory function to avoid cross-$ref deduplication.
+const detailOrderBySchema = () => z.preprocess((v) => (Array.isArray(v) ? v[0] : v), orderByObject());
 // Note: filter/orderBy/scope/first are intentionally absent at the top level —
 // `sf_gql_detail` is single-record-by-Id (FR-5.5). Filtering happens via the
 // declared `$<idVariable>: ID!`; pagination doesn't apply.
@@ -72,7 +76,7 @@ export const DETAIL_INPUT = z
         .array(z.string())
         .optional()
         .describe('Dotted parent-relationship paths, e.g. "Account.Name".'),
-    childRelationships: z.array(childRelationshipSchema(detailOrderBySchema)).optional(),
+    childRelationships: z.array(childRelationshipSchema(detailOrderBySchema())).optional(),
     idVariable: graphqlName('Name (without leading "$") for the ID variable. Defaults to "id". Declared as <name>: ID! and bound via where { Id: { eq: $<name> } } per FR-5.5. Choose a name that does not appear as a $varName in any childRelationships filter/orderBy — collisions are rejected.').optional(),
     operationName: graphqlName("Override the GraphQL operation name. Defaults to <Object>Detail.").optional(),
 })