@uipath/maestro-builder-sdk 6.16.13 → 6.17.0

package/dist/check.js

@@ -7,16 +7,20 @@
  */
 import { Expr, SCHEDULE_PRESETS, DELAY_PRESETS, VARIANT_OPERATION, parseIxpProjectType, flatNameOf, flatNameSegmentsOf, FLAT_SEP } from './flow-sdk.js';
 import { FlowNode } from './core/node-classes.js';
+import { planContributionBindings } from './core/contribution-bindings.js';
+import { resolveContributionDefinition } from './serialize.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
+import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from './core/event-checks.js';
 import { checkCookedEscapes } from './flow-expr-check.js';
 import { FLOW_EXPR_DIALECT, checkBindingLabels, checkBindingPresence, checkConnectorContract as coreCheckConnectorContract, checkConnectorLookups as coreCheckConnectorLookups, checkConnectorSchema as coreCheckConnectorSchema, collectConnectionUses, connectionConnectorConflicts, } from './core/connector-checks.js';
 import { prepareCommand } from './core/cli-spelling.js';
+import { commentText } from './core/comment-text.js';
 import { editDistance } from './core/edit-distance.js';
 import { isAnswerField } from './core/hitl-answers.js';
 import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
 import { declaredExits, hasExits } from './core/step-ports.js';
