@lloyal-labs/lloyal-agents 1.0.0

package/dist/diverge.d.ts

@@ -0,0 +1,39 @@
+import type { Operation } from 'effection';
+import type { DivergeOptions, DivergeResult } from './types';
+/**
+ * Multi-branch perplexity selection as an Effection operation
+ *
+ * Forks N branches from a parent (or a fresh root), generates to EOG via
+ * batched {@link BranchStore.commit}, then selects the lowest-perplexity
+ * attempt. Loser branches are pruned; the caller receives the best branch
+ * still alive.
+ *
+ * When `opts.parent` is provided, the parent branch is NOT pruned — it's
+ * owned by the calling scope. Only the forked attempt branches (losers)
+ * are pruned. The caller owns the winning branch's lifecycle, typically
+ * via {@link Session.promote}.
+ *
+ * Cleanup is structured: each forked branch registers an `ensure()` callback
+ * that prunes it on scope exit. Winners are marked disposed-safe (already
+ * pruned or ownership transferred) before the ensure fires.
+ *
+ * @param opts - Diverge options specifying parent or prompt, attempt count,
+ *   and sampling parameters
+ * @returns Result containing the best branch, all attempt outputs, and
+ *   aggregate statistics
+ *
+ * @example Verify with perplexity selection
+ * ```typescript
+ * const verified = yield* diverge({
+ *   prompt: verifyPrompt,
+ *   attempts: 3,
+ *   params: { temperature: 0.7 },
+ * });
+ * // verified.best is the lowest-perplexity branch, still alive
+ * yield* call(() => session.promote(verified.best));
+ * ```
+ *
+ * @category Agents
+ */
+export declare function diverge(opts: DivergeOptions): Operation<DivergeResult>;
+//# sourceMappingURL=diverge.d.ts.map

package/dist/diverge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diverge.d.ts","sourceRoot":"","sources":["../src/diverge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAI3C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAkB,MAAM,SAAS,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAiB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAAC,aAAa,CAAC,CAsGvE"}

