@uipath/maestro-builder-sdk 6.23.0 → 6.25.0

package/dist/nodes/conversation/flow/check.js

@@ -0,0 +1,54 @@
+import { Expr } from '../../../core/expr.js';
+export const CONVERSATION_DIAGNOSTICS = {
+    CONVERSATION_NO_ID: { severity: 'error', summary: 'a conversational step with no conversationId' },
+    SEND_MESSAGE_NO_EXCHANGE: { severity: 'error', summary: 'sendMessage with no exchangeId' },
+    SEND_MESSAGE_NO_CONTENT: { severity: 'error', summary: 'sendMessage with no content' },
+    CONVERSATION_RANGE: { severity: 'error', summary: 'a history limit outside 1–40' },
+};
+/**
+ * A conversational step (Phase 5C): send-message, wait-for-message, or
+ * get-conversation-context.
+ *
+ * Everything here is decidable offline and invisible later: the node's own
+ * schema requires `conversationId` (and `exchangeId`/`content` on send), and
+ * the two numeric limits are range-checked by the designer but silently
+ * clamped at run time.
+ */
+export function checkConversational(kind, inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    const label = kind === 'sendMessage' ? 'sendMessage'
+        : kind === 'waitForMessage' ? 'waitForMessage' : 'conversationContext';
+    if (blank(inputs?.conversationId)) {
+        at('CONVERSATION_NO_ID', `${label} step "${step}" has no \`conversationId\`, which the node's schema requires — every `
+            + `conversational step is keyed by the conversation it belongs to. The conversation trigger publishes `
+            + `it as out('start', 'conversationId').`, `conversationId: out('start', 'conversationId')`);
+    }
+    if (kind === 'sendMessage') {
+        if (blank(inputs?.exchangeId)) {
+            at('SEND_MESSAGE_NO_EXCHANGE', `sendMessage step "${step}" has no \`exchangeId\` — the node's schema requires it, because a message `
+                + `belongs to one exchange (a user turn and its answers). A wait step publishes it as `
+                + `out('<waitStep>', 'conversationContext.latestExchangeId').`, `exchangeId: out('<waitStep>', 'conversationContext.latestExchangeId')`);
+        }
+        if (blank(inputs?.content)) {
+            at('SEND_MESSAGE_NO_CONTENT', `sendMessage step "${step}" has no \`content\` — the node's schema requires a non-empty message `
+                + `(Markdown), and an empty one posts a blank turn into the conversation.`, `content: 'Looking into it.'`);
+        }
+    }
+    const rangeCheck = (field, max) => {
+        const raw = inputs?.[field];
+        if (raw === undefined || raw instanceof Expr)
+            return;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1 || n > max) {
+            at('CONVERSATION_RANGE', `${label} step "${step}"'s \`${field}\` is ${JSON.stringify(raw)}. The node accepts a whole number from `
+                + `1 to ${max} (the platform default is 20); anything else is clamped at run time, so the flow reads `
+                + `a different amount of history than it says.`, `${field}: 20`);
+        }
+    };
+    if (kind === 'waitForMessage')
+        rangeCheck('numExchanges', 40);
+    if (kind === 'conversationContext')
+        rangeCheck('exchangeLimit', 40);
+}

