@uipath/maestro-builder-sdk 6.40.1 → 6.41.0

package/dist/core/nodes/versioned.d.ts

@@ -12,7 +12,19 @@ export interface VersionedNodeType<Spec, Serialized, Ctx extends ArtifactContext
 /** The implementation type: an artifact's own extension of NodeType, when it has one. */
 Impl extends NodeType<Spec, Serialized, Ctx> = NodeType<Spec, Serialized, Ctx>> {
     readonly kind: string;
+    /**
+     * The type name in the file. For a type that owns a FAMILY of names
+     * (`typeNamePrefix`), the prefix followed by `*` — what messages name it by.
+     */
     readonly typeName: string;
+    /**
+     * Set for a node type whose name carries the resource it calls, so one
+     * implementation owns every name that starts with it: a published function is
+     * `uipath.core.function.<key>`. `typeName` is then this prefix plus `*`, and
+     * the definition the type supplies names the actual node type. Such a type is
+     * per-tenant: no definition could be bundled for a name the SDK cannot know.
+     */
+    readonly typeNamePrefix?: string;
     readonly factory: string;
     /** The version used when the author names none. Changing it is a breaking change. */
     readonly defaultVersion: string;

package/dist/core/nodes/versioned.js

@@ -71,10 +71,15 @@ export function resolveVersionCarried(t, spec, requested, where, carried) {
         // Refused: name both sources, and the way to add the second one.
         const registered = Object.keys(t.versions).sort().join(', ');
         const carriedVersions = [...(carried?.versions?.(t.typeName) ?? [])].sort();
+        // A carried definition is keyed by its concrete name, so it can never answer
+        // a type that owns the names under a prefix: do not offer it as the remedy.
+        const remedy = t.typeNamePrefix !== undefined
+            ? '. Versions are exact — omit { version } to use the default, or request one listed here.'
+            : '. Versions are exact — omit { version } to use the default, request one listed here, or carry '
+                + "that version's definition (the .flow file's definitions[] entry) with .definitions([...]).";
         throw new Error(`${where} requests ${t.typeName}@${requested}, but this SDK registers only ${registered}`
             + (carriedVersions.length > 0 ? ` and the flow carries only ${carriedVersions.join(', ')}` : '')
-            + '. Versions are exact — omit { version } to use the default, request one listed here, or carry '
-            + "that version's definition (the .flow file's definitions[] entry) with .definitions([...]).");
+            + remedy);
     }
     const impl = resolveVersion(t, spec, requested, where);
     return { impl, version: impl.version };

package/dist/core/process-resource.d.ts

