@lloyal-labs/lloyal-agents 1.5.6 → 1.7.0

package/dist/agent-pool.js

@@ -7,12 +7,17 @@ const sdk_1 = require("@lloyal-labs/sdk");
 const context_1 = require("./context");
 const sdk_2 = require("@lloyal-labs/sdk");
 const trace_scope_1 = require("./trace-scope");
-const generate_1 = require("./generate");
 const Agent_1 = require("./Agent");
 const AgentPolicy_1 = require("./AgentPolicy");
 /**
  * Immutable KV budget snapshot for one tick of the agent loop
  *
+ * Frozen at phase boundaries (PRODUCE, SETTLE, DISPATCH) so that all
+ * decisions within a phase are evaluated against the same baseline.
+ * Without this, items processed earlier in a loop would see different
+ * pressure than items processed later — making reject/nudge/kill
+ * decisions order-dependent and nondeterministic.
+ *
  * Created from `SessionContext._storeKvPressure()` which returns
  * `{ nCtx, cellsUsed, remaining }` where `remaining = nCtx - cellsUsed`.
  * `cellsUsed` tracks unique KV cells per branch — incremented on
@@ -93,6 +98,119 @@ class ContextPressure {
     }
 }
 exports.ContextPressure = ContextPressure;
+/**
+ * Inline recovery for a single killed agent (trailing stop).
+ *
+ * Prefills the extraction prompt into the agent's own branch, sets eager
+ * report grammar, generates to stop token, parses JSON, reports result,
+ * and prunes the branch — all before the tick loop continues. The freed
+ * KV lets remaining agents keep researching.
+ *
+ * Returns true if the agent reported findings.
+ */
+function* recoverInline(agent, policy, ctx, store, tw, parentTraceId, events) {
+    const recovery = policy.onRecovery?.(agent);
+    if (!recovery || recovery.type === 'skip') {
+        if (!agent.branch.disposed)
+            agent.branch.pruneSync();
+        return false;
+    }
+    // Build the nudge prompt — a minimal turn injection that triggers
+    // report behavior. The agent's KV already contains the full
+    // conversation context; the prompt is just a nudge.
+    const { prompt } = ctx.formatChatSync(JSON.stringify([
+        { role: 'system', content: recovery.prompt.system },
+        { role: 'user', content: recovery.prompt.user },
+    ]), { enableThinking: false });
+    const sep = ctx.getTurnSeparator();
+    const delta = ctx.tokenizeSync(prompt, false);
+    const tokens = [...sep, ...delta];
+    // Eager report grammar — forces { result: string } output
+    const reportGrammar = yield* (0, effection_1.call)(() => ctx.jsonSchemaToGrammar(JSON.stringify({
+        type: 'object',
+        properties: { result: { type: 'string' } },
+        required: ['result'],
+    })));
+    // Recovery runs in its own scope — if prefill or decode fails
+    // (KV exhaustion), the scope tears down cleanly.
+    let reported = false;
+    try {
+        yield* (0, effection_1.scoped)(function* () {
+            yield* (0, effection_1.call)(() => store.prefill([[agent.branch, tokens]]));
+            agent.branch.setGrammar(reportGrammar);
+            tw.write({
+                traceId: tw.nextId(), parentTraceId, ts: performance.now(),
+                type: 'branch:prefill', branchHandle: agent.id,
+                tokenCount: tokens.length, role: 'recovery',
+            });
+            // Single-agent produce/commit loop
+            let output = '';
+            let tokenCount = 0;
+            for (;;) {
+                const { token, text, isStop } = agent.branch.produceSync();
+                if (isStop)
+                    break;
+                output += text;
+                tokenCount++;
+                yield* (0, effection_1.call)(() => store.commit([[agent.branch, token]]));
+                yield* events.send({ type: 'agent:produce', agentId: agent.id, text, tokenCount });
+            }
+            // Parse + report
+            const parsed = JSON.parse(output);
+            if (parsed?.result) {
+                agent.reportResult(parsed.result, 'scratchpad');
+                yield* events.send({ type: 'agent:report', agentId: agent.id, result: agent.result });
+                reported = true;
+            }
+        });
+    }
+    catch { /* prefill overflow, decode failure, or malformed JSON — non-fatal */ }
+    // Always prune after scope exits (success or failure)
+    if (!agent.branch.disposed)
+        agent.branch.pruneSync();
+    // Emit tick so TUI updates pressure percentage after prune
+    const postPressure = new ContextPressure(ctx);
+    yield* events.send({ type: 'agent:tick', cellsUsed: postPressure.cellsUsed, nCtx: postPressure.nCtx });
+    return reported;
+}
+// ── PRODUCE action handlers ─────────────────────────────────────
+// Each handler encapsulates state transitions, events, and trace for one
+// policy action outcome. The PRODUCE switch dispatches to these.
+function* handleFreeTextReport(a, content, events) {
+    a.reportResult(content, 'free_text');
+    a.transition('idle');
+    yield* events.send({ type: 'agent:report', agentId: a.id, result: a.result });
+    yield* events.send({ type: 'agent:done', agentId: a.id });
+}
+function* handleIdleDrop(a, reason, events, tw, parentTraceId) {
+    a.transition('idle');
+    if (reason !== 'free_text_stop') {
+        tw.write({ traceId: tw.nextId(), parentTraceId, ts: performance.now(),
+            type: 'pool:agentDrop', agentId: a.id,
+            reason: reason === 'max_turns' ? 'maxTurns' : 'pressure_softcut' });
+    }
+    yield* events.send({ type: 'agent:done', agentId: a.id });
+}
+function* handleNudge(a, message, tc, ctx, tools) {
+    const callId = tc?.id || `call_${a.toolCallCount}`;
+    const nudgeResult = { error: message };
+    a.incrementTurns();
+    a.transition('awaiting_tool');
+    const prefillTokens = (0, sdk_2.buildToolResultDelta)(ctx, JSON.stringify(nudgeResult), callId);
+    const probe = tools?.get(tc?.name || '')?.probe(nudgeResult) ?? undefined;
+    a.resetTurn();
+    return { agentId: a.id, prefillTokens, toolName: tc?.name || '', callId, args: tc?.arguments || '', probe };
+}
+function* handleReport(a, result, tc, terminalTool, pruneOnReport, events) {
+    a.reportResult(result, 'report_tool');
+    a.transition('idle');
+    a.incrementToolCalls();
+    yield* events.send({ type: 'agent:tool_call', agentId: a.id, tool: terminalTool, args: tc.arguments });
+    yield* events.send({ type: 'agent:report', agentId: a.id, result: a.result });
+    yield* events.send({ type: 'agent:done', agentId: a.id });
+    if (pruneOnReport && !a.branch.disposed)
+        a.branch.pruneSync();
+}
 /**
  * Fork an agent from a parent branch with its own system prompt and task.
  *
@@ -197,13 +315,13 @@ function useAgentPool(opts) {
     return (0, effection_1.resource)(function* (provide) {
         const ctx = yield* context_1.Ctx.expect();
         const store = yield* context_1.Store.expect();
-        const events = yield* context_1.Events.expect();
+        const poolChannel = (0, effection_1.createChannel)();
         // Bridge for onProgress callbacks — Signal is correct here (external callback).
-        // A spawned forwarder drains the bridge into the Channel with proper scope context.
+        // A spawned forwarder drains the bridge into the poolChannel with proper scope context.
         const progressBridge = (0, effection_1.createSignal)();
         yield* (0, effection_1.spawn)(function* () {
             for (const ev of yield* (0, effection_1.each)(progressBridge)) {
-                yield* events.send(ev);
+                yield* poolChannel.send(ev);
                 yield* effection_1.each.next();
             }
         });
@@ -296,11 +414,6 @@ function useAgentPool(opts) {
             taskSuffixTokens: prefillSetup.map(([, t]) => t.length),
             pressure: { remaining: initPressure.remaining, softLimit: initPressure.softLimit, headroom: initPressure.headroom },
         });
-        // Emit spawn events and activate agents
-        for (const a of agents) {
-            a.transition('active');
-            yield* events.send({ type: 'agent:spawn', agentId: a.id, parentAgentId: a.parentId });
-        }
         // ── Lazy grammar setup ───────────────────────────────────
         const applyLazyGrammar = (a) => {
             if (a.fmt.grammar && a.fmt.grammarLazy && a.fmt.grammarTriggers.length > 0) {
@@ -318,434 +431,360 @@ function useAgentPool(opts) {
         };
         for (const a of agents)
             applyLazyGrammar(a);
-        // ── Tool dispatch coordination ───────────────────────────
-        // Tool results land in settledBuffer during DISPATCH, drained by SETTLE
-        // in the next tick. DISPATCH awaits each tool to completion via
-        // scoped() + call() — no concurrent llama_decode possible.
-        const settledBuffer = [];
-        const dispatchedProbes = new Map();
         const agentById = new Map(agents.map(a => [a.id, a]));
-        let steps = 0;
-        let totalToolCalls = 0;
-        const counters = {
-            warmPrefillCalls: 0,
-            warmPrefillBranches: 0,
-        };
-        // ── Four-phase tick loop ─────────────────────────────────
-        for (;;) {
-            // -- Phase 1: PRODUCE -- sample from active agents, collect tool calls
-            const pressure = new ContextPressure(ctx, pressureOpts);
-            if (trace && (pressure.critical || pressure.headroom < 0)) {
-                try {
-                    process.stderr.write(`[PRODUCE] ${pressure.critical ? 'CRITICAL' : 'SOFT_LIMIT'} remaining=${pressure.remaining} headroom=${pressure.headroom} cellsUsed=${pressure.cellsUsed} nCtx=${pressure.nCtx}\n`);
-                }
-                catch { }
-            }
-            const entries = [];
-            const toolCalls = [];
-            for (const a of agents) {
-                if (a.status !== 'active')
-                    continue;
-                const policyExit = policy.shouldExit?.(a, pressure);
-                if (policyExit ?? pressure.critical) {
-                    a.transition('idle');
-                    const exitReason = pressure.critical ? 'pressure_critical'
-                        : policyExit ? 'policy_exit'
-                            : 'pressure_critical';
-                    tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-                        type: 'pool:agentDrop', agentId: a.id, reason: exitReason });
-                    yield* events.send({ type: 'agent:done', agentId: a.id });
-                    continue;
+        // Subscribe BEFORE spawning tick loop — no events missed
+        const subscription = yield* poolChannel;
+        // Spawn tick loop — runs concurrently with Subscription consumption.
+        // scoped() creates an error boundary: if llama_decode fails (KV exhaustion),
+        // the scope tears down and the channel closes with whatever results exist.
+        yield* (0, effection_1.spawn)(function* () {
+            let steps = 0;
+            let totalToolCalls = 0;
+            const counters = { warmPrefillCalls: 0, warmPrefillBranches: 0 };
+            try {
+                // Emit spawn events and activate agents
+                for (const a of agents) {
+                    a.transition('active');
+                    yield* poolChannel.send({ type: 'agent:spawn', agentId: a.id, parentAgentId: a.parentId });
                 }
-                const { token, text, isStop } = a.branch.produceSync();
-                if (isStop) {
-                    const parsed = ctx.parseChatOutput(a.rawOutput, a.fmt.format, {
-                        reasoningFormat: a.fmt.reasoningFormat,
-                        generationPrompt: a.fmt.generationPrompt,
-                        parser: a.fmt.parser,
-                    });
-                    tw.write({
-                        traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-                        type: 'agent:turn', agentId: a.id, turn: a.turns,
-                        rawOutput: a.rawOutput,
-                        parsedContent: parsed.content || null,
-                        parsedToolCalls: parsed.toolCalls.map(tc => ({ name: tc.name, arguments: tc.arguments })),
-                    });
-                    // Policy decides what to do with the parsed output
-                    const action = policy.onProduced(a, parsed, pressure, policyConfig);
-                    switch (action.type) {
-                        case 'free_text_report':
-                            a.reportResult(action.content, 'free_text');
-                            a.transition('idle');
-                            yield* events.send({ type: 'agent:report', agentId: a.id, result: a.result });
-                            yield* events.send({ type: 'agent:done', agentId: a.id });
+                // ── Phase operations (close over pool scope) ────────────
+                /** SETTLE: prefill tool results that fit, defer oversized items for next tick */
+                function* settle(items) {
+                    const settlePressure = new ContextPressure(ctx, pressureOpts);
+                    let headroom = settlePressure.headroom;
+                    if (trace) {
+                        const desc = items.map(s => `${s.toolName}:${s.prefillTokens.length}`).join(', ');
+                        try {
+                            process.stderr.write(`[SETTLE] remaining=${settlePressure.remaining} headroom=${headroom} cellsUsed=${settlePressure.cellsUsed} nCtx=${settlePressure.nCtx} items=[${desc}]\n`);
+                        }
+                        catch { }
+                    }
+                    const prefillPairs = [];
+                    const settledAgents = [];
+                    const deferred = [];
+                    for (const item of items) {
+                        const a = agentById.get(item.agentId);
+                        if (!a || a.status === 'idle')
                             continue;
-                        case 'idle':
-                            a.transition('idle');
-                            if (action.reason !== 'free_text_stop') {
-                                tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-                                    type: 'pool:agentDrop', agentId: a.id,
-                                    reason: action.reason === 'max_turns' ? 'maxTurns' : 'pressure_softcut' });
+                        if (item.prefillTokens.length > headroom) {
+                            if (trace) {
+                                try {
+                                    process.stderr.write(`[SETTLE] DEFER ${item.toolName}:${item.prefillTokens.length} > headroom=${headroom}\n`);
+                                }
+                                catch { }
                             }
-                            yield* events.send({ type: 'agent:done', agentId: a.id });
-                            continue;
-                        case 'nudge': {
-                            const tc = parsed.toolCalls[0];
-                            const callId = tc?.id || `call_${a.toolCallCount}`;
-                            const nudgeMsg = JSON.stringify({ error: action.message });
-                            a.incrementTurns();
-                            a.transition('awaiting_tool');
-                            const prefillTokens = (0, sdk_2.buildToolResultDelta)(ctx, nudgeMsg, callId);
-                            settledBuffer.push({ agentId: a.id, prefillTokens, toolName: tc?.name || '', callId });
-                            a.resetTurn();
-                            tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-                                type: 'pool:agentNudge', agentId: a.id, reason: 'pressure_softcut' });
+                            deferred.push(item);
                             continue;
                         }