package/dist/diverge.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diverge = diverge;
+const effection_1 = require("effection");
+const sdk_1 = require("@lloyal-labs/sdk");
+const context_1 = require("./context");
+const agent_pool_1 = require("./agent-pool");
+/**
+ * Multi-branch perplexity selection as an Effection operation
+ *
+ * Forks N branches from a parent (or a fresh root), generates to EOG via
+ * batched {@link BranchStore.commit}, then selects the lowest-perplexity
+ * attempt. Loser branches are pruned; the caller receives the best branch
+ * still alive.
+ *
+ * When `opts.parent` is provided, the parent branch is NOT pruned — it's
+ * owned by the calling scope. Only the forked attempt branches (losers)
+ * are pruned. The caller owns the winning branch's lifecycle, typically
+ * via {@link Session.promote}.
+ *
+ * Cleanup is structured: each forked branch registers an `ensure()` callback
+ * that prunes it on scope exit. Winners are marked disposed-safe (already
+ * pruned or ownership transferred) before the ensure fires.
+ *
+ * @param opts - Diverge options specifying parent or prompt, attempt count,
+ *   and sampling parameters
+ * @returns Result containing the best branch, all attempt outputs, and
+ *   aggregate statistics
+ *
+ * @example Verify with perplexity selection
+ * ```typescript
+ * const verified = yield* diverge({
+ *   prompt: verifyPrompt,
+ *   attempts: 3,
+ *   params: { temperature: 0.7 },
+ * });
+ * // verified.best is the lowest-perplexity branch, still alive
+ * yield* call(() => session.promote(verified.best));
+ * ```
+ *
+ * @category Agents
+ */
+function* diverge(opts) {
+    const ctx = yield* context_1.Ctx.expect();
+    const store = yield* context_1.Store.expect();
+    // If parent provided, fork from it. Otherwise create a fresh root.
+    let root;
+    let ownRoot = false;
+    let prefixLength;
+    if (opts.parent) {
+        root = opts.parent;
+        prefixLength = root.position;
+    }
+    else {
+        if (!opts.prompt)
+            throw new Error('diverge() requires either opts.parent or opts.prompt');
+        const tokens = ctx.tokenizeSync(opts.prompt);
+        root = sdk_1.Branch.create(ctx, 0, opts.params ?? {});
+        yield* (0, effection_1.call)(() => root.prefill(tokens));
+        prefixLength = tokens.length;
+        ownRoot = true;
+        // If we created the root, ensure it's cleaned up
+        yield* (0, effection_1.ensure)(() => {
+            if (ownRoot && !root.disposed) {
+                try {
+                    root.pruneSync();
+                }
+                catch { /* children may remain */ }
+            }
+        });
+    }
+    const live = [];
+    for (let i = 0; i < opts.attempts; i++) {
+        const branch = root.forkSync();
+        // Each forked branch gets its own ensure() for structured cleanup
+        yield* (0, effection_1.ensure)(() => {
+            if (!branch.disposed) {
+                try {
+                    branch.pruneSync();
+                }
+                catch { /* already gone */ }
+            }
+        });
+        branch.reseedSampler(2000 + i);
+        live.push({ branch, output: '', done: false, tokenCount: 0, ppl: Infinity });
+    }
+    // Batched generation — produceSync/commit loop
+    let steps = 0;
+    for (;;) {
+        const pressure = new agent_pool_1.ContextPressure(ctx);
+        if (pressure.critical) {
+            for (const a of live) {
+                if (!a.done)
+                    a.done = true;
+            }
+            break;
+        }
+        const entries = [];
+        for (const a of live) {
+            if (a.done)
+                continue;
+            const { token, text, isStop } = a.branch.produceSync();
+            if (isStop) {
+                const p = a.branch.perplexity;
+                a.ppl = Number.isFinite(p) ? p : Infinity;
+                a.done = true;
+                continue;
+            }
+            entries.push([a.branch, token]);
+            a.output += text;
+            a.tokenCount++;
+        }
+        if (entries.length === 0)
+            break;
+        yield* (0, effection_1.call)(() => store.commit(entries));
+        steps++;
+    }
+    // Select by lowest perplexity (most coherent)
+    const bestIdx = live.reduce((bi, a, i) => a.ppl <= live[bi].ppl ? i : bi, 0);
+    // Prune losers now — winner stays alive as caller's result.
+    // ensure() will be a no-op for these since they're already disposed.
+    for (let i = 0; i < live.length; i++) {
+        if (i !== bestIdx && !live[i].branch.disposed) {
+            live[i].branch.pruneSync();
+        }
+    }
+    // If we created root and it's no longer needed, prune it now.
+    // (ensure() will be a no-op since it checks disposed)
+    if (ownRoot && !root.disposed && root.children.length === 0) {
+        root.pruneSync();
+    }
+    const totalTokens = live.reduce((s, a) => s + a.tokenCount, 0);
+    const attempts = live.map(a => ({
+        branch: a.branch,
+        output: a.output,
+        tokenCount: a.tokenCount,
+        ppl: a.ppl,
+    }));
+    return {
+        best: live[bestIdx].branch,
+        bestOutput: live[bestIdx].output,
+        attempts,
+        totalTokens,
+        steps,
+        prefixLength,
+    };
+}
+//# sourceMappingURL=diverge.js.map

package/dist/diverge.js.map

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

package/dist/generate.d.ts

@@ -0,0 +1,30 @@
+import type { Operation } from 'effection';
+import type { GenerateOptions, GenerateResult } from './types';
+/**
+ * Single-branch grammar-constrained generation as an Effection operation
+ *
+ * Creates a fresh branch at position 0, prefills the prompt, generates
+ * to EOG, and prunes the branch. Uses {@link Branch}'s async iterator
+ * — single-branch generation doesn't need batched commit.
+ *
+ * The branch is always cleaned up via try/finally, even on error or
+ * scope cancellation.
+ *
+ * @param opts - Generation options (prompt, grammar, params, parse)
+ * @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),
+ * });
+ * console.log(plan.parsed); // typed result from parse()
+ * ```
+ *
+ * @category Agents
+ */
+export declare function generate<T = unknown>(opts: GenerateOptions): Operation<GenerateResult<T>>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAiB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA0B1F"}

package/dist/generate.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generate = generate;
+const effection_1 = require("effection");
+const sdk_1 = require("@lloyal-labs/sdk");
+const context_1 = require("./context");
+/**
+ * Single-branch grammar-constrained generation as an Effection operation
+ *
+ * Creates a fresh branch at position 0, prefills the prompt, generates
+ * to EOG, and prunes the branch. Uses {@link Branch}'s async iterator
+ * — single-branch generation doesn't need batched commit.
+ *
+ * The branch is always cleaned up via try/finally, even on error or
+ * scope cancellation.
+ *
+ * @param opts - Generation options (prompt, grammar, params, parse)
+ * @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),
+ * });
+ * console.log(plan.parsed); // typed result from parse()
+ * ```
+ *
+ * @category Agents
+ */
+function* generate(opts) {
+    const ctx = yield* context_1.Ctx.expect();
+    const samplerParams = opts.params ?? {};
+    const branch = sdk_1.Branch.create(ctx, 0, samplerParams, undefined, opts.grammar);
+    try {
+        const tokens = ctx.tokenizeSync(opts.prompt);
+        yield* (0, effection_1.call)(() => branch.prefill(tokens));
+        // Consume async iterator inside call() — generators can't use for-await
+        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;
+        return { output, tokenCount, parsed };
+    }
+    finally {
+        if (!branch.disposed)
+            branch.pruneSync();
+    }
+}
+//# sourceMappingURL=generate.js.map

