@elizaos/plugin-workflow 2.0.0-beta.1

package/dist/lib/legacy-text-trigger-migration.js

@@ -0,0 +1,131 @@
+/**
+ * Idempotent migration: legacy `kind: "text"` trigger Tasks → workflow triggers
+ *
+ * Walks every TRIGGER_DISPATCH task for the running agent. For each task whose
+ * stored `metadata.trigger.kind` is `"text"` (or omitted, which is the legacy
+ * default), deploy a one-node workflow built around
+ * `workflows-nodes-base.respondToEvent` and rewrite the trigger metadata so
+ * `kind = "workflow"` plus a pointer to the new workflow. A `migratedFromText`
+ * marker prevents double-conversion on subsequent boots.
+ */
+import { logger, } from '@elizaos/core';
+import { WORKFLOW_SERVICE_TYPE } from '../services/workflow-service';
+const TRIGGER_TASK_NAME = 'TRIGGER_DISPATCH';
+const RESPOND_TO_EVENT_NODE_TYPE = 'workflows-nodes-base.respondToEvent';
+function readWorkflowService(runtime) {
+    const svc = runtime.getService(WORKFLOW_SERVICE_TYPE);
+    return svc ?? null;
+}
+function readTriggerFromMetadata(task) {
+    const trigger = task.metadata?.trigger;
+    if (!trigger || typeof trigger !== 'object' || Array.isArray(trigger))
+        return null;
+    if (typeof trigger.triggerId !== 'string')
+        return null;
+    return trigger;
+}
+function buildRespondToEventWorkflow(trigger, fallbackName) {
+    const displayName = typeof trigger.displayName === 'string' && trigger.displayName.trim().length > 0
+        ? trigger.displayName
+        : fallbackName;
+    const instructions = typeof trigger.instructions === 'string' && trigger.instructions.trim().length > 0
+        ? trigger.instructions
+        : displayName;
+    return {
+        name: displayName,
+        nodes: [
+            {
+                id: 'respond-to-event',
+                name: 'Respond To Event',
+                type: RESPOND_TO_EVENT_NODE_TYPE,
+                typeVersion: 1,
+                position: [0, 0],
+                parameters: {
+                    instructions,
+                    displayName,
+                    wakeMode: 'inject_now',
+                },
+            },
+        ],
+        connections: {},
+    };
+}
+export async function migrateLegacyTextTriggers(runtime) {
+    const summary = { migrated: 0, skipped: 0, failed: 0 };
+    const service = readWorkflowService(runtime);
+    if (!service) {
+        logger.debug({ src: 'plugin:workflow:migration:text-trigger' }, 'WorkflowService not registered; skipping text-trigger migration');
+        return summary;
+    }
+    let tasks;
+    try {
+        tasks = await runtime.getTasksByName(TRIGGER_TASK_NAME);
+    }
+    catch (err) {
+        logger.warn({
+            src: 'plugin:workflow:migration:text-trigger',
+            err: err instanceof Error ? err.message : String(err),
+        }, 'Failed to list trigger dispatch tasks; aborting migration');
+        return summary;
+    }
+    for (const task of tasks) {
+        if (!task.id || task.agentId !== runtime.agentId) {
+            summary.skipped += 1;
+            continue;
+        }
+        const metadata = task.metadata ?? {};
+        if (metadata.migratedFromText === true) {
+            summary.skipped += 1;
+            continue;
+        }
+        const trigger = readTriggerFromMetadata(task);
+        if (!trigger) {
+            summary.skipped += 1;
+            continue;
+        }
+        // `kind` is optional in the legacy schema; absence implies "text".
+        const isTextKind = trigger.kind === 'text' || trigger.kind === undefined;
+        if (!isTextKind) {
+            summary.skipped += 1;
+            continue;
+        }
+        try {
+            const draft = buildRespondToEventWorkflow(trigger, task.name ?? 'Trigger');
+            const deployed = await service.deployWorkflow(draft, runtime.agentId);
+            if (!deployed.id) {
+                summary.failed += 1;
+                logger.warn({
+                    src: 'plugin:workflow:migration:text-trigger',
+                    taskId: task.id,
+                    triggerId: trigger.triggerId,
+                }, 'deployWorkflow returned no id; will retry on next boot');
+                continue;
+            }
+            const updatedTrigger = {
+                ...trigger,
+                kind: 'workflow',
+                workflowId: deployed.id,
+                workflowName: deployed.name,
+            };
+            const nextMetadata = {
+                ...metadata,
+                trigger: updatedTrigger,
+                migratedFromText: true,
+                migratedAt: Date.now(),
+            };
+            await runtime.updateTask(task.id, { metadata: nextMetadata });
+            summary.migrated += 1;
+        }
+        catch (err) {
+            summary.failed += 1;
+            logger.warn({
+                src: 'plugin:workflow:migration:text-trigger',
+                taskId: task.id,
+                triggerId: trigger.triggerId,
+                err: err instanceof Error ? err.message : String(err),
+            }, 'Failed to migrate text trigger to workflow trigger');
+        }
+    }
+    return summary;
+}
+//# sourceMappingURL=legacy-text-trigger-migration.js.map

