@uipath/maestro-builder-sdk 6.42.0 → 6.43.0

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 {

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';

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';

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;