@uipath/maestro-builder-sdk 6.30.3 → 6.30.4

package/dist/core/context-index.d.ts

@@ -32,3 +32,21 @@ export declare function parseContextIndexType(type: string): {
     slug: string;
     id: string;
 } | undefined;
+/**
+ * The retrieval settings an index gets when the author sets none: what
+ * `contextResourceJson` (serialize.ts) writes into `resource.json` `settings`, and
+ * what decompile leaves out of the source because compile would write it anyway.
+ */
+export declare const CONTEXT_INDEX_DEFAULTS: {
+    readonly retrievalMode: "semantic";
+    readonly threshold: 0;
+    readonly resultCount: 3;
+};
+/**
+ * The file extension each retrieval mode accepts by default. The platform's
+ * manifest defaults every mode's NODE to `All`, but its resource schema pins
+ * `structured`/`batchtransform` to `csv` and `deeprag` to `pdf`/`txt` — so a
+ * flat `All` default would emit a resource the platform refuses to parse for
+ * every mode but `semantic`.
+ */
+export declare const CONTEXT_INDEX_DEFAULT_FILE_EXTENSION: Readonly<Record<string, string>>;

package/dist/core/context-index.js

@@ -36,3 +36,22 @@ export function parseContextIndexType(type) {
     const dot = tail.lastIndexOf('.');
     return dot < 0 ? { slug: tail, id: '' } : { slug: tail.slice(0, dot), id: tail.slice(dot + 1) };
 }
+/**
+ * The retrieval settings an index gets when the author sets none: what
+ * `contextResourceJson` (serialize.ts) writes into `resource.json` `settings`, and
+ * what decompile leaves out of the source because compile would write it anyway.
+ */
+export const CONTEXT_INDEX_DEFAULTS = { retrievalMode: 'semantic', threshold: 0, resultCount: 3 };
+/**
+ * The file extension each retrieval mode accepts by default. The platform's
+ * manifest defaults every mode's NODE to `All`, but its resource schema pins
+ * `structured`/`batchtransform` to `csv` and `deeprag` to `pdf`/`txt` — so a
+ * flat `All` default would emit a resource the platform refuses to parse for
+ * every mode but `semantic`.
+ */
+export const CONTEXT_INDEX_DEFAULT_FILE_EXTENSION = {
+    semantic: 'All',
+    structured: 'csv',
+    deeprag: 'pdf',
+    batchtransform: 'csv',
+};

package/dist/decompile.d.ts

@@ -144,9 +144,11 @@ export interface DecompileOptions {
      * (`{{input.start__output__notes}}`), so the recovered source declares its
      * inputs under those names — the same flow, not the same spelling. Without a
      * reader, a shell agent decompiles with empty prompts and a warning.
-     * A context index placed by the canvas or the CLI keeps its real name and
-     * folder only in `<agent source>/resources/<inputs.source>/resource.json`,
-     * which is read the same way.
+     * A context index placed by the canvas or the CLI keeps its real name,
+     * folder and retrieval `settings` (mode, query, threshold, result count, file
+     * extension) only in `<agent source>/resources/<inputs.source>/resource.json`,
+     * which is read the same way. A setting `context: [...]` cannot express is
+     * reported through `warn` (an error when `bestEffort` is false).
      */
     readSidecar?: (relativePath: string) => string | undefined;
 }

package/dist/decompile.js

@@ -36,7 +36,8 @@ import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { SUBFLOW_START_LABEL } from './core/subflow-start.js';
 import { commentText } from './core/comment-text.js';
 import { tsLiteral, tsNumber, tsText } from './core/ts-literal.js';
-import { contextIndexSlug, parseContextIndexType } from './core/context-index.js';
+import { ownEntry } from './core/own-entry.js';
+import { CONTEXT_INDEX_DEFAULTS, CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, contextIndexSlug, parseContextIndexType, } from './core/context-index.js';
 import { wireExprBody } from './core/wire-expr.js';
 import { hasExits } from './core/step-ports.js';
 import { parseIxpProjectType } from './core/actions.js';
@@ -914,7 +915,146 @@ function contextIndexIdentity(agent, c, rPlain) {
             + `will write a different node type. Set \`name\` to the index's real name`
             + (sidecar === undefined ? ', or keep the resources/ folder beside the .flow so decompile can read it.' : '.'));
     }
