loopengine 0.0.17 → 0.0.20

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

@@ -14,18 +14,40 @@ import { ToolLane } from 'toollane';
 import { Reflow } from 'reflowkit';
 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');
+// 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()];
+}
 /** ContextClip only ever needs a flat string per message to estimate
  * token usage — it doesn't need to understand tool_use/tool_result
  * structure, so this is a one-way, read-only projection, never something
@@ -139,7 +161,7 @@ export async function loadDefaultTools(config) {
  * `agents/<name>/` — correct for a top-level agent, where that's exactly
  * where its module lives, but wrong for a subagent: its `config` only
  * carries its own bare name (e.g. 'billing-agent'), not the nested folder
- * loadSubagentTools actually found it in
+ * loadSubagentAsTools actually found it in
  * (`agents/support-orchestrator/subagents/billing-agent/`). Left alone,
  * an omitted `tools`/`rules`/`skillsDirs` on a subagent would silently
  * resolve against `agents/billing-agent/...` instead — empty, if no such
@@ -154,12 +176,19 @@ export async function loadDefaultTools(config) {
  * deny-everything ruleset" fallback loadRules's own default path gets —
  * computed here instead of left to loadRules, since leaving `rules`
  * unset would have it fall through to loadRules's *own* (wrong,
- * name-based) default path instead of this one. */
+ * name-based) default path instead of this one.
+ *
+ * `gateway-tools.yml` (see gateway-tools.ts) gets the same dir-correctness
+ * fix, but merged in unconditionally rather than gated on `tools` being
+ * unset — same reasoning loadSubagentAsTools' own unconditional merge into
+ * the top-level tools line has: gateway-registered tools are an
+ * operator/admin concern, distinct from hand-written `tools`, so setting
+ * `tools` explicitly shouldn't opt a subagent out of its own
+ * gateway-tools.yml the way it opts out of the tools/ folder default. */
 async function resolveSubagentConfig(config, dir) {
     const resolved = { ...config };
-    if (resolved.tools === undefined) {
-        resolved.tools = await loadToolsFromDir(join(dir, 'tools'));
-    }
+    const baseTools = resolved.tools === undefined ? await loadToolsFromDir(join(dir, 'tools')) : resolved.tools;
+    resolved.tools = [...baseTools, ...(await loadGatewayToolsFromDir(dir))];
     if (resolved.rules === undefined) {
         const rulesPath = join(dir, 'actauth.yml');
         if (existsSync(rulesPath)) {
@@ -196,7 +225,7 @@ async function resolveSubagentConfig(config, dir) {
  * called again, one level down. A folder can't be its own ancestor, so
  * this can't cycle the way a hand-wired agentAsTool(getEntry(...)) call
  * elsewhere could. */
-async function loadSubagentTools(config) {
+export async function loadSubagentAsTools(config) {
     const subagentsDir = join(agentsRootDir, config.name, 'subagents');
     if (!existsSync(subagentsDir))
         return [];
@@ -229,27 +258,46 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     // (including `[]`) is used as-is; omitted entirely defaults to
     // importing agents/<name>/tools/index.{ts,js} — see loadDefaultTools's
     // own doc comment for the full reasoning and the cases that can't use it.
-    // agents/<name>/subagents/* is merged in on top either way — see
-    // loadSubagentTools's own doc comment for why that one isn't gated by
+    // agents/<name>/subagents/* and agents/<name>/gateway-tools.yml (see
+    // 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 = [...(config.tools ?? (await loadDefaultTools(config))), ...(await loadSubagentTools(config))];
+    // 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 });
     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
@@ -281,7 +329,7 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             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 });
+            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
@@ -307,6 +355,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,
@@ -349,16 +410,16 @@ 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);
+        log({ type: 'contextclip: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);
+            log({ type: 'reflow:recoveries', recoveries });
         // 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
@@ -368,11 +429,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
@@ -380,13 +464,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: 'skillgarden:invoke', 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,
@@ -397,31 +511,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,6 +1,6 @@
 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
@@ -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;