@uipath/maestro-builder-sdk 6.9.3 → 6.9.4

package/dist/compile-cli.js

@@ -17,7 +17,7 @@
  * product's own gates are supposed to answer. `.build()` still throws on
  * structural problems; only the diagnostic pass is skipped.
  */
-import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { writeFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars, connectorInputErrors } from './serialize.js';
@@ -32,6 +32,28 @@ function opt(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 ? argv[i + 1] : undefined;
 }
+/**
+ * The deployed-resource tool `type` values `compile` writes. NOT every
+ * `$resourceType: 'tool'`: `uip agent refresh` generates the `integration` ones
+ * from the flow's connector nodes into the same directory, so pruning by
+ * `$resourceType` alone would delete the generator's own output.
+ */
+const COMPILE_OWNED_TOOL_TYPES = new Set([
+    'process', 'api', 'processOrchestration', 'flow', 'agent', 'function',
+]);
+/**
+ * Does `compile` own this resource file — i.e. would this run have written it,
+ * so an unwritten one is stale rather than someone else's?
+ *
+ * Everything it says no to belongs to `uip agent refresh` (connector tools) or to
+ * the designer (escalation, mcp, and the kinds the SDK cannot derive).
+ */
+function compileOwnsResource(body) {
+    const kind = body?.$resourceType;
+    if (kind === 'context')
+        return true;
+    return kind === 'tool' && COMPILE_OWNED_TOOL_TYPES.has(String(body?.type));
+}
 export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.error('usage: compile <flow.ts | BaseName> [-o out.flow] [--library <dir>] [--bindings <file>]');
@@ -152,6 +174,61 @@ export async function run(argv) {
         writeFileSync(target, JSON.stringify(s.json, null, 2) + '\n');
         console.log(`compile: wrote ${s.path}`);
     }
+    // PRUNE the agent resources this compile owns but did not write this time.
+    // Compile otherwise only ever ADDS files, and an agent resource is keyed by a
+    // uuid derived from the step name and the resource's identity — so dropping a
+    // `context` from a step, or pointing it at a different index, orphans the old
+    // `resources/<uuid>/resource.json` instead of replacing it. Nothing later
+    // notices it is orphaned: `uip agent refresh` reads every file under
+    // `resources/` and declares it, so `bindings_v2.json` keeps binding an index
+    // the flow no longer references, and a deploy can fail on an index that is
+    // gone. Measured 2026-09-25 — compile with a context, remove it, recompile:
+    // the file survives and refresh still reports `Resources: 1`.
+    //
+    // Only the types THIS compile emits are pruned. `uip agent refresh` generates
+    // connector-tool resources into the same directory, and the designer writes
+    // the families the SDK cannot, so anything else found there is someone else's
+    // and is left alone.
+    const staleBindings = [];
+    const owned = new Set(sidecars
+        .filter((s) => /\/resources\/[^/]+\/resource\.json$/.test(s.path))
+        .map((s) => resolve(outDir, s.path)));
+    for (const agentDir of new Set(sidecars
+        .filter((s) => s.path.endsWith('/agent.json'))
+        .map((s) => dirname(resolve(outDir, s.path))))) {
+        const resourcesDir = join(agentDir, 'resources');
+        if (!existsSync(resourcesDir))
+            continue;
+        for (const entry of readdirSync(resourcesDir)) {
+            const file = join(resourcesDir, entry, 'resource.json');
+            if (!existsSync(file) || owned.has(file))
+                continue;
+            let body;
+            try {
+                body = JSON.parse(readFileSync(file, 'utf8'));
+            }
+            catch {
+                continue; // unreadable: not ours to delete
+            }
+            if (!compileOwnsResource(body))
+                continue;
+            const resourceType = body?.$resourceType;
+            // The binding `uip agent refresh` derived FROM this file has to go with it.
+            // Refresh will not retract it: with no resources left it writes nothing, and
+            // `mergeBindingsV2` preserves every non-connection entry, so the removed
+            // index would stay declared in `bindings_v2.json` and a deploy could still
+            // fail on it. Keyed the way refresh keys it — an index by its name.
+            const named = body?.indexName ?? body?.name;
+            const key = typeof named === 'string' && named !== '' ? named : undefined;
+            if (key !== undefined) {
+                // Keyed the way refresh keys it: an index by its name, a deployed-resource
+                // tool under `process` whatever its own type says.
+                staleBindings.push({ resource: resourceType === 'context' ? 'index' : 'process', key });
+            }
+            rmSync(join(resourcesDir, entry), { recursive: true, force: true });
+            console.log(`compile: removed stale ${join('resources', entry, 'resource.json')}`);
+        }
+    }
     // `bindings_v2.json` — the solution-resource sidecar `uip solution resources
     // refresh` reads. Without it the connection is never declared, so the canvas
     // and the VS Code extension flag the Flow's connection as invalid
