@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/tools/wait-subtasks-tool.js

@@ -0,0 +1,66 @@
+/**
+ * `wait_subtasks` — collect the results of background sub-agents.
+ *
+ * The blocking counterpart to {@link StartSubtaskTool}. Reads the same
+ * per-turn {@link BackgroundSubtaskRegistry} and resolves when every
+ * requested record left "running", on timeout, or when the turn's abort
+ * signal fires — a stop button must never leave the parent parked in a wait.
+ * Timeout and abort return current statuses instead of throwing; a partial
+ * answer beats no answer.
+ */
+import { Tool } from "./base-tool.js";
+import { DEFAULT_WAIT_TIMEOUT_MS, MAX_WAIT_TIMEOUT_MS } from "../background-subtasks.js";
+import { WAIT_SUBTASKS_DESCRIPTION, WAIT_SUBTASKS_SCHEMA } from "../prompts/background-subtask-prompt.js";
+import { isString } from "../utils/type-guards.js";
+const MIN_WAIT_TIMEOUT_MS = 1_000;
+export class WaitSubtasksTool extends Tool {
+    name = "wait_subtasks";
+    description = WAIT_SUBTASKS_DESCRIPTION;
+    jsonSchema = WAIT_SUBTASKS_SCHEMA;
+    registry;
+    constructor(opts) {
+        super();
+        this.registry = opts.background;
+    }
+    async process(context, params) {
+        if (!this.registry) {
+            return {
+                error: "background_unavailable",
+                message: "`wait_subtasks` needs a background registry, but this run carries " +
+                    "no `SubAgentToolRuntime.background`. Nothing can be running in " +
+                    "the background here."
+            };
+        }
+        if (this.registry.size === 0) {
+            return {
+                subtasks: [],
+                message: "No background subtasks have been started in this turn. Start one " +
+                    "with start_subtask."
+            };
+        }
+        const ids = stringArray(params.ids);
+        const timeoutMs = clampTimeout(params.timeout_ms);
+        const rows = await this.registry.wait({
+            ids,
+            timeoutMs,
+            signal: context.signal
+        });
+        return {
+            subtasks: rows,
+            all_settled: rows.every((row) => row.status !== "running")
+        };
+    }
+}
+function stringArray(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const values = raw.filter(isString);
+    return values.length > 0 ? values : undefined;
+}
+function clampTimeout(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
+        return DEFAULT_WAIT_TIMEOUT_MS;
+    }
+    return Math.min(Math.max(Math.floor(raw), MIN_WAIT_TIMEOUT_MS), MAX_WAIT_TIMEOUT_MS);
+}
+//# sourceMappingURL=wait-subtasks-tool.js.map

package/dist/tools/wait-subtasks-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-subtasks-tool.js","sourceRoot":"","sources":["../../src/tools/wait-subtasks-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EAGpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACrB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAOlC,MAAM,OAAO,gBAAiB,SAAQ,IAAI;IAC/B,IAAI,GAAG,eAAe,CAAC;IACvB,WAAW,GAAG,yBAAyB,CAAC;IACxC,UAAU,GAAG,oBAAoB,CAAC;IAE1B,QAAQ,CAA6B;IAEtD,YAAY,IAA6B;QACvC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAO,CACX,OAA0B,EAC1B,MAA+B;QAE/B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO;gBACL,KAAK,EAAE,wBAAwB;gBAC/B,OAAO,EACL,oEAAoE;oBACpE,iEAAiE;oBACjE,sBAAsB;aACzB,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,QAAQ,EAAE,EAAE;gBACZ,OAAO,EACL,mEAAmE;oBACnE,qBAAqB;aACxB,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAClD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACpC,GAAG;YACH,SAAS;YACT,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QACH,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC;SAC3D,CAAC;IACJ,CAAC;CACF;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACjE,OAAO,uBAAuB,CAAC;IACjC,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CACb,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,mBAAmB,CAAC,EAC9C,mBAAmB,CACpB,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -1,47 +1,24 @@
 /**
  * Core type definitions for the agent system.
  */
