@juspay/neurolink/dist/agent/backgroundDelegation.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

/**
 * Async delegation (N2) — spawn a background worker, collect it later, in any
 * order.
 *
 * Delegation through `registerAgentTool` is synchronous: the supervising
 * agent's loop blocks on the worker, so four investigations cost four times
 * one investigation and the supervisor sits idle while each runs. This module
 * keeps the same worker machinery and changes only WHEN the caller waits.
 * `spawnDelegate` records the job and returns a `workerId` immediately;
 * `collectDelegates` hands back whichever worker finished FIRST, which has
 * nothing to do with which was spawned first.
 *
 * Everything underneath already existed and is reused, not re-implemented:
 *
 *  - `runIsolatedAgent` gives the worker a fresh session on a worker instance
 *    that SHARES the host's tool registry (so live MCP connections are reused),
 *    plus waste detection, honest stop reasons and continuation handles;
 *  - the process-wide delegation pool in `agentToolRegistrar` bounds
 *    concurrency — one pool, not a second one competing with the first;
 *  - `bankArtifact` (N3) writes each worker's FULL report to a file, so the
 *    conversation carries a bounded summary and a read-back call rather than
 *    a report that has been truncated into uselessness;
 *  - the checklist's `delegatesPending` / `delegatesReady` counters (N1) are
 *    fed from here, which is how the model learns "a worker finished" from any
 *    `tasks_list` — no polling loop, and no change to the core generate loop.
 *
 * @module agent/backgroundDelegation
 */
import type { NeuroLink } from "../neurolink.js";
import type { ChecklistDelegateCounts, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateRuntimeSettings, DelegateSpawnOptions, MCPExecutableTool } from "../types/index.js";
/**
 * Apply registration options for one host: depth ceiling, queue wait, and a
 * raise (never a lowering) of the shared delegation pool.
 */
export declare function configureDelegation(host: NeuroLink, options?: DelegateRegistrationOptions): DelegateRuntimeSettings;
/**
 * Outstanding workers for a host's session: `pending` are still running or
 * queued, `ready` finished and are waiting to be claimed. This is what feeds
 * every `ChecklistToolResult`, so the model learns a worker landed from any
 * `tasks_list` call.
 */
export declare function delegateCounts(host: NeuroLink, sessionId?: string): ChecklistDelegateCounts;
/**
 * Start a background worker and return its handle immediately — before the
 * pool is waited on, and long before the worker finishes.
 *
 * The worker runs through `runIsolatedAgent`, so it gets a fresh session on a
 * worker instance sharing this host's tool registry (live MCP connections
 * included), waste detection, and an honest stop reason. Its full report is
 * banked to a file when it settles; `collectDelegates` hands back the bounded
 * summary and the pointer.
 *
 * @throws when the task is empty or the caller is already at the depth ceiling
 */
export declare function spawnDelegate(host: NeuroLink, options: DelegateSpawnOptions): Promise<DelegateHandle>;
/**
 * Claim finished workers.
 *
 * `{ mode: "any" }` returns the first worker to FINISH — spawn order is
 * irrelevant. `{ mode: "all" }` returns every outstanding worker in completion
 * order. `{ workerId }` waits for one named worker. Each outcome is claimed
 * exactly once and then dropped, so two collects never report the same work
 * twice.
 *
 * `waitMs: 0` polls (whatever is ready right now); omitting it waits up to the
 * runtime default. `timedOut` says work was still outstanding when the call
 * returned — the signal to come back later, not an error.
 *
 * @throws when a named workerId is unknown to this host and session
 */
export declare function collectDelegates(host: NeuroLink, request: DelegateCollectRequest): Promise<DelegateCollectResult>;
/**
 * Cancel background workers: one by id, or every outstanding worker this host
 * spawned. Cancelled workers still settle into a claimable outcome saying they
 * were cancelled — silence would leave the supervisor waiting on a worker that
 * is never coming back.
 *
 * @returns how many workers were cancelled
 */
export declare function cancelDelegates(host: NeuroLink, workerId?: string): Promise<number>;
/**
 * `delegate_task` and `collect_results`, bound to `host`. Register them with
 * `host.registerTool()` (see `NeuroLink.registerDelegationTools()`), never on
 * the tool registry directly: only the "user-defined" category reaches the
 * LLM's tool schema.
 */
export declare function createDelegationTools(host: NeuroLink): Record<string, MCPExecutableTool>;