@juspay/neurolink 12.1.0 → 12.2.1

package/dist/agent/backgroundDelegation.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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>;