@lloyal-labs/lloyal-agents 1.5.8 → 2.0.0

package/dist/use-agent.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAgent = useAgent;
+exports.agent = agent;
+const effection_1 = require("effection");
+const sdk_1 = require("@lloyal-labs/sdk");
+const context_1 = require("./context");
+const agent_pool_1 = require("./agent-pool");
+const toolkit_1 = require("./toolkit");
+const trace_scope_1 = require("./trace-scope");
+const orchestrators_1 = require("./orchestrators");
+/**
+ * Single-agent resource — delegates to {@link useAgentPool} N=1.
+ *
+ * One path. No conditional. Tools optional — `useAgentPool` with no tools
+ * degenerates cleanly (tick loop: produce → commit → stop, no dispatch).
+ *
+ * Provides a completed Agent with branches alive. The resource keeps the
+ * root and agent branch alive until the caller's scope exits — caller can
+ * fork from the Agent's branch for verification or follow-up.
+ *
+ * Root managed via `ensure()` (not `withSharedRoot`) because the resource
+ * lifetime requires the root alive until the caller's scope exits.
+ *
+ * Events stream passively to the broadcast Channel during the inline drain.
+ *
+ * @param opts - Agent configuration
+ * @returns Agent with result populated, branches alive
+ *
+ * @example Single agent with tools
+ * ```typescript
+ * const agent = yield* useAgent({
+ *   systemPrompt: "You are a research assistant.",
+ *   task: "Find information about X",
+ *   tools: [searchTool, reportTool],
+ *   terminalTool: 'report',
+ * });
+ * // agent.result — findings
+ * // agent.branch — alive, can fork from
+ * ```
+ *
+ * @category Agents
+ */
+function useAgent(opts) {
+    return (0, effection_1.resource)(function* (provide) {
+        const ctx = yield* context_1.Ctx.expect();
+        const broadcast = yield* context_1.Events.expect();
+        const tw = yield* context_1.Trace.expect();
+        const toolkit = (0, toolkit_1.createToolkit)(opts.tools ?? []);
+        const warmParent = opts.parent ?? opts.session?.trunk ?? undefined;
+        const scope = (0, trace_scope_1.traceScope)(tw, null, 'useAgent', {
+            hasTools: !!(opts.tools?.length),
+            hasParent: !!warmParent,
+        });
+        // Create root — ensure() for resource lifetime (not withSharedRoot's try/finally).
+        // The root carries no chat context; the agent's suffix (formatted fresh in
+        // setupAgent) is the agent's full chat. Warm path prefills a turn separator
+        // so the suffix lands on a clean turn boundary.
+        const root = warmParent
+            ? warmParent.forkSync()
+            : sdk_1.Branch.create(ctx, 0, opts.params ?? { temperature: 0.5 });
+        yield* (0, effection_1.ensure)(() => { if (!root.disposed)
+            root.pruneSubtreeSync(); });
+        const prefillTokens = warmParent ? ctx.getTurnSeparator() : [];
+        if (prefillTokens.length > 0) {
+            yield* (0, effection_1.call)(() => root.prefill(prefillTokens));
+        }
+        // Eager grammar from schema — set on root before fork.
+        // Fork inherits grammar state. formatChatSync returns no grammar for
+        // no-tools case, so applyLazyGrammar is a no-op and the inherited
+        // eager grammar persists on the forked agent branch.
+        if (opts.schema) {
+            const grammar = yield* (0, effection_1.call)(() => ctx.jsonSchemaToGrammar(JSON.stringify(opts.schema)));
+            root.setGrammar(grammar);
+        }
+        // Delegate to useAgentPool N=1 via a trivial parallel orchestrator
+        const hasTools = !!(opts.tools?.length);
+        const sub = yield* (0, agent_pool_1.useAgentPool)({
+            root,
+            orchestrate: (0, orchestrators_1.parallel)([{ content: opts.task, systemPrompt: opts.systemPrompt }]),
+            toolsJson: hasTools ? toolkit.toolsJson : '',
+            tools: toolkit.toolMap,
+            terminalTool: opts.terminalTool,
+            maxTurns: opts.maxTurns,
+            policy: opts.policy,
+            trace: opts.trace,
+        });
+        // Drain Subscription inline — forward to broadcast
+        let next = yield* sub.next();
+        while (!next.done) {
+            yield* broadcast.send(next.value);
+            next = yield* sub.next();
+        }
+        const pool = next.value;
+        scope.close();
+        yield* provide(pool.agents[0].agent);
+        // Resource stays alive — branch alive for caller to fork from
+        // ensure() prunes root on scope exit
+    });
+}
+/**
+ * Single-agent scoped operation — wraps {@link useAgent} in `scoped()`.
+ *
+ * Returns completed Agent with result populated. Branches pruned on scope exit.
+ * This is the harness-level API for single-agent steps (plan, eval, bridge).
+ *
+ * @param opts - Agent configuration (same as {@link UseAgentOpts})
+ * @returns Completed Agent with `.result`, `.rawOutput`, `.tokenCount`
+ *
+ * @example Plan step
+ * ```typescript
+ * const a = yield* agent({
+ *   systemPrompt: PLAN.system,
+ *   task: query,
+ *   schema: planSchema,
+ * });
+ * const plan = JSON.parse(a.rawOutput);
+ * ```
+ *
+ * @category Agents
+ */
+function* agent(opts) {
+    return yield* (0, effection_1.scoped)(function* () {
+        return yield* useAgent(opts);
+    });
+}
+//# sourceMappingURL=use-agent.js.map

