loopengine 0.0.20 → 0.1.2

package/dist/core/run-agent.js

@@ -9,13 +9,16 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { Gate, RuleSet, ConsoleApprover } from 'actauth';
 import { SkillGarden } from 'skillgarden';
-import { ContextClipper } from 'contextclip';
+import { BudgetTracker } from './budget.js';
+import { Compactor } from './compaction.js';
 import { ToolLane } from 'toollane';
-import { Reflow } from 'reflowkit';
+import { Recovery } from './recovery.js';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';
 import { loadGatewayToolsFromDir } from './gateway-tools.js';
-import { systemTools, createAskUserTool } from './system-tools/index.js';
+import { systemTools, createAskUserTool, CliQuestionHandler, isDurableQuestionHandler } from './system-tools/index.js';
+import { resolveHttpNotifier } from './http-notifier.js';
+import { CRASH_RECOVERY_CONTINUATION } from './session-store.js';
 export { systemTools } from './system-tools/index.js';
 // Resolved relative to *this file's own location* (via import.meta.url),
 // not process.cwd() — the same reasoning core/agent-registry.ts's own
@@ -48,16 +51,16 @@ export const systemSkillsDir = join(dirname(fileURLToPath(import.meta.url)), 'sy
 export function dedupeToolsByName(list) {
     return [...new Map(list.map((t) => [t.name, t])).values()];
 }
-/** ContextClip only ever needs a flat string per message to estimate
- * token usage — it doesn't need to understand tool_use/tool_result
+/** budget.ts/compaction.ts only ever need a flat string per message to
+ * estimate token usage — neither needs to understand tool_use/tool_result
  * structure, so this is a one-way, read-only projection, never something
  * that needs to be un-projected back. */
-function flattenForContextClip(message) {
+function flattenForBudget(message) {
     if (typeof message.content === 'string')
         return { role: message.role, content: message.content };
     const text = message.content
         .map((block) => {
-        if (block.type === 'text')
+        if (block.type === 'text' || block.type === 'thinking')
             return block.text ?? '';
         if (block.type === 'tool_use')
             return `[tool_use ${block.name}(${JSON.stringify(block.input)})]`;
@@ -244,7 +247,7 @@ export async function loadSubagentAsTools(config) {
     }
     return tools;
 }
-export async function runAgent(config, modelCall, userMessage, history = [], options = {}) {
+async function buildTurnContext(config, modelCall, options) {
     const log = options.onEvent ?? (() => { });
     // tenant: resolved by the caller (adapters/http.ts calls
     // AgentConfig.tenantFor with the request's headers/body; every other
@@ -295,65 +298,45 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     // Also the tail-preservation window recover() below relies on — kept as
     // one named constant so the two can never drift out of sync.
     const tailMessages = 4;
-    const contextClip = new ContextClipper({ budgetTokens: config.contextBudgetTokens ?? 8000, tailMessages });
+    // Two separate objects, not one — budget.ts's BudgetTracker (read-only
+    // check) and compaction.ts's Compactor (the actual recovery) are
+    // deliberately distinct capabilities now, constructed with the same
+    // budgetTokens/softThreshold so a nudge firing and compaction's own
+    // recovery target agree — see budget.ts's own BudgetTrackerOptions doc
+    // comment.
+    const budgetTracker = new BudgetTracker({ budgetTokens: config.contextBudgetTokens ?? 8000 });
+    const compactor = new Compactor({ budgetTokens: config.contextBudgetTokens ?? 8000, softThreshold: budgetTracker.softThreshold, tailMessages });
     const rules = loadRules(config);
-    const gate = new Gate(rules, config.approver ?? options.approver ?? new ConsoleApprover());
+    // AgentConfig.httpNotifier only ever stands in for the http channel —
+    // see its own doc comment for why cli/http_stream never consult it at
+    // all, not even as a fallback.
+    const httpNotifier = resolveHttpNotifier(config);
+    // httpNotifier.approver, when the http channel has one, wins outright
+    // over options.approver — the same "the agent's own explicit choice for
+    // this channel beats whatever the adapter would otherwise default to"
+    // precedent a channel-keyed override always had here. This ordering
+    // matters in practice, not just on paper: adapters/http.ts's own plain
+    // /messages route always passes *some* options.approver (its own
+    // deployment-wide durable default, or a live tracked one) — checking
+    // httpNotifier first is what lets a single agent's own httpNotifier
+    // actually take effect there, rather than being silently shadowed by
+    // that per-deployment default every time.
+    const approver = (options.channel === 'http' ? httpNotifier.approver : undefined) ?? options.approver ?? new ConsoleApprover();
+    const gate = new Gate(rules, approver);
+    // Exact mirror of approver's own resolution above, same reasoning and
+    // same ordering (httpNotifier checked before options.questionHandler,
+    // not after — see approver's own comment for why that order matters in
+    // practice, not just on paper) — see RunAgentOptions.questionHandler's
+    // own doc comment for the one place this still isn't a full mirror of
+    // approver (only the durable branch below actually reads this; the live
+    // branch keeps resolving independently, via onQuestionPending).
+    const questionHandler = (options.channel === 'http' ? httpNotifier.questionHandler : undefined) ?? options.questionHandler ?? new CliQuestionHandler();
     // No explicit isSafeTool: fall back to each called tool's own `safe`
     // flag (looked up by name) rather than defaulting every tool to unsafe
     // outright — see ToolDefinition.safe's own doc comment for why this is
     // the less powerful of the two (name-only, no per-call nuance).
     const isSafeTool = config.isSafeTool ?? ((call) => tools.some((t) => t.name === call.name && t.safe === true));
     const toolLane = new ToolLane({ isSafe: isSafeTool });
-    let messages = [...history, { role: 'user', content: userMessage }];
-    // Tracked in parallel with `messages`, but never rewritten wholesale by
-    // recovery the way `messages` is — this is the actual, authoritative
-    // answer to "what did this turn add," independent of how many times (if
-    // any) the head of `messages` got drained/summarized along the way. See
-    // pushMessage() below and the reconciliation inside onPromptTooLong.
-    let newMessages = [{ role: 'user', content: userMessage }];
-    function pushMessage(message) {
-        messages.push(message);
-        newMessages.push(message);
-    }
-    const reflow = new Reflow({
-        onPromptTooLong: async (currentMessages) => {
-            // newMessages (this turn's own content — not durably stored
-            // anywhere else yet) must never be handed to ContextClip at all.
-            // An earlier version of this reconciliation tried to recover
-            // newMessages *after* compaction by reusing whatever ContextClip's
-            // synthetic head contained — that's unsound: ContextClip's cheap
-            // "drain" stage doesn't produce a head at all, it just deletes old
-            // messages outright, trusting there's a durable copy elsewhere.
-            // That trust is only valid for the *prior* portion; only that
-            // portion is safe to compact at all.
-            const priorCount = currentMessages.length - newMessages.length;
-            const priorPortion = currentMessages.slice(0, priorCount);
-            const result = await contextClip.recover(priorPortion.map(flattenForContextClip));
-            log({ type: 'reflow:recover', from: currentMessages.length, to: result.messages.length + newMessages.length });
-            if (result.action === 'unchanged')
-                return currentMessages;
-            // Same tail-preservation reuse as before, just scoped to
-            // priorPortion alone now — newMessages is appended back whole,
-            // always, regardless of how large it's grown this turn.
-            const preservedTailCount = Math.min(tailMessages, priorPortion.length);
-            const structuredTail = priorPortion.slice(priorPortion.length - preservedTailCount);
-            const newHead = result.messages.slice(0, result.messages.length - preservedTailCount);
-            const recovered = [...newHead, ...structuredTail, ...newMessages];
-            // Reflow.call() only ever returns {value, recoveries, truncated} —
-            // it never hands back whatever `currentMessages` became after a
-            // retry, so recovery would otherwise only ever affect the one
-            // retried call. Reassigning the outer `messages` binding here (this
-            // hook is the only place that has both the recovered array and a
-            // reason to persist it) is what makes recovery durable: every
-            // subsequent contextClip.check() in this loop, and the `history`
-            // this function eventually returns, both see the compacted
-            // conversation from this point on — not the original, ever-growing
-            // one. newMessages itself needs no reconciliation at all — it was
-            // never part of what could be compacted away.
-            messages = recovered;
-            return recovered;
-        },
-    });
     const toolsByName = new Map(tools.map((t) => [t.name, t]));
     // Object identity, not name — an agent that overrides a system tool's
     // name with its own ToolDefinition (dedupeToolsByName's own "config
@@ -404,6 +387,81 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     // (or ping-ponging) tool calls forever — checked before spending a model
     // call on the (maxTurns + 1)-th turn, not after.
     const maxTurns = config.maxTurns ?? 25;
+    return {
+        modelCall,
+        log,
+        scope,
+        sessionId: options.sessionId,
+        skillGarden,
+        toolsByName,
+        systemToolInstances,
+        toolSchemas,
+        systemPrompt,
+        budgetTracker,
+        compactor,
+        gate,
+        toolLane,
+        maxTurns,
+        tailMessages,
+        askUserTool,
+        questionHandler,
+        httpNotifier,
+    };
+}
+/** The turn's actual ReAct loop — shared by runAgent (a fresh turn, its
+ * own starterMessage is the user's own message) and resumeAgent (a
+ * paused turn's completing tool_result message as starterMessage,
+ * picking up right where run-agent.ts's own bucket-then-execute left
+ * off — see RunAgentResult.stopReason's own 'pending_approval' doc
+ * comment). `messages`/`newMessages` are owned by the caller (built
+ * fresh in each case) but mutated here via pushMessage, same as the
+ * single function this was split out of always did. */
+async function runLoop(ctx, messages, newMessages, starterMessage) {
+    const { modelCall, log, scope, sessionId, skillGarden, toolsByName, systemToolInstances, toolSchemas, systemPrompt, budgetTracker, compactor, gate, toolLane, maxTurns, tailMessages, askUserTool, questionHandler } = ctx;
+    function pushMessage(message) {
+        messages.push(message);
+        newMessages.push(message);
+    }
+    const recovery = new Recovery({
+        onPromptTooLong: async (currentMessages) => {
+            // newMessages (this turn's own content — not durably stored
+            // anywhere else yet) must never be handed to the compactor at all.
+            // An earlier version of this reconciliation tried to recover
+            // newMessages *after* compaction by reusing whatever the
+            // compactor's synthetic head contained — that's unsound: its cheap
+            // "drain" stage doesn't produce a head at all, it just deletes old
+            // messages outright, trusting there's a durable copy elsewhere.
+            // That trust is only valid for the *prior* portion; only that
+            // portion is safe to compact at all.
+            const priorCount = currentMessages.length - newMessages.length;
+            const priorPortion = currentMessages.slice(0, priorCount);
+            const result = await compactor.recover(priorPortion.map(flattenForBudget));
+            log({ type: 'prompt:compaction', from: currentMessages.length, to: result.messages.length + newMessages.length });
+            if (result.action === 'unchanged')
+                return currentMessages;
+            // Same tail-preservation reuse as before, just scoped to
+            // priorPortion alone now — newMessages is appended back whole,
+            // always, regardless of how large it's grown this turn.
+            const preservedTailCount = Math.min(tailMessages, priorPortion.length);
+            const structuredTail = priorPortion.slice(priorPortion.length - preservedTailCount);
+            const newHead = result.messages.slice(0, result.messages.length - preservedTailCount);
+            const recovered = [...newHead, ...structuredTail, ...newMessages];
+            // Recovery.call() only ever returns {value, recoveries, truncated} —
+            // it never hands back whatever `currentMessages` became after a
+            // retry, so recovery would otherwise only ever affect the one
+            // retried call. Reassigning the outer `messages` binding here (this
+            // hook is the only place that has both the recovered array and a
+            // reason to persist it) is what makes recovery durable: every
+            // subsequent budgetTracker.check() in this loop, and the `history`
+            // this function eventually returns, both see the compacted
+            // conversation from this point on — not the original, ever-growing
+            // one. newMessages itself needs no reconciliation at all — it was
+            // never part of what could be compacted away.
+            messages = recovered;
+            return recovered;
+        },
+    });
+    pushMessage(starterMessage);
     let turn = 0;
     for (;;) {
         turn++;
@@ -413,13 +471,18 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             log({ type: 'loop:max_turns', maxTurns });
             return { text, history: messages, newMessages, stopReason: 'max_turns' };
         }
-        const budget = contextClip.check(messages.map(flattenForContextClip));
-        log({ type: 'contextclip:check', ...budget });
+        const budget = budgetTracker.check(messages.map(flattenForBudget));
+        log({ type: 'budget:check', ...budget });
         if (budget.action === 'nudge' && budget.nudge)
             pushMessage(budget.nudge);
-        const { value: response, recoveries } = await reflow.call((msgs) => modelCall(msgs, systemPrompt, toolSchemas), messages);
-        if (recoveries.length > 0)
-            log({ type: 'reflow:recoveries', recoveries });
+        // recovery.call()'s own return also includes `recoveries` (which of
+        // its three failure modes fired this call) and `truncated` — not
+        // used here: prompt:compaction above already reports the one
+        // recovery type that's actually wired to a real hook (onPromptTooLong),
+        // and there's no second type yet to justify a second, more generic
+        // event just to aggregate it (see PromptCompactionEvent's own doc
+        // comment for the removed 'recovery:summary').
+        const { value: response } = await recovery.call((msgs) => modelCall(msgs, systemPrompt, toolSchemas), messages);
         // The model's full response — text and tool_use blocks alike, with
         // real ids — becomes this turn's assistant message verbatim. Every
         // tool_use block emitted here gets a matching tool_result pushed
@@ -447,6 +510,15 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         const resultBlocks = [];
         const approvedCalls = [];
         const deniedTools = [];
+        // A DurableApprover/DurableQuestionHandler deferred this call to a
+        // durable record instead of resolving it inline (see
+        // HUMAN_IN_THE_LOOP.md) — collected separately from
+        // approvedCalls/deniedTools since it's neither run now nor denied now.
+        // No tool_result is pushed for these yet; the batch's post-loop
+        // handling below decides what happens to them. One shared array for
+        // both kinds (not two parallel ones) — see PendingItem's own doc
+        // comment for why a mixed batch has to share one checkpoint.
+        const pending = [];
         // Keyed by tool_use id — approvedCalls (a toollane LaneCall) has no
         // room for extra fields of its own, and toolLane.run's own results
         // only carry `id`/`name`/status, not anything about the *decision*
@@ -464,10 +536,42 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             // so it still needs a tool_result to answer it, same as any other.
             if (block.name === 'Skill' && skillGarden) {
                 const body = skillGarden.invoke(block.input.skill, block.input?.args);
-                log({ type: 'skillgarden:invoke', skill: block.input.skill });
+                log({ type: 'skill:loaded', skill: block.input.skill });
                 resultBlocks.push({ type: 'tool_result', tool_use_id: block.id, content: body });
                 continue;
             }
+            // Checked before the systemToolInstances bypass just below (which
+            // would otherwise auto-run ask_user's own execute() straight away,
+            // in-process) — when the resolved QuestionHandler for this channel
+            // is durable (isDurableQuestionHandler — see its own doc comment,
+            // mirroring Gate's isDurableApprover), a system_ask_user call gets
+            // the exact same bucket-then-execute treatment a durably-gated tool
+            // call gets from gate.evaluate() below, never actually invoking the
+            // tool's own execute()/onPending live path at all. See PendingItem's
+            // own doc comment for why this shares `pending` with approvals
+            // rather than its own separate array. Identity, not name
+            // (`toolsByName.get(...) === askUserTool`, not `block.name ===
+            // 'system_ask_user'`) — same reasoning the systemToolInstances check
+            // just below already uses: an agent that deliberately overrode the
+            // name with its own ToolDefinition must still fall through to
+            // gate.evaluate() like any other tool, not get silently swallowed
+            // into the durable-question bucket just because the name happens to
+            // match. The *live* case (questionHandler resolved to something,
+            // just not durable — including the hard CliQuestionHandler default)
+            // deliberately falls through to the systemToolInstances bypass below
+            // unchanged — see RunAgentOptions.questionHandler's own doc comment
+            // for why that half isn't wired to this resolved value yet.
+            if (toolsByName.get(block.name) === askUserTool && isDurableQuestionHandler(questionHandler)) {
+                const question = String(block.input?.question ?? '');
+                const questionOptions = Array.isArray(block.input?.options) ? block.input.options.map(String) : undefined;
+                const { pendingId } = questionHandler.notifyPendingQuestion(question, questionOptions, scope.agent, sessionId);
+                // No 'tool:started'/'tool:result' here — same reasoning the
+                // durably-gated 'pending' branch below has: nothing to report
+                // until a resolve call answers it, later, possibly in a
+                // different process.
+                pending.push({ kind: 'question', toolUseId: block.id, tool: block.name, args: { question, options: questionOptions }, pendingId, reason: question });
+                continue;
+            }
             // See systemToolInstances' own doc comment above — bypasses
             // gate.evaluate entirely, not just auto-approves through it, since
             // ask_user itself can be the approver's own only way to ask a human
@@ -507,6 +611,15 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
                     execute: () => toolsByName.get(block.name).execute(block.input ?? {}),
                 });
             }
+            else if (decision.decision === 'pending') {
+                // No 'tool:started'/'tool:result' here — unlike a live 'ask',
+                // this call isn't running and isn't decided yet; it genuinely
+                // has nothing to report until a resolve call answers it, later,
+                // possibly in a different process. See 'loop:pending_approval'
+                // below (once every block in the batch is known) for the live
+                // signal this batch needed a durable decision.
+                pending.push({ kind: 'approval', toolUseId: block.id, tool: block.name, args: block.input ?? {}, pendingId: decision.pendingId, reason: decision.reason });
+            }
             else {
                 // Every requested tool gets exactly one tool_result back — a
                 // denied call is not simply dropped, or the model has no way to
@@ -556,6 +669,26 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
                 // just above.
                 log({ type: 'tool:result', id: call.id, tool: call.name, args: approvedMetaById.get(call.id)?.args, detailText: skipReason, statusText: 'Skipped.' });
             }
+            // A pending call/question closes exactly the same way an
+            // approved-but-never-run one does above — see HUMAN_IN_THE_LOOP.md's
+            // own "denial closes the checkpoint immediately" semantics: since
+            // this never actually becomes a checkpoint (the batch is resolved
+            // synchronously right here), there's nothing durable left dangling —
+            // only the DurableApprover's/DurableQuestionHandler's own pendingId
+            // record, orphaned but harmless: a resolve call against it later
+            // finds no checkpoint at all (never created) and no-ops, same as any
+            // other unknown pendingId.
+            for (const pendingItem of pending) {
+                log({ type: 'loop:skipped', name: pendingItem.tool, deniedTools });
+                const skipReason = `a sibling tool call in this turn (${deniedTools.join(', ')}) was denied`;
+                resultBlocks.push({
+                    type: 'tool_result',
+                    tool_use_id: pendingItem.toolUseId,
+                    content: `skipped: ${skipReason}`,
+                    is_error: true,
+                });
+                log({ type: 'tool:result', id: pendingItem.toolUseId, tool: pendingItem.tool, args: pendingItem.args, detailText: skipReason, statusText: 'Skipped.' });
+            }
         }
         else {
             // result.id is the same id LaneCall.id was given above — the exact
@@ -591,6 +724,30 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
                     statusText: result.status === 'fulfilled' ? 'Approved.' : 'Error.',
                 });
             }
