qlogicagent 2.13.3 → 2.13.5

package/dist/orchestration/workflow/expression.js

@@ -0,0 +1,474 @@
+/**
+ * Restricted workflow expression evaluator (spec: workflow-dataflow-and-triggers-spec.md §A3–A4,
+ * plan D6). Used to bind node params to upstream data.
+ *
+ * HARD SECURITY LINE: NO arbitrary JS eval. This is a tiny recursive-descent interpreter over a
+ * fixed grammar — property/index path access + a whitelist of pure functions only. Unattended
+ * triggers make eval an injection surface, so arbitrary script is explicitly out of v1.
+ *
+ * Supported:
+ *   - context roots: $input · $json · $node("name") · $now · $vars · $trigger
+ *   - accessors: `.prop` and `[index]` / `["key"]`
+ *   - literals: string ('..' / ".."), number, true/false/null
+ *   - whitelist functions: len, upper, lower, default, jsonpath, date
+ *
+ * fail-loud: unknown roots/functions, reads through null/undefined, and prototype-escape keys
+ * all throw. Absent *leaf* keys evaluate to undefined (so `default(x, fb)` works).
+ */
+const FORBIDDEN_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+// ── Public API ───────────────────────────────────────────────
+/**
+ * Evaluate a single expression body (the text inside `{{ }}`, braces stripped).
+ * Returns the raw value (object/array/number/string/boolean/null/undefined).
+ */
+export function evaluateExpression(body, ctx) {
+    const tokens = tokenize(body);
+    const parser = new Parser(tokens, body);
+    const ast = parser.parseExpression();
+    parser.expectEnd();
+    return evalNode(ast, ctx);
+}
+/**
+ * Static syntax+semantics gate: is `body` a valid expression of THIS language (no evaluation)?
+ * Beyond the grammar, it statically enforces what evalNode would reject at run time anyway:
+ * known context roots, whitelist function names, and "$node(...) is the only callable".
+ * Returns null when valid, else the error message. The n8n expression converter uses this as
+ * its single-track output gate — anything it emits must pass here.
+ */
+export function validateExpressionSyntax(body) {
+    try {
+        const tokens = tokenize(body);
+        const parser = new Parser(tokens, body);
+        const ast = parser.parseExpression();
+        parser.expectEnd();
+        checkStatic(ast);
+        return null;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
+const KNOWN_ROOTS = new Set(["input", "json", "node", "now", "vars", "trigger"]);
+const WHITELIST_FUNCS = new Set(["len", "upper", "lower", "default", "jsonpath", "date"]);
+/** Mirror evalNode's run-time rejections statically (no context needed). */
+function checkStatic(node) {
+    switch (node.type) {
+        case "root":
+            if (!KNOWN_ROOTS.has(node.name)) {
+                throw new Error(`Unknown context root "$${node.name}" (allowed: $input $json $node $now $vars $trigger)`);
+            }
+            return;
+        case "lit":
+            return;
+        case "func":
+            if (!WHITELIST_FUNCS.has(node.name)) {
+                throw new Error(`Unknown function "${node.name}" (whitelist: ${[...WHITELIST_FUNCS].join(", ")})`);
+            }
+            node.args.forEach(checkStatic);
+            return;
+        case "prop":
+            checkStatic(node.target);
+            return;
+        case "index":
+            checkStatic(node.target);
+            if (typeof node.key !== "number" && typeof node.key !== "string") {
+                throw new Error("index key must be a number or string literal");
+            }
+            return;
+        case "call":
+            if (!(node.target.type === "root" && node.target.name === "node")) {
+                throw new Error(`Only $node(...) is callable in this position`);
+            }
+            node.args.forEach(checkStatic);
+            return;
+    }
+}
+/**
+ * Resolve a binding template:
+ *   - exactly `{{ expr }}` (whole string) → returns the raw evaluated value (keeps type)
+ *   - text with embedded `{{ }}` → string interpolation (each sub-expression stringified;
+ *     a sub-expression resolving to null/undefined throws — fail-loud)
+ *   - no `{{ }}` → returned unchanged
+ */
+export function resolveBinding(template, ctx) {
+    const whole = template.match(/^\s*\{\{([\s\S]*)\}\}\s*$/);
+    if (whole) {
+        return evaluateExpression(whole[1], ctx);
+    }
+    if (!template.includes("{{"))
+        return template;
+    return template.replace(/\{\{([\s\S]*?)\}\}/g, (_m, expr) => {
+        const v = evaluateExpression(expr, ctx);
+        if (v === null || v === undefined) {
+            throw new Error(`Expression "{{${expr.trim()}}}" resolved to ${v} in string interpolation`);
+        }
+        return typeof v === "object" ? JSON.stringify(v) : String(v);
+    });
+}
+/**
+ * Recursively resolve every string value in a params object against the context.
+ * Non-string leaves are returned untouched. Arrays and nested objects are walked.
+ */
+export function resolveParams(params, ctx) {
+    return resolveValue(params, ctx);
+}
+function resolveValue(value, ctx) {
+    if (typeof value === "string")
+        return resolveBinding(value, ctx);
+    if (Array.isArray(value))
+        return value.map(v => resolveValue(v, ctx));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = resolveValue(v, ctx);
+        }
+        return out;
+    }
+    return value;
+}
+function tokenize(src) {
+    const toks = [];
+    let i = 0;
+    const isIdStart = (c) => /[A-Za-z_]/.test(c);
+    const isIdChar = (c) => /[A-Za-z0-9_]/.test(c);
+    while (i < src.length) {
+        const c = src[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        if (c === "$") {
+            i++;
+            let name = "";
+            while (i < src.length && isIdChar(src[i]))
+                name += src[i++];
+            if (!name)
+                throw new Error(`Bare "$" is not a valid expression`);
+            toks.push({ t: "dollar", v: name });
+            continue;
+        }
+        if (isIdStart(c)) {
+            let name = "";
+            while (i < src.length && isIdChar(src[i]))
+                name += src[i++];
+            toks.push({ t: "id", v: name });
+            continue;
+        }
+        if (/[0-9]/.test(c) || (c === "-" && /[0-9]/.test(src[i + 1] ?? ""))) {
+            let num = src[i++];
+            while (i < src.length && /[0-9.]/.test(src[i]))
+                num += src[i++];
+            toks.push({ t: "num", v: num });
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            const quote = c;
+            i++;
+            let str = "";
+            while (i < src.length && src[i] !== quote) {
+                if (src[i] === "\\" && i + 1 < src.length) {
+                    str += src[i + 1];
+                    i += 2;
+                }
+                else
+                    str += src[i++];
+            }
+            if (src[i] !== quote)
+                throw new Error(`Unterminated string literal in expression`);
+            i++;
+            toks.push({ t: "str", v: str });
+            continue;
+        }
+        if (".[](),".includes(c)) {
+            toks.push({ t: "punc", v: c });
+            i++;
+            continue;
+        }
+        throw new Error(`Unexpected character "${c}" in expression`);
+    }
+    return toks;
+}
+// ── Parser (recursive descent) ───────────────────────────────
+class Parser {
+    toks;
+    src;
+    pos = 0;
+    constructor(toks, src) {
+        this.toks = toks;
+        this.src = src;
+    }
+    parseExpression() {
+        return this.parseAccessors(this.parseAtom());
+    }
+    peek() { return this.toks[this.pos]; }
+    next() { return this.toks[this.pos++]; }
+    expectEnd() {
+        if (this.pos !== this.toks.length) {
+            throw new Error(`Unexpected trailing tokens in expression "${this.src.trim()}"`);
+        }
+    }
+    parseAtom() {
+        const tok = this.peek();
+        if (!tok)
+            throw new Error(`Empty expression`);
+        if (tok.t === "dollar") {
+            this.next();
+            return { type: "root", name: tok.v };
+        }
+        if (tok.t === "num") {
+            this.next();
+            return { type: "lit", value: Number(tok.v) };
+        }
+        if (tok.t === "str") {
+            this.next();
+            return { type: "lit", value: tok.v };
+        }
+        if (tok.t === "id") {
+            // keyword literal or function call
+            if (tok.v === "true") {
+                this.next();
+                return { type: "lit", value: true };
+            }
+            if (tok.v === "false") {
+                this.next();
+                return { type: "lit", value: false };
+            }
+            if (tok.v === "null") {
+                this.next();
+                return { type: "lit", value: null };
+            }
+            this.next();
+            if (this.peek()?.t === "punc" && this.peek().v === "(") {
+                const args = this.parseArgs();
+                return { type: "func", name: tok.v, args };
+            }
+            throw new Error(`Bare identifier "${tok.v}" is not allowed (only whitelist function calls)`);
+        }
+        if (tok.t === "punc" && tok.v === "(") {
+            this.next();
+            const inner = this.parseExpression();
+            this.expectPunc(")");
+            return inner;
+        }
+        throw new Error(`Unexpected token "${tok.v}" in expression`);
+    }
+    parseAccessors(target) {
+        let node = target;
+        while (true) {
+            const tok = this.peek();
+            if (!tok || tok.t !== "punc")
+                break;
+            if (tok.v === ".") {
+                this.next();
+                const id = this.next();
+                if (!id || (id.t !== "id" && id.t !== "num")) {
+                    throw new Error(`Expected property name after "."`);
+                }
+                node = { type: "prop", target: node, key: id.v };
+            }
+            else if (tok.v === "[") {
+                this.next();
+                const key = this.next();
+                let keyVal;
+                if (key.t === "num")
+                    keyVal = Number(key.v);
+                else if (key.t === "str")
+                    keyVal = key.v;
+                else
+                    throw new Error(`Index must be a number or string literal`);
+                this.expectPunc("]");
+                node = { type: "index", target: node, key: keyVal };
+            }
+            else if (tok.v === "(") {
+                const args = this.parseArgs();
+                node = { type: "call", target: node, args };
+            }
+            else
+                break;
+        }
+        return node;
+    }
+    parseArgs() {
+        this.expectPunc("(");
+        const args = [];
+        if (this.peek()?.t === "punc" && this.peek().v === ")") {
+            this.next();
+            return args;
+        }
+        while (true) {
+            args.push(this.parseExpression());
+            const tok = this.next();
+            if (!tok)
+                throw new Error(`Unterminated argument list`);
+            if (tok.t === "punc" && tok.v === ")")
+                break;
+            if (!(tok.t === "punc" && tok.v === ","))
+                throw new Error(`Expected "," or ")" in argument list`);
+        }
+        return args;
+    }
+    expectPunc(p) {
+        const tok = this.next();
+        if (!tok || tok.t !== "punc" || tok.v !== p) {
+            throw new Error(`Expected "${p}" in expression`);
+        }
+    }
+}
+// ── Evaluator ────────────────────────────────────────────────
+/** Sentinel produced by the `$node` root; only callable, not directly usable. */
+const NODE_ACCESSOR = Symbol("nodeAccessor");
+function evalNode(node, ctx) {
+    switch (node.type) {
+        case "lit":
+            return node.value;
+        case "root":
+            return evalRoot(node.name, ctx);
+        case "func":
+            return evalFunc(node.name, node.args.map(a => evalNode(a, ctx)));
+        case "prop":
+            return access(evalNode(node.target, ctx), node.key);
+        case "index":
+            return access(evalNode(node.target, ctx), node.key);
+        case "call": {
+            const target = evalNode(node.target, ctx);
+            if (target === NODE_ACCESSOR) {
+                const args = node.args.map(a => evalNode(a, ctx));
+                if (args.length !== 1 || typeof args[0] !== "string") {
+                    throw new Error(`$node(...) takes exactly one string argument`);
+                }
+                const rec = ctx.nodes?.[args[0]];
+                if (!rec)
+                    throw new Error(`$node("${args[0]}") not found (not completed or unknown)`);
+                return rec;
+            }
+            throw new Error(`Only $node(...) is callable in this position`);
+        }
+    }
+}
+function evalRoot(name, ctx) {
+    switch (name) {
+        case "input": return ctx.input ?? {};
+        case "json": return ctx.json ?? {};
+        case "vars": return ctx.vars ?? {};
+        case "trigger": return ctx.trigger ?? {};
+        case "now": return (ctx.now ? ctx.now() : new Date()).toISOString();
+        case "node": return NODE_ACCESSOR;
+        default:
+            throw new Error(`Unknown context root "$${name}" (allowed: $input $json $node $now $vars $trigger)`);
+    }
+}
+function access(target, key) {
+    if (typeof key === "string" && FORBIDDEN_KEYS.has(key)) {
+        throw new Error(`Access to "${key}" is forbidden`);
+    }
+    if (target === null || target === undefined) {
+        throw new Error(`Cannot read "${key}" of ${target}`);
+    }
+    if (typeof key === "number") {
+        if (!Array.isArray(target)) {
+            throw new Error(`Cannot index non-array with [${key}]`);
+        }
+        return target[key];
+    }
+    return target[key];
+}
+// ── Whitelist functions ──────────────────────────────────────
+function evalFunc(name, args) {
+    switch (name) {
+        case "len": {
+            const x = args[0];
+            if (typeof x === "string" || Array.isArray(x))
+                return x.length;
+            if (x && typeof x === "object")
+                return Object.keys(x).length;
+            throw new Error(`len() expects string/array/object, got ${typeof x}`);
+        }
+        case "upper":
+            return String(requireArg(args, 0, "upper")).toUpperCase();
+        case "lower":
+            return String(requireArg(args, 0, "lower")).toLowerCase();
+        case "default":
+            return args[0] === null || args[0] === undefined ? args[1] : args[0];
+        case "jsonpath":
+            return jsonpath(args[0], String(requireArg(args, 1, "jsonpath")));
+        case "date":
+            return dateFn(args);
+        // comparison / logic (pure, total) — conditions use these instead of operators (no eval, D6)
+        case "eq": return deepEqual(args[0], args[1]);
+        case "ne": return !deepEqual(args[0], args[1]);
+        case "gt": return cmp(args[0], args[1]) > 0;
+        case "gte": return cmp(args[0], args[1]) >= 0;
+        case "lt": return cmp(args[0], args[1]) < 0;
+        case "lte": return cmp(args[0], args[1]) <= 0;
+        case "not": return !truthy(requireArg(args, 0, "not"));
+        case "and": return args.every(truthy);
+        case "or": return args.some(truthy);
+        case "contains": return contains(args[0], args[1]);
+        default:
+            throw new Error(`Unknown function "${name}()" (whitelist: len upper lower default jsonpath date eq ne gt gte lt lte not and or contains)`);
+    }
+}
+function truthy(x) {
+    return Boolean(x);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a && b && typeof a === "object")
+        return JSON.stringify(a) === JSON.stringify(b);
+    return false;
+}
+/** Compare two values; numbers numerically, strings lexically. Mismatched types → fail-loud. */
+function cmp(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    if (typeof a === "string" && typeof b === "string")
+        return a < b ? -1 : a > b ? 1 : 0;
+    throw new Error(`Cannot compare ${typeof a} with ${typeof b}`);
+}
+function contains(haystack, needle) {
+    if (typeof haystack === "string")
+        return haystack.includes(String(needle));
+    if (Array.isArray(haystack))
+        return haystack.some(x => deepEqual(x, needle));
+    throw new Error(`contains() expects string/array as first argument`);
+}
+function requireArg(args, i, fn) {
+    if (args.length <= i || args[i] === undefined) {
+        throw new Error(`${fn}() missing required argument #${i + 1}`);
+    }
+    return args[i];
+}
+/** Navigate `obj` by a dotted/indexed path like "a.b[0].c". Absent leaf → undefined. */
+function jsonpath(obj, path) {
+    const parts = path.match(/[^.[\]]+/g) ?? [];
+    let cur = obj;
+    for (const part of parts) {
+        if (FORBIDDEN_KEYS.has(part))
+            throw new Error(`jsonpath segment "${part}" is forbidden`);
+        if (cur === null || cur === undefined)
+            return undefined;
+        const idx = /^\d+$/.test(part) ? Number(part) : part;
+        cur = cur[idx];
+    }
+    return cur;
+}
+/** date(): now ISO · date(v): ISO of v · date(v, fmt): formatted with YYYY MM DD HH mm ss. */
+function dateFn(args) {
+    const d = args.length === 0 ? new Date() : new Date(args[0]);
+    if (Number.isNaN(d.getTime()))
+        throw new Error(`date() received an invalid date: ${String(args[0])}`);
+    if (args.length < 2)
+        return d.toISOString();
+    const fmt = String(args[1]);
+    const pad = (n) => String(n).padStart(2, "0");
+    return fmt
+        .replace(/YYYY/g, String(d.getUTCFullYear()))
+        .replace(/MM/g, pad(d.getUTCMonth() + 1))
+        .replace(/DD/g, pad(d.getUTCDate()))
+        .replace(/HH/g, pad(d.getUTCHours()))
+        .replace(/mm/g, pad(d.getUTCMinutes()))
+        .replace(/ss/g, pad(d.getUTCSeconds()));
+}

package/dist/orchestration/workflow/host-executors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Host-backed NodeExecutors (M3 bridge contract; plan D12/D13, spec §B).
+ *
+ * The engine is a pure executor: kinds that need real-world capabilities (agent / tool / http /
+ * mcp / channel) are fulfilled by an injected `ExecutorHost`. In production the openclaw gateway
+ * (or the qlogicagent CLI host) provides a real host; the engine never imports those subsystems.
+ *
+ * These executors are REAL (not mocks): they read the node's resolved params + inputs and delegate
+ * to the host. fail-loud — invoking a host-backed kind with no host throws (no silent fallback).
+ */
+import type { NodeExecutor } from "./node-schema.js";
+/** The host-backed kinds. Register these into a NodeRegistry to enable agent/tool/http/mcp/channel/skill/memory/subworkflow/approval. */
+export declare const hostExecutors: Record<string, NodeExecutor>;
+/** Host-backed kind names (used by callers to know which kinds need a host). */
+export declare const HOST_BACKED_KINDS: string[];