@uipath/maestro-builder-sdk 6.40.1 → 6.41.0

package/dist/nodes/process/flow/check.js

@@ -0,0 +1,444 @@
+import { AGENTIC_PROCESS_FORMS } from '../../../core/agentic-process-forms.js';
+import { GUID_RE } from '../../../core/binding-messages.js';
+import { nearestName } from '../../../core/edit-distance.js';
+import { ownEntry } from '../../../core/own-entry.js';
+import { renamedFieldMessage } from '../../../core/process-resource.js';
+export const PROCESS_DIAGNOSTICS = {
+    AGENTIC_EMPTY_RETURNS: { severity: 'warning', summary: 'an agentic process step with returns: {}' },
+    AGENTIC_KEY_NOT_KEY: { severity: 'error', summary: 'an agentic process step whose key is not a GUID' },
+    AGENTIC_LOCAL_FORM_UNVERIFIED: { severity: 'error', summary: 'an agentic process step in-solution, with a form other than flow' },
+    AGENTIC_LOCAL_HAS_FOLDER: { severity: 'error', summary: 'an agentic process step in-solution, with a folderPath' },
+    AGENTIC_LOCAL_NO_PROJECT_ID: { severity: 'error', summary: 'an agentic process step in-solution, with no projectId' },
+    AGENTIC_LOCAL_PROJECT_ID_NOT_GUID: { severity: 'error', summary: 'an agentic process step in-solution, with a projectId that is not a GUID' },
+    AGENTIC_NAME_IS_PATH: { severity: 'error', summary: 'an agentic process step whose name looks like a folder path' },
+    AGENTIC_NO_FOLDER: { severity: 'error', summary: 'an agentic process step with no folderPath' },
+    AGENTIC_NO_KEY: { severity: 'error', summary: 'an agentic process step with no key' },
+    AGENTIC_NO_NAME: { severity: 'error', summary: 'an agentic process step with no name' },
+    AGENTIC_READ_NOT_OUTPUT: { severity: 'error', summary: 'an agentic process step read outside output' },
+    AGENTIC_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'an agentic process step read of a field returns does not declare' },
+    AGENTIC_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'an agentic process step field read with no returns' },
+    AGENTIC_RESERVED_INPUT: { severity: 'error', summary: 'an agentic process step with the reserved fireAndForget input' },
+    APIWF_EMPTY_RETURNS: { severity: 'warning', summary: 'an API workflow step with returns: {}' },
+    APIWF_KEY_NOT_KEY: { severity: 'error', summary: 'an API workflow step whose key is not a GUID' },
+    APIWF_NAME_IS_PATH: { severity: 'error', summary: 'an API workflow step whose name looks like a folder path' },
+    APIWF_NO_FOLDER: { severity: 'error', summary: 'an API workflow step with no folderPath' },
+    APIWF_NO_KEY: { severity: 'error', summary: 'an API workflow step with no key' },
+    APIWF_NO_NAME: { severity: 'error', summary: 'an API workflow step with no name' },
+    APIWF_READ_NOT_OUTPUT: { severity: 'error', summary: 'an API workflow step read outside output' },
+    APIWF_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'an API workflow step read of a field returns does not declare' },
+    APIWF_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'an API workflow step field read with no returns' },
+    FUNCTION_EMPTY_RETURNS: { severity: 'warning', summary: 'a function step with returns: {}' },
+    FUNCTION_KEY_NOT_KEY: { severity: 'error', summary: 'a function step whose key is not a GUID' },
+    FUNCTION_NAME_IS_PATH: { severity: 'error', summary: 'a function step whose name looks like a folder path' },
+    FUNCTION_NO_FOLDER: { severity: 'error', summary: 'a function step with no folderPath' },
+    FUNCTION_NO_KEY: { severity: 'error', summary: 'a function step with no key' },
+    FUNCTION_NO_NAME: { severity: 'error', summary: 'a function step with no name' },
+    FUNCTION_READ_NOT_OUTPUT: { severity: 'error', summary: 'a function step read outside output' },
+    FUNCTION_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'a function step read of a field returns does not declare' },
+    FUNCTION_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'a function step field read with no returns' },
+    RPA_KEY_NOT_KEY: { severity: 'error', summary: 'an RPA step whose key is not a GUID' },
+    RPA_LOCAL_HAS_FOLDER: { severity: 'error', summary: 'an RPA step in-solution, with a folderPath' },
+    RPA_LOCAL_NO_PROJECT_ID: { severity: 'error', summary: 'an RPA step in-solution, with no projectId' },
+    RPA_LOCAL_PROJECT_ID_NOT_GUID: { severity: 'error', summary: 'an RPA step in-solution, with a projectId that is not a GUID' },
+    RPA_NAME_IS_PATH: { severity: 'error', summary: 'an RPA step whose name looks like a folder path' },
+    RPA_NO_FOLDER: { severity: 'error', summary: 'an RPA step with no folderPath' },
+    RPA_NO_KEY: { severity: 'error', summary: 'an RPA step with no key' },
+    RPA_NO_NAME: { severity: 'error', summary: 'an RPA step with no name' },
+    RPA_READ_NOT_OUTPUT: { severity: 'error', summary: 'an RPA step read outside output' },
+    RPA_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'an RPA step read of a field returns does not declare' },
+    RPA_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'an RPA step field read with no returns' },
+};
+/**
+ * Check an `rpaWorkflow(...)` call.
+ *
+ * WHAT THESE RULES CAN AND CANNOT SEE. Everything about a deployed process that
+ * matters — which arguments it takes, what it returns, whether it exists —
+ * lives on the tenant. So these rules cover exactly the mistakes that are
+ * decidable from the call itself, and the doc says plainly that the rest shows
+ * up as a faulted job on a live run. What is decidable:
+ *
+ *  - a missing/blank `key`, `name` or `folderPath`. Any of the three missing
+ *    is fatal in a way no later rung reports usefully: without `key` the node
+ *    has no type suffix, and without the other two nothing can resolve the node's
+ *    `resourceBindings.name` — which reads as an engine error rather than an
+ *    authoring one.
+ *  - a `key` that is not a GUID. The commonest form of this is passing the
+ *    process's NAME where its release key belongs, which produces a node type
+ *    the platform cannot resolve to anything.
+ *  - a `name` that looks like a path (contains "/"). The two are swappable, and
+ *    the resulting `resourceKey` is wrong in a way that only surfaces as a 400
+ *    from Orchestrator ("Folder does not exist"). That is v1's own 2026-06-26
+ *    failure mode on this task. A single-segment `folderPath` is NOT decidable:
+ *    root folders and personal workspaces are one segment, so it is not flagged.
+ */
+export function checkRpaWorkflow(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    if (blank(inputs?.key) && !blank(inputs?.process)) {
+        at('RPA_NO_KEY', renamedFieldMessage('RPA', step, 'process'), `key: ${JSON.stringify(inputs.process)}`);
+    }
+    else if (blank(inputs?.key)) {
+        at('RPA_NO_KEY', `RPA step "${step}" has no \`key\`. That is the published process's release key (a GUID), and `
+            + `it becomes part of the node's type — without it there is no process to start. Find it with `
+            + `\`uip or processes list --all-folders --process-type Process\` (the row's \`Key\`).`, `key: '486edc26-0658-4ac1-92c9-1ef953927151'`);
+    }
+    else if (!GUID_RE.test(String(inputs.key).trim())) {
+        at('RPA_KEY_NOT_KEY', `RPA step "${step}"'s \`key\` is ${JSON.stringify(inputs.key)}, which is not a release key. `
+            + `\`key\` is the GUID the tenant gives the published process (it becomes the node type's suffix); `
+            + `the process's NAME goes in \`name\` and its folder in \`folderPath\`.`, `key: '<guid>', name: ${JSON.stringify(inputs.key)}`);
+    }
+    if (blank(inputs?.name)) {
+        at('RPA_NO_NAME', `RPA step "${step}" has no \`name\`. The runtime starts the job by name + folder, not by the key in `
+            + `the node type, so without it the process cannot be resolved and the run fails before dispatch.`, `name: 'RPA Workflow'`);
+    }
+    const inSolution = inputs?.location === 'in-solution';
+    if (!inSolution && blank(inputs?.folderPath)) {
+        at('RPA_NO_FOLDER', `RPA step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so the `
+            + `Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-maestro-flow/ProjectEuler RPA'`);
+    }
+    if (inSolution && blank(inputs?.projectId)) {
+        at('RPA_LOCAL_NO_PROJECT_ID', `In-solution RPA step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/process/<project>.json\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('RPA_LOCAL_PROJECT_ID_NOT_GUID', `In-solution RPA step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
+    }
+    if (inSolution && !blank(inputs?.folderPath)) {
+        at('RPA_LOCAL_HAS_FOLDER', `In-solution RPA step "${step}" also sets \`folderPath\` ${JSON.stringify(inputs.folderPath)}. An `
+            + `in-solution sibling has no folder until the solution is deployed — the platform's own manifest `
+            + `writes \`""\` — so the value would be dropped. Remove it, or drop \`location: 'in-solution'\` to `
+            + `call the published copy.`);
+    }
+    // The two are swappable by shape, and swapping them is invisible until
+    // Orchestrator answers "Folder does not exist or the user does not have access".
+    const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
+    if (name.includes('/')) {
+        at('RPA_NAME_IS_PATH', `RPA step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. \`name\` is `
+            + `the process's own name in Orchestrator; the path it lives in goes in \`folderPath\`. Together they `
+            + `form the resourceKey "<folderPath>.<name>", so swapping them points the job at nothing.`);
+    }
+}
+/**
+ * Check an `apiWorkflow(...)` call.
+ *
+ * Same three-identifier shape as `rpaWorkflow`, so the same three mistakes are
+ * decidable from the call itself (a blank field, a `key` that is not a key, and
+ * the swappable `name`/`folderPath` pair). Two things differ, and both come from
+ * the corpus rather than from the surface:
+ *
+ *  - the node type's GUID is the workflow's PROCESS key — the `Key` field of
+ *    `uip or processes list`, whose `ProcessKey` for an API workflow reads
+ *    `<name>.api.<name>` — so the command to name in the diagnostic is that one;
+ *  - `returns` matters MORE here than for rpa, because this task's whole answer is
+ *    a field of the job's output. A read with no `returns` has no schema to check (and
+ *    a read of an undeclared field is `undefined` everywhere), so both are said at
+ *    rung 1 instead — see `checkApiWorkflowRead`.
+ *
+ * What no rule here can see stays what it is: whether the workflow exists, whether
+ * it takes these argument names, whether it returns these fields. Only the tenant
+ * knows, and a wrong one is a faulted job on a live run — which is what the `job`
+ * rung is for.
+ */
+export function checkApiWorkflow(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    if (blank(inputs?.key) && !blank(inputs?.workflow)) {
+        at('APIWF_NO_KEY', renamedFieldMessage('API workflow', step, 'workflow'), `key: ${JSON.stringify(inputs.workflow)}`);
+    }
+    else if (blank(inputs?.key)) {
+        at('APIWF_NO_KEY', `API workflow step "${step}" has no \`key\`. That is the published workflow's key (a GUID), and `
+            + `it becomes part of the node's type — without it there is no workflow to invoke. Find it with `
+            + `\`uip or processes list --all-folders\` (an API workflow's ProcessKey reads "<name>.api.<name>").`, `key: 'ce857908-ee1d-4392-b552-38bcea0be29c'`);
+    }
+    else if (!GUID_RE.test(String(inputs.key).trim())) {
+        at('APIWF_KEY_NOT_KEY', `API workflow step "${step}"'s \`key\` is ${JSON.stringify(inputs.key)}, which is not a key. `
+            + `\`key\` is the GUID the tenant gives the published workflow (it becomes the node type's suffix); `
+            + `the workflow's NAME goes in \`name\` and its folder in \`folderPath\`.`, `key: '<guid>', name: ${JSON.stringify(inputs.key)}`);
+    }
+    if (blank(inputs?.name)) {
+        at('APIWF_NO_NAME', `API workflow step "${step}" has no \`name\`. The runtime starts the job by name + folder, not by the `
+            + `key in the node type, so without it the workflow cannot be resolved and the run fails before dispatch.`, `name: 'NameToAgeFixed'`);
+    }
+    if (blank(inputs?.folderPath)) {
+        at('APIWF_NO_FOLDER', `API workflow step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so the `
+            + `Orchestrator folder holding the workflow is required.`, `folderPath: 'Shared'`);
+    }
+    const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
+    if (name.includes('/')) {
+        at('APIWF_NAME_IS_PATH', `API workflow step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. `
+            + `\`name\` is the workflow's own name in Orchestrator; the path it lives in goes in \`folderPath\`. `
+            + `Together they form the resourceKey "<folderPath>.<name>", so swapping them points the job at nothing.`);
+    }
+    // An empty `returns: {}` is a statement that the workflow returns nothing, which
+    // is legal — but it is almost always a half-finished edit, and the difference
+    // between it and a missing `returns` is invisible in the emitted file.
+    if (inputs?.returns && Object.keys(inputs.returns).length === 0) {
+        ctx.report('APIWF_EMPTY_RETURNS', `API workflow step "${step}" declares \`returns: {}\` — an empty contract, which emits no output `
+            + `schema at all and so reads exactly like omitting it. If the workflow returns nothing, drop the `
+            + `key; if it returns something, name the fields.`);
+    }
+}
+/**
+ * A published FUNCTION step (Phase 5B).
+ *
+ * The same four identity mistakes as its published siblings, in this family's
+ * own vocabulary — and one of its own: a function is usually deployed into a
+ * folder of its own name, so `folderPath: 'Shared'` when the tenant says
+ * `Shared/<name>` points the binding's resourceKey at nothing.
+ */
+export function checkPublishedFunction(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    if (blank(inputs?.key)) {
+        at('FUNCTION_NO_KEY', `Function step "${step}" has no \`key\`. That is the published function's key (a GUID), and it becomes `
+            + `part of the node's type — without it there is no function to invoke. Find it with `
+            + `\`uip maestro flow registry search "uipath.core.function"\`.`, `key: '7059bdb5-fdd7-4e13-9d7b-1748aaeb129d'`);
+    }
+    else if (!GUID_RE.test(String(inputs.key).trim())) {
+        at('FUNCTION_KEY_NOT_KEY', `Function step "${step}"'s \`key\` is ${JSON.stringify(inputs.key)}, which is not a key. \`key\` is the `
+            + `GUID the tenant gives the published function (it becomes the node type's suffix); the function's NAME `
+            + `goes in \`name\` and its folder in \`folderPath\`.`, `key: '<guid>', name: ${JSON.stringify(inputs.key)}`);
+    }
+    if (blank(inputs?.name)) {
+        at('FUNCTION_NO_NAME', `Function step "${step}" has no \`name\`. The runtime resolves the function by name + folder, not by the `
+            + `key in the node type, so without it the dispatch fails before it starts.`, `name: 'acme-echo'`);
+    }
+    if (blank(inputs?.folderPath)) {
+        at('FUNCTION_NO_FOLDER', `Function step "${step}" has no \`folderPath\`. The runtime resolves the function by name + folder — and a `
+            + `function is often deployed into a folder of its OWN name, so read the folder from the tenant rather `
+            + `than assuming 'Shared'.`, `folderPath: 'Shared/acme-echo'`);
+    }
+    const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
+    if (name.includes('/')) {
+        at('FUNCTION_NAME_IS_PATH', `Function step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. \`name\` is `
+            + `the function's own name; the path it lives in goes in \`folderPath\`. Together they form the `
+            + `resourceKey "<folderPath>.<name>", so swapping them points the dispatch at nothing.`);
+    }
+    if (inputs?.returns && Object.keys(inputs.returns).length === 0) {
+        ctx.report('FUNCTION_EMPTY_RETURNS', `Function step "${step}" declares \`returns: {}\` — an empty contract, which emits no output `
+            + `schema and so reads exactly like omitting it. If the function returns nothing, drop the key.`);
+    }
+}
+/**
+ * Check an `agenticProcess(...)` call.
+ *
+ * The same three-identifier shape as `rpaWorkflow`/`apiWorkflow`, so the same
+ * mistakes are decidable from the call itself. Two things are this family's own:
+ *
+ *  - the node type's GUID is the process's own key — the `Key` field of
+ *    `uip or processes list`, whose `ProcessKey` for an agentic process reads
+ *    `<name>.agentic.<name>` — so that is the command the diagnostic names. And it
+ *    names the pagination, because `--all-folders` returns 50 rows with
+ *    `Pagination.HasMore: true` and no warning: the tenant this was written against
+ *    has 98 processes, and the agentic ones are not all in the first page.
+ *  - `fireAndForget` is a RESERVED input. It is the platform's design-time switch
+ *    (flow-v1's `FIRE_AND_FORGET_INPUT`), and its serializer destructures it OUT of
+ *    the node's inputs before emitting, so a process argument that happens to be
+ *    called `fireAndForget` never reaches the process — silently, with a green run
+ *    locally, because a runner that passes the whole envelope through sees nothing
+ *    wrong.
+ *
+ * What no rule here can see stays what it is: whether the process exists, whether
+ * it takes these argument names, whether it returns these fields. Only the tenant
+ * knows, and a wrong one is a faulted job on a live run — which is what the `job`
+ * rung is for.
+ */
+export function checkAgenticProcess(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    if (blank(inputs?.key) && !blank(inputs?.process)) {
+        at('AGENTIC_NO_KEY', renamedFieldMessage('Agentic process', step, 'process'), `key: ${JSON.stringify(inputs.process)}`);
+    }
+    else if (blank(inputs?.key)) {
+        at('AGENTIC_NO_KEY', `Agentic process step "${step}" has no \`key\`. That is the published process's key (a GUID), `
+            + `and it becomes part of the node's type — without it there is no process to start. Find it with `
+            + `\`uip or processes list --all-folders --limit 100\` (an agentic process's ProcessKey reads `
+            + `"<name>.agentic.<name>"; the listing paginates at 50, so pass a limit or scope it to a folder).`, `key: '4fc450ab-89be-4462-8fc8-21ac4c1d6fb9'`);
+    }
+    else if (!GUID_RE.test(String(inputs.key).trim())) {
+        at('AGENTIC_KEY_NOT_KEY', `Agentic process step "${step}"'s \`key\` is ${JSON.stringify(inputs.key)}, which is not a key. `
+            + `\`key\` is the GUID the tenant gives the published process (it becomes the node type's suffix); `
+            + `the process's NAME goes in \`name\` and its folder in \`folderPath\`.`, `key: '<guid>', name: ${JSON.stringify(inputs.key)}`);
+    }
+    if (blank(inputs?.name)) {
+        at('AGENTIC_NO_NAME', `Agentic process step "${step}" has no \`name\`. The runtime starts the job by name + folder, not by `
+            + `the key in the node type, so without it the process cannot be resolved and the run fails before `
+            + `dispatch.`, `name: 'ProcurementProcess'`);
+    }
+    const inSolution = inputs?.location === 'in-solution';
+    if (!inSolution && blank(inputs?.folderPath)) {
+        // `registry list --local` shows an in-solution Flow sibling with folderPath: "".
+        // An explicit `form` other than 'flow' keeps the published hint: switching it would change the node type.
+        const meantInSolution = inputs?.form === 'flow'
+            || (typeof inputs?.folderPath === 'string' && inputs?.form === undefined);
+        if (meantInSolution) {
+            const formPart = inputs?.form === 'flow' ? '' : `, form: 'flow'`;
+            at('AGENTIC_NO_FOLDER', `Agentic process step "${step}" has an empty \`folderPath\`. If the process is an unpublished sibling `
+                + `Flow in this solution, call it in-solution: set \`location: 'in-solution'\`${formPart} and \`projectId\` `
+                + `(the sibling's \`resource.projectKey\` in \`resources/solution_folder/process/flow/<project>.json\`), and `
+                + `drop \`folderPath\`. If it is published, set \`folderPath\` to the Orchestrator folder that holds it — `
+                + `the runtime starts the job by name + folder.`, `location: 'in-solution'${formPart}, projectId: '<resource.projectKey>'`);
+        }
+        else {
+            at('AGENTIC_NO_FOLDER', `Agentic process step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so `
+                + `the Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-agents/ProcurementProcess'`);
+        }
+    }
+    const form = inputs?.form ?? 'bpmn';
+    if (inSolution && form !== 'flow') {
+        at('AGENTIC_LOCAL_FORM_UNVERIFIED', `In-solution agentic process step "${step}" has \`form: ${JSON.stringify(form)}\`. Only \`form: 'flow'\` `
+            + `has been run against an in-solution sibling; the ${JSON.stringify(form)} shape is unproven. Call the `
+            + `published process instead (drop \`location\` and \`projectId\`, set \`folderPath\`), or use `
+            + `\`form: 'flow'\` if the sibling is a Flow.`, `location: 'published', folderPath: 'Shared/<folder>'`);
+    }
+    if (inSolution && blank(inputs?.projectId)) {
+        const folder = (ownEntry(AGENTIC_PROCESS_FORMS, inputs?.form ?? 'bpmn') ?? AGENTIC_PROCESS_FORMS.bpmn).solutionFolder;
+        at('AGENTIC_LOCAL_NO_PROJECT_ID', `In-solution agentic process step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/${folder}/<project>.json\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('AGENTIC_LOCAL_PROJECT_ID_NOT_GUID', `In-solution agentic process step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
+    }
+    if (inSolution && !blank(inputs?.folderPath)) {
+        at('AGENTIC_LOCAL_HAS_FOLDER', `In-solution agentic process step "${step}" also sets \`folderPath\` ${JSON.stringify(inputs.folderPath)}. An `
+            + `in-solution sibling has no folder until the solution is deployed — the platform's own manifest `
+            + `writes \`""\` — so the value would be dropped. Remove it, or drop \`location: 'in-solution'\` to `
+            + `call the published copy.`);
+    }
+    const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
+    if (name.includes('/')) {
+        at('AGENTIC_NAME_IS_PATH', `Agentic process step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. `
+            + `\`name\` is the process's own name in Orchestrator; the path it lives in goes in \`folderPath\`. `
+            + `Together they form the resourceKey "<folderPath>.<name>", so swapping them points the job at nothing.`);
+    }
+    // The platform's own design-time input, which its serializer strips before the
+    // node is emitted — so a process argument by this name is dropped on the way to
+    // the tenant and nothing local notices.
+    if (inputs?.inputs && Object.prototype.hasOwnProperty.call(inputs.inputs, 'fireAndForget')) {
+        at('AGENTIC_RESERVED_INPUT', `Agentic process step "${step}" passes an input called \`fireAndForget\`. That name is RESERVED: it is `
+            + `the platform's design-time switch for starting the process without waiting, and its serializer `
+            + `removes the key from the node's inputs before emitting — so a process argument of that name never `
+            + `arrives. Locally it would appear to work, because this engine passes the whole envelope through. `
+            + `Rename the argument, and note that this surface cannot author fire-and-forget at all (the engine `
+            + `always waits for the job).`);
+    }
+    // An empty `returns: {}` is a statement that the process returns nothing, which is
+    // legal — but it is almost always a half-finished edit, and the difference between
+    // it and a missing `returns` is invisible in the emitted file.
+    if (inputs?.returns && Object.keys(inputs.returns).length === 0) {
+        ctx.report('AGENTIC_EMPTY_RETURNS', `Agentic process step "${step}" declares \`returns: {}\` — an empty contract, which emits no output `
+            + `schema at all and so reads exactly like omitting it. If the process returns nothing, drop the key; `
+            + `if it returns something, name the fields.`);
+    }
+}
+/**
+ * How an RPA step's result read is worded — the shared `<PREFIX>_READ_*` rule
+ * the pipeline's `fields` reader runs (`checkDeclaredOutputRead`).
+ */
+export function rpaWorkflowRead(spec) {
+    return {
+        codePrefix: 'RPA',
+        label: 'RPA process',
+        whenUndeclared: `The process's output arguments live on the tenant; declare the ones you read. `
+            + `\`uip maestro flow registry get uipath.core.rpa-workflow.${spec?.key}\` shows what the platform `
+            + `synthesizes for it.`,
+    };
+}
+/** A read of a published function's result — the api-workflow rules, this family's codes. */
+export function checkPublishedFunctionRead({ node: name, field, rest, reader: step }, spec, report) {
+    if (field !== undefined && field !== 'output') {
+        report('FUNCTION_READ_NOT_OUTPUT', `Function "${name}" publishes its result under "output", but "$vars.${name}.${field}" `
+            + `(read in "${step}") asks for "${field}", which is undefined at run time.`, `out('${name}', '<field>')`);
+        return;
+    }
+    const declared = Object.keys(spec.returns ?? {});
+    const wanted = rest.replace(/^\./, '').split('.')[0];
+    if (!wanted)
+        return; // `$vars.<name>.output` — the whole object.
+    if (declared.length === 0) {
+        report('FUNCTION_READ_WITHOUT_RETURNS', `"$vars.${name}.output.${wanted}" (read in "${step}") reads a field of function "${name}"'s `
+            + `result, but the step declares no \`returns\` — so the node carries no output schema and nothing can `
+            + `tell a real field from a typo. The function's output arguments live on the tenant; declare the ones `
+            + `you read. \`uip maestro flow registry get uipath.core.function.${spec.key}\` shows what the platform `
+            + `synthesizes for it.`, `returns: { ${wanted}: 'string' }`);
+        return;
+    }
+    if (declared.includes(wanted))
+        return;
+    report('FUNCTION_READ_UNKNOWN_FIELD', `"$vars.${name}.output.${wanted}" (read in "${step}") is not one of function "${name}"'s declared `
+        + `returns (${declared.map((d) => `"${d}"`).join(', ')}), so it resolves to undefined.`, `returns: { ${wanted}: 'string' }`);
+}
+export function checkApiWorkflowRead({ node: name, field, rest, reader: step }, spec, report) {
+    if (field === undefined)
+        return; // `out('call')` — the whole output object.
+    if (field === 'error')
+        return; // the error envelope every process node declares.
+    if (field !== 'output') {
+        report('APIWF_READ_NOT_OUTPUT', `API workflow "${name}" publishes the job's output arguments under "output", but `
+            + `"$vars.${name}.${field}" (read in "${step}") asks for "${field}", which is undefined at run time.`, `out('${name}', '<field>')`);
+        return;
+    }
+    const declared = Object.keys(spec.returns ?? {});
+    const wanted = rest.replace(/^\./, '').split('.')[0];
+    if (!wanted)
+        return; // `$vars.<name>.output` — the whole object.
+    if (declared.length === 0) {
+        report('APIWF_READ_WITHOUT_RETURNS', `"$vars.${name}.output.${wanted}" (read in "${step}") reads a field of API workflow "${name}"'s `
+            + `result, but the step declares no \`returns\` — so the node carries no output schema and nothing `
+            + `can tell a real field from a typo. The workflow's output arguments live on the tenant; declare `
+            + `the ones you read. \`uip maestro flow registry get uipath.core.api-workflow.${spec.key}\` `
+            + `shows what the platform synthesizes for it.`, `returns: { ${wanted}: 'string' }`);
+        return;
+    }
+    if (declared.includes(wanted))
+        return;
+    const nearest = nearestName(wanted, declared);
+    report('APIWF_READ_UNKNOWN_FIELD', `API workflow "${name}" declares no output "${wanted}" (read as "$vars.${name}.output.${wanted}" in `
+        + `"${step}"). Its \`returns\` names: ${declared.join(', ')}. A read outside that set is undefined `
+        + `on every rung and on the platform.`, nearest !== undefined ? `out('${name}', '${nearest}')` : undefined);
+}
+/**
+ * A read of an agentic process's output: `out('<step>', '<field>')`.
+ *
+ * `waitForJob` records the job's `OutputArguments` UNWRAPPED under `output`, so the
+ * readable fields are exactly the ones `returns` declares. The three mistakes are
+ * api-workflow's, and one of them has a sharper edge here: a process may DECLARE a
+ * field and return it EMPTY (`ProcurementProcess` declares `{status: boolean}` and
+ * answers `{"status": null}` on every job), so a declared read is checkable but a
+ * non-empty VALUE is not something any offline gate can promise.
+ */
+export function checkAgenticProcessRead({ node: name, field, rest, reader: step }, spec, report) {
+    if (field === undefined)
+        return; // `out('call')` — the whole output object.
+    if (field === 'error')
+        return; // the error envelope every process node declares.
+    if (field !== 'output') {
+        report('AGENTIC_READ_NOT_OUTPUT', `Agentic process "${name}" publishes the job's output arguments under "output", but `
+            + `"$vars.${name}.${field}" (read in "${step}") asks for "${field}", which is undefined at run time.`, `out('${name}', '<field>')`);
+        return;
+    }
+    const declared = Object.keys(spec.returns ?? {});
+    const wanted = rest.replace(/^\./, '').split('.')[0];
+    if (!wanted)
+        return; // `$vars.<name>.output` — the whole object.
+    if (declared.length === 0) {
+        report('AGENTIC_READ_WITHOUT_RETURNS', `"$vars.${name}.output.${wanted}" (read in "${step}") reads a field of agentic process "${name}"'s `
+            + `result, but the step declares no \`returns\` — so the node carries no output schema and nothing can `
+            + `tell a real field from a typo. The process's output arguments live on the tenant; declare the ones `
+            + `you read. \`uip maestro flow registry get uipath.core.agentic-process.${spec.key}\` shows what `
+            + `the platform synthesizes for it.`, `returns: { ${wanted}: 'string' }`);
+        return;
+    }
+    if (declared.includes(wanted))
+        return;
+    const nearest = nearestName(wanted, declared);
+    report('AGENTIC_READ_UNKNOWN_FIELD', `Agentic process "${name}" declares no output "${wanted}" (read as "$vars.${name}.output.${wanted}" in `
+        + `"${step}"). Its \`returns\` names: ${declared.join(', ')}. A read outside that set is undefined on `
+        + `every rung and on the platform.`, nearest !== undefined ? `out('${name}', '${nearest}')` : undefined);
+}

package/dist/nodes/process/flow/factories.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The process factories — `rpaWorkflow()`, `apiWorkflow()`, `publishedFunction()`
+ * and `agenticProcess()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports them.
+ */
+import { type ActionSpec } from '../../../core/actions.js';
+import type { AgenticProcessInputs, ApiWorkflowInputs, PublishedFunctionInputs, RpaWorkflowInputs } from './spec.js';
+/**
+ * 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 declare function rpaWorkflow(inputs: RpaWorkflowInputs): ActionSpec;
+/**
+ * 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 declare function apiWorkflow(inputs: ApiWorkflowInputs): ActionSpec;
+/**
+ * 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 declare function publishedFunction(inputs: PublishedFunctionInputs): ActionSpec;
+/**
+ * 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 declare function agenticProcess(inputs: AgenticProcessInputs): ActionSpec;