qlogicagent 2.13.3 → 2.13.5

package/dist/orchestration/workflow/n8n-import.js

@@ -0,0 +1,319 @@
+/**
+ * n8n workflow JSON import — read-format-only translator (plan M5 §2.1: "导入 n8n workflow JSON
+ * (读格式,不打包其代码)"), deepened for IT-11 (spec D35).
+ *
+ * Converts an n8n workflow export (its public JSON shape: `nodes` + `connections`) into our own
+ * WorkflowDef. This reads n8n's data FORMAT only — it links/embeds NONE of n8n's runtime code, so
+ * the SUL licensing concern (plan §2.1 / risk register) does not apply.
+ *
+ * Error model (IT-11): STRUCTURAL problems (malformed JSON, duplicate/missing node names, dangling
+ * connections) stay fail-loud — the graph identity itself is broken, nothing useful survives.
+ * SEMANTIC gaps (unmapped node type, inconvertible expression, Code-node JS) DEGRADE EXPLICITLY:
+ * the node lands as kind "manual" (its executor throws at run time — never silently passes
+ * through), the original n8n type/params are preserved for the human, and every degradation is
+ * itemized in the returned ConversionReport. Nothing is silently dropped; no JS is ever executed
+ * (D6 hard line — n8n Code nodes are flagged manual, not emulated).
+ *
+ * Credentials: n8n nodes carry `credentials: {type: {id,name}}` references. The secrets are NOT
+ * in the export — we extract them as CredentialRequirement entries (mapped to vault types, D29)
+ * so the import UI can walk the user through re-binding.
+ */
+import { convertN8nParams } from "./n8n-expression.js";
+/** Curated n8n type → our node kind. Anything absent degrades to "manual" (explicit, reported). */
+const N8N_TYPE_MAP = {
+    "n8n-nodes-base.set": "set",
+    "n8n-nodes-base.if": "if",
+    "n8n-nodes-base.merge": "merge",
+    "n8n-nodes-base.noOp": "passthrough",
+    "n8n-nodes-base.httpRequest": "http",
+    "n8n-nodes-base.manualTrigger": "trigger",
+    "n8n-nodes-base.scheduleTrigger": "trigger",
+    "n8n-nodes-base.cron": "trigger",
+    "n8n-nodes-base.webhook": "trigger",
+    // IT-11 expansion — D34 kinds give these real landing targets.
+    "n8n-nodes-base.formTrigger": "trigger",
+    "n8n-nodes-base.switch": "switch",
+    "n8n-nodes-base.filter": "filter",
+    "n8n-nodes-base.wait": "wait",
+    "n8n-nodes-base.aggregate": "aggregate",
+    "n8n-nodes-base.executeWorkflow": "subworkflow",
+};
+/** n8n credential type → suggested vault type (D29). Unknown types suggest "custom". */
+const N8N_CREDENTIAL_TYPE_MAP = {
+    httpBasicAuth: "basic",
+    httpBearerAuth: "bearer",
+    httpHeaderAuth: "custom",
+    httpQueryAuth: "custom",
+    oAuth2Api: "oauth2",
+    httpCustomAuth: "custom",
+};
+/** n8n types that are pure annotations — dropping them loses no behavior (still reported). */
+const N8N_SKIP_TYPES = new Set(["n8n-nodes-base.stickyNote"]);
+/** n8n types that RUN CODE — always manual (D6: we never execute imported JS/Python). */
+const N8N_CODE_TYPES = new Set([
+    "n8n-nodes-base.code",
+    "n8n-nodes-base.function",
+    "n8n-nodes-base.functionItem",
+]);
+/** Thrown when an n8n workflow is STRUCTURALLY untranslatable. Carries every problem found. */
+export class N8nImportError extends Error {
+    errors;
+    constructor(errors) {
+        super(`n8n import rejected: ${errors.join("; ")}`);
+        this.errors = errors;
+        this.name = "N8nImportError";
+    }
+}
+/**
+ * Convert an n8n workflow (a JSON string or already-parsed object) into a WorkflowDef + report.
+ * The returned def is NOT yet graph-validated — pass it to `validateWorkflowDef` / a controller
+ * write path, which is the single existing invariant gate.
+ */
+export function convertN8nWorkflow(input, workflowId) {
+    const wf = parseWorkflow(input);
+    const errors = [];
+    const report = {
+        status: "full",
+        nodes: [],
+        expressions: { converted: 0, manual: [] },
+        credentials: [],
+        notes: [],
+    };
+    // Node names are n8n's identity (connections reference them); they must be unique + non-empty.
+    const seen = new Set();
+    const skipped = new Set();
+    const nodes = [];
+    for (const [i, n] of wf.nodes.entries()) {
+        if (typeof n?.name !== "string" || n.name === "") {
+            errors.push(`nodes[${i}] has a missing/empty name`);
+            continue;
+        }
+        if (seen.has(n.name)) {
+            errors.push(`duplicate node name "${n.name}"`);
+            continue;
+        }
+        seen.add(n.name);
+        if (typeof n.type !== "string" || n.type === "") {
+            errors.push(`node "${n.name}" has a missing/empty type`);
+            continue;
+        }
+        if (N8N_SKIP_TYPES.has(n.type)) {
+            skipped.add(n.name);
+            report.nodes.push({ id: n.name, n8nType: n.type, outcome: "skipped", notes: ["纯注释节点,无行为,已略过"] });
+            continue;
+        }
+        extractCredentials(n, report);
+        const nodeReport = { id: n.name, n8nType: n.type, outcome: "converted", notes: [] };
+        report.nodes.push(nodeReport);
+        let kind = N8N_TYPE_MAP[n.type];
+        if (N8N_CODE_TYPES.has(n.type)) {
+            kind = "manual";
+            nodeReport.outcome = "manual";
+            nodeReport.notes.push("Code 节点含任意 JS — 本系统不执行导入代码(安全红线),请用受限「字段映射 transform」或 AI 节点重做此步");
+        }
+        else if (!kind) {
+            kind = "manual";
+            nodeReport.outcome = "manual";
+            nodeReport.notes.push(`未映射的 n8n 节点类型「${n.type}」,请人工换成对应节点`);
+        }
+        // Expression conversion (IT-11): deep-walk params, converting `={{ }}` strings.
+        const stats = { converted: 0, manual: [], notes: [] };
+        const convertedParams = convertN8nParams({ ...(n.parameters ?? {}) }, stats);
+        report.expressions.converted += stats.converted;
+        for (const m of stats.manual) {
+            report.expressions.manual.push({ nodeId: n.name, ...m });
+            nodeReport.notes.push(`参数 ${m.path}:${m.reason}`);
+            if (nodeReport.outcome === "converted")
+                nodeReport.outcome = "partial";
+        }
+        report.notes.push(...stats.notes.filter((x) => !report.notes.includes(x)));
+        const node = {
+            id: n.name,
+            kind,
+            name: n.name,
+            params: { ...convertedParams, _n8nType: n.type },
+        };
+        if (Array.isArray(n.position) && Number.isFinite(n.position[0]) && Number.isFinite(n.position[1])) {
+            node.ui = { x: n.position[0], y: n.position[1] };
+        }
+        if (kind === "if")
+            node.outPorts = ["true", "false"];
+        applyKindSpecificConversion(node, kind, nodeReport);
+        nodes.push(node);
+    }
+    const edges = wf.connections ? buildEdges(wf.connections, seen, skipped, nodes, errors) : [];
+    if (nodes.length === 0 && errors.length === 0) {
+        errors.push("workflow has no nodes");
+    }
+    if (errors.length > 0)
+        throw new N8nImportError(errors);
+    report.status = report.nodes.some((r) => r.outcome === "manual")
+        ? "manual"
+        : report.nodes.some((r) => r.outcome === "partial") || report.expressions.manual.length > 0
+            ? "partial"
+            : "full";
+    return {
+        name: typeof wf.name === "string" && wf.name !== "" ? wf.name : workflowId,
+        def: { id: workflowId, nodes, edges },
+        report,
+    };
+}
+/** Parameter-shape conversions for kinds whose n8n params have a direct equivalent. */
+function applyKindSpecificConversion(node, kind, nodeReport) {
+    const p = node.params;
+    if (kind === "wait") {
+        // n8n: {amount, unit: seconds|minutes|hours} → ours: {ms}
+        const amount = typeof p.amount === "number" ? p.amount : Number(p.amount);
+        const unit = typeof p.unit === "string" ? p.unit : "seconds";
+        const factor = unit === "hours" ? 3_600_000 : unit === "minutes" ? 60_000 : 1_000;
+        if (Number.isFinite(amount) && amount > 0) {
+            p.ms = Math.min(3_600_000, Math.round(amount * factor));
+            if (amount * factor > 3_600_000)
+                nodeReport.notes.push("等待超过 1 小时被截到上限 3600s(更长等待是后续「持久挂起」能力)");
+        }
+        else {
+            nodeReport.outcome = nodeReport.outcome === "manual" ? "manual" : "partial";
+            nodeReport.notes.push("wait 时长参数无法解析,请在节点上补「等待秒数」");
+        }
+        return;
+    }
+    if (kind === "subworkflow") {
+        // n8n executeWorkflow: {workflowId: {value} | string} → ours: {workflowId}
+        const wid = typeof p.workflowId === "object" && p.workflowId !== null
+            ? p.workflowId.value
+            : p.workflowId;
+        if (typeof wid === "string" && wid) {
+            p.workflowId = wid;
+            nodeReport.notes.push("子流程目标沿用 n8n 工作流 id,请确认/改绑本系统中的目标工作流");
+            if (nodeReport.outcome === "converted")
+                nodeReport.outcome = "partial";
+        }
+        else {
+            nodeReport.outcome = nodeReport.outcome === "manual" ? "manual" : "partial";
+            nodeReport.notes.push("未能取出子流程目标,请在节点上选择要调用的工作流");
+        }
+        return;
+    }
+    if (kind === "switch" || kind === "filter") {
+        // n8n's structured conditions (operators, type coercion) exceed our restricted language —
+        // the node lands with original params preserved; conditions need a human pass.
+        nodeReport.outcome = nodeReport.outcome === "manual" ? "manual" : "partial";
+        nodeReport.notes.push(`n8n 的结构化条件(运算符/类型比较)超出受限表达式,请在节点上重写${kind === "switch" ? " cases" : "保留条件"}`);
+    }
+}
+/** Extract credential references (secrets are never in the export — only id/name pointers). */
+function extractCredentials(n, report) {
+    if (!n.credentials || typeof n.credentials !== "object")
+        return;
+    for (const [credType, ref] of Object.entries(n.credentials)) {
+        report.credentials.push({
+            nodeId: n.name,
+            n8nCredentialType: credType,
+            label: ref?.name,
+            suggestedVaultType: N8N_CREDENTIAL_TYPE_MAP[credType] ?? "custom",
+        });
+    }
+}
+function parseWorkflow(input) {
+    let obj;
+    if (typeof input === "string") {
+        try {
+            obj = JSON.parse(input);
+        }
+        catch (e) {
+            throw new N8nImportError([`invalid JSON: ${e.message}`]);
+        }
+    }
+    else {
+        obj = input;
+    }
+    if (!obj || typeof obj !== "object") {
+        throw new N8nImportError(["workflow must be a JSON object"]);
+    }
+    const wf = obj;
+    if (!Array.isArray(wf.nodes)) {
+        throw new N8nImportError(["workflow.nodes must be an array"]);
+    }
+    if (wf.connections !== undefined && (typeof wf.connections !== "object" || wf.connections === null)) {
+        throw new N8nImportError(["workflow.connections must be an object"]);
+    }
+    return { name: wf.name, nodes: wf.nodes, connections: wf.connections ?? {} };
+}
+/**
+ * Translate n8n's `connections` map into data edges. n8n keys connections by SOURCE NAME; `main`
+ * is an array indexed by OUTPUT port; each entry is a list of targets `{ node, index }`.
+ * fromPort: output index 0 → "default" (or "true" for an `if`); index 1 on an `if` → "false";
+ * a `switch` maps output index N → declared port (case_N). Edges touching SKIPPED annotation
+ * nodes are dropped silently-safe (the node has no behavior). Other unmodeled fan-outs fail loud.
+ */
+function buildEdges(connections, knownNames, skipped, nodes, errors) {
+    const kindOf = new Map(nodes.map(n => [n.id, n.kind]));
+    const edges = [];
+    // Deterministic order: sort source names; preserve n8n's array order for ports/targets.
+    for (const from of Object.keys(connections).sort()) {
+        if (skipped.has(from))
+            continue;
+        if (!knownNames.has(from)) {
+            errors.push(`connection source "${from}" is not a declared node`);
+            continue;
+        }
+        const main = connections[from]?.main;
+        if (!Array.isArray(main))
+            continue;
+        for (let outIdx = 0; outIdx < main.length; outIdx++) {
+            const fromPort = resolveOutPort(from, kindOf.get(from), outIdx, nodes, errors);
+            const targets = main[outIdx];
+            if (!Array.isArray(targets))
+                continue;
+            for (const t of targets) {
+                if (!t || typeof t.node !== "string") {
+                    errors.push(`connection from "${from}" has a malformed target`);
+                    continue;
+                }
+                if (skipped.has(t.node))
+                    continue;
+                if (!knownNames.has(t.node)) {
+                    errors.push(`connection from "${from}" targets missing node "${t.node}"`);
+                    continue;
+                }
+                const edge = { from, to: t.node };
+                if (fromPort !== "default")
+                    edge.fromPort = fromPort;
+                edges.push(edge);
+            }
+        }
+    }
+    return edges;
+}
+function resolveOutPort(from, kind, outIdx, nodes, errors) {
+    if (kind === "if") {
+        if (outIdx === 0)
+            return "true";
+        if (outIdx === 1)
+            return "false";
+        errors.push(`if node "${from}" has an unsupported output index ${outIdx} (only 0/1)`);
+        return "default";
+    }
+    if (kind === "switch") {
+        // n8n switch fans out by rule index; declare ports lazily on the node as case_N.
+        const port = `case_${outIdx}`;
+        const node = nodes.find((n) => n.id === from);
+        if (node) {
+            node.outPorts = node.outPorts ?? [];
+            if (!node.outPorts.includes(port))
+                node.outPorts.push(port);
+        }
+        return port;
+    }
+    if (kind === "filter") {
+        // n8n filter has kept(0) and (in some versions) discarded(1); we only model kept.
+        if (outIdx === 0)
+            return "default";
+        errors.push(`filter node "${from}" 的「丢弃」输出口无对应(仅支持保留口),请重接`);
+        return "default";
+    }
+    if (outIdx === 0)
+        return "default";
+    errors.push(`node "${from}" has an unmodeled multi-output index ${outIdx} (only single-output supported)`);
+    return "default";
+}