@@ -0,0 +1,102 @@
+/**
+ * core/process-resource — what every process-resource node (an RPA process, an
+ * API workflow, a published function, an agentic process, an agent) shares: its
+ * definition's shape, where the resource lives, and the one binding pair per
+ * process it references. The process node family (nodes/process/flow/) builds
+ * the four process definitions with these; serialize uses them for the agent,
+ * the agents' process tools, and a raw node's process bindings.
+ */
+import type { ProcessLocation } from './actions.js';
+/** Every `resourceSubType` a process-resource binding pair can carry. */
+export type ProcessResourceSubType = 'Process' | 'Api' | 'ProcessOrchestration' | 'Flow' | 'CaseManagement' | 'Agent' | 'Function';
+/**
+ * What a process-resource definition builder returns. Only the binding subtype is
+ * typed, so a misspelled `resourceSubType` in a builder fails `tsc`; the emit path
+ * copies it onto the bindings pair.
+ */
+export interface ProcessResourceDef {
+    [field: string]: any;
+    model: {
+        [field: string]: any;
+        bindings: {
+            [field: string]: any;
+            resourceSubType: ProcessResourceSubType;
+        };
+    };
+}
+/**
+ * Where a process resource lives, as ONE slot every process-resource definition
+ * shares. In the platform model "in this solution" is orthogonal to the
+ * resource type: flow-core's single `createModel` (`@uipath/flow-core`
+ * `manifest/mappers/node-manifest-builder.ts`, what `uip maestro flow registry
+ * get --local` and Studio Web both run) adds `projectId`, `projectName` and
+ * `isInSolution: true` to the model of ANY process resource built from a sibling
+ * project.
+ *
+ * The in-solution shape, transcribed from `registry get --local` for a sibling
+ * Flow (2026-10-08) and from uipath-cli's `buildInSolutionNodeManifests`:
+ *  - `resourceKey` is the bare key (the sibling's `resource.key`), not
+ *    `<folderPath>.<name>`; the folder default is `''`;
+ *  - no `section: 'Published'`;
+ *  - `projectId` on the definition AND on the model, with `projectName` and
+ *    `isInSolution: true` (the marker the canvas reads);
+ *  - description `(In-solution) <name>`, tags `in-solution` / `local`, and the
+ *    `open-workflow` toolbar action.
+ */
+export declare function processResourceLocation(spec: {
+    key: string;
+    name: string;
+    folderPath?: string;
+    location?: ProcessLocation;
+    projectId?: string;
+}): {
+    inSolution: boolean;
+    folderPath: string;
+    resourceKey: string;
+    description: string;
+    tags: string[];
+    /** Spread onto the definition, before `model`. */
+    definitionExtras: Record<string, unknown>;
+    /** Spread onto `model` after `bindings`; `section` for a published resource. */
+    modelExtras: Record<string, unknown>;
+};
+/**
+ * The two bindings a process reference always carries — `name` + `folderPath`,
+ * both keyed to the SAME `resourceKey`, which is how the node (via its
+ * definition's `model.bindings.resourceKey`) finds them. 45 of 45 deployed rpa
+ * instances and 42 of 42 deployed api-workflow instances have exactly these two,
+ * and no more.
+ *
+ * ONE PAIR PER PROCESS, not per step. Bindings are addressed by
+ * `resource + resourceKey + propertyAttribute` — the key a bindings lookup map is
+ * built on — so a second pair for the same process is not a second
+ * reference: it is a duplicate that SHADOWS the first, both steps resolve to
+ * whichever was inserted last, and the loser sits in the file referenced by
+ * nothing. This is the shape PR 12 filed against the rpa family (the queue
+ * emitter already avoided it) and the ride-along this card owns; the ids now come
+ * from the process rather than from a step name, so two steps starting the same
+ * process share one pair.
+ */
+export declare function processResourceBindings(spec: {
+    name: string;
+    folderPath: string;
+    resourceSubType: ProcessResourceSubType;
+    resourceKey?: string;
+}, existing: ReadonlyMap<string, any>): {
+    ids: {
+        name: string;
+        folderPath: string;
+    };
+    entries: any[];
+};
+/**
+ * The four published-resource factories once each named the release key
+ * differently — `rpaWorkflow({process})`, `apiWorkflow({workflow})`,
+ * `agenticProcess({process})`, `agent({agent})` — for one identical thing: the
+ * GUID in a process's `Key` field. They are all `key` now.
+ *
+ * Flows authored against the old names would otherwise fail as "has no `key`",
+ * which points at the wrong problem. When the retired field is the one carrying a
+ * value, say so and name the replacement.
+ */
+export declare function renamedFieldMessage(label: string, step: string, oldField: string): string;

package/dist/core/process-resource.js

