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

package/dist/network-guard.js

@@ -0,0 +1,106 @@
+/**
+ * Which network addresses untrusted code may reach.
+ *
+ * Guest JavaScript and the host binaries it drives run inside the server, so
+ * "fetch this URL" is a request to open a socket from a process that sits
+ * behind the cloud's perimeter. The address that matters most is
+ * `169.254.169.254`, the instance metadata service, but loopback, the private
+ * ranges, CGNAT and the IPv6 spellings of all of them reach the same class of
+ * thing: services that trusted the network instead of the caller.
+ *
+ * This lives apart from `js-sandbox.ts` because the fetch bridge is no longer
+ * the only caller: `yt_dlp` hands a URL to a downloader that opens its own
+ * sockets, and one wrong answer there is the same breach. One table, one
+ * predicate, both surfaces.
+ *
+ * The table itself is `@nodetool-ai/runtime`'s: `isBlockedIpLiteral` in
+ * `providers/safe-url.ts`, imported through the leaf subpath so the browser
+ * bundle takes the module and not the rest of runtime. What stays here is the
+ * *policy* this surface applies on top of it — plain http is allowed (a Code
+ * node reaching an internal HTTP service is a supported thing to configure),
+ * and a host may waive the address check with `allowPrivate`, which NodeTool's
+ * default egress policy never does.
+ *
+ * The check reads the URL's host. A hostname that *resolves* to a blocked
+ * address is caught by {@link assertResolvedHostAllowed}, which the caller
+ * uses when it can afford a DNS round trip.
+ */
+import { importNodeBuiltin } from "@nodetool-ai/config";
+import { isBlockedIpLiteral } from "@nodetool-ai/runtime/safe-url";
+export { isBlockedIpLiteral };
+/**
+ * SSRF allow-check for the sandbox fetch bridge. Rejects non-http(s) schemes
+ * and hosts that resolve to loopback/link-local/private literals or localhost.
+ * Throws on a blocked URL.
+ */
+export function assertFetchUrlAllowed(url, allowPrivate = false) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error("fetch: invalid URL");
+    }
+    // Scheme is checked even in private-network mode: `file:`, `gopher:` and
+    // friends are never reachable through the bridge, whatever the host allows.
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`fetch: unsupported scheme "${parsed.protocol}"`);
+    }
+    if (allowPrivate)
+        return;
+    const host = parsed.hostname.toLowerCase();
+    if (host === "localhost" || host.endsWith(".localhost")) {
+        throw new Error("fetch: access to localhost is blocked");
+    }
+    if (isBlockedIpLiteral(host)) {
+        throw new Error(`fetch: access to internal/private address "${host}" is blocked`);
+    }
+}
+/**
+ * Refuse a URL whose hostname resolves to a blocked address, on top of the
+ * literal check {@link assertFetchUrlAllowed} makes.
+ *
+ * A literal check answers `metadata.example.com` with "that is not an IP", and
+ * the name resolves to `169.254.169.254` a millisecond later. Resolving here
+ * closes the ordinary case. It does not close every case — the process we hand
+ * the URL to resolves again (so a record that changes between the two answers
+ * wins) and follows its own redirects — which is why this is one layer, not
+ * the boundary. `label` names the caller in the refusal.
+ */
+export async function assertResolvedHostAllowed(url, label, resolve = defaultResolver) {
+    const host = new URL(url).hostname.replace(/^\[|\]$/g, "");
+    // A literal needs no resolution; assertFetchUrlAllowed already judged it.
+    if (/^[\d.]+$/.test(host) || host.includes(":"))
+        return;
+    let addresses;
+    try {
+        addresses = await resolve(host);
+    }
+    catch {
+        // A name that does not resolve is the downloader's error to report, with
+        // its own message, not ours to guess at.
+        return;
+    }
+    const blocked = addresses.find((address) => isBlockedIpLiteral(address));
+    if (blocked !== undefined) {
+        throw new Error(`${label}: "${host}" resolves to the internal address "${blocked}", which is blocked`);
+    }
+}
+/**
+ * `node:dns` is loaded through `importNodeBuiltin`, never imported at the top
+ * level: this module is reachable from `js-sandbox.ts`, which the browser
+ * workflow-runner bundles. A static `node:dns/promises` import broke that
+ * bundle outright — the harness aliases `node:dns` to an empty stub, and
+ * `node:dns/promises` then resolved to a path inside that file.
+ *
+ * Off Node there is no resolver, and a caller that cannot resolve treats the
+ * name the way an unresolvable one is treated: the literal check has already
+ * run, and whoever opens the socket reports the rest.
+ */
+const defaultResolver = async (host) => {
+    const dns = await importNodeBuiltin("node:dns/promises");
+    if (!dns)
+        return [];
+    return (await dns.lookup(host, { all: true })).map((entry) => entry.address);
+};
+//# sourceMappingURL=network-guard.js.map

