@juspay/neurolink 12.0.5 → 12.2.0

package/CHANGELOG.md

@@ -1,8 +1,8 @@
-## [12.0.5](https://github.com/juspay/neurolink/compare/v12.0.4...v12.0.5) (2026-08-26)
+## [12.2.0](https://github.com/juspay/neurolink/compare/v12.1.0...v12.2.0) (2026-08-27)
 
-### Bug Fixes
+### Features
 
-- **(core):** window an over-budget prompt instead of dead-ending prompt+tools-only calls ([6d0b436](https://github.com/juspay/neurolink/commit/6d0b4363cb8b38cdbe37e905d5f267668d2ec3bf))
+- **(agent):** task checklist, async delegation, artifact banking, background commands ([444b2ab](https://github.com/juspay/neurolink/commit/444b2ab6a76cc55b2e3d36223502151b3ad1fee2))
 
 ## [11.2.3](https://github.com/juspay/neurolink/compare/v11.2.2...v11.2.3) (2026-08-19)
 

package/dist/agent/agentToolRegistrar.d.ts

@@ -14,6 +14,8 @@
  */
 import type { NeuroLink } from "../neurolink.js";
 import type { AgentToolRegistrationOptions, GenerateOptions, IsolatedAgentDefinition } from "../types/index.js";
+/** Bound on the content text returned into the host loop per delegation. */
+export declare const DELEGATION_RESULT_CONTENT_CHARS = 4000;
 /**
  * Enter a per-turn delegation scope for a top-level generate(). Returns null
  * when a scope is already active (nested/internal generates share the
@@ -31,6 +33,34 @@ export declare function beginDelegationTurn(host: NeuroLink, options: GenerateOp
  * checks) — request-scoped via AsyncLocalStorage, never instance state.
  */
 export declare function runWithNestedDelegationDepth<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * The delegation depth a tool call is being made AT — execution context
+ * first (a worker running the host's registered closure arrives with its own
+ * `agentDepth`), then the per-turn ALS scope, then the host's own context.
+ *
+ * Exported so every delegation surface answers "how deep am I?" the same
+ * way; `executeDelegation` and the background form both call it.
+ */
+export declare function resolveDelegationDepth(host: NeuroLink, executionContext?: Record<string, unknown>): number;
+/**
+ * Raise the process-wide delegation pool to at least `capacity` slots.
+ *
+ * Raises only — never lowers. The pool is shared by every delegation surface,
+ * so a per-agent "max concurrent" that could shrink it would be a throttle on
+ * everyone else's work. Queued waiters the raise just unblocked are granted
+ * immediately, so a raise never leaves capacity idle behind a full queue.
+ */
+export declare function raiseDelegationPoolCapacity(capacity: number): void;
+/**
+ * Take a pool slot only if one is free right now. Returns the release
+ * function, or undefined when the pool is full — never queues.
+ *
+ * Background delegation needs the answer synchronously: `spawnDelegate`
+ * returns a handle BEFORE the worker starts, and the handle reports whether
+ * the worker is running or waiting for a slot. Asking after the fact would be
+ * a guess.
+ */
+export declare function tryAcquireDelegationSlot(): (() => void) | undefined;
 /**
  * Acquire a slot in the process-wide delegation pool, waiting up to
  * `timeoutMs` in the queue. Resolves to a release function.

package/dist/agent/agentToolRegistrar.js

@@ -19,7 +19,7 @@ import { hasOpenIsolatedAgentHandle, runIsolatedAgent, } from "./isolatedAgentRu
 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;
+export const DELEGATION_RESULT_CONTENT_CHARS = 4000;
 // ── Registrations ──────────────────────────────────────────────────────────
 const hostRegistrations = new WeakMap();
 function registrationsFor(host) {
@@ -80,13 +80,28 @@ export function runWithNestedDelegationDepth(fn) {
         : { 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).
+/**
+ * The delegation depth a tool call is being made AT — execution context
+ * first (a worker running the host's registered closure arrives with its own
+ * `agentDepth`), then the per-turn ALS scope, then the host's own context.
+ *
+ * Exported so every delegation surface answers "how deep am I?" the same
+ * way; `executeDelegation` and the background form both call it.
+ */
+export function resolveDelegationDepth(host, executionContext) {
     const fromExecution = executionContext?.agentDepth;
     if (typeof fromExecution === "number") {
         return fromExecution;
     }
+    const turnScope = turnStorage.getStore();
+    return turnScope?.depth ?? resolveDepth(host);
+}
+/**
+ * Depth declared by the CALL or the instance. The execution context — which
+ * carries the agentDepth stamped on the worker actually making the call — is
+ * checked one level up, in {@link resolveDelegationDepth}.
+ */
+function resolveDepth(host, options) {
     const fromCall = options?.context?.agentDepth;
     if (typeof fromCall === "number") {
         return fromCall;
@@ -106,6 +121,57 @@ function releasePoolSlot() {
         next.grant();
     }
 }
+/**
+ * Raise the process-wide delegation pool to at least `capacity` slots.
+ *
+ * Raises only — never lowers. The pool is shared by every delegation surface,
+ * so a per-agent "max concurrent" that could shrink it would be a throttle on
+ * everyone else's work. Queued waiters the raise just unblocked are granted
+ * immediately, so a raise never leaves capacity idle behind a full queue.
+ */
+export function raiseDelegationPoolCapacity(capacity) {
+    // Infinity historically meant "unbounded" (Math.max accepted it); map it to
+    // a finite stand-in rather than silently dropping to the default. NaN stays
+    // rejected — it used to deadlock the pool permanently (Math.max(4, NaN) is
+    // NaN, and `poolInUse < NaN` is always false).
+    const UNBOUNDED_STAND_IN = 1024;
+    if (capacity === Number.POSITIVE_INFINITY) {
+        capacity = UNBOUNDED_STAND_IN;
+    }
+    if (!Number.isFinite(capacity) || capacity <= poolCapacity) {
+        return;
+    }
+    poolCapacity = capacity;
+    while (poolInUse < poolCapacity && poolWaiters.length > 0) {
+        const next = poolWaiters.shift();
+        if (next) {
+            poolInUse++;
+            next.grant();
+        }
+    }
+}
+/**
+ * Take a pool slot only if one is free right now. Returns the release
+ * function, or undefined when the pool is full — never queues.
+ *
+ * Background delegation needs the answer synchronously: `spawnDelegate`
+ * returns a handle BEFORE the worker starts, and the handle reports whether
+ * the worker is running or waiting for a slot. Asking after the fact would be
+ * a guess.
+ */
+export function tryAcquireDelegationSlot() {
+    if (poolInUse >= poolCapacity) {
+        return undefined;
+    }
+    poolInUse++;
+    let released = false;
+    return () => {
+        if (!released) {
+            released = true;
+            releasePoolSlot();
+        }
+    };
+}
 /**
  * Acquire a slot in the process-wide delegation pool, waiting up to
  * `timeoutMs` in the queue. Resolves to a release function.
@@ -169,17 +235,7 @@ export function registerAgentTool(host, definition, options = {}) {
         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();
-            }
-        }
+        raiseDelegationPoolCapacity(options.maxConcurrent);
     }
     const registration = {
         name,
@@ -228,9 +284,7 @@ async function executeDelegation(host, registration, params, context) {
     // 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));
+    const depth = resolveDelegationDepth(host, contextRecord);
     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.`);
     }

package/dist/agent/backgroundCommands.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Background commands (N4) — run a command detached, bank every byte it
+ * writes, monitor it while it runs.
+ *
+ * A reviewing agent has to run real commands — a build, a test suite, a linter
+ * whose output IS the evidence for a finding — and the naive shapes both fail.
+ * `bashTool` blocks the loop, hands the model a shell, and truncates its own
+ * output at 100 KB. A `child_process` call with a string command is a shell
+ * injection with extra steps.
+ *
+ * This module keeps three promises instead:
+ *
+ *  - **Detached.** `startBackgroundCommand` returns a `taskId` immediately; the
+ *    agent keeps working and asks about the command when it wants to.
+ *  - **Nothing discarded.** Both streams are written straight to files as they
+ *    arrive and the COMPLETE files are banked as artifacts (N3) when the
+ *    command settles. The conversation gets a bounded tail plus a read-back
+ *    call. The single bound is `maxOutputBytes`, and reaching it is a state
+ *    (`output-limit`) the caller can see, not a silent cut.
+ *  - **Hardened by contract.** argv arrays with `shell: false`, an exact-match
+ *    executable allowlist, a cwd that must resolve through symlinks inside a
+ *    declared root, and a timeout that escalates SIGTERM → SIGKILL.
+ *
+ * Completion reaches the model the same way a delegate's does (N2.3): the
+ * `running` / `finished` counters ride on every command tool result and — via
+ * the checklist — on every `tasks_list`. The core generate loop is untouched.
+ *
+ * @module agent/backgroundCommands
+ */
+import type { NeuroLink } from "../neurolink.js";
+import type { BackgroundCommandCounts, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, MCPExecutableTool } from "../types/index.js";
+/**
+ * Declare what this host may execute. There is no default: until this is
+ * called, every start is refused, because "run whatever the model asks" is not
+ * a defensible default for a primitive that spawns processes.
+ */
+export declare function setBackgroundCommandPolicy(host: NeuroLink, policy: BackgroundCommandPolicy): void;
+/** The policy in force for a host, or undefined when none was declared. */
+export declare function getBackgroundCommandPolicy(host: NeuroLink): BackgroundCommandPolicy | undefined;
+/**
+ * Commands for a host's session: `running` have not settled, `finished` have.
+ * Carried on every command tool result and on every `ChecklistToolResult`, so
+ * the model learns a build finished without polling for it.
+ */
+export declare function backgroundCommandCounts(host: NeuroLink, sessionId?: string): BackgroundCommandCounts;
+/**
+ * Start a command in the background and get its task id immediately.
+ *
+ * @throws when no policy is set, argv is malformed, the executable is not
+ *         allowlisted, the policy vetoes the command, or the cwd escapes the
+ *         sandbox root. Every message names its own recovery step.
+ */
+export declare function startBackgroundCommand(host: NeuroLink, argv: string[], options: BackgroundCommandOptions): Promise<BackgroundCommandHandle>;
+/**
+ * Everything known about one command right now — synchronous, because the
+ * job state is live and a monitor that has to be awaited is a monitor nobody
+ * calls mid-loop.
+ *
+ * @throws when the task id is unknown to this host
+ */
+export declare function getBackgroundCommandStatus(host: NeuroLink, taskId: string): BackgroundCommandStatus;
+/**
+ * Wait for a command to settle.
+ *
+ * `timeoutMs` bounds the WAIT, not the command: when it elapses the current
+ * (still running) status is returned rather than throwing, so a caller can
+ * poll in bounded steps without ever losing the job.
+ *
+ * @throws when the task id is unknown to this host
+ */
+export declare function awaitBackgroundCommand(host: NeuroLink, taskId: string, opts?: {
+    timeoutMs?: number;
+}): Promise<BackgroundCommandStatus>;
+/**
+ * Kill a running command: SIGTERM (or the signal you name), SIGKILL five
+ * seconds later if it is still there. Resolves with the settled status, so a
+ * caller never has to guess whether the output was banked yet.
+ *
+ * Killing an already-settled command is a no-op that returns its status —
+ * the outcome is not discarded.
+ *
+ * @throws when the task id is unknown to this host
+ */
+export declare function killBackgroundCommand(host: NeuroLink, taskId: string, signal?: NodeJS.Signals): Promise<BackgroundCommandStatus>;
+/**
+ * Kill every unsettled command this host started. Host lifecycle only
+ * (`shutdown()`/`dispose()`): a disposed instance must not leave child
+ * processes running with nobody left to collect them.
+ *
+ * @returns how many commands were signalled
+ */
+export declare function killAllBackgroundCommands(host: NeuroLink): Promise<number>;
+/**
+ * Read one character window of a command's output, straight from its log file.
+ *
+ * Works while the command is still running — that is the monitor case — and
+ * after it settled. Character offsets, `totalSize` and `hasMore` match
+ * `retrieve_context` exactly, so paging code written for one works on the
+ * other.
+ *
+ * @throws when the task id is unknown to this host
+ */
+export declare function readBackgroundCommandOutput(host: NeuroLink, taskId: string, page: BackgroundCommandPageRequest): Promise<BackgroundCommandOutputPage>;
+/**
+ * The four model-facing command tools, bound to `host`. Register them with
+ * `host.registerTool()` (see `NeuroLink.registerBackgroundCommandTools()`),
+ * never on the tool registry directly: only the "user-defined" category
+ * reaches the LLM's tool schema.
+ */
+export declare function createBackgroundCommandTools(host: NeuroLink): Record<string, MCPExecutableTool>;