loopengine 0.0.21 → 0.1.2

package/dist/core/run-agent.d.ts

@@ -1,5 +1,5 @@
 import { RuleSet, type Approver } from 'actauth';
-import type { AgentConfig, ToolDefinition, ToolSchema } from '#core/agent-config.js';
+import type { AgentConfig, ApproverChannel, QuestionHandler, ToolDefinition, ToolSchema } from '#core/agent-config.js';
 import { type PendingQuestion } from './system-tools/index.js';
 import type { LoopEvent } from './loop-events.js';
 export { systemTools } from './system-tools/index.js';
@@ -8,7 +8,18 @@ export declare const systemSkillsDir: string;
 export declare function dedupeToolsByName(list: ToolDefinition[]): ToolDefinition[];
 export interface ModelContentBlock {
     type: string;
-    /** text blocks. */
+    /** text blocks, and thinking blocks (a model's own chain-of-thought,
+     * e.g. DeepSeek's `reasoning_content` sibling field, or — if a
+     * model-calls/* adapter ever opts into it — Anthropic's own `thinking`
+     * content block). Reuses this same field rather than adding a
+     * thinking-only one, since both are just "a string of the model's own
+     * words." Carried opaquely: loopengine never reads or reasons about
+     * this text itself, only round-trips it back verbatim on the next
+     * request that includes this message — some reasoning-mode providers
+     * (DeepSeek's thinking mode, confirmed live; Anthropic's extended
+     * thinking, documented the same way) reject the request outright if a
+     * prior turn's reasoning gets silently dropped on the way back in,
+     * once the conversation has tool_calls in it. */
     text?: string;
     /** tool_use blocks: this call's own id (referenced by a later tool_result). */
     id?: string;
@@ -73,15 +84,32 @@ export interface RunAgentOptions {
      * pending question can't be session-scoped — still fine, it's still
      * agent-scoped either way. */
     sessionId?: string;
-    /** Default Approver for this call's 'ask' decisions, when
-     * AgentConfig.approver isn't set — the seam an adapter uses to pick
-     * whichever approver actually fits its own channel (ConsoleApprover for
-     * a real terminal, a web-based one for an HTTP-served conversation,
-     * ...) without every agent needing to hardcode one itself. An explicit
-     * AgentConfig.approver still wins outright over this when the agent
-     * author set one on purpose — same as it always has (see Gate
-     * construction below) — this only fills in when that's absent. Default,
-     * if neither is given: actauth's own ConsoleApprover, same as always. */
+    /** Which channel this call is on — checked below against `'http'`,
+     * the only value `AgentConfig.httpNotifier` ever matches (see that
+     * field's own doc comment). Omitted (a standalone script, a bespoke
+     * dispatcher with no fixed channel identity) means `httpNotifier` is
+     * never consulted at all — `approver` below is the only thing that
+     * applies. */
+    channel?: ApproverChannel;
+    /** This call's own default Approver for 'ask' decisions, when
+     * `AgentConfig.httpNotifier` doesn't supply one (only possible on the
+     * `http` channel, and only when it lists `'approval'`) — the seam an
+     * adapter uses to pick whichever approver actually fits its own channel
+     * (ConsoleApprover for a real terminal, a fresh WebchatApprover per
+     * streamed turn, a WebhookApprover for a background dispatcher,
+     * ...) without every agent needing to hardcode one itself. `http`'s own
+     * `httpNotifier`, if it covers `'approval'`, still wins outright over
+     * this — the agent author's own explicit choice *for that channel*
+     * beats whatever the adapter would otherwise default to (see Gate
+     * construction below) — `cli`/`http_stream` have no such override at
+     * all, so this is the only thing that ever applies there. Default, if
+     * neither is given: actauth's own ConsoleApprover, same as always.
+     *
+     * Can be a DurableApprover (WebhookApprover, ...) instead of a live
+     * one — see HUMAN_IN_THE_LOOP.md. A background/cron dispatcher calling
+     * runAgent() directly is exactly this same kind of caller, and should
+     * pass its own durable default here the same way adapters/http.ts's
+     * stream route passes a fresh WebchatApprover. */
     approver?: Approver;
     /** Fired the instant the system ask_user tool registers a new pending
      * question — this is the seam that decides between a real, answerable
@@ -100,6 +128,30 @@ export interface RunAgentOptions {
      * that genuinely has an answering mechanism (adapters/http.ts, for both
      * its routes) should pass this. */
     onQuestionPending?: (question: PendingQuestion) => void;
+    /** This call's own default QuestionHandler — question-side sibling of
+     * `approver` above, same precedence (`AgentConfig.httpNotifier`, when it
+     * covers `'question'` on the `http` channel, still wins outright over
+     * this) and the same `LiveQuestionHandler | DurableQuestionHandler`
+     * union `approver` itself is, duck-typed the same way (see
+     * `isDurableQuestionHandler`). Default, if neither this nor
+     * `httpNotifier` supplies one: `new CliQuestionHandler()` — same role
+     * `new ConsoleApprover()` plays for `approver`.
+     *
+     * One real, current asymmetry versus `approver`: only the *durable*
+     * half of this union is actually wired into the loop below — a
+     * `system_ask_user` call only ever consults this field to decide
+     * live-vs-durable; the live case still always falls through to
+     * `onQuestionPending`/the tool's own independent live resolution
+     * (unchanged from before this field existed), never actually calling
+     * a live `QuestionHandler` resolved here. See HUMAN_IN_THE_LOOP.md's
+     * "Durable questions" section for why: fully wiring the live half too
+     * would mean moving system_ask_user's answer-collection inline into
+     * this loop (changing today's batching semantics — right now a
+     * pending question is deferred past the whole tool_use batch scan,
+     * unlike a live approval) and a breaking change to createAskUserTool's
+     * own signature — deliberately deferred rather than done half-carefully
+     * here. */
+    questionHandler?: QuestionHandler;
 }
 export interface RunAgentResult {
     /** Final assistant text for this turn. */
@@ -132,8 +184,62 @@ export interface RunAgentResult {
      * model requested in the same turn, even one already approved, never
      * runs either (see the loop's own body); it gets a "skipped", not a
      * "denied", tool_result, since it was never evaluated against its own
-     * rule. */
-    stopReason?: 'max_turns' | 'denied';
+     * rule.
+     *
+     * 'pending_approval' / 'pending_question': at least one requested tool
+     * call is durably pending a DurableApprover decision, or at least one
+     * `system_ask_user` call is durably pending a DurableQuestionHandler
+     * answer (see HUMAN_IN_THE_LOOP.md) — same "the whole batch stops here"
+     * shape as 'denied', except this isn't a rejection: any already-run
+     * sibling call in the same batch still ran (see the loop's own
+     * bucket-then-execute), captured in `pending.resultsSoFar`, and the
+     * turn resumes later via resumeAgent() once every pendingId in
+     * `pending.outstanding` is resolved — not by sending another message
+     * the way 'denied' recovers. A batch can mix both kinds (a gated tool
+     * call and an `system_ask_user` call in the same model response) — both
+     * land in the same `pending.outstanding`, since the one dangling
+     * assistant tool_use message can only ever get one completing
+     * tool_result message; `stopReason` reports 'pending_approval' for that
+     * mixed case too (only a batch with *no* approval items at all reports
+     * 'pending_question'). `newMessages` ends at the dangling assistant
+     * tool_use message, same crash-recovery shape session-store.ts's own
+     * hasUnresolvedToolCall already detects — entered on purpose here,
+     * not by accident. runAgent() does no I/O (see this module's own
+     * header comment): turning `pending` into a durable TurnCheckpoint
+     * (core/durable-approvals.ts) is the caller's job. */
+    stopReason?: 'max_turns' | 'denied' | 'pending_approval' | 'pending_question';
+    /** Set only when stopReason is 'pending_approval' or 'pending_question'. */
+    pending?: {
+        /** tool_result blocks already computed this batch — safely
+         * auto-allowed calls that ran immediately despite a gated/asked
+         * sibling still being outstanding. Not yet pushed into `newMessages`/
+         * `history`: incomplete until every outstanding item below is
+         * resolved too, and a real model API expects one complete
+         * tool_result message per assistant tool_use message, not a partial
+         * one now and a follow-up later. */
+        resultsSoFar: ModelContentBlock[];
+        /** One entry per tool call still awaiting a durable decision, keyed
+         * by the pendingId its DurableApprover/DurableQuestionHandler handed
+         * out — what an incoming resolution actually names. `kind`
+         * distinguishes which of the two this is — for 'question', `args` is
+         * `{ question, options }` and `reason` is the question text itself
+         * (there's no separate ActAuth "reason" for a question the way there
+         * is for a gated tool call's decision). */
+        outstanding: PendingItem[];
+    };
+}
+/** One requested call still awaiting a durable decision — either a gated
+ * tool call (`kind: 'approval'`) or a `system_ask_user` call (`kind:
+ * 'question'`), unified into one array so a batch mixing both shares
+ * exactly one checkpoint (see RunAgentResult.stopReason's own doc
+ * comment for why that has to be true). */
+export interface PendingItem {
+    kind: 'approval' | 'question';
+    toolUseId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    pendingId: string;
+    reason: string;
 }
 /** Resolves AgentConfig.rules the same way skillsDirs resolves its own
  * default: an inline array is used as-is (full 3-segment scopePattern,
@@ -180,3 +286,25 @@ export declare function loadDefaultTools(config: AgentConfig): Promise<ToolDefin
  * elsewhere could. */
 export declare function loadSubagentAsTools(config: AgentConfig): Promise<ToolDefinition[]>;
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;
+/** 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 declare function resumeAgent(config: AgentConfig, modelCall: ModelCall, history: Message[], resolution: ModelContentBlock[], options?: RunAgentOptions): Promise<RunAgentResult>;

package/dist/core/run-agent.js

@@ -16,7 +16,9 @@ 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
@@ -58,7 +60,7 @@ function flattenForBudget(message) {
         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)})]`;
@@ -245,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
@@ -305,63 +307,36 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     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 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;
-        },
-    });
     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
@@ -412,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++;
@@ -460,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*
@@ -481,6 +540,38 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
                 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
@@ -520,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
@@ -569,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
@@ -604,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
@@ -620,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

@@ -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. */