brownian-code 2026.2.13 → 2026.6.4

package/src/agent/agent.test.ts

@@ -1,50 +1,88 @@
-import { describe, test, expect, mock, beforeAll, afterAll, beforeEach } from 'bun:test';
-import { createMockAIMessage, createMockTool, createTempDir } from '../test-utils/mocks.js';
-import type { AgentEvent, DoneEvent } from './types.js';
+import {
+  describe,
+  test,
+  expect,
+  mock,
+  beforeAll,
+  afterAll,
+  beforeEach,
+} from "bun:test";
+import { join } from "path";
+import {
+  createMockAIMessage,
+  createMockTool,
+  createTempDir,
+} from "../test-utils/mocks.js";
+import type { AgentConfig, AgentEvent, DoneEvent } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // Mock dependencies before importing Agent
 // ---------------------------------------------------------------------------
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const mockCallLlm = mock(async (): Promise<any> => ({
-  response: 'default response',
-  usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
-}));
+const mockCallLlm = mock(
+  async (): Promise<any> => ({
+    response: "default response",
+    usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+  }),
+);
+
+// Force the agent loop's blocking fallback by making streaming throw.
+// Tests drive scenarios via mockCallLlm (which doubles as
+// callLlmWithMessages). Streaming-specific tests can still override.
+const mockStreamLlmWithMessages = mock(async function* (): AsyncGenerator<
+  unknown,
+  void
+> {
+  throw new Error("Streaming mocked off — blocking path used in tests");
+});
 