+            // At least one call this batch is durably pending — resultBlocks is
+            // incomplete (missing an entry for every pending item) and must
+            // NOT be pushed as the completing tool_result message: a real model
+            // API expects exactly one, complete, tool_result per tool_use
+            // message, not a partial one now and a follow-up later. Stop here
+            // instead — newMessages already ends at the dangling assistant
+            // tool_use message pushed above, the same crash-recovery shape
+            // session-store.ts's own hasUnresolvedToolCall already detects (see
+            // RunAgentResult.stopReason's own doc comment). Turning this into a
+            // durable TurnCheckpoint is the caller's job — this loop does no I/O.
+            if (pending.length > 0) {
+                // A mixed batch (both kinds present) reports 'pending_approval' —
+                // see RunAgentResult.stopReason's own doc comment for why that's
+                // the right call, not an arbitrary tie-break.
+                const stopReason = pending.some((p) => p.kind === 'approval') ? 'pending_approval' : 'pending_question';
+                log({ type: stopReason === 'pending_question' ? 'loop:pending_question' : 'loop:pending_approval', pendingIds: pending.map((p) => p.pendingId) });
+                return {
+                    text: `Stopped — awaiting durable ${stopReason === 'pending_question' ? 'answer' : 'approval'} for: ${pending.map((p) => p.tool).join(', ')}.`,
+                    history: messages,
+                    newMessages,
+                    stopReason,
+                    pending: { resultsSoFar: resultBlocks, outstanding: pending },
+                };
+            }
         }
         pushMessage({ role: 'user', content: resultBlocks });
         // Stop here, don't loop back for another model call — same reasoning