-                        case 'report':
-                            a.reportResult(action.result, 'report_tool');
-                            a.transition('idle');
-                            a.incrementToolCalls();
-                            totalToolCalls++;
-                            yield* events.send({ type: 'agent:tool_call', agentId: a.id, tool: terminalTool, args: parsed.toolCalls[0].arguments });
-                            yield* events.send({ type: 'agent:report', agentId: a.id, result: a.result });
-                            yield* events.send({ type: 'agent:done', agentId: a.id });
-                            if (pruneOnReport && !a.branch.disposed) {
-                                a.branch.pruneSync();
-                            }
-                            continue;
-                        case 'tool_call':
-                            a.transition('awaiting_tool');
-                            toolCalls.push({ agent: a, tc: action.tc });
-                            a.resetTurn();
-                            continue;
-                    }
-                }
-                entries.push([a.branch, token]);
-                if (trace) {
-                    const entropy = a.branch.modelEntropy();
-                    const surprisal = a.branch.modelSurprisal(token);
-                    a.accumulateTokenWithTrace(text, entropy, surprisal);
-                    yield* events.send({
-                        type: 'agent:produce', agentId: a.id, text, tokenCount: a.tokenCount,
-                        entropy, surprisal,
-                    });
-                }
-                else {
-                    a.accumulateToken(text);
-                    yield* events.send({ type: 'agent:produce', agentId: a.id, text, tokenCount: a.tokenCount });
-                }
-            }
-            // -- Phase 2: COMMIT -- batch-decode produced tokens
-            if (entries.length > 0) {
-                yield* (0, effection_1.call)(() => store.commit(entries));
-                steps++;
-                const commitPressure = new ContextPressure(ctx, pressureOpts);
-                yield* events.send({ type: 'agent:tick', cellsUsed: commitPressure.cellsUsed, nCtx: commitPressure.nCtx });
-            }
-            // -- Phase 3: SETTLE -- drain settled tool buffer, batch prefill
-            const settled = settledBuffer.splice(0);
-            if (settled.length > 0) {
-                // Fresh snapshot — Phase 2 commits may have advanced positions
-                const settlePressure = new ContextPressure(ctx, pressureOpts);
-                let headroom = settlePressure.headroom;
-                if (trace) {
-                    const items = settled.map(s => `${s.toolName}:${s.prefillTokens.length}`).join(', ');
-                    try {
-                        process.stderr.write(`[SETTLE] remaining=${settlePressure.remaining} headroom=${headroom} cellsUsed=${settlePressure.cellsUsed} nCtx=${settlePressure.nCtx} items=[${items}]\n`);
+                        prefillPairs.push([a.branch, item.prefillTokens]);
+                        settledAgents.push(a);
+                        headroom -= item.prefillTokens.length;
+                        const postSettle = new ContextPressure(ctx, pressureOpts);
+                        a.recordToolResult({
+                            name: item.toolName, args: item.args,
+                            resultTokenCount: item.prefillTokens.length,
+                            contextAfterPercent: postSettle.percentAvailable,
+                            timestamp: performance.now(),
+                        });
+                        tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
+                            type: 'branch:prefill', branchHandle: a.id,
+                            tokenCount: item.prefillTokens.length, role: 'toolResult' });
                     }