@@ -167,6 +244,10 @@ export async function run(argv) {
         // file for a flow that has no resources at all.
         if (connections.length > 0 || existing !== undefined) {
             const merged = mergeBindingsV2(existing, connections);
+            if (staleBindings.length > 0) {
+                const dropped = new Set(staleBindings.map((b) => `${b.resource}\u0000${b.key}`));
+                merged.resources = merged.resources.filter((r) => !dropped.has(`${r.resource}\u0000${r.key}`));
+            }
             writeFileSync(sidecarPath, JSON.stringify(merged, null, 2) + '\n');
             const kept = merged.resources.length - connections.length;
             console.log(`compile: wrote bindings_v2.json (${connections.length} connection resource(s)`

package/dist/core/actions.d.ts

@@ -1827,6 +1827,12 @@ export interface ProcessToolRef {
     name: string;
     /** The Orchestrator folder it lives in, e.g. `'Shared'`. */
     folderPath: string;
+    /**
+     * What the tool does. The agent runtime hands this to the MODEL as the tool's
+     * description, so it is how the model decides when to call it — a tool with
+     * only a name is one the model has to guess at.
+     */
+    description?: 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`. */

package/dist/serialize.d.ts

@@ -23,10 +23,11 @@ export interface SerializeOpts {
     warn?: (warning: SerializeWarning) => void;
     /**
      * Filled in by `serialize` with the extra files the flow needs beside the
-     * `.flow`, relative to it. Today that is one `<source>/agent.json` per inline
-     * agent: the node points at that directory and the platform resolves the agent's
-     * real configuration there, so a `.flow` shipped without it references a
-     * definition that is not on disk.
+     * `.flow`, relative to it: one `<source>/agent.json` per inline agent, plus a
+     * `<source>/resources/<id>/resource.json` for each capability the compiler can
+     * derive. The node points at that directory and the platform resolves the
+     * agent's real configuration there, so a `.flow` shipped without them references
+     * a definition that is not on disk.
      *
      * An out-parameter rather than a second return value so no caller that ignores
      * sidecars has to change — but a caller that WRITES the flow has to write these

package/dist/serialize.js

@@ -857,6 +857,172 @@ function renderContextQuery(query, rename) {
     }
     return { ...base, promptValue: asText };
 }
+/**
+ * The file extension each retrieval mode accepts by default. The platform's
+ * manifest defaults every mode's NODE to `All`, but its resource schema pins
+ * `structured`/`batchtransform` to `csv` and `deeprag` to `pdf`/`txt` — so a
+ * flat `All` default would emit a resource the platform refuses to parse for
+ * every mode but `semantic`.
+ */
+const DEFAULT_FILE_EXTENSION = {
+    semantic: 'All',
+    structured: 'csv',
+    deeprag: 'pdf',
+    batchtransform: 'csv',
+};
+/**
+ * The `resources/<id>/resource.json` an inline agent's context index needs.
+ *
+ * The node is only half of a grounded agent, the same split as the agent itself
+ * (see `inlineAgentJson`). The platform resolves an agent's capabilities from
+ * `<source>/resources/<resource-id>/resource.json`, and `uip agent refresh` turns
+ * those into the `bindings_v2.json` entries `uip solution resources refresh`
+ * syncs. Keyed by the node's `inputs.source`, which is what joins the two halves.
+ *
+ * On the CLI path the file is the only copy: refresh strips the node and
+ * re-derives it from here, so a `.flow` with the node and no file validates clean
+ * and leaves the agent ungrounded. (Studio Web is the other direction — its
+ * `mapContextResource` builds this file FROM the canvas node.)
+ *
+ * Shape and enums are the platform's `currentResourceStorageSchema`
+ * (`@uipath/agents-storage-schemas`): `description`, `folderPath`, `indexName` and
+ * all six `settings` keys are required, `fileExtension` is `{value}` rather than a
+ * bare string, and the retrieval mode pins which extensions it accepts — hence the
+ * per-mode default here against the node's flat `'All'`. An unparseable resource
+ * is worse than none: `uip agent refresh` falls back to `resources: []` and drops
+ * every other binding with it.
+ */
+function contextResourceJson(cx, spec) {
+    const mode = cx.retrievalMode ?? 'semantic';
+    return {
+        $resourceType: 'context',
+        id: spec.id,
+        // Null rather than absent: optional in the schema, but every deployed
+        // resource carries it, and a designer round-trip writes it back.
+        referenceKey: null,
+        name: cx.name,
+        description: `Context grounding index "${cx.name}".`,
+        contextType: 'index',
+        // Required by the schema, and load-bearing: this file carries no `indexId`,
+        // so `indexName` + `folderPath` is the whole locator, and `createIndexBinding`
+        // leaves the folder off the binding when it is empty. `check` warns when the
+        // author omits it — an index outside the deployment folder is then unresolvable.
+        folderPath: cx.folderPath ?? '',
+        indexName: cx.name,
+        settings: {
+            retrievalMode: mode,
+            // The resource's `query` is VARIANT-tagged where the node's is MODE-tagged,
+            // and the two vocabularies do not overlap. `prompt` — what a designer types
+            // as guidance — is the model-invoked `dynamic`, and its text is the
+            // `description` the model reads when deciding what to search for.
+            // `text-builder` — an expression the runtime templates — is the pre-fetched
+            // `static`, and its text is the `value`. Confirmed behaviourally: switching
+            // the SDK's `query` from a string to an expression turned the same agent's
+            // retrieval from a tool call into a pre-fetch.
+            query: spec.query.mode === 'text-builder'
+                ? { variant: 'static', value: String(spec.query.textValue ?? '') }
+                : { variant: 'dynamic', description: String(spec.query.promptValue ?? '') },
+            folderPathPrefix: { variant: 'static' },
+            threshold: cx.threshold ?? 0,
+            resultCount: cx.resultCount ?? 3,
+            fileExtension: { value: cx.fileExtension ?? DEFAULT_FILE_EXTENSION[mode] ?? 'All' },
+            // Mode-specific keys the schema REQUIRES of those two modes and rejects
+            // nowhere else, carrying the node's own constants through the enum's
+            // spelling (the node says `enabled`; the resource says `Enabled`/`Inline`).
+            ...(mode === 'deeprag' ? { citationMode: { value: 'Inline' } } : {}),
+            ...(mode === 'batchtransform'
+                ? { webSearchGrounding: { value: 'Enabled' }, outputColumns: [] }
+                : {}),
+        },
+    };
+}
+/** A `fieldSchema` object with every declared property marked required. */
+function requireAll(schema) {
+    const names = Object.keys(schema.properties);
+    return names.length === 0 ? schema : { ...schema, required: names };
+}
+/**
+ * The resource `type` each deployed-resource tool kind carries in the agent
+ * project, which is NOT its node-type namespace: `maestro` mints
+ * `…tool.processorchestration.*` and its resource type is `processOrchestration`.
+ * Read off the platform's `currentResourceStorageSchema`; flow-workbench's
+ * `CANVAS_TO_STORAGE_TOOL_TYPE` maps them the same way.
+ */
+const TOOL_RESOURCE_TYPE = {
+    process: 'process', api: 'api', maestro: 'processOrchestration',
+    flow: 'flow', agent: 'agent', function: 'function',
+};
+/**
+ * The `resources/<id>/resource.json` a DEPLOYED-RESOURCE tool needs — the tool
+ * half of what `contextResourceJson` does for an index, and inert for the same
+ * reason (see that function).
+ *
+ * Shape from a real agent project (`WebResearchBriefingAgent`'s `CountSources`,
+ * a `kind: 'process'` tool), cross-checked against the platform schema: this
+ * family carries `argumentProperties` and `referenceKey` but no `iconUrl`, and
+ * `exampleCalls` is present-and-empty. `location: 'solution'` and an empty
+ * `properties.folderPath` are the inline-in-flow pair Studio Web's
+ * `mapToolResource` writes and uipcli's `agent validate` enforces — the folder
+ * itself lives in the flow's top-level `bindings[]`, which
+ * `processResourceBindings` already writes for this tool.
+ *
+ * Returns `undefined` for every OTHER kind. Which kinds get a file is measured,
+ * because `uip agent refresh` strips each resource node and re-derives it FROM
+ * the file: where the node is `source`-only the round-trip is lossless, and where
+ * the node carries the configuration the strip loses it and the rebuild cannot
+ * put it back, so writing the file turns a valid flow INVALID.
+ *
+ *  * `ixp`, `clientside` — measured to fail exactly that way (`ixp` leaves the
+ *    flow failing validate; `clientside` drops the four inputs its node needs).
+ *  * `connector` — `uip agent refresh` GENERATES it from the flow's connector
+ *    node, reconstructing a whole `properties` block the SDK should not duplicate.
+ *  * `mcp`, `a2a` — need the server's `availableTools` and the remote agent's
+ *    card, which are tenant reads.
+ *  * `builtin`, `httpRequest` — need a `properties.toolType` that maps
+ *    one-to-one for `batchtransform` alone; a wrong one selects a different tool.
+ */
+function toolResourceJson(tr, spec) {
+    const common = {
+        $resourceType: 'tool',
+        id: spec.id,
+        name: tr.name,
+        // The runtime hands this to the MODEL as the tool's description, so an empty
+        // one is a tool the model has to guess at from its name alone.
+        description: tr.description ?? '',
+        isEnabled: true,
+        // `required` matters here where it does not on the agent's own contract: the
+        // model reads this schema to build the call, and an argument the process needs
+        // but the schema calls optional fails at run time with nothing said at compile
+        // time. The corpus fixture lists every declared argument.
+        inputSchema: requireAll(fieldSchema(tr.inputs)),
+        outputSchema: fieldSchema(tr.returns),
+        // No policies: `inlineAgent`'s tool refs carry none, and the field is
+        // required-but-emptyable.
+        guardrail: { policies: [] },
+        settings: {},
+        argumentProperties: {},
+    };
+    const resourceType = TOOL_RESOURCE_TYPE[tr.kind];
+    if (resourceType !== undefined) {
+        return {
+            ...common,
+            type: resourceType,
+            location: 'solution',
+            // The deployed resource's own key: what joins this tool to the release the
+            // solution declares.
+            referenceKey: tr.key,
+            // `folderPath` is EMPTY on purpose, and the tenant folder is not lost: for
+            // an inline-in-flow agent the folder lives in the flow's own top-level
+            // `bindings[]`, which `processResourceBindings` already writes for this
+            // tool. uipcli's `agent validate` says so where it enforces the pair —
+            // *"Inline-in-flow agents store folder info in the flow's top-level
+            // bindings[] rather than in the tool resource — Studio Web emits an empty
+            // folderPath here"* — and every `inlineAgent` tool is inline by definition.
+            properties: { processName: tr.name, folderPath: '', exampleCalls: [] },
+        };
+    }
+    return undefined;
+}
 /**
  * The one TARGET handle every tool resource declares: `input`, artifact-typed,
  * fed by the two agent types' `tool` handles. Transcribed from `registry get`
@@ -4496,6 +4662,12 @@ export function serialize(built, opts = {}) {
                 // `inputDefaults` are the shape a designer-placed node has — so an omitted
                 // option emits the designer's value rather than nothing.
                 delete cnode.model;
+                // ONE identity, spent twice: the node's `inputs.source` and the sidecar
+                // resource's `id` are the same uuid, because that is what joins them. The
+                // platform validator says so in its own refusal text — *"the resource id
+                // from the parent inline agent's `resources[]`"*.
+                const contextResourceId = stableUuid(`${built.id}/${step.name}/context/${cx.id}`);
+                const contextQuery = renderContextQuery(cx.query, scope.rename);
                 cnode.inputs = {
                     // REQUIRED, and the platform's validator is what says so — measured
                     // 2026-07-31, omitting it: *"Node type
@@ -4504,7 +4676,7 @@ export function serialize(built, opts = {}) {
                     // node"* (MST-9265). It is the resource's own identity inside the
                     // project, so it is derived from flow + step + index rather than random,
                     // exactly like the agent's `source`: a recompile must not be a diff.
-                    source: stableUuid(`${built.id}/${step.name}/context/${cx.id}`),
+                    source: contextResourceId,
                     indexId: cx.id,
                     indexName: cx.name,
                     ...(cx.folderKey === undefined ? {} : { folderKey: cx.folderKey }),
@@ -4514,7 +4686,7 @@ export function serialize(built, opts = {}) {
                     // `{mode, textValue, promptValue, argumentPath}`, with the mode saying
                     // which field is live. A plain string is the `prompt` mode; a flow
                     // expression is `text-builder`, whose `textValue` the runtime templates.
-                    query: renderContextQuery(cx.query, scope.rename),
+                    query: contextQuery,
                     threshold: cx.threshold ?? 0,
                     resultCount: cx.resultCount ?? 3,
                     fileExtension: cx.fileExtension ?? 'All',
@@ -4525,6 +4697,12 @@ export function serialize(built, opts = {}) {
                 };
                 scope.nodes.push(cnode);
                 addEdge(scope, { node: id, port: 'context' }, cid, 'input');
+                // The other half — without it the node is inert: see
+                // `contextResourceJson`.
+                sidecars.push({
+                    path: `${source}/resources/${contextResourceId}/resource.json`,
+                    json: contextResourceJson(cx, { id: contextResourceId, query: contextQuery }),
+                });
             }
             // TOOLS — one resource node per tool, joined to the agent's `tool` handle;
             // the same artifact shape as context (no incoming control flow, no output,
@@ -4674,12 +4852,23 @@ export function serialize(built, opts = {}) {
                             : tr.kind === 'clientside' ? `clientside.${tr.name}`
                                 : tr.kind === 'httpRequest' ? `httprequest.${tr.name ?? 'default'}`
                                     : tr.key;
+                const toolResourceId = stableUuid(`${built.id}/${step.name}/tool/${toolSeed}`);
                 tnode.inputs = {
-                    source: stableUuid(`${built.id}/${step.name}/tool/${toolSeed}`),
+                    source: toolResourceId,
                     ...extraInputs,
                 };
                 scope.nodes.push(tnode);
                 addEdge(scope, { node: id, port: 'tool' }, tid, 'input');
+                // The other half, for the kinds whose file is DERIVABLE — see
+                // `toolResourceJson` for which are not, and why each is left to the
+                // generator or the designer rather than guessed.
+                const toolResource = toolResourceJson(tr, { id: toolResourceId });
+                if (toolResource !== undefined) {
+                    sidecars.push({
+                        path: `${source}/resources/${toolResourceId}/resource.json`,
+                        json: toolResource,
+                    });
+                }
             }
             // ESCALATION — the agent's TOP handle; an Action Center app task a human
             // completes. The node's inputs are the platform's `inputDefaults` shape
@@ -4787,6 +4976,9 @@ export function serialize(built, opts = {}) {
                 };
                 scope.nodes.push(mnode);
                 addEdge(scope, { node: id, port: 'memory' }, mid, 'input');
+                // No `features/<id>/feature.json` until `check` stops refusing memory
+                // (AGENT_MEMORY_NOT_AUTHORABLE); its shape maps cleanly off `AgentMemoryRef`
+                // but cannot be exercised while the handle does not exist.
             }
             for (const t of tails)
                 addEdge(scope, t, id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.9.3",
+  "version": "6.9.4",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "ac3e6768fb9c4f51d37eb6f51c588cbf7b7912c7"
+  "gitref": "ca9f8350a07eaf7ec145b315ad37e75e00a23049"
 }