package/dist/network-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-guard.js","sourceRoot":"","sources":["../src/network-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAU9B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,YAAY,GAAG,KAAK;IACrE,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACxC,CAAC;IACD,yEAAyE;IACzE,4EAA4E;IAC5E,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,YAAY;QAAE,OAAO;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,8CAA8C,IAAI,cAAc,CACjE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,GAAW,EACX,KAAa,EACb,OAAO,GAAiB,eAAe;IAEvC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3D,0EAA0E;IAC1E,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO;IACxD,IAAI,SAAmB,CAAC;IACxB,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,yCAAyC;QACzC,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IACzE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,MAAM,IAAI,uCAAuC,OAAO,qBAAqB,CACtF,CAAC;IACJ,CAAC;AACH,CAAC;AAKD;;;;;;;;;;GAUG;AACH,MAAM,eAAe,GAAiB,KAAK,EAAE,IAAI,EAAE,EAAE;IACnD,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAc,mBAAmB,CAAC,CAAC;IACtE,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,OAAO,CAAC,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC/E,CAAC,CAAC"}

package/dist/normalize-model-properties.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Complete the model properties on a planner-authored node.
+ *
+ * The planner writes models as a bare `{provider, id}` pair — that is what the
+ * system prompt asks for, and what `find_model` results look like. The node
+ * property types (`language_model`, `image_model`, …) are richer: they carry a
+ * `type` discriminator and a display `name`. Nothing at runtime notices the
+ * difference, because model lookup only reads `provider` and `id`, so an
+ * incomplete model survives execution and lands in the saved workflow, where
+ * the editor has no discriminator to work with.
+ *
+ * The declared type comes from the registry rather than being assumed: a
+ * TextToImage node's `model` is an `image_model`, not a `language_model`.
+ */
+import type { NodeMetadata } from "@nodetool-ai/node-sdk";
+/** Registry surface this needs — a subset of NodeRegistry, so stubs work. */
+export interface ModelPropertyRegistry {
+    getMetadata(nodeType: string): NodeMetadata | undefined | null;
+}
+/**
+ * Return `properties` with every model-typed value completed. Values that
+ * already carry a `type`, and properties the registry doesn't describe as a
+ * model, are returned untouched.
+ */
+export declare function normalizeModelProperties(nodeType: string, properties: Record<string, unknown> | undefined, registry: ModelPropertyRegistry): Record<string, unknown> | undefined;
+//# sourceMappingURL=normalize-model-properties.d.ts.map

package/dist/normalize-model-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-model-properties.d.ts","sourceRoot":"","sources":["../src/normalize-model-properties.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,IAAI,CAAC;CAChE;AAiBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC/C,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA6BrC"}

package/dist/normalize-model-properties.js