package/dist/use-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-agent.js","sourceRoot":"","sources":["../src/use-agent.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lloyal-labs/lloyal-agents",
-  "version": "1.5.8",
+  "version": "2.0.0",
   "description": "Multi-agent inference inside the decode loop — structured concurrency over shared KV state",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,12 +9,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lloyal-ai/sdk.git",
+    "url": "git+https://github.com/lloyal-ai/hdk.git",
     "directory": "packages/agents"
   },
-  "homepage": "https://github.com/lloyal-ai/sdk/tree/main/packages/agents#readme",
+  "homepage": "https://github.com/lloyal-ai/hdk/tree/main/packages/agents#readme",
   "bugs": {
-    "url": "https://github.com/lloyal-ai/sdk/issues"
+    "url": "https://github.com/lloyal-ai/hdk/issues"
   },
   "keywords": [
     "llm",
@@ -31,7 +31,7 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@lloyal-labs/sdk": "^1.5.8",
+    "@lloyal-labs/sdk": "^2.0.0",
     "effection": "^4.0.2",
     "eta": "^4.5.1"
   },

package/dist/generate.d.ts

@@ -1,77 +0,0 @@
-import type { Operation } from 'effection';
-import { Branch } from '@lloyal-labs/sdk';
-import type { GenerateOptions, GenerateResult } from './types';
-/**
- * Prepare a branch for generation — create/fork, set grammar, prefill prompt
- *
- * Returns the prepared Branch ready for token production. The caller owns the
- * branch and decides how to consume it:
- *
- * - **Manual loop** — call `produceSync()` / `commit()` for per-token control,
- *   streaming UI updates, or integration into a batched tick loop
- * - **Async iterator** — `for await (const { text } of branch)` for convenience
- * - **Pass to `generate()`** — which calls `prepare()` internally
- *
- * The caller is responsible for pruning the branch when done.
- *
- * When `parent` is provided, forks from it and prefills the prompt as a delta
- * (with turn separator). Otherwise creates a fresh root branch.
- *
- * @param opts - Generation options (prompt, grammar, params, parent)
- * @returns Prepared Branch with prompt prefilled, ready for produce/commit
- *
- * @example Stream tokens to UI
- * ```typescript
- * const branch = yield* prepare({ prompt, grammar });
- * try {
- *   let output = '';
- *   while (true) {
- *     const { token, text, isStop } = branch.produceSync();
- *     if (isStop) break;
- *     yield* call(() => branch.commit(token));
- *     output += text;
- *     updateUI(text);  // per-token streaming
- *   }
- * } finally {
- *   if (!branch.disposed) branch.pruneSync();
- * }
- * ```
- *
- * @example Batch multiple prepared branches
- * ```typescript
- * const branches = [];
- * for (const task of tasks) {
- *   branches.push(yield* prepare({ prompt: task.prompt, grammar, parent: root }));
- * }
- * // Caller batches via BranchStore.commit() for continuous tree batching
- * ```
- *
- * @category Agents
- */
-export declare function prepare(opts: GenerateOptions): Operation<Branch>;
-/**
- * Single-branch grammar-constrained generation as an Effection operation
- *
- * Convenience wrapper over {@link prepare} — creates/forks a branch, prefills
- * the prompt, generates to EOG, parses the output, and prunes the branch.
- *
- * For per-token streaming or batched generation, use {@link prepare} directly
- * and run your own produce/commit loop.
- *
- * @param opts - Generation options (prompt, grammar, params, parse, parent)
- * @returns Generated text, token count, and optionally parsed result
- *
- * @example Grammar-constrained JSON generation
- * ```typescript
- * const plan = yield* generate({
- *   prompt: planPrompt,
- *   grammar: planGrammar,
- *   params: { temperature: 0.3 },
- *   parse: output => JSON.parse(output),
- * });
- * ```
- *
- * @category Agents
- */
-export declare function generate<T = unknown>(opts: GenerateOptions): Operation<GenerateResult<T>>;
-//# sourceMappingURL=generate.d.ts.map