-                    catch { }
-                }
-                const prefillPairs = [];
-                const settledAgents = [];
-                for (const item of settled) {
-                    const a = agentById.get(item.agentId);
-                    if (!a || a.status === 'idle')
-                        continue;
-                    if (item.prefillTokens.length > headroom) {
+                    if (prefillPairs.length > 0) {
                         if (trace) {
+                            const total = prefillPairs.reduce((s, [, t]) => s + t.length, 0);
                             try {
-                                process.stderr.write(`[SETTLE] REJECT ${item.toolName}:${item.prefillTokens.length} > headroom=${headroom}\n`);
+                                process.stderr.write(`[SETTLE] PREFILL ${prefillPairs.length} branches, ${total} tokens, headroom_after=${headroom}\n`);
                             }
                             catch { }
                         }
-                        const settleAction = policy.onSettleReject(a, item.prefillTokens.length, settlePressure, policyConfig);
-                        if (settleAction.type === 'nudge') {
-                            const nudgeMsg = JSON.stringify({ error: settleAction.message });
-                            const nudgeTokens = (0, sdk_2.buildToolResultDelta)(ctx, nudgeMsg, item.callId);
-                            if (nudgeTokens.length <= headroom) {
-                                prefillPairs.push([a.branch, nudgeTokens]);
-                                settledAgents.push(a);
-                                headroom -= nudgeTokens.length;
+                        yield* (0, effection_1.call)(() => store.prefill(prefillPairs));
+                        counters.warmPrefillCalls++;
+                        counters.warmPrefillBranches += prefillPairs.length;
+                        // Probe prefill from DISPATCH
+                        const probePairs = [];
+                        for (const a of settledAgents) {
+                            const probe = items.find(s => s.agentId === a.id)?.probe;
+                            if (probe) {
+                                const probeTokens = ctx.tokenizeSync(probe, false);
+                                probePairs.push([a.branch, probeTokens]);
                                 tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-                                    type: 'pool:agentNudge', agentId: a.id, reason: 'pressure_settle_reject' });
-                                continue;
+                                    type: 'branch:prefill', branchHandle: a.id,
+                                    tokenCount: probeTokens.length, role: 'probe', probeText: probe });
                             }
                         }
-                        // Nudge failed (tokens don't fit) or policy said kill
-                        tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-                            type: 'pool:agentDrop', agentId: a.id, reason: 'pressure_settle_reject' });
-                        a.transition('idle');
-                        yield* events.send({ type: 'agent:done', agentId: a.id });
-                        continue;
+                        if (probePairs.length > 0) {
+                            yield* (0, effection_1.call)(() => store.prefill(probePairs));
+                        }
+                        for (const a of settledAgents) {
+                            a.transition('active');
+                            a.resetTurn();
+                            applyLazyGrammar(a);
+                        }
                     }
