@lloyal-labs/lloyal-agents 1.7.0 → 2.0.0

package/dist/orchestrators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrators.d.ts","sourceRoot":"","sources":["../src/orchestrators.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAQ,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6FAA6F;IAC7F,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAEzC,0FAA0F;IAC1F,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAExC;;;OAGG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAE7E,oFAAoF;IACpF,MAAM,CAAC,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC;CAChD;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;AAIjE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,SAAS,EAAE,KAAG,YAI3C,CAAC;AAEJ;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EACrB,OAAO,CAAC,EAAE,EACV,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,KAC5C,YAaA,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,GAAI,WAAW,SAAS,EAAE,SAAS,SAAS,EAAE,KAAG,YAajE,CAAC;AAEJ;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,OAAO,EAAE,KAAG,YA0CtC,CAAC"}

package/dist/orchestrators.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dag = exports.fanout = exports.chain = exports.parallel = void 0;
+const effection_1 = require("effection");
+// ── Factories ──────────────────────────────────────────────────
+/**
+ * Parallel orchestrator — spawn all tasks upfront, wait for all to complete.
+ * This is the default shape that `useAgentPool` used to provide implicitly.
+ *
+ * @example
+ * ```ts
+ * yield* agentPool({
+ *   tools: [...],
+ *   orchestrate: parallel(questions.map(q => ({ content: q, systemPrompt: RESEARCH_PROMPT }))),
+ * });
+ * ```
+ *
+ * @category Agents
+ */
+const parallel = (tasks) => function* (ctx) {
+    const agents = yield* (0, effection_1.all)(tasks.map(t => ctx.spawn({ ...t, parent: t.parent ?? ctx.root })));
+    yield* (0, effection_1.all)(agents.map(a => ctx.waitFor(a)));
+};
+exports.parallel = parallel;
+/**
+ * Chain orchestrator — sequential execution. Each step may extend the shared
+ * root with its findings before the next step forks from the extended position.
+ *
+ * The second argument maps each item to a ChainStep, so callers can compute
+ * per-task prompts and spine labels from their own data model without
+ * coupling the factory to a particular task type.
+ *
+ * @example
+ * ```ts
+ * yield* agentPool({
+ *   tools: [...],
+ *   parent: queryRoot,
+ *   orchestrate: chain(researchTasks, (task, i) => ({
+ *     task: { content: taskToContent(task), systemPrompt: renderWorker({ taskIndex: i }) },
+ *     userContent: `Research task: ${task.description}`,
+ *   })),
+ * });
+ * ```
+ *
+ * @category Agents
+ */
+const chain = (items, toStep) => function* (ctx) {
+    for (const [i, item] of items.entries()) {
+        const step = toStep(item, i);
+        if (step.beforeSpawn)
+            yield* step.beforeSpawn();
+        const agent = yield* ctx.waitFor(yield* ctx.spawn({ ...step.task, parent: step.task.parent ?? ctx.root }));
+        const delta = agent.result && step.userContent
+            ? yield* ctx.extendRoot(step.userContent, agent.result)
+            : 0;
+        if (step.afterExtend)
+            yield* step.afterExtend(delta, ctx.root.position);
+    }
+};
+exports.chain = chain;
+/**
+ * Fanout orchestrator — landscape task first (optionally extending the spine),
+ * then N independent domain tasks in parallel. Domain tasks fork from the
+ * post-landscape root and do NOT see each other's findings.
+ *
+ * The canonical shape for multi-domain queries: one landscape survey that
+ * loads vocabulary into the spine, then one task per independent domain.
+ *
+ * @example
+ * ```ts
+ * yield* agentPool({
+ *   orchestrate: fanout(
+ *     { task: { content: landscapeQuery, systemPrompt: WORKER }, userContent: 'Landscape survey' },
+ *     domainQueries.map(q => ({ content: q, systemPrompt: WORKER })),
+ *   ),
+ * });
+ * ```
+ *
+ * @category Agents
+ */
+const fanout = (landscape, domains) => function* (ctx) {
+    const l = yield* ctx.waitFor(yield* ctx.spawn({ ...landscape.task, parent: landscape.task.parent ?? ctx.root }));
+    if (l.result && landscape.userContent) {
+        yield* ctx.extendRoot(landscape.userContent, l.result);
+    }
+    const agents = yield* (0, effection_1.all)(domains.map(d => ctx.spawn({ ...d, parent: d.parent ?? ctx.root })));
+    yield* (0, effection_1.all)(agents.map(a => ctx.waitFor(a)));
+};
+exports.fanout = fanout;
+/**
+ * DAG orchestrator — lazy spawn on dependency resolution. Independent nodes
+ * run in parallel; dependent nodes wait until their dependencies complete
+ * (and their findings extend the spine) before forking.
+ *
+ * Subsumes the design in `docs/dag-pool.md` — DAG is an orchestration
+ * pattern expressed on top of the general primitive, not a pool internals
+ * change.
+ *
+ * @category Agents
+ */
+const dag = (nodes) => {
+    validateDAG(nodes);
+    return function* (ctx) {
+        // Each node runs as a child Task. Dependencies are expressed by
+        // awaiting the dep's Task (`yield* depTask`) — Task<T> extends
+        // Future<T> extends Operation<T>, so this is the canonical Effection
+        // cross-task rendezvous (see frontside.com/effection/api/v4/Task).
+        //
+        // Why this beats the older recursive-spawnNode-with-Sets approach:
+        //   - No mutable bookkeeping. The "node N is done" signal IS the
+        //     Task itself; the runtime tracks lifetimes for free.
+        //   - No race window for double-spawn. Each node spawns exactly
+        //     once, by definition (one entry per `tasks.set`).
+        //   - Failure propagates through the dependency edges automatically:
+        //     if node A throws, every task awaiting A's Task receives the
+        //     same error, and structured concurrency halts the rest.
+        const tasks = new Map();
+        function* runNode(n) {
+            // Gate: wait for every declared dep's task to complete. The map is
+            // fully populated before any node body runs (spawned tasks don't
+            // execute until the parent yields, and the spawn loop below is
+            // synchronous between iterations).
+            for (const depId of n.dependsOn ?? []) {
+                yield* tasks.get(depId);
+            }
+            const agent = yield* ctx.waitFor(yield* ctx.spawn({ ...n.task, parent: n.task.parent ?? ctx.root }));
+            if (agent.result && n.userContent) {
+                yield* ctx.extendRoot(n.userContent, agent.result);
+            }
+        }
+        for (const n of nodes) {
+            tasks.set(n.id, yield* (0, effection_1.spawn)(() => runNode(n)));
+        }
+        // Await every task. Roots run first (no deps to await); descendants
+        // unblock as their deps complete. Any throw inside a node propagates
+        // here and halts the rest via structured concurrency.
+        for (const t of tasks.values())
+            yield* t;
+    };
+};
+exports.dag = dag;
+function validateDAG(nodes) {
+    const ids = new Set(nodes.map(n => n.id));
+    const duplicates = nodes.filter((n, i) => nodes.findIndex(m => m.id === n.id) !== i);
+    if (duplicates.length > 0) {
+        throw new Error(`dag: duplicate node ids: ${duplicates.map(n => n.id).join(', ')}`);
+    }
+    for (const n of nodes) {
+        for (const dep of n.dependsOn ?? []) {
+            if (!ids.has(dep))
+                throw new Error(`dag: node '${n.id}' depends on unknown node '${dep}'`);
+        }
+    }
+    // Cycle detection via DFS
+    const visiting = new Set();
+    const visited = new Set();
+    const byId = new Map(nodes.map(n => [n.id, n]));
+    function visit(id, path) {
+        if (visited.has(id))
+            return;
+        if (visiting.has(id))
+            throw new Error(`dag: cycle detected: ${[...path, id].join(' -> ')}`);
+        visiting.add(id);
+        const node = byId.get(id);
+        for (const dep of node?.dependsOn ?? [])
+            visit(dep, [...path, id]);
+        visiting.delete(id);
+        visited.add(id);
+    }
+    for (const n of nodes)
+        visit(n.id, []);
+}
+//# sourceMappingURL=orchestrators.js.map