package/dist/generate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAiB,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC,CAiDjE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAiB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA2C1F"}

package/dist/generate.js

@@ -1,166 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.prepare = prepare;
-exports.generate = generate;
-const effection_1 = require("effection");
-const sdk_1 = require("@lloyal-labs/sdk");
-const context_1 = require("./context");
-const trace_scope_1 = require("./trace-scope");
-/**
- * Prepare a branch for generation — create/fork, set grammar, prefill prompt
- *
- * Returns the prepared Branch ready for token production. The caller owns the
- * branch and decides how to consume it:
- *
- * - **Manual loop** — call `produceSync()` / `commit()` for per-token control,
- *   streaming UI updates, or integration into a batched tick loop
- * - **Async iterator** — `for await (const { text } of branch)` for convenience
- * - **Pass to `generate()`** — which calls `prepare()` internally
- *
- * The caller is responsible for pruning the branch when done.
- *
- * When `parent` is provided, forks from it and prefills the prompt as a delta
- * (with turn separator). Otherwise creates a fresh root branch.
- *
- * @param opts - Generation options (prompt, grammar, params, parent)
- * @returns Prepared Branch with prompt prefilled, ready for produce/commit
- *
- * @example Stream tokens to UI
- * ```typescript
- * const branch = yield* prepare({ prompt, grammar });
- * try {
- *   let output = '';
- *   while (true) {
- *     const { token, text, isStop } = branch.produceSync();
- *     if (isStop) break;
- *     yield* call(() => branch.commit(token));
- *     output += text;
- *     updateUI(text);  // per-token streaming
- *   }
- * } finally {
- *   if (!branch.disposed) branch.pruneSync();
- * }
- * ```
- *
- * @example Batch multiple prepared branches
- * ```typescript
- * const branches = [];
- * for (const task of tasks) {
- *   branches.push(yield* prepare({ prompt: task.prompt, grammar, parent: root }));
- * }
- * // Caller batches via BranchStore.commit() for continuous tree batching
- * ```
- *
- * @category Agents
- */
-function* prepare(opts) {
-    const ctx = yield* context_1.Ctx.expect();
-    const tw = yield* context_1.Trace.expect();
-    const samplerParams = opts.params ?? {};
-    const hasParent = !!opts.parent;
-    const scope = (0, trace_scope_1.traceScope)(tw, null, 'prepare', { role: hasParent ? 'scratchpad' : 'root', hasGrammar: !!opts.grammar });
-    let branch;
-    if (opts.parent) {
-        branch = yield* (0, effection_1.call)(() => opts.parent.fork());
-    }
-    else {
-        branch = sdk_1.Branch.create(ctx, 0, samplerParams, undefined, opts.grammar);
-    }
-    tw.write({
-        traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
-        type: 'branch:create', branchHandle: branch.handle,
-        parentHandle: opts.parent?.handle ?? null,
-        position: 0, role: hasParent ? 'scratchpad' : 'root',
-    });
-    let prefillCount;
-    if (opts.parent) {
-        if (opts.grammar)
-            branch.setGrammar(opts.grammar);
-        const sep = ctx.getTurnSeparator();
-        const delta = yield* (0, effection_1.call)(() => ctx.tokenize(opts.prompt, false));
-        const tokens = [...sep, ...delta];
-        prefillCount = tokens.length;
-        yield* (0, effection_1.call)(() => branch.prefill(tokens));
-    }
-    else {
-        const tokens = ctx.tokenizeSync(opts.prompt);
-        prefillCount = tokens.length;
-        yield* (0, effection_1.call)(() => branch.prefill(tokens));
-    }
-    tw.write({
-        traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
-        type: 'prompt:format', promptText: opts.prompt, tokenCount: prefillCount,
-        messages: '', role: 'generate', grammar: opts.grammar,
-    });
-    tw.write({
-        traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
-        type: 'branch:prefill', branchHandle: branch.handle, tokenCount: prefillCount,
-        role: hasParent ? 'scratchpad' : 'sharedPrefix',
-    });
-    scope.close();
-    return branch;
-}
-/**
- * Single-branch grammar-constrained generation as an Effection operation
- *
- * Convenience wrapper over {@link prepare} — creates/forks a branch, prefills
- * the prompt, generates to EOG, parses the output, and prunes the branch.
- *
- * For per-token streaming or batched generation, use {@link prepare} directly
- * and run your own produce/commit loop.
- *
- * @param opts - Generation options (prompt, grammar, params, parse, parent)
- * @returns Generated text, token count, and optionally parsed result
- *
- * @example Grammar-constrained JSON generation
- * ```typescript
- * const plan = yield* generate({
- *   prompt: planPrompt,
- *   grammar: planGrammar,
- *   params: { temperature: 0.3 },
- *   parse: output => JSON.parse(output),
- * });
- * ```
- *
- * @category Agents
- */
-function* generate(opts) {
-    const tw = yield* context_1.Trace.expect();
-    const scope = (0, trace_scope_1.traceScope)(tw, null, 'generate', { hasGrammar: !!opts.grammar, hasParent: !!opts.parent });
-    const branch = yield* prepare(opts);
-    tw.write({
-        traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
-        type: 'generate:start', branchHandle: branch.handle,
-        hasGrammar: !!opts.grammar, hasParent: !!opts.parent,
-        role: opts.parent ? 'scratchpad' : 'root',
-    });
-    try {
-        const { output, tokenCount } = yield* (0, effection_1.call)(async () => {
-            let output = '';
-            let tokenCount = 0;
-            for await (const { text } of branch) {
-                output += text;
-                tokenCount++;
-            }
-            return { output, tokenCount };
-        });
-        const parsed = opts.parse ? opts.parse(output) : undefined;
-        tw.write({
-            traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
-            type: 'generate:end', branchHandle: branch.handle, tokenCount, output,
-            parsed: parsed !== undefined ? parsed : undefined,
-        });
-        return { output, tokenCount, parsed };
-    }
-    finally {
-        if (!branch.disposed) {
-            tw.write({
-                traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
-                type: 'branch:prune', branchHandle: branch.handle, position: 0,
-            });
-            branch.pruneSync();
-        }
-        scope.close();
-    }
-}
-//# sourceMappingURL=generate.js.map

