@uipath/maestro-builder-sdk 6.41.2 → 6.43.0

package/dist/nodes/agent/flow/node-type.js

@@ -0,0 +1,422 @@
+/**
+ * The agents family's node types: the text conversational agent
+ * (`uipath.agent.conversational`, 1.6 and 1.7), the voice agent
+ * (`uipath.agent.voice`, 1.0 and 1.1), and the two voice call steps
+ * (`uipath.conversational.voice.create-outgoing-call` and `.end-call`, 1.0).
+ * Every one is bundled. The two agents are SHELL nodes: the node carries the
+ * agent's folder (`source`) and its turn wiring, and the prompt, model and run
+ * settings live in the `<source>/agent.json` sidecar it writes (#927). Moved
+ * from serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, sidecars, printed
+ * source, codes and messages unchanged.
+ */
+import { agentInputPlan, agentSidecarInputs, conversationalAgentJson, voiceAgentJson } from '../../../core/agent-sidecar.js';
+import { Expr, toExpr } from '../../../core/expr.js';
+import { wireExprBody } from '../../../core/wire-expr.js';
+import { checkConversationalAgent, checkInlineAgent, checkInlineAgentRead, checkVoice } from './check.js';
+import { INLINE_AGENT_DEFAULT_VERSION, INLINE_AGENT_VERSIONS, serializeInlineAgent } from './inline-agent.js';
+import { liftInlineAgent, printInlineAgent } from './inline-agent-lift.js';
+import { INLINE_AGENT } from './resources.js';
+const CREATE_OUTGOING_CALL = 'uipath.conversational.voice.create-outgoing-call';
+const END_CALL = 'uipath.conversational.voice.end-call';
+const VOICE_AGENT = 'uipath.agent.voice';
+const CONVERSATIONAL_AGENT = 'uipath.agent.conversational';
+/** Neither call step nor agent reads anything back as an error: what they publish is the definition's. */
+const opaque = () => ({ kind: 'opaque' });
+/** An options object from present entries, as decompile spells one; '' when nothing is present. */
+function opts(ctx, entries) {
+    const parts = entries.filter(([, v]) => v !== undefined).map(([k, v]) => `${ctx.key(k)}: ${v}`);
+    return parts.length ? `{ ${parts.join(', ')} }` : '';
+}
+// ─── the voice call steps ───────────────────────────────────────────────────
+/**
+ * The two VOICE service tasks. Both keep the service model on the DEFINITION
+ * (the family convention) and write the author's fields over the definition's
+ * own empty defaults.
+ */
+function serializeCall(spec, ctx, typeName) {
+    const def = ctx.definition(typeName, ctx.version);
+    const defaults = JSON.parse(JSON.stringify(def?.inputDefaults ?? {}));
+    const inputs = spec.kind === 'createOutgoingCall'
+        ? {
+            ...defaults,
+            from: ctx.render(toExpr(spec.inputs.from)),
+            to: typeof spec.inputs.to === 'string'
+                ? { type: 'literal', expression: spec.inputs.to, fieldType: 'string' }
+                : ctx.render(toExpr(spec.inputs.to)),
+        }
+        : {
+            ...defaults,
+            // The whole call-context OBJECT, not a scalar — bound from a trigger or a
+            // create-call step.
+            callContext: ctx.render(toExpr(spec.inputs.callContext)),
+        };
+    return { model: 'omit', inputs };
+}
+/**
+ * A call step's field as the author wrote it: a `=js:` expression, or a bare
+ * `$vars.` reference, back to an `Expr`; anything else as its text.
+ */
+function liftCallValue(x) {
+    const raw = typeof x === 'string' ? x : String(x?.expression ?? x ?? '');
+    if (raw.startsWith('=js:'))
+        return new Expr(raw.slice(4));
+    if (raw.startsWith('$vars.'))
+        return new Expr(raw);
+    return raw;
+}
+function liftCall(node, kind) {
+    const i = (node.inputs ?? {});
+    return kind === 'createOutgoingCall'
+        ? { kind, inputs: { from: liftCallValue(i.from), to: liftCallValue(i.to) } }
+        : { kind, inputs: { callContext: liftCallValue(i.callContext) } };
+}
+function printCall(spec, ctx) {
+    const i = spec.inputs;
+    return spec.kind === 'createOutgoingCall'
+        ? { factory: 'createOutgoingCall', options: [['from', ctx.value(i.from)], ['to', ctx.value(i.to)]] }
+        : { factory: 'endCall', options: [['callContext', ctx.value(i.callContext)]] };
+}
+// ─── the shell agents ───────────────────────────────────────────────────────
+/**
+ * Both agents leave on `success`. Named, because the definition's first handle
+ * is not it: `escalation`, `context` and `tool` are artifact handles a resource
+ * attaches to, and the default-handle rule would pick one of them.
+ */
+const SHELL_FORWARD_PORT = 'success';
+/**
+ * A VOICE agent: the inline agent's cluster shape (a `source` uuid plus an
+ * `agent.json` sidecar the platform resolves at `<source>/agent.json`), with the
+ * voice family's own inputs. There is no prompt templating and no declared
+ * `returns` — the turn comes from the live call, and the definition declares
+ * what comes back.
+ */
+function serializeVoiceAgent(s, ctx) {
+    const source = ctx.agentSource(s.source);
+    const plan = agentInputPlan(s.inputs ?? {}, (v) => ctx.render(v));
+    // A SHELL node (#927): the system prompt and the `voice` settings live only
+    // in the sidecar's `messages` and `settings.voice`. On a voice node either
+    // one makes Studio Web treat the `.flow` as authoritative and skip the
+    // sidecar (`hasEmbeddedAgentContent`). `uip maestro flow debug` builds the
+    // voice agent from the sidecar (`packageInlineAgents`).
+    // The node keeps exactly the keys `toAgentShellInputs` keeps;
+    // `maxIterations` and `metadata.isConversational` are in the sidecar.
+    const inputs = {
+        source,
+        callContext: ctx.render(toExpr(s.callContext)),
+        ...(plan.refs.length === 0 ? {} : {
+            agentInputVariables: plan.refs.map((r) => ({ id: r.flatName, type: 'string', binding: r.binding })),
+        }),
+    };
+    // The sidecar half, in the voice dialect: `settings.voice` carries the audio
+    // configuration (the storage layer's own StoredVoiceSettings shape), and the
+    // messages carry the system prompt alone.
+    const json = voiceAgentJson({
+        systemPrompt: s.systemPrompt, plan, voice: s.voice, maxIterations: s.maxIterations, source, name: ctx.step,
+    });
+    ctx.sidecar({ path: `${source}/agent.json`, json });
+    if (plan.refs.length > 0)
+        ctx.typeAgentInputs(json.inputSchema, plan.refs);
+    // The resource model lives on the definition (its `model.source: true` is
+    // what makes `source` an input), as on the inline agent.
+    return { model: 'omit', port: SHELL_FORWARD_PORT, inputs };
+}
+/**
+ * The text CONVERSATIONAL agent: the inline agent's cluster shape (a minted
+ * `source` plus an `agent.json` sidecar) with the family's own turn wiring. The
+ * per-turn bindings live in `conversationalAgentSettings` — the platform's
+ * serializer reads that sub-object and turns it into the engine's
+ * `fpsProperties`, so the SDK writes the designer's shape and lets the platform
+ * do that translation.
+ */
+function serializeConversationalAgent(s, ctx) {
+    const source = ctx.agentSource(s.source);
+    const st = s.settings ?? {};
+    // The FOUR individual fields are the runtime's source of truth — the
+    // platform's own editor says so ("they always reflect the current
+    // configuration regardless of mode; `mode` and `context` exist only to
+    // restore the editor UI"), and its validator refuses a node without
+    // `conversationId` even when a context binding is present. So `'simple'`
+    // mode DERIVES them from the context exactly as `deriveFieldsFromContext`
+    // does, appending each field's own context path (note `latestExchangeId`,
+    // which is not the field's own name).
+    const rendered = (v) => ctx.render(toExpr(v));
+    const ctxExpr = st.context === undefined ? undefined : toExpr(st.context);
+    const derive = (contextPath) => {
+        if (ctxExpr === undefined || ctxExpr.literal)
+            return undefined;
+        return ctx.render(new Expr(`${ctxExpr.js}.${contextPath}`));
+    };
+    const field = (authored, contextPath) => authored !== undefined ? rendered(authored) : derive(contextPath);
+    const settings = {
+        mode: st.mode ?? 'simple',
+        ...(st.context !== undefined ? { context: rendered(st.context) } : {}),
+    };
+    for (const [key, contextPath] of [
+        ['conversationId', 'conversationId'],
+        ['exchangeId', 'latestExchangeId'],
+        ['messages', 'messages'],
+        ['userSettings', 'userSettings'],
+    ]) {
+        const v = field(st[key], contextPath);
+        if (v !== undefined)
+            settings[key] = v;
+    }
+    ctx.sidecar({
+        path: `${source}/agent.json`,
+        json: conversationalAgentJson({
+            model: s.model, systemPrompt: s.systemPrompt, temperature: s.temperature,
+            maxTokenPerResponse: s.maxTokenPerResponse, maxIterations: s.maxIterations,
+            guardrails: s.guardrails, source, name: ctx.step,
+        }),
+    });
+    // A SHELL node, like the inline agent's (#927): exactly the keys
+    // `toAgentShellInputs` keeps. The system prompt, the model and the run
+    // settings live only in the sidecar (`metadata.isConversational` there is the
+    // family flag). `endExchange` is written nowhere: the platform retired it (the
+    // node's v1.7 migration drops it, and the converter always sends
+    // `conversationalService.endExchange = ''`).
+    return { model: 'omit', port: SHELL_FORWARD_PORT, inputs: { source, conversationalAgentSettings: settings } };
+}
+/**
+ * The node's inputs over its sidecar's (a key on the node wins), the prompt
+ * with each input's rendered binding put back as its placeholder, and the
+ * `agentInputVariables` as `{{input.<flatName>}}` refs in the file's order.
+ */
+function liftShell(node, ctx, dialect) {
+    const own = (node.inputs ?? {});
+    const i = {
+        ...agentSidecarInputs({
+            nodeId: ctx.nodeId, inputs: own, source: ctx.sourceText(own.source), dialect,
+            read: (path) => ctx.sidecar(path), warn: (m) => ctx.warn(m),
+        }),
+        ...own,
+    };
+    // 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; 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 inputs = refs
+        // 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) => [r.flatName, new Expr(wireExprBody(r.binding))]);
+    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' ? raw : undefined;
+    };
+    const prompt = (v) => {
+        const raw = plain(v);
+        return raw === undefined ? undefined : unrender(raw);
+    };
+    return { i, inputs, plain, num, prompt };
+}
+function liftVoiceAgent(node, ctx) {
+    const { i, inputs, plain, num, prompt } = liftShell(node, ctx, 'voice');
+    const v = (i.voice ?? {});
+    const raw = plain(i.callContext) ?? '';
+    return {
+        kind: 'voiceAgent',
+        inputs: {
+            systemPrompt: prompt(i.systemPrompt),
+            inputs,
+            callContext: { raw, js: wireExprBody(raw) },
+            voice: Object.keys(v).length === 0 ? undefined : {
+                model: v.model, persona: v.persona, temperature: num(v.temperature), maxTokens: num(v.maxTokens),
+            },
+            maxIterations: num(i.maxIterations),
+            source: plain(i.source),
+        },
+    };
+}
+function liftConversationalAgent(node, ctx) {
+    const { i, plain, num, prompt } = liftShell(node, ctx, 'conversational');
+    const st = (i.conversationalAgentSettings ?? {});
+    // `sourceText` rather than a string test: since the envelope reaches these
+    // five keys (migrate's `NESTED_BINDING_INPUTS`), a bare string is only what a
+    // pre-1.6 file carries. Reading strings alone made every modern file
+    // decompile to a conversational agent with no turn wiring.
+    const setting = (k) => {
+        const raw = ctx.sourceText(st[k]);
+        return raw === undefined || raw === '' || raw === '=js:' ? undefined : raw;
+    };
+    return {
+        kind: 'conversationalAgent',
+        inputs: {
+            model: plain(i.model),
+            systemPrompt: prompt(i.systemPrompt),
+            mode: typeof st.mode === 'string' ? st.mode : 'simple',
+            settings: {
+                context: setting('context'), conversationId: setting('conversationId'), exchangeId: setting('exchangeId'),
+                messages: setting('messages'), userSettings: setting('userSettings'),
+            },
+            temperature: num(i.temperature),
+            maxTokenPerResponse: num(i.maxTokenPerResponse),
+            maxIterations: num(i.maxIterations),
+            guardrails: Array.isArray(i.guardrails) && i.guardrails.length > 0 ? i.guardrails : undefined,
+            source: plain(i.source),
+        },
+    };
+}
+function printShellAgent(spec, ctx) {
+    const num = (n) => (n === undefined ? undefined : String(n));
+    if (spec.kind === 'voiceAgent') {
+        const a = spec.inputs;
+        const v = a.voice;
+        // `|| undefined`: a voice block naming none of the four settings prints no
+        // `voice` option rather than an empty `voice: `.
+        const voiceSrc = v === undefined ? undefined : opts(ctx, [
+            ['model', typeof v.model === 'string' ? ctx.string(v.model) : undefined],
+            ['persona', typeof v.persona === 'string' ? ctx.string(v.persona) : undefined],
+            ['temperature', num(v.temperature)],
+            ['maxTokens', num(v.maxTokens)],
+        ]) || undefined;
+        return {
+            factory: 'voiceAgent',
+            options: [
+                ['systemPrompt', ctx.string(a.systemPrompt ?? '')],
+                ['inputs', a.inputs.length ? `{ ${a.inputs.map(([k, e]) => `${ctx.key(k)}: ${ctx.value(e)}`).join(', ')} }` : undefined],
+                // Anything but a `$vars.` reference stays the wire text verbatim.
+                ['callContext', a.callContext.js.startsWith('$vars.') ? ctx.value(new Expr(a.callContext.js)) : ctx.string(a.callContext.raw)],
+                ['voice', voiceSrc],
+                ['maxIterations', num(a.maxIterations)],
+                ['source', ctx.string(a.source ?? '')],
+            ],
+        };
+    }
+    const a = spec.inputs;
+    // Only a `=js:` value is an expression, printed as `out(...)` for a single
+    // path and a `js` template for anything composite. Any other string is
+    // literal text, as the product reads it (flow-schema
+    // `coerceToExpressionValue`), even when it looks like `$vars.…`.
+    const setting = (raw) => raw === undefined ? undefined : raw.startsWith('=js:') ? ctx.value(new Expr(raw.slice(4))) : ctx.string(raw);
+    // `'simple'` mode DERIVES the four runtime fields from `context`, so only the
+    // context binding is the author's; recovering the derived ones would re-emit
+    // them as hand-bound custom fields.
+    const settingsSrc = a.mode === 'custom'
+        ? opts(ctx, [
+            ['mode', ctx.string('custom')],
+            ['conversationId', setting(a.settings.conversationId)],
+            ['exchangeId', setting(a.settings.exchangeId)],
+            ['messages', setting(a.settings.messages)],
+            ['userSettings', setting(a.settings.userSettings)],
+        ])
+        : opts(ctx, [['context', setting(a.settings.context)]]);
+    return {
+        factory: 'conversationalAgent',
+        options: [
+            ['model', ctx.string(a.model ?? '')],
+            ['systemPrompt', ctx.string(a.systemPrompt ?? '')],
+            // `settings` is required on ConversationalAgentInputs, so an empty one stays
+            // as `{}`, which check then reports as CONV_AGENT_NO_TURN.
+            ['settings', settingsSrc || '{}'],
+            ['temperature', num(a.temperature)],
+            ['maxTokenPerResponse', num(a.maxTokenPerResponse)],
+            ['maxIterations', num(a.maxIterations)],
+            ['guardrails', a.guardrails === undefined ? undefined : ctx.json(a.guardrails)],
+            ['source', ctx.string(a.source ?? '')],
+        ],
+    };
+}
+// ─── the node types ─────────────────────────────────────────────────────────
+const createOutgoingCall10 = {
+    kind: 'createOutgoingCall', typeName: CREATE_OUTGOING_CALL, version: '1.0', factory: 'createOutgoingCall', definition: 'bundled',
+    rawNode: { factory: 'createOutgoingCall()' },
+    serialize: (spec, ctx) => serializeCall(spec, ctx, CREATE_OUTGOING_CALL),
+    deserialize: (node) => liftCall(node, 'createOutgoingCall'),
+    print: (spec, ctx) => printCall(spec, ctx),
+    check: (spec, ctx) => checkVoice('createOutgoingCall', spec.inputs, ctx),
+    // check collected no expressions for a voice step before the port; unchanged by it.
+    expressions: () => [],
+    output: opaque,
+};
+const endCall10 = {
+    kind: 'endCall', typeName: END_CALL, version: '1.0', factory: 'endCall', definition: 'bundled',
+    rawNode: { factory: 'endCall()' },
+    serialize: (spec, ctx) => serializeCall(spec, ctx, END_CALL),
+    deserialize: (node) => liftCall(node, 'endCall'),
+    print: (spec, ctx) => printCall(spec, ctx),
+    check: (spec, ctx) => checkVoice('endCall', spec.inputs, ctx),
+    expressions: () => [],
+    output: opaque,
+};
+function voiceAgentAt(version) {
+    return {
+        kind: 'voiceAgent', typeName: VOICE_AGENT, version, factory: 'voiceAgent', definition: 'bundled',
+        rawNode: { factory: 'voiceAgent()' },
+        serialize: (spec, ctx) => serializeVoiceAgent(spec.inputs, ctx),
+        deserialize: (node, ctx) => liftVoiceAgent(node, ctx),
+        print: (spec, ctx) => printShellAgent(spec, ctx),
+        check: (spec, ctx) => checkVoice('voiceAgent', spec.inputs, ctx),
+        expressions: () => [],
+        output: opaque,
+    };
+}
+function conversationalAgentAt(version) {
+    return {
+        kind: 'conversationalAgent', typeName: CONVERSATIONAL_AGENT, version, factory: 'conversationalAgent', definition: 'bundled',
+        rawNode: { factory: 'conversationalAgent()' },
+        serialize: (spec, ctx) => serializeConversationalAgent(spec.inputs, ctx),
+        deserialize: (node, ctx) => liftConversationalAgent(node, ctx),
+        print: (spec, ctx) => printShellAgent(spec, ctx),
+        check: (spec, ctx) => checkConversationalAgent(spec.inputs, ctx),
+        expressions: () => [],
+        output: opaque,
+    };
+}
+const voiceAgent = {
+    kind: 'voiceAgent', typeName: VOICE_AGENT, factory: 'voiceAgent',
+    // 1.0 is the first bundled entry, which is what the node was emitted at before
+    // the port; 1.1 adds the error port and is reached by `{ version: '1.1' }`.
+    defaultVersion: '1.0',
+    versions: { '1.0': voiceAgentAt('1.0'), '1.1': voiceAgentAt('1.1') },
+};
+const conversationalAgent = {
+    kind: 'conversationalAgent', typeName: CONVERSATIONAL_AGENT, factory: 'conversationalAgent',
+    defaultVersion: '1.6',
+    versions: { '1.6': conversationalAgentAt('1.6'), '1.7': conversationalAgentAt('1.7') },
+};
+/**
+ * The inline agent at one version. Per-tenant, for the queue's reason: each
+ * flow's definition is the bundled one plus edits (`inlineAgentDef` sets the
+ * output's source and keeps the `memory` handle only when an agent of the flow
+ * attaches memory), so serialize supplies the definition it built. Every
+ * bundled version declares an error port.
+ */
+function inlineAgentAt(version) {
+    return {
+        kind: 'inlineAgent', typeName: INLINE_AGENT, version, factory: 'inlineAgent', definition: 'per-tenant',
+        errorPort: true,
+        rawNode: { factory: 'inlineAgent()' },
+        serialize: (spec, ctx) => serializeInlineAgent(spec.inputs, ctx),
+        deserialize: (node, ctx) => liftInlineAgent(node, ctx),
+        print: (spec, ctx) => printInlineAgent(spec, ctx),
+        check: (spec, ctx) => checkInlineAgent(spec.inputs, ctx),
+        // check collected no expressions for an inline agent before the port; unchanged by it.
+        expressions: () => [],
+        output: (spec) => ({ kind: 'reader', read: (read, report) => checkInlineAgentRead(read, spec.inputs, report) }),
+    };
+}
+const inlineAgent = {
+    kind: 'inlineAgent', typeName: INLINE_AGENT, factory: 'inlineAgent',
+    // The NEWEST bundled version, not the first (#956): `mode` and `memory` no
+    // longer pick one, so every call shape gets the current definition.
+    defaultVersion: INLINE_AGENT_DEFAULT_VERSION,
+    versions: Object.fromEntries(INLINE_AGENT_VERSIONS.map((v) => [v, inlineAgentAt(v)])),
+};
+export const agentNodeTypes = [createOutgoingCall10, endCall10, voiceAgent, conversationalAgent, inlineAgent];