package/dist/orchestrators.js.map

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

package/dist/replay.d.ts

@@ -0,0 +1,96 @@
+import type { Operation } from 'effection';
+import { Branch } from '@lloyal-labs/sdk';
+import type { TraceEvent } from './trace-types';
+/**
+ * Serialized state needed to reconstruct a Branch deterministically.
+ *
+ * `rootPrompt` is the tokenized prompt that initialized a shared root — the
+ * full formatted chat template including system prompt and any tool schemas.
+ * Captured from `prompt:format` events with `role: 'sharedRoot'`.
+ *
+ * `turns` is an ordered list of user/assistant turn pairs that were prefilled
+ * on top of the root via {@link extendSpine}. Empty for pool-start replay
+ * (any orchestration shape that doesn't extend the spine — e.g. `parallel`);
+ * populated for spine-extending orchestrations (`chain`, `fanout`, `dag`).
+ *
+ * @category Agents
+ */
+export interface BranchCheckpoint {
+    rootPrompt: string;
+    turns: Array<{
+        userContent: string;
+        assistantContent: string;
+    }>;
+}
+/**
+ * Extract the shared-root prompt from a trace, with no spine extensions.
+ *
+ * Useful for replaying parallel orchestrations, or for forking a fresh
+ * agent off the same pool-start state for A/B experiments.
+ *
+ * @param events - parsed JSONL trace events, in emission order
+ * @throws If no `prompt:format` event with `role: 'sharedRoot'` is found.
+ *
+ * @category Agents
+ */
+export declare function extractRootCheckpoint(events: TraceEvent[]): BranchCheckpoint;
+/**
+ * Extract a full spine checkpoint — root prompt plus every `spine:extend`
+ * event in emission order.
+ *
+ * When `opts.poolTraceId` is set, only spine extensions under that pool's
+ * scope are included (useful when a trace contains multiple nested or
+ * sequential pools with independent spines — typically the research pool
+ * vs. a later synthesis pool, both extending their own roots).
+ *
+ * @param events - parsed JSONL trace events, in emission order
+ * @param opts.poolTraceId - filter extensions to this pool's scope
+ * @throws If no shared-root prompt is found.
+ *
+ * @category Agents
+ */
+export declare function extractSpineCheckpoint(events: TraceEvent[], opts?: {
+    poolTraceId?: number;
+}): BranchCheckpoint;
+/**
+ * Materialize a Branch reflecting the checkpointed state.
+ *
+ * Creates a fresh root at position 0 in the active `SessionContext`, prefills
+ * the tokenized root prompt, then applies each turn delta via `buildTurnDelta`
+ * + `store.prefill`. Registers an `ensure()` so the subtree is pruned when
+ * the caller's scope exits — lifetime follows the enclosing `scoped()` or
+ * `resource()`, matching how `withSharedRoot` manages its own root.
+ *
+ * Pass the returned branch as `parent` to `agentPool` to run a replacement
+ * stage (synth re-run, single-agent replay with modified prompt, etc.) against
+ * the reconstructed KV state.
+ *
+ * @example Replay a pool-start (parallel orchestration) with a modified task
+ * ```ts
+ * const events = parseTrace(tracePath);
+ * const checkpoint = extractRootCheckpoint(events);
+ * const root = yield* reconstructBranch(checkpoint);
+ * yield* agentPool({
+ *   parent: root,
+ *   orchestrate: parallel([{ content: modifiedTask, systemPrompt: modifiedSys }]),
+ *   ...
+ * });
+ * ```
+ *
+ * @example Replay a spine-chain (research) state with a different synth prompt
+ * ```ts
+ * const events = parseTrace(tracePath);
+ * const checkpoint = extractSpineCheckpoint(events);
+ * const queryRoot = yield* reconstructBranch(checkpoint);
+ * yield* agentPool({
+ *   parent: queryRoot,
+ *   orchestrate: parallel([{ content: SYNTHESIZE.user }]),
+ *   systemPrompt: SYNTHESIZE.system,
+ *   ...
+ * });
+ * ```
+ *
+ * @category Agents
+ */
+export declare function reconstructBranch(checkpoint: BranchCheckpoint): Operation<Branch>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAkB,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,gBAAgB,CAW5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,UAAU,EAAE,EACpB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,gBAAgB,CASlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAiB,iBAAiB,CAAC,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAC,MAAM,CAAC,CAgBlF"}