package/dist/nodes/conversation/flow/factories.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The conversation factories, `sendMessage()`, `waitForMessage()` and
+ * `conversationContext()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports them.
+ */
+import { type ActionSpec } from '../../../core/actions.js';
+import type { ConversationContextInputs, SendMessageInputs, WaitForMessageInputs } from './spec.js';
+/**
+ * Post an assistant message into a live conversation
+ * (`uipath.conversational.send-message`).
+ *
+ * ```ts
+ * .step('answer', sendMessage({
+ *   conversationId: out('start', 'conversationId'),
+ *   exchangeId: out('listen', 'conversationContext.latestExchangeId'),
+ *   content: 'Your order ships tomorrow.',
+ * }))
+ * ```
+ *
+ * The message is Markdown (`text/markdown` is the node's only supported type)
+ * and the role is always `assistant` — a flow speaks as the assistant.
+ *
+ * @param inputs - The conversation, the exchange, and what to say.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function sendMessage(inputs: SendMessageInputs): ActionSpec;
+/**
+ * PAUSE until the person sends their next message
+ * (`uipath.conversational.wait-for-message`) — a catch event, like
+ * `waitForEvent`, so the flow suspends rather than polling.
+ *
+ * ```ts
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * ```
+ *
+ * It resumes with the conversation context:
+ * `out('listen', 'conversationContext.messages')` is the transcript and
+ * `…conversationContext.latestExchangeId` is the turn to answer.
+ *
+ * @param inputs - The conversation to wait on, and how much history to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function waitForMessage(inputs: WaitForMessageInputs): ActionSpec;
+/**
+ * READ a conversation's transcript so far without waiting
+ * (`uipath.conversational.get-conversation-context`) — the shape a
+ * conversational agent takes as its turn context.
+ *
+ * ```ts
+ * .step('history', conversationContext({
+ *   conversationId: out('start', 'conversationId'), exchangeLimit: 10,
+ * }))
+ * ```
+ *
+ * @param inputs - The conversation to read, and how many exchanges to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function conversationContext(inputs: ConversationContextInputs): ActionSpec;

package/dist/nodes/conversation/flow/factories.js

@@ -0,0 +1,63 @@
+/**
+ * The conversation factories, `sendMessage()`, `waitForMessage()` and
+ * `conversationContext()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports them.
+ */
+import { builtinActionSpec } from '../../../core/actions.js';
+/**
+ * Post an assistant message into a live conversation
+ * (`uipath.conversational.send-message`).
+ *
+ * ```ts
+ * .step('answer', sendMessage({
+ *   conversationId: out('start', 'conversationId'),
+ *   exchangeId: out('listen', 'conversationContext.latestExchangeId'),
+ *   content: 'Your order ships tomorrow.',
+ * }))
+ * ```
+ *
+ * The message is Markdown (`text/markdown` is the node's only supported type)
+ * and the role is always `assistant` — a flow speaks as the assistant.
+ *
+ * @param inputs - The conversation, the exchange, and what to say.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function sendMessage(inputs) {
+    return builtinActionSpec({ kind: 'sendMessage', inputs });
+}
+/**
+ * PAUSE until the person sends their next message
+ * (`uipath.conversational.wait-for-message`) — a catch event, like
+ * `waitForEvent`, so the flow suspends rather than polling.
+ *
+ * ```ts
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * ```
+ *
+ * It resumes with the conversation context:
+ * `out('listen', 'conversationContext.messages')` is the transcript and
+ * `…conversationContext.latestExchangeId` is the turn to answer.
+ *
+ * @param inputs - The conversation to wait on, and how much history to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function waitForMessage(inputs) {
+    return builtinActionSpec({ kind: 'waitForMessage', inputs });
+}
+/**
+ * READ a conversation's transcript so far without waiting
+ * (`uipath.conversational.get-conversation-context`) — the shape a
+ * conversational agent takes as its turn context.
+ *
+ * ```ts
+ * .step('history', conversationContext({
+ *   conversationId: out('start', 'conversationId'), exchangeLimit: 10,
+ * }))
+ * ```
+ *
+ * @param inputs - The conversation to read, and how many exchanges to return.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function conversationContext(inputs) {
+    return builtinActionSpec({ kind: 'conversationContext', inputs });
+}

package/dist/nodes/conversation/flow/family.d.ts

@@ -0,0 +1,3 @@
+/** The conversation node family, as flow-node-registry.ts lists it: the three `uipath.conversational.*` steps. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const conversationFlowFamily: FlowNodeFamily;

package/dist/nodes/conversation/flow/family.js

@@ -0,0 +1,8 @@
+import { CONVERSATION_DIAGNOSTICS } from './check.js';
+import { conversationNodeTypes } from './node-type.js';
+export const conversationFlowFamily = {
+    id: 'conversation',
+    title: 'Conversation',
+    types: conversationNodeTypes,
+    diagnostics: CONVERSATION_DIAGNOSTICS,
+};

package/dist/nodes/conversation/flow/index.d.ts

@@ -0,0 +1,3 @@
+/** The conversation family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/conversation/flow/index.js

@@ -0,0 +1,3 @@
+/** The conversation family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/conversation/flow/node-type.d.ts

@@ -0,0 +1,14 @@
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+import type { ConversationContextInputs, SendMessageInputs, WaitForMessageInputs } from './spec.js';
+type Spec = {
+    kind: 'sendMessage';
+    inputs: SendMessageInputs;
+} | {
+    kind: 'waitForMessage';
+    inputs: WaitForMessageInputs;
+} | {
+    kind: 'conversationContext';
+    inputs: ConversationContextInputs;
+};
+export declare const conversationNodeTypes: FlowVersionedNodeType<Spec>[];
+export {};

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

@@ -0,0 +1,117 @@
+/**
+ * The three conversational node types: `uipath.conversational.send-message`
+ * (1.0, 1.1), `.wait-for-message` (1.0, 1.1) and `.get-conversation-context`
+ * (1.0). Moved from serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, printed source,
+ * codes and messages unchanged.
+ */
+import { Expr, toExpr } from '../../../core/expr.js';
+import { jsonClone } from '../../../core/json-file.js';
+import { checkConversational } from './check.js';
+/**
+ * The definition's `inputDefaults`, which supply the fixed fields the platform's
+ * schema requires (`role: 'assistant'` and `mimeType: 'text/markdown'` on send,
+ * `from: 'User'` on wait) — the author never writes a value the enum only allows
+ * one of. Always the 1.0 definition's, whatever version is emitted: that is what
+ * the pipeline wrote before the port (its `defByType` holds the first bundled
+ * copy), so a 1.1 step still carries 1.0's `endExchange` / `numExchanges` keys.
+ */
+function defaults(ctx, typeName) {
+    return jsonClone(ctx.definition(typeName, '1.0')?.inputDefaults ?? {});
+}
+/** A value rendered as the file stores it; a bare literal is wrapped first, as the pipeline did. */
+const rendered = (ctx, v) => ctx.render(toExpr(v));
+/**
+ * A serialized value as the author wrote it. Decompile's own reading: the text of
+ * a string, or of an envelope's `expression`; `=js:` and a bare `$vars.` path are
+ * references, anything else a literal string.
+ */
+function lifted(x, ctx) {
+    const raw = typeof x === 'string' ? x : String(x?.expression ?? x ?? '');
+    if (raw.startsWith('=js:'))
+        return ctx.expr(raw);
+    if (raw.startsWith('$vars.'))
+        return ctx.expr(`=js:${raw}`);
+    return raw;
+}
+/** A number, or undefined for an absent or non-finite one. */
+function liftedNumber(x) {
+    if (x === undefined || x === null)
+        return undefined;
+    const n = Number(x?.expression ?? x);
+    return Number.isFinite(n) ? n : undefined;
+}
+const printed = (v, ctx) => (v instanceof Expr ? ctx.value(v) : ctx.string(String(v)));
+function conversationAt(kind, typeName, version) {
+    return {
+        kind, typeName, version, factory: kind, definition: 'bundled',
+        rawNode: { factory: `${kind}()` },
+        serialize: (spec, ctx) => {
+            const i = spec.inputs;
+            const base = { ...defaults(ctx, typeName), conversationId: rendered(ctx, i.conversationId) };
+            const inputs = kind === 'sendMessage'
+                ? {
+                    ...base,
+                    exchangeId: rendered(ctx, i.exchangeId),
+                    content: rendered(ctx, i.content),
+                    ...(i.endExchange !== undefined ? { endExchange: i.endExchange } : {}),
+                }
+                : kind === 'waitForMessage'
+                    ? { ...base, ...(i.numExchanges !== undefined ? { numExchanges: i.numExchanges } : {}) }
+                    : { ...base, ...(i.exchangeLimit !== undefined ? { exchangeLimit: i.exchangeLimit } : {}) };
+            // The service model stays on the DEFINITION only: these are
+            // `bpmn:ServiceTask` / `bpmn:IntermediateCatchEvent` nodes whose
+            // serviceType the platform resolves from `definitions[]`.
+            return { model: 'omit', inputs, port: 'output' };
+        },
+        // The fixed enum fields come from the definition's defaults, so nothing of
+        // them is recovered — only what an author could have written.
+        deserialize: (node, ctx) => {
+            const i = (node.inputs ?? {});
+            const conversationId = lifted(i.conversationId, ctx);
+            if (kind === 'sendMessage') {
+                return {
+                    kind,
+                    inputs: {
+                        conversationId,
+                        exchangeId: lifted(i.exchangeId, ctx),
+                        content: lifted(i.content, ctx),
+                        // The definition defaults `endExchange` to false; only a departure was authored.
+                        ...(i.endExchange === true ? { endExchange: true } : {}),
+                    },
+                };
+            }
+            const field = kind === 'waitForMessage' ? 'numExchanges' : 'exchangeLimit';
+            const n = liftedNumber(i[field]);
+            return { kind, inputs: { conversationId, ...(n !== undefined && n !== 20 ? { [field]: n } : {}) } };
+        },
+        print: (spec, ctx) => {
+            const i = spec.inputs;
+            const cid = ['conversationId', printed(i.conversationId, ctx)];
+            if (kind === 'sendMessage') {
+                return {
+                    factory: kind,
+                    options: [cid, ['exchangeId', printed(i.exchangeId, ctx)], ['content', printed(i.content, ctx)],
+                        ['endExchange', i.endExchange === true ? 'true' : undefined]],
+                };
+            }
+            const field = kind === 'waitForMessage' ? 'numExchanges' : 'exchangeLimit';
+            return { factory: kind, options: [cid, [field, i[field] !== undefined ? ctx.json(i[field]) : undefined]] };
+        },
+        check: (spec, ctx) => checkConversational(kind, spec.inputs, ctx),
+        // check collected no expressions for a conversational step before the port; unchanged by it.
+        expressions: () => [],
+        output: () => ({ kind: 'opaque' }),
+    };
+}
+function conversationType(kind, typeName, versions) {
+    return {
+        kind, typeName, factory: kind, defaultVersion: '1.0',
+        versions: Object.fromEntries(versions.map((v) => [v, conversationAt(kind, typeName, v)])),
+    };
+}
+export const conversationNodeTypes = [
+    conversationType('sendMessage', 'uipath.conversational.send-message', ['1.0', '1.1']),
+    conversationType('waitForMessage', 'uipath.conversational.wait-for-message', ['1.0', '1.1']),
+    conversationType('conversationContext', 'uipath.conversational.get-conversation-context', ['1.0']),
+];

