@uipath/maestro-builder-sdk 6.42.0 → 6.44.0

package/dist/flow-expr-check.js

@@ -29,6 +29,7 @@
  */
 import { Expr, cookedEscapesOf } from './core/expr.js';
 import { checkExpression, cookedEscapeDiagnostics } from './core/expr-check.js';
+import { stepDeclaredVariables } from './flow-step-variables.js';
 const NOUN = 'input, variable, or step';
 /**
  * Every `$vars` root a reference may legitimately resolve to, across the WHOLE
@@ -77,6 +78,10 @@ function addStepNames(steps, roots) {
         // they are edges, not nodes, so there is nothing to reference them by.
         if (s.kind !== 'return' && s.kind !== 'stepToRef' && s.kind !== 'stepToList' && s.kind !== 'break' && s.kind !== 'continue')
             roots.add(s.name);
+        // A step declares the variables its fields land in too (`check.ts` mirrors this, #1309).
+        if (s.kind === 'action' || s.kind === 'stepSwitch')
+            for (const v of stepDeclaredVariables(s.spec, s.options?.version))
+                roots.add(v);
         switch (s.kind) {
             case 'stepToList':
                 addStepNames(s.body, roots);

package/dist/flow-node-registry.js

@@ -8,6 +8,7 @@
  */
 import { NodeTypeRegistry } from './core/nodes/registry.js';
 import { hasBundledDefinition } from './flow-definitions.js';
+import { agentFlowFamily } from './nodes/agent/flow/family.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';
@@ -21,5 +22,5 @@ import { queueFlowFamily } from './nodes/queue/flow/family.js';
 import { scriptFlowFamily } from './nodes/script/flow/family.js';
 import { transformFlowFamily } from './nodes/transform/flow/family.js';
 /** The families, in no significant order. Adding one is the whole of registering it. */
-export const FLOW_NODE_FAMILIES = [aiPatternsFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_FAMILIES = [agentFlowFamily, aiPatternsFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
 export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });

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

@@ -14,6 +14,7 @@ import type { VersionedNodeType } from './core/nodes/versioned.js';
 import type { NodeFamily, Placement } from './core/nodes/family.js';
 import type { DefinitionReference, NodeContribution } from './core/node-classes.js';
 import type { CheckOpts } from './check.js';
+import type { SerializeOpts } from './serialize.js';
 import type { DeclaredExit, NoExits } from './core/step-ports.js';
 /**
  * What a Flow node type's `serialize` returns: the node's type-owned fields.
@@ -65,6 +66,27 @@ export interface FlowNodeContribution extends Omit<NodeContribution, 'definition
      * `{nodeId}` substitution, which a merged contribution's outputs get.
      */
     replaceOutputs?: boolean;
