@salesforce/graphiti 10.10.2

package/src/intent/build-delete.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildOutput } from "./build-output.js";
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import { type DeleteSpec, type ToolOutput } from "./types.js";
+import { assertGraphqlName } from "../lib/graphql-name.js";
+import { selectDottedFieldPath } from "../lib/path-selection.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+import { addVariable, createSession, deepSetArg } from "../lib/session.js";
+import { mutationFieldPath } from "../lib/uiapi.js";
+
+/**
+ * Build a UIAPI delete mutation against a Salesforce org. Implements
+ * `sf_gql_delete` intent for the graphiti MCP server (FR-5.7).
+ *
+ * Unlike create/update, delete is uniform across SObjects:
+ * - The input type is the schema-wide `RecordDeleteInput!`, NOT an
+ *   `<Object>`-specific input. Every `<Object>Delete` mutation field
+ *   accepts the same `RecordDeleteInput!` carrying the record `Id`.
+ * - The result is a `RecordDeletePayload` exposing only `Id` (a plain
+ *   `ID`, not a value wrapper), so the selection is always `Id` and
+ *   there is no `Record` sub-path — hence no `returnFields`.
+ *
+ * Implicit behaviors not visible in the signature:
+ * - `inputVariable` defaults to `"input"`, declared as
+ *   `$<name>: RecordDeleteInput!`. A leading `$` is stripped.
+ * - Operation name defaults to `Delete<Object>` (e.g. `DeleteAccount`).
+ *
+ * Throws on invalid `object`, `inputVariable`, or `operationName` (must be
+ * valid GraphQL Names), auth-missing, or introspection failure (via
+ * `getSchemaWithPriming`); never throws on validation or codegen
+ * failure (those surface as `warnings[]`).
+ */
+export async function buildDelete(spec: DeleteSpec, deps?: PrimeDeps): Promise<ToolOutput> {
+	assertGraphqlName(spec.object, "buildDelete", "object");
+
+	const inputVar = (spec.inputVariable ?? "input").replace(/^\$/, "");
+	assertGraphqlName(inputVar, "buildDelete", "inputVariable");
+
+	const { schema, primingNote, instanceUrl } = await getSchemaWithPriming(spec.org, deps);
+
+	const session = createSession(spec.org, "mutation", instanceUrl);
+	session.operationName = spec.operationName ?? "Delete" + spec.object;
+	assertGraphqlName(session.operationName, "buildDelete", "operationName");
+
+	const fieldPath = mutationFieldPath(spec.object, "Delete");
+	addVariable(session, inputVar, "RecordDeleteInput!");
+	deepSetArg(session, fieldPath, "input", [], "$" + inputVar);
+
+	// Delete payloads expose only `Id` (a plain ID — never a value wrapper).
+	// The selection is a literal single segment on the mutation field, so
+	// `selectDottedFieldPath` cannot realistically throw here: there is no
+	// user-supplied dotted path (unlike `buildMutation`'s `returnFields`) and
+	// no top-level mutation-arg context that raises `MutationContextError`.
+	selectDottedFieldPath(session, schema, fieldPath, "Id");
+
+	return buildOutput(session, schema, primingNote, []);
+}

