@uipath/maestro-builder-sdk 6.24.0 → 6.25.0

package/dist/decompile.js

@@ -45,7 +45,7 @@ import { outputBackingGlobal, outputBackingName } from './flow-output-backing.js
 import { mapJsCode } from './core/js-code-spans.js';
 import { missingBindingLabels } from './core/binding-messages.js';
 import { prepareCommand } from './core/cli-spelling.js';
-import { OUTCOME_HANDLE_NODE_TYPES, outcomeSlug } from './core/hitl-routing.js';
+import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
 import { eventFilterFromTreeLeaf } from './core/event-filters.js';
 import { sdkFormFieldType } from './core/form-field-type.js';
@@ -226,9 +226,6 @@ const T = {
     inlineAgent: 'uipath.agent.autonomous',
     conversationalAgent: 'uipath.agent.conversational',
     voiceAgent: 'uipath.agent.voice',
-    hitlQuickForm: 'uipath.human-in-the-loop.quick-form',
-    hitlActionApp: 'uipath.human-in-the-loop.coded-action-app',
-    hitlDocValidation: 'uipath.human-in-the-loop.document-validation',
     triggerVoice: 'core.trigger.voice',
     createOutgoingCall: 'uipath.conversational.voice.create-outgoing-call',
     endCall: 'uipath.conversational.voice.end-call',
@@ -560,7 +557,7 @@ function registeredImpl(node) {
  * the node. A node at a version the type does not register is lifted by its
  * default version's implementation, as every built-in family lifts any version.
  */
-function liftRegistered(node, impl = registeredImpl(node)) {
+function liftRegistered(node, impl = registeredImpl(node), graph) {
     if (!impl)
         return undefined;
     const version = String(node.typeVersion ?? '');
@@ -574,6 +571,8 @@ function liftRegistered(node, impl = registeredImpl(node)) {
         // when the file carries none (a hand-trimmed or SDK-written file).
         definition: () => runDefs.get(`${node.type}@${version}`) ?? BUNDLED_DEFINITIONS[`${node.type}@${version}`] ?? runDefs.get(node.type),
         warn: warnOnce,
+        outPorts: () => (graph?.outEdges(node.id) ?? []).map((e) => e.sourcePort),
+        convergedFanOut: () => graph?.convergedFanOut(node.id) === true,
     };
     const spec = impl.deserialize(node, ctx);
     return spec === undefined ? undefined : { impl, spec };
@@ -586,8 +585,8 @@ function liftRegistered(node, impl = registeredImpl(node)) {
  * `{ version }` the type does not register, with a warning. `undefined` when the type is not registered, or the node type declines
  * the node; the caller's branches take it from there.
  */
-function emitRegisteredSpec(node, imp, inputNames) {
-    const lifted = liftRegistered(node);
+function emitRegisteredSpec(node, imp, inputNames, graph) {
+    const lifted = liftRegistered(node, registeredImpl(node), graph);
     if (!lifted)
         return undefined;
     const { impl, spec } = lifted;
@@ -629,7 +628,7 @@ function emitRegisteredSpec(node, imp, inputNames) {
 function emitStepSpec(node, imp, inputNames, o, graph) {
     // A registered node type lifts itself; every other type falls through to the
     // branches below until its family is ported (FB014's pins are the list).
-    const lifted = emitRegisteredSpec(node, imp, inputNames);
+    const lifted = emitRegisteredSpec(node, imp, inputNames, graph);
     if (lifted !== undefined)
         return lifted;
     switch (node.type) {
@@ -651,11 +650,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
         case T.conversationalAgent:
         case T.voiceAgent:
             return emitAgentCluster(node, imp, inputNames, graph);
-        case T.hitl:
-        case T.hitlQuickForm:
-        case T.hitlActionApp:
-        case T.hitlDocValidation:
-            return emitHitl(node, imp, inputNames, graph);
         default:
             // A connector action node: `uipath.connector.<key>.<action>` (but NOT the
             // event nodes `uipath.connector.event.*` / `.trigger.*`, which are triggers).
@@ -1260,184 +1254,6 @@ function emitAgentCluster(node, imp, inputNames, graph) {
         ['source', tsLiteral(plain(i.source) ?? '')],
     ])})`;
 }
-/**
- * A HUMAN TASK — the base node plus its three sub-typed variants.
- *
- * `hitlInputs` is the widest lowering in the serializer, so this inverts it
- * field by field. Three of its outputs are DERIVED and deliberately not
- * recovered: `schema.schemaId` (a stable hash of the flow and node ids),
- * `type: 'quick'` (the base node's discriminator), and the `variable`/`binding`
- * wiring each field row carries — all of them are re-emitted from what comes
- * back here.
- *
- * A value equal to what serialize would have DEFAULTED is omitted rather than
- * recovered: the step's own name for `title`, `'Low'` for `priority`, and the
- * definition's own `inputDefaults.recipient` for delivery. Recovering those
- * would add arguments the author never wrote to every task.
- */
-function emitHitl(node, imp, inputNames, graph) {
-    const i = (node.inputs ?? {});
-    const schema = (i.schema ?? {});
-    const plain = (v) => {
-        const raw = unwrapSource(v);
-        return raw === undefined || raw === '' ? undefined : raw;
-    };
-    const variant = node.type === T.hitlQuickForm ? 'quick-form'
-        : node.type === T.hitlActionApp ? 'action-app'
-            : node.type === T.hitlDocValidation ? 'document-validation'
-                : undefined;
-    // A field row's binding is a variable PATH (`vars.x`), not an expression —
-    // serialize rewrote the author's `$vars.x` on the way out, so put it back.
-    const bindingExpr = (v) => {
-        const raw = plain(v);
-        if (raw === undefined)
-            return undefined;
-        const js = wireExprBody(raw);
-        return emitBareExpr(js.startsWith('vars.') ? `$${js}` : js, imp, inputNames);
-    };
-    const rows = (Array.isArray(schema.fields) ? schema.fields : []);
-    const fields = rows.map((f) => {
-        const id = String(f.id ?? '');
-        const direction = String(f.direction ?? 'output');
-        return opts([
-            ['id', tsLiteral(id)],
-            // serialize defaults a row's label to its id.
-            ['label', typeof f.label === 'string' && f.label !== id ? tsLiteral(f.label) : undefined],
-            // The product's own spelling (`"string"`, `"datetime"`, …) → the SDK's (#1143).
-            ['type', tsLiteral(sdkFormFieldType(f.type ?? 'text') ?? String(f.type))],
-            ['direction', tsLiteral(direction)],
-            ['value', direction === 'input' || direction === 'inOut' ? bindingExpr(f.binding) : undefined],
-            ['required', f.required === true ? 'true' : undefined],
-        ]);
-    });
-    const outcomeRows = (Array.isArray(schema.outcomes) ? schema.outcomes : []);
-    const outcomes = outcomeRows.map((o, idx) => {
-        const name = String(o.name ?? '');
-        // The file's id comes back only when serialize would not derive it from the
-        // name: a designer-drawn task's ids (`outcome-1778015958049`) are not slugs,
-        // and merge keeps the ORIGINAL node, so recompiled edges must use its ids
-        // (#1130). An SDK-written task's ids are slugs and stay implicit.
-        const id = typeof o.id === 'string' && o.id !== '' && o.id !== outcomeSlug(name, idx) ? o.id : undefined;
-        // A bare string is the shorthand; `action: 'End'` or a kept id needs the object.
-        return o.action === 'End' || id !== undefined
-            ? opts([
-                ['name', tsLiteral(name)],
-                ['action', o.action === 'End' ? tsLiteral('End') : undefined],
-                ['id', id !== undefined ? tsLiteral(id) : undefined],
-            ])
-            : tsLiteral(name);
-    });
-    // Delivery: only an override comes back. The definition's own default is what
-    // serialize emits when the author wrote nothing.
-    const def = runDefs.get(`${node.type}@${node.typeVersion}`) ?? runDefs.get(node.type);
-    const defaultRecipient = JSON.stringify(def?.inputDefaults?.recipient ?? null);
-    const rec = i.recipient;
-    let recipientSrc;
-    if (rec !== undefined && JSON.stringify(rec) !== defaultRecipient) {
-        const assignee = (rec.assignee ?? {});
-        const channels = Array.isArray(rec.channels) ? rec.channels : undefined;
-        recipientSrc = opts([
-            ['channels', channels ? `[${channels.map((c) => tsLiteral(c)).join(', ')}]` : undefined],
-            ['assignee', opts([
-                    ['type', tsLiteral(String(assignee.type ?? 'user'))],
-                    ['value', typeof assignee.value === 'string' ? tsLiteral(assignee.value) : undefined],
-                    ['displayName', typeof assignee.displayName === 'string' ? tsLiteral(assignee.displayName) : undefined],
-                ])],
-        ]);
-    }
-    // The deployed app that owns the form (action-app, and a custom-render
-    // validation station). `appInputBindings` maps the app's own parameter names
-    // to `=`-prefixed expressions.
-    const app = i.app;
-    // `app.inputs` is a VALUE map — what to send the app, keyed by the app's own
-    // parameter names — and it lowers to a SIBLING key, `appInputBindings`, whose
-    // values are `=vars.…` paths (or literals). Not a type map, and not inside
-    // `app`: both are easy to assume and both round-trip wrong.
-    const bindings = (i.appInputBindings ?? {});
-    const appInputs = Object.keys(bindings).length === 0 ? undefined : objLit(Object.entries(bindings).map(([k, v]) => {
-        const raw = String(v ?? '');
-        return [k, raw.startsWith('=') ? emitBareExpr(wireExprBody(raw), imp, inputNames) : tsLiteral(raw)];
-    }));
-    const appSrc = app === undefined ? undefined : opts([
-        // `displayName` is serialize's echo of `name`; only `name` is authored.
-        ['name', tsText(app.name)],
-        ['key', tsText(app.key)],
-        ['folderPath', typeof app.folderPath === 'string' && app.folderPath !== '' ? tsLiteral(app.folderPath) : undefined],
-        ['appSystemName', app.appSystemName === null ? 'null'
-                : typeof app.appSystemName === 'string' ? tsLiteral(app.appSystemName) : undefined],
-        ['inputs', appInputs],
-    ]);
-    // The validation station's own inputs ride as PLAIN `$vars.…` paths. Anything
-    // but a `$vars.` reference stays the wire text verbatim.
-    const stationExpr = (v) => {
-        const raw = plain(v);
-        if (raw === undefined)
-            return undefined;
-        const js = wireExprBody(raw);
-        return js.startsWith('$vars.') ? emitBareExpr(js, imp, inputNames) : tsLiteral(raw);
-    };
-    const render = plain(i.validationRenderType);
-    const documentSrc = node.type !== T.hitlDocValidation ? undefined : opts([
-        ['extractionResult', stationExpr(i.extractionResult) ?? tsLiteral('')],
-        ['storageBucket', plain(i.storageBucket) !== undefined ? tsLiteral(plain(i.storageBucket)) : undefined],
-        ['documentId', plain(i.documentId) !== undefined ? tsLiteral(plain(i.documentId)) : undefined],
-        // 'standard' is the definition's default.
-        ['render', render !== undefined && render !== 'standard' ? tsLiteral(render) : undefined],
-        ['taxonomy', stationExpr(i.taxonomy)],
-    ]);
-    // On the base node the VERSION says it: 1.1 routes per outcome, 1.2 adds the
-    // error output (and implies the routing). Everywhere else — quick-form, a
-    // base task on 1.0 — the EDGES say it: outcomes that lead to different places
-    // are routed per outcome (`outcomePorts: true`, which a pinned 1.0 keeps at
-    // 1.0), and outcomes that all lead to one step are a fan-out, which the
-    // task's default recompiles to.
-    const version = String(node.typeVersion ?? '');
-    const exposeError = version === '1.2';
-    const outEdges = graph?.outEdges(node.id) ?? [];
-    const derivesHandles = OUTCOME_HANDLE_NODE_TYPES.has(String(node.type));
-    const outcomePorts = (node.type === T.hitl && version === '1.1')
-        || (derivesHandles && !versionRoutesHitl(node) && graph !== undefined && !graph.convergedFanOut(node.id)
-            && outEdges.some((e) => e.sourcePort.startsWith('outcome-')));
-    // A lone `completed` edge on a task with several outcomes is the shape the
-    // designer stopped drawing: before flow-workbench #3512 (09-08) it was
-    // unconditioned, so every outcome continued down it; since then Studio Web and
-    // the converter remap it to the primary outcome only. Recompiling writes one
-    // `outcome-<id>` edge per outcome to the same step — the first meaning — so
-    // this is the one place decompile→compile is deliberately not exact. Say so.
-    const legacyCompleted = derivesHandles && outcomeIdsOfNode(node).length > 1
-        && outEdges.some((e) => e.sourcePort === 'completed');
-    // Both a converged fan-out and a legacy lone `completed` mean "every outcome
-    // continues to the next step". Say so in the source with `outcomePorts: false`
-    // rather than leaving it to the `{ version }` pin, so the intent survives an
-    // author dropping the pin.
-    const fanOut = !outcomePorts && derivesHandles && !versionRoutesHitl(node) && outcomeIdsOfNode(node).length > 1
-        && (legacyCompleted || graph?.convergedFanOut(node.id) === true);
-    if (legacyCompleted) {
-        warnOnce(`human task ${tsLiteral(node.id)} leaves on the legacy 'completed' handle, which Studio Web no longer draws `
-            + `once a task has outcomes (it reads the edge as the primary outcome only). Recompiling emits one `
-            + `outcome-<id> edge per outcome to the same step, so every outcome continues — what the edge meant `
-            + `before flow-workbench #3512.`);
-    }
-    const title = plain(i.title);
-    const priority = plain(i.priority);
-    return `${imp.use('hitl')}(${opts([
-        ['variant', variant !== undefined ? tsLiteral(variant) : undefined],
-        // serialize defaults the title to the step's own name.
-        ['title', title !== undefined && title !== node.id ? tsLiteral(title) : undefined],
-        ['priority', priority !== undefined && priority !== 'Low' ? tsLiteral(priority) : undefined],
-        ['labels', plain(i.labels) !== undefined ? tsLiteral(plain(i.labels)) : undefined],
-        ['recipient', recipientSrc],
-        ['app', appSrc],
-        ['document', documentSrc],
-        // An app task and a validation station own no inline form; an empty array
-        // there is serialize's own, not the author's.
-        ['fields', fields.length ? `[${fields.join(', ')}]`
-                : (variant === 'action-app' || variant === 'document-validation') ? undefined : '[]'],
-        ['outcomes', `[${outcomes.join(', ')}]`],
-        ['outcomePorts', outcomePorts ? 'true' : fanOut ? 'false' : undefined],
-        ['exposeError', exposeError ? 'true' : undefined],
-    ])})`;
-}
 /**
  * A connector EVENT subscription, shared by the trigger (`onEvent`) and the
  * mid-flow wait (`waitForEvent`) — the same node body in both places, so the

package/dist/flow-node-registry.js

@@ -13,11 +13,12 @@ import { conversationFlowFamily } from './nodes/conversation/flow/family.js';
 import { dataFabricFlowFamily } from './nodes/data-fabric/flow/family.js';
 import { delayFlowFamily } from './nodes/delay/flow/family.js';
 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 { 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, httpFlowFamily, mockFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_FAMILIES = [aiPatternsFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
 export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });

package/dist/flow-node-type.d.ts

@@ -42,17 +42,40 @@ export interface FlowNodeContribution extends Omit<NodeContribution, 'definition
     model?: 'definition' | 'omit';
     /** The forward port the next step's edge leaves from. Default: the definition's default source handle. */
     port?: string;
+    /**
+     * Several forward ports, every one of which continues to the next step — a
+     * fan-out (a human task that does not route per outcome leaves on each
+     * outcome's handle). `endsRun` marks one the step list ends with an End
+     * instead (an `action: 'End'` outcome). Wins over `port`.
+     */
+    fanOut?: ReadonlyArray<{
+        readonly port: string;
+        readonly endsRun?: boolean;
+    }>;
+    /**
+     * `outputs` REPLACES the definition's `outputDefinition` on the node instead of
+     * being merged over it — for an instance whose output slots are its own (a
+     * human task's form decides them). Replaced outputs are written verbatim: no
+     * `{nodeId}` substitution, which a merged contribution's outputs get.
+     */
+    replaceOutputs?: boolean;
 }
 /** What `serialize` may ask of the serializer, for one placement. */
 export interface FlowSerializeContext {
     /** The step name the author gave this node. */
     readonly step: string;
+    /** The id this node is emitted under (rename-aware for a reused subflow copy). */
+    readonly nodeId: string;
+    /** The flow's id, as the file's top-level `id` carries it. */
+    readonly flowId: string;
     /**
      * The version being emitted, always set: the author's `{ version }` when the step
      * names one, else what `select()` or the default chose. It does not say whether
      * the author pinned it.
      */
     readonly version: string;
+    /** The author's `{ version }`, when the step names one; undefined when `select()` or the default chose. */
+    readonly pinnedVersion: string | undefined;
     /** Render one value (an `Expr`, or a literal) as the file stores it, with this scope's rename map. */
     render(value: unknown): unknown;
     /**
@@ -128,6 +151,17 @@ export interface FlowDeserializeContext {
     definition(): unknown;
     /** Report something the lift could not keep. Decompile prints it once. */
     warn(message: string): void;
+    /** The source ports this node's out-edges leave from, in edge order (an empty list outside a graph). */
+    outPorts(): readonly string[];
+    /**
+     * Whether this node is a human task (base or quick-form, not routing by its
+     * 1.1/1.2 version) whose every outcome in `inputs.schema.outcomes` is wired, all
+     * to ONE target, with no other exit edge: a fan-out that converges, which the
+     * source spells as continuing every outcome to the next step rather than as
+     * arms. The decompiler's graph answers it from the node's outcomes, not from
+     * the type's `exits()`, so it is `false` for any other node.
+     */
+    convergedFanOut(): boolean;
 }
 /** What `print` may ask of the decompiler. Every method returns source text. */
 export interface FlowPrintContext {
@@ -254,10 +288,20 @@ export interface FlowNodeType<Spec> extends NodeType<Spec, FlowNodeContribution,
      * and the port each leaves on — or why it has none to route. What
      * `.stepSwitch()` routes over, what an arm's `value` and a `.stepToList` port
      * are checked against, and what decompile reads a fully wired node back as.
+     * `pinnedVersion` is the author's `{ version }`, when the step names one: a
+     * human task's routing depends on whether it is pinned, not only on the version.
      * Omitted: the type has no author-declared fan-out. The `error` port is never
      * one of these (`.onError()` routes it).
      */
-    exits?(spec: Spec): DeclaredExit[] | NoExits;
+    exits?(spec: Spec, pinnedVersion?: string): DeclaredExit[] | NoExits;
+    /**
+     * Whether `port` is a forward handle the PRODUCT derives for this spec, which
+     * the definition does not list — a human task's `outcome-<id>` handles, drawn
+     * from its outcomes at every version while the definition declares only
+     * `completed`. Serialize refuses a forward port that is neither declared by
+     * the definition, an exit of the type, nor derived.
+     */
+    derivesPort?(spec: Spec, port: string): boolean;
 }
 /** A Flow node type with several versions. */
 export type FlowVersionedNodeType<Spec> = VersionedNodeType<Spec, FlowNodeContribution, FlowContexts, FlowNodeType<Spec>>;

package/dist/flow-sdk.d.ts

@@ -23,6 +23,7 @@ export * from './nodes/conversation/flow/index.js';
 export * from './nodes/data-fabric/flow/index.js';
 export * from './nodes/delay/flow/index.js';
 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/queue/flow/index.js';

package/dist/flow-sdk.js

@@ -27,6 +27,7 @@ export * from './nodes/conversation/flow/index.js';
 export * from './nodes/data-fabric/flow/index.js';
 export * from './nodes/delay/flow/index.js';
 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/queue/flow/index.js';

package/dist/flow-step-exits.js

@@ -26,5 +26,5 @@ export function stepExits(spec, pinnedVersion) {
     catch {
         impl = resolveVersion(entry.type, spec, undefined, 'exits');
     }
-    return impl.exits?.(spec) ?? declaredExits(spec, pinnedVersion);
+    return impl.exits?.(spec, pinnedVersion) ?? declaredExits(spec, pinnedVersion);
 }

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

@@ -0,0 +1,38 @@
+/**
+ * The HITL family's rules: the form, outcomes, variant and delivery of one human
+ * task (`checkHitl`), and a read of its result (`checkHitlRead`). Moved from
+ * check.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and
+ * messages unchanged. The rules that need the rest of the flow — an outcome no
+ * route takes, an outcome nothing downstream tells apart, a port the task does
+ * not draw — stay in check.ts, which walks the flow.
+ */
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { OutputPathRead } from '../../../core/nodes/node-type.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import type { HitlInputs } from './spec.js';
+export declare const HITL_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * A human task's form.
+ *
+ * Everything here is a mistake no later rung can see, which is the test for
+ * earning a place in `check` rather than in the docs: the flow compiles, deploys,
+ * and shows a person a form with something quietly missing from it. These catch it
+ * at rung 1, in the author's own vocabulary.
+ */
+export declare function checkHitl(inputs: HitlInputs, ctx: FlowCheckContext): void;
+/**
+ * A read of a human task's output: `out('<step>', '<field>')`.
+ *
+ * The node publishes an object keyed by the form's ANSWER fields plus `Action`.
+ * Two mistakes are silent at run time and both are caught here:
+ *
+ *  - reading a field the form does not answer (a shown field, or a typo) —
+ *    `undefined`, offline and deployed;
+ *  - reading `$vars.<step>.status`, the platform's own projection of the chosen
+ *    outcome. It resolves *deployed*, so the flow works in production and reads
+ *    `undefined` on this SDK's offline rungs — a divergence, which is why the read
+ *    is redirected rather than merely flagged. (A runner that derives declared
+ *    output variables resolves `status` offline as well; the surface still points
+ *    at one spelling so a flow reads the same everywhere.)
+ */
+export declare function checkHitlRead({ node: name, field, rest, reader: step }: OutputPathRead, form: HitlInputs | undefined, report: (code: string, message: string, suggestion?: string) => void): void;