package/dist/generate.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate.js","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"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"}

package/dist/run-agents.d.ts

@@ -1,39 +0,0 @@
-import type { Operation } from 'effection';
-import type { AgentPoolOptions, AgentPoolResult } from './types';
-/**
- * Run an agent pool with automatic branch cleanup on return
- *
- * Wraps {@link useAgentPool} in `scoped()` — agent branches are pruned
- * when the scope exits, before this operation returns. Use this when you
- * don't need to fork from agent branches after the pool completes.
- *
- * For multi-level tree topology (forking from agent branches for
- * verification or follow-up), use {@link useAgentPool} directly within
- * your own scope management.
- *
- * @param opts - Pool configuration: tasks, tools, sampling params, max turns
- * @returns Agent pool result (branches already pruned)
- *
- * @example Research agents with shared root
- * ```typescript
- * const pool = yield* withSharedRoot(
- *   { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
- *   function*(root, prefixLen) {
- *     return yield* runAgents({
- *       tasks: questions.map(q => ({
- *         systemPrompt: RESEARCH_PROMPT,
- *         content: q,
- *         tools: toolsJson,
- *         parent: root,
- *       })),
- *       tools: toolMap,
- *       maxTurns: 6,
- *     });
- *   },
- * );
- * ```
- *
- * @category Agents
- */
-export declare function runAgents(opts: AgentPoolOptions): Operation<AgentPoolResult>;
-//# sourceMappingURL=run-agents.d.ts.map

