@uipath/maestro-builder-sdk 6.24.0 → 6.25.1

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

@@ -0,0 +1,357 @@
+import { Expr } from '../../../core/expr.js';
+import { nearestName } from '../../../core/edit-distance.js';
+import { FORM_FIELD_TYPES, formFieldTypeHint, formFieldTypeWhy } from '../../../core/form-field-type.js';
+import { isAnswerField } from '../../../core/hitl-answers.js';
+import { hitlDerivesOutcomeHandles, outcomeIdOf } from '../../../core/hitl-routing.js';
+export const HITL_DIAGNOSTICS = {
+    HITL_VARIANT_UNKNOWN: { severity: 'error', summary: 'a variant that names no human-task node type' },
+    HITL_OUTCOME_PORTS_VARIANT: { severity: 'error', summary: 'exposeError or outcomePorts on a variant that cannot honour it' },
+    HITL_DOCUMENT_WITHOUT_VARIANT: { severity: 'error', summary: 'a document on a task that is not a validation station' },
+    HITL_DOCVAL_WITH_FIELDS: { severity: 'error', summary: 'form fields on a validation station' },
+    HITL_DOCVAL_NO_DOCUMENT: { severity: 'error', summary: 'a validation station with no document' },
+    DOCVAL_NO_EXTRACTION: { severity: 'error', summary: 'a validation station with no extractionResult' },
+    DOCVAL_TAXONOMY_REQUIRED: { severity: 'error', summary: 'a custom-rendered validation station with no taxonomy' },
+    DOCVAL_RENDER_UNKNOWN: { severity: 'error', summary: 'a render type the station does not know' },
+    HITL_APP_WITHOUT_VARIANT: { severity: 'error', summary: 'an app on a task whose form lives in the flow' },
+    HITL_APP_WITH_FIELDS: { severity: 'error', summary: 'form fields on an app-backed task' },
+    HITL_APP_MISSING: { severity: 'error', summary: 'an action-app task that names no app' },
+    HITL_APP_INCOMPLETE: { severity: 'error', summary: 'an app reference missing name, key or folderPath' },
+    HITL_NO_FIELDS: { severity: 'error', summary: 'no fields array' },
+    HITL_FIELD_NO_ID: { severity: 'error', summary: 'a form field with no id' },
+    HITL_DUP_FIELD: { severity: 'error', summary: 'a form field id declared twice' },
+    HITL_FIELD_RESERVED_ID: { severity: 'error', summary: 'a form field id the result already uses' },
+    HITL_FIELD_TYPE_UNKNOWN: { severity: 'error', summary: 'a form field type the platform does not recognize' },
+    HITL_FIELD_NO_VALUE: { severity: 'error', summary: 'a shown field with no value' },
+    HITL_FIELD_VALUE_NOT_REF: { severity: 'error', summary: 'a shown field filled from a literal' },
+    HITL_FIELD_VALUE_NOT_PATH: { severity: 'error', summary: 'a shown field filled from a computed expression' },
+    HITL_FIELD_DIRECTION: { severity: 'error', summary: 'a field direction that is not input, output or inOut' },
+    HITL_NO_OUTCOMES: { severity: 'error', summary: 'no outcomes, so the task never completes' },
+    HITL_OUTCOME_BAD_ID: { severity: 'error', summary: 'an outcome id that is not a non-empty string' },
+    HITL_DUP_OUTCOME_ID: { severity: 'error', summary: 'two outcomes on one id' },
+    HITL_OUTCOME_NO_NAME: { severity: 'error', summary: 'an outcome with no name' },
+    HITL_DUP_OUTCOME: { severity: 'error', summary: 'an outcome name declared twice' },
+    HITL_OUTCOME_ACTION: { severity: 'error', summary: 'an outcome action other than Continue or End' },
+    HITL_CHANNEL_UNKNOWN: { severity: 'error', summary: 'a delivery channel the platform does not recognize' },
+    HITL_RECIPIENT_TYPE: { severity: 'error', summary: 'an assignee type the platform does not recognize' },
+    HITL_RECIPIENT_VALUE: { severity: 'warning', summary: 'a custom assignment with no value' },
+    HITL_READ_STATUS: { severity: 'error', summary: 'a read of the status projection instead of output.Action' },
+    HITL_READ_NOT_OUTPUT: { severity: 'error', summary: 'a read of the task outside output' },
+    HITL_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'a read of a field the form does not answer' },
+};
+/** Names the human task's own result already uses — an answer cannot claim one. */
+const RESERVED_ANSWER_IDS = new Set(['output', 'status', 'Action']);
+/**
+ * The human-task node types `variant` can name. `document-validation` resolves
+ * from the BUNDLED workbench manifest (the tenant registry does not serve the
+ * family — same availability note as do-while).
+ */
+const HITL_VARIANTS = ['quick-form', 'action-app', 'document-validation'];
+/**
+ * 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 function checkHitl(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    // Which of the three human-task node types this step emits. The two suffixed
+    // variants differ in exactly one authoring-visible way — who OWNS the form —
+    // and that is what the next four rules are about.
+    const variant = inputs?.variant;
+    if (variant !== undefined && variant !== 'quick-form' && variant !== 'action-app'
+        && variant !== 'document-validation') {
+        const nearest = nearestName(String(variant), HITL_VARIANTS);
+        at('HITL_VARIANT_UNKNOWN', `Human task "${step}" names the variant ${JSON.stringify(variant)}, which is not a human-task `
+            + `node type that resolves on this tenant. Valid: ${HITL_VARIANTS.join(', ')} — or omit it for `
+            + `the default node type (uipath.human-in-the-loop).`, nearest !== undefined ? `variant: '${nearest}'` : `Omit \`variant\`.`);
+        return;
+    }
+    const isApp = variant === 'action-app';
+    const isDocval = variant === 'document-validation';
+    // The error output is the BASE node's 1.2 definition, which no variant has.
+    // Per-outcome exits are not a version question: quick-form draws one handle
+    // per outcome like the base node, so it may ask for them; the two app-backed
+    // variants read their outcomes from the app and leave on `completed`.
+    if (variant !== undefined
+        && (inputs?.exposeError === true || (inputs?.outcomePorts === true && !hitlDerivesOutcomeHandles(variant)))) {
+        at('HITL_OUTCOME_PORTS_VARIANT', inputs?.exposeError === true
+            ? `Human task "${step}" asks for exposeError, but its variant is "${variant}" — the error output `
+                + `exists only on the base node type's 1.2 definition.`
+            : `Human task "${step}" asks for outcomePorts, but its variant is "${variant}", which reads its `
+                + `outcomes from its app and leaves on its single 'completed' exit.`, inputs?.exposeError === true
+            ? 'Omit `variant`, or drop exposeError.'
+            : `Route on out('${step}', 'Action') downstream.`);
+        return;
+    }
+    if (inputs?.document !== undefined && !isDocval) {
+        at('HITL_DOCUMENT_WITHOUT_VARIANT', `Human task "${step}" names a document to validate, but its variant is `
+            + `${variant === undefined ? 'the default node type' : `"${variant}"`} — only the validation `
+            + `station reads it, so it would be emitted and ignored.`, `variant: 'document-validation'`);
+        return;
+    }
+    if (isDocval) {
+        if (Array.isArray(inputs?.fields) && inputs.fields.length > 0) {
+            at('HITL_DOCVAL_WITH_FIELDS', `Human task "${step}" is a Document Validation task but also declares ${inputs.fields.length} `
+                + `form field(s). The validation station IS the form — these are dropped.`, `Delete \`fields\`.`);
+            return;
+        }
+        const doc = inputs?.document;
+        if (!doc || typeof doc !== 'object') {
+            at('HITL_DOCVAL_NO_DOCUMENT', `Human task "${step}" uses variant 'document-validation' but names no document — the station `
+                + `has nothing to validate.`, `document: { extractionResult: out('<extractStep>', 'ExtractionResult') }`);
+            return;
+        }
+        const er = doc.extractionResult;
+        const erEmpty = er === undefined || er === null || (typeof er === 'string' && !er.trim());
+        if (erEmpty) {
+            at('DOCVAL_NO_EXTRACTION', `Human task "${step}" gives the validation station no extractionResult. Bind the `
+                + `ExtractionResult output of the upstream extract step — the platform's own validator `
+                + `rejects the node without it.`, `extractionResult: out('<extractStep>', 'ExtractionResult')`);
+        }
+        if (doc.render === 'custom') {
+            const tx = doc.taxonomy;
+            if (tx === undefined || tx === null || (typeof tx === 'string' && !tx.trim())) {
+                at('DOCVAL_TAXONOMY_REQUIRED', `Human task "${step}" renders validation in a custom app (render: 'custom') but names no `
+                    + `taxonomy — the platform requires one for the app's Validation Control.`, `taxonomy: out('<classifyStep>', 'taxonomy')  // or the taxonomy id string`);
+            }
+        }
+        else if (doc.render !== undefined && doc.render !== 'standard') {
+            at('DOCVAL_RENDER_UNKNOWN', `Human task "${step}" gives the validation render type ${JSON.stringify(doc.render)}. Valid: `
+                + `'standard' (the native station, the default) or 'custom' (an app with a Validation Control).`, `render: 'standard'`);
+        }
+        // No inline form — skip the field rules; outcomes still route, fall through.
+    }
+    if (!isApp && !(isDocval && inputs?.document?.render === 'custom') && inputs?.app !== undefined) {
+        at('HITL_APP_WITHOUT_VARIANT', `Human task "${step}" names a deployed app, but its variant is `
+            + `${variant === undefined ? 'the default node type' : `"${variant}"`}, whose form lives in the `
+            + `flow. The app would be emitted and then ignored — the reviewer still gets the inline form.`, `variant: 'action-app'`);
+        return;
+    }
+    if (isApp) {
+        // The app owns the form, so `fields` is not merely unnecessary here — it is a
+        // statement about a form this node does not have, and the platform drops it.
+        if (Array.isArray(inputs?.fields) && inputs.fields.length > 0) {
+            at('HITL_APP_WITH_FIELDS', `Human task "${step}" is backed by an Action App but also declares ${inputs.fields.length} form `
+                + `field(s). The form belongs to the DEPLOYED APP, not to the flow, so these are dropped and `
+                + `the reviewer sees the app's own form instead.`, `Delete \`fields\`; map values into the app with \`app.inputs\` instead.`);
+            return;
+        }
+        const app = inputs?.app;
+        if (!app || typeof app !== 'object') {
+            at('HITL_APP_MISSING', `Human task "${step}" uses variant 'action-app', which takes its form from a deployed Action `
+                + `App — but names no app, so nothing tells the platform which form to show.`, `app: { name: 'Expense Review', key: '<guid>', folderPath: 'Shared' }`);
+            return;
+        }
+        for (const k of ['name', 'key', 'folderPath']) {
+            if (typeof app[k] !== 'string' || !app[k].trim()) {
+                at('HITL_APP_INCOMPLETE', `Human task "${step}" names an Action App with no ${k}. An app is resolved by its key plus `
+                    + `the folder it is deployed in, with the name shown to the reviewer — all three are needed `
+                    + `for the platform to find it.`, `app: { name: 'Expense Review', key: '<guid>', folderPath: 'Shared' }`);
+                return;
+            }
+        }
+        // Outcomes still matter for an app task: the flow's own routing and its
+        // `Action`/`status` outputs are derived from them, so fall through to the
+        // outcome rules below rather than returning here.
+    }
+    // An app task legitimately has no form fields of its own — the rules below then
+    // walk an empty list and only the outcome rules bite, which is what we want.
+    const fields = isApp || isDocval ? (inputs?.fields ?? []) : inputs?.fields;
+    if (!Array.isArray(fields)) {
+        at('HITL_NO_FIELDS', `Human task "${step}" has no fields array. Give it the form: what the reviewer reads `
+            + `(direction 'input') and what they fill in (direction 'output').`, `fields: [{ id: 'amount', type: 'number', direction: 'input', value: input('amount') }]`);
+        return;
+    }
+    const seen = new Set();
+    let answers = 0;
+    fields.forEach((f, i) => {
+        const where = `fields[${i}]`;
+        const id = typeof f?.id === 'string' ? f.id.trim() : '';
+        if (!id) {
+            at('HITL_FIELD_NO_ID', `Human task "${step}" has a form field with no id (${where}). The id is the key the `
+                + `reviewer's answer comes back under, so a field without one is dropped.`, `id: 'amount'`);
+            return;
+        }
+        if (seen.has(id)) {
+            at('HITL_DUP_FIELD', `Human task "${step}" declares the form field "${id}" twice. The answer object is keyed `
+                + `by field id, so the second silently replaces the first.`, `Rename one of them.`);
+            return;
+        }
+        seen.add(id);
+        if (RESERVED_ANSWER_IDS.has(id)) {
+            at('HITL_FIELD_RESERVED_ID', `Human task "${step}" has a form field named "${id}", which the task's own result already `
+                + `uses (its output object carries "Action", and the node publishes "output" and "status"). `
+                + `The platform drops a field that collides with those.`, `Rename it, e.g. id: '${id}Value'.`);
+            return;
+        }
+        if (!FORM_FIELD_TYPES.includes(String(f?.type))) {
+            at('HITL_FIELD_TYPE_UNKNOWN', `Human task "${step}" gives the form field "${id}" the type ${JSON.stringify(f?.type)}, `
+                + `${formFieldTypeWhy(f?.type)}. Valid: ${FORM_FIELD_TYPES.join(', ')}.`, formFieldTypeHint(f?.type));
+        }
+        if (isAnswerField(f))
+            answers++; // an `output`, or an `inOut` whose reviewed value comes back
+        if (f?.direction === 'input' || f?.direction === 'inOut') {
+            const value = f.value;
+            if (value === undefined || value === null) {
+                at('HITL_FIELD_NO_VALUE', `Human task "${step}" shows the form field "${id}" to the reviewer but gives it no value, `
+                    + `so the field renders empty — the flow says "show them this" and shows them nothing.`, `value: input('<flowInput>')  // or out('<step>', '<field>')`);
+            }
+            else if (!(value instanceof Expr)) {
+                at('HITL_FIELD_VALUE_NOT_REF', `Human task "${step}" gives the form field "${id}" a raw `
+                    + `${Array.isArray(value) ? 'array' : typeof value} as its value. A shown field is filled `
+                    + `from a variable PATH, not a constant — the platform reads the string as a lookup, so a `
+                    + `literal resolves to nothing on the form.`, `value: input('<flowInput>')`);
+            }
+            else if (value.literal || !/^\$vars\.[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/.test(value.js.trim())) {
+                // Same trap as a transform's `collection`: a computed expression resolves
+                // locally and to nothing once deployed, where it is used as a path.
+                at('HITL_FIELD_VALUE_NOT_PATH', `Human task "${step}" fills the form field "${id}" from the expression `
+                    + `"${value.literal ? String(value.value) : value.js.trim().slice(0, 60)}". A field binding is `
+                    + `a variable PATH, so a computed expression resolves to nothing on the deployed form. `
+                    + `Compute it in a script step first and point the field at that step's output.`, `value: out('<scriptStep>')`);
+            }
+        }
+        else if (f?.direction !== 'output') {
+            at('HITL_FIELD_DIRECTION', `Human task "${step}" gives the form field "${id}" the direction `
+                + `${JSON.stringify(f?.direction)}. A field is shown to the `
+                + `reviewer ('input'), filled in by them ('output'), or pre-filled and editable ('inOut'); `
+                + `anything else appears in the form schema and is neither displayed nor read back.`, `direction: 'output'`);
+        }
+    });
+    const outcomes = inputs?.outcomes;
+    if (!Array.isArray(outcomes) || outcomes.length === 0) {
+        at('HITL_NO_OUTCOMES', `Human task "${step}" declares no outcomes, so the reviewer has no button to complete the `
+            + `task with and the flow waits forever.`, `outcomes: ['Approve', 'Reject']`);
+        return;
+    }
+    const names = new Set();
+    const ids = new Map();
+    outcomes.forEach((o, i) => {
+        const name = (typeof o === 'string' ? o : o?.name)?.trim();
+        // Two outcomes on one id would share one `outcome-<id>` port, so the
+        // second's edge could never be told apart. An explicit `id` can collide
+        // with another outcome's derived slug.
+        const id = outcomeIdOf(o, i);
+        const explicitId = typeof o === 'object' && o !== null ? o.id : undefined;
+        if (explicitId !== undefined && (typeof explicitId !== 'string' || explicitId === '')) {
+            at('HITL_OUTCOME_BAD_ID', `Human task "${step}" outcome ${JSON.stringify(name ?? i)} has an id that is not a non-empty string. `
+                + `Leave \`id\` out to use the slug of the name.`, `{ name: ${JSON.stringify(name ?? 'Approve')} }`);
+        }
+        else if (ids.has(id) && ids.get(id) !== String(name ?? '')) {
+            // Same name, same id: HITL_DUP_OUTCOME below reports it once, as a name clash.
+            at('HITL_DUP_OUTCOME_ID', `Human task "${step}" gives outcomes "${ids.get(id)}" and "${name}" the same id "${id}", so both would `
+                + `leave from one 'outcome-${id}' port. Give one of them a different \`id\`.`);
+        }
+        else {
+            ids.set(id, String(name ?? ''));
+        }
+        if (!name) {
+            at('HITL_OUTCOME_NO_NAME', `Human task "${step}" has an outcome with no name (outcomes[${i}]). The result carries the `
+                + `outcome's NAME — it is what "$vars.${step}.output.Action" holds and what the platform's `
+                + `own routing conditions compare against — so a nameless one can never be matched.`, `outcomes: ['Approve', 'Reject']`);
+            return;
+        }
+        if (names.has(name)) {
+            at('HITL_DUP_OUTCOME', `Human task "${step}" declares the outcome "${name}" twice. Only the name reaches the flow, `
+                + `so two outcomes sharing one are indistinguishable downstream.`, `Rename one of them.`);
+            return;
+        }
+        names.add(name);
+        const action = typeof o === 'string' ? undefined : o?.action;
+        if (action !== undefined && action !== 'Continue' && action !== 'End') {
+            at('HITL_OUTCOME_ACTION', `Human task "${step}" gives the outcome "${name}" the action ${JSON.stringify(action)}. Only `
+                + `the exact string 'End' means "end the process here"; anything else — including 'end' — is `
+                + `read as 'Continue'.`, `action: 'End'`);
+        }
+    });
+    // Delivery: the channel ids and assignee types are closed platform
+    // vocabularies; a typo silently falls back to tenant defaults at run time.
+    const HITL_CHANNELS = ['Slack', 'teams', 'Email', 'ActionCenter'];
+    const HITL_ASSIGNEE_TYPES = ['user', 'group', 'staticEmail', 'staticGroupName', 'workload', 'roundRobin', 'custom'];
+    const rec = inputs?.recipient;
+    if (rec !== undefined) {
+        for (const ch of rec.channels ?? []) {
+            if (!HITL_CHANNELS.includes(String(ch))) {
+                const nearest = nearestName(String(ch), HITL_CHANNELS);
+                at('HITL_CHANNEL_UNKNOWN', `Human task "${step}" delivers over the channel ${JSON.stringify(ch)}, which the platform `
+                    + `does not recognize — valid: ${HITL_CHANNELS.join(', ')} (Microsoft Teams really is the `
+                    + `lowercase 'teams').`, nearest !== undefined ? `channels: ['${nearest}']` : undefined);
+            }
+        }
+        const at2 = rec.assignee?.type;
+        if (!HITL_ASSIGNEE_TYPES.includes(String(at2))) {
+            const nearest = nearestName(String(at2), HITL_ASSIGNEE_TYPES);
+            at('HITL_RECIPIENT_TYPE', `Human task "${step}" assigns its recipient with the type ${JSON.stringify(at2)}. Valid: `
+                + `${HITL_ASSIGNEE_TYPES.join(', ')}.`, nearest !== undefined ? `assignee: { type: '${nearest}' }` : undefined);
+        }
+        else if (at2 === 'custom' && !(typeof rec.assignee?.value === 'string' && rec.assignee.value.trim())) {
+            at('HITL_RECIPIENT_VALUE', `Human task "${step}" uses a custom assignment with no value — the engine gets an `
+                + `empty custom-assignees expression and falls back to the tenant default.`, `assignee: { type: 'custom', value: '<expression>' }`);
+        }
+    }
+    // A form with nothing to fill in and one outcome is a notification, not a task
+    // — but it is a legitimate one (an acknowledgement step), so this is not an
+    // error. Two or more outcomes with no answer fields is the common approval
+    // shape and equally fine. Nothing to report either way.
+    void answers;
+}
+/**
+ * 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 function checkHitlRead({ node: name, field, rest, reader: step }, form, report) {
+    if (field === undefined) {
+        // `out('review')` — the whole answer object. Legitimate (a script may want
+        // all of it), same as a subflow's bare read being legitimate.
+        return;
+    }
+    if (field === 'status') {
+        report('HITL_READ_STATUS', `"$vars.${name}.status" (read in "${step}") is the platform's own projection of the chosen `
+            + `outcome, not part of the answer object. Read the outcome from the output instead, which is `
+            + `the spelling flow-v1's routing conditions use and the one every rung here resolves.`, `out('${name}', 'Action')`);
+        return;
+    }
+    if (field !== 'output') {
+        report('HITL_READ_NOT_OUTPUT', `Human task "${name}" publishes its result under "output", but "$vars.${name}.${field}" `
+            + `(read in "${step}") asks for "${field}", which is undefined at run time.`, `out('${name}', '<fieldId>')`);
+        return;
+    }
+    // `out(name, 'x')` renders as `$vars.<name>.output.x`, so the answer field is
+    // the first segment of `rest` — which arrives with its leading dot
+    // (`.approved`), the same shape `checkSubflowRead` receives.
+    const answer = rest.replace(/^\./, '').split('.')[0];
+    if (!answer)
+        return; // `$vars.<name>.output` — the whole object, fine.
+    if (answer === 'Action')
+        return; // which outcome was pressed.
+    const answers = (form?.fields ?? [])
+        .filter((f) => isAnswerField(f) && typeof f?.id === 'string')
+        .map((f) => f.id);
+    if (answers.includes(answer))
+        return;
+    const shown = (form?.fields ?? [])
+        .filter((f) => f?.direction === 'input' && typeof f?.id === 'string')
+        .map((f) => f.id);
+    const nearest = nearestName(answer, [...answers, 'Action']);
+    report('HITL_READ_UNKNOWN_FIELD', `Human task "${name}" has no answer "${answer}" (read as "$vars.${name}.output.${answer}" in `
+        + `"${step}"). Its result carries only the fields the reviewer FILLS IN or EDITS`
+        + `${answers.length > 0 ? ` (${answers.join(', ')})` : ' (it declares none)'} plus "Action". `
+        + (shown.includes(answer)
+            ? `"${answer}" is a field the reviewer only reads, so it is not part of the answer — read the `
+                + `value you bound to it instead.`
+            : 'Nothing else resolves at run time.'), nearest !== undefined ? `out('${name}', '${nearest}')` : undefined);
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The HITL factory, `hitl()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports it.
+ */
+import { type ActionSpec } from '../../../core/actions.js';
+import type { HitlInputs } from './spec.js';
+/**
+ * Declare a human task — a step that pauses for a person to read some values,
+ * fill others in, and press one of the outcome buttons.
+ *
+ * @remarks
+ * Read an answer with `out('review', '<fieldId>')`, and which button they pressed
+ * with `out('review', 'Action')` — branch on that for per-outcome routing.
+ *
+ * ### Picking a node type with `variant`
+ *
+ * The example above emits `uipath.human-in-the-loop`, the original node, and
+ * that stays the default. Two other spellings of the same human task exist
+ * ({@link HitlVariant}), and `variant` is how you say which:
+ *
+ * ```ts
+ * // Same inline form, the newer node type — no `inputs.type` is written.
+ * hitl({ variant: 'quick-form', fields: […], outcomes: ['Approve', 'Reject'] })
+ *
+ * // The form lives in a DEPLOYED APP: no `fields`, but still your outcomes.
+ * hitl({
+ *   variant: 'action-app',
+ *   app: { name: 'Expense Review', key: '<guid>', folderPath: 'Shared',
+ *          inputs: { 'Expense Amount': out('fetchExpense', 'total') } },
+ *   outcomes: ['Approve', 'Reject'],
+ * })
+ * ```
+ *
+ * What every variant shares: one `completed` port, and the same two outputs
+ * (`output`, carrying the answers, and `status`, carrying the outcome name) —
+ * all three definitions declare them identically, so downstream reads do not
+ * change when you switch.
+ *
+ * @example
+ * **Pause for a person to approve, then read their decision**
+ * ```ts
+ * .step('review', hitl({
+ *   title: 'Review Expense',
+ *   fields: [
+ *     { id: 'amount',   type: 'number',  direction: 'input',  value: input('amount') },
+ *     { id: 'approved', type: 'boolean', direction: 'output' },
+ *     { id: 'comments', type: 'text',    direction: 'output' },
+ *   ],
+ *   outcomes: ['Approve', 'Reject'],
+ * }))
+ * .step('log', script({ code: 'return "Decision: " + $vars.review.output.approved;' }))
+ * ```
+ *
+ * @param inputs - The form's fields, outcomes and recipient.
+ * @returns An action spec for `.step(...)`.
+ * @example example-eval/GallerySubmission.flow.ts
+ */
+export declare function hitl(inputs: HitlInputs): ActionSpec;