-/**
- * Agent execution mode:
- * - "loop": Simple iterative LLM + tool calling loop (like SimpleAgent)
- * - "plan": LLM creates a task plan, then executes steps (like Agent)
- * - "multi-agent": Multiple sub-agents running in parallel (like TeamExecutor)
- */
-export type AgentMode = "loop" | "plan" | "multi-agent";
-/**
- * Configuration for a sub-agent in multi-agent mode.
- * Used when auto-specializing agents from an objective.
- */
-export interface SubAgentConfig {
-    /** Human-readable name for the sub-agent. */
-    name: string;
-    /** Role description for the sub-agent. */
-    role: string;
-    /** Skill tags for task matching. */
-    skills: string[];
-    /** Tool names this sub-agent can use (beyond team tools). */
-    tools?: string[];
-    /** Override model for this sub-agent. If not set, uses the parent agent's model. */
-    model?: string;
-    /** Override provider for this sub-agent. If not set, uses the parent agent's provider. */
-    provider?: string;
-}
 export interface Step {
     id: string;
     instructions: string;
+    /**
+     * True only when the step produced a valid result. A failed step is
+     * terminal but NOT completed — dependents must not run on its output.
+     */
     completed: boolean;
+    /** True when the step ended without a usable result. Mutually exclusive with {@link completed}. */
+    failed?: boolean;
+    /** Failure cause, set alongside {@link failed}. */
+    error?: string;
     startTime?: number;
     endTime?: number;
     dependsOn: string[];
     tools?: string[];
     outputSchema?: string;
     logs: string[];
-    /** Step execution mode: discover produces a list, process fans out over it, aggregate collects. */
-    mode?: "discover" | "process" | "aggregate";
-    /** Template with {field} placeholders, rendered per item for process-mode fan-out. */
-    perItemInstructions?: string;
-    /** JSON schema string applied to each ephemeral step's output in process mode. */
-    perItemSchema?: string;
 }
 export interface Task {
     id: string;
@@ -62,4 +39,12 @@ export interface TaskPlan {
     title: string;
     tasks: Task[];
 }
+/**
+ * ProcessingContext variable key under which a host publishes the
+ * `PermissionGateOptions` every loop under it must gate through. Declared in
+ * `@nodetool-ai/runtime` so the workflow hosts below this package can set a
+ * gate on the context they build; re-exported here for every existing import.
+ * Read it with `gateFromContext`, never directly.
+ */
+export { PERMISSION_GATE_CONTEXT_KEY } from "@nodetool-ai/runtime";
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mGAAmG;IACnG,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IAC5C,sFAAsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,mGAAmG;IACnG,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED;;;;;;GAMG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/types.js

@@ -1,5 +1,12 @@
 /**
  * Core type definitions for the agent system.
  */
-export {};
+/**
+ * ProcessingContext variable key under which a host publishes the
+ * `PermissionGateOptions` every loop under it must gate through. Declared in
+ * `@nodetool-ai/runtime` so the workflow hosts below this package can set a
+ * gate on the context they build; re-exported here for every existing import.
+ * Read it with `gateFromContext`, never directly.
+ */
+export { PERMISSION_GATE_CONTEXT_KEY } from "@nodetool-ai/runtime";
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2CH;;;;;;GAMG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/utils/dag-scheduler.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Event-driven scheduling for a dependency graph.
+ *
+ * The task and step executors used to dispatch in barrier rounds: start every
+ * ready node, wait for the slowest, recompute the ready set. A chain behind a
+ * slow sibling therefore waited on the sibling in every round, and the round
+ * cap turned depth into failure. Here a node starts the moment its last
+ * dependency settles, and what bounds the work is the run's semaphore and the
+ * run budget rather than a count of rounds.
+ *
+ * The scheduler owns dependency state and event order; it knows nothing about
+ * tasks, steps, or messages. A caller supplies the nodes, a generator per node,
+ * and the events to emit when a node settles or is blocked.
+ *
+ * Order is the round loop's: a node's own events, then its settle events, then
+ * the blocked events of everything downstream of it, and only then are the
+ * nodes it unblocked started. Events of nodes running concurrently interleave,
+ * as they always did.
+ */
+import type { Semaphore } from "@nodetool-ai/runtime";
+/** Reason given to `settle` for a node nothing could ever run. */
+export declare const UNSATISFIABLE_DEPENDENCY = "unsatisfiable dependency";
+/** Reason given to `settle` for a node still unsettled when the signal fired. */
+export declare const ABORTED = "aborted";
+export interface DagNode {
+    id: string;
+    dependsOn: readonly string[];
+}
+export type DagOutcome = "ok" | "failed";
+/**
+ * How a node's generator settled. A generator that returns nothing settled
+ * `ok` — a run that fails reports it, since a failure that throws is an
+ * exception and propagates instead.
+ */
+export interface DagRunResult {
+    outcome: DagOutcome;
+    error?: string;
+}
+export interface DagScheduleOptions<N extends DagNode, E> {
+    nodes: readonly N[];
+    /** The node's event stream. Its return value carries how the node settled. */
+    run: (node: N) => AsyncGenerator<E, DagRunResult | void>;
+    /** Terminal events for a node that ran, or that could never run. */
+    settle: (node: N, outcome: DagOutcome, error?: string) => E[];
+    /** Permit pool bounding how many nodes run at once across the whole run. */
+    concurrency: Semaphore;
+    /**
+     * Bound on the nodes *this* schedule runs at once, on top of the pool. A
+     * pool shared by several schedules bounds them together; this bounds one of
+     * them. Unset, only the pool bounds it.
+     */
+    maxConcurrent?: number;
+    signal?: AbortSignal;
+    /**
+     * Events for a node that will never run because `by` failed. Called once per
+     * blocked node, naming the failed dependency immediately above it, and the
+     * blocked node counts as failed for everything below it (I-5: a failed
+     * dependency is never satisfied).
+     */
+    onBlocked: (node: N, by: N) => E[];
+}
+/**
+ * Run the graph, yielding every event its nodes produce.
+ *
+ * Ends when every node has settled. A state with unsettled nodes, nothing
+ * running and nothing ready cannot happen for a graph `PlanBuilder` accepted —
+ * it rejects cycles on the way in — so the scheduler asserts progress rather
+ * than hanging: those nodes settle failed with
+ * {@link UNSATISFIABLE_DEPENDENCY}.
+ *
+ * An exception thrown by a node's generator propagates once the other running
+ * generators have drained; that node never settles and the post-run settling
+ * is skipped, which is what the merge has always done.
+ *
+ * On abort the stream ends, every running generator is returned, and every
+ * node still unsettled — the ones that were running included — settles failed
+ * with {@link ABORTED}. A generator parked on an `await` that ignores the
+ * signal cannot be returned until that await resolves, so a node's own work
+ * must honour the signal; the merge has always required this of its producers.
+ *
+ * Work is O(nodes + edges): each node is settled once and each edge is walked
+ * once, whether it is decremented on success or followed by the block cascade.
+ */
+export declare function scheduleDag<N extends DagNode, E>(opts: DagScheduleOptions<N, E>): AsyncGenerator<E>;
+//# sourceMappingURL=dag-scheduler.d.ts.map

package/dist/utils/dag-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag-scheduler.d.ts","sourceRoot":"","sources":["../../src/utils/dag-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,kEAAkE;AAClE,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AACnE,iFAAiF;AACjF,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,QAAQ,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC;IACtD,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IACpB,8EAA8E;IAC9E,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC,CAAC;IACzD,oEAAoE;IACpE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC,EAAE,CAAC;IAC9D,4EAA4E;IAC5E,WAAW,EAAE,SAAS,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAuB,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EACrD,IAAI,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,cAAc,CAAC,CAAC,CAAC,CAyInB"}

package/dist/utils/dag-scheduler.js

@@ -0,0 +1,180 @@
+/**
+ * Event-driven scheduling for a dependency graph.
+ *
+ * The task and step executors used to dispatch in barrier rounds: start every
+ * ready node, wait for the slowest, recompute the ready set. A chain behind a
+ * slow sibling therefore waited on the sibling in every round, and the round
+ * cap turned depth into failure. Here a node starts the moment its last
+ * dependency settles, and what bounds the work is the run's semaphore and the
+ * run budget rather than a count of rounds.
+ *
+ * The scheduler owns dependency state and event order; it knows nothing about
+ * tasks, steps, or messages. A caller supplies the nodes, a generator per node,
+ * and the events to emit when a node settles or is blocked.
+ *
+ * Order is the round loop's: a node's own events, then its settle events, then
+ * the blocked events of everything downstream of it, and only then are the
+ * nodes it unblocked started. Events of nodes running concurrently interleave,
+ * as they always did.
+ */
+import { createDynamicMerge } from "./merge-generators.js";
+/** Reason given to `settle` for a node nothing could ever run. */
+export const UNSATISFIABLE_DEPENDENCY = "unsatisfiable dependency";
+/** Reason given to `settle` for a node still unsettled when the signal fired. */
+export const ABORTED = "aborted";
+/**
+ * Run the graph, yielding every event its nodes produce.
+ *
+ * Ends when every node has settled. A state with unsettled nodes, nothing
+ * running and nothing ready cannot happen for a graph `PlanBuilder` accepted —
+ * it rejects cycles on the way in — so the scheduler asserts progress rather
+ * than hanging: those nodes settle failed with
+ * {@link UNSATISFIABLE_DEPENDENCY}.
+ *
+ * An exception thrown by a node's generator propagates once the other running
+ * generators have drained; that node never settles and the post-run settling
+ * is skipped, which is what the merge has always done.
+ *
+ * On abort the stream ends, every running generator is returned, and every
+ * node still unsettled — the ones that were running included — settles failed
+ * with {@link ABORTED}. A generator parked on an `await` that ignores the
+ * signal cannot be returned until that await resolves, so a node's own work
+ * must honour the signal; the merge has always required this of its producers.
+ *
+ * Work is O(nodes + edges): each node is settled once and each edge is walked
+ * once, whether it is decremented on success or followed by the block cascade.
+ */
+export async function* scheduleDag(opts) {
+    const { nodes, run, settle, concurrency, maxConcurrent, signal, onBlocked } = opts;
+    /** Nodes depending on the keyed id, in the order the caller listed them. */
+    const dependents = new Map();
+    /** Dependencies each node is still waiting on. */
+    const waitingOn = new Map();
+    for (const node of nodes) {
+        waitingOn.set(node.id, node.dependsOn.length);
+        for (const dep of node.dependsOn) {
+            const list = dependents.get(dep);
+            if (list) {
+                list.push(node);
+            }
+            else {
+                dependents.set(dep, [node]);
+            }
+        }
+    }
+    const settled = new Set();
+    /** Grows monotonically; `readyCursor` marks what has been started. */
+    const ready = [];
+    let readyCursor = 0;
+    let inFlight = 0;
+    const merge = createDynamicMerge({
+        semaphore: concurrency,
+        concurrency: maxConcurrent,
+        signal
+    });
+    /**
+     * Mark every unsettled node downstream of a failure and collect their
+     * blocked events. Breadth-first, so each node names the dependency directly
+     * above it, which is the id the round loop reported.
+     */
+    function blockDependents(failedNode) {
+        const events = [];
+        // A cursor, not a shift: `Array.shift` is O(length), which would make a
+        // wide cascade quadratic in the number of blocked nodes.
+        const frontier = [failedNode];
+        for (let i = 0; i < frontier.length; i++) {
+            const blocking = frontier[i];
+            for (const dependent of dependents.get(blocking.id) ?? []) {
+                if (settled.has(dependent.id))
+                    continue;
+                settled.add(dependent.id);
+                events.push(...onBlocked(dependent, blocking));
+                frontier.push(dependent);
+            }
+        }
+        return events;
+    }
+    function releaseDependents(node) {
+        for (const dependent of dependents.get(node.id) ?? []) {
+            if (settled.has(dependent.id))
+                continue;
+            const left = (waitingOn.get(dependent.id) ?? 0) - 1;
+            waitingOn.set(dependent.id, left);
+            if (left === 0)
+                ready.push(dependent);
+        }
+    }
+    function startReady() {
+        while (readyCursor < ready.length) {
+            const node = ready[readyCursor++];
+            inFlight++;
+            merge.add(wrap(node));
+        }
+    }
+    function wrap(node) {
+        return (async function* () {
+            let outcome = null;
+            try {
+                // Nothing past the `yield*` runs when the consumer stops early: an
+                // abort leaves this node unsettled on purpose, and the post-run pass
+                // settles it with the reason the run actually ended for.
+                const result = yield* run(node);
+                outcome = result ? result.outcome : "ok";
+                // Bookkeeping first, and in one uninterrupted stretch: a `yield`
+                // hands control to another node's wrapper, which must not see this
+                // node half-settled.
+                settled.add(node.id);
+                const terminal = settle(node, outcome, result ? result.error : undefined);
+                const cascade = outcome === "failed" ? blockDependents(node) : [];
+                for (const event of terminal) {
+                    yield event;
+                }
+                for (const event of cascade) {
+                    yield event;
+                }
+            }
+            finally {
+                inFlight--;
+                // A node whose generator threw releases nothing: the exception is on
+                // its way out of the merge, and this only keeps the stream from
+                // waiting on a node that will never settle. Dependents are released
+                // here, after the terminal events above, and not before them: a
+                // sibling's `finally` calls `startReady` too, and a dependent pushed
+                // to `ready` before its dependency's settle events were yielded could
+                // start between them.
+                if (outcome !== null) {
+                    if (outcome === "ok")
+                        releaseDependents(node);
+                    startReady();
+                }
+                // Every node settled, or nothing left that could start one: either
+                // way no further generator will be added, so let the stream end.
+                if (inFlight === 0)
+                    merge.close();
+            }
+        })();
+    }
+    for (const node of nodes) {
+        if (node.dependsOn.length === 0)
+            ready.push(node);
+    }
+    startReady();
+    if (inFlight === 0)
+        merge.close();
+    for await (const event of merge.stream()) {
+        yield event;
+    }
+    // Unsettled leftovers: a node the abort cut short, or one whose dependencies
+    // can never be satisfied. Neither may be left looking like it is still
+    // running.
+    const reason = signal?.aborted ? ABORTED : UNSATISFIABLE_DEPENDENCY;
+    for (const node of nodes) {
+        if (settled.has(node.id))
+            continue;
+        settled.add(node.id);
+        for (const event of settle(node, "failed", reason)) {
+            yield event;
+        }
+    }
+}
+//# sourceMappingURL=dag-scheduler.js.map

package/dist/utils/dag-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag-scheduler.js","sourceRoot":"","sources":["../../src/utils/dag-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,kEAAkE;AAClE,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC;AACnE,iFAAiF;AACjF,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AA2CjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAChC,IAA8B;IAE9B,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,GACzE,IAAI,CAAC;IAEP,4EAA4E;IAC5E,MAAM,UAAU,GAAG,IAAI,GAAG,EAAe,CAAC;IAC1C,kDAAkD;IAClD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,IAAI,EAAE,CAAC;gBACT,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,sEAAsE;IACtE,MAAM,KAAK,GAAQ,EAAE,CAAC;IACtB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,MAAM,KAAK,GAAG,kBAAkB,CAAI;QAClC,SAAS,EAAE,WAAW;QACtB,WAAW,EAAE,aAAa;QAC1B,MAAM;KACP,CAAC,CAAC;IAEH;;;;OAIG;IACH,SAAS,eAAe,CAAC,UAAa;QACpC,MAAM,MAAM,GAAQ,EAAE,CAAC;QACvB,wEAAwE;QACxE,yDAAyD;QACzD,MAAM,QAAQ,GAAQ,CAAC,UAAU,CAAC,CAAC;QACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC7B,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC1D,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;oBAAE,SAAS;gBACxC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;gBAC/C,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,SAAS,iBAAiB,CAAC,IAAO;QAChC,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;YACtD,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAAE,SAAS;YACxC,MAAM,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACpD,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAClC,IAAI,IAAI,KAAK,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,SAAS,UAAU;QACjB,OAAO,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;YAClC,QAAQ,EAAE,CAAC;YACX,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,SAAS,IAAI,CAAC,IAAO;QACnB,OAAO,CAAC,KAAK,SAAS,CAAC;YACrB,IAAI,OAAO,GAAsB,IAAI,CAAC;YACtC,IAAI,CAAC;gBACH,mEAAmE;gBACnE,qEAAqE;gBACrE,yDAAyD;gBACzD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAChC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;gBACzC,iEAAiE;gBACjE,mEAAmE;gBACnE,qBAAqB;gBACrB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACrB,MAAM,QAAQ,GAAG,MAAM,CACrB,IAAI,EACJ,OAAO,EACP,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAClC,CAAC;gBACF,MAAM,OAAO,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;oBAC7B,MAAM,KAAK,CAAC;gBACd,CAAC;gBACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;oBAC5B,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,QAAQ,EAAE,CAAC;gBACX,qEAAqE;gBACrE,gEAAgE;gBAChE,oEAAoE;gBACpE,gEAAgE;gBAChE,qEAAqE;gBACrE,sEAAsE;gBACtE,sBAAsB;gBACtB,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;oBACrB,IAAI,OAAO,KAAK,IAAI;wBAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC;oBAC9C,UAAU,EAAE,CAAC;gBACf,CAAC;gBACD,mEAAmE;gBACnE,iEAAiE;gBACjE,IAAI,QAAQ,KAAK,CAAC;oBAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YACpC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IACD,UAAU,EAAE,CAAC;IACb,IAAI,QAAQ,KAAK,CAAC;QAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAElC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACzC,MAAM,KAAK,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,uEAAuE;IACvE,WAAW;IACX,MAAM,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC;IACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,SAAS;QACnC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;YACnD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/utils/json-parser.d.ts

@@ -11,5 +11,36 @@
  *
  * Returns null if no valid JSON can be extracted.
  */
-export declare function extractJSON(text: string): unknown | null;
+/**
+ * A value `JSON.parse` can produce — the only shapes that survive a JSON round
+ * trip, and therefore the only ones that cross a text or WASM boundary.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function extractJSON(text: string): JsonValue | null;
+/**
+ * Recover the complete prefix of a JSON object that was cut off mid-write.
+ *
+ * A vision judge asked for `{"verdict": …, "defects": […]}` and stopped at its
+ * token ceiling three defects in. {@link extractJSON} returns null for that —
+ * every strategy needs a balanced document — so the caller reported "did not
+ * return parseable JSON" and threw away a verdict and two usable defects that
+ * were fully written.
+ *
+ * This drops the incomplete tail: it walks back from the end to the last point
+ * where a value had just closed, closes the brackets that were still open
+ * there, and parses that. Returns null when nothing parses — a reply that is
+ * not JSON at all stays an error, and a *complete* document is
+ * {@link extractJSON}'s job, so try that first.
+ */
+export declare function salvageTruncatedJSON(text: string): JsonValue | null;
+/**
+ * {@link extractJSON}, falling back to {@link salvageTruncatedJSON}.
+ *
+ * For callers where a partial answer beats no answer — a critique whose
+ * defects list was cut short is still a critique. Never use it where a
+ * truncated document would be mistaken for a complete instruction.
+ */
+export declare function extractJSONAllowingTruncation(text: string): JsonValue | null;
 //# sourceMappingURL=json-parser.d.ts.map

package/dist/utils/json-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-parser.d.ts","sourceRoot":"","sources":["../../src/utils/json-parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA6DxD"}
+{"version":3,"file":"json-parser.d.ts","sourceRoot":"","sources":["../../src/utils/json-parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAiF1D;AAiCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CA0DnE;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAE5E"}