-                    prefillPairs.push([a.branch, item.prefillTokens]);
-                    settledAgents.push(a);
-                    headroom -= item.prefillTokens.length;
-                    // Record tool history for policy decisions
-                    const postSettle = new ContextPressure(ctx, pressureOpts);
-                    a.recordToolResult({
-                        name: item.toolName,
-                        args: item.callId,
-                        resultTokenCount: item.prefillTokens.length,
-                        contextAfterPercent: postSettle.percentAvailable,
-                        timestamp: performance.now(),
-                    });
-                    tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-                        type: 'branch:prefill', branchHandle: a.id,
-                        tokenCount: item.prefillTokens.length, role: 'toolResult' });
+                    return deferred;
                 }
-                if (prefillPairs.length > 0) {
-                    if (trace) {
-                        const totalPrefill = prefillPairs.reduce((s, [, t]) => s + t.length, 0);
+                /** DISPATCH: execute tool calls sequentially, return settled items for next tick */
+                function* dispatch(calls) {
+                    const results = [];
+                    for (const { agent, tc } of calls) {
+                        let toolArgs;
                         try {
-                            process.stderr.write(`[SETTLE] PREFILL ${prefillPairs.length} branches, ${totalPrefill} tokens, headroom_after=${headroom}\n`);
+                            toolArgs = JSON.parse(tc.arguments);
+                        }
+                        catch {
+                            toolArgs = {};
+                        }
+                        const callId = tc.id || `call_${agent.toolCallCount}`;
+                        agent.incrementToolCalls();
+                        totalToolCalls++;
+                        agent.incrementTurns();
+                        yield* poolChannel.send({ type: 'agent:tool_call', agentId: agent.id, tool: tc.name, args: tc.arguments });
+                        const tool = tools.get(tc.name);
+                        const dispatchPressure = new ContextPressure(ctx, pressureOpts);
+                        const explore = policy.shouldExplore?.(agent, dispatchPressure) ?? true;
+                        const dispatchTraceId = tw.nextId();
+                        const toolT0 = performance.now();
+                        tw.write({
+                            traceId: dispatchTraceId, parentTraceId: poolScope.traceId, ts: toolT0,
+                            type: 'tool:dispatch', agentId: agent.id, tool: tc.name,
+                            toolIndex: toolIndexMap.get(tc.name) ?? -1, toolkitSize,
+                            args: toolArgs, callId,
+                            explore, percentAvailable: dispatchPressure.percentAvailable,
+                        });
+                        const peerHistory = agents
+                            .filter(a => a.id !== agent.id)
+                            .flatMap(a => a.toolHistory);
+                        const toolContext = {
+                            agentId: agent.id, branch: agent.branch,
+                            onProgress: (p) => {
+                                progressBridge.send({ type: 'agent:tool_progress', agentId: agent.id, tool: tc.name, filled: p.filled, total: p.total });
+                            },
+                            scorer: opts.scorer, explore,
+                            pressurePercentAvailable: dispatchPressure.percentAvailable,
+                            peerHistory,
+                        };
+                        try {
+                            yield* context_1.TraceParent.set(dispatchTraceId);
+                            yield* context_1.CallingAgent.set(agent);
+                            const result = yield* (0, effection_1.scoped)(function* () {
+                                return yield* (0, effection_1.call)(() => tool ? tool.execute(toolArgs, toolContext) : Promise.resolve({ error: `Unknown tool: ${tc.name}` }));
+                            });
+                            const postToolPressure = new ContextPressure(ctx, pressureOpts);
+                            const contextAvailablePercent = postToolPressure.percentAvailable;
+                            if (result && typeof result === 'object' && !Array.isArray(result)) {
+                                result._contextAvailablePercent = contextAvailablePercent;
+                                const resultObj = result;
+                                if (Array.isArray(resultObj.results)) {
+                                    agent.addNestedResults(resultObj.results.filter((f) => typeof f === 'string'));
+                                }
+                                if (Array.isArray(resultObj.nestedResults)) {
+                                    agent.addNestedResults(resultObj.nestedResults.filter((f) => typeof f === 'string'));
+                                }
+                            }
+                            const resultStr = JSON.stringify(result);
+                            yield* poolChannel.send({ type: 'agent:tool_result', agentId: agent.id, tool: tc.name, result: resultStr, contextAvailablePercent });
+                            const prefillTokens = (0, sdk_2.buildToolResultDelta)(ctx, resultStr, callId);
+                            const probe = tool?.probe(result) ?? undefined;
+                            results.push({ agentId: agent.id, prefillTokens, toolName: tc.name, callId, args: tc.arguments, probe });
+                            tw.write({ traceId: tw.nextId(), parentTraceId: dispatchTraceId, ts: performance.now(),
+                                type: 'tool:result', agentId: agent.id, tool: tc.name,
+                                result, prefillTokenCount: prefillTokens.length,
+                                durationMs: performance.now() - toolT0 });
+                        }
+                        catch (err) {
+                            agent.transition('idle');
+                            agent.reportResult(`Tool error: ${err.message}`, 'tool_error');
+                            tw.write({ traceId: tw.nextId(), parentTraceId: dispatchTraceId, ts: performance.now(),
+                                type: 'tool:error', agentId: agent.id, tool: tc.name,
+                                error: err.message });
                         }
-                        catch { }
                     }
-                    yield* (0, effection_1.call)(() => store.prefill(prefillPairs));
-                    counters.warmPrefillCalls++;
-                    counters.warmPrefillBranches += prefillPairs.length;
-                    // Prefill per-tool reasoning probes for agents that just got real
-                    // tool results. Each tool can optionally return a probe string via
-                    // its `probe` getter — prefilled after the tool result to nudge the
-                    // model into prose reasoning before the next tool call.
-                    const probePairs = [];
-                    for (const a of settledAgents) {
-                        const probe = dispatchedProbes.get(a.id);
-                        if (probe)
-                            probePairs.push([a.branch, ctx.tokenizeSync(probe, false)]);
+                    return results;
+                }
+                // ── Four-phase tick loop ─────────────────────────────────
+                let pendingSettled = [];
+                // ── Four-phase tick loop ─────────────────────────────────
+                let recoveryAttempted = false;
+                for (;;) {
+                    // -- Phase 1: PRODUCE -- sample from active agents, collect tool calls
+                    policy.resetTick?.();
+                    const pressure = new ContextPressure(ctx, pressureOpts);
+                    if (trace && (pressure.critical || pressure.headroom < 0)) {
+                        try {
+                            process.stderr.write(`[PRODUCE] ${pressure.critical ? 'CRITICAL' : 'SOFT_LIMIT'} remaining=${pressure.remaining} headroom=${pressure.headroom} cellsUsed=${pressure.cellsUsed} nCtx=${pressure.nCtx}\n`);
+                        }
+                        catch { }
                     }
-                    if (probePairs.length > 0) {
-                        yield* (0, effection_1.call)(() => store.prefill(probePairs));
+                    const entries = [];
+                    const toolCalls = [];
+                    const nudges = [];
+                    for (const a of agents) {
+                        if (a.status !== 'active')
+                            continue;
+                        const policyExit = policy.shouldExit?.(a, pressure);
+                        if (policyExit ?? pressure.critical) {
+                            a.transition('idle');
+                            const exitReason = pressure.critical ? 'pressure_critical'
+                                : policyExit ? 'policy_exit'
+                                    : 'pressure_critical';
+                            tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
+                                type: 'pool:agentDrop', agentId: a.id, reason: exitReason });
+                            yield* poolChannel.send({ type: 'agent:done', agentId: a.id });
+                            // Trailing stop: extract findings inline, free KV for remaining agents
+                            yield* recoverInline(a, policy, ctx, store, tw, poolScope.traceId, poolChannel);
+                            continue;
+                        }
+                        const { token, text, isStop } = a.branch.produceSync();
+                        if (isStop) {
+                            const parsed = a.finalize(ctx);
+                            tw.write({
+                                traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
+                                type: 'agent:turn', agentId: a.id, turn: a.turns,
+                                rawOutput: a.rawOutput,
+                                parsedContent: parsed.content || null,
+                                parsedToolCalls: parsed.toolCalls.map(tc => ({ name: tc.name, arguments: tc.arguments })),
+                            });
+                            // Policy decides what to do with the parsed output
+                            const action = policy.onProduced(a, parsed, pressure, policyConfig);
+                            switch (action.type) {
+                                case 'free_text_report':
+                                    yield* handleFreeTextReport(a, action.content, poolChannel);
+                                    continue;
+                                case 'idle':
+                                    yield* handleIdleDrop(a, action.reason, poolChannel, tw, poolScope.traceId);
+                                    continue;
+                                case 'nudge':
+                                    nudges.push(yield* handleNudge(a, action.message, parsed.toolCalls[0], ctx, tools));
+                                    tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
+                                        type: 'pool:agentNudge', agentId: a.id, reason: 'nudge', message: action.message });
+                                    continue;
+                                case 'report':
+                                    yield* handleReport(a, action.result, parsed.toolCalls[0], terminalTool, pruneOnReport, poolChannel);
+                                    totalToolCalls++;
+                                    continue;
+                                case 'tool_call':
+                                    a.transition('awaiting_tool');
+                                    toolCalls.push({ agent: a, tc: action.tc });
+                                    a.resetTurn();
+                                    continue;
+                            }
+                        }
+                        entries.push([a.branch, token]);
+                        if (trace) {
+                            const entropy = a.branch.modelEntropy();
+                            const surprisal = a.branch.modelSurprisal(token);
+                            a.accumulateTokenWithTrace(text, entropy, surprisal);
+                            a.observe(ctx);
+                            yield* poolChannel.send({
+                                type: 'agent:produce', agentId: a.id, text, tokenCount: a.tokenCount,
+                                entropy, surprisal,
+                            });
+                        }
+                        else {
+                            a.accumulateToken(text);
+                            a.observe(ctx);
+                            yield* poolChannel.send({ type: 'agent:produce', agentId: a.id, text, tokenCount: a.tokenCount });
+                        }
                     }
-                    dispatchedProbes.clear();
-                    // Only NOW transition state + reset grammar
-                    for (const a of settledAgents) {
-                        a.transition('active');
-                        a.resetTurn();
-                        applyLazyGrammar(a);
+                    // -- Phase 2: COMMIT -- batch-decode produced tokens
+                    if (entries.length > 0) {
+                        yield* (0, effection_1.call)(() => store.commit(entries));
+                        steps++;
+                        const commitPressure = new ContextPressure(ctx, pressureOpts);
+                        yield* poolChannel.send({ type: 'agent:tick', cellsUsed: commitPressure.cellsUsed, nCtx: commitPressure.nCtx });
                     }
-                }
-            }
-            // -- Phase 4: DISPATCH -- execute collected tool calls sequentially
-            // scoped() creates an error boundary — inner pool errors are caught
-            // here instead of crashing the outer pool. call() yields the Operation
-            // directly, ensuring exclusive llama_context access (no concurrent
-            // AsyncWorkers). See docs/agents/concurrency.md.
-            for (const { agent, tc } of toolCalls) {
-                let toolArgs;
-                try {
-                    toolArgs = JSON.parse(tc.arguments);
-                }
-                catch {
-                    toolArgs = {};
-                }
-                const callId = tc.id || `call_${agent.toolCallCount}`;
-                agent.incrementToolCalls();
-                totalToolCalls++;
-                agent.incrementTurns();
-                yield* events.send({ type: 'agent:tool_call', agentId: agent.id, tool: tc.name, args: tc.arguments });
-                const tool = tools.get(tc.name);
-                // Fresh pressure snapshot — SETTLE may have consumed significant KV
-                // since the PRODUCE-phase snapshot at tick-top. On 16K context, a
-                // single SETTLE pass can drain 12-18% of capacity (3 agents' tool
-                // results). Using stale PRODUCE pressure here would keep agents in
-                // explore mode past the threshold.
-                const dispatchPressure = new ContextPressure(ctx, pressureOpts);
-                const explore = policy.shouldExplore?.(agent, dispatchPressure) ?? true;
-                const dispatchTraceId = tw.nextId();
-                const toolT0 = performance.now();
-                tw.write({
-                    traceId: dispatchTraceId, parentTraceId: poolScope.traceId, ts: toolT0,
-                    type: 'tool:dispatch', agentId: agent.id, tool: tc.name,
-                    toolIndex: toolIndexMap.get(tc.name) ?? -1, toolkitSize,
-                    args: toolArgs, callId,
-                    explore, percentAvailable: dispatchPressure.percentAvailable,
-                });
-                const toolContext = {
-                    agentId: agent.id,
-                    branch: agent.branch,
-                    onProgress: (p) => {
-                        progressBridge.send({ type: 'agent:tool_progress', agentId: agent.id, tool: tc.name, filled: p.filled, total: p.total });
-                    },
-                    scorer: opts.scorer,
-                    explore,
-                    pressurePercentAvailable: dispatchPressure.percentAvailable,
-                };
-                try {
-                    // Set TraceParent + CallingAgent so inner pools inherit lineage
-                    yield* context_1.TraceParent.set(dispatchTraceId);
-                    yield* context_1.CallingAgent.set(agent);
-                    const result = yield* (0, effection_1.scoped)(function* () {
-                        return yield* (0, effection_1.call)(() => tool ? tool.execute(toolArgs, toolContext) : Promise.resolve({ error: `Unknown tool: ${tc.name}` }));
-                    });
-                    // Inject context availability into tool result so agent can make pressure-aware decisions
-                    const postToolPressure = new ContextPressure(ctx, pressureOpts);
-                    const contextAvailablePercent = postToolPressure.percentAvailable;
-                    if (result && typeof result === 'object' && !Array.isArray(result)) {
-                        result._contextAvailablePercent = contextAvailablePercent;
-                        // Collect nested results from recursive tool returns
-                        const resultObj = result;
-                        if (Array.isArray(resultObj.results)) {
-                            agent.addNestedResults(resultObj.results.filter((f) => typeof f === 'string'));
-                        }
-                        if (Array.isArray(resultObj.nestedResults)) {
-                            agent.addNestedResults(resultObj.nestedResults.filter((f) => typeof f === 'string'));
+                    // -- Phase 3: SETTLE (settle what fits, defer what doesn't)
+                    const toSettle = [...pendingSettled, ...nudges];
+                    const deferred = toSettle.length > 0 ? yield* settle(toSettle) : [];
+                    // Stall-breaker: if items are deferred and no active agents remain,
+                    // sacrifice an awaiting_tool agent to free KV. Without this, agents
+                    // with oversized results stay awaiting_tool indefinitely — PRODUCE
+                    // skips them, headroom never recovers, the pool loops forever.
+                    if (deferred.length > 0 && !agents.some(a => a.status === 'active')) {
+                        const victim = agents.find(a => a.status === 'awaiting_tool' && !a.branch.disposed);
+                        if (victim) {
+                            victim.transition('idle');
+                            tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
+                                type: 'pool:agentDrop', agentId: victim.id, reason: 'pressure_settle_reject' });
+                            yield* poolChannel.send({ type: 'agent:done', agentId: victim.id });
+                            yield* recoverInline(victim, policy, ctx, store, tw, poolScope.traceId, poolChannel);
                         }
                     }
-                    const resultStr = JSON.stringify(result);
-                    yield* events.send({ type: 'agent:tool_result', agentId: agent.id, tool: tc.name, result: resultStr, contextAvailablePercent });
-                    const prefillTokens = (0, sdk_2.buildToolResultDelta)(ctx, resultStr, callId);
-                    settledBuffer.push({ agentId: agent.id, prefillTokens, toolName: tc.name, callId });
-                    const probe = tool?.probe;
-                    if (probe)
-                        dispatchedProbes.set(agent.id, probe);
-                    tw.write({
-                        traceId: tw.nextId(), parentTraceId: dispatchTraceId, ts: performance.now(),
-                        type: 'tool:result', agentId: agent.id, tool: tc.name,
-                        result, prefillTokenCount: prefillTokens.length,
-                        durationMs: performance.now() - toolT0,
-                    });
-                }
-                catch (err) {
-                    agent.transition('idle');
-                    agent.reportResult(`Tool error: ${err.message}`, 'tool_error');
-                    tw.write({
-                        traceId: tw.nextId(), parentTraceId: dispatchTraceId, ts: performance.now(),
-                        type: 'tool:error', agentId: agent.id, tool: tc.name,
-                        error: err.message,
-                    });
-                }
-            }
-            // -- Termination
-            if (agents.every(a => a.status === 'idle' || a.status === 'disposed'))
-                break;
-        }
-        // ── Idle processing: scratchpad recovery ─────────────────
-        // Policy decides per-agent whether to extract findings from killed agents.
-        // The pool owns the grammar and fork/generate/parse mechanics.
-        // Free KV from agents that already reported — gives room for extraction.
-        for (const a of agents) {
-            if (a.result && !a.branch.disposed) {
-                a.branch.pruneSync();
-            }
-        }
-        // Check if any agent needs recovery before setting up grammar
-        const needsRecovery = agents.some(a => a.status === 'idle' && !a.result && !a.branch.disposed &&
-            policy.onRecovery?.(a)?.type === 'extract');
-        if (needsRecovery) {
-            const reportSchema = {
-                type: 'object',
-                properties: { result: { type: 'string' } },
-                required: ['result'],
-            };
-            const reportGrammar = yield* (0, effection_1.call)(() => ctx.jsonSchemaToGrammar(JSON.stringify(reportSchema)));
-            // Cache formatted prompts per unique prompt object
-            const promptCache = new Map();
-            for (const a of agents) {
-                if (a.status !== 'idle' || a.result || a.branch.disposed)
-                    continue;
-                const recovery = policy.onRecovery?.(a);
-                if (!recovery || recovery.type === 'skip') {
-                    if (!a.branch.disposed)
-                        a.branch.pruneSync();
-                    continue;
-                }
-                // Format extraction prompt (cache by system+user key)
-                const cacheKey = recovery.prompt.system + '\0' + recovery.prompt.user;
-                let extractionPromptStr = promptCache.get(cacheKey);
-                if (!extractionPromptStr) {
-                    const reportMessages = [
-                        { role: 'system', content: recovery.prompt.system },
-                        { role: 'user', content: recovery.prompt.user },
-                    ];
-                    const { prompt } = ctx.formatChatSync(JSON.stringify(reportMessages), { enableThinking: false });
-                    extractionPromptStr = prompt;
-                    promptCache.set(cacheKey, prompt);
-                }
-                try {
-                    yield* events.send({ type: 'agent:spawn', agentId: a.id, parentAgentId: a.parentId });
-                    const branch = yield* (0, generate_1.prepare)({
-                        prompt: extractionPromptStr,
-                        grammar: reportGrammar,
-                        parent: a.branch,
-                    });
-                    try {
-                        let output = '';
-                        let tokenCount = 0;
-                        yield* (0, effection_1.call)(async () => {
-                            for await (const { text } of branch) {
-                                output += text;
-                                tokenCount++;
+                    // -- Phase 4: DISPATCH
+                    const dispatched = yield* dispatch(toolCalls);
+                    // Deferred + new dispatch results → next tick's SETTLE
+                    pendingSettled = [...deferred, ...dispatched];
+                    // -- Termination + recovery
+                    if (agents.every(a => a.status === 'idle' || a.status === 'disposed')) {
+                        if (!recoveryAttempted) {
+                            recoveryAttempted = true;
+                            // Recover any idle agents that weren't handled by inline recovery
+                            // (e.g., killed by max_turns, time budget, or free_text_stop)
+                            for (const a of agents) {
+                                if (a.status === 'idle' && !a.result && !a.branch.disposed) {
+                                    yield* recoverInline(a, policy, ctx, store, tw, poolScope.traceId, poolChannel);
+                                }
                             }
-                        });
-                        const tickPressure = new ContextPressure(ctx, pressureOpts);
-                        yield* events.send({
-                            type: 'agent:tick', cellsUsed: tickPressure.cellsUsed, nCtx: tickPressure.nCtx,
-                        });
-                        const parsed = JSON.parse(output);
-                        if (parsed?.result) {
-                            a.reportResult(parsed.result, 'scratchpad');
-                            yield* events.send({ type: 'agent:report', agentId: a.id, result: a.result });
                         }
+                        break;
                     }
-                    finally {
-                        if (!branch.disposed)
-                            branch.pruneSync();
-                    }
-                }
-                catch {
-                    /* extraction failure non-fatal */
                 }
-                if (!a.branch.disposed)
-                    a.branch.pruneSync();
+                // ── Close channel with result — consumers get AgentPoolResult as close value ───────
+                // Branch cleanup is handled by each branch's ensure() from setupAgent —
+                // when this resource's scope exits, all ensure() callbacks fire.
+                tw.write({
+                    traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
+                    type: 'pool:close',
+                    agents: agents.map(a => ({
+                        agentId: a.id, tokenCount: a.tokenCount,
+                        toolCallCount: a.toolCallCount, result: a.result,
+                        ppl: a.branch.disposed ? 0 : a.branch.perplexity,
+                    })),
+                    totalTokens: agents.reduce((s, a) => s + a.tokenCount, 0),
+                    steps, durationMs: performance.now() - poolT0,
+                });
+                poolScope.close();
+                const result = {
+                    agents: agents.map(a => ({
+                        agentId: a.id,
+                        parentAgentId: a.parentId,
+                        branch: a.branch,
+                        agent: a,
+                        result: a.result,
+                        toolCallCount: a.toolCallCount,
+                        tokenCount: a.tokenCount,
+                        ppl: a.branch.disposed ? 0 : a.branch.perplexity,
+                        samplingPpl: a.branch.disposed ? 0 : a.branch.samplingPerplexity,
+                        trace: trace ? a.traceBuffer : undefined,
+                        nestedResults: [...a.nestedResults],
+                    })),
+                    totalTokens: agents.reduce((s, a) => s + a.tokenCount, 0),
+                    totalToolCalls,
+                    steps,
+                    counters,
+                };
+                yield* poolChannel.close(result);
             }
-        }
-        // ── Provide result — suspends, branches stay alive ───────
-        // Branch cleanup is handled by each branch's ensure() from setupAgent —
-        // when this resource's scope exits, all ensure() callbacks fire.
-        tw.write({
-            traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
-            type: 'pool:close',
-            agents: agents.map(a => ({
-                agentId: a.id, tokenCount: a.tokenCount,
-                toolCallCount: a.toolCallCount, result: a.result,
-                ppl: a.branch.disposed ? 0 : a.branch.perplexity,
-            })),
-            totalTokens: agents.reduce((s, a) => s + a.tokenCount, 0),
-            steps, durationMs: performance.now() - poolT0,
-        });
-        poolScope.close();
-        const result = {
-            agents: agents.map(a => ({
-                agentId: a.id,
-                parentAgentId: a.parentId,
-                branch: a.branch,
-                result: a.result,
-                toolCallCount: a.toolCallCount,
-                tokenCount: a.tokenCount,
-                ppl: a.branch.disposed ? 0 : a.branch.perplexity,
-                samplingPpl: a.branch.disposed ? 0 : a.branch.samplingPerplexity,
-                trace: trace ? a.traceBuffer : undefined,
-                nestedResults: [...a.nestedResults],
-            })),
-            totalTokens: agents.reduce((s, a) => s + a.tokenCount, 0),
-            totalToolCalls,
-            steps,
-            counters,
-        };
-        yield* provide(result);
+            catch {
+                // KV exhaustion or other decode failure — close with partial results
+                poolScope.close();
+                const partial = {
+                    agents: agents.map(a => ({
+                        agentId: a.id, parentAgentId: a.parentId, branch: a.branch, agent: a,
+                        result: a.result, toolCallCount: a.toolCallCount, tokenCount: a.tokenCount,
+                        ppl: a.branch.disposed ? 0 : a.branch.perplexity,
+                        samplingPpl: a.branch.disposed ? 0 : a.branch.samplingPerplexity,
+                        trace: trace ? a.traceBuffer : undefined,
+                        nestedResults: [...a.nestedResults],
+                    })),
+                    totalTokens: agents.reduce((s, a) => s + a.tokenCount, 0),
+                    totalToolCalls, steps, counters,
+                };
+                yield* poolChannel.close(partial);
+            }
+        }); // end spawn — tick loop
+        yield* provide(subscription);
     });
 }
 //# sourceMappingURL=agent-pool.js.map