@uipath/maestro-builder-sdk 6.16.13 → 6.17.0

package/dist/serialize.js

@@ -14,6 +14,7 @@ import { Expr, toExpr, SCHEDULE_PRESETS, DELAY_PRESETS, parseIxpProjectType, fla
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { dataFabricUnknownInputs } from './core/typed-raw-node.js';
+import { planContributionBindings } from './core/contribution-bindings.js';
 import { isAnswerField } from './core/hitl-answers.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingMissingMessage, bindingSelfNameMessage, bindingUndeclaredMessage, missingBindingLabels, undeclaredBinding } from './core/binding-messages.js';
@@ -49,6 +50,8 @@ import { resolveSchemaVersion } from './schema-version.js';
 import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-variables.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
+import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
+import { types } from './core/expr.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 // core-definitions.json is an object keyed by "<nodeType>@<version>".
 const DEFS = JSON.parse(readFileSync(join(HERE, 'core-definitions.json'), 'utf8'));
@@ -143,6 +146,53 @@ const SUBFLOW_OUTPUT = {
 };
 /** The RPA-workflow node type family. The process's release key is the suffix. */
 const RPA_WORKFLOW_PREFIX = 'uipath.core.rpa-workflow.';
+/**
+ * Where a process resource lives, as ONE slot every process-resource definition
+ * shares. In the platform model "in this solution" is orthogonal to the
+ * resource type: flow-core's single `createModel` (`@uipath/flow-core`
+ * `manifest/mappers/node-manifest-builder.ts`, what `uip maestro flow registry
+ * get --local` and Studio Web both run) adds `projectId`, `projectName` and
+ * `isInSolution: true` to the model of ANY process resource built from a sibling
+ * project.
+ *
+ * The in-solution shape, transcribed from `registry get --local` for a sibling
+ * Flow (2026-10-08) and from uipath-cli's `buildInSolutionNodeManifests`:
+ *  - `resourceKey` is the bare key (the sibling's `resource.key`), not
+ *    `<folderPath>.<name>`; the folder default is `''`;
+ *  - no `section: 'Published'`;
+ *  - `projectId` on the definition AND on the model, with `projectName` and
+ *    `isInSolution: true` (the marker the canvas reads);
+ *  - description `(In-solution) <name>`, tags `in-solution` / `local`, and the
+ *    `open-workflow` toolbar action.
+ */
+function processResourceLocation(spec) {
+    if (spec.location === 'in-solution') {
+        return {
+            inSolution: true,
+            folderPath: '',
+            resourceKey: spec.key,
+            description: `(In-solution) ${spec.name}`,
+            tags: ['in-solution', 'local'],
+            definitionExtras: {
+                toolbarExtensions: {
+                    design: { actions: [{ id: 'open-workflow', icon: 'external-link', label: 'Open' }] },
+                },
+                projectId: spec.projectId,
+            },
+            modelExtras: { projectId: spec.projectId, projectName: spec.name, isInSolution: true },
+        };
+    }
+    const folderPath = spec.folderPath ?? '';
+    return {
+        inSolution: false,
+        folderPath,
+        resourceKey: `${folderPath}.${spec.name}`,
+        description: `(${folderPath})`,
+        tags: [],
+        definitionExtras: {},
+        modelExtras: {},
+    };
+}
 /**
  * Build the definition for one deployed RPA process.
  *
@@ -177,7 +227,8 @@ const RPA_WORKFLOW_PREFIX = 'uipath.core.rpa-workflow.';
  *    element while publishing a null step output.
  */
 function rpaWorkflowDef(spec) {
-    const resourceKey = `${spec.folderPath}.${spec.name}`;
+    const loc = processResourceLocation(spec);
+    const { resourceKey } = loc;
     const properties = {};
     for (const [k, v] of Object.entries(spec.inputs)) {
         properties[k] = { type: typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : 'string' };
@@ -187,8 +238,8 @@ function rpaWorkflowDef(spec) {
         version: '1.0.0',
         category: 'rpa-workflow',
         runtimeConstraints: { exclude: ['api-function'] },
-        description: `(${spec.folderPath})`,
-        tags: [],
+        description: loc.description,
+        tags: loc.tags,
         sortOrder: 530,
         supportsErrorHandling: true,
         display: { label: spec.name, icon: 'rpa' },
@@ -196,11 +247,12 @@ function rpaWorkflowDef(spec) {
             { position: 'left', handles: [{ id: 'input', type: 'target', handleType: 'input' }] },
             { position: 'right', handles: [{ id: 'output', type: 'source', handleType: 'output' }] },
         ],
+        ...loc.definitionExtras,
         model: {
             type: 'bpmn:ServiceTask',
             serviceType: 'Orchestrator.StartJob',
             version: 'v2',
-            section: 'Published',
+            ...(loc.inSolution ? {} : { section: 'Published' }),
             bindings: {
                 resource: 'process',
                 resourceSubType: 'Process',
@@ -208,9 +260,10 @@ function rpaWorkflowDef(spec) {
                 orchestratorType: 'process',
                 values: [
                     { name: 'name', propertyAttribute: 'name', default: spec.name },
-                    { name: 'folderPath', propertyAttribute: 'folderPath', default: spec.folderPath },
+                    { name: 'folderPath', propertyAttribute: 'folderPath', default: loc.folderPath },
                 ],
             },
+            ...loc.modelExtras,
             context: [
                 { name: 'name', type: 'string', value: '<bindings.name>' },
                 { name: 'folderPath', type: 'string', value: '<bindings.folderPath>' },
@@ -453,41 +506,6 @@ function publishedFunctionDef(spec) {
         debug: { runtime: 'bpmnEngine' },
     };
 }
-const AGENTIC_PROCESS_PREFIX = 'uipath.core.agentic-process.';
-/**
- * The three published forms under the Agentic Process umbrella (design §2.1).
- * One public factory, three wire identities — transcribed from flow-v1's
- * `RESOURCE_TYPE_METADATA` (ProcessOrchestration / Flow / CaseManagement):
- * node-type segment, category, icon, resource subtype, `orchestratorType`
- * (`resourceType.toLowerCase()`, per `createModel`), and the sync/async
- * service-type pair. All three declare the fire-and-forget switch.
- */
-const AGENTIC_PROCESS_FORMS = {
-    bpmn: {
-        prefix: AGENTIC_PROCESS_PREFIX,
-        category: 'agentic-process',
-        icon: 'agentic-process',
-        resourceSubType: 'ProcessOrchestration',
-        orchestratorType: 'processorchestration',
-        serviceType: 'Orchestrator.StartAgenticProcess',
-    },
-    flow: {
-        prefix: 'uipath.core.flow.',
-        category: 'flow',
-        icon: 'flow-project',
-        resourceSubType: 'Flow',
-        orchestratorType: 'flow',
-        serviceType: 'Orchestrator.StartFlowProcess',
-    },
-    case: {
-        prefix: 'uipath.core.case-management.',
-        category: 'case-management',
-        icon: 'case-management',
-        resourceSubType: 'CaseManagement',
-        orchestratorType: 'casemanagement',
-        serviceType: 'Orchestrator.StartCaseMgmtProcess',
-    },
-};
 /**
  * Build the definition for one deployed agentic process (a Maestro process
  * orchestration).
@@ -529,7 +547,8 @@ const AGENTIC_PROCESS_FORMS = {
  */
 function agenticProcessDef(spec) {
     const form = AGENTIC_PROCESS_FORMS[spec.form ?? 'bpmn'];
-    const resourceKey = `${spec.folderPath}.${spec.name}`;
+    const loc = processResourceLocation(spec);
+    const { resourceKey } = loc;
     const properties = {};
     for (const [k, v] of Object.entries(spec.inputs)) {
         properties[k] = { type: typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : 'string' };
@@ -539,8 +558,8 @@ function agenticProcessDef(spec) {
         version: '1.0.0',
         category: form.category,
         runtimeConstraints: { exclude: ['api-function'] },
-        description: `(${spec.folderPath})`,
-        tags: [],
+        description: loc.description,
+        tags: loc.tags,
         sortOrder: 507,
         supportsErrorHandling: true,
         display: { label: spec.name, icon: form.icon },
@@ -548,11 +567,12 @@ function agenticProcessDef(spec) {
             { position: 'left', handles: [{ id: 'input', type: 'target', handleType: 'input' }] },
             { position: 'right', handles: [{ id: 'output', type: 'source', handleType: 'output' }] },
         ],
+        ...loc.definitionExtras,
         model: {
             type: 'bpmn:ServiceTask',
             serviceType: form.serviceType,
             version: 'v2',
-            section: 'Published',
+            ...(loc.inSolution ? {} : { section: 'Published' }),
             bindings: {
                 resource: 'process',
                 resourceSubType: form.resourceSubType,
@@ -560,9 +580,10 @@ function agenticProcessDef(spec) {
                 orchestratorType: form.orchestratorType,
                 values: [
                     { name: 'name', propertyAttribute: 'name', default: spec.name },
-                    { name: 'folderPath', propertyAttribute: 'folderPath', default: spec.folderPath },
+                    { name: 'folderPath', propertyAttribute: 'folderPath', default: loc.folderPath },
                 ],
             },
+            ...loc.modelExtras,
             context: [
                 { name: 'name', type: 'string', value: '<bindings.name>' },
                 { name: 'folderPath', type: 'string', value: '<bindings.folderPath>' },
@@ -741,28 +762,6 @@ function agentDef(spec) {
         debug: { runtime: 'bpmnEngine' },
     };
 }
-/**
- * Build the definition for the INLINE autonomous agent.
- *
- * This is the one node type in the agent family that is the SAME on every tenant —
- * it carries its own configuration instead of referencing a resource — so
- * `uip maestro flow registry get uipath.agent.autonomous` is a direct oracle rather
- * than a per-instance answer, and the def can be built from constants without a
- * corpus vote. Transcribed 2026-07-29: `version: '1.2'`, `sortOrder: 5`,
- * `supportsErrorHandling: true`, `model.source: true`,
- * `Orchestrator.StartInlineAgentJob`, the three required inputs, the artifact
- * handles (escalation / context / tool) and `success` + `error` on the right with
- * `isDefaultForType` on `success`.
- *
- * The deployed corpus (29 `uipath.agent.autonomous` nodes, 05-18 → 07-29) agrees on
- * everything a `.flow` carries and settles the one thing the def leaves open:
- * `outputs.output.source` is `=result.response` in 27 of 27 that declare outputs —
- * unanimous here, unlike the published family, because the platform's
- * append-`=this` fallback only fires for a node that declares no `output` at all.
- * `typeVersion` in that corpus is 1.1 ×10, 1.2 ×15, 1.3 ×4; we emit the registry's
- * 1.2. (`shared/sample-flows/inline-agent.flow` says 1.0, which appears in **none**
- * of the 29 — the same bundled-sample era gap as the published family's.)
- */
 /**
  * The definition for ONE Context Grounding index resource, transcribed from the
  * platform's own registry entry (`uip maestro flow registry get
@@ -984,6 +983,45 @@ const CONNECTOR_TOOL_RESOURCE_TYPE = 'integration';
  * on its own it says nothing about who owns a file: `properties.toolType` does.
  */
 const INTERNAL_TOOL_RESOURCE_TYPE = 'internal';
+/**
+ * Where an agent schema property points to declare "this is a FILE":
+ * `{ $ref: JOB_ATTACHMENT_REF }`, with {@link jobAttachmentDefinition} under the
+ * same schema's `definitions['job-attachment']`.
+ */
+const JOB_ATTACHMENT_REF = '#/definitions/job-attachment';
+/**
+ * The canonical `job-attachment` definition an agent schema's file field
+ * `$ref`s into — the uipath-agents skill's `agent-definition.md` § File
+ * Attachments ("Schema is fixed — copy verbatim"), and the same block the
+ * platform's own analyze-attachments tool contract carries.
+ *
+ * It tells the agent runtime that an input is an Orchestrator attachment, so a
+ * file tool (Analyze Files) can resolve the attachment's `ID`.
+ *
+ * A function, not a shared object: each schema gets its own copy, so an edit
+ * to one emitted file cannot reach another.
+ *
+ * (The case serializer keeps its own copy in `case/entry-points.ts`: that one
+ * mirrors the platform's `entry-points.json` packager byte for byte, and its
+ * `MimeType` description differs.)
+ */
+function jobAttachmentDefinition() {
+    return {
+        type: 'object',
+        properties: {
+            ID: { type: 'string', description: 'Orchestrator attachment key' },
+            FullName: { type: 'string', description: 'File name' },
+            MimeType: { type: 'string', description: 'MIME type, e.g. "application/pdf", "image/png"' },
+            Metadata: {
+                type: 'object',
+                description: 'Dictionary<string, string> of metadata',
+                additionalProperties: { type: 'string' },
+            },
+        },
+        required: ['ID'],
+        'x-uipath-resource-kind': 'JobAttachment',
+    };
+}
 /** The `properties.toolType` of the built-in HTTP-request tool's file (#935). */
 const HTTP_REQUEST_TOOL_TYPE = 'http-request';
 /**
@@ -1139,29 +1177,13 @@ function builtinToolResourceJson(tool, label, inputs, spec) {
                 properties: {
                     attachments: {
                         type: 'array',
-                        items: { $ref: '#/definitions/job-attachment' },
+                        items: { $ref: JOB_ATTACHMENT_REF },
                         description: String(inputs.attachmentsDescription ?? ''),
                     },
                     analysisTask: { type: 'string', description: String(inputs.analysisTaskDescription ?? '') },
                 },
                 required: ['attachments', 'analysisTask'],
-                definitions: {
-                    'job-attachment': {
-                        type: 'object',
-                        properties: {
-                            ID: { type: 'string', description: 'Orchestrator attachment key' },
-                            FullName: { type: 'string', description: 'File name' },
-                            MimeType: { type: 'string', description: 'MIME type, e.g. "application/pdf", "image/png"' },
-                            Metadata: {
-                                type: 'object',
-                                description: 'Dictionary<string, string> of metadata',
-                                additionalProperties: { type: 'string' },
-                            },
-                        },
-                        required: ['ID'],
-                        'x-uipath-resource-kind': 'JobAttachment',
-                    },
-                },
+                definitions: { 'job-attachment': jobAttachmentDefinition() },
             },
             outputSchema: {
                 type: 'object',
@@ -1324,6 +1346,24 @@ const QUICK_FORM_FIELD_SCHEMA = {
     text: { type: 'string' }, number: { type: 'number' }, boolean: { type: 'boolean' },
     'date-time': { type: 'string', format: 'date-time' },
 };
+/**
+ * The folder an app escalation names: the author's `folderPath`, or
+ * `solution_folder` when they gave none — an app that ships in this solution.
+ *
+ * `solution_folder` is the platform's own spelling for that case: it is the
+ * `Folder` that `uip solution resources list` reports for a solution-internal
+ * app, and what the agents skill tells authors to copy into
+ * `channels[].properties.folderName`. The SDK used to write `""`, which no
+ * product writer produces (flow-builder-sdk#967). Measured, the two are the
+ * same everywhere it counts: the agent tool's binding generator drops both
+ * from the App binding (`resolveFolderPathBindingValue`), `uip agent refresh`
+ * plus `uip solution resources refresh` derive byte-identical files from
+ * either, and a live debug resolves the app in the debug folder for both. So
+ * this changes the vocabulary, not the behaviour.
+ */
+function escalationAppFolder(app) {
+    return app.folderPath ? app.folderPath : 'solution_folder';
+}
 /**
  * The `resources/<id>/resource.json` an inline agent's ESCALATION needs — the
  * escalation half of what `toolResourceJson` does for a tool, and inert without
@@ -1400,7 +1440,7 @@ function escalationResourceJson(esc, spec) {
                 // refresh` imports; `folderName` is the app's Orchestrator folder.
                 resourceKey: app.key,
                 appName: app.name,
-                folderName: app.folderPath ?? '',
+                folderName: escalationAppFolder(app),
                 // The app's deploy version (its action schema's `version`). The SDK does
                 // not read the action schema, so this is the platform's own default — the
                 // storage migration that introduced the field writes `1` when absent.
@@ -2183,134 +2223,88 @@ function memoryResourceDef(spec) {
         },
     };
 }
-function inlineAgentDef(spec) {
-    return {
-        nodeType: INLINE_AGENT_TYPE,
-        version: '1.2',
-        category: 'agent',
-        description: 'AI agent that completes tasks autonomously',
-        tags: ['agentic', 'ai', 'autonomous', 'agent'],
-        sortOrder: 5,
-        supportsErrorHandling: true,
-        display: { label: 'Autonomous Agent', icon: 'autonomous-agent', shape: 'rectangle' },
-        handleConfiguration: [
-            {
-                position: 'top',
-                handles: [{
-                        id: 'escalation', type: 'source', handleType: 'artifact', label: 'Escalations', showButton: true,
-                        constraints: {
-                            // BOTH spellings, as the platform's own def declares them (`registry
-                            // get uipath.agent.autonomous`, 2026-07-31): the bare type is the
-                            // pre-split era's escalation node, the wildcard is today's suffixed
-                            // variants (`.coded-action-app` / `.quick-form`). Emitting only the
-                            // bare one — as this did until card G16 — declared a handle that
-                            // rejected every node the current registry can actually serve.
-                            allowedTargets: [
-                                { nodeType: 'uipath.agent.resource.escalation' },
-                                { nodeType: 'uipath.agent.resource.escalation.*' },
-                            ],
-                            validationMessage: 'Only Agent Escalation nodes can connect here',
-                        },
-                    }],
-            },
-            {
-                position: 'bottom',
-                handles: [
-                    {
-                        id: 'context', type: 'source', handleType: 'artifact', label: 'Context', showButton: true,
-                        constraints: {
-                            allowedTargets: [{ nodeType: 'uipath.agent.resource.context.*' }],
-                            validationMessage: 'Only Context resource nodes can connect here',
-                        },
-                    },
-                    {
-                        id: 'tool', type: 'source', handleType: 'artifact', label: 'Tools', showButton: true,
-                        constraints: {
-                            allowedTargets: [{ nodeType: 'uipath.agent.resource.tool.*' }],
-                            validationMessage: 'Only Tool resource nodes can connect here',
-                        },
-                    },
-                ],
-            },
-            { position: 'left', handles: [{ id: 'input', type: 'target', handleType: 'input' }] },
-            {
-                position: 'right',
-                handles: [
-                    { id: 'success', type: 'source', handleType: 'output', isDefaultForType: true },
-                    {
-                        id: 'error', type: 'source', handleType: 'output', label: 'Error',
-                        visible: '{inputs.errorHandlingEnabled}',
-                        constraints: { maxConnections: 1 },
-                    },
-                ],
-            },
-        ],
-        inputDefinition: {
-            type: 'object',
-            properties: {
-                systemPrompt: { type: 'string', minLength: 1, errorMessage: { minLength: 'System prompt is required' } },
-                userPrompt: { type: 'string', minLength: 1, errorMessage: { minLength: 'User prompt is required' } },
-                model: { type: 'string', minLength: 1, errorMessage: { minLength: 'Model is required' } },
-                temperature: { type: 'number', minimum: 0, maximum: 1 },
-                maxTokenPerResponse: { type: 'number', minimum: 0, maximum: 16384 },
-                modelMaxTokens: { type: 'number', minimum: 0 },
-                maxIterations: { type: 'number', minimum: 1, maximum: 100 },
-                guardrails: { type: 'array' },
-                agentInputVariables: { type: 'array' },
-                agentOutputVariables: { type: 'array' },
-            },
-            required: ['systemPrompt', 'userPrompt', 'model'],
-        },
-        inputDefaults: {},
-        outputDefinition: {
-            output: {
-                type: 'object',
-                description: 'Agent response',
-                // `=result.response`, not `=this` — 27 of 27 deployed instances, and the
-                // engine's own inline dispatch returns `{ response: { …declared keys } }`.
-                source: '=result.response',
-                var: 'output',
-                // NO per-instance schema here, and that is the whole point of this comment:
-                // `definitions[]` is keyed by node TYPE, and every inline agent in a flow
-                // shares this ONE entry. A flow with two agents (an analyst and a writer,
-                // say) therefore cannot have both contracts here — whichever was emitted
-                // last would win, and every read against the other resolved to the wrong
-                // shape. Measured on GA row 7's port, whose four `.return()` mappings off
-                // the ANALYST drew 25 undeclared-field errors quoting the WRITER's fields
-                // (`Available at "$vars.disputeAnalystAgent.output": "subject", "body"`) on
-                // a flow that is correct.
-                //
-                // The instance is where an authored contract belongs, and the SDK already
-                // writes it there (`node.outputs.output.schema`, below). A reader that
-                // refines per node then picks it up — applying an instance schema when the
-                // definition's is GENERIC and never overriding a definition that declares
-                // a shape, which is right in general and was
-                // exactly what this def defeated.
-                //
-                // Deployed truth agrees: v1's own two-agent BillingDisputeResolution
-                // artifact (1.0, 2026-07-15) carries `properties: { content: {…} }` on the
-                // shared definition and `schema: null` on both agent nodes.
-            },
-            error: {
-                type: 'object',
-                description: 'Error information if the node fails',
-                source: '=Error',
-                var: 'error',
-            },
-        },
-        model: {
-            source: true,
-            type: 'bpmn:ServiceTask',
-            serviceType: 'Orchestrator.StartInlineAgentJob',
-            version: 'v2',
-            context: [
-                { name: '_label', type: 'string', value: '' },
-                { name: 'name', type: 'string', value: '' },
-                { name: 'entryPoint', type: 'string', value: '' },
-            ],
-        },
-        debug: { runtime: 'bpmnEngine' },
-    };
+/** Numeric dotted compare: '1.10' > '1.9'. */
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * The inline agent's bundled versions, oldest first, and the newest of them.
+ * The newest bundled pair is the default, so there is no version literal in
+ * this file: when the registry serves a newer version, `check:definitions`
+ * reports the missing pair, `sync:definitions` adds it, and the default follows.
+ */
+const INLINE_AGENT_VERSIONS = Object.keys(DEFS)
+    .filter((k) => k.startsWith(`${INLINE_AGENT_TYPE}@`))
+    .map((k) => k.slice(INLINE_AGENT_TYPE.length + 1))
+    .sort(compareVersions);
+const INLINE_AGENT_DEFAULT_VERSION = INLINE_AGENT_VERSIONS[INLINE_AGENT_VERSIONS.length - 1];
+/** True when a definition declares the agent's `memory` artifact handle. */
+function declaresMemoryHandle(def) {
+    return (def?.handleConfiguration ?? []).some((g) => (g?.handles ?? []).some((h) => h?.id === 'memory'));
+}
+/**
+ * The definition for the INLINE autonomous agent: the bundled pair for
+ * `version` (the newest by default), plus an explicit overlay of the details
+ * the registry payload does not carry.
+ *
+ * This is the one node type in the agent family that is the SAME on every
+ * tenant — it carries its own configuration instead of referencing a resource —
+ * so `uip maestro flow registry get uipath.agent.autonomous` is a direct oracle
+ * and the bundle entry is the registry's definition as last synced
+ * (`sync:definitions` writes it through unchanged; `check:definitions --deep`
+ * reports content that has moved since). Versions and content both come from
+ * there.
+ *
+ * The overlay, and nothing else:
+ *
+ *  * `outputDefinition.output.source` is `=result.response`. The registry's
+ *    definition declares no `source`; the deployed corpus (29 `uipath.agent.autonomous` nodes, 05-18 → 07-29) has
+ *    `=result.response` in 27 of 27 that declare outputs, and the engine's own
+ *    inline dispatch returns `{ response: { …declared keys } }`. Without it the
+ *    node's `output` is the whole result envelope rather than the declared keys.
+ *    It is applied at every version; the registry payload has no `source`.
+ *  * The `memory` handle is kept only when the flow attaches memory. It is
+ *    LOCAL content (#431) on the bundled 1.4, absent from the registry's 1.4
+ *    (`check.ts` AGENT_MEMORY_NOT_AUTHORABLE), so an agent without memory gets
+ *    the registry's handle set.
+ *
+ * NO per-instance schema goes on the definition: `definitions[]` is keyed by
+ * node TYPE, and every inline agent in a flow shares this one entry. A flow
+ * with two agents (an analyst and a writer, say) therefore cannot have both
+ * contracts here — whichever was emitted last would win, and every read against
+ * the other resolved to the wrong shape (GA row 7's port: 25 undeclared-field
+ * errors on a correct flow). The authored contract goes on the NODE
+ * (`node.outputs.output.schema`, in the `inlineAgent` arm), where a reader that
+ * refines per node picks it up.
+ *
+ * The bundled 1.2 is the pre-#956 default, kept so a flow this SDK compiled
+ * before — and a decompile of one, which pins `{ version: '1.2' }` — still
+ * compiles. The corpus also carries 1.1 and 1.3; `shared/sample-flows/
+ * inline-agent.flow` says 1.0, which appears in none of the 29.
+ */
+function inlineAgentDef(version, withMemory) {
+    const bundled = DEFS[`${INLINE_AGENT_TYPE}@${version}`];
+    if (!bundled)
+        return undefined;
+    const def = clone(bundled);
+    const output = def.outputDefinition?.output;
+    if (output)
+        output.source = '=result.response';
+    if (!withMemory) {
+        for (const group of def.handleConfiguration ?? []) {
+            if (Array.isArray(group?.handles))
+                group.handles = group.handles.filter((h) => h?.id !== 'memory');
+        }
+        def.handleConfiguration = (def.handleConfiguration ?? []).filter((g) => g?.handles?.length);
+    }
+    return def;
 }
 /**
  * Classify a RENDERED input value (the output of {@link renderValue}).
@@ -2379,6 +2373,19 @@ function renderAgentSidecarPrompt(template, plan) {
         return whole;
     });
 }
+/**
+ * The `version` every `agent.json` sidecar declares — the agent tool's
+ * `AGENT_SCHEMA_VERSION` (uipath-cli `packages/agent-tool/src/templates/agent-template.ts`).
+ *
+ * It is not a free label. The agents backend reads an on-file `outputSchema`
+ * only at `version >= 1.2.0` (UiPath/Agents#5705), and since uipath-cli#3753
+ * `uip agent init` writes `1.2.0` and `uip agent validate` refuses anything else
+ * with `AgentValidationOutdated` ("Agent version "1.1.0" is outdated; latest is
+ * "1.2.0""). The bump is a version change only: `uip agent refresh` rewrites
+ * the field and nothing else. All three writers below share this one constant
+ * so they cannot fall behind separately (flow-builder-sdk#962).
+ */
+const AGENT_DEFINITION_VERSION = '1.2.0';
 /**
  * The `agent.json` an inline agent's `source` directory must hold.
  *
@@ -2389,8 +2396,9 @@ function renderAgentSidecarPrompt(template, plan) {
  * inline-agent node and no such file references a definition that is not there.
  *
  * Shape transcribed from deployed agents under `runs/` (e.g. the four DevCon
- * billing agents, `version: '1.1.0'`, `type: 'lowCode'`), which is also what
- * `uip agent init --inline-in-flow` scaffolds. `contentTokens` mirrors `content` as
+ * billing agents, `type: 'lowCode'`), which is also what
+ * `uip agent init --inline-in-flow` scaffolds. The `version` is
+ * {@link AGENT_DEFINITION_VERSION}, not the `1.1.0` those older agents carry. `contentTokens` mirrors `content` as
  * one `simpleText` run: the designer uses those tokens to render a prompt with
  * inline variable chips, and a single run is the faithful encoding of a plain
  * string.
@@ -2406,7 +2414,7 @@ function renderAgentSidecarPrompt(template, plan) {
  */
 function conversationalAgentJson(spec) {
     return {
-        version: '1.1.0',
+        version: AGENT_DEFINITION_VERSION,
         settings: {
             model: spec.model,
             // Required by the platform's agent.json schema, same as the inline
@@ -2458,7 +2466,7 @@ function voiceAgentJson(spec) {
     const DEFAULT_PERSONA = 'Aoede';
     const v = spec.voice ?? {};
     return {
-        version: '1.1.0',
+        version: AGENT_DEFINITION_VERSION,
         settings: {
             engine: 'conversational-v1',
             mode: 'voice',
@@ -2490,7 +2498,7 @@ function voiceAgentJson(spec) {
 }
 function inlineAgentJson(spec) {
     return {
-        version: '1.1.0',
+        version: AGENT_DEFINITION_VERSION,
         settings: {
             model: spec.model,
             // `maxTokens` and `temperature` are REQUIRED by the platform's own
@@ -3920,7 +3928,7 @@ function describeDeclared(bindings) {
  * exactly (design §2.6/§4.2): the named version resolves or compilation fails,
  * and a contributor that ignored the author's requested version is rejected.
  */
-function resolveContributionDefinition(ref, requestedVersion, where) {
+export function resolveContributionDefinition(ref, requestedVersion, where) {
     if (!ref || typeof ref.nodeType !== 'string' || !ref.nodeType || typeof ref.version !== 'string' || !ref.version) {
         throw new Error(`${where}: contribute() returned a DefinitionReference without an exact nodeType + version.`);
     }
@@ -4405,10 +4413,16 @@ function typeAgentInputSchemas(scope, globals) {
         if (g.direction === 'in' && g.triggerNodeId)
             lookup.set(`${g.triggerNodeId}.output.${g.id}`, { type: g.type, schema: g.schema });
     }
-    for (const { properties, refs } of scope.agentSchemas) {
+    for (const { schema, refs } of scope.agentSchemas) {
         for (const r of refs) {
-            properties[r.flatName] = jsonSchemaForRef(r.binding, lookup);
+            schema.properties[r.flatName] = jsonSchemaForRef(r.binding, lookup);
         }
+        // A file property is a `$ref`, and a `$ref` resolves against THIS schema's
+        // `definitions` — so the block is added exactly when a file property is
+        // present (a schema with no file keeps the shape it always had).
+        const hasFile = Object.values(schema.properties).some((p) => p?.$ref === JOB_ATTACHMENT_REF);
+        if (hasFile)
+            schema.definitions = { ...schema.definitions, 'job-attachment': jobAttachmentDefinition() };
     }
 }
 /** One property's schema — `{}` when the type cannot be established. See {@link typeAgentInputSchemas}. */
@@ -4498,17 +4512,58 @@ function walkSchemaType(schema, segments) {
     }
     return typeof current?.type === 'string' ? current.type : undefined;
 }
-/** A resolved type → its JSON-Schema property, with v1's two normalisations. */
+/**
+ * A resolved type → its JSON-Schema property.
+ *
+ * Every type a flow can DECLARE (`types.*`) has its own case, and the switch is
+ * exhaustive over {@link TypeDesc}: adding a type to `types` without deciding
+ * what an agent sees for it is a compile error here, not a silent `{}`.
+ *
+ * `file` → `{ $ref: '#/definitions/job-attachment' }`; the caller adds the
+ * definition (see `typeAgentInputSchemas`).
+ *
+ * Typeless `{}` is the answer for `any` and for "unknown" (`undefined`,
+ * or a type string from a node definition that is not in the SDK's
+ * vocabulary): that is v1's own rule for a type it cannot establish
+ * (`buildAgentInputTypeResolver` → `'any'` → a property with no `type`), and it
+ * keeps the runtime's pydantic model from refusing a value the SDK only
+ * guessed at.
+ */
 function jsonSchemaForType(type) {
-    // `any`, `undefined` and the file/octet aliases all mean "do not constrain".
-    // (v1 maps `octet-stream`/`file` to `object`; the SDK declares nothing rather
-    // than guess, because a file input reaches an agent through a `$ref` the
-    // sidecar does not carry.)
-    if (!type || type === 'any' || type === 'file' || type === 'octet-stream')
+    if (type === 'octet-stream')
+        return { $ref: JOB_ATTACHMENT_REF }; // v1's alias for file
+    if (type === undefined || !isTypeDesc(type))
         return {};
-    if (type === 'array')
-        return { type: 'array', items: {} };
-    return { type };
+    switch (type) {
+        case 'file': return { $ref: JOB_ATTACHMENT_REF };
+        case 'any': return {};
+        // A bare `type: 'array'` makes the runtime's `jsonschema_to_pydantic`
+        // reject a valid array (v1's note at `uipath.ts:118-123`, MST-9544).
+        case 'array': return { type: 'array', items: {} };
+        case 'string':
+        case 'number':
+        case 'integer':
+        case 'boolean':
+        case 'object':
+            return { type };
+        // The case vocabulary's widths and date kinds, as JSON Schema spells them
+        // (the same table `case/entry-points.ts` projects with).
+        case 'float': return { type: 'number', format: 'float' };
+        case 'double': return { type: 'number', format: 'double' };
+        case 'date': return { type: 'string', format: 'date' };
+        case 'datetime': return { type: 'string', format: 'date-time' };
+        // A case `jsonSchema` variable's shape lives in its `body`, which this
+        // lookup does not carry — so its type is not established here.
+        case 'jsonSchema': return {};
+        default: {
+            const unmapped = type;
+            throw new Error(`jsonSchemaForType: no agent schema mapping for type '${String(unmapped)}'`);
+        }
+    }
+}
+const TYPE_DESCS = new Set(Object.values(types));
+function isTypeDesc(type) {
+    return TYPE_DESCS.has(type);
 }
 /**
  * An End node's `outputs` map: every variable this scope exposes as a flow
@@ -4624,6 +4679,61 @@ export function serialize(built, opts = {}) {
      * A bindings entry the node does not reference is not a bound resource.
      */
     const resourceBindings = new Map();
+    /**
+     * Hoist a contribution's own bindings, then close every `<bindings.NAME>` its
+     * definition references and it did not supply, from the definition's own
+     * `model.bindings` (flow-builder-sdk#942). Shared by the three contribution
+     * sites (step, trigger, entry point), so a `rawNode` and a hand-written
+     * subclass get the same entries a typed emitter would. `check` runs the same
+     * plan dry (`checkContribution` in `check.ts`), so it reports what this throws.
+     */
+    function hoistContributionBindings(def, supplied, where) {
+        for (const b of supplied ?? [])
+            resourceBindings.set(b.id, b);
+        const plan = planContributionBindings(def, supplied);
+        if (plan.problems.length) {
+            throw new BindingRefusal('CONTRIBUTION_BINDING_UNRESOLVED', `${where}: ${plan.problems.join(' ')}`);
+        }
+        if (plan.entries.length === 0)
+            return;
+        // A process reference is the name + folderPath pair every typed process step
+        // emits: go through the same builder, so a raw node and a typed step on ONE
+        // process share one pair instead of shadowing each other.
+        const byName = new Map(plan.entries.map((e) => [e.name, e]));
+        const pairName = byName.get('name');
+        const pairFolder = byName.get('folderPath');
+        if (plan.resource === 'process' && plan.entries.length === 2 && pairName?.propertyAttribute === 'name'
+            && pairFolder?.propertyAttribute === 'folderPath' && pairName.default !== undefined
+            && pairFolder.default !== undefined) {
+            const { entries } = processResourceBindings({
+                name: pairName.default,
+                folderPath: pairFolder.default,
+                resourceSubType: pairName.resourceSubType,
+                resourceKey: plan.resourceKey,
+            }, resourceBindings);
+            for (const b of entries) {
+                // processResourceBindings types the subtype to the families it knows; keep
+                // the definition's own spelling (or none) verbatim.
+                if (pairName.resourceSubType === undefined)
+                    delete b.resourceSubType;
+                resourceBindings.set(b.id, b);
+            }
+            return;
+        }
+        for (const e of plan.entries) {
+            const same = [...resourceBindings.values()].some((b) => b.resource === e.resource
+                && b.resourceKey === e.resourceKey && b.name === e.name && b.propertyAttribute === e.propertyAttribute);
+            if (same)
+                continue;
+            const slug = e.resourceKey.replace(/[^A-Za-z0-9]/g, '') || 'Resource';
+            const cap = (t) => t.charAt(0).toUpperCase() + t.slice(1);
+            const stem = `b${cap(slug)}${cap(e.name.replace(/[^A-Za-z0-9]/g, ''))}`;
+            let id = stem;
+            for (let n = 2; resourceBindings.has(id); n++)
+                id = `${stem}${n}`;
+            resourceBindings.set(id, { id, ...e });
+        }
+    }
     /**
      * Extra files the flow needs beside the `.flow` — see `SerializeOpts.sidecars`.
      * Written into the caller's array when one was passed, so a caller that wants them
@@ -4719,13 +4829,15 @@ export function serialize(built, opts = {}) {
      * (design §2.6): resolution is exact — `<type>@<version>` from the bundle, or
      * the version of the definition already in hand — and a version the SDK
      * cannot resolve exactly fails compilation rather than floating to a default.
+     * An undefined `label` takes the definition's `display.label`, which is what
+     * the canvas shows on a freshly dropped node.
      */
     function makeNode(type, id, label, o = {}) {
         let def = o.def ?? defByType.get(type);
         if (o.requestedVersion !== undefined && def?.version !== o.requestedVersion) {
             const exact = o.def ? undefined : DEFS[`${type}@${o.requestedVersion}`];
             if (!exact) {
-                throw new Error(`"${label}" requests ${type}@${o.requestedVersion}, but this SDK resolves only `
+                throw new Error(`"${label ?? id}" requests ${type}@${o.requestedVersion}, but this SDK resolves only `
                     + `${type}@${def?.version ?? '<none>'}. Versions are exact — omit { version } to use `
                     + `the pinned default, or request a version this SDK ships.`);
             }
@@ -4738,7 +4850,7 @@ export function serialize(built, opts = {}) {
             type,
             typeVersion: def?.version ?? '1.0.0',
             ui: { position: { x: 256 + col * 288, y: 144 + (o.parentId ? 160 : 0) }, size: { width: 96, height: 96 }, collapsed: false },
-            display: { label, ...(def?.display?.icon ? { icon: def.display.icon } : {}) },
+            display: { label: label ?? def?.display?.label ?? id, ...(def?.display?.icon ? { icon: def.display.icon } : {}) },
         };
         col++;
         // A Data Fabric node gets no node-level `model`, whichever path emits it
@@ -4862,7 +4974,7 @@ export function serialize(built, opts = {}) {
     if (customTrigger) {
         const contribution = customTrigger.contribute(built.triggerOptions?.version !== undefined ? { requestedVersion: built.triggerOptions.version } : {});
         const def = resolveContributionDefinition(contribution.definition, built.triggerOptions?.version, 'trigger');
-        const node = makeNode(def.nodeType, triggerId, def.display?.label ?? 'Start', { def, requestedVersion: built.triggerOptions?.version });
+        const node = makeNode(def.nodeType, triggerId, built.triggerOptions?.label ?? def.display?.label ?? 'Start', { def, requestedVersion: built.triggerOptions?.version });
         const inputs = renderDeep(contribution.inputs ?? {}, NO_RENAME);
         if (def.model?.entryPointId === true && inputs.entryPointId === undefined) {
             inputs.entryPointId = stableId(`${built.id}:start:entryPoint`);
@@ -4870,25 +4982,26 @@ export function serialize(built, opts = {}) {
                 inputs.isDefaultEntryPoint = true;
         }
         node.inputs = inputs;
-        for (const b of contribution.bindings ?? [])
-            resourceBindings.set(b.id, b);
+        hoistContributionBindings(def, contribution.bindings, 'trigger');
         root.nodes.push(node);
     }
+    // The author's `.trigger(spec, { label })`; makeNode falls back to the definition's label.
+    const rootLabel = built.triggerOptions?.label;
     const trigger = customTrigger
         ? root.nodes[root.nodes.length - 1]
         : eventTriggerRc
-            ? makeNode(eventTriggerRc.nodeType, triggerId, built.trigger?.kind === 'event' ? 'Event trigger' : 'Start', { def: eventTriggerRc.v1def, requestedVersion: built.triggerOptions?.version })
+            ? makeNode(eventTriggerRc.nodeType, triggerId, rootLabel, { def: eventTriggerRc.v1def, requestedVersion: built.triggerOptions?.version })
             : built.trigger?.kind === 'scheduled'
-                ? makeNode(NODE_TYPE.scheduledTrigger, triggerId, 'Scheduled trigger', {
+                ? makeNode(NODE_TYPE.scheduledTrigger, triggerId, rootLabel, {
                     requestedVersion: scheduledVersion(built.trigger.inputs, built.triggerOptions?.version),
                 })
                 : built.trigger?.kind === 'form'
-                    ? makeNode(NODE_TYPE.formTrigger, triggerId, 'Form trigger', { requestedVersion: built.triggerOptions?.version })
+                    ? makeNode(NODE_TYPE.formTrigger, triggerId, rootLabel, { requestedVersion: built.triggerOptions?.version })
                     : built.trigger?.kind === 'conversation'
-                        ? makeNode(NODE_TYPE.conversationTrigger, triggerId, 'Conversation trigger', { requestedVersion: built.triggerOptions?.version })
+                        ? makeNode(NODE_TYPE.conversationTrigger, triggerId, rootLabel, { requestedVersion: built.triggerOptions?.version })
                         : built.trigger?.kind === 'voice'
-                            ? makeNode(NODE_TYPE.voiceTrigger, triggerId, 'Incoming call trigger', { requestedVersion: built.triggerOptions?.version })
-                            : makeNode(NODE_TYPE.trigger, triggerId, 'Manual trigger', { requestedVersion: built.triggerOptions?.version });
+                            ? makeNode(NODE_TYPE.voiceTrigger, triggerId, rootLabel, { requestedVersion: built.triggerOptions?.version })
+                            : makeNode(NODE_TYPE.trigger, triggerId, rootLabel, { requestedVersion: built.triggerOptions?.version });
     if (!customTrigger) {
         trigger.inputs = eventTriggerRc && built.trigger?.kind === 'event'
             ? {
@@ -5006,8 +5119,7 @@ export function serialize(built, opts = {}) {
         if (contribution.outputs) {
             node.outputs = { ...(node.outputs ?? {}), ...subNodeId(clone(contribution.outputs), id) };
         }
-        for (const b of contribution.bindings ?? [])
-            resourceBindings.set(b.id, b);
+        hoistContributionBindings(def, contribution.bindings, where);
         scope.nodes.push(node);
         for (const t of tails)
             addEdge(scope, t, id);
@@ -5165,16 +5277,30 @@ export function serialize(built, opts = {}) {
                 // required: it is what the platform scaffolds, so a flow that reads
                 // `content` is a real (if toy) flow. `check` says so.
                 : { content: 'string' };
-            // Rich options select a newer definition: `mode` needs the registry's
-            // CURRENT 1.3 (which adds the field), `memory` needs 1.4 (which adds the
-            // handle — derived from 1.3 by the workbench v1.4 migration; the tenant
-            // registry still serves 1.3). Without either, the 1.2 literal is emitted
-            // byte-identically.
-            const def = s.memory !== undefined
-                ? clone(DEFS[`${INLINE_AGENT_TYPE}@1.4`])
-                : s.mode !== undefined
-                    ? clone(DEFS[`${INLINE_AGENT_TYPE}@1.3`])
-                    : inlineAgentDef({ returns });
+            // ONE default version for every call shape — the newest bundled pair (see
+            // `inlineAgentDef`). `mode` and `memory` used to pick the version too (1.3
+            // and 1.4), so a plain agent got a superseded 1.2 and each option moved
+            // the node to another version as a side effect (#956). Both now live in
+            // the sidecar and on edges; neither selects a definition. An explicit
+            // `{ version }` (what decompile writes back) resolves exactly.
+            const version = step.options?.version ?? INLINE_AGENT_DEFAULT_VERSION;
+            // `definitions[]` holds one entry per type@version, so a flow where any
+            // agent attaches memory keeps the handle for all of them.
+            const withMemory = s.memory !== undefined
+                || declaresMemoryHandle(emittedDefs.get(`${INLINE_AGENT_TYPE}@${version}`));
+            const def = inlineAgentDef(version, withMemory);
+            if (!def) {
+                throw new Error(`"${step.name}" requests ${INLINE_AGENT_TYPE}@${version}, but this SDK resolves only `
+                    + `${INLINE_AGENT_VERSIONS.map((v) => `${INLINE_AGENT_TYPE}@${v}`).join(', ')}. Versions are exact — `
+                    + `omit { version } to use the default (${INLINE_AGENT_DEFAULT_VERSION}), or request a version this SDK ships.`);
+            }
+            if (s.memory !== undefined && !declaresMemoryHandle(def)) {
+                throw new Error(`"${step.name}" attaches \`memory\`, but ${INLINE_AGENT_TYPE}@${version} declares no \`memory\` handle. `
+                    + (version === INLINE_AGENT_DEFAULT_VERSION
+                        ? `Pin a version that has it with inlineAgent({ ..., version: '<x.y>' }) `
+                            + `(bundled with memory: ${INLINE_AGENT_VERSIONS.filter((v) => declaresMemoryHandle(DEFS[`${INLINE_AGENT_TYPE}@${v}`])).join(', ') || 'none'}), or drop \`memory\`.`
+                        : `Drop { version: '${version}' } to use ${INLINE_AGENT_DEFAULT_VERSION}, or drop \`memory\`.`));
+            }
             const id = stepUid(scope, step.name);
             // `source` is the agent's directory name. Derived from the flow id + step
             // name rather than random so a recompile is byte-identical — a v4-shaped uuid
@@ -5263,7 +5389,7 @@ export function serialize(built, opts = {}) {
             // The schema's property TYPES need this scope's finished variables, which
             // do not exist yet — park them (the `properties` object is filled in
             // place when the scope closes). See `typeAgentInputSchemas`.
-            scope.agentSchemas.push({ properties: agentJson.inputSchema.properties, refs: plan.refs });
+            scope.agentSchemas.push({ schema: agentJson.inputSchema, refs: plan.refs });
             // GROUNDING — one resource node per context index, joined to the agent's own
             // `context` handle. An ARTIFACT, not a step: it takes no incoming control
             // flow, produces no output, and never reaches the End node. The edge runs OUT
@@ -5612,7 +5738,7 @@ export function serialize(built, opts = {}) {
                         name: app.name,
                         appName: app.name,
                         displayName: app.name,
-                        folderPath: app.folderPath ?? '',
+                        folderPath: escalationAppFolder(app),
                         inputSchema: fieldSchema(app.inputs),
                         outputSchema: fieldSchema(app.outputs),
                     },
@@ -5679,21 +5805,28 @@ export function serialize(built, opts = {}) {
             // downstream in the engine.
             const s = spec.inputs;
             const nodeInputs = s.inputs ?? {};
-            const subType = spec.kind === 'apiWorkflow' ? 'Api'
-                : spec.kind === 'agenticProcess' ? 'ProcessOrchestration'
-                    : spec.kind === 'publishedFunction' ? 'Function'
-                        : 'Process';
             const fireAndForget = spec.kind === 'agenticProcess' && spec.inputs.completion === 'fire-and-forget';
             const def = spec.kind === 'publishedFunction'
-                ? publishedFunctionDef({ key: spec.inputs.key, name: s.name, folderPath: s.folderPath, inputs: nodeInputs, returns: spec.inputs.returns })
+                ? publishedFunctionDef({ key: spec.inputs.key, name: s.name, folderPath: spec.inputs.folderPath, inputs: nodeInputs, returns: spec.inputs.returns })
                 : spec.kind === 'apiWorkflow'
-                    ? apiWorkflowDef({ key: spec.inputs.key, name: s.name, folderPath: s.folderPath, inputs: nodeInputs, returns: spec.inputs.returns })
+                    ? apiWorkflowDef({ key: spec.inputs.key, name: s.name, folderPath: spec.inputs.folderPath, inputs: nodeInputs, returns: spec.inputs.returns })
                     : spec.kind === 'agenticProcess'
-                        ? agenticProcessDef({ key: spec.inputs.key, name: s.name, folderPath: s.folderPath, inputs: nodeInputs, returns: spec.inputs.returns, form: spec.inputs.form })
-                        : rpaWorkflowDef({ key: spec.inputs.key, name: s.name, folderPath: s.folderPath, inputs: nodeInputs, returns: spec.inputs.returns });
+                        ? agenticProcessDef({
+                            key: spec.inputs.key, name: s.name, folderPath: s.folderPath, location: spec.inputs.location,
+                            projectId: spec.inputs.projectId, inputs: nodeInputs, returns: spec.inputs.returns, form: spec.inputs.form,
+                        })
+                        : rpaWorkflowDef({
+                            key: spec.inputs.key, name: s.name, folderPath: s.folderPath, location: spec.inputs.location,
+                            projectId: spec.inputs.projectId, inputs: nodeInputs, returns: spec.inputs.returns,
+                        });
             // The bindings first: two steps on the same process share ONE pair, and the
             // definition's `model.context` names ids that have to exist.
-            const { entries } = processResourceBindings({ name: s.name, folderPath: s.folderPath, resourceSubType: subType }, resourceBindings);
+            // Read off the definition: one kind carries several subtypes (agenticProcess by `form`).
+            // The pair's key and folder come off it too: an in-solution step's resourceKey is the
+            // bare sibling key and its folder is `''`.
+            const subType = def.model.bindings.resourceSubType;
+            const pairFolder = def.model.bindings.values.find((v) => v.name === 'folderPath').default;
+            const { entries } = processResourceBindings({ name: s.name, folderPath: pairFolder, resourceSubType: subType, resourceKey: def.model.bindings.resourceKey }, resourceBindings);
             for (const b of entries)
                 resourceBindings.set(b.id, b);
             const id = stepUid(scope, step.name);
@@ -5903,7 +6036,7 @@ export function serialize(built, opts = {}) {
             });
             if (plan.refs.length > 0) {
                 const agentJson = sidecars[sidecars.length - 1].json;
-                scope.agentSchemas.push({ properties: agentJson.inputSchema.properties, refs: plan.refs });
+                scope.agentSchemas.push({ schema: agentJson.inputSchema, refs: plan.refs });
             }
             for (const t of tails)
                 addEdge(scope, t, id);
@@ -6871,19 +7004,20 @@ export function serialize(built, opts = {}) {
             takenIds.add(ep.id);
             const spec = ep.trigger;
             const requestedVersion = ep.options?.version;
+            // The author's label; makeNode falls back to the definition's label.
+            const epLabel = ep.options?.label;
             const customEp = spec instanceof FlowTrigger && !('kind' in spec) ? spec : undefined;
             const epSpec = spec;
             let node;
             if (customEp) {
                 const contribution = customEp.contribute(requestedVersion !== undefined ? { requestedVersion } : {});
                 const def = resolveContributionDefinition(contribution.definition, requestedVersion, `entryPoint "${ep.id}"`);
-                node = makeNode(def.nodeType, ep.id, def.display?.label ?? ep.id, { def, requestedVersion });
+                node = makeNode(def.nodeType, ep.id, ep.options?.label ?? def.display?.label ?? ep.id, { def, requestedVersion });
                 node.inputs = {
                     entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`),
                     ...renderDeep(contribution.inputs ?? {}, NO_RENAME),
                 };
-                for (const b of contribution.bindings ?? [])
-                    resourceBindings.set(b.id, b);
+                hoistContributionBindings(def, contribution.bindings, `entryPoint "${ep.id}"`);
             }
             else if (epSpec.kind === 'event') {
                 if (!opts.library)
@@ -6891,7 +7025,7 @@ export function serialize(built, opts = {}) {
                 const sub = epSpec.subscription;
                 const rc = opts.library.resolveEvent('trigger', sub.connector, sub.event, sub.version, sub.object);
                 refuseUnverifiedByoa(opts, 'trigger', sub);
-                node = makeNode(rc.nodeType, ep.id, 'Event trigger', { def: rc.v1def, requestedVersion });
+                node = makeNode(rc.nodeType, ep.id, epLabel, { def: rc.v1def, requestedVersion });
                 node.inputs = {
                     entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`),
                     detail: eventDetail(rc, sub, ep.id, opts, `onEvent() entry point "${ep.id}"`),
@@ -6906,7 +7040,7 @@ export function serialize(built, opts = {}) {
                     resourceBindings.set(b.id, b);
             }
             else if (epSpec.kind === 'scheduled') {
-                node = makeNode(NODE_TYPE.scheduledTrigger, ep.id, 'Scheduled trigger', {
+                node = makeNode(NODE_TYPE.scheduledTrigger, ep.id, epLabel, {
                     requestedVersion: scheduledVersion(epSpec.inputs, requestedVersion),
                 });
                 node.inputs = {
@@ -6915,22 +7049,22 @@ export function serialize(built, opts = {}) {
                 };
             }
             else if (epSpec.kind === 'form') {
-                node = makeNode(NODE_TYPE.formTrigger, ep.id, 'Form trigger', { requestedVersion });
+                node = makeNode(NODE_TYPE.formTrigger, ep.id, epLabel, { requestedVersion });
                 node.inputs = {
                     entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`),
                     schema: { fields: formTriggerFields(ep.inputs), outcomes: [] },
                 };
             }
             else if (epSpec.kind === 'conversation') {
-                node = makeNode(NODE_TYPE.conversationTrigger, ep.id, 'Conversation trigger', { requestedVersion });
+                node = makeNode(NODE_TYPE.conversationTrigger, ep.id, epLabel, { requestedVersion });
                 node.inputs = { entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`) };
             }
             else if (epSpec.kind === 'voice') {
-                node = makeNode(NODE_TYPE.voiceTrigger, ep.id, 'Incoming call trigger', { requestedVersion });
+                node = makeNode(NODE_TYPE.voiceTrigger, ep.id, epLabel, { requestedVersion });
                 node.inputs = { entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`) };
             }
             else if (epSpec.kind === 'manual') {
-                node = makeNode(NODE_TYPE.trigger, ep.id, 'Manual trigger', { requestedVersion });
+                node = makeNode(NODE_TYPE.trigger, ep.id, epLabel, { requestedVersion });
                 node.inputs = { entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`) };
             }
             else {