@juspay/neurolink 10.5.2 → 10.6.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [10.6.0](https://github.com/juspay/neurolink/compare/v10.5.3...v10.6.0) (2026-07-27)
+
+### Features
+
+- **(agent):** add isolated sub-agent runtime and host-loop delegation ([e62390f](https://github.com/juspay/neurolink/commit/e62390f2348d492a21703e7df734de2e23e543e5))
+
+## [10.5.3](https://github.com/juspay/neurolink/compare/v10.5.2...v10.5.3) (2026-07-26)
+
+### Bug Fixes
+
+- **(ci):** raise yama floor to v2.7.2 for the 5m litellm timeout ([0dcf295](https://github.com/juspay/neurolink/commit/0dcf295547aaabfcaa95da2956f5c045d909db9b))
+
 ## [10.5.2](https://github.com/juspay/neurolink/compare/v10.5.1...v10.5.2) (2026-07-24)
 
 ### Bug Fixes

package/dist/agent/agent.js

@@ -108,6 +108,12 @@ export class Agent {
             timestamp: startTime,
         });
         try {
+            // No ghost runs: an already-aborted parent stops the agent before any
+            // model call is made. Typed so callers can branch on the ABORT
+            // category instead of parsing free text.
+            if (options?.abortSignal?.aborted) {
+                throw ErrorFactory.aborted(new Error("Agent execution aborted before start"));
+            }
             // Validate input if schema provided
             if (this.inputSchema && typeof input !== "string") {
                 const validation = this.inputSchema.safeParse(input);
@@ -149,19 +155,14 @@ export class Agent {
                 contentLength: result.content?.length || 0,
                 toolsUsed: result.toolsUsed?.length || 0,
             });
-            // Pass through toolExecutions, adding duration (not provided by generate())
-            const toolExecutions = result.toolExecutions?.map((te) => ({
-                name: te.name,
-                input: te.input,
-                output: te.output,
-                duration: 0,
-            }));
             const agentResult = {
                 content: result.content || "",
                 object: parsedOutput,
                 usage: result.usage,
                 toolsUsed: result.toolsUsed,
-                toolExecutions,
+                // Real per-call records straight from the tool loop (N2)
+                toolExecutions: result.toolExecutions,
+                stopReason: result.stopReason,
                 duration,
                 status: "success",
                 agentId: this.id,
@@ -219,6 +220,10 @@ export class Agent {
             traceId,
         };
         try {
+            // Mirror execute(): an already-aborted parent never starts the stream.
+            if (options?.abortSignal?.aborted) {
+                throw ErrorFactory.aborted(new Error("Agent stream aborted before start"));
+            }
             // Validate input if schema provided
             if (this.inputSchema && typeof input !== "string") {
                 const validation = this.inputSchema.safeParse(input);
@@ -367,6 +372,20 @@ export class Agent {
             ...(this.tools && this.tools.length > 0 && { toolFilter: this.tools }),
             maxSteps: options?.maxSteps ?? this.maxSteps,
             requestId: traceId,
+            // Turn budget + cancellation, forwarded verbatim to generate() — the
+            // machinery (wrap-up nudge, stall watchdog, honest stopReason) lives
+            // in the tool loop; the agent layer just passes it through.
+            ...(options?.abortSignal && { abortSignal: options.abortSignal }),
+            ...(options?.timeout !== undefined && { timeout: options.timeout }),
+            ...(options?.turnTimeoutMs !== undefined && {
+                turnTimeoutMs: options.turnTimeoutMs,
+            }),
+            ...(options?.wrapupTimeLeadMs !== undefined && {
+                wrapupTimeLeadMs: options.wrapupTimeLeadMs,
+            }),
+            ...(options?.stallTimeoutMs !== undefined && {
+                stallTimeoutMs: options.stallTimeoutMs,
+            }),
             context: {
                 agentId: this.id,
                 agentName: this.name,
@@ -390,6 +409,18 @@ export class Agent {
             // toolFilter delegates to BaseProvider.applyToolFiltering() natively
             ...(this.tools && this.tools.length > 0 && { toolFilter: this.tools }),
             maxSteps: options?.maxSteps ?? this.maxSteps,
+            // Turn budget + cancellation, forwarded verbatim to stream()
+            ...(options?.abortSignal && { abortSignal: options.abortSignal }),
+            ...(options?.timeout !== undefined && { timeout: options.timeout }),
+            ...(options?.turnTimeoutMs !== undefined && {
+                turnTimeoutMs: options.turnTimeoutMs,
+            }),
+            ...(options?.wrapupTimeLeadMs !== undefined && {
+                wrapupTimeLeadMs: options.wrapupTimeLeadMs,
+            }),
+            ...(options?.stallTimeoutMs !== undefined && {
+                stallTimeoutMs: options.stallTimeoutMs,
+            }),
             context: {
                 agentId: this.id,
                 agentName: this.name,

package/dist/agent/agentNetwork.js

@@ -13,6 +13,7 @@ import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { ErrorFactory } from "../utils/errorHandling.js";
 import { Agent } from "./agent.js";
+import { acquireDelegationSlot, runWithNestedDelegationDepth, } from "./agentToolRegistrar.js";
 /**
  * AgentNetwork - Multi-agent orchestration using the ai SDK tool loop
  *
@@ -171,21 +172,62 @@ export class AgentNetwork {
             // Capture in closure so the async execute below closes over the right values
             const capturedId = id;
             const capturedAgent = agentInstance;
-            const schema = z.object({
-                task: z.string().describe("The task to delegate to this agent"),
-            });
+            // Honor the agent's declared inputSchema; default to a plain task
+            // string when the definition doesn't declare one.
+            const customSchema = capturedAgent.inputSchema;
+            const schema = customSchema ??
+                z.object({
+                    task: z.string().describe("The task to delegate to this agent"),
+                });
             tools[`agent_${capturedId}`] = tool({
                 description: `Agent: ${capturedAgent.name} - ${capturedAgent.description}`,
                 inputSchema: schema,
                 execute: async (params) => {
-                    logger.debug(`[AgentNetwork:${this.id}] Delegating to agent: ${capturedAgent.name}`, { task: params.task.slice(0, 100) });
-                    const result = await capturedAgent.execute(params.task);
-                    return {
-                        agentId: capturedId,
-                        content: result.content,
-                        status: result.status,
-                        error: result.error,
-                    };
+                    // With a custom inputSchema the parsed object passes through to
+                    // the agent untouched; the default schema unwraps the task string.
+                    const input = customSchema
+                        ? params
+                        : params.task;
+                    logger.debug(`[AgentNetwork:${this.id}] Delegating to agent: ${capturedAgent.name}`, {
+                        task: typeof input === "string"
+                            ? input.slice(0, 100)
+                            : input && typeof input === "object"
+                                ? Object.keys(input).join(",")
+                                : String(input),
+                    });
+                    // Standalone-mode delegations share the same process-wide pool as
+                    // host-loop delegations (registerAgentTool), so concurrent agent
+                    // fan-out is bounded framework-wide. Refusals carry the recovery
+                    // instruction, mirroring the host-loop contract.
+                    let release;
+                    try {
+                        release = await acquireDelegationSlot();
+                    }
+                    catch {
+                        return {
+                            agentId: capturedId,
+                            content: "",
+                            status: "error",
+                            error: `All delegation slots are busy and the queue timed out. Do not retry agent_${capturedId} immediately; synthesize from the results you already have.`,
+                        };
+                    }
+                    try {
+                        // The agent executes one delegation level deeper: this tool call
+                        // holds a pool slot for its whole duration, so any
+                        // registered-agent-tool delegation the agent makes from inside
+                        // must take the nested path instead of queueing behind the slot
+                        // its own caller is holding.
+                        const result = await runWithNestedDelegationDepth(() => capturedAgent.execute(input));
+                        return {
+                            agentId: capturedId,
+                            content: result.content,
+                            status: result.status,
+                            error: result.error,
+                        };
+                    }
+                    finally {
+                        release();
+                    }
                 },
             });
         }
@@ -214,9 +256,9 @@ Use the appropriate agent tool(s) to handle the task. Return a clear, complete f
     buildTrace(toolExecutions, traceId, startTime) {
         const steps = (toolExecutions ?? []).map((exec, index) => {
             // Tool name format is "agent_<id>" — extract agent id
-            const agentId = exec.name.startsWith("agent_")
-                ? exec.name.slice("agent_".length)
-                : exec.name;
+            const agentId = exec.toolName.startsWith("agent_")
+                ? exec.toolName.slice("agent_".length)
+                : exec.toolName;
             const primitive = this.primitives.get(agentId);
             return {
                 index,
@@ -225,10 +267,11 @@ Use the appropriate agent tool(s) to handle the task. Return a clear, complete f
                     id: agentId,
                     name: primitive?.name ?? agentId,
                 },
-                input: exec.input,
-                output: exec.output,
-                duration: 0, // individual step timing not available from generate()
-                timestamp: startTime,
+                input: exec.params,
+                output: exec.resultText,
+                ...(exec.isError && { error: exec.resultText }),
+                duration: exec.durationMs,
+                timestamp: exec.startedAt || startTime,
             };
         });
         return {
@@ -272,8 +315,7 @@ Use the appropriate agent tool(s) to handle the task. Return a clear, complete f
                 maxSteps,
                 tools: agentTools,
             });
-            const toolExecutions = (result.toolExecutions ?? []);
-            const trace = this.buildTrace(toolExecutions, traceId, startTime);
+            const trace = this.buildTrace(result.toolExecutions, traceId, startTime);
             // Aggregate token usage across all agent tool calls
             const usage = result.usage;
             const totalUsage = {

package/dist/agent/agentToolRegistrar.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Host-loop delegation (N5): `registerAgentTool()` wraps an isolated agent
+ * (runIsolatedAgent) as a tool on the HOST NeuroLink instance, so the host's
+ * EXISTING generate() loop delegates — never a second router generate.
+ *
+ * Framework policy lives here:
+ *  - per-turn delegation caps, counted per top-level generate() in the loop
+ *    itself (AsyncLocalStorage turn scope);
+ *  - depth limits via tool context (`agentDepth`) — at the limit the tool is
+ *    withheld from the request entirely;
+ *  - a process-wide concurrency pool with queue timeout, shared by every
+ *    registered agent tool;
+ *  - every refusal carries its recovery instruction in the error text.
+ */
+import type { NeuroLink } from "../neurolink.js";
+import type { AgentToolRegistrationOptions, GenerateOptions, IsolatedAgentDefinition } from "../types/index.js";
+/**
+ * Enter a per-turn delegation scope for a top-level generate(). Returns null
+ * when a scope is already active (nested/internal generates share the
+ * top-level turn's counters) — the caller then proceeds without wrapping.
+ */
+export declare function beginDelegationTurn(host: NeuroLink, options: GenerateOptions | string | Record<string, unknown>): {
+    options: typeof options;
+    run: <T>(fn: () => Promise<T>) => Promise<T>;
+} | null;
+/**
+ * Run `fn` one delegation level deeper, sharing the current turn's counters.
+ * Used by AgentNetwork's standalone delegations: the network holds a pool
+ * slot around each agent execution, so any registered-agent-tool delegation
+ * the agent makes from inside must take the NESTED path (pool bypass, depth
+ * checks) — request-scoped via AsyncLocalStorage, never instance state.
+ */
+export declare function runWithNestedDelegationDepth<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Acquire a slot in the process-wide delegation pool, waiting up to
+ * `timeoutMs` in the queue. Resolves to a release function.
+ */
+export declare function acquireDelegationSlot(timeoutMs?: number): Promise<() => void>;
+/**
+ * Register an isolated agent as a delegation tool on the host instance.
+ * The tool becomes available to every generate()/stream() the host runs —
+ * inside its existing loop, no second router generate.
+ */
+export declare function registerAgentTool(host: NeuroLink, definition: IsolatedAgentDefinition, options?: AgentToolRegistrationOptions): {
+    name: string;
+};
+/** Test-only: reset the process-wide pool. */
+export declare function resetDelegationPoolForTests(capacity?: number): void;

package/dist/agent/agentToolRegistrar.js

@@ -0,0 +1,336 @@
+/**
+ * Host-loop delegation (N5): `registerAgentTool()` wraps an isolated agent
+ * (runIsolatedAgent) as a tool on the HOST NeuroLink instance, so the host's
+ * EXISTING generate() loop delegates — never a second router generate.
+ *
+ * Framework policy lives here:
+ *  - per-turn delegation caps, counted per top-level generate() in the loop
+ *    itself (AsyncLocalStorage turn scope);
+ *  - depth limits via tool context (`agentDepth`) — at the limit the tool is
+ *    withheld from the request entirely;
+ *  - a process-wide concurrency pool with queue timeout, shared by every
+ *    registered agent tool;
+ *  - every refusal carries its recovery instruction in the error text.
+ */
+import { AsyncLocalStorage } from "async_hooks";
+import { logger } from "../utils/logger.js";
+import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
+import { hasOpenIsolatedAgentHandle, runIsolatedAgent, } from "./isolatedAgentRunner.js";
+const DEFAULT_POOL_CAPACITY = 4;
+const DEFAULT_POOL_QUEUE_TIMEOUT_MS = 30_000;
+/** Bound on the content text returned into the host loop per delegation. */
+const DELEGATION_RESULT_CONTENT_CHARS = 4000;
+// ── Registrations ──────────────────────────────────────────────────────────
+const hostRegistrations = new WeakMap();
+function registrationsFor(host) {
+    let map = hostRegistrations.get(host);
+    if (!map) {
+        map = new Map();
+        hostRegistrations.set(host, map);
+    }
+    return map;
+}
+// ── Per-turn scope (delegation caps) ───────────────────────────────────────
+const turnStorage = new AsyncLocalStorage();
+/**
+ * Enter a per-turn delegation scope for a top-level generate(). Returns null
+ * when a scope is already active (nested/internal generates share the
+ * top-level turn's counters) — the caller then proceeds without wrapping.
+ */
+export function beginDelegationTurn(host, options) {
+    if (turnStorage.getStore()) {
+        return null;
+    }
+    const registrations = registrationsFor(host);
+    let scopedOptions = options;
+    if (registrations.size > 0 && typeof options !== "string") {
+        const depth = resolveDepth(host, options);
+        const withheld = [...registrations.values()]
+            .filter((r) => r.options.maxDepth !== undefined && depth >= r.options.maxDepth)
+            .map((r) => r.name);
+        if (withheld.length > 0) {
+            const generateOptions = options;
+            scopedOptions = {
+                ...generateOptions,
+                excludeTools: [...(generateOptions.excludeTools ?? []), ...withheld],
+            };
+            logger.debug("[AgentToolRegistrar] Withholding depth-limited agent tools", { withheld, depth });
+        }
+    }
+    const state = {
+        counts: new Map(),
+        depth: resolveDepth(host, typeof options === "string" ? undefined : options),
+    };
+    return {
+        options: scopedOptions,
+        run: (fn) => turnStorage.run(state, fn),
+    };
+}
+/**
+ * Run `fn` one delegation level deeper, sharing the current turn's counters.
+ * Used by AgentNetwork's standalone delegations: the network holds a pool
+ * slot around each agent execution, so any registered-agent-tool delegation
+ * the agent makes from inside must take the NESTED path (pool bypass, depth
+ * checks) — request-scoped via AsyncLocalStorage, never instance state.
+ */
+export function runWithNestedDelegationDepth(fn) {
+    const store = turnStorage.getStore();
+    const state = store
+        ? { counts: store.counts, depth: store.depth + 1 }
+        : { counts: new Map(), depth: 1 };
+    return turnStorage.run(state, fn);
+}
+function resolveDepth(host, options, executionContext) {
+    // Execution context wins: it carries the agentDepth stamped on the worker
+    // that is actually making this call (see executeDelegation).
+    const fromExecution = executionContext?.agentDepth;
+    if (typeof fromExecution === "number") {
+        return fromExecution;
+    }
+    const fromCall = options?.context?.agentDepth;
+    if (typeof fromCall === "number") {
+        return fromCall;
+    }
+    const fromInstance = host.getToolContext()?.agentDepth;
+    return typeof fromInstance === "number" ? fromInstance : 0;
+}
+// ── Process-wide delegation pool ───────────────────────────────────────────
+let poolCapacity = DEFAULT_POOL_CAPACITY;
+let poolInUse = 0;
+const poolWaiters = [];
+function releasePoolSlot() {
+    poolInUse = Math.max(0, poolInUse - 1);
+    const next = poolWaiters.shift();
+    if (next) {
+        poolInUse++;
+        next.grant();
+    }
+}
+/**
+ * Acquire a slot in the process-wide delegation pool, waiting up to
+ * `timeoutMs` in the queue. Resolves to a release function.
+ */
+export function acquireDelegationSlot(timeoutMs = DEFAULT_POOL_QUEUE_TIMEOUT_MS) {
+    if (poolInUse < poolCapacity) {
+        poolInUse++;
+        let released = false;
+        return Promise.resolve(() => {
+            if (!released) {
+                released = true;
+                releasePoolSlot();
+            }
+        });
+    }
+    return new Promise((resolve, reject) => {
+        const waiter = {
+            grant: () => {
+                clearTimeout(timer);
+                let released = false;
+                resolve(() => {
+                    if (!released) {
+                        released = true;
+                        releasePoolSlot();
+                    }
+                });
+            },
+            cancel: (reason) => {
+                clearTimeout(timer);
+                reject(reason);
+            },
+        };
+        const timer = setTimeout(() => {
+            const index = poolWaiters.indexOf(waiter);
+            if (index !== -1) {
+                poolWaiters.splice(index, 1);
+            }
+            waiter.cancel(new Error("delegation pool queue timeout"));
+        }, timeoutMs);
+        timer.unref?.();
+        poolWaiters.push(waiter);
+    });
+}
+// ── Refusals (recovery instruction always included) ────────────────────────
+function refusal(message) {
+    return { isError: true, error: message };
+}
+// ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Register an isolated agent as a delegation tool on the host instance.
+ * The tool becomes available to every generate()/stream() the host runs —
+ * inside its existing loop, no second router generate.
+ */
+export function registerAgentTool(host, definition, options = {}) {
+    if (!definition?.id || !definition?.instructions) {
+        throw new Error("registerAgentTool: definition must include id and instructions");
+    }
+    const name = options.name ?? definition.id;
+    const registrations = registrationsFor(host);
+    if (registrations.has(name)) {
+        throw new Error(`registerAgentTool: an agent tool named "${name}" is already registered on this instance`);
+    }
+    if (options.maxConcurrent !== undefined) {
+        // Process-wide pool: the largest registered capacity wins (raises only —
+        // never lowers; this is not a per-agent throttle). Grant any queued
+        // waiters the raise just unblocked.
+        poolCapacity = Math.max(poolCapacity, options.maxConcurrent);
+        while (poolInUse < poolCapacity && poolWaiters.length > 0) {
+            const next = poolWaiters.shift();
+            if (next) {
+                poolInUse++;
+                next.grant();
+            }
+        }
+    }
+    const registration = {
+        name,
+        definition,
+        options,
+    };
+    registrations.set(name, registration);
+    const inputSchema = definition.inputSchema
+        ? convertZodToJsonSchema(definition.inputSchema)
+        : {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "The task to delegate to this agent",
+                },
+            },
+            required: ["task"],
+        };
+    host.registerTool(name, {
+        name,
+        description: `Delegate to agent: ${definition.name} — ${definition.description}`,
+        inputSchema: inputSchema,
+        execute: async (params, context) => {
+            return executeDelegation(host, registration, params, context);
+        },
+    });
+    logger.debug("[AgentToolRegistrar] Registered agent tool", {
+        name,
+        agentId: definition.id,
+        maxDelegationsPerTurn: options.maxDelegationsPerTurn,
+        maxDepth: options.maxDepth,
+    });
+    return { name };
+}
+async function executeDelegation(host, registration, params, context) {
+    const { name, definition, options } = registration;
+    const contextRecord = context && typeof context === "object"
+        ? context
+        : {};
+    // Depth comes from the EXECUTION context first: when a worker created with
+    // the shared tool registry delegates, the registration lives on the host
+    // but the call arrives with the worker's tool context carrying the
+    // agentDepth this registrar set — the host instance context would read 0
+    // every time and nested delegation would never hit the limit. When the
+    // execution context carries no depth, the ALS turn scope's depth covers
+    // the composed path (AgentNetwork wraps its agents one level deeper).
+    const turnScope = turnStorage.getStore();
+    const depth = typeof contextRecord.agentDepth === "number"
+        ? contextRecord.agentDepth
+        : (turnScope?.depth ?? resolveDepth(host));
+    if (options.maxDepth !== undefined && depth >= options.maxDepth) {
+        return refusal(`Delegation depth limit reached (${depth}/${options.maxDepth}). Complete this investigation yourself with your own tools instead of delegating further.`);
+    }
+    const sessionId = typeof contextRecord.sessionId === "string"
+        ? contextRecord.sessionId
+        : undefined;
+    // Open-handle conflict: an in-progress leashed leg for this agent, owned
+    // by THIS host + caller session, must be continued, not restarted. Other
+    // sessions' handles are invisible here — the pool bounds cross-session
+    // concurrency.
+    const openHandle = hasOpenIsolatedAgentHandle(host, definition.id, sessionId);
+    if (openHandle.open) {
+        return refusal(`Agent "${definition.id}" already has an in-progress investigation (handle ${openHandle.handle}); continue it via its handle instead of delegating anew.`);
+    }
+    // Per-turn cap — counted in the loop itself, per top-level generate. The
+    // count check runs before the pool wait, but the count is CONSUMED only
+    // once a run actually starts: a refusal (depth/handle/pool) must not burn
+    // one of the model's delegations. Nested scopes share the top-level
+    // turn's counters (see runWithNestedDelegationDepth).
+    const turnState = turnScope;
+    if (options.maxDelegationsPerTurn !== undefined && turnState) {
+        const used = turnState.counts.get(name) ?? 0;
+        if (used >= options.maxDelegationsPerTurn) {
+            return refusal(`Delegation limit reached: ${name} has already been called ${used}× this turn (max ${options.maxDelegationsPerTurn}). Do not call ${name} again this turn; synthesize from the investigations you already have.`);
+        }
+    }
+    // Nested delegations bypass the pool: the outer delegation already holds a
+    // slot, so queueing nested work behind a full pool would deadlock it (all
+    // slots held by outers waiting on their inners).
+    let release;
+    if (depth === 0) {
+        try {
+            release = await acquireDelegationSlot(options.poolQueueTimeoutMs ?? DEFAULT_POOL_QUEUE_TIMEOUT_MS);
+        }
+        catch {
+            return refusal(`All delegation slots are busy and the queue timed out. Do not retry ${name} immediately; continue with your own tools or synthesize from the investigations you already have.`);
+        }
+    }
+    try {
+        // Consume the per-turn count only now that the run actually starts.
+        if (options.maxDelegationsPerTurn !== undefined && turnState) {
+            turnState.counts.set(name, (turnState.counts.get(name) ?? 0) + 1);
+        }
+        // Default task-string schema: unwrap `task`; a bare string passes
+        // through; any other object passes through whole (runIsolatedAgent
+        // JSON-stringifies structured input — never "[object Object]").
+        const input = definition.inputSchema
+            ? params
+            : typeof params?.task === "string"
+                ? params.task
+                : typeof params === "string"
+                    ? params
+                    : (params ?? {});
+        const abortSignal = contextRecord
+            .abortSignal;
+        const outcome = await runIsolatedAgent(host, definition, input, {
+            ...(abortSignal && { abortSignal }),
+            ...(options.leg && { leg: options.leg }),
+            ...(options.handleTtlMs !== undefined && {
+                handleTtlMs: options.handleTtlMs,
+            }),
+            ...(options.waste && { waste: options.waste }),
+            ...(options.overrides && { overrides: options.overrides }),
+            toolContext: {
+                agentDepth: depth + 1,
+                ...(sessionId && { sessionId }),
+            },
+        });
+        // Bounded summary into the host loop — full records stay on the outcome
+        // for programmatic callers; the model gets the essentials.
+        return {
+            status: outcome.status,
+            ...(outcome.data !== undefined && { data: outcome.data }),
+            ...(outcome.content && {
+                content: outcome.content.length > DELEGATION_RESULT_CONTENT_CHARS
+                    ? `${outcome.content.slice(0, DELEGATION_RESULT_CONTENT_CHARS)}…`
+                    : outcome.content,
+            }),
+            ...(outcome.stopReason && { stopReason: outcome.stopReason }),
+            toolCallsUsed: outcome.toolExecutions.length,
+            durationMs: outcome.durationMs,
+            ...(outcome.handle && { handle: outcome.handle }),
+            ...(outcome.delta && { delta: outcome.delta }),
+            ...(outcome.nextPlan && { nextPlan: outcome.nextPlan }),
+            ...(outcome.wasteSignals && { wasteSignals: outcome.wasteSignals }),
+            ...(outcome.budget && { budget: outcome.budget }),
+        };
+    }
+    catch (error) {
+        return refusal(`Delegation to ${name} failed: ${error instanceof Error ? error.message : String(error)}. Continue with your own tools or synthesize from what you already have.`);
+    }
+    finally {
+        release?.();
+    }
+}
+/** Test-only: reset the process-wide pool. */
+export function resetDelegationPoolForTests(capacity) {
+    poolCapacity = capacity ?? DEFAULT_POOL_CAPACITY;
+    poolInUse = 0;
+    poolWaiters
+        .splice(0, poolWaiters.length)
+        .forEach((w) => w.cancel(new Error("pool reset")));
+}

package/dist/agent/index.d.ts

@@ -31,6 +31,9 @@
  */
 export { Agent } from "./agent.js";
 export { AgentNetwork } from "./agentNetwork.js";
+export { runIsolatedAgent, continueIsolatedAgent, stopIsolatedAgent, buildMechanicalDigest, hasOpenIsolatedAgentHandle, } from "./isolatedAgentRunner.js";
+export { registerAgentTool, beginDelegationTurn, acquireDelegationSlot, runWithNestedDelegationDepth, resetDelegationPoolForTests, } from "./agentToolRegistrar.js";
+export { collectStructuredCandidates, recoverStructuredData, summarizeZodError, } from "./structuredRecovery.js";
 export { directAgentTools, getAvailableToolNames, getToolsForCategory, } from "./directTools.js";
 export { buildConfidencePrompt, buildMultiStepPlanningPrompt, buildRoutingPrompt, parseRoutingResponse, ROUTING_PROMPTS, } from "./prompts/routingPrompts.js";
 export { AgentCoordinator, TaskDistributor } from "./coordination/index.js";

package/dist/agent/index.js

@@ -32,6 +32,10 @@
 // Core agent classes
 export { Agent } from "./agent.js";
 export { AgentNetwork } from "./agentNetwork.js";
+// Isolated sub-agent runtime (N4/N5)
+export { runIsolatedAgent, continueIsolatedAgent, stopIsolatedAgent, buildMechanicalDigest, hasOpenIsolatedAgentHandle, } from "./isolatedAgentRunner.js";
+export { registerAgentTool, beginDelegationTurn, acquireDelegationSlot, runWithNestedDelegationDepth, resetDelegationPoolForTests, } from "./agentToolRegistrar.js";
+export { collectStructuredCandidates, recoverStructuredData, summarizeZodError, } from "./structuredRecovery.js";
 // Direct tools (existing)
 export { directAgentTools, getAvailableToolNames, getToolsForCategory, } from "./directTools.js";
 // Routing prompts and utilities