package/src/intent/build-detail.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildOutput } from "./build-output.js";
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import { selectChildRelationship } from "./select-child-relationship.js";
+import { type DetailSpec, type ToolOutput } from "./types.js";
+import { assertGraphqlName } from "../lib/graphql-name.js";
+import { selectDottedFieldPath } from "../lib/path-selection.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+import { addVariable, createSession, deepSetArg } from "../lib/session.js";
+import { connectionNodePath, connectionPath } from "../lib/uiapi.js";
+
+/**
+ * Build a UIAPI single-record detail query against a Salesforce org. Implements
+ * `sf_gql_detail` intent for the graphiti MCP server (FR-5.5).
+ *
+ * Implicit behaviors not visible in the signature:
+ * - Always declares `<idVariable>: ID!` (default name `id`) and binds it via
+ *   `where: { Id: { eq: $<idVariable> } }`, with `first: 1` set on the
+ *   connection. Single-record by Id is the whole point of this tool.
+ * - Unlike `sf_gql_list`: no `$after` cursor, no `pageInfo` selection, and no
+ *   top-level `filter` / `orderBy` / `scope`.
+ * - Scalar fields auto-wrap with `{ value }` per UIAPI; `Id` is selected bare.
+ * - Dotted paths in `fields` / `parentFields` expand polymorphic unions into
+ *   per-member inline fragments; members lacking the field are silently skipped.
+ * - `childRelationships` render as `<rel> { edges { node { ... } } }`
+ *   connections with their own `first` / `filter` / `orderBy` (and `$varName`
+ *   leaves promote the same way they do on `sf_gql_list`).
+ * - Operation name defaults to `<Object>Detail`.
+ *
+ * Throws on invalid `object` or `operationName` (must be valid GraphQL Names),
+ * auth-missing or introspection failure (via `getSchemaWithPriming`), on FR-5.5
+ * spec violations (empty `idVariable`, collision with a child-filter `$varName`
+ * of a different type); never throws on validation or codegen failure (those
+ * surface as `warnings[]`).
+ */
+export async function buildDetail(spec: DetailSpec, deps?: PrimeDeps): Promise<ToolOutput> {
+	if (spec.idVariable !== undefined && spec.idVariable.length === 0) {
+		throw new Error("buildDetail: idVariable must be a non-empty string (FR-5.5)");
+	}
+	assertGraphqlName(spec.object, "buildDetail", "object");
+
+	const { schema, primingNote, instanceUrl } = await getSchemaWithPriming(spec.org, deps);
+
+	const session = createSession(spec.org, "query", instanceUrl);
+	session.operationName = spec.operationName ?? `${spec.object}Detail`;
+	assertGraphqlName(session.operationName, "buildDetail", "operationName");
+
+	const connection = connectionPath(spec.object);
+	const node = connectionNodePath(connection);
+
+	for (const field of spec.fields) {
+		selectDottedFieldPath(session, schema, node, field);
+	}
+
+	if (spec.parentFields) {
+		for (const pf of spec.parentFields) {
+			selectDottedFieldPath(session, schema, node, pf);
+		}
+	}
+
+	if (spec.childRelationships) {
+		for (const child of spec.childRelationships) {
+			selectChildRelationship(session, schema, node, child);
+		}
+	}
+
+	// FR-5.5: <idVariable>: ID! + where: { Id: { eq: $<idVariable> } } + first: 1.
+	// Per-leaf deepSetArg is the cleanest form for a hardcoded shape: session.ts
+	// preserves the leading `$` raw, and query-builder.ts emits it as an unquoted
+	// variable reference. Same machinery the aggregate builder uses for groupBy.
+	const idVar = spec.idVariable ?? "id";
+
+	// Children promote variables before the ID var is added; if a child filter
+	// already declared a variable with this name AND a different type, we'd
+	// silently overwrite it to `ID!` — corrupting the user's filter binding.
+	// Detect and throw rather than mask the conflict.
+	const existing = session.variables.find((v) => v.name === idVar);
+	if (existing && existing.type !== "ID!") {
+		throw new Error(
+			`buildDetail: idVariable "${idVar}" collides with a $${idVar} reference in childRelationships ` +
+				`(declared as ${existing.type}); choose a different idVariable.`,
+		);
+	}
+
+	addVariable(session, idVar, "ID!");
+	deepSetArg(session, connection, "where", ["Id", "eq"], `$${idVar}`);
+	deepSetArg(session, connection, "first", [], "1");
+
+	return buildOutput(session, schema, primingNote);
+}

package/src/intent/build-discover.ts