package/dist/run-agents.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-agents.d.ts","sourceRoot":"","sources":["../src/run-agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAiB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC,eAAe,CAAC,CAI7E"}

package/dist/run-agents.js

@@ -1,46 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runAgents = runAgents;
-const effection_1 = require("effection");
-const agent_pool_1 = require("./agent-pool");
-/**
- * Run an agent pool with automatic branch cleanup on return
- *
- * Wraps {@link useAgentPool} in `scoped()` — agent branches are pruned
- * when the scope exits, before this operation returns. Use this when you
- * don't need to fork from agent branches after the pool completes.
- *
- * For multi-level tree topology (forking from agent branches for
- * verification or follow-up), use {@link useAgentPool} directly within
- * your own scope management.
- *
- * @param opts - Pool configuration: tasks, tools, sampling params, max turns
- * @returns Agent pool result (branches already pruned)
- *
- * @example Research agents with shared root
- * ```typescript
- * const pool = yield* withSharedRoot(
- *   { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
- *   function*(root, prefixLen) {
- *     return yield* runAgents({
- *       tasks: questions.map(q => ({
- *         systemPrompt: RESEARCH_PROMPT,
- *         content: q,
- *         tools: toolsJson,
- *         parent: root,
- *       })),
- *       tools: toolMap,
- *       maxTurns: 6,
- *     });
- *   },
- * );
- * ```
- *
- * @category Agents
- */
-function* runAgents(opts) {
-    return yield* (0, effection_1.scoped)(function* () {
-        return yield* (0, agent_pool_1.useAgentPool)({ pruneOnReport: true, ...opts });
-    });
-}
-//# sourceMappingURL=run-agents.js.map

package/dist/run-agents.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-agents.js","sourceRoot":"","sources":["../src/run-agents.ts"],"names":[],"mappings":";;AAwCA,8BAIC;AA5CD,yCAAmC;AAEnC,6CAA4C;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,QAAe,CAAC,CAAC,SAAS,CAAC,IAAsB;IAC/C,OAAO,KAAK,CAAC,CAAC,IAAA,kBAAM,EAAC,QAAQ,CAAC;QAC5B,OAAO,KAAK,CAAC,CAAC,IAAA,yBAAY,EAAC,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/spawn-agents.d.ts