@@ -0,0 +1,118 @@
+/**
+ * Where a process resource lives, as ONE slot every process-resource definition
+ * shares. In the platform model "in this solution" is orthogonal to the
+ * resource type: flow-core's single `createModel` (`@uipath/flow-core`
+ * `manifest/mappers/node-manifest-builder.ts`, what `uip maestro flow registry
+ * get --local` and Studio Web both run) adds `projectId`, `projectName` and
+ * `isInSolution: true` to the model of ANY process resource built from a sibling
+ * project.
+ *
+ * The in-solution shape, transcribed from `registry get --local` for a sibling
+ * Flow (2026-10-08) and from uipath-cli's `buildInSolutionNodeManifests`:
+ *  - `resourceKey` is the bare key (the sibling's `resource.key`), not
+ *    `<folderPath>.<name>`; the folder default is `''`;
+ *  - no `section: 'Published'`;
+ *  - `projectId` on the definition AND on the model, with `projectName` and
+ *    `isInSolution: true` (the marker the canvas reads);
+ *  - description `(In-solution) <name>`, tags `in-solution` / `local`, and the
+ *    `open-workflow` toolbar action.
+ */
+export function processResourceLocation(spec) {
+    if (spec.location === 'in-solution') {
+        return {
+            inSolution: true,
+            folderPath: '',
+            resourceKey: spec.key,
+            description: `(In-solution) ${spec.name}`,
+            tags: ['in-solution', 'local'],
+            definitionExtras: {
+                toolbarExtensions: {
+                    design: { actions: [{ id: 'open-workflow', icon: 'external-link', label: 'Open' }] },
+                },
+                projectId: spec.projectId,
+            },
+            modelExtras: { projectId: spec.projectId, projectName: spec.name, isInSolution: true },
+        };
+    }
+    const folderPath = spec.folderPath ?? '';
+    return {
+        inSolution: false,
+        folderPath,
+        resourceKey: `${folderPath}.${spec.name}`,
+        description: `(${folderPath})`,
+        tags: [],
+        definitionExtras: {},
+        modelExtras: {},
+    };
+}
+/**
+ * The two bindings a process reference always carries — `name` + `folderPath`,
+ * both keyed to the SAME `resourceKey`, which is how the node (via its
+ * definition's `model.bindings.resourceKey`) finds them. 45 of 45 deployed rpa
+ * instances and 42 of 42 deployed api-workflow instances have exactly these two,
+ * and no more.
+ *
+ * ONE PAIR PER PROCESS, not per step. Bindings are addressed by
+ * `resource + resourceKey + propertyAttribute` — the key a bindings lookup map is
+ * built on — so a second pair for the same process is not a second
+ * reference: it is a duplicate that SHADOWS the first, both steps resolve to
+ * whichever was inserted last, and the loser sits in the file referenced by
+ * nothing. This is the shape PR 12 filed against the rpa family (the queue
+ * emitter already avoided it) and the ride-along this card owns; the ids now come
+ * from the process rather than from a step name, so two steps starting the same
+ * process share one pair.
+ */
+export function processResourceBindings(spec, existing) {
+    const resourceKey = spec.resourceKey ?? `${spec.folderPath}.${spec.name}`;
+    const found = (attr) => [...existing.values()].find((b) => b.resource === 'process' && b.resourceKey === resourceKey && b.propertyAttribute === attr)?.id;
+    const already = { name: found('name'), folderPath: found('folderPath') };
+    if (already.name && already.folderPath) {
+        return { ids: { name: already.name, folderPath: already.folderPath }, entries: [] };
+    }
+    // A readable, stable id per process. Two processes sharing a NAME across folders
+    // would collide, so the id is suffixed until it is free — the queue emitter's
+    // shape, which this is a port of.
+    const slug = spec.name.replace(/[^A-Za-z0-9]/g, '') || 'Process';
+    let base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}`;
+    for (let n = 2; existing.has(`${base}Name`) || existing.has(`${base}FolderPath`); n++) {
+        base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}${n}`;
+    }
+    const ids = { name: `${base}Name`, folderPath: `${base}FolderPath` };
+    return { ids, entries: [
+            {
+                id: ids.name,
+                name: 'name',
+                type: 'string',
+                resource: 'process',
+                resourceKey,
+                default: spec.name,
+                propertyAttribute: 'name',
+                resourceSubType: spec.resourceSubType,
+            },
+            {
+                id: ids.folderPath,
+                name: 'folderPath',
+                type: 'string',
+                resource: 'process',
+                resourceKey,
+                default: spec.folderPath,
+                propertyAttribute: 'folderPath',
+                resourceSubType: spec.resourceSubType,
+            },
+        ] };
+}
+/**
+ * The four published-resource factories once each named the release key
+ * differently — `rpaWorkflow({process})`, `apiWorkflow({workflow})`,
+ * `agenticProcess({process})`, `agent({agent})` — for one identical thing: the
+ * GUID in a process's `Key` field. They are all `key` now.
+ *
+ * Flows authored against the old names would otherwise fail as "has no `key`",
+ * which points at the wrong problem. When the retired field is the one carrying a
+ * value, say so and name the replacement.
+ */
+export function renamedFieldMessage(label, step, oldField) {
+    return (`${label} step "${step}" uses \`${oldField}\`, which was renamed to \`key\`. All four ` +
+        `published-resource factories now take \`key\` — the GUID in the process's \`Key\` field ` +
+        `(\`uip or processes list\`) — so they read the same way. Rename \`${oldField}:\` to \`key:\`.`);
+}

package/dist/decompile.js

