@vellumai/assistant 0.8.5 → 0.8.7

package/src/__tests__/conversation-queue.test.ts

@@ -1,10 +1,13 @@
 import { rmSync, writeFileSync } from "node:fs";
 import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { CompactionCircuit } from "../agent/compaction-circuit.js";
 import type {
   AgentEvent,
+  AgentLoopRunResult,
   CheckpointDecision,
   CheckpointInfo,
+  ExitReason,
 } from "../agent/loop.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import type { Message, ProviderResponse } from "../providers/types.js";
@@ -175,7 +178,7 @@ mock.module("../memory/conversation-crud.js", () => ({
     _convId: string,
     role: string,
     content: string,
-    metadata?: Record<string, unknown>,
+    options?: { metadata?: Record<string, unknown> },
   ) => {
     // Simulate a persist failure for tests that need to exercise the
     // tail-persist-failed path in drainBatch. Triggered by matching any
@@ -186,13 +189,20 @@ mock.module("../memory/conversation-crud.js", () => ({
       }
     }
     const id = `msg-${Date.now()}-${capturedAddMessages.length}`;
-    capturedAddMessages.push({ id, role, content, metadata });
+    capturedAddMessages.push({
+      id,
+      role,
+      content,
+      metadata: options?.metadata,
+    });
     return { id };
   },
   updateConversationUsage: () => {},
   updateConversationTitle: () => {},
   getMessageById: () => null,
   getLastUserTimestampBefore: () => 0,
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
+  updateMessageContent: mock(() => {}),
 }));
 
 mock.module("../memory/conversation-queries.js", () => ({
@@ -315,16 +325,24 @@ interface PendingRun {
   resolve: (history: Message[]) => void;
   reject: (err: Error) => void;
   messages: Message[];
-  onEvent: (event: AgentEvent) => void;
+  onEvent: (event: AgentEvent) => void | Promise<void>;
   onCheckpoint?: (
     checkpoint: CheckpointInfo,
   ) => CheckpointDecision | Promise<CheckpointDecision>;
+  /**
+   * Pause-reason recorded from the most recent `onCheckpoint` call, mirroring
+   * how the production loop carries it back via {@link AgentLoopRunResult}.
+   * `resolve(history)` packages this into the run result so the orchestrator
+   * derives its handoff bookkeeping the same way it does against the real loop.
+   */
+  exitReason: ExitReason | null;
 }
 
 let pendingRuns: PendingRun[] = [];
 
 mock.module("../agent/loop.js", () => ({
   AgentLoop: class {
+    compactionCircuit = new CompactionCircuit("test-conv");
     constructor() {}
     getToolTokenBudget() {
       return 0;
@@ -337,15 +355,33 @@ mock.module("../agent/loop.js", () => ({
     }
     async run(
       messages: Message[],
-      onEvent: (event: AgentEvent) => void,
-      _signal?: AbortSignal,
-      _requestId?: string,
-      onCheckpoint?: (
-        checkpoint: CheckpointInfo,
-      ) => CheckpointDecision | Promise<CheckpointDecision>,
-    ): Promise<Message[]> {
-      return new Promise<Message[]>((resolve, reject) => {
-        pendingRuns.push({ resolve, reject, messages, onEvent, onCheckpoint });
+      onEvent: (event: AgentEvent) => void | Promise<void>,
+      options?: {
+        onCheckpoint?: (
+          checkpoint: CheckpointInfo,
+        ) => CheckpointDecision | Promise<CheckpointDecision>;
+      },
+    ): Promise<AgentLoopRunResult> {
+      return new Promise<AgentLoopRunResult>((resolveResult, reject) => {
+        const pending: PendingRun = {
+          resolve: (history: Message[]) =>
+            resolveResult({
+              history,
+              exitReason: pending.exitReason,
+            }),
+          reject,
+          messages,
+          onEvent,
+          exitReason: null,
+          onCheckpoint: options?.onCheckpoint
+            ? async (checkpoint) => {
+                const decision = await options.onCheckpoint!(checkpoint);
+                pending.exitReason = decision === "continue" ? null : decision;
+                return decision;
+              }
+            : undefined,
+        };
+        pendingRuns.push(pending);
       });
     }
   },
@@ -409,9 +445,9 @@ function makeConversation(
     "conv-1",
     provider,
     "system prompt",
-    4096,
     sendToClient ?? (() => {}),
     "/tmp",
+    { maxTokens: 4096 },
   );
   const conversationWithWorkspaceDeps =
     conversationObj as ConversationWithWorkspaceDeps;
@@ -471,7 +507,7 @@ async function waitForCondition(
  * that `runAgentLoop` expects (usage + message_complete) so the conversation
  * cleanly transitions out of its processing state.
  */
-function resolveRun(index: number) {
+async function resolveRun(index: number) {
   const run = pendingRuns[index];
   if (!run) throw new Error(`No pending run at index ${index}`);
   // Emit the events runAgentLoop expects
@@ -479,14 +515,17 @@ function resolveRun(index: number) {
     role: "assistant",
     content: [{ type: "text", text: `reply-${index}` }],
   };
-  run.onEvent({
+  // Prime the assistant row anchor — production code emits this from
+  // `AgentLoop.run` just before `provider.sendMessage`.
+  await run.onEvent({ type: "llm_call_started" });
+  await run.onEvent({
     type: "usage",
     inputTokens: 10,
     outputTokens: 5,
     model: "mock",
     providerDurationMs: 100,
   });
-  run.onEvent({ type: "message_complete", message: assistantMsg });
+  await run.onEvent({ type: "message_complete", message: assistantMsg });
   // Return updated history with the assistant message appended
   run.resolve([...run.messages, assistantMsg]);
 }
@@ -519,12 +558,12 @@ describe("Conversation message queue", () => {
     const events2: ServerMessage[] = [];
 
     // Start first message — this will block on AgentLoop.run
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
 
     // Wait for the first AgentLoop.run to be registered
     await waitForPendingRun(1);
@@ -533,18 +572,17 @@ describe("Conversation message queue", () => {
     expect(conversation.isProcessing()).toBe(true);
 
     // Enqueue second message — should NOT throw
-    const result = conversation.enqueueMessage(
-      "msg-2",
-      [],
-      (e) => events2.push(e),
-      "req-2",
-    );
+    const result = conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
     expect(result.queued).toBe(true);
     expect(result.requestId).toBe("req-2");
     expect(conversation.getQueueDepth()).toBe(1);
 
     // Complete the first message
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // After the first run resolves, the queue drains and triggers a second run.
@@ -557,7 +595,7 @@ describe("Conversation message queue", () => {
     expect(pendingRuns.length).toBe(2);
 
     // Complete the second run
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -570,21 +608,29 @@ describe("Conversation message queue", () => {
     const events3: ServerMessage[] = [];
 
     // Start first message
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue two more sibling passthrough messages
-    conversation.enqueueMessage("msg-2", [], (e) => events2.push(e), "req-2");
-    conversation.enqueueMessage("msg-3", [], (e) => events3.push(e), "req-3");
+    conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
+    conversation.enqueueMessage({
+      content: "msg-3",
+      onEvent: (e) => events3.push(e),
+      requestId: "req-3",
+    });
     expect(conversation.getQueueDepth()).toBe(2);
 
     // Complete run 0 → drain pulls msg-2 and msg-3 into ONE batched run.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -623,7 +669,7 @@ describe("Conversation message queue", () => {
     expect(combinedUserText).toContain("msg-3");
 
     // Resolve the batched run; message_complete must fan out to both clients.
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
 
     expect(events2.some((e) => e.type === "message_complete")).toBe(true);
@@ -637,20 +683,23 @@ describe("Conversation message queue", () => {
     const events2: ServerMessage[] = [];
 
     // Start first message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue second — simulating what handleUserMessage does
-    const result = conversation.enqueueMessage(
-      "msg-2",
-      [],
-      (e) => events2.push(e),
-      "req-2",
-    );
+    const result = conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
     expect(result.queued).toBe(true);
 
     // Complete first
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -664,7 +713,7 @@ describe("Conversation message queue", () => {
     });
 
     // Complete second run so the conversation finishes cleanly
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -676,12 +725,24 @@ describe("Conversation message queue", () => {
     const events3: ServerMessage[] = [];
 
     // Start first message
-    conversation.processMessage("msg-1", [], () => {}, "req-1");
+    conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue two more
-    conversation.enqueueMessage("msg-2", [], (e) => events2.push(e), "req-2");
-    conversation.enqueueMessage("msg-3", [], (e) => events3.push(e), "req-3");
+    conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
+    conversation.enqueueMessage({
+      content: "msg-3",
+      onEvent: (e) => events3.push(e),
+      requestId: "req-3",
+    });
     expect(conversation.getQueueDepth()).toBe(2);
 
     // Abort
@@ -727,12 +788,12 @@ describe("Conversation message queue", () => {
     const events: ServerMessage[] = [];
 
     // Start a message — blocks on AgentLoop.run
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Reject the AgentLoop.run() with a provider error to trigger the
@@ -754,23 +815,27 @@ describe("Conversation message queue", () => {
     await conversation.loadFromDb();
 
     // Start first message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     expect(conversation.getQueueDepth()).toBe(0);
 
-    conversation.enqueueMessage("msg-2", [], () => {}, "req-2");
+    conversation.enqueueMessage({ content: "msg-2", requestId: "req-2" });
     expect(conversation.getQueueDepth()).toBe(1);
 
-    conversation.enqueueMessage("msg-3", [], () => {}, "req-3");
+    conversation.enqueueMessage({ content: "msg-3", requestId: "req-3" });
     expect(conversation.getQueueDepth()).toBe(2);
 
-    conversation.enqueueMessage("msg-4", [], () => {}, "req-4");
+    conversation.enqueueMessage({ content: "msg-4", requestId: "req-4" });
     expect(conversation.getQueueDepth()).toBe(3);
 
     // Complete first → drain pulls all three same-interface passthroughs
     // into a single batched run (depth → 0, runs → 2 total).
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -778,7 +843,7 @@ describe("Conversation message queue", () => {
     expect(pendingRuns.length).toBe(2);
 
     // Complete the batched run; conversation finishes cleanly.
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -791,23 +856,31 @@ describe("Conversation message queue", () => {
     const events3: ServerMessage[] = [];
 
     // Start first message — blocks on AgentLoop.run
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue a message with empty content (will fail persistUserMessage)
-    conversation.enqueueMessage("", [], (e) => events2.push(e), "req-2");
+    conversation.enqueueMessage({
+      content: "",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
     // Enqueue a valid message after the bad one
-    conversation.enqueueMessage("msg-3", [], (e) => events3.push(e), "req-3");
+    conversation.enqueueMessage({
+      content: "msg-3",
+      onEvent: (e) => events3.push(e),
+      requestId: "req-3",
+    });
     expect(conversation.getQueueDepth()).toBe(2);
 
     // Complete first message — triggers drain. The empty message should fail
     // to persist, but the drain should continue to msg-3.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // msg-3 should have been dequeued and started a new AgentLoop.run
@@ -824,7 +897,7 @@ describe("Conversation message queue", () => {
     expect(events3.some((e) => e.type === "message_dequeued")).toBe(true);
 
     // Complete the third message's run
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
 
     // msg-3 should have completed successfully
@@ -851,7 +924,11 @@ describe("Batched drain", () => {
     const events5: ServerMessage[] = [];
 
     // Start in-flight message (msg-1)
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue 4 messages with interfaces [macos, macos, cli, macos].
@@ -860,46 +937,34 @@ describe("Batched drain", () => {
       userMessageInterface: iface,
       assistantMessageInterface: iface,
     });
-    conversation.enqueueMessage(
-      "msg-2",
-      [],
-      (e) => events2.push(e),
-      "req-2",
-      undefined,
-      undefined,
-      meta("macos"),
-    );
-    conversation.enqueueMessage(
-      "msg-3",
-      [],
-      (e) => events3.push(e),
-      "req-3",
-      undefined,
-      undefined,
-      meta("macos"),
-    );
-    conversation.enqueueMessage(
-      "msg-4",
-      [],
-      (e) => events4.push(e),
-      "req-4",
-      undefined,
-      undefined,
-      meta("cli"),
-    );
-    conversation.enqueueMessage(
-      "msg-5",
-      [],
-      (e) => events5.push(e),
-      "req-5",
-      undefined,
-      undefined,
-      meta("macos"),
-    );
+    conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+      metadata: meta("macos"),
+    });
+    conversation.enqueueMessage({
+      content: "msg-3",
+      onEvent: (e) => events3.push(e),
+      requestId: "req-3",
+      metadata: meta("macos"),
+    });
+    conversation.enqueueMessage({
+      content: "msg-4",
+      onEvent: (e) => events4.push(e),
+      requestId: "req-4",
+      metadata: meta("cli"),
+    });
+    conversation.enqueueMessage({
+      content: "msg-5",
+      onEvent: (e) => events5.push(e),
+      requestId: "req-5",
+      metadata: meta("macos"),
+    });
     expect(conversation.getQueueDepth()).toBe(4);
 
     // Resolve msg-1 → batched run pulls macos msg-2 + msg-3.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -927,7 +992,7 @@ describe("Batched drain", () => {
     );
 
     // Resolve the batched run → drain pulls the cli single-message run.
-    resolveRun(1);
+    await resolveRun(1);
     await waitForPendingRun(3);
 
     // cli run contains msg-4 as a single-message run.
@@ -942,7 +1007,7 @@ describe("Batched drain", () => {
     );
 
     // Resolve the cli run → drain pulls the final macos single-message run.
-    resolveRun(2);
+    await resolveRun(2);
     await waitForPendingRun(4);
     const finalHistory = pendingRuns[3].messages;
     const finalUserText = finalHistory
@@ -957,7 +1022,7 @@ describe("Batched drain", () => {
     // Four total runs: msg-1, batched [msg-2, msg-3], msg-4, msg-5.
     expect(pendingRuns.length).toBe(4);
 
-    resolveRun(3);
+    await resolveRun(3);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -970,36 +1035,37 @@ describe("Batched drain", () => {
     const eventsWorld: ServerMessage[] = [];
 
     // Start in-flight message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue ["hello", "/compact", "world"]. /compact resolves to a non-
     // passthrough slash, so the batch builder stops at "hello" (length 1),
     // then /compact takes the single-message /compact short-circuit path
     // (no new runAgentLoop invocation), then "world" drains as its own run.
-    conversation.enqueueMessage(
-      "hello",
-      [],
-      (e) => eventsHello.push(e),
-      "req-hello",
-    );
-    conversation.enqueueMessage(
-      "/compact",
-      [],
-      (e) => eventsSlash.push(e),
-      "req-slash",
-    );
-    conversation.enqueueMessage(
-      "world",
-      [],
-      (e) => eventsWorld.push(e),
-      "req-world",
-    );
+    conversation.enqueueMessage({
+      content: "hello",
+      onEvent: (e) => eventsHello.push(e),
+      requestId: "req-hello",
+    });
+    conversation.enqueueMessage({
+      content: "/compact",
+      onEvent: (e) => eventsSlash.push(e),
+      requestId: "req-slash",
+    });
+    conversation.enqueueMessage({
+      content: "world",
+      onEvent: (e) => eventsWorld.push(e),
+      requestId: "req-world",
+    });
     expect(conversation.getQueueDepth()).toBe(3);
 
     // Resolve msg-1 → drain pulls "hello" as its own run (batch stops at
     // /compact boundary).
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -1010,7 +1076,7 @@ describe("Batched drain", () => {
 
     // Resolve "hello" → drain pops /compact via the builder-rejected path,
     // runs its short-circuit (no new runAgentLoop), then drains "world".
-    resolveRun(1);
+    await resolveRun(1);
     await waitForPendingRun(3);
 
     // /compact should have emitted its own message_complete via the short-
@@ -1019,7 +1085,7 @@ describe("Batched drain", () => {
     expect(eventsWorld.some((e) => e.type === "message_dequeued")).toBe(true);
     expect(pendingRuns.length).toBe(3);
 
-    resolveRun(2);
+    await resolveRun(2);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1042,7 +1108,11 @@ describe("Batched drain", () => {
     const eventsPlainB: ServerMessage[] = [];
 
     // Start in-flight message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue ["plain-a", "/status", "plain-b"]. /status resolves to a non-
@@ -1051,29 +1121,26 @@ describe("Batched drain", () => {
     // unknown-slash short-circuit path (no new runAgentLoop invocation — it
     // emits assistant_text_delta + message_complete inline), then "plain-b"
     // drains as its own run.
-    conversation.enqueueMessage(
-      "plain-a",
-      [],
-      (e) => eventsPlainA.push(e),
-      "req-plain-a",
-    );
-    conversation.enqueueMessage(
-      "/status",
-      [],
-      (e) => eventsSlash.push(e),
-      "req-slash",
-    );
-    conversation.enqueueMessage(
-      "plain-b",
-      [],
-      (e) => eventsPlainB.push(e),
-      "req-plain-b",
-    );
+    conversation.enqueueMessage({
+      content: "plain-a",
+      onEvent: (e) => eventsPlainA.push(e),
+      requestId: "req-plain-a",
+    });
+    conversation.enqueueMessage({
+      content: "/status",
+      onEvent: (e) => eventsSlash.push(e),
+      requestId: "req-slash",
+    });
+    conversation.enqueueMessage({
+      content: "plain-b",
+      onEvent: (e) => eventsPlainB.push(e),
+      requestId: "req-plain-b",
+    });
     expect(conversation.getQueueDepth()).toBe(3);
 
     // Resolve msg-1 → drain pulls "plain-a" as its own run (batch stops at
     // the /status boundary).
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -1086,7 +1153,7 @@ describe("Batched drain", () => {
     // runs its unknown-slash short-circuit (no new runAgentLoop, emits
     // assistant_text_delta + message_complete inline), then drains "plain-b"
     // as its own run.
-    resolveRun(1);
+    await resolveRun(1);
     await waitForPendingRun(3);
 
     // /status should have emitted its own assistant_text_delta + message_complete
@@ -1100,7 +1167,7 @@ describe("Batched drain", () => {
     // without a runAgentLoop invocation.
     expect(pendingRuns.length).toBe(3);
 
-    resolveRun(2);
+    await resolveRun(2);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1110,7 +1177,11 @@ describe("Batched drain", () => {
     await conversation.loadFromDb();
 
     // Start in-flight message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Two sibling messages, each with a distinct image attachment.
@@ -1132,11 +1203,19 @@ describe("Batched drain", () => {
         filePath: "/tmp/b.png",
       },
     ];
-    conversation.enqueueMessage("with-A", attachA, () => {}, "req-A");
-    conversation.enqueueMessage("with-B", attachB, () => {}, "req-B");
+    conversation.enqueueMessage({
+      content: "with-A",
+      attachments: attachA,
+      requestId: "req-A",
+    });
+    conversation.enqueueMessage({
+      content: "with-B",
+      attachments: attachB,
+      requestId: "req-B",
+    });
     expect(conversation.getQueueDepth()).toBe(2);
 
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -1170,7 +1249,7 @@ describe("Batched drain", () => {
     expect(allText).toContain("a.png");
     expect(allText).toContain("b.png");
 
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1185,34 +1264,33 @@ describe("Batched drain", () => {
       new MessageQueue(budget);
 
     // Start in-flight so subsequent enqueues are queued (not processed).
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Fill to just-under budget: two ~500-char messages (1512+1512 = 3024 bytes).
-    const accepted1 = conversation.enqueueMessage(
-      "x".repeat(500),
-      [],
-      () => {},
-      "req-big-1",
-    );
-    const accepted2 = conversation.enqueueMessage(
-      "y".repeat(500),
-      [],
-      () => {},
-      "req-big-2",
-    );
+    const accepted1 = conversation.enqueueMessage({
+      content: "x".repeat(500),
+      requestId: "req-big-1",
+    });
+    const accepted2 = conversation.enqueueMessage({
+      content: "y".repeat(500),
+      requestId: "req-big-2",
+    });
     expect(accepted1.queued).toBe(true);
     expect(accepted2.queued).toBe(true);
     // A third would push the queue over budget → rejected. Capture its
     // onEvent callback so we can verify the queue_full error event reaches
     // the rejected caller (not just the synchronous return value).
     const rejectedEvents: ServerMessage[] = [];
-    const rejected = conversation.enqueueMessage(
-      "z".repeat(500),
-      [],
-      (e) => rejectedEvents.push(e),
-      "req-over",
-    );
+    const rejected = conversation.enqueueMessage({
+      content: "z".repeat(500),
+      onEvent: (e) => rejectedEvents.push(e),
+      requestId: "req-over",
+    });
     expect(rejected.queued).toBe(false);
     expect(rejected.rejected).toBe(true);
     expect(conversation.getQueueDepth()).toBe(2);
@@ -1231,33 +1309,41 @@ describe("Batched drain", () => {
     }
 
     // Complete in-flight → drain pulls both queued passthroughs as ONE batched run.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
     expect(conversation.getQueueDepth()).toBe(0);
 
     // Resolve the batched run.
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
 
     // After the full drain, the byte budget must be fully reclaimed — a fresh
     // round of enqueues up to the budget should succeed again. Spin up another
     // in-flight message to reach the queueing state.
-    const p2 = conversation.processMessage("msg-2", [], () => {}, "req-2");
+    const p2 = conversation.processMessage({
+      content: "msg-2",
+      attachments: [],
+      requestId: "req-2",
+    });
     await waitForPendingRun(3);
     expect(
-      conversation.enqueueMessage("a".repeat(500), [], () => {}, "req-a")
-        .queued,
+      conversation.enqueueMessage({
+        content: "a".repeat(500),
+        requestId: "req-a",
+      }).queued,
     ).toBe(true);
     expect(
-      conversation.enqueueMessage("b".repeat(500), [], () => {}, "req-b")
-        .queued,
+      conversation.enqueueMessage({
+        content: "b".repeat(500),
+        requestId: "req-b",
+      }).queued,
     ).toBe(true);
 
-    resolveRun(2);
+    await resolveRun(2);
     await p2;
     await waitForPendingRun(4);
-    resolveRun(3);
+    await resolveRun(3);
     await new Promise((r) => setTimeout(r, 10));
   });
 });
@@ -1281,7 +1367,11 @@ describe("Batched drain correctness fixes", () => {
     const eventsRegular: ServerMessage[] = [];
 
     // Start in-flight message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue a surface-action message (activeSurfaceId set + tracked in
@@ -1289,25 +1379,23 @@ describe("Batched drain correctness fixes", () => {
     // same interface. The batch builder must reject the surface-action head
     // so each drains as its own run.
     conversation.surfaceActionRequestIds.add("req-surface");
-    conversation.enqueueMessage(
-      "surface action response",
-      [],
-      (e) => eventsSurface.push(e),
-      "req-surface",
-      "surface-1", // activeSurfaceId
-    );
-    conversation.enqueueMessage(
-      "regular follow-up",
-      [],
-      (e) => eventsRegular.push(e),
-      "req-regular",
-    );
+    conversation.enqueueMessage({
+      content: "surface action response",
+      onEvent: (e) => eventsSurface.push(e),
+      requestId: "req-surface",
+      activeSurfaceId: "surface-1",
+    });
+    conversation.enqueueMessage({
+      content: "regular follow-up",
+      onEvent: (e) => eventsRegular.push(e),
+      requestId: "req-regular",
+    });
     expect(conversation.getQueueDepth()).toBe(2);
 
     // Complete run 0 → drain must NOT batch the surface-action with the
     // regular passthrough. Expect the surface-action to drain as a single
     // run first.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -1322,7 +1410,7 @@ describe("Batched drain correctness fixes", () => {
 
     // Complete the surface-action run; drain pulls the regular passthrough
     // as its own separate run.
-    resolveRun(1);
+    await resolveRun(1);
     await waitForPendingRun(3);
     expect(pendingRuns.length).toBe(3);
     expect(
@@ -1331,7 +1419,7 @@ describe("Batched drain correctness fixes", () => {
 
     // Total runs = 3: msg-1, surface-action, regular — NOT 2 (would mean
     // they were batched).
-    resolveRun(2);
+    await resolveRun(2);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1345,12 +1433,12 @@ describe("Batched drain correctness fixes", () => {
     const events4: ServerMessage[] = [];
 
     // Start in-flight message
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue three sibling passthroughs (msg-2 = head, msg-3 = mid,
@@ -1360,7 +1448,11 @@ describe("Batched drain correctness fixes", () => {
     // fresh one). Calling abort() now aborts that fresh controller, and
     // the drainBatch loop's abort check after msg-3's persist will break,
     // so msg-4 never persists.
-    conversation.enqueueMessage("msg-2", [], (e) => events2.push(e), "req-2");
+    conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
 
     // Install a one-shot abort trigger on msg-3's dequeue event. We do
     // this before enqueueing so the wrapped callback is what drainBatch
@@ -1373,8 +1465,16 @@ describe("Batched drain correctness fixes", () => {
         conversation.abort();
       }
     };
-    conversation.enqueueMessage("msg-3", [], onMsg3Event, "req-3");
-    conversation.enqueueMessage("msg-4", [], (e) => events4.push(e), "req-4");
+    conversation.enqueueMessage({
+      content: "msg-3",
+      onEvent: onMsg3Event,
+      requestId: "req-3",
+    });
+    conversation.enqueueMessage({
+      content: "msg-4",
+      onEvent: (e) => events4.push(e),
+      requestId: "req-4",
+    });
     expect(conversation.getQueueDepth()).toBe(3);
 
     const persistedUserRowCountBefore = capturedAddMessages.filter(
@@ -1382,7 +1482,7 @@ describe("Batched drain correctness fixes", () => {
     ).length;
 
     // Complete run 0 → drain pulls the sibling batch.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // Give the drain loop a chance to iterate. Abort happens on msg-3's
@@ -1412,12 +1512,12 @@ describe("Batched drain correctness fixes", () => {
     const events4: ServerMessage[] = [];
 
     // Start in-flight message
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue three siblings. Configure addMessage to throw for the second
@@ -1426,28 +1526,25 @@ describe("Batched drain correctness fixes", () => {
     // msg-tail's requestId (the LAST successful persist), not msg-mid's.
     addMessageShouldThrowForContent.add("msg-mid-unique-marker");
 
-    conversation.enqueueMessage(
-      "msg-head",
-      [],
-      (e) => events2.push(e),
-      "req-head",
-    );
-    conversation.enqueueMessage(
-      "msg-mid-unique-marker",
-      [],
-      (e) => events3.push(e),
-      "req-mid",
-    );
-    conversation.enqueueMessage(
-      "msg-tail",
-      [],
-      (e) => events4.push(e),
-      "req-tail",
-    );
+    conversation.enqueueMessage({
+      content: "msg-head",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-head",
+    });
+    conversation.enqueueMessage({
+      content: "msg-mid-unique-marker",
+      onEvent: (e) => events3.push(e),
+      requestId: "req-mid",
+    });
+    conversation.enqueueMessage({
+      content: "msg-tail",
+      onEvent: (e) => events4.push(e),
+      requestId: "req-tail",
+    });
     expect(conversation.getQueueDepth()).toBe(3);
 
     // Complete run 0 → batched drain.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -1464,7 +1561,7 @@ describe("Batched drain correctness fixes", () => {
     ).toBe("req-tail");
 
     // Cleanup: resolve the batched run.
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 20));
   });
 
@@ -1477,12 +1574,12 @@ describe("Batched drain correctness fixes", () => {
     const events3: ServerMessage[] = [];
     const events4: ServerMessage[] = [];
 
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Mid tail will fail to persist. After the batched run resolves,
@@ -1492,31 +1589,28 @@ describe("Batched drain correctness fixes", () => {
     // desync the client.
     addMessageShouldThrowForContent.add("fanout-mid-marker");
 
-    conversation.enqueueMessage(
-      "fanout-head",
-      [],
-      (e) => events2.push(e),
-      "req-fanout-head",
-    );
-    conversation.enqueueMessage(
-      "fanout-mid-marker",
-      [],
-      (e) => events3.push(e),
-      "req-fanout-mid",
-    );
-    conversation.enqueueMessage(
-      "fanout-tail",
-      [],
-      (e) => events4.push(e),
-      "req-fanout-tail",
-    );
+    conversation.enqueueMessage({
+      content: "fanout-head",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-fanout-head",
+    });
+    conversation.enqueueMessage({
+      content: "fanout-mid-marker",
+      onEvent: (e) => events3.push(e),
+      requestId: "req-fanout-mid",
+    });
+    conversation.enqueueMessage({
+      content: "fanout-tail",
+      onEvent: (e) => events4.push(e),
+      requestId: "req-fanout-tail",
+    });
 
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
     // Drive the batched run to emit message_complete via fanOutOnEvent.
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 20));
 
     expect(events3.find((e) => e.type === "error")).toBeDefined();
@@ -1536,7 +1630,11 @@ describe("Batched drain correctness fixes", () => {
     await conversation.loadFromDb();
 
     // Start in-flight message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Snapshot the count before drain so we only compare batch-emitted
@@ -1544,12 +1642,12 @@ describe("Batched drain correctness fixes", () => {
     const baseline = activityStates.length;
 
     // Enqueue three sibling passthroughs.
-    conversation.enqueueMessage("msg-2", [], () => {}, "req-2");
-    conversation.enqueueMessage("msg-3", [], () => {}, "req-3");
-    conversation.enqueueMessage("msg-4", [], () => {}, "req-4");
+    conversation.enqueueMessage({ content: "msg-2", requestId: "req-2" });
+    conversation.enqueueMessage({ content: "msg-3", requestId: "req-3" });
+    conversation.enqueueMessage({ content: "msg-4", requestId: "req-4" });
 
     // Complete run 0 → drain pulls the batched siblings as ONE run.
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -1569,7 +1667,7 @@ describe("Batched drain correctness fixes", () => {
       requestId: "req-2", // head's requestId, per the fix
     });
 
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1610,17 +1708,21 @@ describe("Conversation queue policy helpers", () => {
     await conversation.loadFromDb();
 
     // Start processing to make the session busy
-    conversation.processMessage("msg-1", [], () => {}, "req-1");
+    conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue a message while processing
-    conversation.enqueueMessage("msg-2", [], () => {}, "req-2");
+    conversation.enqueueMessage({ content: "msg-2", requestId: "req-2" });
     expect(conversation.hasQueuedMessages()).toBe(true);
 
     // Cleanup: resolve the pending run
-    resolveRun(0);
+    await resolveRun(0);
     await waitForPendingRun(2);
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1637,7 +1739,11 @@ describe("Conversation queue policy helpers", () => {
     await conversation.loadFromDb();
 
     // Start processing — but don't enqueue anything
-    conversation.processMessage("msg-1", [], () => {}, "req-1");
+    conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     expect(conversation.isProcessing()).toBe(true);
@@ -1645,7 +1751,7 @@ describe("Conversation queue policy helpers", () => {
     expect(conversation.canHandoffAtCheckpoint()).toBe(false);
 
     // Cleanup
-    resolveRun(0);
+    await resolveRun(0);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1654,20 +1760,24 @@ describe("Conversation queue policy helpers", () => {
     await conversation.loadFromDb();
 
     // Start processing
-    conversation.processMessage("msg-1", [], () => {}, "req-1");
+    conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue a message
-    conversation.enqueueMessage("msg-2", [], () => {}, "req-2");
+    conversation.enqueueMessage({ content: "msg-2", requestId: "req-2" });
 
     expect(conversation.isProcessing()).toBe(true);
     expect(conversation.hasQueuedMessages()).toBe(true);
     expect(conversation.canHandoffAtCheckpoint()).toBe(true);
 
     // Cleanup
-    resolveRun(0);
+    await resolveRun(0);
     await waitForPendingRun(2);
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1705,16 +1815,16 @@ describe("Conversation checkpoint handoff", () => {
     const events1: ServerMessage[] = [];
 
     // Start processing first message
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue a second message while the first is processing
-    conversation.enqueueMessage("msg-2", [], () => {}, "req-2");
+    conversation.enqueueMessage({ content: "msg-2", requestId: "req-2" });
     expect(conversation.hasQueuedMessages()).toBe(true);
 
     // The pending run should have received an onCheckpoint callback.
@@ -1728,11 +1838,11 @@ describe("Conversation checkpoint handoff", () => {
       history: [],
     });
 
-    // Because there is a queued message, the callback should return 'yield'
-    expect(decision).toBe("yield");
+    // Because there is a queued message, the callback should yield for handoff
+    expect(decision).toEqual("handoff");
 
     // Complete the run so the conversation finishes cleanly
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // After yield, the first message should emit generation_handoff
@@ -1747,7 +1857,7 @@ describe("Conversation checkpoint handoff", () => {
 
     // The queued message should now be draining (second run started)
     await waitForPendingRun(2);
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1756,7 +1866,11 @@ describe("Conversation checkpoint handoff", () => {
     await conversation.loadFromDb();
 
     // Start processing — no enqueued messages
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     expect(conversation.hasQueuedMessages()).toBe(false);
@@ -1775,7 +1889,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(decision).toBe("continue");
 
     // Cleanup
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
   });
 
@@ -1789,18 +1903,30 @@ describe("Conversation checkpoint handoff", () => {
     const events4: ServerMessage[] = [];
 
     // Start first message (mid-tool-use — will yield at the next checkpoint)
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue three sibling passthroughs while msg-1 is mid-turn
-    conversation.enqueueMessage("msg-2", [], (e) => events2.push(e), "req-2");
-    conversation.enqueueMessage("msg-3", [], (e) => events3.push(e), "req-3");
-    conversation.enqueueMessage("msg-4", [], (e) => events4.push(e), "req-4");
+    conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
+    conversation.enqueueMessage({
+      content: "msg-3",
+      onEvent: (e) => events3.push(e),
+      requestId: "req-3",
+    });
+    conversation.enqueueMessage({
+      content: "msg-4",
+      onEvent: (e) => events4.push(e),
+      requestId: "req-4",
+    });
     expect(conversation.getQueueDepth()).toBe(3);
 
     // Simulate the agent loop yielding at the checkpoint (first run is mid-tool-use)
@@ -1812,10 +1938,10 @@ describe("Conversation checkpoint handoff", () => {
       hasToolUse: true,
       history: [],
     });
-    expect(decision).toBe("yield");
+    expect(decision).toEqual("handoff");
 
     // Complete first run
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // The yielded drain pulls ALL THREE queued siblings as ONE batched run —
@@ -1829,7 +1955,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(events4.some((e) => e.type === "message_dequeued")).toBe(true);
 
     // Resolve the batched run — message_complete fans out to all three clients.
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
 
     expect(events2.some((e) => e.type === "message_complete")).toBe(true);
@@ -1845,20 +1971,24 @@ describe("Conversation checkpoint handoff", () => {
     const events2: ServerMessage[] = [];
 
     // Start processing first message
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue a second message while the first is processing
-    conversation.enqueueMessage("msg-2", [], (e) => events2.push(e), "req-2");
+    conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => events2.push(e),
+      requestId: "req-2",
+    });
     expect(conversation.hasQueuedMessages()).toBe(true);
 
     // Simulate tool-use turns: the agent loop calls onCheckpoint at each turn boundary.
-    // Because there is a queued message, the callback should return 'yield'.
+    // Because there is a queued message, the callback should yield for handoff.
     const run = pendingRuns[0];
     expect(run.onCheckpoint).toBeDefined();
 
@@ -1870,10 +2000,10 @@ describe("Conversation checkpoint handoff", () => {
       hasToolUse: true,
       history: [],
     });
-    expect(decision).toBe("yield");
+    expect(decision).toEqual("handoff");
 
     // Complete the run (AgentLoop resolves after yielding)
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // Verify generation_handoff was emitted (not plain message_complete)
@@ -1896,7 +2026,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(events2.some((e) => e.type === "message_dequeued")).toBe(true);
 
     // Complete the second run
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1912,12 +2042,12 @@ describe("Conversation checkpoint handoff", () => {
     };
 
     // Start processing message A
-    const pA = conversation.processMessage(
-      "msg-A",
-      [],
-      (e) => eventsA.push(e),
-      "req-A",
-    );
+    const pA = conversation.processMessage({
+      content: "msg-A",
+      attachments: [],
+      onEvent: (e) => eventsA.push(e),
+      requestId: "req-A",
+    });
     await waitForPendingRun(1);
 
     // Enqueue messages B, C, D — each on a distinct userMessageInterface so the
@@ -1926,33 +2056,24 @@ describe("Conversation checkpoint handoff", () => {
       userMessageInterface: iface,
       assistantMessageInterface: iface,
     });
-    conversation.enqueueMessage(
-      "msg-B",
-      [],
-      makeHandler("B"),
-      "req-B",
-      undefined,
-      undefined,
-      meta("macos"),
-    );
-    conversation.enqueueMessage(
-      "msg-C",
-      [],
-      makeHandler("C"),
-      "req-C",
-      undefined,
-      undefined,
-      meta("cli"),
-    );
-    conversation.enqueueMessage(
-      "msg-D",
-      [],
-      makeHandler("D"),
-      "req-D",
-      undefined,
-      undefined,
-      meta("vellum"),
-    );
+    conversation.enqueueMessage({
+      content: "msg-B",
+      onEvent: makeHandler("B"),
+      requestId: "req-B",
+      metadata: meta("macos"),
+    });
+    conversation.enqueueMessage({
+      content: "msg-C",
+      onEvent: makeHandler("C"),
+      requestId: "req-C",
+      metadata: meta("cli"),
+    });
+    conversation.enqueueMessage({
+      content: "msg-D",
+      onEvent: makeHandler("D"),
+      requestId: "req-D",
+      metadata: meta("vellum"),
+    });
     expect(conversation.getQueueDepth()).toBe(3);
 
     // Handoff from A -> B
@@ -1965,8 +2086,8 @@ describe("Conversation checkpoint handoff", () => {
         hasToolUse: true,
         history: [],
       }),
-    ).toBe("yield");
-    resolveRun(0);
+    ).toEqual("handoff");
+    await resolveRun(0);
     await pA;
 
     // B should be draining
@@ -1982,8 +2103,8 @@ describe("Conversation checkpoint handoff", () => {
         hasToolUse: true,
         history: [],
       }),
-    ).toBe("yield");
-    resolveRun(1);
+    ).toEqual("handoff");
+    await resolveRun(1);
     await waitForPendingRun(3);
 
     // Handoff from C -> D
@@ -1997,8 +2118,8 @@ describe("Conversation checkpoint handoff", () => {
         hasToolUse: true,
         history: [],
       }),
-    ).toBe("yield");
-    resolveRun(2);
+    ).toEqual("handoff");
+    await resolveRun(2);
     await waitForPendingRun(4);
 
     // D has no more queued -> checkpoint should return 'continue'
@@ -2013,7 +2134,7 @@ describe("Conversation checkpoint handoff", () => {
       }),
     ).toBe("continue");
 
-    resolveRun(3);
+    await resolveRun(3);
     await new Promise((r) => setTimeout(r, 10));
 
     // Verify FIFO dequeue order
@@ -2029,21 +2150,29 @@ describe("Conversation checkpoint handoff", () => {
     const eventsC: ServerMessage[] = [];
 
     // Start processing message A
-    const pA = conversation.processMessage(
-      "msg-A",
-      [],
-      (e) => eventsA.push(e),
-      "req-A",
-    );
+    const pA = conversation.processMessage({
+      content: "msg-A",
+      attachments: [],
+      onEvent: (e) => eventsA.push(e),
+      requestId: "req-A",
+    });
     await waitForPendingRun(1);
 
     // Enqueue B (empty content — will fail to persist) and C (valid)
-    conversation.enqueueMessage("", [], (e) => eventsB.push(e), "req-B");
-    conversation.enqueueMessage("msg-C", [], (e) => eventsC.push(e), "req-C");
+    conversation.enqueueMessage({
+      content: "",
+      onEvent: (e) => eventsB.push(e),
+      requestId: "req-B",
+    });
+    conversation.enqueueMessage({
+      content: "msg-C",
+      onEvent: (e) => eventsC.push(e),
+      requestId: "req-C",
+    });
     expect(conversation.getQueueDepth()).toBe(2);
 
     // Complete message A — triggers drain. B should fail, C should proceed.
-    resolveRun(0);
+    await resolveRun(0);
     await pA;
 
     // C should have been dequeued and started a new AgentLoop.run
@@ -2060,7 +2189,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(eventsC.some((e) => e.type === "message_dequeued")).toBe(true);
 
     // Complete C's run
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
 
     // C should have completed successfully
@@ -2072,7 +2201,11 @@ describe("Conversation checkpoint handoff", () => {
     await conversation.loadFromDb();
 
     // Start processing
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // The first run should have onCheckpoint
@@ -2097,7 +2230,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(pendingRuns[1].onCheckpoint).toBeDefined();
 
     // Complete retry cleanly
-    resolveRun(1);
+    await resolveRun(1);
     await p1;
   });
 });
@@ -2116,11 +2249,15 @@ describe("Conversation usage requestId correlation", () => {
     const conversation = makeConversation();
     await conversation.loadFromDb();
 
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-42");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-42",
+    });
     await waitForPendingRun(1);
 
     // Complete the run — this triggers recordUsage with the request's ID
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // The usage event should carry the request ID, not null
@@ -2149,16 +2286,20 @@ describe("Terminal trace events on rejection/failure", () => {
     await conversation.loadFromDb();
 
     // Start first message
-    const p1 = conversation.processMessage("msg-1", [], () => {}, "req-1");
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Enqueue empty content (will fail persistUserMessage)
-    conversation.enqueueMessage("", [], () => {}, "req-bad");
+    conversation.enqueueMessage({ content: "", requestId: "req-bad" });
     // Enqueue valid message so drain continues
-    conversation.enqueueMessage("msg-3", [], () => {}, "req-3");
+    conversation.enqueueMessage({ content: "msg-3", requestId: "req-3" });
 
     // Complete first — triggers drain, empty msg fails persist
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
@@ -2173,7 +2314,7 @@ describe("Terminal trace events on rejection/failure", () => {
     expect(errorTrace).toBeDefined();
 
     // Cleanup
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 });
@@ -2197,12 +2338,12 @@ describe("Conversation host attachment directives", () => {
       const conversation = makeConversation((msg) => clientEvents.push(msg));
       await conversation.loadFromDb();
 
-      const p1 = conversation.processMessage(
-        "msg-1",
-        [],
-        (e) => events.push(e),
-        "req-1",
-      );
+      const p1 = conversation.processMessage({
+        content: "msg-1",
+        attachments: [],
+        onEvent: (e) => events.push(e),
+        requestId: "req-1",
+      });
       await waitForPendingRun(1);
 
       const run = pendingRuns[0];
@@ -2215,6 +2356,7 @@ describe("Conversation host attachment directives", () => {
           },
         ],
       };
+      await run.onEvent({ type: "llm_call_started" });
       run.onEvent({
         type: "usage",
         inputTokens: 10,
@@ -2266,12 +2408,12 @@ describe("Conversation host attachment directives", () => {
       const conversation = makeConversation((msg) => clientEvents.push(msg));
       await conversation.loadFromDb();
 
-      const p1 = conversation.processMessage(
-        "msg-1",
-        [],
-        (e) => events.push(e),
-        "req-1",
-      );
+      const p1 = conversation.processMessage({
+        content: "msg-1",
+        attachments: [],
+        onEvent: (e) => events.push(e),
+        requestId: "req-1",
+      });
       await waitForPendingRun(1);
 
       const run = pendingRuns[0];
@@ -2284,6 +2426,7 @@ describe("Conversation host attachment directives", () => {
           },
         ],
       };
+      await run.onEvent({ type: "llm_call_started" });
       run.onEvent({
         type: "usage",
         inputTokens: 10,
@@ -2352,12 +2495,12 @@ describe("Conversation attachment event payloads", () => {
     const conversation = makeConversation();
     await conversation.loadFromDb();
 
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     const run = pendingRuns[0];
@@ -2377,6 +2520,7 @@ describe("Conversation attachment event payloads", () => {
         } as any,
       ],
     });
+    await run.onEvent({ type: "llm_call_started" });
     run.onEvent({
       type: "usage",
       inputTokens: 10,
@@ -2414,16 +2558,16 @@ describe("Conversation attachment event payloads", () => {
     const conversation = makeConversation();
     await conversation.loadFromDb();
 
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events1.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events1.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Queue a second message so the first run yields via checkpoint handoff.
-    conversation.enqueueMessage("msg-2", [], () => {}, "req-2");
+    conversation.enqueueMessage({ content: "msg-2", requestId: "req-2" });
 
     const run = pendingRuns[0];
     expect(run.onCheckpoint).toBeDefined();
@@ -2434,7 +2578,7 @@ describe("Conversation attachment event payloads", () => {
         hasToolUse: true,
         history: [],
       }),
-    ).toBe("yield");
+    ).toEqual("handoff");
 
     const assistantMsg: Message = {
       role: "assistant",
@@ -2452,6 +2596,7 @@ describe("Conversation attachment event payloads", () => {
         } as any,
       ],
     });
+    await run.onEvent({ type: "llm_call_started" });
     run.onEvent({
       type: "usage",
       inputTokens: 10,
@@ -2478,7 +2623,7 @@ describe("Conversation attachment event payloads", () => {
     expect(attachments[0].data).toBe("iVBORw0K");
 
     await waitForPendingRun(2);
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 });
@@ -2498,19 +2643,19 @@ describe("Regression: cancel semantics and error channel split", () => {
     await conversation.loadFromDb();
 
     // Start processing a message — collect events from the per-message callback
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => msgEvents.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => msgEvents.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // User cancels — sets the abort signal
     conversation.abort();
 
     // Resolve the pending run so the abort-check path fires
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // generation_cancelled should be emitted via the per-message callback
@@ -2532,12 +2677,12 @@ describe("Regression: cancel semantics and error channel split", () => {
     await conversation.loadFromDb();
     linkAttachmentShouldThrow = true;
 
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => events.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => events.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
     const run = pendingRuns[0];
     const assistantMsg: Message = {
@@ -2556,6 +2701,7 @@ describe("Regression: cancel semantics and error channel split", () => {
         } as any,
       ],
     });
+    await run.onEvent({ type: "llm_call_started" });
     run.onEvent({
       type: "usage",
       inputTokens: 10,
@@ -2585,12 +2731,12 @@ describe("Regression: cancel semantics and error channel split", () => {
     const conversation = makeConversation();
     await conversation.loadFromDb();
 
-    const p1 = conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => allEvents.push(e),
-      "req-1",
-    );
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => allEvents.push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
     // Simulate a provider failure
@@ -2614,26 +2760,24 @@ describe("Regression: cancel semantics and error channel split", () => {
 
     const eventsPerMsg: ServerMessage[][] = [[], [], []];
 
-    conversation.processMessage(
-      "msg-1",
-      [],
-      (e) => eventsPerMsg[0].push(e),
-      "req-1",
-    );
+    conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: (e) => eventsPerMsg[0].push(e),
+      requestId: "req-1",
+    });
     await waitForPendingRun(1);
 
-    conversation.enqueueMessage(
-      "msg-2",
-      [],
-      (e) => eventsPerMsg[1].push(e),
-      "req-2",
-    );
-    conversation.enqueueMessage(
-      "msg-3",
-      [],
-      (e) => eventsPerMsg[2].push(e),
-      "req-3",
-    );
+    conversation.enqueueMessage({
+      content: "msg-2",
+      onEvent: (e) => eventsPerMsg[1].push(e),
+      requestId: "req-2",
+    });
+    conversation.enqueueMessage({
+      content: "msg-3",
+      onEvent: (e) => eventsPerMsg[2].push(e),
+      requestId: "req-3",
+    });
 
     conversation.abort();
 
@@ -2668,19 +2812,23 @@ describe("Regression: cancel semantics and error channel split", () => {
       const events2: ServerMessage[] = [];
 
       // Start first message (promise intentionally not awaited — we test queue drain behavior)
-      const _p1 = conversation.processMessage(
-        "msg-1",
-        [],
-        (e) => events1.push(e),
-        "req-1",
-      );
+      const _p1 = conversation.processMessage({
+        content: "msg-1",
+        attachments: [],
+        onEvent: (e) => events1.push(e),
+        requestId: "req-1",
+      });
       await waitForPendingRun(1);
 
       // Enqueue a second message while the first is processing
-      conversation.enqueueMessage("msg-2", [], (e) => events2.push(e), "req-2");
+      conversation.enqueueMessage({
+        content: "msg-2",
+        onEvent: (e) => events2.push(e),
+        requestId: "req-2",
+      });
 
       // Complete the first agent loop run
-      resolveRun(0);
+      await resolveRun(0);
 
       // The turn should still complete (timeout fires) and drain the queue
       // even though commitTurnChanges never resolves.
@@ -2701,7 +2849,7 @@ describe("Regression: cancel semantics and error channel split", () => {
 
       // Complete the second run so the test can clean up
       turnCommitHangForever = false;
-      resolveRun(1);
+      await resolveRun(1);
       await new Promise((r) => origSetTimeout(r, 10));
     } finally {
       turnCommitHangForever = false;