package/dist/nodes/conversation/flow/spec.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The conversation family's authoring types (`uipath.conversational.send-message`,
+ * `.wait-for-message`, `.get-conversation-context`), and their kinds' entries in
+ * `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
+ */
+import type { Expr } from '../../../core/expr.js';
+export interface SendMessageInputs {
+    /**
+     * The conversation to post into — from the conversation trigger
+     * (`out('start', 'conversationId')`) or a context read. Required.
+     */
+    conversationId: string | Expr;
+    /**
+     * The exchange (one user turn plus its answers) the message belongs to —
+     * `out('<waitStep>', 'conversationContext.latestExchangeId')`, or the
+     * trigger's exchange for the first answer. Required by the node's schema.
+     */
+    exchangeId: string | Expr;
+    /** What to say. Markdown — the node's only supported `mimeType`. Required. */
+    content: string | Expr;
+    /**
+     * Whether this message CLOSES the exchange. The platform's legacy default is
+     * to end it; pass `false` to keep the exchange open for another message.
+     */
+    endExchange?: boolean;
+}
+export interface WaitForMessageInputs {
+    /** The conversation to wait on. Required. */
+    conversationId: string | Expr;
+    /**
+     * How many past exchanges the returned context carries. 1–40 in the
+     * designer; the platform default is 20.
+     */
+    numExchanges?: number;
+}
+export interface ConversationContextInputs {
+    /** The conversation to read. Required. */
+    conversationId: string | Expr;
+    /**
+     * How many exchanges to return, 1–40. The platform default is 20.
+     */
+    exchangeLimit?: number;
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link sendMessage} builds. */
+        sendMessage: {
+            inputs: SendMessageInputs;
+        };
+        /** The spec {@link waitForMessage} builds. */
+        waitForMessage: {
+            inputs: WaitForMessageInputs;
+        };
+        /** The spec {@link conversationContext} builds. */
+        conversationContext: {
+            inputs: ConversationContextInputs;
+        };
+    }
+}

package/dist/nodes/conversation/flow/spec.js

@@ -0,0 +1 @@
+export {};

package/dist/nodes/hitl/flow/check.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The HITL family's rules: the form, outcomes, variant and delivery of one human
+ * task (`checkHitl`), and a read of its result (`checkHitlRead`). Moved from
+ * check.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and
+ * messages unchanged. The rules that need the rest of the flow — an outcome no
+ * route takes, an outcome nothing downstream tells apart, a port the task does
+ * not draw — stay in check.ts, which walks the flow.
+ */
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { OutputPathRead } from '../../../core/nodes/node-type.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import type { HitlInputs } from './spec.js';
+export declare const HITL_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * A human task's form.
+ *
+ * Everything here is a mistake no later rung can see, which is the test for
+ * earning a place in `check` rather than in the docs: the flow compiles, deploys,
+ * and shows a person a form with something quietly missing from it. These catch it
+ * at rung 1, in the author's own vocabulary.
+ */
+export declare function checkHitl(inputs: HitlInputs, ctx: FlowCheckContext): void;
+/**
+ * A read of a human task's output: `out('<step>', '<field>')`.
+ *
+ * The node publishes an object keyed by the form's ANSWER fields plus `Action`.
+ * Two mistakes are silent at run time and both are caught here:
+ *
+ *  - reading a field the form does not answer (a shown field, or a typo) —
+ *    `undefined`, offline and deployed;
+ *  - reading `$vars.<step>.status`, the platform's own projection of the chosen
+ *    outcome. It resolves *deployed*, so the flow works in production and reads
+ *    `undefined` on this SDK's offline rungs — a divergence, which is why the read
+ *    is redirected rather than merely flagged. (A runner that derives declared
+ *    output variables resolves `status` offline as well; the surface still points
+ *    at one spelling so a flow reads the same everywhere.)
+ */
+export declare function checkHitlRead({ node: name, field, rest, reader: step }: OutputPathRead, form: HitlInputs | undefined, report: (code: string, message: string, suggestion?: string) => void): void;