@@ -0,0 +1,199 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { type GraphQLSchema } from "graphql";
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import {
+	type DiscoverOutput,
+	type DiscoverSpec,
+	type FieldDescription,
+	type ObjectDescription,
+} from "./types.js";
+import { getOrgAuth as realGetOrgAuth, type OrgAuth } from "../lib/auth.js";
+import {
+	type FieldMetadata,
+	getObjectInfo as realGetObjectInfo,
+	getRequiredCreateFields,
+	type ObjectInfoResult,
+} from "../lib/object-info.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+import { resolvePath } from "../lib/walker.js";
+
+export interface DiscoverDeps {
+	primeDeps?: PrimeDeps;
+	getOrgAuth?: (orgAlias: string) => Promise<OrgAuth>;
+	getObjectInfo?: (
+		auth: OrgAuth,
+		orgAlias: string,
+		sObjectName: string,
+	) => Promise<ObjectInfoResult>;
+}
+
+/**
+ * Build the `sf_gql_discover` payload. Three modes:
+ *
+ * - `list_objects`: enumerate queryable SObjects from the schema's
+ *   `uiapi.query` selection. Optional `search` substring-filters names.
+ * - `describe_object`: fetch ObjectInfo for `spec.object` and project it
+ *   onto the spec-defined `ObjectDescription` shape.
+ * - `describe_field`: same as `describe_object`, narrowed to one field.
+ *
+ * Schema priming follows FR-13.3 — first call against an unprimed org
+ * triggers introspection and surfaces a `Note: Primed schema cache ...`
+ * warning. ObjectInfo carries its own per-object cache inside
+ * `lib/object-info.ts` (1-hour TTL), so describe_* modes do not
+ * re-introspect on every call.
+ */
+export async function buildDiscover(
+	spec: DiscoverSpec,
+	deps: DiscoverDeps = {},
+): Promise<DiscoverOutput> {
+	const { schema, primingNote } = await getSchemaWithPriming(spec.org, deps.primeDeps);
+	const warnings = primingNote ? [primingNote] : [];
+
+	if (spec.mode === "list_objects") {
+		const objects = listQueryableObjects(schema, spec.search);
+		return { mode: "list_objects", objects, ...(warnings.length ? { warnings } : {}) };
+	}
+
+	if (!spec.object) {
+		throw new Error(`sf_gql_discover mode "${spec.mode}" requires "object".`);
+	}
+
+	const getAuth = deps.getOrgAuth ?? realGetOrgAuth;
+	const fetchObjectInfo = deps.getObjectInfo ?? realGetObjectInfo;
+	const auth = await getAuth(spec.org);
+	// ObjectInfo failures (auth expired, network blip, object missing) propagate
+	// to the caller. Earlier work tried a schema-only fallback that returned
+	// field names from the cached GraphQL schema, but that response cannot
+	// satisfy ObjectDescription (no picklists, no filterable/sortable flags,
+	// no requiredOnCreate) and silently invites consumers to treat absent
+	// metadata as authoritative absence. A loud error forces the right
+	// recovery (refresh auth, prime schema, retry).
+	const info = await fetchObjectInfo(auth, spec.org, spec.object);
+
+	if (spec.mode === "describe_field") {
+		if (!spec.field) {
+			throw new Error('sf_gql_discover mode "describe_field" requires "field".');
+		}
+		const field = info.fields.find((f) => f.apiName === spec.field);
+		if (!field) {
+			throw new Error(
+				`Field "${spec.field}" not found on "${spec.object}". Use mode "describe_object" to list fields.`,
+			);
+		}
+		return {
+			mode: "describe_field",
+			field: toFieldDescription(field, info),
+			...(warnings.length ? { warnings } : {}),
+		};
+	}
+
+	if (spec.mode === "describe_object") {
+		return {
+			mode: "describe_object",
+			object: toObjectDescription(spec.object, info),
+			...(warnings.length ? { warnings } : {}),
+		};
+	}
+
+	// Exhaustiveness guard: any new DiscoverMode added to types.ts must
+	// surface as a TS error here instead of silently falling through to
+	// describe_object.
+	throw new Error(`Unhandled discover mode: ${exhaustive(spec.mode)}`);
+}
+
+function exhaustive(value: never): never {
+	throw new Error(`Unexpected value: ${String(value)}`);
+}
+
+function listQueryableObjects(
+	schema: GraphQLSchema,
+	search?: string,
+): { name: string; label?: string }[] {
+	let result: { name: string; label?: string }[];
+	try {
+		const walker = resolvePath(schema, "query", ["uiapi", "query"]);
+		// uiapi.query exposes per-SObject Connection fields (Account, Contact, etc.)
+		// alongside non-SObject helpers (search, aggregate). Filter to fields whose
+		// return type follows the *Connection convention so list_objects matches
+		// the spec contract — "queryable SObjects" — instead of leaking helpers.
+		result = walker.fields
+			.filter((f) => /Connection$/.test(f.typeName.replace(/[![\]]/g, "")))
+			.map((f) => ({
+				name: f.name,
+				...(f.description ? { label: f.description } : {}),
+			}));
+	} catch {
+		return [];
+	}
+
+	if (search && search.trim().length > 0) {
+		const needle = search.toLowerCase();
+		result = result.filter((o) => o.name.toLowerCase().includes(needle));
+	}
+	result.sort((a, b) => a.name.localeCompare(b.name));
+	return result;
+}
+
+function toFieldDescription(field: FieldMetadata, info: ObjectInfoResult): FieldDescription {
+	const picklist = info.picklists.find((p) => p.apiName === field.apiName);
+	// `parseObjectInfoResponse` already drops null-valued entries, but the
+	// PicklistValue type still allows null — filter narrows to string[].
+	const picklistValues =
+		picklist?.values.map((v) => v.value).filter((v): v is string => v !== null) ?? [];
+
+	return {
+		name: field.apiName,
+		label: field.label ?? field.apiName,
+		type: field.dataType ?? "UNKNOWN",
+		filterable: field.filterable,
+		sortable: field.sortable,
+		nameField: field.nameField,
+		compound: field.compound,
+		defaultedOnCreate: field.defaultedOnCreate,
+		...(picklistValues.length > 0 ? { picklistValues } : {}),
+	};
+}
+
+function toObjectDescription(name: string, info: ObjectInfoResult): ObjectDescription {
+	const fields = info.fields.map((f) => toFieldDescription(f, info));
+
+	const childRelationships = info.childRelationships
+		.filter((cr) => cr.relationshipName !== null)
+		.map((cr) => ({
+			relationshipName: cr.relationshipName as string,
+			childObject: cr.childObjectApiName,
+		}));
+
+	const parentReferences = info.fields
+		.filter((f) => f.reference && f.referenceToInfos.length > 0)
+		.map((f) => ({
+			field: f.apiName,
+			targetObjects: f.referenceToInfos.map((r) => r.apiName),
+		}));
+
+	const filterableFields = info.fields
+		.filter((f) => f.filterable && !f.compound)
+		.map((f) => f.apiName);
+
+	const sortable = info.fields.find((f) => f.sortable && !f.compound);
+	const orderByExample: Record<string, unknown> = sortable
+		? { [sortable.apiName]: { order: "DESC" } }
+		: {};
+
+	const requiredOnCreate = getRequiredCreateFields(info).map((f) => f.apiName);
+
+	return {
+		name,
+		fields,
+		childRelationships,
+		parentReferences,
+		filterableFields,
+		orderByExample,
+		requiredOnCreate,
+	};
+}