-    return { name, id, folderPath: rPlain(c, 'folderPath') ?? sidecarText('folderPath') };
+    return { name, id, folderPath: rPlain(c, 'folderPath') ?? sidecarText('folderPath'), sidecar };
+}
+/** The retrieval modes `ContextIndexRef.retrievalMode` can hold. */
+const CONTEXT_RETRIEVAL_MODES = new Set(['semantic', 'structured', 'deeprag', 'batchtransform']);
+/** The `settings` keys of a context `resource.json` that {@link contextIndexSettings} reads or checks. */
+const CONTEXT_SETTINGS_KEYS = new Set([
+    'retrievalMode', 'query', 'folderPathPrefix', 'threshold', 'resultCount', 'fileExtension',
+    'citationMode', 'webSearchGrounding', 'outputColumns',
+]);
+/**
+ * A context index's retrieval settings, as the `context: [...]` entry's option
+ * rows (`retrievalMode`, `query`, `threshold`, `resultCount`, `fileExtension`),
+ * each left out when it is what compile writes anyway.
+ *
+ * The inverse of `contextResourceJson` (serialize.ts). Read from the sidecar's
+ * `settings` first: a node the canvas or the CLI placed keeps its inputs minimal
+ * (`inputs.source`), so `resource.json` is the only copy, and it is what the
+ * runtime reads. The node's own inputs (the SDK writes both) answer when there
+ * is no sidecar. Before #1183 neither was read, so a no-edit round trip reset
+ * every setting to the SDK default without a word.
+ *
+ * The query is variant-tagged in the sidecar and mode-tagged on the node:
+ *
+ *  - `dynamic` / `prompt` → a plain string (the guidance the model reads);
+ *  - `static` / `text-builder` whose text is a `=js:` expression → that
+ *    expression, which compile writes back as `text-builder` / `static`;
+ *  - `static` with `''` is the canvas's spelling of "no query", as the SDK's
+ *    `dynamic` with `''` is: left out.
+ *
+ * A setting the SDK cannot express (a `static` query of plain text, an
+ * `argument` query, deeprag citations off, batchtransform web grounding off or
+ * output columns, a folder-path prefix, an unknown mode or key) is reported:
+ * a warning, or an error under `--strict`. Compile would write the SDK's
+ * value instead, so it is never dropped silently.
+ */
+function contextIndexSettings(agent, c, sidecar) {
+    const settings = sidecar?.settings && typeof sidecar.settings === 'object' && !Array.isArray(sidecar.settings)
+        ? sidecar.settings : undefined;
+    const ni = (c.inputs ?? {});
+    const where = `context index "${c.id}" on agent "${agent.id}"`;
+    const lossy = (what) => {
+        const message = `${where}: ${what}, which \`context: [...]\` cannot express, so compile writes the SDK's `
+            + `value instead. Edit that setting in the canvas after merging, or keep the original resource.json.`;
+        if (runStrict)
+            throw new Error(`decompile: ${message}`);
+        warnOnce(message);
+    };
+    const textOf = (v) => (typeof v === 'string' ? v : undefined);
+    const numOf = (v) => {
+        const raw = unwrapPlain(v);
+        return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+    };
+    const valueOf = (v) => (v && typeof v === 'object' ? v.value : undefined);
+    // Retrieval mode.
+    const rawMode = textOf(settings?.retrievalMode) ?? textOf(unwrapSource(ni.retrievalMode));
+    let mode = CONTEXT_INDEX_DEFAULTS.retrievalMode;
+    if (rawMode !== undefined && rawMode !== '') {
+        if (CONTEXT_RETRIEVAL_MODES.has(rawMode))
+            mode = rawMode;
+        else
+            lossy(`its retrieval mode is ${JSON.stringify(rawMode)}`);
+    }
+    const sidecarQuery = (() => {
+        const q = settings?.query;
+        if (!q || typeof q !== 'object')
+            return undefined;
+        if (q.variant === 'dynamic')
+            return { kind: 'prompt', text: textOf(q.description) ?? '' };
+        if (q.variant === 'static')
+            return { kind: 'text', text: textOf(q.value) ?? '' };
+        if (q.variant === 'argument')
+            return { kind: 'argument', text: textOf(q.value) ?? '' };
+        lossy(`its query has variant ${JSON.stringify(q.variant)}`);
+        return undefined;
+    })();
+    const nodeQuery = (() => {
+        const q = ni.query;
+        if (typeof q === 'string')
+            return q === '' ? undefined : { kind: q.startsWith('=js:') ? 'text' : 'prompt', text: q };
+        if (!q || typeof q !== 'object')
+            return undefined;
+        const t = q;
+        if (t.mode === 'text-builder')
+            return { kind: 'text', text: textOf(t.textValue) ?? '' };
+        if (t.mode === 'variable')
+            return { kind: 'argument', text: textOf(t.argumentPath) ?? '' };
+        return { kind: 'prompt', text: textOf(t.promptValue) ?? '' };
+    })();
+    const query = sidecarQuery ?? nodeQuery;
+    let querySrc;
+    if (query?.kind === 'prompt' && query.text !== '')
+        querySrc = tsLiteral(query.text);
+    else if (query?.kind === 'text' && query.text.startsWith('=js:'))
+        querySrc = tsLiteral(query.text);
+    else if (query?.kind === 'text' && query.text !== '')
+        lossy(`its query is static text (${JSON.stringify(query.text)})`);
+    else if (query?.kind === 'argument')
+        lossy(`its query is the agent argument ${JSON.stringify(query.text)}`);
+    // Numbers and the file extension.
+    const threshold = numOf(settings?.threshold) ?? numOf(ni.threshold);
+    const resultCount = numOf(settings?.resultCount) ?? numOf(ni.resultCount);
+    const fileExtension = textOf(valueOf(settings?.fileExtension)) ?? textOf(unwrapSource(ni.fileExtension));
+    // The node's flat `All` is the platform's node default for every mode; only
+    // the resource's per-mode default is what compile would write anyway.
+    const defaultExtension = ownEntry(CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, mode) ?? 'All';
+    const extensionSrc = fileExtension === undefined || fileExtension === '' || fileExtension === defaultExtension
+        || (settings?.fileExtension === undefined && fileExtension === 'All')
+        ? undefined : tsLiteral(fileExtension);
+    // What compile writes as constants; anything else has no field.
+    if (mode === 'deeprag') {
+        const citation = textOf(valueOf(settings?.citationMode)) ?? textOf(unwrapSource(ni.citations));
+        if (citation !== undefined && !['Inline', 'enabled'].includes(citation))
+            lossy(`its citation mode is ${JSON.stringify(citation)}`);
+    }
+    if (mode === 'batchtransform') {
+        const grounding = textOf(valueOf(settings?.webSearchGrounding)) ?? textOf(valueOf(ni.webSearchGrounding));
+        if (grounding !== undefined && !['Enabled', 'enabled'].includes(grounding))
+            lossy(`its web search grounding is ${JSON.stringify(grounding)}`);
+        const columns = settings?.outputColumns ?? ni.outputColumns;
+        if (Array.isArray(columns) && columns.length > 0)
+            lossy(`it has ${columns.length} output column(s)`);
+    }
+    // The folder-path prefix: variant-tagged in the sidecar, mode-tagged on the node.
+    const field = (v, k) => (v && typeof v === 'object' ? textOf(v[k]) : undefined);
+    const prefixText = settings?.folderPathPrefix !== undefined
+        ? field(settings.folderPathPrefix, 'value') ?? field(settings.folderPathPrefix, 'description') ?? ''
+        : field(ni.folderPathPrefix, 'textValue') ?? field(ni.folderPathPrefix, 'promptValue') ?? '';
+    if (prefixText !== '')
+        lossy(`its folder-path prefix is ${JSON.stringify(prefixText)}`);
+    for (const k of Object.keys(settings ?? {})) {
+        if (!CONTEXT_SETTINGS_KEYS.has(k))
+            lossy(`its resource.json settings carry ${JSON.stringify(k)}`);
+    }
+    return [
+        ['query', querySrc],
+        ['retrievalMode', mode !== CONTEXT_INDEX_DEFAULTS.retrievalMode ? tsLiteral(mode) : undefined],
+        ['threshold', threshold !== undefined && threshold !== CONTEXT_INDEX_DEFAULTS.threshold ? tsNumber(threshold) : undefined],
+        ['resultCount', resultCount !== undefined && resultCount !== CONTEXT_INDEX_DEFAULTS.resultCount ? tsNumber(resultCount) : undefined],
+        ['fileExtension', extensionSrc],
+    ];
 }
 /**
  * A context resource's `resource.json` sidecar, parsed; `undefined` when it is
@@ -1136,21 +1276,14 @@ function emitAgentCluster(node, imp, inputNames, graph) {
         return opts([['kind', tsLiteral('builtin')], ['tool', tsLiteral('summarize')]]); // unreachable in practice
     });
     const contextSrc = resource('context').map((c) => {
-        // `query` is a MODE TRIPLE, not a string: the author's value lands in
-        // `promptValue` (prompt mode) or `textValue` (text-builder). Reading the
-        // field itself finds an object and silently recovers nothing.
-        const q = rInputs(c).query;
-        const queryText = typeof q?.promptValue === 'string' && q.promptValue !== '' ? q.promptValue
-            : typeof q?.textValue === 'string' && q.textValue !== '' ? q.textValue
-                : typeof q === 'string' && q !== '' ? q
-                    : undefined;
-        const { name, id, folderPath } = contextIndexIdentity(node, c, rPlain);
+        const { name, id, folderPath, sidecar } = contextIndexIdentity(node, c, rPlain);
         return opts([
             ['name', tsLiteral(name)],
             ['id', tsLiteral(id)],
             ['folderPath', folderPath !== undefined ? tsLiteral(folderPath) : undefined],
             ['folderKey', rPlain(c, 'folderKey') !== undefined ? tsLiteral(rPlain(c, 'folderKey')) : undefined],
-            ['query', queryText !== undefined ? tsLiteral(queryText) : undefined],
+            // `query` and the retrieval settings, from resource.json or the node (#1183).
+            ...contextIndexSettings(node, c, sidecar),
         ]);
     });
     const escalationSrc = resource('escalation').map((e) => {

package/dist/serialize.js

@@ -10,7 +10,7 @@ import ixpDefinition from './ixp-definition.json' with { type: 'json' };
 import { BUNDLED_DEFINITIONS, bundledVersions } from './flow-definitions.js';
 import { Expr, toExpr, SCHEDULE_PRESETS, parseIxpProjectType, flatNameOf, flatNameSegmentsOf } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
-import { contextIndexType } from './core/context-index.js';
+import { CONTEXT_INDEX_DEFAULTS, CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, contextIndexType } from './core/context-index.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { rawNodeInputProblem, registeredRawType } from './raw-node-advice.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
@@ -855,19 +855,6 @@ function renderContextQuery(query, rename) {
     }
     return { ...base, promptValue: asText };
 }
-/**
- * The file extension each retrieval mode accepts by default. The platform's
- * manifest defaults every mode's NODE to `All`, but its resource schema pins
- * `structured`/`batchtransform` to `csv` and `deeprag` to `pdf`/`txt` — so a
- * flat `All` default would emit a resource the platform refuses to parse for
- * every mode but `semantic`.
- */
-const DEFAULT_FILE_EXTENSION = {
-    semantic: 'All',
-    structured: 'csv',
-    deeprag: 'pdf',
-    batchtransform: 'csv',
-};
 /**
  * The `resources/<id>/resource.json` an inline agent's context index needs.
  *
@@ -891,7 +878,7 @@ const DEFAULT_FILE_EXTENSION = {
  * every other binding with it.
  */
 function contextResourceJson(cx, spec) {
-    const mode = cx.retrievalMode ?? 'semantic';
+    const mode = cx.retrievalMode ?? CONTEXT_INDEX_DEFAULTS.retrievalMode;
     return {
         $resourceType: 'context',
         id: spec.id,
@@ -920,10 +907,12 @@ function contextResourceJson(cx, spec) {
             query: spec.query.mode === 'text-builder'
                 ? { variant: 'static', value: String(spec.query.textValue ?? '') }
                 : { variant: 'dynamic', description: String(spec.query.promptValue ?? '') },
-            folderPathPrefix: { variant: 'static' },
-            threshold: cx.threshold ?? 0,
-            resultCount: cx.resultCount ?? 3,
-            fileExtension: { value: cx.fileExtension ?? ownEntry(DEFAULT_FILE_EXTENSION, mode) ?? 'All' },
+            // `value: ''`, as the canvas writes it (flow-workbench `mapContextQueryToWire`
+            // always sets the value), so a canvas index's resource round-trips unchanged.
+            folderPathPrefix: { variant: 'static', value: '' },
+            threshold: cx.threshold ?? CONTEXT_INDEX_DEFAULTS.threshold,
+            resultCount: cx.resultCount ?? CONTEXT_INDEX_DEFAULTS.resultCount,
+            fileExtension: { value: cx.fileExtension ?? ownEntry(CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, mode) ?? 'All' },
             // Mode-specific keys the schema REQUIRES of those two modes and rejects
             // nowhere else, carrying the node's own constants through the enum's
             // spelling (the node says `enabled`; the resource says `Enabled`/`Inline`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.30.3",
+  "version": "6.30.4",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "cdac1f9944a11065ba6cc13061a0873f53683358"
+  "gitref": "09ce362aa97a2af0513e0c5883ccaa032df52a4a"
 }