@uipath/maestro-builder-sdk 6.42.0 → 6.44.0

package/dist/nodes/agent/flow/spec.d.ts

@@ -0,0 +1,448 @@
+/**
+ * The agents family's authoring types — the text conversational agent
+ * (`uipath.agent.conversational`), the voice agent (`uipath.agent.voice`) and
+ * the two voice call steps (`uipath.conversational.voice.create-outgoing-call`,
+ * `.end-call`) and the inline agent (`uipath.agent.autonomous`) — and their
+ * kinds' entries in `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md. The guardrails and the resource refs
+ * (`ToolRef`, `ContextIndexRef`, `EscalationRef`, `AgentMemoryRef`) stay in
+ * core: the resource identities and the bindings writers read them.
+ */
+import type { AgentGuardrail, AgentMemoryRef, ContextIndexRef, EscalationRef, InlineAgentFieldType, ToolRef } from '../../../core/actions.js';
+import type { Expr } from '../../../core/expr.js';
+/**
+ * How a conversational agent gets its turn — the node's own
+ * `conversationalAgentSettings` sub-object.
+ *
+ * @remarks
+ * `'simple'` (the default) derives everything from ONE conversation-context
+ * binding: `context` is the whole context object, and the platform reads
+ * `conversationId` / `latestExchangeId` / `messages` / `userSettings` out of
+ * it. `'custom'` binds each field yourself — for a flow that assembles a turn
+ * from more than one source.
+ */
+export interface ConversationalAgentSettings {
+    /** `'simple'` (the default) binds the whole context once; `'custom'` binds each field. */
+    mode?: 'simple' | 'custom';
+    /** The whole conversation context — `'simple'` mode's single binding. */
+    context?: Expr | string;
+    /** `'custom'` mode: the conversation id. */
+    conversationId?: Expr | string;
+    /** `'custom'` mode: the exchange id. */
+    exchangeId?: Expr | string;
+    /** `'custom'` mode: the chat history array. */
+    messages?: Expr | string;
+    /** `'custom'` mode: the caller's per-user settings object. */
+    userSettings?: Expr | string;
+}
+/** What `conversationalAgent()` takes: the agent's instructions and model, and how it gets its turn. */
+export interface ConversationalAgentInputs {
+    /**
+     * The agent's standing instructions for the conversation. Plain text — a
+     * conversational agent's turn comes from the transcript, not from flow
+     * arguments, so there is no `{{input.…}}` templating.
+     */
+    systemPrompt: string;
+    /** The MODEL to run, e.g. `'gpt-5.4'`. Required by the node's definition. */
+    model: string;
+    /**
+     * How the agent gets its turn. The common case is
+     * `{ context: out('<waitStep>', 'conversationContext') }` — one binding the
+     * platform reads conversation id, exchange id, history and user settings out
+     * of. See {@link ConversationalAgentSettings}.
+     */
+    settings: ConversationalAgentSettings;
+    /**
+     * Whether the agent's reply CLOSES the exchange.
+     *
+     * @deprecated Has no effect and is not emitted. The platform retired the input:
+     * the conversational agent's v1.7 node migration removes it, and the converter
+     * always sends `conversationalService.endExchange = ''`. Wait-for-message and
+     * the end of the conversation close open exchanges.
+     */
+    endExchange?: boolean;
+    /** Sampling temperature, 0–1. */
+    temperature?: number;
+    /** Max tokens in one response. */
+    maxTokenPerResponse?: number;
+    /**
+     * The model's own context ceiling.
+     *
+     * @deprecated Has no effect and is not emitted. Studio Web derives it from the
+     * selected model.
+     */
+    modelMaxTokens?: number;
+    /** How many tool-calling rounds one turn may take, 1–100. */
+    maxIterations?: number;
+    /** Safety rails, the same array `inlineAgent` takes. */
+    guardrails?: AgentGuardrail[];
+    /**
+     * The agent's own directory name (a UUID) — the node carries it as `source`
+     * and the compiler writes `<source>/agent.json` beside the flow. Derived from
+     * the flow id + step name when omitted.
+     */
+    source?: string;
+}
+/** What `createOutgoingCall()` takes: the two numbers, in E.164. */
+export interface CreateOutgoingCallInputs {
+    /**
+     * The number to call FROM — a provisioned number on the tenant's telephony
+     * provider, in E.164 (`'+15551234567'`). Required.
+     */
+    from: string | Expr;
+    /** The number to call, in E.164. Required. */
+    to: string | Expr;
+}
+/** What `endCall()` takes: the call to hang up. */
+export interface EndCallInputs {
+    /**
+     * The call to hang up — bind the `callContext` published by the incoming-call
+     * trigger (`out('start', 'callContext')`) or by `createOutgoingCall`
+     * (`out('<step>', 'callContext')`). Required.
+     */
+    callContext: Expr | string;
+}
+/**
+ * The audio settings a voice agent speaks with.
+ *
+ * @remarks
+ * `model` is a VOICE model (a live/realtime one — not the text models
+ * `inlineAgent` takes), and `persona` is one of that model's own voices, so the
+ * two travel together. The platform's catalog today is
+ * `'gemini-3.1-flash-live-preview'` (personas Aoede, Charon, Fenrir, Kore,
+ * Leda, Orus, Puck, Zephyr) and `'gpt-realtime-2'` (alloy, ash, ballad, coral,
+ * echo, sage, shimmer, verse); omit both for the platform default.
+ */
+export interface VoiceSettings {
+    /** The voice model, e.g. `'gemini-3.1-flash-live-preview'`. */
+    model?: string;
+    /** One of that model's personas, e.g. `'Kore'`. */
+    persona?: string;
+    /** Sampling temperature, 0–1. */
+    temperature?: number;
+    /** Max tokens per response. */
+    maxTokens?: number;
+    /** The model's own context ceiling — informational. */
+    modelMaxTokens?: number;
+}
+/** What `voiceAgent()` takes: the agent's instructions, the call it joins, and how it sounds. */
+export interface VoiceAgentInputs {
+    /**
+     * The agent's standing instructions — who it is on the call and what it must
+     * do. Use `{{input.<name>}}` placeholders for values declared in `inputs`;
+     * the caller's audio remains the conversational turn.
+     */
+    systemPrompt: string;
+    /**
+     * Flow values made available to `systemPrompt` placeholders. Each key must
+     * be referenced as `{{input.<key>}}`; the compiler emits the node's runtime
+     * argument binding and the matching agent.json input contract together.
+     */
+    inputs?: Record<string, unknown>;
+    /**
+     * The call to attach the agent to — the `callContext` from the incoming-call
+     * trigger or `createOutgoingCall`. Required: without it the agent has no
+     * audio channel to join.
+     */
+    callContext: Expr | string;
+    /** How the agent sounds. Omit for the platform default voice. */
+    voice?: VoiceSettings;
+    /**
+     * How many tool-calling rounds the agent may take in one turn. The node's
+     * schema allows **1–8** — a tighter ceiling than a text agent's, because a
+     * caller is waiting.
+     */
+    maxIterations?: number;
+    /**
+     * The agent's own directory name (a UUID) — the node carries it as `source`
+     * and the compiler writes `<source>/agent.json` beside the flow. Omit and one
+     * is derived from the flow id + step name, so a recompile is not a diff.
+     */
+    source?: string;
+}
+/** What `inlineAgent()` takes: the model and prompts, the inputs and `returns`, the run settings, and the resources the agent attaches. */
+export interface InlineAgentInputs {
+    /**
+     * The MODEL to run, e.g. `'gpt-5.4'`. Required by the node's definition, and
+     * worth a thought rather than a default: the platform's own scaffold ships
+     * `gpt-4o-2024-11-20`, which is stale, and v1's own smoke check for this node
+     * type FAILS a flow that keeps it. List what the tenant has with
+     * `uip agent model list`.
+     */
+    model: string;
+    /**
+     * The agent's standing instructions — who it is, and what each `returns` field
+     * should hold. Required by the definition (`minLength: 1`).
+     *
+     * **Write it as plain text, and reference a value as `{{input.<name>}}`** — the
+     * agent's own template syntax, and the same names `inputs` declares:
+     *
+     * ```ts
+     * systemPrompt: 'You classify support email. Return a result conforming to the output '
+     *   + 'schema. category: billing | technical | account. priority: low | normal | high.',
+     * userPrompt: 'Classify this email:\n{{input.body}}',
+     * inputs: { body: input('body') },
+     * returns: { category: 'string', priority: 'string' },
+     * ```
+     *
+     * Why a placeholder rather than an interpolated expression: an inline agent is two
+     * artifacts, and its prompt exists in TWO dialects. You write one; the compiler
+     * emits the other into the `agent.json` sidecar. The `.flow` node carries no copy
+     * of the prompt: it is a shell, so Studio Web reads the sidecar.
+     *
+     *   1. yours          `{{input.claim}}`
+     *   2. the AGENT.JSON `{{input.prepare__output__claimRef}}` ← what the runtime SENDS
+     *
+     * The second exists because the platform does not send an agent the names you
+     * declared: it names each argument after the bound reference PATH, `__`-joined.
+     * For a flow input the two coincide (`$vars.notes` → `notes`); for a step output
+     * they do not, and a sidecar still saying `{{input.claim}}` templates against a key
+     * that is not there — the literal text reaches the model. See the inline-agent
+     * node reference (`website/reference/inline-agent.md`) §"The prompt dialects".
+     *
+     * **The answer's shape is `returns`, not the prompt.** `returns` becomes the node's
+     * `agentOutputVariables` and the `agent.json` `outputSchema` — what Studio Web's
+     * Outputs editor writes — and the platform's agent runtime ends each run with a
+     * built-in structured call (`end_execution`) that fills exactly those fields. So
+     * `out('<step>', '<field>')` reads a typed value, not text to parse. Describe what
+     * each field holds, in the product's own wording, as the example above does:
+     * `Return a result conforming to the output schema. <field>: <how to fill it>.`
+     *
+     * Never ask for JSON TEXT as well ("Return ONLY a JSON object with keys …"). The
+     * model then packs its whole answer, serialized, into ONE string field: a writer
+     * declaring `{ subject, body }` came back on 2026-09-23 with
+     * `body: '{"subject":"…","body":"Dear …"}'` in 3 of 3 debug runs, and the flow sent
+     * that text on. A field that should carry structure is declared `'object'` or
+     * `'array'` instead.
+     *
+     * @enforcedBy INLINE_AGENT_PROMPT_JSON_TEXT A prompt that asks for JSON text while
+     * `returns` declares fields is refused; the platform accepts it and the run returns
+     * the packed value.
+     */
+    systemPrompt: string;
+    /**
+     * The per-run request. Required by the definition (`minLength: 1`). Same
+     * `{{input.<name>}}` placeholders as `systemPrompt`.
+     */
+    userPrompt: string;
+    /**
+     * The values the agent gets, by YOUR name for each one — e.g.
+     * `{ body: input('body') }`. These become the node's `agentInputVariables`
+     * descriptor array (`{ id, type, binding }`, the shape 48 of 53 deployed instances
+     * carry) and the `agent.json`'s `inputSchema`.
+     *
+     * **The name is yours only in this file.** Both emitted artifacts carry the
+     * PLATFORM's name — the bound reference's path, `__`-joined
+     * (`out('prepare','claimRef')` → `prepare__output__claimRef`) — because that is what
+     * the runtime keys the agent's JobArguments by, and an `agent.json` speaking any
+     * other name templates against nothing. You never write the long form.
+     *
+     * **Reference each one in a prompt as `{{input.<name>}}`.** Not decoration: the
+     * platform's deployed input list is not necessarily this array. flow-v1's
+     * `preDeriveAgentInputDefinitions` pre-pass scans the node's PROMPTS for `$vars.*`
+     * references, merges what it finds with this list, and — when its caller asks for
+     * pruning — DROPS an entry no prompt reference points at. A referenced entry
+     * survives every one of those paths; an unreferenced one survives only some.
+     * `check` warns when none of them is referenced, which is the case where the agent
+     * would arrive with no arguments at all.
+     *
+     * Two shapes have no platform name and are handled rather than renamed:
+     *
+     *  - a **literal** (`{ tier: 'Enterprise' }`) is INLINED into both prompts — there
+     *    is no argument for one, so a token could never substitute;
+     *  - a **computed expression** is refused by `check`
+     *    (`INLINE_AGENT_COMPOSITE_INPUT`): the platform names one argument per
+     *    reference, so an expression spanning several has none. Compute it in a
+     *    `script` step first and bind that step's output.
+     */
+    inputs?: Record<string, unknown>;
+    /**
+     * The fields the agent must return, and their types — e.g.
+     * `{ category: 'string', priority: 'string' }`. These become the node's
+     * `agentOutputVariables` descriptor array AND the emitted `agent.json`'s
+     * `outputSchema`, and they are what makes `out('<step>', 'category')` a checkable
+     * read.
+     *
+     * Defaults to the definition's own default, `{ content: 'string' }` — which is
+     * the toy scaffold shape, so declare something real if the flow reads fields.
+     *
+     * @enforcedBy INLINE_AGENT_READ_UNKNOWN_FIELD A read outside the declared set is
+     * undefined on every rung and on the platform.
+     */
+    returns?: Record<string, InlineAgentFieldType>;
+    /**
+     * The agent's own directory name — a UUID. The node carries it as `source`, and
+     * the platform resolves the agent's configuration at `<source>/agent.json`
+     * relative to the project (flow-v1 emits `entryPoint: <source>/agent.json`), so
+     * the compiler writes that file next to the `.flow`.
+     *
+     * Omit it and one is derived from the flow id + step name, so a given flow emits
+     * the same uuid every time (a random one would make every compile a diff).
+     */
+    source?: string;
+    /** Sampling temperature, 0–1. The definition's range; omit for the model's default. */
+    temperature?: number;
+    /** Max tokens in one response, 0–16384. */
+    maxTokenPerResponse?: number;
+    /**
+     * The model's own context ceiling, e.g. `128000`.
+     *
+     * @deprecated Has no effect and is not emitted. Studio Web derives it from the
+     * selected model each time the agent is opened, and the sidecar has no field
+     * for it.
+     */
+    modelMaxTokens?: number;
+    /** How many tool-calling rounds the agent may take, 1–100. */
+    maxIterations?: number;
+    /**
+     * The harness the agent runs on — `'standard'` (the default) or
+     * `'advanced'`, written to the `agent.json`'s `settings.mode`. It does not
+     * change the node's version: every inline agent emits the bundle's newest
+     * `uipath.agent.autonomous` definition (1.4).
+     */
+    mode?: 'standard' | 'advanced';
+    /**
+     * Safety rails over the agent's inputs, outputs, LLM calls and tools — the
+     * platform's own array shape ({@link AgentGuardrail}), carried in the
+     * `agent.json` (every bundled definition declares the input).
+     *
+     * ```ts
+     * guardrails: [{
+     *   id: 'no-pii', $guardrailType: 'custom', name: 'Block PII',
+     *   selector: { scopes: ['Agent'] },
+     *   action: { $actionType: 'block', reason: 'PII detected' },
+     *   enabledForEvals: true,
+     *   rules: [{ $ruleType: 'word', fieldSelector: { $selectorType: 'all' },
+     *             operator: 'matchesRegex', value: '\\d{3}-\\d{2}-\\d{4}' }],
+     * }]
+     * ```
+     */
+    guardrails?: AgentGuardrail[];
+    /**
+     * Attach an episodic memory so the agent learns from past runs — one
+     * {@link AgentMemoryRef}, wired to the agent's `memory` handle (declared by
+     * the bundled 1.4 definition, which every inline agent uses).
+     */
+    memory?: AgentMemoryRef;
+    /**
+     * GROUND the agent on tenant knowledge — one or more Context Grounding
+     * (semantic) indexes, wired to the agent's own `context` handle.
+     *
+     * ```ts
+     * inlineAgent({
+     *   model: 'gpt-5.4',
+     *   systemPrompt: 'You decide billing disputes from the SOPs. Return a result conforming to the output '
+     *     + 'schema. determination: valid | invalid | needs_review. rationale: the SOP rule that decided it.',
+     *   userPrompt: 'Dispute: {{input.description}}',
+     *   inputs: { description: input('disputeDescription') },
+     *   returns: { determination: 'string', rationale: 'string' },
+     *   context: [{
+     *     name: 'Billing Dispute SOP Index',
+     *     id: 'cc45b9b4-dbf6-47b3-40ac-08debc0cec5b',
+     *     folderPath: 'Shared/uipath-maestro-flow/BillingDispute',
+     *     query: 'billing dispute resolution policy',
+     *   }],
+     * })
+     * ```
+     *
+     * Each entry becomes its own NODE —
+     * `uipath.agent.resource.context.index.<slug>.<id>` — joined to the agent by an
+     * edge out of the agent's `context` port. That is the platform's own shape: the
+     * agent definition declares the handle with
+     * `allowedTargets: [{ nodeType: 'uipath.agent.resource.context.*' }]`, and the
+     * index's definition declares the mirror
+     * (`allowedSources: [{ nodeType: 'uipath.agent.autonomous', handleId: 'context' }]`,
+     * `maxConnections: 1`). Nothing is a binding: the index's identity is IN the node
+     * type, exactly as a published agent's release key is.
+     *
+     * **Both identifiers are needed and neither is derivable.** The node type carries
+     * a slug of the name AND the index's uuid; the node's inputs carry `indexName` +
+     * `indexId` again, because the designer reads one and the runtime the other. Find
+     * them together — the uuid is the tail of the registry node type:
+     *
+     * ```bash
+     * uip maestro flow registry search "<index name>" --output json
+     * ```
+     *
+     * **Grounding is a CLOUD-side capability.** An offline run has no retrieval
+     * service to reach, so its answer is ungrounded
+     * however this is configured — which is why an offline rung can only assert the
+     * WIRING and a live rung only that the agent answered. Say so in a task rather
+     * than letting a green rung imply retrieval happened.
+     */
+    context?: ContextIndexRef | ContextIndexRef[];
+    /**
+     * Give the agent TOOLS — capabilities it may call while reasoning, wired to
+     * the agent's own `tool` handle. Each entry becomes its own resource NODE
+     * (`uipath.agent.resource.tool.<kind>…`), joined to the agent by an edge out
+     * of its `tool` port — the same artifact shape as `context`.
+     *
+     * ```ts
+     * tools: [
+     *   { kind: 'builtin', tool: 'summarize' },
+     *   { kind: 'connector', connector: 'uipath-atlassian-jira', operation: 'create-issue',
+     *     connection: 'jira', folder: 'shared' },   // bindings.json labels, both required
+     *   { kind: 'process', key: '6235d64e-b190-4b7a-8918-723df964c068',
+     *     name: 'Create TestCase', folderPath: 'Shared',
+     *     inputs: { title: 'string' }, returns: { id: 'string' } },
+     * ]
+     * ```
+     *
+     * WHEN a tool runs is the model's decision at run time — nothing in the flow
+     * calls it. Locally that means tool nodes are never stepped through (they are
+     * artifacts, not steps), so no local rung proves a tool was USED — only that
+     * the wiring and shapes are right. Say so in any task that scores this.
+     */
+    tools?: ToolRef | ToolRef[];
+    /**
+     * Let the agent ESCALATE to a human mid-run — an Action Center app task,
+     * wired to the agent's own `escalation` handle (its TOP port).
+     *
+     * ```ts
+     * escalation: {
+     *   name: 'ContentReview',
+     *   description: 'Escalate uncertain content to a human reviewer',
+     *   app: {
+     *     key: '454921d6-137f-4897-943a-1ebf29b15f80',
+     *     name: 'ContentReviewApp',
+     *     folderPath: 'Shared',
+     *     inputs: { ContentText: 'string' },
+     *     outputs: { ReviewDecision: 'string' },
+     *   },
+     *   recipients: ['reviewer@example.com'],
+     *   outcomes: ['approve', 'reject'],
+     * }
+     * ```
+     *
+     * The emitted node type is `uipath.agent.resource.escalation.coded-action-app`
+     * — the registry's CURRENT spelling (the bare `….escalation` is the pre-split
+     * era; the agent's handle accepts both, and `registry get` resolves only the
+     * suffixed one). The other variant, `escalation.quick-form`, is feature-gated
+     * off on this tenant and not authorable.
+     */
+    escalation?: EscalationRef | EscalationRef[];
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link createOutgoingCall} builds. */
+        createOutgoingCall: {
+            inputs: CreateOutgoingCallInputs;
+        };
+        /** The spec {@link endCall} builds. */
+        endCall: {
+            inputs: EndCallInputs;
+        };
+        /** The spec {@link voiceAgent} builds. */
+        voiceAgent: {
+            inputs: VoiceAgentInputs;
+        };
+        /** The spec {@link conversationalAgent} builds. */
+        conversationalAgent: {
+            inputs: ConversationalAgentInputs;
+        };
+        /** The spec {@link inlineAgent} builds. */
+        inlineAgent: {
+            inputs: InlineAgentInputs;
+        };
+    }
+}