@@ -1,104 +0,0 @@
-import type { Operation } from 'effection';
-import type { Branch } from '@lloyal-labs/sdk';
-import { Tool } from './Tool';
-import type { JsonSchema } from './types';
-import type { AgentPoolResult } from './types';
-import type { AgentPolicy } from './AgentPolicy';
-import type { EntailmentScorer } from './source';
-/**
- * Configuration for the self-referential recursive tool.
- *
- * @category Agents
- */
-export interface RecursiveOpts {
-    /** Tool name agents see in their toolkit. @default "delegate" */
-    name?: string;
-    /** Tool description shown in the agent's tool schema. */
-    description?: string;
-    /**
-     * JSON schema for the recursive tool's arguments.
-     * @default `{ type: 'object', properties: { tasks: { type: 'array', items: { type: 'string' } } }, required: ['tasks'] }`
-     */
-    argsSchema?: JsonSchema;
-    /**
-     * Extract task strings from parsed tool arguments.
-     * @default `(args) => args.tasks as string[]`
-     */
-    extractTasks?: (args: Record<string, unknown>) => string[];
-}
-/**
- * Options for {@link spawnAgents}.
- *
- * @category Agents
- */
-export interface SpawnAgentsOpts {
-    /** Data access tools (from a Source or custom). */
-    tools: Tool[];
-    /** System prompt for spawned agents. */
-    systemPrompt: string;
-    /** One task per agent — content string for each. */
-    tasks: string[];
-    /** Terminal tool name + instance. Pool intercepts calls to this tool and extracts results. */
-    terminalTool?: {
-        name: string;
-        tool: Tool;
-    };
-    /** Max tool-use turns per agent before hard cut. @default 100 */
-    maxTurns?: number;
-    /**
-     * Enable self-referential recursion. When truthy, a wrapper tool is
-     * added to the toolkit that calls `spawnAgents()` recursively with
-     * the same config. Agents can delegate sub-tasks at arbitrary depth,
-     * bounded by KV pressure.
-     *
-     * Pass `true` for defaults, or an object to configure the tool's
-     * name, description, args schema, and task extraction.
-     */
-    recursive?: boolean | RecursiveOpts;
-    /** Prune agent branches immediately on report, freeing KV mid-pool. */
-    pruneOnReport?: boolean;
-    /** Custom agent policy. @default DefaultAgentPolicy */
-    policy?: AgentPolicy;
-    /** Enable structured trace events. */
-    trace?: boolean;
-    /** Parent branch for warm path (Continuous Context). Sub-agents inherit full attention state. */
-    parent?: Branch;
-    /** Entailment scorer for semantic coherence across recursive depths.
-     *  Created via {@link Source.createScorer}. Propagated to all inner pools. */
-    scorer?: EntailmentScorer;
-    /** Similarity threshold for echo detection. If all proposed sub-questions
-     *  score above this against the agent's own task, the delegation is rejected
-     *  as a paraphrase rather than a decomposition. @default 0.8 */
-    echoThreshold?: number;
-    /** When true, also check proposed questions against ancestor tasks via
-     *  walkAncestors(). Disabled by default to avoid false positives on
-     *  genuine narrowing. Enable after observing local echo check behaviour. */
-    checkAncestorEcho?: boolean;
-}
-/**
- * Spawn parallel agents with tools, optionally self-referential.
- *
- * Creates a shared root, forks one agent per task, runs the four-phase
- * tick loop, and returns results. When `recursive` is enabled, a
- * delegate tool is added to the toolkit that calls `spawnAgents()`
- * again — enabling agents to delegate sub-tasks at arbitrary depth.
- *
- * This is the general-purpose orchestration primitive. The harness
- * controls the prompt, tools, recursion shape, and policy. Sources
- * just provide data access tools.
- *
- * @example Research harness
- * ```typescript
- * const result = yield* spawnAgents({
- *   tools: source.tools,
- *   systemPrompt: RESEARCH_PROMPT,
- *   tasks: questions,
- *   terminalTool: { name: 'report', tool: reportTool },
- *   recursive: { name: 'web_research', extractTasks: (a) => a.questions as string[] },
- * });
- * ```
- *
- * @category Agents
- */
-export declare function spawnAgents(opts: SpawnAgentsOpts): Operation<AgentPoolResult>;
-//# sourceMappingURL=spawn-agents.d.ts.map

package/dist/spawn-agents.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"spawn-agents.d.ts","sourceRoot":"","sources":["../src/spawn-agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAWjD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;CAC5D;AAID;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8FAA8F;IAC9F,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC;IAC5C,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACpC,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;kFAC8E;IAC9E,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;oEAEgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;gFAE4E;IAC5E,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA8MD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAiB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC,eAAe,CAAC,CAgD9E"}