qlogicagent 2.10.22 → 2.10.24

package/dist/types/orchestration/workflow/workflow-patch.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 type { WorkflowDef, WorkflowNodeDef, DataEdge } from "./node-schema.js";
+import type { TriggerDef } from "./workflow-trigger.js";
+export type { TriggerDef } from "./workflow-trigger.js";
+/** A workflow trigger (spec §B / plan D7). Registered by the gateway trigger layer. */
+/** Workflow-global fields a patch can set (kept separate from the node graph). */
+export interface WorkflowMeta {
+    name?: string;
+    active?: boolean;
+    trigger?: TriggerDef | null;
+}
+/** The full mutable target of a patch: the node graph plus workflow-global meta. */
+export interface PatchTarget {
+    def: WorkflowDef;
+    meta: WorkflowMeta;
+}
+export type WorkflowPatch = {
+    op: "add_node";
+    node: WorkflowNodeDef;
+} | {
+    op: "remove_node";
+    nodeId: string;
+} | {
+    op: "update_params";
+    nodeId: string;
+    params: Record<string, unknown>;
+} | {
+    op: "rename_node";
+    nodeId: string;
+    name: string;
+} | {
+    op: "add_edge";
+    edge: DataEdge;
+} | {
+    op: "remove_edge";
+    edge: {
+        from: string;
+        to: string;
+        fromPort?: string;
+    };
+} | {
+    op: "set_trigger";
+    trigger: TriggerDef | null;
+} | {
+    op: "set_meta";
+    meta: {
+        name?: string;
+        active?: boolean;
+    };
+};
+/** A patch + concurrency/scope envelope (spec §C). `scope` present ⇒ scoped (框选) edit. */
+export interface PatchEnvelope {
+    patch: WorkflowPatch[];
+    /** Optimistic-concurrency base revision (LWW handled by the store layer). */
+    baseRev?: number;
+    /** Selected node ids for a scoped edit; given ⇒ ops may only touch the selection subgraph. */
+    scope?: string[];
+}
+export interface ApplyResult {
+    target: PatchTarget;
+    applied: WorkflowPatch[];
+}
+/** Thrown when a patch is rejected. `errors` is the ordered list of reasons (for self-correction). */
+export declare class PatchError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * 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 declare function applyPatch(target: PatchTarget, env: PatchEnvelope): ApplyResult;
+/**
+ * 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 declare function validateWorkflowDef(def: WorkflowDef): string[];

package/dist/types/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/types/orchestration/workflow/workflow-runtime.d.ts

@@ -0,0 +1,127 @@
+/**
+ * WorkflowRuntime — the automation data-routing driver (M2; plan §M2, spec §A1/§A5).
+ *
+ * Responsibilities (control/data separation, spec §A1):
+ *   - DagScheduler v2 owns CONTROL (ready/skip/loop/ports). The runtime owns DATA:
+ *     for each ready node it collects upstream outputs along data edges (fromPort→toPort),
+ *     resolves param expressions, invokes the registered NodeExecutor, stores outputs, and
+ *     reports completion + firedPorts back to the scheduler.
+ *   - run-from-node + output cache (spec §A5): cache key = hash(kind + resolved params +
+ *     input signature + runIndex). A clean node hits cache (executor skipped); a changed node
+ *     and its dirty downstream recompute. This is content-addressed, so successive run() calls
+ *     after a param change recompute only the dirty subgraph.
+ *   - loop control is runtime-owned (DagScheduler.decideLoop), not a user executor.
+ *   - every node passes an injectable budget/permission gate before executing (plan D15).
+ *
+ * fail-loud: unknown kinds, gate rejections, and executor errors all throw and halt the run.
+ */
+import { DagScheduler } from "../dag-scheduler.js";
+import { type PortMap } from "./data-item.js";
+import { NodeRegistry } from "./node-registry.js";
+import type { RunCheckpoint } from "./run-checkpoint-store.js";
+import type { WorkflowDef, ExecutorHost } from "./node-schema.js";
+/** Gate invoked before each node executes (budget / permission). Throw to halt the run. */
+export interface ExecutionGate {
+    check(nodeId: string, kind: string): void;
+    /**
+     * Optionally raise the gate's remaining allowance so a budget-paused run can resume (D15
+     * "抬预算后 resume"). Gates without a budget may omit this. Implementations are fail-loud on
+     * non-positive deltas.
+     */
+    extend?(delta: {
+        executions?: number;
+        durationMs?: number;
+    }): void;
+}
+/**
+ * Thrown by a gate (or `pause()`) to suspend the run gracefully. Unlike a plain error this is
+ * not a failure: completed work stays cached, and a later `run()` on the same instance resumes
+ * (cached nodes hit, only the not-yet-run remainder executes).
+ */
+export declare class WorkflowPauseSignal extends Error {
+    readonly atNodeId?: string | undefined;
+    constructor(atNodeId?: string | undefined);
+}
+export interface RunResult {
+    status: "completed" | "failed" | "paused";
+    /** nodeId → its output PortMap. */
+    outputs: Record<string, PortMap>;
+    /** nodeIds whose executor actually ran in this run (cache misses). */
+    executed: Set<string>;
+    progress: ReturnType<DagScheduler["getProgress"]>;
+    /** Set when status === "paused": the node the run suspended at. */
+    pausedAt?: string;
+}
+export interface WorkflowRuntimeOptions {
+    registry?: NodeRegistry;
+    gate?: ExecutionGate;
+    now?: () => Date;
+    trigger?: Record<string, unknown>;
+    log?: {
+        info(m: string): void;
+        warn(m: string): void;
+    };
+    /** Host capabilities for host-backed kinds (agent/tool/http/mcp/channel), D13. */
+    host?: ExecutorHost;
+    /** Cancellation propagated to host calls. */
+    signal?: AbortSignal;
+    /** Durable run checkpoint for crash-restart recovery (plan §M3). */
+    checkpoint?: RunCheckpoint;
+}
+export declare class WorkflowRuntime {
+    private def;
+    private readonly registry;
+    private readonly gate?;
+    private readonly now;
+    private readonly trigger?;
+    private readonly log?;
+    private readonly host?;
+    private readonly signal?;
+    private readonly checkpoint?;
+    private dag;
+    private readonly nodeDefs;
+    private readonly nodeOutputs;
+    /** Content-addressed output cache; persists across run() calls for run-from-node. */
+    private readonly cache;
+    /** loopBack source nodeId → loop controller nodeId. */
+    private readonly loopBackOf;
+    /** Cooperative pause request; honored before the next node executes. */
+    private pauseRequested;
+    /** True once the durable checkpoint has been loaded into `cache` (load once per instance). */
+    private checkpointLoaded;
+    constructor(def: WorkflowDef, opts?: WorkflowRuntimeOptions);
+    /** Patch a node's params (for run-from-node param changes). Invalidates nothing directly —
+     * the content-addressed cache recomputes only what changed. */
+    setNodeParams(nodeId: string, params: Record<string, unknown>): void;
+    /** Request a cooperative pause: the in-flight run suspends before the next node executes. */
+    pause(): void;
+    /**
+     * Raise the budget gate's remaining allowance so a budget-paused run can resume (D15
+     * "抬预算后 resume"). fail-loud if this runtime was built without an extensible budget gate.
+     */
+    extendBudget(delta: {
+        executions?: number;
+        durationMs?: number;
+    }): void;
+    /** Execute the workflow to completion (or until the gate halts / a branch fails / a pause). */
+    run(): Promise<RunResult>;
+    /**
+     * Seed the content-addressed cache from a durable checkpoint (once per instance). After a
+     * crash-restart a fresh runtime replays the DAG; nodes that completed before the crash hit
+     * these entries and their executors are not re-invoked (no duplicate side effects).
+     */
+    private loadCheckpoint;
+    /** Persist the full content-addressed cache so a crash mid-run can resume from here. */
+    private persistCheckpoint;
+    private executeNode;
+    /** Loop entry: fire the "loop" port once to kick the first iteration. */
+    private enterLoop;
+    private decideLoopBack;
+    /** Loop again? No condition → loop until the scheduler's maxIterations cap. */
+    private evalLoopCondition;
+    /** Collect inputs for a node from completed upstream outputs along forward data edges. */
+    private collectInputs;
+    private buildExprContext;
+    private cacheKey;
+    private buildDag;
+}