package/src/intent/build-list.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildOutput } from "./build-output.js";
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import { selectChildRelationship } from "./select-child-relationship.js";
+import { type ListSpec, type ToolOutput } from "./types.js";
+import { assertGraphqlName } from "../lib/graphql-name.js";
+import { selectDottedFieldPath } from "../lib/path-selection.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+import { addVariable, createSession, deepSetArg, selectLeaf } from "../lib/session.js";
+import { normalizeOrderBy, 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.
+ *
+ * Implicit behaviors not visible in the signature:
+ * - Scalar fields are auto-wrapped with `{ value }` per UIAPI; `Id` is selected bare.
+ * - Dotted paths in `fields` / `parentFields` expand polymorphic unions into
+ *   per-member inline fragments; members lacking the field are silently skipped.
+ * - `childRelationships` render as `<rel> { edges { node { ... } } }` connections.
+ * - `$varName` leaves anywhere in `filter` / `orderBy` / `scope` promote to typed
+ *   query variables (inferred from the schema; nullable; `String` on inference miss).
+ * - `orderBy` arrays are collapsed to the first element (UIAPI expects a singleton).
+ * - Cursor pagination is always on: declares `$after: String`, selects
+ *   `pageInfo { hasNextPage endCursor }`, defaults `first: 10`.
+ * - Operation name defaults to `<Object>List`.
+ *
+ * Throws on invalid `object` or `operationName` (must be valid GraphQL Names),
+ * auth-missing, or introspection failure (via `getSchemaWithPriming`); never
+ * throws on validation or codegen failure (those surface as `warnings[]`).
+ */
+export async function buildList(spec: ListSpec, deps?: PrimeDeps): Promise<ToolOutput> {
+	assertGraphqlName(spec.object, "buildList", "object");
+
+	const { schema, primingNote, instanceUrl } = await getSchemaWithPriming(spec.org, deps);
+
+	const session = createSession(spec.org, "query", instanceUrl);
+	session.operationName = spec.operationName ?? `${spec.object}List`;
+	assertGraphqlName(session.operationName, "buildList", "operationName");
+
+	const connectionPath = ["uiapi", "query", spec.object];
+	const nodePath = [...connectionPath, "edges", "node"];
+
+	for (const field of spec.fields) {
+		selectDottedFieldPath(session, schema, nodePath, field);
+	}
+
+	if (spec.parentFields) {
+		for (const pf of spec.parentFields) {
+			selectDottedFieldPath(session, schema, nodePath, pf);
+		}
+	}
+
+	if (spec.childRelationships) {
+		for (const child of spec.childRelationships) {
+			selectChildRelationship(session, schema, nodePath, child);
+		}
+	}
+
+	const first = spec.first ?? 10;
+	deepSetArg(session, connectionPath, "first", [], String(first));
+
+	addVariable(session, "after", "String");
+	deepSetArg(session, connectionPath, "after", [], "$after");
+
+	selectLeaf(session, [...connectionPath, "pageInfo", "hasNextPage"]);
+	selectLeaf(session, [...connectionPath, "pageInfo", "endCursor"]);
+
+	if (spec.filter) {
+		promoteVariables(session, schema, connectionPath, "where", spec.filter);
+		deepSetArg(session, connectionPath, "where", [], JSON.stringify(spec.filter));
+	}
+
+	const orderBy = normalizeOrderBy(spec.orderBy);
+	if (orderBy) {
+		promoteVariables(session, schema, connectionPath, "orderBy", orderBy);
+		deepSetArg(session, connectionPath, "orderBy", [], JSON.stringify(orderBy));
+	}
+
+	if (spec.scope) {
+		promoteVariables(session, schema, connectionPath, "scope", spec.scope);
+		deepSetArg(session, connectionPath, "scope", [], spec.scope);
+	}
+
+	return buildOutput(session, schema, primingNote);
+}

package/src/intent/build-mutation.ts

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildOutput } from "./build-output.js";
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import { type CreateSpec, type ToolOutput, type UpdateSpec } from "./types.js";
+import { assertGraphqlName } from "../lib/graphql-name.js";
+import { selectDottedFieldPath } from "../lib/path-selection.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+import { addVariable, createSession, deepSetArg } from "../lib/session.js";
+import {
+	createInputTypeName,
+	mutationFieldPath,
+	mutationRecordPath,
+	updateInputTypeName,
+} from "../lib/uiapi.js";
+
+export type MutationOp = "Create" | "Update";
+
+/**
+ * Build a UIAPI Create/Update mutation against a Salesforce org. Shared
+ * implementation for `sf_gql_create` and `sf_gql_update` (FR-5.6).
+ *
+ * Implicit behaviors:
+ * - `returnFields` defaults to `["Id"]`.
+ * - `inputVariable` defaults to `"input"`; a leading `$` is stripped.
+ * - Operation name defaults to `<Op><Object>` (e.g. `CreateAccount`, `UpdateAccount`).
+ * - The `input` argument on the mutation field is bound to the declared variable.
+ *
+ * Throws on invalid `object`/`inputVariable`/`operationName` GraphQL Names, empty
+ * `returnFields`, auth-missing, or introspection failure. Never throws on
+ * validation/codegen failure (those surface as `warnings[]`).
+ */
+export async function buildMutation(
+	spec: CreateSpec | UpdateSpec,
+	op: MutationOp,
+	deps?: PrimeDeps,
+): Promise<ToolOutput> {
+	assertGraphqlName(spec.object, "buildMutation", "object");
+
+	const inputVar = (spec.inputVariable ?? "input").replace(/^\$/, "");
+	assertGraphqlName(inputVar, "buildMutation", "inputVariable");
+
+	if (spec.returnFields !== undefined && spec.returnFields.length === 0) {
+		throw new Error("buildMutation: returnFields must contain at least one field");
+	}
+
+	const { schema, primingNote, instanceUrl } = await getSchemaWithPriming(spec.org, deps);
+
+	const session = createSession(spec.org, "mutation", instanceUrl);
+	session.operationName = spec.operationName ?? op + spec.object;
+	assertGraphqlName(session.operationName, "buildMutation", "operationName");
+
+	const fieldPath = mutationFieldPath(spec.object, op);
+	const recordPath = mutationRecordPath(spec.object, op);
+	const inputTypeName =
+		op === "Create" ? createInputTypeName(spec.object) : updateInputTypeName(spec.object);
+	addVariable(session, inputVar, inputTypeName + "!");
+	deepSetArg(session, fieldPath, "input", [], "$" + inputVar);
+
+	const extraWarnings: string[] = [];
+	for (const field of spec.returnFields ?? ["Id"]) {
+		try {
+			selectDottedFieldPath(session, schema, recordPath, field);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			extraWarnings.push(`returnFields: ${msg}`);
+		}
+	}
+
+	return buildOutput(session, schema, primingNote, extraWarnings);
+}

