qlogicagent 2.13.4 → 2.13.5

package/dist/orchestration/dag-scheduler.js

@@ -0,0 +1,546 @@
+/**
+ * DAG Scheduler v2 — unified scheduling for Product + Automation modes.
+ *
+ * Single-track model: one algorithm, no compat shims, no legacy paths.
+ * Product mode = flat DAG (kind:"agent", no conditions, no loops) — strict subset.
+ *
+ * Spec: docs/dag-scheduler-v2-spec.md
+ */
+// ── Types ────────────────────────────────────────────────────
+/**
+ * Loop safety hard ceiling (plan D15): a loop controller's `maxIterations` is required and may
+ * never exceed this. Unattended/triggered runs must not be able to declare an effectively
+ * unbounded loop, so a value above the cap is rejected fail-loud at construction — not clamped.
+ */
+export const LOOP_MAX_ITERATIONS_HARD_CAP = 1000;
+// ── DAG Scheduler ────────────────────────────────────────────
+export class DagScheduler {
+    nodes = new Map();
+    edges = [];
+    constructor(defs) {
+        for (const def of defs) {
+            if (this.nodes.has(def.id)) {
+                throw new Error(`Duplicate node ID: ${def.id}`);
+            }
+            this.nodes.set(def.id, {
+                id: def.id,
+                kind: def.kind ?? "agent",
+                params: def.params ?? {},
+                status: "pending",
+                outPorts: def.outPorts ?? ["default"],
+                joinPolicy: def.joinPolicy ?? "all",
+                runIndex: 0,
+                maxIterations: def.maxIterations,
+            });
+        }
+        // Derive edges from dependsOn
+        for (const def of defs) {
+            for (const dep of def.dependsOn ?? []) {
+                if (!this.nodes.has(dep)) {
+                    throw new Error(`Node "${def.id}" depends on unknown node "${dep}"`);
+                }
+                this.edges.push({ from: dep, to: def.id, fromPort: "default" });
+            }
+        }
+        this.validateDag();
+    }
+    // ── Read API ─────────────────────────────────────────────
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    getAllNodes() {
+        return [...this.nodes.values()];
+    }
+    /**
+     * Ready = pending + all forward incoming edges satisfied (or no incoming edges).
+     * Spec §3.1.
+     */
+    getReadyNodes() {
+        const ready = [];
+        for (const node of this.nodes.values()) {
+            if (node.status !== "pending")
+                continue;
+            if (this.isBlockedByFailed(node.id))
+                continue;
+            const inEdges = this.incomingForwardEdges(node.id);
+            if (inEdges.length === 0) {
+                ready.push(node);
+                continue;
+            }
+            if (node.joinPolicy === "any") {
+                if (inEdges.some(e => this.edgeSatisfied(e)))
+                    ready.push(node);
+            }
+            else {
+                if (inEdges.every(e => this.edgeSatisfied(e)))
+                    ready.push(node);
+            }
+        }
+        return ready;
+    }
+    isFinished() {
+        for (const node of this.nodes.values()) {
+            if (node.status === "running" || node.status === "paused")
+                return false;
+            if (node.status === "pending") {
+                if (!this.isBlockedByFailed(node.id) && !this.isSkippable(node.id))
+                    return false;
+            }
+        }
+        return true;
+    }
+    /** All nodes completed or skipped (skipped = intentionally not run, counts as success). */
+    isAllCompleted() {
+        return [...this.nodes.values()].every(n => n.status === "completed" || n.status === "skipped");
+    }
+    getBlockedNodes() {
+        return [...this.nodes.values()].filter(n => n.status === "pending" && this.isBlockedByFailed(n.id));
+    }
+    getProgress() {
+        let completed = 0, running = 0, failed = 0, pending = 0, paused = 0, skipped = 0;
+        for (const node of this.nodes.values()) {
+            switch (node.status) {
+                case "completed":
+                    completed++;
+                    break;
+                case "running":
+                    running++;
+                    break;
+                case "failed":
+                    failed++;
+                    break;
+                case "pending":
+                    pending++;
+                    break;
+                case "paused":
+                    paused++;
+                    break;
+                case "skipped":
+                    skipped++;
+                    break;
+            }
+        }
+        return { total: this.nodes.size, completed, running, failed, pending, paused, skipped };
+    }
+    // ── Lifecycle ────────────────────────────────────────────
+    markRunning(id) {
+        const node = this.requireNode(id);
+        if (node.status !== "pending")
+            throw new Error(`Node "${id}" is ${node.status}, cannot start`);
+        node.status = "running";
+        node.startedAt = Date.now();
+    }
+    /**
+     * Mark completed. firedPorts omitted → all outPorts fire (agent/tool nodes).
+     * Triggers skip propagation (§3.2).
+     */
+    markCompleted(id, out) {
+        const node = this.requireNode(id);
+        if (node.status !== "running")
+            throw new Error(`Node "${id}" is ${node.status}, cannot complete`);
+        node.status = "completed";
+        node.output = out.output;
+        node.completedAt = Date.now();
+        node.firedPorts = out.firedPorts ?? node.outPorts;
+        this.propagateSkips();
+    }
+    markFailed(id, error) {
+        const node = this.requireNode(id);
+        node.status = "failed";
+        node.error = error;
+        node.completedAt = Date.now();
+        this.propagateSkips();
+    }
+    markPaused(id) {
+        const node = this.requireNode(id);
+        if (node.status === "running")
+            node.status = "paused";
+    }
+    resumePaused(id) {
+        const node = this.requireNode(id);
+        if (node.status === "paused")
+            node.status = "pending";
+    }
+    markSkipped(id) {
+        const node = this.requireNode(id);
+        if (node.status !== "pending")
+            throw new Error(`Node "${id}" is ${node.status}, cannot skip`);
+        node.status = "skipped";
+        node.firedPorts = [];
+        this.propagateSkips();
+    }
+    pauseAll() {
+        for (const node of this.nodes.values()) {
+            if (node.status === "running")
+                node.status = "paused";
+        }
+    }
+    resumeAll() {
+        for (const node of this.nodes.values()) {
+            if (node.status === "paused")
+                node.status = "pending";
+        }
+    }
+    /**
+     * Loop controller decision (§3.3).
+     * If again && iterations remain → reset loop body, fire "loop" port.
+     * Otherwise → fire "done" port (exit).
+     */
+    decideLoop(loopId, again) {
+        const loop = this.requireNode(loopId);
+        if (loop.kind !== "loop")
+            throw new Error(`Node "${loopId}" is not a loop controller`);
+        if (!loop.maxIterations || loop.maxIterations <= 0) {
+            throw new Error(`Loop "${loopId}" requires maxIterations > 0`);
+        }
+        const iteration = loop.iteration ?? 0;
+        if (again && iteration < loop.maxIterations) {
+            loop.iteration = iteration + 1;
+            loop.firedPorts = ["loop"];
+            this.resetLoopScope(loopId);
+        }
+        else {
+            loop.firedPorts = ["done"];
+            if (again) {
+                // Forced exit at cap — surface as warn-level info for event layer
+                loop.error = `loop_cap_reached:${loop.maxIterations}`;
+            }
+        }
+        this.propagateSkips();
+    }
+    // ── Topology Mutations ───────────────────────────────────
+    addNode(def) {
+        if (this.nodes.has(def.id))
+            throw new Error(`Node "${def.id}" already exists`);
+        for (const dep of def.dependsOn ?? []) {
+            if (!this.nodes.has(dep))
+                throw new Error(`Node "${def.id}" depends on unknown node "${dep}"`);
+        }
+        this.nodes.set(def.id, {
+            id: def.id,
+            kind: def.kind ?? "agent",
+            params: def.params ?? {},
+            status: "pending",
+            outPorts: def.outPorts ?? ["default"],
+            joinPolicy: def.joinPolicy ?? "all",
+            runIndex: 0,
+            maxIterations: def.maxIterations,
+        });
+        for (const dep of def.dependsOn ?? []) {
+            this.edges.push({ from: dep, to: def.id, fromPort: "default" });
+        }
+        try {
+            this.validateDag();
+        }
+        catch (e) {
+            this.nodes.delete(def.id);
+            this.edges = this.edges.filter(e2 => e2.to !== def.id || !def.dependsOn?.includes(e2.from));
+            throw e;
+        }
+    }
+    /** Add multiple nodes atomically. All-or-nothing. */
+    addNodes(defs) {
+        const added = [];
+        const addedEdges = [];
+        try {
+            for (const def of defs) {
+                if (this.nodes.has(def.id))
+                    throw new Error(`Node "${def.id}" already exists`);
+                for (const dep of def.dependsOn ?? []) {
+                    if (!this.nodes.has(dep))
+                        throw new Error(`Unknown dep "${dep}" for "${def.id}"`);
+                }
+                this.nodes.set(def.id, {
+                    id: def.id, kind: def.kind ?? "agent", params: def.params ?? {},
+                    status: "pending", outPorts: def.outPorts ?? ["default"],
+                    joinPolicy: def.joinPolicy ?? "all", runIndex: 0,
+                    maxIterations: def.maxIterations,
+                });
+                added.push(def.id);
+                const newEdges = (def.dependsOn ?? []).map(dep => ({ from: dep, to: def.id, fromPort: "default" }));
+                this.edges.push(...newEdges);
+                addedEdges.push(...newEdges);
+            }
+            this.validateDag();
+        }
+        catch (e) {
+            for (const id of added)
+                this.nodes.delete(id);
+            this.edges = this.edges.filter(e2 => !addedEdges.includes(e2));
+            throw e;
+        }
+    }
+    /**
+     * Remove a pending node. Cannot remove running or completed nodes.
+     * Removes all edges incident to this node.
+     */
+    removeNode(id) {
+        const node = this.requireNode(id);
+        if (node.status === "running")
+            throw new Error(`Cannot remove running node "${id}"`);
+        if (node.status === "completed")
+            throw new Error(`Cannot remove completed node "${id}"`);
+        this.edges = this.edges.filter(e => e.from !== id && e.to !== id);
+        this.nodes.delete(id);
+    }
+    /**
+     * Reset a failed node to pending. Optionally patches params (e.g. revised prompt).
+     */
+    retryNode(id, paramsPatch) {
+        const node = this.requireNode(id);
+        if (node.status !== "failed") {
+            throw new Error(`Node "${id}" is ${node.status}, only failed nodes can be retried`);
+        }
+        node.status = "pending";
+        node.error = undefined;
+        node.output = undefined;
+        node.firedPorts = undefined;
+        node.startedAt = undefined;
+        node.completedAt = undefined;
+        if (paramsPatch)
+            Object.assign(node.params, paramsPatch);
+    }
+    /** Merge patch into node.params. Node must be pending. */
+    updateNodeParams(id, patch) {
+        const node = this.requireNode(id);
+        if (node.status !== "pending") {
+            throw new Error(`Node "${id}" is ${node.status}, can only update pending nodes`);
+        }
+        Object.assign(node.params, patch);
+    }
+    /** Add an explicit edge. Validates no cycle. Validates ports exist on source. */
+    addEdge(edge) {
+        const { from, to, fromPort = "default", loopBack = false } = edge;
+        if (!this.nodes.has(from))
+            throw new Error(`Unknown source node "${from}"`);
+        if (!this.nodes.has(to))
+            throw new Error(`Unknown target node "${to}"`);
+        const src = this.nodes.get(from);
+        if (!loopBack && !src.outPorts.includes(fromPort)) {
+            throw new Error(`Node "${from}" has no outPort "${fromPort}"`);
+        }
+        const dup = this.edges.find(e => e.from === from && e.to === to && (e.fromPort ?? "default") === fromPort);
+        if (dup)
+            return; // idempotent
+        this.edges.push({ from, to, fromPort, loopBack });
+        if (!loopBack) {
+            try {
+                this.validateDag();
+            }
+            catch (e) {
+                this.edges = this.edges.filter(e2 => !(e2.from === from && e2.to === to && (e2.fromPort ?? "default") === fromPort));
+                throw e;
+            }
+        }
+        else {
+            // LoopBack edge returns to the loop controller (the edge target).
+            // The controller owns maxIterations (see decideLoop / loopBodyNodes).
+            const controller = this.nodes.get(to);
+            if (!controller.maxIterations || controller.maxIterations <= 0) {
+                this.edges.pop();
+                throw new Error(`LoopBack controller "${to}" requires maxIterations > 0`);
+            }
+        }
+    }
+    removeEdge(from, to, fromPort) {
+        const port = fromPort ?? "default";
+        this.edges = this.edges.filter(e => !(e.from === from && e.to === to && (e.fromPort ?? "default") === port));
+    }
+    // ── Persistence ──────────────────────────────────────────
+    serialize() {
+        return [...this.nodes.values()].map(n => {
+            const inDeps = this.incomingForwardEdges(n.id).map(e => e.from);
+            return {
+                id: n.id, kind: n.kind, params: n.params,
+                dependsOn: inDeps,
+                outPorts: n.outPorts, joinPolicy: n.joinPolicy,
+                status: n.status,
+                firedPorts: n.firedPorts, output: n.output, error: n.error,
+                startedAt: n.startedAt, completedAt: n.completedAt,
+                runIndex: n.runIndex, maxIterations: n.maxIterations, iteration: n.iteration,
+            };
+        });
+    }
+    /**
+     * Restore status from persisted snapshot.
+     * Running nodes become pending (need re-execution after crash).
+     * Missing fields use defaults.
+     */
+    restore(data) {
+        for (const item of data) {
+            const node = this.nodes.get(item.id);
+            if (!node)
+                continue;
+            node.status = item.status === "running" ? "pending" : item.status;
+            node.output = item.output;
+            node.error = item.error;
+            node.firedPorts = item.firedPorts;
+            node.startedAt = item.startedAt;
+            node.completedAt = item.completedAt;
+            node.runIndex = item.runIndex ?? 0;
+            node.iteration = item.iteration;
+        }
+    }
+    // ── Internal algorithms ──────────────────────────────────
+    /** §3.1 edge predicate: source completed AND this port fired. */
+    edgeSatisfied(e) {
+        const src = this.nodes.get(e.from);
+        if (!src || src.status !== "completed")
+            return false;
+        const port = e.fromPort ?? "default";
+        return (src.firedPorts ?? src.outPorts).includes(port);
+    }
+    /** An edge is "dead" if the source is skipped, OR source completed but did NOT fire this port. */
+    edgeDead(e) {
+        const src = this.nodes.get(e.from);
+        if (!src)
+            return false;
+        if (src.status === "skipped")
+            return true;
+        if (src.status === "completed") {
+            // A loop controller is NOT terminal until it fires "done"; while it is still
+            // iterating (firing "loop"), its other ports are pending, not dead. Skipping
+            // the "done"-port subgraph mid-iteration would prematurely kill the exit branch.
+            if (src.kind === "loop" && !(src.firedPorts ?? []).includes("done")) {
+                return false;
+            }
+            const port = e.fromPort ?? "default";
+            return !(src.firedPorts ?? src.outPorts).includes(port);
+        }
+        return false;
+    }
+    incomingForwardEdges(id) {
+        return this.edges.filter(e => e.to === id && !e.loopBack);
+    }
+    isBlockedByFailed(id) {
+        return this.incomingForwardEdges(id).some(e => {
+            const src = this.nodes.get(e.from);
+            return src?.status === "failed";
+        });
+    }
+    /** A pending node is "skippable" if all its forward edges are dead. */
+    isSkippable(id) {
+        const inEdges = this.incomingForwardEdges(id);
+        if (inEdges.length === 0)
+            return false;
+        const node = this.nodes.get(id);
+        if (node.joinPolicy === "any") {
+            return inEdges.every(e => this.edgeDead(e));
+        }
+        else {
+            return inEdges.some(e => this.edgeDead(e));
+        }
+    }
+    /**
+     * §3.2 Skip propagation.
+     * After markCompleted/markFailed/markSkipped, repeatedly mark pending nodes
+     * whose incoming edges are all dead as skipped.
+     * Product mode (no conditional edges) → no-op.
+     */
+    propagateSkips() {
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const node of this.nodes.values()) {
+                if (node.status !== "pending")
+                    continue;
+                if (this.isSkippable(node.id)) {
+                    node.status = "skipped";
+                    node.firedPorts = [];
+                    changed = true;
+                }
+            }
+        }
+    }
+    /**
+     * §3.3 Reset all loop-body nodes back to pending for next iteration.
+     */
+    resetLoopScope(loopId) {
+        const bodyIds = this.loopBodyNodes(loopId);
+        for (const id of bodyIds) {
+            const n = this.nodes.get(id);
+            n.status = "pending";
+            n.runIndex = (n.runIndex ?? 0) + 1;
+            n.output = undefined;
+            n.firedPorts = undefined;
+            n.error = undefined;
+            n.startedAt = undefined;
+            n.completedAt = undefined;
+        }
+    }
+    /**
+     * Compute the loop body: nodes reachable from the loop controller's "loop" outPort
+     * via non-loopBack forward edges, up to (but not including) the loop controller itself.
+     * The controller's "done" port leads OUT of the loop and is not part of the body.
+     */
+    loopBodyNodes(loopId) {
+        const body = new Set();
+        const visit = (id, isController) => {
+            for (const e of this.edges) {
+                if (e.from !== id || e.loopBack)
+                    continue;
+                // From the controller, only the "loop" port enters the body.
+                if (isController && (e.fromPort ?? "default") !== "loop")
+                    continue;
+                if (e.to === loopId)
+                    continue; // loopBack target excluded
+                if (body.has(e.to))
+                    continue;
+                body.add(e.to);
+                visit(e.to, false);
+            }
+        };
+        visit(loopId, true);
+        return body;
+    }
+    // ── Validation ───────────────────────────────────────────
+    validateDag() {
+        // Dependency integrity
+        for (const e of this.edges) {
+            if (!this.nodes.has(e.from))
+                throw new Error(`Edge references unknown source "${e.from}"`);
+            if (!this.nodes.has(e.to))
+                throw new Error(`Edge references unknown target "${e.to}"`);
+        }
+        // Cycle detection on non-loopBack edges
+        const forward = this.edges.filter(e => !e.loopBack);
+        const visited = new Set();
+        const inStack = new Set();
+        const dfs = (id) => {
+            if (inStack.has(id))
+                throw new Error(`Cycle detected involving node "${id}"`);
+            if (visited.has(id))
+                return;
+            inStack.add(id);
+            for (const e of forward) {
+                if (e.from === id)
+                    dfs(e.to);
+            }
+            inStack.delete(id);
+            visited.add(id);
+        };
+        for (const id of this.nodes.keys())
+            dfs(id);
+        // LoopBack validation: the controller (edge target) must have maxIterations
+        for (const e of this.edges) {
+            if (!e.loopBack)
+                continue;
+            const controller = this.nodes.get(e.to);
+            if (!controller?.maxIterations || controller.maxIterations <= 0) {
+                throw new Error(`LoopBack controller "${e.to}" must have maxIterations > 0`);
+            }
+        }
+        // D15 safety hard ceiling: no loop may declare more than the hard cap of iterations.
+        for (const node of this.nodes.values()) {
+            if (node.maxIterations !== undefined && node.maxIterations > LOOP_MAX_ITERATIONS_HARD_CAP) {
+                throw new Error(`Loop "${node.id}" maxIterations ${node.maxIterations} exceeds the hard cap of ${LOOP_MAX_ITERATIONS_HARD_CAP}`);
+            }
+        }
+    }
+    requireNode(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            throw new Error(`Unknown node: "${id}"`);
+        return node;
+    }
+}

