@juspay/neurolink 10.5.2 → 10.6.0

package/dist/agent/isolatedAgentRunner.d.ts

@@ -0,0 +1,73 @@
+/**
+ * runIsolatedAgent() — the production sub-agent runner.
+ *
+ * One function replacing what every consumer hand-rolled on top of
+ * generate(): a worker-mode instance (memory off, orchestration off,
+ * observability inherited), a tool-using research pass under the turn budget
+ * (wrap-up nudge + stall watchdog + honest stopReason), an extraction pass
+ * that ALWAYS runs tools-off on its own timeout, a structured-recovery
+ * ladder with corrective re-asks, a delivery guarantee (non-empty execution
+ * records never produce an empty result), abort chaining, a lifecycle event
+ * stream, leashed legs with TTL'd resume handles, and mechanical
+ * waste-signature detection.
+ *
+ * Behavioral contract: docs/plans/2026-07-27-isolated-agent-runner-rfc.md.
+ */
+import type { NeuroLink } from "../neurolink.js";
+import type { AgentRunOptions, AgentRunOutcome, IsolatedAgentDefinition, ToolExecutionRecord } from "../types/index.js";
+/**
+ * True when the SAME host + caller session already has an open (live)
+ * leashed handle for this agent definition.
+ *
+ * Deliberately narrow: a handle belongs to the conversation that opened it,
+ * so the conflict only exists when the caller-supplied `sessionId` matches —
+ * a multi-tenant host must never refuse thread B because thread A has an
+ * in-flight leg (thread B cannot see, continue, or legitimately steer that
+ * handle). Callers without a stable sessionId get no conflict detection;
+ * cross-session concurrency is the delegation pool's job.
+ */
+export declare function hasOpenIsolatedAgentHandle(host: unknown, definitionId: string, callerSessionId?: string): {
+    open: boolean;
+    handle?: string;
+};
+/**
+ * Mechanical digest of a run's execution records: which tools ran, ok/failed
+ * counts, and bounded excerpts of successful payloads. The delivery
+ * guarantee's last line of defense — a non-empty execution record can never
+ * produce an empty result.
+ */
+export declare function buildMechanicalDigest(records: ToolExecutionRecord[]): {
+    kind: "mechanical-digest";
+    toolsRun: Record<string, {
+        calls: number;
+        ok: number;
+        failed: number;
+    }>;
+    excerpts: Array<{
+        toolName: string;
+        params: string;
+        resultText: string;
+    }>;
+};
+/**
+ * Run an isolated sub-agent: research pass with tools under the turn budget,
+ * extraction pass tools-off on its own timeout, structured recovery,
+ * delivery guarantee, abort chaining, events, and (when `options.leg` is
+ * set) leashed legs with a TTL'd resume handle.
+ */
+export declare function runIsolatedAgent(host: NeuroLink, definition: IsolatedAgentDefinition, input: string | Record<string, unknown>, options?: AgentRunOptions): Promise<AgentRunOutcome>;
+/**
+ * Resume a leashed run. `guidance`, when provided, is appended as a user
+ * turn before the next leg — this is how a supervisor re-steers a drifting
+ * worker. An expired handle returns its tombstoned final outcome once.
+ * Handles are owned by the host that created them; a handle with a leg
+ * already in flight refuses a second continuation instead of racing it.
+ */
+export declare function continueIsolatedAgent(host: NeuroLink, handle: string, guidance?: string): Promise<AgentRunOutcome>;
+/**
+ * Stop a leashed run: dispose the worker and return the final outcome
+ * (mechanical digest over everything gathered so far). Refuses while a leg
+ * is in flight — cancel an in-flight leg via the run's `abortSignal` instead
+ * of disposing its worker mid-generate.
+ */
+export declare function stopIsolatedAgent(host: NeuroLink, handle: string): Promise<AgentRunOutcome>;