@uipath/maestro-builder-sdk 6.41.2 → 6.43.0

package/dist/nodes/agent/flow/resources.js

@@ -0,0 +1,1409 @@
+/**
+ * What an inline agent attaches: the definition of each resource node (a
+ * context index, a tool, an escalation, a memory) and the
+ * `<source>/resources/<id>/resource.json` the platform resolves it from, plus
+ * the agent's own per-flow definition (`inlineAgentDef`). Moved from
+ * serialize.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; every
+ * definition and file is unchanged.
+ */
+import ixpDefinition from '../../../core/ixp-definition.json' with { type: 'json' };
+import { JOB_ATTACHMENT_REF, jobAttachmentDefinition } from '../../../core/agent-sidecar.js';
+import { BUILTIN_TOOL_TYPE, CONNECTOR_TOOL_RESOURCE_TYPE, HTTP_REQUEST_TOOL_TYPE, INTERNAL_TOOL_RESOURCE_TYPE, TOOL_RESOURCE_TYPE, } from '../../../core/agent-tool-resources.js';
+import { buildConfiguration } from '../../../core/connector-configuration.js';
+import { multipartBodyFieldName, transportHttpMethod } from '../../../core/connector-inputs.js';
+import { CONTEXT_INDEX_DEFAULTS, CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, contextIndexType } from '../../../core/context-index.js';
+import { formFieldJsonSchema } from '../../../core/form-field-type.js';
+import { jsonClone } from '../../../core/json-clone.js';
+import { ownEntry } from '../../../core/own-entry.js';
+/** The inline (autonomous) agent's node type — fixed, not per-instance. */
+export const INLINE_AGENT = 'uipath.agent.autonomous';
+const IXP_DEF = ixpDefinition;
+/**
+ * The definition for ONE Context Grounding index resource, transcribed from the
+ * platform's own registry entry (`uip maestro flow registry get
+ * uipath.agent.resource.context.index.<slug>.<uuid>`, read 2026-07-31 against the
+ * tenant's "Billing Dispute SOP Index"), and confirmed against the `.flow` v1
+ * emits for the same index.
+ *
+ * Per-INSTANCE, unlike `inlineAgentDef`: the index's identity is in the node type,
+ * so every tenant index is its own type — the same shape as a published agent's
+ * release key. What is constant is everything else, and this builds that from the
+ * one thing an author supplies (name + uuid).
+ *
+ * Two details are load-bearing rather than decorative:
+ *
+ *  * `handleConfiguration` declares a single TARGET handle `input` whose
+ *    `allowedSources` are the two agent types' `context` handles, with
+ *    `maxConnections: 1`. That is the mirror of the agent's own
+ *    `allowedTargets: [{ nodeType: 'uipath.agent.resource.context.*' }]`, and it is
+ *    what makes the designer draw the join.
+ *  * `model: { source: true }` and nothing else. A resource node has no
+ *    `bpmn:` type, no serviceType and no bindings — it is not a step, it is an
+ *    artifact hanging off one. The v1 artifact carries no `bindings[]` entry for it
+ *    at all.
+ */
+export function contextIndexDef(spec) {
+    return {
+        nodeType: contextIndexType(spec),
+        version: '1.0.0',
+        category: 'agent',
+        tags: ['agent-context', 'index'],
+        description: `Context grounding index "${spec.name}".`,
+        sortOrder: 505,
+        display: { label: spec.name, description: `Context grounding index "${spec.name}".`, icon: 'file-text', shape: 'circle' },
+        handleConfiguration: [
+            {
+                position: 'top',
+                handles: [{
+                        id: 'input', type: 'target', handleType: 'artifact',
+                        constraints: {
+                            maxConnections: 1,
+                            allowedSources: [
+                                { nodeType: 'uipath.agent.autonomous', handleId: 'context' },
+                                { nodeType: 'uipath.agent.conversational', handleId: 'context' },
+                            ],
+                            validationMessage: "Only Agent's context handle can connect here",
+                        },
+                    }],
+            },
+        ],
+        model: { source: true },
+        // The platform's own `inputDefinition.properties`, transcribed. Carried so the
+        // node's inputs are CHECKABLE — without an input schema nothing can validate
+        // this node's inputs at all, and a misspelled `resultCount` reaches the tenant
+        // unremarked.
+        //
+        // The registry's `allOf` conditionals (which retrieval modes require a query,
+        // and which of the query object's three modes is live) are deliberately NOT
+        // copied: they are the designer FORM's logic, and the serializer already emits
+        // a well-formed `query` for the mode it sets.
+        inputDefinition: {
+            type: 'object',
+            properties: {
+                indexId: { type: 'string' },
+                indexName: { type: 'string' },
+                folderKey: { type: 'string' },
+                folderPath: { type: 'string' },
+                retrievalMode: { type: 'string' },
+                query: { type: 'object' },
+                threshold: { type: 'number', minimum: 0, maximum: 1 },
+                resultCount: { type: 'number', minimum: 1, maximum: 40 },
+                fileExtension: { type: 'string' },
+                folderPathPrefix: { type: 'object' },
+                citations: { type: 'string' },
+                outputColumns: { type: 'array' },
+                webSearchGrounding: { type: 'object', properties: { value: { type: 'string' } } },
+            },
+        },
+    };
+}
+/**
+ * Render an index's retrieval query into the platform's MODE-TAGGED object.
+ *
+ * The index definition's own schema (`inputDefinition.allOf`) says `query` is a
+ * `oneOf` over three shapes, each identified by `mode`: `prompt` → `promptValue`,
+ * `text-builder` → `textValue`, `variable` → `argumentPath`. All four fields are
+ * present in the platform's `inputDefaults`; only the one the mode names is read.
+ *
+ * A plain string is a `prompt` (what a designer types); anything expression-shaped
+ * is `text-builder`, whose `textValue` the runtime templates — the same slot the
+ * `folderPathPrefix` field uses, and the reason that field ships with
+ * `mode: 'text-builder'` by default.
+ */
+export function renderContextQuery(query, render) {
+    const base = { mode: 'prompt', textValue: '', promptValue: '', argumentPath: '' };
+    if (query === undefined || query === null)
+        return base;
+    const rendered = render(query);
+    const asText = typeof rendered === 'string' ? rendered : JSON.stringify(rendered);
+    if (typeof rendered === 'string' && rendered.startsWith('=js:')) {
+        return { ...base, mode: 'text-builder', textValue: asText };
+    }
+    return { ...base, promptValue: asText };
+}
+/**
+ * The `resources/<id>/resource.json` an inline agent's context index needs.
+ *
+ * The node is only half of a grounded agent, the same split as the agent itself
+ * (see `inlineAgentJson`). The platform resolves an agent's capabilities from
+ * `<source>/resources/<resource-id>/resource.json`, and `uip agent refresh` turns
+ * those into the `bindings_v2.json` entries `uip solution resources refresh`
+ * syncs. Keyed by the node's `inputs.source`, which is what joins the two halves.
+ *
+ * On the CLI path the file is the only copy: refresh strips the node and
+ * re-derives it from here, so a `.flow` with the node and no file validates clean
+ * and leaves the agent ungrounded. (Studio Web is the other direction — its
+ * `mapContextResource` builds this file FROM the canvas node.)
+ *
+ * Shape and enums are the platform's `currentResourceStorageSchema`
+ * (`@uipath/agents-storage-schemas`): `description`, `folderPath`, `indexName` and
+ * all six `settings` keys are required, `fileExtension` is `{value}` rather than a
+ * bare string, and the retrieval mode pins which extensions it accepts — hence the
+ * per-mode default here against the node's flat `'All'`. An unparseable resource
+ * is worse than none: `uip agent refresh` falls back to `resources: []` and drops
+ * every other binding with it.
+ */
+export function contextResourceJson(cx, spec) {
+    const mode = cx.retrievalMode ?? CONTEXT_INDEX_DEFAULTS.retrievalMode;
+    return {
+        $resourceType: 'context',
+        id: spec.id,
+        // Null rather than absent: optional in the schema, but every deployed
+        // resource carries it, and a designer round-trip writes it back.
+        referenceKey: null,
+        name: cx.name,
+        description: `Context grounding index "${cx.name}".`,
+        contextType: 'index',
+        // Required by the schema, and load-bearing: this file carries no `indexId`,
+        // so `indexName` + `folderPath` is the whole locator, and `createIndexBinding`
+        // leaves the folder off the binding when it is empty. `check` warns when the
+        // author omits it — an index outside the deployment folder is then unresolvable.
+        folderPath: cx.folderPath ?? '',
+        indexName: cx.name,
+        settings: {
+            retrievalMode: mode,
+            // The resource's `query` is VARIANT-tagged where the node's is MODE-tagged,
+            // and the two vocabularies do not overlap. `prompt` — what a designer types
+            // as guidance — is the model-invoked `dynamic`, and its text is the
+            // `description` the model reads when deciding what to search for.
+            // `text-builder` — an expression the runtime templates — is the pre-fetched
+            // `static`, and its text is the `value`. Confirmed behaviourally: switching
+            // the SDK's `query` from a string to an expression turned the same agent's
+            // retrieval from a tool call into a pre-fetch.
+            query: spec.query.mode === 'text-builder'
+                ? { variant: 'static', value: String(spec.query.textValue ?? '') }
+                : { variant: 'dynamic', description: String(spec.query.promptValue ?? '') },
+            // `value: ''`, as the canvas writes it (flow-workbench `mapContextQueryToWire`
+            // always sets the value), so a canvas index's resource round-trips unchanged.
+            folderPathPrefix: { variant: 'static', value: '' },
+            threshold: cx.threshold ?? CONTEXT_INDEX_DEFAULTS.threshold,
+            resultCount: cx.resultCount ?? CONTEXT_INDEX_DEFAULTS.resultCount,
+            fileExtension: { value: cx.fileExtension ?? ownEntry(CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, mode) ?? 'All' },
+            // Mode-specific keys the schema REQUIRES of those two modes and rejects
+            // nowhere else, carrying the node's own constants through the enum's
+            // spelling (the node says `enabled`; the resource says `Enabled`/`Inline`).
+            ...(mode === 'deeprag' ? { citationMode: { value: 'Inline' } } : {}),
+            ...(mode === 'batchtransform'
+                ? { webSearchGrounding: { value: 'Enabled' }, outputColumns: [] }
+                : {}),
+        },
+    };
+}
+/** A `fieldSchema` object with every declared property marked required. */
+export function requireAll(schema) {
+    const names = Object.keys(schema.properties);
+    return names.length === 0 ? schema : { ...schema, required: names };
+}
+/**
+ * The `resources/<id>/resource.json` a DEPLOYED-RESOURCE tool needs — the tool
+ * half of what `contextResourceJson` does for an index, and inert for the same
+ * reason (see that function).
+ *
+ * Shape from a real agent project (`WebResearchBriefingAgent`'s `CountSources`,
+ * a `kind: 'process'` tool), cross-checked against the platform schema: this
+ * family carries `argumentProperties` and `referenceKey` but no `iconUrl`, and
+ * `exampleCalls` is present-and-empty. `location: 'solution'` and an empty
+ * `properties.folderPath` are the inline-in-flow pair Studio Web's
+ * `mapToolResource` writes and uipcli's `agent validate` enforces — the folder
+ * itself lives in the flow's top-level `bindings[]`, which
+ * `processResourceBindings` already writes for this tool.
+ *
+ * Returns `undefined` for every OTHER kind. Which kinds get a file is measured,
+ * because `uip agent refresh` strips each resource node and re-derives it FROM
+ * the file: where the node is `source`-only the round-trip is lossless, and where
+ * the node carries the configuration the strip loses it and the rebuild cannot
+ * put it back, so writing the file turns a valid flow INVALID.
+ *
+ *  * `ixp`, `clientside` — measured to fail exactly that way (`ixp` leaves the
+ *    flow failing validate; `clientside` drops the four inputs its node needs).
+ *  * `connector` — has its own writer, {@link connectorToolResourceJson}: its
+ *    node carries the configuration in `inputs.detail`, which the strip keeps,
+ *    and the file is the one `uip agent refresh` itself derives from it.
+ *  * `mcp`, `a2a` — need the server's `availableTools` and the remote agent's
+ *    card, which are tenant reads.
+ *  * `builtin` — has its own writer, {@link builtinToolResourceJson}: its
+ *    `toolType` is a fixed per-tool constant, so the file is derivable offline.
+ *  * `httpRequest` — has its own writer, {@link httpRequestToolResourceJson}:
+ *    the file carries the request config as static `argumentProperties` and the
+ *    model-facing `inputSchema`, both derivable from the node (#935).
+ *
+ * Which `type`/`toolType` values compile writes — and so owns and may prune —
+ * is {@link compileOwnsResource}, read off the same tables these writers use.
+ */
+export function toolResourceJson(tr, spec) {
+    const common = {
+        $resourceType: 'tool',
+        id: spec.id,
+        name: tr.name,
+        // The runtime hands this to the MODEL as the tool's description, so an empty
+        // one is a tool the model has to guess at from its name alone.
+        description: tr.description ?? '',
+        isEnabled: true,
+        // `required` matters here where it does not on the agent's own contract: the
+        // model reads this schema to build the call, and an argument the process needs
+        // but the schema calls optional fails at run time with nothing said at compile
+        // time. The corpus fixture lists every declared argument.
+        inputSchema: requireAll(fieldSchema(tr.inputs)),
+        outputSchema: fieldSchema(tr.returns),
+        // No policies: `inlineAgent`'s tool refs carry none, and the field is
+        // required-but-emptyable.
+        guardrail: { policies: [] },
+        settings: {},
+        argumentProperties: {},
+    };
+    const resourceType = ownEntry(TOOL_RESOURCE_TYPE, tr.kind);
+    if (resourceType !== undefined) {
+        return {
+            ...common,
+            type: resourceType,
+            location: 'solution',
+            // The deployed resource's own key: what joins this tool to the release the
+            // solution declares.
+            referenceKey: tr.key,
+            // `folderPath` is EMPTY on purpose, and the tenant folder is not lost: for
+            // an inline-in-flow agent the folder lives in the flow's own top-level
+            // `bindings[]`, which `processResourceBindings` already writes for this
+            // tool. uipcli's `agent validate` says so where it enforces the pair —
+            // *"Inline-in-flow agents store folder info in the flow's top-level
+            // bindings[] rather than in the tool resource — Studio Web emits an empty
+            // folderPath here"* — and every `inlineAgent` tool is inline by definition.
+            properties: { processName: tr.name, folderPath: '', exampleCalls: [] },
+        };
+    }
+    return undefined;
+}
+/** `inline` → `Inline`: the node's enum spelling to the resource schema's. */
+export const enumValue = (v) => {
+    const s = String(v ?? '');
+    return s.charAt(0).toUpperCase() + s.slice(1);
+};
+/**
+ * The `resources/<id>/resource.json` of a platform BUILT-IN tool (#920) — the
+ * file the runtime builds the agent's tool list from. Without it the
+ * `tool.builtin.*` node is inert, the same failure #806 fixed for deployed
+ * resources: the agent runs with no built-in tool and the model never learns
+ * it exists.
+ *
+ * Derived from the node's own inputs (`tdef.inputDefaults` with the author's
+ * values over them), because those are what the file must agree with:
+ * `uip agent refresh --inline-in-flow` shell-ifies every resource node down to
+ * `{source, detail, itemsDescription}` and Studio Web re-hydrates the rest FROM
+ * this file, so a value only on the node does not survive a refresh or a
+ * designer round-trip.
+ *
+ * Shape: the skill's per-tool walkthroughs (`analyze-attachments.md`,
+ * `deeprag/impl-json.md`, `batch-transform/impl-json.md`) checked against the
+ * platform's `builtInToolResourceStorageSchemaV40`. Two vocabularies differ
+ * from the node's, as they do for a context index (`contextResourceJson`): the
+ * resource `query` is VARIANT-tagged where the node's is MODE-tagged, and its
+ * enums are capitalized (`Inline`, `Enabled`). `analyze-attachments` declares
+ * the model-facing call contract (`attachments` + `analysisTask` → `analysis`);
+ * `deep-rag` and `batch-transform` declare empty schemas and carry their
+ * configuration in `properties.settings`.
+ */
+export function builtinToolResourceJson(tool, label, inputs, spec) {
+    const toolType = ownEntry(BUILTIN_TOOL_TYPE, tool);
+    if (toolType === undefined)
+        return undefined;
+    const empty = { type: 'object', properties: {} };
+    const common = {
+        $resourceType: 'tool',
+        id: spec.id,
+        // Null, not absent: what identifies a built-in as NOT an external tool.
+        referenceKey: null,
+        name: label,
+        type: INTERNAL_TOOL_RESOURCE_TYPE,
+        description: String(inputs.description ?? ''),
+        isEnabled: true,
+        settings: {},
+        guardrail: { policies: [] },
+        argumentProperties: {},
+    };
+    const query = inputs.query?.mode === 'text-builder'
+        ? { variant: 'static', value: String(inputs.query.textValue ?? '') }
+        : { variant: 'dynamic', description: String(inputs.query?.promptValue ?? '') };
+    if (toolType === 'analyze-attachments') {
+        return {
+            ...common,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    attachments: {
+                        type: 'array',
+                        items: { $ref: JOB_ATTACHMENT_REF },
+                        description: String(inputs.attachmentsDescription ?? ''),
+                    },
+                    analysisTask: { type: 'string', description: String(inputs.analysisTaskDescription ?? '') },
+                },
+                required: ['attachments', 'analysisTask'],
+                definitions: { 'job-attachment': jobAttachmentDefinition() },
+            },
+            outputSchema: {
+                type: 'object',
+                properties: {
+                    analysis: {
+                        type: 'string',
+                        description: 'Analysis result of the attachments (analysis, summary, extracted information, etc.)',
+                    },
+                },
+                required: ['analysis'],
+            },
+            properties: { toolType, exampleCalls: [] },
+        };
+    }
+    if (toolType === 'deep-rag') {
+        return {
+            ...common,
+            inputSchema: empty,
+            outputSchema: empty,
+            properties: {
+                toolType,
+                exampleCalls: [],
+                settings: {
+                    contextType: 'attachments',
+                    query,
+                    folderPathPrefix: { variant: 'static' },
+                    fileExtension: { value: String(inputs.fileExtension?.value ?? 'pdf') },
+                    citationMode: { value: enumValue(inputs.citationMode?.value ?? 'inline') },
+                },
+            },
+        };
+    }
+    return {
+        ...common,
+        inputSchema: empty,
+        outputSchema: empty,
+        properties: {
+            toolType,
+            exampleCalls: [],
+            settings: {
+                contextType: 'attachments',
+                query,
+                folderPathPrefix: { variant: 'static' },
+                outputColumns: Array.isArray(inputs.outputColumns) ? inputs.outputColumns : [],
+                webSearchGrounding: { value: enumValue(inputs.webSearchGrounding?.value ?? 'enabled') },
+            },
+        },
+    };
+}
+/**
+ * The six request fields of the HTTP-request tool, in the node's (and the
+ * designer's file's) order, with the JSON Schema each takes in the file's
+ * model-facing `inputSchema`. `headers`/`params` are name/value rows and
+ * `timeout` is a number — the same normalization the node's text-builder
+ * values already carry.
+ */
+export const HTTP_REQUEST_FIELDS = [
+    ['url', { type: 'string' }],
+    ['method', { type: 'string' }],
+    ['headers', { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, value: { type: 'string' } } } }],
+    ['params', { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, value: { type: 'string' } } } }],
+    ['body', { type: 'string' }],
+    ['timeout', { type: 'number' }],
+];
+/**
+ * The `resources/<id>/resource.json` of the built-in HTTP-request tool (#935) —
+ * without it the deployed agent is never offered the tool (measured: one LLM
+ * call, no tool span), and `uip agent refresh --inline-in-flow` strips the node
+ * to `{source}`, so the request config is lost entirely.
+ *
+ * Derived from the node's own mode-tagged inputs, so the two halves cannot
+ * disagree. The rules are the ones Studio Web's own file follows (measured by
+ * saving the agent once in the designer; a file built by these rules is
+ * JSON-equal to it, and a debug run with only this file showed the tool spans):
+ *
+ *  * `inputSchema` declares all six fields, each with the node's `promptValue`
+ *    as its description — the text the model reads when it fills the field;
+ *  * `argumentProperties` pins every field NOT in `prompt` mode as
+ *    `$['<field>']: {variant: 'static', value: <textValue>}` — a fixed value the
+ *    model does not get to choose. The SDK writes only `prompt` and
+ *    `text-builder` fields; a `text-builder` value is the literal.
+ */
+export function httpRequestToolResourceJson(label, inputs, spec) {
+    const properties = {};
+    const argumentProperties = {};
+    for (const [field, schema] of HTTP_REQUEST_FIELDS) {
+        const row = (inputs[field] ?? {});
+        properties[field] = { ...schema, description: String(row.promptValue ?? '') };
+        if (row.mode !== undefined && row.mode !== 'prompt') {
+            argumentProperties[`$['${field}']`] = { variant: 'static', value: row.textValue, isSensitive: false };
+        }
+    }
+    return {
+        $resourceType: 'tool',
+        id: spec.id,
+        canvasNodeId: spec.canvasNodeId,
+        name: label,
+        type: INTERNAL_TOOL_RESOURCE_TYPE,
+        description: String(inputs.description ?? ''),
+        isEnabled: true,
+        inputSchema: { type: 'object', properties, required: ['url'] },
+        outputSchema: { type: 'object', properties: {} },
+        settings: {},
+        guardrail: { policies: [] },
+        argumentProperties,
+        properties: { toolType: HTTP_REQUEST_TOOL_TYPE },
+    };
+}
+/**
+ * The .NET type an Action Center app argument of each field type carries. Studio
+ * Web serializes the task payload through `inputSchemaDotnetTypeMapping`, which
+ * the platform schema REQUIRES on an `actionCenter` channel; it reads the raw
+ * type off the app's action schema, which the SDK does not fetch, so this is
+ * the inverse of flow-workbench's `dotNetTypeToJsonSchema` for the scalars and
+ * `System.Object` for the two composite types it has no single answer for.
+ */
+export const DOTNET_TYPE = {
+    string: 'System.String', number: 'System.Double', integer: 'System.Int32',
+    boolean: 'System.Boolean', object: 'System.Object', array: 'System.Object',
+};
+/**
+ * The folder an app escalation names: the author's `folderPath`, or
+ * `solution_folder` when they gave none — an app that ships in this solution.
+ *
+ * `solution_folder` is the platform's own spelling for that case: it is the
+ * `Folder` that `uip solution resources list` reports for a solution-internal
+ * app, and what the agents skill tells authors to copy into
+ * `channels[].properties.folderName`. The SDK used to write `""`, which no
+ * product writer produces (flow-builder-sdk#967). Measured, the two are the
+ * same everywhere it counts: the agent tool's binding generator drops both
+ * from the App binding (`resolveFolderPathBindingValue`), `uip agent refresh`
+ * plus `uip solution resources refresh` derive byte-identical files from
+ * either, and a live debug resolves the app in the debug folder for both. So
+ * this changes the vocabulary, not the behaviour.
+ */
+export function escalationAppFolder(app) {
+    return app.folderPath ? app.folderPath : 'solution_folder';
+}
+/**
+ * The `resources/<id>/resource.json` an inline agent's ESCALATION needs — the
+ * escalation half of what `toolResourceJson` does for a tool, and inert without
+ * it for the same reason (#921). Measured 2026-10-05 on alpha with `uip maestro
+ * flow debug`: the same agent, told to escalate every claim, answered *"could
+ * not escalate: no ExpenseEscalation tool available"* with the node alone, and
+ * created the Action Center task with this file beside it.
+ *
+ * Shape: the uipath-agents skill's agent-level escalation resource (it owns the
+ * body), checked field by field against the platform's
+ * `currentResourceStorageSchema` — which REQUIRES `description` (top level and
+ * channel), `isAgentMemoryEnabled`, `governanceProperties`, `properties`,
+ * `inputSchemaDotnetTypeMapping` and `channels[].properties.appVersion`.
+ *
+ * Unlike a tool, an escalation node CARRIES its configuration, and `uip agent
+ * refresh --inline-in-flow` strips it to `source` either way. Writing the file
+ * does not change that; it is what makes refresh keep the escalation at all
+ * (`Resources: 1` and the App binding in `bindings_v2.json`, against
+ * `Resources: 0` without it). The compiled `.flow` keeps the node's full inputs,
+ * so `flow validate` is unaffected.
+ */
+export function escalationResourceJson(esc, spec) {
+    const outcomeMapping = esc.outcomes && esc.outcomes.length
+        ? Object.fromEntries(esc.outcomes.map((o) => [o, 'continue']))
+        : {};
+    const common = {
+        id: spec.channelId,
+        name: 'Channel',
+        description: esc.description ?? '',
+        outcomeMapping,
+        recipients: (esc.recipients ?? []).map((v) => ({ type: 3, value: v })),
+        taskTitle: esc.taskTitle ?? '',
+        taskTitleV2: {
+            type: 'textBuilder',
+            tokens: esc.taskTitle ? [{ type: 'simpleText', rawString: esc.taskTitle }] : [],
+        },
+        labels: esc.labels ?? [],
+        argumentProperties: {},
+    };
+    let channel;
+    if (spec.quickFormSchema !== undefined) {
+        // The INLINE form: the node's own `schema` (fields + outcomes) is the
+        // channel's, and its contract is read off the field directions — what the
+        // reviewer is shown (`input`/`inOut`) and what comes back (`output`/`inOut`).
+        const fields = esc.fields ?? [];
+        const props = (dirs) => Object.fromEntries(fields
+            .filter((f) => dirs.includes(f.direction))
+            .map((f) => [f.id, formFieldJsonSchema(f.type) ?? { type: 'string' }]));
+        channel = {
+            ...common,
+            type: 'actionCenterQuickForm',
+            inputSchema: { type: 'object', properties: props(['input', 'inOut']) },
+            outputSchema: { type: 'object', properties: props(['output', 'inOut']) },
+            properties: {
+                schema: spec.quickFormSchema,
+                isActionableMessageEnabled: false,
+                actionableMessageMetaData: null,
+            },
+        };
+    }
+    else {
+        const app = esc.app;
+        const mapping = (fields) => Object.fromEntries(Object.entries(fields ?? {}).map(([k, t]) => [k, ownEntry(DOTNET_TYPE, t) ?? 'System.Object']));
+        channel = {
+            ...common,
+            type: 'actionCenter',
+            inputSchema: fieldSchema(app.inputs),
+            outputSchema: fieldSchema(app.outputs),
+            inputSchemaDotnetTypeMapping: mapping(app.inputs),
+            outputSchemaDotnetTypeMapping: mapping(app.outputs),
+            properties: {
+                // The app's key and name are what `uip agent refresh` turns into the
+                // App binding (`name` + `folderPath`) that `uip solution resources
+                // refresh` imports; `folderName` is the app's Orchestrator folder.
+                resourceKey: app.key,
+                appName: app.name,
+                folderName: escalationAppFolder(app),
+                // The app's deploy version (its action schema's `version`). The SDK does
+                // not read the action schema, so this is the platform's own default — the
+                // storage migration that introduced the field writes `1` when absent.
+                appVersion: app.version ?? 1,
+                isActionableMessageEnabled: false,
+                actionableMessageMetaData: null,
+            },
+        };
+    }
+    return {
+        $resourceType: 'escalation',
+        id: spec.id,
+        name: esc.name,
+        description: esc.description ?? '',
+        escalationType: 0,
+        isAgentMemoryEnabled: false,
+        properties: {},
+        governanceProperties: { isEscalatedAtRuntime: false },
+        isEnabled: true,
+        channels: [channel],
+    };
+}
+/**
+ * The one TARGET handle every tool resource declares: `input`, artifact-typed,
+ * fed by the two agent types' `tool` handles. Transcribed from `registry get`
+ * (identical across `tool.builtin.*`, `tool.connector.*` and every
+ * per-instance kind, 2026-07-31) — the mirror of the agent's own
+ * `allowedTargets: [{ nodeType: 'uipath.agent.resource.tool.*' }]`.
+ */
+export function toolInputHandle() {
+    return {
+        position: 'top',
+        handles: [{
+                id: 'input', type: 'target', handleType: 'artifact', isDefaultForType: true,
+                constraints: {
+                    maxConnections: 1,
+                    allowedSources: [
+                        { nodeType: 'uipath.agent.autonomous', handleId: 'tool' },
+                        { nodeType: 'uipath.agent.conversational', handleId: 'tool' },
+                    ],
+                    validationMessage: "Only Agent's tool handle can connect here",
+                },
+            }],
+    };
+}
+/** A `{ name: type }` field map as the JSON-schema object the platform stores. */
+export function fieldSchema(fields) {
+    return {
+        type: 'object',
+        properties: Object.fromEntries(Object.entries(fields ?? {}).map(([k, t]) => [k, { type: t }])),
+    };
+}
+/**
+ * The definitions for the three platform BUILT-IN tools, transcribed from
+ * `uip maestro flow registry get uipath.agent.resource.tool.builtin.<name>`
+ * (2026-07-31, version 1.1 all three). These are fixed types — no tenant
+ * resource behind them — so unlike every other tool kind the def CAN be
+ * bundled.
+ *
+ * One wrinkle carried faithfully rather than smoothed over: the three defs
+ * disagree about where the node's `source` identity lives. `analyzefiles`
+ * declares `model.source: true` (the resource-family convention);
+ * `summarize`/`batchtransform` have NO model and declare `source` as an
+ * ordinary input instead. Both spellings satisfy the platform's stable-UUID
+ * requirement, so each def ships the registry's own shape.
+ */
+export const BUILTIN_TOOL_DEFS = {
+    analyzefiles: {
+        nodeType: 'uipath.agent.resource.tool.builtin.analyzefiles',
+        version: '1.1',
+        category: 'agent.tool.builtin',
+        tags: ['agent-tool', 'builtin', 'analyze', 'files', 'attachments'],
+        description: 'Extract and analyze content from files',
+        sortOrder: 48,
+        display: {
+            label: 'Analyze Files',
+            description: 'Analyze one or more files with an LLM to extract, synthesize, or answer queries about their content.',
+            icon: 'paperclip', shape: 'circle',
+        },
+        handleConfiguration: [toolInputHandle()],
+        model: { source: true },
+        inputDefinition: {
+            type: 'object',
+            properties: {
+                description: { type: 'string' },
+                attachmentsDescription: { type: 'string' },
+                itemsDescription: {
+                    type: 'array',
+                    items: { type: 'object', properties: { label: { type: 'string' }, value: { type: 'string' } } },
+                },
+                analysisTaskDescription: { type: 'string' },
+                exampleCalls: { type: 'array' },
+            },
+        },
+        inputDefaults: {
+            description: 'Analyze one or more files with an LLM to extract, synthesize, or answer queries about their content.',
+            attachmentsDescription: 'Array of files, documents, images, or other attachments to process',
+            itemsDescription: [],
+            analysisTaskDescription: "The task, question, or instruction for processing the files (e.g., 'summarize this document', 'extract key points', 'what is in this image')",
+            exampleCalls: [],
+        },
+    },
+    summarize: {
+        nodeType: 'uipath.agent.resource.tool.builtin.summarize',
+        version: '1.1',
+        category: 'agent.tool.builtin',
+        tags: ['agent-tool', 'builtin', 'summarize', 'document', 'synthesis', 'citations'],
+        description: 'Synthesize across documents with citations',
+        sortOrder: 48,
+        display: {
+            label: 'Summarize',
+            description: 'Get comprehensive synthesis across up to 1,000 pages with citations.',
+            icon: 'database', shape: 'circle',
+        },
+        handleConfiguration: [toolInputHandle()],
+        inputDefinition: {
+            type: 'object',
+            properties: {
+                description: { type: 'string' },
+                source: { type: 'string' },
+                query: { type: 'object' },
+                fileExtension: { type: 'object', properties: { value: { type: 'string' } } },
+                citationMode: { type: 'object', properties: { value: { type: 'string' } } },
+            },
+        },
+        inputDefaults: {
+            description: 'Get comprehensive synthesis across up to 1,000 pages with citations.',
+            source: '',
+            query: { mode: 'prompt', textValue: '', promptValue: '', argumentPath: '' },
+            fileExtension: { value: 'pdf' },
+            citationMode: { value: 'inline' },
+        },
+    },
+    batchtransform: {
+        nodeType: 'uipath.agent.resource.tool.builtin.batchtransform',
+        version: '1.1',
+        category: 'agent.tool.builtin',
+        tags: ['agent-tool', 'builtin', 'batch-transform', 'csv', 'transform'],
+        description: 'Process and transform CSV files',
+        sortOrder: 48,
+        display: {
+            label: 'Batch Transform',
+            description: 'Process and transform CSV files.',
+            icon: 'table', shape: 'circle',
+        },
+        handleConfiguration: [toolInputHandle()],
+        inputDefinition: {
+            type: 'object',
+            properties: {
+                description: { type: 'string' },
+                source: { type: 'string' },
+                query: { type: 'object' },
+                outputColumns: { type: 'array' },
+                webSearchGrounding: { type: 'object', properties: { value: { type: 'string' } } },
+            },
+        },
+        inputDefaults: {
+            description: 'Process and transform CSV files.',
+            source: '',
+            query: { mode: 'prompt', textValue: '', promptValue: '', argumentPath: '' },
+            outputColumns: [],
+            webSearchGrounding: { value: 'enabled' },
+        },
+    },
+};
+/**
+ * The definition for one CONNECTOR-operation tool, derived from the same
+ * curated-library entry `connector(…)` resolves — measured equivalence, not
+ * hope: the library's `.v1def.json` `model` (bindings + the
+ * connectorKey/objectName/method context) is byte-identical to what
+ * `registry get uipath.agent.resource.tool.connector.<key>.<op>` returns for
+ * the same operation, minus `source: true` (checked 2026-07-31 against
+ * `uipath-uipath-airdk/web-search`). What the tool era changes is the frame:
+ * the node type moves one namespace over, the category gains the
+ * `agent.tool.` prefix over the v1def's own (which carries the connector's
+ * numeric id — `connector.196640` → `agent.tool.connector.196640`), the
+ * handle becomes the tool artifact handle, and `sortOrder` is the registry's
+ * 565.
+ */
+export function connectorToolDef(rc) {
+    const v1 = rc.v1def ?? {};
+    const suffix = String(rc.nodeType).replace(/^uipath\.connector\./, '');
+    return {
+        nodeType: `uipath.agent.resource.tool.connector.${suffix}`,
+        version: v1.version ?? '1.0.0',
+        category: `agent.tool.${v1.category ?? 'connector'}`,
+        tags: ['agent-tool', 'connector', 'activity'],
+        sortOrder: 565,
+        display: { ...jsonClone(v1.display ?? {}), shape: 'circle' },
+        handleConfiguration: [toolInputHandle()],
+        model: { ...jsonClone(v1.model ?? {}), source: true },
+        inputDefinition: { type: 'object', properties: {} },
+        inputDefaults: {},
+    };
+}
+/** The folder key a connection with no folder binding carries in its resource.json. */
+export const NO_FOLDER_KEY = '00000000-0000-0000-0000-000000000000';
+/**
+ * The library's operation description without the `(<Connector Name>) ` prefix
+ * the v1def's `display.description` carries — the model reads this text, and
+ * the designer's own resource.json has the bare sentence.
+ */
+export function connectorToolDescription(rc) {
+    const text = String(rc.v1def?.display?.description ?? rc.entry?.display?.description ?? '');
+    const prefix = `(${rc.connectorName}) `;
+    return rc.connectorName && text.startsWith(prefix) ? text.slice(prefix.length) : text;
+}
+/**
+ * An agent-decided value: `{{prompt: "<what the model is told>"}}`, byte for byte
+ * what the product writes — `uip maestro flow node configure` (UiPath/cli
+ * `connector-service.ts`, `` `{{prompt: "${f.description || f.displayName || f.name}"}}` ``)
+ * and the designer's `PROMPT_WRAPPER` (@uipath/maestro-sdk) both splice the text RAW.
+ * The chip format has no escape: the product's reader (`PROMPT_UNWRAPPER`) slices
+ * off the fixed `{{prompt:` / `}}` frame and strips one pair of outer quotes, so
+ * any text — `"`, `\`, a newline, a `}}` — round-trips. Escaping it here made the
+ * model read literal backslashes. FB011 registers this as the one raw chip splice.
+ */
+export function promptChip(f) {
+    const text = f.description || f.displayName || f.name;
+    return `{{prompt: "${text}"}}`;
+}
+export const isPromptChip = (v) => typeof v === 'string' && v.startsWith('{{prompt');
+/** The text inside `{{prompt: "…"}}`, read the way the product reads it (maestro-sdk PROMPT_UNWRAPPER); `''` when `value` is not a chip. */
+export function chipText(value) {
+    if (!(value.startsWith('{{prompt:') && value.endsWith('}}')))
+        return '';
+    const inner = value.slice(9, -2).trim();
+    const quoted = (inner.startsWith('"') && inner.endsWith('"')) || (inner.startsWith("'") && inner.endsWith("'"));
+    return quoted ? inner.slice(1, -1) : inner;
+}
+/** A field's enum as `{ name, value }` rows, the platform's spelling; `undefined` when it has none. */
+export function enumRows(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.map((e) => (typeof e === 'string'
+        ? { name: e, value: e }
+        : { name: String(e?.name ?? e?.value ?? ''), value: String(e?.value ?? e?.name ?? '') }));
+}
+/**
+ * The `inputs.detail` of a connector-tool node — the same key set a
+ * `connector()` step's node carries, with the request buckets filled the way
+ * `uip maestro flow node configure` fills them for a `tool.connector.*` node
+ * (uipcli `buildAgentToolParamsFromMetadata`): every BODY field is
+ * agent-decided (`{{prompt: "<description>"}}`) except a single-value enum,
+ * which is its one constant (the model would otherwise guess — `google` for
+ * `GoogleCustomSearch`); a QUERY/PATH parameter with a declared default sends
+ * it, and otherwise is agent-decided too.
+ */
+export function connectorToolDetail(rc, conn, folder, seed) {
+    const params = Array.isArray(rc.entry?.operation?.parameters) ? rc.entry.operation.parameters : [];
+    const buckets = { body: {}, query: {}, path: {} };
+    for (const f of rc.fields ?? []) {
+        const loc = f.location ?? 'body';
+        if (loc === 'body') {
+            const only = enumRows(f.enum);
+            buckets.body[f.name] = only && only.length === 1 ? only[0].value : promptChip(f);
+        }
+        else if (loc === 'query' || loc === 'path') {
+            const dflt = params.find((p) => p?.name === f.name)?.defaultValue;
+            buckets[loc][f.name] = dflt !== undefined && dflt !== null && dflt !== '' ? dflt : promptChip(f);
+        }
+    }
+    const parts = rc.multipartParts ?? [];
+    return {
+        connector: rc.connectorKey,
+        method: transportHttpMethod(rc.httpMethod),
+        endpoint: rc.endpoint,
+        ...(rc.objectName ? { objectName: rc.objectName } : {}),
+        inputMetadata: parts.length
+            ? { type: 'multipart', multipart: { bodyFieldName: multipartBodyFieldName(parts) } }
+            : {},
+        errorState: { hasError: false },
+        telemetryData: { connectorKey: rc.connectorKey, connectorName: rc.connectorName },
+        configuration: buildConfiguration(rc.entry, rc.version, {}, seed),
+        ...(rc.activityTypeId ? { uiPathActivityTypeId: rc.activityTypeId } : {}),
+        ...(conn ? { connectionId: conn, connectionResourceId: conn } : {}),
+        ...(folder ? { connectionFolderKey: folder } : {}),
+        bodyParameters: buckets.body,
+        ...(Object.keys(buckets.path).length ? { pathParameters: buckets.path } : {}),
+        ...(Object.keys(buckets.query).length ? { queryParameters: buckets.query } : {}),
+        ...(parts.length ? { multipartParameters: parts.map((p) => ({ name: p.name, dataType: p.dataType })) } : {}),
+    };
+}
+/** Walk (creating) the object chain for a dotted field name; returns the parent schema and the leaf key. */
+export function nestedSlot(root, name) {
+    const segments = name.split('.');
+    let parent = root;
+    for (const seg of segments.slice(0, -1)) {
+        let child = parent.properties[seg];
+        if (!child || child.type !== 'object') {
+            child = { type: 'object', properties: {} };
+            parent.properties[seg] = child;
+        }
+        parent = child;
+    }
+    return { parent, leaf: segments[segments.length - 1] };
+}
+/**
+ * The `resources/<id>/resource.json` of a CONNECTOR tool (#867) — the file the
+ * agent runtime registers the tool from, and the one that puts the connection
+ * under the solution's Resources.
+ *
+ * The shape is uipcli's `mapConnectorToolToResource` (the writer behind `uip
+ * agent refresh --inline-in-flow`, itself ported from flow-workbench's
+ * `agent-connector-tool` mapper), in its metadata-enriched form: field types,
+ * enums, `required` and the response fields come from the curated library,
+ * which carries the same declarations that command fetches from Integration
+ * Service. Where that writer and a Studio Web export differ, this follows the
+ * writer: `enum`/`oneOf` only on agent-decided fields (a static field with an
+ * enum breaks the runtime's model build), no `additionalProperties`, and
+ * array-of-object response fields (`results[*]`) left out.
+ *
+ * The values come from the node's own `detail` — the same source refresh reads —
+ * so a later refresh rewrites this file to itself.
+ */
+export function connectorToolResourceJson(ctx, id) {
+    const { rc, detail } = ctx;
+    const valueOf = (raw) => raw !== null && typeof raw === 'object' ? JSON.stringify(raw) : String(raw ?? '');
+    const bucketOf = { body: 'bodyParameters', query: 'queryParameters', path: 'pathParameters' };
+    const fields = [];
+    for (const f of rc.fields ?? []) {
+        const loc = f.location ?? 'body';
+        if (loc === 'multipart')
+            continue;
+        const value = valueOf(detail[bucketOf[loc]]?.[f.name]);
+        fields.push({
+            name: f.name,
+            fieldLocation: loc,
+            type: f.type || 'string',
+            ...(loc === 'body' && enumRows(f.enum)
+                ? { enumValues: enumRows(f.enum) } : {}),
+            required: f.required === true,
+            description: f.description ?? '',
+            ...(f.displayName ? { displayName: f.displayName } : {}),
+            value,
+            isPrompt: isPromptChip(value),
+        });
+    }
+    for (const part of (detail.multipartParameters ?? [])) {
+        fields.push({
+            name: part.name, fieldLocation: 'multipart', type: part.dataType || 'string',
+            required: false, description: '', value: '{{prompt}}', isPrompt: true,
+        });
+    }
+    const inputSchema = { type: 'object', properties: {} };
+    for (const f of fields) {
+        if (f.fieldLocation === 'multipart')
+            continue;
+        const { parent, leaf } = nestedSlot(inputSchema, f.name);
+        const prop = { type: f.type, title: f.displayName ?? leaf, description: f.description };
+        if (f.isPrompt && f.enumValues) {
+            prop.enum = f.enumValues.map((e) => e.value);
+            prop.oneOf = f.enumValues.map((e) => ({ const: e.value, title: e.name }));
+        }
+        parent.properties[leaf] = prop;
+        if (f.required)
+            (parent.required ??= []).push(leaf);
+    }
+    const outputSchema = { type: 'object', properties: {}, definitions: {} };
+    for (const f of (rc.entry?.outputSchema?.fields ?? [])) {
+        if (typeof f?.name !== 'string' || f.name.includes('[*]'))
+            continue;
+        const { parent, leaf } = nestedSlot(outputSchema, f.name);
+        parent.properties[leaf] = {
+            type: f.type || 'string',
+            title: f.displayName ?? leaf,
+            ...(f.description ? { description: f.description } : {}),
+        };
+    }
+    const multipart = detail.inputMetadata?.type === 'multipart';
+    return {
+        $resourceType: 'tool',
+        name: ctx.name,
+        description: ctx.description,
+        location: 'external',
+        type: CONNECTOR_TOOL_RESOURCE_TYPE,
+        inputSchema,
+        outputSchema,
+        settings: {},
+        properties: {
+            toolPath: rc.endpoint ?? '',
+            objectName: rc.objectName ?? '',
+            toolDisplayName: ctx.name,
+            toolDescription: ctx.description,
+            // The operation KEY (`GETBYID` for a get-by-id), not the transport verb:
+            // the runtime sends it to Integration Service to pick the operation.
+            method: rc.httpMethod,
+            connection: {
+                id: detail.connectionId ?? '',
+                name: rc.connectorName,
+                elementInstanceId: 0,
+                apiBaseUri: '',
+                state: 'enabled',
+                isDefault: false,
+                connector: { key: rc.connectorKey, name: rc.connectorName, image: '' },
+                folder: { key: detail.connectionFolderKey ?? NO_FOLDER_KEY, path: '' },
+            },
+            parameters: fields.map((f, i) => ({
+                name: f.name,
+                displayName: f.displayName ?? f.name,
+                type: f.type,
+                fieldLocation: f.fieldLocation,
+                value: f.value,
+                // uipcli's fallback: an undescribed agent-decided field keeps the chip's own text.
+                description: f.description || (f.isPrompt ? chipText(f.value) : ''),
+                position: f.required ? 'primary' : 'secondary',
+                sortOrder: i + 1,
+                required: f.required,
+                fieldVariant: f.isPrompt ? 'dynamic' : 'static',
+                isCascading: false,
+                dynamic: f.isPrompt,
+                enumValues: f.enumValues ?? null,
+                loadReferenceOptionsByDefault: null,
+                dynamicBehavior: [],
+                reference: null,
+            })),
+            bodyStructure: multipart
+                ? { contentType: 'multipart', jsonBodySection: detail.inputMetadata.multipart?.bodyFieldName ?? 'body' }
+                : { contentType: 'json' },
+        },
+        guardrail: { policies: [] },
+        iconUrl: ctx.iconUrl,
+        id,
+        isEnabled: true,
+    };
+}
+/**
+ * The tool kinds that wrap a DEPLOYED tenant resource, and everything that
+ * differs between them. Transcribed from `registry get` over one live example
+ * of each (2026-07-31): the five agree on the whole frame (`bpmn:ServiceTask`,
+ * `version: 'v2'`, `section: 'Published'`, the `<bindings.name>` /
+ * `<bindings.folderPath>` context, `source: true`, version `1.0.0`, the tool
+ * artifact handle, `tags: ['agent-tool']`) and differ in exactly these rows.
+ */
+export const PROCESS_TOOL_META = {
+    process: { ns: 'process', serviceType: 'Orchestrator.StartJob', subType: 'Process', orchestratorType: 'process', category: 'agent.tool.rpa', icon: 'rpa', sortOrder: 550 },
+    api: { ns: 'api', serviceType: 'Orchestrator.ExecuteApiWorkflowAsync', subType: 'Api', orchestratorType: 'api', category: 'agent.tool.api', icon: 'api', sortOrder: 555 },
+    maestro: { ns: 'processorchestration', serviceType: 'Orchestrator.StartAgenticProcess', subType: 'ProcessOrchestration', orchestratorType: 'processorchestration', category: 'agent.tool.agentic-process', icon: 'agentic-process', sortOrder: 558 },
+    flow: { ns: 'flow', serviceType: 'Orchestrator.StartFlowProcess', subType: 'Flow', orchestratorType: 'flow', category: 'agent.tool.flow', icon: 'flow-project', sortOrder: 559 },
+    agent: { ns: 'agent', serviceType: 'Orchestrator.StartAgentJob', subType: 'Agent', orchestratorType: 'agent', category: 'agent.tool.agent', icon: 'autonomous-agent', sortOrder: 560 },
+    // A published FUNCTION as an agent tool (Phase 5): same shape as its
+    // siblings, with the function family's service type and binding subtype
+    // (see `publishedFunctionDef`, transcribed from the platform's manifest).
+    function: { ns: 'function', serviceType: 'Orchestrator.ExecuteFunctionAsync', subType: 'Function', orchestratorType: 'function', category: 'agent.tool.function', icon: 'function', sortOrder: 557 },
+};
+/**
+ * The definition for one per-instance tool resource. Like `rpaWorkflowDef`
+ * and its siblings — whose model half this shares verb for verb — the def
+ * cannot be bundled: the node type carries the deployed resource's own key,
+ * and the contract (`inputSchema`/`outputSchema` in `inputDefaults`, which is
+ * where the registry's tenant-synthesized copy puts it) comes from the author
+ * because offline nothing else can know it.
+ */
+export function processToolDef(kind, spec) {
+    const meta = PROCESS_TOOL_META[kind];
+    const inputProps = Object.keys(spec.inputs ?? {});
+    return {
+        nodeType: `uipath.agent.resource.tool.${meta.ns}.${spec.key}`,
+        version: '1.0.0',
+        category: meta.category,
+        tags: ['agent-tool'],
+        sortOrder: meta.sortOrder,
+        display: { label: spec.name, icon: meta.icon, shape: 'circle' },
+        handleConfiguration: [toolInputHandle()],
+        model: {
+            type: 'bpmn:ServiceTask',
+            serviceType: meta.serviceType,
+            version: 'v2',
+            section: 'Published',
+            bindings: {
+                resource: 'process',
+                resourceSubType: meta.subType,
+                resourceKey: `${spec.folderPath}.${spec.name}`,
+                orchestratorType: meta.orchestratorType,
+                values: [
+                    { name: 'name', propertyAttribute: 'name', default: spec.name },
+                    { name: 'folderPath', propertyAttribute: 'folderPath', default: spec.folderPath },
+                ],
+            },
+            context: [
+                { name: 'name', type: 'string', value: '<bindings.name>' },
+                { name: 'folderPath', type: 'string', value: '<bindings.folderPath>' },
+                { name: '_label', type: 'string', value: spec.name },
+            ],
+            source: true,
+        },
+        // The registry's per-tenant copy declares the resource's arguments here
+        // when it can read the deployed resource; offline the author's declaration
+        // is the only source (`{}` when none — the registry's own empty shape).
+        inputDefinition: inputProps.length ? fieldSchema(spec.inputs) : {},
+        inputDefaults: {
+            ...Object.fromEntries(inputProps.map((k) => [k, null])),
+            inputSchema: fieldSchema(spec.inputs),
+            outputSchema: fieldSchema(spec.returns),
+        },
+    };
+}
+/**
+ * The definition for one published IxP project AS A TOOL.
+ *
+ * The same registry family as `ixpExtractDef`'s one namespace over, and the
+ * comparison that prices it: this def has **no `model` key at all** — which is
+ * not special, it is the shape `tool.builtin.summarize` and
+ * `tool.builtin.batchtransform` already carry. So an IxP tool needs no bindings
+ * and no resource identity beyond the node type; the agent's own resource list
+ * is what points at it. (G16 deferred this family as "`model: null`" — measured
+ * again on 2026-07-31 with a fresh registry cache, the key is absent, and the
+ * only genuinely new thing is the 6-field `inputDefaults` below.)
+ *
+ * Transcribed from `registry get uipath.agent.resource.tool.ixp.<slug>.<projectId>`
+ * (2026-07-31, post-`pull --force`). Note the tail is the project's OWN id here,
+ * where an extraction STEP's type carries the project VERSION id.
+ */
+export function ixpToolDef(spec) {
+    const slug = spec.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    const attachmentDescription = spec.attachment?.description ?? 'File to extract data from.';
+    return {
+        nodeType: `uipath.agent.resource.tool.ixp.${slug}.${spec.projectId}`,
+        version: '1.0.0',
+        category: 'agent.tool.ixp',
+        tags: ['agent-tool', 'ixp', 'document-understanding'],
+        description: '',
+        sortOrder: 575,
+        display: {
+            label: spec.name,
+            description: spec.description ?? '',
+            icon: 'file-text',
+            shape: 'circle',
+        },
+        handleConfiguration: [toolInputHandle()],
+        form: {
+            id: 'ixp-tool-form',
+            title: 'IXP Tool',
+            sections: [{
+                    id: 'ixp-settings',
+                    title: 'IXP Settings',
+                    collapsible: true,
+                    defaultExpanded: true,
+                    fields: [
+                        { name: 'inputs.name', type: 'text', label: 'Name' },
+                        { name: 'inputs.description', type: 'textarea', label: 'Description', placeholder: 'Enter tool description' },
+                        {
+                            name: 'inputs.versionTag', type: 'select', label: 'Model',
+                            placeholder: 'Select a version tag',
+                            dataSource: {
+                                type: 'fetch',
+                                url: `uipath://ixp/projects/${spec.projectId}/tags`,
+                                method: 'GET',
+                                transform: 'data.map(tag => ({ label: tag.name, value: tag.name }))',
+                            },
+                        },
+                        {
+                            name: 'inputs.attachmentConfig', type: 'custom', component: 'ixp-attachment-editor',
+                            label: '', componentProps: { defaultDescription: attachmentDescription },
+                        },
+                    ],
+                }],
+        },
+        // The tool namespace's OWN `inputDefinition` — the same 11-property
+        // catalogue, but with `required: ["fileRef"]` and no `minLength`s, because a
+        // tool has no model or folder to resolve at design time (measured: the
+        // extractor's and the tool's copies are NOT equal, even post-pull) — plus
+        // ONE deliberate widening, three keys.
+        //
+        // The registry's copy declares neither `name` nor `description`, and its own
+        // `form` binds `inputs.name` and `inputs.description` as the tool's first two
+        // fields, so a node that omits them is a tool with no name. `source` is the
+        // third: the platform's validator requires a stable uuid there on every
+        // agent-resource node (MST-9265), and its own model-less builtin tool defs
+        // declare it as an input for exactly that reason. Widening is lesson 42's
+        // other branch, taken here because — unlike the extractor's `description` —
+        // these three are load-bearing rather than inert.
+        inputDefinition: {
+            ...jsonClone(IXP_DEF.toolInputDefinition),
+            properties: {
+                ...jsonClone(IXP_DEF.toolInputDefinition.properties),
+                source: { type: 'string' },
+                name: { type: 'string' },
+                description: { type: 'string' },
+            },
+        },
+        inputDefaults: {
+            name: spec.name,
+            description: spec.description ?? '',
+            projectName: spec.name,
+            projectId: spec.projectId,
+            versionTag: spec.versionTag ?? '',
+            attachmentConfig: {
+                mode: spec.attachment?.mode ?? 'prompt',
+                description: attachmentDescription,
+                argumentPath: spec.attachment?.argumentPath ?? '',
+            },
+        },
+    };
+}
+/**
+ * The definition for an ESCALATION — the `coded-action-app` variant, which is
+ * the one this tenant's registry serves. Transcribed from `registry get
+ * uipath.agent.resource.escalation.coded-action-app` (2026-07-31, v1.1).
+ *
+ * Node-type note, because it is the one place this card had to choose between
+ * eras: the deployed corpus (2026-05-22) carries the BARE
+ * `uipath.agent.resource.escalation`, today's registry resolves only the
+ * suffixed variants, and the agent definition's own handle accepts both
+ * (`allowedTargets: [{escalation}, {escalation.*}]`). New emission follows
+ * what the registry can still answer for.
+ */
+export function escalationDef() {
+    return {
+        nodeType: 'uipath.agent.resource.escalation.coded-action-app',
+        version: '1.1',
+        category: 'agent',
+        tags: ['agentic', 'ai', 'agent', 'escalation'],
+        description: 'Escalate to a human for review or action',
+        sortOrder: 5,
+        display: {
+            label: 'Action App Escalation',
+            description: 'Escalation point for human intervention',
+            icon: 'user-round', shape: 'circle',
+        },
+        handleConfiguration: [
+            {
+                position: 'bottom',
+                handles: [{
+                        id: 'input', type: 'target', handleType: 'artifact',
+                        constraints: {
+                            maxConnections: 1,
+                            allowedSources: [
+                                { nodeType: 'uipath.agent.autonomous', handleId: 'escalation' },
+                                { nodeType: 'uipath.agent.conversational', handleId: 'escalation' },
+                            ],
+                            validationMessage: "Only Agent's escalation handle can connect here",
+                        },
+                    }],
+            },
+        ],
+        model: { source: true },
+        // ONE deliberate widening over the registry's copy, documented rather than
+        // silent: the registry's inputDefinition declares only {name, description,
+        // type} while its own inputDefaults — and every deployed escalation node in
+        // the corpus — carry six more keys (app, recipients, outcomeMapping,
+        // _additionalProps, _notifications, _appInputs). A def that under-declares
+        // what the node carries makes a validator flag OUR OWN emission — it sets
+        // inputs its type does not declare (measured: v1's deployed escalation
+        // artifact draws the same six warnings). Declaring them keeps
+        // the node checkable, which is the same reason CX's context def carries a
+        // full schema (its comment: "without it a misspelled field reaches the
+        // tenant unremarked").
+        inputDefinition: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', minLength: 1 },
+                description: { type: 'string' },
+                type: { type: 'string' },
+                app: { type: ['object', 'null'] },
+                recipients: { type: 'array' },
+                outcomeMapping: { type: ['object', 'null'] },
+                _additionalProps: { type: 'object' },
+                _notifications: { type: 'boolean' },
+                _appInputs: { type: ['object', 'null'] },
+            },
+            required: ['name'],
+        },
+        inputDefaults: {
+            name: 'Escalation',
+            description: '',
+            type: 'app-task',
+            app: null,
+            recipients: [],
+            outcomeMapping: null,
+            _additionalProps: { taskTitle: '', priority: 'medium', labels: [] },
+            _notifications: false,
+            _appInputs: null,
+        },
+    };
+}
+/**
+ * The definition for ONE MCP-server tool resource, mirrored from the platform's
+ * own mapper (`flow-core` `transformMcpServer`, read from the workbench dist —
+ * the registry serves the family per instance, tenant-side). The node type is
+ * minted from the server's name and key with the mapper's own slug rule.
+ */
+export function mcpToolDef(spec) {
+    const slug = (v) => v.replace(/[^a-zA-Z0-9.]+/g, '-').toLowerCase();
+    return {
+        nodeType: `uipath.agent.resource.tool.mcp.${slug(spec.name)}.${slug(spec.key)}`,
+        version: '1.0.0',
+        category: 'agent.tool.mcp',
+        tags: ['agent-tool', 'mcp', 'mcp-server'],
+        description: spec.description ?? '',
+        sortOrder: 585,
+        display: { label: spec.name, description: spec.description ?? '', icon: 'mcp', shape: 'circle' },
+        handleConfiguration: [toolInputHandle()],
+        model: { source: true },
+        inputDefaults: {
+            name: spec.name,
+            description: spec.description ?? '',
+            referenceKey: spec.key,
+            folderPath: spec.folderPath ?? '',
+            folderKey: spec.folderKey ?? '',
+            mcpType: spec.mcpType ?? '',
+            serviceName: spec.serviceName ?? '',
+            // The mapper's field name for the canonical server SLUG (historical).
+            serverUrl: spec.slug ?? '',
+            selectedTools: spec.selectedTools ?? [],
+            toolCatalog: spec.selectedTools ?? [],
+            discoveryMode: { type: 'cached', refreshSchemaBeforeCall: true },
+        },
+    };
+}
+/**
+ * The definition for ONE remote-A2A tool resource, mirrored from
+ * `transformRemoteA2aResource` — same provenance and slug rule as the MCP def.
+ */
+export function a2aToolDef(spec) {
+    const slug = (v) => v.replace(/[^a-zA-Z0-9.]+/g, '-').toLowerCase();
+    return {
+        nodeType: `uipath.agent.resource.tool.a2a.${slug(spec.name)}.${slug(spec.key)}`,
+        version: '1.0.0',
+        category: 'agent.tool.remote-a2a',
+        tags: ['agent-tool', 'remote-a2a', 'a2a', 'agent'],
+        description: spec.description ?? '',
+        sortOrder: 590,
+        display: { label: spec.name, description: spec.description ?? '', icon: 'a2a', shape: 'circle' },
+        handleConfiguration: [toolInputHandle()],
+        model: { source: true },
+        inputDefaults: {
+            name: spec.name,
+            description: spec.description ?? '',
+            slug: spec.slug,
+            cachedAgentCard: spec.cachedAgentCard ?? null,
+            referenceKey: spec.key,
+            resourceType: spec.resourceType ?? null,
+            folderPath: spec.folderPath ?? '',
+            folderKey: spec.folderKey ?? '',
+            resourceFolderPath: spec.resourceFolderPath ?? '',
+        },
+        outputDefinition: {},
+    };
+}
+/**
+ * The definition for ONE episodic-memory resource, mirrored from
+ * `transformEpisodicMemory`. The memory's identity rides ON the
+ * inputDefinition (`memoryId`/`folderKey`), verbatim — that is where the
+ * platform's own mapper puts it.
+ */
+export function memoryResourceDef(spec) {
+    const slug = (v) => v.replace(/[^a-zA-Z0-9.]+/g, '-').toLowerCase();
+    return {
+        nodeType: `uipath.agent.resource.memory.${slug(spec.name)}.${slug(spec.id)}`,
+        version: '1.0.0',
+        category: 'agent',
+        tags: ['agent-memory', 'memory'],
+        description: spec.description ?? '',
+        sortOrder: 15,
+        display: { label: spec.name, description: spec.description ?? '', icon: 'database', shape: 'circle' },
+        handleConfiguration: [{
+                position: 'bottom',
+                handles: [{
+                        id: 'input', type: 'target', handleType: 'artifact',
+                        constraints: {
+                            maxConnections: 1,
+                            allowedSources: [
+                                { nodeType: 'uipath.agent.autonomous', handleId: 'memory' },
+                                { nodeType: 'uipath.agent.conversational', handleId: 'memory' },
+                            ],
+                            validationMessage: "Only Agent's memory handle can connect here",
+                        },
+                    }],
+            }],
+        model: { source: true },
+        inputDefinition: {
+            memoryId: spec.id,
+            folderKey: spec.folderKey ?? '',
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                description: { type: 'string' },
+                dynamicFewShotLearning: { type: 'boolean' },
+                semanticSimilarity: { type: 'number', minimum: 0, maximum: 1 },
+                kValue: { type: 'number' },
+                searchMode: { type: 'string' },
+            },
+        },
+        inputDefaults: {
+            name: spec.name,
+            description: spec.description ?? '',
+            dynamicFewShotLearning: true,
+            semanticSimilarity: 0,
+            kValue: 3,
+            searchMode: 'hybrid',
+        },
+    };
+}
+/** True when a definition declares the agent's `memory` artifact handle. */
+export function declaresMemoryHandle(def) {
+    return (def?.handleConfiguration ?? []).some((g) => (g?.handles ?? []).some((h) => h?.id === 'memory'));
+}
+/**
+ * The definition for the INLINE autonomous agent: the bundled pair for
+ * `version` (the newest by default), plus an explicit overlay of the details
+ * the registry payload does not carry.
+ *
+ * This is the one node type in the agent family that is the SAME on every
+ * tenant — it carries its own configuration instead of referencing a resource —
+ * so `uip maestro flow registry get uipath.agent.autonomous` is a direct oracle
+ * and the bundle entry is the registry's definition as last synced
+ * (`sync:definitions` writes it through unchanged; `check:definitions --deep`
+ * reports content that has moved since). Versions and content both come from
+ * there.
+ *
+ * The overlay, and nothing else:
+ *
+ *  * `outputDefinition.output.source` is `=result.response`. The registry's
+ *    definition declares no `source`; the deployed corpus (29 `uipath.agent.autonomous` nodes, 05-18 → 07-29) has
+ *    `=result.response` in 27 of 27 that declare outputs, and the engine's own
+ *    inline dispatch returns `{ response: { …declared keys } }`. Without it the
+ *    node's `output` is the whole result envelope rather than the declared keys.
+ *    It is applied at every version; the registry payload has no `source`.
+ *  * The `memory` handle is kept only when the flow attaches memory. It is
+ *    LOCAL content (#431) on the bundled 1.4, absent from the registry's 1.4
+ *    (`check.ts` AGENT_MEMORY_NOT_AUTHORABLE), so an agent without memory gets
+ *    the registry's handle set.
+ *
+ * NO per-instance schema goes on the definition: `definitions[]` is keyed by
+ * node TYPE, and every inline agent in a flow shares this one entry. A flow
+ * with two agents (an analyst and a writer, say) therefore cannot have both
+ * contracts here — whichever was emitted last would win, and every read against
+ * the other resolved to the wrong shape (GA row 7's port: 25 undeclared-field
+ * errors on a correct flow). The authored contract goes on the NODE
+ * (`node.outputs.output.schema`, in the `inlineAgent` arm), where a reader that
+ * refines per node picks it up.
+ *
+ * The bundled 1.2 is the pre-#956 default, kept so a flow this SDK compiled
+ * before — and a decompile of one, which pins `{ version: '1.2' }` — still
+ * compiles. The corpus also carries 1.1 and 1.3; `shared/sample-flows/
+ * inline-agent.flow` says 1.0, which appears in none of the 29.
+ */
+export function inlineAgentDef(version, withMemory, resolve) {
+    const bundled = resolve(INLINE_AGENT, version);
+    if (!bundled)
+        return undefined;
+    const def = jsonClone(bundled);
+    const output = def.outputDefinition?.output;
+    if (output)
+        output.source = '=result.response';
+    if (!withMemory) {
+        for (const group of def.handleConfiguration ?? []) {
+            if (Array.isArray(group?.handles))
+                group.handles = group.handles.filter((h) => h?.id !== 'memory');
+        }
+        def.handleConfiguration = (def.handleConfiguration ?? []).filter((g) => g?.handles?.length);
+    }
+    return def;
+}