package/src/intent/build-output.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { type GraphQLSchema } from "graphql";
+import { type ToolOutput, type VariableInfo } from "./types.js";
+import { generateTypes } from "../lib/codegen.js";
+import { renderQuery } from "../lib/query-builder.js";
+import { type QuerySession } from "../lib/session.js";
+import { validateQuery } from "../lib/validator.js";
+
+const SCHEMA_LEVEL_ERROR_MARKERS = ["must define one or more fields"];
+
+/**
+ * Render → validate → codegen → assemble. Shared finalizer for every typed
+ * intent function (`buildList`, `buildDetail`, …).
+ *
+ * Never throws. 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>`.
+ *
+ * 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.
+ *
+ * `primingNote` (if provided) is prepended to `warnings[]` so callers can surface
+ * the FR-13.3 lazy-prime notification without a separate channel. `extraWarnings`
+ * are appended after schema-validation warnings — used by intent builders to
+ * surface non-validator findings (e.g. malformed `$var` placeholders).
+ */
+export function buildOutput(
+	session: QuerySession,
+	schema: GraphQLSchema,
+	primingNote?: string,
+	extraWarnings: string[] = [],
+): ToolOutput {
+	const query = renderQuery(session);
+	const warnings: string[] = primingNote ? [primingNote] : [];
+
+	try {
+		const errors = validateQuery(schema, query);
+		for (const err of errors) {
+			if (SCHEMA_LEVEL_ERROR_MARKERS.some((m) => err.message.includes(m))) continue;
+			warnings.push(`Validation: ${err.message}`);
+		}
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		warnings.push(`Validation: schema check skipped (${message})`);
+	}
+
+	let types: string;
+	try {
+		types = generateTypes(session, schema);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		types = `// Type generation failed: ${message}`;
+		warnings.push(`Codegen: ${message}`);
+	}
+
+	const variables: VariableInfo[] = session.variables.map((v) => ({
+		name: v.name,
+		type: v.type,
+		required: v.type.endsWith("!"),
+	}));
+
+	warnings.push(...extraWarnings);
+
+	return { query, variables, types, warnings };
+}

