@uipath/maestro-builder-sdk 6.23.0 → 6.25.0

package/dist/core/stable-id.js

@@ -91,3 +91,19 @@ export function sha256Uuid(seed) {
     const h = createHash('sha256').update(seed).digest('hex');
     return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
+/**
+ * A deterministic UUID for the form schema, derived from the flow and node ids.
+ *
+ * The platform uses `schemaId` to identify and cache a form, so it has to be
+ * stable across builds of the same flow — a random one would make every rebuild a
+ * different form and every emitted `.flow` a different file. Shaped as a v5 UUID
+ * (SHA-1 based, version + variant bits set) because that is what the field holds.
+ */
+export function schemaId(flowId, nodeId) {
+    const h = createHash('sha1').update(`uipath.human-in-the-loop:${flowId}:${nodeId}`).digest();
+    const b = Buffer.from(h.subarray(0, 16));
+    b[6] = (b[6] & 0x0f) | 0x50;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const hex = b.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/core/step-ports.d.ts

@@ -1,3 +1,27 @@
+/**
+ * The exits an action declares that the AUTHOR named — a human task's outcomes,
+ * an HTTP call's response branches — and the port each one leaves on. Every
+ * family that has them is a registered node type and declares its own
+ * (`FlowNodeType.exits`); `stepExits` in flow-step-exits.ts asks it first, and
+ * what is left here is the reason a kind has none.
+ *
+ * This is what `.stepSwitch()` routes over, and the reason it exists as a table
+ * rather than as more `if (spec.kind === …)` arms: `serialize` has to turn
+ * an arm's `value` into a port, `check` has to say which values are legal and
+ * which were left out, and `decompile` has to turn a port back into a value.
+ * Those three read the same list instead of each carrying their own copy of
+ * "how a human task names its ports".
+ *
+ * `undefined` means the family has no author-declared fan-out at all, which is
+ * what makes `.stepSwitch()` on it an error rather than a no-op.
+ *
+ * The `error` port is deliberately NOT here. It is declared by the definition
+ * rather than by the author, it exists on families that have no other fan-out,
+ * and it is already routed by `.onError()` / `.stepToList('error', …)`. Folding
+ * it in would make every action a `.stepSwitch` candidate and would put failure
+ * handling and outcome routing in one list, where an omitted arm would mean two
+ * different things.
+ */
 /** One author-named exit: the value an arm matches on, and the port it wires. */
 export interface DeclaredExit {
     /** What `.stepSwitch()`'s arm `value` matches — the outcome or branch NAME. */
@@ -31,7 +55,7 @@ type SpecLike = {
  * The author-declared exits of `spec`, or a `NoExits` explaining why there are
  * none to route.
  */
-export declare function declaredExits(spec: SpecLike | undefined, pinnedVersion?: string): DeclaredExit[] | NoExits;
+export declare function declaredExits(spec: SpecLike | undefined, _pinnedVersion?: string): DeclaredExit[] | NoExits;
 /** Narrowing helper — `declaredExits` returns one or the other. */
 export declare function hasExits(r: DeclaredExit[] | NoExits): r is DeclaredExit[];
 export {};

package/dist/core/step-ports.js

@@ -1,8 +1,9 @@
 /**
- * The exits an action declares that the AUTHOR named — a human task's outcomes —
- * and the port each one leaves on. A registered node type declares its own
- * (`FlowNodeType.exits`: an HTTP call's response branches); `stepExits` in
- * flow-step-exits.ts asks it first and falls back here.
+ * The exits an action declares that the AUTHOR named — a human task's outcomes,
+ * an HTTP call's response branches — and the port each one leaves on. Every
+ * family that has them is a registered node type and declares its own
+ * (`FlowNodeType.exits`); `stepExits` in flow-step-exits.ts asks it first, and
+ * what is left here is the reason a kind has none.
  *
  * This is what `.stepSwitch()` routes over, and the reason it exists as a table
  * rather than as more `if (spec.kind === …)` arms: `serialize` has to turn
@@ -21,54 +22,12 @@
  * handling and outcome routing in one list, where an omitted arm would mean two
  * different things.
  */
-import { hitlExitModel } from './hitl-routing.js';
 /**
  * The author-declared exits of `spec`, or a `NoExits` explaining why there are
  * none to route.
  */
-export function declaredExits(spec, pinnedVersion) {
+export function declaredExits(spec, _pinnedVersion) {
     const kind = spec && 'kind' in spec ? spec.kind : undefined;
-    if (kind === 'hitl') {
-        const inputs = spec?.inputs;
-        const model = hitlExitModel(inputs, pinnedVersion);
-        if (model.shape === 'placeholder') {
-            // WHY it has no outcome exits decides what the author can do about it, so
-            // the caller gets the specific one rather than "ports are off".
-            if ((inputs?.outcomes ?? []).length === 0) {
-                return { reason: 'it declares no outcomes', suggestion: `outcomes: ['Approve', 'Reject']` };
-            }
-            return {
-                reason: `the '${inputs?.variant}' variant reads its outcomes from its app and leaves on its single 'completed' exit`,
-                suggestion: `Use .step() and switch on out('<step>', 'Action').`,
-            };
-        }
-        // A quick-form task and a pinned one continue every outcome under `.step()`,
-        // but their outcome handles are real, so `.stepSwitch` routes them. The
-        // other fan-out reasons leave nothing to route.
-        if (model.shape === 'every-outcome' && model.why !== 'quick-form' && model.why !== 'pinned') {
-            if (model.why === 'outcomePorts: false') {
-                return {
-                    reason: 'outcomePorts: false continues every outcome to the next step',
-                    suggestion: 'Drop `outcomePorts: false`.',
-                };
-            }
-            if (model.why === 'one outcome') {
-                return {
-                    reason: 'a single outcome has a single exit, so there is nothing to route',
-                    suggestion: 'Use .step() — the next step follows it unconditionally.',
-                };
-            }
-            return {
-                reason: 'every outcome ends the process, so no exit distinguishes them',
-                suggestion: 'Use .step().',
-            };
-        }
-        return model.exits.map((e) => ({
-            value: e.value,
-            port: e.port,
-            ...(e.endsProcess ? { endsProcess: true } : {}),
-        }));
-    }
     return {
         reason: `a ${kind ?? 'custom'} step declares no author-named exits`,
         suggestion: 'Use .step(); route failures with .onError().',

package/dist/core/typed-raw-node.js

@@ -32,19 +32,8 @@ export const TYPED_FACTORIES = {
     'uipath.agent.autonomous': { factory: 'inlineAgent()' },
     'uipath.agent.conversational': { factory: 'conversationalAgent()' },
     'uipath.agent.voice': { factory: 'voiceAgent()' },
-    'uipath.conversational.get-conversation-context': { factory: 'conversationContext()' },
-    'uipath.conversational.send-message': { factory: 'sendMessage()' },
     'uipath.conversational.voice.create-outgoing-call': { factory: 'createOutgoingCall()' },
     'uipath.conversational.voice.end-call': { factory: 'endCall()' },
-    'uipath.conversational.wait-for-message': { factory: 'waitForMessage()' },
-    'uipath.human-in-the-loop': { factory: 'hitl()' },
-    'uipath.human-in-the-loop.coded-action-app': {
-        factory: "hitl({ variant: 'action-app' })",
-    },
-    'uipath.human-in-the-loop.document-validation': {
-        factory: "hitl({ variant: 'document-validation' })",
-    },
-    'uipath.human-in-the-loop.quick-form': { factory: "hitl({ variant: 'quick-form' })" },
 };
 /**
  * A reminder, as a `warning`, that a `rawNode` stands in for a typed factory,

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,12 +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',
-    sendMessage: 'uipath.conversational.send-message',
-    waitForMessage: 'uipath.conversational.wait-for-message',
-    conversationContext: 'uipath.conversational.get-conversation-context',
     triggerVoice: 'core.trigger.voice',
     createOutgoingCall: 'uipath.conversational.voice.create-outgoing-call',
     endCall: 'uipath.conversational.voice.end-call',
@@ -563,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 ?? '');
@@ -577,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 };
@@ -589,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;
@@ -632,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) {
@@ -654,52 +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);
-        case T.sendMessage:
-        case T.waitForMessage:
-        case T.conversationContext: {
-            // The fixed enum fields (`role`/`mimeType`/`from`) come from the
-            // definition's defaults, so nothing of them is recovered — only what an
-            // author could have written.
-            const i = (node.inputs ?? {});
-            const v = (x) => {
-                const raw = typeof x === 'string' ? x : String(x?.expression ?? x ?? '');
-                return raw.startsWith('=js:') ? emitBareExpr(raw.slice(4), imp, inputNames)
-                    : raw.startsWith('$vars.') ? emitBareExpr(raw, imp, inputNames)
-                        : tsLiteral(raw);
-            };
-            const num = (x) => {
-                if (x === undefined || x === null)
-                    return undefined;
-                const n = Number(x?.expression ?? x);
-                return Number.isFinite(n) ? String(n) : undefined;
-            };
-            const cid = ['conversationId', v(i.conversationId)];
-            if (node.type === T.sendMessage) {
-                return `${imp.use('sendMessage')}(${opts([
-                    cid,
-                    ['exchangeId', v(i.exchangeId)],
-                    ['content', v(i.content)],
-                    // The definition defaults `endExchange` to false; only a departure
-                    // from the default is something the author wrote.
-                    ['endExchange', i.endExchange === true ? 'true' : undefined],
-                ])})`;
-            }
-            if (node.type === T.waitForMessage) {
-                return `${imp.use('waitForMessage')}(${opts([
-                    cid,
-                    ['numExchanges', num(i.numExchanges) === '20' ? undefined : num(i.numExchanges)],
-                ])})`;
-            }
-            return `${imp.use('conversationContext')}(${opts([
-                cid,
-                ['exchangeLimit', num(i.exchangeLimit) === '20' ? undefined : num(i.exchangeLimit)],
-            ])})`;
-        }
         default:
             // A connector action node: `uipath.connector.<key>.<action>` (but NOT the
             // event nodes `uipath.connector.event.*` / `.trigger.*`, which are triggers).
@@ -1304,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

@@ -9,14 +9,16 @@
 import { NodeTypeRegistry } from './core/nodes/registry.js';
 import { hasBundledDefinition } from './flow-definitions.js';
 import { aiPatternsFlowFamily } from './nodes/ai-patterns/flow/family.js';
+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, 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

@@ -19,9 +19,11 @@
 export * from './core/expr.js';
 export * from './core/actions.js';
 export * from './nodes/ai-patterns/flow/index.js';
+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

@@ -23,9 +23,11 @@ export * from './core/expr.js';
 export * from './core/actions.js';
 // Node families' public surfaces (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §8).
 export * from './nodes/ai-patterns/flow/index.js';
+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/conversation/flow/check.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The conversation family's rules. Moved from check.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and messages unchanged.
+ */
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+export declare const CONVERSATION_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * A conversational step (Phase 5C): send-message, wait-for-message, or
+ * get-conversation-context.
+ *
+ * Everything here is decidable offline and invisible later: the node's own
+ * schema requires `conversationId` (and `exchangeId`/`content` on send), and
+ * the two numeric limits are range-checked by the designer but silently
+ * clamped at run time.
+ */
+export declare function checkConversational(kind: 'sendMessage' | 'waitForMessage' | 'conversationContext', inputs: Record<string, unknown> | undefined, ctx: FlowCheckContext): void;