loopengine 0.0.18 → 0.0.21

package/dist/{run-agent.js → core/run-agent.js}

@@ -9,29 +9,51 @@ 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';
+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 agent-registry.ts's own
-// agentsDir uses. In dev (tsx), this file and agents/ are both source
-// .ts, side by side. In the built dist/, this file is dist/run-agent.js
-// and its sibling agents/ is dist/agents/**/*.js (tsc-compiled) — cwd is
-// irrelevant to either case, only "next to this module" is reliably
-// right in both. skillsDirs/rules don't need this: actauth.yml/SKILL.md
-// are plain data copied verbatim into the image (see Dockerfile), so
-// they exist at the same cwd-relative path either way; a tools/index.ts
-// is real code that only exists compiled, at a different relative
-// location, once dist/ is what's actually running.
-const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), 'agents');
-/** ContextClip only ever needs a flat string per message to estimate
- * token usage — it doesn't need to understand tool_use/tool_result
+// not process.cwd() — the same reasoning core/agent-registry.ts's own
+// agentsDir uses. In dev (tsx), this file lives in core/ with agents/ one
+// level up, at repo root. In the built dist/, this file is
+// dist/core/run-agent.js with dist/agents/**/*.js (tsc-compiled,
+// preserving the source tree's shape) one level up from *it* the same
+// way — cwd is irrelevant to either case, only "one level up from this
+// module" is reliably right in both. skillsDirs/rules don't need this:
+// actauth.yml/SKILL.md are plain data copied verbatim into the image (see
+// Dockerfile), so they exist at the same cwd-relative path either way; a
+// tools/index.ts is real code that only exists compiled, at a different
+// relative location, once dist/ is what's actually running.
+const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'agents');
+// Same "resolved relative to this file's own location" reasoning as
+// agentsRootDir above, but system-skills/ is a same-level sibling of
+// run-agent.ts itself (both live directly under core/ — see package.json's
+// own "files" list), not one level up the way agents/ is, so this one
+// stays a direct join with no '..'.
+export const systemSkillsDir = join(dirname(fileURLToPath(import.meta.url)), 'system-skills');
+// Tools every agent gets (see systemTools' own doc comment) are merged
+// in *first*, not last — combined with keeping each name's *last*
+// occurrence (a plain Map naturally does this: re-setting an existing
+// key overwrites its value without moving it), that means an agent's
+// own tool of the same name (config.tools, a subagent, a gateway source)
+// always wins over the system default, never the reverse. Also used to
+// dedupe the *array itself*, not just resolution at call time — without
+// this, a name collision would still show up twice in toolSchemas,
+// confusing (or rejected outright by) a real model API.
+export function dedupeToolsByName(list) {
+    return [...new Map(list.map((t) => [t.name, t])).values()];
+}
+/** 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
@@ -241,28 +263,49 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     // gateway-tools.ts) are both merged in on top either way — see
     // loadSubagentAsTools's own doc comment for why neither is gated by
     // whether `tools` was explicit.
-    const tools = [
+    // systemTools go first and are deduped by name (dedupeToolsByName keeps
+    // each name's *last* occurrence) — so config.tools/subagents/gateway
+    // tools always win over a same-named system default, never the
+    // reverse, even though systemTools is merged in unconditionally
+    // (unlike the others below, it's not gated on `tools` being omitted).
+    // ask_user is built fresh per call, not part of the static systemTools
+    // array — its onPending needs options.onQuestionPending, not `log`
+    // (options.onEvent's own fallback) — see RunAgentOptions.onQuestionPending's
+    // own doc comment for why those two are deliberately not the same thing.
+    const askUserTool = createAskUserTool({ agent: config.name, sessionId: options.sessionId }, options.onQuestionPending);
+    const tools = dedupeToolsByName([
+        ...systemTools,
+        askUserTool,
         ...(config.tools ?? (await loadDefaultTools(config))),
         ...(await loadSubagentAsTools(config)),
         ...(await loadGatewayToolsFromDir(join(agentsRootDir, config.name))),
-    ];
+    ]);
     // Omitted entirely (undefined): default to this agent's own
     // agents/<name>/skills — the folder-form convention every agent in
     // this repo already follows (see agent-config.ts's skillsDirs doc
-    // comment). An explicit `[]` is a real opt-out, not "unset," and skips
-    // the default — SkillGarden's own missing-directory handling
-    // (discoverSkillFiles walks best-effort, no throw) is what makes
-    // pointing this at a folder that doesn't exist (a flat-file agent with
-    // no skills at all) harmless: an empty index, not an error.
+    // comment). An explicit `[]` is a real opt-out of the agent's *own*
+    // skills dir, but systemSkillsDir is still always included below —
+    // same "not opt-out-able the normal way" as systemTools above.
+    // SkillGarden's own missing-directory handling (discoverSkillFiles
+    // walks best-effort, no throw) is what makes pointing this at a folder
+    // that doesn't exist (a flat-file agent with no skills at all)
+    // harmless: an empty index, not an error.
     const skillsDirs = config.skillsDirs ?? [`agents/${config.name}/skills`];
-    const skillGarden = skillsDirs.length ? new SkillGarden({ dirs: skillsDirs, indexBudgetTokens: config.skillIndexBudgetTokens ?? 200 }) : null;
-    const skillIndex = skillGarden?.buildIndex().included ?? [];
+    const skillGarden = new SkillGarden({ dirs: [...skillsDirs, systemSkillsDir], indexBudgetTokens: config.skillIndexBudgetTokens ?? 200 });
+    const skillIndex = skillGarden.buildIndex().included;
     // 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 ?? new ConsoleApprover());
+    const gate = new Gate(rules, config.approver ?? options.approver ?? new ConsoleApprover());
     // 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
@@ -280,21 +323,21 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         messages.push(message);
         newMessages.push(message);
     }
-    const reflow = new Reflow({
+    const recovery = new Recovery({
         onPromptTooLong: async (currentMessages) => {
             // newMessages (this turn's own content — not durably stored
-            // anywhere else yet) must never be handed to ContextClip at all.
+            // 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 ContextClip's
-            // synthetic head contained — that's unsound: ContextClip's cheap
+            // 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 contextClip.recover(priorPortion.map(flattenForContextClip));
-            log('reflow:recover', { from: currentMessages.length, to: result.messages.length + newMessages.length });
+            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
@@ -304,13 +347,13 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             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} —
+            // 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 contextClip.check() in this loop, and the `history`
+            // 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
@@ -320,6 +363,19 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         },
     });
     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
+    // wins" rule above) is a deliberate opt-out, and that override should
+    // still go through the agent's own rules like anything else; only the
+    // genuine, unmodified system implementation always bypasses the gate.
+    // ask_user in particular can't be gated at all without a real deadlock:
+    // it's the mechanism a human uses to answer the agent, so requiring a
+    // human decision just to *ask* one is circular, not just redundant —
+    // and every default_decision this repo's own agents actually use
+    // ('ask' or 'deny', see loadRules' own doc comment) would otherwise
+    // catch it, since neither system tool ever appears in an agent's own
+    // actauth.yml.
+    const systemToolInstances = new Set([...systemTools, askUserTool]);
     const toolSchemas = tools.map(({ name, description, input_schema }) => ({
         name,
         description,
@@ -362,16 +418,21 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         if (turn > maxTurns) {
             const text = `Stopped after ${maxTurns} turns without a final answer — the agent may be stuck in a loop.`;
             pushMessage({ role: 'assistant', content: text });
-            log('loop:max_turns', { maxTurns });
+            log({ type: 'loop:max_turns', maxTurns });
             return { text, history: messages, newMessages, stopReason: 'max_turns' };
         }
-        const budget = contextClip.check(messages.map(flattenForContextClip));
-        log('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('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
@@ -381,11 +442,34 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         const toolUseBlocks = response.content.filter((b) => b.type === 'tool_use');
         if (toolUseBlocks.length === 0) {
             const text = response.content.find((b) => b.type === 'text')?.text ?? '';
-            log('loop:done', text);
+            log({ type: 'loop:done', text });
             return { text, history: messages, newMessages };
         }
+        // The model's own text alongside a tool_use request (its "I'll do X"
+        // preamble) is already durable via pushMessage above, but the only
+        // *live* SSE event that ever carries assistant text is 'done', which
+        // fires once at the very end of the whole turn — a live caller
+        // watching this turn in progress (adapters/http.ts's streaming route,
+        // the playground) would otherwise jump straight from "thinking..." to
+        // an approval/question card with zero explanation, and only ever see
+        // this sentence later, after a refresh replays stored history —
+        // confirmed live.
+        const preambleText = response.content.find((b) => b.type === 'text')?.text;
+        if (preambleText)
+            log({ type: 'assistant:text', text: preambleText });
         const resultBlocks = [];
         const approvedCalls = [];
+        const deniedTools = [];
+        // 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*
+        // that let a call through in the first place (or what it was even
+        // called with). This is what lets the reason still get attached to
+        // the right tool_result once execution finishes below, and lets the
+        // 'tool:result' live event (see below) report the same args a
+        // resumed/refreshed view of this same call would show, without
+        // changing toollane's own types.
+        const approvedMetaById = new Map();
         for (const block of toolUseBlocks) {
             // Skill invocation injects instructions into context; it isn't a
             // real tool call and doesn't need ActAuth gating or ToolLane
@@ -393,13 +477,43 @@ 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('skillgarden:invoke', block.input.skill);
+                log({ type: 'skill:loaded', skill: block.input.skill });
                 resultBlocks.push({ type: 'tool_result', tool_use_id: block.id, content: body });
                 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
+            // anything in the first place.
+            if (systemToolInstances.has(toolsByName.get(block.name))) {
+                log({ type: 'actauth:decision', tool: block.name, decision: 'allow', reason: 'system tool — always allowed' });
+                approvedMetaById.set(block.id, { reason: 'system tool — always allowed', args: block.input ?? {} });
+                // Fired the moment the decision is in, not once execution finishes
+                // (see the 'tool:started' vs 'tool:result' split below) — a system
+                // tool can still be slow, and this is the one path that had no
+                // interactive card of its own to show something sooner.
+                log({ type: 'tool:started', id: block.id, tool: block.name, args: block.input ?? {}, detailText: 'system tool — always allowed' });
+                approvedCalls.push({
+                    id: block.id,
+                    name: block.name,
+                    execute: () => toolsByName.get(block.name).execute(block.input ?? {}),
+                });
+                continue;
+            }
             const decision = await gate.evaluate(block.name, block.input ?? {}, scope);
-            log('actauth:decision', { tool: block.name, decision: decision.decision, reason: decision.reason });
+            log({ type: 'actauth:decision', tool: block.name, decision: decision.decision, reason: decision.reason });
             if (decision.decision === 'allow') {
+                approvedMetaById.set(block.id, { reason: decision.reason, args: block.input ?? {} });
+                // Fired the instant the decision is in, not once execution
+                // finishes below — closes what would otherwise be a multi-second
+                // silent gap while a slow call runs. Always emitted, whether or
+                // not a human was actually asked live: run-agent.ts itself has no
+                // notion of "already shown elsewhere" — that's a rendering
+                // decision, and belongs to whichever channel adapter is actually
+                // presenting this turn (see web/playground.ts's own
+                // wasAskedInteractively, which decides whether this duplicates an
+                // approval card already on screen), not to the engine loop.
+                log({ type: 'tool:started', id: block.id, tool: block.name, args: block.input ?? {}, detailText: decision.reason });
                 approvedCalls.push({
                     id: block.id,
                     name: block.name,
@@ -410,31 +524,99 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
                 // Every requested tool gets exactly one tool_result back — a
                 // denied call is not simply dropped, or the model has no way to
                 // tell "denied" apart from "hasn't run yet" and may just
-                // re-request it forever.
+                // re-request it forever. Recorded even though this turn is about
+                // to stop (see deniedTools below) — a later message continuing
+                // this same session still needs a complete, consistent history,
+                // not a dangling tool_use with no answer.
+                deniedTools.push(block.name);
                 resultBlocks.push({
                     type: 'tool_result',
                     tool_use_id: block.id,
                     content: `denied: ${decision.reason}`,
                     is_error: true,
                 });
+                // Always emitted — see the 'allow' branch's own comment above on
+                // why this engine loop no longer decides whether a live UI
+                // already has some other representation of this decision on
+                // screen (an approval card that went through an interactive
+                // ask). That's a rendering call, made by whichever channel
+                // adapter is presenting this turn.
+                log({ type: 'tool:result', id: block.id, tool: block.name, args: block.input ?? {}, detailText: decision.reason, statusText: 'Denied.' });
+            }
+        }
+        if (deniedTools.length > 0) {
+            // A denial cancels the *whole* batch, not just the call(s) that
+            // were themselves denied — an approved sibling call from the same
+            // turn never runs at all, same reasoning Claude Code itself stops
+            // an entire pending batch rather than quietly carrying out the
+            // parts you didn't object to. Every approved call still gets
+            // exactly one tool_result back regardless (the model emitted a
+            // tool_use for it, so it needs an answer) — "skipped", not
+            // "denied": it was never evaluated against its own rule, a
+            // *different* call in the same turn was what stopped it.
+            for (const call of approvedCalls) {
+                log({ type: 'loop:skipped', name: call.name, deniedTools });
+                const skipReason = `a sibling tool call in this turn (${deniedTools.join(', ')}) was denied`;
+                resultBlocks.push({
+                    type: 'tool_result',
+                    tool_use_id: call.id,
+                    content: `skipped: ${skipReason}`,
+                    is_error: true,
+                });
+                // A skipped call never went through gate.evaluate at all — no
+                // approver, no interactive card, nothing live ever showed it was
+                // even requested. Same reasoning as the straight-denied case
+                // just above.
+                log({ type: 'tool:result', id: call.id, tool: call.name, args: approvedMetaById.get(call.id)?.args, detailText: skipReason, statusText: 'Skipped.' });
             }
         }
-        // result.id is the same id LaneCall.id was given above — the exact
-        // per-call identity that makes it possible to link a result back to
-        // the specific tool_use block that requested it, even when several
-        // calls ran in the same parallel lane. The old flattened-text design
-        // could only link by tool *name*, ambiguous the moment two calls to
-        // the same tool ran in one turn.
-        for await (const result of toolLane.run(approvedCalls)) {
-            const summary = result.status === 'fulfilled' ? JSON.stringify(result.value) : `ERROR: ${result.error}`;
-            log('toollane:result', { name: result.name, summary });
-            resultBlocks.push({
-                type: 'tool_result',
-                tool_use_id: result.id,
-                content: summary,
-                is_error: result.status === 'rejected',
-            });
+        else {
+            // result.id is the same id LaneCall.id was given above — the exact
+            // per-call identity that makes it possible to link a result back
+            // to the specific tool_use block that requested it, even when
+            // several calls ran in the same parallel lane. The old
+            // flattened-text design could only link by tool *name*, ambiguous
+            // the moment two calls to the same tool ran in one turn.
+            for await (const result of toolLane.run(approvedCalls)) {
+                const summary = result.status === 'fulfilled' ? JSON.stringify(result.value) : `ERROR: ${result.error}`;
+                const meta = approvedMetaById.get(result.id);
+                log({ type: 'toollane:result', name: result.name, summary });
+                resultBlocks.push({
+                    type: 'tool_result',
+                    tool_use_id: result.id,
+                    content: summary,
+                    is_error: result.status === 'rejected',
+                    reason: meta?.reason,
+                });
+                // Always emitted — this is what turns the earlier 'tool:started'
+                // event's "Running…" placeholder into the real outcome (matched
+                // by the same id), for every call regardless of how it got
+                // approved. See the 'allow' branch's own comment above: deciding
+                // whether this duplicates an approval card already on screen is
+                // a rendering call for the channel adapter presenting this turn,
+                // not something this engine loop tracks.
+                log({
+                    type: 'tool:result',
+                    id: result.id,
+                    tool: result.name,
+                    args: meta?.args,
+                    detailText: meta?.reason,
+                    statusText: result.status === 'fulfilled' ? 'Approved.' : 'Error.',
+                });
+            }
         }
         pushMessage({ role: 'user', content: resultBlocks });
+        // Stop here, don't loop back for another model call — same reasoning
+        // Claude Code itself stops and waits for you rather than working
+        // around a tool call you just rejected, instead of silently handing
+        // "denied: ..." to the model and letting it decide on its own what to
+        // try next (retry the same tool, reach for a different one, or just
+        // talk its way past the refusal).
+        if (deniedTools.length > 0) {
+            const text = `Stopped — you denied: ${deniedTools.join(', ')}. Send another message to continue.`;
+            pushMessage({ role: 'assistant', content: text });
+            log({ type: 'loop:denied', deniedTools });
+            return { text, history: messages, newMessages, stopReason: 'denied' };
+        }
     }
 }

package/dist/{session-store.d.ts → core/session-store.d.ts}

@@ -1,12 +1,12 @@
 import { Redis } from 'ioredis';
 import { type Storage } from 'sessionknit';
-import type { Message } from '#run-agent.js';
+import type { Message } from '#core/run-agent.js';
 export interface SessionResult<T> {
     /** Exactly what this turn added — durably appended as-is, in order.
      * 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[];
@@ -18,6 +18,17 @@ export interface SessionStore {
      * process or (for RedisSessionStore) any other — durably appends
      * fn's result.newMessages in order, and resolves with fn's result. */
     withSession<T>(sessionId: string, fn: (history: Message[]) => Promise<SessionResult<T>>): Promise<T>;