package/dist/orchestration/error-handling/error-classification.d.ts

@@ -0,0 +1,3 @@
+export type ErrorCategory = "RETRYABLE_TRANSIENT" | "RETRYABLE_DEGRADED" | "NON_RETRYABLE_AUTH" | "NON_RETRYABLE_CONTENT" | "NON_RETRYABLE_QUOTA" | "TOOL_EXECUTION_FAILED";
+export declare function classifyError(status: number | undefined, message?: string): ErrorCategory;
+export declare function isRetryableCategory(category: ErrorCategory): boolean;

package/dist/orchestration/error-handling/error-classification.js

@@ -0,0 +1,35 @@
+// ============================================================
+// Error classification — maps FailoverReason to high-level
+// retry categories for consumers that need a simple decision.
+// ============================================================
+import { classifyFailoverReason, classifyFailoverReasonFromHttpStatus, } from "./failover-classification.js";
+const FAILOVER_TO_CATEGORY = {
+    timeout: "RETRYABLE_TRANSIENT",
+    overloaded: "RETRYABLE_TRANSIENT",
+    rate_limit: "RETRYABLE_DEGRADED",
+    auth: "NON_RETRYABLE_AUTH",
+    auth_permanent: "NON_RETRYABLE_AUTH",
+    billing: "NON_RETRYABLE_QUOTA",
+    format: "NON_RETRYABLE_CONTENT",
+    model_not_found: "NON_RETRYABLE_CONTENT",
+    session_expired: "NON_RETRYABLE_CONTENT",
+    unknown: "RETRYABLE_TRANSIENT",
+};
+const RETRYABLE_CATEGORIES = new Set([
+    "RETRYABLE_TRANSIENT",
+    "RETRYABLE_DEGRADED",
+    "TOOL_EXECUTION_FAILED",
+]);
+export function classifyError(status, message) {
+    const reason = classifyFailoverReasonFromHttpStatus(status, message) ??
+        (message ? classifyFailoverReason(message) : null);
+    if (!reason) {
+        return typeof status === "number" && status >= 400 && status < 500
+            ? "NON_RETRYABLE_CONTENT"
+            : "RETRYABLE_TRANSIENT";
+    }
+    return FAILOVER_TO_CATEGORY[reason];
+}
+export function isRetryableCategory(category) {
+    return RETRYABLE_CATEGORIES.has(category);
+}

package/dist/orchestration/error-handling/failover-classification.d.ts

@@ -0,0 +1,8 @@
+export type FailoverReason = "auth" | "auth_permanent" | "format" | "rate_limit" | "overloaded" | "billing" | "timeout" | "model_not_found" | "session_expired" | "unknown";
+export declare function isTimeoutErrorMessage(raw: string): boolean;
+export declare function isCloudflareOrHtmlErrorPage(raw: string): boolean;
+export declare function isTransientHttpError(raw: string): boolean;
+export declare function classifyFailoverReasonFromHttpStatus(status: number | undefined, message?: string): FailoverReason | null;
+export declare function isModelNotFoundErrorMessage(raw: string): boolean;
+export declare function classifyFailoverReason(raw: string): FailoverReason | null;
+export declare function isFailoverErrorMessage(raw: string): boolean;