package/dist/nodes/hitl/flow/factories.js

@@ -0,0 +1,59 @@
+/**
+ * The HITL factory, `hitl()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports it.
+ */
+import { builtinActionSpec } from '../../../core/actions.js';
+/**
+ * Declare a human task — a step that pauses for a person to read some values,
+ * fill others in, and press one of the outcome buttons.
+ *
+ * @remarks
+ * Read an answer with `out('review', '<fieldId>')`, and which button they pressed
+ * with `out('review', 'Action')` — branch on that for per-outcome routing.
+ *
+ * ### Picking a node type with `variant`
+ *
+ * The example above emits `uipath.human-in-the-loop`, the original node, and
+ * that stays the default. Two other spellings of the same human task exist
+ * ({@link HitlVariant}), and `variant` is how you say which:
+ *
+ * ```ts
+ * // Same inline form, the newer node type — no `inputs.type` is written.
+ * hitl({ variant: 'quick-form', fields: […], outcomes: ['Approve', 'Reject'] })
+ *
+ * // The form lives in a DEPLOYED APP: no `fields`, but still your outcomes.
+ * hitl({
+ *   variant: 'action-app',
+ *   app: { name: 'Expense Review', key: '<guid>', folderPath: 'Shared',
+ *          inputs: { 'Expense Amount': out('fetchExpense', 'total') } },
+ *   outcomes: ['Approve', 'Reject'],
+ * })
+ * ```
+ *
+ * What every variant shares: one `completed` port, and the same two outputs
+ * (`output`, carrying the answers, and `status`, carrying the outcome name) —
+ * all three definitions declare them identically, so downstream reads do not
+ * change when you switch.
+ *
+ * @example
+ * **Pause for a person to approve, then read their decision**
+ * ```ts
+ * .step('review', hitl({
+ *   title: 'Review Expense',
+ *   fields: [
+ *     { id: 'amount',   type: 'number',  direction: 'input',  value: input('amount') },
+ *     { id: 'approved', type: 'boolean', direction: 'output' },
+ *     { id: 'comments', type: 'text',    direction: 'output' },
+ *   ],
+ *   outcomes: ['Approve', 'Reject'],
+ * }))
+ * .step('log', script({ code: 'return "Decision: " + $vars.review.output.approved;' }))
+ * ```
+ *
+ * @param inputs - The form's fields, outcomes and recipient.
+ * @returns An action spec for `.step(...)`.
+ * @example example-eval/GallerySubmission.flow.ts
+ */
+export function hitl(inputs) {
+    return builtinActionSpec({ kind: 'hitl', inputs });
+}

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

@@ -0,0 +1,3 @@
+/** The HITL node family, as flow-node-registry.ts lists it: the four human-task node types. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const hitlFlowFamily: FlowNodeFamily;

package/dist/nodes/hitl/flow/family.js

@@ -0,0 +1,8 @@
+import { HITL_DIAGNOSTICS } from './check.js';
+import { hitlNodeTypes } from './node-type.js';
+export const hitlFlowFamily = {
+    id: 'hitl',
+    title: 'Human task',
+    types: hitlNodeTypes,
+    diagnostics: HITL_DIAGNOSTICS,
+};

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

@@ -0,0 +1,3 @@
+/** The HITL family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/hitl/flow/index.js

@@ -0,0 +1,3 @@
+/** The HITL family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

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

@@ -0,0 +1,7 @@
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+import type { HitlInputs } from './spec.js';
+export type HitlSpec = {
+    kind: 'hitl';
+    inputs: HitlInputs;
+};
+export declare const hitlNodeTypes: FlowVersionedNodeType<HitlSpec>[];