package/dist/lib/legacy-text-trigger-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-text-trigger-migration.js","sourceRoot":"","sources":["../../src/lib/legacy-text-trigger-migration.ts"],"names":[],"mappings":"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"}

package/dist/lib/workflow-clarification.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Clarification helpers for workflow generation routes.
+ *
+ * - `coerceClarifications`: normalizes the plugin's mixed-shape
+ *   `_meta.requiresClarification` (legacy strings + structured objects)
+ *   into typed `WorkflowClarificationRequest[]`.
+ * - `setByDotPath`: applies `{paramPath, value}` resolutions to a draft
+ *   workflow JSON in place. Supports dot segments and bracketed-string
+ *   segments (`nodes["Discord Send"].parameters.channelId`).
+ *
+ * Kept out of `workflows-routes.ts` so the handlers stay focused on transport.
+ */
+export interface WorkflowClarificationRequest {
+    kind: 'target_channel' | 'target_server' | 'recipient' | 'value' | 'free_text';
+    platform?: string;
+    scope?: {
+        guildId?: string;
+    };
+    question: string;
+    paramPath: string;
+}
+export interface WorkflowClarificationResolution {
+    paramPath: string;
+    value: string;
+}
+export interface WorkflowClarificationTargetGroup {
+    platform: string;
+    groupId: string;
+    groupName: string;
+    targets: Array<{
+        id: string;
+        name: string;
+        kind: 'channel' | 'recipient' | 'chat';
+    }>;
+}
+export declare function coerceClarifications(raw: unknown): WorkflowClarificationRequest[];
+/**
+ * Tokenizer for paramPath. Handles three segment forms:
+ *   - dot identifier:        `parameters`
+ *   - bracketed quoted key:  `["Discord Send"]` or `['k']`
+ *   - bracketed numeric:     `[0]`
+ */
+export declare function parseParamPath(path: string): string[];
+/**
+ * Mutate `obj` so that its value at `paramPath` becomes `value`. Creates
+ * intermediate plain objects as needed; never replaces an existing
+ * non-object intermediate (those throw, since the path is invalid).
+ *
+ * Segments that hit an array can be:
+ *   - numeric → direct index
+ *   - non-numeric (string) → looked up against the array's `.name` or `.id`
+ *     field. Common in LLM output: the model writes `nodes["Post to Slack"]`
+ *     rather than `nodes[2]`. Treating that as a hard failure forced every
+ *     clarification resolution through a 400.
+ *
+ * If the segment expects an array but the existing intermediate is a non-
+ * array object, we treat it as an object key (workflow shapes mix arrays and
+ * objects fairly freely; we err on the side of preserving structure).
+ *
+ * Terminal-segment guard: refuses to overwrite an existing object with a
+ * non-object value. The LLM sometimes emits a paramPath that points at a
+ * parent scope rather than a leaf (e.g.
+ * `nodes["Hourly Trigger"].parameters` for a question whose answer is a
+ * channel name); naively writing the string there replaces the entire
+ * `parameters` object and the workflow runner then rejects the workflow with
+ * `parameters must be object`. Throwing here gives `applyResolutions` a
+ * chance to fall back to the userNotes path.
+ */
+export declare function setByDotPath(obj: Record<string, unknown>, paramPath: string, value: unknown): void;
+export declare function applyResolutions(draft: Record<string, unknown>, resolutions: ReadonlyArray<WorkflowClarificationResolution>): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    paramPath?: string;
+};
+/**
+ * Drop the resolved clarifications from the draft's `_meta` so the next
+ * read of the draft does not re-prompt the user for the same parameter.
+ *
+ * Two pruning paths:
+ *  1. Object-form clarifications with paramPath → prune by paramPath match.
+ *  2. String-form clarifications (LLM emits free-form questions without a
+ *     paramPath) and object-form clarifications with empty paramPath →
+ *     prune positionally by `freeFormCount` (UI presents them in order, so
+ *     each free-form resolution consumes the next one).
+ *
+ * Positional-pruning contract: free-form items are dropped from the head of
+ * the stored list in order. The UI must therefore submit answers in the
+ * order they were presented, with no skipped or out-of-order items in a
+ * single batch — otherwise the wrong question gets pruned. If we ever need
+ * to support partial/interleaved submissions, switch the resolution payload
+ * to send the answered question text and match by value here instead.
+ */
+export declare function pruneResolvedClarifications(draft: Record<string, unknown>, resolved: ReadonlySet<string>, freeFormCount?: number): void;
+/**
+ * Subset of `ElizaConnectorTargetCatalog` used by the route. Declared here
+ * (vs. imported from the service) so route tests can stub it without
+ * spinning up the full service.
+ */
+export interface CatalogLike {
+    listGroups(opts?: {
+        platform?: string;
+        groupId?: string;
+    }): Promise<WorkflowClarificationTargetGroup[]>;
+}
+/**
+ * Build a catalog snapshot for the platforms referenced by `clarifications`.
+ * If multiple clarifications reference the same platform, we union their
+ * groupId scopes — broader queries (no scope) always win.
+ */
+export declare function buildCatalogSnapshot(catalog: CatalogLike, clarifications: ReadonlyArray<WorkflowClarificationRequest>): Promise<WorkflowClarificationTargetGroup[]>;
+//# sourceMappingURL=workflow-clarification.d.ts.map