package/dist/types/orchestration/workflow/workflow-scheduler.d.ts

@@ -0,0 +1,83 @@
+/**
+ * In-process workflow trigger scheduler (plan M3 trigger layer).
+ *
+ * Architecture note: scheduling lives INSIDE qlogicagent, not the gateway. This mirrors the
+ * established precedent — the idle "dream" timer was deliberately moved out of the openclaw gateway
+ * into qlogicagent so the Agent owns its own timed lifecycle ("Agent 是唯一状态拥有者"). The gateway
+ * remains a pure relay: it terminates external ingress (webhook HTTP, inbound IM) and forwards those
+ * events here via `onWebhook` / `onImMessage`; the cron clock and the run decision are the Agent's.
+ *
+ * The scheduler is the consumer of WorkflowController: on `start()` it loads every active workflow
+ * (`listActive`, spec §B4 restart re-registration) and arms a timer per `schedule` trigger; on fire
+ * it calls `controller.run(id, { type: "schedule" })`. Webhook / IM / manual triggers are
+ * caller-driven (the gateway relay or the agent invokes the matching method). Concurrency,
+ * budgeting, and permission gating all live in `controller.run` — the scheduler only decides WHEN.
+ *
+ * Determinism: the clock (now + timers) is injected, so tests pin time exactly and far-future cron
+ * delays are handled by chunked re-arming (Node's setTimeout caps at ~24.8 days).
+ */
+import type { WorkflowController, RunOutcome } from "./workflow-controller.js";
+export type TimerHandle = unknown;
+/** Injectable clock + timer surface so the scheduler is fully deterministic under test. */
+export interface SchedulerClock {
+    now(): number;
+    setTimer(fn: () => void, delayMs: number): TimerHandle;
+    clearTimer(handle: TimerHandle): void;
+}
+/** Default clock backed by the real system time and Node timers. */
+export declare const systemClock: SchedulerClock;
+export interface SchedulerDeps {
+    controller: WorkflowController;
+    clock?: SchedulerClock;
+    /**
+     * Surfaces an error from a timer-driven (cron) run, which has no caller to throw back to.
+     * Required so a failed unattended run is never silently swallowed (§1.5 fail-loud). Caller-driven
+     * triggers (webhook/IM/manual) propagate their errors to the caller instead.
+     */
+    onError: (err: unknown, workflowId: string) => void;
+}
+export declare class WorkflowScheduler {
+    private readonly controller;
+    private readonly clock;
+    private readonly onError;
+    /** Every registered workflow's trigger, keyed by id (the single source for lookups). */
+    private readonly triggers;
+    /** Active cron arms keyed by workflow id. */
+    private readonly cronArms;
+    private started;
+    constructor(deps: SchedulerDeps);
+    /** Load every active workflow and arm its trigger (spec §B4 restart re-registration). */
+    start(): Promise<void>;
+    /** Stop all timers and forget every registration. Idempotent. */
+    stop(): void;
+    /**
+     * Re-read a workflow and (re-)arm its trigger after a create/patch/setActive change. If the
+     * workflow no longer exists or is inactive it is unregistered. Active workflows are armed by
+     * their current trigger (manual ⇒ lookup-only, no timer).
+     */
+    refresh(id: string): Promise<void>;
+    /** Drop a workflow's registration and cancel any pending cron timer. */
+    unregister(id: string): void;
+    /** Workflow ids currently registered (for inspection/tests). */
+    registeredIds(): string[];
+    /** The epoch ms a scheduled workflow will next fire, or undefined if it has no cron arm. */
+    nextFireAt(id: string): number | undefined;
+    /**
+     * Deliver an external webhook hit. Runs every active workflow whose webhook trigger path equals
+     * `path`. Returns the outcomes (empty ⇒ no workflow matched, which the gateway maps to 404).
+     * Errors propagate to the caller (the HTTP handler), which is the fail-loud surface here.
+     */
+    onWebhook(path: string, payload?: Record<string, unknown>): Promise<RunOutcome[]>;
+    /**
+     * Deliver an inbound IM message. Runs every active workflow whose im-message trigger is on
+     * `channel` and whose optional `match` regex tests `text`. The message text + channel are merged
+     * into the run payload so downstream nodes can reference `$trigger`.
+     */
+    onImMessage(channel: string, text: string, payload?: Record<string, unknown>): Promise<RunOutcome[]>;
+    /** Manually trigger a single workflow (the agent's `workflow.run`). Errors propagate to caller. */
+    triggerManual(id: string, payload?: Record<string, unknown>): Promise<RunOutcome>;
+    private matchingIds;
+    private registerTrigger;
+    private armCron;
+    private fireCron;
+}