@@ -0,0 +1,58 @@
+/**
+ * Complete the model properties on a planner-authored node.
+ *
+ * The planner writes models as a bare `{provider, id}` pair — that is what the
+ * system prompt asks for, and what `find_model` results look like. The node
+ * property types (`language_model`, `image_model`, …) are richer: they carry a
+ * `type` discriminator and a display `name`. Nothing at runtime notices the
+ * difference, because model lookup only reads `provider` and `id`, so an
+ * incomplete model survives execution and lands in the saved workflow, where
+ * the editor has no discriminator to work with.
+ *
+ * The declared type comes from the registry rather than being assumed: a
+ * TextToImage node's `model` is an `image_model`, not a `language_model`.
+ */
+/** Property types whose values are model references. */
+const MODEL_TYPE_SUFFIX = "_model";
+function isBareModelRef(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const v = value;
+    return (typeof v["provider"] === "string" &&
+        typeof v["id"] === "string" &&
+        typeof v["type"] !== "string");
+}
+/**
+ * Return `properties` with every model-typed value completed. Values that
+ * already carry a `type`, and properties the registry doesn't describe as a
+ * model, are returned untouched.
+ */
+export function normalizeModelProperties(nodeType, properties, registry) {
+    if (!properties)
+        return properties;
+    const meta = registry.getMetadata(nodeType);
+    if (!meta)
+        return properties;
+    let changed = false;
+    const next = { ...properties };
+    for (const [key, value] of Object.entries(properties)) {
+        if (!isBareModelRef(value))
+            continue;
+        const declared = meta.properties?.find((p) => p.name === key)?.type?.type;
+        if (!declared || !declared.endsWith(MODEL_TYPE_SUFFIX))
+            continue;
+        next[key] = {
+            type: declared,
+            provider: value.provider,
+            id: value.id,
+            // The planner drops the name `find_model` gave it; the id is the best
+            // remaining label and is what the editor falls back to anyway.
+            name: value.name ?? value.id,
+            path: null,
+            supported_tasks: []
+        };
+        changed = true;
+    }
+    return changed ? next : properties;
+}
+//# sourceMappingURL=normalize-model-properties.js.map

package/dist/normalize-model-properties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-model-properties.js","sourceRoot":"","sources":["../src/normalize-model-properties.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,wDAAwD;AACxD,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAEnC,SAAS,cAAc,CACrB,KAAc;IAEd,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9E,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,QAAQ;QACjC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ;QAC3B,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,CAC9B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAgB,EAChB,UAA+C,EAC/C,QAA+B;IAE/B,IAAI,CAAC,UAAU;QAAE,OAAO,UAAU,CAAC;IAEnC,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI;QAAE,OAAO,UAAU,CAAC;IAE7B,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAA4B,EAAE,GAAG,UAAU,EAAE,CAAC;IAExD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;YAAE,SAAS;QAErC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;QAC1E,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,iBAAiB,CAAC;YAAE,SAAS;QAEjE,IAAI,CAAC,GAAG,CAAC,GAAG;YACV,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,sEAAsE;YACtE,+DAA+D;YAC/D,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE;YAC5B,IAAI,EAAE,IAAI;YACV,eAAe,EAAE,EAAE;SACpB,CAAC;QACF,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;AACrC,CAAC"}

package/dist/output-format.d.ts

@@ -5,6 +5,10 @@
  * presentation format.
  */
 export type AgentOutputFormat = "structured" | "markdown" | "text" | "html";
-export declare const OUTPUT_FORMAT_DIRECTIVES: Record<Exclude<AgentOutputFormat, "structured">, string>;
+export declare const OUTPUT_FORMAT_DIRECTIVES: {
+    markdown: string;
+    text: string;
+    html: string;
+};
 export declare function outputFormatDirective(format: AgentOutputFormat): string | null;
 //# sourceMappingURL=output-format.d.ts.map

