@uipath/maestro-builder-sdk 6.47.1 → 6.47.2

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

@@ -412,22 +412,47 @@ export type WaitConnectorSpec = WaitConnectorPlaceholderSpec | EventSubscription
 export type ConnectorSpecData = Extract<ActionSpec, {
     kind: 'connector';
 }>;
-/** Whether an external Integration Service task blocks for its result or waits for a callback. */
-export type ExternalExecutionMode = 'sync' | 'async';
+/**
+ * The external agent's or automation's `executionType`, as Integration Service
+ * reports it for the connector object.
+ *
+ * @remarks
+ * This is a property of the connector object, not a choice about the case: copy
+ * it from the activity's `case spec` result
+ * (`Data.EssentialConfiguration.essentialConfiguration.executionType`). The Case
+ * Designer saves `sync` as the `Sync…Execution` service type and both `async`
+ * and `hybrid` as `Async…Execution`, and writes the value itself into the task's
+ * `executionType` context.
+ *
+ * `hybrid` is refused for now (EXTERNAL_TASK_HYBRID_UNSUPPORTED): the Designer
+ * also writes an event pair for it (`operation`, `eventMode`) that the connector
+ * library does not carry (#1387). Add a task on a hybrid object in Studio Web.
+ *
+ * It does not decide whether the stage waits for the task. A task the stage must
+ * not wait on is `.required(false)`, whatever its execution type. For example, a
+ * Snowflake Cortex Interact Agent is `sync` even when the stage moves on without
+ * it.
+ */
+export type ExternalExecutionMode = 'sync' | 'async' | 'hybrid';
 /** Required wiring and typed inputs for an external agent/workflow invocation. */
 export interface ExternalTaskOptions<I extends Record<string, unknown>> {
     /** Symbolic Integration Service connection name declared in `bindings.json`. */
     connection: string;
     /** Symbolic Orchestrator folder binding name declared in `bindings.json`. */
     folder: string;
-    /** Closed runtime mode; each family lowers this to its exact supported service type. */
+    /**
+     * The connector object's `executionType` from its `case spec` result. Required:
+     * the connector library does not carry it yet (#1369), and a wrong value passes
+     * `validate` but runs the wrong contract. Not whether the stage waits: that is
+     * `.required(false)`. See {@link ExternalExecutionMode}.
+     */
     mode: ExternalExecutionMode;
     /** Inputs statically checked by the generated connector descriptor. */
     inputs: I;
 }
 /** Normalized descriptor and execution mode stored on a built external task. */
 export interface ExternalTaskSpecData {
-    /** Requested blocking or callback execution mode. */
+    /** The connector object's `executionType`. */
     mode: ExternalExecutionMode;
     /** Shared connector action identity, inputs, and symbolic bindings. */
     connector: ConnectorSpecData;
@@ -934,7 +959,7 @@ declare class TaskBuilder {
      * Invoke an external agent through its generated Integration Service descriptor.
      *
      * @param descriptor - An `AgentExecution` operation from a generated connector module.
-     * @param opts - Required connection/folder bindings, sync/async mode, and descriptor-typed inputs.
+     * @param opts - Required connection/folder bindings, the object's execution type, and descriptor-typed inputs.
      * @returns This builder, so calls chain.
      */
     externalAgent<I extends Record<string, unknown>, O>(descriptor: ConnectorDescriptor<I, O>, opts: ExternalTaskOptions<I>): this;
@@ -942,7 +967,7 @@ declare class TaskBuilder {
      * Invoke an external workflow through its generated Integration Service descriptor.
      *
      * @param descriptor - A `ProcessExecution` operation from a generated connector module.
-     * @param opts - Required connection/folder bindings, sync/async mode, and descriptor-typed inputs.
+     * @param opts - Required connection/folder bindings, the object's execution type, and descriptor-typed inputs.
      * @returns This builder, so calls chain.
      */
     externalWorkflow<I extends Record<string, unknown>, O>(descriptor: ConnectorDescriptor<I, O>, opts: ExternalTaskOptions<I>): this;

package/dist/case/case-sdk.js

@@ -328,7 +328,7 @@ class TaskBuilder {
      * Invoke an external agent through its generated Integration Service descriptor.
      *
      * @param descriptor - An `AgentExecution` operation from a generated connector module.
-     * @param opts - Required connection/folder bindings, sync/async mode, and descriptor-typed inputs.
+     * @param opts - Required connection/folder bindings, the object's execution type, and descriptor-typed inputs.
      * @returns This builder, so calls chain.
      */
     externalAgent(descriptor, opts) {
@@ -338,7 +338,7 @@ class TaskBuilder {
      * Invoke an external workflow through its generated Integration Service descriptor.
      *
      * @param descriptor - A `ProcessExecution` operation from a generated connector module.
-     * @param opts - Required connection/folder bindings, sync/async mode, and descriptor-typed inputs.
+     * @param opts - Required connection/folder bindings, the object's execution type, and descriptor-typed inputs.
      * @returns This builder, so calls chain.
      */
     externalWorkflow(descriptor, opts) {

package/dist/case/check.js

@@ -6,7 +6,7 @@ import { schemaVersionRefusal } from '../schema-version.js';
 import { caseJsonPreservation, caseJsonPreservationErrors } from './preserve.js';
 import { EQUALS_EXPR_DIALECT, checkBindingLabels, checkConnectorContract, checkConnectorLookups, checkConnectorSchema, } from '../core/connector-checks.js';
 import { checkEventResolution } from '../core/event-checks.js';
-import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT } from './external.js';
+import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT, EXTERNAL_TASK_HYBRID_UNSUPPORTED, externalHybridRefusal, isExternalExecutionMode } from './external.js';
 import { isResourceLabelRefusal, resolveResourceRef } from './resource-identity.js';
 const TYPE_NAMES = new Set(Object.values(types));
 // audit-case-coverage: rule-slot table start
@@ -571,11 +571,18 @@ function checkStage(stage, diags, refStage, refPlacement, bindings) {
                     where: t.name,
                 });
             else {
-                if (t.external.mode !== 'sync' && t.external.mode !== 'async')
+                if (!isExternalExecutionMode(t.external.mode))
                     diags.push({
                         level: 'error',
                         code: 'EXTERNAL_TASK_MODE',
-                        message: `${family} task "${t.name}" mode must be "sync" or "async"; no other service type is valid.`,
+                        message: `${family} task "${t.name}" mode must be the connector object's executionType: "sync", "async" or "hybrid".`,
+                        where: t.name,
+                    });
+                else if (t.external.mode === 'hybrid')
+                    diags.push({
+                        level: 'error',
+                        code: EXTERNAL_TASK_HYBRID_UNSUPPORTED,
+                        message: externalHybridRefusal(`${family} task "${t.name}"`),
                         where: t.name,
                     });
                 if (!t.external.connector?.key?.trim() || !t.external.connector?.action?.trim())

package/dist/case/decompile.js

@@ -1,6 +1,7 @@
 import { commentText } from '../core/comment-text.js';
 import { tsLiteral, tsNumber } from '../core/ts-literal.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS } from './format-profile.js';
+import { EXTERNAL_TASK_CONTEXT, externalDescriptorRefusal, externalHybridRefusal, externalServiceType, isExternalExecutionMode } from './external.js';
 import { preserveSchemaVersion } from '../schema-version.js';
 import { ownEntry } from '../core/own-entry.js';
 import { isUnrestorableSlotId } from './preserve.js';
@@ -523,6 +524,42 @@ function connectorVersion(context) {
 function toCamel(value) {
     return value.replace(/_([a-z0-9])/gi, (_match, char) => String(char).toUpperCase());
 }
+/**
+ * A connector activity's authored inputs, lifted from its `pathParameters` /
+ * `queryParameters` / `body` input containers. A `body` key is the authored
+ * name; a path or query key is the camelCased wire name, mapped back to the
+ * operation's parameter name. Shared by the plain connector lift and the
+ * external task lift, so the two cannot drift.
+ *
+ * With `owner`, the lift is strict (the external task shape): a row that is not
+ * one of the three containers, or a container whose body is not an object, is
+ * refused. Without it, such rows are skipped, as the connector lift always did.
+ */
+function connectorInputs(slots, resolved, owner) {
+    const parameterByWireName = new Map();
+    for (const parameter of resolved.entry.operation?.parameters ?? [])
+        parameterByWireName.set(toCamel(String(parameter.name)), String(parameter.name));
+    const inputs = {};
+    for (const slot of slots) {
+        const name = String(slot?.name ?? '');
+        if (owner && !CONNECTOR_INPUT_CONTAINERS.has(name))
+            throw new Error(`${owner} has unsupported input row "${name}".`);
+        const body = slot?.body;
+        if (owner && body === undefined)
+            continue;
+        if (!body || typeof body !== 'object' || Array.isArray(body)) {
+            if (owner)
+                throw new Error(`${owner} input container "${name}" must carry an object body.`);
+            continue;
+        }
+        for (const [wireName, value] of Object.entries(body)) {
+            const authoredName = name === 'body' ? wireName : (parameterByWireName.get(wireName) ?? wireName);
+            inputs[authoredName] = value;
+        }
+    }
+    return inputs;
+}
+const CONNECTOR_INPUT_CONTAINERS = new Set(['pathParameters', 'queryParameters', 'body']);
 function connectorCall(task, refs, library) {
     if (!library)
         throw new Error(`connector task "${task.displayName ?? task.id ?? '?'}" needs the connector library; pass DecompileOptions.library or --library.`);
@@ -542,19 +579,7 @@ function connectorCall(task, refs, library) {
         version: connectorVersion(context),
     });
     const resolved = library.resolve(identity.key, identity.action, identity.version, identity.object);
-    const parameterByWireName = new Map();
-    for (const parameter of resolved.entry.operation?.parameters ?? [])
-        parameterByWireName.set(toCamel(String(parameter.name)), String(parameter.name));
-    const inputs = {};
-    for (const slot of Array.isArray(data.inputs) ? data.inputs : []) {
-        const body = slot?.body;
-        if (!body || typeof body !== 'object' || Array.isArray(body))
-            continue;
-        for (const [wireName, value] of Object.entries(body)) {
-            const authoredName = slot.name === 'body' ? wireName : (parameterByWireName.get(wireName) ?? wireName);
-            inputs[authoredName] = value;
-        }
-    }
+    const inputs = connectorInputs(Array.isArray(data.inputs) ? data.inputs : [], resolved);
     const connection = bindingName(context.get('connection')?.value, refs);
     const folder = bindingName(context.get('folderKey')?.value, refs);
     const options = opts([
@@ -565,6 +590,14 @@ function connectorCall(task, refs, library) {
     ]);
     return `.connector(${tsLiteral(identity.key)}, ${tsLiteral(identity.action)}, ${tsLiteral(inputs)}${options ? `, ${options}` : ''})`;
 }
+/**
+ * Lift an External Agent / External Workflow task saved in the Case Designer's
+ * shape (the one `serialize` emits): a connector activity's context and input
+ * containers plus the object's `executionType`, which becomes `mode`. The
+ * service type must be the one that execution type gives, so a plan whose two
+ * disagree is refused rather than lifted to a source that would compile to
+ * something else.
+ */
 function externalCall(task, refs, library) {
     const kind = task.type;
     const owner = `${kind} task "${task.displayName ?? task.id ?? '?'}"`;
@@ -575,33 +608,24 @@ function externalCall(task, refs, library) {
     const unknownData = Object.keys(data).find((name) => !allowed.has(name));
     if (unknownData)
         throw new Error(`${owner} has unsupported data field "${unknownData}".`);
-    if (!Array.isArray(data.bindings) || data.bindings.length !== 0)
+    if (data.bindings !== undefined && (!Array.isArray(data.bindings) || data.bindings.length !== 0))
         throw new Error(`${owner} data.bindings must be an empty array; bindings live at case root.`);
-    const modes = kind === 'external-agent'
-        ? new Map([
-            [CASE_FORMAT_PROFILE.externalAgentSyncServiceType, 'sync'],
-            [CASE_FORMAT_PROFILE.externalAgentAsyncServiceType, 'async'],
-        ])
-        : new Map([
-            [CASE_FORMAT_PROFILE.externalWorkflowSyncServiceType, 'sync'],
-            [CASE_FORMAT_PROFILE.externalWorkflowAsyncServiceType, 'async'],
-        ]);
-    const mode = modes.get(data.serviceType);
-    if (!mode)
-        throw new Error(`${owner} has unsupported serviceType "${String(data.serviceType ?? '')}".`);
     if (!Array.isArray(data.context))
         throw new Error(`${owner} requires a resolved context array.`);
-    // A trailing `activityConfigurationVersion: v2` row only picks the Designer
-    // panel; compile writes it back from the plan's `intsvcActivityConfig` flag.
-    const rows = data.context;
-    const last = rows[rows.length - 1];
-    const configRows = last?.name === 'activityConfigurationVersion' && last.value === 'v2' && last.type === 'string'
-        ? rows.slice(0, -1)
-        : rows;
-    const expectedContext = ['activity', 'connectorKey', 'connection', 'folderKey', 'method', 'path'];
-    if (configRows.map((row) => row.name).join('\0') !== expectedContext.join('\0'))
-        throw new Error(`${owner} context must contain exactly ${expectedContext.join(', ')} in canonical order, optionally followed by activityConfigurationVersion v2.`);
-    const context = contextMap({ context: configRows });
+    // A hybrid task carries an event pair the SDK cannot write back (#1387): refuse
+    // it by name, before its extra context rows are reported as unknown.
+    if (data.context.some((row) => row?.name === 'executionType' && row.value === 'hybrid'))
+        throw new Error(externalHybridRefusal(owner));
+    // Exactly the context rows serialize writes (the Designer's set): an unknown
+    // or repeated row would be dropped by the lift and lost on recompile.
+    const contextNames = data.context.map((row) => String(row?.name ?? ''));
+    const unknownContext = contextNames.find((name, at) => !EXTERNAL_TASK_CONTEXT.includes(name) || contextNames.indexOf(name) !== at);
+    if (unknownContext !== undefined)
+        throw new Error(`${owner} has unsupported or repeated context row "${unknownContext}".`);
+    const absentContext = EXTERNAL_TASK_CONTEXT.find((name) => !contextNames.includes(name));
+    if (absentContext)
+        throw new Error(`${owner} is missing context row "${absentContext}".`);
+    const context = contextMap(data);
     const stringValue = (name) => {
         const row = context.get(name);
         if (row?.type !== 'string' || typeof row.value !== 'string' || !row.value)
@@ -617,36 +641,26 @@ function externalCall(task, refs, library) {
             throw new Error(`${owner} context ${name} references missing root binding "${id}".`);
         return bindingLabel(refs, id);
     };
+    const mode = stringValue('executionType');
+    if (!isExternalExecutionMode(mode))
+        throw new Error(`${owner} has unsupported executionType "${mode}".`);
+    const serviceType = externalServiceType(kind, mode);
+    if (data.serviceType !== serviceType)
+        throw new Error(`${owner} has serviceType "${String(data.serviceType ?? '')}", but its executionType "${mode}" saves as "${serviceType}".`);
     const identity = library.identifyAction({
         connectorKey: stringValue('connectorKey'),
         httpMethod: stringValue('method'),
         endpoint: stringValue('path'),
+        objectName: stringValue('objectName'),
+        version: connectorVersion(context),
     });
     const resolved = library.resolve(identity.key, identity.action, identity.version, identity.object);
-    const expectedSubType = kind === 'external-agent' ? 'AgentExecution' : 'ProcessExecution';
-    if (resolved.entry.operation?.subType !== expectedSubType)
-        throw new Error(`${owner} resolves to ${String(resolved.entry.operation?.subType ?? 'no subtype')}, not ${expectedSubType}.`);
-    if (stringValue('activity') !== resolved.activityTypeId)
-        throw new Error(`${owner} activity does not match its descriptor.`);
+    const refused = externalDescriptorRefusal(kind, resolved);
+    if (refused)
+        throw new Error(`${owner}: ${refused}`);
     if (!Array.isArray(data.inputs))
         throw new Error(`${owner} inputs must be an array.`);
-    const fields = new Map(resolved.fields.map((field) => [field.name, field]));
-    const inputs = {};
-    for (const row of data.inputs) {
-        const name = String(row?.name ?? '');
-        if (!name || row.id !== name || row.target !== name || !fields.has(name))
-            throw new Error(`${owner} has unsupported input row "${name}".`);
-        inputs[name] = row.value;
-    }
-    const missing = resolved.fields.find((field) => field.required && !(field.name in inputs));
-    if (missing)
-        throw new Error(`${owner} is missing required input "${missing.name}".`);
-    if (!Array.isArray(data.outputs) || data.outputs.length !== 1)
-        throw new Error(`${owner} must carry exactly one response output.`);
-    const output = data.outputs[0];
-    if (output.name !== 'response' || output.type !== 'json' || output.source !== '.'
-        || typeof output.var !== 'string' || output.id !== output.var)
-        throw new Error(`${owner} has an unsupported response output.`);
+    const inputs = connectorInputs(data.inputs, resolved, owner);
     const descriptor = `{ nodeType: ${tsLiteral(resolved.nodeType)}, version: ${tsLiteral(resolved.version)} }`;
     const options = opts([
         ['connection', tsLiteral(binding('connection'))],

package/dist/case/external.d.ts

@@ -8,6 +8,45 @@
  * `buildConnectorInputs`, which `check` already runs as `connectorInputs`.
  */
 import type { ResolvedConnector } from '../core/library.js';
+import type { ExternalExecutionMode } from './case-sdk.js';
+/**
+ * The context rows `serialize` writes on an external task: the set the Case
+ * Designer saves for a sync object (`uip`'s
+ * `tests/fixtures/external-tasks/designer-saved.json`, the Snowflake Cortex
+ * agent). `decompile` refuses a task with any other row, since the lift would
+ * drop it without a word. A `hybrid` task (which also carries `operation` and
+ * `eventMode`) is refused before this check; see {@link externalHybridRefusal}.
+ */
+export declare const EXTERNAL_TASK_CONTEXT: readonly string[];
+/** Check's code for {@link externalHybridRefusal}. */
+export declare const EXTERNAL_TASK_HYBRID_UNSUPPORTED = "EXTERNAL_TASK_HYBRID_UNSUPPORTED";
+/**
+ * Why an external task on a `hybrid` object cannot be compiled or decompiled
+ * yet. The Case Designer saves such a task with an event pair (context
+ * `operation`, e.g. `TRIGGER_CREATED`, and `eventMode`, e.g. `polling`, also in
+ * the metadata's `activityPropertyConfiguration`) that it reads from live
+ * Integration Service metadata. The connector library does not carry that pair
+ * (#1387), so the SDK cannot write the task faithfully, and a guessed pair could
+ * deploy a task that never completes. `check`, `serialize` and `decompile` all
+ * refuse with this text.
+ *
+ * @param owner - The task as the message names it, e.g. `External Workflow task "Run"`.
+ * @returns The refusal.
+ */
+export declare function externalHybridRefusal(owner: string): string;
+/** The execution types an external task accepts: the values Integration Service reports. */
+export declare function isExternalExecutionMode(value: unknown): value is ExternalExecutionMode;
+/**
+ * The `data.serviceType` the Case Designer saves for an external task of this
+ * execution type. Studio Web runs `hybrid` as `async` (`determineActualIntsvcType`),
+ * so both save as the `Async…Execution` type; the CLI's `externalServiceType`
+ * and its strict validator read the same table.
+ *
+ * @param kind - The task kind.
+ * @param mode - The connector object's `executionType`.
+ * @returns The service type.
+ */
+export declare function externalServiceType(kind: 'external-agent' | 'external-workflow', mode: ExternalExecutionMode): string;
 /** Check's code for {@link externalDescriptorRefusal}. */
 export declare const EXTERNAL_TASK_DESCRIPTOR_CONTRACT = "EXTERNAL_TASK_DESCRIPTOR_CONTRACT";
 /**
@@ -17,8 +56,8 @@ export declare const EXTERNAL_TASK_DESCRIPTOR_CONTRACT = "EXTERNAL_TASK_DESCRIPT
  * Workflow task a `ProcessExecution` one: the service type the task emits
  * (`Intsvc.SyncAgentExecution`, …) is chosen by the family, and a descriptor of
  * the other kind (or a plain connector action) would run the wrong contract.
- * Both need the operation's `uiPathActivityTypeId`, which the task emits as its
- * `activity` context.
+ * Both need the operation's `uiPathActivityTypeId`, which the task's `metadata`
+ * context carries.
  *
  * @param kind - The task kind.
  * @param rc - What `library.resolve` returned for the task's descriptor.

package/dist/case/external.js

@@ -1,3 +1,57 @@
+import { CASE_FORMAT_PROFILE } from './format-profile.js';
+/**
+ * The context rows `serialize` writes on an external task: the set the Case
+ * Designer saves for a sync object (`uip`'s
+ * `tests/fixtures/external-tasks/designer-saved.json`, the Snowflake Cortex
+ * agent). `decompile` refuses a task with any other row, since the lift would
+ * drop it without a word. A `hybrid` task (which also carries `operation` and
+ * `eventMode`) is refused before this check; see {@link externalHybridRefusal}.
+ */
+export const EXTERNAL_TASK_CONTEXT = [
+    'connectorKey', 'connection', 'resourceKey', 'folderKey', 'objectName', 'method', 'path',
+    'executionType', 'metadata', 'activityConfigurationVersion',
+];
+/** Check's code for {@link externalHybridRefusal}. */
+export const EXTERNAL_TASK_HYBRID_UNSUPPORTED = 'EXTERNAL_TASK_HYBRID_UNSUPPORTED';
+/**
+ * Why an external task on a `hybrid` object cannot be compiled or decompiled
+ * yet. The Case Designer saves such a task with an event pair (context
+ * `operation`, e.g. `TRIGGER_CREATED`, and `eventMode`, e.g. `polling`, also in
+ * the metadata's `activityPropertyConfiguration`) that it reads from live
+ * Integration Service metadata. The connector library does not carry that pair
+ * (#1387), so the SDK cannot write the task faithfully, and a guessed pair could
+ * deploy a task that never completes. `check`, `serialize` and `decompile` all
+ * refuse with this text.
+ *
+ * @param owner - The task as the message names it, e.g. `External Workflow task "Run"`.
+ * @returns The refusal.
+ */
+export function externalHybridRefusal(owner) {
+    return (`${owner} is on a "hybrid" object, which Case cannot compile yet: the connector library does not carry ` +
+        `the event pair the Case Designer writes for it (operation, e.g. "TRIGGER_CREATED", and eventMode, e.g. "polling"), ` +
+        `so the task cannot be written faithfully. Add this task in Studio Web for now; ` +
+        `https://github.com/UiPath/builder-sdk/issues/1387 tracks the library change.`);
+}
+/** The execution types an external task accepts: the values Integration Service reports. */
+export function isExternalExecutionMode(value) {
+    return value === 'sync' || value === 'async' || value === 'hybrid';
+}
+/**
+ * The `data.serviceType` the Case Designer saves for an external task of this
+ * execution type. Studio Web runs `hybrid` as `async` (`determineActualIntsvcType`),
+ * so both save as the `Async…Execution` type; the CLI's `externalServiceType`
+ * and its strict validator read the same table.
+ *
+ * @param kind - The task kind.
+ * @param mode - The connector object's `executionType`.
+ * @returns The service type.
+ */
+export function externalServiceType(kind, mode) {
+    const sync = mode === 'sync';
+    if (kind === 'external-agent')
+        return sync ? CASE_FORMAT_PROFILE.externalAgentSyncServiceType : CASE_FORMAT_PROFILE.externalAgentAsyncServiceType;
+    return sync ? CASE_FORMAT_PROFILE.externalWorkflowSyncServiceType : CASE_FORMAT_PROFILE.externalWorkflowAsyncServiceType;
+}
 /** Check's code for {@link externalDescriptorRefusal}. */
 export const EXTERNAL_TASK_DESCRIPTOR_CONTRACT = 'EXTERNAL_TASK_DESCRIPTOR_CONTRACT';
 /**
@@ -7,8 +61,8 @@ export const EXTERNAL_TASK_DESCRIPTOR_CONTRACT = 'EXTERNAL_TASK_DESCRIPTOR_CONTR
  * Workflow task a `ProcessExecution` one: the service type the task emits
  * (`Intsvc.SyncAgentExecution`, …) is chosen by the family, and a descriptor of
  * the other kind (or a plain connector action) would run the wrong contract.
- * Both need the operation's `uiPathActivityTypeId`, which the task emits as its
- * `activity` context.
+ * Both need the operation's `uiPathActivityTypeId`, which the task's `metadata`
+ * context carries.
  *
  * @param kind - The task kind.
  * @param rc - What `library.resolve` returned for the task's descriptor.

package/dist/case/serialize.js

@@ -16,7 +16,7 @@ import { EQUALS_EXPR_DIALECT } from '../core/connector-checks.js';
 import { bindingLabelRefusal } from '../core/binding-messages.js';
 import { resolveEventWhere } from '../core/lookups.js';
 import { resolveCaseSubscription } from './subscription.js';
-import { externalDescriptorRefusal } from './external.js';
+import { externalDescriptorRefusal, externalHybridRefusal, externalServiceType, isExternalExecutionMode } from './external.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS } from './format-profile.js';
 import { isResourceLabelRefusal, resolveResourceRef, resourceIdentity } from './resource-identity.js';
 import { ownEntry } from '../core/own-entry.js';
@@ -971,7 +971,7 @@ function taskData(task, resolver, taskId, stageId, ids) {
             return connectorTaskData(task.connector, resolver, taskId, `Connector task "${task.name}"`);
         case 'external-agent':
         case 'external-workflow':
-            return externalTaskData(task.kind, task.external, resolver, `${task.kind === 'external-agent' ? 'External Agent' : 'External Workflow'} task "${task.name}"`);
+            return externalTaskData(task.kind, task.external, resolver, taskId, `${task.kind === 'external-agent' ? 'External Agent' : 'External Workflow'} task "${task.name}"`);
         case 'wait-for-timer': {
             if (task.timer?.duration)
                 return { timerType: 'timeDuration', timeDuration: task.timer.duration };
@@ -1360,7 +1360,7 @@ function businessRuleTaskData(task, resolver, elementId, ids) {
  * the op's output schema. Connection/folder resolve through `bindings` and are
  * referenced as `=bindings.<id>`, with the binding entry collected at case root.
  */
-function connectorTaskData(spec, resolver, elementId, where) {
+function connectorTaskData(spec, resolver, elementId, where, executionType) {
     if (!resolver.library)
         throw new Error(`connector task needs the connector library — pass { library } to serialize or use uip maestro case compile --library.`);
     const rc = resolver.library.resolve(spec.key, spec.action, spec.version, spec.object);
@@ -1378,7 +1378,7 @@ function connectorTaskData(spec, resolver, elementId, where) {
     const folderRef = folderBindingRef(resolver, spec.folder, connRef, { attribute: 'folder', where, target });
     if (folderRef)
         context.push(io('folderKey', 'string', { value: `=bindings.${folderRef.id}` }));
-    context.push(io('objectName', 'string', { value: op.objectName ?? spec.action }), io('method', 'string', { value: transportHttpMethod(rc.httpMethod) }), io('path', 'string', { value: rc.endpoint }), io('metadata', 'json', { body: connectorMetadata(rc, op) }));
+    context.push(io('objectName', 'string', { value: op.objectName ?? spec.action }), io('method', 'string', { value: transportHttpMethod(rc.httpMethod) }), io('path', 'string', { value: rc.endpoint }), io('metadata', 'json', { body: connectorMetadata(rc, op, executionType) }));
     // inputs: the shared validator (`core/connector-inputs.ts`), the one Flow's and
     // BPMN's serializers and every family's `check` run. It refuses a missing
     // required field, an unknown or mistyped input, and swaps a `lookup()` token for
@@ -1412,66 +1412,35 @@ function connectorTaskData(spec, resolver, elementId, where) {
     const outputs = connectorOutputs(rc, elementId, resolver);
     return { serviceType: CASE_FORMAT_PROFILE.connectorActivityServiceType, context, inputs, outputs, bindings: [] };
 }
-function externalTaskData(kind, spec, resolver, where) {
+/**
+ * An External Agent / External Workflow task, in the shape the Case Designer
+ * saves one (`uip`'s `tests/fixtures/external-tasks/designer-saved.json`, alpha
+ * 2026-10-16): a connector activity's `data` — `connectorKey`, `connection`,
+ * `resourceKey`, `folderKey`, `objectName`, `method`, `path`, `metadata`
+ * context; `pathParameters` / `queryParameters` / `body` input containers;
+ * `response` + `Error` outputs — plus the object's `executionType` (in the
+ * context and in the metadata's configuration), `activityConfigurationVersion:
+ * "v2"`, and the sync or async service type that execution type gives.
+ */
+function externalTaskData(kind, spec, resolver, elementId, where) {
     if (!resolver.library)
         throw new Error(`${kind} task needs the connector library — pass { library } to serialize or use uip maestro case compile --library.`);
     const rc = resolver.library.resolve(spec.connector.key, spec.connector.action, spec.connector.version, spec.connector.object);
     const refused = externalDescriptorRefusal(kind, rc);
     if (refused)
         throw new Error(refused);
-    if (spec.mode !== 'sync' && spec.mode !== 'async')
-        throw new Error(`${kind} task mode must be "sync" or "async".`);
-    const target = { key: spec.connector.key, action: spec.connector.action };
-    const connection = bindingRef(resolver, spec.connector.connection, 'Connection', 'ConnectionId', `${rc.connectorKey} connection`, { attribute: 'connection', where, target });
-    const folder = folderBindingRef(resolver, spec.connector.folder, connection, { attribute: 'folder', where, target });
-    if (!connection || !folder)
+    if (!isExternalExecutionMode(spec.mode))
+        throw new Error(`${kind} task mode must be the connector object's executionType: "sync", "async" or "hybrid".`);
+    if (spec.mode === 'hybrid')
+        throw new Error(externalHybridRefusal(where));
+    if (!spec.connector.connection || !spec.connector.folder)
         throw new Error(`${kind} task requires non-empty connection and folder binding names.`);
-    const serviceType = kind === 'external-agent'
-        ? (spec.mode === 'sync'
-            ? CASE_FORMAT_PROFILE.externalAgentSyncServiceType
-            : CASE_FORMAT_PROFILE.externalAgentAsyncServiceType)
-        : (spec.mode === 'sync'
-            ? CASE_FORMAT_PROFILE.externalWorkflowSyncServiceType
-            : CASE_FORMAT_PROFILE.externalWorkflowAsyncServiceType);
-    // The inputs: the shared validator every connector activity runs (unknown,
-    // missing required or mistyped input; a `lookup()` swapped for its recorded id,
-    // or refused). Case `check` reports the same through `connectorInputs`.
-    const fields = new Map(rc.fields.map((field) => [field.name, field]));
-    const slots = buildConnectorInputs(rc, spec.connector.inputs, {
-        dialect: EQUALS_EXPR_DIALECT,
-        resolutions: resolver.library.lookupResolutions,
-        lookups: resolver.library.lookupSpecs(spec.connector.key, spec.connector.action, spec.connector.version, spec.connector.object),
-    });
-    const resolved = {
-        ...slots.bodyParameters, ...slots.pathParameters, ...slots.queryParameters,
-    };
-    const responseVar = connectorOutputVar(resolver, 'response');
-    return {
-        serviceType,
-        context: [
-            io('activity', 'string', { value: rc.activityTypeId }),
-            io('connectorKey', 'string', { value: rc.connectorKey }),
-            io('connection', 'string', { value: `=bindings.${connection.id}` }),
-            io('folderKey', 'string', { value: `=bindings.${folder.id}` }),
-            io('method', 'string', { value: transportHttpMethod(rc.httpMethod) }),
-            io('path', 'string', { value: rc.endpoint }),
-        ],
-        inputs: Object.entries(spec.connector.inputs).map(([name, value]) => ({
-            id: name,
-            name,
-            type: jsonType(fields.get(name)?.type),
-            value: name in resolved ? resolved[name] : value,
-            target: name,
-        })),
-        outputs: [{
-                id: responseVar,
-                name: 'response',
-                type: 'json',
-                source: '.',
-                var: responseVar,
-            }],
-        bindings: [],
-    };
+    const data = connectorTaskData(spec.connector, resolver, elementId, where, spec.mode);
+    const context = data.context;
+    const metadataAt = context.findIndex((row) => row.name === 'metadata');
+    context.splice(metadataAt, 0, io('executionType', 'string', { value: spec.mode }));
+    context.push(io('activityConfigurationVersion', 'string', { value: 'v2' }));
+    return { ...data, serviceType: externalServiceType(kind, spec.mode) };
 }
 /** A context/output name/value entry (the caseplan `InputOutput` shape). */
 function io(name, type, extra) {
@@ -1579,7 +1548,7 @@ function folderBindingRef(resolver, name, connection, site) {
 /** The connector `metadata` json blob: the FUNCTIONAL essentialConfiguration +
  * activityTypeId. Designer cosmetics (packageId/activityColor/…) are omitted —
  * the caseplan schema-validates without them (see design §C). */
-function connectorMetadata(rc, op) {
+function connectorMetadata(rc, op, executionType) {
     const instanceParameters = {
         connectorKey: rc.connectorKey,
         objectName: op.objectName ?? rc.nodeType.split('.').pop(),
@@ -1596,6 +1565,9 @@ function connectorMetadata(rc, op) {
             httpMethod: transportHttpMethod(rc.httpMethod),
             path: rc.endpoint,
             packageVersion: rc.version,
+            // An external task's object states how it runs; the Designer saves it here
+            // and beside the configuration. A plain connector activity has none.
+            ...(executionType ? { executionType } : {}),
         },
     };
     return {
@@ -1603,6 +1575,7 @@ function connectorMetadata(rc, op) {
             configuration: `=jsonString:${JSON.stringify(configuration)}`,
             uiPathActivityTypeId: rc.activityTypeId ?? '',
             errorState: { issues: [] },
+            ...(executionType ? { executionType } : {}),
         },
         activityMetadata: {
             activity: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.47.1",
+  "version": "6.47.2",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "05cde3ec95db903ec81d2df24fd4e60bade77a97"
+  "gitref": "16b96902c3da22af8e0fc3cfc8a53edcc832f04c"
 }