@uipath/maestro-builder-sdk 6.41.2 → 6.43.0

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

@@ -1,11 +1,11 @@
 /**
  * The process family's authoring types — an RPA process (`uipath.core.rpa-workflow.<key>`),
  * an API workflow (`uipath.core.api-workflow.<key>`), a published function
- * (`uipath.core.function.<key>`) and an agentic process (`uipath.core.agentic-process.<key>`,
- * `uipath.core.flow.<key>`, `uipath.core.case-management.<key>`) — and their kinds'
- * entries in `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
- * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md. `ProcessLocation` stays in core: the
- * agent shares it.
+ * (`uipath.core.function.<key>`), an agentic process (`uipath.core.agentic-process.<key>`,
+ * `uipath.core.flow.<key>`, `uipath.core.case-management.<key>`) and a published agent
+ * (`uipath.core.agent.<key>`) — and their kinds' entries in `FlowActionSpecs`. Moved
+ * from core/actions.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
+ * `ProcessLocation` stays in core: `core/process-resource.ts` reads it.
  */
 import type { ProcessLocation, ReturnFieldType } from '../../../core/actions.js';
 export interface RpaWorkflowInputs {
@@ -232,6 +232,109 @@ export type AgenticProcessCompletion = {
 };
 /** 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';
+/** Where a published agent lives: deployed to a folder (`'published'`) or a sibling project of the same solution (`'in-solution'`). */
+export type AgentLocation = ProcessLocation;
+/** What `agent()` takes: the agent resource to start, its arguments, and the output fields a read may name. */
+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` 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;
+}
 declare module '../../../core/actions.js' {
     interface FlowActionSpecs {
         /** The spec {@link rpaWorkflow} builds. */
@@ -250,6 +353,10 @@ declare module '../../../core/actions.js' {
         agenticProcess: {
             inputs: AgenticProcessInputs;
         };
+        /** The spec {@link agent} builds. */
+        agent: {
+            inputs: AgentInputs;
+        };
     }
 }
 export {};

package/dist/registry/describe-cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Print one connector operation's page: its inputs, outputs, lookups and the code to
+ * write.
+ *
+ * The page comes from where `check` and `compile` read: the flow's prepared
+ * `connectors-local` overlay first, then the library. So after `registry prepare`
+ * it shows the connection's real fields. It is rendered from the entry on each call,
+ * so it needs no `library-md` tree and no file the agent must keep a path to.
+ */
+export declare function run(argv: string[]): Promise<number>;

package/dist/registry/describe-cli.js

@@ -0,0 +1,41 @@
+import { printResult, reportResult } from '../cli-result.js';
+import { flagValue } from '../cli-run.js';
+import { openCliLibrary } from '../core/cli-library.js';
+import { PULL_COMMAND } from '../core/cli-spelling.js';
+import { renderMarkdownPage } from './generators/markdown/index.js';
+import { symbolIndex } from './naming.js';
+/**
+ * Print one connector operation's page: its inputs, outputs, lookups and the code to
+ * write.
+ *
+ * The page comes from where `check` and `compile` read: the flow's prepared
+ * `connectors-local` overlay first, then the library. So after `registry prepare`
+ * it shows the connection's real fields. It is rendered from the entry on each call,
+ * so it needs no `library-md` tree and no file the agent must keep a path to.
+ */
+export async function run(argv) {
+    const nodeType = argv[0];
+    const library = openCliLibrary(argv);
+    if (!library) {
+        console.error(`No connector library is cached. Run \`${PULL_COMMAND}\`, or pass --library <dir>.`);
+        return 2;
+    }
+    let source;
+    try {
+        source = library.pageSource(nodeType, flagValue(argv, '--connector-version'), flagValue(argv, '--object'));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    // The symbol names `prepare`'s module exports: it counts GenericExpanded entries only when the overlay has one.
+    const expanded = source.prepared && source.rows.some((e) => e?.activityType === 'GenericExpanded');
+    const body = renderMarkdownPage(source.entry, source.v1def, { symbols: symbolIndex(source.rows, expanded), invariant: source.invariant });
+    // No path: on a browser host it names a store the agent cannot open.
+    const origin = source.prepared ? 'the prepared copy from `registry prepare`' : 'the connector library';
+    const page = `> Source: ${origin}\n\n${body.replace(/\n$/, '')}`;
+    // The page alone, so `uip … --output plain` prints just the Markdown.
+    reportResult({ page });
+    printResult(page);
+    return 0;
+}