package/dist/output-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-format.d.ts","sourceRoot":"","sources":["../src/output-format.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5E,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAC3C,OAAO,CAAC,iBAAiB,EAAE,YAAY,CAAC,EACxC,MAAM,CAKP,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAG9E"}
+{"version":3,"file":"output-format.d.ts","sourceRoot":"","sources":["../src/output-format.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5E,eAAO,MAAM,wBAAwB;;;;CAOpC,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,GACxB,MAAM,GAAG,IAAI,CAGf"}

package/dist/output-format.js.map

@@ -1 +1 @@
-{"version":3,"file":"output-format.js","sourceRoot":"","sources":["../src/output-format.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,CAAC,MAAM,wBAAwB,GAGjC;IACF,QAAQ,EAAE,+BAA+B;IACzC,IAAI,EAAE,2BAA2B;IACjC,IAAI,EAAE,8BAA8B;CACrC,CAAC;AAEF,MAAM,UAAU,qBAAqB,CAAC,MAAyB;IAC7D,IAAI,MAAM,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,wBAAwB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"output-format.js","sourceRoot":"","sources":["../src/output-format.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,QAAQ,EAAE,+BAA+B;IACzC,IAAI,EAAE,2BAA2B;IACjC,IAAI,EAAE,8BAA8B;CAIrC,CAAC;AAEF,MAAM,UAAU,qBAAqB,CACnC,MAAyB;IAEzB,IAAI,MAAM,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,wBAAwB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/dist/parallel-task-executor.d.ts

@@ -2,18 +2,12 @@
  * ParallelTaskExecutor -- orchestrates parallel execution of a multi-task plan.
  *
  * Each task in the plan runs as an independent sub-agent via TaskExecutor.
- * Tasks form a DAG via their `dependsOn` arrays. Independent tasks
- * (those with no unmet dependencies) run concurrently.
- *
- * Flow:
- *   TaskPlan (multiple Tasks) → ParallelTaskExecutor
- *     → finds tasks with satisfied dependencies
- *     → runs them concurrently, each via TaskExecutor
- *     → stores results in shared context
- *     → repeats until all tasks complete
+ * Tasks form a DAG via their `dependsOn` arrays, handed to {@link scheduleDag}:
+ * a task starts the moment its last dependency settles, and its results reach
+ * shared memory before its dependents are released. Nothing counts dispatch
+ * rounds — the run budget and the permit pool bound the work.
  */
-import type { BaseProvider } from "@nodetool-ai/runtime";
-import type { ProcessingContext } from "@nodetool-ai/runtime";
+import type { BaseProvider, ProcessingContext, RunBudget } from "@nodetool-ai/runtime";
 import type { ProcessingMessage } from "@nodetool-ai/protocol";
 import type { Tool } from "./tools/base-tool.js";
 import type { TaskPlan } from "./types.js";
@@ -25,11 +19,22 @@ export interface ParallelTaskExecutorOptions {
     taskPlan: TaskPlan;
     systemPrompt?: string;
     inputs?: Record<string, unknown>;
-    /** Maximum total iteration count across all tasks. */
-    maxIterations?: number;
     /** Maximum iterations per step within a task. */
     maxStepIterations?: number;
-    maxTokenLimit?: number;
+    /** Concurrent task and step executions. Defaults to the shared agent policy. */
+    maxConcurrentAgents?: number;
+    /** Cap on output tokens per step turn. Forwarded to each TaskExecutor. */
+    maxTokens?: number;
+    /**
+     * The run's budget, forwarded to every task and through it to every step,
+     * whose provider conversations draw on its permit pool. Omitted, the budget
+     * on {@link context} is used.
+     */
+    budget?: RunBudget;
+    /** External cancellation, forwarded to every task and step executor. */
+    signal?: AbortSignal;
+    /** Sandbox package specifiers the session consents to, forwarded per task. */
+    sandboxPackages?: readonly string[];
 }
 export declare class ParallelTaskExecutor {
     private readonly provider;
@@ -39,10 +44,22 @@ export declare class ParallelTaskExecutor {
     private readonly context;
     private readonly inputs;
     private readonly systemPrompt;
-    private readonly maxIterations;
     private readonly maxStepIterations;
-    private readonly maxTokenLimit;
-    /** Results collected per task ID. */
+    private readonly maxConcurrentAgents;
+    private readonly maxTokens?;
+    private readonly budget?;
+    private readonly signal?;
+    private readonly sandboxPackages;
+    /**
+     * IDs of tasks that did not genuinely succeed — a failed step, an
+     * unsatisfiable dependency, or an `{ error }` result. Tracked apart from
+     * `task.completed` so a failed task is never recorded as a success nor
+     * counted as a satisfied dependency.
+     */
+    private readonly failedTaskIds;
+    /** Why a task that actually ran failed, read by {@link settleTask}. */
+    private readonly failureReasons;
+    /** What a task that actually ran produced, read by {@link settleTask}. */
     private readonly taskResults;
     constructor(opts: ParallelTaskExecutorOptions);
     /**
@@ -51,37 +68,51 @@ export declare class ParallelTaskExecutor {
      */
     execute(): AsyncGenerator<ProcessingMessage>;
     /**
-     * Execute a single task as an independent sub-agent.
-     * Injects dependency results into the task's context before execution.
+     * The tasks the scheduler runs, with the dependencies each waits on.
+     *
+     * A task already completed before the plan starts is not a node, and counts
+     * as a satisfied dependency for the rest; so does an input key. A dependency
+     * naming neither is left in place, so the task never becomes ready and the
+     * scheduler settles it with `unsatisfiable dependency`.
      */
-    private executeTask;
+    private taskNodes;
     /**
-     * Build a map of dependency results for a task.
+     * Execute a single task as an independent sub-agent, and report how it
+     * settled. Its terminal `task_update` is {@link settleTask}'s to emit: the
+     * scheduler releases this task's dependents only after that runs, so a
+     * dependent's first event cannot land before its dependency's last one.
      */
-    private buildDependencyContext;
+    private runTask;
     /**
-     * Build system prompt enhanced with dependency results.
+     * Terminal events for a settled task: the `task_update` every lifecycle
+     * consumer resolves the task on, plus an error log when it failed.
+     *
+     * A task that never ran — blocked by a dependency that can never be
+     * satisfied, or cut short by the run's signal — is recorded as failed here
+     * rather than left looking like it is still running.
      */
-    private buildTaskSystemPrompt;
+    private settleTask;
+    /** Record a task that never ran as failed and build its terminal events. */
+    private blockTaskEvents;
     /**
-     * Check if all tasks have been completed.
-     */
-    private allTasksComplete;
-    /**
-     * Find tasks whose dependencies are all satisfied.
-     */
-    private getExecutableTasks;
-    /**
-     * Get the result of a specific task.
+     * Decide whether a task that just returned actually failed. Detects:
+     *  - steps that never completed (the run budget stopped them, or a
+     *    dependency could never be satisfied), and
+     *  - steps (or the resolved task result) whose value settles as a failure.
+     * Returns a human-readable reason on failure, or `null` on success.
      */
+    private detectTaskFailure;
+    /** IDs of tasks that did not succeed. Empty when the whole plan succeeded. */
+    getFailedTaskIds(): string[];
+    /** Whether any task in the plan failed or was blocked. */
+    hasFailures(): boolean;
+    /** Get the result of a specific task from shared memory. */
     getTaskResult(taskId: string): unknown;
-    /**
-     * Get all task results.
-     */
+    /** Get all task results recorded in shared memory. */
     getAllResults(): Record<string, unknown>;
     /**
      * Get the result of the final task (last task in the plan, typically the aggregator).
      */
-    getFinalResult(): unknown;
+    getFinalResult(): {} | null;
 }
 //# sourceMappingURL=parallel-task-executor.d.ts.map

package/dist/parallel-task-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parallel-task-executor.d.ts","sourceRoot":"","sources":["../src/parallel-task-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EACV,iBAAiB,EAKlB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,YAAY,CAAC;AAQjD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;gBAE9C,IAAI,EAAE,2BAA2B;IAc7C;;;OAGG;IACI,OAAO,IAAI,cAAc,CAAC,iBAAiB,CAAC;IAiFnD;;;OAGG;YACY,WAAW;IAuF1B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAa9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAItC;;OAEG;IACH,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQxC;;OAEG;IACH,cAAc,IAAI,OAAO;CAK1B"}
+{"version":3,"file":"parallel-task-executor.d.ts","sourceRoot":"","sources":["../src/parallel-task-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACV,MAAM,sBAAsB,CAAC;AAO9B,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,uBAAuB,CAAC;AAgB/B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,YAAY,CAAC;AASjD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoB;IACpD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAE1D,YAAY,IAAI,EAAE,2BAA2B,EAgB5C;IAED;;;OAGG;IACI,OAAO,IAAI,cAAc,CAAC,iBAAiB,CAAC,CAoDlD;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAcjB;;;;;OAKG;YACY,OAAO;IA0GtB;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAoDlB,4EAA4E;IAC5E,OAAO,CAAC,eAAe;IAmBvB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAgCzB,8EAA8E;IAC9E,gBAAgB,IAAI,MAAM,EAAE,CAE3B;IAED,0DAA0D;IAC1D,WAAW,IAAI,OAAO,CAErB;IAED,4DAA4D;IAC5D,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErC;IAED,sDAAsD;IACtD,aAAa,4BAOZ;IAED;;OAEG;IACH,cAAc,cAIb;CACF"}