+    /** Read-only peek at a session's current history — no new turn, nothing
+     * appended. Backs adapters/http.ts's GET .../sessions/:id (the
+     * playground's "resume a past conversation" sidebar rehydrates the chat
+     * pane from this, rather than pretending a new message was sent).
+     * Deliberately *not* behind withSession's own per-sessionId exclusivity
+     * — see the concrete implementation's own doc comment for why that's
+     * safe, and why this needs to work *especially* while a turn is still
+     * in flight (blocked on a human — see web/web-approver.ts /
+     * system-tools/ask_user.ts),
+     * not only once it's finished. */
+    getHistory(sessionId: string): Promise<Message[]>;
     close(): Promise<void>;
 }
 /** Serializes async work per key within this process. Good enough for
@@ -40,6 +51,7 @@ declare class SessionKnitStore implements SessionStore {
     private readonly knit;
     constructor(storage: Storage<Message>, lock: <T>(sessionId: string, fn: () => Promise<T>) => Promise<T>, onClose?: () => Promise<void>);
     withSession<T>(sessionId: string, fn: (history: Message[]) => Promise<SessionResult<T>>): Promise<T>;
+    getHistory(sessionId: string): Promise<Message[]>;
     close(): Promise<void>;
 }
 /** One JSONL entry log per session under `dir`. Fine for a single local

package/dist/{session-store.js → core/session-store.js}

@@ -107,6 +107,25 @@ class SessionKnitStore {
             return result;
         });
     }
+    // Deliberately *not* behind this.lock the way withSession is — that
+    // lock is held for withSession's *entire* fn(), which can now mean an
+    // 'ask' decision or an ask_user question blocked on a human for
+    // minutes (see web/web-approver.ts / system-tools/ask_user.ts). Confirmed
+    // live: a session with a pending question hung this call indefinitely,
+    // which is exactly backwards for what it's for — the playground's own
+    // "resume a session" flow (see its own checkForPendingItems) needs this
+    // to work *especially* while something's pending, not only once it
+    // isn't. Safe unlocked: withSession's own append loop only ever runs
+    // after fn() has already fully resolved (see its own body — nothing
+    // about the *next* turn is written until then), so there's nothing for
+    // an in-flight turn to race this against except that append loop
+    // itself, a few awaits, not the human-wait duration in front of it. A
+    // read that lands mid-append just sees an older, still-fully-valid
+    // prefix, not torn data.
+    async getHistory(sessionId) {
+        const { messages } = await this.knit.resume(sessionId);
+        return messages;
+    }
     async close() {
         await this.onClose();
     }

package/dist/core/system-tools/ask_user.d.ts

@@ -0,0 +1,72 @@
+import type { ToolDefinition } from '../agent-config.js';
+export interface PendingQuestion {
+    id: string;
+    question: string;
+    /** Suggested answers, if the model gave any — never the only allowed
+     * answer, a human can still type free text either way (see
+     * answerQuestion, which takes any string). */
+    options?: string[];
+    /** Which agent raised this — always known (config.name), so listing can
+     * always at least be scoped per-agent even without a session id. */
+    agent: string;
+    /** Which conversation raised this, if the caller has one (see
+     * RunAgentOptions.sessionId's own doc comment for when it doesn't) —
+     * lets listQuestions scope down to exactly one conversation instead of
+     * every question raised by this agent, or this whole process. */
+    sessionId?: string;
+    requestedAt: string;
+}
+/** Builds the ask_user ToolDefinition for one runAgent() call.
+ *
+ * context identifies *whose* question this is (see PendingQuestion's own
+ * doc comment) — without it, listQuestions() would have no way to scope
+ * down to one agent/conversation, and every caller would see every
+ * pending question this whole process has ever raised.
+ *
+ * onPending, when given, is how a live caller (adapters/http.ts's
+ * streaming route passes `(q) => log('question:pending', q)`, which
+ * onEvent forwards straight onto that turn's SSE connection — see
+ * playground.ts's own inline card for it) finds out immediately instead
+ * of having to poll listQuestions(). It's a notification only, not a
+ * routing key: the question is registered in the same shared
+ * questionsById either way, so answerQuestion() works regardless of
+ * whether anything was listening for onPending in the first place.
+ *
+ * Omitted entirely (a plain CLI run, or any caller with no live channel
+ * of its own) falls back to a blocking terminal prompt instead of a
+ * pending entry nothing could ever answer — same reasoning
+ * ConsoleApprover exists for permission asks with nowhere else to go.
+ *
+ * Named `system_ask_user`, not the bare `ask_user` an agent author would
+ * naturally reach for on their own — see system-tools/read_file.ts's own
+ * doc comment on the same `system_` prefix for the full reasoning
+ * (unlikely to collide by accident, and run-agent.ts's own
+ * systemToolInstances gate bypass treats a same-named override as a
+ * deliberate opt-out when one does happen). It matters even more here
+ * than for read_file: this tool *is* a human's only way to answer the
+ * agent in the first place, so it can never be gated at all without a
+ * real deadlock, not just a redundant check — a name any other tool
+ * could plausibly reach for by accident would risk silently losing that
+ * guarantee, not just risk a surprising override. */
+export declare function createAskUserTool(context: {
+    agent: string;
+    sessionId?: string;
+}, onPending?: (question: PendingQuestion) => void): ToolDefinition;
+/** Oldest first, same ordering reasoning web/web-approver.ts's listApprovals
+ * uses — whichever question has been waiting longest surfaces first.
+ * Unfiltered (both omitted) returns every question pending anywhere in
+ * this process — real uses (an operator's own admin view, say) should
+ * filter, since that's every conversation's questions mixed together. */
+export declare function listQuestions(filter?: {
+    agent?: string;
+    sessionId?: string;
+}): PendingQuestion[];
+/** Peek at a pending question's own entry (its agent/sessionId, in
+ * particular) without answering it — adapters/http.ts needs this *before*
+ * calling answerQuestion() below, to know which turn's early-return race
+ * (see its own sessionTurns) to resume once this one's answered. */
+export declare function findQuestion(id: string): PendingQuestion | undefined;
+/** Returns false for an unknown/already-answered/timed-out id, so the
+ * caller can report that distinctly (a 404) instead of silently
+ * no-opping — same convention web/web-approver.ts's decideApproval uses. */
+export declare function answerQuestion(id: string, answer: string): boolean;