package/dist/registry/library-reader.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Reading an extracted `library-json/` tree.
+ *
+ * Every generator walks the same index and opens the same two files per
+ * operation. This is that walk, once, with the path rules the Python spelled in
+ * three places: the entry is `index.json`'s `path`, the sidecar is the same path
+ * with `.json` swapped for `.v1def.json`, and a sidecar that is a one-element
+ * list is unwrapped.
+ */
+import { type ReadText } from "../core/read-text.js";
 import type { IndexRow, LibraryEntry, LibraryIndex, V1Definition } from "./model/library.js";
 export interface LoadedLibrary {
     /** The `library-json` directory. */
@@ -14,7 +24,7 @@ export interface LoadedLibrary {
 }
 /** `<path minus .json>.v1def.json`, the sidecar beside an entry. */
 export declare function sidecarPath(entryRelativePath: string): string;
-export declare function readJsonFile(path: string): unknown;
 /** A sidecar may be `[definition]` in some snapshots; the definition is what callers want. */
 export declare function unwrapV1Def(raw: unknown): V1Definition | undefined;
-export declare function loadLibrary(dir: string): LoadedLibrary;
+/** `read` defaults to the disk; a host without one passes its own (`core/read-text.ts`). */
+export declare function loadLibrary(dir: string, read?: ReadText): LoadedLibrary;

package/dist/registry/library-reader.js

@@ -7,16 +7,12 @@
  * with `.json` swapped for `.v1def.json`, and a sidecar that is a one-element
  * list is unwrapped.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { libraryPath, readTextFromDisk } from "../core/read-text.js";
 import { loadInvariantCollections } from "./lookup-specs.js";
 /** `<path minus .json>.v1def.json`, the sidecar beside an entry. */
 export function sidecarPath(entryRelativePath) {
     return `${entryRelativePath.slice(0, -".json".length)}.v1def.json`;
 }
-export function readJsonFile(path) {
-    return JSON.parse(readFileSync(path, "utf8"));
-}
 /** A sidecar may be `[definition]` in some snapshots; the definition is what callers want. */
 export function unwrapV1Def(raw) {
     if (Array.isArray(raw))
@@ -25,26 +21,31 @@ export function unwrapV1Def(raw) {
         return raw;
     return undefined;
 }
-export function loadLibrary(dir) {
-    const indexPath = join(dir, "index.json");
-    if (!existsSync(indexPath)) {
+/** `read` defaults to the disk; a host without one passes its own (`core/read-text.ts`). */
+export function loadLibrary(dir, read = readTextFromDisk) {
+    const indexPath = libraryPath(dir, "index.json");
+    const indexText = read(indexPath);
+    if (indexText === undefined) {
         throw new Error(`library missing index.json: ${indexPath}`);
     }
-    const index = readJsonFile(indexPath);
-    const invariant = loadInvariantCollections(dir);
+    const index = JSON.parse(indexText);
+    const invariant = loadInvariantCollections(dir, read);
+    const readIfPresent = (path) => {
+        const text = read(path);
+        return text === undefined ? undefined : JSON.parse(text);
+    };
     return {
         dir,
         index,
         invariant,
-        entryPath: (row) => join(dir, row.path),
-        v1defPath: (row) => join(dir, sidecarPath(row.path)),
+        entryPath: (row) => libraryPath(dir, row.path),
+        v1defPath: (row) => libraryPath(dir, sidecarPath(row.path)),
         readEntry(row) {
-            const path = join(dir, row.path);
-            return existsSync(path) ? readJsonFile(path) : undefined;
+            return readIfPresent(libraryPath(dir, row.path));
         },
         readV1Def(row) {
-            const path = join(dir, sidecarPath(row.path));
-            return existsSync(path) ? unwrapV1Def(readJsonFile(path)) : undefined;
+            const raw = readIfPresent(libraryPath(dir, sidecarPath(row.path)));
+            return raw === undefined ? undefined : unwrapV1Def(raw);
         },
     };
 }

package/dist/registry/lookup-specs.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Which connector input fields earn a `.by*` helper, and what the helper needs.
+ *
+ * A `reference` with a `lookupValue` says a field's value is an opaque id to be
+ * resolved against a live connection. Two classes are excluded: IDENTITY
+ * lookups, where `lookupValue` is the only `lookupNames` entry so resolving
+ * returns what it was given, and INVARIANT collections, whose ids are a property
+ * of the connector's API rather than of a connection (a country list), read from
+ * the curated `invariant-collections.json` ledger. Everything else is a lookup;
+ * the fallback direction is the safe one.
+ *
+ * Ported from `integrations/scripts/_lookups.py` and the `lookup_specs` half of
+ * `generate_connectors_ts.py`. `core/lookups.ts` keeps `check` and `compile`
+ * agreeing with this by importing it.
+ */
+import { type ReadText } from "../core/read-text.js";
 import type { FieldReference, LibraryField } from "./model/library.js";
 export declare const LEDGER_FILENAME = "invariant-collections.json";
 /**
@@ -5,7 +21,7 @@ export declare const LEDGER_FILENAME = "invariant-collections.json";
  * ledger reads as empty rather than raising: the permissive path is the
  * pre-ledger behaviour, so a bad edit loses exactness, never a build.
  */
-export declare function loadInvariantCollections(libraryDir: string | undefined): Set<string>;
+export declare function loadInvariantCollections(libraryDir: string | undefined, read?: ReadText): Set<string>;
 /** The field's `reference` block when it declares a resolvable value. */
 export declare function referenceOf(field: {
     reference?: unknown;

package/dist/registry/lookup-specs.js

@@ -13,8 +13,7 @@
  * `generate_connectors_ts.py`. `core/lookups.ts` keeps `check` and `compile`
  * agreeing with this by importing it.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { libraryPath, readTextFromDisk } from "../core/read-text.js";
 import { pyTruthy } from "./generators/type-tree.js";
 import { byAliases } from "./naming.js";
 export const LEDGER_FILENAME = "invariant-collections.json";
@@ -23,15 +22,12 @@ export const LEDGER_FILENAME = "invariant-collections.json";
  * ledger reads as empty rather than raising: the permissive path is the
  * pre-ledger behaviour, so a bad edit loses exactness, never a build.
  */
-export function loadInvariantCollections(libraryDir) {
+export function loadInvariantCollections(libraryDir, read = readTextFromDisk) {
     if (!libraryDir)
         return new Set();
-    const path = join(libraryDir, LEDGER_FILENAME);
-    if (!existsSync(path))
-        return new Set();
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
+        parsed = JSON.parse(read(libraryPath(libraryDir, LEDGER_FILENAME)) ?? "{}");
     }
     catch {
         return new Set();

package/dist/registry/path-cli.js

@@ -1,6 +1,7 @@
 import { printResult, reportResult } from '../cli-result.js';
 import { join } from "node:path";
-import { CURRENT_LINK, PULL_COMMAND, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "../core/library-cache.js";
+import { PULL_COMMAND } from "../core/cli-spelling.js";
+import { CURRENT_LINK, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "../core/library-cache.js";
 /**
  * Say where the connector library is.
  *

package/dist/registry/search-cli.js

@@ -1,6 +1,7 @@
 import { printResult, reportResult } from '../cli-result.js';
 import { readFile, stat } from "node:fs/promises";
-import { PULL_COMMAND, resolveLibraryDir } from "../core/library-cache.js";
+import { PULL_COMMAND } from "../core/cli-spelling.js";
+import { resolveLibraryDir } from "../core/library-cache.js";
 import { dirname, join } from "node:path";
 export const DEFAULT_SEARCH_LIMIT = 20;
 const USAGE = "Usage: flow-sdk registry search [query] [--library <dir>] [--library-md <dir>] [--connector <key>] [--limit <n>]";

package/dist/serialize.d.ts

@@ -13,31 +13,6 @@ import { connectorInputErrors as coreConnectorInputErrors } from './core/connect
  * dropping it would make `check` quietly accept what `compile` throws on.
  */
 export declare function connectorInputErrors(rc: Parameters<typeof coreConnectorInputErrors>[0], inputs: Record<string, unknown>, resolutions?: Parameters<typeof coreConnectorInputErrors>[2], lookups?: Parameters<typeof coreConnectorInputErrors>[3]): string | undefined;
-/**
- * Every tool resource identity `compile` writes, read off the tables its
- * writers use — so a tool kind cannot be written without being owned, or owned
- * without being written (#935: the #920 built-in files were written as
- * `internal` and never pruned, because ownership was a hand-kept list in
- * `compile-cli.ts` that did not have them).
- *
- *  * `types` — the resource `type`s compile owns OUTRIGHT: every deployed-resource
- *    kind's, and `integration` (connector tools, since #867).
- *  * `internalToolTypes` — `internal` is shared with designer-only built-ins
- *    (`load-attachments`, `create-file`, `jev-classifier`), so for it ownership
- *    is the `properties.toolType`, and only the ones compile writes.
- */
-export declare const COMPILE_WRITTEN_TOOL_RESOURCES: {
-    readonly types: ReadonlySet<string>;
-    readonly internalToolTypes: ReadonlySet<string>;
-};
-/**
- * Does `compile` own this `resources/<id>/resource.json` — would a compile have
- * written it, so one this compile did not write is stale rather than someone
- * else's? Everything it says no to belongs to the designer or to `uip agent
- * refresh` (escalation, mcp, designer-only built-ins, the kinds the SDK cannot
- * derive), and is never deleted.
- */
-export declare function compileOwnsResource(body: Record<string, unknown> | undefined): boolean;
 /**
  * A compile-time observation that does not stop emission. `check()` has its
  * diagnostics; this is the serializer's own channel for things it can only see
@@ -129,9 +104,8 @@ export declare function serializeWithSidecars(built: BuiltFlow, opts?: Serialize
 /**
  * The node type a typed action compiles to, when that type's definition is
  * bundled in `core-definitions.json`. `undefined` for a family whose definition
- * is built per tenant or per call (connector, rpaWorkflow, apiWorkflow,
- * agenticProcess, publishedFunction, agent, ixpExtract) and for a spec this SDK
- * does not lower by kind.
+ * is built per tenant or per call (connector, ixpExtract) and for a spec this
+ * SDK does not lower by kind.
  *
  * A registered kind (flow-node-registry.ts) is not listed: its type is the
  * registry's.
@@ -141,17 +115,16 @@ export declare function bundledActionNodeType(spec: {
     inputs?: any;
 } | undefined): string | undefined;
 /**
- * The definition serialize synthesizes for a family that has no bundled one:
- * a published process resource (`rpaWorkflow`, `apiWorkflow`,
- * `agenticProcess`, `publishedFunction`, `agent`) or an `ixpExtract` step.
- * Their node type carries a tenant's key, so the SDK builds the definition
- * per call, transcribed from what `registry get` returns. `undefined` for
- * every other kind (a bundled family, a connector, a container).
+ * The definition serialize synthesizes for a kind that has no bundled one and
+ * is not on the node-type registry: an `ixpExtract` step. Its node type carries
+ * a tenant's key, so the SDK builds the definition per call, transcribed from
+ * what `registry get` returns. `undefined` for every other kind (a bundled
+ * family, a connector, a container, a registered kind — the published process
+ * resources and the agent build theirs in nodes/process/flow/).
  *
  * The emit path builds its definition here, and `check` asks this same
  * definition whether the node has an error port (#1040), so the two cannot
- * disagree. For instance `publishedFunction(...)` yields
- * `uipath.core.function.<key>@1.0.0` with `supportsErrorHandling: true`.
+ * disagree.
  *
  * Throws what the family's builder throws for an unusable spec (an
  * `ixpExtract` project that is not a node type).
@@ -160,24 +133,6 @@ export declare function perCallDefinition(spec: {
     kind?: string;
     inputs?: any;
 } | undefined): any | undefined;
-/**
- * The definition version serialize emits for a typed action step that is not
- * yet on the node-type registry: the author's `{ version }` when given,
- * otherwise the version the step's inputs select, otherwise `undefined` (the
- * pinned default). One such family picks a version itself: `inlineAgent`
- * takes the newest bundled version, not the first bundled entry.
- *
- * The emit paths read their version here, and `check` resolves the definition
- * it asks about with this same version (#1041), so the two cannot pick
- * different definitions. For instance `inlineAgent({ ... })` gives the newest
- * bundled version in both. A registered family (e.g. `dataFabricRead`, whose
- * `resultMode` selects `core.datafabric.read@1.4`) gets the same guarantee from
- * the registry's `resolveVersion`, which check and serialize both call.
- */
-export declare function actionVersion(spec: {
-    kind?: string;
-    inputs?: any;
-} | undefined, explicit: string | undefined): string | undefined;
 /**
  * The bundled definition of `nodeType` that `makeNode` resolves: the author's
  * exact `{ version }` when given, otherwise the pinned default (the first