@uipath/maestro-builder-sdk 6.30.3 → 6.31.0

package/dist/bindings-v2-files.d.ts

@@ -0,0 +1,5 @@
+import type { BindingsV2Document, InlineAgentFiles } from './bindings-v2.js';
+/** Read a `bindings_v2.json`, or `undefined` when absent or unparseable. */
+export declare function readBindingsV2(path: string): BindingsV2Document | undefined;
+/** Read one inline agent's directory the way refresh does; `undefined` when it has no readable `agent.json`. */
+export declare function readInlineAgentFiles(agentDir: string): InlineAgentFiles | undefined;

package/dist/bindings-v2-files.js

@@ -0,0 +1,49 @@
+/**
+ * Reading `bindings_v2.json` and an inline agent's directory from disk, for
+ * `compile-cli`. Apart from `bindings-v2.ts`, whose derivations `serialize` uses,
+ * so serializing a flow loads no `node:fs`.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from './core/node-envelope.js';
+/** Read a `bindings_v2.json`, or `undefined` when absent or unparseable. */
+export function readBindingsV2(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        // A hand-broken sidecar should not fail the compile; it is regenerated below.
+        return undefined;
+    }
+}
+/** Read one inline agent's directory the way refresh does; `undefined` when it has no readable `agent.json`. */
+export function readInlineAgentFiles(agentDir) {
+    let agent;
+    try {
+        agent = JSON.parse(readFileSync(join(agentDir, 'agent.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const read = (sub, file, tag) => {
+        const dir = join(agentDir, sub);
+        if (!existsSync(dir))
+            return [];
+        const out = [];
+        for (const entry of readdirSync(dir).sort()) {
+            try {
+                const body = JSON.parse(readFileSync(join(dir, entry, file), 'utf8'));
+                if (isRecord(body) && body[tag])
+                    out.push(body);
+            }
+            catch {
+                // Refresh skips a malformed or missing file the same way.
+            }
+        }
+        return out;
+    };
+    return { agent, resources: read('resources', 'resource.json', '$resourceType'), features: read('features', 'feature.json', '$featureType') };
+}

package/dist/bindings-v2.d.ts

@@ -59,8 +59,6 @@ export declare function connectionResources(flow: unknown): BindingsV2Resource[]
  * had put there.
  */
 export declare function mergeBindingsV2(existing: unknown, connections: BindingsV2Resource[]): BindingsV2Document;
-/** Read a `bindings_v2.json`, or `undefined` when absent or unparseable. */
-export declare function readBindingsV2(path: string): BindingsV2Document | undefined;
 /** The files of one inline agent, as `uip agent refresh` reads them. */
 export interface InlineAgentFiles {
     /** `<agent>/agent.json`. */
@@ -116,5 +114,3 @@ export declare function mergeInlineAgentResources(existing: BindingsV2Resource[]
  * @returns The rows to write.
  */
 export declare function refreshInlineAgentRows(resources: BindingsV2Resource[], agents: InlineAgentFiles[], removedResources: unknown[]): BindingsV2Resource[];
-/** Read one inline agent's directory the way refresh does; `undefined` when it has no readable `agent.json`. */
-export declare function readInlineAgentFiles(agentDir: string): InlineAgentFiles | undefined;

package/dist/bindings-v2.js

@@ -53,8 +53,6 @@
  * PRESERVED untouched and never invented ({@link mergeBindingsV2},
  * {@link mergeInlineAgentResources}).
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { BindingRefusal, connectionConnectorConflictMessage } from './core/binding-messages.js';
 import { isRecord } from './core/node-envelope.js';
 /** The document version pack emits. */
@@ -255,19 +253,6 @@ export function mergeBindingsV2(existing, connections) {
     const version = (isRecord(existing) && nonEmptyString(existing.version)) || DOCUMENT_VERSION;
     return { version, resources: [...connections, ...preserved] };
 }
-/** Read a `bindings_v2.json`, or `undefined` when absent or unparseable. */
-export function readBindingsV2(path) {
-    if (!existsSync(path))
-        return undefined;
-    try {
-        const parsed = JSON.parse(readFileSync(path, 'utf8'));
-        return isRecord(parsed) ? parsed : undefined;
-    }
-    catch {
-        // A hand-broken sidecar should not fail the compile; it is regenerated below.
-        return undefined;
-    }
-}
 // ─────────────────────────────────────────────────────────────────────────────
 // Inline-agent rows — the ones `uip agent refresh --inline-in-flow` derives
 // ─────────────────────────────────────────────────────────────────────────────
@@ -536,31 +521,3 @@ export function refreshInlineAgentRows(resources, agents, removedResources) {
         out = mergeInlineAgentResources(out, rows);
     return out;
 }
-/** Read one inline agent's directory the way refresh does; `undefined` when it has no readable `agent.json`. */
-export function readInlineAgentFiles(agentDir) {
-    let agent;
-    try {
-        agent = JSON.parse(readFileSync(join(agentDir, 'agent.json'), 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-    const read = (sub, file, tag) => {
-        const dir = join(agentDir, sub);
-        if (!existsSync(dir))
-            return [];
-        const out = [];
-        for (const entry of readdirSync(dir).sort()) {
-            try {
-                const body = JSON.parse(readFileSync(join(dir, entry, file), 'utf8'));
-                if (isRecord(body) && body[tag])
-                    out.push(body);
-            }
-            catch {
-                // Refresh skips a malformed or missing file the same way.
-            }
-        }
-        return out;
-    };
-    return { agent, resources: read('resources', 'resource.json', '$resourceType'), features: read('features', 'feature.json', '$featureType') };
-}

package/dist/case/merge.js

@@ -48,7 +48,7 @@
  */
 import { collectPreservation } from './decompile.js';
 import { applyPreservation } from './serialize.js';
-import { jsonClone } from '../core/json-file.js';
+import { jsonClone } from '../core/json-clone.js';
 /** Stage labels in a document, in order. */
 function stageLabels(document) {
     return (document.nodes ?? [])

package/dist/compile-cli.js

@@ -27,7 +27,8 @@ import { check } from './check.js';
 import { flowCheckOpts, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
-import { connectionResources, inlineAgentResources, mergeBindingsV2, readBindingsV2, refreshInlineAgentRows, readInlineAgentFiles, } from './bindings-v2.js';
+import { connectionResources, inlineAgentResources, mergeBindingsV2, refreshInlineAgentRows } from './bindings-v2.js';
+import { readBindingsV2, readInlineAgentFiles } from './bindings-v2-files.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { defaultBindingsFile } from './workdir.js';
 import { isWithin } from './path-within.js';

package/dist/core/connector-resolve-error.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The refusal `Library.resolve` throws. Apart from `core/library.ts`, which reads
+ * the connector library from disk, so `serialize` can recognise the refusal
+ * without loading `node:fs` (FB015). `core/library.ts` re-exports both.
+ */
+/** Why `Library.resolve` refused a connector action. */
+export type ConnectorResolveCode = 
+/** The library carries no such operation (or no such connector, or not at that version). */
+'CONNECTOR_NOT_IN_LIBRARY'
+/** A GENERIC operation (one entry per object) named without an `object`. */
+ | 'CONNECTOR_OBJECT_REQUIRED'
+/** An `object` on a single, non-generic operation. */
+ | 'CONNECTOR_OBJECT_NOT_GENERIC'
+/**
+ * The index lists the operation, but its entry file or `.v1def.json` sidecar is
+ * missing or not valid JSON: the library on disk is incomplete (#1015).
+ */
+ | 'CONNECTOR_LIBRARY_ENTRY_UNREADABLE';
+/**
+ * The refusal `Library.resolve` throws, with a `code` for each reason.
+ *
+ * Typed so a caller can tell a refusal from a bug without matching on message
+ * text: `check` reports it under this code with this message, and a compile
+ * that throws it carries the same code into its `--json` diagnostics (#948).
+ */
+export declare class ConnectorResolveError extends Error {
+    readonly code: ConnectorResolveCode;
+    constructor(code: ConnectorResolveCode, message: string);
+}

package/dist/core/connector-resolve-error.js

@@ -0,0 +1,20 @@
+/**
+ * The refusal `Library.resolve` throws. Apart from `core/library.ts`, which reads
+ * the connector library from disk, so `serialize` can recognise the refusal
+ * without loading `node:fs` (FB015). `core/library.ts` re-exports both.
+ */
+/**
+ * The refusal `Library.resolve` throws, with a `code` for each reason.
+ *
+ * Typed so a caller can tell a refusal from a bug without matching on message
+ * text: `check` reports it under this code with this message, and a compile
+ * that throws it carries the same code into its `--json` diagnostics (#948).
+ */
+export class ConnectorResolveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ConnectorResolveError';
+        this.code = code;
+    }
+}

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/core/json-clone.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A deep copy of a JSON value. Apart from `core/json-file.ts`, which writes files,
+ * so the modules that only copy values load no `node:fs`.
+ */
+/** `JSON.parse(JSON.stringify(value))`: a deep copy of a JSON value that drops `undefined` and functions, the semantics every copy relied on. */
+export declare function jsonClone<T>(value: T): T;

package/dist/core/json-clone.js

@@ -0,0 +1,8 @@
+/**
+ * A deep copy of a JSON value. Apart from `core/json-file.ts`, which writes files,
+ * so the modules that only copy values load no `node:fs`.
+ */
+/** `JSON.parse(JSON.stringify(value))`: a deep copy of a JSON value that drops `undefined` and functions, the semantics every copy relied on. */
+export function jsonClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/core/json-file.d.ts

@@ -1,3 +1 @@
 export declare function writeJsonFile(path: string, value: unknown): void;
-/** `JSON.parse(JSON.stringify(value))`: a deep copy of a JSON value that drops `undefined` and functions, the semantics every copy relied on. */
-export declare function jsonClone<T>(value: T): T;

package/dist/core/json-file.js

@@ -10,7 +10,3 @@ import { writeFileSync } from 'node:fs';
 export function writeJsonFile(path, value) {
     writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
 }
-/** `JSON.parse(JSON.stringify(value))`: a deep copy of a JSON value that drops `undefined` and functions, the semantics every copy relied on. */
-export function jsonClone(value) {
-    return JSON.parse(JSON.stringify(value));
-}

package/dist/core/library.d.ts

@@ -218,30 +218,7 @@ export interface LibraryOpts {
      */
     overlayDir?: string;
 }
-/** Why {@link Library.resolve} refused a connector action. */
-export type ConnectorResolveCode = 
-/** The library carries no such operation (or no such connector, or not at that version). */
-'CONNECTOR_NOT_IN_LIBRARY'
-/** A GENERIC operation (one entry per object) named without an `object`. */
- | 'CONNECTOR_OBJECT_REQUIRED'
-/** An `object` on a single, non-generic operation. */
- | 'CONNECTOR_OBJECT_NOT_GENERIC'
-/**
- * The index lists the operation, but its entry file or `.v1def.json` sidecar is
- * missing or not valid JSON: the library on disk is incomplete (#1015).
- */
- | 'CONNECTOR_LIBRARY_ENTRY_UNREADABLE';
-/**
- * The refusal {@link Library.resolve} throws, with a `code` for each reason.
- *
- * Typed so a caller can tell a refusal from a bug without matching on message
- * text: `check` reports it under this code with this message, and a compile
- * that throws it carries the same code into its `--json` diagnostics (#948).
- */
-export declare class ConnectorResolveError extends Error {
-    readonly code: ConnectorResolveCode;
-    constructor(code: ConnectorResolveCode, message: string);
-}
+export { ConnectorResolveError, type ConnectorResolveCode } from './connector-resolve-error.js';
 export declare class Library {
     private layers;
     /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */

package/dist/core/library.js

@@ -15,21 +15,8 @@ import { loadListEnvelopes, lookupListEnvelope } from './list-envelope.js';
 import { lookupSpecOf } from './lookups.js';
 import { loadByoaLedger, loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
 import { ownEntry } from './own-entry.js';
-/**
- * The refusal {@link Library.resolve} throws, with a `code` for each reason.
- *
- * Typed so a caller can tell a refusal from a bug without matching on message
- * text: `check` reports it under this code with this message, and a compile
- * that throws it carries the same code into its `--json` diagnostics (#948).
- */
-export class ConnectorResolveError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = 'ConnectorResolveError';
-        this.code = code;
-    }
-}
+import { ConnectorResolveError } from './connector-resolve-error.js';
+export { ConnectorResolveError } from './connector-resolve-error.js';
 export class Library {
     layers = [];
     /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */

package/dist/core/typescript-module.d.ts

@@ -1,2 +1,22 @@
+/**
+ * The TypeScript compiler, loaded on first use.
+ *
+ * Every builder entry reaches the expression and script checkers, and loading the compiler
+ * costs ~120 ms that a flow which never runs those checks should not pay (FB009). The
+ * specifier stays a literal at the call so the architecture lint sees the edge (as a lazy
+ * one); FB005 keeps this the only definition.
+ *
+ * A host without Node (a browser sandbox that bundles the compiler) hands it over before
+ * the first check: `globalThis[Symbol.for('uipath.maestro-builder-sdk.typescript')] = ts`.
+ * Otherwise `createRequire` comes from `process.getBuiltinModule`, not an `import`, so the
+ * modules that check a flow load no `node:` builtin (FB015 exempts this fallback).
+ * `process` is read through `globalThis`, as in `core/cli-spelling.ts`, so a host without
+ * one gets the error below instead of a `ReferenceError`.
+ *
+ * The triple-slash reference is load-bearing: tests type-check authored and generated
+ * code against `flow-sdk.ts`'s graph without `@types/node`, and that graph reaches other
+ * `node:` imports by type (`core/library-cache.ts`, `core/bindings.ts`). This reference is
+ * what brings the Node types into that program. It is not emitted into the .d.ts.
+ */
 import type * as TS from 'typescript';
 export declare function typescript(): typeof TS;

package/dist/core/typescript-module.js

@@ -1,18 +1,13 @@
-/// <reference types="node" />
-/**
- * The TypeScript compiler, loaded on first use.
- *
- * Every builder entry reaches the expression and script checkers, and loading the compiler
- * costs ~120 ms that a flow which never runs those checks should not pay (FB009). The
- * specifier stays a literal at the call so the architecture lint sees the edge (as a lazy
- * one); FB005 keeps this the only definition.
- *
- * The triple-slash reference: tests type-check generated code against `flow-sdk.ts`'s
- * import graph without `@types/node` in scope, and this is the one `node:` import in that
- * graph. Without it they fail with TS2307 on 'node:module'. It is not emitted into the .d.ts.
- */
-import { createRequire } from 'node:module';
+const HOST_TYPESCRIPT = Symbol.for('uipath.maestro-builder-sdk.typescript');
 let typescriptModule;
 export function typescript() {
-    return (typescriptModule ??= createRequire(import.meta.url)('typescript'));
+    return (typescriptModule ??= globalThis[HOST_TYPESCRIPT] ?? fromNode());
+}
+function fromNode() {
+    const getBuiltinModule = globalThis.process?.getBuiltinModule;
+    if (getBuiltinModule === undefined) {
+        throw new Error("no TypeScript compiler: outside Node, set globalThis[Symbol.for('uipath.maestro-builder-sdk.typescript')] to the 'typescript' module before checking a flow");
+    }
+    const { createRequire } = getBuiltinModule('node:module');
+    return createRequire(import.meta.url)('typescript');
 }

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/merge-cli.js

@@ -42,7 +42,8 @@
 import { reportResult } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
 import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
-import { readBindingsV2, readInlineAgentFiles, refreshInlineAgentRows } from './bindings-v2.js';
+import { refreshInlineAgentRows } from './bindings-v2.js';
+import { readBindingsV2, readInlineAgentFiles } from './bindings-v2-files.js';
 import { basename, dirname, join, resolve } from 'node:path';
 import { MergeRefusedError, mergeFlowWithSidecars } from './merge.js';
 import { sidecarSetFromList } from './merge-sidecars.js';

package/dist/merge-sidecars.js

@@ -64,7 +64,7 @@
  *
  * Pure: the caller reads the files ({@link SidecarSet}) and writes the result.
  */
-import { jsonClone } from './core/json-file.js';
+import { jsonClone } from './core/json-clone.js';
 /** The `{ path, json }` list `serializeWithSidecars` returns, as a {@link SidecarSet}. */
 export function sidecarSetFromList(list) {
     return (source) => {

package/dist/merge.js

@@ -75,7 +75,7 @@
  * declare. See merge-roundtrip.ts.
  */
 import { bindingIdentity } from './core/binding-identity.js';
-import { jsonClone } from './core/json-file.js';
+import { jsonClone } from './core/json-clone.js';
 import { DEFINITIONLESS_NODE_TYPES } from './core/definitionless-node-types.js';
 import { MergeRefusedError, mergedFileFindings, roundTripFindings } from './merge-roundtrip.js';
 import { placeAddedNodes } from './node-placement.js';

package/dist/nodes/conversation/flow/node-type.js

@@ -6,7 +6,7 @@
  * codes and messages unchanged.
  */
 import { Expr, toExpr } from '../../../core/expr.js';
-import { jsonClone } from '../../../core/json-file.js';
+import { jsonClone } from '../../../core/json-clone.js';
 import { checkConversational } from './check.js';
 /**
  * The definition's `inputDefaults`, which supply the fixed fields the platform's

package/dist/nodes/document/flow/node-type.js

@@ -10,7 +10,7 @@
  * express yet.
  */
 import { toExpr } from '../../../core/expr.js';
-import { jsonClone } from '../../../core/json-file.js';
+import { jsonClone } from '../../../core/json-clone.js';
 export const DOCUMENT_DIAGNOSTICS = {
     DOC_NO_FILEREF: { severity: 'error', summary: 'no fileRef, so nothing to classify or extract from' },
     EXTRACT_SCHEMA_SHAPE: { severity: 'error', summary: 'a Dynamic Extract schema that is not an object' },

package/dist/nodes/hitl/flow/node-type.js

@@ -16,7 +16,7 @@ import { Expr, toExpr } from '../../../core/expr.js';
 import { FORM_FIELD_JSON_TYPE, sdkFormFieldType } from '../../../core/form-field-type.js';
 import { isAnswerField } from '../../../core/hitl-answers.js';
 import { OUTCOME_HANDLE_NODE_TYPES, hitlExitModel, outcomeIdOf, outcomeSlug } from '../../../core/hitl-routing.js';
-import { jsonClone } from '../../../core/json-file.js';
+import { jsonClone } from '../../../core/json-clone.js';
 import { ownEntry } from '../../../core/own-entry.js';
 import { schemaId } from '../../../core/stable-id.js';
 import { wireExprBody } from '../../../core/wire-expr.js';

package/dist/nodes/http/flow/node-type.js

@@ -7,7 +7,7 @@
  * messages unchanged. Decompile now also recovers `returns` (see `liftReturns`).
  */
 import { Expr } from '../../../core/expr.js';
-import { jsonClone } from '../../../core/json-file.js';
+import { jsonClone } from '../../../core/json-clone.js';
 import { wireExprBody } from '../../../core/wire-expr.js';
 import { checkHttpRead, checkHttpStep, plainHttpOnErrorMessage } from './check.js';
 const PLAIN = 'core.action.http';

package/dist/nodes/queue/flow/node-type.js

@@ -1,5 +1,5 @@
 import { Expr } from '../../../core/expr.js';
-import { jsonClone } from '../../../core/json-file.js';
+import { jsonClone } from '../../../core/json-clone.js';
 import { checkQueueItem } from './check.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './record.js';
 const CREATE = 'core.action.queue.create';

package/dist/nodes/script/flow/node-type.js

@@ -5,7 +5,7 @@
  * source, codes and messages unchanged.
  */
 import { declaredScriptShape, inferScriptShape } from '../../../core/script-return.js';
-import { jsonClone } from '../../../core/json-file.js';
+import { jsonClone } from '../../../core/json-clone.js';
 import { checkScript } from './check.js';
 /**
  * Declare what a `core.action.script` node actually publishes.

package/dist/nodes/transform/flow/node-type.js

@@ -8,7 +8,7 @@
  */
 import { Expr } from '../../../core/expr.js';
 import { wireExprBody } from '../../../core/wire-expr.js';
-import { jsonClone } from '../../../core/json-file.js';
+import { jsonClone } from '../../../core/json-clone.js';
 import { VARIANT_OPERATION } from './spec.js';
 import { checkTransform } from './check.js';
 /**

package/dist/registry/library-build/events.js

@@ -23,7 +23,7 @@ import { safeCacheName } from "../uip/response-cache.js";
 import { schemaCacheScope, writeCache } from "./context.js";
 import { objectsComeFromTheConnection } from "./generic-expand.js";
 import { codePointSlice, get, isPyDict, item, pyIter, pyOr, pyTruthy } from "./py.js";
-import { jsonClone } from "../../core/json-file.js";
+import { jsonClone } from "../../core/json-clone.js";
 /**
  * `Parameters[].type` on a `triggers objects` row routes the value into one of
  * three `--detail` buckets at emit time. Everything unrecognized is an event

package/dist/registry/library-build/generic-expand.js

@@ -21,7 +21,7 @@ import { messageOf } from "../errors.js";
 import { isHttpPassthrough, normalizeFieldKeys, pick } from "./canonical.js";
 import { isDescribeObject, isDescribeOperation, isResourcesList } from "./context.js";
 import { get, item, pyIter, pyOr, pyTruthy } from "./py.js";
-import { jsonClone } from "../../core/json-file.js";
+import { jsonClone } from "../../core/json-clone.js";
 /**
  * `_generic_templates_by_op`: bucket Generic CRUD entries by IS operation
  * name per connector. Generic CRUD actions carry an `operation` verb

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';
@@ -20,7 +20,7 @@ import { stepExits } from './flow-step-exits.js';
 import { resolveVersionCarried } from './core/nodes/versioned.js';
 import { indexCarriedDefinitions } from './core/carried-definitions.js';
 import { FORM_FIELD_JSON_TYPE } from './core/form-field-type.js';
-import { ConnectorResolveError } from './core/library.js';
+import { ConnectorResolveError } from './core/connector-resolve-error.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
 import { ByoaRefusal, byoaUnverified } from './core/byoa.js';
@@ -64,7 +64,7 @@ import { resourceNodeSortOrder } from './core/process-resource-sort-order.js';
 import { types } from './core/expr.js';
 import { SUBFLOW_START_LABEL } from './core/subflow-start.js';
 import { ownEntry } from './core/own-entry.js';
-import { jsonClone } from './core/json-file.js';
+import { jsonClone } from './core/json-clone.js';
 // core-definitions.json is an object keyed by "<nodeType>@<version>".
 const DEFS = BUNDLED_DEFINITIONS;
 // FIRST occurrence wins: with multiple bundled versions of one family (HITL
@@ -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.31.0",
   "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": "21719d7a1fd422a6886d9021c02cf2f124c4f627"
 }