package/dist/replay.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRootCheckpoint = extractRootCheckpoint;
+exports.extractSpineCheckpoint = extractSpineCheckpoint;
+exports.reconstructBranch = reconstructBranch;
+const effection_1 = require("effection");
+const sdk_1 = require("@lloyal-labs/sdk");
+const context_1 = require("./context");
+/**
+ * Extract the shared-root prompt from a trace, with no spine extensions.
+ *
+ * Useful for replaying parallel orchestrations, or for forking a fresh
+ * agent off the same pool-start state for A/B experiments.
+ *
+ * @param events - parsed JSONL trace events, in emission order
+ * @throws If no `prompt:format` event with `role: 'sharedRoot'` is found.
+ *
+ * @category Agents
+ */
+function extractRootCheckpoint(events) {
+    const sharedRoot = events.find((e) => e.type === 'prompt:format' && e.role === 'sharedRoot');
+    if (!sharedRoot) {
+        throw new Error('extractRootCheckpoint: no prompt:format event with role=sharedRoot found in trace');
+    }
+    return { rootPrompt: sharedRoot.promptText, turns: [] };
+}
+/**
+ * Extract a full spine checkpoint — root prompt plus every `spine:extend`
+ * event in emission order.
+ *
+ * When `opts.poolTraceId` is set, only spine extensions under that pool's
+ * scope are included (useful when a trace contains multiple nested or
+ * sequential pools with independent spines — typically the research pool
+ * vs. a later synthesis pool, both extending their own roots).
+ *
+ * @param events - parsed JSONL trace events, in emission order
+ * @param opts.poolTraceId - filter extensions to this pool's scope
+ * @throws If no shared-root prompt is found.
+ *
+ * @category Agents
+ */
+function extractSpineCheckpoint(events, opts = {}) {
+    const root = extractRootCheckpoint(events);
+    const turns = [];
+    for (const e of events) {
+        if (e.type !== 'spine:extend')
+            continue;
+        if (opts.poolTraceId != null && e.parentTraceId !== opts.poolTraceId)
+            continue;
+        turns.push({ userContent: e.userContent, assistantContent: e.assistantContent });
+    }
+    return { rootPrompt: root.rootPrompt, turns };
+}
+/**
+ * Materialize a Branch reflecting the checkpointed state.
+ *
+ * Creates a fresh root at position 0 in the active `SessionContext`, prefills
+ * the tokenized root prompt, then applies each turn delta via `buildTurnDelta`
+ * + `store.prefill`. Registers an `ensure()` so the subtree is pruned when
+ * the caller's scope exits — lifetime follows the enclosing `scoped()` or
+ * `resource()`, matching how `withSharedRoot` manages its own root.
+ *
+ * Pass the returned branch as `parent` to `agentPool` to run a replacement
+ * stage (synth re-run, single-agent replay with modified prompt, etc.) against
+ * the reconstructed KV state.
+ *
+ * @example Replay a pool-start (parallel orchestration) with a modified task
+ * ```ts
+ * const events = parseTrace(tracePath);
+ * const checkpoint = extractRootCheckpoint(events);
+ * const root = yield* reconstructBranch(checkpoint);
+ * yield* agentPool({
+ *   parent: root,
+ *   orchestrate: parallel([{ content: modifiedTask, systemPrompt: modifiedSys }]),
+ *   ...
+ * });
+ * ```
+ *
+ * @example Replay a spine-chain (research) state with a different synth prompt
+ * ```ts
+ * const events = parseTrace(tracePath);
+ * const checkpoint = extractSpineCheckpoint(events);
+ * const queryRoot = yield* reconstructBranch(checkpoint);
+ * yield* agentPool({
+ *   parent: queryRoot,
+ *   orchestrate: parallel([{ content: SYNTHESIZE.user }]),
+ *   systemPrompt: SYNTHESIZE.system,
+ *   ...
+ * });
+ * ```
+ *
+ * @category Agents
+ */
+function* reconstructBranch(checkpoint) {
+    const ctx = yield* context_1.Ctx.expect();
+    const store = yield* context_1.Store.expect();
+    const root = sdk_1.Branch.create(ctx, 0, {});
+    yield* (0, effection_1.ensure)(() => { if (!root.disposed)
+        root.pruneSubtreeSync(); });
+    const rootTokens = ctx.tokenizeSync(checkpoint.rootPrompt, false);
+    yield* (0, effection_1.call)(() => root.prefill(rootTokens));
+    for (const turn of checkpoint.turns) {
+        const delta = (0, sdk_1.buildTurnDelta)(ctx, turn.userContent, turn.assistantContent);
+        yield* (0, effection_1.call)(() => store.prefill([[root, delta]]));
+    }
+    return root;
+}
+//# sourceMappingURL=replay.js.map