package/dist/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":";;AAgCA,4BA0BC;AA1DD,yCAAiC;AAEjC,0CAA0C;AAC1C,uCAAgC;AAGhC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,QAAe,CAAC,CAAC,QAAQ,CAAc,IAAqB;IAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,aAAG,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,YAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE7E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAE1C,wEAAwE;QACxE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,KAAK,IAAI,EAAE;YACpD,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,UAAU,GAAG,CAAC,CAAC;YACnB,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;gBACpC,MAAM,IAAI,IAAI,CAAC;gBACf,UAAU,EAAE,CAAC;YACf,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAChC,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACxC,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC3C,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { Ctx, Store, Events } from './context';
+export { Tool } from './Tool';
+export { buildUserDelta, buildToolResultDelta } from '@lloyal-labs/sdk';
+export { generate } from './generate';
+export { diverge } from './diverge';
+export { useAgentPool, ContextPressure } from './agent-pool';
+export { runAgents } from './run-agents';
+export { createToolkit } from './toolkit';
+export { initAgents } from './init';
+export { withSharedRoot } from './shared-root';
+export type { Toolkit } from './toolkit';
+export type { AgentHandle } from './init';
+export type { SharedRootOptions } from './shared-root';
+export type { TraceToken, JsonSchema, ToolSchema, ToolContext, PressureThresholds, AgentTaskSpec, AgentPoolOptions, AgentResult, AgentPoolResult, GenerateOptions, GenerateResult, DivergeOptions, DivergeAttempt, DivergeResult, AgentEvent, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,YAAY,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSharedRoot = exports.initAgents = exports.createToolkit = exports.runAgents = exports.ContextPressure = exports.useAgentPool = exports.diverge = exports.generate = exports.buildToolResultDelta = exports.buildUserDelta = exports.Tool = exports.Events = exports.Store = exports.Ctx = void 0;
+var context_1 = require("./context");
+Object.defineProperty(exports, "Ctx", { enumerable: true, get: function () { return context_1.Ctx; } });
+Object.defineProperty(exports, "Store", { enumerable: true, get: function () { return context_1.Store; } });
+Object.defineProperty(exports, "Events", { enumerable: true, get: function () { return context_1.Events; } });
+var Tool_1 = require("./Tool");
+Object.defineProperty(exports, "Tool", { enumerable: true, get: function () { return Tool_1.Tool; } });
+var sdk_1 = require("@lloyal-labs/sdk");
+Object.defineProperty(exports, "buildUserDelta", { enumerable: true, get: function () { return sdk_1.buildUserDelta; } });
+Object.defineProperty(exports, "buildToolResultDelta", { enumerable: true, get: function () { return sdk_1.buildToolResultDelta; } });
+var generate_1 = require("./generate");
+Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return generate_1.generate; } });
+var diverge_1 = require("./diverge");
+Object.defineProperty(exports, "diverge", { enumerable: true, get: function () { return diverge_1.diverge; } });
+var agent_pool_1 = require("./agent-pool");
+Object.defineProperty(exports, "useAgentPool", { enumerable: true, get: function () { return agent_pool_1.useAgentPool; } });
+Object.defineProperty(exports, "ContextPressure", { enumerable: true, get: function () { return agent_pool_1.ContextPressure; } });
+var run_agents_1 = require("./run-agents");
+Object.defineProperty(exports, "runAgents", { enumerable: true, get: function () { return run_agents_1.runAgents; } });
+var toolkit_1 = require("./toolkit");
+Object.defineProperty(exports, "createToolkit", { enumerable: true, get: function () { return toolkit_1.createToolkit; } });
+var init_1 = require("./init");
+Object.defineProperty(exports, "initAgents", { enumerable: true, get: function () { return init_1.initAgents; } });
+var shared_root_1 = require("./shared-root");
+Object.defineProperty(exports, "withSharedRoot", { enumerable: true, get: function () { return shared_root_1.withSharedRoot; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qCAA+C;AAAtC,8FAAA,GAAG,OAAA;AAAE,gGAAA,KAAK,OAAA;AAAE,iGAAA,MAAM,OAAA;AAC3B,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,wCAAwE;AAA/D,qGAAA,cAAc,OAAA;AAAE,2GAAA,oBAAoB,OAAA;AAC7C,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,qCAAoC;AAA3B,kGAAA,OAAO,OAAA;AAChB,2CAA6D;AAApD,0GAAA,YAAY,OAAA;AAAE,6GAAA,eAAe,OAAA;AACtC,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAClB,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AACtB,+BAAoC;AAA3B,kGAAA,UAAU,OAAA;AACnB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA"}

package/dist/init.d.ts

@@ -0,0 +1,58 @@
+import type { Operation, Channel } from 'effection';
+import { BranchStore } from '@lloyal-labs/sdk';
+import { Session } from '@lloyal-labs/sdk';
+import type { SessionContext } from '@lloyal-labs/sdk';
+import type { AgentEvent } from './types';
+/**
+ * Handle returned by {@link initAgents} containing all agent resources
+ *
+ * @category Agents
+ */
+export interface AgentHandle<E = AgentEvent> {
+    /** The session context (model, tokenizer, KV cache) */
+    ctx: SessionContext;
+    /** Branch store for batched commit/prefill across branches */
+    store: BranchStore;
+    /** Session managing conversation trunk and branch lifecycle */
+    session: Session;
+    /** Channel for subscribing to agent events */
+    events: Channel<E, void>;
+}
+/**
+ * Bootstrap the agent infrastructure and register structured cleanup
+ *
+ * Creates {@link BranchStore}, {@link Session}, and an event channel, then
+ * sets all three Effection contexts ({@link Ctx}, {@link Store},
+ * {@link Events}) in the caller's scope. Cleanup runs on scope exit
+ * (Ctrl-C, error, normal completion) via `ensure()`.
+ *
+ * Context values are set in the caller's scope — visible to all subsequent
+ * operations. This is why `initAgents` uses `ensure()` rather than
+ * `resource()`: a resource creates a child scope where `Ctx.set()` would
+ * be invisible to sibling operations.
+ *
+ * The caller creates the {@link SessionContext} (model path, nCtx, KV types
+ * are harness-specific decisions) and passes it in.
+ *
+ * @param ctx - Session context created via `createContext()`
+ * @returns Agent handle with session, store, and event channel
+ *
+ * @example Canonical bootstrap
+ * ```typescript
+ * main(function*() {
+ *   const ctx = yield* call(() => createContext({
+ *     modelPath, nCtx: 16384,
+ *     nSeqMax: 4, typeK: 'q4_0', typeV: 'q4_0',
+ *   }));
+ *
+ *   const { session, events } = yield* initAgents(ctx);
+ *   // Ctx, Store, Events are now set — generate(), diverge(),
+ *   // useAgentPool() will find them automatically.
+ *   // Cleanup runs on scope exit.
+ * });
+ * ```
+ *
+ * @category Agents
+ */
+export declare function initAgents<E = AgentEvent>(ctx: SessionContext): Operation<AgentHandle<E>>;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,UAAU;IACzC,uDAAuD;IACvD,GAAG,EAAE,cAAc,CAAC;IACpB,8DAA8D;IAC9D,KAAK,EAAE,WAAW,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAiB,UAAU,CAAC,CAAC,GAAG,UAAU,EACxC,GAAG,EAAE,cAAc,GAClB,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAe3B"}

package/dist/init.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initAgents = initAgents;
+const effection_1 = require("effection");
+const sdk_1 = require("@lloyal-labs/sdk");
+const sdk_2 = require("@lloyal-labs/sdk");
+const context_1 = require("./context");
+/**
+ * Bootstrap the agent infrastructure and register structured cleanup
+ *
+ * Creates {@link BranchStore}, {@link Session}, and an event channel, then
+ * sets all three Effection contexts ({@link Ctx}, {@link Store},
+ * {@link Events}) in the caller's scope. Cleanup runs on scope exit
+ * (Ctrl-C, error, normal completion) via `ensure()`.
+ *
+ * Context values are set in the caller's scope — visible to all subsequent
+ * operations. This is why `initAgents` uses `ensure()` rather than
+ * `resource()`: a resource creates a child scope where `Ctx.set()` would
+ * be invisible to sibling operations.
+ *
+ * The caller creates the {@link SessionContext} (model path, nCtx, KV types
+ * are harness-specific decisions) and passes it in.
+ *
+ * @param ctx - Session context created via `createContext()`
+ * @returns Agent handle with session, store, and event channel
+ *
+ * @example Canonical bootstrap
+ * ```typescript
+ * main(function*() {
+ *   const ctx = yield* call(() => createContext({
+ *     modelPath, nCtx: 16384,
+ *     nSeqMax: 4, typeK: 'q4_0', typeV: 'q4_0',
+ *   }));
+ *
+ *   const { session, events } = yield* initAgents(ctx);
+ *   // Ctx, Store, Events are now set — generate(), diverge(),
+ *   // useAgentPool() will find them automatically.
+ *   // Cleanup runs on scope exit.
+ * });
+ * ```
+ *
+ * @category Agents
+ */
+function* initAgents(ctx) {
+    const store = new sdk_1.BranchStore(ctx);
+    const session = new sdk_2.Session({ ctx, store });
+    const events = (0, effection_1.createChannel)();
+    yield* context_1.Ctx.set(ctx);
+    yield* context_1.Store.set(store);
+    yield* context_1.Events.set(events);
+    yield* (0, effection_1.ensure)(function* () {
+        yield* (0, effection_1.call)(() => session.dispose());
+        ctx.dispose();
+    });
+    return { ctx, store, session, events };
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":";;AA4DA,gCAiBC;AA7ED,yCAAwD;AAExD,0CAA+C;AAC/C,0CAA2C;AAE3C,uCAA+C;AAmB/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,QAAe,CAAC,CAAC,UAAU,CACzB,GAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,iBAAW,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,aAAO,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAqB,IAAA,yBAAa,GAAW,CAAC;IAE1D,KAAK,CAAC,CAAC,aAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB,KAAK,CAAC,CAAC,eAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,KAAK,CAAC,CAAC,gBAAM,CAAC,GAAG,CAAC,MAA8C,CAAC,CAAC;IAElE,KAAK,CAAC,CAAC,IAAA,kBAAM,EAAC,QAAQ,CAAC;QACrB,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACrC,GAAG,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC"}

package/dist/run-agents.d.ts

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,46 @@
+"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)(opts);
+    });
+}
+//# sourceMappingURL=run-agents.js.map

package/dist/run-agents.js.map

@@ -0,0 +1 @@
+{"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,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/shared-root.d.ts

@@ -0,0 +1,55 @@
+import type { Operation } from 'effection';
+import { Branch } from '@lloyal-labs/sdk';
+import type { SamplingParams } from './types';
+/**
+ * Configuration for {@link withSharedRoot}
+ *
+ * @category Agents
+ */
+export interface SharedRootOptions {
+    /** System prompt to tokenize and prefill into the shared root */
+    systemPrompt: string;
+    /** JSON-serialized tool schemas for tool-aware prompt formatting */
+    tools?: string;
+    /** Sampling parameters for the root branch */
+    params?: SamplingParams;
+}
+/**
+ * Scoped shared root branch with guaranteed cleanup
+ *
+ * Creates a root branch, prefills the system prompt, and passes it to
+ * the body function. The root is pruned via try/finally when the body
+ * returns or throws, regardless of whether children still exist.
+ *
+ * Use this for the cold-path pattern where multiple agents share a
+ * tokenized system prompt prefix. The `sharedPrefixLength` passed to
+ * the body enables KV savings calculation.
+ *
+ * @param opts - System prompt, tools, and sampling parameters
+ * @param body - Operation that receives the root branch and prefix length.
+ *   Typically calls {@link runAgents} or {@link useAgentPool} inside.
+ * @returns The body's return value
+ *
+ * @example Cold-path research with shared prefix
+ * ```typescript
+ * const { result, prefixLen } = yield* withSharedRoot(
+ *   { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
+ *   function*(root, prefixLen) {
+ *     const result = yield* runAgents({
+ *       tasks: questions.map(q => ({
+ *         systemPrompt: RESEARCH_PROMPT,
+ *         content: q,
+ *         tools: toolsJson,
+ *         parent: root,
+ *       })),
+ *       tools: toolMap,
+ *     });
+ *     return { result, prefixLen };
+ *   },
+ * );
+ * ```
+ *
+ * @category Agents
+ */
+export declare function withSharedRoot<T>(opts: SharedRootOptions, body: (root: Branch, sharedPrefixLength: number) => Operation<T>): Operation<T>;
+//# sourceMappingURL=shared-root.d.ts.map

package/dist/shared-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-root.d.ts","sourceRoot":"","sources":["../src/shared-root.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAiB,cAAc,CAAC,CAAC,EAC/B,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAC/D,SAAS,CAAC,CAAC,CAAC,CAkBd"}