package/src/intent/build-raw.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildOutput } from "./build-output.js";
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import { type RawSpec, type RawOperation, type ToolOutput } from "./types.js";
+import { applyCommand } from "../lib/apply-command.js";
+import { assertGraphqlName } from "../lib/graphql-name.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+import { createSession } from "../lib/session.js";
+
+const DEFAULT_OP_NAME: Record<RawOperation, string> = {
+	query: "RawQuery",
+	mutation: "RawMutation",
+	aggregate: "RawAggregate",
+};
+
+/**
+ * Build an arbitrary UIAPI operation from CLI-style commands. Implements
+ * `sf_gql_raw` — the low-level escape hatch (FR-12) for operations the typed
+ * tools do not model (cross-union selections, custom mutations).
+ *
+ * `operation` selects the session root (query/mutation/aggregate); the agent
+ * hand-drives every selection. No typed-tool sugar (no aggregations[] handling,
+ * no auto-pagination, no Id defaulting).
+ *
+ * Fails fast: the first command that cannot be applied throws
+ * `command <i> (<cmd>): <why>`. Throws on an invalid `typeName` (must be a valid
+ * GraphQL Name), auth-missing / introspection failure (via getSchemaWithPriming)
+ * and on empty `commands`. Never throws on validation or codegen failure (those
+ * surface as warnings[]).
+ */
+export async function buildRaw(spec: RawSpec, deps?: PrimeDeps): Promise<ToolOutput> {
+	if (!spec.commands || spec.commands.length === 0) {
+		throw new Error("buildRaw: commands must contain at least one command");
+	}
+
+	const operation: RawOperation = spec.operation ?? "query";
+	const { schema, primingNote, instanceUrl } = await getSchemaWithPriming(spec.org, deps);
+
+	const session = createSession(spec.org, operation, instanceUrl);
+	// `typeName` lands only in the rendered operation-name position (buildOutput
+	// runs codegen without a typeName option), so it carries the GraphQL Name
+	// constraint just like the typed builders' `operationName`.
+	session.operationName = spec.typeName ?? DEFAULT_OP_NAME[operation];
+	assertGraphqlName(session.operationName, "buildRaw", "typeName");
+
+	spec.commands.forEach((cmd, i) => {
+		try {
+			applyCommand(session, schema, cmd);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`command ${i} (${cmd}): ${msg}`);
+		}
+	});
+
+	return buildOutput(session, schema, primingNote);
+}

package/src/intent/build-update.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildMutation } from "./build-mutation.js";
+import { type ToolOutput, type UpdateSpec } from "./types.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+
+/**
+ * Build a UIAPI update mutation against a Salesforce org. Implements
+ * `sf_gql_update` intent for the graphiti MCP server (FR-5.6). Thin
+ * wrapper around `buildMutation` with `op = "Update"`; see that helper
+ * for behavior details.
+ */
+export async function buildUpdate(spec: UpdateSpec, deps?: PrimeDeps): Promise<ToolOutput> {
+	return buildMutation(spec, "Update", deps);
+}