@uipath/maestro-builder-sdk 6.42.0 → 6.44.0

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

@@ -0,0 +1,572 @@
+/**
+ * The inline agent's lift and printer: the agent node, its `<source>/agent.json`
+ * and the resource nodes on its artifact handles, read back as one
+ * `inlineAgent({ … context, tools, escalation, memory })` call. Moved from
+ * decompile.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the printed
+ * source, warnings and `--strict` refusals are unchanged.
+ *
+ * Every value the lift recovers from a resource is literal data — a name, an
+ * id, a setting, a form row; an expression query is printed as the text compile
+ * reads it from — so the lift writes each resource's options as source once,
+ * through the core literal writers, while the warnings and refusals that
+ * reading them raises still go through the context. The agent's own inputs are
+ * the only expressions, kept as `Expr`s for the printer.
+ */
+import { agentSidecarInputs } from '../../../core/agent-sidecar.js';
+import { derivedContextSource, derivedEscalationSource, derivedResourceNodeId, derivedToolSource, } from '../../../core/agent-resource-identity.js';
+import { CONTEXT_INDEX_DEFAULTS, CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, contextIndexSlug, parseContextIndexType, } from '../../../core/context-index.js';
+import { Expr } from '../../../core/expr.js';
+import { formFieldRowLoss, formFieldRowLossMessage, formFieldSettingsSource, liftFormFieldSettings, sourceFormFieldType, } from '../../../core/form-field-type.js';
+import { ownEntry } from '../../../core/own-entry.js';
+import { tsKey as key, tsLiteral, tsNumber, tsObject as objLit, tsOptions as opts, tsText } from '../../../core/ts-literal.js';
+import { wireExprBody } from '../../../core/wire-expr.js';
+/** Where the agent's own `inputs` go in the option list: the printer writes them, as expressions. */
+const INPUT_ROWS = Symbol('inputs');
+/** Plain JSON data as source, in the `{ k: v }` / `[a, b]` spelling (a form field's `options`, `rules`, `defaultValue`). */
+function dataSource(v) {
+    if (Array.isArray(v))
+        return `[${v.map(dataSource).join(', ')}]`;
+    if (v !== null && typeof v === 'object') {
+        const parts = Object.entries(v).filter(([, x]) => x !== undefined).map(([k, x]) => `${key(k)}: ${dataSource(x)}`);
+        return parts.length ? `{ ${parts.join(', ')} }` : '{}';
+    }
+    return tsLiteral(v);
+}
+/**
+ * Where a context-index resource node keeps its identity, read in the order
+ * that holds for every writer.
+ *
+ * SDK compile writes `indexId` / `indexName` / `folderPath` onto the node. The
+ * canvas and the CLI do not: their node carries only `inputs.source`, and the
+ * identity lives in two other places.
+ *
+ *  - The node TYPE, `…context.index.<slug>.<uuid>`: the uuid is the index id
+ *    (the `ContextIndexRef.id` JSDoc says to read it there).
+ *  - The resource sidecar `<agent source>/resources/<inputs.source>/resource.json`,
+ *    whose `name` is the index's real name (the one the slug is made from) and
+ *    whose `folderPath` is its folder. `display.label` is only what the canvas
+ *    shows, and a canvas rename changes it.
+ *
+ * So the id comes from the type (then `inputs.indexId`). The name is the first
+ * of `inputs.indexName`, sidecar `name`, sidecar `indexName`, label that slugs to
+ * the type's slug, else the first one present in that order. Compile derives
+ * the type from `slug(name)` + id, so when the chosen name does not slug back to
+ * the type's slug the recompiled node gets a different type, and that is warned.
+ */
+function contextIndexIdentity(agent, c, rPlain, ctx) {
+    const fromType = parseContextIndexType(c.type);
+    const sidecar = contextResourceSidecar(agent, c, ctx);
+    const sidecarText = (k) => typeof sidecar?.[k] === 'string' && sidecar[k] !== '' ? sidecar[k] : undefined;
+    const label = typeof c.display?.label === 'string' && c.display.label !== '' ? c.display.label : undefined;
+    // The canvas can set both sidecar `name` and `indexName`, and they can differ.
+    // The one that slugs to the type's slug is the one the type was built from, so
+    // it wins; the fixed order is the fallback when none matches.
+    const candidates = [rPlain(c, 'indexName'), sidecarText('name'), sidecarText('indexName'), label]
+        .filter((n) => n !== undefined);
+    const name = (fromType?.slug ? candidates.find((n) => contextIndexSlug(n) === fromType.slug) : undefined)
+        ?? candidates[0] ?? '';
+    const id = (fromType?.id || undefined) ?? rPlain(c, 'indexId') ?? '';
+    if (fromType !== undefined && fromType.slug !== '' && contextIndexSlug(name) !== fromType.slug) {
+        ctx.warn(`context index "${c.id}" on agent "${agent.id}": its node type names the index "${fromType.slug}", `
+            + `but the name decompile recovered, ${JSON.stringify(name)}, slugs to "${contextIndexSlug(name)}", so compile `
+            + `will write a different node type. Set \`name\` to the index's real name`
+            + (sidecar === undefined ? ', or keep the resources/ folder beside the .flow so decompile can read it.' : '.'));
+    }
+    return { name, id, folderPath: rPlain(c, 'folderPath') ?? sidecarText('folderPath'), sidecar };
+}
+/** The retrieval modes `ContextIndexRef.retrievalMode` can hold. */
+const CONTEXT_RETRIEVAL_MODES = new Set(['semantic', 'structured', 'deeprag', 'batchtransform']);
+/** The `settings` keys of a context `resource.json` that {@link contextIndexSettings} reads or checks. */
+const CONTEXT_SETTINGS_KEYS = new Set([
+    'retrievalMode', 'query', 'folderPathPrefix', 'threshold', 'resultCount', 'fileExtension',
+    'citationMode', 'webSearchGrounding', 'outputColumns',
+]);
+/**
+ * A context index's retrieval settings, as the `context: [...]` entry's option
+ * rows (`retrievalMode`, `query`, `threshold`, `resultCount`, `fileExtension`),
+ * each left out when it is what compile writes anyway.
+ *
+ * The inverse of `contextResourceJson` (serialize.ts). Read from the sidecar's
+ * `settings` first: a node the canvas or the CLI placed keeps its inputs minimal
+ * (`inputs.source`), so `resource.json` is the only copy, and it is what the
+ * runtime reads. The node's own inputs (the SDK writes both) answer when there
+ * is no sidecar. Before #1183 neither was read, so a no-edit round trip reset
+ * every setting to the SDK default without a word.
+ *
+ * The query is variant-tagged in the sidecar and mode-tagged on the node:
+ *
+ *  - `dynamic` / `prompt` → a plain string (the guidance the model reads);
+ *  - `static` / `text-builder` whose text is a `=js:` expression → that
+ *    expression, which compile writes back as `text-builder` / `static`;
+ *  - `static` with `''` is the canvas's spelling of "no query", as the SDK's
+ *    `dynamic` with `''` is: left out.
+ *
+ * A setting the SDK cannot express (a `static` query of plain text, an
+ * `argument` query, deeprag citations off, batchtransform web grounding off or
+ * output columns, a folder-path prefix, an unknown mode or key) is reported:
+ * a warning, or an error under `--strict`. Compile would write the SDK's
+ * value instead, so it is never dropped silently.
+ */
+function contextIndexSettings(agent, c, sidecar, ctx) {
+    const settings = sidecar?.settings && typeof sidecar.settings === 'object' && !Array.isArray(sidecar.settings)
+        ? sidecar.settings : undefined;
+    const ni = (c.inputs ?? {});
+    const where = `context index "${c.id}" on agent "${agent.id}"`;
+    const lossy = (what) => {
+        const message = `${where}: ${what}, which \`context: [...]\` cannot express, so compile writes the SDK's `
+            + `value instead. Edit that setting in the canvas after merging, or keep the original resource.json.`;
+        ctx.lossy(message);
+    };
+    const textOf = (v) => (typeof v === 'string' ? v : undefined);
+    const numOf = (v) => {
+        const raw = ctx.plainValue(v);
+        return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+    };
+    const valueOf = (v) => (v && typeof v === 'object' ? v.value : undefined);
+    // Retrieval mode.
+    const rawMode = textOf(settings?.retrievalMode) ?? textOf(ctx.sourceText(ni.retrievalMode));
+    let mode = CONTEXT_INDEX_DEFAULTS.retrievalMode;
+    if (rawMode !== undefined && rawMode !== '') {
+        if (CONTEXT_RETRIEVAL_MODES.has(rawMode))
+            mode = rawMode;
+        else
+            lossy(`its retrieval mode is ${JSON.stringify(rawMode)}`);
+    }
+    const sidecarQuery = (() => {
+        const q = settings?.query;
+        if (!q || typeof q !== 'object')
+            return undefined;
+        if (q.variant === 'dynamic')
+            return { kind: 'prompt', text: textOf(q.description) ?? '' };
+        if (q.variant === 'static')
+            return { kind: 'text', text: textOf(q.value) ?? '' };
+        if (q.variant === 'argument')
+            return { kind: 'argument', text: textOf(q.value) ?? '' };
+        lossy(`its query has variant ${JSON.stringify(q.variant)}`);
+        return undefined;
+    })();
+    const nodeQuery = (() => {
+        const q = ni.query;
+        if (typeof q === 'string')
+            return q === '' ? undefined : { kind: q.startsWith('=js:') ? 'text' : 'prompt', text: q };
+        if (!q || typeof q !== 'object')
+            return undefined;
+        const t = q;
+        if (t.mode === 'text-builder')
+            return { kind: 'text', text: textOf(t.textValue) ?? '' };
+        if (t.mode === 'variable')
+            return { kind: 'argument', text: textOf(t.argumentPath) ?? '' };
+        return { kind: 'prompt', text: textOf(t.promptValue) ?? '' };
+    })();
+    const query = sidecarQuery ?? nodeQuery;
+    let querySrc;
+    if (query?.kind === 'prompt' && query.text !== '')
+        querySrc = tsLiteral(query.text);
+    else if (query?.kind === 'text' && query.text.startsWith('=js:'))
+        querySrc = tsLiteral(query.text);
+    else if (query?.kind === 'text' && query.text !== '')
+        lossy(`its query is static text (${JSON.stringify(query.text)})`);
+    else if (query?.kind === 'argument')
+        lossy(`its query is the agent argument ${JSON.stringify(query.text)}`);
+    // Numbers and the file extension.
+    const threshold = numOf(settings?.threshold) ?? numOf(ni.threshold);
+    const resultCount = numOf(settings?.resultCount) ?? numOf(ni.resultCount);
+    const fileExtension = textOf(valueOf(settings?.fileExtension)) ?? textOf(ctx.sourceText(ni.fileExtension));
+    // The node's flat `All` is the platform's node default for every mode; only
+    // the resource's per-mode default is what compile would write anyway.
+    const defaultExtension = ownEntry(CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, mode) ?? 'All';
+    const extensionSrc = fileExtension === undefined || fileExtension === '' || fileExtension === defaultExtension
+        || (settings?.fileExtension === undefined && fileExtension === 'All')
+        ? undefined : tsLiteral(fileExtension);
+    // What compile writes as constants; anything else has no field.
+    if (mode === 'deeprag') {
+        const citation = textOf(valueOf(settings?.citationMode)) ?? textOf(ctx.sourceText(ni.citations));
+        if (citation !== undefined && !['Inline', 'enabled'].includes(citation))
+            lossy(`its citation mode is ${JSON.stringify(citation)}`);
+    }
+    if (mode === 'batchtransform') {
+        const grounding = textOf(valueOf(settings?.webSearchGrounding)) ?? textOf(valueOf(ni.webSearchGrounding));
+        if (grounding !== undefined && !['Enabled', 'enabled'].includes(grounding))
+            lossy(`its web search grounding is ${JSON.stringify(grounding)}`);
+        const columns = settings?.outputColumns ?? ni.outputColumns;
+        if (Array.isArray(columns) && columns.length > 0)
+            lossy(`it has ${columns.length} output column(s)`);
+    }
+    // The folder-path prefix: variant-tagged in the sidecar, mode-tagged on the node.
+    const field = (v, k) => (v && typeof v === 'object' ? textOf(v[k]) : undefined);
+    const prefixText = settings?.folderPathPrefix !== undefined
+        ? field(settings.folderPathPrefix, 'value') ?? field(settings.folderPathPrefix, 'description') ?? ''
+        : field(ni.folderPathPrefix, 'textValue') ?? field(ni.folderPathPrefix, 'promptValue') ?? '';
+    if (prefixText !== '')
+        lossy(`its folder-path prefix is ${JSON.stringify(prefixText)}`);
+    for (const k of Object.keys(settings ?? {})) {
+        if (!CONTEXT_SETTINGS_KEYS.has(k))
+            lossy(`its resource.json settings carry ${JSON.stringify(k)}`);
+    }
+    return [
+        ['query', querySrc],
+        ['retrievalMode', mode !== CONTEXT_INDEX_DEFAULTS.retrievalMode ? tsLiteral(mode) : undefined],
+        ['threshold', threshold !== undefined && threshold !== CONTEXT_INDEX_DEFAULTS.threshold ? tsNumber(threshold) : undefined],
+        ['resultCount', resultCount !== undefined && resultCount !== CONTEXT_INDEX_DEFAULTS.resultCount ? tsNumber(resultCount) : undefined],
+        ['fileExtension', extensionSrc],
+    ];
+}
+/**
+ * A context resource's `resource.json` sidecar, parsed; `undefined` when it is
+ * not beside the `.flow`, or (with a warning) when it is not a JSON object.
+ */
+function contextResourceSidecar(agent, c, ctx) {
+    const agentSource = ctx.sourceText(agent.inputs?.source);
+    const resourceSource = ctx.sourceText(c.inputs?.source);
+    if (!agentSource || !resourceSource)
+        return undefined;
+    const path = `${agentSource}/resources/${resourceSource}/resource.json`;
+    const raw = ctx.sidecar(path);
+    if (raw === undefined)
+        return undefined;
+    try {
+        const json = JSON.parse(raw);
+        if (json && typeof json === 'object' && !Array.isArray(json))
+            return json;
+    }
+    catch {
+        // Reported below with the non-object case.
+    }
+    ctx.warn(`context index "${c.id}": ${path} is not valid JSON, so its name and folder decompile from the node.`);
+    return undefined;
+}
+/**
+ * An AGENT and its attached resources — the inline autonomous agent, the
+ * conversational agent, and the voice agent.
+ *
+ * The cluster is a node plus artifact nodes on its `tool` / `context` /
+ * `escalation` / `memory` handles, so this walks those edges and recovers each
+ * resource as an argument rather than as a step (see {@link ARTIFACT_PORTS}).
+ *
+ * **The author's input NAMES are not recoverable, and that is by design.** The
+ * platform does not send an agent the names you declared: it keys each argument
+ * by the reference PATH, `__`-joined (`$vars.prep.output` → `prep__output`), and
+ * only those flat names survive in the emitted file. Recovery therefore uses
+ * them for both the `inputs` keys and the `{{input.…}}` placeholders — the same
+ * arguments reach the model, spelled the platform's way. (Node ids are
+ * preserved exactly; only these logical names change.)
+ */
+export function liftInlineAgent(node, ctx) {
+    // A key on the node wins over the sidecar's copy of it.
+    const own = (node.inputs ?? {});
+    const i = {
+        ...agentSidecarInputs({
+            nodeId: node.id, inputs: own, source: ctx.sourceText(own.source), dialect: 'inline',
+            read: (path) => ctx.sidecar(path), warn: (m) => ctx.warn(m),
+        }),
+        ...own,
+    };
+    const plain = (v) => {
+        const raw = ctx.sourceText(v);
+        return raw === undefined || raw === '' ? undefined : raw;
+    };
+    const num = (v) => {
+        const raw = ctx.plainValue(v);
+        return typeof raw === 'number' ? String(raw) : undefined;
+    };
+    // Prompts. A sidecar prompt already speaks `{{input.<flatName>}}`, so this
+    // leaves it alone. An EMBEDDED node's prompt (Studio Web with the
+    // self-contained flag on, or an SDK before #927) carries each input as its
+    // rendered binding instead; the bindings in `agentInputVariables` are exactly
+    // what to put back — longest first, so a shorter binding cannot eat a longer
+    // one's prefix.
+    const vars = (Array.isArray(i.agentInputVariables) ? i.agentInputVariables : []);
+    const refs = vars
+        .filter((v) => typeof v.id === 'string' && typeof v.binding === 'string')
+        .map((v) => ({ flatName: v.id, binding: v.binding }))
+        .sort((a, b) => b.binding.length - a.binding.length);
+    const unrender = (text) => {
+        let out = text;
+        for (const r of refs)
+            out = out.split(r.binding).join(`{{input.${r.flatName}}}`);
+        return out;
+    };
+    const promptSrc = (v) => {
+        const raw = plain(v);
+        return raw === undefined ? undefined : tsLiteral(unrender(raw));
+    };
+    const inputRows = refs
+        // Emit in the file's own order, not the length-sorted one.
+        .slice()
+        .sort((a, b) => vars.findIndex((v) => v.id === a.flatName) - vars.findIndex((v) => v.id === b.flatName))
+        .map((r) => {
+        return [r.flatName, new Expr(wireExprBody(r.binding))];
+    });
+    const outVars = (Array.isArray(i.agentOutputVariables) ? i.agentOutputVariables : []);
+    const returns = outVars.length
+        ? objLit(outVars.map((v) => [String(v.id ?? ''), tsLiteral(String(v.type ?? 'string'))]))
+        : undefined;
+    // The resources, from the agent's own artifact edges. Each edge read here is
+    // carried by the agent spec (edge accounting, #1125); `limit` is for a port
+    // the spec carries only one resource on.
+    const resource = (port, limit = Infinity) => ctx.attached(port, limit);
+    // Record what compile will call each folded resource node. Serialize mints
+    // `uid(scope, \`${step.name}<Kind>\`)` per resource, in spec order, and the
+    // spec order is this edge order: the first is `<agent><Kind>`, the n-th
+    // `<agent><Kind><n>` (claimId's dedupe). Only the first memory is recovered,
+    // so every further memory maps to `undefined`.
+    //
+    // When a port's nodes do not ALL carry those ids (the canvas or the CLI named
+    // them), every resource on the port is written with its own `nodeId`, and
+    // compile keeps the file's ids. All of them, not only the odd one: compile
+    // numbers the derived ids in order, so a derived id after an explicit one
+    // would come out one lower than the file's.
+    // This reads the edges directly, not through `resource()`: it must see EVERY
+    // artifact edge, including ones the spec does not carry, and it must not
+    // account for any edge.
+    const keepIds = new Set();
+    for (const [port, kind, emittedCount] of [
+        ['context', 'Context', Infinity], ['tool', 'Tool', Infinity],
+        ['escalation', 'Escalation', Infinity], ['memory', 'Memory', 1],
+    ]) {
+        const targets = ctx.attachedIds(port);
+        const keep = port !== 'memory'
+            && targets.some((id, k) => id !== derivedResourceNodeId(node.id, kind, k));
+        targets.forEach((id, k) => {
+            if (keep)
+                keepIds.add(id);
+            ctx.absorb(id, keep ? id : k >= emittedCount ? undefined : derivedResourceNodeId(node.id, kind, k));
+        });
+    }
+    /**
+     * The `nodeId` / `source` entries for resource node `r`: each only when it
+     * differs from what compile derives (`derivedSource`), so a flow compile
+     * wrote decompiles without them.
+     */
+    const placement = (r, derivedSource) => {
+        const source = ctx.sourceText((r.inputs ?? {}).source);
+        return [
+            ['nodeId', keepIds.has(r.id) ? tsLiteral(r.id) : undefined],
+            ['source', source !== undefined && source !== '' && source !== derivedSource ? tsLiteral(source) : undefined],
+        ];
+    };
+    /** A tool's options plus its placement; `seed` is the ref compile derives the tool's directory from. */
+    const toolOpts = (t, seed, entries) => opts([...entries, ...placement(t, derivedToolSource(ctx.flowId, node.id, seed))]);
+    const rInputs = (n) => (n.inputs ?? {});
+    const rPlain = (n, k) => {
+        const raw = ctx.sourceText(rInputs(n)[k]);
+        return raw === undefined || raw === '' ? undefined : raw;
+    };
+    const toolSrc = resource('tool').map((t) => {
+        const ti = rInputs(t);
+        const type = t.type;
+        if (type === 'uipath.agent.resource.tool.clientside') {
+            const schemaTypes = (v) => {
+                const props = v?.properties;
+                if (!props || Object.keys(props).length === 0)
+                    return undefined;
+                return objLit(Object.entries(props).map(([k, x]) => [k, tsLiteral(String(x?.type ?? 'string'))]));
+            };
+            return toolOpts(t, { kind: 'clientside', name: rPlain(t, 'name') ?? '' }, [
+                ['kind', tsLiteral('clientside')],
+                ['name', tsLiteral(rPlain(t, 'name') ?? '')],
+                ['description', rPlain(t, 'description') !== undefined ? tsLiteral(rPlain(t, 'description')) : undefined],
+                ['inputs', schemaTypes(ti.inputSchema)],
+                ['returns', schemaTypes(ti.outputSchema)],
+            ]);
+        }
+        if (type === 'uipath.agent.resource.tool.builtin.httprequest') {
+            // A field is authored only when it left prompt mode (text-builder).
+            const fixed = (k) => {
+                const row = ti[k];
+                if (!row || row.mode !== 'text-builder')
+                    return undefined;
+                const v = row.textValue;
+                return typeof v === 'number' ? String(v) : typeof v === 'string' ? tsLiteral(v) : JSON.stringify(v);
+            };
+            // `name` is not recovered, so compile derives the directory from the default.
+            return toolOpts(t, { kind: 'httpRequest' }, [
+                ['kind', tsLiteral('httpRequest')],
+                ['url', fixed('url')], ['method', fixed('method')],
+                ['headers', fixed('headers')], ['params', fixed('params')],
+                ['body', fixed('body')], ['timeout', fixed('timeout')],
+            ]);
+        }
+        if (type.startsWith('uipath.agent.resource.tool.mcp.')) {
+            return toolOpts(t, { kind: 'mcp', name: '', key: rPlain(t, 'referenceKey') ?? '' }, [
+                ['kind', tsLiteral('mcp')],
+                ['name', tsLiteral(rPlain(t, 'name') ?? '')],
+                ['key', tsLiteral(rPlain(t, 'referenceKey') ?? '')],
+                // The mapper's field name for the canonical server slug.
+                ['slug', rPlain(t, 'serverUrl') !== undefined ? tsLiteral(rPlain(t, 'serverUrl')) : undefined],
+                ['folderPath', rPlain(t, 'folderPath') !== undefined ? tsLiteral(rPlain(t, 'folderPath')) : undefined],
+                ['mcpType', rPlain(t, 'mcpType') !== undefined ? tsLiteral(rPlain(t, 'mcpType')) : undefined],
+            ]);
+        }
+        if (type.startsWith('uipath.agent.resource.tool.a2a.')) {
+            return toolOpts(t, { kind: 'a2a', name: '', slug: '', key: rPlain(t, 'referenceKey') ?? '' }, [
+                ['kind', tsLiteral('a2a')],
+                ['name', tsLiteral(rPlain(t, 'name') ?? '')],
+                ['key', tsLiteral(rPlain(t, 'referenceKey') ?? '')],
+                ['slug', tsLiteral(rPlain(t, 'slug') ?? '')],
+                ['folderPath', rPlain(t, 'folderPath') !== undefined ? tsLiteral(rPlain(t, 'folderPath')) : undefined],
+            ]);
+        }
+        if (type.startsWith('uipath.agent.resource.tool.builtin.')) {
+            const tool = type.slice('uipath.agent.resource.tool.builtin.'.length);
+            return toolOpts(t, { kind: 'builtin', tool }, [
+                ['kind', tsLiteral('builtin')],
+                ['tool', tsLiteral(tool)],
+                ['description', rPlain(t, 'description') !== undefined ? tsLiteral(rPlain(t, 'description')) : undefined],
+            ]);
+        }
+        if (type.startsWith('uipath.agent.resource.tool.ixp.')) {
+            const tail = type.slice('uipath.agent.resource.tool.ixp.'.length);
+            const projectId = tail.slice(tail.indexOf('.') + 1);
+            return toolOpts(t, { kind: 'ixp', name: '', projectId }, [
+                ['kind', tsLiteral('ixp')],
+                ['projectId', tsLiteral(projectId)],
+                ['name', tsLiteral(rPlain(t, 'name') ?? '')],
+            ]);
+        }
+        // The per-instance resource kinds (process / api / flow / maestro / agent /
+        // function): the key is the node type's tail, the rest is a binding pair.
+        const PROCESS_NS = [
+            ['uipath.agent.resource.tool.processorchestration.', 'maestro'],
+            ['uipath.agent.resource.tool.process.', 'process'],
+            ['uipath.agent.resource.tool.function.', 'function'],
+            ['uipath.agent.resource.tool.api.', 'api'],
+            ['uipath.agent.resource.tool.flow.', 'flow'],
+            ['uipath.agent.resource.tool.agent.', 'agent'],
+        ];
+        const ns = PROCESS_NS.find(([prefix]) => type.startsWith(prefix));
+        if (ns) {
+            const def = ctx.definitionOf(t);
+            const values = (def?.model?.bindings?.values ?? []);
+            const bound = (n) => {
+                const row = values.find((v) => v.name === n);
+                return typeof row?.default === 'string' ? row.default : undefined;
+            };
+            const key = type.slice(ns[0].length);
+            return toolOpts(t, { kind: 'process', name: '', folderPath: '', key }, [
+                ['kind', tsLiteral(ns[1])],
+                ['key', tsLiteral(key)],
+                ['name', tsLiteral(bound('name') ?? rPlain(t, 'name') ?? '')],
+                ['folderPath', tsLiteral(bound('folderPath') ?? '')],
+            ]);
+        }
+        return opts([['kind', tsLiteral('builtin')], ['tool', tsLiteral('summarize')]]); // unreachable in practice
+    });
+    const contextSrc = resource('context').map((c) => {
+        const { name, id, folderPath, sidecar } = contextIndexIdentity(node, c, rPlain, ctx);
+        // Compile labels the node with `name`; a canvas rename is kept as `label`.
+        const label = typeof c.display?.label === 'string' && c.display.label !== '' && c.display.label !== name
+            ? c.display.label : undefined;
+        return opts([
+            ['name', tsLiteral(name)],
+            ['id', tsLiteral(id)],
+            ['folderPath', folderPath !== undefined ? tsLiteral(folderPath) : undefined],
+            ['folderKey', rPlain(c, 'folderKey') !== undefined ? tsLiteral(rPlain(c, 'folderKey')) : undefined],
+            // `query` and the retrieval settings, from resource.json or the node (#1183).
+            ...contextIndexSettings(node, c, sidecar, ctx),
+            ['label', label !== undefined ? tsLiteral(label) : undefined],
+            ...placement(c, derivedContextSource(ctx.flowId, node.id, id)),
+        ]);
+    });
+    const escalationSrc = resource('escalation').map((e) => {
+        const ei = rInputs(e);
+        const recipients = Array.isArray(ei.recipients)
+            ? ei.recipients.map((r) => tsText(r.value))
+            : [];
+        const outcomeNames = Object.keys((ei.outcomeMapping ?? {}));
+        const isQuickForm = e.type === 'uipath.agent.resource.escalation.quick-form';
+        const rows = isQuickForm
+            ? (ei.schema?.fields ?? [])
+            : [];
+        const app = ei.app;
+        const extra = (ei._additionalProps ?? {});
+        return opts([
+            ['variant', isQuickForm ? tsLiteral('quick-form') : undefined],
+            ['name', tsLiteral(rPlain(e, 'name') ?? '')],
+            ['description', rPlain(e, 'description') !== undefined ? tsLiteral(rPlain(e, 'description')) : undefined],
+            ['fields', rows.length ? `[${rows.map((f) => {
+                    const id = String(f.id ?? '');
+                    const direction = String(f.direction ?? 'output');
+                    // Every row key the source cannot carry is reported, never dropped
+                    // silently: a warning, an error under --strict (#1250).
+                    const loss = formFieldRowLoss(f, 'escalation');
+                    if (loss.length > 0) {
+                        const message = formFieldRowLossMessage(`quick-form escalation ${JSON.stringify(rPlain(e, 'name') ?? e.id)} on agent ${JSON.stringify(node.id)}`, id, loss);
+                        ctx.lossy(message);
+                    }
+                    return opts([
+                        ['id', tsText(f.id)],
+                        // serialize defaults a row's label to its id.
+                        ['label', typeof f.label === 'string' && f.label !== id ? tsLiteral(f.label) : undefined],
+                        ['type', tsLiteral(sourceFormFieldType(f.type ?? 'string'))],
+                        ['direction', tsLiteral(direction)],
+                        ['required', typeof f.required === 'boolean' && direction !== 'input' ? String(f.required) : undefined],
+                        ...formFieldSettingsSource(liftFormFieldSettings(f), dataSource),
+                    ]);
+                }).join(', ')}]` : undefined],
+            ['app', app === undefined ? undefined : opts([
+                    ['key', tsText(app.key)],
+                    ['name', tsText(app.name)],
+                    ['folderPath', typeof app.folderPath === 'string' && app.folderPath !== '' ? tsLiteral(app.folderPath) : undefined],
+                ])],
+            ['recipients', recipients.length ? `[${recipients.join(', ')}]` : undefined],
+            ['outcomes', outcomeNames.length ? `[${outcomeNames.map((o) => tsLiteral(o)).join(', ')}]` : undefined],
+            ['taskTitle', typeof extra.taskTitle === 'string' && extra.taskTitle !== '' ? tsLiteral(extra.taskTitle) : undefined],
+            // 'medium' is the platform default.
+            ['priority', typeof extra.priority === 'string' && extra.priority !== 'medium' ? tsLiteral(extra.priority) : undefined],
+            ...placement(e, derivedEscalationSource(ctx.flowId, node.id, rPlain(e, 'name') ?? '')),
+        ]);
+    });
+    const mem = resource('memory', 1)[0];
+    const memorySrc = mem === undefined ? undefined : (() => {
+        // The memory's id is the node type's tail; the def carries it too.
+        const tail = mem.type.slice('uipath.agent.resource.memory.'.length);
+        const id = tail.slice(tail.indexOf('.') + 1);
+        const mi = rInputs(mem);
+        return opts([
+            ['name', tsLiteral(rPlain(mem, 'name') ?? '')],
+            ['id', tsLiteral(id)],
+            ['description', rPlain(mem, 'description') !== undefined ? tsLiteral(rPlain(mem, 'description')) : undefined],
+            // The platform defaults: few-shot on, similarity 0, k 3, hybrid search.
+            ['dynamicFewShotLearning', ctx.plainValue(mi.dynamicFewShotLearning) === false ? 'false' : undefined],
+            ['semanticSimilarity', num(mi.semanticSimilarity) !== undefined && num(mi.semanticSimilarity) !== '0' ? num(mi.semanticSimilarity) : undefined],
+            ['kValue', num(mi.kValue) !== undefined && num(mi.kValue) !== '3' ? num(mi.kValue) : undefined],
+            ['searchMode', rPlain(mem, 'searchMode') !== undefined && rPlain(mem, 'searchMode') !== 'hybrid'
+                    ? tsLiteral(rPlain(mem, 'searchMode')) : undefined],
+        ]);
+    })();
+    const guardrails = Array.isArray(i.guardrails) && i.guardrails.length > 0
+        ? JSON.stringify(i.guardrails)
+        : undefined;
+    const list = (items) => (items.length ? `[${items.join(', ')}]` : undefined);
+    return { kind: 'inlineAgent', inputs: { inputRows, options: [
+                ['model', tsLiteral(plain(i.model) ?? '')],
+                ['systemPrompt', promptSrc(i.systemPrompt) ?? tsLiteral('')],
+                ['userPrompt', promptSrc(i.userPrompt) ?? tsLiteral('')],
+                ['inputs', INPUT_ROWS],
+                ['returns', returns],
+                ['temperature', num(i.temperature)],
+                ['maxTokenPerResponse', num(i.maxTokenPerResponse)],
+                ['maxIterations', num(i.maxIterations)],
+                ['mode', plain(i.mode) !== undefined ? tsLiteral(plain(i.mode)) : undefined],
+                ['guardrails', guardrails],
+                ['context', list(contextSrc)],
+                ['tools', list(toolSrc)],
+                ['escalation', list(escalationSrc)],
+                ['memory', memorySrc],
+                // The agent's directory uuid is derived from the flow and step ids, but a
+                // decompiled flow must keep the ORIGINAL — the sidecar lives at
+                // `<source>/agent.json`, so a re-derived one would point at nothing.
+                ['source', tsLiteral(plain(i.source) ?? '')],
+            ] } };
+}
+export function printInlineAgent(spec, ctx) {
+    const { inputRows, options } = spec.inputs;
+    const rows = inputRows.length
+        ? `{ ${inputRows.map(([k, e]) => `${ctx.key(k)}: ${ctx.value(e)}`).join(', ')} }`
+        : undefined;
+    return {
+        factory: 'inlineAgent',
+        options: options.map(([k, v]) => [k, v === INPUT_ROWS ? rows : v]),
+    };
+}

package/dist/nodes/agent/flow/inline-agent.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The inline (autonomous) agent's serialize: the agent node, its
+ * `<source>/agent.json`, and every resource it attaches — a node per context
+ * index, tool, escalation and memory on the agent's artifact handles, with the
+ * `resources/<id>/resource.json` each one resolves from. Moved from serialize.ts
+ * in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; nodes, edges,
+ * definitions, bindings and files unchanged.
+ */
+import type { InlineAgentInputs } from './spec.js';
+import type { FlowNodeContribution, FlowSerializeContext } from '../../../flow-node-type.js';
+/** Every bundled version of the inline agent, oldest first; the newest is the default (#956). */
+export declare const INLINE_AGENT_VERSIONS: readonly string[];
+export declare const INLINE_AGENT_DEFAULT_VERSION: string;
+/** The inline agent's node, sidecar and resources. */
+export declare function serializeInlineAgent(s: InlineAgentInputs, ctx: FlowSerializeContext): FlowNodeContribution;