+    /**
+     * Resource nodes this node carries on its artifact handles — an agent's
+     * contexts, tools, escalations and memory. Each is placed after this node and
+     * before the edges into it, drawn as a circle, with no node-level `model`, and
+     * joined by an edge from this node's `port` to the resource's `input`. Its
+     * inputs are written as given (render them first), and its definition is
+     * emitted into `definitions[]` like a per-tenant node's. A resource is not a
+     * step: it takes no control flow and never reaches an End.
+     */
+    attach?: ReadonlyArray<{
+        /** Its node id, from {@link FlowSerializeContext.resourceNodeId}. */
+        readonly id: string;
+        /** Its definition (the manifest). */
+        readonly definition: unknown;
+        readonly label: string;
+        readonly inputs: Readonly<Record<string, unknown>>;
+        /** The artifact handle on THIS node the edge leaves from (`context`, `tool`, `escalation`, `memory`). */
+        readonly port: string;
+        /** Display fields set over the definition's, after `shape: 'circle'` (a tool's `description`). */
+        readonly display?: Readonly<Record<string, unknown>>;
+    }>;
 }
 /** What `serialize` may ask of the serializer, for one placement. */
 export interface FlowSerializeContext {
@@ -95,10 +117,12 @@ export interface FlowSerializeContext {
     /** A deterministic id for `seed`, unique to this flow and node. */
     mint(seed: string): string;
     /**
-     * Hoist a binding entry into the flow's `bindings`, deduplicated by `id`. With
-     * the contribution's own `bindings`, these must close every `<bindings.NAME>`
-     * the node's definition references: serialize refuses a name left open
-     * (`CONTRIBUTION_BINDING_UNRESOLVED`), and `check` does not see bindings.
+     * Hoist a binding entry into the flow's `bindings`, deduplicated by `id`. It is
+     * in {@link bindings} at once, so a second resource of this step sees the
+     * first one's pair. With the contribution's own `bindings`, these must close
+     * every `<bindings.NAME>` the node's definition references: serialize refuses
+     * a name left open (`CONTRIBUTION_BINDING_UNRESOLVED`), and `check` does not
+     * see bindings.
      */
     bind(entry: {
         readonly id: string;
@@ -122,7 +146,15 @@ export interface FlowSerializeContext {
      * refusal check reports, and a value that cannot be a tenant id is warned about
      * (`CONNECTION_STUB`). `where` names the site in both, e.g. `managed http "fetch"`.
      */
-    resolveBinding(name: string, attribute: 'connection' | 'folder', where: string): string;
+    resolveBinding(name: string, attribute: 'connection' | 'folder', where: string, target?: {
+        key: string;
+        action?: string;
+    }): string;
+    /** An unset label resolves to nothing. */
+    resolveBinding(name: string | undefined, attribute: 'connection' | 'folder', where: string, target?: {
+        key: string;
+        action?: string;
+    }): string | undefined;
     /**
      * Hoist the Integration Service connection pair a definition's `model`
      * references (`<bindings.NAME>` for its connection id and folder key), deduped
@@ -133,11 +165,54 @@ export interface FlowSerializeContext {
     bindConnection(o: {
         model: unknown;
         connectorKey: string;
-        connectionId: string;
+        /** Undefined for an unresolved connection: the entries still close the references, with no `default`. */
+        connectionId: string | undefined;
         folderKey?: string;
         /** The entries' `resourceKey`; defaults to `connectionId`. */
         resourceKey?: string;
     }): void;
+    /**
+     * The folder an agent step's files live in (`<source>/agent.json`), a uuid:
+     * `carried` when the author or the file gave one, else one derived from the
+     * flow id and step name, so a recompile is byte-identical — then moved by the
+     * compile's `agentSource` option when it owns the folders (#1184).
+     */
+    agentSource(carried: string | undefined): string;
+    /**
+     * Write a file beside the `.flow` (an agent's `agent.json`), at a path relative
+     * to it. The same file twice is not a clash (a subflow body emitted for two
+     * callers); two different contents at a path an explicit `source` chose are
+     * refused (`INLINE_AGENT_RESOURCE_SOURCE_DUP`). The `json` object is kept, not
+     * copied, so `typeAgentInputs` can still fill it in.
+     */
+    sidecar(file: {
+        path: string;
+        json: unknown;
+    }, explicitSource?: boolean): void;
+    /**
+     * Type an agent sidecar's `inputSchema` once this scope's variables are known:
+     * each ref's `flatName` property gets the JSON Schema of the variable its
+     * `binding` reads, which no step can know while it is serialized (a later step
+     * may declare it).
+     */
+    typeAgentInputs(schema: {
+        properties: Record<string, unknown>;
+        definitions?: Record<string, unknown>;
+    }, refs: ReadonlyArray<{
+        flatName: string;
+        binding: string;
+    }>): void;
+    /**
+     * Claim the node id of a resource this step attaches: `explicit` exactly as
+     * written (decompile writes the file's id), refused when blank or already
+     * another node's (`INLINE_AGENT_RESOURCE_NODE_ID`); else `<seed>`, deduped
+     * file-wide (`<seed>2`, …).
+     */
+    resourceNodeId(explicit: string | undefined, seed: string, where: string): string;
+    /** The definition this flow has already emitted for `type@version`, if any (definitions[] holds one per pair). */
+    emitted(typeName: string, version: string): unknown;
+    /** The connector library serialize was given, for a type that resolves a connector operation. */
+    readonly library: SerializeOpts['library'];
 }
 /** What `deserialize` may ask of the decompiler, for one serialized node. */
 export interface FlowDeserializeContext {
@@ -168,6 +243,33 @@ export interface FlowDeserializeContext {
      * decompile.
      */
     lossy(message: string): void;
+    /**
+     * A file beside the `.flow` (an agent's `<source>/agent.json`) as text, by its
+     * path relative to it; undefined when decompile was given no reader or the
+     * file is not there.
+     */
+    sidecar(path: string): string | undefined;
+    /** The id of the flow being decompiled, as the source will name it: compile derives a resource's folder from it. */
+    readonly flowId: string;
+    /** Another node's definition: the file's own `definitions[]` entry for its type and version. */
+    definitionOf(node: {
+        type: string;
+        typeVersion?: string;
+    }): unknown;
+    /**
+     * The nodes attached to this one on an artifact handle (`tool`, `context`,
+     * `escalation`, `memory`), in edge order, at most `limit` of them. Their edges
+     * are carried by this node's spec, so they are not reported as dropped.
+     */
+    attached(port: string, limit?: number): readonly unknown[];
+    /** The ids of every node attached on that handle, without claiming their edges. */
+    attachedIds(port: string): readonly string[];
+    /**
+     * Record that an attached node folds into this node's spec, and the id
+     * compile will give it (undefined: compile will not emit it again), so what
+     * decompile writes about it — a layout entry — names the recompiled node.
+     */
+    absorb(nodeId: string, compiledId: string | undefined): void;
     /** The source ports this node's out-edges leave from, in edge order (an empty list outside a graph). */
     outPorts(): readonly string[];
     /**
@@ -233,7 +335,29 @@ export interface FlowCheckContext {
     }, use?: {
         id: string;
         connector: string | undefined;
+    }, 
+    /** The connector operation the labels are for, so a refusal names the `prepare` command for it. */
+    target?: {
+        key: string;
+        action?: string;
     }): void;
+    /**
+     * The node ids and folders this step's attached resources take, recorded
+     * file-wide — across the root flow and every subflow, as compile claims them.
+     * An explicit id equal to one another node gets is reported once the whole
+     * file is checked (`INLINE_AGENT_RESOURCE_NODE_ID`).
+     */
+    readonly resources: {
+        /** An id compile derives for one of this step's resources, and what it is, for that report. */
+        derivedNodeId(id: string, what: string): void;
+        /** Claim an explicit node id: the earlier claimant when one already has it (and nothing is recorded), else undefined. */
+        claimNodeId(id: string, what: string): {
+            step: string;
+            what: string;
+        } | undefined;
+        /** Claim an agent's folder (its `source`, compared lower-cased): the other step that has it, else undefined. */
+        claimFolder(source: string): string | undefined;
+    };
 }
 /** What a family-level `check` may ask of the checker. */
 export interface FlowFamilyCheckContext {
@@ -317,6 +441,15 @@ export interface FlowNodeType<Spec> extends NodeType<Spec, FlowNodeContribution,
      * one of these (`.onError()` routes it).
      */
     exits?(spec: Spec, pinnedVersion?: string): DeclaredExit[] | NoExits;
+    /**
+     * The flow variables a step of this type DECLARES by running: names a later
+     * `$vars.<name>` read resolves to that are neither a `.var()` nor a step
+     * name. A quick form's asked field lands its answer in its `variable`
+     * (`vars.<Step>_<field>`, as the designer names it), so the task declares
+     * that variable. `check` adds them to its declared set (#1309). Omitted: the
+     * type declares none.
+     */
+    declares?(spec: Spec, pinnedVersion?: string): string[];
     /**
      * 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

package/dist/flow-sdk.d.ts

@@ -18,6 +18,7 @@
  */
 export * from './core/expr.js';
 export * from './core/actions.js';
+export * from './nodes/agent/flow/index.js';
 export * from './nodes/ai-patterns/flow/index.js';
 export * from './nodes/conversation/flow/index.js';
 export * from './nodes/data-fabric/flow/index.js';
@@ -443,6 +444,39 @@ export interface NodeOptions {
      */
     label?: string;
 }
+/**
+ * The options of `.parallel()`: the join's {@link NodeOptions}, plus the fork
+ * node when the flow has one.
+ */
+export interface ParallelOptions extends NodeOptions {
+    /**
+     * A FORK node the arms leave from: a `core.logic.merge` with one incoming
+     * edge and one edge per arm, which is how Studio Web draws a parallel split
+     * (its "Parallel" gateway). Without it the arms leave from the previous
+     * step's own port, one edge per arm, which the platform runs the same way.
+     * Name it to round-trip a flow the canvas drew with a fork node; `label` is
+     * the canvas text, defaulting to the name, and `version` the fork node's
+     * exact `core.logic.merge` version when it differs from the join's.
+     *
+     * ```ts
+     * .parallel('join', [(a) => a.step('t1', …), (b) => b.step('t2', …)], { fork: 'split' })
+     * ```
+     */
+    fork?: string | {
+        name: string;
+        label?: string;
+        version?: string;
+    };
+}
+/**
+ * The fork node a `.parallel()` asks for, normalized, or `undefined`.
+ * @internal
+ */
+export declare function parallelFork(options: ParallelOptions | undefined): {
+    name: string;
+    label?: string;
+    version?: string;
+} | undefined;
 /**
  * `.return(...)`-specific options.
  *
@@ -587,15 +621,16 @@ export type Step = {
 /**
  * A fan-out and its join. `arms` is one step list per arm — an ARRAY, because
  * arms are positional and carry no author-supplied keys — and `name` names the
- * Merge node the arms converge on (the only node this step creates; the fork
- * itself is just N edges out of one port).
+ * Merge node the arms converge on (the only node this step creates unless
+ * `options.fork` names a fork node too; otherwise the fork is just N edges
+ * out of one port).
  */
  | {
     kind: 'parallel';
     name: string;
     label?: string;
     arms: Step[][];
-    options?: NodeOptions;
+    options?: ParallelOptions;
 }
 /**
  * A hard stop: `core.logic.terminate`, a BPMN End event carrying a
@@ -1136,11 +1171,12 @@ declare class StepList {
      * @param arms - One callback per parallel arm, each receiving its own
      * sub-builder. Two or more.
      * @param options - Node options; `version` selects the exact definition
-     * version (see {@link NodeOptions}).
+     * version (see {@link NodeOptions}), and `fork` names a fork node the arms
+     * leave from (see {@link ParallelOptions}).
      * @returns This builder, positioned after the Merge — so what you chain next
      * runs once, when every arm has finished.
      */
-    parallel(name: string, arms: ((b: StepList) => void)[], options?: NodeOptions): this;
+    parallel(name: string, arms: ((b: StepList) => void)[], options?: ParallelOptions): this;
     /**
      * Iterate `collection`; `bodyFn` receives a sub-builder for the loop body.
      *

package/dist/flow-sdk.js

@@ -22,6 +22,7 @@
 export * from './core/expr.js';
 export * from './core/actions.js';
 // Node families' public surfaces (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §8).
+export * from './nodes/agent/flow/index.js';
 export * from './nodes/ai-patterns/flow/index.js';
 export * from './nodes/conversation/flow/index.js';
 export * from './nodes/data-fabric/flow/index.js';
@@ -263,6 +264,18 @@ export function conversationTrigger() {
 export function voiceTrigger() {
     return builtinTriggerSpec({ kind: 'voice' });
 }
+/**
+ * The fork node a `.parallel()` asks for, normalized, or `undefined`.
+ * @internal
+ */
+export function parallelFork(options) {
+    const fork = options?.fork;
+    if (fork === undefined)
+        return undefined;
+    return typeof fork === 'string'
+        ? { name: fork }
+        : { name: fork.name, ...(fork.label !== undefined ? { label: fork.label } : {}), ...(fork.version !== undefined ? { version: fork.version } : {}) };
+}
 /**
  * A node's layout at a canvas position — the short form of a {@link NodeLayout}
  * for the `nodes` map of {@link FlowBuilder.layout}.
@@ -763,7 +776,8 @@ class StepList {
      * @param arms - One callback per parallel arm, each receiving its own
      * sub-builder. Two or more.
      * @param options - Node options; `version` selects the exact definition
-     * version (see {@link NodeOptions}).
+     * version (see {@link NodeOptions}), and `fork` names a fork node the arms
+     * leave from (see {@link ParallelOptions}).
      * @returns This builder, positioned after the Merge — so what you chain next
      * runs once, when every arm has finished.
      */

package/dist/flow-step-variables.d.ts

@@ -0,0 +1,4 @@
+export declare function stepDeclaredVariables(spec: {
+    kind?: unknown;
+    inputs?: unknown;
+} | undefined, pinnedVersion?: string): string[];

package/dist/flow-step-variables.js

@@ -0,0 +1,22 @@
+/**
+ * The flow variables a step DECLARES by running (`FlowNodeType.declares`): a
+ * quick form's asked fields land in their `variable` (`vars.<Step>_<field>` as
+ * the designer names it), and later steps read `$vars.<name>`. Resolved at the
+ * version the step resolves to, the way `stepExits` does, so `check` and
+ * `flow-expr-check` agree on what a step publishes (#1309).
+ */
+import { resolveVersion } from './core/nodes/versioned.js';
+import { FLOW_NODE_TYPES } from './flow-node-registry.js';
+export function stepDeclaredVariables(spec, pinnedVersion) {
+    const entry = typeof spec?.kind === 'string' ? FLOW_NODE_TYPES.byKind(spec.kind, spec) : undefined;
+    if (!entry)
+        return [];
+    let impl;
+    try {
+        impl = resolveVersion(entry.type, spec, pinnedVersion, 'declares');
+    }
+    catch {
+        impl = resolveVersion(entry.type, spec, undefined, 'declares');
+    }
+    return impl.declares?.(spec, pinnedVersion) ?? [];
+}

package/dist/loop-version.d.ts

@@ -3,28 +3,45 @@ import type { LoopOptions, Step } from './flow-sdk.js';
 export declare const LOOP_NODE_TYPE = "core.logic.loop";
 /** The `core.logic.loop` version `.loop()` emits unless `{ version }` pins another. */
 export declare const LOOP_DEFAULT_VERSION = "2.4";
+/**
+ * The definition a loop at `version` compiles against: the bundled one, else
+ * the one the flow carries (`carried`, a `.definitions()` lookup), else
+ * `undefined`. `serialize` and `check` both resolve through this, so they agree
+ * on a carried `core.logic.loop@1.0`'s handles and inputs (#1311).
+ */
+export declare function resolveLoopDefinition(version: string, carried?: (type: string, version: string) => unknown): unknown;
 /** The version `.loop()` emits for these options. */
 export declare function loopVersion(options: LoopOptions | undefined): string;
 /**
  * True when this loop version's body runs from the inner `start` handle and goes
  * back through `continue` (2.x); false for the legacy `output`/`loopBack` shape.
- * A version with no bundled definition counts as 2.x; its lookup fails later.
+ *
+ * The answer is read off the definition's target handles. `definition` is the
+ * one the loop compiles against: the bundled one for `version` by default, or
+ * the one the flow carries (`.definitions([...])`) when the SDK bundles none —
+ * a designer-saved `core.logic.loop@1.0` keeps its `output`/`loopBack` handles
+ * only because its carried definition says so (#1311). A version with no
+ * definition at all counts as 2.x; its lookup fails later.
  */
-export declare function loopHasInnerHandles(version: string): boolean;
+export declare function loopHasInnerHandles(version: string, definition?: unknown): boolean;
 /**
  * The features this loop uses that its version's definition cannot express, in
  * a fixed order (`parallel`, `completionCondition`, `breakEnabled`, `break()`).
  * Empty when all are supported, or when no definition is bundled for the version
  * (an unknown version is reported elsewhere, by the definition lookup).
  */
-export declare function unsupportedLoopFeatures(options: LoopOptions | undefined, usesBreak: boolean): string[];
+export declare function unsupportedLoopFeatures(options: LoopOptions | undefined, usesBreak: boolean, definition?: unknown): string[];
+/** The inputs a loop definition declares (`collection`, `parallel`, `completionCondition`, `breakEnabled`, …). */
+export declare function loopDeclaredInputs(definition: unknown): Record<string, unknown>;
 /**
  * The refusal for a loop whose options or body need a definition the requested
  * version does not have, or `undefined` when there is nothing to refuse.
  * `serialize` throws it; `check` reports it as `LOOP_VERSION_UNSUPPORTED` with
- * the same text, so the author reads one message in both places.
+ * the same text, so the author reads one message in both places. `definition`
+ * is the one the loop compiles against (bundled, else carried), as for
+ * `loopHasInnerHandles`.
  */
-export declare function loopVersionRefusal(name: string, options: LoopOptions | undefined, usesBreak: boolean): string | undefined;
+export declare function loopVersionRefusal(name: string, options: LoopOptions | undefined, usesBreak: boolean, definition?: unknown): string | undefined;
 /**
  * The warning for `parallel: true` on a 1.0.0 loop, or `undefined`. The 1.0.0
  * definition declares the input, so the loop compiles and a canvas 1.0.0 loop
@@ -32,7 +49,7 @@ export declare function loopVersionRefusal(name: string, options: LoopOptions |
  * confirmed, so a new loop that needs that should use the default version.
  * `check` reports it as `LOOP_PARALLEL_LEGACY`.
  */
-export declare function loopParallelWarning(name: string, options: LoopOptions | undefined): string | undefined;
+export declare function loopParallelWarning(name: string, options: LoopOptions | undefined, definition?: unknown): string | undefined;
 /**
  * True when a container body (or an arm/handler inside it, but not a NESTED
  * container's body) breaks: a nested `.loop()`/`.doWhile()` owns its own

package/dist/loop-version.js

@@ -11,6 +11,15 @@ import { BUNDLED_DEFINITIONS } from './flow-definitions.js';
 export const LOOP_NODE_TYPE = 'core.logic.loop';
 /** The `core.logic.loop` version `.loop()` emits unless `{ version }` pins another. */
 export const LOOP_DEFAULT_VERSION = '2.4';
+/**
+ * The definition a loop at `version` compiles against: the bundled one, else
+ * the one the flow carries (`carried`, a `.definitions()` lookup), else
+ * `undefined`. `serialize` and `check` both resolve through this, so they agree
+ * on a carried `core.logic.loop@1.0`'s handles and inputs (#1311).
+ */
+export function resolveLoopDefinition(version, carried) {
+    return loopDefinition(version) ?? carried?.(LOOP_NODE_TYPE, version);
+}
 /** The version `.loop()` emits for these options. */
 export function loopVersion(options) {
     return options?.version ?? LOOP_DEFAULT_VERSION;
@@ -18,10 +27,16 @@ export function loopVersion(options) {
 /**
  * True when this loop version's body runs from the inner `start` handle and goes
  * back through `continue` (2.x); false for the legacy `output`/`loopBack` shape.
- * A version with no bundled definition counts as 2.x; its lookup fails later.
+ *
+ * The answer is read off the definition's target handles. `definition` is the
+ * one the loop compiles against: the bundled one for `version` by default, or
+ * the one the flow carries (`.definitions([...])`) when the SDK bundles none —
+ * a designer-saved `core.logic.loop@1.0` keeps its `output`/`loopBack` handles
+ * only because its carried definition says so (#1311). A version with no
+ * definition at all counts as 2.x; its lookup fails later.
  */
-export function loopHasInnerHandles(version) {
-    return loopDefinition(version) ? targetHandleIds(version).has('continue') : true;
+export function loopHasInnerHandles(version, definition = loopDefinition(version)) {
+    return definition ? targetHandleIdsOf(definition).has('continue') : true;
 }
 /** The loop options whose support depends on the version, in message order. */
 const VERSIONED_OPTIONS = ['parallel', 'completionCondition', 'breakEnabled'];
@@ -31,24 +46,29 @@ const VERSIONED_OPTIONS = ['parallel', 'completionCondition', 'breakEnabled'];
  * Empty when all are supported, or when no definition is bundled for the version
  * (an unknown version is reported elsewhere, by the definition lookup).
  */
-export function unsupportedLoopFeatures(options, usesBreak) {
-    const def = loopDefinition(loopVersion(options));
-    if (!def)
+export function unsupportedLoopFeatures(options, usesBreak, definition = loopDefinition(loopVersion(options))) {
+    if (!definition)
         return [];
-    const inputs = def.inputDefinition?.properties ?? {};
+    const inputs = loopDeclaredInputs(definition);
     const out = VERSIONED_OPTIONS.filter((k) => options?.[k] !== undefined && !(k in inputs));
-    if (usesBreak && !targetHandleIds(loopVersion(options)).has('break'))
+    if (usesBreak && !targetHandleIdsOf(definition).has('break'))
         out.push('break()');
     return out;
 }
+/** The inputs a loop definition declares (`collection`, `parallel`, `completionCondition`, `breakEnabled`, …). */
+export function loopDeclaredInputs(definition) {
+    return definition?.inputDefinition?.properties ?? {};
+}
 /**
  * The refusal for a loop whose options or body need a definition the requested
  * version does not have, or `undefined` when there is nothing to refuse.
  * `serialize` throws it; `check` reports it as `LOOP_VERSION_UNSUPPORTED` with
- * the same text, so the author reads one message in both places.
+ * the same text, so the author reads one message in both places. `definition`
+ * is the one the loop compiles against (bundled, else carried), as for
+ * `loopHasInnerHandles`.
  */
-export function loopVersionRefusal(name, options, usesBreak) {
-    const missing = unsupportedLoopFeatures(options, usesBreak);
+export function loopVersionRefusal(name, options, usesBreak, definition = loopDefinition(loopVersion(options))) {
+    const missing = unsupportedLoopFeatures(options, usesBreak, definition);
     if (missing.length === 0)
         return undefined;
     const version = loopVersion(options);
@@ -63,8 +83,8 @@ export function loopVersionRefusal(name, options, usesBreak) {
  * confirmed, so a new loop that needs that should use the default version.
  * `check` reports it as `LOOP_PARALLEL_LEGACY`.
  */
-export function loopParallelWarning(name, options) {
-    if (options?.parallel !== true || loopHasInnerHandles(loopVersion(options)))
+export function loopParallelWarning(name, options, definition = loopDefinition(loopVersion(options))) {
+    if (options?.parallel !== true || loopHasInnerHandles(loopVersion(options), definition))
         return undefined;
     return `loop "${name}": parallel: true on { version: '${loopVersion(options)}' } is written to the node, but `
         + `that version is not confirmed to run iterations in parallel, so the loop may run them one by one. `
@@ -86,9 +106,11 @@ export function bodyUsesBreak(steps) {
 function loopDefinition(version) {
     return BUNDLED_DEFINITIONS[`${LOOP_NODE_TYPE}@${version}`];
 }
-function targetHandleIds(version) {
+/** The ids of a definition's target handles (`input`, `loopBack`, `continue`, `break`, …). */
+function targetHandleIdsOf(definition) {
     const ids = new Set();
-    for (const group of loopDefinition(version)?.handleConfiguration ?? []) {
+    const groups = definition?.handleConfiguration ?? [];
+    for (const group of groups) {
         for (const h of group.handles ?? [])
             if (h.type === 'target')
                 ids.add(h.id);

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

@@ -0,0 +1,88 @@
+/**
+ * The agents family's rules: what is decidable from a call to
+ * `conversationalAgent()`, `voiceAgent()`, `createOutgoingCall()`, `endCall()`
+ * or `inlineAgent()` — the turn wiring, the call's numbers, the `callContext`
+ * the voice steps share, and an inline agent's prompts, inputs, guardrails and
+ * resources. 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 { OutputPathRead } from '../../../core/nodes/node-type.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import type { InlineAgentInputs } from './spec.js';
+export declare const AGENT_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * A conversational AGENT step (Phase 5).
+ *
+ * The turn wiring is the whole risk: `'simple'` mode reads everything out of
+ * ONE conversation-context binding, so a flow that names neither the context
+ * nor the individual fields deploys an agent with no transcript to answer.
+ */
+export declare function checkConversationalAgent(inputs: Record<string, unknown> | undefined, ctx: FlowCheckContext): void;
+/**
+ * A VOICE step (Phase 5D): create-outgoing-call, end-call, or the voice agent.
+ *
+ * Two things are decidable offline and expensive later: a call needs both
+ * numbers in a form the telephony provider accepts, and every voice step needs
+ * the `callContext` OBJECT — binding a bare conversation id instead is the
+ * classic mistake, because the field is typed `object` and a string passes the
+ * file's schema while failing at dispatch.
+ */
+export declare function checkVoice(kind: 'createOutgoingCall' | 'endCall' | 'voiceAgent', inputs: Record<string, unknown> | undefined, ctx: FlowCheckContext): void;
+/**
+ * The phrase in `text` that tells a model to answer in JSON TEXT, or `undefined`.
+ *
+ * `check` uses it for `INLINE_AGENT_PROMPT_JSON_TEXT`, passing the step's `returns`
+ * keys so the brace form only counts a brace that spells one of them. Without
+ * `returnKeys` (the example and doc sweeps) any quoted identifier key counts.
+ * `{{input.*}}` placeholders are removed first, so an input named `json` never
+ * matches.
+ *
+ * @example
+ * ```ts
+ * jsonTextDirective('Return ONLY a JSON object with keys "subject" and "body".'); // 'Return ONLY a JSON'
+ * jsonTextDirective('Return ONLY {"category","priority"}.', ['category']);       // '{"category",'
+ * jsonTextDirective('Return a result conforming to the output schema.');          // undefined
+ * jsonTextDirective('Do not return JSON.');                                       // undefined
+ * jsonTextDirective('Answer the question using the JSON data below.');            // undefined
+ * ```
+ */
+export declare function jsonTextDirective(text: string, returnKeys?: readonly string[]): string | undefined;
+/**
+ * Check an `inlineAgent(...)` call.
+ *
+ * The interesting difference from every other node this SDK authors: **nothing here
+ * lives on a tenant.** An inline agent's whole contract is in the call, so these
+ * rules can be certain rather than best-effort — the definition's own `required`
+ * list is checkable, and so is whether the prompts and the declared variables agree.
+ *
+ * Three rules exist because the PLATFORM does something with what you wrote:
+ *
+ *  - `INLINE_AGENT_SCAFFOLD_MODEL` — the model the platform's own scaffold ships is
+ *    stale, and v1's smoke check for this node type fails a flow that keeps it. A
+ *    warning, not an error: it is a real model id, it just should not be a default
+ *    nobody chose.
+ *  - `INLINE_AGENT_UNREFERENCED_INPUT` — flow-v1 derives the deployed input list by
+ *    scanning the PROMPTS for `$vars.*` references and only falls back to the
+ *    authored `agentInputVariables` when that pre-pass did not run. So a declared
+ *    input the prompts never mention is pruned deployed while arriving locally: a
+ *    disagreement between rungs and the platform, which is the one class that has to
+ *    be said out loud rather than left to a run.
+ *  - `INLINE_AGENT_PROMPT_JSON_TEXT` — the platform returns `returns` as a typed
+ *    object: it becomes the `agent.json` `outputSchema`, and the agent runtime ends
+ *    a run with a structured call that fills exactly those fields. A prompt that
+ *    ALSO asks for JSON text makes the model pack its whole answer, serialized, into
+ *    one string field. See {@link jsonTextDirective}.
+ */
+export declare function checkInlineAgent(inputs: InlineAgentInputs | undefined, ctx: FlowCheckContext): void;
+/**
+ * A read of an inline agent's output: `out('<step>', '<field>')`.
+ *
+ * Stricter than the published families' equivalent, and it can afford to be: the
+ * declared `returns` IS the contract (there is no tenant to disagree with), and it
+ * is what any runner has to coerce the model's completion to: build
+ * `{ <declared keys> }` and put the raw completion in the first one if the model
+ * ignored the shape. So a read outside the set is undefined by construction, not
+ * merely probably.
+ */
+export declare function checkInlineAgentRead({ node: name, field, rest, reader: step }: OutputPathRead, spec: InlineAgentInputs, report: (code: string, message: string, suggestion?: string) => void): void;