package/dist/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":";;AAoCA,sDAWC;AAiBD,wDAYC;AA0CD,8CAgBC;AAtID,yCAAyC;AAEzC,0CAA0D;AAC1D,uCAAuC;AAsBvC;;;;;;;;;;GAUG;AACH,SAAgB,qBAAqB,CAAC,MAAoB;IACxD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAC5B,CAAC,CAAC,EAAuD,EAAE,CACzD,CAAC,CAAC,IAAI,KAAK,eAAe,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,CACxD,CAAC;IACF,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,mFAAmF,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,sBAAsB,CACpC,MAAoB,EACpB,OAAiC,EAAE;IAEnC,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc;YAAE,SAAS;QACxC,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,IAAI,CAAC,CAAC,aAAa,KAAK,IAAI,CAAC,WAAW;YAAE,SAAS;QAC/E,KAAK,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,QAAe,CAAC,CAAC,iBAAiB,CAAC,UAA4B;IAC7D,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,aAAG,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,eAAK,CAAC,MAAM,EAAE,CAAC;IAEpC,MAAM,IAAI,GAAG,YAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACvC,KAAK,CAAC,CAAC,IAAA,kBAAM,EAAC,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtE,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAClE,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5C,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,IAAA,oBAAc,EAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC3E,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/shared-root.d.ts