@@ -607,3 +764,101 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         }
     }
 }
+/** Invokes an AgentConfig.onRunStart/onRunFinish callback per its own
+ * never-awaited contract (see AgentConfig's own doc comments on each) —
+ * whether `call()` throws synchronously or returns a rejected Promise,
+ * the failure is logged, never surfaced to (or awaited by) the loop that
+ * triggered it. One shared implementation for both hooks and both of
+ * runAgent/resumeAgent's own call sites, rather than four copies of the
+ * same try/catch-and-maybe-.catch dance. */
+function fireLifecycleHook(label, agentName, call) {
+    try {
+        const result = call();
+        if (result && typeof result.catch === 'function') {
+            result.catch((err) => console.error(`[loopengine] ${label} threw for agent '${agentName}':`, err));
+        }
+    }
+    catch (err) {
+        console.error(`[loopengine] ${label} threw for agent '${agentName}':`, err);
+    }
+}
+/** `cli` and `http_stream` both already deliver the start/finish signal
+ * to whoever's actually waiting, synchronously, as part of that channel's
+ * own normal response — a terminal that just ran the command, or an SSE
+ * connection that already carries its own `session`/`done` events on the
+ * exact same stream. Firing onRunStart/onRunFinish there too would just
+ * be a second, redundant copy of information the caller already has, so
+ * neither hook is invoked for those two channels — not left to each
+ * implementation to notice and filter out itself the way `channel` in
+ * the fired context still lets you filter *within* the channels this
+ * does fire for (`http`, or no channel at all — a bespoke script has no
+ * such guaranteed synchronous delivery to assume either way, so it still
+ * fires there). */
+function shouldFireLifecycleHooks(channel) {
+    return channel !== 'cli' && channel !== 'http_stream';
+}
+export async function runAgent(config, modelCall, userMessage, history = [], options = {}) {
+    const ctx = await buildTurnContext(config, modelCall, options);
+    // config.onRunStart, if set, still wins outright over notifier's own
+    // derived hook — see NotifierConfig's own doc comment on precedence.
+    const onRunStart = config.onRunStart ?? (options.channel === 'http' ? ctx.httpNotifier.onRunStart : undefined);
+    if (onRunStart && shouldFireLifecycleHooks(options.channel)) {
+        fireLifecycleHook('onRunStart', config.name, () => onRunStart({ agent: config.name, tenant: ctx.scope.tenant, sessionId: options.sessionId, channel: options.channel, trigger: 'message' }));
+    }
+    const result = await runLoop(ctx, [...history], [], { role: 'user', content: userMessage });
+    const onRunFinish = config.onRunFinish ?? (options.channel === 'http' ? ctx.httpNotifier.onRunFinish : undefined);
+    if (onRunFinish && !result.pending && shouldFireLifecycleHooks(options.channel)) {
+        fireLifecycleHook('onRunFinish', config.name, () => onRunFinish({ agent: config.name, tenant: ctx.scope.tenant, sessionId: options.sessionId, channel: options.channel, text: result.text, stopReason: result.stopReason }));
+    }
+    return result;
+}
+/** Continues a turn durably paused on RunAgentResult.stopReason ===
+ * 'pending_approval' — see HUMAN_IN_THE_LOOP.md for the full design.
+ * `history` is durable session history including the dangling assistant
+ * tool_use message the pause left behind (exactly what a caller's
+ * SessionStore.getHistory/withSession already returns — this needs no
+ * special resumed-session handling, since that message is real, already
+ * on disk). `resolution` is the *complete* set of tool_result blocks
+ * answering that message — every entry from a resolved TurnCheckpoint's
+ * own resultsSoFar, once its outstanding is empty; assembling that is the
+ * caller's job (core/durable-approvals.ts's own CheckpointStore only
+ * stores it, it doesn't execute tools or know when a batch is complete —
+ * see that module's own doc comment), not something this function
+ * derives on its own.
+ *
+ * Pushes `resolution` as the completing message and picks the loop back
+ * up from there — a fresh model call, now with the full picture, exactly
+ * like a synchronous 'ask' would have continued if it hadn't needed to
+ * pause at all. Can itself return with stopReason 'pending_approval'
+ * again (the model's next round of tool calls hits another durably-gated
+ * one), 'denied', 'max_turns', or a genuine finish — runLoop handles all
+ * of those uniformly regardless of how this turn started. */
+export async function resumeAgent(config, modelCall, history, resolution, options = {}) {
+    const ctx = await buildTurnContext(config, modelCall, options);
+    const onRunStart = config.onRunStart ?? (options.channel === 'http' ? ctx.httpNotifier.onRunStart : undefined);
+    if (onRunStart && shouldFireLifecycleHooks(options.channel)) {
+        fireLifecycleHook('onRunStart', config.name, () => onRunStart({ agent: config.name, tenant: ctx.scope.tenant, sessionId: options.sessionId, channel: options.channel, trigger: 'resolution' }));
+    }
+    // sessions.withSession's own load (adapters/http.ts's respondAfterResolution)
+    // runs through the exact same hasUnresolvedToolCall check real crash
+    // recovery uses — a durable pause deliberately leaves the identical
+    // dangling-tool_use shape (see HUMAN_IN_THE_LOOP.md's own "same
+    // crash-recovery shape... entered on purpose"), so session-store.ts has
+    // no way to tell the two apart and injects its own synthetic
+    // CRASH_RECOVERY_CONTINUATION message regardless. Only resumeAgent
+    // itself knows, by the fact that it's being called at all with a real
+    // resolution in hand, that this wasn't a crash — so it's the only place
+    // that can safely strip that message back out before it ends up wedged
+    // between the assistant's tool_calls message and the tool_result
+    // answering it, which every OpenAI-wire-compatible provider rejects
+    // outright (an assistant message with tool_calls must be immediately
+    // followed by one tool message per call, nothing in between).
+    const lastMessage = history[history.length - 1];
+    const effectiveHistory = lastMessage?.role === 'user' && lastMessage.content === CRASH_RECOVERY_CONTINUATION ? history.slice(0, -1) : history;
+    const result = await runLoop(ctx, [...effectiveHistory], [], { role: 'user', content: resolution });
+    const onRunFinish = config.onRunFinish ?? (options.channel === 'http' ? ctx.httpNotifier.onRunFinish : undefined);
+    if (onRunFinish && !result.pending && shouldFireLifecycleHooks(options.channel)) {
+        fireLifecycleHook('onRunFinish', config.name, () => onRunFinish({ agent: config.name, tenant: ctx.scope.tenant, sessionId: options.sessionId, channel: options.channel, text: result.text, stopReason: result.stopReason }));
+    }
+    return result;
+}

