@salesforce/graphiti 10.10.2

package/dist/intent/build-discover.js

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import { getOrgAuth as realGetOrgAuth } from "../lib/auth.js";
+import { getObjectInfo as realGetObjectInfo, getRequiredCreateFields, } from "../lib/object-info.js";
+import { resolvePath } from "../lib/walker.js";
+/**
+ * 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, deps = {}) {
+    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) {
+    throw new Error(`Unexpected value: ${String(value)}`);
+}
+function listQueryableObjects(schema, search) {
+    let result;
+    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, info) {
+    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 !== 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, info) {
+    const fields = info.fields.map((f) => toFieldDescription(f, info));
+    const childRelationships = info.childRelationships
+        .filter((cr) => cr.relationshipName !== null)
+        .map((cr) => ({
+        relationshipName: cr.relationshipName,
+        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 = sortable
+        ? { [sortable.apiName]: { order: "DESC" } }
+        : {};
+    const requiredOnCreate = getRequiredCreateFields(info).map((f) => f.apiName);
+    return {
+        name,
+        fields,
+        childRelationships,
+        parentReferences,
+        filterableFields,
+        orderByExample,
+        requiredOnCreate,
+    };
+}
+//# sourceMappingURL=build-discover.js.map

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

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

package/dist/intent/build-list.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { type ListSpec, type ToolOutput } from "./types.js";
+import { type PrimeDeps } from "../lib/prime-schema.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 declare function buildList(spec: ListSpec, deps?: PrimeDeps): Promise<ToolOutput>;

package/dist/intent/build-list.js

@@ -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 { 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";
+/**
+ * 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, deps) {
+    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);
+}
+//# sourceMappingURL=build-list.js.map

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

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

package/dist/intent/build-mutation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { type CreateSpec, type ToolOutput, type UpdateSpec } from "./types.js";
+import { type PrimeDeps } from "../lib/prime-schema.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 declare function buildMutation(spec: CreateSpec | UpdateSpec, op: MutationOp, deps?: PrimeDeps): Promise<ToolOutput>;

package/dist/intent/build-mutation.js

@@ -0,0 +1,54 @@
+/**
+ * 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 { assertGraphqlName } from "../lib/graphql-name.js";
+import { selectDottedFieldPath } from "../lib/path-selection.js";
+import { addVariable, createSession, deepSetArg } from "../lib/session.js";
+import { createInputTypeName, mutationFieldPath, mutationRecordPath, updateInputTypeName, } from "../lib/uiapi.js";
+/**
+ * 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, op, deps) {
+    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 = [];
+    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);
+}
+//# sourceMappingURL=build-mutation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-mutation.js","sourceRoot":"","sources":["../../src/intent/build-mutation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACN,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,iBAAiB,CAAC;AAIzB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,IAA6B,EAC7B,EAAc,EACd,IAAgB;IAEhB,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,CAAC,CAAC;IAE1D,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpE,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,eAAe,CAAC,CAAC;IAE9D,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAExF,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IACjE,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/D,iBAAiB,CAAC,OAAO,CAAC,aAAa,EAAE,eAAe,EAAE,eAAe,CAAC,CAAC;IAE3E,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvD,MAAM,aAAa,GAClB,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvF,WAAW,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,GAAG,GAAG,CAAC,CAAC;IACpD,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,GAAG,QAAQ,CAAC,CAAC;IAE5D,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC;YACJ,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,aAAa,CAAC,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;QAC5C,CAAC;IACF,CAAC;IAED,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;AACjE,CAAC"}

package/dist/intent/build-output.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 } from "./types.js";
+import { type QuerySession } from "../lib/session.js";
+/**
+ * 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 declare function buildOutput(session: QuerySession, schema: GraphQLSchema, primingNote?: string, extraWarnings?: string[]): ToolOutput;

package/dist/intent/build-output.js

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { generateTypes } from "../lib/codegen.js";
+import { renderQuery } from "../lib/query-builder.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, schema, primingNote, extraWarnings = []) {
+    const query = renderQuery(session);
+    const warnings = 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;
+    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 = session.variables.map((v) => ({
+        name: v.name,
+        type: v.type,
+        required: v.type.endsWith("!"),
+    }));
+    warnings.push(...extraWarnings);
+    return { query, variables, types, warnings };
+}
+//# sourceMappingURL=build-output.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-output.js","sourceRoot":"","sources":["../../src/intent/build-output.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,0BAA0B,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAC1B,OAAqB,EACrB,MAAqB,EACrB,WAAoB,EACpB,gBAA0B,EAAE;IAE5B,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAa,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5D,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;gBAAE,SAAS;YAC9E,QAAQ,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,CAAC;IACF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,QAAQ,CAAC,IAAI,CAAC,qCAAqC,OAAO,GAAG,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACJ,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,KAAK,GAAG,8BAA8B,OAAO,EAAE,CAAC;QAChD,QAAQ,CAAC,IAAI,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,SAAS,GAAmB,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/D,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;KAC9B,CAAC,CAAC,CAAC;IAEJ,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;IAEhC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC9C,CAAC"}

package/dist/intent/build-raw.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { type RawSpec, type ToolOutput } from "./types.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+/**
+ * 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 declare function buildRaw(spec: RawSpec, deps?: PrimeDeps): Promise<ToolOutput>;

package/dist/intent/build-raw.js

@@ -0,0 +1,54 @@
+/**
+ * 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 { applyCommand } from "../lib/apply-command.js";
+import { assertGraphqlName } from "../lib/graphql-name.js";
+import { createSession } from "../lib/session.js";
+const DEFAULT_OP_NAME = {
+    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, deps) {
+    if (!spec.commands || spec.commands.length === 0) {
+        throw new Error("buildRaw: commands must contain at least one command");
+    }
+    const operation = 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);
+}
+//# sourceMappingURL=build-raw.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-raw.js","sourceRoot":"","sources":["../../src/intent/build-raw.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,eAAe,GAAiC;IACrD,KAAK,EAAE,UAAU;IACjB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;CACzB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAa,EAAE,IAAgB;IAC7D,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,SAAS,GAAiB,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC;IAC1D,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAExF,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IAChE,6EAA6E;IAC7E,0EAA0E;IAC1E,4DAA4D;IAC5D,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,QAAQ,IAAI,eAAe,CAAC,SAAS,CAAC,CAAC;IACpE,iBAAiB,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAEjE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QAChC,IAAI,CAAC;YACJ,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC;QAClD,CAAC;IACF,CAAC,CAAC,CAAC;IAEH,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;AAClD,CAAC"}

package/dist/intent/build-update.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+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 declare function buildUpdate(spec: UpdateSpec, deps?: PrimeDeps): Promise<ToolOutput>;

package/dist/intent/build-update.js

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { buildMutation } from "./build-mutation.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, deps) {
+    return buildMutation(spec, "Update", deps);
+}
+//# sourceMappingURL=build-update.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-update.js","sourceRoot":"","sources":["../../src/intent/build-update.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAgB,EAAE,IAAgB;IACnE,OAAO,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AAC5C,CAAC"}

package/dist/intent/get-schema-with-priming.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { type GraphQLSchema } from "graphql";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+export interface SchemaWithPriming {
+    schema: GraphQLSchema;
+    instanceUrl: string;
+    primingNote?: string;
+}
+/**
+ * Resolve the schema for `orgAlias`, lazily priming the on-disk cache on miss.
+ *
+ * - Cache hit → `{ schema, instanceUrl }` only.
+ * - Cache miss + auth resolves → introspects, writes cache, returns
+ *   `{ schema, instanceUrl, primingNote: 'Note: Primed schema cache for "<org>" (took Nms)' }`.
+ *   Callers thread the note into their `ToolOutput.warnings[]` per FR-13.3.
+ * - Auth missing or introspection failure → throws (FR-13.5 / FR-13.6).
+ *
+ * The returned schema is loaded by instance URL (auth-free fast path), so the
+ * cost of `getSchema(prime.instanceUrl)` is just a Map lookup after the first
+ * call per process.
+ */
+export declare function getSchemaWithPriming(orgAlias: string, deps?: PrimeDeps): Promise<SchemaWithPriming>;