@@ -183,6 +183,12 @@ function verClause(node) {
  */
 function shippedVersions(type) {
     const registered = FLOW_NODE_TYPES.byTypeName(type);
+    // A type that owns the names under a prefix (`uipath.core.api-workflow.<key>`)
+    // resolves a pin by its `<prefix>*` name, which no carried definition has, so
+    // it is treated as resolving its version elsewhere: its pin is kept and no
+    // `.definitions([...])` is offered that compile could not use (#1218).
+    if (registered?.type.typeNamePrefix !== undefined)
+        return [];
     return registered ? Object.keys(registered.type.versions) : bundledVersions(type);
 }
 /**
@@ -1624,18 +1630,11 @@ function legacyAgentTemplateInput(v) {
     return { ...o, type: 'jsExpression', expression: m[1] };
 }
 function emitPublishedResource(node, imp, inputNames) {
+    // The published AGENT resource — the same shape as the process family's
+    // node types (identity in the definition's binding pair, contract in its
+    // output schema), which lift themselves (nodes/process/flow/).
     const FAMILIES = [
-        { prefix: 'uipath.core.rpa-workflow.', factory: 'rpaWorkflow' },
-        { prefix: 'uipath.core.api-workflow.', factory: 'apiWorkflow' },
-        { prefix: 'uipath.core.function.', factory: 'publishedFunction' },
-        // The published AGENT resource — same shape as its siblings (identity in
-        // the definition's binding pair, contract in its output schema).
         { prefix: 'uipath.core.agent.', factory: 'agent' },
-        // The Agentic Process umbrella: one factory, three wire identities. `bpmn`
-        // is the default form, so only the other two name it.
-        { prefix: 'uipath.core.agentic-process.', factory: 'agenticProcess' },
-        { prefix: 'uipath.core.flow.', factory: 'agenticProcess', form: 'flow' },
-        { prefix: 'uipath.core.case-management.', factory: 'agenticProcess', form: 'case' },
     ];
     const family = FAMILIES.find((f) => node.type.startsWith(f.prefix));
     if (!family)

package/dist/flow-node-registry.js

@@ -16,9 +16,10 @@ import { documentFlowFamily } from './nodes/document/flow/family.js';
 import { hitlFlowFamily } from './nodes/hitl/flow/family.js';
 import { httpFlowFamily } from './nodes/http/flow/family.js';
 import { mockFlowFamily } from './nodes/mock/flow/family.js';
+import { processFlowFamily } from './nodes/process/flow/family.js';
 import { queueFlowFamily } from './nodes/queue/flow/family.js';
 import { scriptFlowFamily } from './nodes/script/flow/family.js';
 import { transformFlowFamily } from './nodes/transform/flow/family.js';
 /** The families, in no significant order. Adding one is the whole of registering it. */
-export const FLOW_NODE_FAMILIES = [aiPatternsFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_FAMILIES = [aiPatternsFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
 export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });

package/dist/flow-sdk.d.ts

@@ -26,6 +26,7 @@ export * from './nodes/document/flow/index.js';
 export * from './nodes/hitl/flow/index.js';
 export * from './nodes/http/flow/index.js';
 export * from './nodes/mock/flow/index.js';
+export * from './nodes/process/flow/index.js';
 export * from './nodes/queue/flow/index.js';
 export * from './nodes/script/flow/index.js';
 export * from './nodes/transform/flow/index.js';

package/dist/flow-sdk.js

@@ -30,6 +30,7 @@ export * from './nodes/document/flow/index.js';
 export * from './nodes/hitl/flow/index.js';
 export * from './nodes/http/flow/index.js';
 export * from './nodes/mock/flow/index.js';
+export * from './nodes/process/flow/index.js';
 export * from './nodes/queue/flow/index.js';
 export * from './nodes/script/flow/index.js';
 export * from './nodes/transform/flow/index.js';

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

@@ -0,0 +1,112 @@
+/**
+ * The process family's rules: what is decidable from the call to `rpaWorkflow()`,
+ * `apiWorkflow()`, `publishedFunction()` or `agenticProcess()` (the three
+ * identifiers, the in-solution location, `returns`), and a read of each one's
+ * result. Moved from check.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md;
+ * codes and messages unchanged. Whether the process exists, takes these
+ * arguments or returns these fields is the tenant's to say.
+ */
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { FieldsRead, OutputPathRead } from '../../../core/nodes/node-type.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import type { AgenticProcessInputs, ApiWorkflowInputs, PublishedFunctionInputs, RpaWorkflowInputs } from './spec.js';
+export declare const PROCESS_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * 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 declare function checkRpaWorkflow(inputs: RpaWorkflowInputs | undefined, ctx: FlowCheckContext): void;
+/**
+ * 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 declare function checkApiWorkflow(inputs: ApiWorkflowInputs | undefined, ctx: FlowCheckContext): void;
+/**
+ * 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 declare function checkPublishedFunction(inputs: PublishedFunctionInputs | undefined, ctx: FlowCheckContext): void;
+/**
+ * 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 declare function checkAgenticProcess(inputs: AgenticProcessInputs | undefined, ctx: FlowCheckContext): void;
+/**
+ * How an RPA step's result read is worded — the shared `<PREFIX>_READ_*` rule
+ * the pipeline's `fields` reader runs (`checkDeclaredOutputRead`).
+ */
+export declare function rpaWorkflowRead(spec: RpaWorkflowInputs | undefined): FieldsRead;
+/** A read of a published function's result — the api-workflow rules, this family's codes. */
+export declare function checkPublishedFunctionRead({ node: name, field, rest, reader: step }: OutputPathRead, spec: PublishedFunctionInputs, report: (code: string, message: string, suggestion?: string) => void): void;
+export declare function checkApiWorkflowRead({ node: name, field, rest, reader: step }: OutputPathRead, spec: ApiWorkflowInputs, report: (code: string, message: string, suggestion?: string) => void): void;
+/**
+ * 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 declare function checkAgenticProcessRead({ node: name, field, rest, reader: step }: OutputPathRead, spec: AgenticProcessInputs, report: (code: string, message: string, suggestion?: string) => void): void;