package/dist/core/session-store.d.ts

@@ -6,7 +6,7 @@ export interface SessionResult<T> {
      * This has to come from the caller explicitly (runAgent's own
      * RunAgentResult.newMessages) rather than being inferred by diffing a
      * returned `history` against what withSession loaded: that only works
-     * if history only ever grows, which isn't true once ContextClip
+     * if history only ever grows, which isn't true once compaction.ts's own
      * recovery can shrink/rewrite it mid-turn — see RunAgentResult's own
      * doc comment for the full reasoning. */
     newMessages: Message[];
@@ -42,6 +42,7 @@ export declare class KeyedMutex {
      * work across all keys has settled. */
     size(): number;
 }
+export declare const CRASH_RECOVERY_CONTINUATION = "[session resumed after an interruption \u2014 the assistant had requested tool calls but the process stopped before any results were recorded; treat those tools as not having run]";
 /** Wraps a SessionKnit log behind the flat load/run/append contract
  * runAgent's callers use. Shared by both the file- and Redis-backed
  * stores below — only the Storage and the lock differ. */

package/dist/core/session-store.js

@@ -75,11 +75,13 @@ function hasUnresolvedToolCall(message) {
         Array.isArray(message.content) &&
         message.content.some((block) => block.type === 'tool_use'));
 }
