@lloyal-labs/lloyal-agents 1.0.0

package/README.md

@@ -0,0 +1,280 @@
+# @lloyal-labs/lloyal-agents
+
+Structured concurrency agent runtime for the lloyal inference platform.
+
+`lloyal-agents` runs multi-agent inference inside the decode loop. Agents are branches of a single running process — forked from shared KV cache state, advancing through one GPU forward pass per tick, spawning sub-agents from their own live branches at arbitrary depth. Orchestration is not a layer above inference. It is inference.
+
+```bash
+npm i @lloyal-labs/lloyal-agents
+```
+
+**Backends:** [lloyal.node](https://github.com/lloyal-ai/lloyal.node) — prebuilt binaries for macOS (Metal, CPU), Linux (CPU, CUDA, Vulkan), and Windows (CPU, CUDA, Vulkan). GPU selection at runtime.
+
+## Generation as the Primitive
+
+The core architectural decision: generation is the primitive, not the API call. Agents are not processes that exchange messages. They are branches of a running inference process — forked from shared KV cache state, generating independently, their outputs comparable because they share a computational origin.
+
+This is built on [lloyal.node](https://github.com/lloyal-ai/lloyal.node), which provides forkable decode state and continuous tree batching over llama.cpp. `lloyal-agents` adds structured concurrency, tool dispatch, and a three-phase tick loop that drives N branches through a single GPU forward pass per step.
+
+The public API surface:
+
+```typescript
+import {
+  initAgents, // bootstrap: session, store, event channel
+  generate, // single-branch grammar-constrained generation
+  diverge, // multi-branch perplexity selection
+  useAgentPool, // concurrent agents as an Effection resource
+  runAgents, // same, with automatic branch cleanup
+  withSharedRoot, // scoped shared KV prefix with guaranteed teardown
+  createToolkit, // tool registry from Tool[] → toolMap + toolsJson
+  Ctx,
+  Store,
+  Events, // Effection contexts — implicit dependency resolution
+} from "@lloyal-labs/lloyal-agents";
+```
+
+That is essentially the entire framework.
+
+### Bootstrap
+
+```typescript
+import { main, call } from "effection";
+import { createContext } from "@lloyal-labs/lloyal.node";
+import { initAgents } from "@lloyal-labs/lloyal-agents";
+
+main(function* () {
+  const ctx = yield* call(() =>
+    createContext({
+      modelPath: "model.gguf",
+      nCtx: 16384,
+      nSeqMax: 8,
+      typeK: "q4_0",
+      typeV: "q4_0",
+    }),
+  );
+
+  const { session, events } = yield* initAgents(ctx);
+  // Ctx, Store, Events now set — generate(), diverge(),
+  // useAgentPool() find them automatically.
+  // Session + context disposed on scope exit.
+});
+```
+
+## Shared Frontier
+
+When agents fork from a common branch, they inherit its KV cache — the full attention state up to the fork point. This boundary is the shared frontier: the last position where all agents had identical computational state.
+
+Everything before the frontier is shared context. Everything after is independent reasoning. The model doesn't need to be told what the other agents know — it already attended over the same prefix. Communication happened at prefill time, through the attention mechanism, with zero serialization overhead.
+
+```typescript
+yield *
+  withSharedRoot(
+    { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
+    function* (root, prefixLen) {
+      // root is a prefilled branch — system prompt already in KV cache.
+      // Every agent forked from root shares that prefix.
+      // KV saved = prefixLen × (agentCount - 1)
+      return yield* runAgents({
+        tasks: questions.map((q) => ({
+          systemPrompt: RESEARCH_PROMPT,
+          content: q,
+          tools: toolsJson,
+          parent: root,
+        })),
+        tools: toolMap,
+      });
+    },
+  );
+```
+
+`withSharedRoot` creates the prefix, passes it to the body, and guarantees cleanup via `try/finally` — the root branch cannot leak out of the block. Effection enforces the lifetime.
+
+## In-Loop Orchestration
+
+All active agents advance together in a three-phase tick loop:
+
+**PRODUCE.** Every generating agent calls `produceSync()` — synchronous sampling with no async gap between agents. This matters because it means the entire produce phase is a single uninterrupted pass over the active set.
+
+**COMMIT.** One `store.commit()` call packs all produced tokens into a single `llama_batch` and dispatches once. N branches, one GPU call. No per-agent decode overhead.
+
+**SETTLE.** Tool results that resolved during COMMIT are drained from a buffer. Each result is tokenized into a delta, budget-checked against a fresh `ContextPressure` snapshot, and batch-prefilled into the agent's branch. Grammar state resets. The agent transitions back to `generating`.
+
+```typescript
+// From the tick loop — Phase 1
+const entries: [Branch, number][] = [];
+for (const a of agents) {
+  if (a.state !== "generating") continue;
+  if (pressure.critical) {
+    a.state = "done";
+    continue;
+  }
+
+  const { token, text, isStop } = a.branch.produceSync();
+  if (isStop) {
+    /* parse tool calls, dispatch or finalize */ continue;
+  }
+  entries.push([a.branch, token]);
+}
+
+// Phase 2 — single GPU dispatch
+if (entries.length > 0) {
+  yield * call(() => store.commit(entries));
+}
+```
+
+When no agent is generating and tools are still pending, the loop parks itself via `action()` — an Effection primitive that suspends the generator until a tool resolves and calls `wakeIdle()`. No polling. No sleep loops.
+
+## Structured Concurrency DAG
+
+Agent lifecycles are managed by [Effection](https://github.com/thefrontside/effection), a structured concurrency library for JavaScript. This is not optional sugar — it is load-bearing infrastructure. It is what makes recursive agents possible.
+
+Every branch registers an `ensure()` callback at fork time:
+
+```typescript
+function* setupAgent(parent, task, ctx) {
+  const branch = parent.forkSync();
+  yield* ensure(() => {
+    if (!branch.disposed) branch.pruneSync();
+  });
+  // ...
+}
+```
+
+If the scope exits — error, cancellation, normal completion — the branch is pruned. Orphaned branches are structurally impossible. Tool dispatch uses `scope.run()` for eager start inside the agent pool scope; if the scope tears down, pending tools are cancelled. The DAG is not imposed on the orchestration. It is intrinsic to the Effection task tree.
+
+`useAgentPool` is an Effection `resource()` — it suspends via `provide()` after all agents complete, but keeps their branches alive. The caller can fork sub-agents from any completed agent's branch. Those sub-agents inherit the parent agent's full KV state — everything it generated, every tool result it consumed, every reasoning step it took. No summarization. No context window management. The sub-agent continues from the parent's frontier.
+
+The deep-research harness ships a concrete example: `reportPass`. Research agents run through the tick loop with tools — search, grep, read_file, report. Some agents get hard-cut by context pressure before they can submit findings. Rather than losing their work, the harness forks a sub-agent from each hard-cut agent's branch with a constrained tool set (report only):
+
+```typescript
+function* reportPass(pool: AgentPoolResult, opts: WorkflowOpts) {
+  const hardCut = pool.agents.filter((a) => !a.findings && !a.branch.disposed);
+  if (hardCut.length === 0) return;
+
+  const reporters = yield* runAgents({
+    tasks: hardCut.map((a) => ({
+      systemPrompt: REPORT_PROMPT,
+      content: "Report your findings.",
+      tools: reportOnlyTools,
+      parent: a.branch, // fork from the parent agent's branch
+    })),
+    tools: new Map([["report", reportTool]]),
+    terminalTool: "report",
+  });
+
+  hardCut.forEach((a, i) => {
+    if (reporters.agents[i]?.findings)
+      a.findings = reporters.agents[i].findings;
+  });
+}
+```
+
+The sub-agent sees everything the parent saw — its system prompt, its tool calls, its partial reasoning — because that state is already in the KV cache at the fork point. The sub-agent just continues from where the parent was cut off, with a tighter mandate.
+
+This is the DAG in practice: parent agents form the first level, reporter sub-agents form the second. `runAgents` wraps `useAgentPool` in `scoped()`, so the reporter branches are pruned when it returns. The parent branches are still alive in the outer scope. When that outer scope exits, every `ensure()` callback fires and prunes the parents. Teardown propagates top-down. Cleanup is guaranteed bottom-up.
+
+There is nothing in the framework that limits this to two levels. Agents can spawn sub-agents that spawn sub-agents. An agent pool can run inside another agent pool's scope. The structured concurrency guarantees compose at every depth.
+
+## Hallucination Detection
+
+The framework provides hallucination detection at two levels.
+
+**Per-token observables.** Every branch exposes runtime-accessible signals on every step: `branch.modelEntropy()` (Shannon entropy of the full vocabulary distribution), `branch.modelSurprisal(token)` (surprisal of the chosen token: -log2(p)), `branch.perplexity` (model-level, from raw logits), and `branch.samplingPerplexity` (sampling-level, from the filtered distribution). The delta between model and sampling perplexity is itself a hallucination indicator — high sampling perplexity relative to model perplexity means the sampler is working against the model's probability mass.
+
+Enable `trace: true` on agent pools to capture entropy and surprisal on every `agent:produce` event.
+
+**Multi-branch semantic comparison.** `diverge()` forks N branches from a shared frontier, generates independently, and returns all outputs with their perplexity scores:
+
+```typescript
+const result =
+  yield *
+  diverge({
+    parent: root, // shared frontier
+    attempts: 3, // fork 3 branches
+    params: { temperature: 0.7 },
+  });
+// result.best — lowest-perplexity branch, still alive
+// result.attempts — all branches with output, ppl, token count
+// Losers already pruned. Winner's branch is caller's responsibility.
+```
+
+The harness decides how to compare. The deep-research example measures semantic equivalence across diverge outputs using bigram Jaccard similarity — where branches agree, the model is confident; where they diverge, hallucination risk is high. No model call required for the comparison itself. Other harnesses can use different equivalence measures over the same `diverge()` primitive.
+
+This directly operationalizes the semantic entropy work from Farquhar et al. ([Nature, 2024](https://www.nature.com/articles/s41586-024-07421-0)) — but as a runtime primitive, not a post-hoc metric. The key constraint: divergence from a common computational ancestor is signal. Divergence from independently-constructed contexts is sampling variance. This measurement is only meaningful because agents share a frontier.
+
+## Session Accumulation
+
+When agents converge — when the entropy gate passes — the winning branch is not returned as output. It is promoted. It becomes the new trunk of the session. The next query starts from ground that was computationally earned by the previous convergence check.
+
+This is the cold/warm session distinction. A cold query runs the full pipeline: plan the decomposition, dispatch research agents, synthesize via `diverge`, evaluate convergence, promote. A warm query — one where a trusted trunk already exists — skips verification entirely. The frontier is already established. Agents fork from it, research, and the session responds directly from findings.
+
+Each promote is an epistemic commitment: this branch survived N-way comparison and convergence evaluation, so it becomes the basis for future reasoning. The session doesn't just carry forward text — it carries forward the KV state of a branch that survived verification. Future agents fork from this state. Their shared frontier is not an empty system prompt. It is the accumulated, verified reasoning of every previous cycle.
+
+Over multiple queries, the session compounds. Early queries establish the foundation. Later queries branch from it, research further, verify further, promote further. The trunk grows. The frontier advances. The model's effective context is not what you put in the prompt — it is what was earned by convergence.
+
+## Context Pressure
+
+KV cache is finite. `ContextPressure` snapshots the remaining budget on every tick and enforces two thresholds:
+
+- **softLimit** (default 1024 tokens remaining): SETTLE rejects tool results that would cross this floor. PRODUCE hard-cuts agents requesting non-terminal tool calls. Terminal tools (e.g. `report`) still pass — agents can always submit findings. INIT drops agents that don't fit above this floor.
+- **hardLimit** (default 128 tokens remaining): agents killed immediately before `produceSync()`. No decode call is made below this line — it would crash.
+
+Tool result prefill in the SETTLE phase is budget-gated against a fresh pressure snapshot. If a tool result doesn't fit, the agent is terminated rather than risking a context overflow mid-generation. The softLimit reserves space for downstream work — reporter sub-agents, verification passes.
+
+```typescript
+yield *
+  useAgentPool({
+    tasks,
+    tools: toolMap,
+    terminalTool: "report",
+    pressure: { softLimit: 2048 }, // reserve 2K for reporters + verify
+  });
+```
+
+## Tools
+
+Tools are class-based with OpenAI-compatible function schemas:
+
+```typescript
+import { Tool } from "@lloyal-labs/lloyal-agents";
+import type { ToolContext } from "@lloyal-labs/lloyal-agents";
+
+class SearchTool extends Tool<{ query: string }> {
+  readonly name = "search";
+  readonly description = "Semantic search over the corpus";
+  readonly parameters = {
+    type: "object",
+    properties: { query: { type: "string", description: "Search query" } },
+    required: ["query"],
+  };
+
+  async execute(args: { query: string }, context?: ToolContext) {
+    const results = await this.reranker.rank(args.query, this.chunks);
+    context?.onProgress?.({
+      filled: results.length,
+      total: this.chunks.length,
+    });
+    return results.slice(0, 10);
+  }
+}
+```
+
+`createToolkit(tools)` aggregates tools into a `{ toolMap, toolsJson }` pair — `toolMap` for runtime dispatch, `toolsJson` for prompt formatting.
+
+## Events
+
+The runtime emits structured events for TUI, logging, or telemetry:
+
+| Event                 | Payload                                                   |
+| --------------------- | --------------------------------------------------------- |
+| `agent:spawn`         | `agentId`, `parentAgentId`                                |
+| `agent:produce`       | `agentId`, `text`, `tokenCount`, `entropy?`, `surprisal?` |
+| `agent:tool_call`     | `agentId`, `tool`, `args`                                 |
+| `agent:tool_result`   | `agentId`, `tool`, `result`                               |
+| `agent:tool_progress` | `agentId`, `tool`, `filled`, `total`                      |
+| `agent:report`        | `agentId`, `findings`                                     |
+| `agent:done`          | `agentId`                                                 |
+
+## License
+
+Apache-2.0

package/dist/Tool.d.ts

@@ -0,0 +1,65 @@
+import type { JsonSchema, ToolSchema, ToolContext } from './types';
+/**
+ * Abstract base class for tools usable by agents in the runtime
+ *
+ * Subclass to define tools that agents can invoke during generation.
+ * Implement `name`, `description`, `parameters`, and `execute()`. The
+ * {@link schema} getter auto-generates the OpenAI-compatible function
+ * schema expected by `formatChat()`.
+ *
+ * Pass tool instances to {@link createToolkit} to build the `toolMap`
+ * and `toolsJson` pair consumed by {@link useAgentPool} and
+ * {@link runAgents}.
+ *
+ * @example Search tool
+ * ```typescript
+ * class SearchTool extends Tool<{ query: string; topK?: number }> {
+ *   readonly name = 'search';
+ *   readonly description = 'Search the corpus for relevant passages';
+ *   readonly parameters = {
+ *     type: 'object',
+ *     properties: {
+ *       query: { type: 'string', description: 'Search query' },
+ *       topK: { type: 'number', description: 'Number of results' },
+ *     },
+ *     required: ['query'],
+ *   };
+ *
+ *   async execute(args: { query: string; topK?: number }, ctx?: ToolContext) {
+ *     const results = await this.reranker.rank(args.query, args.topK ?? 5);
+ *     return { results };
+ *   }
+ * }
+ * ```
+ *
+ * @category Agents
+ */
+export declare abstract class Tool<TArgs = Record<string, unknown>> {
+    /** Tool name — used as the function identifier in tool calls */
+    abstract readonly name: string;
+    /** Human-readable description shown to the model */
+    abstract readonly description: string;
+    /** JSON Schema describing the tool's expected arguments */
+    abstract readonly parameters: JsonSchema;
+    /**
+     * Execute the tool with parsed arguments
+     *
+     * Called by the agent pool when the model emits a tool call matching
+     * this tool's name. The return value is JSON-serialized and prefilled
+     * back into the agent's context as a tool result.
+     *
+     * @param args - Parsed arguments from the model's tool call
+     * @param context - Execution context with progress reporting callback
+     * @returns Tool result (will be JSON-serialized)
+     */
+    abstract execute(args: TArgs, context?: ToolContext): Promise<unknown>;
+    /**
+     * OpenAI-compatible function tool schema
+     *
+     * Auto-generated from `name`, `description`, and `parameters`.
+     * Used by {@link createToolkit} to build the JSON string passed
+     * to `formatChat()`.
+     */
+    get schema(): ToolSchema;
+}
+//# sourceMappingURL=Tool.d.ts.map

package/dist/Tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../src/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8BAAsB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IACtC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAEtE;;;;;;OAMG;IACH,IAAI,MAAM,IAAI,UAAU,CASvB;CACF"}

package/dist/Tool.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = void 0;
+/**
+ * Abstract base class for tools usable by agents in the runtime
+ *
+ * Subclass to define tools that agents can invoke during generation.
+ * Implement `name`, `description`, `parameters`, and `execute()`. The
+ * {@link schema} getter auto-generates the OpenAI-compatible function
+ * schema expected by `formatChat()`.
+ *
+ * Pass tool instances to {@link createToolkit} to build the `toolMap`
+ * and `toolsJson` pair consumed by {@link useAgentPool} and
+ * {@link runAgents}.
+ *
+ * @example Search tool
+ * ```typescript
+ * class SearchTool extends Tool<{ query: string; topK?: number }> {
+ *   readonly name = 'search';
+ *   readonly description = 'Search the corpus for relevant passages';
+ *   readonly parameters = {
+ *     type: 'object',
+ *     properties: {
+ *       query: { type: 'string', description: 'Search query' },
+ *       topK: { type: 'number', description: 'Number of results' },
+ *     },
+ *     required: ['query'],
+ *   };
+ *
+ *   async execute(args: { query: string; topK?: number }, ctx?: ToolContext) {
+ *     const results = await this.reranker.rank(args.query, args.topK ?? 5);
+ *     return { results };
+ *   }
+ * }
+ * ```
+ *
+ * @category Agents
+ */
+class Tool {
+    /**
+     * OpenAI-compatible function tool schema
+     *
+     * Auto-generated from `name`, `description`, and `parameters`.
+     * Used by {@link createToolkit} to build the JSON string passed
+     * to `formatChat()`.
+     */
+    get schema() {
+        return {
+            type: 'function',
+            function: {
+                name: this.name,
+                description: this.description,
+                parameters: this.parameters,
+            },
+        };
+    }
+}
+exports.Tool = Tool;
+//# sourceMappingURL=Tool.js.map

package/dist/Tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../src/Tool.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAsB,IAAI;IAqBxB;;;;;;OAMG;IACH,IAAI,MAAM;QACR,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B;SACF,CAAC;IACJ,CAAC;CACF;AAtCD,oBAsCC"}

package/dist/agent-pool.d.ts

@@ -0,0 +1,114 @@
+import type { Operation } from 'effection';
+import { type SessionContext } from '@lloyal-labs/sdk';
+import type { PressureThresholds, AgentPoolOptions, AgentPoolResult } from './types';
+/**
+ * Immutable KV budget snapshot for one tick of the agent loop
+ *
+ * Created from `SessionContext._storeKvPressure()` which returns
+ * `{ nCtx, cellsUsed, remaining }` where `remaining = nCtx - cellsUsed`.
+ * `cellsUsed` is a monotonic counter in `BranchStore` — it increments on
+ * every `decode_each` / `decode_scatter` but does **not** decrement on
+ * individual branch prune (only resets on bulk ops like `retainOnly` and
+ * `drain`). This means `remaining` is a conservative lower bound that
+ * becomes increasingly pessimistic as branches are pruned mid-run.
+ *
+ * Two thresholds partition `remaining` into three zones:
+ *
+ * ```
+ * ┌──────────────────────────────────────────────────────┐
+ * │                    nCtx                              │
+ * │  ┌──────────┬───────────────────┬──────────────────┐ │
+ * │  │cellsUsed │    headroom > 0   │    softLimit     │ │
+ * │  │ (in use) │   (new work OK)   │   (reserved)     │ │
+ * │  └──────────┴───────────────────┴──────────────────┘ │
+ * │              ◄── remaining ──►  │                    │
+ * │                                 │                    │
+ * │  headroom = remaining - softLimit                    │
+ * │  critical = remaining < hardLimit                    │
+ * └──────────────────────────────────────────────────────┘
+ * ```
+ *
+ * - **headroom > 0** — room for new work (tool results, generation)
+ * - **headroom ≤ 0** — over budget. SETTLE rejects tool results, PRODUCE
+ *   hard-cuts non-terminal tool calls. Terminal tools still pass.
+ * - **critical** — remaining below hardLimit. Agents killed before
+ *   `produceSync()` to prevent llama_decode crashes.
+ *
+ * @category Agents
+ */
+export declare class ContextPressure {
+    /** Default softLimit: 1024 tokens reserved for downstream work */
+    static readonly DEFAULT_SOFT_LIMIT = 1024;
+    /** Default hardLimit: 128 tokens crash-prevention floor */
+    static readonly DEFAULT_HARD_LIMIT = 128;
+    /**
+     * KV slots remaining (`nCtx - cellsUsed`).
+     * Infinity when nCtx ≤ 0 (no context limit).
+     * Conservative: may undercount actual free space when branches have been
+     * pruned, since `cellsUsed` is monotonic.
+     */
+    readonly remaining: number;
+    /** Remaining KV floor — tokens reserved for downstream work */
+    readonly softLimit: number;
+    /** Crash-prevention floor — agents killed when remaining drops below */
+    readonly hardLimit: number;
+    constructor(ctx: SessionContext, opts?: PressureThresholds);
+    /**
+     * Tokens available for new work: `remaining - softLimit`.
+     * Positive means room to accept tool results or continue generating.
+     * Negative means over budget — SETTLE rejects, PRODUCE hard-cuts.
+     */
+    get headroom(): number;
+    /** `remaining < hardLimit` — agent must not call `produceSync()`. */
+    get critical(): boolean;
+    /** Can `tokenCount` tokens fit while staying above softLimit? */
+    canFit(tokenCount: number): boolean;
+}
+/**
+ * Concurrent agent generation loop as an Effection resource
+ *
+ * Runs N agents in parallel using a three-phase tick loop over shared
+ * {@link BranchStore} infrastructure. Each agent forks from a parent
+ * branch, generates tokens, invokes tools, and reports findings.
+ *
+ * **Three-phase tick loop:**
+ * 1. **PRODUCE** — sample all active agents via `produceSync()` (no async gap)
+ * 2. **COMMIT** — single GPU call via `store.commit()` for all produced tokens
+ * 3. **SETTLE** — drain settled tool results, batch prefill, reset grammars
+ *
+ * Tool dispatch uses `scope.run()` for eager start — tool executions run as
+ * children of the agent pool scope and are cancelled if the scope exits.
+ *
+ * **Resource semantics:** `provide()` suspends after all agents complete,
+ * keeping branches alive so the caller can fork from them (e.g. for
+ * verification). Branches are pruned when the scope exits — each branch's
+ * `ensure()` from `setupAgent` handles cleanup automatically.
+ *
+ * For automatic branch cleanup on return, use {@link runAgents} instead.
+ *
+ * @param opts - Pool configuration: tasks, tools, sampling params, max turns
+ * @returns Agent pool result with per-agent findings and aggregate statistics
+ *
+ * @example Shared root with agent pool
+ * ```typescript
+ * const pool = yield* withSharedRoot(
+ *   { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
+ *   function*(root) {
+ *     return yield* useAgentPool({
+ *       tasks: questions.map(q => ({
+ *         systemPrompt: RESEARCH_PROMPT,
+ *         content: q,
+ *         tools: toolsJson,
+ *         parent: root,
+ *       })),
+ *       tools: toolMap,
+ *       maxTurns: 6,
+ *     });
+ *   },
+ * );
+ * ```
+ *
+ * @category Agents
+ */
+export declare function useAgentPool(opts: AgentPoolOptions): Operation<AgentPoolResult>;
+//# sourceMappingURL=agent-pool.d.ts.map

package/dist/agent-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-pool.d.ts","sourceRoot":"","sources":["../src/agent-pool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,WAAW,CAAC;AAE3D,OAAO,EAA+G,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIpK,OAAO,KAAK,EAEV,kBAAkB,EAElB,gBAAgB,EAChB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAqCjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,eAAe;IAC1B,kEAAkE;IAClE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,QAAQ;IAC1C,2DAA2D;IAC3D,MAAM,CAAC,QAAQ,CAAC,kBAAkB,OAAO;IAEzC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,kBAAkB;IAO1D;;;;OAIG;IACH,IAAI,QAAQ,IAAI,MAAM,CAA4C;IAElE,qEAAqE;IACrE,IAAI,QAAQ,IAAI,OAAO,CAA4C;IAEnE,iEAAiE;IACjE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;CACpC;AAwDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC,eAAe,CAAC,CAwW/E"}