package/dist/nodes/agent/flow/spec.js

@@ -0,0 +1 @@
+export {};

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

@@ -30,6 +30,7 @@ export const HITL_DIAGNOSTICS = {
     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_FIELD_VARIABLE: { severity: 'error', summary: "an asked field's variable that is not one identifier, or sits on a shown field" },
     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' },
@@ -225,6 +226,20 @@ export function checkHitl(inputs, ctx) {
         for (const problem of formFieldSettingProblems(f)) {
             at('HITL_FIELD_SETTING_INVALID', `Human task "${step}" gives the form field "${id}" ${problem}. The platform refuses the form.`);
         }
+        // The landing variable is read as `$vars.<variable>`, so it has to be one
+        // identifier — not a path, not a `vars.` prefix — and only an asked field
+        // has one: a shown field's row is written without it (#1309).
+        const variable = f?.variable;
+        if (variable !== undefined) {
+            if (f?.direction !== 'output') {
+                at('HITL_FIELD_VARIABLE', `Human task "${step}"'s form field "${id}" sets \`variable\` on a ${f?.direction === 'inOut' ? 'pre-filled' : 'shown'} field. `
+                    + `Only an asked field (direction 'output') lands its answer in a variable; the SDK writes the row without one.`, 'Drop `variable`, or make the field direction: \'output\'.');
+            }
+            else if (typeof variable !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(variable)) {
+                at('HITL_FIELD_VARIABLE', `Human task "${step}"'s form field "${id}" has variable ${JSON.stringify(variable)}, which is not one identifier. `
+                    + `It is read as $vars.<variable>, so give the name only — no \`vars.\` prefix, no dots.`, typeof variable === 'string' && variable.startsWith('vars.') ? `variable: '${variable.slice(5)}'` : `variable: '${step}_${id}'`);
+            }
+        }
         if (isAnswerField(f))
             answers++; // an `output`, or an `inOut` whose reviewed value comes back
         if (f?.direction === 'input' || f?.direction === 'inOut') {

package/dist/nodes/hitl/flow/node-type.js

@@ -13,7 +13,7 @@
  * every edge out of an outcome-handle node to.
  */
 import { Expr, toExpr } from '../../../core/expr.js';
-import { formFieldJsonSchema, formFieldRowLoss, formFieldRowLossMessage, formFieldSettingsSource, formFieldSettingsWire, liftFormFieldSettings, sourceFormFieldType, wireFormFieldType, } from '../../../core/form-field-type.js';
+import { formFieldJsonSchema, formFieldRowLoss, formFieldRowLossMessage, formFieldSettingsSource, formFieldSettingsWire, formFieldVariableName, liftFormFieldSettings, sourceFormFieldType, wireFormFieldType, } from '../../../core/form-field-type.js';
 import { isAnswerField } from '../../../core/hitl-answers.js';
 import { OUTCOME_HANDLE_NODE_TYPES, hitlExitModel, outcomeIdOf, outcomeSlug } from '../../../core/hitl-routing.js';
 import { jsonClone } from '../../../core/json-clone.js';
@@ -82,8 +82,9 @@ function hitlInputs(inputs, nodeType, ctx) {
         else {
             // The answer's landing variable. The platform falls back to the field id
             // when this is absent; naming it keeps the emitted flow explicit and
-            // matches what the designer writes.
-            base.variable = `vars.${f.id}`;
+            // matches what the designer writes — `vars.<Step>_<field>` when the author
+            // (or the canvas) named one, else the field's own id (#1309).
+            base.variable = `vars.${f.variable ?? f.id}`;
             const required = f.required;
             if (typeof required === 'boolean')
                 base.required = required;
@@ -331,6 +332,11 @@ function liftHitl(node, typeName, ctx) {
         const id = String(f.id ?? '');
         const direction = String(f.direction ?? 'output');
         const value = direction === 'input' || direction === 'inOut' ? bindingExpr(f.binding) : undefined;
+        // An asked field's landing variable comes back when it is not the field's
+        // own id — the designer's `vars.<Step>_<field>` (#1309); `formFieldRowLoss`
+        // reports any other spelling.
+        const landing = direction === 'output' ? formFieldVariableName(f.variable) : undefined;
+        const variable = landing !== undefined && landing !== id ? landing : undefined;
         // Every row key the source cannot carry is reported, never dropped
         // silently: a warning, an error under --strict (#1250).
         const loss = formFieldRowLoss(f, 'human task');
@@ -346,6 +352,7 @@ function liftHitl(node, typeName, ctx) {
             direction,
             ...(value !== undefined ? { value } : {}),
             ...(typeof f.required === 'boolean' && direction !== 'input' ? { required: f.required } : {}),
+            ...(variable !== undefined ? { variable } : {}),
             ...liftFormFieldSettings(f),
         };
     });
@@ -509,6 +516,7 @@ function printHitl({ inputs }, ctx) {
         ['direction', ctx.string(f.direction)],
         ['value', f.value !== undefined ? ctx.value(f.value) : undefined],
         ['required', f.required !== undefined ? String(f.required) : undefined],
+        ['variable', f.variable !== undefined ? ctx.string(f.variable) : undefined],
         ...formFieldSettingsSource(f, ctx.value),
     ], ctx));
     const outcomes = h.outcomes.map((o) => (typeof o === 'string' ? ctx.string(o) : obj([
@@ -596,6 +604,13 @@ function hitlAt(typeName, version, factory) {
             .filter((f) => f?.direction === 'input')
             .map((f) => ({ value: f.value })),
         output: ({ inputs }) => ({ kind: 'reader', read: (read, report) => checkHitlRead(read, inputs, report) }),
+        // An asked field's answer lands in its `variable` (`vars.<Step>_<field>` as
+        // the designer names it), else in `vars.<id>` — serialize writes one or the
+        // other on every asked row — and later steps read it as `$vars.<name>`: the
+        // task declares that variable (#1309).
+        declares: ({ inputs }) => (inputs?.fields ?? [])
+            .map((f) => (f?.direction === 'output' ? (f.variable ?? f.id) : undefined))
+            .filter((v) => typeof v === 'string' && v !== ''),
         exits: hitlExits,
         // The base node and quick-form draw one `outcome-<id>` handle per outcome,
         // whatever the version; their definitions declare only `completed`.

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

@@ -1,6 +1,6 @@
 /**
  * The process family's rules: what is decidable from the call to `rpaWorkflow()`,
- * `apiWorkflow()`, `publishedFunction()` or `agenticProcess()` (the three
+ * `apiWorkflow()`, `publishedFunction()`, `agenticProcess()` or `agent()` (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
@@ -9,7 +9,7 @@
 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';
+import type { AgentInputs, AgenticProcessInputs, ApiWorkflowInputs, PublishedFunctionInputs, RpaWorkflowInputs } from './spec.js';
 export declare const PROCESS_DIAGNOSTICS: DiagnosticCatalog;
 /**
  * Check an `rpaWorkflow(...)` call.
@@ -110,3 +110,41 @@ export declare function checkApiWorkflowRead({ node: name, field, rest, reader:
  * 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;
+/**
+ * Check an `agent(...)` call — a published or in-solution agent (coded or
+ * low-code).
+ *
+ * WHAT THESE RULES CAN AND CANNOT SEE. Whether the agent exists, which kind it is,
+ * and what it returns all live on the tenant. So these cover what is decidable from
+ * the call — and two of them are the exact classes v1's own baseline on this family
+ * fails on, which is why they are errors rather than warnings:
+ *
+ *  - **A reference to nothing.** 5 of 16 `skill-flow-coded-agent` runs in the
+ *    06-29 → 07-20 window emitted an agent node whose `resourceKey` was a LOCAL
+ *    project id and whose `folderPath` was `""`, and faulted at job start with
+ *    `[170007] … HTTP 404 "The job's associated process could not be found"`. A
+ *    blank `name` or `folderPath` is that flow, caught before a tenant round trip.
+ *  - **The empty-input floor.** `inputs` is required by the type, so `{}` is the only
+ *    way to reach it, and it is worth saying what the platform then does — see
+ *    `AGENT_EMPTY_INPUT_FLOOR`.
+ *
+ * What no rule here can see: whether the agent's ANSWER is right. That is CP-3's
+ * ruling — a green live rung means a model responded with the declared shape — and
+ * the gate that does cover a flow FAKING an answer is an offline `replays:` seed
+ * asserting the exact unfixtured value, not a check.
+ */
+export declare function checkAgent(inputs: AgentInputs | undefined, ctx: FlowCheckContext): void;
+/**
+ * A read of a published agent's output: `out('<step>', '<field>')`.
+ *
+ * The three mistakes are api-workflow's and agentic-process's, plus a fourth this
+ * family owns: a read whose CASE differs from the declared field. That is worth its
+ * own message because for a while it was a live-only defect rather than a mistake —
+ * a poller that read the job through `uip agent run status` got a PascalCased
+ * envelope, so `output.Count` was right live and wrong offline while
+ * `output.count` was the reverse (flow-builder-sdk #122). Now the agent's own field
+ * names arrive verbatim and the wrong case is simply undefined; naming it as a CASE
+ * problem rather than an unknown field is the difference between a two-second fix and
+ * a re-read of the registry.
+ */
+export declare function checkAgentRead({ node: name, field, rest, reader: step }: OutputPathRead, spec: AgentInputs, report: (code: string, message: string, suggestion?: string) => void): void;