@@ -7,10 +7,6 @@ import type { SamplingParams } from "./types";
  * @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;
     /**
@@ -24,32 +20,74 @@ export interface SharedRootOptions {
      *
      * When provided, the root inherits the parent's full KV state —
      * every tool call, tool result, and generated token the parent
-     * accumulated. The system prompt is prefilled as a delta on top.
-     * Sub-agents forking from this root attend over the parent's
-     * complete attention state (Continuous Context).
+     * accumulated. Sub-agents forking from this root attend over the
+     * parent's complete attention state (Continuous Context).
      *
      * When omitted, creates a fresh root at position 0 (cold start).
      */
     parent?: Branch;
+    /**
+     * When set, prefill the chat-format `[system + tools]` header onto the
+     * root once at setup. Every agent forking from the root inherits these
+     * tokens via `forkSync`'s metadata-only KV prefix-share — the role and
+     * tool schemas appear ONCE in physical KV regardless of how many agents
+     * the pool spawns.
+     *
+     * The resulting `FormatConfig` (parser/grammar/format/triggers) is set
+     * on the {@link RootFmt} context so `setupAgent` can detect shared mode,
+     * skip its own system+tools formatting, and inherit the dispatch-side
+     * fmt from the root.
+     *
+     * Use this for orchestrators where every agent shares the same role —
+     * chain-mode research pools, fanout-style same-role pools, etc. Mixed-
+     * role workflows (research → compare → synthesize) keep using per-spec
+     * `SpawnSpec.systemPrompt` and don't pass this option.
+     */
+    systemPrompt?: string;
+    /**
+     * JSON-serialized tool schemas to embed in the chat-format header
+     * prefilled at setup. Format matches `FormatChatOptions.tools` — output
+     * of `createToolkit(...).toolsJson`. Only applied when `systemPrompt` is
+     * also set; ignored otherwise.
+     */
+    toolsJson?: string;
+    /**
+     * Whether to enable thinking-mode tokens (e.g. `<think>` blocks) when
+     * formatting the shared root header. Threaded through to the chat-format
+     * call AND stored on the `RootFmt` FormatConfig so `setupAgent`'s
+     * shared-mode shortcut copies a parser/grammar/triggers configuration
+     * consistent with the per-agent suffix formatting.
+     *
+     * Should match the `enableThinking` value the caller passes to the agent
+     * pool — divergent values produce inconsistent grammar between the
+     * prefilled root and per-agent suffixes.
+     *
+     * @default false
+     */
+    enableThinking?: boolean;
 }
 /**
  * Scoped shared root branch with guaranteed cleanup
  *
- * Creates (or forks) 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.
+ * Creates (or forks) a root branch for the pool's agents to fork from.
+ * The root is pruned via try/finally when the body returns or throws,
+ * regardless of whether children still exist.
+ *
+ * Each agent's chat format (system + user + generation prompt) is rendered
+ * fresh inside `setupAgent`, so this root carries no chat context itself —
+ * it exists as the pool's branching point and as the spine that
+ * `ctx.extendRoot` writes onto between tasks.
  *
- * **Cold path** (no `parent`): creates root at position 0, prefills system
- * prompt. Use for top-level research where no prior context exists.
+ * **Cold path** (no `parent`): creates a root at position 0 with no prefill.
+ * Agents fork at position 0; their full chat context lives in their own suffix.
  *
- * **Warm path** (`parent` provided): forks from parent branch, prefills
- * system prompt as a delta. Sub-agents inherit the parent's full KV state.
- * Use for recursive tools (web_research, research) where sub-agents should
- * attend over the calling agent's accumulated evidence.
+ * **Warm path** (`parent` provided): forks from parent and prefills a turn
+ * separator so subsequent agent suffixes land on a clean turn boundary.
+ * Sub-agents inherit the parent's full KV state via the fork.
  *
- * @param opts - System prompt, tools, sampling parameters, and optional parent branch
+ * @param opts - Sampling parameters and optional parent branch
  * @param body - Operation that receives the root branch and prefix length.
- *   Typically calls {@link runAgents} or {@link useAgentPool} inside.
+ *   Typically calls {@link useAgentPool} inside.
  * @returns The body's return value
  *
  * @category Agents

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

@@ -1 +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;AAI1C,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;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;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,CAkGd"}
+{"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;AAI1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;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,CAsHd"}