@uipath/maestro-builder-sdk 5.2.0

package/dist/core/actions.js

@@ -0,0 +1,1062 @@
+import { splitConnectorNodeType, isTriggerDescriptor, } from './connectors.js';
+import { FlowAction, FlowTrigger } from './node-classes.js';
+/**
+ * The operation `type` each variant node must carry — one of, and only.
+ *
+ * @internal Serializer plumbing; an author states the variant, not the mapping.
+ */
+export const VARIANT_OPERATION = {
+    map: 'map',
+    filter: 'filter',
+    'group-by': 'groupBy',
+};
+// ─── Document extraction (uipath.ixp.*) ──────────────────────────────────────
+//
+// The platform's *Extract* node (that is its `display.canvasLabel`): it hands a
+// document to a published IxP — Intelligent eXtraction Platform — project and
+// reads the trained model's fields back. Every extractor on a tenant is its own
+// node type, `uipath.ixp.<projectSlug>.<projectVersionId>-<folderKey>`, so the
+// four identity fields below come from the tenant and are named exactly as the
+// node names them.
+//
+// The type is RESOLVED, never constructed: three different spellings of that
+// tail exist in the deployed corpus (the sanitized folder path, the literal
+// string `undefined`, and today's version-id + folder-key pair), so copy the
+// one `registry search` prints.
+/**
+ * Split an extractor's node type into the two GUIDs its tail packs.
+ *
+ * `uipath.ixp.<projectSlug>.<projectVersionId>-<folderKey>` — the version id is
+ * the `ixpDeployment` binding's `resourceKey` and the node's `model.id`; the
+ * folder key is `inputs.folderKey`. Returns `undefined` for a tail that is not
+ * exactly two uuids joined by `-`, which is how the two older spellings (a
+ * sanitized folder path, and the literal string `undefined`) are refused rather
+ * than mis-split.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function parseIxpProjectType(nodeType) {
+    const rest = nodeType.startsWith('uipath.ixp.') ? nodeType.slice('uipath.ixp.'.length) : undefined;
+    if (!rest)
+        return undefined;
+    const dot = rest.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    const slug = rest.slice(0, dot);
+    const tail = rest.slice(dot + 1);
+    const m = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i.exec(tail);
+    if (!m)
+        return undefined;
+    return { slug, versionId: m[1], folderKey: m[2] };
+}
+// ─── Delay (core.logic.delay) ────────────────────────────────────────────────
+/**
+ * The twelve durations the designer's dropdown offers. Purely an ENCODING
+ * detail: a duration in this list ships as `timerPreset: '<duration>'` and any
+ * other ships as `timerPreset: 'custom'` + `timerValue: '<duration>'`. Both
+ * deploy and both wait the same length of time — the author never picks.
+ * `core-definitions.test.ts` pins this list against the definition's own form.
+ */
+export const DELAY_PRESETS = [
+    'PT5S', 'PT15S', 'PT30S', 'PT1M', 'PT5M', 'PT15M', 'PT30M',
+    'PT1H', 'PT6H', 'PT12H', 'P1D', 'P1W',
+];
+// ── Built-in spec adapters ──────────────────────────────────────────────────
+// Every factory result IS a FlowAction/FlowTrigger instance (design §4.4 pass
+// 1), so `instanceof` can tell an SDK-owned construct from a raw literal. The
+// serializer still lowers built-ins through its kind-switch — these adapters
+// exist for identity, not lowering — and `Object.assign` keeps every spec
+// field an own enumerable property, so the wire-visible shape (JSON, toEqual,
+// spread) is exactly what the plain object was.
+class BuiltinAction extends FlowAction {
+    constructor(spec) {
+        super();
+        Object.assign(this, spec);
+    }
+    contribute() {
+        throw new Error('built-in action specs are lowered by the serializer directly; contribute() is only called on custom FlowAction subclasses');
+    }
+}
+class BuiltinTrigger extends FlowTrigger {
+    constructor(spec) {
+        super();
+        Object.assign(this, spec);
+    }
+    contribute() {
+        throw new Error('built-in trigger specs are lowered by the serializer directly; contribute() is only called on custom FlowTrigger subclasses');
+    }
+}
+/**
+ * Wrap a built-in action spec literal in its adapter class without changing
+ * its declared type. SDK-internal — factories call it so their results are
+ * `instanceof FlowAction`; authors never need it.
+ *
+ * @internal
+ * @param spec - The spec literal a factory built.
+ * @returns The same spec, as a `FlowAction` instance.
+ */
+export function builtinActionSpec(spec) {
+    return new BuiltinAction(spec);
+}
+/**
+ * Wrap a built-in trigger spec literal in its adapter class without changing
+ * its declared type. SDK-internal — factories call it so their results are
+ * `instanceof FlowTrigger`; authors never need it.
+ *
+ * @internal
+ * @param spec - The spec literal a factory built.
+ * @returns The same spec, as a `FlowTrigger` instance.
+ */
+export function builtinTriggerSpec(spec) {
+    return new BuiltinTrigger(spec);
+}
+/**
+ * Declare an HTTP request action, explicitly choosing standalone or managed.
+ *
+ * @param inputs - The request: `url`, `method`, `body`, the response fields you
+ * read back via `returns`, and the `managed` node choice.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function http(inputs) {
+    if (typeof inputs.managed !== 'boolean') {
+        throw new Error('http() requires managed: true or managed: false because they emit different platform nodes. '
+            + 'Use true for Managed HTTP Request/core.action.http.v2 or when non-2xx statuses must reach .onError(); '
+            + 'use false for the standalone core.action.http node.');
+    }
+    return builtinActionSpec({ kind: 'http', inputs });
+}
+/**
+ * Declare an inline script action.
+ *
+ * @param inputs - The JavaScript body (`code`, which must `return`) and what it
+ * returns (`returns`).
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function script(inputs) {
+    return builtinActionSpec({ kind: 'script', inputs });
+}
+/**
+ * Declare a Transform action — a chain of declarative operations over a
+ * collection. Read the result downstream with `out('<step>')`.
+ *
+ * @remarks
+ * For a node that does ONE thing, name the variant — the emitted `.flow` then
+ * carries `core.action.transform.filter` and reads as `Filter` in the designer
+ * instead of a generic `Transform`:
+ *
+ * ```ts
+ * .step('bigOrders', transform({
+ *   variant: 'filter',
+ *   collection: v('orders'),
+ *   operations: [
+ *     { type: 'filter', filters: [{ field: 'amount', condition: 'greater_equal', value: 100 }] },
+ *   ],
+ * }))
+ * ```
+ *
+ * @example
+ * **Filter a collection, then reshape what survives**
+ * ```ts
+ * .var('catalog', types.array, [
+ *   { title: 'Deep Learning', author: 'Goodfellow', difficulty: 9, pages: 800 },
+ *   { title: 'Information Theory', author: 'MacKay', difficulty: 7, pages: 540 },
+ * ])
+ * .step('curate', transform({
+ *   collection: v('catalog'),
+ *   operations: [
+ *     { type: 'filter', operation: 'and', filters: [
+ *       { field: 'difficulty', condition: 'greater_than', value: 5 },
+ *       { field: 'pages', condition: 'less_than', value: 600 },
+ *     ] },
+ *     { type: 'map', keepOriginalFields: false, mappings: [
+ *       { field: 'title', transformation: 'uppercase' },
+ *       { field: 'author' },
+ *     ] },
+ *   ],
+ * }))
+ * ```
+ *
+ * @param inputs - The `collection` to transform and the chain of `operations` to
+ * run over it.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function transform(inputs) {
+    return builtinActionSpec({ kind: 'transform', inputs });
+}
+/**
+ * Declare a human task — a step that pauses for a person to read some values,
+ * fill others in, and press one of the outcome buttons.
+ *
+ * @remarks
+ * Read an answer with `out('review', '<fieldId>')`, and which button they pressed
+ * with `out('review', 'Action')` — branch on that for per-outcome routing.
+ *
+ * ### Picking a node type with `variant`
+ *
+ * The example above emits `uipath.human-in-the-loop`, the original node, and
+ * that stays the default. Two other spellings of the same human task exist
+ * ({@link HitlVariant}), and `variant` is how you say which:
+ *
+ * ```ts
+ * // Same inline form, the newer node type — no `inputs.type` is written.
+ * hitl({ variant: 'quick-form', fields: […], outcomes: ['Approve', 'Reject'] })
+ *
+ * // The form lives in a DEPLOYED APP: no `fields`, but still your outcomes.
+ * hitl({
+ *   variant: 'action-app',
+ *   app: { name: 'Expense Review', key: '<guid>', folderPath: 'Shared',
+ *          inputs: { 'Expense Amount': out('fetchExpense', 'total') } },
+ *   outcomes: ['Approve', 'Reject'],
+ * })
+ * ```
+ *
+ * What every variant shares: one `completed` port, and the same two outputs
+ * (`output`, carrying the answers, and `status`, carrying the outcome name) —
+ * all three definitions declare them identically, so downstream reads do not
+ * change when you switch.
+ *
+ * @example
+ * **Pause for a person to approve, then read their decision**
+ * ```ts
+ * .step('review', hitl({
+ *   title: 'Review Expense',
+ *   fields: [
+ *     { id: 'amount',   type: 'number',  direction: 'input',  value: input('amount') },
+ *     { id: 'approved', type: 'boolean', direction: 'output' },
+ *     { id: 'comments', type: 'text',    direction: 'output' },
+ *   ],
+ *   outcomes: ['Approve', 'Reject'],
+ * }))
+ * .step('log', script({ code: 'return "Decision: " + $vars.review.output.approved;' }))
+ * ```
+ *
+ * @param inputs - The form's fields, outcomes and recipient.
+ * @returns An action spec for `.step(...)`.
+ * @example example-eval/GallerySubmission.flow.ts
+ */
+export function hitl(inputs) {
+    return builtinActionSpec({ kind: 'hitl', inputs });
+}
+/**
+ * Summarize a document with citations — the platform's **Summarize** node.
+ *
+ * @remarks
+ * **The node type is `uipath.pattern.deep-rag`.** The canvas calls it
+ * *Summarize*, its properties panel is titled *Summarize Configuration*, and
+ * the wire type stays `deep-rag` — it is the same node, under the name the
+ * backend service contract uses (`ECS.DeepRag`). There is no
+ * `uipath.pattern.summarize`. (A same-named inline-agent TOOL,
+ * `uipath.agent.resource.tool.builtin.summarize`, is a different family.)
+ *
+ * The answer's fields are **PascalCase** — `content.Text`,
+ * `content.Citations[].{Ordinal, PageNumber, Source, Reference}`. Lowercase
+ * `content.text` resolves to nothing at run time.
+ *
+ * A local run cannot reach the service: it returns the baked
+ * fixture shape, and only a real platform run (`uip maestro flow debug
+ * --attachment <var>=<file>`) calls the model.
+ *
+ * @example
+ * **Summarize an attached contract, with citations**
+ * ```ts
+ * flow('SummarizeDemo')
+ *   .input({ documentFile: types.file })
+ *   .output({ summary: types.string, citations: types.array })
+ *   .step('summarizeContract', summarize({
+ *     attachment: out('start', 'documentFile'),
+ *     prompt: 'Write a 5-bullet executive summary covering scope, term and SLAs.',
+ *     returnCitations: true,
+ *   }))
+ *   .return({
+ *     summary:   out('summarizeContract', 'content.Text'),
+ *     citations: out('summarizeContract', 'content.Citations'),
+ *   })
+ * ```
+ *
+ * @param inputs - The document (`attachment`), the question to answer (`prompt`),
+ * and whether to return citations.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function summarize(inputs) {
+    return builtinActionSpec({ kind: 'summarize', inputs });
+}
+/**
+ * Add AI-generated columns to a CSV — the platform's **Batch transform** node,
+ * `uipath.pattern.batch-transform` (service contract `ECS.BatchTransform`).
+ *
+ * @remarks
+ * The output is a **file handle for the enriched CSV**, not the rows:
+ * `{ ID, FullName, MimeType }` — the service writes a new
+ * `batch-transform-<uuid>.csv` and hands back its attachment. Note `ID`, two
+ * capitals: that is what the platform returns.
+ *
+ * Same dispatch story as {@link summarize} — dry-run fixture locally, a real
+ * model call only on a platform run.
+ *
+ * @example
+ * **Categorize each CSV row with two generated columns**
+ * ```ts
+ * flow('BatchTransformDemo')
+ *   .input({ csvFile: types.file })
+ *   .output({ result: types.file })
+ *   .step('categorizeRows', batchTransform({
+ *     attachment: out('start', 'csvFile'),
+ *     prompt: 'Classify each row by category and write a one-line summary.',
+ *     outputColumns: [
+ *       { name: 'Category', description: 'One of: Utility, Software, Travel, Other' },
+ *       { name: 'Summary',  description: 'Plain-English one-line summary of the row' },
+ *     ],
+ *   }))
+ *   .return({ result: out('categorizeRows') })
+ * ```
+ *
+ * @param inputs - The CSV (`attachment`), the instruction (`prompt`), and the
+ * `outputColumns` to add to each row.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function batchTransform(inputs) {
+    return builtinActionSpec({ kind: 'batchTransform', inputs });
+}
+/**
+ * Extract fields from a document with a published IxP project — the platform's
+ * **Extract** node (`uipath.ixp.*`, service contract `IXP.Extraction`).
+ *
+ * @remarks
+ * **The result's shape is three levels deep and PascalCase.** A field lands at
+ * `out('<step>', 'ExtractionResult.ResultsDocument.Fields')` — an array of
+ * `{ FieldId, FieldName, FieldType, IsMissing, Values[], Confidence }`, looked
+ * up by `FieldName`. `Fields[]` is under `ResultsDocument`, not directly under
+ * `ExtractionResult`, and there is no `result` wrapper: the platform's
+ * serializer strips it before the value reaches the variable.
+ *
+ * **A local run cannot extract anything** — extraction needs a real document on
+ * the IxP service. An offline run returns the baked
+ * fixture shape, and only a platform run reaches the model. So a green local
+ * rung proves the wiring and the definition, never that a document was read.
+ *
+ * **`fileRef` is emitted as a PLAIN `=js:` string, not the expression envelope
+ * the rest of the file uses** — the one place this family diverges from the
+ * format's general spelling, and the contract this node owes the platform. The
+ * product's own `ixp-node` validator tests `typeof fileRef !== 'string'` and
+ * refuses the object form (*"inputs.fileRef must be a `=js:$vars.…`
+ * expression"*), the node's registry manifest declares
+ * `{type:'string', minLength:1}`, and so do all 150 v1-authored instances in the
+ * deployed corpus that carry the field — at file versions 1.6, 1.8 and 1.9 alike,
+ * with zero envelopes among them. The RUNTIME
+ * accepts both, so only `uip maestro flow validate` sees a wrong one; the
+ * emitter's exemption lives in `migrate.ts` (`UNWRAPPED_INPUTS`).
+ * See `skill/references/ixp.md` §3.
+ *
+ * @example
+ * **Extract an invoice total and read it out of the nested result**
+ * ```ts
+ * flow('InvoiceIntake')
+ *   .input({ invoiceFile: types.file })
+ *   .output({ total: types.string })
+ *   .step('extract', ixpExtract({
+ *     project: 'uipath.ixp.invoiceixp-cef0d447-ixp.ff973488-5d89-8035-86ac-f980b4be6deb-c4359cde-55f0-4f0e-9322-c6cdce74ab4c',
+ *     modelName: 'invoiceixp-cef0d447-ixp',
+ *     name: 'InvoiceIXP',
+ *     folderName: 'Shared',
+ *     fileRef: out('start', 'invoiceFile'),
+ *   }))
+ *   .step('readTotal', script({ code: `
+ *     const fields = $vars.extract.output.ExtractionResult.ResultsDocument.Fields || [];
+ *     return { total: fields.find(f => f.FieldName === 'invoiceTotal')?.Values?.[0] };
+ *   ` }))
+ *   .return({ total: out('readTotal', 'total') })
+ * ```
+ *
+ * @param inputs - The published IxP `project` and `modelName`, and the document
+ * to read (`fileRef`).
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function ixpExtract(inputs) {
+    return builtinActionSpec({ kind: 'ixpExtract', inputs });
+}
+/**
+ * Declare a delay — a step that pauses the flow for a fixed length of time and
+ * then carries on.
+ *
+ * @remarks
+ * A delay produces nothing: there is no `out('settle')` to read. It is a wait,
+ * not a value.
+ *
+ * The node itself splits that one duration across two fields (`timerPreset`
+ * holds it directly, or the literal `"custom"` with the real value in
+ * `timerValue`); the serializer picks the encoding, so you state the wait once.
+ *
+ * @example
+ * **Wait thirty seconds before carrying on**
+ * ```ts
+ * .step('settle', delay({ duration: 'PT30S' }))
+ * ```
+ *
+ * @param inputs - How long to wait (`duration`), as an ISO-8601 duration.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function delay(inputs) {
+    // Key presence, not value shape: `{ duration: undefined }` picks the
+    // duration arm and flows to check()'s DELAY_NO_DURATION diagnostic — the
+    // factory only rejects picking BOTH arms or NEITHER.
+    const hasDuration = 'duration' in inputs;
+    const hasUntil = 'until' in inputs;
+    if (hasDuration === hasUntil) {
+        throw new Error("delay() takes exactly ONE of { duration } (an ISO-8601 duration, e.g. 'PT15M') or "
+            + "{ until } (an ISO-8601 date-time, e.g. '2026-09-01T09:00:00Z').");
+    }
+    return builtinActionSpec({ kind: 'delay', inputs });
+}
+/**
+ * Declare a PLACEHOLDER step — "a real node goes here later".
+ *
+ * @remarks
+ * A mock takes **no inputs and publishes nothing**. It is a marker on the canvas
+ * that keeps the graph wired and the flow deployable while one step is still
+ * missing — not a stub that returns test data. `out('extractInvoice')` is
+ * refused at compile time (`MOCK_HAS_NO_OUTPUT`) because it would read `null` at
+ * run time, always.
+ *
+ * Say what belongs there in the step's own name and in the label the canvas
+ * shows; the corpus's placeholders read like
+ * `"Extract Invoice Fields (mock — IxP model not yet published)"`.
+ *
+ * ### Why there are no arguments (convention #191 — the family contract)
+ *
+ * The platform's `core.logic.mock@1.0.0` declares **no `inputDefinition`** and one
+ * output whose `source` is the literal `"null"`. Measured over the 4,033 distinct
+ * archived `.flow` artifacts: **74 mock instances in 62 flows, and 0 carrying a
+ * fixture anywhere in the node** — 71 of them with `inputs: {}` or no `inputs`
+ * key. The 3 exceptions carry free-text `placeholder` / `_placeholder` keys the
+ * definition never declares, invented by agents on runs that scored 0.9 and 0.4.
+ *
+ * **This is NOT a local runner's `kind: 'mock'` test construct**, which returns a
+ * baked fixture. They are different things that share
+ * a name, and a `mock({ fixture })` surface would emit a node whose local
+ * behaviour and deployed behaviour disagree silently — see
+ * [#125](https://github.com/UiPath/flow-builder-sdk/issues/125). Nothing this SDK
+ * emits opens that channel: an SDK-authored mock publishes `null` locally,
+ * exactly as the platform does.
+ *
+ * @example
+ * **Hold a step's place until the real node exists**
+ * ```ts
+ * .step('extractInvoice', mock())      // ← swap for the IxP node once the project exists
+ * ```
+ *
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function mock() {
+    return builtinActionSpec({ kind: 'mock' });
+}
+/**
+ * Invoke a deployed RPA (robotic process automation) workflow — a classic
+ * UI-automation process, published to Orchestrator, run by a robot.
+ *
+ * @remarks
+ * Three fields identify the process and they all come from the tenant, which is
+ * why they are named exactly as the platform names them:
+ *
+ *   key         the published process's release key (a GUID). It becomes part of
+ *               the node's TYPE — `uipath.core.rpa-workflow.<key>` — so the
+ *               platform can tell one process's node from another's.
+ *   name        the process's name in Orchestrator.
+ *   folderPath  the Orchestrator folder it lives in.
+ *
+ * `name` + `folderPath` are what the robot is actually started by (the runtime
+ * re-resolves the release from them), and together they are also the process's
+ * `resourceKey`: `"<folderPath>.<name>"`. The serializer emits the two of them
+ * as the flow's process bindings and points the node at them, because a
+ * bindings entry the node does not reference is not a bound process.
+ *
+ * `inputs` are the PROCESS's own input arguments — whatever it declares, by its
+ * own argument names. They are not a fixed schema.
+ *
+ * The step publishes whatever the process returns, under `output`: read a field
+ * with `out('<step>', '<field>')`. Nothing local can check that an argument name
+ * or a returned field name matches the deployed process — only the robot knows —
+ * so a wrong name shows up as a faulted job on a live run, not at compile time.
+ *
+ * @example
+ * **Start a deployed process and read what it returns**
+ * ```ts
+ * .step('getTitle', rpaWorkflow({
+ *   key: '486edc26-0658-4ac1-92c9-1ef953927151',
+ *   name: 'RPA Workflow',
+ *   folderPath: 'Shared/uipath-maestro-flow/ProjectEuler RPA',
+ *   inputs: { problemId: 123 },
+ * }))
+ * .return({ title: out('getTitle', 'title') })
+ * ```
+ *
+ * @param inputs - The published process to start (`key`, `name`, `folderPath`),
+ * its `inputs`, and the output fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function rpaWorkflow(inputs) {
+    return builtinActionSpec({ kind: 'rpaWorkflow', inputs });
+}
+/**
+ * Invoke a deployed API workflow — a coded workflow published to Orchestrator,
+ * run as a serverless job rather than by a robot.
+ *
+ * @remarks
+ * The same three identifiers as `rpaWorkflow`, for the same reason: `key` is
+ * the key the node's TYPE carries (`uipath.core.api-workflow.<key>`), while
+ * `name` + `folderPath` are what the runtime resolves the job by — and together
+ * they are the workflow's `resourceKey`, `"<folderPath>.<name>"`. The serializer
+ * emits those two as the flow's process bindings and points the node at them.
+ *
+ * The step publishes the job's output arguments under `output`, so
+ * `out('<step>', '<field>')` reads one of the fields `returns` declares. Whether
+ * an argument name or a returned field actually matches the deployed workflow is
+ * something only the tenant knows — a wrong one is a faulted job on a live run,
+ * not a compile error.
+ *
+ * @example
+ * **Start an API workflow and read a declared output argument**
+ * ```ts
+ * .step('getAge', apiWorkflow({
+ *   key: 'ce857908-ee1d-4392-b552-38bcea0be29c',
+ *   name: 'NameToAgeFixed',
+ *   folderPath: 'Shared',
+ *   inputs: { name: 'tomasz' },
+ *   returns: { EstimatedAge: 'integer' },
+ * }))
+ * .return({ age: out('getAge', 'EstimatedAge') })
+ * ```
+ *
+ * @param inputs - The published API workflow to start (`key`, `name`,
+ * `folderPath`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function apiWorkflow(inputs) {
+    return builtinActionSpec({ kind: 'apiWorkflow', inputs });
+}
+/**
+ * Invoke a published Orchestrator **Function** — a deployed unit of code run as
+ * one step (`uipath.core.function.<key>`, dispatched as
+ * `Orchestrator.ExecuteFunctionAsync`).
+ *
+ * ```ts
+ * .step('echo', publishedFunction({
+ *   key: '7059bdb5-fdd7-4e13-9d7b-1748aaeb129d',
+ *   name: 'acme-echo',
+ *   folderPath: 'Shared/acme-echo',
+ *   inputs: { message: 'hello' },
+ *   returns: { echoed: 'string' },
+ * }))
+ * ```
+ *
+ * The node type carries the key, so the function must already exist on the
+ * tenant — read `key`, `name` and `folderPath` from the registry rather than
+ * constructing them. Like the other published families, the resource identity
+ * is CLOSED by a binding pair (`<folderPath>.<name>`), and two steps on the
+ * same function share one pair.
+ *
+ * @param inputs - The function's identity, its arguments, and what it returns.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function publishedFunction(inputs) {
+    return builtinActionSpec({ kind: 'publishedFunction', inputs });
+}
+/**
+ * Post an assistant message into a live conversation
+ * (`uipath.conversational.send-message`).
+ *
+ * ```ts
+ * .step('answer', sendMessage({
+ *   conversationId: out('start', 'conversationId'),
+ *   exchangeId: out('listen', 'conversationContext.latestExchangeId'),
+ *   content: 'Your order ships tomorrow.',
+ * }))
+ * ```
+ *
+ * The message is Markdown (`text/markdown` is the node's only supported type)
+ * and the role is always `assistant` — a flow speaks as the assistant.
+ *
+ * @param inputs - The conversation, the exchange, and what to say.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function sendMessage(inputs) {
+    return builtinActionSpec({ kind: 'sendMessage', inputs });
+}
+/**
+ * PAUSE until the person sends their next message
+ * (`uipath.conversational.wait-for-message`) — a catch event, like
+ * `waitForEvent`, so the flow suspends rather than polling.
+ *
+ * ```ts
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * ```
+ *
+ * It resumes with the conversation context:
+ * `out('listen', 'conversationContext.messages')` is the transcript and
+ * `…conversationContext.latestExchangeId` is the turn to answer.
+ *
+ * @param inputs - The conversation to wait on, and how much history to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function waitForMessage(inputs) {
+    return builtinActionSpec({ kind: 'waitForMessage', inputs });
+}
+/**
+ * READ a conversation's transcript so far without waiting
+ * (`uipath.conversational.get-conversation-context`) — the shape a
+ * conversational agent takes as its turn context.
+ *
+ * ```ts
+ * .step('history', conversationContext({
+ *   conversationId: out('start', 'conversationId'), exchangeLimit: 10,
+ * }))
+ * ```
+ *
+ * @param inputs - The conversation to read, and how many exchanges to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function conversationContext(inputs) {
+    return builtinActionSpec({ kind: 'conversationContext', inputs });
+}
+/**
+ * Place an outgoing phone call
+ * (`uipath.conversational.voice.create-outgoing-call`) and get back the
+ * `callContext` every other voice step is keyed by.
+ *
+ * ```ts
+ * .step('dial', createOutgoingCall({ from: '+15550001111', to: input('customerPhone') }))
+ * .step('talk', voiceAgent({
+ *   systemPrompt: 'Confirm the delivery window, then thank them.',
+ *   callContext: out('dial', 'callContext'),
+ * }))
+ * ```
+ *
+ * @param inputs - The provisioned `from` number and the `to` number to dial.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function createOutgoingCall(inputs) {
+    return builtinActionSpec({ kind: 'createOutgoingCall', inputs });
+}
+/**
+ * Hang up (`uipath.conversational.voice.end-call`). Reads
+ * `out('<step>', 'ended')`.
+ *
+ * @param inputs - The `callContext` of the call to end.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function endCall(inputs) {
+    return builtinActionSpec({ kind: 'endCall', inputs });
+}
+/**
+ * Put a VOICE agent on a live call (`uipath.agent.voice`) — it speaks and
+ * listens for one turn, then the flow continues.
+ *
+ * ```ts
+ * .trigger(voiceTrigger())
+ * .step('greet', voiceAgent({
+ *   systemPrompt: 'Greet {{input.customerName}} and find out why they called.',
+ *   inputs: { customerName: input('customerName') },
+ *   callContext: out('start', 'callContext'),
+ *   voice: { model: 'gemini-3.1-flash-live-preview', persona: 'Kore' },
+ * }))
+ * ```
+ *
+ * Like `inlineAgent`, compile emits the node PLUS a stable
+ * `<source>/agent.json` sidecar. Unlike it, the turn's content comes from the
+ * call rather than from a user-prompt argument. Flow context can still be
+ * supplied through `inputs` and referenced from the system prompt. There are no
+ * declared `returns`: read the turn back as
+ * `out('<step>', 'uipath__agent_response_messages')`.
+ *
+ * @param inputs - The instructions, the call to join, and how the agent sounds.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function voiceAgent(inputs) {
+    return builtinActionSpec({ kind: 'voiceAgent', inputs });
+}
+/**
+ * A CONVERSATIONAL agent (`uipath.agent.conversational`) — it answers one turn
+ * of a live chat, reading the transcript rather than flow arguments.
+ *
+ * ```ts
+ * .trigger(conversationTrigger())
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * .step('reply', conversationalAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt: 'You are a support agent. Be brief.',
+ *   settings: { context: out('listen', 'conversationContext') },
+ * }))
+ * ```
+ *
+ * The reply is `out('<step>', 'uipath__agent_response_messages')` — the
+ * platform's own field name. Like `inlineAgent`, compile emits the node plus a
+ * stable `<source>/agent.json` sidecar.
+ *
+ * `sendMessage` is the alternative when the flow (not a model) decides what to
+ * say; this factory is for when the model does.
+ *
+ * @param inputs - The model, the instructions, and how the turn is bound.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function conversationalAgent(inputs) {
+    return builtinActionSpec({ kind: 'conversationalAgent', inputs });
+}
+/**
+ * Invoke a deployed AGENTIC PROCESS — a Maestro process orchestration published to
+ * Orchestrator: a BPMN process that coordinates agents, robots and people, started
+ * as a job the same way an RPA or API workflow is.
+ *
+ * @remarks
+ * The same three identifiers as `rpaWorkflow` and `apiWorkflow`, for the same
+ * reason: `key` is the key the node's TYPE carries
+ * (`uipath.core.agentic-process.<key>`), while `name` + `folderPath` are what
+ * the runtime resolves the job by — and together they are the process's
+ * `resourceKey`, `"<folderPath>.<name>"`. The serializer emits those two as the
+ * flow's process bindings and points the node at them.
+ *
+ * By default the step WAITS for the process and publishes its output arguments
+ * under `output`, so `out('<step>', '<field>')` reads one of the fields
+ * `returns` declares.
+ *
+ * `completion: 'fire-and-forget'` selects the designer's own async switch
+ * instead: the node's service type becomes `Orchestrator.Start…ProcessAsync`
+ * and it publishes no output but `error`. The type is a discriminated union, so
+ * `returns` is impossible in that form and nothing downstream can read one; a
+ * local run dispatches without waiting and yields `{ jobKey, started: true }`.
+ *
+ * `form` picks which published Agentic Process this is — `'bpmn'` (the default,
+ * a Maestro process orchestration), `'flow'` (a published Maestro Flow), or
+ * `'case'` (a Case Management process). They share one public concept and
+ * differ only in wire identity.
+ *
+ * @example
+ * **Start a Maestro process and wait for its result**
+ * ```ts
+ * .step('runIntake', agenticProcess({
+ *   key: '4fc450ab-89be-4462-8fc8-21ac4c1d6fb9',
+ *   name: 'ProcurementProcess',
+ *   folderPath: 'Shared/uipath-agents/ProcurementProcess',
+ *   inputs: { productId: 1 },
+ *   returns: { status: 'boolean' },
+ * }))
+ * .return({ ok: out('runIntake', 'status') })
+ * ```
+ *
+ * @param inputs - The published Maestro process to start (`key`, `name`,
+ * `folderPath`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function agenticProcess(inputs) {
+    // Types are erased at run time, so the discriminated union alone cannot stop
+    // `{ completion: 'fire-and-forget', returns: {...} }` arriving from untyped
+    // code — and silently dropping the returns would validate a read that can
+    // never be satisfied.
+    if (inputs.completion === 'fire-and-forget' && inputs.returns !== undefined) {
+        throw new Error("agenticProcess(): completion 'fire-and-forget' publishes no output — remove `returns`, "
+            + "or use completion: 'wait' to read the process result.");
+    }
+    return builtinActionSpec({ kind: 'agenticProcess', inputs });
+}
+/**
+ * Invoke an AGENT resource — either one published to Orchestrator or a sibling
+ * agent project registered in the same solution. Both start through
+ * `Orchestrator.StartAgentJob`.
+ *
+ * @remarks
+ * **Coded and low-code agents are the same node.** This one factory authors both.
+ * `registry get` on a coded agent and on a low-code one returns the same node type,
+ * the same service type, the same `sortOrder: 505` and the same bindings shape; the
+ * only difference is the icon, which is what `flavour` sets. Which kind a resource
+ * is a property of what somebody published, not of the flow — so if a task asks for
+ * "a coded agent", what it is asking you to get right is the RESOURCE you point at.
+ *
+ * **What this factory cannot do, said plainly:** it does not create an agent. A
+ * published resource must already be deployed. An in-solution resource must first
+ * be scaffolded and registered with `uip solution projects add`; this factory then
+ * authors the local reference from the registered resource key and project id.
+ *
+ * The three identifiers are separate for `rpaWorkflow`'s reason: `agent` is the key
+ * the node's TYPE carries (`uipath.core.agent.<agent>`), while `name` +
+ * `folderPath` are what the runtime resolves the job by and together are the
+ * `resourceKey`, `"<folderPath>.<name>"`. `folderPath` earns its keep twice here —
+ * see {@link AgentInputs.folderPath} for the two-agents-called-CountLetters case.
+ *
+ * The step WAITS for the job and publishes its output arguments under `output`, so
+ * `out('<step>', '<field>')` reads a field `returns` declares — using the names the
+ * agent's own definition declares, case included.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * A green live rung here means **a model responded with the declared output shape**,
+ * not that the answer was right. A real Orchestrator job runs, the flow's input
+ * reaches it, and its answer reaches the flow's output — all four independently
+ * checkable (`ladder.sh job`). Whether the number it returned is the correct number
+ * is the model's business, and no rung asserts it. What CAN be asserted is that the
+ * flow did not fake it: the offline seeds assert the exact UNFIXTURED value, which a
+ * hardcoded answer cannot produce.
+ *
+ * @example
+ * **Start a published agent and read one declared output**
+ * ```ts
+ * .step('countLetters', agent({
+ *   key: '6a47dc5b-5fd4-461f-b97d-6c1817abcaaa',
+ *   name: 'CountLetters LowCode Agent',
+ *   folderPath: 'Shared/uipath-maestro-flow/CountLetters LowCode',
+ *   inputs: { inputString: input('word') },
+ *   returns: { count: 'integer', inputString: 'string' },
+ * }))
+ * .return({ rs: out('countLetters', 'count') })
+ * ```
+ *
+ * @param inputs - The agent to start (`name`, `folderPath`, and `key` or
+ * `projectId`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function agent(inputs) {
+    return builtinActionSpec({ kind: 'agent', inputs });
+}
+/**
+ * Declare an INLINE AUTONOMOUS AGENT — an agent defined inside this flow's own
+ * project rather than published to Orchestrator (`uipath.agent.autonomous`,
+ * `Orchestrator.StartInlineAgentJob`).
+ *
+ * @remarks
+ * **Two artifacts, not one.** The node carries the prompts and the variable
+ * descriptors, and it points at a directory — `source` — where the platform expects
+ * the agent's own configuration (flow-v1 emits `entryPoint: <source>/agent.json`).
+ * So `compile` writes `<source>/agent.json` beside the `.flow`, built from the same
+ * fields. Nothing to assemble by hand; `source` defaults to a uuid derived from the
+ * flow id and step name so a recompile is not a diff.
+ *
+ * **How this differs from `agent()`.** That one references something already
+ * published and started as an Orchestrator job; this one IS the definition, and the
+ * platform runs it inside the flow's own debug/publish context. The practical
+ * consequences: there is no folder, no release key and no binding pair here — and
+ * no `uip` verb that starts one headlessly either.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * Weaker than `agent()`'s, and in a specific way. `Orchestrator.StartInlineAgentJob`
+ * is Studio-Web-debug-only, so there is no Orchestrator job to point at and no
+ * headless verb that starts one. No local runner currently calls a model for this
+ * node either — an offline run asserts the WIRING and the declared `returns` shape,
+ * never that a model answered. Two differences would remain for any runner that did
+ * call one: knowledge grounding (a context handle) is a cloud-side index an offline
+ * path does not have, so the call would be ungrounded; and the node's `model` would
+ * have to be substituted for one reachable headlessly. Answer quality stays on the
+ * offline `expect` seeds; real behaviour needs a Studio Web debug run.
+ *
+ * @example
+ * **Classify an email with an agent defined inline**
+ * ```ts
+ * .step('triage', inlineAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt:
+ *     'You are a support triage assistant. Classify the email into exactly one ' +
+ *     'category (billing | technical | account) and one priority (low | normal | ' +
+ *     'high). Return ONLY a JSON object with keys "category" and "priority".',
+ *   userPrompt: 'Classify this email:\n{{input.body}}',
+ *   inputs: { body: input('body') },
+ *   returns: { category: 'string', priority: 'string' },
+ * }))
+ * .return({ category: out('triage', 'category') })
+ * ```
+ *
+ * @param inputs - The agent defined in this project: its `model`,
+ * `systemPrompt`, `userPrompt`, and the `returns` fields it must produce.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function inlineAgent(inputs) {
+    return builtinActionSpec({ kind: 'inlineAgent', inputs });
+}
+/**
+ * Classify a document into a document type (`uipath.document.classify`). The
+ * result publishes `ClassificationResult` — an array of typed classifications
+ * with page ranges and confidences.
+ *
+ * @param inputs - The file reference and optional page range / split / model settings.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function documentClassify(inputs) {
+    return builtinActionSpec({ kind: 'documentClassify', inputs });
+}
+/**
+ * Extract fields from a document with an INLINE schema — Dynamic Extract
+ * (`uipath.ixp.extract-document-builder`), the newer of the two extraction
+ * shapes. No deployed IXP project is referenced: the extraction schema rides
+ * the node. The result publishes `ExtractionResult` (and `Taxonomy`).
+ *
+ * @param inputs - The file reference, the inline extraction schema, and
+ * optional page range / model settings.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dynamicExtract(inputs) {
+    return builtinActionSpec({ kind: 'dynamicExtract', inputs });
+}
+/**
+ * Read ONE entity record from Data Fabric (`core.datafabric.read`). The record
+ * publishes to the step's `output`; downstream references re-fetch fresh data
+ * at activation time (the engine re-runs the query rather than caching).
+ *
+ * @remarks
+ * **Prefer the connector for Data Fabric work during the transition.**
+ * `core.datafabric.*` has exactly two verbs — this one and
+ * {@link dataFabricUpdate} — and neither declares an output schema. Create,
+ * delete, get-by-id, a multi-record query with a row limit, file record fields
+ * and entity events are NOT in this family: they are operations on the SAME
+ * product reached through its Integration Service connector,
+ * `uipath-uipath-dataservice` (the tenant displays it as **UiPath Data
+ * Fabric**), which covers every verb including the two here.
+ *
+ * Taking this node for the one verb that has a native form leaves the rest of
+ * the same entity on the connector — two connection bindings and two payload
+ * shapes in one flow. So route entity work through the connector unless the
+ * scenario names these nodes; native forms for the remaining verbs are the
+ * direction of travel, and this guidance changes when they land. `check` does
+ * not reject a native node — this is a routing default, not a rule:
+ *
+ * ```ts
+ * .step('create', connector('uipath-uipath-dataservice', 'create-entity-record',
+ *   { entityName: 'Contracts', contractTitle: 'Q3 renewal' }, { connection: 'df' }))
+ * ```
+ *
+ * That operation's body fields come from the entity, so the library cannot
+ * carry them: run `npx flow-sdk registry prepare uipath-uipath-dataservice
+ * create-entity-record -f entityName=<Entity>` first (`uip maestro registry
+ * prepare …` is the same command when you are driving through the UiPath CLI). The routing table is in
+ * the `data-fabric.md` reference and the parent-field loop in
+ * `connector-params.md` — cited by name rather than linked, because this
+ * comment renders both into the flat corpus, where those files sit alongside
+ * it, and onto the site, where each symbol is its own page and a relative
+ * `./data-fabric` resolves to nothing.
+ *
+ * @param inputs - The entity, optional filter rows, and folder scope.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricRead(inputs) {
+    return builtinActionSpec({ kind: 'dataFabricRead', inputs });
+}
+/**
+ * Update an entity record in Data Fabric (`core.datafabric.update`). Target the
+ * record by id or through an earlier {@link dataFabricRead} step; downstream
+ * reads of this step observe the record AFTER the write.
+ *
+ * @remarks
+ * The second and last verb of the native family — see {@link dataFabricRead}
+ * for what the family does NOT cover, which connector operation covers it
+ * instead, and why entity work routes through the connector during the
+ * transition. For an update whose flow also creates, gets or deletes on the
+ * same entity, use `connector(…, 'update-entity-record', …)` so the flow keeps
+ * one surface.
+ *
+ * @param inputs - The entity, the record selector, and the columns to write.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricUpdate(inputs) {
+    const byId = inputs.record?.byId !== undefined;
+    const fromRead = typeof inputs.record?.fromRead === 'string';
+    if (byId === fromRead) {
+        throw new Error("dataFabricUpdate() targets exactly ONE of record: { byId } or record: { fromRead: '<step>' }.");
+    }
+    return builtinActionSpec({ kind: 'dataFabricUpdate', inputs });
+}
+/**
+ * Declare an Orchestrator QUEUE ITEM step.
+ *
+ * @remarks
+ * A queue is Orchestrator's work list: something puts items on it, and an
+ * automation bound to the queue takes them off one at a time. This step is the
+ * putting-on half.
+ *
+ * `queue` + `folderPath` are what the runtime resolves the queue by, and `key` is
+ * the queue's own Orchestrator key: it joins this node to the flow's queue
+ * bindings, which the serializer emits and points the node at. All three, for the
+ * same reason `rpaWorkflow` takes three — the key is the AUTHORING identity, the
+ * two bindings are the RUNTIME one.
+ *
+ * `item` is the work item's data. It becomes the item's `SpecificContent`, and it
+ * must be FLAT: Orchestrator rejects a nested object or array outright.
+ *
+ * **`wait`** picks between the family's two node types, which are one construct
+ * with two data paths. Default `false` enqueues and moves on, publishing the queue
+ * item's own Orchestrator record — read a field with `out('<step>', 'Key')`, and
+ * nothing extra has to be declared because that record's shape is the same for
+ * every queue. `wait: true` PARKS the flow until the item has been processed and
+ * publishes the consumer's result instead, which is per-automation — so a read of
+ * it needs `returns`, exactly as an rpa process's output does.
+ *
+ * What no rung can tell you: whether anything actually drains this queue. A
+ * `wait: true` step on a queue with no consumer waits until it times out.
+ *
+ * @example
+ * **Enqueue a work item and read its Orchestrator key**
+ * ```ts
+ * .step('enqueue', queueItem({
+ *   queue: 'SupplierInvoices',
+ *   folderPath: 'Shared',
+ *   key: 'fa1a7328-cd17-4525-b5ab-29d86e399312',
+ *   item: { InvoiceId: input('invoiceRef'), Amount: input('amount') },
+ *   reference: 'INV-2031',
+ * }))
+ * .return({ itemKey: out('enqueue', 'Key') })
+ * ```
+ *
+ * @param inputs - The `queue` and `folderPath`, the `item` to add, and whether
+ * to `wait` for it to be processed.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function queueItem(inputs) {
+    return builtinActionSpec({ kind: 'queueItem', inputs });
+}
+export function connector(a, b, c, d) {
+    if (typeof a === 'string') {
+        const opts = (d ?? {});
+        return builtinActionSpec({
+            kind: 'connector',
+            key: a,
+            action: b,
+            version: opts.version,
+            connection: opts.connection,
+            folder: opts.folder,
+            object: opts.object,
+            inputs: c ?? {},
+        });
+    }
+    // Descriptor form: (descriptor, inputs, opts) — derive key/action from the nodeType.
+    const { key, action } = splitConnectorNodeType(a.nodeType);
+    const opts = (c ?? {});
+    return builtinActionSpec({
+        kind: 'connector',
+        key,
+        action,
+        version: opts.version ?? a.version,
+        connection: opts.connection,
+        folder: opts.folder,
+        object: opts.object ?? a.objectName,
+        inputs: b ?? {},
+    });
+}
+/**
+ * Fold a typed `(descriptor, opts)` call into the same {@link EventSubscription}
+ * the stringly form produces, or pass a stringly subscription through unchanged.
+ * Shared by `onEvent` (flow-sdk) and `waitForEvent` so both surfaces stay in
+ * lock-step — the descriptor only supplies `connector`/`event`/`version`.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function subscriptionFrom(a, opts) {
+    if (!isTriggerDescriptor(a))
+        return a;
+    // No options at all is legal: an operation with no event parameters (HTTP
+    // Webhook) has nothing to put in them, and the descriptor carries the version.
+    return {
+        connector: a.connector,
+        event: a.event,
+        ...(opts?.where ? { where: opts.where } : {}),
+        ...(opts?.object ? { object: opts.object } : {}),
+        ...(opts?.filters ? { filters: opts.filters } : {}),
+        ...(opts?.connection ? { connection: opts.connection } : {}),
+        ...(opts?.folder ? { folder: opts.folder } : {}),
+        version: opts?.version ?? a.version,
+    };
+}
+export function waitForEvent(a, opts) {
+    return builtinActionSpec({ kind: 'waitEvent', subscription: subscriptionFrom(a, opts) });
+}