@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/__tests__/agent-loop.test.ts

@@ -56,10 +56,18 @@ describe("AgentLoop", () => {
   // 1. Basic text response
   test("returns history with assistant message for simple text response", async () => {
     const { provider } = createMockProvider([textResponse("Hi there!")]);
-    const loop = new AgentLoop(provider, "system prompt");
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system prompt",
+      conversationId: "test-conversation",
+    });
 
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // History should contain original user message + assistant response
     expect(history).toHaveLength(2);
@@ -85,12 +93,19 @@ describe("AgentLoop", () => {
       return { content: "file data here", isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Tool executor was called with correct args
     expect(toolCalls).toHaveLength(1);
@@ -134,12 +149,18 @@ describe("AgentLoop", () => {
       overrideProfile = "quality-optimized";
       return { content: "ok", isError: false };
     };
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
 
-    await loop.run([userMessage], collectEvents([]), {
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents([]),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       requestId: "req-1",
       callSite: "mainAgent",
       resolveOverrideProfile: () => overrideProfile,
@@ -163,12 +184,18 @@ describe("AgentLoop", () => {
       maxInputTokens = 10_000;
       return { content: toolOutput, isError: false };
     };
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
 
-    await loop.run([userMessage], collectEvents([]), {
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents([]),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       requestId: "req-1",
       callSite: "mainAgent",
       resolveContextWindow: () => ({
@@ -204,11 +231,18 @@ describe("AgentLoop", () => {
       };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
-    const { history } = await loop.run([userMessage], () => {});
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Provider called 3 times (two tool rounds + final text)
     expect(calls).toHaveLength(3);
@@ -227,8 +261,17 @@ describe("AgentLoop", () => {
     ]);
 
     // No tool executor provided
-    const loop = new AgentLoop(provider, "system", { tools: dummyTools });
-    const { history } = await loop.run([userMessage], () => {});
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+      tools: dummyTools,
+    });
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Should stop after first response (no executor to handle tool use)
     expect(history).toHaveLength(2);
@@ -245,9 +288,17 @@ describe("AgentLoop", () => {
       },
     };
 
-    const loop = new AgentLoop(provider, "system");
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Only the original message remains (no assistant message added on error)
     expect(history).toHaveLength(1);
@@ -266,8 +317,15 @@ describe("AgentLoop", () => {
     controller.abort(); // abort immediately
 
     const { provider } = createMockProvider([textResponse("Should not reach")]);
-    const loop = new AgentLoop(provider, "system");
-    const { history } = await loop.run([userMessage], () => {}, {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       signal: controller.signal,
     });
 
@@ -294,11 +352,17 @@ describe("AgentLoop", () => {
       return { content: "data", isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
-    const { history } = await loop.run([userMessage], () => {}, {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       signal: controller.signal,
     });
 
@@ -340,12 +404,18 @@ describe("AgentLoop", () => {
       return { content: "should never return", isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const start = Date.now();
-    const { history } = await loop.run([userMessage], () => {}, {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       signal: controller.signal,
     });
     const elapsed = Date.now() - start;
@@ -384,10 +454,18 @@ describe("AgentLoop", () => {
   // 7. Events — verify text_delta and other events are emitted
   test("emits text_delta events during streaming", async () => {
     const { provider } = createMockProvider([textResponse("Hello world")]);
-    const loop = new AgentLoop(provider, "system");
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
 
     const events: AgentEvent[] = [];
-    await loop.run([userMessage], collectEvents(events));
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     const textDeltas = events.filter((e) => e.type === "text_delta");
     expect(textDeltas).toHaveLength(1);
@@ -398,10 +476,18 @@ describe("AgentLoop", () => {
 
   test("emits usage events", async () => {
     const { provider } = createMockProvider([textResponse("Hi")]);
-    const loop = new AgentLoop(provider, "system");
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
 
     const events: AgentEvent[] = [];
-    await loop.run([userMessage], collectEvents(events));
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     const usageEvents = events.filter((e) => e.type === "usage");
     expect(usageEvents).toHaveLength(1);
@@ -416,10 +502,18 @@ describe("AgentLoop", () => {
 
   test("emits message_complete events", async () => {
     const { provider } = createMockProvider([textResponse("Done")]);
-    const loop = new AgentLoop(provider, "system");
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
 
     const events: AgentEvent[] = [];
-    await loop.run([userMessage], collectEvents(events));
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     const completeEvents = events.filter((e) => e.type === "message_complete");
     expect(completeEvents).toHaveLength(1);
@@ -436,13 +530,20 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "file data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
 
     const events: AgentEvent[] = [];
-    await loop.run([userMessage], collectEvents(events));
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     const toolUseEvents = events.filter((e) => e.type === "tool_use");
     expect(toolUseEvents).toHaveLength(1);
@@ -480,12 +581,19 @@ describe("AgentLoop", () => {
       content: "ENOENT: file not found",
       isError: true,
     });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
 
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     const secondCallMessages = calls[1].messages;
     const lastMsg = secondCallMessages[secondCallMessages.length - 1];
@@ -515,12 +623,19 @@ describe("AgentLoop", () => {
       return { content: "full output", isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    await loop.run([userMessage], collectEvents(events));
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     const chunkEvents = events.filter((e) => e.type === "tool_output_chunk");
     expect(chunkEvents).toHaveLength(2);
@@ -537,11 +652,18 @@ describe("AgentLoop", () => {
   // 11. System prompt and tools are passed to provider
   test("passes system prompt and tools to provider", async () => {
     const { provider, calls } = createMockProvider([textResponse("Hi")]);
-    const loop = new AgentLoop(provider, "My system prompt", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "My system prompt",
+      conversationId: "test-conversation",
       tools: dummyTools,
     });
 
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     expect(calls[0].systemPrompt).toBe("My system prompt");
     expect(calls[0].tools).toEqual(dummyTools);
@@ -550,9 +672,17 @@ describe("AgentLoop", () => {
   // 12. No tools configured — tools are not passed to provider
   test("does not pass tools to provider when none are configured", async () => {
     const { provider, calls } = createMockProvider([textResponse("Hi")]);
-    const loop = new AgentLoop(provider, "system");
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
 
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     expect(calls[0].tools).toBeUndefined();
   });
@@ -605,12 +735,19 @@ describe("AgentLoop", () => {
       };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // All 3 tools should have been called
     expect(executionLog).toHaveLength(3);
@@ -699,12 +836,18 @@ describe("AgentLoop", () => {
       return { content: "data", isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events), {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       signal: controller.signal,
     });
 
@@ -773,12 +916,19 @@ describe("AgentLoop", () => {
       return { content: `contents of ${path}`, isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    await loop.run([userMessage], collectEvents(events));
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Collect tool_result events in order
     const toolResultEvents = events.filter(
@@ -805,7 +955,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "file data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
@@ -816,7 +969,12 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    await loop.run([userMessage], () => {}, { onCheckpoint });
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+      onCheckpoint,
+    });
 
     expect(checkpoints).toHaveLength(1);
     expect(checkpoints[0]).toMatchObject({
@@ -837,14 +995,20 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
 
     const onCheckpoint = (): CheckpointDecision => "continue";
 
-    const { history } = await loop.run([userMessage], () => {}, {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       onCheckpoint,
     });
 
@@ -864,14 +1028,20 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
 
     const onCheckpoint = (): CheckpointDecision => "budget";
 
-    const { history } = await loop.run([userMessage], () => {}, {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       onCheckpoint,
     });
 
@@ -891,12 +1061,19 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
 
-    const { history } = await loop.run([userMessage], () => {});
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Normal behavior: 2 provider calls, full history
     expect(calls).toHaveLength(2);
@@ -914,7 +1091,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
@@ -925,7 +1105,12 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    await loop.run([userMessage], () => {}, { onCheckpoint });
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+      onCheckpoint,
+    });
 
     expect(checkpoints).toHaveLength(3);
     expect(checkpoints[0].turnIndex).toBe(0);
@@ -938,7 +1123,12 @@ describe("AgentLoop", () => {
     const { provider } = createMockProvider([
       textResponse("Just a text response"),
     ]);
-    const loop = new AgentLoop(provider, "system", { tools: dummyTools });
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+      tools: dummyTools,
+    });
 
     const checkpoints: CheckpointInfo[] = [];
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
@@ -946,7 +1136,10 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    const { history } = await loop.run([userMessage], () => {}, {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       onCheckpoint,
     });
 
@@ -991,7 +1184,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
@@ -1002,7 +1198,12 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    await loop.run([userMessage], () => {}, { onCheckpoint });
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+      onCheckpoint,
+    });
 
     expect(checkpoints).toHaveLength(1);
     expect(checkpoints[0].toolCount).toBe(3);
@@ -1022,7 +1223,10 @@ describe("AgentLoop", () => {
 
     const { provider, calls } = createMockProvider(responses);
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
@@ -1035,7 +1239,10 @@ describe("AgentLoop", () => {
     };
 
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events), {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       onCheckpoint,
     });
 
@@ -1091,7 +1298,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
@@ -1101,7 +1311,10 @@ describe("AgentLoop", () => {
       return checkpoint.turnIndex === 1 ? "budget" : "continue";
     };
 
-    const { history } = await loop.run([userMessage], () => {}, {
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
       onCheckpoint,
     });
 
@@ -1118,9 +1331,18 @@ describe("AgentLoop", () => {
   // 25. Without resolveTools, static tools are used
   test("without resolveTools, static tools are passed to provider", async () => {
     const { provider, calls } = createMockProvider([textResponse("Hi")]);
-    const loop = new AgentLoop(provider, "system", { tools: dummyTools });
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+      tools: dummyTools,
+    });
 
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     expect(calls[0].tools).toEqual(dummyTools);
   });
@@ -1151,11 +1373,18 @@ describe("AgentLoop", () => {
       return resolvedTools;
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       toolExecutor: toolExecutor,
       resolveTools: resolveTools,
     });
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // resolveTools should be called once per provider turn (2 turns total)
     expect(resolverCalls).toHaveLength(2);
@@ -1183,11 +1412,18 @@ describe("AgentLoop", () => {
     const resolveTools = (): ToolDefinition[] => dynamicTools;
 
     // Pass different static tools to verify they are overridden
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       resolveTools: resolveTools,
     });
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Provider should receive the dynamically resolved tools, not the static ones
     expect(calls[0].tools).toEqual(dynamicTools);
@@ -1240,11 +1476,18 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "ok", isError: false });
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       toolExecutor: toolExecutor,
       resolveTools: resolveTools,
     });
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Provider should have been called 3 times
     expect(calls).toHaveLength(3);
@@ -1263,11 +1506,18 @@ describe("AgentLoop", () => {
       textResponse("No tools available"),
     ]);
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       resolveTools: resolveTools,
     });
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Empty array should result in undefined tools (same as no-tools behavior)
     expect(calls[0].tools).toBeUndefined();
@@ -1291,13 +1541,20 @@ describe("AgentLoop", () => {
       return { content: largeContent, isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       config: { maxInputTokens: 180_000 },
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // The tool result user message is at index 2 in history
     const toolResultMsg = history[2];
@@ -1340,13 +1597,20 @@ describe("AgentLoop", () => {
       return { content: smallContent, isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       config: { maxInputTokens: 180_000 },
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // The tool result user message is at index 2 in history
     const toolResultMsg = history[2];
@@ -1398,12 +1662,19 @@ describe("AgentLoop", () => {
       ],
     });
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // The final assistant message in HISTORY should retain placeholders
     // (so the model never sees real values on subsequent turns)
@@ -1464,12 +1735,19 @@ describe("AgentLoop", () => {
       ],
     });
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    await loop.run([userMessage], collectEvents(events));
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Collect all text_delta events from the final turn (after tool result)
     const textDeltas = events.filter(
@@ -1496,12 +1774,19 @@ describe("AgentLoop", () => {
       // No sensitiveBindings
     });
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     const lastAssistant = history[history.length - 1];
     const textBlock = lastAssistant.content.find(
@@ -1540,11 +1825,18 @@ describe("AgentLoop", () => {
       return { content: "file contents", isError: false };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Provider should have been called 3 times (error -> retry -> final text)
     expect(calls).toHaveLength(3);
@@ -1598,11 +1890,18 @@ describe("AgentLoop", () => {
       return { content: "service unavailable", isError: true };
     };
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
-    await loop.run([userMessage], () => {});
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     expect(calls).toHaveLength(5);
 
@@ -1644,12 +1943,19 @@ describe("AgentLoop", () => {
       isError: false,
     });
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Provider should be called 3 times: initial, empty response, retry
     expect(calls).toHaveLength(3);
@@ -1719,12 +2025,19 @@ describe("AgentLoop", () => {
       isError: false,
     });
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Provider called exactly 2 times: initial [text+tool_use], then empty.
     // No third (retry) call because the prior turn had visible text.
@@ -1778,12 +2091,19 @@ describe("AgentLoop", () => {
       isError: false,
     });
 
-    const loop = new AgentLoop(provider, "system", {
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
       tools: dummyTools,
       toolExecutor: toolExecutor,
     });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Provider called 3 times: initial, empty, retry (also empty)
     expect(calls).toHaveLength(3);
@@ -1812,9 +2132,17 @@ describe("AgentLoop", () => {
 
     const { provider, calls } = createMockProvider([emptyResponse]);
 
-    const loop = new AgentLoop(provider, "system");
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
     const events: AgentEvent[] = [];
-    const { history } = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     // Should NOT retry — this is the first turn with no tool use history
     expect(calls).toHaveLength(1);
@@ -1827,8 +2155,17 @@ describe("AgentLoop", () => {
   test("threads callSite from AgentLoop.run() into per-call provider config", async () => {
     const { provider, calls } = createMockProvider([textResponse("ok")]);
 
-    const loop = new AgentLoop(provider, "system");
-    await loop.run([userMessage], () => {}, { callSite: "heartbeatAgent" });
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+      callSite: "heartbeatAgent",
+    });
 
     expect(calls).toHaveLength(1);
     expect(calls[0].options?.config?.callSite).toBe("heartbeatAgent");
@@ -1837,8 +2174,16 @@ describe("AgentLoop", () => {
   test("omits callSite from provider config when not supplied", async () => {
     const { provider, calls } = createMockProvider([textResponse("ok")]);
 
-    const loop = new AgentLoop(provider, "system");
-    await loop.run([userMessage], () => {});
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
+    await loop.run({
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
 
     expect(calls).toHaveLength(1);
     expect(calls[0].options?.config?.callSite).toBeUndefined();