@vellumai/assistant 0.8.4 → 0.8.6

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

@@ -193,6 +193,8 @@ mock.module("../memory/conversation-crud.js", () => ({
   updateConversationTitle: () => {},
   getMessageById: () => null,
   getLastUserTimestampBefore: () => 0,
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
+  updateMessageContent: mock(() => {}),
 }));
 
 mock.module("../memory/conversation-queries.js", () => ({
@@ -315,7 +317,7 @@ 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>;
@@ -337,7 +339,7 @@ mock.module("../agent/loop.js", () => ({
     }
     async run(
       messages: Message[],
-      onEvent: (event: AgentEvent) => void,
+      onEvent: (event: AgentEvent) => void | Promise<void>,
       _signal?: AbortSignal,
       _requestId?: string,
       onCheckpoint?: (
@@ -471,7 +473,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 +481,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]);
 }
@@ -533,18 +538,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 +561,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));
   });
 
@@ -579,12 +583,20 @@ describe("Conversation message queue", () => {
     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 +635,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);
@@ -641,16 +653,15 @@ describe("Conversation message queue", () => {
     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 +675,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));
   });
 
@@ -680,8 +691,16 @@ describe("Conversation message queue", () => {
     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
@@ -759,18 +778,18 @@ describe("Conversation message queue", () => {
 
     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 +797,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));
   });
 
@@ -800,14 +819,22 @@ describe("Conversation message queue", () => {
     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 +851,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
@@ -860,46 +887,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 +942,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 +957,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 +972,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));
   });
 
@@ -977,29 +992,26 @@ describe("Batched drain", () => {
     // 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 +1022,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 +1031,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));
   });
 
@@ -1051,29 +1063,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 +1095,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 +1109,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));
   });
 
@@ -1132,11 +1141,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 +1187,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));
   });
 
@@ -1189,30 +1206,25 @@ describe("Batched drain", () => {
     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,13 +1243,13 @@ 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
@@ -1246,18 +1258,22 @@ describe("Batched drain", () => {
     const p2 = conversation.processMessage("msg-2", [], () => {}, "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));
   });
 });
@@ -1289,25 +1305,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 +1336,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 +1345,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));
   });
 
@@ -1360,7 +1374,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 +1391,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 +1408,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
@@ -1426,28 +1452,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 +1487,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));
   });
 
@@ -1492,31 +1515,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();
@@ -1544,12 +1564,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 +1589,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));
   });
 
@@ -1614,13 +1634,13 @@ describe("Conversation queue policy helpers", () => {
     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));
   });
 
@@ -1645,7 +1665,7 @@ describe("Conversation queue policy helpers", () => {
     expect(conversation.canHandoffAtCheckpoint()).toBe(false);
 
     // Cleanup
-    resolveRun(0);
+    await resolveRun(0);
     await new Promise((r) => setTimeout(r, 10));
   });
 
@@ -1658,16 +1678,16 @@ describe("Conversation queue policy helpers", () => {
     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));
   });
 
@@ -1714,7 +1734,7 @@ describe("Conversation checkpoint handoff", () => {
     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.
@@ -1732,7 +1752,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(decision).toBe("yield");
 
     // 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 +1767,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));
   });
 
@@ -1775,7 +1795,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(decision).toBe("continue");
 
     // Cleanup
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
   });
 
@@ -1798,9 +1818,21 @@ describe("Conversation checkpoint handoff", () => {
     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)
@@ -1815,7 +1847,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(decision).toBe("yield");
 
     // Complete first run
-    resolveRun(0);
+    await resolveRun(0);
     await p1;
 
     // The yielded drain pulls ALL THREE queued siblings as ONE batched run —
@@ -1829,7 +1861,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);
@@ -1854,7 +1886,11 @@ describe("Conversation checkpoint handoff", () => {
     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.
@@ -1873,7 +1909,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(decision).toBe("yield");
 
     // 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 +1932,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));
   });
 
@@ -1926,33 +1962,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
@@ -1966,7 +1993,7 @@ describe("Conversation checkpoint handoff", () => {
         history: [],
       }),
     ).toBe("yield");
-    resolveRun(0);
+    await resolveRun(0);
     await pA;
 
     // B should be draining
@@ -1983,7 +2010,7 @@ describe("Conversation checkpoint handoff", () => {
         history: [],
       }),
     ).toBe("yield");
-    resolveRun(1);
+    await resolveRun(1);
     await waitForPendingRun(3);
 
     // Handoff from C -> D
@@ -1998,7 +2025,7 @@ describe("Conversation checkpoint handoff", () => {
         history: [],
       }),
     ).toBe("yield");
-    resolveRun(2);
+    await resolveRun(2);
     await waitForPendingRun(4);
 
     // D has no more queued -> checkpoint should return 'continue'
@@ -2013,7 +2040,7 @@ describe("Conversation checkpoint handoff", () => {
       }),
     ).toBe("continue");
 
-    resolveRun(3);
+    await resolveRun(3);
     await new Promise((r) => setTimeout(r, 10));
 
     // Verify FIFO dequeue order
@@ -2038,12 +2065,20 @@ describe("Conversation checkpoint handoff", () => {
     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 +2095,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
@@ -2097,7 +2132,7 @@ describe("Conversation checkpoint handoff", () => {
     expect(pendingRuns[1].onCheckpoint).toBeDefined();
 
     // Complete retry cleanly
-    resolveRun(1);
+    await resolveRun(1);
     await p1;
   });
 });
@@ -2120,7 +2155,7 @@ describe("Conversation usage requestId correlation", () => {
     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
@@ -2153,12 +2188,12 @@ describe("Terminal trace events on rejection/failure", () => {
     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 +2208,7 @@ describe("Terminal trace events on rejection/failure", () => {
     expect(errorTrace).toBeDefined();
 
     // Cleanup
-    resolveRun(1);
+    await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 });
@@ -2215,6 +2250,7 @@ describe("Conversation host attachment directives", () => {
           },
         ],
       };
+      await run.onEvent({ type: "llm_call_started" });
       run.onEvent({
         type: "usage",
         inputTokens: 10,
@@ -2284,6 +2320,7 @@ describe("Conversation host attachment directives", () => {
           },
         ],
       };
+      await run.onEvent({ type: "llm_call_started" });
       run.onEvent({
         type: "usage",
         inputTokens: 10,
@@ -2377,6 +2414,7 @@ describe("Conversation attachment event payloads", () => {
         } as any,
       ],
     });
+    await run.onEvent({ type: "llm_call_started" });
     run.onEvent({
       type: "usage",
       inputTokens: 10,
@@ -2423,7 +2461,7 @@ describe("Conversation attachment event payloads", () => {
     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();
@@ -2452,6 +2490,7 @@ describe("Conversation attachment event payloads", () => {
         } as any,
       ],
     });
+    await run.onEvent({ type: "llm_call_started" });
     run.onEvent({
       type: "usage",
       inputTokens: 10,
@@ -2478,7 +2517,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));
   });
 });
@@ -2510,7 +2549,7 @@ describe("Regression: cancel semantics and error channel split", () => {
     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
@@ -2556,6 +2595,7 @@ describe("Regression: cancel semantics and error channel split", () => {
         } as any,
       ],
     });
+    await run.onEvent({ type: "llm_call_started" });
     run.onEvent({
       type: "usage",
       inputTokens: 10,
@@ -2622,18 +2662,16 @@ describe("Regression: cancel semantics and error channel split", () => {
     );
     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();
 
@@ -2677,10 +2715,14 @@ describe("Regression: cancel semantics and error channel split", () => {
       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 +2743,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;