-mock.module('../model/llm.js', () => ({
+mock.module("../model/llm.js", () => ({
   callLlm: mockCallLlm,
-  DEFAULT_MODEL: 'claude-sonnet-4-5',
-}));
-
-const mockGetTools = mock(() => [
-  createMockTool('search', '{"results": "BTC is $65000"}'),
-  createMockTool('api', '{"data": "some api data"}'),
-]);
-
-mock.module('../tools/registry.js', () => ({
-  getTools: mockGetTools,
-  buildToolDescriptions: () => 'Mock tool descriptions',
+  callLlmWithMessages: mockCallLlm,
+  streamLlmWithMessages: mockStreamLlmWithMessages,
+  DEFAULT_MODEL: "claude-sonnet-4-5",
+  DEFAULT_PROVIDER: "anthropic",
+  getChatModel: () => ({}),
+  getFastModel: (_provider: string, fallback: string) => fallback,
 }));
 
-mock.module('./prompts.js', () => ({
-  buildSystemPrompt: () => 'You are a test agent.',
-  buildIterationPrompt: (query: string, results: string) => `Query: ${query}\nResults: ${results}`,
-  buildFinalAnswerPrompt: (query: string, context: string) => `Answer: ${query}\nContext: ${context}`,
-  DEFAULT_SYSTEM_PROMPT: 'Default test system prompt.',
+// Disable the agent's MCP warm-up during tests so it doesn't make
+// real network calls. The flag is checked in src/agent/agent.ts.
+process.env.BROWNIAN_SKIP_MCP_WARMUP = "1";
+
+// Tool-result-storage is mocked so individual tests can simulate disk-write
+// failure (mockPersistLargeResult.mockImplementationOnce). Defaults preserve
+// the real behavior shape so existing tests are unaffected.
+const mockPersistLargeResult = mock(
+  (toolName: string, callId: string, _result: string) => ({
+    preview: `[mocked preview for ${toolName}]`,
+    filePath: `/tmp/mocked-${callId}.txt`,
+  }),
+);
+const mockExceedsSizeCap = mock((s: string) => s.length > 50_000);
+const mockBuildPersistedContent = mock(
+  (filePath: string, preview: string, originalSizeBytes: number) =>
+    `[Result persisted to ${filePath} (${Math.round(originalSizeBytes / 1024)} KB)]\n\nPreview:\n${preview}`,
+);
+
+mock.module("../utils/tool-result-storage.js", () => ({
+  exceedsSizeCap: mockExceedsSizeCap,
+  persistLargeResult: mockPersistLargeResult,
+  buildPersistedContent: mockBuildPersistedContent,
+  MAX_TOOL_RESULT_CHARS: 50_000,
+  PREVIEW_CHARS: 2_000,
 }));
 
-mock.module('../utils/tool-description.js', () => ({
-  getToolDescription: (name: string) => name,
-}));
+// Import Agent after mocks
+const { Agent } = await import("./agent.js");
 
-mock.module('../skills/index.js', () => ({
-  discoverSkills: () => [],
-  buildSkillMetadataSection: () => '',
-}));
+const createDefaultTools = () => [
+  createMockTool("search", '{"results": "BTC is $65000"}'),
+  createMockTool("api", '{"data": "some api data"}'),
+];
 
-// Import Agent after mocks
-const { Agent } = await import('./agent.js');
+let activeTools = createDefaultTools();
 
 // ---------------------------------------------------------------------------
 // Setup temp CWD for scratchpad files
@@ -52,26 +90,38 @@ const { Agent } = await import('./agent.js');
 
 let originalCwd: string;
 let cleanup: () => void;
+let originalBrownianDir: string | undefined;
 
 beforeAll(() => {
   originalCwd = process.cwd();
+  originalBrownianDir = process.env.BROWNIAN_DIR;
   const tmp = createTempDir();
   cleanup = tmp.cleanup;
   process.chdir(tmp.path);
+  process.env.BROWNIAN_DIR = join(tmp.path, ".brownian");
 });
 
 afterAll(() => {
   process.chdir(originalCwd);
+  if (originalBrownianDir === undefined) {
+    delete process.env.BROWNIAN_DIR;
+  } else {
+    process.env.BROWNIAN_DIR = originalBrownianDir;
+  }
   cleanup();
 });
 
 beforeEach(() => {
-  mockCallLlm.mockClear();
-  mockGetTools.mockClear();
-  mockGetTools.mockReturnValue([
-    createMockTool('search', '{"results": "BTC is $65000"}'),
-    createMockTool('api', '{"data": "some api data"}'),
-  ]);
+  // mockReset clears both the call history AND queued return values
+  // (mockResolvedValueOnce). The new agent loop consumes fewer LLM
+  // calls per iteration than the old loop, so leftover queued values
+  // from a prior test can leak into the next one if we only mockClear.
+  mockCallLlm.mockReset();
+  mockCallLlm.mockResolvedValue({
+    response: "default response",
+    usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+  });
+  activeTools = createDefaultTools();
 });
 
 // ---------------------------------------------------------------------------
@@ -88,97 +138,121 @@ async function collectEvents(agent: any, query: string): Promise<AgentEvent[]> {
 }
 
 function findDone(events: AgentEvent[]): DoneEvent {
-  return events.find(e => e.type === 'done') as DoneEvent;
+  return events.find((e) => e.type === "done") as DoneEvent;
+}
+
+async function createTestAgent(config: AgentConfig = {}) {
+  return Agent.create({
+    model: "claude-sonnet-4-5",
+    memoryEnabled: false,
+    systemPrompt: "You are a test agent.",
+    tools: activeTools as unknown as NonNullable<AgentConfig["tools"]>,
+    ...config,
+  });
 }
 
 // ---------------------------------------------------------------------------
 // Simple query (no tools)
 // ---------------------------------------------------------------------------
 
-describe('Agent - simple query (no tools)', () => {
-  test('LLM returns string → done with text, iterations=1', async () => {
+describe("Agent - simple query (no tools)", () => {
+  test("LLM returns string → done with text, iterations=1", async () => {
     mockCallLlm.mockResolvedValue({
-      response: 'Hello! How can I help?',
+      response: "Hello! How can I help?",
       usage: { inputTokens: 50, outputTokens: 20, totalTokens: 70 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'hi');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "hi");
 
     const done = findDone(events);
     expect(done).toBeDefined();
-    expect(done.answer).toBe('Hello! How can I help?');
+    expect(done.answer).toBe("Hello! How can I help?");
     expect(done.iterations).toBe(1);
     expect(done.toolCalls.length).toBe(0);
   });
+
+  test("strips markdown heading markers from final answers", async () => {
+    mockCallLlm.mockResolvedValue({
+      response:
+        "## PEPE Token Analysis\n\n### Risk Summary\n\nUse **small** sizing.\n\n*Data via CoinGecko*",
+      usage: { inputTokens: 50, outputTokens: 20, totalTokens: 70 },
+    });
+
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "analyze PEPE");
+
+    const done = findDone(events);
+    expect(done.answer).toBe(
+      "PEPE Token Analysis\n\nRisk Summary\n\nUse **small** sizing.\n\nData via CoinGecko",
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------
 // Single tool call
 // ---------------------------------------------------------------------------
 
-describe('Agent - tool calls', () => {
-  test('single tool call flow: tool_start → tool_end → done', async () => {
+describe("Agent - tool calls", () => {
+  test("single tool call flow: tool_start → tool_end → done", async () => {
     // First call: LLM wants to call a tool
     mockCallLlm.mockResolvedValueOnce({
-      response: createMockAIMessage('Let me search for that', [
-        { name: 'search', args: { query: 'BTC price' } },
+      response: createMockAIMessage("Let me search for that", [
+        { name: "search", args: { query: "BTC price" } },
       ]),
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     // Second call: LLM gives final answer (no tools)
     mockCallLlm.mockResolvedValueOnce({
-      response: 'BTC is at $65,000',
+      response: "BTC is at $65,000",
       usage: { inputTokens: 200, outputTokens: 100, totalTokens: 300 },
     });
     // Third call: final answer generation
     mockCallLlm.mockResolvedValueOnce({
-      response: 'Bitcoin is currently priced at $65,000.',
+      response: "Bitcoin is currently priced at $65,000.",
       usage: { inputTokens: 150, outputTokens: 80, totalTokens: 230 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'What is BTC price?');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "What is BTC price?");
 
-    const types = events.map(e => e.type);
-    expect(types).toContain('tool_start');
-    expect(types).toContain('tool_end');
-    expect(types).toContain('done');
+    const types = events.map((e) => e.type);
+    expect(types).toContain("tool_start");
+    expect(types).toContain("tool_end");
+    expect(types).toContain("done");
 
     const done = findDone(events);
     expect(done.toolCalls.length).toBeGreaterThan(0);
   });
 
-  test('tool error: yields tool_error and agent continues', async () => {
-    const errorTool = createMockTool('broken', () => {
-      throw new Error('API timeout');
+  test("tool error: yields tool_error and agent continues", async () => {
+    const errorTool = createMockTool("broken", () => {
+      throw new Error("API timeout");
     });
-    mockGetTools.mockReturnValue([errorTool]);
+    activeTools = [errorTool];
 
     // LLM calls the broken tool
     mockCallLlm.mockResolvedValueOnce({
-      response: createMockAIMessage('', [
-        { name: 'broken', args: {} },
-      ]),
+      response: createMockAIMessage("", [{ name: "broken", args: {} }]),
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     // LLM gives answer after error
     mockCallLlm.mockResolvedValueOnce({
-      response: 'I encountered an error.',
+      response: "I encountered an error.",
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     // Final answer generation
     mockCallLlm.mockResolvedValueOnce({
-      response: 'Sorry, there was an error getting the data.',
+      response: "Sorry, there was an error getting the data.",
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'test error');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "test error");
 
-    const types = events.map(e => e.type);
-    expect(types).toContain('tool_error');
-    expect(types).toContain('done');
+    const types = events.map((e) => e.type);
+    expect(types).toContain("tool_error");
+    expect(types).toContain("done");
   });
 });
 
@@ -186,17 +260,19 @@ describe('Agent - tool calls', () => {
 // Max iterations
 // ---------------------------------------------------------------------------
 
-describe('Agent - max iterations', () => {
-  test('stops at max iterations and still generates final answer', async () => {
+describe("Agent - max iterations", () => {
+  test("stops at max iterations and still generates final answer", async () => {
     // Always return tool calls to force max iterations
     mockCallLlm.mockResolvedValue({
-      response: createMockAIMessage('thinking...', [
-        { name: 'search', args: { query: 'loop' } },
+      response: createMockAIMessage("thinking...", [
+        { name: "search", args: { query: "loop" } },
       ]),
       usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5', maxIterations: 2 });
+    const agent = await createTestAgent({
+      maxIterations: 2,
+    });
 
     // Override only the last callLlm (final answer after max iterations)
     let callCount = 0;
@@ -204,20 +280,20 @@ describe('Agent - max iterations', () => {
       callCount++;
       if (callCount <= 2) {
         return {
-          response: createMockAIMessage('', [
-            { name: 'search', args: { query: `attempt ${callCount}` } },
+          response: createMockAIMessage("", [
+            { name: "search", args: { query: `attempt ${callCount}` } },
           ]),
           usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
         };
       }
       // Final answer generation call
       return {
-        response: 'Max iterations reached, here is what I found.',
+        response: "Max iterations reached, here is what I found.",
         usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
       };
     });
 
-    const events = await collectEvents(agent, 'loop test');
+    const events = await collectEvents(agent, "loop test");
     const done = findDone(events);
     expect(done).toBeDefined();
     expect(done.iterations).toBe(2);
@@ -228,15 +304,15 @@ describe('Agent - max iterations', () => {
 // No tools available
 // ---------------------------------------------------------------------------
 
-describe('Agent - no tools', () => {
+describe("Agent - no tools", () => {
   test('yields done with "No tools available" message', async () => {
-    mockGetTools.mockReturnValue([]);
+    activeTools = [];
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'test query');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "test query");
 
     const done = findDone(events);
-    expect(done.answer).toContain('No tools available');
+    expect(done.answer).toContain("No tools available");
     expect(done.iterations).toBe(0);
   });
 });
@@ -245,38 +321,38 @@ describe('Agent - no tools', () => {
 // Skill deduplication
 // ---------------------------------------------------------------------------
 
-describe('Agent - skill deduplication', () => {
-  test('same skill called twice → second skipped', async () => {
+describe("Agent - skill deduplication", () => {
+  test("same skill called twice → second skipped", async () => {
     const skillInvocations: string[] = [];
-    const skillTool = createMockTool('skill', (args) => {
+    const skillTool = createMockTool("skill", (args) => {
       skillInvocations.push(args.skill as string);
-      return 'skill result';
+      return "skill result";
     });
-    mockGetTools.mockReturnValue([skillTool]);
+    activeTools = [skillTool];
 
     // LLM requests same skill twice in one response
     mockCallLlm.mockResolvedValueOnce({
-      response: createMockAIMessage('', [
-        { name: 'skill', args: { skill: 'price-lookup' } },
-        { name: 'skill', args: { skill: 'price-lookup' } },
+      response: createMockAIMessage("", [
+        { name: "skill", args: { skill: "price-lookup" } },
+        { name: "skill", args: { skill: "price-lookup" } },
       ]),
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     mockCallLlm.mockResolvedValueOnce({
-      response: 'Done.',
+      response: "Done.",
       usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
     });
     mockCallLlm.mockResolvedValueOnce({
-      response: 'Final answer after skill.',
+      response: "Final answer after skill.",
       usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'run skill');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "run skill");
 
     // Skill should only have been invoked once
     expect(skillInvocations.length).toBe(1);
-    expect(skillInvocations[0]).toBe('price-lookup');
+    expect(skillInvocations[0]).toBe("price-lookup");
   });
 });
 
@@ -284,30 +360,30 @@ describe('Agent - skill deduplication', () => {
 // Thinking events
 // ---------------------------------------------------------------------------
 
-describe('Agent - thinking events', () => {
-  test('emits thinking event when LLM includes text alongside tool calls', async () => {
+describe("Agent - thinking events", () => {
+  test("emits thinking event when LLM includes text alongside tool calls", async () => {
     mockCallLlm.mockResolvedValueOnce({
-      response: createMockAIMessage('Let me search for Bitcoin data.', [
-        { name: 'search', args: { query: 'BTC' } },
+      response: createMockAIMessage("Let me search for Bitcoin data.", [
+        { name: "search", args: { query: "BTC" } },
       ]),
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     mockCallLlm.mockResolvedValueOnce({
-      response: 'BTC is $65k',
+      response: "BTC is $65k",
       usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
     });
     mockCallLlm.mockResolvedValueOnce({
-      response: 'Bitcoin costs $65,000.',
+      response: "Bitcoin costs $65,000.",
       usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'BTC price');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "BTC price");
 
-    const thinking = events.find(e => e.type === 'thinking');
+    const thinking = events.find((e) => e.type === "thinking");
     expect(thinking).toBeDefined();
-    if (thinking?.type === 'thinking') {
-      expect(thinking.message).toContain('search for Bitcoin');
+    if (thinking?.type === "thinking") {
+      expect(thinking.message).toContain("search for Bitcoin");
     }
   });
 });
@@ -316,15 +392,15 @@ describe('Agent - thinking events', () => {
 // Token usage tracking
 // ---------------------------------------------------------------------------
 
-describe('Agent - token usage', () => {
-  test('done event includes accumulated token usage', async () => {
+describe("Agent - token usage", () => {
+  test("done event includes accumulated token usage", async () => {
     mockCallLlm.mockResolvedValue({
-      response: 'Quick answer',
+      response: "Quick answer",
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'simple');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "simple");
 
     const done = findDone(events);
     expect(done.tokenUsage).toBeDefined();
@@ -337,46 +413,48 @@ describe('Agent - token usage', () => {
 // buildFullContextForAnswer
 // ---------------------------------------------------------------------------
 
-describe('Agent - context building', () => {
-  test('filters out error results from final context', async () => {
-    const errorTool = createMockTool('flaky', (args) => {
-      if (args.fail) throw new Error('timeout');
+describe("Agent - context building", () => {
+  test("filters out error results from final context", async () => {
+    const errorTool = createMockTool("flaky", (args) => {
+      if (args.fail) throw new Error("timeout");
       return '{"data": "good"}';
     });
-    const goodTool = createMockTool('reliable', () => '{"data": "success"}');
-    mockGetTools.mockReturnValue([errorTool, goodTool]);
+    const goodTool = createMockTool("reliable", () => '{"data": "success"}');
+    activeTools = [errorTool, goodTool];
 
     // First call: both tools, one will fail
     mockCallLlm.mockResolvedValueOnce({
-      response: createMockAIMessage('', [
-        { name: 'flaky', args: { fail: true } },
-        { name: 'reliable', args: {} },
+      response: createMockAIMessage("", [
+        { name: "flaky", args: { fail: true } },
+        { name: "reliable", args: {} },
       ]),
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     // Second call: no more tools
     mockCallLlm.mockResolvedValueOnce({
-      response: 'data gathered',
+      response: "data gathered",
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     // Final answer
     mockCallLlm.mockResolvedValueOnce({
-      response: 'Here is the result from reliable tool.',
+      response: "Here is the result from reliable tool.",
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'mixed results');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "mixed results");
 
     const done = findDone(events);
     expect(done.answer).toBeDefined();
     // The final answer prompt should have been called with context that excludes errors
     // We can verify the LLM was called with a prompt that doesn't include "Error:"
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const lastCallArgs = mockCallLlm.mock.calls[mockCallLlm.mock.calls.length - 1] as any[];
+    const lastCallArgs = mockCallLlm.mock.calls[
+      mockCallLlm.mock.calls.length - 1
+    ] as any[];
     const promptArg = lastCallArgs?.[0] as string;
     if (promptArg) {
-      expect(promptArg).not.toContain('Error: timeout');
+      expect(promptArg).not.toContain("Error: timeout");
     }
   });
 });
@@ -385,30 +463,176 @@ describe('Agent - context building', () => {
 // answer_start event
 // ---------------------------------------------------------------------------
 
-describe('Agent - answer_start event', () => {
-  test('emits answer_start before done', async () => {
+describe("Agent - answer_start event", () => {
+  test("emits answer_start before done", async () => {
     mockCallLlm.mockResolvedValueOnce({
-      response: createMockAIMessage('', [
-        { name: 'search', args: { query: 'test' } },
+      response: createMockAIMessage("", [
+        { name: "search", args: { query: "test" } },
       ]),
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
     });
     mockCallLlm.mockResolvedValueOnce({
-      response: 'done searching',
+      response: "done searching",
       usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
     });
     mockCallLlm.mockResolvedValueOnce({
-      response: 'Final answer.',
+      response: "Final answer.",
       usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
     });
 
-    const agent = Agent.create({ model: 'claude-sonnet-4-5' });
-    const events = await collectEvents(agent, 'test');
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "test");
 
-    const types = events.map(e => e.type);
-    const answerStartIdx = types.indexOf('answer_start');
-    const doneIdx = types.indexOf('done');
+    const types = events.map((e) => e.type);
+    const answerStartIdx = types.indexOf("answer_start");
+    const doneIdx = types.indexOf("done");
     expect(answerStartIdx).toBeGreaterThanOrEqual(0);
     expect(doneIdx).toBeGreaterThan(answerStartIdx);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Disk-full / persistLargeResult regression
+// ---------------------------------------------------------------------------
+
+describe("Agent - large tool result resilience", () => {
+  test("persistLargeResult error does not crash agent loop (disk-full regression)", async () => {
+    // Force the size-cap branch and make the disk write throw, simulating a
+    // full disk or unwritable ~/.brownian/tool-results/.
+    mockExceedsSizeCap.mockImplementationOnce(() => true);
+    mockPersistLargeResult.mockImplementationOnce(() => {
+      throw new Error("ENOSPC: no space left on device");
+    });
+
+    const bigResult = "X".repeat(60_000);
+    activeTools = [createMockTool("huge_tool", bigResult)];
+
+    // 1. Agent calls huge_tool
+    mockCallLlm.mockResolvedValueOnce({
+      response: createMockAIMessage("looking up", [
+        { name: "huge_tool", args: {} },
+      ]),
+      usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+    });
+    // 2. Agent has results, returns final answer (no more tool calls).
+    // The new loop emits the AIMessage's text directly — no separate
+    // final-answer LLM call like the old loop had.
+    mockCallLlm.mockResolvedValueOnce({
+      response: "Done.",
+      usage: { inputTokens: 200, outputTokens: 100, totalTokens: 300 },
+    });
+
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "huge tool query");
+
+    // Agent should have completed (not crashed)
+    const done = findDone(events);
+    expect(done).toBeDefined();
+    expect(done.answer).toBe("Done.");
+    // No tool errors should have been emitted (the disk failure should be silent)
+    const toolErrors = events.filter((e) => e.type === "tool_error");
+    expect(toolErrors.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Dexter-parity wirings: queue drain, context-overflow retry
+// ---------------------------------------------------------------------------
+
+describe("Agent - Dexter-parity wirings", () => {
+  test("drainQueue: emits queue_drain when MessageQueue has pending items", async () => {
+    // Iter 1: tool call.
+    mockCallLlm.mockResolvedValueOnce({
+      response: createMockAIMessage("looking up", [
+        { name: "search", args: { query: "BTC" } },
+      ]),
+      usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+    });
+    // Iter 2: final answer.
+    mockCallLlm.mockResolvedValueOnce({
+      response: "Answer with mid-run input merged.",
+      usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+    });
+
+    // Build a stub MessageQueue with one queued message ready to drain
+    // between iterations.
+    let drained = false;
+    const messageQueue = {
+      isEmpty: () => drained,
+      dequeueAll: () => {
+        drained = true;
+        return [{ text: "Also include ETH", timestamp: Date.now() }];
+      },
+      enqueue: () => {},
+      size: () => (drained ? 0 : 1),
+      clear: () => {
+        drained = true;
+      },
+    };
+
+    const agent = await createTestAgent({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      messageQueue: messageQueue as any,
+    });
+    const events = await collectEvents(agent, "BTC price");
+
+    const drain = events.find((e) => e.type === "queue_drain");
+    expect(drain).toBeDefined();
+    if (drain?.type === "queue_drain") {
+      expect(drain.messageCount).toBe(1);
+      expect(drain.mergedText).toContain("Also include ETH");
+    }
+  });
+
+  test("isContextOverflowError: retries with truncated messages", async () => {
+    // First LLM call throws a context-overflow error.
+    mockCallLlm.mockImplementationOnce(async () => {
+      throw new Error("context length exceeded");
+    });
+    // Second LLM call (after retry/truncate) returns final answer.
+    mockCallLlm.mockResolvedValueOnce({
+      response: "Recovered after truncation.",
+      usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+    });
+
+    // Seed history so truncate has something to drop.
+    const inMemoryHistory = {
+      hasMessages: () => false,
+      selectRelevantMessages: async () => [],
+    };
+    const agent = await createTestAgent();
+
+    // The retry path needs the messages array to actually have rounds
+    // to truncate. With an empty history and just the first turn, there
+    // are no rounds yet, so the retry will exhaust its budget and emit
+    // a done-with-error. Either outcome counts as "doesn't crash".
+    const events: AgentEvent[] = [];
+    for await (const ev of agent.run(
+      "tell me about BTC",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      inMemoryHistory as any,
+    )) {
+      events.push(ev);
+    }
+
+    const done = findDone(events);
+    expect(done).toBeDefined();
+    // Loop terminated cleanly; either with the recovered answer or a
+    // surfaced error done-event. Both are acceptable outcomes.
+    expect(typeof done.answer).toBe("string");
+  });
+
+  test("microcompact-trigger event types are emitted (smoke)", async () => {
+    // Stress test: many small tool calls that don't trigger thresholds
+    // here, but exercise that the event union accepts the new types.
+    mockCallLlm.mockResolvedValueOnce({
+      response: "Quick answer.",
+      usage: { inputTokens: 50, outputTokens: 20, totalTokens: 70 },
+    });
+    const agent = await createTestAgent();
+    const events = await collectEvents(agent, "hi");
+    const types = events.map((e) => e.type);
+    // Should have terminated cleanly with done.
+    expect(types).toContain("done");
+  });
+});