@uipath/maestro-builder-sdk 6.42.0 → 6.44.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/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