qlogicagent 2.13.4 → 2.13.5

package/dist/orchestration/workflow/workflow-patch.js

@@ -0,0 +1,369 @@
+/**
+ * WorkflowPatch — the single mutation channel for workflow editing (plan D17/D19,
+ * spec workflow-conversational-editing-spec.md §C).
+ *
+ * One change protocol for BOTH agent edits and canvas hand-edits: every edit is a list of
+ * `WorkflowPatch` ops applied transactionally to a workflow's graph. This module is the
+ * deterministic ENGINE half (no gateway, no UI, no LLM):
+ *   - applies the 8 ops to a WorkflowDef (+ workflow meta/trigger),
+ *   - enforces scoped-edit boundaries (框选批注: ops may only touch the selection subgraph,
+ *     D19) at the PROTOCOL level — not a prompt soft-constraint,
+ *   - validates the resulting graph through DagScheduler v2's invariants (acyclic minus
+ *     loopBack, edge integrity, loop maxIterations) — the spec's "patch 落库前过 validateDag".
+ *
+ * Transactional + fail-loud (§1.5): a patch is all-or-nothing. The candidate is built on a deep
+ * clone; if any op is illegal, references a missing node/edge, breaks scope, or yields an invalid
+ * graph, the WHOLE patch is rejected via `PatchError` (carrying `errors` for agent self-correction)
+ * and the input is never mutated. No partial application, no silent drop.
+ */
+import { DagScheduler } from "../dag-scheduler.js";
+import { portTypesCompatible } from "./node-schema.js";
+import { validateTrigger } from "./trigger-validation.js";
+import { validateExpressionSyntax } from "./expression.js";
+/** Thrown when a patch is rejected. `errors` is the ordered list of reasons (for self-correction). */
+export class PatchError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Patch rejected: ${errors.join("; ")}`);
+        this.errors = errors;
+        this.name = "PatchError";
+    }
+}
+// ── Apply ────────────────────────────────────────────────────────────────────
+/**
+ * Apply a patch transactionally. Returns a NEW PatchTarget (input untouched) or throws PatchError.
+ * Scope enforcement (when `scope` is set, spec §C):
+ *   - update_params / rename_node / remove_node: the node MUST be in scope.
+ *   - add_node: allowed; the new node joins the in-scope set for subsequent ops in this patch.
+ *   - add_edge / remove_edge: at least ONE endpoint must be in scope (selection-boundary edges).
+ *   - set_trigger / set_meta: workflow-global ⇒ rejected under a scoped edit.
+ */
+export function applyPatch(target, env) {
+    const errors = [];
+    const next = cloneTarget(target);
+    const nodeIndex = new Map(next.def.nodes.map(n => [n.id, n]));
+    const scope = env.scope ? new Set(env.scope) : undefined;
+    // Newly added nodes count as in-scope for later ops in the same patch (boundary growth).
+    const addedInScope = new Set();
+    const inScope = (id) => !scope || scope.has(id) || addedInScope.has(id);
+    const applied = [];
+    for (const [i, op] of env.patch.entries()) {
+        const at = `op[${i}] ${op.op}`;
+        switch (op.op) {
+            case "add_node": {
+                if (!op.node?.id)
+                    errors.push(`${at}: node.id is required`);
+                else if (nodeIndex.has(op.node.id))
+                    errors.push(`${at}: node "${op.node.id}" already exists`);
+                else {
+                    next.def.nodes.push(op.node);
+                    nodeIndex.set(op.node.id, op.node);
+                    if (scope)
+                        addedInScope.add(op.node.id);
+                }
+                break;
+            }
+            case "remove_node": {
+                if (!nodeIndex.has(op.nodeId))
+                    errors.push(`${at}: node "${op.nodeId}" not found`);
+                else if (!inScope(op.nodeId))
+                    errors.push(`${at}: node "${op.nodeId}" is outside the edit scope`);
+                else {
+                    next.def.nodes = next.def.nodes.filter(n => n.id !== op.nodeId);
+                    nodeIndex.delete(op.nodeId);
+                    // Cascade: drop every edge touching the removed node (spec §C "连带删除关联边").
+                    next.def.edges = next.def.edges.filter(e => e.from !== op.nodeId && e.to !== op.nodeId);
+                }
+                break;
+            }
+            case "update_params": {
+                const node = nodeIndex.get(op.nodeId);
+                if (!node)
+                    errors.push(`${at}: node "${op.nodeId}" not found`);
+                else if (!inScope(op.nodeId))
+                    errors.push(`${at}: node "${op.nodeId}" is outside the edit scope`);
+                else
+                    node.params = mergeParams(node.params, op.params);
+                break;
+            }
+            case "rename_node": {
+                const node = nodeIndex.get(op.nodeId);
+                if (!node)
+                    errors.push(`${at}: node "${op.nodeId}" not found`);
+                else if (!inScope(op.nodeId))
+                    errors.push(`${at}: node "${op.nodeId}" is outside the edit scope`);
+                else
+                    node.name = op.name;
+                break;
+            }
+            case "set_node_options": {
+                const node = nodeIndex.get(op.nodeId);
+                if (!node) {
+                    errors.push(`${at}: node "${op.nodeId}" not found`);
+                    break;
+                }
+                if (!inScope(op.nodeId)) {
+                    errors.push(`${at}: node "${op.nodeId}" is outside the edit scope`);
+                    break;
+                }
+                if (op.retry !== undefined) {
+                    if (op.retry === null)
+                        delete node.retry;
+                    else if (!Number.isInteger(op.retry.maxTries) || op.retry.maxTries < 1 || op.retry.maxTries > 10) {
+                        errors.push(`${at}: retry.maxTries must be an integer 1..10`);
+                    }
+                    else if (op.retry.backoffMs !== undefined && (!Number.isFinite(op.retry.backoffMs) || op.retry.backoffMs < 0)) {
+                        errors.push(`${at}: retry.backoffMs must be a non-negative number`);
+                    }
+                    else {
+                        node.retry = { maxTries: op.retry.maxTries, ...(op.retry.backoffMs !== undefined ? { backoffMs: op.retry.backoffMs } : {}) };
+                    }
+                }
+                if (op.timeoutMs !== undefined) {
+                    if (op.timeoutMs === null)
+                        delete node.timeoutMs;
+                    else if (!Number.isFinite(op.timeoutMs) || op.timeoutMs <= 0)
+                        errors.push(`${at}: timeoutMs must be a positive number`);
+                    else
+                        node.timeoutMs = op.timeoutMs;
+                }
+                if (op.onError !== undefined) {
+                    if (op.onError === null)
+                        delete node.onError;
+                    else if (op.onError !== "stop" && op.onError !== "continue" && op.onError !== "errorPort") {
+                        errors.push(`${at}: onError must be "stop"|"continue"|"errorPort"`);
+                    }
+                    else {
+                        node.onError = op.onError;
+                    }
+                }
+                break;
+            }
+            case "set_node_ui": {
+                if (!op.positions || typeof op.positions !== "object") {
+                    errors.push(`${at}: positions is required`);
+                    break;
+                }
+                for (const [nodeId, p] of Object.entries(op.positions)) {
+                    const node = nodeIndex.get(nodeId);
+                    if (!node) {
+                        errors.push(`${at}: node "${nodeId}" not found`);
+                        continue;
+                    }
+                    if (!inScope(nodeId)) {
+                        errors.push(`${at}: node "${nodeId}" is outside the edit scope`);
+                        continue;
+                    }
+                    if (p === null) {
+                        delete node.ui;
+                        continue;
+                    }
+                    if (!Number.isFinite(p?.x) || !Number.isFinite(p?.y)) {
+                        errors.push(`${at}: position for "${nodeId}" must be finite {x,y}`);
+                        continue;
+                    }
+                    node.ui = { x: p.x, y: p.y };
+                }
+                break;
+            }
+            case "add_edge": {
+                const e = op.edge;
+                if (!e?.from || !e?.to) {
+                    errors.push(`${at}: edge.from and edge.to are required`);
+                    break;
+                }
+                if (scope && !inScope(e.from) && !inScope(e.to)) {
+                    errors.push(`${at}: edge ${e.from}→${e.to} has no endpoint in the edit scope`);
+                    break;
+                }
+                // R5 手动连线:重复拒(DagScheduler.addEdge 静默幂等去重 —— 不拦的话 def.edges
+                // 会落下字面重复边,validateGraph 看不见)。识别键与 remove_edge 一致(from,to,fromPort)。
+                const fp = e.fromPort ?? "default";
+                if (next.def.edges.some(x => x.from === e.from && x.to === e.to && (x.fromPort ?? "default") === fp)) {
+                    errors.push(`${at}: 连线已存在(${e.from} → ${e.to})`);
+                    break;
+                }
+                // R5 端口类型校验(单一真相在引擎;画布的即时拒绝是本规则的镜像)。
+                const srcNode = nodeIndex.get(e.from);
+                const dstNode = nodeIndex.get(e.to);
+                const srcType = srcNode?.outPortTypes?.[fp];
+                const dstType = dstNode?.inPorts?.find(p => p.name === (e.toPort ?? "default"))?.type;
+                if (!portTypesCompatible(srcType, dstType)) {
+                    errors.push(`${at}: 端口类型不匹配:「${srcNode?.name ?? e.from}」输出 ${srcType ?? "any"},「${dstNode?.name ?? e.to}」需要 ${dstType ?? "any"} —— 接不上,请换个目标端口`);
+                    break;
+                }
+                next.def.edges.push(e);
+                break;
+            }
+            case "remove_edge": {
+                const { from, to, fromPort } = op.edge;
+                if (scope && !inScope(from) && !inScope(to))
+                    errors.push(`${at}: edge ${from}→${to} has no endpoint in the edit scope`);
+                else {
+                    const before = next.def.edges.length;
+                    next.def.edges = next.def.edges.filter(e => !(e.from === from && e.to === to && (e.fromPort ?? "default") === (fromPort ?? "default")));
+                    if (next.def.edges.length === before)
+                        errors.push(`${at}: edge ${from}→${to} not found`);
+                }
+                break;
+            }
+            case "set_trigger": {
+                if (scope)
+                    errors.push(`${at}: trigger is workflow-global and cannot be changed in a scoped edit`);
+                else if (op.trigger) {
+                    const triggerErrors = validateTrigger(op.trigger);
+                    if (triggerErrors.length > 0) {
+                        for (const e of triggerErrors)
+                            errors.push(`${at}: ${e}`);
+                    }
+                    else {
+                        next.meta.trigger = op.trigger;
+                    }
+                }
+                else {
+                    next.meta.trigger = op.trigger; // null clears the trigger
+                }
+                break;
+            }
+            case "set_meta": {
+                if (scope)
+                    errors.push(`${at}: meta is workflow-global and cannot be changed in a scoped edit`);
+                else {
+                    if (op.meta.name !== undefined)
+                        next.meta.name = op.meta.name;
+                    if (op.meta.active !== undefined)
+                        next.meta.active = op.meta.active;
+                }
+                break;
+            }
+            default: {
+                errors.push(`${at}: unknown op`);
+            }
+        }
+        if (errors.length === 0)
+            applied.push(op);
+    }
+    if (errors.length > 0)
+        throw new PatchError(errors);
+    // Graph invariants (acyclic minus loopBack, edge integrity, loop maxIterations) via DagScheduler.
+    validateGraph(next.def, errors);
+    // 静态表达式闸:create/update 一直在跑(validateWorkflowDef),patch 此前漏挂 ——
+    // 坏 {{ }} 经 update_params/add_node 写入,写入期不拦、运行期才爆(R5 真机踩到)。
+    // 同一闸、同一豁免(`=` 前缀 n8n 原文),无第二轨。
+    validateDefExpressions(next.def, errors);
+    if (errors.length > 0)
+        throw new PatchError(errors);
+    return { target: next, applied };
+}
+// ── helpers ──────────────────────────────────────────────────────────────────
+/** Shallow-merge params; an explicit `null` value deletes the key (spec §G decision). */
+function mergeParams(current, patch) {
+    const out = { ...(current ?? {}) };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null)
+            delete out[k];
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Validate a standalone WorkflowDef against DagScheduler v2's invariants (acyclic minus loopBack,
+ * edge integrity, duplicate ids, loop maxIterations + hard cap). Returns a list of human-readable
+ * errors; empty ⇒ valid. This is the SAME graph gate `applyPatch` runs, exported so every
+ * persistence path (controller create/update) enforces identical invariants — single-track, no
+ * write path may bypass validation (D17 "一个 store").
+ */
+export function validateWorkflowDef(def) {
+    const errors = [];
+    validateGraph(def, errors);
+    validateDefExpressions(def, errors);
+    return errors;
+}
+/**
+ * Static expression gate: every `{{ }}` segment in node params must parse in the restricted
+ * language (known roots / whitelist funcs / $node-only calls — validateExpressionSyntax).
+ * Catches AI-proposed n8n-isms (pipes, operators, method calls) at WRITE time with a pointable
+ * error instead of a mid-run explosion. Same single gate every write path already runs.
+ */
+function validateDefExpressions(def, errors) {
+    const walk = (value, nodeId, path) => {
+        if (typeof value === "string") {
+            // `=`-prefixed strings are n8n's expression marker — the IT-11 importer deliberately
+            // keeps UNCONVERTED originals visible (reported "manual"); they are not our language,
+            // so they pass the write gate and fail loud at run time if actually executed.
+            if (value.startsWith("="))
+                return;
+            for (const m of value.matchAll(/\{\{([\s\S]*?)\}\}/g)) {
+                const err = validateExpressionSyntax(m[1].trim());
+                if (err)
+                    errors.push(`节点「${nodeId}」参数 ${path} 的表达式「{{ ${m[1].trim()} }}」超出受限语言:${err}`);
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((v, i) => walk(v, nodeId, `${path}[${i}]`));
+            return;
+        }
+        if (value && typeof value === "object") {
+            for (const [k, v] of Object.entries(value))
+                walk(v, nodeId, path ? `${path}.${k}` : k);
+        }
+    };
+    for (const node of def.nodes) {
+        if (node.params)
+            walk(node.params, node.id, "");
+    }
+}
+/** Run the candidate graph through DagScheduler v2's validateDag (invoked on construction). */
+function validateGraph(def, errors) {
+    try {
+        const defs = def.nodes.map(n => {
+            let outPorts = n.outPorts ?? defaultOutPorts(n.kind);
+            // onError:"errorPort" adds an "error" out port (D32) — mirror the runtime's DAG build so
+            // patches wiring error edges validate.
+            if (n.onError === "errorPort" && !outPorts.includes("error"))
+                outPorts = [...outPorts, "error"];
+            return {
+                id: n.id,
+                kind: n.kind,
+                params: n.params ?? {},
+                outPorts,
+                joinPolicy: n.joinPolicy ?? "all",
+                maxIterations: n.maxIterations,
+            };
+        });
+        const dag = new DagScheduler(defs);
+        for (const e of def.edges) {
+            if (e.loopBack)
+                continue;
+            dag.addEdge({ from: e.from, to: e.to, fromPort: e.fromPort ?? "default" });
+        }
+        for (const e of def.edges) {
+            if (!e.loopBack)
+                continue;
+            dag.addEdge({ from: e.from, to: e.to, loopBack: true });
+        }
+    }
+    catch (err) {
+        errors.push(`graph invalid: ${err.message}`);
+    }
+}
+function defaultOutPorts(kind) {
+    if (kind === "if")
+        return ["true", "false"];
+    if (kind === "loop")
+        return ["loop", "done"];
+    return ["default"];
+}
+function cloneTarget(target) {
+    return {
+        def: {
+            ...target.def,
+            nodes: target.def.nodes.map(n => ({ ...n, params: n.params ? { ...n.params } : undefined })),
+            edges: target.def.edges.map(e => ({ ...e })),
+            vars: target.def.vars ? { ...target.def.vars } : undefined,
+        },
+        meta: { ...target.meta },
+    };
+}

package/dist/orchestration/workflow/workflow-render.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Compact workflow renderer — the "workflow-as-context" feeder (plan D17,
+ * spec workflow-conversational-editing-spec.md §B).
+ *
+ * Every page-chat user turn injects the LATEST workflow as compact, deterministic text (NOT raw
+ * JSON: cheaper tokens, never stale, stable node ids the agent references back in a WorkflowPatch).
+ * This module is the deterministic ENGINE half of that loop — the agent reads this rendering and
+ * emits a `WorkflowPatch` (workflow-patch.ts) against the shown `rev`. Pure function: no gateway,
+ * no LLM, no I/O.
+ *
+ * Determinism (§1.5): node order follows the def's node array (stable, persisted order); param
+ * keys are sorted; expressions (`{{ }}`) render verbatim so the agent can copy them into bindings.
+ * Large graphs truncate with an explicit hint to call `workflow.get` for the full definition.
+ */
+import type { WorkflowDef } from "./node-schema.js";
+import type { TriggerDef } from "./workflow-patch.js";
+/** The minimal shape needed to render (WorkflowRecord satisfies it). */
+export interface RenderableWorkflow {
+    name: string;
+    rev: number;
+    active: boolean;
+    trigger?: TriggerDef | null;
+    def: WorkflowDef;
+}
+export interface RenderOptions {
+    /** Max nodes to list before truncating (default 50). */
+    maxNodes?: number;
+    /** Max rendered length of a single param value before eliding (default 60). */
+    maxValueLen?: number;
+}
+/**
+ * Render a workflow as compact agent-context text. Shape (spec §B):
+ *
+ *   Workflow "晨报" (rev 7, trigger: schedule "0 9 * * *", active)
+ *   nodes:
+ *     n1 [agent]   prompt="抓取今日新闻要点"   out: default
+ *     n3 [if]      cond={{ $json.count > 0 }}   out: true,false
+ *   edges:
+ *     n1.default→n2.default ; n3.true→n4.default
+ */
+export declare function renderWorkflow(wf: RenderableWorkflow, opts?: RenderOptions): string;

package/dist/orchestration/workflow/workflow-render.js

@@ -0,0 +1,108 @@
+/**
+ * Compact workflow renderer — the "workflow-as-context" feeder (plan D17,
+ * spec workflow-conversational-editing-spec.md §B).
+ *
+ * Every page-chat user turn injects the LATEST workflow as compact, deterministic text (NOT raw
+ * JSON: cheaper tokens, never stale, stable node ids the agent references back in a WorkflowPatch).
+ * This module is the deterministic ENGINE half of that loop — the agent reads this rendering and
+ * emits a `WorkflowPatch` (workflow-patch.ts) against the shown `rev`. Pure function: no gateway,
+ * no LLM, no I/O.
+ *
+ * Determinism (§1.5): node order follows the def's node array (stable, persisted order); param
+ * keys are sorted; expressions (`{{ }}`) render verbatim so the agent can copy them into bindings.
+ * Large graphs truncate with an explicit hint to call `workflow.get` for the full definition.
+ */
+/**
+ * Render a workflow as compact agent-context text. Shape (spec §B):
+ *
+ *   Workflow "晨报" (rev 7, trigger: schedule "0 9 * * *", active)
+ *   nodes:
+ *     n1 [agent]   prompt="抓取今日新闻要点"   out: default
+ *     n3 [if]      cond={{ $json.count > 0 }}   out: true,false
+ *   edges:
+ *     n1.default→n2.default ; n3.true→n4.default
+ */
+export function renderWorkflow(wf, opts = {}) {
+    const maxNodes = opts.maxNodes ?? 50;
+    const maxValueLen = opts.maxValueLen ?? 60;
+    const header = `Workflow ${JSON.stringify(wf.name)} (rev ${wf.rev}, trigger: ${renderTrigger(wf.trigger)}, ${wf.active ? "active" : "inactive"})`;
+    const nodes = wf.def.nodes;
+    const shown = nodes.slice(0, maxNodes);
+    const nodeLines = shown.map(n => "  " + renderNode(n, maxValueLen));
+    const nodesBlock = nodes.length === 0 ? "nodes: (none)" : ["nodes:", ...nodeLines].join("\n");
+    const truncated = nodes.length > maxNodes
+        ? `\n  … ${nodes.length - maxNodes} more node(s); call workflow.get for the full definition`
+        : "";
+    const edgesBlock = renderEdges(wf.def.edges);
+    return `${header}\n${nodesBlock}${truncated}\n${edgesBlock}`;
+}
+// ── pieces ───────────────────────────────────────────────────────────────────
+function renderTrigger(t) {
+    if (!t)
+        return "none";
+    switch (t.type) {
+        case "manual":
+            return "manual";
+        case "schedule":
+            return `schedule ${JSON.stringify(t.cron)}`;
+        case "im-message":
+            return t.match
+                ? `im-message ${t.channel} match=${JSON.stringify(t.match)}`
+                : `im-message ${t.channel}`;
+        case "webhook":
+            return `webhook ${t.path}`;
+        case "intent":
+            return `intent ${t.phrases.map((p) => JSON.stringify(p)).join(" / ")}${t.semantic ? " +semantic" : ""}`;
+        case "form":
+            return `form [${t.fields.map((f) => f.key).join(", ")}]`;
+    }
+}
+function renderNode(n, maxValueLen) {
+    const name = n.name ? ` "${n.name}"` : "";
+    const params = renderParams(n.params, maxValueLen);
+    const outPorts = (n.outPorts ?? defaultOutPorts(n.kind)).join(",");
+    const parts = [`${n.id} [${n.kind}]${name}`];
+    if (params)
+        parts.push(params);
+    parts.push(`out: ${outPorts}`);
+    return parts.join("  ");
+}
+function renderParams(params, maxValueLen) {
+    if (!params)
+        return "";
+    const keys = Object.keys(params).sort();
+    if (keys.length === 0)
+        return "";
+    return keys.map(k => `${k}=${renderValue(params[k], maxValueLen)}`).join(" ");
+}
+function renderValue(v, maxValueLen) {
+    let s;
+    if (typeof v === "string") {
+        // Expressions render verbatim so the agent can copy them into bindings.
+        s = v.includes("{{") ? v : JSON.stringify(v);
+    }
+    else {
+        s = JSON.stringify(v);
+    }
+    if (s.length > maxValueLen)
+        s = s.slice(0, maxValueLen - 1) + "…";
+    return s;
+}
+function renderEdges(edges) {
+    if (edges.length === 0)
+        return "edges: (none)";
+    const parts = edges.map(e => {
+        const fromPort = e.fromPort ?? "default";
+        const toPort = e.toPort ?? "default";
+        const loop = e.loopBack ? " (loopBack)" : "";
+        return `${e.from}.${fromPort}→${e.to}.${toPort}${loop}`;
+    });
+    return `edges:\n  ${parts.join(" ; ")}`;
+}
+function defaultOutPorts(kind) {
+    if (kind === "if")
+        return ["true", "false"];
+    if (kind === "loop")
+        return ["loop", "done"];
+    return ["default"];
+}