@uipath/maestro-builder-sdk 5.2.0

package/dist/core/actions.d.ts

@@ -0,0 +1,3244 @@
+/**
+ * core/actions — action specifications shared by every builder SDK.
+ *
+ * An action describes *what a node does* (an HTTP call, an inline script, an
+ * Integration Service connector activity) independent of which artifact it
+ * lives in — a Flow step, a Case connector task, or a BPMN service task all
+ * take the same specs. Each domain's serializer maps an `ActionSpec` onto its
+ * target node shape.
+ */
+import type { Expr } from './expr.js';
+import type { LookupToken } from './lookups.js';
+import { type ConnectorDescriptor, type TriggerDescriptor } from './connectors.js';
+import type { ScriptReturns } from './script-return.js';
+/** One conditional response branch on an HTTP node — a designer-visible side exit. */
+export interface HttpBranch {
+    /**
+     * The branch's name — it becomes the node's `branch-<name>` source port, so
+     * keep it port-safe (letters, digits, `_`, `-`). Route it with
+     * `.stepToList('branch-<name>', ...)` after the step; the main path continues
+     * from the default port as always.
+     */
+    name: string;
+    /**
+     * When to take this exit, evaluated against the response — e.g.
+     * js-tagged: `$vars.fetch.output.statusCode === 429`. Branches are checked in
+     * order; the first truthy one wins, else the default port fires.
+     */
+    condition: Expr;
+}
+interface HttpInputsBase {
+    /**
+     * Conditional response branches — extra source ports (`branch-<name>`)
+     * beside the default. See {@link HttpBranch}; both HTTP node families
+     * declare them.
+     */
+    branches?: HttpBranch[];
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string | Expr;
+    headers?: Record<string, string | Expr>;
+    query?: Record<string, string | Expr>;
+    body?: string | Expr;
+    contentType?: string;
+    /**
+     * Choose the HTTP node explicitly. `false` emits the standalone
+     * `core.action.http`; `true` emits the managed `core.action.http.v2`, routed
+     * through Integration Service's HTTP connector.
+     *
+     * This has no default because these are different platform nodes, not two
+     * modes of one node. A silent `false` made an omitted field compile and
+     * validate as the wrong node while changing failure routing and connection
+     * behavior.
+     *
+     * It is not a version bump, it changes two things you can see:
+     *
+     * - **a 4xx/5xx FAILS the step**, so `.onError(…)` fires on it. On the plain
+     *   node the same 404 comes back on the SUCCESS path as
+     *   `out('fetch','statusCode')` and no error handler ever runs — which is why
+     *   an error port only makes sense here (`check` says so: HTTP_ONERROR_V1).
+     *   The handler can answer the flow (`.return`), stop the run
+     *   (`.terminate`), or compensate and continue at a step the success path
+     *   also reaches (`h.rejoin('<step>')` — see `references/error-handling.md`);
+     * - both nodes expose JSON responses as parsed values in the live product;
+     *   use `returns` to declare fields before reading them. The node choice does
+     *   not decide whether application/json is parsed.
+     *
+     * With `managed: true`, omit `connection` and `folder` for the platform's
+     * manual/implicit mode, or provide both symbolic names to reuse an Integration
+     * Service HTTP connection. A local run remains unauthenticated.
+     *
+     * @enforcedBy HTTP_ONERROR_V1 `.onError()` on an http step needs `managed: true`; on
+     * the standalone node a 4xx arrives on the SUCCESS path and no handler runs.
+     */
+    managed: boolean;
+    /**
+     * The response BODY's top-level fields and their types — e.g.
+     * `{ items: 'array' }`. Required for either HTTP node if anything reads a
+     * field off a parsed JSON body.
+     *
+     * Why you have to say: the platform's own definition declares the response as
+     * a bare object, because only the API being called knows its shape. Without
+     * this, `out('fetch','body','items')` reads from an object with no declared
+     * fields, and nothing downstream can tell a real field from a typo. Same rule,
+     * and the same word, as
+     * `rpaWorkflow`'s `returns`.
+     */
+    returns?: Record<string, ReturnFieldType>;
+    /**
+     * How long to wait for the response before giving up, as an **ISO-8601
+     * duration** — `'PT30S'` is "give up after 30 seconds", `'PT1M'` one minute,
+     * `'PT15M'` fifteen.
+     *
+     * Both http node types carry this, and both definitions declare the same
+     * default (`PT15M`), so leaving it unset is not "no timeout" — it is fifteen
+     * minutes. Omitted from the emitted node unless you set it, which keeps a flow
+     * that doesn't care byte-identical to the platform's own default shape (~99%
+     * of the 808 deployed http nodes are on the defaults).
+     *
+     * `check` rejects a string the platform cannot parse as a duration —
+     * `'30s'`, `'PT'` and `'30'` are all errors that name the expected form.
+     *
+     * @defaultValue `'PT15M'`
+     * @enforcedBy HTTP_TIMEOUT_NOT_DURATION Must be an ISO-8601 duration.
+     */
+    timeout?: string;
+    /**
+     * How many times to RETRY a retryable failure (5xx, 429, a network error) —
+     * `0`, the definitions' default, means "try once, don't retry". `2` means up
+     * to three attempts in total.
+     *
+     * Must be a non-negative integer. Above **5** `check` warns rather than
+     * errors: the deployed corpus's
+     * largest author-set value is 3, and the platform's own ceiling is not
+     * measured — so a bigger number may well work, and refusing it outright would
+     * fence off something we have no evidence is wrong.
+     *
+     * @defaultValue `0`
+     * @enforcedBy HTTP_RETRY_COUNT_INVALID Must be a non-negative integer.
+     */
+    retryCount?: number;
+}
+export type HttpInputs = HttpInputsBase & ({
+    managed: false;
+    connection?: never;
+    folder?: never;
+} | {
+    managed: true;
+    /** Symbolic HTTP connection name declared in bindings.json. */
+    connection?: string;
+    /** Symbolic folder name declared in bindings.json. */
+    folder?: string;
+    /**
+     * Connector key whose authentication the HTTP proxy should reuse.
+     * Defaults to `uipath-uipath-http`. Set this for a connector-specific
+     * fallback endpoint, for example `uipath-salesforce-slack`.
+     * Requires both `connection` and `folder`.
+     */
+    targetConnector?: string;
+});
+export interface ScriptInputs {
+    /** JavaScript body. Must `return` its result. Referenced via out('<step>'). */
+    code: string;
+    /**
+     * What the body RETURNS — the type of `out('<step>')`.
+     *
+     * The platform's definition can only say `output: {type: 'object'}` (a node
+     * type cannot know what a particular body returns), so the designer types
+     * every script read as `Record<string, any>` and reports mapping one into a
+     * `string` output as `Type 'Record<string, any>' is not assignable to type
+     * 'string'` — on a flow that is correct and runs.
+     *
+     * **Usually you do not need this.** The compiler reads the body and declares
+     * what it plainly returns, so `return "pending-approval"` is already a
+     * `string`. Reach for `returns` when the body does not say so syntactically —
+     * a value that comes back from a runtime read, or an object assembled
+     * dynamically:
+     *
+     * ```ts
+     * .step('policyLimit', script({
+     *   code: 'return $vars.fetchPolicy.output.body.limit;',
+     *   returns: 'number',
+     * }))
+     * ```
+     *
+     * For an object return, name the FIELDS instead — the spelling every other
+     * action's `returns` uses, and what licenses `out('<step>', '<field>')`:
+     *
+     * ```ts
+     * returns: { total: 'number', currency: 'string' }
+     * ```
+     *
+     * An explicit `returns` always wins over what the body looks like. Nothing is
+     * inferred when the body does not plainly agree with itself, and an unknown
+     * shape stays the definition's open object rather than being guessed at.
+     */
+    returns?: ScriptReturns;
+}
+export interface ConnectorOpts {
+    /** Connector action version (defaults to the library's newest match). */
+    version?: string;
+    /** Symbolic connection name declared in bindings.json (→ ConnectionId). */
+    connection?: string;
+    /** Symbolic folder name declared in bindings.json (→ connectionFolderKey). */
+    folder?: string;
+    /**
+     * Which OBJECT a **generic** operation addresses — e.g. ServiceNow's "List All
+     * Records" on `'acr_user'`, NetSuite's "Get Record" on `'AccountingPeriod'`.
+     *
+     * A generic (`GenericExpanded`) operation encodes only the VERB in its node
+     * type, and the library carries one entry per object underneath it:
+     * `uipath.connector.uipath-oracle-netsuite.get-record` alone covers **182
+     * objects**. Measured on the shipped library: **448 of 1,823 nodeTypes map to
+     * more than one entry, 5,206 entries deep**
+     * ([#143](https://github.com/UiPath/flow-builder-sdk/issues/143)) — so without
+     * this, `connector(key, action, …)` could only ever reach whichever object
+     * sorted first, silently.
+     *
+     * ```ts
+     * connector('uipath-servicenow-servicenow', 'list-all-records', {},
+     *           { connection: 'servicenow', folder: 'shared', object: 'acr_user' })
+     * ```
+     *
+     * **Omitting it on an ambiguous nodeType is a compile error** that lists the
+     * objects (with a nearest-match hint) — the alternative, keeping first-match,
+     * is what made the defect silent.
+     *
+     * **An object the library does not list is ACCEPTED, with a warning.** A
+     * connector's object set is scoped to the *connection*, not to the registry
+     * snapshot: `acr_user` is a real ServiceNow table and appears in no library
+     * entry. So the contract is: stamp it, flag it `objectNameUnverified`, and let
+     * the tenant boundary resolve it before dispatch — the SDK refusing what the
+     * platform accepts would just be the two layers disagreeing.
+     *
+     * Passing it for a CURATED (single-entry) operation whose entry names a
+     * different object is an error: nothing could make that right.
+     */
+    object?: string;
+}
+/** How a filter combines its rules: every rule must match, or any one. */
+export type FilterMatch = 'and' | 'or';
+/** Comparison a filter rule applies to a field. */
+export type FilterCondition = 'equals' | 'not_equals' | 'greater_than' | 'less_than' | 'greater_equal' | 'less_equal' | 'contains' | 'not_contains' | 'starts_with' | 'not_starts_with' | 'ends_with' | 'not_ends_with' | 'matches_regex' | 'in' | 'not_in' | 'is_null' | 'is_not_null' | 'is_empty' | 'is_not_empty';
+export interface FilterRule {
+    /** Field on each item. Dot-paths reach nested fields (`'order.amount'`). */
+    field: string;
+    condition: FilterCondition;
+    /**
+     * What to compare against — a LITERAL only. The transform runtime reads this
+     * value as-is and evaluates nothing, so an expression here would compare every
+     * item against that text and match nothing. Hence `Expr` is not accepted: for
+     * a dynamic threshold, filter in a `script` step instead.
+     * Omit for the value-free conditions (`is_null`, `is_empty`, …).
+     */
+    value?: string | number | boolean | null;
+}
+/** What a map does to a field's value. Only `copy` is meaningful for non-text. */
+export type Transformation = 'copy' | 'uppercase' | 'lowercase' | 'trim';
+export interface FieldMapping {
+    /** Field to carry into the output. Must exist on the item, or it is skipped. */
+    field: string;
+    /** Defaults to `'copy'` (the value unchanged). */
+    transformation?: Transformation;
+    /** Output field name. Omit to keep `field`'s own name. */
+    renameTo?: string;
+}
+export type AggregationOperation = 'count' | 'sum' | 'average' | 'min' | 'max' | 'first' | 'last' | 'collect';
+export interface Aggregation {
+    operation: AggregationOperation;
+    /** Output field name for the aggregate. Required. */
+    alias: string;
+    /** Field to aggregate. Required for every operation except `count`. */
+    field?: string;
+}
+/**
+ * One link in the chain. Operations run in the order given, and each one's
+ * result is the next one's input — so a `map` that drops a field puts it out of
+ * reach of a later `filter`.
+ */
+export type TransformOperation = {
+    type: 'filter';
+    filters: FilterRule[];
+    operation?: FilterMatch;
+} | {
+    type: 'map';
+    mappings: FieldMapping[];
+    keepOriginalFields?: boolean;
+} | {
+    type: 'groupBy';
+    groupByField: string;
+    aggregations?: Aggregation[];
+};
+/**
+ * Which Transform node type to emit.
+ *
+ * @remarks
+ * The platform ships four: the generic `core.action.transform`, which chains N
+ * operations, plus three single-purpose variants that each run exactly one.
+ * They share ONE runtime — flow-v1 routes all four node types through the same
+ * script generators and dispatches on the OPERATION's `type`, never the node's
+ * (`bpmn-to-xml.ts`'s `DATA_TRANSFORM_NODE_TYPES` / `generateDataTransformScript`).
+ * So a variant is the generic constrained to one operation, wearing a
+ * self-describing node type and its own editor in the designer.
+ *
+ * Note the spelling: the node type is `core.action.transform.group-by`
+ * (hyphen), while the operation it carries is `type: 'groupBy'` (camelCase) —
+ * that mismatch is the platform's, not ours.
+ */
+export type TransformVariant = 'map' | 'filter' | 'group-by';
+/**
+ * The operation `type` each variant node must carry — one of, and only.
+ *
+ * @internal Serializer plumbing; an author states the variant, not the mapping.
+ */
+export declare const VARIANT_OPERATION: Record<TransformVariant, TransformOperation['type']>;
+export interface TransformInputs {
+    /**
+     * The array to transform, as a REFERENCE: `v('catalog')` or
+     * `out('fetchOrders', 'body.items')`.
+     *
+     * This is a variable PATH, not a value field — the runtime turns the string
+     * into a lookup. An inline array or a computed `js` expression therefore
+     * resolves to nothing, which is why the type is `Expr` and `check` rejects
+     * anything that is not a bare `$vars.…` path. Keep static data in a
+     * `.var(name, types.array, [...])` default and point here.
+     */
+    collection: Expr;
+    /**
+     * Emit a single-purpose variant node instead of the generic Transform.
+     * Omit it for the generic (the default).
+     *
+     * With a variant, `operations` must hold exactly ONE operation of the
+     * matching type — `'filter'` → `type: 'filter'`, `'map'` → `type: 'map'`,
+     * `'group-by'` → `type: 'groupBy'`. `check` rejects anything else, naming
+     * both the variant and the operation it found.
+     */
+    variant?: TransformVariant;
+    /** At least one operation — an empty chain is a no-op node. */
+    operations: TransformOperation[];
+}
+/**
+ * A form field's type. These are the platform's own strings — an unrecognized
+ * one is NOT an error there, it silently normalizes to text (so a number field
+ * becomes a text box), which is why `check` rejects anything outside this set.
+ */
+export type FormFieldType = 'text' | 'number' | 'boolean' | 'date-time';
+/** A value the reviewer READS: shown on the form, filled in from the flow. */
+export interface ShownField {
+    /** Field id — the key the answer object uses. Must be unique on the form. */
+    id: string;
+    /** Label the reviewer sees. Defaults to `id`. */
+    label?: string;
+    type: FormFieldType;
+    direction: 'input';
+    /**
+     * What to show — a reference, e.g. `input('amount')` or
+     * `out('fetchInvoice', 'body.total')`. Required: a shown field with nothing
+     * bound to it renders EMPTY on the deployed form, so the flow says "show them
+     * this" and shows them nothing.
+     */
+    value: Expr;
+}
+/** A value the reviewer FILLS IN: read downstream with `out('<step>', '<id>')`. */
+export interface AskedField {
+    /** Field id — the key the answer object uses. Must be unique on the form. */
+    id: string;
+    /** Label the reviewer sees. Defaults to `id`. */
+    label?: string;
+    type: FormFieldType;
+    direction: 'output';
+    /** Reviewer must fill it in before the task can be completed. */
+    required?: boolean;
+}
+/**
+ * A value the reviewer READS **and can correct**: pre-filled from the flow,
+ * editable on the form, and the (possibly changed) value comes back as an
+ * answer. Read it downstream with `out('<step>', '<id>')` — the write target is
+ * the field's own id, deliberately decoupled from where the pre-fill came from.
+ */
+export interface InOutField {
+    /** Field id — the key the answer object uses. Must be unique on the form. */
+    id: string;
+    /** Label the reviewer sees. Defaults to `id`. */
+    label?: string;
+    type: FormFieldType;
+    direction: 'inOut';
+    /** What to pre-fill — a reference, e.g. `out('fetchInvoice', 'body.total')`. */
+    value: Expr;
+    /** Reviewer must confirm/fill it before the task can be completed. */
+    required?: boolean;
+}
+export type FormField = ShownField | AskedField | InOutField;
+/**
+ * Where the task is delivered. The four ids are the platform's own — including
+ * the lowercase `'teams'`, which is how every deployed recipient spells
+ * Microsoft Teams (the canvas's channel list, `hitl-types.ts`).
+ */
+export type HitlChannel = 'Slack' | 'teams' | 'Email' | 'ActionCenter';
+/**
+ * How the task is assigned, the platform's own vocabulary (canvas
+ * `HITL_ASSIGNEE_TYPE`): `'user'` a single user, `'group'` all users of a
+ * group, `'staticEmail'`/`'staticGroupName'` literal values instead of
+ * directory picks, `'workload'`/`'roundRobin'` distribution over a group, and
+ * `'custom'` an expression the engine evaluates (`value` holds it).
+ */
+export type HitlAssigneeType = 'user' | 'group' | 'staticEmail' | 'staticGroupName' | 'workload' | 'roundRobin' | 'custom';
+/** A per-channel Integration Service connection (Slack / Teams delivery). */
+export interface HitlConnection {
+    /** The connection's display name. */
+    name?: string | null;
+    /** The connection key the engine resolves, e.g. `'Slack'` for the default. */
+    key: string;
+    /** Folder the connection lives in; `null` for tenant-level defaults. */
+    folderPath?: string | null;
+}
+/**
+ * Who gets the task and over which channels. Omit the whole object for the
+ * definition's default (Email + Action Center, assigned to a group) — which is
+ * what 203 of 233 deployed v1 human tasks carry, and what this SDK has always
+ * emitted.
+ *
+ * ```ts
+ * hitl({
+ *   recipient: {
+ *     channels: ['Email', 'ActionCenter'],
+ *     assignee: { type: 'user', value: 'reviewer@acme.test' },
+ *   },
+ *   …
+ * })
+ * ```
+ */
+export interface HitlRecipient {
+    /** Delivery channels. Defaults to the emitted definition's own default set. */
+    channels?: HitlChannel[];
+    /** Who the task is assigned to. */
+    assignee: {
+        type: HitlAssigneeType;
+        /**
+         * The user email / group name / expression, per `type`. The engine lowers
+         * this to its `{ Value, Type }` recipient contract; without one the task
+         * falls back to the tenant's assignment default.
+         */
+        value?: string;
+        /** Display name the designer shows next to the pick. Cosmetic. */
+        displayName?: string;
+    };
+    /**
+     * Per-channel connections, keyed by channel id (`Slack` / `teams`). Only the
+     * connector-backed channels take one; Email and Action Center do not.
+     */
+    connections?: Partial<Record<'Slack' | 'teams', HitlConnection>>;
+}
+/**
+ * The Document Validation task's subject — `variant: 'document-validation'`
+ * only. The reviewer gets the platform's validation station (or a custom app
+ * with a Validation Control) over a document and its extraction result.
+ */
+export interface DocValidationInputs {
+    /**
+     * The extraction result to validate — bind the `ExtractionResult` output of
+     * an upstream Extract step, e.g. `out('extract', 'ExtractionResult')`.
+     * Required: the station has nothing to validate without it.
+     */
+    extractionResult: Expr | string;
+    /** Storage bucket id holding the document. */
+    storageBucket?: string;
+    /** The document's id within the bucket. */
+    documentId?: string;
+    /**
+     * `'standard'` (default) for the native validation station, `'custom'` for a
+     * custom app with a Validation Control — which then requires `taxonomy`.
+     */
+    render?: 'standard' | 'custom';
+    /** The taxonomy the custom app validates against. Required when `render: 'custom'`. */
+    taxonomy?: Expr | string;
+}
+/**
+ * One completion button. `action: 'End'` marks an outcome that ENDS the process
+ * rather than continuing (the platform's own two-value vocabulary — anything
+ * that is not exactly `'End'` reads as continue).
+ *
+ * @remarks
+ * A bare string is shorthand for `{ name }`.
+ */
+export type Outcome = string | {
+    name: string;
+    action?: 'Continue' | 'End';
+};
+/**
+ * WHICH human-task node type to emit. The platform ships three spellings of the
+ * same node; two of them resolve on this tenant and are what this option picks.
+ *
+ * @remarks
+ * - **omitted** — `uipath.human-in-the-loop`, the original node, which chooses
+ *   the form kind with `inputs.type: 'quick'`. This is the default and it does
+ *   not change: it is where the platform's own versioning continues, and 319 of
+ *   the corpus's human tasks are on it.
+ * - **`'quick-form'`** — `uipath.human-in-the-loop.quick-form`. Same inline form,
+ *   but the node TYPE is the "quick" choice, so no `inputs.type` is written
+ *   (165 of its 175 deployed instances omit it). Everything you author is
+ *   identical; pick it when something downstream keys on the literal type
+ *   string, which flow-v1's own task checkers do.
+ * - **`'action-app'`** — `uipath.human-in-the-loop.coded-action-app`. The form is
+ *   NOT in the flow: it belongs to a deployed Action App, named by `app`. You
+ *   still declare `outcomes` (the flow routes on them); you must NOT declare
+ *   `fields` (the app owns them) — `check` says so.
+ *
+ * - **`'document-validation'`** — `uipath.human-in-the-loop.document-validation`.
+ *   A validation station over a document + extraction result, named by
+ *   `document`. No `fields` (the station is the form); `outcomes` still route.
+ *   The definition is BUNDLED from the workbench manifest — the tenant registry
+ *   does not serve the family (same availability note as do-while).
+ */
+export type HitlVariant = 'quick-form' | 'action-app' | 'document-validation';
+/**
+ * A deployed Action App that supplies a human task's form — the `'action-app'`
+ * variant's subject.
+ *
+ * @remarks
+ * The names are the platform's own, from flow-v1's app picker: an app is closed
+ * by `key` (its GUID) plus the `folderPath` it is deployed in, with `name` the
+ * human-readable title. This SDK is offline and never calls the Apps API, so
+ * what you write here is what you already know about the app.
+ *
+ * ```ts
+ * hitl({
+ *   variant: 'action-app',
+ *   app: {
+ *     name: 'Expense Review',
+ *     key: 'c0ba97df-8a30-4fe0-b4b4-4611a631d77b',
+ *     folderPath: 'Shared',
+ *     inputs: { 'Expense Amount': out('fetchExpense', 'total') },
+ *   },
+ *   outcomes: ['Approve', 'Reject'],
+ * })
+ * ```
+ */
+export interface AppRef {
+    /** The app's display title, e.g. `'Expense Review'`. */
+    name: string;
+    /** The app's key (a GUID) — how the platform resolves which app this is. */
+    key: string;
+    /** Fully-qualified folder the app is deployed in, e.g. `'Shared'`. */
+    folderPath: string;
+    /**
+     * The app's stable system name. `null` until the app's first deployment
+     * assigns one, which is why it is optional and why `null` is a legal value
+     * rather than something to omit.
+     */
+    appSystemName?: string | null;
+    /**
+     * What to send the app, keyed by the app's OWN input parameter names — so the
+     * keys are the app author's, spaces and all (`'Invoice Amount'`), not
+     * identifiers of ours. Values are references, e.g. `out('step', 'field')`.
+     *
+     * Emitted as `inputs.appInputBindings`, the map flow-v1's serializer turns
+     * into the task's `HitlTaskArguments`.
+     */
+    inputs?: Record<string, Expr | string>;
+}
+export interface HitlInputs {
+    /**
+     * Which human-task node type to emit. Omit it for today's default — see
+     * {@link HitlVariant}. Omitting it emits exactly what it always has.
+     */
+    variant?: HitlVariant;
+    /**
+     * The deployed Action App that owns this task's form. Required by — and only
+     * legal with — `variant: 'action-app'`.
+     */
+    app?: AppRef;
+    /** Task title the reviewer sees. Defaults to the step's label. */
+    title?: string;
+    /** Action Center priority. Defaults to `'Low'`. */
+    priority?: 'Low' | 'Medium' | 'High';
+    /**
+     * The form, as an array of field descriptors — `direction: 'input'` for a value
+     * the reviewer reads, `'output'` for one they fill in. An array (not a map)
+     * because the ids are yours and order is the order on the form.
+     *
+     * Required for the inline-form variants (the default and `'quick-form'`).
+     * FORBIDDEN with `variant: 'action-app'`, where the form belongs to the
+     * deployed app rather than to the flow — `check` says so both ways.
+     */
+    fields?: FormField[];
+    /**
+     * The completion buttons, e.g. `['Approve', 'Reject']`. At least one, or the
+     * reviewer has no way to complete the task and the flow waits forever. The
+     * first is the primary (default) one.
+     *
+     * Which one they pressed is `out('<step>', 'Action')` — that is what the
+     * platform's own routing conditions compare against, so branch on it.
+     */
+    outcomes: Outcome[];
+    /** Who gets the task and how. Omit for the definition's default delivery. */
+    recipient?: HitlRecipient;
+    /** Action Center labels, comma-separated (the platform stores one string). */
+    labels?: string;
+    /**
+     * Route each outcome from its OWN port instead of the single `completed`
+     * exit. Selects the node's **1.1** definition, whose exits are
+     * `outcome-<id>` handles (one per outcome; ids are the outcome names
+     * slugified, e.g. `'Approve'` → `outcome-approve`).
+     *
+     * The FIRST (primary) outcome continues the main path; route the others with
+     * `.stepToList('outcome-<id>', …)`. Base variant only — the sub-typed nodes
+     * have no per-outcome definition version.
+     */
+    outcomePorts?: boolean;
+    /**
+     * Expose the task's runtime error as a bindable `out('<step>', 'error')`
+     * object (`{ code, message, detail, category, status }`). Selects the node's
+     * **1.2** definition — which also routes per outcome, so this implies
+     * {@link HitlInputs.outcomePorts | outcomePorts}. Base variant only.
+     */
+    exposeError?: boolean;
+    /**
+     * The document to validate. Required by — and only legal with —
+     * `variant: 'document-validation'`.
+     */
+    document?: DocValidationInputs;
+}
+export interface SendMessageInputs {
+    /**
+     * The conversation to post into — from the conversation trigger
+     * (`out('start', 'conversationId')`) or a context read. Required.
+     */
+    conversationId: string | Expr;
+    /**
+     * The exchange (one user turn plus its answers) the message belongs to —
+     * `out('<waitStep>', 'conversationContext.latestExchangeId')`, or the
+     * trigger's exchange for the first answer. Required by the node's schema.
+     */
+    exchangeId: string | Expr;
+    /** What to say. Markdown — the node's only supported `mimeType`. Required. */
+    content: string | Expr;
+    /**
+     * Whether this message CLOSES the exchange. The platform's legacy default is
+     * to end it; pass `false` to keep the exchange open for another message.
+     */
+    endExchange?: boolean;
+}
+export interface WaitForMessageInputs {
+    /** The conversation to wait on. Required. */
+    conversationId: string | Expr;
+    /**
+     * How many past exchanges the returned context carries. 1–40 in the
+     * designer; the platform default is 20.
+     */
+    numExchanges?: number;
+}
+export interface ConversationContextInputs {
+    /** The conversation to read. Required. */
+    conversationId: string | Expr;
+    /**
+     * How many exchanges to return, 1–40. The platform default is 20.
+     */
+    exchangeLimit?: number;
+}
+/**
+ * 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 {
+    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;
+}
+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. The platform's legacy
+     * default is to end it; pass `false` to keep it open for another turn.
+     */
+    endExchange?: boolean;
+    /** Sampling temperature, 0–1. */
+    temperature?: number;
+    /** Max tokens in one response. */
+    maxTokenPerResponse?: number;
+    /** The model's own context ceiling — informational. */
+    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;
+}
+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;
+}
+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;
+}
+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;
+}
+export interface SummarizeInputs {
+    /**
+     * The document to summarize — a whole **Flow Attachment** object
+     * (`{ ID, FullName, MimeType, Metadata }`), not a path, id or URL.
+     *
+     * In practice that is a `file`-typed flow input:
+     *
+     * ```ts
+     * flow('SummarizeDemo')
+     *   .input({ documentFile: types.file })
+     *   .step('summarizeContract', summarize({ attachment: input('documentFile'), … }))
+     * ```
+     *
+     * `out('start', 'documentFile')` is the same value written the way the CANVAS
+     * writes it (`$vars.start.output.documentFile`, resolved through the input's
+     * `triggerNodeId` binding). Both forms run — measured on the real service —
+     * so prefer whichever the task asks for; `out('start', …)` is what a
+     * designer-made flow looks like.
+     *
+     * The service reads the file's CONTENT, and refuses one it cannot treat as a
+     * document: a PDF summarizes, a plain `.txt` comes back
+     * `[460005] … "No valid files to use for Summarization."`
+     */
+    attachment: Expr;
+    /** What the summary should cover, e.g. `'Write a 5-bullet executive summary…'`. */
+    prompt: string | Expr;
+    /**
+     * Ask the service for per-claim citations. Each is
+     * `{ Ordinal, PageNumber, Source, Reference }` and lands in
+     * `out('<step>', 'content.Citations')`. Defaults to `false`.
+     */
+    returnCitations?: boolean;
+}
+/** One column Batch Transform appends to the CSV. */
+export interface OutputColumn {
+    /** The new column's header, e.g. `'Category'`. */
+    name: string;
+    /** What the model should put in it, e.g. `'One of: Utility, Software, Travel, Other'`. */
+    description: string;
+}
+export interface BatchTransformInputs {
+    /**
+     * The CSV to enrich — a whole **Flow Attachment** object, same shape and same
+     * two ways of referencing it as {@link SummarizeInputs.attachment}.
+     */
+    attachment: Expr;
+    /** How to process each row, e.g. `'Classify each row and write a one-line summary.'`. */
+    prompt: string | Expr;
+    /**
+     * The columns to add, in order. The node's own field name — an array of
+     * `{ name, description }`, one per new column.
+     */
+    outputColumns: OutputColumn[];
+    /** Let the model use web search while transforming. Defaults to `false`. */
+    enableWebSearchGrounding?: boolean;
+}
+/**
+ * Split an extractor's node type into the two GUIDs its tail packs.
+ *
+ * `uipath.ixp.<projectSlug>.<projectVersionId>-<folderKey>` — the version id is
+ * the `ixpDeployment` binding's `resourceKey` and the node's `model.id`; the
+ * folder key is `inputs.folderKey`. Returns `undefined` for a tail that is not
+ * exactly two uuids joined by `-`, which is how the two older spellings (a
+ * sanitized folder path, and the literal string `undefined`) are refused rather
+ * than mis-split.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export declare function parseIxpProjectType(nodeType: string): {
+    slug: string;
+    versionId: string;
+    folderKey: string;
+} | undefined;
+export interface IxpExtractInputs {
+    /**
+     * The extractor's node type, verbatim from
+     * `uip maestro flow registry search -f "type:startsWith=uipath.ixp"` — e.g.
+     * `'uipath.ixp.invoiceixp-cef0d447-ixp.ff973488-5d89-8035-86ac-f980b4be6deb-c4359cde-55f0-4f0e-9322-c6cdce74ab4c'`.
+     *
+     * **Run `uip maestro flow registry pull --force` first.** `registry search`
+     * and `registry get` answer from a local cache (`~/.uipath/nodes/`), so
+     * without a pull you are reading whenever you last synced.
+     *
+     * Two GUIDs are packed in that tail — the project **version** id and the
+     * **folder** key — and both are read back out of it here, which is why
+     * nothing else has to be passed twice.
+     */
+    project: string;
+    /**
+     * The project's own name, as the tenant spells it — the slug, e.g.
+     * `'idp-benchmark---invoices-c735405a-ixp'`. It is
+     * `inputDefaults.modelName` in `registry get`, and the node carries it as
+     * both `modelName` and `projectName` (one value, two fields — the designer
+     * shows it in two disabled boxes).
+     *
+     * It cannot be recovered from {@link IxpExtractInputs.project}: the node type's slug is
+     * lower-cased and de-punctuated (`---` collapses to `-`), which does not
+     * invert.
+     */
+    modelName: string;
+    /**
+     * The deployment's display name, e.g. `'InvoiceIXP'` —
+     * `inputDefaults.model.modelDisplayName`. It becomes the node's
+     * `model.modelDisplayName` and the `ixpDeployment` binding's `name`.
+     */
+    name: string;
+    /**
+     * The folder the project is published in, e.g. `'Shared'` or
+     * `'Shared/uipath-maestro-flow/BillingDispute'` —
+     * `inputDefaults.folderName`. It becomes the binding's `folderPath` default
+     * and the definition's own `description`.
+     */
+    folderName: string;
+    /**
+     * The document to extract from — a whole **Flow Attachment** object, the same
+     * shape and the same two ways of referencing it as
+     * {@link SummarizeInputs.attachment}:
+     *
+     * ```ts
+     * flow('InvoiceIntake')
+     *   .input({ invoiceFile: types.file })
+     *   .step('extract', ixpExtract({ …, fileRef: out('start', 'invoiceFile') }))
+     * ```
+     *
+     * It is the node's only authored input, and the definition marks it
+     * `required` (with `modelName` and `folderKey`, which this factory fills in).
+     */
+    fileRef: Expr;
+    /** Pages to process, e.g. `'1-5'`. Empty (the default) means the whole document. */
+    pageRange?: string;
+    /** Pin a published version tag. Empty (the default) means the latest. */
+    versionTag?: string;
+    /**
+     * The folder's key CHAIN, when the project lives in a nested folder —
+     * `inputDefaults.model.folderPath`, a dot-joined path of ancestor folder keys
+     * (`<root>.<parent>.<folder>`). Defaults to the folder key alone, which is
+     * what the platform writes for a project published straight into `Shared`.
+     */
+    folderPath?: string;
+    /**
+     * A free-text note on the node. Off by default, deliberately: the definition
+     * does not declare it (so setting it draws a "sets an input its type does not
+     * declare" warning unless the emitted definition is widened in the same
+     * write, which this does), and it is empty in 114 of the 117 deployed nodes
+     * that carry it at all.
+     */
+    description?: string;
+}
+/**
+ * The twelve durations the designer's dropdown offers. Purely an ENCODING
+ * detail: a duration in this list ships as `timerPreset: '<duration>'` and any
+ * other ships as `timerPreset: 'custom'` + `timerValue: '<duration>'`. Both
+ * deploy and both wait the same length of time — the author never picks.
+ * `core-definitions.test.ts` pins this list against the definition's own form.
+ */
+export declare const DELAY_PRESETS: readonly ["PT5S", "PT15S", "PT30S", "PT1M", "PT5M", "PT15M", "PT30M", "PT1H", "PT6H", "PT12H", "P1D", "P1W"];
+export type DelayInputs = {
+    /**
+     * How long to wait, as an ISO-8601 duration: `PT30S`, `PT15M`, `PT2H`,
+     * `P1D`, `P1W`. `PT` separates the time part, so `P1M` is a MONTH and
+     * `PT1M` is a minute.
+     * ISO-8601 duration format documentation is here:
+     * {@link https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm}
+     */
+    duration: string;
+    /** Impossible together with `duration` — a delay waits one way or the other. */
+    until?: never;
+} | {
+    /**
+     * Wait until an ABSOLUTE date-time, ISO-8601: `2026-09-01T09:00:00Z` or
+     * `2026-09-01T09:00:00+02:00`. The platform's timeDate timer: the run
+     * parks until the wall clock reaches this moment (already-past dates
+     * fire immediately).
+     */
+    until: string;
+    /** Impossible together with `until` — a delay waits one way or the other. */
+    duration?: never;
+};
+export interface RpaWorkflowInputs {
+    /**
+     * The published process's release key (a GUID). It becomes part of the node's
+     * type, `uipath.core.rpa-workflow.<key>`. Find it with
+     * `uip or processes list --all-folders --process-type Process` (the row's `Key`)
+     * or `uip maestro flow registry search "uipath.core.rpa-workflow"`.
+     */
+    key: string;
+    /** The process's name in Orchestrator — e.g. `'RPA Workflow'`. */
+    name: string;
+    /**
+     * The Orchestrator folder holding the process — e.g.
+     * `'Shared/uipath-maestro-flow/ProjectEuler RPA'`.
+     */
+    folderPath: string;
+    /**
+     * The PROCESS's own input arguments, by its own argument names (e.g.
+     * `{ problemId: 123 }`). Not a fixed schema — every process declares its own,
+     * and only the deployed process knows them.
+     */
+    inputs?: Record<string, unknown>;
+    /**
+     * The process's OUTPUT arguments — the fields it returns, and their types
+     * (e.g. `{ title: 'string' }`). Required if anything reads the step's output.
+     *
+     * Why you have to say: the process's output schema lives on the tenant, and
+     * authoring happens offline. Without it `$vars.<step>.output.<field>` reads
+     * from an object with no declared fields, and nothing could tell a real field
+     * from a typo. Declaring
+     * the fields here is the same thing the platform's own definition does when it
+     * can reach the process, and it is what lets a misspelled read be caught at
+     * `uip maestro flow check` instead of at run time.
+     */
+    returns?: Record<string, ReturnFieldType>;
+}
+export interface ApiWorkflowInputs {
+    /**
+     * The published API workflow's key (a GUID). It becomes part of the node's
+     * type, `uipath.core.api-workflow.<key>`. Find it with
+     * `uip or processes list --all-folders --process-type Api` (an API workflow's
+     * `ProcessKey` reads `<name>.api.<name>`; the GUID you want is the row's `Key`)
+     * or `uip maestro flow registry search`.
+     */
+    key: string;
+    /** The workflow's name in Orchestrator — e.g. `'NameToAgeFixed'`. */
+    name: string;
+    /** The Orchestrator folder holding it — e.g. `'Shared'`. */
+    folderPath: string;
+    /**
+     * The WORKFLOW's own input arguments, by its own argument names (e.g.
+     * `{ name: 'tomasz' }`). Not a fixed schema — every workflow declares its own.
+     */
+    inputs?: Record<string, unknown>;
+    /**
+     * The workflow's OUTPUT arguments — the fields it returns, and their types
+     * (e.g. `{ EstimatedAge: 'integer' }`). Required if anything reads the step's
+     * output, for the same reason as `rpaWorkflow`'s: the schema lives on the
+     * tenant and authoring happens offline, so an undeclared read is rejected.
+     *
+     * `'integer'` is what makes the replay fixture a number rather than a string;
+     * see {@link ReturnFieldType} for why the vocabulary carries it.
+     *
+     * @enforcedBy APIWF_READ_WITHOUT_RETURNS Reading a field off the result requires
+     * declaring it here.
+     */
+    returns?: Record<string, ReturnFieldType>;
+}
+/**
+ * A published Orchestrator **Function** — a small, single-purpose unit of code
+ * deployed as its own resource and invoked as one step
+ * (`Orchestrator.ExecuteFunctionAsync`). Same published-resource shape as
+ * {@link ApiWorkflowInputs}; what differs is the family and the folder.
+ */
+export interface PublishedFunctionInputs {
+    /**
+     * The function's key (a GUID) — it becomes part of the node's type,
+     * `uipath.core.function.<key>`. Find it with
+     * `uip maestro flow registry search "uipath.core.function"` (after
+     * `registry pull --force`) or the Orchestrator process listing.
+     */
+    key: string;
+    /** The function's name in Orchestrator, e.g. `'acme-echo'`. */
+    name: string;
+    /**
+     * The Orchestrator folder holding it. A function is usually deployed into a
+     * folder of its OWN name (e.g. `'Shared/acme-echo'`), and the binding's
+     * `resourceKey` is `<folderPath>.<name>` — copy the folder from the tenant
+     * rather than assuming `'Shared'`.
+     */
+    folderPath: string;
+    /** The function's own input arguments, by its own names. */
+    inputs?: Record<string, unknown>;
+    /**
+     * The function's OUTPUT arguments — the fields it returns, and their types.
+     * Required if anything reads the step's output: the schema lives on the
+     * tenant and authoring is offline, so an undeclared read is rejected.
+     *
+     * @enforcedBy FUNCTION_READ_WITHOUT_RETURNS Reading a field off the result
+     * requires declaring it here.
+     */
+    returns?: Record<string, ReturnFieldType>;
+}
+interface AgenticProcessInputsBase {
+    /**
+     * The published agentic process's key (a GUID). It becomes part of the node's
+     * type, `uipath.core.agentic-process.<key>`. Find it with
+     * `uip or processes list --all-folders --process-type ProcessOrchestration` (an
+     * agentic process's `ProcessKey` reads `<name>.agentic.<name>`; the GUID you want
+     * is the row's `Key`) or `uip maestro flow registry search agentic`.
+     *
+     * `--all-folders` PAGINATES at 50 rows and says so in `Pagination.HasMore` — pass
+     * `--limit`/`--offset`, or scope the call with `--folder-path`, or a process that
+     * exists will look as though it does not.
+     */
+    key: string;
+    /** The process's name in Orchestrator — e.g. `'ProcurementProcess'`. */
+    name: string;
+    /**
+     * The Orchestrator folder holding it — e.g.
+     * `'Shared/uipath-agents/ProcurementProcess'`.
+     */
+    folderPath: string;
+    /**
+     * The PROCESS's own input arguments, by its own argument names (e.g.
+     * `{ productId: 1 }`). Not a fixed schema — every agentic process declares its
+     * own, and only the deployed process knows them.
+     */
+    inputs?: Record<string, unknown>;
+    /**
+     * Which published form this Agentic Process is: the three forms
+     * share one public concept and differ only in wire identity. `'bpmn'` (the
+     * default, and what this factory always emitted) is a Maestro BPMN process
+     * orchestration; `'flow'` is a published Maestro Flow; `'case'` is a Case
+     * Management process.
+     */
+    form?: 'bpmn' | 'flow' | 'case';
+}
+/**
+ * Whether an Agentic Process step waits for the process's result.
+ * The discriminated union makes `returns` impossible to declare in the
+ * fire-and-forget form: an async dispatch publishes no output, so nothing
+ * downstream may read one.
+ */
+export type AgenticProcessCompletion = {
+    /** Wait for the process and publish its outputs (the default). */
+    completion?: 'wait';
+    /**
+     * The process's OUTPUT arguments — the fields it returns, and their types (e.g.
+     * `{ status: 'boolean' }`). Required if anything reads the step's output, for the
+     * same reason as `rpaWorkflow`'s and `apiWorkflow`'s: the schema lives on the
+     * tenant and authoring happens offline, so an undeclared read is rejected.
+     *
+     * `uip maestro flow registry get uipath.core.agentic-process.<process>` shows what
+     * the platform synthesizes, under `outputDefinition.output.schema.properties`.
+     *
+     * Worth knowing before you assert on a value: a process can DECLARE a field and
+     * still leave it empty. `Shared/uipath-agents/ProcurementProcess` declares
+     * `{status: boolean}` and every job returns `{"status": null}` (measured
+     * 2026-07-29, four jobs) — the field arrives, the value does not.
+     *
+     * @enforcedBy AGENTIC_READ_WITHOUT_RETURNS Reading a field off the result requires
+     * declaring it here.
+     */
+    returns?: Record<string, ReturnFieldType>;
+} | {
+    /**
+     * Dispatch the process and continue immediately — the platform's
+     * fire-and-forget switch. The node keeps only its `error` output (dispatch
+     * failures still route), and `check` rejects any read of the step's result.
+     * A local replay treats this as dispatch-only: it never fabricates the
+     * output a real run would not publish.
+     */
+    completion: 'fire-and-forget';
+    /** Impossible by design: an async dispatch publishes no output. */
+    returns?: never;
+};
+/** What `agenticProcess()` takes: the shared fields plus the completion policy. */
+export type AgenticProcessInputs = AgenticProcessInputsBase & AgenticProcessCompletion;
+/**
+ * Which KIND of agent project was published behind a `uipath.core.agent.<key>`
+ * resource. Display-only — see {@link AgentInputs.flavour}.
+ */
+export type AgentFlavour = 'coded' | 'lowcode';
+export type AgentLocation = 'published' | 'in-solution';
+export interface AgentInputs {
+    /**
+     * The agent resource key (a GUID). It becomes the node's TYPE,
+     * `uipath.core.agent.<key>`. For a published agent this is the Orchestrator
+     * release key; for an in-solution sibling it is `resource.key` from
+     * `resources/solution_folder/process/agent/<project>.json`.
+     *
+     * Find it with `uip or processes list --all-folders --process-type Agent` (an agent's
+     * `ProcessKey` reads `<project>.agent.<name>`; the GUID you want is the row's
+     * **`Key`**) or `uip maestro flow registry search uipath.core.agent`.
+     *
+     * Pass `--limit`: `--all-folders` returns 50 rows and reports the truncation
+     * only in `Pagination.HasMore`, so an agent that exists can look absent.
+     */
+    key: string;
+    /** The agent project name. */
+    name: string;
+    /**
+     * Where the referenced agent lives. Published is the backward-compatible
+     * default. Use `in-solution` only after registering a sibling agent project
+     * with `uip solution projects add`.
+     */
+    location?: AgentLocation;
+    /**
+     * The Orchestrator folder holding it — e.g.
+     * `'Shared/uipath-maestro-flow/CountLetters LowCode'`.
+     *
+     * **Not optional, and not cosmetic.** Agent names are unique per FOLDER, not per
+     * tenant: `codereval/DefaultTenant` carries two agents called `CountLetters`,
+     * one in `Shared` and one in `Shared/uipath-maestro-flow/CountLetters CodedAgent`,
+     * with different release keys. The release is resolved by listing THIS
+     * folder, so the folder is what picks the agent you meant. Required for a
+     * published agent; omit it for an in-solution sibling.
+     */
+    folderPath?: string;
+    /**
+     * The sibling agent project's `resource.projectKey`, read from
+     * `resources/solution_folder/process/agent/<project>.json`. Required only
+     * when `location` is `in-solution`.
+     */
+    projectId?: string;
+    /**
+     * The AGENT's own input arguments, by its own argument names (e.g.
+     * `{ inputString: 'arrow' }`). Every agent declares its own — read them from
+     * `uip maestro flow registry get uipath.core.agent.<agent>` under
+     * `inputDefinition.properties`.
+     *
+     * **Required, unlike the other job families' `inputs`.** An agent node with
+     * nothing bound is one the platform REWRITES behind your back: flow-v1's
+     * `applyEmptyInputFloor` seeds `JobArguments: { input: <empty-for-declared-type> }`
+     * — a key named `input`, which is not in the agent's own schema unless the agent
+     * happens to declare one — because the Python agent runner validates the body
+     * against a schema with a required `input` field and rejects a bare `{}` with
+     * *"Field required: input"* (the pod then exits `0x33`). Locally the envelope
+     * passes straight through and the run is green, so nothing but a checker can see
+     * it. Pass `{}` explicitly if you really mean "no arguments" and `check` will
+     * tell you what the platform will do with it.
+     */
+    inputs: Record<string, unknown>;
+    /**
+     * The agent's OUTPUT fields and their types (e.g.
+     * `{ count: 'integer', inputString: 'string' }`). Required if anything reads the
+     * step's output, for the same reason as `rpaWorkflow`'s: the schema lives on the
+     * tenant and authoring happens offline, so an undeclared read is rejected —
+     * rightly, since nothing offline could tell a real field from a typo.
+     *
+     * `uip maestro flow registry get uipath.core.agent.<agent>` shows what the
+     * platform declares, under `outputDefinition.output.schema.properties`.
+     *
+     * **Case matters.** The agent answers with the field names its own definition
+     * declares (`count`, not `Count`). It used to be a live-only trap: a poller that
+     * read the job through `uip agent run status` got a PascalCased envelope, so a
+     * read of `count` was right offline and `undefined` live (flow-builder-sdk #122).
+     * Declare the names the definition declares.
+     *
+     * @enforcedBy AGENT_READ_WITHOUT_RETURNS Reading a field off the result requires
+     * declaring it here.
+     */
+    returns?: Record<string, ReturnFieldType>;
+    /**
+     * Whether the published resource is a CODED agent project (LangGraph /
+     * LlamaIndex / OpenAI Agents) or a low-code one built in Agent Builder.
+     *
+     * **Display-only, and it is the only thing that differs.** `registry get` on a
+     * coded and a low-code agent returns the same node type, the same
+     * `Orchestrator.StartAgentJob` service type, the same `sortOrder: 505` and the
+     * same bindings shape; the single difference is `display.icon` —
+     * `coded-agent` vs `autonomous-agent`. Which one a given resource is cannot be
+     * known offline, so it is stated here rather than guessed. Check with
+     * `uip maestro flow registry get uipath.core.agent.<agent>` → `display.icon`.
+     *
+     * Defaults to `'lowcode'`. Nothing in the runtime keys on it.
+     */
+    flavour?: AgentFlavour;
+}
+/** A JSON-schema-ish type for one field of an inline agent's input/output schema. */
+export type InlineAgentFieldType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+/**
+ * A JSON-schema-ish type for one field of a step's declared `returns`.
+ *
+ * Every `returns` map is transcribed from — or lowered into — a JSON Schema
+ * `properties.<field>.type`, so the vocabulary is JSON Schema's, and it is the
+ * same at every call site. `'integer'` belongs to it because the platform's own
+ * synthesized definitions use it: `registry get` on a deployed API workflow
+ * returns `properties.EstimatedAge.type: 'integer'`, and Orchestrator does the
+ * same for an `Int32`/`Int64` output argument on an RPA process.
+ *
+ * This type exists so that stays true. It was previously spelled inline at
+ * seven sites, `'integer'` was added to three of them, and the four left behind
+ * were not distinguishable by any contract — `rpaWorkflow` in particular is
+ * decompiled by the SAME line of `emitPublishedResource` as `apiWorkflow`, so a
+ * deployed process with an integer output round-tripped to source that would
+ * not compile.
+ */
+export type ReturnFieldType = InlineAgentFieldType;
+/** Where a guardrail applies: the whole agent, its LLM calls, or its tools. */
+export type GuardrailScope = 'Agent' | 'Llm' | 'Tool';
+/** Which artifacts inside the scope the guardrail watches. */
+export interface GuardrailSelector {
+    scopes: GuardrailScope[];
+    /** Restrict to named tools/models; omit for all in scope. */
+    matchNames?: string[];
+}
+/** A field the rule or filter action points at. */
+export interface GuardrailFieldReference {
+    path: string;
+    source: 'input' | 'output';
+    title?: string;
+}
+/** All fields, or a named few. */
+export type GuardrailFieldSelector = {
+    $selectorType: 'all';
+} | {
+    $selectorType: 'specific';
+    fields: GuardrailFieldReference[];
+};
+/** One condition of a custom guardrail. */
+export type GuardrailRule = {
+    $ruleType: 'word';
+    fieldSelector: GuardrailFieldSelector;
+    operator: 'contains' | 'doesNotContain' | 'equals' | 'doesNotEqual' | 'startsWith' | 'doesNotStartWith' | 'endsWith' | 'doesNotEndWith' | 'isEmpty' | 'isNotEmpty' | 'matchesRegex';
+    value?: string;
+} | {
+    $ruleType: 'number';
+    fieldSelector: GuardrailFieldSelector;
+    operator: 'equals' | 'doesNotEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual';
+    value: number;
+} | {
+    $ruleType: 'boolean';
+    fieldSelector: GuardrailFieldSelector;
+    operator: 'equals';
+    value: boolean;
+} | {
+    $ruleType: 'always';
+    applyTo: 'input' | 'output' | 'inputAndOutput';
+};
+/** What happens when a guardrail trips. */
+export type GuardrailAction = {
+    $actionType: 'block';
+    reason: string;
+} | {
+    $actionType: 'filter';
+    fields: GuardrailFieldReference[];
+} | {
+    $actionType: 'log';
+    severityLevel: 'Info' | 'Warning' | 'Error';
+};
+/** A rule-based guardrail you author in place. */
+export interface CustomGuardrail {
+    /** Stable id — yours; unique within the agent. */
+    id: string;
+    $guardrailType: 'custom';
+    name: string;
+    description?: string;
+    selector: GuardrailSelector;
+    action: GuardrailAction;
+    /** Also apply the guardrail when the agent runs under evals. */
+    enabledForEvals: boolean;
+    rules: GuardrailRule[];
+}
+/** A platform-shipped validator, configured by parameters. */
+export interface BuiltInValidatorGuardrail {
+    /** Stable id — yours; unique within the agent. */
+    id: string;
+    $guardrailType: 'builtInValidator';
+    name: string;
+    description?: string;
+    selector: GuardrailSelector;
+    action: GuardrailAction;
+    enabledForEvals: boolean;
+    /** The validator's platform id, e.g. a PII or jailbreak detector. */
+    validatorType: string;
+    validatorParameters: Array<{
+        $parameterType: 'enum-list';
+        id: string;
+        value: string[];
+    } | {
+        $parameterType: 'map-enum';
+        id: string;
+        value: Record<string, number>;
+    } | {
+        $parameterType: 'number';
+        id: string;
+        value: number;
+    } | {
+        $parameterType: 'text';
+        id: string;
+        value: string;
+    } | {
+        $parameterType: 'enum';
+        id: string;
+        value: string;
+    } | {
+        $parameterType: 'text-list';
+        id: string;
+        value: string[];
+    } | {
+        $parameterType: 'boolean';
+        id: string;
+        value: boolean;
+    }>;
+}
+export type AgentGuardrail = CustomGuardrail | BuiltInValidatorGuardrail;
+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 it must return.
+     * 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 ONLY {"category","priority"}.',
+     * userPrompt: 'Classify this email:\n{{input.body}}',
+     * inputs: { body: input('body') },
+     * ```
+     *
+     * Why a placeholder rather than an interpolated expression: an inline agent is two
+     * artifacts, and its prompt exists in THREE dialects. You write one; the compiler
+     * emits the other two.
+     *
+     *   1. yours          `{{input.claim}}`
+     *   2. the NODE's     `=js:$vars.prepare.output.claimRef`   ← what the platform SCANS
+     *   3. the AGENT.JSON `{{input.prepare__output__claimRef}}` ← what the runtime SENDS
+     *
+     * The third exists because the platform does not send an agent the names you
+     * declared: it scans the node's prompts for `$vars.*` references and names each
+     * argument after the 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 `skill/references/inline-agent.md`
+     * §"The three prompt DIALECTS".
+     *
+     * If the agent has to answer in a shape the flow then reads, say so here. The
+     * `returns` keys are what a downstream `out(...)` reads, and the engine's own live
+     * path appends a "return ONLY a JSON object with exactly these keys" directive for
+     * the same reason — a system prompt that contradicts it is a fight the model may
+     * lose.
+     */
+    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 — informational, e.g. `128000`. */
+    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'`. Naming it selects the node's **1.3** definition (the
+     * registry's current, which adds the field); omitting it emits the 1.2
+     * definition byte-identically.
+     */
+    mode?: 'standard' | 'advanced';
+    /**
+     * Safety rails over the agent's inputs, outputs, LLM calls and tools — the
+     * platform's own array shape ({@link AgentGuardrail}), carried on the node
+     * (its 1.2 definition already declares the input) and in the `agent.json`.
+     *
+     * ```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 (its 1.4
+     * definition; naming one selects it).
+     */
+    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 ONLY {"determination","rationale"}.',
+     *   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' },
+     *   { 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[];
+}
+/** The three platform-shipped built-in tools (fixed registry types). */
+export type BuiltinToolName = 'analyzefiles' | 'summarize' | 'batchtransform';
+/**
+ * One tool on an inline agent — a discriminated union over the kinds the
+ * tenant's registry actually serves (`uipath.agent.resource.tool.*`).
+ *
+ * @remarks
+ * One kind is NOT here, and for a reason outside this repo:
+ * `tool.mcp.*`/`uipath.agent.resource.mcp.*` resolves to nothing on this tenant
+ * (no MCP server exists to point at, so there is no definition to derive).
+ */
+export type ToolRef = BuiltinToolRef | ConnectorToolRef | ProcessToolRef | IxpToolRef | McpToolRef | RemoteA2aToolRef | ClientSideToolRef | HttpRequestToolRef;
+/**
+ * An MCP server the agent may call tools on. The node type is minted from the
+ * server's name and key exactly as the platform's own mapper does
+ * (`uipath.agent.resource.tool.mcp.<name-slug>.<key-slug>`), and the node
+ * carries the server identity the runtime resolves (folder + slug).
+ */
+export interface McpToolRef {
+    kind: 'mcp';
+    /** The server's display name on the tenant. */
+    name: string;
+    /** The server's key (a GUID) — the solution reference the runtime resolves. */
+    key: string;
+    description?: string;
+    /** Orchestrator folder the server lives in. */
+    folderPath?: string;
+    /** That folder's key, when you have it. */
+    folderKey?: string;
+    /** Server subtype — the referenceV2 `type` (e.g. `'external'`). */
+    mcpType?: string;
+    serviceName?: string;
+    /** The canonical server slug; the runtime resolves `folderPath`/`slug`. */
+    slug?: string;
+    /**
+     * Tool rows from the server's catalog to expose. Omit for none-yet — the
+     * designer's tool picker backfills on discovery, and the runtime can refresh
+     * the schema before a call (the default discovery mode).
+     */
+    selectedTools?: unknown[];
+}
+/**
+ * A remote A2A (agent-to-agent) endpoint the agent may delegate to. Node type
+ * `uipath.agent.resource.tool.a2a.<name-slug>.<key-slug>`, minted exactly as
+ * the platform's mapper does.
+ */
+export interface RemoteA2aToolRef {
+    kind: 'a2a';
+    /** The remote agent's display name. */
+    name: string;
+    /** The resource key (a GUID). */
+    key: string;
+    /** The remote agent's slug — required; the mapper refuses a blank one. */
+    slug: string;
+    description?: string;
+    /** The cached agent card (capability document), when you have one. */
+    cachedAgentCard?: Record<string, unknown> | null;
+    resourceType?: string | null;
+    folderPath?: string;
+    folderKey?: string;
+    resourceFolderPath?: string;
+}
+/**
+ * A CLIENT-side tool: the agent asks the CALLING application to run it and
+ * hand the answer back (`uipath.agent.resource.tool.clientside`). The flow
+ * declares the contract; the client owns the implementation.
+ */
+export interface ClientSideToolRef {
+    kind: 'clientside';
+    /** The tool's name — what the model calls. */
+    name: string;
+    /** What the tool does — the model reads this to decide when to call it. */
+    description?: string;
+    /** The tool's arguments, by name. */
+    inputs?: Record<string, InlineAgentFieldType>;
+    /** What the client returns, by name. */
+    returns?: Record<string, InlineAgentFieldType>;
+}
+/**
+ * The built-in HTTP-request tool (`uipath.agent.resource.tool.builtin.httprequest`):
+ * the agent performs an HTTP call. Each field is either FIXED here (give a
+ * value) or left to the MODEL to fill at call time (omit it — the definition's
+ * own prompt-mode default, with the platform's field description).
+ */
+export interface HttpRequestToolRef {
+    kind: 'httpRequest';
+    /** Node label. Defaults to the definition's ('HTTP Request'). */
+    name?: string;
+    description?: string;
+    /** Fix the absolute URL; omit to let the model supply it. */
+    url?: string;
+    /** Fix the method (GET/POST/PUT/PATCH/DELETE); omit for model-supplied. */
+    method?: string;
+    /** Fix request headers as name/value pairs; omit for model-supplied. */
+    headers?: Array<{
+        name: string;
+        value: string;
+    }>;
+    /** Fix query parameters as name/value pairs; omit for model-supplied. */
+    params?: Array<{
+        name: string;
+        value: string;
+    }>;
+    /** Fix the body (a string — JSON goes as a string); omit for model-supplied. */
+    body?: string;
+    /** Fix the timeout in seconds; omit for model-supplied. */
+    timeout?: number;
+}
+/**
+ * An episodic memory the agent learns from across runs, wired to the agent's
+ * own `memory` handle. Node type
+ * `uipath.agent.resource.memory.<name-slug>.<id-slug>`, minted exactly as the
+ * platform's mapper does. Naming one selects the agent's **1.4** definition
+ * (which adds the handle) — transcribed from workbench source; the tenant
+ * registry serves 1.3 (same availability note as do-while).
+ */
+export interface AgentMemoryRef {
+    /** The memory's display name on the tenant. */
+    name: string;
+    /** The memory's id (a GUID). */
+    id: string;
+    description?: string;
+    /** Folder key the memory lives in. */
+    folderKey?: string;
+    /** Learn from similar past runs (few-shot). Platform default `true`. */
+    dynamicFewShotLearning?: boolean;
+    /** Similarity threshold 0–1. Platform default `0`. */
+    semanticSimilarity?: number;
+    /** How many past examples to retrieve. Platform default `3`. */
+    kValue?: number;
+    /** Retrieval mode. Platform default `'hybrid'`. */
+    searchMode?: 'hybrid' | 'semantic';
+}
+/**
+ * A platform built-in tool. Self-contained: no bindings, no tenant resource,
+ * no identifiers to look up — the node type is a fixed string.
+ */
+export interface BuiltinToolRef {
+    kind: 'builtin';
+    /** Which built-in: `'analyzefiles'`, `'summarize'` or `'batchtransform'`. */
+    tool: BuiltinToolName;
+    /** What the agent is told the tool does. Defaults to the platform's own text. */
+    description?: string;
+    /**
+     * `summarize`/`batchtransform` only: the standing query or instruction. A
+     * plain string, or a flow expression when it depends on the run (the same
+     * mode-tagged rendering as a context index's `query`).
+     */
+    query?: unknown;
+    /** `summarize` only: restrict to one file type. The platform defaults to `'pdf'`. */
+    fileExtension?: string;
+    /** `summarize` only: citation style. The platform defaults to `'inline'`. */
+    citationMode?: string;
+}
+/**
+ * An Integration Service connector operation as a tool — e.g. "create a Jira
+ * issue". Resolved from the same curated library as `connector(…)`, so the
+ * connector key and operation name are validated at compile and the emitted
+ * definition carries the operation's real object/verb.
+ */
+export interface ConnectorToolRef {
+    kind: 'connector';
+    /** The connector's key, e.g. `'uipath-atlassian-jira'`. */
+    connector: string;
+    /** The operation, e.g. `'create-issue'` — same names `connector()` takes. */
+    operation: string;
+    /** Pin an operation version; defaults like `connector()`'s. */
+    version?: string;
+    /** Disambiguate a generic operation by OBJECT, exactly as `connector()` does. */
+    object?: string;
+    /** Display label; defaults to the library's own (e.g. `'Create Issue'`). */
+    name?: string;
+}
+/**
+ * The tool kinds that wrap a DEPLOYED tenant resource. `kind` picks the
+ * namespace and service:
+ *
+ * @remarks
+ * | kind | node type | starts |
+ * |---|---|---|
+ * | `'process'` | `tool.process.<key>` | an RPA process (`Orchestrator.StartJob`) |
+ * | `'agent'` | `tool.agent.<key>` | a published agent (`StartAgentJob`) |
+ * | `'api'` | `tool.api.<key>` | an API workflow (`ExecuteApiWorkflowAsync`) |
+ * | `'flow'` | `tool.flow.<key>` | a Maestro flow (`StartFlowProcess`) |
+ * | `'maestro'` | `tool.processorchestration.<key>` | an agentic process (`StartAgenticProcess`) |
+ */
+export type ProcessToolKind = 'process' | 'agent' | 'api' | 'flow' | 'maestro' | 'function';
+/**
+ * A deployed tenant resource the agent may invoke. Like `rpaWorkflow()` and
+ * its siblings, the definition cannot be bundled — the node type carries the
+ * resource's own key and the platform synthesizes the contract per tenant —
+ * so the author supplies the three identifiers, plus the contract when the
+ * agent's answer or arguments matter.
+ */
+export interface ProcessToolRef {
+    kind: ProcessToolKind;
+    /**
+     * The resource's key (a GUID) — the tail of the registry node type. Find it
+     * with `uip maestro flow registry search "uipath.agent.resource.tool.<ns>"`
+     * (or `uip solution resources list` for the release key).
+     */
+    key: string;
+    /** The resource's display name on the tenant, e.g. `'Create TestCase'`. */
+    name: string;
+    /** The Orchestrator folder it lives in, e.g. `'Shared'`. */
+    folderPath: string;
+    /** The resource's input arguments, by name and type — becomes its `inputSchema`. */
+    inputs?: Record<string, InlineAgentFieldType>;
+    /** What it returns, by name and type — becomes its `outputSchema`. */
+    returns?: Record<string, InlineAgentFieldType>;
+}
+/**
+ * A published IxP (Intelligent eXtraction Platform) project as a tool — the
+ * agent decides when to extract a document and reads the fields back.
+ *
+ * @remarks
+ * The same project identity as {@link IxpExtractInputs}, minus the file: a tool
+ * is handed its document by the agent at run time, so `attachmentConfig` (the
+ * platform's own field) says where that document comes from rather than
+ * `fileRef` naming one.
+ */
+export interface IxpToolRef {
+    kind: 'ixp';
+    /**
+     * The IxP project's id (a GUID) — the tail of the registry node type
+     * `uipath.agent.resource.tool.ixp.<slug>.<projectId>`. Find it with
+     * `uip maestro flow registry search -f "type:startsWith=uipath.agent.resource.tool.ixp"`
+     * (after `uip maestro flow registry pull --force`, or the answer is your last
+     * sync's).
+     *
+     * Note this is the PROJECT id, where an extraction STEP's node type carries
+     * the project **version** id — two different GUIDs for the same project.
+     */
+    projectId: string;
+    /** The project's display name, e.g. `'Vendor Invoices'`. */
+    name: string;
+    /** What the agent is told the tool does. Defaults to the platform's own text. */
+    description?: string;
+    /** Pin a published version tag; the platform defaults to the latest. */
+    versionTag?: string;
+    /**
+     * Where the document comes from. `'prompt'` (the platform's default) lets the
+     * agent pass one; `'argument'` binds it to a named argument path.
+     */
+    attachment?: {
+        mode?: 'prompt' | 'argument';
+        description?: string;
+        argumentPath?: string;
+    };
+}
+/**
+ * One escalation an inline agent may raise — an Action Center app task a human
+ * completes (the `coded-action-app` variant, the one this tenant's registry
+ * serves).
+ */
+export interface EscalationRef {
+    /** The escalation's name — required by the definition (`minLength: 1`). */
+    name: string;
+    /** When the agent should escalate — what a reviewer sees as the reason. */
+    description?: string;
+    /**
+     * Which escalation node type to emit. Omit for the default —
+     * `….escalation.coded-action-app`, the registry's current spelling, whose
+     * form is a deployed app named by `app`. `'quick-form'` emits
+     * `….escalation.quick-form`, whose form lives INLINE in `fields` (bundled
+     * from the workbench manifest; the tenant registry does not serve it —
+     * same availability note as do-while).
+     */
+    variant?: 'quick-form';
+    /**
+     * The inline form for a `'quick-form'` escalation — the same field rows a
+     * human task's form takes. Forbidden with the app-backed default.
+     */
+    fields?: FormField[];
+    /**
+     * The deployed Action Center app that carries the review. Required by — and
+     * only legal with — the app-backed default variant.
+     */
+    app?: {
+        /** The app's key (a GUID) — from the app's URL or `uip` app listings. */
+        key: string;
+        /** The app's name, e.g. `'ContentReviewApp'`. */
+        name: string;
+        /** The Orchestrator folder the app lives in. */
+        folderPath?: string;
+        /** The fields the agent hands the reviewer — becomes the app's `inputSchema`. */
+        inputs?: Record<string, InlineAgentFieldType>;
+        /** The fields the reviewer answers with — becomes the app's `outputSchema`. */
+        outputs?: Record<string, InlineAgentFieldType>;
+    };
+    /** Who gets the task — email addresses. */
+    recipients?: string[];
+    /**
+     * The outcomes a reviewer can pick (e.g. `['approve', 'reject']`). Each maps
+     * to `'continue'` — the agent resumes with the reviewer's answer either way,
+     * which is the only mapping the deployed corpus carries.
+     */
+    outcomes?: string[];
+    /** The task's title in Action Center. */
+    taskTitle?: string;
+    /** Task priority. The platform defaults to `'medium'`. */
+    priority?: 'low' | 'medium' | 'high' | 'critical';
+    /** Labels on the task, for Action Center filtering. */
+    labels?: string[];
+}
+/**
+ * One Context Grounding index an inline agent is grounded on.
+ *
+ * @remarks
+ * The optional fields mirror the platform's own `inputDefaults` for an index
+ * resource, so omitting them emits exactly what the designer would.
+ */
+export interface ContextIndexRef {
+    /** The index's display name on the tenant, e.g. `'Billing Dispute SOP Index'`. */
+    name: string;
+    /**
+     * The index's uuid. It is the tail of the registry node type
+     * (`uipath.agent.resource.context.index.<slug>.<uuid>`), which is where to read
+     * it from — `uip maestro flow registry search "<name>"`.
+     */
+    id: string;
+    /** The Orchestrator folder the index lives in, e.g. `'Shared/uipath-maestro-flow/BillingDispute'`. */
+    folderPath?: string;
+    /** That folder's key, when you have it. The runtime resolves the folder either way. */
+    folderKey?: string;
+    /**
+     * What to retrieve — required by the index definition's own schema for every
+     * retrieval mode except `deeprag`/`batchtransform`. A plain string, or a flow
+     * expression when the query depends on the run.
+     */
+    query?: string | Expr;
+    /** `'semantic'` (the default), `'structured'`, `'deeprag'` or `'batchtransform'`. */
+    retrievalMode?: 'semantic' | 'structured' | 'deeprag' | 'batchtransform';
+    /** How many chunks to retrieve, 1–40. The platform defaults to 3. */
+    resultCount?: number;
+    /** Minimum similarity, 0–1. The platform defaults to 0. */
+    threshold?: number;
+    /** Restrict to one file type; `'All'` (the platform's default) or e.g. `'pdf'`. */
+    fileExtension?: string;
+}
+/** The three priorities an Orchestrator queue item can carry. */
+export type QueuePriority = 'Low' | 'Normal' | 'High';
+export interface QueueItemInputs {
+    /** The queue's name in Orchestrator — e.g. `'SupplierInvoices'`. */
+    queue: string;
+    /** The Orchestrator folder holding the queue — e.g. `'Shared'`. */
+    folderPath: string;
+    /**
+     * The queue's own Orchestrator key (a GUID). It is the JOIN between this node
+     * and the flow's queue bindings — a node which does not reference its bindings
+     * cannot be dispatched — and it is what
+     * the designer's queue picker writes. The RUNTIME resolves the queue by
+     * `queue` + `folderPath`, so all three are needed and none is redundant.
+     *
+     * Find it with `uip or queues list --all-folders`.
+     */
+    key: string;
+    /**
+     * The work item's own data: a FLAT object of primitive values. It becomes the
+     * item's `SpecificContent`, and Orchestrator rejects a nested object or array
+     * with "Property values must be simple (like numbers or text)".
+     */
+    item: Record<string, unknown>;
+    /** Processing priority. Defaults to `'Normal'`, as the node type does. */
+    priority?: QueuePriority;
+    /**
+     * A reference string for the item. Optional in general — but a queue created
+     * with "enforce unique reference" REQUIRES one and rejects a repeat with
+     * `HTTP 409: Duplicate Reference`, so derive it from the flow's input rather
+     * than hard-coding it.
+     *
+     * Which is why it takes an {@link Expr} as well as a literal: the serializer
+     * renders it through the same path as any other value, so
+     * `reference: input('invoiceRef')` and
+     * ``reference: js`${input('invoiceRef')} + "-review"` `` both emit. Typing it
+     * as a bare `string` contradicted the advice directly above and stopped two
+     * of the SDK's own examples compiling.
+     */
+    reference?: string | Expr;
+    /** Earliest the item may be processed, ISO-8601 (e.g. `'2026-08-01T09:00:00Z'`). */
+    deferDate?: string;
+    /** Latest the item should be processed, ISO-8601. What an SLA is measured against. */
+    dueDate?: string;
+    /**
+     * `false` (the default) enqueues and moves on — `core.action.queue.create`.
+     * `true` PARKS the flow until whatever consumes the queue has processed the
+     * item, and publishes that result — `core.action.queue.create-and-wait`.
+     *
+     * The two are one construct with two data paths, so this is one field rather
+     * than two factories. Waiting is not free: nothing completes the item but a
+     * consumer (an RPA process bound to the queue), so a flow that waits on a queue
+     * nobody drains waits forever.
+     */
+    wait?: boolean;
+    /**
+     * Only for `wait: true`: the fields the PROCESSED item's result carries, and
+     * their types (e.g. `{ approved: 'boolean' }`). Required if anything reads the
+     * step's output.
+     *
+     * Why you have to say: what a consumer writes into a transaction's `Output` is
+     * that automation's business, not the queue's — no definition declares it and
+     * authoring happens offline. Without it `$vars.<step>.output.<field>` reads from
+     * an object with no declared fields, and nothing could tell a real field from
+     * a typo.
+     *
+     * `wait: false` needs none: what it publishes is the queue ITEM's own
+     * Orchestrator record (`Key`, `Status`, `Reference`, `SpecificContent`, …),
+     * which is the same for every queue, so the serializer declares it for you.
+     */
+    returns?: Record<string, ReturnFieldType>;
+}
+/** One filter row on a Data Fabric read — rows AND together unless `or` is set. */
+export interface DataFabricFilter {
+    /** The entity column to filter on. */
+    field: string;
+    /** Comparison operator the designer offers — `=` (the default), `!=`, `>`, `>=`, `<`, `<=`, `contains`, … */
+    operator?: string;
+    /** The comparison value. An `Expr` re-evaluates at activation time. */
+    value: string | Expr;
+    /** Join this row to the PREVIOUS one with OR instead of AND. */
+    or?: boolean;
+}
+export interface DataFabricReadInputs {
+    /** The Data Fabric entity's name, e.g. `'Invoices'`. */
+    entity: string;
+    /** Filter rows selecting the record to read. Omit to read the first record. */
+    filters?: DataFabricFilter[];
+    /** Folder key (GUID) for folder-scoped entities. */
+    folderKey?: string;
+}
+export interface DataFabricUpdateInputs {
+    /** The Data Fabric entity's name, e.g. `'Invoices'`. */
+    entity: string;
+    /**
+     * Which record to update: `{ byId: <record id> }`, or `{ fromRead: '<step>' }`
+     * naming an earlier `dataFabricRead` step whose record this write targets.
+     */
+    record: {
+        byId: string | Expr;
+        fromRead?: never;
+    } | {
+        fromRead: string;
+        byId?: never;
+    };
+    /**
+     * The columns to write, by field name. An empty string is a real write — it
+     * clears the column.
+     */
+    set: Record<string, string | Expr>;
+    /** Folder key (GUID) for folder-scoped entities. */
+    folderKey?: string;
+}
+export interface DocumentClassifyInputs {
+    /** The document to classify — a file reference (`input('file')`, `out('fetch', 'fileRef')`, …). */
+    fileRef: string | Expr;
+    /** Page range to classify, e.g. `'1-3'`. Omit for the whole document. */
+    pageRange?: string;
+    /** Split multi-document files into per-type page ranges. */
+    splitPages?: boolean;
+    /** Model configuration overrides; omit for the platform defaults (gemini_2_5_flash). */
+    modelConfig?: Record<string, unknown>;
+}
+export interface DynamicExtractInputs {
+    /** The document to extract from — a file reference. */
+    fileRef: string | Expr;
+    /**
+     * The IXP model deployment the extraction runs against. Dynamic Extract
+     * authors its SCHEMA inline, but execution still needs a model: Studio Web's
+     * panel destructures `modelName` and `folderKey`, and the platform rejects an
+     * instance without them.
+     */
+    model: {
+        /** The deployment's model name, e.g. `'invoiceixp-cef0d447-ixp'`. */
+        modelName: string;
+        /** Folder key (GUID) the deployment lives in. */
+        folderKey: string;
+        /** The IXP project's id (GUID). */
+        projectId?: string;
+        /** The IXP project's display name. */
+        projectName?: string;
+        /** Folder display name. */
+        folderName?: string;
+        /** Deployment version tag; omit for the live version. */
+        versionTag?: string;
+    };
+    /**
+     * The extraction schema (the node's inline taxonomy): a JSON-schema-shaped
+     * document describing the fields to extract. This is the Dynamic Extract
+     * node's defining input — authored inline rather than referencing a deployed
+     * IXP project (use {@link ixpExtract} for those).
+     */
+    schema?: Record<string, unknown>;
+    /** Page range to extract, e.g. `'1-3'`. Omit for the whole document. */
+    pageRange?: string;
+    /** Model configuration overrides; omit for the platform defaults. */
+    modelConfig?: Record<string, unknown>;
+}
+export type ActionSpec = {
+    kind: 'http';
+    inputs: HttpInputs;
+} | {
+    kind: 'script';
+    inputs: ScriptInputs;
+} | {
+    kind: 'transform';
+    inputs: TransformInputs;
+} | {
+    kind: 'hitl';
+    inputs: HitlInputs;
+} | {
+    kind: 'delay';
+    inputs: DelayInputs;
+}
+/** A placeholder — no inputs, publishes nothing. See {@link mock}. */
+ | {
+    kind: 'mock';
+} | {
+    kind: 'rpaWorkflow';
+    inputs: RpaWorkflowInputs;
+} | {
+    kind: 'apiWorkflow';
+    inputs: ApiWorkflowInputs;
+} | {
+    kind: 'publishedFunction';
+    inputs: PublishedFunctionInputs;
+} | {
+    kind: 'sendMessage';
+    inputs: SendMessageInputs;
+} | {
+    kind: 'waitForMessage';
+    inputs: WaitForMessageInputs;
+} | {
+    kind: 'conversationContext';
+    inputs: ConversationContextInputs;
+} | {
+    kind: 'createOutgoingCall';
+    inputs: CreateOutgoingCallInputs;
+} | {
+    kind: 'endCall';
+    inputs: EndCallInputs;
+} | {
+    kind: 'voiceAgent';
+    inputs: VoiceAgentInputs;
+} | {
+    kind: 'conversationalAgent';
+    inputs: ConversationalAgentInputs;
+} | {
+    kind: 'agenticProcess';
+    inputs: AgenticProcessInputs;
+} | {
+    kind: 'agent';
+    inputs: AgentInputs;
+} | {
+    kind: 'inlineAgent';
+    inputs: InlineAgentInputs;
+} | {
+    kind: 'queueItem';
+    inputs: QueueItemInputs;
+} | {
+    kind: 'summarize';
+    inputs: SummarizeInputs;
+} | {
+    kind: 'batchTransform';
+    inputs: BatchTransformInputs;
+} | {
+    kind: 'ixpExtract';
+    inputs: IxpExtractInputs;
+} | {
+    kind: 'connector';
+    key: string;
+    action: string;
+    version?: string;
+    connection?: string;
+    folder?: string;
+    /** Which OBJECT a generic operation addresses — see {@link ConnectorOpts.object}. */
+    object?: string;
+    inputs: Record<string, unknown>;
+} | {
+    kind: 'documentClassify';
+    inputs: DocumentClassifyInputs;
+} | {
+    kind: 'dynamicExtract';
+    inputs: DynamicExtractInputs;
+} | {
+    kind: 'dataFabricRead';
+    inputs: DataFabricReadInputs;
+} | {
+    kind: 'dataFabricUpdate';
+    inputs: DataFabricUpdateInputs;
+} | {
+    kind: 'waitEvent';
+    subscription: EventSubscription;
+};
+/**
+ * Wrap a built-in action spec literal in its adapter class without changing
+ * its declared type. SDK-internal — factories call it so their results are
+ * `instanceof FlowAction`; authors never need it.
+ *
+ * @internal
+ * @param spec - The spec literal a factory built.
+ * @returns The same spec, as a `FlowAction` instance.
+ */
+export declare function builtinActionSpec<S extends object>(spec: S): S;
+/**
+ * Wrap a built-in trigger spec literal in its adapter class without changing
+ * its declared type. SDK-internal — factories call it so their results are
+ * `instanceof FlowTrigger`; authors never need it.
+ *
+ * @internal
+ * @param spec - The spec literal a factory built.
+ * @returns The same spec, as a `FlowTrigger` instance.
+ */
+export declare function builtinTriggerSpec<S extends object>(spec: S): S;
+/**
+ * Declare an HTTP request action, explicitly choosing standalone or managed.
+ *
+ * @param inputs - The request: `url`, `method`, `body`, the response fields you
+ * read back via `returns`, and the `managed` node choice.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function http(inputs: HttpInputs): ActionSpec;
+/**
+ * Declare an inline script action.
+ *
+ * @param inputs - The JavaScript body (`code`, which must `return`) and what it
+ * returns (`returns`).
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function script(inputs: ScriptInputs): ActionSpec;
+/**
+ * Declare a Transform action — a chain of declarative operations over a
+ * collection. Read the result downstream with `out('<step>')`.
+ *
+ * @remarks
+ * For a node that does ONE thing, name the variant — the emitted `.flow` then
+ * carries `core.action.transform.filter` and reads as `Filter` in the designer
+ * instead of a generic `Transform`:
+ *
+ * ```ts
+ * .step('bigOrders', transform({
+ *   variant: 'filter',
+ *   collection: v('orders'),
+ *   operations: [
+ *     { type: 'filter', filters: [{ field: 'amount', condition: 'greater_equal', value: 100 }] },
+ *   ],
+ * }))
+ * ```
+ *
+ * @example
+ * **Filter a collection, then reshape what survives**
+ * ```ts
+ * .var('catalog', types.array, [
+ *   { title: 'Deep Learning', author: 'Goodfellow', difficulty: 9, pages: 800 },
+ *   { title: 'Information Theory', author: 'MacKay', difficulty: 7, pages: 540 },
+ * ])
+ * .step('curate', transform({
+ *   collection: v('catalog'),
+ *   operations: [
+ *     { type: 'filter', operation: 'and', filters: [
+ *       { field: 'difficulty', condition: 'greater_than', value: 5 },
+ *       { field: 'pages', condition: 'less_than', value: 600 },
+ *     ] },
+ *     { type: 'map', keepOriginalFields: false, mappings: [
+ *       { field: 'title', transformation: 'uppercase' },
+ *       { field: 'author' },
+ *     ] },
+ *   ],
+ * }))
+ * ```
+ *
+ * @param inputs - The `collection` to transform and the chain of `operations` to
+ * run over it.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function transform(inputs: TransformInputs): ActionSpec;
+/**
+ * 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;
+/**
+ * Summarize a document with citations — the platform's **Summarize** node.
+ *
+ * @remarks
+ * **The node type is `uipath.pattern.deep-rag`.** The canvas calls it
+ * *Summarize*, its properties panel is titled *Summarize Configuration*, and
+ * the wire type stays `deep-rag` — it is the same node, under the name the
+ * backend service contract uses (`ECS.DeepRag`). There is no
+ * `uipath.pattern.summarize`. (A same-named inline-agent TOOL,
+ * `uipath.agent.resource.tool.builtin.summarize`, is a different family.)
+ *
+ * The answer's fields are **PascalCase** — `content.Text`,
+ * `content.Citations[].{Ordinal, PageNumber, Source, Reference}`. Lowercase
+ * `content.text` resolves to nothing at run time.
+ *
+ * A local run cannot reach the service: it returns the baked
+ * fixture shape, and only a real platform run (`uip maestro flow debug
+ * --attachment <var>=<file>`) calls the model.
+ *
+ * @example
+ * **Summarize an attached contract, with citations**
+ * ```ts
+ * flow('SummarizeDemo')
+ *   .input({ documentFile: types.file })
+ *   .output({ summary: types.string, citations: types.array })
+ *   .step('summarizeContract', summarize({
+ *     attachment: out('start', 'documentFile'),
+ *     prompt: 'Write a 5-bullet executive summary covering scope, term and SLAs.',
+ *     returnCitations: true,
+ *   }))
+ *   .return({
+ *     summary:   out('summarizeContract', 'content.Text'),
+ *     citations: out('summarizeContract', 'content.Citations'),
+ *   })
+ * ```
+ *
+ * @param inputs - The document (`attachment`), the question to answer (`prompt`),
+ * and whether to return citations.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function summarize(inputs: SummarizeInputs): ActionSpec;
+/**
+ * Add AI-generated columns to a CSV — the platform's **Batch transform** node,
+ * `uipath.pattern.batch-transform` (service contract `ECS.BatchTransform`).
+ *
+ * @remarks
+ * The output is a **file handle for the enriched CSV**, not the rows:
+ * `{ ID, FullName, MimeType }` — the service writes a new
+ * `batch-transform-<uuid>.csv` and hands back its attachment. Note `ID`, two
+ * capitals: that is what the platform returns.
+ *
+ * Same dispatch story as {@link summarize} — dry-run fixture locally, a real
+ * model call only on a platform run.
+ *
+ * @example
+ * **Categorize each CSV row with two generated columns**
+ * ```ts
+ * flow('BatchTransformDemo')
+ *   .input({ csvFile: types.file })
+ *   .output({ result: types.file })
+ *   .step('categorizeRows', batchTransform({
+ *     attachment: out('start', 'csvFile'),
+ *     prompt: 'Classify each row by category and write a one-line summary.',
+ *     outputColumns: [
+ *       { name: 'Category', description: 'One of: Utility, Software, Travel, Other' },
+ *       { name: 'Summary',  description: 'Plain-English one-line summary of the row' },
+ *     ],
+ *   }))
+ *   .return({ result: out('categorizeRows') })
+ * ```
+ *
+ * @param inputs - The CSV (`attachment`), the instruction (`prompt`), and the
+ * `outputColumns` to add to each row.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function batchTransform(inputs: BatchTransformInputs): ActionSpec;
+/**
+ * Extract fields from a document with a published IxP project — the platform's
+ * **Extract** node (`uipath.ixp.*`, service contract `IXP.Extraction`).
+ *
+ * @remarks
+ * **The result's shape is three levels deep and PascalCase.** A field lands at
+ * `out('<step>', 'ExtractionResult.ResultsDocument.Fields')` — an array of
+ * `{ FieldId, FieldName, FieldType, IsMissing, Values[], Confidence }`, looked
+ * up by `FieldName`. `Fields[]` is under `ResultsDocument`, not directly under
+ * `ExtractionResult`, and there is no `result` wrapper: the platform's
+ * serializer strips it before the value reaches the variable.
+ *
+ * **A local run cannot extract anything** — extraction needs a real document on
+ * the IxP service. An offline run returns the baked
+ * fixture shape, and only a platform run reaches the model. So a green local
+ * rung proves the wiring and the definition, never that a document was read.
+ *
+ * **`fileRef` is emitted as a PLAIN `=js:` string, not the expression envelope
+ * the rest of the file uses** — the one place this family diverges from the
+ * format's general spelling, and the contract this node owes the platform. The
+ * product's own `ixp-node` validator tests `typeof fileRef !== 'string'` and
+ * refuses the object form (*"inputs.fileRef must be a `=js:$vars.…`
+ * expression"*), the node's registry manifest declares
+ * `{type:'string', minLength:1}`, and so do all 150 v1-authored instances in the
+ * deployed corpus that carry the field — at file versions 1.6, 1.8 and 1.9 alike,
+ * with zero envelopes among them. The RUNTIME
+ * accepts both, so only `uip maestro flow validate` sees a wrong one; the
+ * emitter's exemption lives in `migrate.ts` (`UNWRAPPED_INPUTS`).
+ * See `skill/references/ixp.md` §3.
+ *
+ * @example
+ * **Extract an invoice total and read it out of the nested result**
+ * ```ts
+ * flow('InvoiceIntake')
+ *   .input({ invoiceFile: types.file })
+ *   .output({ total: types.string })
+ *   .step('extract', ixpExtract({
+ *     project: 'uipath.ixp.invoiceixp-cef0d447-ixp.ff973488-5d89-8035-86ac-f980b4be6deb-c4359cde-55f0-4f0e-9322-c6cdce74ab4c',
+ *     modelName: 'invoiceixp-cef0d447-ixp',
+ *     name: 'InvoiceIXP',
+ *     folderName: 'Shared',
+ *     fileRef: out('start', 'invoiceFile'),
+ *   }))
+ *   .step('readTotal', script({ code: `
+ *     const fields = $vars.extract.output.ExtractionResult.ResultsDocument.Fields || [];
+ *     return { total: fields.find(f => f.FieldName === 'invoiceTotal')?.Values?.[0] };
+ *   ` }))
+ *   .return({ total: out('readTotal', 'total') })
+ * ```
+ *
+ * @param inputs - The published IxP `project` and `modelName`, and the document
+ * to read (`fileRef`).
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function ixpExtract(inputs: IxpExtractInputs): ActionSpec;
+/**
+ * Declare a delay — a step that pauses the flow for a fixed length of time and
+ * then carries on.
+ *
+ * @remarks
+ * A delay produces nothing: there is no `out('settle')` to read. It is a wait,
+ * not a value.
+ *
+ * The node itself splits that one duration across two fields (`timerPreset`
+ * holds it directly, or the literal `"custom"` with the real value in
+ * `timerValue`); the serializer picks the encoding, so you state the wait once.
+ *
+ * @example
+ * **Wait thirty seconds before carrying on**
+ * ```ts
+ * .step('settle', delay({ duration: 'PT30S' }))
+ * ```
+ *
+ * @param inputs - How long to wait (`duration`), as an ISO-8601 duration.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function delay(inputs: DelayInputs): ActionSpec;
+/**
+ * Declare a PLACEHOLDER step — "a real node goes here later".
+ *
+ * @remarks
+ * A mock takes **no inputs and publishes nothing**. It is a marker on the canvas
+ * that keeps the graph wired and the flow deployable while one step is still
+ * missing — not a stub that returns test data. `out('extractInvoice')` is
+ * refused at compile time (`MOCK_HAS_NO_OUTPUT`) because it would read `null` at
+ * run time, always.
+ *
+ * Say what belongs there in the step's own name and in the label the canvas
+ * shows; the corpus's placeholders read like
+ * `"Extract Invoice Fields (mock — IxP model not yet published)"`.
+ *
+ * ### Why there are no arguments (convention #191 — the family contract)
+ *
+ * The platform's `core.logic.mock@1.0.0` declares **no `inputDefinition`** and one
+ * output whose `source` is the literal `"null"`. Measured over the 4,033 distinct
+ * archived `.flow` artifacts: **74 mock instances in 62 flows, and 0 carrying a
+ * fixture anywhere in the node** — 71 of them with `inputs: {}` or no `inputs`
+ * key. The 3 exceptions carry free-text `placeholder` / `_placeholder` keys the
+ * definition never declares, invented by agents on runs that scored 0.9 and 0.4.
+ *
+ * **This is NOT a local runner's `kind: 'mock'` test construct**, which returns a
+ * baked fixture. They are different things that share
+ * a name, and a `mock({ fixture })` surface would emit a node whose local
+ * behaviour and deployed behaviour disagree silently — see
+ * [#125](https://github.com/UiPath/flow-builder-sdk/issues/125). Nothing this SDK
+ * emits opens that channel: an SDK-authored mock publishes `null` locally,
+ * exactly as the platform does.
+ *
+ * @example
+ * **Hold a step's place until the real node exists**
+ * ```ts
+ * .step('extractInvoice', mock())      // ← swap for the IxP node once the project exists
+ * ```
+ *
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function mock(): ActionSpec;
+/**
+ * Invoke a deployed RPA (robotic process automation) workflow — a classic
+ * UI-automation process, published to Orchestrator, run by a robot.
+ *
+ * @remarks
+ * Three fields identify the process and they all come from the tenant, which is
+ * why they are named exactly as the platform names them:
+ *
+ *   key         the published process's release key (a GUID). It becomes part of
+ *               the node's TYPE — `uipath.core.rpa-workflow.<key>` — so the
+ *               platform can tell one process's node from another's.
+ *   name        the process's name in Orchestrator.
+ *   folderPath  the Orchestrator folder it lives in.
+ *
+ * `name` + `folderPath` are what the robot is actually started by (the runtime
+ * re-resolves the release from them), and together they are also the process's
+ * `resourceKey`: `"<folderPath>.<name>"`. The serializer emits the two of them
+ * as the flow's process bindings and points the node at them, because a
+ * bindings entry the node does not reference is not a bound process.
+ *
+ * `inputs` are the PROCESS's own input arguments — whatever it declares, by its
+ * own argument names. They are not a fixed schema.
+ *
+ * The step publishes whatever the process returns, under `output`: read a field
+ * with `out('<step>', '<field>')`. Nothing local can check that an argument name
+ * or a returned field name matches the deployed process — only the robot knows —
+ * so a wrong name shows up as a faulted job on a live run, not at compile time.
+ *
+ * @example
+ * **Start a deployed process and read what it returns**
+ * ```ts
+ * .step('getTitle', rpaWorkflow({
+ *   key: '486edc26-0658-4ac1-92c9-1ef953927151',
+ *   name: 'RPA Workflow',
+ *   folderPath: 'Shared/uipath-maestro-flow/ProjectEuler RPA',
+ *   inputs: { problemId: 123 },
+ * }))
+ * .return({ title: out('getTitle', 'title') })
+ * ```
+ *
+ * @param inputs - The published process to start (`key`, `name`, `folderPath`),
+ * its `inputs`, and the output fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function rpaWorkflow(inputs: RpaWorkflowInputs): ActionSpec;
+/**
+ * Invoke a deployed API workflow — a coded workflow published to Orchestrator,
+ * run as a serverless job rather than by a robot.
+ *
+ * @remarks
+ * The same three identifiers as `rpaWorkflow`, for the same reason: `key` is
+ * the key the node's TYPE carries (`uipath.core.api-workflow.<key>`), while
+ * `name` + `folderPath` are what the runtime resolves the job by — and together
+ * they are the workflow's `resourceKey`, `"<folderPath>.<name>"`. The serializer
+ * emits those two as the flow's process bindings and points the node at them.
+ *
+ * The step publishes the job's output arguments under `output`, so
+ * `out('<step>', '<field>')` reads one of the fields `returns` declares. Whether
+ * an argument name or a returned field actually matches the deployed workflow is
+ * something only the tenant knows — a wrong one is a faulted job on a live run,
+ * not a compile error.
+ *
+ * @example
+ * **Start an API workflow and read a declared output argument**
+ * ```ts
+ * .step('getAge', apiWorkflow({
+ *   key: 'ce857908-ee1d-4392-b552-38bcea0be29c',
+ *   name: 'NameToAgeFixed',
+ *   folderPath: 'Shared',
+ *   inputs: { name: 'tomasz' },
+ *   returns: { EstimatedAge: 'integer' },
+ * }))
+ * .return({ age: out('getAge', 'EstimatedAge') })
+ * ```
+ *
+ * @param inputs - The published API workflow to start (`key`, `name`,
+ * `folderPath`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function apiWorkflow(inputs: ApiWorkflowInputs): ActionSpec;
+/**
+ * Invoke a published Orchestrator **Function** — a deployed unit of code run as
+ * one step (`uipath.core.function.<key>`, dispatched as
+ * `Orchestrator.ExecuteFunctionAsync`).
+ *
+ * ```ts
+ * .step('echo', publishedFunction({
+ *   key: '7059bdb5-fdd7-4e13-9d7b-1748aaeb129d',
+ *   name: 'acme-echo',
+ *   folderPath: 'Shared/acme-echo',
+ *   inputs: { message: 'hello' },
+ *   returns: { echoed: 'string' },
+ * }))
+ * ```
+ *
+ * The node type carries the key, so the function must already exist on the
+ * tenant — read `key`, `name` and `folderPath` from the registry rather than
+ * constructing them. Like the other published families, the resource identity
+ * is CLOSED by a binding pair (`<folderPath>.<name>`), and two steps on the
+ * same function share one pair.
+ *
+ * @param inputs - The function's identity, its arguments, and what it returns.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function publishedFunction(inputs: PublishedFunctionInputs): ActionSpec;
+/**
+ * Post an assistant message into a live conversation
+ * (`uipath.conversational.send-message`).
+ *
+ * ```ts
+ * .step('answer', sendMessage({
+ *   conversationId: out('start', 'conversationId'),
+ *   exchangeId: out('listen', 'conversationContext.latestExchangeId'),
+ *   content: 'Your order ships tomorrow.',
+ * }))
+ * ```
+ *
+ * The message is Markdown (`text/markdown` is the node's only supported type)
+ * and the role is always `assistant` — a flow speaks as the assistant.
+ *
+ * @param inputs - The conversation, the exchange, and what to say.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function sendMessage(inputs: SendMessageInputs): ActionSpec;
+/**
+ * PAUSE until the person sends their next message
+ * (`uipath.conversational.wait-for-message`) — a catch event, like
+ * `waitForEvent`, so the flow suspends rather than polling.
+ *
+ * ```ts
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * ```
+ *
+ * It resumes with the conversation context:
+ * `out('listen', 'conversationContext.messages')` is the transcript and
+ * `…conversationContext.latestExchangeId` is the turn to answer.
+ *
+ * @param inputs - The conversation to wait on, and how much history to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function waitForMessage(inputs: WaitForMessageInputs): ActionSpec;
+/**
+ * READ a conversation's transcript so far without waiting
+ * (`uipath.conversational.get-conversation-context`) — the shape a
+ * conversational agent takes as its turn context.
+ *
+ * ```ts
+ * .step('history', conversationContext({
+ *   conversationId: out('start', 'conversationId'), exchangeLimit: 10,
+ * }))
+ * ```
+ *
+ * @param inputs - The conversation to read, and how many exchanges to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function conversationContext(inputs: ConversationContextInputs): ActionSpec;
+/**
+ * Place an outgoing phone call
+ * (`uipath.conversational.voice.create-outgoing-call`) and get back the
+ * `callContext` every other voice step is keyed by.
+ *
+ * ```ts
+ * .step('dial', createOutgoingCall({ from: '+15550001111', to: input('customerPhone') }))
+ * .step('talk', voiceAgent({
+ *   systemPrompt: 'Confirm the delivery window, then thank them.',
+ *   callContext: out('dial', 'callContext'),
+ * }))
+ * ```
+ *
+ * @param inputs - The provisioned `from` number and the `to` number to dial.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function createOutgoingCall(inputs: CreateOutgoingCallInputs): ActionSpec;
+/**
+ * Hang up (`uipath.conversational.voice.end-call`). Reads
+ * `out('<step>', 'ended')`.
+ *
+ * @param inputs - The `callContext` of the call to end.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function endCall(inputs: EndCallInputs): ActionSpec;
+/**
+ * Put a VOICE agent on a live call (`uipath.agent.voice`) — it speaks and
+ * listens for one turn, then the flow continues.
+ *
+ * ```ts
+ * .trigger(voiceTrigger())
+ * .step('greet', voiceAgent({
+ *   systemPrompt: 'Greet {{input.customerName}} and find out why they called.',
+ *   inputs: { customerName: input('customerName') },
+ *   callContext: out('start', 'callContext'),
+ *   voice: { model: 'gemini-3.1-flash-live-preview', persona: 'Kore' },
+ * }))
+ * ```
+ *
+ * Like `inlineAgent`, compile emits the node PLUS a stable
+ * `<source>/agent.json` sidecar. Unlike it, the turn's content comes from the
+ * call rather than from a user-prompt argument. Flow context can still be
+ * supplied through `inputs` and referenced from the system prompt. There are no
+ * declared `returns`: read the turn back as
+ * `out('<step>', 'uipath__agent_response_messages')`.
+ *
+ * @param inputs - The instructions, the call to join, and how the agent sounds.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function voiceAgent(inputs: VoiceAgentInputs): ActionSpec;
+/**
+ * A CONVERSATIONAL agent (`uipath.agent.conversational`) — it answers one turn
+ * of a live chat, reading the transcript rather than flow arguments.
+ *
+ * ```ts
+ * .trigger(conversationTrigger())
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * .step('reply', conversationalAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt: 'You are a support agent. Be brief.',
+ *   settings: { context: out('listen', 'conversationContext') },
+ * }))
+ * ```
+ *
+ * The reply is `out('<step>', 'uipath__agent_response_messages')` — the
+ * platform's own field name. Like `inlineAgent`, compile emits the node plus a
+ * stable `<source>/agent.json` sidecar.
+ *
+ * `sendMessage` is the alternative when the flow (not a model) decides what to
+ * say; this factory is for when the model does.
+ *
+ * @param inputs - The model, the instructions, and how the turn is bound.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function conversationalAgent(inputs: ConversationalAgentInputs): ActionSpec;
+/**
+ * Invoke a deployed AGENTIC PROCESS — a Maestro process orchestration published to
+ * Orchestrator: a BPMN process that coordinates agents, robots and people, started
+ * as a job the same way an RPA or API workflow is.
+ *
+ * @remarks
+ * The same three identifiers as `rpaWorkflow` and `apiWorkflow`, for the same
+ * reason: `key` is the key the node's TYPE carries
+ * (`uipath.core.agentic-process.<key>`), while `name` + `folderPath` are what
+ * the runtime resolves the job by — and together they are the process's
+ * `resourceKey`, `"<folderPath>.<name>"`. The serializer emits those two as the
+ * flow's process bindings and points the node at them.
+ *
+ * By default the step WAITS for the process and publishes its output arguments
+ * under `output`, so `out('<step>', '<field>')` reads one of the fields
+ * `returns` declares.
+ *
+ * `completion: 'fire-and-forget'` selects the designer's own async switch
+ * instead: the node's service type becomes `Orchestrator.Start…ProcessAsync`
+ * and it publishes no output but `error`. The type is a discriminated union, so
+ * `returns` is impossible in that form and nothing downstream can read one; a
+ * local run dispatches without waiting and yields `{ jobKey, started: true }`.
+ *
+ * `form` picks which published Agentic Process this is — `'bpmn'` (the default,
+ * a Maestro process orchestration), `'flow'` (a published Maestro Flow), or
+ * `'case'` (a Case Management process). They share one public concept and
+ * differ only in wire identity.
+ *
+ * @example
+ * **Start a Maestro process and wait for its result**
+ * ```ts
+ * .step('runIntake', agenticProcess({
+ *   key: '4fc450ab-89be-4462-8fc8-21ac4c1d6fb9',
+ *   name: 'ProcurementProcess',
+ *   folderPath: 'Shared/uipath-agents/ProcurementProcess',
+ *   inputs: { productId: 1 },
+ *   returns: { status: 'boolean' },
+ * }))
+ * .return({ ok: out('runIntake', 'status') })
+ * ```
+ *
+ * @param inputs - The published Maestro process to start (`key`, `name`,
+ * `folderPath`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function agenticProcess(inputs: AgenticProcessInputs): ActionSpec;
+/**
+ * Invoke an AGENT resource — either one published to Orchestrator or a sibling
+ * agent project registered in the same solution. Both start through
+ * `Orchestrator.StartAgentJob`.
+ *
+ * @remarks
+ * **Coded and low-code agents are the same node.** This one factory authors both.
+ * `registry get` on a coded agent and on a low-code one returns the same node type,
+ * the same service type, the same `sortOrder: 505` and the same bindings shape; the
+ * only difference is the icon, which is what `flavour` sets. Which kind a resource
+ * is a property of what somebody published, not of the flow — so if a task asks for
+ * "a coded agent", what it is asking you to get right is the RESOURCE you point at.
+ *
+ * **What this factory cannot do, said plainly:** it does not create an agent. A
+ * published resource must already be deployed. An in-solution resource must first
+ * be scaffolded and registered with `uip solution projects add`; this factory then
+ * authors the local reference from the registered resource key and project id.
+ *
+ * The three identifiers are separate for `rpaWorkflow`'s reason: `agent` is the key
+ * the node's TYPE carries (`uipath.core.agent.<agent>`), while `name` +
+ * `folderPath` are what the runtime resolves the job by and together are the
+ * `resourceKey`, `"<folderPath>.<name>"`. `folderPath` earns its keep twice here —
+ * see {@link AgentInputs.folderPath} for the two-agents-called-CountLetters case.
+ *
+ * The step WAITS for the job and publishes its output arguments under `output`, so
+ * `out('<step>', '<field>')` reads a field `returns` declares — using the names the
+ * agent's own definition declares, case included.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * A green live rung here means **a model responded with the declared output shape**,
+ * not that the answer was right. A real Orchestrator job runs, the flow's input
+ * reaches it, and its answer reaches the flow's output — all four independently
+ * checkable (`ladder.sh job`). Whether the number it returned is the correct number
+ * is the model's business, and no rung asserts it. What CAN be asserted is that the
+ * flow did not fake it: the offline seeds assert the exact UNFIXTURED value, which a
+ * hardcoded answer cannot produce.
+ *
+ * @example
+ * **Start a published agent and read one declared output**
+ * ```ts
+ * .step('countLetters', agent({
+ *   key: '6a47dc5b-5fd4-461f-b97d-6c1817abcaaa',
+ *   name: 'CountLetters LowCode Agent',
+ *   folderPath: 'Shared/uipath-maestro-flow/CountLetters LowCode',
+ *   inputs: { inputString: input('word') },
+ *   returns: { count: 'integer', inputString: 'string' },
+ * }))
+ * .return({ rs: out('countLetters', 'count') })
+ * ```
+ *
+ * @param inputs - The agent to start (`name`, `folderPath`, and `key` or
+ * `projectId`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function agent(inputs: AgentInputs): ActionSpec;
+/**
+ * Declare an INLINE AUTONOMOUS AGENT — an agent defined inside this flow's own
+ * project rather than published to Orchestrator (`uipath.agent.autonomous`,
+ * `Orchestrator.StartInlineAgentJob`).
+ *
+ * @remarks
+ * **Two artifacts, not one.** The node carries the prompts and the variable
+ * descriptors, and it points at a directory — `source` — where the platform expects
+ * the agent's own configuration (flow-v1 emits `entryPoint: <source>/agent.json`).
+ * So `compile` writes `<source>/agent.json` beside the `.flow`, built from the same
+ * fields. Nothing to assemble by hand; `source` defaults to a uuid derived from the
+ * flow id and step name so a recompile is not a diff.
+ *
+ * **How this differs from `agent()`.** That one references something already
+ * published and started as an Orchestrator job; this one IS the definition, and the
+ * platform runs it inside the flow's own debug/publish context. The practical
+ * consequences: there is no folder, no release key and no binding pair here — and
+ * no `uip` verb that starts one headlessly either.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * Weaker than `agent()`'s, and in a specific way. `Orchestrator.StartInlineAgentJob`
+ * is Studio-Web-debug-only, so there is no Orchestrator job to point at and no
+ * headless verb that starts one. No local runner currently calls a model for this
+ * node either — an offline run asserts the WIRING and the declared `returns` shape,
+ * never that a model answered. Two differences would remain for any runner that did
+ * call one: knowledge grounding (a context handle) is a cloud-side index an offline
+ * path does not have, so the call would be ungrounded; and the node's `model` would
+ * have to be substituted for one reachable headlessly. Answer quality stays on the
+ * offline `expect` seeds; real behaviour needs a Studio Web debug run.
+ *
+ * @example
+ * **Classify an email with an agent defined inline**
+ * ```ts
+ * .step('triage', inlineAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt:
+ *     'You are a support triage assistant. Classify the email into exactly one ' +
+ *     'category (billing | technical | account) and one priority (low | normal | ' +
+ *     'high). Return ONLY a JSON object with keys "category" and "priority".',
+ *   userPrompt: 'Classify this email:\n{{input.body}}',
+ *   inputs: { body: input('body') },
+ *   returns: { category: 'string', priority: 'string' },
+ * }))
+ * .return({ category: out('triage', 'category') })
+ * ```
+ *
+ * @param inputs - The agent defined in this project: its `model`,
+ * `systemPrompt`, `userPrompt`, and the `returns` fields it must produce.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function inlineAgent(inputs: InlineAgentInputs): ActionSpec;
+/**
+ * Classify a document into a document type (`uipath.document.classify`). The
+ * result publishes `ClassificationResult` — an array of typed classifications
+ * with page ranges and confidences.
+ *
+ * @param inputs - The file reference and optional page range / split / model settings.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function documentClassify(inputs: DocumentClassifyInputs): ActionSpec;
+/**
+ * Extract fields from a document with an INLINE schema — Dynamic Extract
+ * (`uipath.ixp.extract-document-builder`), the newer of the two extraction
+ * shapes. No deployed IXP project is referenced: the extraction schema rides
+ * the node. The result publishes `ExtractionResult` (and `Taxonomy`).
+ *
+ * @param inputs - The file reference, the inline extraction schema, and
+ * optional page range / model settings.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function dynamicExtract(inputs: DynamicExtractInputs): ActionSpec;
+/**
+ * Read ONE entity record from Data Fabric (`core.datafabric.read`). The record
+ * publishes to the step's `output`; downstream references re-fetch fresh data
+ * at activation time (the engine re-runs the query rather than caching).
+ *
+ * @remarks
+ * **Prefer the connector for Data Fabric work during the transition.**
+ * `core.datafabric.*` has exactly two verbs — this one and
+ * {@link dataFabricUpdate} — and neither declares an output schema. Create,
+ * delete, get-by-id, a multi-record query with a row limit, file record fields
+ * and entity events are NOT in this family: they are operations on the SAME
+ * product reached through its Integration Service connector,
+ * `uipath-uipath-dataservice` (the tenant displays it as **UiPath Data
+ * Fabric**), which covers every verb including the two here.
+ *
+ * Taking this node for the one verb that has a native form leaves the rest of
+ * the same entity on the connector — two connection bindings and two payload
+ * shapes in one flow. So route entity work through the connector unless the
+ * scenario names these nodes; native forms for the remaining verbs are the
+ * direction of travel, and this guidance changes when they land. `check` does
+ * not reject a native node — this is a routing default, not a rule:
+ *
+ * ```ts
+ * .step('create', connector('uipath-uipath-dataservice', 'create-entity-record',
+ *   { entityName: 'Contracts', contractTitle: 'Q3 renewal' }, { connection: 'df' }))
+ * ```
+ *
+ * That operation's body fields come from the entity, so the library cannot
+ * carry them: run `npx flow-sdk registry prepare uipath-uipath-dataservice
+ * create-entity-record -f entityName=<Entity>` first (`uip maestro registry
+ * prepare …` is the same command when you are driving through the UiPath CLI). The routing table is in
+ * the `data-fabric.md` reference and the parent-field loop in
+ * `connector-params.md` — cited by name rather than linked, because this
+ * comment renders both into the flat corpus, where those files sit alongside
+ * it, and onto the site, where each symbol is its own page and a relative
+ * `./data-fabric` resolves to nothing.
+ *
+ * @param inputs - The entity, optional filter rows, and folder scope.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function dataFabricRead(inputs: DataFabricReadInputs): ActionSpec;
+/**
+ * Update an entity record in Data Fabric (`core.datafabric.update`). Target the
+ * record by id or through an earlier {@link dataFabricRead} step; downstream
+ * reads of this step observe the record AFTER the write.
+ *
+ * @remarks
+ * The second and last verb of the native family — see {@link dataFabricRead}
+ * for what the family does NOT cover, which connector operation covers it
+ * instead, and why entity work routes through the connector during the
+ * transition. For an update whose flow also creates, gets or deletes on the
+ * same entity, use `connector(…, 'update-entity-record', …)` so the flow keeps
+ * one surface.
+ *
+ * @param inputs - The entity, the record selector, and the columns to write.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function dataFabricUpdate(inputs: DataFabricUpdateInputs): ActionSpec;
+/**
+ * Declare an Orchestrator QUEUE ITEM step.
+ *
+ * @remarks
+ * A queue is Orchestrator's work list: something puts items on it, and an
+ * automation bound to the queue takes them off one at a time. This step is the
+ * putting-on half.
+ *
+ * `queue` + `folderPath` are what the runtime resolves the queue by, and `key` is
+ * the queue's own Orchestrator key: it joins this node to the flow's queue
+ * bindings, which the serializer emits and points the node at. All three, for the
+ * same reason `rpaWorkflow` takes three — the key is the AUTHORING identity, the
+ * two bindings are the RUNTIME one.
+ *
+ * `item` is the work item's data. It becomes the item's `SpecificContent`, and it
+ * must be FLAT: Orchestrator rejects a nested object or array outright.
+ *
+ * **`wait`** picks between the family's two node types, which are one construct
+ * with two data paths. Default `false` enqueues and moves on, publishing the queue
+ * item's own Orchestrator record — read a field with `out('<step>', 'Key')`, and
+ * nothing extra has to be declared because that record's shape is the same for
+ * every queue. `wait: true` PARKS the flow until the item has been processed and
+ * publishes the consumer's result instead, which is per-automation — so a read of
+ * it needs `returns`, exactly as an rpa process's output does.
+ *
+ * What no rung can tell you: whether anything actually drains this queue. A
+ * `wait: true` step on a queue with no consumer waits until it times out.
+ *
+ * @example
+ * **Enqueue a work item and read its Orchestrator key**
+ * ```ts
+ * .step('enqueue', queueItem({
+ *   queue: 'SupplierInvoices',
+ *   folderPath: 'Shared',
+ *   key: 'fa1a7328-cd17-4525-b5ab-29d86e399312',
+ *   item: { InvoiceId: input('invoiceRef'), Amount: input('amount') },
+ *   reference: 'INV-2031',
+ * }))
+ * .return({ itemKey: out('enqueue', 'Key') })
+ * ```
+ *
+ * @param inputs - The `queue` and `folderPath`, the `item` to add, and whether
+ * to `wait` for it to be processed.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function queueItem(inputs: QueueItemInputs): ActionSpec;
+/**
+ * Declare an Integration Service connector action — the typed form, where a
+ * generated descriptor supplies the nodeType and statically-checked input types:
+ * `connector(CreateIssue, { fields: { summary: '…' } }, { connection })`.
+ *
+ * @remarks
+ * `I` is deliberately UNCONSTRAINED. It was `I extends Record<string, unknown>`,
+ * and that quietly disabled the entire typed surface: TypeScript gives implicit
+ * index signatures to type aliases but NOT to interfaces, and the generator emits
+ * `export interface CreateIssueInputs`. So the constraint could never be
+ * satisfied, `I` fell back to its default, and every `connector(Descriptor, …)`
+ * call failed to typecheck with "Index signature for type 'string' is missing".
+ * Nothing caught it because `compile` runs under `--experimental-strip-types`,
+ * which erases types without checking them — the descriptors were typed for a
+ * check that was never performed. The constraint bought nothing (the
+ * implementation signature casts regardless) and cost the feature.
+ *
+ * @param descriptor - The generated operation, from a prepared connector module.
+ * @param inputs - The activity's inputs, typed by the descriptor.
+ * @param opts - Symbolic `connection` / `folder`, an action `version`, and the
+ * `object` a generic operation addresses.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function connector<I, O>(descriptor: ConnectorDescriptor<I, O>, inputs: I, opts?: ConnectorOpts): ActionSpec;
+/**
+ * Stringly form, for a connector with no prepared module —
+ * `connector('uipath-salesforce-slack', 'send-message-to-channel', { … })`.
+ *
+ * @remarks
+ * `key`/`action` identify the library entry; `inputs` are the connector's
+ * activity inputs; `connection`/`folder` are symbolic names resolved via
+ * `bindings.json`.
+ *
+ * @param key - The connector library key, e.g. `'uipath-atlassian-jira'`.
+ * @param action - The operation id, e.g. `'create-issue'`.
+ * @param inputs - The activity's inputs, checked against the library at build time.
+ * @param opts - Symbolic `connection` / `folder`, an action `version`, and the
+ * `object` a generic operation addresses.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function connector(key: string, action: string, inputs?: Record<string, unknown>, opts?: ConnectorOpts): ActionSpec;
+/**
+ * One filter condition on the event payload. An ARRAY of these, never an object
+ * map — filters are positional, carry author-supplied field names, and the
+ * designer stores them as a list (the descriptor rule, from PR 1's switch cases).
+ *
+ * Exactly ONE operator key per condition. The vocabulary is the designer's own,
+ * and each form was measured against the platform's filter compiler, so the
+ * emitted `filterExpression` is byte-for-byte what the canvas would have written:
+ *
+ * - text tests, string values: `contains` (case-sensitive substring, the same test
+ *   Integration Service applies server-side), `startsWith`, `endsWith`;
+ * - equality, any literal: `equals`, `notEquals`;
+ * - ordering, a NUMBER or an ISO-8601 DATE string: `lessThan`, `lessThanOrEqual`,
+ *   `greaterThan`, `greaterThanOrEqual`. A date compares as the designer does
+ *   (`to_number(dueDate)<to_number('2026-08-04')`); a plain string under an
+ *   ordering operator would match nothing at runtime, so `check` refuses it.
+ *
+ * @remarks
+ * `{ field: 'subject', contains: 'Invoice' }`, `{ field: 'priority', greaterThan: 3 }`,
+ * `{ field: 'dueDate', lessThan: '2026-08-04' }`.
+ */
+export type EventFilter = {
+    field: string;
+} & ({
+    contains: string;
+} | {
+    startsWith: string;
+} | {
+    endsWith: string;
+} | {
+    equals: string | number | boolean;
+} | {
+    notEquals: string | number | boolean;
+} | {
+    lessThan: string | number;
+} | {
+    lessThanOrEqual: string | number;
+} | {
+    greaterThan: string | number;
+} | {
+    greaterThanOrEqual: string | number;
+});
+/**
+ * The typed `onEvent`/`waitForEvent` options — everything an
+ * {@link EventSubscription} carries except `connector`/`event`, which the
+ * {@link TriggerDescriptor} supplies. `where` is generic so a connection-scoped
+ * descriptor (C4) can type its parameter names; offline it is a loose string map.
+ */
+export interface TriggerOptions<W = Record<string, string>> {
+    /**
+     * The subscription's scope — the connector's event parameters, which is what IS
+     * registers. Loose offline; for Outlook `email-received` that is
+     * `{ parentFolderId: '<mail folder id>' }`.
+     *
+     * OPTIONAL, because not every operation has event parameters: HTTP Webhook takes
+     * none (the connection IS the scope), so `onEvent(HttpWebhook)` with no options
+     * at all is correct there. `check` reads the library and says which case you are
+     * in.
+     *
+     * A value may be a {@link LookupToken} — `lookup(EmailReceived,
+     * 'parentFolderId').by('displayName', 'Inbox')` — resolved by `registry
+     * prepare --resolve` and substituted at compile, exactly like a connector
+     * input.
+     */
+    where?: {
+        [K in keyof W]?: W[K] | LookupToken;
+    };
+    /**
+     * The OBJECT a GENERIC event watches — the one thing its node type does not
+     * say. `record-created` / `record-updated` on Data Fabric, Salesforce,
+     * ServiceNow, Jira and some sixty other connectors fire for ONE object of the
+     * connection (an entity, a table, a custom object), and the library carries no
+     * default for it: `uip is triggers objects <key> <EVENT> --connection-id <id>`
+     * lists the choices. REQUIRED for such an event, refused for a curated one whose
+     * object is built in (Outlook `email-received` is always `Message`). It is not
+     * an event parameter, so it does not go in `where`.
+     */
+    object?: string;
+    /** Optional filters on the payload. Omit to take every event in scope. */
+    filters?: EventFilter[];
+    /** bindings.json id for the connection (defaults to the flow's single binding). */
+    connection?: string;
+    /** bindings.json id for the folder key. */
+    folder?: string;
+    /** Override the descriptor's version. */
+    version?: string;
+}
+/** What a connector event subscribes to. */
+export interface EventSubscription {
+    /** Connector key, e.g. `'uipath-microsoft-outlook365'`. */
+    connector: string;
+    /** The curated event, e.g. `'email-received'`. */
+    event: string;
+    /**
+     * The connector's event parameters — what SCOPES the subscription. For Outlook
+     * email-received that is `{ parentFolderId: '<mail folder id>' }`; the field
+     * names come from the connector, and the ids are only resolvable against the
+     * bound connection (`uip is triggers describe <key> <EVENT> <object>
+     * --connection-id <id>`).
+     *
+     * **Optional, because not every operation has any.** The HTTP Webhook connector
+     * takes none at all — each connection owns one webhook URL and every request to
+     * it is an event for that connection — so `where: {}` (or omitting it) is the
+     * only correct authoring there, and 20 of 20 deployed `http-webhook` nodes carry
+     * an empty `detail.eventParameters`. Omitting it on an operation that DOES have
+     * parameters is legal too (the subscription listens to everything the connection
+     * can see) and `check` says so as a warning.
+     *
+     * A value may be a {@link LookupToken}, resolved by `registry prepare
+     * --resolve` and substituted at compile.
+     */
+    where?: Record<string, string | LookupToken>;
+    /**
+     * The OBJECT a GENERIC event watches (a Data Fabric entity, a Salesforce or
+     * ServiceNow object, a Jira record type). Required for such an event, refused
+     * for a curated one; see {@link TriggerOptions.object}.
+     */
+    object?: string;
+    /** Optional filters on the payload. Omit to take every event in scope. */
+    filters?: EventFilter[];
+    /** bindings.json id for the connection (defaults to the flow's single binding). */
+    connection?: string;
+    /** bindings.json id for the folder key. */
+    folder?: string;
+    version?: string;
+}
+/**
+ * Fold a typed `(descriptor, opts)` call into the same {@link EventSubscription}
+ * the stringly form produces, or pass a stringly subscription through unchanged.
+ * Shared by `onEvent` (flow-sdk) and `waitForEvent` so both surfaces stay in
+ * lock-step — the descriptor only supplies `connector`/`event`/`version`.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export declare function subscriptionFrom<W>(a: EventSubscription | TriggerDescriptor<W, unknown>, opts?: TriggerOptions<W>): EventSubscription;
+/**
+ * Wait mid-flow until a connector event fires, then continue with its payload —
+ * the typed form, where a generated trigger descriptor identifies the event:
+ * `waitForEvent(EmailReceived, { where: { … } })`.
+ *
+ * @remarks
+ * Read the matched event with `out('waitForReply', 'subject')`. To START a flow on
+ * the event instead, pass `onEvent(...)` to `.trigger(...)` — same subscription,
+ * different node type.
+ *
+ * The stringly form names the connector and event directly:
+ *
+ * ```ts
+ * .step('waitForReply', waitForEvent({
+ *   connector: 'uipath-microsoft-outlook365',
+ *   event: 'email-received',
+ *   where: { parentFolderId: inboxId },
+ *   filters: [{ field: 'subject', contains: 'TestWaitFor' }],
+ * }))
+ * ```
+ *
+ * A generated {@link TriggerDescriptor} can supply the connector/event instead:
+ *
+ * ```ts
+ * import { EmailReceived } from './sdk/connectors/uipath-microsoft-outlook365.triggers.ts';
+ * waitForEvent(EmailReceived, { where: { parentFolderId: inboxId },
+ *   filters: [{ field: 'subject', contains: 'TestWaitFor' }] })
+ * ```
+ *
+ * @param descriptor - The generated trigger, from a prepared connector module.
+ * @param opts - The event's `where` scope, `filters`, and symbolic
+ * `connection` / `folder`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function waitForEvent<W>(descriptor: TriggerDescriptor<W, unknown>, opts?: TriggerOptions<W>): ActionSpec;
+/**
+ * Stringly form, for an event with no prepared module.
+ *
+ * @param subscription - The event to wait for: `connector`, `event`, its `where`
+ * scope, and optional `filters`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function waitForEvent(subscription: EventSubscription): ActionSpec;
+export {};