package/dist/lib/workflow-clarification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-clarification.d.ts","sourceRoot":"","sources":["../../src/lib/workflow-clarification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,gBAAgB,GAAG,eAAe,GAAG,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;KACxC,CAAC,CAAC;CACJ;AAkDD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,4BAA4B,EAAE,CAyCjF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAiDrD;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GACb,IAAI,CAoEN;AA2BD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,EAAE,aAAa,CAAC,+BAA+B,CAAC,GAC1D;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAyDjE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,aAAa,SAAI,GAChB,IAAI,CAoCN;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,IAAI,CAAC,EAAE;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,aAAa,CAAC,4BAA4B,CAAC,GAC1D,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAwB7C"}

package/dist/lib/workflow-clarification.js

@@ -0,0 +1,425 @@
+/**
+ * Clarification helpers for workflow generation routes.
+ *
+ * - `coerceClarifications`: normalizes the plugin's mixed-shape
+ *   `_meta.requiresClarification` (legacy strings + structured objects)
+ *   into typed `WorkflowClarificationRequest[]`.
+ * - `setByDotPath`: applies `{paramPath, value}` resolutions to a draft
+ *   workflow JSON in place. Supports dot segments and bracketed-string
+ *   segments (`nodes["Discord Send"].parameters.channelId`).
+ *
+ * Kept out of `workflows-routes.ts` so the handlers stay focused on transport.
+ */
+import { logger } from '@elizaos/core';
+const VALID_KINDS = new Set([
+    'target_channel',
+    'target_server',
+    'recipient',
+    'value',
+    'free_text',
+]);
+/**
+ * Stable sort priority for clarification kinds. Lower number = asked first.
+ *
+ * `target_server` MUST come before `target_channel` because the channel
+ * picker reads `scope.guildId` from the server pick to narrow its options.
+ * If the LLM emits them in reverse order (which it sometimes does), the
+ * user picks a channel first against an unscoped catalog, which is bad UX
+ * (every channel from every guild they belong to) and can land the wrong
+ * id when channel names collide across guilds.
+ *
+ * `recipient` shares the server-scoped concern — DMs/contacts belong to a
+ * platform context — so it sorts after `target_server` too. `value` and
+ * `free_text` don't depend on prior picks; relative order is preserved
+ * because Array.prototype.sort is stable as of ES2019.
+ */
+const KIND_SORT_PRIORITY = {
+    target_server: 0,
+    target_channel: 1,
+    recipient: 1,
+    value: 2,
+    free_text: 3,
+};
+function isStructuredClarification(v) {
+    if (!v || typeof v !== 'object') {
+        return false;
+    }
+    const o = v;
+    if (typeof o.question !== 'string' || o.question.trim().length === 0) {
+        return false;
+    }
+    // `kind` and `paramPath` may be missing on partial / older payloads — we
+    // default them here rather than reject the item outright.
+    return true;
+}
+export function coerceClarifications(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return [];
+    }
+    const out = [];
+    for (const item of raw) {
+        if (typeof item === 'string') {
+            const trimmed = item.trim();
+            if (trimmed.length === 0) {
+                continue;
+            }
+            out.push({ kind: 'free_text', question: trimmed, paramPath: '' });
+            continue;
+        }
+        if (!isStructuredClarification(item)) {
+            continue;
+        }
+        const kindRaw = typeof item.kind === 'string' ? item.kind : 'free_text';
+        const kind = (VALID_KINDS.has(kindRaw) ? kindRaw : 'free_text');
+        const platform = typeof item.platform === 'string' ? item.platform : undefined;
+        let scope;
+        if (item.scope && typeof item.scope === 'object' && typeof item.scope.guildId === 'string') {
+            scope = {
+                guildId: item.scope.guildId,
+            };
+        }
+        const paramPath = typeof item.paramPath === 'string' ? item.paramPath : '';
+        out.push({
+            kind,
+            platform,
+            scope,
+            question: item.question.trim(),
+            paramPath,
+        });
+    }
+    // Stable-sort so dependency-bearing kinds come first. Within the same
+    // priority bucket the LLM's emission order is preserved.
+    out.sort((a, b) => KIND_SORT_PRIORITY[a.kind] - KIND_SORT_PRIORITY[b.kind]);
+    return out;
+}
+/**
+ * Tokenizer for paramPath. Handles three segment forms:
+ *   - dot identifier:        `parameters`
+ *   - bracketed quoted key:  `["Discord Send"]` or `['k']`
+ *   - bracketed numeric:     `[0]`
+ */
+export function parseParamPath(path) {
+    const segments = [];
+    let i = 0;
+    const n = path.length;
+    while (i < n) {
+        const ch = path[i];
+        if (ch === '.') {
+            i += 1;
+            continue;
+        }
+        if (ch === '[') {
+            const close = path.indexOf(']', i);
+            if (close < 0) {
+                throw new Error(`unterminated bracket at index ${i}`);
+            }
+            const inner = path.slice(i + 1, close).trim();
+            if (inner.length === 0) {
+                throw new Error(`empty bracket at index ${i}`);
+            }
+            const first = inner[0];
+            const last = inner[inner.length - 1];
+            if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+                segments.push(inner.slice(1, -1));
+            }
+            else if (/^[0-9]+$/.test(inner)) {
+                segments.push(inner);
+            }
+            else {
+                // Unquoted bare identifier inside brackets — accept to be lenient
+                // with LLM output (e.g. `[channelId]`).
+                segments.push(inner);
+            }
+            i = close + 1;
+            continue;
+        }
+        // Identifier run: read until next `.` or `[`.
+        let j = i;
+        while (j < n && path[j] !== '.' && path[j] !== '[') {
+            j += 1;
+        }
+        const ident = path.slice(i, j).trim();
+        if (ident.length === 0) {
+            throw new Error(`empty identifier at index ${i}`);
+        }
+        segments.push(ident);
+        i = j;
+    }
+    if (segments.length === 0) {
+        throw new Error('paramPath has no segments');
+    }
+    return segments;
+}
+/**
+ * Find the index of a named entry in an array of objects, matching against
+ * `.name` first then `.id`. Returns -1 if no match. Used by `setByDotPath`
+ * to resolve `nodes["My Node"]`-style segments — the LLM consistently
+ * addresses workflow nodes by their human name even though `workflow.nodes`
+ * is an array, so we map name → index here rather than rejecting the path.
+ */
+function findArrayIndexByNameOrId(arr, key) {
+    for (let i = 0; i < arr.length; i += 1) {
+        const entry = arr[i];
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const obj = entry;
+        if (obj.name === key || obj.id === key) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Mutate `obj` so that its value at `paramPath` becomes `value`. Creates
+ * intermediate plain objects as needed; never replaces an existing
+ * non-object intermediate (those throw, since the path is invalid).
+ *
+ * Segments that hit an array can be:
+ *   - numeric → direct index
+ *   - non-numeric (string) → looked up against the array's `.name` or `.id`
+ *     field. Common in LLM output: the model writes `nodes["Post to Slack"]`
+ *     rather than `nodes[2]`. Treating that as a hard failure forced every
+ *     clarification resolution through a 400.
+ *
+ * If the segment expects an array but the existing intermediate is a non-
+ * array object, we treat it as an object key (workflow shapes mix arrays and
+ * objects fairly freely; we err on the side of preserving structure).
+ *
+ * Terminal-segment guard: refuses to overwrite an existing object with a
+ * non-object value. The LLM sometimes emits a paramPath that points at a
+ * parent scope rather than a leaf (e.g.
+ * `nodes["Hourly Trigger"].parameters` for a question whose answer is a
+ * channel name); naively writing the string there replaces the entire
+ * `parameters` object and the workflow runner then rejects the workflow with
+ * `parameters must be object`. Throwing here gives `applyResolutions` a
+ * chance to fall back to the userNotes path.
+ */
+export function setByDotPath(obj, paramPath, value) {
+    const segments = parseParamPath(paramPath);
+    let cur = obj;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        const seg = segments[i];
+        const isArrayIndex = /^[0-9]+$/.test(seg);
+        if (Array.isArray(cur)) {
+            let idx;
+            if (isArrayIndex) {
+                idx = Number(seg);
+            }
+            else {
+                idx = findArrayIndexByNameOrId(cur, seg);
+                if (idx < 0) {
+                    throw new Error(`paramPath segment "${seg}" did not match any element by name/id at depth ${i}`);
+                }
+            }
+            let next = cur[idx];
+            if (next === undefined || next === null) {
+                next = /^[0-9]+$/.test(segments[i + 1]) ? [] : {};
+                cur[idx] = next;
+            }
+            if (typeof next !== 'object') {
+                throw new Error(`paramPath cannot descend into non-object at "${seg}" (depth ${i})`);
+            }
+            cur = next;
+            continue;
+        }
+        let next = cur[seg];
+        if (next === undefined || next === null) {
+            next = /^[0-9]+$/.test(segments[i + 1]) ? [] : {};
+            cur[seg] = next;
+        }
+        if (typeof next !== 'object') {
+            throw new Error(`paramPath cannot descend into non-object at "${seg}" (depth ${i})`);
+        }
+        cur = next;
+    }
+    const last = segments[segments.length - 1];
+    const isNonNullObject = (v) => v !== null && typeof v === 'object';
+    if (Array.isArray(cur)) {
+        let idx;
+        if (/^[0-9]+$/.test(last)) {
+            idx = Number(last);
+        }
+        else {
+            idx = findArrayIndexByNameOrId(cur, last);
+            if (idx < 0) {
+                throw new Error(`paramPath terminal segment "${last}" did not match any element by name/id at array`);
+            }
+        }
+        if (isNonNullObject(cur[idx]) && !isNonNullObject(value)) {
+            throw new Error(`paramPath terminal "${last}" currently holds an object; refusing to overwrite with non-object value (path likely points at a parent scope rather than a leaf field)`);
+        }
+        cur[idx] = value;
+    }
+    else {
+        const existing = cur[last];
+        if (isNonNullObject(existing) && !isNonNullObject(value)) {
+            throw new Error(`paramPath terminal "${last}" currently holds an object; refusing to overwrite with non-object value (path likely points at a parent scope rather than a leaf field)`);
+        }
+        cur[last] = value;
+    }
+}
+/**
+ * Append a free-form answer to `draft._meta.userNotes`. Used for
+ * clarifications with no `paramPath` AND as the fallback when
+ * `setByDotPath` can't resolve a paramPath against the current draft.
+ * Subsequent LLM regeneration rounds read these notes from `_meta` so the
+ * user's answer is preserved across the failure rather than discarded.
+ */
+function appendUserNote(draft, value) {
+    const existingMeta = draft._meta;
+    const meta = existingMeta && typeof existingMeta === 'object'
+        ? existingMeta
+        : {};
+    draft._meta = meta;
+    let notes;
+    if (Array.isArray(meta.userNotes)) {
+        notes = meta.userNotes;
+    }
+    else {
+        notes = meta.userNotes !== null && meta.userNotes !== undefined ? [String(meta.userNotes)] : [];
+        meta.userNotes = notes;
+    }
+    notes.push(value);
+}
+export function applyResolutions(draft, resolutions) {
+    for (const r of resolutions) {
+        if (!r || typeof r.paramPath !== 'string') {
+            return { ok: false, error: 'resolution missing paramPath' };
+        }
+        if (typeof r.value !== 'string') {
+            return {
+                ok: false,
+                error: 'resolution value must be a string',
+                paramPath: r.paramPath,
+            };
+        }
+        if (r.paramPath.length === 0) {
+            // Free-form clarification with no field to wire into. Record the user's
+            // answer under draft._meta.userNotes so subsequent LLM iterations can
+            // consume the context, but don't mutate the workflow itself.
+            appendUserNote(draft, r.value);
+            continue;
+        }
+        // Surface structural parse errors (unterminated bracket, empty
+        // identifier, etc.) up to the caller as a 400 — these signal a
+        // malformed LLM emission and cannot be silently recovered into
+        // userNotes without losing the failure mode in the metrics pipeline.
+        try {
+            parseParamPath(r.paramPath);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `paramPath is structurally invalid: ${err instanceof Error ? err.message : String(err)}`,
+                paramPath: r.paramPath,
+            };
+        }
+        try {
+            setByDotPath(draft, r.paramPath, r.value);
+        }
+        catch (err) {
+            // Lookup-time failure: the path parsed cleanly but didn't resolve
+            // against the current draft (e.g. references a node the LLM didn't
+            // actually create, or points at a parent scope rather than a leaf
+            // field). Failing the whole resolution batch with a 400 is a
+            // dead-end — the user has no way to recover without re-prompting
+            // from scratch. Log a warn and record the answer as a free-form
+            // note so the next regeneration round can use it.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            logger.warn({
+                src: 'plugin:workflow:clarification:applyResolutions',
+                err: errMsg,
+                paramPath: r.paramPath,
+            }, `setByDotPath failed for paramPath "${r.paramPath}"; recording "${r.value}" as a free-form note instead`);
+            appendUserNote(draft, r.value);
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Drop the resolved clarifications from the draft's `_meta` so the next
+ * read of the draft does not re-prompt the user for the same parameter.
+ *
+ * Two pruning paths:
+ *  1. Object-form clarifications with paramPath → prune by paramPath match.
+ *  2. String-form clarifications (LLM emits free-form questions without a
+ *     paramPath) and object-form clarifications with empty paramPath →
+ *     prune positionally by `freeFormCount` (UI presents them in order, so
+ *     each free-form resolution consumes the next one).
+ *
+ * Positional-pruning contract: free-form items are dropped from the head of
+ * the stored list in order. The UI must therefore submit answers in the
+ * order they were presented, with no skipped or out-of-order items in a
+ * single batch — otherwise the wrong question gets pruned. If we ever need
+ * to support partial/interleaved submissions, switch the resolution payload
+ * to send the answered question text and match by value here instead.
+ */
+export function pruneResolvedClarifications(draft, resolved, freeFormCount = 0) {
+    const meta = draft._meta;
+    if (!meta || typeof meta !== 'object') {
+        return;
+    }
+    const list = meta.requiresClarification;
+    if (!Array.isArray(list)) {
+        return;
+    }
+    let toDropFreeForm = freeFormCount;
+    const remaining = list.filter((item) => {
+        if (typeof item === 'string') {
+            if (toDropFreeForm > 0) {
+                toDropFreeForm -= 1;
+                return false;
+            }
+            return true;
+        }
+        if (item && typeof item === 'object') {
+            const path = item.paramPath;
+            if (typeof path === 'string' && path.length > 0 && resolved.has(path)) {
+                return false;
+            }
+            // Empty-paramPath object-form: also positional.
+            if ((typeof path !== 'string' || path.length === 0) && toDropFreeForm > 0) {
+                toDropFreeForm -= 1;
+                return false;
+            }
+        }
+        return true;
+    });
+    if (remaining.length === 0) {
+        delete meta.requiresClarification;
+    }
+    else {
+        meta.requiresClarification = remaining;
+    }
+}
+/**
+ * Build a catalog snapshot for the platforms referenced by `clarifications`.
+ * If multiple clarifications reference the same platform, we union their
+ * groupId scopes — broader queries (no scope) always win.
+ */
+export async function buildCatalogSnapshot(catalog, clarifications) {
+    const platforms = new Set();
+    for (const c of clarifications) {
+        if (c.platform) {
+            platforms.add(c.platform);
+        }
+    }
+    if (platforms.size === 0) {
+        return [];
+    }
+    const out = [];
+    const seen = new Set();
+    for (const platform of platforms) {
+        const groups = await catalog.listGroups({ platform });
+        for (const g of groups) {
+            const key = `${g.platform}::${g.groupId}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            out.push(g);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=workflow-clarification.js.map