@uipath/maestro-builder-sdk 6.32.8 → 6.33.1

package/dist/case/case-sdk.d.ts

@@ -1010,10 +1010,16 @@ declare class StageBuilder {
      * scheduler rules whether they share a set or not, and the designer writes
      * one task per set even for a stage its own SDD calls parallel.
      *
+     * A task without a `runs-sequentially` rule is always written to a set of its
+     * own, placed right after the set `lane` names; `lane` only groups sequential
+     * tasks. Case schema V31 made set membership behavioural: its V30→V31
+     * migration rewrites the entry conditions of any non-sequential task that
+     * shares a set (builder-sdk#1248).
+     *
      * @param displayName - The task's display name.
      * @param fn - Receives a sub-builder for what the task does.
-     * @param opts - `lane` is the task's set index in `data.tasks[][]` (default 0);
-     *   it orders `runs-sequentially` sets and is inert for every other task.
+     * @param opts - `lane` is the index of the set a `runs-sequentially` task joins
+     *   in `data.tasks[][]` (default 0). Any other task gets its own set after it.
      * @returns This builder, so calls chain.
      */
     task(displayName: string, fn: (t: TaskBuilder) => void, opts?: {

package/dist/case/case-sdk.js

@@ -516,10 +516,16 @@ class StageBuilder {
      * scheduler rules whether they share a set or not, and the designer writes
      * one task per set even for a stage its own SDD calls parallel.
      *
+     * A task without a `runs-sequentially` rule is always written to a set of its
+     * own, placed right after the set `lane` names; `lane` only groups sequential
+     * tasks. Case schema V31 made set membership behavioural: its V30→V31
+     * migration rewrites the entry conditions of any non-sequential task that
+     * shares a set (builder-sdk#1248).
+     *
      * @param displayName - The task's display name.
      * @param fn - Receives a sub-builder for what the task does.
-     * @param opts - `lane` is the task's set index in `data.tasks[][]` (default 0);
-     *   it orders `runs-sequentially` sets and is inert for every other task.
+     * @param opts - `lane` is the index of the set a `runs-sequentially` task joins
+     *   in `data.tasks[][]` (default 0). Any other task gets its own set after it.
      * @returns This builder, so calls chain.
      */
     task(displayName, fn, opts = {}) {

package/dist/case/serialize.js

@@ -10,6 +10,7 @@
  */
 import { IdGen } from './ids.js';
 import { isUnrestorableSlotId } from './preserve.js';
+import { v31TaskSets } from './task-sets.js';
 import { buildConnectorInputs, nestConnectorBody, transportHttpMethod } from '../core/connector-inputs.js';
 import { EQUALS_EXPR_DIALECT } from '../core/connector-checks.js';
 import { bindingLabelRefusal } from '../core/binding-messages.js';
@@ -109,6 +110,8 @@ export function serialize(built, opts = {}) {
     built.stages.forEach((stage) => prealloc(stage.slaRules, stage.label));
     const stageIds = [];
     const taskIds = []; // [stageIndex][lane][taskIndex]
+    // The task sets as written: one set per parallel task (see `laneSets`).
+    const stageLanes = built.stages.map((stage) => laneSets(stage.lanes));
     // Task displayNames must be unique across the whole case: the platform rejects
     // duplicates (CASE_MGMT_STAGE_TASK_NAME_DUPLICATE, CRITICAL), and a bare
     // `selected-tasks-completed` reference resolves against a single name→id map, so
@@ -121,7 +124,7 @@ export function serialize(built, opts = {}) {
         resolver.stageIdByLabel.set(stage.label, sid);
         stageIds.push(sid);
         taskIds.push([]);
-        stage.lanes.forEach((lane, li) => {
+        stageLanes[si].forEach((lane, li) => {
             taskIds[si].push([]);
             lane.forEach((task) => {
                 if (seenTaskNames.has(task.name))
@@ -144,7 +147,7 @@ export function serialize(built, opts = {}) {
     const triggerNodeByRef = new Map();
     built.triggers.forEach((t, i) => triggerNodeByRef.set(t, triggerNodes[i]));
     built.stages.forEach((stage, si) => {
-        nodes.push(emitStage(stage, si, stageIds[si], taskIds[si], ids, resolver));
+        nodes.push(emitStage(stage, stageLanes[si], si, stageIds[si], taskIds[si], ids, resolver));
     });
     // ── Metadata (case-level) ──
     const metadata = {
@@ -382,7 +385,7 @@ export function applyPreservation(result, preservation, options = {}) {
         .filter((node) => String(node.type ?? '').endsWith('Stage'));
     for (const entry of preservation.taskFields ?? []) {
         const stage = stageNodes.find((candidate) => candidate.data?.label === entry.stage);
-        const task = stage?.data?.tasks?.[entry.lane]?.find((candidate) => candidate.displayName === entry.task);
+        const task = stageTask(stage, entry.task);
         // A brownfield edit may deliberately delete a typed task or its stage. Its
         // attached designer-only fields leave with that construct; surviving tasks
         // still collide-refuse below instead of letting preservation overwrite
@@ -408,7 +411,7 @@ export function applyPreservation(result, preservation, options = {}) {
     }
     for (const entry of preservation.omitTaskElementIds ?? []) {
         const stage = stageNodes.find((candidate) => candidate.data?.label === entry.stage);
-        const task = stage?.data?.tasks?.[entry.lane]?.find((candidate) => candidate.displayName === entry.task);
+        const task = stageTask(stage, entry.task);
         if (task)
             delete task.elementId;
     }
@@ -483,8 +486,8 @@ function applyPreservedIdentities(result, preservation) {
         takeConditions(stage?.data?.entryConditions, stageIdentity.entryConditions);
         takeConditions(stage?.data?.exitConditions, stageIdentity.exitConditions);
         takeSlas(stage?.data?.slaRules, stageIdentity.slaRules);
-        (stageIdentity.tasks ?? []).forEach((lane, laneIndex) => lane.forEach((taskIdentity) => {
-            const task = stage?.data?.tasks?.[laneIndex]?.find((candidate) => candidate.displayName === taskIdentity.name);
+        (stageIdentity.tasks ?? []).forEach((lane) => lane.forEach((taskIdentity) => {
+            const task = stageTask(stage, taskIdentity.name);
             take(task, taskIdentity.id);
             takeConditions(task?.entryConditions, taskIdentity.entryConditions);
             (taskIdentity.inputs ?? []).forEach((row, index) => take(task?.data?.inputs?.[index], row.id));
@@ -729,13 +732,25 @@ function emitTriggers(triggers, ids, resolver) {
         };
     });
 }
-function emitStage(stage, si, stageId, laneTaskIds, ids, resolver) {
+/** A stage's task sets as the serializer writes them — one set per parallel task (`v31TaskSets`). */
+function laneSets(lanes) {
+    return v31TaskSets(lanes, (task) => task.entry.some((condition) => condition.rules.some((group) => group.some((r) => r.rule === 'runs-sequentially'))));
+}
+/** One emitted task of a stage node, by its (case-unique) display name, in any set. */
+function stageTask(stage, name) {
+    for (const lane of stage?.data?.tasks ?? [])
+        for (const candidate of lane)
+            if (candidate.displayName === name)
+                return candidate;
+    return undefined;
+}
+function emitStage(stage, lanes, si, stageId, laneTaskIds, ids, resolver) {
     const data = {
         [CASE_FORMAT_PROFILE.stageLabelField]: stage.label,
         parentElement: { id: 'root', type: 'case-management:root' },
         isInvalidDropTarget: false,
         isPendingParent: false,
-        tasks: stage.lanes.map((lane, li) => lane.map((task, ti) => emitTask(task, stage.label, laneTaskIds[li][ti], ids, resolver))),
+        tasks: lanes.map((lane, li) => lane.map((task, ti) => emitTask(task, stage.label, laneTaskIds[li][ti], ids, resolver))),
     };
     if (stage.description)
         data.description = stage.description;

package/dist/case/task-sets.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Task sets (`data.tasks[i]`) in the shape Case schema V31+ keeps unchanged.
+ *
+ * V31 made a set a sequential chain. Its V30→V31 migration — which the product
+ * runs on every V30 document it reads — keeps a set unchanged only when it holds
+ * one task, or when every task in it declares a `runs-sequentially` rule. Every
+ * other task in a shared set has its entry conditions REPLACED by a generated
+ * `runs-sequentially` condition, so two parallel `current-stage-entered` tasks
+ * written into one set ran one after the other, under conditions the author
+ * never wrote, and nothing reported it (builder-sdk#1248).
+ *
+ * At V30 the regrouping is free: the converter reads a set's position only for
+ * tasks whose every rule is `runs-sequentially`; every other task runs on its
+ * own entry condition wherever it sits. A task the migration would rewrite
+ * therefore moves to a set of its own right after the set it was written in, so
+ * the stage's flattened task order — the order the converter writes its rules
+ * in — is unchanged too. Tasks the migration treats as sequential keep their
+ * set. The only case that reorders is a set that mixed both kinds: its
+ * sequential tasks stay together and the others follow.
+ *
+ * Generic over the task shape so the serializer (built tasks) and the tests
+ * (emitted JSON) apply the one rule.
+ */
+export declare function v31TaskSets<T>(sets: readonly (readonly T[])[], runsSequentially: (task: T) => boolean): T[][];
+/** The V30→V31 migration's own test, on emitted task JSON: any rule of any entry condition is `runs-sequentially`. */
+export declare function taskJsonRunsSequentially(task: {
+    entryConditions?: Array<{
+        rules?: Array<Array<{
+            rule?: string;
+        }>>;
+    }>;
+}): boolean;

package/dist/case/task-sets.js

@@ -0,0 +1,43 @@
+/**
+ * Task sets (`data.tasks[i]`) in the shape Case schema V31+ keeps unchanged.
+ *
+ * V31 made a set a sequential chain. Its V30→V31 migration — which the product
+ * runs on every V30 document it reads — keeps a set unchanged only when it holds
+ * one task, or when every task in it declares a `runs-sequentially` rule. Every
+ * other task in a shared set has its entry conditions REPLACED by a generated
+ * `runs-sequentially` condition, so two parallel `current-stage-entered` tasks
+ * written into one set ran one after the other, under conditions the author
+ * never wrote, and nothing reported it (builder-sdk#1248).
+ *
+ * At V30 the regrouping is free: the converter reads a set's position only for
+ * tasks whose every rule is `runs-sequentially`; every other task runs on its
+ * own entry condition wherever it sits. A task the migration would rewrite
+ * therefore moves to a set of its own right after the set it was written in, so
+ * the stage's flattened task order — the order the converter writes its rules
+ * in — is unchanged too. Tasks the migration treats as sequential keep their
+ * set. The only case that reorders is a set that mixed both kinds: its
+ * sequential tasks stay together and the others follow.
+ *
+ * Generic over the task shape so the serializer (built tasks) and the tests
+ * (emitted JSON) apply the one rule.
+ */
+export function v31TaskSets(sets, runsSequentially) {
+    const out = [];
+    for (const set of sets) {
+        if (set.length <= 1 || set.every(runsSequentially)) {
+            out.push([...set]);
+            continue;
+        }
+        const sequential = set.filter(runsSequentially);
+        if (sequential.length)
+            out.push(sequential);
+        for (const task of set)
+            if (!runsSequentially(task))
+                out.push([task]);
+    }
+    return out;
+}
+/** The V30→V31 migration's own test, on emitted task JSON: any rule of any entry condition is `runs-sequentially`. */
+export function taskJsonRunsSequentially(task) {
+    return (task.entryConditions ?? []).some((condition) => (condition.rules ?? []).some((group) => group.some((r) => r?.rule === 'runs-sequentially')));
+}

package/dist/check.js

@@ -34,9 +34,29 @@ import { plainHttpOnErrorMessage } from './nodes/http/flow/family.js';
 import { resolveVersion, resolveVersionCarried } from './core/nodes/versioned.js';
 import { declaredErrorPortRefusal } from './core/error-port.js';
 import { bodyUsesBreak, loopParallelWarning, loopVersionRefusal } from './loop-version.js';
+import { derivedResourceNodeId } from './core/agent-resource-identity.js';
+const newResourceIdLedger = () => ({ explicit: new Map(), taken: new Map(), agentSources: new Map() });
+/** INLINE_AGENT_RESOURCE_NODE_ID for each explicit `nodeId` another node of the file also gets. */
+function resourceNodeIdClashes(ledger) {
+    const out = [];
+    for (const [id, { step, what }] of ledger.explicit) {
+        const other = ledger.taken.get(id);
+        if (other === undefined)
+            continue;
+        out.push({
+            level: 'error', code: 'INLINE_AGENT_RESOURCE_NODE_ID', step,
+            message: `Inline agent step "${step}" gives its ${what} the \`nodeId\` "${id}", which is already `
+                + `${other}. Node ids are unique in a flow, so compile cannot write both. Give the resource another id, `
+                + 'or omit `nodeId` to derive one.',
+        });
+    }
+    return out;
+}
 export function check(built, opts = {}) {
     let diags = [];
-    const uses = collectConnectionUses(() => { diags = checkFlow(built, [], opts); });
+    const ledger = newResourceIdLedger();
+    const uses = collectConnectionUses(() => { diags = checkFlow(built, [], opts, ledger); });
+    diags.push(...resourceNodeIdClashes(ledger));
     for (const { id, message } of connectionConnectorConflicts(uses, opts)) {
         diags.push({ level: 'error', code: 'CONNECTION_CONNECTOR_CONFLICT', step: id, message });
     }
@@ -87,7 +107,7 @@ function checkStepIds(stepNames, trigger, diags) {
  * to notice a flow that (transitively) calls itself before the serializer
  * recurses forever.
  */
-function checkFlow(built, ancestors, opts = {}) {
+function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger()) {
     const diags = [];
     if (!built.id)
         diags.push({ level: 'error', code: 'NO_ID', message: 'flow() requires an id.' });
@@ -516,7 +536,7 @@ function checkFlow(built, ancestors, opts = {}) {
                     checkAgent(s.name, s.spec.inputs, diags);
                 }
                 if (s.spec.kind === 'inlineAgent') {
-                    checkInlineAgent(s.name, s.spec.inputs, diags, opts);
+                    checkInlineAgent(s.name, s.spec.inputs, diags, opts, ledger);
                 }
                 {
                     const rule = OUTPUT_READ_RULES[s.spec.kind];
@@ -878,6 +898,15 @@ function checkFlow(built, ancestors, opts = {}) {
     }
     reportUnreachableHitlOutcomes(hitlChoiceNoPorts, exprs, diags);
     checkRegisteredFamilies(registeredSteps, unresolvedSteps, stepNames, diags);
+    // The ids this scope's other nodes get, for the file-wide nodeId check in `check`.
+    for (const n of stepNames)
+        if (!ledger.taken.has(n))
+            ledger.taken.set(n, `the id of step "${n}"`);
+    if (!ledger.taken.has(triggerId))
+        ledger.taken.set(triggerId, 'the id of the trigger');
+    for (const ep of built.entryPoints ?? [])
+        if (!ledger.taken.has(ep.id))
+            ledger.taken.set(ep.id, `the id of entry point "${ep.id}"`);
     // Entry points: unique roots with valid triggers, colliding with nothing.
     const epIds = new Set();
     for (const ep of built.entryPoints ?? []) {
@@ -1294,7 +1323,7 @@ function checkFlow(built, ancestors, opts = {}) {
     for (const [stepName, child] of subflowChildren) {
         if (ancestors.includes(child) || child === built)
             continue;
-        for (const d of checkFlow(child, [...ancestors, built], opts)) {
+        for (const d of checkFlow(child, [...ancestors, built], opts, ledger)) {
             diags.push({
                 ...d,
                 code: d.code,
@@ -3061,7 +3090,7 @@ export function jsonTextDirective(text, returnKeys) {
  *    ALSO asks for JSON text makes the model pack its whole answer, serialized, into
  *    one string field. See {@link jsonTextDirective}.
  */
-function checkInlineAgent(step, inputs, diags, opts = {}) {
+function checkInlineAgent(step, inputs, diags, opts = {}, ledger = newResourceIdLedger()) {
     const at = (code, message, suggestion) => {
         diags.push({ level: 'error', code, message, step, ...(suggestion ? { suggestion } : {}) });
     };
@@ -3168,6 +3197,79 @@ function checkInlineAgent(step, inputs, diags, opts = {}) {
             + `and the one v1's smoke check for this node type FAILS a flow for keeping (it is the definition's `
             + `\`inputDefaults.model\`, not a choice). Pick a current model: \`uip agent model list\`.`);
     }
+    // Where each resource node sits (`nodeId`, `source`): decompile writes them
+    // for a node the canvas placed, and compile writes them as given. A blank or
+    // repeated id would make compile refuse the flow or overwrite another node,
+    // and a `source` that is not a uuid names a directory the platform does not
+    // expect (the agent's own `source` has the same rule).
+    const asList = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v]);
+    const placed = [
+        ...asList(inputs?.context).map((r) => ({ what: `context index "${r?.name ?? ''}"`, kind: 'Context', nodeId: r?.nodeId, source: r?.source })),
+        ...asList(inputs?.tools).map((r) => ({ what: `${r?.kind ?? ''} tool`, kind: 'Tool', nodeId: r?.nodeId, source: r?.source })),
+        ...asList(inputs?.escalation).map((r) => ({ what: `escalation "${r?.name ?? ''}"`, kind: 'Escalation', nodeId: r?.nodeId, source: r?.source })),
+    ];
+    // The ids compile derives for the resources with no `nodeId`: the n-th one of
+    // a kind gets `<step><Kind>`, then `<step><Kind>2`, ... An explicit id equal to
+    // one of them makes compile refuse the flow, or rename the derived node.
+    for (const kind of ['Context', 'Tool', 'Escalation']) {
+        const derived = placed.filter((r) => r.kind === kind && r.nodeId === undefined);
+        derived.forEach((r, n) => {
+            const id = derivedResourceNodeId(step, kind, n);
+            if (!ledger.taken.has(id))
+                ledger.taken.set(id, `the id compile derives for the ${r.what} of inline agent step "${step}"`);
+        });
+    }
+    /** Explicit `source` -> the resource on THIS agent that has it: two would write one resource.json. */
+    const sources = new Map();
+    for (const r of placed) {
+        if (r.nodeId !== undefined) {
+            const id = typeof r.nodeId === 'string' ? r.nodeId : '';
+            const other = ledger.explicit.get(id);
+            if (id.trim() === '') {
+                at('INLINE_AGENT_RESOURCE_NODE_ID', `Inline agent step "${step}" gives its ${r.what} the \`nodeId\` ${JSON.stringify(r.nodeId)}, which is `
+                    + `not a node id. Omit \`nodeId\` to derive one, or give the id the node has in the flow.`);
+            }
+            else if (other !== undefined) {
+                at('INLINE_AGENT_RESOURCE_NODE_ID', `Inline agent step "${step}" gives its ${r.what} the \`nodeId\` "${id}", which the ${other.what} `
+                    + `(on step "${other.step}") already has. Node ids are unique in a flow.`);
+            }
+            else {
+                ledger.explicit.set(id, { step, what: r.what });
+            }
+        }
+        if (r.source === undefined)
+            continue;
+        // Not trimmed: compile writes `source` as given, into `inputs.source` and the directory name.
+        if (!GUID_RE.test(String(r.source))) {
+            at('INLINE_AGENT_RESOURCE_SOURCE_NOT_GUID', `Inline agent step "${step}" gives its ${r.what} the \`source\` ${JSON.stringify(r.source)}, which is not `
+                + `a uuid${/^\s|\s$/.test(String(r.source)) ? ' (it has spaces around it)' : ''}. \`source\` is the resource's `
+                + `directory under the agent's own (\`resources/<source>/resource.json\`) and the node's \`inputs.source\`. `
+                + 'Omit it and one is derived from the flow id, the step and the resource.');
+            continue;
+        }
+        const key = String(r.source).toLowerCase();
+        const first = sources.get(key);
+        if (first !== undefined) {
+            at('INLINE_AGENT_RESOURCE_SOURCE_DUP', `Inline agent step "${step}" gives its ${first} and its ${r.what} the same \`source\` "${String(r.source)}". `
+                + 'Both would write `resources/<source>/resource.json` under this agent, and the second file would replace '
+                + 'the first. Give each resource its own `source`, or omit `source` to derive one.');
+        }
+        else {
+            sources.set(key, r.what);
+        }
+    }
+    if (typeof inputs?.source === 'string' && GUID_RE.test(inputs.source.trim())) {
+        const key = inputs.source.trim().toLowerCase();
+        const other = ledger.agentSources.get(key);
+        if (other !== undefined && other !== step) {
+            at('INLINE_AGENT_RESOURCE_SOURCE_DUP', `Inline agent steps "${other}" and "${step}" have the same \`source\` "${inputs.source}". Both would write `
+                + '`<source>/agent.json`, and the second file would replace the first. Give each agent its own `source`, '
+                + 'or omit it to derive one.');
+        }
+        else {
+            ledger.agentSources.set(key, step);
+        }
+    }
     if (inputs?.source !== undefined && !GUID_RE.test(String(inputs.source).trim())) {
         at('INLINE_AGENT_SOURCE_NOT_GUID', `Inline agent step "${step}"'s \`source\` is ${JSON.stringify(inputs.source)}, which is not a uuid. `
             + `\`source\` is the agent's own DIRECTORY name, and the platform resolves its configuration at `

package/dist/core/actions.d.ts

@@ -1131,7 +1131,43 @@ export type BuiltinToolName = 'analyzefiles' | 'summarize' | 'batchtransform';
  * `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;
+export type ToolRef = (BuiltinToolRef | ConnectorToolRef | ProcessToolRef | IxpToolRef | McpToolRef | RemoteA2aToolRef | ClientSideToolRef | HttpRequestToolRef) & AgentResourcePlacement;
+/**
+ * Where one of an inline agent's resources (a context index, a tool, an
+ * escalation) sits in the `.flow`: the id of its own resource NODE and the
+ * directory that holds its `resource.json`.
+ *
+ * @remarks
+ * Omit both when you write a flow: compile derives them, so a recompile is not
+ * a diff. Decompile writes them only for a file whose resource node another
+ * tool placed (the canvas, `uip maestro flow node add`) under an id or directory
+ * compile would not derive, so a no-edit round trip keeps the node, its layout
+ * entry and its directory instead of replacing them.
+ *
+ * ```ts
+ * // decompiled from a canvas file that named the index's node `ctx_7f2a1b`
+ * context: [{
+ *   name: 'Example SOP Index', id: '11111111-2222-4333-8444-555555555555',
+ *   nodeId: 'ctx_7f2a1b', source: 'd84e2c17-6a3f-4c59-b0e2-7f1a9c5b3d28',
+ * }]
+ * ```
+ */
+export interface AgentResourcePlacement {
+    /**
+     * The resource node's id. Defaults to `<agent step>Context`, `<agent step>Tool`
+     * or `<agent step>Escalation`, numbered from 2 for a second resource of the
+     * same kind (`<agent step>Context2`). Compile writes it as given and refuses an
+     * id another node in the flow already has (`check`: `INLINE_AGENT_RESOURCE_NODE_ID`).
+     */
+    nodeId?: string;
+    /**
+     * The resource's directory id, a uuid: the node's `inputs.source` and the
+     * `id` of `<agent source>/resources/<source>/resource.json`. Defaults to one
+     * derived from the flow id, the agent step and the resource, so a given flow
+     * emits the same uuid every time.
+     */
+    source?: string;
+}
 /**
  * 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
@@ -1398,9 +1434,9 @@ export interface IxpToolRef {
 /**
  * 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).
+ * serves), placed in the flow by {@link AgentResourcePlacement}.
  */
-export interface EscalationRef {
+export interface EscalationRef extends AgentResourcePlacement {
     /** The escalation's name — required by the definition (`minLength: 1`). */
     name: string;
     /** When the agent should escalate — what a reviewer sees as the reason. */
@@ -1463,13 +1499,14 @@ export interface EscalationRef {
     labels?: string[];
 }
 /**
- * One Context Grounding index an inline agent is grounded on.
+ * One Context Grounding index an inline agent is grounded on, placed in the
+ * flow by {@link AgentResourcePlacement}.
  *
  * @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 {
+export interface ContextIndexRef extends AgentResourcePlacement {
     /** The index's display name on the tenant, e.g. `'Billing Dispute SOP Index'`. */
     name: string;
     /**
@@ -1496,6 +1533,11 @@ export interface ContextIndexRef {
     threshold?: number;
     /** Restrict to one file type; `'All'` (the platform's default) or e.g. `'pdf'`. */
     fileExtension?: string;
+    /**
+     * The resource node's label on the canvas. Defaults to `name`. Only the
+     * canvas shows it; the index is found by `name` and `id`.
+     */
+    label?: string;
 }
 /**
  * Every action kind, keyed by kind, to the body of its spec — the arm's fields

package/dist/core/agent-resource-identity.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The identity compile derives for an inline agent's resource node when the
+ * author gives none: its node id and its resource directory (`inputs.source`).
+ *
+ * Serialize uses these to name what it emits. Decompile uses the same functions
+ * to decide whether a file's resource node carries the identity compile would
+ * derive anyway; when it does not (the canvas or the CLI placed the node), the
+ * decompiled source spells it out as `nodeId` / `source`
+ * (`AgentResourcePlacement`). One definition for both directions keeps
+ * them inverses: a second copy in decompile would drift from serialize's.
+ */
+import type { ToolRef } from './actions.js';
+/** The resource handles whose nodes compile names after the agent step. */
+export type AgentResourceKind = 'Context' | 'Tool' | 'Escalation' | 'Memory';
+/**
+ * The node id compile gives the `n`-th (0-based) resource of `kind` on agent
+ * step `agentStep` when no `nodeId` is set: `<step><Kind>`, then
+ * `<step><Kind>2`, `<step><Kind>3`, ... Characters a node id cannot hold become
+ * `_`, as compile's own id claim does. This assumes no other node already holds
+ * that id, which is the case for a flow compile wrote.
+ */
+export declare function derivedResourceNodeId(agentStep: string, kind: AgentResourceKind, n: number): string;
+/** The directory compile derives for a context index (`id` = the index id). */
+export declare function derivedContextSource(flowId: string, agentStep: string, indexId: string): string;
+/**
+ * What tells one tool on an agent from another for its derived directory: the
+ * built-in's name, the connector operation, the IxP project, the client-side or
+ * HTTP tool's name, else the resource key.
+ */
+export declare function toolResourceSeed(tr: ToolRef): string;
+/** The directory compile derives for a tool. */
+export declare function derivedToolSource(flowId: string, agentStep: string, tr: ToolRef): string;
+/** The directory compile derives for an escalation (`name` = the escalation's name). */
+export declare function derivedEscalationSource(flowId: string, agentStep: string, name: string): string;

package/dist/core/agent-resource-identity.js

@@ -0,0 +1,37 @@
+import { fnv1aX4Uuid } from './stable-id.js';
+/**
+ * The node id compile gives the `n`-th (0-based) resource of `kind` on agent
+ * step `agentStep` when no `nodeId` is set: `<step><Kind>`, then
+ * `<step><Kind>2`, `<step><Kind>3`, ... Characters a node id cannot hold become
+ * `_`, as compile's own id claim does. This assumes no other node already holds
+ * that id, which is the case for a flow compile wrote.
+ */
+export function derivedResourceNodeId(agentStep, kind, n) {
+    const base = `${agentStep}${kind}`.replace(/[^A-Za-z0-9_]/g, '_');
+    return n === 0 ? base : `${base}${n + 1}`;
+}
+/** The directory compile derives for a context index (`id` = the index id). */
+export function derivedContextSource(flowId, agentStep, indexId) {
+    return fnv1aX4Uuid(`${flowId}/${agentStep}/context/${indexId}`);
+}
+/**
+ * What tells one tool on an agent from another for its derived directory: the
+ * built-in's name, the connector operation, the IxP project, the client-side or
+ * HTTP tool's name, else the resource key.
+ */
+export function toolResourceSeed(tr) {
+    return tr.kind === 'builtin' ? tr.tool
+        : tr.kind === 'connector' ? `${tr.connector}.${tr.operation}`
+            : tr.kind === 'ixp' ? tr.projectId
+                : tr.kind === 'clientside' ? `clientside.${tr.name}`
+                    : tr.kind === 'httpRequest' ? `httprequest.${tr.name ?? 'default'}`
+                        : tr.key;
+}
+/** The directory compile derives for a tool. */
+export function derivedToolSource(flowId, agentStep, tr) {
+    return fnv1aX4Uuid(`${flowId}/${agentStep}/tool/${toolResourceSeed(tr)}`);
+}
+/** The directory compile derives for an escalation (`name` = the escalation's name). */
+export function derivedEscalationSource(flowId, agentStep, name) {
+    return fnv1aX4Uuid(`${flowId}/${agentStep}/escalation/${name}`);
+}