package/dist/types/orchestration/workflow/workflow-store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Workflow Store — persist workflow definitions + lifecycle state to disk (spec §B4).
+ *
+ * Stored at `<project>/.qlogicagent/workflows/<workflowId>/workflow.json`. Listing enumerates
+ * subdirectories (mirrors product-persistence.ts). The store is the single source of truth for a
+ * workflow's definition, its active flag, and its concurrency policy; the gateway re-registers
+ * triggers for every active workflow on restart (spec §B4).
+ *
+ * fail-loud: missing id on save throws; load returns undefined only for a genuinely absent record.
+ */
+import type { WorkflowDef } from "./node-schema.js";
+import type { TriggerDef } from "./workflow-patch.js";
+/** What to do when a workflow is triggered while a previous run is still in-flight (spec §B5). */
+export type ConcurrencyPolicy = "queue" | "skip" | "parallel";
+export interface WorkflowRecord {
+    id: string;
+    name: string;
+    def: WorkflowDef;
+    /** Active workflows have their triggers registered by the gateway (spec §B4). */
+    active: boolean;
+    concurrency: ConcurrencyPolicy;
+    /** The workflow's trigger (set via a WorkflowPatch set_trigger op; spec §C/D7). */
+    trigger?: TriggerDef | null;
+    /** Monotonic revision for optimistic concurrency (LWW); bumped on every patch (spec §C). */
+    rev: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare class WorkflowStore {
+    private readonly cwd;
+    constructor(cwd: string);
+    save(record: WorkflowRecord): Promise<void>;
+    load(id: string): Promise<WorkflowRecord | undefined>;
+    /** Load a record or throw (fail-loud lookup for callers that require existence). */
+    require(id: string): Promise<WorkflowRecord>;
+    list(): Promise<WorkflowRecord[]>;
+    /** Active workflows the gateway must re-register triggers for after a restart (spec §B4). */
+    listActive(): Promise<WorkflowRecord[]>;
+    delete(id: string): Promise<void>;
+}

package/dist/types/orchestration/workflow/workflow-trigger.d.ts

@@ -0,0 +1,14 @@
+/** Workflow trigger definitions shared by patching, validation, storage, and render helpers. */
+export type TriggerDef = {
+    type: "manual";
+} | {
+    type: "schedule";
+    cron: string;
+} | {
+    type: "im-message";
+    channel: string;
+    match?: string;
+} | {
+    type: "webhook";
+    path: string;
+};

package/dist/types/permissions.d.ts

@@ -0,0 +1,2 @@
+export { PERMISSION_MODES, } from "./runtime/ports/permission-contracts.js";
+export type { ApprovalRequest, ApprovalResponse, PermissionAllowResult, PermissionApprovalResolver, PermissionAskResult, PermissionBehavior, PermissionConfig, PermissionDecisionReason, PermissionDenyResult, PermissionMetadataResolver, PermissionMode, PermissionResult, PermissionRuleEnginePort, PermissionRuleEntry, PermissionUpdate, ToolPermissionCheckInput, } from "./runtime/ports/permission-contracts.js";

package/dist/types/permissions.public-api.test.d.ts

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