muonroi-cli 1.3.4 → 1.4.1

package/dist/src/storage/transcript.js

@@ -1,4 +1,5 @@
 import { getCompactionSummaryText } from "../orchestrator/compaction.js";
+import { getResponseTaskType, isResponseTool } from "../pil/response-tools.js";
 import { getDatabase, withTransaction } from "./db.js";
 import { extractToolResultFromOutput, getOutputKind, isOutputSuccess } from "./tool-results.js";
 import { buildEffectiveTranscript } from "./transcript-view.js";
@@ -41,11 +42,11 @@ function isInternalCouncilMarker(content) {
 }
 function loadMessageRows(sessionId) {
     const rows = getDatabase()
-        .prepare(`
-    SELECT session_id, seq, role, message_json, created_at
-    FROM messages
-    WHERE session_id = ?
-    ORDER BY seq ASC
+        .prepare(`
+    SELECT session_id, seq, role, message_json, created_at
+    FROM messages
+    WHERE session_id = ?
+    ORDER BY seq ASC
   `)
         .all(sessionId);
     for (const row of rows) {
@@ -65,12 +66,12 @@ function toPersistedCompaction(row) {
 }
 export function loadLatestCompaction(sessionId) {
     const row = getDatabase()
-        .prepare(`
-    SELECT session_id, first_kept_seq, summary, tokens_before, created_at
-    FROM compactions
-    WHERE session_id = ?
-    ORDER BY id DESC
-    LIMIT 1
+        .prepare(`
+    SELECT session_id, first_kept_seq, summary, tokens_before, created_at
+    FROM compactions
+    WHERE session_id = ?
+    ORDER BY id DESC
+    LIMIT 1
   `)
         .get(sessionId);
     return toPersistedCompaction(row);
@@ -111,37 +112,37 @@ export function appendMessages(sessionId, messages) {
         // with `status='completed'` and the full message_json. Pre-A5 callers
         // hit this path identically: there is no pending row so the IGNORE
         // branch is unused and the INSERT wins.
-        const insertMessage = db.prepare(`
-      INSERT INTO messages (session_id, seq, role, message_json, created_at, status)
-      VALUES (?, ?, ?, ?, ?, 'completed')
-      ON CONFLICT(session_id, seq) DO UPDATE SET
-        role = excluded.role,
-        message_json = excluded.message_json,
-        status = 'completed'
+        const insertMessage = db.prepare(`
+      INSERT INTO messages (session_id, seq, role, message_json, created_at, status)
+      VALUES (?, ?, ?, ?, ?, 'completed')
+      ON CONFLICT(session_id, seq) DO UPDATE SET
+        role = excluded.role,
+        message_json = excluded.message_json,
+        status = 'completed'
     `);
-        const insertToolCall = db.prepare(`
-      INSERT OR IGNORE INTO tool_calls (
-        session_id, message_seq, tool_call_id, tool_name, args_json, status, started_at, completed_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        const insertToolCall = db.prepare(`
+      INSERT OR IGNORE INTO tool_calls (
+        session_id, message_seq, tool_call_id, tool_name, args_json, status, started_at, completed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `);
-        const updateToolCall = db.prepare(`
-      UPDATE tool_calls
-      SET tool_name = ?, args_json = ?, status = ?, completed_at = ?
-      WHERE session_id = ? AND tool_call_id = ?
+        const updateToolCall = db.prepare(`
+      UPDATE tool_calls
+      SET tool_name = ?, args_json = ?, status = ?, completed_at = ?
+      WHERE session_id = ? AND tool_call_id = ?
     `);
-        const selectToolCall = db.prepare(`
-      SELECT id, tool_call_id, tool_name, args_json
-      FROM tool_calls
-      WHERE session_id = ? AND tool_call_id = ?
+        const selectToolCall = db.prepare(`
+      SELECT id, tool_call_id, tool_name, args_json
+      FROM tool_calls
+      WHERE session_id = ? AND tool_call_id = ?
     `);
-        const insertToolResult = db.prepare(`
-      INSERT INTO tool_results (tool_call_row_id, output_kind, output_json, success, created_at)
-      VALUES (?, ?, ?, ?, ?)
+        const insertToolResult = db.prepare(`
+      INSERT INTO tool_results (tool_call_row_id, output_kind, output_json, success, created_at)
+      VALUES (?, ?, ?, ?, ?)
     `);
-        const updateSession = db.prepare(`
-      UPDATE sessions
-      SET updated_at = ?
-      WHERE id = ?
+        const updateSession = db.prepare(`
+      UPDATE sessions
+      SET updated_at = ?
+      WHERE id = ?
     `);
         messages.forEach((message, index) => {
             const seq = nextSeq + index;
@@ -203,10 +204,10 @@ export function persistToolCallWriteAhead(sessionId, messageSeq, toolCallId, too
     const now = new Date().toISOString();
     try {
         getDatabase()
-            .prepare(`
-        INSERT OR IGNORE INTO tool_calls (
-          session_id, message_seq, tool_call_id, tool_name, args_json, status, started_at, completed_at
-        ) VALUES (?, ?, ?, ?, ?, 'pending', ?, NULL)
+            .prepare(`
+        INSERT OR IGNORE INTO tool_calls (
+          session_id, message_seq, tool_call_id, tool_name, args_json, status, started_at, completed_at
+        ) VALUES (?, ?, ?, ?, ?, 'pending', ?, NULL)
       `)
             .run(sessionId, messageSeq, toolCallId, toolName, argsJson, now);
     }
@@ -252,10 +253,10 @@ export function persistMessageWriteAhead(sessionId, seq, role, messageJson) {
     const now = new Date().toISOString();
     try {
         getDatabase()
-            .prepare(`
-        INSERT OR IGNORE INTO messages (
-          session_id, seq, role, message_json, created_at, status
-        ) VALUES (?, ?, ?, ?, ?, 'pending')
+            .prepare(`
+        INSERT OR IGNORE INTO messages (
+          session_id, seq, role, message_json, created_at, status
+        ) VALUES (?, ?, ?, ?, ?, 'pending')
       `)
             .run(sessionId, seq, role, messageJson, now);
     }
@@ -273,10 +274,10 @@ export function persistMessageWriteAhead(sessionId, seq, role, messageJson) {
 export function markMessageCompleted(sessionId, seq) {
     try {
         getDatabase()
-            .prepare(`
-        UPDATE messages
-        SET status = 'completed'
-        WHERE session_id = ? AND seq = ? AND status = 'pending'
+            .prepare(`
+        UPDATE messages
+        SET status = 'completed'
+        WHERE session_id = ? AND seq = ? AND status = 'pending'
       `)
             .run(sessionId, seq);
     }
@@ -295,10 +296,10 @@ export function markMessageCompleted(sessionId, seq) {
 export function markMessageErrored(sessionId, seq) {
     try {
         getDatabase()
-            .prepare(`
-        UPDATE messages
-        SET status = 'errored'
-        WHERE session_id = ? AND seq = ? AND status = 'pending'
+            .prepare(`
+        UPDATE messages
+        SET status = 'errored'
+        WHERE session_id = ? AND seq = ? AND status = 'pending'
       `)
             .run(sessionId, seq);
     }
@@ -306,14 +307,58 @@ export function markMessageErrored(sessionId, seq) {
         /* fail-open */
     }
 }
+/**
+ * Mark write-ahead rows orphaned by an earlier process kill (Ctrl+C, OOM,
+ * `taskkill /F`) as `aborted` instead of leaving them `pending` forever.
+ *
+ * Triggered by SessionStore.openSession() so a fresh launch cleans up after
+ * the previous run that died mid-turn. Only rows older than `staleAfterMs`
+ * are touched — leaving a 5-minute safety margin so a concurrently-running
+ * muonroi-cli process never has its live in-flight rows clobbered.
+ *
+ * Two row classes:
+ *  - `tool_calls.status = 'pending'`  and `started_at` older than threshold
+ *    → set status='aborted', completed_at=now (so forensics can distinguish
+ *    "tool exec threw" (errored) from "process died before result" (aborted))
+ *  - `messages.status = 'pending'`    and `created_at` older than threshold
+ *    → set status='aborted'
+ *
+ * Returns the row counts changed (mostly for tests + ops visibility).
+ */
+export function sweepStalePendingRows(staleAfterMs = 5 * 60 * 1000) {
+    const cutoff = new Date(Date.now() - staleAfterMs).toISOString();
+    const now = new Date().toISOString();
+    try {
+        const db = getDatabase();
+        const toolCalls = db
+            .prepare(`
+        UPDATE tool_calls
+        SET status = 'aborted', completed_at = ?
+        WHERE status = 'pending' AND started_at < ?
+      `)
+            .run(now, cutoff);
+        const messages = db
+            .prepare(`
+        UPDATE messages
+        SET status = 'aborted'
+        WHERE status = 'pending' AND created_at < ?
+      `)
+            .run(cutoff);
+        return { toolCalls: toolCalls.changes, messages: messages.changes };
+    }
+    catch (err) {
+        console.error(`[transcript] sweepStalePendingRows failed: ${err?.message}`);
+        return { toolCalls: 0, messages: 0 };
+    }
+}
 export function markToolCallErrored(sessionId, toolCallId, errorMessage) {
     const now = new Date().toISOString();
     try {
         getDatabase()
-            .prepare(`
-        UPDATE tool_calls
-        SET status = 'errored', completed_at = ?, args_json = COALESCE(args_json, ?)
-        WHERE session_id = ? AND tool_call_id = ?
+            .prepare(`
+        UPDATE tool_calls
+        SET status = 'errored', completed_at = ?, args_json = COALESCE(args_json, ?)
+        WHERE session_id = ? AND tool_call_id = ?
       `)
             .run(now, JSON.stringify({ error: errorMessage.slice(0, 500) }), sessionId, toolCallId);
     }
@@ -323,14 +368,14 @@ export function markToolCallErrored(sessionId, toolCallId, errorMessage) {
 }
 export function appendCompaction(sessionId, firstKeptSeq, summary, tokensBefore) {
     withTransaction((db) => {
-        db.prepare(`
-      INSERT INTO compactions (session_id, first_kept_seq, summary, tokens_before, created_at)
-      VALUES (?, ?, ?, ?, ?)
+        db.prepare(`
+      INSERT INTO compactions (session_id, first_kept_seq, summary, tokens_before, created_at)
+      VALUES (?, ?, ?, ?, ?)
     `).run(sessionId, firstKeptSeq, summary, tokensBefore, new Date().toISOString());
-        db.prepare(`
-      UPDATE sessions
-      SET updated_at = ?
-      WHERE id = ?
+        db.prepare(`
+      UPDATE sessions
+      SET updated_at = ?
+      WHERE id = ?
     `).run(new Date().toISOString(), sessionId);
     });
 }
@@ -365,6 +410,36 @@ export function buildChatEntries(sessionId) {
             for (const part of message.content) {
                 if (part.type !== "tool-result")
                     continue;
+                // Response tools (respond_general/analyze/plan/...) are the model's
+                // TERMINAL structured answer (identity execute — the payload lives in
+                // the call args and is echoed in the result). The live stream yields
+                // them as a `structured_response` chunk (message-processor.ts:2733),
+                // which the UI renders as the answer block. Persisted history MUST
+                // rebuild the SAME entry: finalizeActiveTurn (app.tsx) replaces the
+                // live message list with getChatEntries() on every normal turn, so if
+                // we rebuilt a respond_* result as a bare tool_result the rendered
+                // answer would be silently dropped the instant streaming ended (live
+                // repro session 9d3d371ca1bd: grok investigated, emitted a 10K-char
+                // respond_general, the answer flashed then vanished on turn finalize —
+                // the user saw only the "→ respond_general" indicator). AI SDK v5/v6
+                // wraps tool outputs as `{type:"json", value:{...}}`; unwrap to expose
+                // the schema-shaped payload to the renderer.
+                if (isResponseTool(part.toolName)) {
+                    const rawOutput = part.output;
+                    const unwrapped = rawOutput && typeof rawOutput === "object" && rawOutput.type === "json"
+                        ? (rawOutput.value ?? {})
+                        : (rawOutput ?? {});
+                    entries.push({
+                        type: "structured_response",
+                        content: "",
+                        timestamp,
+                        structuredResponse: {
+                            taskType: getResponseTaskType(part.toolName) ?? part.toolName,
+                            data: unwrapped,
+                        },
+                    });
+                    continue;
+                }
                 const toolCall = callMap.get(part.toolCallId) ?? toFallbackToolCall(part.toolCallId, part.toolName);
                 const toolResult = toolResults.get(part.toolCallId) ??
                     extractToolResultFromOutput(part.output) ?? {
@@ -385,10 +460,10 @@ export function buildChatEntries(sessionId) {
 }
 function getNextSequence(db, sessionId) {
     const row = db
-        .prepare(`
-    SELECT COALESCE(MAX(seq), 0) AS max_seq
-    FROM messages
-    WHERE session_id = ?
+        .prepare(`
+    SELECT COALESCE(MAX(seq), 0) AS max_seq
+    FROM messages
+    WHERE session_id = ?
   `)
         .get(sessionId);
     return (row?.max_seq ?? 0) + 1;
@@ -438,12 +513,12 @@ function renderAssistantContent(content, callMap) {
 }
 function loadStoredToolResults(sessionId) {
     const rows = getDatabase()
-        .prepare(`
-    SELECT tc.tool_call_id, tr.output_json
-    FROM tool_results tr
-    JOIN tool_calls tc ON tc.id = tr.tool_call_row_id
-    WHERE tc.session_id = ?
-    ORDER BY tr.id ASC
+        .prepare(`
+    SELECT tc.tool_call_id, tr.output_json
+    FROM tool_results tr
+    JOIN tool_calls tc ON tc.id = tr.tool_call_row_id
+    WHERE tc.session_id = ?
+    ORDER BY tr.id ASC
   `)
         .all(sessionId);
     return new Map(rows.map((row) => [row.tool_call_id, JSON.parse(row.output_json)]));

package/dist/src/storage/ui-interaction-log.d.ts

@@ -14,7 +14,7 @@
  */
 export type UIInteractionSubtype = "route_decision" | "sprint_stage" | "sprint_halt" | "askcard_open" | "askcard_answered" | "askcard_cancel" | "halt_card_open" | "halt_card_answered" | "init_new_step" | "init_new_submitted" | "init_new_result" | "init_new_resume" | "init_new_retry";
 interface RouteDecisionPayload {
-    path: "hot-path" | "council";
+    path: "hot-path" | "council" | "maintain";
     complexity: string;
     forceCouncil: boolean;
     /** PIL sufficiency gaps that forced the Council path (empty when complete). */
@@ -37,6 +37,16 @@ interface AskcardOpenPayload {
     phase: string;
     optionCount: number;
     defaultIndex?: number;
+    /**
+     * The rendered option labels, in order. Persisted so a DB / `usage forensics`
+     * audit can measure WHAT the "Recommended" badge pointed at — not just its
+     * index. Without it, recommend-correctness (e.g. the scope-card "Entire
+     * project" fix) was unverifiable from past sessions: metadata only carried
+     * optionCount + defaultIndex, never the labels.
+     */
+    optionLabels?: string[];
+    /** Convenience: optionLabels[defaultIndex] — the recommended option's label. */
+    recommendedLabel?: string;
 }
 interface AskcardAnsweredPayload {
     questionId: string;

package/dist/src/storage/usage-cap.test.js

@@ -9,7 +9,7 @@ beforeEach(async () => {
     tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "usage-test-"));
 });
 afterEach(async () => {
-    await fs.rm(tmpDir, { recursive: true, force: true });
+    await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
 });
 function currentMonthUTC() {
     const d = new Date();

package/dist/src/storage/usage.js

@@ -12,31 +12,31 @@ export function recordUsageEvent(sessionId, source, model, usage, messageSeq, pi
     const cacheCreationTokens = usage.cacheCreationTokens ?? 0;
     const costMicros = estimateCostMicros(model, inputTokens, outputTokens, cacheReadTokens);
     getDatabase()
-        .prepare(`
-    INSERT INTO usage_events (
-      session_id, message_seq, source, model, input_tokens, output_tokens, total_tokens, cost_micros, created_at,
-      pil_active, enrichment_delta, cache_read_tokens, cache_creation_tokens, provider_options_shape
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        .prepare(`
+    INSERT INTO usage_events (
+      session_id, message_seq, source, model, input_tokens, output_tokens, total_tokens, cost_micros, created_at,
+      pil_active, enrichment_delta, cache_read_tokens, cache_creation_tokens, provider_options_shape
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `)
         .run(sessionId, messageSeq ?? null, source, model, inputTokens, outputTokens, totalTokens, costMicros, new Date().toISOString(), pilActive ? 1 : 0, enrichmentDelta, cacheReadTokens, cacheCreationTokens, providerOptionsShape);
 }
 export function getSessionTotalTokens(sessionId) {
     const row = getDatabase()
-        .prepare(`
-    SELECT COALESCE(SUM(total_tokens), 0) AS total_tokens
-    FROM usage_events
-    WHERE session_id = ?
+        .prepare(`
+    SELECT COALESCE(SUM(total_tokens), 0) AS total_tokens
+    FROM usage_events
+    WHERE session_id = ?
   `)
         .get(sessionId);
     return row?.total_tokens ?? 0;
 }
 export function listSessionUsage(sessionId) {
     const rows = getDatabase()
-        .prepare(`
-    SELECT id, session_id, message_seq, source, model, input_tokens, output_tokens, total_tokens, cost_micros, created_at, cache_read_tokens, cache_creation_tokens
-    FROM usage_events
-    WHERE session_id = ?
-    ORDER BY id ASC
+        .prepare(`
+    SELECT id, session_id, message_seq, source, model, input_tokens, output_tokens, total_tokens, cost_micros, created_at, cache_read_tokens, cache_creation_tokens
+    FROM usage_events
+    WHERE session_id = ?
+    ORDER BY id ASC
   `)
         .all(sessionId);
     return rows.map((row) => ({

package/dist/src/storage/workspaces.js

@@ -8,14 +8,14 @@ export function ensureWorkspace(cwd) {
     const now = new Date().toISOString();
     const id = createHash("sha1").update(resolved.scopeKey).digest("hex").slice(0, 16);
     const db = getDatabase();
-    db.prepare(`
-    INSERT INTO workspaces (id, scope_key, canonical_path, git_root, display_name, last_seen_at)
-    VALUES (@id, @scope_key, @canonical_path, @git_root, @display_name, @last_seen_at)
-    ON CONFLICT(scope_key) DO UPDATE SET
-      canonical_path = excluded.canonical_path,
-      git_root = excluded.git_root,
-      display_name = excluded.display_name,
-      last_seen_at = excluded.last_seen_at
+    db.prepare(`
+    INSERT INTO workspaces (id, scope_key, canonical_path, git_root, display_name, last_seen_at)
+    VALUES (@id, @scope_key, @canonical_path, @git_root, @display_name, @last_seen_at)
+    ON CONFLICT(scope_key) DO UPDATE SET
+      canonical_path = excluded.canonical_path,
+      git_root = excluded.git_root,
+      display_name = excluded.display_name,
+      last_seen_at = excluded.last_seen_at
   `).run({
         id,
         scope_key: resolved.scopeKey,
@@ -25,10 +25,10 @@ export function ensureWorkspace(cwd) {
         last_seen_at: now,
     });
     const row = db
-        .prepare(`
-    SELECT id, scope_key, canonical_path, git_root, display_name, last_seen_at
-    FROM workspaces
-    WHERE scope_key = ?
+        .prepare(`
+    SELECT id, scope_key, canonical_path, git_root, display_name, last_seen_at
+    FROM workspaces
+    WHERE scope_key = ?
   `)
         .get(resolved.scopeKey);
     if (!row) {

package/dist/src/tools/__tests__/vision-gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/__tests__/vision-gate.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { messagesHaveImagePart, VISION_TOOL_NAMES, visionToolsNeeded } from "../vision-gate.js";
+describe("visionToolsNeeded", () => {
+    it("drops vision tools for a pure-text turn with no image anywhere", () => {
+        expect(visionToolsNeeded({ userMessage: "what is this project about?", messages: [], cachedImageCount: 0 })).toBe(false);
+        expect(visionToolsNeeded({ userMessage: "fix the auth bug in src/auth/login.ts" })).toBe(false);
+    });
+    it("keeps vision tools when the message text references an image", () => {
+        for (const msg of [
+            "analyze screenshot.png",
+            "what does this diagram show?",
+            "review the figma mockup",
+            "here is a data:image/png;base64,AAAA",
+            "phân tích cái ảnh này giúp tôi",
+        ]) {
+            expect(visionToolsNeeded({ userMessage: msg })).toBe(true);
+        }
+    });
+    it("keeps vision tools when the turn carries an image content part (attachment)", () => {
+        const messages = [
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: "what is this?" },
+                    { type: "image", mediaType: "image/png", data: "BASE64" },
+                ],
+            },
+        ];
+        expect(visionToolsNeeded({ userMessage: "what is this?", messages })).toBe(true);
+    });
+    it("keeps vision tools when earlier turns cached images (follow-up queries)", () => {
+        expect(visionToolsNeeded({ userMessage: "what color is the button?", cachedImageCount: 2 })).toBe(true);
+    });
+    it("keeps vision tools on a continuation that already used tools (BUG-A guard)", () => {
+        expect(visionToolsNeeded({ userMessage: "continue", priorTurnHadTools: true })).toBe(true);
+    });
+    it("exports exactly the three vision tool ids (todo_write / core tools excluded)", () => {
+        expect([...VISION_TOOL_NAMES]).toEqual(["analyze_image", "ask_vision_proxy", "list_vision_cache"]);
+        expect(VISION_TOOL_NAMES).not.toContain("todo_write");
+        expect(VISION_TOOL_NAMES).not.toContain("read_file");
+    });
+});
+describe("messagesHaveImagePart", () => {
+    it("detects an image part by type", () => {
+        expect(messagesHaveImagePart([{ role: "user", content: [{ type: "image", data: "x" }] }])).toBe(true);
+    });
+    it("detects an image part by mediaType prefix", () => {
+        expect(messagesHaveImagePart([{ role: "user", content: [{ type: "file", mediaType: "image/jpeg" }] }])).toBe(true);
+    });
+    it("returns false for text-only content and malformed input", () => {
+        expect(messagesHaveImagePart([{ role: "user", content: [{ type: "text", text: "hi" }] }])).toBe(false);
+        expect(messagesHaveImagePart([{ role: "user", content: "plain string" }])).toBe(false);
+        expect(messagesHaveImagePart(undefined)).toBe(false);
+    });
+});
+//# sourceMappingURL=vision-gate.test.js.map

package/dist/src/tools/bash-output-cache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * src/tools/bash-output-cache.ts
+ *
+ * In-memory cache of full (ANSI-stripped, untruncated) stdout+stderr from
+ * foreground bash runs, keyed by a per-process monotonic `runId`. Backs the
+ * `bash_output_get` tool (Fix #2) so the agent can re-query a captured run
+ * with different head/tail/grep slices instead of re-running the command
+ * with cosmetic flag changes — the loop pattern observed in session
+ * `9b56560aeeb6` where the agent ran `bunx vitest run` 18 times.
+ *
+ * The cache lives in module scope (process singleton) — a session-scoped
+ * cache would complicate the BashTool API for negligible gain (entries
+ * naturally roll out via the LRU cap). Functions here are pure aside from
+ * the module-scoped Map; safe to unit-test by `clearBashOutputCache()`
+ * between cases.
+ */
+export interface BashRunRecord {
+    /** Stable run id, e.g. "bash-42". */
+    id: string;
+    /** The original command as passed to BashTool.execute. */
+    command: string;
+    /** Full stdout (ANSI-stripped). May be empty. */
+    stdout: string;
+    /** Full stderr (ANSI-stripped). May be empty. */
+    stderr: string;
+    /** Exit code if known, else null. */
+    exitCode: number | null;
+    /** ISO timestamp when execute() returned. */
+    completedAt: string;
+    /** Wall-clock duration in ms. */
+    durationMs: number;
+}
+export declare function nextBashRunId(): string;
+export declare function recordBashRun(record: Omit<BashRunRecord, "completedAt"> & {
+    completedAt?: string;
+}): void;
+export declare function getBashRun(id: string): BashRunRecord | null;
+export declare function listBashRunIds(): string[];
+export declare function clearBashOutputCache(): void;
+export declare function stripAnsi(text: string): string;
+export type BashSliceMode = "tail" | "head" | "grep" | "lines" | "full";
+export interface BashSliceInput {
+    mode: BashSliceMode;
+    /** Number of lines for head/tail. Defaults to 50. */
+    lines?: number;
+    /** Regex pattern for grep mode. */
+    pattern?: string;
+    /** Line range "N-M" (1-based inclusive) for lines mode. */
+    range?: string;
+    /** Case-insensitive grep. Default false. */
+    caseInsensitive?: boolean;
+}
+export interface BashSliceResult {
+    ok: boolean;
+    text: string;
+    matchedLines?: number;
+    totalLines: number;
+}
+export declare function sliceBashOutput(record: BashRunRecord, input: BashSliceInput): BashSliceResult;

package/dist/src/tools/bash-output-cache.js

@@ -0,0 +1,108 @@
+/**
+ * src/tools/bash-output-cache.ts
+ *
+ * In-memory cache of full (ANSI-stripped, untruncated) stdout+stderr from
+ * foreground bash runs, keyed by a per-process monotonic `runId`. Backs the
+ * `bash_output_get` tool (Fix #2) so the agent can re-query a captured run
+ * with different head/tail/grep slices instead of re-running the command
+ * with cosmetic flag changes — the loop pattern observed in session
+ * `9b56560aeeb6` where the agent ran `bunx vitest run` 18 times.
+ *
+ * The cache lives in module scope (process singleton) — a session-scoped
+ * cache would complicate the BashTool API for negligible gain (entries
+ * naturally roll out via the LRU cap). Functions here are pure aside from
+ * the module-scoped Map; safe to unit-test by `clearBashOutputCache()`
+ * between cases.
+ */
+const MAX_ENTRIES = 50;
+// LRU via insertion order. Map preserves insertion order; on access we
+// re-insert to bump the entry to the freshest position.
+const cache = new Map();
+let nextId = 1;
+export function nextBashRunId() {
+    return `bash-${nextId++}`;
+}
+export function recordBashRun(record) {
+    const entry = {
+        ...record,
+        completedAt: record.completedAt ?? new Date().toISOString(),
+    };
+    cache.delete(record.id); // ensure insertion-order bump
+    cache.set(record.id, entry);
+    while (cache.size > MAX_ENTRIES) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        cache.delete(oldest);
+    }
+}
+export function getBashRun(id) {
+    const r = cache.get(id);
+    if (!r)
+        return null;
+    // Touch to bump in LRU order.
+    cache.delete(id);
+    cache.set(id, r);
+    return r;
+}
+export function listBashRunIds() {
+    return [...cache.keys()];
+}
+export function clearBashOutputCache() {
+    cache.clear();
+    nextId = 1;
+}
+// ---------------------------------------------------------------------------
+// ANSI strip — matches the standard ECMA-48 CSI sequences plus the OSC and
+// single-character escapes vitest / bun emit even when FORCE_COLOR=0. Copied
+// out of strip-ansi (MIT, sindresorhus) to avoid pulling a runtime dep.
+// ---------------------------------------------------------------------------
+const ANSI_PATTERN = new RegExp([
+    "[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z0-9/#&.:=?%@~_]+)*|[a-zA-Z0-9]+(?:;[-a-zA-Z0-9/#&.:=?%@~_]*)*)?\\u0007)",
+    "(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]))",
+].join("|"), "g");
+export function stripAnsi(text) {
+    if (!text)
+        return text;
+    return text.replace(ANSI_PATTERN, "");
+}
+export function sliceBashOutput(record, input) {
+    const merged = record.stderr ? `${record.stdout}\n[stderr]\n${record.stderr}` : record.stdout;
+    const allLines = merged.length === 0 ? [] : merged.split("\n");
+    const total = allLines.length;
+    const lines = input.lines ?? 50;
+    switch (input.mode) {
+        case "full":
+            return { ok: true, text: merged, totalLines: total };
+        case "head":
+            return { ok: true, text: allLines.slice(0, Math.max(1, lines)).join("\n"), totalLines: total };
+        case "tail":
+            return { ok: true, text: allLines.slice(-Math.max(1, lines)).join("\n"), totalLines: total };
+        case "lines": {
+            const m = (input.range ?? "").match(/^(\d+)\s*-\s*(\d+)$/);
+            if (!m)
+                return { ok: false, text: "Invalid range — expected 'N-M' (1-based)", totalLines: total };
+            const start = Math.max(1, Number(m[1]));
+            const end = Math.min(total, Number(m[2]));
+            if (start > end)
+                return { ok: false, text: `Empty range (start ${start} > end ${end})`, totalLines: total };
+            return { ok: true, text: allLines.slice(start - 1, end).join("\n"), totalLines: total };
+        }
+        case "grep": {
+            if (!input.pattern)
+                return { ok: false, text: "Missing pattern for grep mode", totalLines: total };
+            let re;
+            try {
+                re = new RegExp(input.pattern, input.caseInsensitive ? "i" : "");
+            }
+            catch (err) {
+                return { ok: false, text: `Invalid regex: ${err.message}`, totalLines: total };
+            }
+            const matched = allLines.filter((l) => re.test(l));
+            return { ok: true, text: matched.join("\n"), matchedLines: matched.length, totalLines: total };
+        }
+        default:
+            return { ok: false, text: `Unknown mode: ${input.mode}`, totalLines: total };
+    }
+}
+//# sourceMappingURL=bash-output-cache.js.map

package/dist/src/tools/bash-output-cache.test.d.ts

@@ -0,0 +1 @@
+export {};