+// Exported so resumeAgent (run-agent.ts) can strip this exact message
+// back out when it turns out the "interruption" wasn't a crash at all —
+// see that constant's own doc comment for why the two can't be told
+// apart at the point sessionknit's own resume() runs.
+export const CRASH_RECOVERY_CONTINUATION = '[session resumed after an interruption — the assistant had requested tool calls but the process stopped before any results were recorded; treat those tools as not having run]';
 function buildContinuation() {
-    return {
-        role: 'user',
-        content: '[session resumed after an interruption — the assistant had requested tool calls but the process stopped before any results were recorded; treat those tools as not having run]',
-    };
+    return { role: 'user', content: CRASH_RECOVERY_CONTINUATION };
 }
 /** Wraps a SessionKnit log behind the flat load/run/append contract
  * runAgent's callers use. Shared by both the file- and Redis-backed

package/dist/core/system-skills/system-skills/composio-large-outputs/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: composio-large-outputs
+description: How to retrieve a gateway tool's real output when its result says storedInFile is true instead of returning the data inline.
+---
+
+# Gateway tools with a large result
+
+Some gateway tools (Composio-sourced ones in particular) return a small
+pointer object instead of their real output when the actual result is
+too large to return inline:
+
+```
+{
+  "successful": true,
+  "storedInFile": true,
+  "tokenCount": 10234,
+  "outputFilePath": "/tmp/.../SOME_TOOL_OUTPUT_xxxxx.json"
+}
+```
+
+When you see `storedInFile: true` in a tool result, the real data is
+**not** in that object — it's in the file at `outputFilePath`. Call
+`system_read_file` with that exact path to retrieve the actual content
+before answering. Don't guess at an answer, summarize from the pointer
+alone, or claim you don't have the data — read the file first.