package/dist/intent/get-schema-with-priming.js

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { primeSchemaWithLock } from "../lib/prime-schema.js";
+import { getSchema } from "../lib/walker.js";
+/**
+ * Resolve the schema for `orgAlias`, lazily priming the on-disk cache on miss.
+ *
+ * - Cache hit → `{ schema, instanceUrl }` only.
+ * - Cache miss + auth resolves → introspects, writes cache, returns
+ *   `{ schema, instanceUrl, primingNote: 'Note: Primed schema cache for "<org>" (took Nms)' }`.
+ *   Callers thread the note into their `ToolOutput.warnings[]` per FR-13.3.
+ * - Auth missing or introspection failure → throws (FR-13.5 / FR-13.6).
+ *
+ * The returned schema is loaded by instance URL (auth-free fast path), so the
+ * cost of `getSchema(prime.instanceUrl)` is just a Map lookup after the first
+ * call per process.
+ */
+export async function getSchemaWithPriming(orgAlias, deps) {
+    const prime = await primeSchemaWithLock(orgAlias, deps);
+    const schema = getSchema(prime.instanceUrl);
+    const base = { schema, instanceUrl: prime.instanceUrl };
+    return prime.cached
+        ? base
+        : {
+            ...base,
+            primingNote: `Note: Primed schema cache for "${orgAlias}" (took ${prime.durationMs}ms)`,
+        };
+}
+//# sourceMappingURL=get-schema-with-priming.js.map

package/dist/intent/get-schema-with-priming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-schema-with-priming.js","sourceRoot":"","sources":["../../src/intent/get-schema-with-priming.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAkB,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAQ7C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,QAAgB,EAChB,IAAgB;IAEhB,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;IACxD,OAAO,KAAK,CAAC,MAAM;QAClB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC;YACA,GAAG,IAAI;YACP,WAAW,EAAE,kCAAkC,QAAQ,WAAW,KAAK,CAAC,UAAU,KAAK;SACvF,CAAC;AACL,CAAC"}