@uipath/maestro-builder-sdk 6.14.4 → 6.14.5

package/dist/compile-cli.js

@@ -36,20 +36,24 @@ function opt(argv, name) {
     return i >= 0 ? argv[i + 1] : undefined;
 }
 /**
- * The deployed-resource tool `type` values `compile` writes. NOT every
- * `$resourceType: 'tool'`: `uip agent refresh` generates the `integration` ones
- * from the flow's connector nodes into the same directory, so pruning by
- * `$resourceType` alone would delete the generator's own output.
+ * The tool `type` values `compile` writes. NOT every `$resourceType: 'tool'`:
+ * the designer writes kinds the SDK cannot derive into the same directory, so
+ * pruning by `$resourceType` alone would delete theirs.
+ *
+ * `integration` (connector tools) is compile's since #867: compile writes the
+ * file under the tool node's own `source` id, the same id and content `uip agent
+ * refresh --inline-in-flow` derives from that node, so a file under any other id
+ * belongs to a tool node the flow no longer has.
  */
 const COMPILE_OWNED_TOOL_TYPES = new Set([
-    'process', 'api', 'processOrchestration', 'flow', 'agent', 'function',
+    'process', 'api', 'processOrchestration', 'flow', 'agent', 'function', 'integration',
 ]);
 /**
  * Does `compile` own this resource file — i.e. would this run have written it,
  * so an unwritten one is stale rather than someone else's?
  *
- * Everything it says no to belongs to `uip agent refresh` (connector tools) or to
- * the designer (escalation, mcp, and the kinds the SDK cannot derive).
+ * Everything it says no to belongs to the designer (escalation, mcp, and the
+ * kinds the SDK cannot derive).
  */
 function compileOwnsResource(body) {
     const kind = body?.$resourceType;
@@ -236,7 +240,9 @@ export async function run(argv) {
             // fail on it. Keyed the way refresh keys it — an index by its name.
             const named = body?.indexName ?? body?.name;
             const key = typeof named === 'string' && named !== '' ? named : undefined;
-            if (key !== undefined) {
+            // A connector tool's binding is a `connection` row, and `mergeBindingsV2`
+            // re-derives every connection row from the flow below — nothing to retract.
+            if (key !== undefined && body?.type !== 'integration') {
                 // Keyed the way refresh keys it: an index by its name, a deployed-resource
                 // tool under `process` whatever its own type says.
                 staleBindings.push({ resource: resourceType === 'context' ? 'index' : 'process', key });

package/dist/core/actions.d.ts

@@ -1806,6 +1806,25 @@ export interface ConnectorToolRef {
     object?: string;
     /** Display label; defaults to the library's own (e.g. `'Create Issue'`). */
     name?: string;
+    /**
+     * What the agent is told the tool does — the runtime hands it to the MODEL.
+     * Defaults to the library's own operation description.
+     */
+    description?: string;
+    /**
+     * The connection's binding NAME in `bindings.json` — the same label
+     * `connector()`'s `connection` option takes (e.g. `'genai'`), resolved to
+     * the tenant connection id at compile. Required: a connector tool with no
+     * connection has nothing to call Integration Service with, and `check`
+     * reports `INLINE_AGENT_TOOL_CONNECTOR_NO_CONNECTION`.
+     */
+    connection?: string;
+    /**
+     * The connection's folder binding NAME in `bindings.json` (a `FolderKey`
+     * entry) — the same label `connector()`'s `folder` option takes. Required
+     * with `connection`.
+     */
+    folder?: string;
 }
 /**
  * The tool kinds that wrap a DEPLOYED tenant resource. `kind` picks the

package/dist/serialize.js

@@ -980,8 +980,9 @@ const TOOL_RESOURCE_TYPE = {
  *
  *  * `ixp`, `clientside` — measured to fail exactly that way (`ixp` leaves the
  *    flow failing validate; `clientside` drops the four inputs its node needs).
- *  * `connector` — `uip agent refresh` GENERATES it from the flow's connector
- *    node, reconstructing a whole `properties` block the SDK should not duplicate.
+ *  * `connector` — has its own writer, {@link connectorToolResourceJson}: its
+ *    node carries the configuration in `inputs.detail`, which the strip keeps,
+ *    and the file is the one `uip agent refresh` itself derives from it.
  *  * `mcp`, `a2a` — need the server's `availableTools` and the remote agent's
  *    card, which are tenant reads.
  *  * `builtin`, `httpRequest` — need a `properties.toolType` that maps
@@ -1202,6 +1203,225 @@ function connectorToolDef(rc) {
         inputDefaults: {},
     };
 }
+/** The folder key a connection with no folder binding carries in its resource.json. */
+const NO_FOLDER_KEY = '00000000-0000-0000-0000-000000000000';
+/**
+ * The library's operation description without the `(<Connector Name>) ` prefix
+ * the v1def's `display.description` carries — the model reads this text, and
+ * the designer's own resource.json has the bare sentence.
+ */
+function connectorToolDescription(rc) {
+    const text = String(rc.v1def?.display?.description ?? rc.entry?.display?.description ?? '');
+    const prefix = `(${rc.connectorName}) `;
+    return rc.connectorName && text.startsWith(prefix) ? text.slice(prefix.length) : text;
+}
+/** An agent-decided value: `{{prompt: "<what the model is told>"}}`. */
+function promptChip(f) {
+    const text = f.description || f.displayName || f.name;
+    return `{{prompt: "${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"}}`;
+}
+const isPromptChip = (v) => typeof v === 'string' && v.startsWith('{{prompt');
+/** The text inside `{{prompt: "…"}}`, unescaped; `''` for a bare `{{prompt}}`. */
+function chipText(value) {
+    const m = /\{\{\s*prompt:\s*"((?:[^"\\]|\\.)*)"/.exec(value);
+    return m ? m[1].replace(/\\(.)/g, '$1') : '';
+}
+/** A field's enum as `{ name, value }` rows, the platform's spelling; `undefined` when it has none. */
+function enumRows(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.map((e) => (typeof e === 'string'
+        ? { name: e, value: e }
+        : { name: String(e?.name ?? e?.value ?? ''), value: String(e?.value ?? e?.name ?? '') }));
+}
+/**
+ * The `inputs.detail` of a connector-tool node — the same key set a
+ * `connector()` step's node carries, with the request buckets filled the way
+ * `uip maestro flow node configure` fills them for a `tool.connector.*` node
+ * (uipcli `buildAgentToolParamsFromMetadata`): every BODY field is
+ * agent-decided (`{{prompt: "<description>"}}`) except a single-value enum,
+ * which is its one constant (the model would otherwise guess — `google` for
+ * `GoogleCustomSearch`); a QUERY/PATH parameter with a declared default sends
+ * it, and otherwise is agent-decided too.
+ */
+function connectorToolDetail(rc, conn, folder, seed) {
+    const params = Array.isArray(rc.entry?.operation?.parameters) ? rc.entry.operation.parameters : [];
+    const buckets = { body: {}, query: {}, path: {} };
+    for (const f of rc.fields ?? []) {
+        const loc = f.location ?? 'body';
+        if (loc === 'body') {
+            const only = enumRows(f.enum);
+            buckets.body[f.name] = only && only.length === 1 ? only[0].value : promptChip(f);
+        }
+        else if (loc === 'query' || loc === 'path') {
+            const dflt = params.find((p) => p?.name === f.name)?.defaultValue;
+            buckets[loc][f.name] = dflt !== undefined && dflt !== null && dflt !== '' ? dflt : promptChip(f);
+        }
+    }
+    const parts = rc.multipartParts ?? [];
+    return {
+        connector: rc.connectorKey,
+        method: transportHttpMethod(rc.httpMethod),
+        endpoint: rc.endpoint,
+        ...(rc.objectName ? { objectName: rc.objectName } : {}),
+        inputMetadata: parts.length
+            ? { type: 'multipart', multipart: { bodyFieldName: multipartBodyFieldName(parts) } }
+            : {},
+        errorState: { hasError: false },
+        telemetryData: { connectorKey: rc.connectorKey, connectorName: rc.connectorName },
+        configuration: buildConfiguration(rc.entry, rc.version, {}, seed),
+        ...(rc.activityTypeId ? { uiPathActivityTypeId: rc.activityTypeId } : {}),
+        ...(conn ? { connectionId: conn, connectionResourceId: conn } : {}),
+        ...(folder ? { connectionFolderKey: folder } : {}),
+        bodyParameters: buckets.body,
+        ...(Object.keys(buckets.path).length ? { pathParameters: buckets.path } : {}),
+        ...(Object.keys(buckets.query).length ? { queryParameters: buckets.query } : {}),
+        ...(parts.length ? { multipartParameters: parts.map((p) => ({ name: p.name, dataType: p.dataType })) } : {}),
+    };
+}
+/** Walk (creating) the object chain for a dotted field name; returns the parent schema and the leaf key. */
+function nestedSlot(root, name) {
+    const segments = name.split('.');
+    let parent = root;
+    for (const seg of segments.slice(0, -1)) {
+        let child = parent.properties[seg];
+        if (!child || child.type !== 'object') {
+            child = { type: 'object', properties: {} };
+            parent.properties[seg] = child;
+        }
+        parent = child;
+    }
+    return { parent, leaf: segments[segments.length - 1] };
+}
+/**
+ * The `resources/<id>/resource.json` of a CONNECTOR tool (#867) — the file the
+ * agent runtime registers the tool from, and the one that puts the connection
+ * under the solution's Resources.
+ *
+ * The shape is uipcli's `mapConnectorToolToResource` (the writer behind `uip
+ * agent refresh --inline-in-flow`, itself ported from flow-workbench's
+ * `agent-connector-tool` mapper), in its metadata-enriched form: field types,
+ * enums, `required` and the response fields come from the curated library,
+ * which carries the same declarations that command fetches from Integration
+ * Service. Where that writer and a Studio Web export differ, this follows the
+ * writer: `enum`/`oneOf` only on agent-decided fields (a static field with an
+ * enum breaks the runtime's model build), no `additionalProperties`, and
+ * array-of-object response fields (`results[*]`) left out.
+ *
+ * The values come from the node's own `detail` — the same source refresh reads —
+ * so a later refresh rewrites this file to itself.
+ */
+function connectorToolResourceJson(ctx, id) {
+    const { rc, detail } = ctx;
+    const valueOf = (raw) => raw !== null && typeof raw === 'object' ? JSON.stringify(raw) : String(raw ?? '');
+    const bucketOf = { body: 'bodyParameters', query: 'queryParameters', path: 'pathParameters' };
+    const fields = [];
+    for (const f of rc.fields ?? []) {
+        const loc = f.location ?? 'body';
+        if (loc === 'multipart')
+            continue;
+        const value = valueOf(detail[bucketOf[loc]]?.[f.name]);
+        fields.push({
+            name: f.name,
+            fieldLocation: loc,
+            type: f.type || 'string',
+            ...(loc === 'body' && enumRows(f.enum)
+                ? { enumValues: enumRows(f.enum) } : {}),
+            required: f.required === true,
+            description: f.description ?? '',
+            ...(f.displayName ? { displayName: f.displayName } : {}),
+            value,
+            isPrompt: isPromptChip(value),
+        });
+    }
+    for (const part of (detail.multipartParameters ?? [])) {
+        fields.push({
+            name: part.name, fieldLocation: 'multipart', type: part.dataType || 'string',
+            required: false, description: '', value: '{{prompt}}', isPrompt: true,
+        });
+    }
+    const inputSchema = { type: 'object', properties: {} };
+    for (const f of fields) {
+        if (f.fieldLocation === 'multipart')
+            continue;
+        const { parent, leaf } = nestedSlot(inputSchema, f.name);
+        const prop = { type: f.type, title: f.displayName ?? leaf, description: f.description };
+        if (f.isPrompt && f.enumValues) {
+            prop.enum = f.enumValues.map((e) => e.value);
+            prop.oneOf = f.enumValues.map((e) => ({ const: e.value, title: e.name }));
+        }
+        parent.properties[leaf] = prop;
+        if (f.required)
+            (parent.required ??= []).push(leaf);
+    }
+    const outputSchema = { type: 'object', properties: {}, definitions: {} };
+    for (const f of (rc.entry?.outputSchema?.fields ?? [])) {
+        if (typeof f?.name !== 'string' || f.name.includes('[*]'))
+            continue;
+        const { parent, leaf } = nestedSlot(outputSchema, f.name);
+        parent.properties[leaf] = {
+            type: f.type || 'string',
+            title: f.displayName ?? leaf,
+            ...(f.description ? { description: f.description } : {}),
+        };
+    }
+    const multipart = detail.inputMetadata?.type === 'multipart';
+    return {
+        $resourceType: 'tool',
+        name: ctx.name,
+        description: ctx.description,
+        location: 'external',
+        type: 'integration',
+        inputSchema,
+        outputSchema,
+        settings: {},
+        properties: {
+            toolPath: rc.endpoint ?? '',
+            objectName: rc.objectName ?? '',
+            toolDisplayName: ctx.name,
+            toolDescription: ctx.description,
+            // The operation KEY (`GETBYID` for a get-by-id), not the transport verb:
+            // the runtime sends it to Integration Service to pick the operation.
+            method: rc.httpMethod,
+            connection: {
+                id: detail.connectionId ?? '',
+                name: rc.connectorName,
+                elementInstanceId: 0,
+                apiBaseUri: '',
+                state: 'enabled',
+                isDefault: false,
+                connector: { key: rc.connectorKey, name: rc.connectorName, image: '' },
+                folder: { key: detail.connectionFolderKey ?? NO_FOLDER_KEY, path: '' },
+            },
+            parameters: fields.map((f, i) => ({
+                name: f.name,
+                displayName: f.displayName ?? f.name,
+                type: f.type,
+                fieldLocation: f.fieldLocation,
+                value: f.value,
+                // uipcli's fallback: an undescribed agent-decided field keeps the chip's own text.
+                description: f.description || (f.isPrompt ? chipText(f.value) : ''),
+                position: f.required ? 'primary' : 'secondary',
+                sortOrder: i + 1,
+                required: f.required,
+                fieldVariant: f.isPrompt ? 'dynamic' : 'static',
+                isCascading: false,
+                dynamic: f.isPrompt,
+                enumValues: f.enumValues ?? null,
+                loadReferenceOptionsByDefault: null,
+                dynamicBehavior: [],
+                reference: null,
+            })),
+            bodyStructure: multipart
+                ? { contentType: 'multipart', jsonBodySection: detail.inputMetadata.multipart?.bodyFieldName ?? 'body' }
+                : { contentType: 'json' },
+        },
+        guardrail: { policies: [] },
+        iconUrl: ctx.iconUrl,
+        id,
+        isEnabled: true,
+    };
+}
 /**
  * The tool kinds that wrap a DEPLOYED tenant resource, and everything that
  * differs between them. Transcribed from `registry get` over one live example
@@ -4712,6 +4932,7 @@ export function serialize(built, opts = {}) {
                 let tdef;
                 let label;
                 let extraInputs = {};
+                let connectorTool;
                 if (tr.kind === 'builtin') {
                     tdef = clone(BUILTIN_TOOL_DEFS[tr.tool]);
                     if (!tdef)
@@ -4754,10 +4975,33 @@ export function serialize(built, opts = {}) {
                     const rc = opts.library.resolve(tr.connector, tr.operation, tr.version, tr.object);
                     tdef = connectorToolDef(rc);
                     label = tr.name ?? rc.v1def?.display?.label ?? tr.operation;
-                    // The connector tool's configuration (connection, folder) is bound at
-                    // the agent/solution layer, not on the node: the deployed corpus
-                    // carries `inputs: {}` and a top-level `bindings: []` even for a
-                    // connector tool, so nothing is emitted here beyond the identity.
+                    // The connection rides the same three places it does for a
+                    // `connector()` step, because the platform reads it from the same
+                    // three (#867):
+                    //  * the node's `inputs.detail` — what `uip maestro flow node configure`
+                    //    writes on a `tool.connector.*` node, what `uip agent refresh
+                    //    --inline-in-flow` builds the tool's resource.json FROM, and what
+                    //    its shell-ify pass keeps ("where a connector tool's request config
+                    //    lives"). It is also what `bindings_v2.json` is derived from.
+                    //  * the top-level `bindings[]` pair the def's `model.context`
+                    //    placeholders (`<bindings.… connection>` / `<bindings.FolderKey>`)
+                    //    name.
+                    //  * the agent's `resources/<id>/resource.json` (below).
+                    // Emitting none of them left the tool with no connection anywhere.
+                    const where = `inline agent "${step.name}"'s connector tool "${tr.connector}/${tr.operation}"`;
+                    const target = { key: tr.connector, action: tr.operation };
+                    const conn = resolveBinding(opts, tr.connection, 'connection', where, target);
+                    const folder = resolveBinding(opts, tr.folder, 'folder', where, target);
+                    const { entries: connBindings } = connectionResourceBindings({ def: rc.v1def, connectorKey: rc.connectorKey, connectionId: conn, folderKey: folder }, resourceBindings);
+                    for (const b of connBindings)
+                        resourceBindings.set(b.id, b);
+                    const detail = connectorToolDetail(rc, conn, folder, `${step.name}Tool`);
+                    extraInputs = { detail };
+                    connectorTool = {
+                        rc, detail, name: label,
+                        description: tr.description ?? connectorToolDescription(rc),
+                        iconUrl: String(tdef.display?.icon ?? ''),
+                    };
                 }
                 else if (tr.kind === 'mcp') {
                     // Per-instance def minted like the ixp family's; the node carries the
@@ -4837,6 +5081,10 @@ export function serialize(built, opts = {}) {
                 const tid = uid(scope, `${step.name}Tool`);
                 const tnode = makeNode(tdef.nodeType, tid, label, { parentId, def: tdef });
                 tnode.display = { ...tnode.display, shape: 'circle' };
+                // `uip agent refresh` reads the tool's description off the node's display
+                // first, so the node carries the one the resource.json does.
+                if (connectorTool)
+                    tnode.display.description = connectorTool.description;
                 // The resource model lives on the DEFINITION only (CX's rule for
                 // context, and what the deployed corpus carries for tools).
                 delete tnode.model;
@@ -4855,8 +5103,10 @@ export function serialize(built, opts = {}) {
                 addEdge(scope, { node: id, port: 'tool' }, tid, 'input');
                 // The other half, for the kinds whose file is DERIVABLE — see
                 // `toolResourceJson` for which are not, and why each is left to the
-                // generator or the designer rather than guessed.
-                const toolResource = toolResourceJson(tr, { id: toolResourceId });
+                // designer rather than guessed.
+                const toolResource = connectorTool
+                    ? connectorToolResourceJson(connectorTool, toolResourceId)
+                    : toolResourceJson(tr, { id: toolResourceId });
                 if (toolResource !== undefined) {
                     sidecars.push({
                         path: `${source}/resources/${toolResourceId}/resource.json`,

package/lib/README.md

@@ -90,6 +90,7 @@ points at the materialized `library-json/`. Until you unpack, only
 | `uipath-atlassian-jira` | `create-issue` | `fields.project.key`, `fields.summary` |
 | `uipath-salesforce-slack` | `send-message-to-user` | `channel`, `messageToSend` |
 | `uipath-microsoft-outlook365` | `send-email` | `message.toRecipients` |
+| `uipath-uipath-airdk` | `web-search` | `query` — the inline-agent connector-tool fixture (#867) |
 
 ## Refreshing the shipped library (needs an authenticated `uip`)
 

package/lib/library-json.samples/index.json

@@ -163,6 +163,15 @@
       "objectName": "send_message_to_user_v2",
       "path": "uipath-salesforce-slack/send-message-to-user@1.0.0.json"
     },
+    {
+      "nodeType": "uipath.connector.uipath-uipath-airdk.web-search",
+      "version": "1.0.0",
+      "connectorKey": "uipath-uipath-airdk",
+      "label": "Web Search",
+      "activityType": "Curated",
+      "objectName": "v2::webSearch",
+      "path": "uipath-uipath-airdk/web-search@1.0.0.json"
+    },
     {
       "nodeType": "uipath.connector.uipath-uipath-dataservice.query-entity-records",
       "version": "1.0.0",

package/lib/library-json.samples/uipath-uipath-airdk/web-search@1.0.0.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": "1",
+  "nodeType": "uipath.connector.uipath-uipath-airdk.web-search",
+  "version": "1.0.0",
+  "category": "connector.196640",
+  "tags": [
+    "connector",
+    "activity"
+  ],
+  "connector": {
+    "key": "uipath-uipath-airdk",
+    "name": "UiPath GenAI Activities"
+  },
+  "operation": {
+    "name": "Create",
+    "objectName": "v2::webSearch",
+    "objectDisplayName": "Web Search",
+    "httpMethod": "POST",
+    "path": "/v2/webSearch",
+    "subType": "standard",
+    "supportsStreaming": false,
+    "activityType": "Curated",
+    "pathTemplate": "/v2/webSearch"
+  },
+  "display": {
+    "label": "Web Search",
+    "description": "(UiPath GenAI Activities) Web search executes a search of the public domain using a natural language search query. The search results are available in the output. Web search offers near-real time search results, but certain time sensitive data like stock prices or weather will not consistently be current. There could be a few days lag. Be sure to pass in date/time and/or location as arguments in the query if required.",
+    "icon": "https://alpha.uipath.com/bc2ddac5-57bc-40e6-93fe-3b319b60ce36/studio_/typecache/icons/d93eefff0af32b964a4ce6fe3823de1d4c7ed71962c6f878520b57ebf8f4497a.svg",
+    "iconBackground": "linear-gradient(225deg, #FAFAFB 0%, #ECEDEF 100%)",
+    "iconBackgroundDark": "linear-gradient(225deg, #526069 0%, rgba(50, 60, 66, 0.6) 100%)",
+    "operationLabel": "Web Search"
+  },
+  "runtime": {
+    "bpmnType": "bpmn:SendTask",
+    "serviceType": "Intsvc.ActivityExecution",
+    "activityConfigurationVersion": "v1",
+    "requiresConnection": true,
+    "requiresFolderKey": true,
+    "requiresConnectionForSchema": false
+  },
+  "inputSchema": {
+    "fields": [
+      {
+        "name": "provider",
+        "type": "string",
+        "displayName": "Search Engine",
+        "description": "The search engine to use",
+        "enum": [
+          "GoogleCustomSearch"
+        ],
+        "required": true
+      },
+      {
+        "name": "query",
+        "type": "string",
+        "displayName": "Search",
+        "description": "The natural language query to search the web for",
+        "required": true
+      },
+      {
+        "name": "num",
+        "type": "integer",
+        "displayName": "Number of results",
+        "description": "The number of results. Default to 10.",
+        "required": false
+      },
+      {
+        "name": "start",
+        "type": "integer",
+        "displayName": "Start",
+        "description": "First result index (pagination).",
+        "required": false
+      },
+      {
+        "name": "siteSearch",
+        "type": "string",
+        "displayName": "Site Search",
+        "description": "Restrict or exclude results for a domain.",
+        "required": false
+      },
+      {
+        "name": "siteSearchFilter",
+        "type": "string",
+        "displayName": "Site Search Filter",
+        "description": "Either \"i\" (include) or \"e\" (exclude).",
+        "required": false
+      }
+    ]
+  },
+  "outputSchema": {
+    "fields": [
+      {
+        "name": "formattedResults",
+        "type": "string",
+        "displayName": "FormattedResults",
+        "description": "The search results string containing title, URL, and snippet"
+      },
+      {
+        "name": "results[*].title",
+        "type": "string",
+        "displayName": "Result title",
+        "description": "The title of a search result item."
+      },
+      {
+        "name": "results[*].snippet",
+        "type": "string",
+        "displayName": "Result snippet",
+        "description": "A brief summary or excerpt of a search result item."
+      },
+      {
+        "name": "results[*].url",
+        "type": "string",
+        "displayName": "Result url",
+        "description": "The web address of the search result."
+      }
+    ]
+  }
+}