package/dist/orchestration/workflow/node-registry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * NodeExecutor registry (M2; plan §M2 "NodeExecutor 注册表").
+ *
+ * Single source of truth mapping node `kind` → executor. fail-loud on unknown kinds and
+ * duplicate registration. Built-in deterministic executors (set / if / merge) register here;
+ * host-backed executors (agent / tool / http / mcp / channel) are injected by the host so the
+ * engine stays a pure executor (plan D12/D13).
+ */
+import type { NodeExecutor } from "./node-schema.js";
+export declare class NodeRegistry {
+    private executors;
+    constructor(includeBuiltins?: boolean);
+    register(kind: string, executor: NodeExecutor): void;
+    /** Replace an existing executor (e.g. host overrides a built-in). Must already exist. */
+    override(kind: string, executor: NodeExecutor): void;
+    has(kind: string): boolean;
+    get(kind: string): NodeExecutor;
+    kinds(): string[];
+}

package/dist/orchestration/workflow/node-registry.js

@@ -0,0 +1,45 @@
+/**
+ * NodeExecutor registry (M2; plan §M2 "NodeExecutor 注册表").
+ *
+ * Single source of truth mapping node `kind` → executor. fail-loud on unknown kinds and
+ * duplicate registration. Built-in deterministic executors (set / if / merge) register here;
+ * host-backed executors (agent / tool / http / mcp / channel) are injected by the host so the
+ * engine stays a pure executor (plan D12/D13).
+ */
+import { builtinExecutors } from "./builtin-executors.js";
+export class NodeRegistry {
+    executors = new Map();
+    constructor(includeBuiltins = true) {
+        if (includeBuiltins) {
+            for (const [kind, exec] of Object.entries(builtinExecutors)) {
+                this.executors.set(kind, exec);
+            }
+        }
+    }
+    register(kind, executor) {
+        if (this.executors.has(kind)) {
+            throw new Error(`NodeExecutor for kind "${kind}" already registered`);
+        }
+        this.executors.set(kind, executor);
+    }
+    /** Replace an existing executor (e.g. host overrides a built-in). Must already exist. */
+    override(kind, executor) {
+        if (!this.executors.has(kind)) {
+            throw new Error(`Cannot override unregistered kind "${kind}"`);
+        }
+        this.executors.set(kind, executor);
+    }
+    has(kind) {
+        return this.executors.has(kind);
+    }
+    get(kind) {
+        const exec = this.executors.get(kind);
+        if (!exec) {
+            throw new Error(`No NodeExecutor registered for kind "${kind}"`);
+        }
+        return exec;
+    }
+    kinds() {
+        return [...this.executors.keys()];
+    }
+}

