@uipath/maestro-builder-sdk 6.41.2 → 6.43.0

package/dist/nodes/agent/flow/inline-agent.js

@@ -0,0 +1,526 @@
+import { agentInputPlan, inlineAgentJson } from '../../../core/agent-sidecar.js';
+import { derivedContextSource, derivedEscalationSource, derivedToolSource } from '../../../core/agent-resource-identity.js';
+import { GUID_RE } from '../../../core/binding-messages.js';
+import { formFieldSettingsWire, wireFormFieldType } from '../../../core/form-field-type.js';
+import { outcomeSlug } from '../../../core/hitl-routing.js';
+import { jsonClone } from '../../../core/json-clone.js';
+import { subNodeId } from '../../../core/node-id-placeholder.js';
+import { ownEntry } from '../../../core/own-entry.js';
+import { processResourceBindings } from '../../../core/process-resource.js';
+import { fnv1aX4Uuid, schemaId } from '../../../core/stable-id.js';
+import { synthesizedDefinitionRefusal } from '../../../core/synthesized-definition.js';
+import { BUILTIN_TOOL_DEFS, INLINE_AGENT, PROCESS_TOOL_META, a2aToolDef, builtinToolResourceJson, connectorToolDef, connectorToolDescription, connectorToolDetail, connectorToolResourceJson, contextIndexDef, contextResourceJson, declaresMemoryHandle, escalationAppFolder, escalationDef, escalationResourceJson, fieldSchema, httpRequestToolResourceJson, inlineAgentDef, ixpToolDef, mcpToolDef, memoryResourceDef, processToolDef, renderContextQuery, toolResourceJson, } from './resources.js';
+/** Every bundled version of the inline agent, oldest first; the newest is the default (#956). */
+export const INLINE_AGENT_VERSIONS = ['1.2', '1.3', '1.4'];
+export const INLINE_AGENT_DEFAULT_VERSION = INLINE_AGENT_VERSIONS[INLINE_AGENT_VERSIONS.length - 1];
+/** The inline agent's node, sidecar and resources. */
+export function serializeInlineAgent(s, ctx) {
+    const step = ctx.step;
+    const render = (v) => ctx.render(v);
+    const returns = s.returns && Object.keys(s.returns).length
+        ? s.returns
+        // The definition's own default. Deliberately kept rather than made
+        // required: it is what the platform scaffolds, so a flow that reads
+        // `content` is a real (if toy) flow. `check` says so.
+        : { content: 'string' };
+    // ONE default version for every call shape — the newest bundled pair (see
+    // `inlineAgentDef`). `mode` and `memory` used to pick the version too (1.3
+    // and 1.4), so a plain agent got a superseded 1.2 and each option moved the
+    // node to another version as a side effect (#956). Both now live in the
+    // sidecar and on edges; neither selects a definition. An explicit
+    // `{ version }` (what decompile writes back) resolves exactly.
+    const version = ctx.version;
+    // `definitions[]` holds one entry per type@version, so a flow where any
+    // agent attaches memory keeps the handle for all of them.
+    const withMemory = s.memory !== undefined || declaresMemoryHandle(ctx.emitted(INLINE_AGENT, version));
+    const def = inlineAgentDef(version, withMemory, (t, v) => ctx.definition(t, v));
+    // The registry refuses a version it neither registers nor finds carried
+    // before serialize runs, so a definition always resolves here.
+    if (!def)
+        throw new Error(`internal SDK error: step "${step}": no definition resolves for ${INLINE_AGENT}@${version}.`);
+    if (s.memory !== undefined && !declaresMemoryHandle(def)) {
+        throw new Error(`"${step}" attaches \`memory\`, but ${INLINE_AGENT}@${version} declares no \`memory\` handle. `
+            + (version === INLINE_AGENT_DEFAULT_VERSION
+                ? `Pin a version that has it with inlineAgent({ ..., version: '<x.y>' }) `
+                    + `(bundled with memory: ${INLINE_AGENT_VERSIONS.filter((v) => declaresMemoryHandle(ctx.definition(INLINE_AGENT, v))).join(', ') || 'none'}), or drop \`memory\`.`
+                : `Drop { version: '${version}' } to use ${INLINE_AGENT_DEFAULT_VERSION}, or drop \`memory\`.`));
+    }
+    // `source` is the agent's directory name; see `ctx.agentSource`.
+    const source = ctx.agentSource(s.source);
+    // The per-instance CONTRACT lands on the node, because the definition is
+    // shared by every inline agent in the flow and cannot hold it (see
+    // `inlineAgentDef`): the declared keys over a copy of the definition's
+    // generic `output` descriptor, which is the shape an instance-refining reader
+    // picks up. The definition's slots get their `{nodeId}` placeholders filled,
+    // as every node's do; the author's keys are written as given, so the schema
+    // names exactly what `agentOutputVariables` and agent.json declare. Hence the
+    // whole map, `error` included, replaces the definition's rather than merging
+    // over it (a merge would fill placeholders in the author's keys too).
+    const outputs = def.outputDefinition === undefined ? undefined
+        : subNodeId(def.outputDefinition, ctx.nodeId);
+    if (outputs?.output && Object.keys(returns).length) {
+        outputs.output.schema = {
+            type: 'object',
+            properties: Object.fromEntries(Object.entries(returns).map(([k, t]) => [k, { type: t }])),
+        };
+    }
+    // What the PLATFORM will call each of these — computed once and shared by the
+    // descriptor array below and the sidecar. See `agentInputPlan`.
+    const plan = agentInputPlan(s.inputs ?? {}, render);
+    // A SHELL node (#927): the prompts and the model live only in the
+    // `<source>/agent.json` sidecar written below, never on the node. Studio Web
+    // decides which copy wins by `hasEmbeddedAgentContent` (@uipath/flow-schema):
+    // any `systemPrompt`/`userPrompt` string on the node makes the `.flow`
+    // authoritative and the sidecar is skipped, so a node copy shadowed the
+    // sidecar and lost the input tokens and the tool configuration on the first
+    // save. With no prompt strings the converter also keeps the
+    // `agentInputVariables` below as written (`canPruneAgentInputs` is false), and
+    // `uip maestro flow debug` reconciles them against the sidecar's `inputSchema`.
+    //
+    // The run settings (`mode`, `temperature`, `maxTokenPerResponse`,
+    // `maxIterations`, `guardrails`) live in the sidecar too. The node keeps
+    // exactly the keys Studio Web's own strip keeps (`toAgentShellInputs`,
+    // @uipath/flow-schema): anything else is discarded on hydrate, and while
+    // present it makes Studio Web "trust the .flow" when the sidecar folder is
+    // missing (`flowNodeHasRealInputs`), flushing a prompt-less agent.json.
+    // `modelMaxTokens` is written nowhere: the designer derives it from the
+    // selected model.
+    const inputs = {
+        source,
+        // The two DESCRIPTOR ARRAYS. `agentInputVariables` entries carry the binding
+        // expression; `agentOutputVariables` entries are name + type only, and the
+        // runtime's structured final call fills exactly these keys.
+        //
+        // `id` is the FLAT NAME, not the author's — the name the runtime's
+        // JobArguments are keyed by, and the key the CLI reconciles against the
+        // sidecar's `inputSchema`. One entry per flatName, so two logical names bound
+        // to the same reference claim one argument rather than two.
+        agentInputVariables: plan.refs.map((r) => ({ id: r.flatName, type: 'string', binding: r.binding })),
+        agentOutputVariables: Object.entries(returns).map(([k, t]) => ({ id: k, type: t })),
+    };
+    // The other half of the artifact: the agent's own configuration, which the
+    // platform resolves at `<source>/agent.json`, written by compile-cli beside
+    // the `.flow`. The AGENT's dialect: `{{input.x}}` placeholders, rewritten from
+    // the author's logical names to the FLAT NAMES the runtime's JobArguments are
+    // keyed by (board G-20).
+    const agentJson = inlineAgentJson({
+        model: s.model,
+        systemPrompt: s.systemPrompt,
+        userPrompt: s.userPrompt,
+        plan,
+        returns,
+        temperature: s.temperature,
+        maxTokenPerResponse: s.maxTokenPerResponse,
+        maxIterations: s.maxIterations,
+        mode: s.mode,
+        guardrails: s.guardrails,
+        source,
+        name: step,
+    });
+    ctx.sidecar({ path: `${source}/agent.json`, json: agentJson });
+    // The schema's property TYPES need this scope's finished variables, which do
+    // not exist yet: the `properties` object is filled in place when the scope
+    // closes.
+    ctx.typeAgentInputs(agentJson.inputSchema, plan.refs);
+    const attach = [];
+    // GROUNDING — one resource node per context index, joined to the agent's own
+    // `context` handle. An ARTIFACT, not a step: it takes no incoming control
+    // flow, produces no output, and never reaches the End node. The edge runs OUT
+    // of the agent (source port `context`) INTO the resource's `input` port, which
+    // is the direction both definitions declare.
+    const contexts = s.context === undefined ? [] : Array.isArray(s.context) ? s.context : [s.context];
+    for (const cx of contexts) {
+        // `check`'s AGENT_CONTEXT_NO_ID, again for `--no-check`: a blank id builds
+        // the type `…context.index.<slug>.`, which no tenant serves, and nothing
+        // after this point would say so.
+        if (typeof cx?.id !== 'string' || !GUID_RE.test(cx.id)) {
+            throw Object.assign(new Error(`inline agent "${step}": context index "${cx?.name ?? ''}" needs its index id (a GUID) as \`id\`; `
+                + `got ${JSON.stringify(cx?.id)}. \`uip solution resources list --kind Index --source remote --search "<name>"\` returns it as \`Key\`.`), { code: 'AGENT_CONTEXT_NO_ID' });
+        }
+        const cdef = contextIndexDef({ name: cx.name, id: cx.id });
+        // `<step>Context`, deduped for a second index on the same agent, unless the
+        // author placed it (`nodeId`, which decompile writes for a node the canvas
+        // named). Not slugged from the index NAME: an id is the author's handle on
+        // the node and a 40-character one helps nobody.
+        const cid = ctx.resourceNodeId(cx.nodeId, `${step}Context`, `inline agent "${step}": context index "${cx.name}"`);
+        // ONE identity, spent twice: the node's `inputs.source` and the sidecar
+        // resource's `id` are the same uuid, because that is what joins them. The
+        // platform validator says so in its own refusal text — *"the resource id
+        // from the parent inline agent's `resources[]`"*.
+        const contextResourceId = cx.source ?? derivedContextSource(ctx.flowId, step, cx.id);
+        const contextQuery = renderContextQuery(cx.query, render);
+        // The index's own configuration; the platform's `inputDefaults` are the
+        // shape a designer-placed node has, so an omitted option emits the
+        // designer's value rather than nothing.
+        attach.push({
+            id: cid, definition: cdef, label: cx.label ?? cx.name, port: 'context',
+            inputs: {
+                // REQUIRED, and the platform's validator is what says so — measured
+                // 2026-07-31, omitting it: *"Node type
+                // uipath.agent.resource.context.index.… requires a stable UUID at
+                // inputs.source … Set \"inputs\": { \"source\": \"<uuid>\" } on the
+                // node"* (MST-9265). It is the resource's own identity inside the
+                // project, so it is derived from flow + step + index rather than random,
+                // exactly like the agent's `source`: a recompile must not be a diff. An
+                // author's `source` (a canvas directory decompile carried) wins.
+                source: contextResourceId,
+                indexId: cx.id,
+                indexName: cx.name,
+                ...(cx.folderKey === undefined ? {} : { folderKey: cx.folderKey }),
+                ...(cx.folderPath === undefined ? {} : { folderPath: cx.folderPath }),
+                retrievalMode: cx.retrievalMode ?? 'semantic',
+                // The platform's `query` is a MODE-TAGGED object, not a bare string:
+                // `{mode, textValue, promptValue, argumentPath}`, with the mode saying
+                // which field is live. A plain string is the `prompt` mode; a flow
+                // expression is `text-builder`, whose `textValue` the runtime templates.
+                query: contextQuery,
+                threshold: cx.threshold ?? 0,
+                resultCount: cx.resultCount ?? 3,
+                fileExtension: cx.fileExtension ?? 'All',
+                folderPathPrefix: { mode: 'text-builder', textValue: '', promptValue: '', argumentPath: '' },
+                citations: 'enabled',
+                outputColumns: [],
+                webSearchGrounding: { value: 'enabled' },
+            },
+        });
+        // The other half — without it the node is inert: see `contextResourceJson`.
+        ctx.sidecar({
+            path: `${source}/resources/${contextResourceId}/resource.json`,
+            json: contextResourceJson(cx, { id: contextResourceId, query: contextQuery }),
+        }, cx.source !== undefined);
+    }
+    // TOOLS — one resource node per tool, joined to the agent's `tool` handle; the
+    // same artifact shape as context (no incoming control flow, no output, never
+    // reaches End — a graph walk drops it).
+    //
+    // Every tool node carries `inputs.source` — the platform's validator requires
+    // "a stable UUID at inputs.source … the resource id from the parent inline
+    // agent's resources[] for agent-tool resource nodes" (MST-9265's own wording)
+    // — derived, so a recompile is not a diff.
+    const toolRefs = s.tools === undefined ? [] : Array.isArray(s.tools) ? s.tools : [s.tools];
+    for (const tr of toolRefs) {
+        let tdef;
+        let label;
+        let extraInputs = {};
+        let connectorTool;
+        if (tr.kind === 'builtin') {
+            const bdef = ownEntry(BUILTIN_TOOL_DEFS, tr.tool);
+            tdef = bdef === undefined ? undefined : jsonClone(bdef);
+            if (!tdef)
+                throw new Error(`inline agent "${step}": unknown builtin tool "${tr.tool}" (analyzefiles | summarize | batchtransform).`);
+            label = tdef.display.label;
+            // The designer-placed node carries the def's `inputDefaults` with the
+            // author's values over them — the context rule, kept per builtin (each def
+            // declares different fields, so overrides apply only where the def has the
+            // field).
+            extraInputs = jsonClone(tdef.inputDefaults);
+            // summarize/batchtransform declare `source` among their defaults (as an
+            // empty string); the derived uuid below must win, not be clobbered.
+            delete extraInputs.source;
+            if (tr.description !== undefined)
+                extraInputs.description = tr.description;
+            if ('query' in extraInputs && tr.query !== undefined) {
+                extraInputs.query = renderContextQuery(tr.query, render);
+            }
+            if ('fileExtension' in extraInputs && tr.fileExtension !== undefined) {
+                extraInputs.fileExtension = { value: tr.fileExtension };
+            }
+            if ('citationMode' in extraInputs && tr.citationMode !== undefined) {
+                extraInputs.citationMode = { value: tr.citationMode };
+            }
+        }
+        else if (tr.kind === 'ixp') {
+            tdef = ixpToolDef(tr);
+            label = tr.name;
+            // The node carries the def's own `inputDefaults` (name / description /
+            // project identity / attachment config) with the derived `source` over
+            // them — the builtin-tool rule, not the process-tool one, because this
+            // family's configuration lives on the NODE rather than in a binding: its
+            // def declares no `model` at all, so there is no resource identity to bind
+            // and nothing to add to `bindings[]`.
+            extraInputs = jsonClone(tdef.inputDefaults);
+        }
+        else if (tr.kind === 'connector') {
+            if (!ctx.library)
+                throw new Error(`inline agent "${step}"'s connector tool needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+            const rc = ctx.library.resolve(tr.connector, tr.operation, tr.version, tr.object);
+            // An entry `prepare` synthesized from Integration Service compiles in BPMN
+            // only — for a tool as for a step: `connectorToolDef` reads the same
+            // definition, and a synthesized one has no form or handles.
+            const noDefinition = synthesizedDefinitionRefusal(rc);
+            if (noDefinition)
+                throw noDefinition;
+            tdef = connectorToolDef(rc);
+            label = tr.name ?? rc.v1def?.display?.label ?? tr.operation;
+            // The connection rides the same three places it does for a `connector()`
+            // step, because the platform reads it from the same three (#867):
+            //  * the node's `inputs.detail` — what `uip maestro flow node configure`
+            //    writes on a `tool.connector.*` node, what `uip agent refresh
+            //    --inline-in-flow` builds the tool's resource.json FROM, and what its
+            //    shell-ify pass keeps ("where a connector tool's request config
+            //    lives"). It is also what `bindings_v2.json` is derived from.
+            //  * the top-level `bindings[]` pair the def's `model.context` placeholders
+            //    (`<bindings.… connection>` / `<bindings.FolderKey>`) name.
+            //  * the agent's `resources/<id>/resource.json` (below).
+            // Emitting none of them left the tool with no connection anywhere.
+            const where = `inline agent "${step}"'s connector tool "${tr.connector}/${tr.operation}"`;
+            const target = { key: tr.connector, action: tr.operation };
+            const conn = ctx.resolveBinding(tr.connection, 'connection', where, target);
+            const folder = ctx.resolveBinding(tr.folder, 'folder', where, target);
+            ctx.bindConnection({
+                model: rc.v1def?.model, connectorKey: rc.connectorKey, connectionId: conn,
+                ...(folder !== undefined ? { folderKey: folder } : {}),
+            });
+            const detail = connectorToolDetail(rc, conn, folder, `${step}Tool`);
+            extraInputs = { detail };
+            connectorTool = {
+                rc, detail, name: label,
+                description: tr.description ?? connectorToolDescription(rc),
+                iconUrl: String(tdef.display?.icon ?? ''),
+            };
+        }
+        else if (tr.kind === 'mcp') {
+            // Per-instance def minted like the ixp family's; the node carries the def's
+            // own defaults (server identity + tool selection) — the configuration lives
+            // on the node, not in a binding.
+            tdef = mcpToolDef(tr);
+            label = tr.name;
+            extraInputs = jsonClone(tdef.inputDefaults);
+        }
+        else if (tr.kind === 'a2a') {
+            tdef = a2aToolDef(tr);
+            label = tr.name;
+            extraInputs = jsonClone(tdef.inputDefaults);
+        }
+        else if (tr.kind === 'clientside') {
+            // A static bundled def: the flow declares only the CONTRACT — the calling
+            // application owns the implementation.
+            tdef = jsonClone(ctx.definition('uipath.agent.resource.tool.clientside', '1.0'));
+            label = tr.name;
+            extraInputs = {
+                ...jsonClone(tdef.inputDefaults),
+                name: tr.name,
+                ...(tr.description !== undefined ? { description: tr.description } : {}),
+                ...(tr.inputs !== undefined ? { inputSchema: fieldSchema(tr.inputs) } : {}),
+                ...(tr.returns !== undefined ? { outputSchema: fieldSchema(tr.returns) } : {}),
+            };
+        }
+        else if (tr.kind === 'httpRequest') {
+            // Each field is a mode triple: a FIXED author value rides as text-builder
+            // (headers/params as name/value rows, timeout numeric — the storage
+            // layer's own normalization), an omitted one keeps the definition's
+            // prompt-mode default so the MODEL fills it at call time.
+            tdef = jsonClone(ctx.definition('uipath.agent.resource.tool.builtin.httprequest', '1.0'));
+            label = tr.name ?? tdef.display.label;
+            extraInputs = jsonClone(tdef.inputDefaults);
+            const fix = (field, value) => {
+                const row = extraInputs[field];
+                extraInputs[field] = { ...row, mode: 'text-builder', textValue: value };
+            };
+            if (tr.url !== undefined)
+                fix('url', tr.url);
+            if (tr.method !== undefined)
+                fix('method', tr.method);
+            if (tr.headers !== undefined)
+                fix('headers', tr.headers);
+            if (tr.params !== undefined)
+                fix('params', tr.params);
+            if (tr.body !== undefined)
+                fix('body', tr.body);
+            if (tr.timeout !== undefined)
+                fix('timeout', tr.timeout);
+            // Always set, falling back to the definition's own text: the resource file
+            // hands this to the MODEL as the tool's description, and the node must
+            // carry the same one (#935).
+            extraInputs.description = tr.description ?? String(tdef.description ?? '');
+        }
+        else {
+            const meta = ownEntry(PROCESS_TOOL_META, tr.kind);
+            if (!meta)
+                throw new Error(`inline agent "${step}": unknown tool kind "${tr.kind}".`);
+            tdef = processToolDef(tr.kind, tr);
+            label = tr.name;
+            // The definition's `model.context` names `<bindings.name>` /
+            // `<bindings.folderPath>` — the same pair every published-resource STEP
+            // references — so the entries must exist at the top level (v1's current
+            // authoring doc says so for process tools; a def whose bindings resolve to
+            // nothing is a dangling reference).
+            const { entries } = processResourceBindings({ name: tr.name, folderPath: tr.folderPath, resourceSubType: meta.subType }, ctx.bindings);
+            for (const b of entries)
+                ctx.bind(b);
+            // The NODE stays minimal — `source` only. Both witnesses agree: the
+            // deployed corpus carries `inputs: {}` on every per-instance tool, and
+            // v1's current authoring doc says "inputs.source only, no instance model".
+            // The contract (inputSchema/outputSchema) lives on the DEFINITION's
+            // inputDefaults, where the registry's tenant-synthesized copy puts it —
+            // emitting it on the node too would set inputs the def's own schema does
+            // not declare (our own output would be flagged).
+        }
+        const tid = ctx.resourceNodeId(tr.nodeId, `${step}Tool`, `inline agent "${step}": ${tr.kind} tool "${label}"`);
+        const toolResourceId = tr.source ?? derivedToolSource(ctx.flowId, step, tr);
+        const toolInputs = { source: toolResourceId, ...extraInputs };
+        attach.push({
+            id: tid, definition: tdef, label, port: 'tool', inputs: toolInputs,
+            // `uip agent refresh` reads the tool's description off the node's display
+            // first, so the node carries the one the resource.json does.
+            ...(connectorTool ? { display: { description: connectorTool.description } } : {}),
+        });
+        // The other half, for the kinds whose file is DERIVABLE — see
+        // `toolResourceJson` for which are not, and why each is left to the designer
+        // rather than guessed.
+        const toolResource = connectorTool
+            ? connectorToolResourceJson(connectorTool, toolResourceId)
+            : tr.kind === 'builtin'
+                ? builtinToolResourceJson(tr.tool, label, toolInputs, { id: toolResourceId })
+                : tr.kind === 'httpRequest'
+                    ? httpRequestToolResourceJson(label, toolInputs, { id: toolResourceId, canvasNodeId: tid })
+                    : toolResourceJson(tr, { id: toolResourceId });
+        if (toolResource !== undefined) {
+            ctx.sidecar({ path: `${source}/resources/${toolResourceId}/resource.json`, json: toolResource }, tr.source !== undefined);
+        }
+    }
+    // ESCALATION — the agent's TOP handle; an Action Center app task a human
+    // completes. The node's inputs are the platform's `inputDefaults` shape with
+    // the author's values — the exact shape the deployed corpus carries.
+    const escalations = s.escalation === undefined ? [] : Array.isArray(s.escalation) ? s.escalation : [s.escalation];
+    for (const esc of escalations) {
+        const where = `inline agent "${step}": escalation "${esc.name}"`;
+        const channelId = fnv1aX4Uuid(`${ctx.flowId}/${step}/escalation/${esc.name}/channel`);
+        if (esc.variant === 'quick-form') {
+            // The INLINE-form escalation: the same schema rows a human task's quick
+            // form carries, on the bundled `.quick-form` definition (the tenant
+            // registry does not serve the family).
+            const qdef = jsonClone(ctx.definition('uipath.agent.resource.escalation.quick-form', '1.2'));
+            const qid = ctx.resourceNodeId(esc.nodeId, `${step}Escalation`, where);
+            const rows = (esc.fields ?? []).map((f) => {
+                const required = f.direction === 'input' ? undefined : f.required;
+                return {
+                    id: f.id,
+                    label: f.label ?? f.id,
+                    type: wireFormFieldType(f.type),
+                    direction: f.direction,
+                    ...(typeof required === 'boolean' ? { required } : {}),
+                    // The field's settings (`controlType`, a picker's `options`,
+                    // `defaultValue`, `colSpan`, …), as the human task's rows carry them
+                    // (#1235, #1250).
+                    ...formFieldSettingsWire(f),
+                };
+            });
+            const qsource = esc.source ?? derivedEscalationSource(ctx.flowId, step, esc.name);
+            const schema = {
+                // The runtime refuses a quick form without one (`AGENT_STARTUP.
+                // INVALID_TOOL_CONFIG`: "has a quick form schema without a schemaId",
+                // measured 2026-10-05) — the same stable id a human task's form carries.
+                schemaId: schemaId(ctx.flowId, qid),
+                fields: rows,
+                outcomes: (esc.outcomes ?? []).map((o, i) => ({
+                    id: outcomeSlug(o, i), name: o, type: 'string', isPrimary: i === 0, action: 'Continue',
+                })),
+            };
+            attach.push({
+                id: qid, definition: qdef, label: esc.name, port: 'escalation',
+                inputs: {
+                    source: qsource,
+                    name: esc.name,
+                    description: esc.description ?? '',
+                    type: 'quick-form',
+                    schema,
+                    recipients: (esc.recipients ?? []).map((v) => ({ type: 3, value: v })),
+                    outcomeMapping: esc.outcomes && esc.outcomes.length
+                        ? Object.fromEntries(esc.outcomes.map((o) => [o, 'continue']))
+                        : null,
+                    _additionalProps: {
+                        taskTitle: esc.taskTitle ?? '',
+                        priority: esc.priority ?? 'medium',
+                        labels: esc.labels ?? [],
+                    },
+                    _notifications: false,
+                },
+            });
+            // The other half — without it the escalation is inert: see
+            // `escalationResourceJson`.
+            ctx.sidecar({
+                path: `${source}/resources/${qsource}/resource.json`,
+                json: escalationResourceJson(esc, { id: qsource, channelId, quickFormSchema: schema }),
+            }, esc.source !== undefined);
+            continue;
+        }
+        const app = esc.app;
+        const edef = escalationDef();
+        const eid = ctx.resourceNodeId(esc.nodeId, `${step}Escalation`, where);
+        const esource = esc.source ?? derivedEscalationSource(ctx.flowId, step, esc.name);
+        attach.push({
+            id: eid, definition: edef, label: esc.name, port: 'escalation',
+            inputs: {
+                source: esource,
+                name: esc.name,
+                description: esc.description ?? '',
+                type: 'app-task',
+                app: {
+                    key: app.key,
+                    name: app.name,
+                    appName: app.name,
+                    displayName: app.name,
+                    folderPath: escalationAppFolder(app),
+                    inputSchema: fieldSchema(app.inputs),
+                    outputSchema: fieldSchema(app.outputs),
+                },
+                // `{type: 3, value: <email>}` is the deployed corpus's recipient shape
+                // (type 3 = email address).
+                recipients: (esc.recipients ?? []).map((v) => ({ type: 3, value: v })),
+                // Every deployed outcome maps to 'continue' — the agent resumes with the
+                // reviewer's answer whichever outcome they pick.
+                outcomeMapping: esc.outcomes && esc.outcomes.length
+                    ? Object.fromEntries(esc.outcomes.map((o) => [o, 'continue']))
+                    : null,
+                _additionalProps: {
+                    taskTitle: esc.taskTitle ?? '',
+                    priority: esc.priority ?? 'medium',
+                    labels: esc.labels ?? [],
+                },
+                _notifications: false,
+                _appInputs: null,
+            },
+        });
+        ctx.sidecar({
+            path: `${source}/resources/${esource}/resource.json`,
+            json: escalationResourceJson(esc, { id: esource, channelId }),
+        }, esc.source !== undefined);
+    }
+    // MEMORY — one episodic-memory resource on the agent's `memory` handle (the
+    // 1.4 definition selected above). Same artifact shape as context.
+    if (s.memory !== undefined) {
+        const m = s.memory;
+        attach.push({
+            id: ctx.resourceNodeId(undefined, `${step}Memory`, `inline agent "${step}": memory "${m.name}"`),
+            definition: memoryResourceDef(m), label: m.name, port: 'memory',
+            inputs: {
+                source: fnv1aX4Uuid(`${ctx.flowId}/${step}/memory/${m.id}`),
+                name: m.name,
+                description: m.description ?? '',
+                dynamicFewShotLearning: m.dynamicFewShotLearning ?? true,
+                semanticSimilarity: m.semanticSimilarity ?? 0,
+                kValue: m.kValue ?? 3,
+                searchMode: m.searchMode ?? 'hybrid',
+            },
+        });
+        // No `features/<id>/feature.json` until `check` stops refusing memory
+        // (AGENT_MEMORY_NOT_AUTHORABLE); its shape maps cleanly off `AgentMemoryRef`
+        // but cannot be exercised while the handle does not exist.
+    }
+    return {
+        definition: { source: 'snapshot', nodeType: def.nodeType, version: def.version, manifest: def },
+        // Unlike the published families the inline agent KEEPS no node-level model:
+        // 29 of 29 deployed instances carry none (the def's `model.source: true` is
+        // what tells the serializer the node has a `source` input).
+        model: 'omit',
+        // The forward handle is `success`, not `output` — the definition declares
+        // `success` (with `isDefaultForType`) + `error` on the right, and 29 of 29
+        // deployed instances wire the outgoing edge to `success`. Named, because the
+        // definition's first handles are the artifact handles a resource attaches to.
+        port: 'success',
+        inputs,
+        ...(outputs !== undefined ? { outputs, replaceOutputs: true } : {}),
+        attach,
+    };
+}

package/dist/nodes/agent/flow/node-type.d.ts

@@ -0,0 +1,20 @@
+import type { FlowNodeType, FlowVersionedNodeType } from '../../../flow-node-type.js';
+import type { ConversationalAgentInputs, CreateOutgoingCallInputs, EndCallInputs, InlineAgentInputs, VoiceAgentInputs } from './spec.js';
+type AgentSpec = {
+    kind: 'createOutgoingCall';
+    inputs: CreateOutgoingCallInputs;
+} | {
+    kind: 'endCall';
+    inputs: EndCallInputs;
+} | {
+    kind: 'voiceAgent';
+    inputs: VoiceAgentInputs;
+} | {
+    kind: 'conversationalAgent';
+    inputs: ConversationalAgentInputs;
+} | {
+    kind: 'inlineAgent';
+    inputs: InlineAgentInputs;
+};
+export declare const agentNodeTypes: (FlowNodeType<AgentSpec> | FlowVersionedNodeType<AgentSpec>)[];
+export {};