-import { childStepLists, stopsAtEnd } from './flow-step-tree.js';
+import { stopsAtEnd } from './flow-step-tree.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-variables.js';
@@ -54,9 +58,11 @@ function checkFlow(built, ancestors, opts = {}) {
     if (maybeCustomTrigger !== undefined && !('kind' in maybeCustomTrigger) && maybeCustomTrigger instanceof FlowNode) {
         // A custom FlowTrigger subclass reports through its own diagnostics() hook;
         // the built-in trigger rules key on `kind` and don't apply.
-        for (const d of maybeCustomTrigger.diagnostics()) {
+        const own = maybeCustomTrigger.diagnostics();
+        for (const d of own) {
             diags.push({ level: d.severity, code: d.code, message: d.message, step: 'trigger' });
         }
+        checkContribution(maybeCustomTrigger, built.triggerOptions?.version, 'trigger', own.some((d) => d.severity === 'error'), diags);
     }
     else if (built.trigger !== undefined)
         checkTrigger(built.trigger, diags, opts);
@@ -366,9 +372,11 @@ function checkFlow(built, ancestors, opts = {}) {
                 // don't apply, and it reports through its own diagnostics() hook.
                 const maybeCustom = s.spec;
                 if (!('kind' in maybeCustom) && maybeCustom instanceof FlowNode) {
-                    for (const d of maybeCustom.diagnostics()) {
+                    const own = maybeCustom.diagnostics();
+                    for (const d of own) {
                         diags.push({ level: d.severity, code: d.code, message: d.message, step: s.name });
                     }
+                    checkContribution(maybeCustom, s.options?.version, s.name, own.some((d) => d.severity === 'error'), diags);
                 }
                 if (s.spec.kind === 'transform')
                     checkTransform(s.name, s.spec.inputs, diags, typeOf, triggerId);
@@ -864,9 +872,11 @@ function checkFlow(built, ancestors, opts = {}) {
         epIds.add(ep.id);
         const maybeCustomEp = ep.trigger;
         if (!('kind' in maybeCustomEp) && maybeCustomEp instanceof FlowNode) {
-            for (const d of maybeCustomEp.diagnostics()) {
+            const own = maybeCustomEp.diagnostics();
+            for (const d of own) {
                 diags.push({ level: d.severity, code: d.code, message: d.message, step: ep.id });
             }
+            checkContribution(maybeCustomEp, ep.options?.version, ep.id, own.some((d) => d.severity === 'error'), diags);
         }
         else {
             checkTrigger(ep.trigger, diags, opts, ep.id);
@@ -1283,13 +1293,10 @@ function checkFlow(built, ancestors, opts = {}) {
             }
         }
     }
-    // Walk for a `.return()` rather than stringifying the step tree: a subflow
-    // step carries a whole child flow, so the tree can be cyclic (a flow that
-    // runs itself — SUBFLOW_CYCLE) and always contains the CHILD's returns, which
-    // say nothing about whether THIS flow terminates.
-    const hasTerminal = hasReturn(built.steps);
-    if (!hasTerminal)
-        diags.push({ level: 'warning', code: 'NO_RETURN', message: 'Flow has no return(); a default End node will be appended.' });
+    // The End compile appends when the root path runs out of steps (#941).
+    const fallOff = checkFallOffEnd(built);
+    if (fallOff)
+        diags.push(fallOff);
     // Check every child flow with the same rules, in its OWN scope — a child's
     // steps never see the parent's variables, so its undeclared references,
     // duplicate step names and type mismatches are its own. Diagnostics come back
@@ -1376,9 +1383,124 @@ function checkLoopListEnvelope(loop, connectors, opts, diags) {
         suggestion,
     });
 }
-/** True if any step on THIS flow's own tree is a `.return()`. */
-function hasReturn(steps) {
-    return steps.some((s) => s.kind === 'return' || childStepLists(s).some(hasReturn));
+/**
+ * NO_RETURN: a path that runs off the end of the flow, where a declared output
+ * is never written (#941).
+ *
+ * It asks serialize's question, not "is there a `.return()` anywhere?".
+ * serialize appends an End exactly when the root walk has tails left
+ * (`if (finalTails.length)`), and `armTails` mirrors that walk tail for tail.
+ * So a `.terminate()` path appends no End, and a branch where one arm returns
+ * and the other falls off DOES append one.
+ *
+ * The appended End maps every output from its own variable
+ * (`result <- $vars.result`), the same as a `.return()` that names no value.
+ * That loses nothing when the flow declares no outputs, or when each output
+ * was set on the way: by a `default`, a `{ shared }` input that every root
+ * feeds, or `{ updates }` on a step of that path. The warning names the outputs
+ * that are not, and the steps the path falls off from.
+ *
+ * Not covered: the private End a `.stepToList` body gets (#742). `armTails`
+ * skips those bodies, and that End is a different emission site with no
+ * output mappings at all.
+ */
+function checkFallOffEnd(built) {
+    if (built.outputs.length === 0)
+        return undefined;
+    const from = built.triggerId ?? 'start';
+    if (armTails(built.steps, [{ from }]).length === 0)
+        return undefined;
+    const preset = new Set(built.outputs.filter((o) => o.default !== undefined).map((o) => o.name));
+    // A shared input sets its variable only on runs that enter through a root
+    // feeding it, so it counts as preset only when every root does.
+    const roots = sharedInputRoots(built);
+    for (const t of planSharedInputs({ roots, outputs: built.outputs, vars: built.vars }).targets) {
+        if (t.declaredAs === 'output' && roots.every((r) => t.feeds.some((f) => f.root === r.id)))
+            preset.add(t.name);
+    }
+    const tails = writtenTails(built.steps, [{ from, written: preset }], []);
+    const missing = built.outputs.map((o) => o.name).filter((n) => tails.some((t) => !t.written.has(n)));
+    if (missing.length === 0)
+        return undefined;
+    const steps = [...new Set(tails.filter((t) => missing.some((n) => !t.written.has(n))).map((t) => t.from))];
+    const one = missing.length === 1;
+    return {
+        level: 'warning',
+        code: 'NO_RETURN',
+        message: `Path ending at ${steps.map((x) => `"${x}"`).join(', ')} falls into the End compile appends. `
+            + `${one ? 'Output' : 'Outputs'} ${missing.map((n) => `"${n}"`).join(', ')} may be unset there. `
+            + `End the path with .return({ … }) or set ${one ? 'it' : 'them'} with { updates } (a loop body may run zero times).`,
+        step: steps[0],
+        suggestion: `.return({ ${missing.map((n) => `${n}: …`).join(', ')} })`,
+    };
+}
+/**
+ * `armTails`, step for step, carrying what each path has surely written. A
+ * `.return()` value is NOT a write here: it lives on that `.return()`'s End,
+ * which is not the End this is about. Where paths meet, only what all of them
+ * wrote counts.
+ *
+ * A `.break()` leaves the enclosing loop with what its path wrote so far, so
+ * its tail goes to `breaks`, and the loop counts it as one of the ways out. A
+ * loop body may run zero times, so it writes nothing for sure. A do-while body
+ * runs at least once, and is left by its end or by a `.break()`, so what all of
+ * those wrote counts. Every `.parallel` arm runs, so what each surely writes
+ * counts.
+ */
+function writtenTails(steps, incoming, breaks) {
+    let tails = incoming;
+    for (const st of steps) {
+        if (st.kind === 'stepToList')
+            continue;
+        if (st.kind === 'stepToRef') {
+            if (st.port === 'output')
+                tails = [];
+            continue;
+        }
+        if (st.kind === 'break') {
+            breaks.push(...tails);
+            return [];
+        }
+        if (st.kind === 'return' || st.kind === 'terminate')
+            return [];
+        const before = surelyWritten(tails);
+        const written = new Set([...before, ...Object.keys(st.options?.updates ?? {})]);
+        const arm = (body) => writtenTails(body, [{ from: st.name, written }], breaks);
+        if (st.kind === 'action') {
+            tails = actionTails(st.name, st.spec, st.options?.version)
+                .map((t) => ({ from: t.from, written }));
+        }
+        else if (st.kind === 'stepSwitch') {
+            tails = st.cases.flatMap((c) => arm(c.body));
+        }
+        else if (st.kind === 'branch') {
+            tails = [...arm(st.then), ...arm(st.otherwise)];
+        }
+        else if (st.kind === 'switch') {
+            tails = [...st.cases.flatMap((c) => arm(c.body)), ...(st.default !== undefined ? arm(st.default) : [])];
+        }
+        else if (st.kind === 'doWhile') {
+            const exits = [];
+            exits.push(...writtenTails(st.body, [{ from: st.name, written }], exits));
+            surelyWritten(exits).forEach((n) => written.add(n));
+            tails = [{ from: st.name, written }];
+        }
+        else if (st.kind === 'parallel') {
+            for (const body of st.arms)
+                surelyWritten(arm(body)).forEach((n) => written.add(n));
+            tails = [{ from: st.name, written }];
+        }
+        else {
+            tails = [{ from: st.name, written }];
+        }
+    }
+    return tails;
+}
+/** What every one of `tails` has written; nothing when there are none. */
+function surelyWritten(tails) {
+    if (tails.length === 0)
+        return new Set();
+    return new Set([...tails[0].written].filter((n) => tails.every((t) => t.written.has(n))));
 }
 /**
  * Closest of `candidates` to `name`: same word ignoring case, one contained in
@@ -1982,10 +2104,11 @@ function renamedFieldMessage(label, step, oldField) {
  *  - a `key` that is not a GUID. The commonest form of this is passing the
  *    process's NAME where its release key belongs, which produces a node type
  *    the platform cannot resolve to anything.
- *  - a `folderPath` that looks like a name, or a `name` that looks like a path —
- *    the two are swappable by shape and the resulting `resourceKey` is wrong in a
- *    way that only surfaces as a 400 from Orchestrator ("Folder does not exist").
- *    That is v1's own 2026-06-26 failure mode on this task.
+ *  - a `name` that looks like a path (contains "/"). The two are swappable, and
+ *    the resulting `resourceKey` is wrong in a way that only surfaces as a 400
+ *    from Orchestrator ("Folder does not exist"). That is v1's own 2026-06-26
+ *    failure mode on this task. A single-segment `folderPath` is NOT decidable:
+ *    root folders and personal workspaces are one segment, so it is not flagged.
  */
 function checkRpaWorkflow(step, inputs, diags) {
     const at = (code, message, suggestion) => {
@@ -2009,33 +2132,33 @@ function checkRpaWorkflow(step, inputs, diags) {
         at('RPA_NO_NAME', `RPA step "${step}" has no \`name\`. The runtime starts the job by name + folder, not by the key in `
             + `the node type, so without it the process cannot be resolved and the run fails before dispatch.`, `name: 'RPA Workflow'`);
     }
-    if (blank(inputs?.folderPath)) {
+    const inSolution = inputs?.location === 'in-solution';
+    if (!inSolution && blank(inputs?.folderPath)) {
         at('RPA_NO_FOLDER', `RPA step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so the `
             + `Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-maestro-flow/ProjectEuler RPA'`);
     }
+    if (inSolution && blank(inputs?.projectId)) {
+        at('RPA_LOCAL_NO_PROJECT_ID', `In-solution RPA step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/process/<project>.json\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('RPA_LOCAL_PROJECT_ID_NOT_GUID', `In-solution RPA step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
+    }
+    if (inSolution && !blank(inputs?.folderPath)) {
+        at('RPA_LOCAL_HAS_FOLDER', `In-solution RPA step "${step}" also sets \`folderPath\` ${JSON.stringify(inputs.folderPath)}. An `
+            + `in-solution sibling has no folder until the solution is deployed — the platform's own manifest `
+            + `writes \`""\` — so the value would be dropped. Remove it, or drop \`location: 'in-solution'\` to `
+            + `call the published copy.`);
+    }
     // The two are swappable by shape, and swapping them is invisible until
     // Orchestrator answers "Folder does not exist or the user does not have access".
     const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
-    const folder = typeof inputs?.folderPath === 'string' ? inputs.folderPath.trim() : '';
     if (name.includes('/')) {
         at('RPA_NAME_IS_PATH', `RPA step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. \`name\` is `
             + `the process's own name in Orchestrator; the path it lives in goes in \`folderPath\`. Together they `
             + `form the resourceKey "<folderPath>.<name>", so swapping them points the job at nothing.`);
     }
-    if (folder && !folder.includes('/') && name && !name.includes('/')) {
-        // A single-segment folder is legal ("Shared"), so this is only worth saying
-        // when the folder ALSO fails to look like one of the tenant's roots.
-        if (!/^(Shared|Personal|My Workspace)$/i.test(folder)) {
-            diags.push({
-                level: 'warning',
-                code: 'RPA_FOLDER_NOT_PATH',
-                message: `RPA step "${step}"'s \`folderPath\` is ${JSON.stringify(inputs.folderPath)} — a single segment with no `
-                    + `"/". Orchestrator folder paths are usually nested (e.g. "Shared/<team>/<solution>"). If this is `
-                    + `the process's name rather than its folder, the two arguments are swapped.`,
-                step,
-            });
-        }
-    }
 }
 /**
  * Check an `apiWorkflow(...)` call.
@@ -2636,10 +2759,33 @@ function checkAgenticProcess(step, inputs, diags) {
             + `the key in the node type, so without it the process cannot be resolved and the run fails before `
             + `dispatch.`, `name: 'ProcurementProcess'`);
     }
-    if (blank(inputs?.folderPath)) {
+    const inSolution = inputs?.location === 'in-solution';
+    if (!inSolution && blank(inputs?.folderPath)) {
         at('AGENTIC_NO_FOLDER', `Agentic process step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so `
             + `the Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-agents/ProcurementProcess'`);
     }
+    const form = inputs?.form ?? 'bpmn';
+    if (inSolution && form !== 'flow') {
+        at('AGENTIC_LOCAL_FORM_UNVERIFIED', `In-solution agentic process step "${step}" has \`form: ${JSON.stringify(form)}\`. Only \`form: 'flow'\` `
+            + `has been run against an in-solution sibling; the ${JSON.stringify(form)} shape is unproven. Call the `
+            + `published process instead (drop \`location\` and \`projectId\`, set \`folderPath\`), or use `
+            + `\`form: 'flow'\` if the sibling is a Flow.`, `location: 'published', folderPath: 'Shared/<folder>'`);
+    }
+    if (inSolution && blank(inputs?.projectId)) {
+        const folder = (AGENTIC_PROCESS_FORMS[inputs?.form ?? 'bpmn'] ?? AGENTIC_PROCESS_FORMS.bpmn).solutionFolder;
+        at('AGENTIC_LOCAL_NO_PROJECT_ID', `In-solution agentic process step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/${folder}/<project>.json\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('AGENTIC_LOCAL_PROJECT_ID_NOT_GUID', `In-solution agentic process step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
+    }
+    if (inSolution && !blank(inputs?.folderPath)) {
+        at('AGENTIC_LOCAL_HAS_FOLDER', `In-solution agentic process step "${step}" also sets \`folderPath\` ${JSON.stringify(inputs.folderPath)}. An `
+            + `in-solution sibling has no folder until the solution is deployed — the platform's own manifest `
+            + `writes \`""\` — so the value would be dropped. Remove it, or drop \`location: 'in-solution'\` to `
+            + `call the published copy.`);
+    }
     const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
     if (name.includes('/')) {
         at('AGENTIC_NAME_IS_PATH', `Agentic process step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. `
@@ -3642,7 +3788,7 @@ function checkQueueItem(step, inputs, diags) {
                     + `Orchestrator rejects a queue item whose property values are not simple: `
                     + `"Property values must be simple (like numbers or text) and not complex or composite `
                     + `data types (like objects or arrays)". Flatten it, or JSON-encode it into one string `
-                    + `field.`, `item: { ${k}: JSON.stringify(...) }  // or ${k}Id, ${k}Name, …`);
+                    + `field.`, `item: { ${k}: JSON.stringify(...) }  // or ${commentText(k)}Id, ${commentText(k)}Name, …`);
             }
         }
     }
@@ -3933,7 +4079,7 @@ function fanInDiag(join, arm, steps, tails) {
             + `edge, so the run never gets past "${join}" — with no incident, and \`flow validate\` answers Valid. Add a `
             + `step at the end of the arm${last?.name ? `, after "${last.name}"` : ''}, so the paths meet on that step and `
             + `only its one edge reaches the join, or move human task "${task}" out of the \`.parallel(…)\`.`,
-        suggestion: `….step('record', …)  // last step of arm ${arm + 1}`,
+        suggestion: `….step('record', …)  // last step of arm ${commentText(arm + 1)}`,
     };
 }
 /**
@@ -5623,3 +5769,39 @@ function checkSchemaVersion(built, ancestors, diags) {
         });
     }
 }
+/**
+ * Run a custom node's contribution lowering DRY, so `check` reports what
+ * `compile` would throw. For instance, a `rawNode` carrying an in-solution
+ * sibling's manifest with no `values` row for `<bindings.folderPath>` fails here
+ * with the same code compile throws.
+ *
+ * It calls `contribute()`, resolves the definition the way serialize does, and
+ * plans the `bindings[]` entries serialize would build
+ * ({@link planContributionBindings}). A name the plan cannot close is
+ * `CONTRIBUTION_BINDING_UNRESOLVED` — the same code and sentence serialize
+ * throws. A contribution that throws is `CONTRIBUTION_INVALID`, unless
+ * `ownError` says the node's own `diagnostics()` already reported an error (a
+ * raw connector node throws for the reason `RAW_NODE_CONNECTOR` already gives).
+ */
+function checkContribution(node, requestedVersion, step, ownError, diags) {
+    let def;
+    let supplied;
+    try {
+        const contribution = node.contribute(requestedVersion !== undefined ? { requestedVersion } : {});
+        def = resolveContributionDefinition(contribution.definition, requestedVersion, `step "${step}"`);
+        supplied = contribution.bindings;
+    }
+    catch (e) {
+        if (ownError)
+            return;
+        diags.push({
+            level: 'error', code: 'CONTRIBUTION_INVALID', step,
+            message: `compile cannot lower step "${step}": ${e instanceof Error ? e.message : String(e)}`,
+        });
+        return;
+    }
+    const plan = planContributionBindings(def, supplied);
+    if (plan.problems.length === 0)
+        return;
+    diags.push({ level: 'error', code: 'CONTRIBUTION_BINDING_UNRESOLVED', step, message: plan.problems.join(' ') });
+}

package/dist/cli-result.d.ts

@@ -34,3 +34,12 @@ export declare function reportDiagnostics(diags: ReadonlyArray<{
     message: string;
     suggestion?: string;
 }>): void;
+/**
+ * The error diagnostic for a throw that ends a compile: the error's own string
+ * `code` when it carries one, else `COMPILE_FAILED`.
+ */
+export declare function thrownDiagnostic(error: unknown): {
+    level: 'error';
+    code: string;
+    message: string;
+};

package/dist/cli-result.js

@@ -47,3 +47,15 @@ export function reportDiagnostics(diags) {
         diagnostics: diags.map((d) => ({ level: d.level, code: d.code, message: d.message, ...(d.suggestion ? { suggestion: d.suggestion } : {}) })),
     });
 }
+/**
+ * The error diagnostic for a throw that ends a compile: the error's own string
+ * `code` when it carries one, else `COMPILE_FAILED`.
+ */
+export function thrownDiagnostic(error) {
+    const code = error?.code;
+    return {
+        level: 'error',
+        code: typeof code === 'string' && code.length > 0 ? code : 'COMPILE_FAILED',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}

package/dist/compile-cli.js

@@ -17,8 +17,9 @@
  * product's own gates are supposed to answer. `.build()` still throws on
  * structural problems; only the diagnostic pass is skipped.
  */
-import { reportDiagnostics, reportResult } from './cli-result.js';
-import { writeFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { reportDiagnostics, reportResult, thrownDiagnostic } from './cli-result.js';
+import { writeJsonFile } from './core/json-file.js';
+import { 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, compileOwnsResource } from './serialize.js';
@@ -26,9 +27,10 @@ import { check } from './check.js';
 import { byoaCheckOpts, eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
-import { connectionResources, mergeBindingsV2, readBindingsV2 } from './bindings-v2.js';
+import { connectionResources, inlineAgentResources, mergeBindingsV2, mergeInlineAgentResources, readBindingsV2, readInlineAgentFiles, } from './bindings-v2.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { defaultBindingsFile } from './workdir.js';
+import { isWithin } from './path-within.js';
 import { BindingRefusal } from './core/binding-messages.js';
 import { ByoaRefusal } from './core/byoa.js';
 export async function run(argv) {
@@ -65,6 +67,8 @@ export async function run(argv) {
     const library = openCliLibrary(argv);
     const bindFile = flagValue(argv, '--bindings') ?? defaultBindingsFile();
     const bindings = new Bindings(bindFile);
+    // One list per run; every exit path reports it (reportResult overwrites keys).
+    const diagnostics = [];
     if (!noCheck) {
         const diags = check(built, library
             ? {
@@ -100,8 +104,9 @@ export async function run(argv) {
         const errors = diags.filter((d) => d.level === 'error');
         for (const d of diags)
             console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
+        diagnostics.push(...diags);
         if (errors.length) {
-            reportDiagnostics(diags);
+            reportDiagnostics(diagnostics);
             console.error(`compile: ${errors.length} error(s); not emitting.`);
             return 1;
         }
@@ -121,28 +126,27 @@ export async function run(argv) {
         emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w) });
     }
     catch (error) {
-        if (!(error instanceof BindingRefusal || error instanceof ByoaRefusal))
-            throw error;
         for (const w of warnings)
             console.error(`  ⚠ [${w.code}] ${w.message}`);
+        diagnostics.push(...warnings.map(serializeWarningDiagnostic));
+        if (!(error instanceof BindingRefusal || error instanceof ByoaRefusal)) {
+            // Any other throw still ends the run through the caller (exit 1, `--json`
+            // `error`); the list is reported first.
+            diagnostics.push(thrownDiagnostic(error));
+            reportDiagnostics(diagnostics);
+            throw error;
+        }
         console.error(`  ✗ [${error.code}] ${error.message}`);
-        reportDiagnostics([
-            ...warnings.map((w) => ({ level: 'warning', code: w.code, message: w.message })),
-            { level: 'error', code: error.code, message: error.message },
-        ]);
+        diagnostics.push({ level: 'error', code: error.code, message: error.message });
+        reportDiagnostics(diagnostics);
         console.error('compile: 1 error(s); not emitting.');
         return 1;
     }
     const { flow: flowJson, sidecars } = emitted;
     for (const w of warnings)
         console.error(`  ⚠ [${w.code}] ${w.message}`);
+    diagnostics.push(...warnings.map(serializeWarningDiagnostic));
     const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
-    writeFileSync(out, JSON.stringify(flowJson, null, 2) + '\n');
-    console.log(`compile: wrote ${out} (${flowJson.nodes.length} nodes, ${flowJson.edges.length} edges)`);
-    const written = [];
-    reportResult({ path: resolve(out), nodes: flowJson.nodes.length, edges: flowJson.edges.length, sidecars: written });
-    // Same keys and types as a failed compile: `warnings` a count, `diagnostics` the list.
-    reportDiagnostics(warnings.map((w) => ({ level: 'warning', code: w.code, message: w.message })));
     // An inline agent is TWO artifacts: the node, and the agent's own configuration
     // at `<source>/agent.json` — which is where flow-v1's serializer points the
     // runtime (`entryPoint: "<source>/agent.json"`, resolved relative to the
@@ -151,19 +155,31 @@ export async function run(argv) {
     // Sidecar paths are relative to the emitted flow, and are confined to its
     // directory: a `..` or absolute path in one would be a bug here, not author
     // input, but it is cheap to refuse rather than write outside the project.
+    //
+    // Every sidecar is checked before anything is written; success is reported
+    // only once every file is on disk.
     const outDir = dirname(resolve(out));
-    for (const s of sidecars) {
-        const target = resolve(outDir, s.path);
-        if (target !== outDir && !target.startsWith(outDir + '/')) {
-            console.error(`compile: refusing to write a sidecar outside the flow's directory: ${s.path}`);
-            reportResult({ error: `refusing to write a sidecar outside the flow's directory: ${s.path}` });
-            return 1;
-        }
+    const targets = sidecars.map((s) => ({ sidecar: s, target: resolve(outDir, s.path) }));
+    const escaping = targets.find(({ target }) => target === outDir || !isWithin(outDir, target));
+    if (escaping) {
+        const message = `refusing to write a sidecar outside the flow's directory: ${escaping.sidecar.path}`;
+        console.error(`compile: ${message}; not emitting.`);
+        diagnostics.push({ level: 'error', code: 'SIDECAR_OUTSIDE_FLOW_DIR', message });
+        reportDiagnostics(diagnostics);
+        return 1;
+    }
+    // Reported before the first write, so a write that throws still carries it.
+    reportDiagnostics(diagnostics);
+    writeJsonFile(out, flowJson);
+    console.log(`compile: wrote ${out} (${flowJson.nodes.length} nodes, ${flowJson.edges.length} edges)`);
+    const written = [];
+    for (const { sidecar, target } of targets) {
         mkdirSync(dirname(target), { recursive: true });
-        writeFileSync(target, JSON.stringify(s.json, null, 2) + '\n');
-        console.log(`compile: wrote ${s.path}`);
+        writeJsonFile(target, sidecar.json);
+        console.log(`compile: wrote ${sidecar.path}`);
         written.push(target);
     }
+    reportResult({ path: resolve(out), nodes: flowJson.nodes.length, edges: flowJson.edges.length, sidecars: written });
     // 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
@@ -180,13 +196,14 @@ export async function run(argv) {
     // families the SDK cannot into the same directory (including `internal`
     // built-ins such as `load-attachments`), so anything else found there is
     // someone else's and is left alone.
-    const staleBindings = [];
+    const removedResources = [];
     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 agentDirs = [...new Set(sidecars
+            .filter((s) => s.path.endsWith('/agent.json'))
+            .map((s) => dirname(resolve(outDir, s.path))))];
+    for (const agentDir of agentDirs) {
         const resourcesDir = join(agentDir, 'resources');
         if (!existsSync(resourcesDir))
             continue;
@@ -203,23 +220,7 @@ export async function run(argv) {
             }
             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;
-            // A connector tool's binding is a `connection` row, and `mergeBindingsV2`
-            // re-derives every connection row from the flow below — nothing to retract.
-            // A built-in (`internal`) tool binds nothing at all: retracting a `process`
-            // row under its label could only remove a real process tool's binding.
-            if (key !== undefined && body?.type !== 'integration' && body?.type !== 'internal') {
-                // 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 });
-            }
+            removedResources.push(body);
             rmSync(join(resourcesDir, entry), { recursive: true, force: true });
             console.log(`compile: removed stale ${join('resources', entry, 'resource.json')}`);
         }
@@ -235,20 +236,44 @@ export async function run(argv) {
         const sidecarPath = join(outDir, 'bindings_v2.json');
         const connections = connectionResources(flowJson);
         const existing = readBindingsV2(sidecarPath);
+        // Each inline agent's own rows (process, index, app, … — #962), derived from
+        // the agent directory as it now stands on disk, the way `uip agent refresh
+        // --inline-in-flow` derives them. `uip agent validate --inline-in-flow`
+        // requires every one of them, so leaving them to a refresh the SDK route
+        // never runs made every agent with a deployed-resource tool, a context index
+        // or an app escalation fail validate with `AgentValidationDrift`.
+        const agentRows = agentDirs
+            .map((dir) => readInlineAgentFiles(dir))
+            .filter((files) => files !== undefined)
+            .map((files) => inlineAgentResources(files));
+        // The rows a PRUNED resource declared go with it: refresh never retracts a
+        // row, so an index the flow dropped would stay declared and a deploy could
+        // still fail on it. Generated by the same function, so they match exactly,
+        // and kept when a resource that still exists declares the same row.
+        // Connection rows are skipped: every one is re-derived from the flow below.
+        const live = new Set(agentRows.flat().map((r) => `${r.resource}\u0000${r.key}`));
+        const stale = new Set(inlineAgentResources({ agent: {}, resources: removedResources, features: [] })
+            .filter((r) => r.resource !== 'connection' && !live.has(`${r.resource}\u0000${r.key}`))
+            .map((r) => `${r.resource}\u0000${r.key}`));
         // Nothing to declare and nothing already declared — do not create an empty
         // file for a flow that has no resources at all.
-        if (connections.length > 0 || existing !== undefined) {
+        if (connections.length > 0 || existing !== undefined || agentRows.some((rows) => rows.length > 0)) {
             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;
+            merged.resources = merged.resources.filter((r) => !stale.has(`${r.resource}\u0000${r.key}`));
+            for (const rows of agentRows)
+                merged.resources = mergeInlineAgentResources(merged.resources, rows);
+            writeJsonFile(sidecarPath, merged);
+            const derived = new Set([...connections, ...agentRows.flat()].map((r) => `${r.resource}\u0000${r.key}`));
+            const agentCount = merged.resources.filter((r) => r.resource !== 'connection' && derived.has(`${r.resource}\u0000${r.key}`)).length;
+            const kept = merged.resources.filter((r) => !derived.has(`${r.resource}\u0000${r.key}`)).length;
             console.log(`compile: wrote bindings_v2.json (${connections.length} connection resource(s)`
+                + `${agentCount > 0 ? `, ${agentCount} inline-agent resource(s)` : ''}`
                 + `${kept > 0 ? `, ${kept} other resource(s) preserved` : ''})`);
         }
     }
     return 0;
 }
+function serializeWarningDiagnostic(w) {
+    return { level: 'warning', code: w.code, message: w.message };
+}
 runWhenInvokedDirectly(import.meta.url, 'compile', run);