package/dist/orchestration/workflow/node-schema.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Workflow node schema + NodeExecutor contract (M2; plan D10, spec §A1/§A6).
+ *
+ * One declarative schema, three consumers: inline UI (M4) / execution (here) / NL generation (M5).
+ * Control/data separation (spec §A1): the DagScheduler owns control; executors are pure data
+ * transforms `(inputs, params, ctx) → { outputs, firedPorts }`.
+ */
+import type { DataItem, PortMap } from "./data-item.js";
+/** Port type for connection validation (spec §A6). "any" connects to anything. */
+export type PortType = "any" | "string" | "number" | "boolean" | "json" | "image" | "video" | "audio" | "binary";
+export interface PortDef {
+    name: string;
+    type?: PortType;
+}
+/**
+ * Port-type compatibility — the SINGLE truth for connection validation (R5 手动连线)。
+ * add_edge 拿它兜底;画布的即时拒绝只是这条规则的前端镜像。
+ * 规则:any 通配两侧;同型相通;媒体(image/video/audio)可入 binary(媒体 ⊆ 二进制,
+ * 例如"存文件"节点收任意二进制)。其余不通。
+ */
+export declare function portTypesCompatible(src: PortType | undefined, dst: PortType | undefined): boolean;
+/** Declarative workflow node (persisted; may carry `{{ }}` expressions in params). */
+export interface WorkflowNodeDef {
+    id: string;
+    kind: string;
+    /** Optional human-friendly display name (rename_node patch op; spec D17 §C). */
+    name?: string;
+    params?: Record<string, unknown>;
+    /** Output ports; default ["default"]. if→["true","false"], loop→["loop","done"]. */
+    outPorts?: string[];
+    /**
+     * Out-port data types(端口名 → 类型;缺省 "any")。与 outPorts(名字,控制流)刻意分离:
+     * DagScheduler 只关心端口名,类型只参与连线校验(add_edge)与画布 Handle 配色 —— 改
+     * outPorts 为混合型会波及全部调度消费方,不值得。
+     */
+    outPortTypes?: Record<string, PortType>;
+    /** Input ports (for type-checked routing); default ["default"]. */
+    inPorts?: PortDef[];
+    joinPolicy?: "all" | "any";
+    maxIterations?: number;
+    /** Retry the executor on failure: total attempts = maxTries (≥1); exponential backoff from backoffMs (default 1000). */
+    retry?: {
+        maxTries: number;
+        backoffMs?: number;
+    };
+    /** Per-attempt deadline; the executor's signal aborts when exceeded (counts as a failure → retry applies). */
+    timeoutMs?: number;
+    /**
+     * What a FINAL failure (after retries) does to the run:
+     *   "stop"(default)= run fails loud; "continue" = node marked failed, fires no ports
+     *   (downstream skips), other branches keep running; "errorPort" = a DataItem with the
+     *   error routes out the "error" port (wire an error-handler/notify subgraph to it).
+     */
+    onError?: "stop" | "continue" | "errorPort";
+    /**
+     * Canvas position pinned by a manual drag (set_node_ui patch op). Layout-only — the
+     * engine never reads it; absent ⇒ the canvas auto-layouts the node. Travels with the
+     * def (Bundle/export/Hub/n8n-import) so a hand-arranged graph stays arranged.
+     */
+    ui?: {
+        x: number;
+        y: number;
+    };
+}
+/** A data edge (carries DataItem[]). fromPort/toPort default "default". */
+export interface DataEdge {
+    from: string;
+    to: string;
+    fromPort?: string;
+    toPort?: string;
+    loopBack?: boolean;
+}
+export interface WorkflowDef {
+    id: string;
+    nodes: WorkflowNodeDef[];
+    edges: DataEdge[];
+    /** Workflow-level variables exposed to expressions as $vars. */
+    vars?: Record<string, unknown>;
+}
+/**
+ * SINGLE source of the attended/unattended split. Attended = a person is present right now:
+ * manual (pressed 运行), intent (just SAID it, confirmed by default D22), form (just SUBMITTED
+ * it, D34). Everything else (schedule / im-message / webhook) fires with nobody watching.
+ * Lives here (leaf module) so both the gate and host-executors can import it cycle-free.
+ */
+export declare function isUnattendedTrigger(kind: string): boolean;
+export interface ExecutorContext {
+    nodeId: string;
+    kind: string;
+    /** Owning workflow id (def.id) — lets host-backed nodes (approval) tag outbound notifications. */
+    workflowId?: string;
+    /** This run's trigger kind (manual/schedule/…) — drives fine-grained unattended audits (IT-7b). */
+    triggerKind?: string;
+    /** 0-based; increments per loop iteration (drives the cache key, spec §A5). */
+    runIndex: number;
+    vars: Record<string, unknown>;
+    trigger?: Record<string, unknown>;
+    /** Injected clock for determinism. */
+    now: () => Date;
+    log?: {
+        info(m: string): void;
+        warn(m: string): void;
+    };
+    /** Host capabilities for host-backed node kinds (agent/tool/http/mcp/channel), D13. */
+    host?: ExecutorHost;
+    /** Cooperative cancellation for long-running host calls. */
+    signal?: AbortSignal;
+}
+/**
+ * Capabilities the HOST (openclaw gateway, or the qlogicagent CLI host) provides to back node
+ * kinds the engine cannot fulfil on its own. The engine stays a pure executor (plan D12/D13):
+ * agent/tool/mcp/http are qlogicagent-owned host capabilities; channel/IM call back into the
+ * openclaw channel layer. fail-loud: a host-backed kind with no host throws.
+ */
+export interface ExecutorHost {
+    /** Run an agent turn. Returns the agent's structured output as DataItem(s). */
+    runAgent(req: AgentHostRequest): Promise<DataItem[]>;
+    /** Invoke a qlogicagent tool by name. */
+    invokeTool(req: ToolHostRequest): Promise<DataItem[]>;
+    /** Perform an HTTP request (credentials resolved host-side). */
+    httpRequest(req: HttpHostRequest): Promise<DataItem[]>;
+    /** Invoke an MCP server tool. */
+    invokeMcp(req: McpHostRequest): Promise<DataItem[]>;
+    /** Send a message out through a channel (飞书/微信/…) via the openclaw channel layer. */
+    sendChannel(req: ChannelHostRequest): Promise<DataItem[]>;
+    /** Project-scoped memory (memdir) read/write/search for the `memory` kind (spec D25). */
+    memory?(req: MemoryHostRequest): Promise<DataItem[]>;
+    /** Run another workflow as a step (D34); the host enforces cycle guards. */
+    runSubworkflow?(req: SubworkflowHostRequest): Promise<DataItem[]>;
+    /**
+     * Human-in-the-loop approval (D34): notify the owner and AWAIT the decision in-memory
+     * (the run stays "running"; the node shows pending). A restart loses pending approvals —
+     * the run then fails loud (durable suspended-run resumption is a tracked follow-up).
+     */
+    approval?(req: ApprovalHostRequest): Promise<{
+        approved: boolean;
+        decidedAt: string;
+        note?: string;
+    }>;
+    /**
+     * D34 wait-until-webhook: suspend the branch until the given webhook path is called
+     * (await-in-memory, same posture as approval — the run stays "running"; a restart loses the
+     * wait and the run fails loud; checkpoint replay recovers prior steps on re-run).
+     */
+    waitWebhook?(req: WebhookWaitHostRequest): Promise<Record<string, unknown>>;
+}
+export interface AgentHostRequest {
+    agentId?: string;
+    prompt: string;
+    input: DataItem[];
+    signal?: AbortSignal;
+}
+export interface ToolHostRequest {
+    tool: string;
+    args: Record<string, unknown>;
+    /** True when this run's trigger is unattended — the host applies fine-grained audits (IT-7b). */
+    unattended?: boolean;
+    input: DataItem[];
+    signal?: AbortSignal;
+}
+export interface HttpHostRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    /** Vault credential to inject as auth headers at execution time (D29; resolved host-side). */
+    credentialId?: string;
+    signal?: AbortSignal;
+}
+export interface McpHostRequest {
+    server: string;
+    tool: string;
+    args: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface ChannelHostRequest {
+    channel: string;
+    target?: string;
+    payload: unknown;
+    input: DataItem[];
+    signal?: AbortSignal;
+}
+export interface SubworkflowHostRequest {
+    workflowId: string;
+    /** The calling workflow's id — joins the cycle-guard chain so top-level runs count too. */
+    callerWorkflowId?: string;
+    /** Cross-project call target; absent = the calling workflow's own project root. */
+    projectId?: string;
+    /** Becomes the sub-run's $trigger payload (falls back to the upstream item's json). */
+    payload?: Record<string, unknown>;
+    input: DataItem[];
+    signal?: AbortSignal;
+}
+export interface ApprovalHostRequest {
+    nodeId: string;
+    /** Owning workflow id so the approval surface can name/locate the workflow. */
+    workflowId?: string;
+    /** Plain-language question shown to the owner (默认 "继续执行?"). */
+    prompt?: string;
+    /** Auto-deny deadline; default 24h. */
+    timeoutMs?: number;
+    input: DataItem[];
+    signal?: AbortSignal;
+}
+export interface WebhookWaitHostRequest {
+    /** Webhook path to wait for (normalized with a leading "/"). */
+    path: string;
+    nodeId: string;
+    workflowId?: string;
+    /** Auto-fail deadline; default 24h (a forever-pending branch is a leak, not patience). */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface MemoryHostRequest {
+    op: "read" | "write" | "search";
+    /** Topic-file name; absent → operate on the always-visible index. */
+    key?: string;
+    /** Content for `write` (falls back to the upstream item's json when omitted). */
+    value?: unknown;
+    /** Query for `search`. */
+    query?: string;
+    input: DataItem[];
+    signal?: AbortSignal;
+}
+export interface NodeExecResult {
+    /** outPort → DataItem[]. */
+    outputs: PortMap;
+    /** Control nodes (if/loop) set this; data nodes omit → all outPorts fire. */
+    firedPorts?: string[];
+}
+/** A node executor: pure with respect to (inputs, params, ctx). NO hidden global state. */
+export type NodeExecutor = (inputs: PortMap, params: Record<string, unknown>, ctx: ExecutorContext) => Promise<NodeExecResult> | NodeExecResult;

package/dist/orchestration/workflow/node-schema.js

@@ -0,0 +1,29 @@
+/**
+ * Workflow node schema + NodeExecutor contract (M2; plan D10, spec §A1/§A6).
+ *
+ * One declarative schema, three consumers: inline UI (M4) / execution (here) / NL generation (M5).
+ * Control/data separation (spec §A1): the DagScheduler owns control; executors are pure data
+ * transforms `(inputs, params, ctx) → { outputs, firedPorts }`.
+ */
+/**
+ * Port-type compatibility — the SINGLE truth for connection validation (R5 手动连线)。
+ * add_edge 拿它兜底;画布的即时拒绝只是这条规则的前端镜像。
+ * 规则:any 通配两侧;同型相通;媒体(image/video/audio)可入 binary(媒体 ⊆ 二进制,
+ * 例如"存文件"节点收任意二进制)。其余不通。
+ */
+export function portTypesCompatible(src, dst) {
+    const s = src ?? "any";
+    const d = dst ?? "any";
+    if (s === "any" || d === "any" || s === d)
+        return true;
+    return d === "binary" && (s === "image" || s === "video" || s === "audio");
+}
+/**
+ * SINGLE source of the attended/unattended split. Attended = a person is present right now:
+ * manual (pressed 运行), intent (just SAID it, confirmed by default D22), form (just SUBMITTED
+ * it, D34). Everything else (schedule / im-message / webhook) fires with nobody watching.
+ * Lives here (leaf module) so both the gate and host-executors can import it cycle-free.
+ */
+export function isUnattendedTrigger(kind) {
+    return kind !== "manual" && kind !== "intent" && kind !== "form";
+}