@vellumai/assistant 0.12.2-dev.202609181515.7e76c92 → 0.12.2-dev.202609181615.645c0a5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609181515.7e76c92",
+  "version": "0.12.2-dev.202609181615.645c0a5",
   "license": "MIT",
   "type": "module",
   "exports": {

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

@@ -6,7 +6,7 @@
  */
 import { beforeEach, describe, expect, test } from "bun:test";
 
-import type { AgentEvent } from "../agent/loop.js";
+import type { AgentEvent, PreparedModelCall } from "../agent/loop.js";
 import { AgentLoop } from "../agent/loop.js";
 import type {
   PostModelCallContext,
@@ -18,12 +18,14 @@ import type {
   ContentBlock,
   Message,
   ProviderResponse,
+  ToolDefinition,
 } from "../providers/types.js";
 import {
   createMockProvider,
   textResponse,
   toolUseResponse,
 } from "./helpers/mock-provider.js";
+import { setConfig } from "./helpers/set-config.js";
 
 const userMessage: Message = {
   role: "user",
@@ -91,6 +93,7 @@ function registerOutputHookPlugin(hooks: {
 describe("agent loop output hooks", () => {
   beforeEach(() => {
     resetPluginRegistryAndRegisterDefaults();
+    setConfig("llm", {});
   });
 
   test("post-model-call transforms the persisted message content", async () => {
@@ -403,6 +406,152 @@ describe("agent loop output hooks", () => {
     expect(calls[0].options?.config?.overrideProfile).toBe("fast-profile");
   });
 
+  test("prepared model call carries the post-hook route and wire tool surface", async () => {
+    registerOutputHookPlugin({
+      preModelCall: (ctx) => {
+        ctx.systemPrompt = `${ctx.systemPrompt ?? ""} [EDITED]`;
+        ctx.modelProfile = "fast-profile";
+      },
+    });
+    const tool: ToolDefinition = {
+      name: "dynamic_tool",
+      description: "Dynamic",
+      input_schema: { type: "object" },
+    };
+    const { provider, calls } = createMockProvider([textResponse("hi")]);
+    Object.assign(provider, { supportsNativeWebSearch: true });
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "base prompt",
+      conversationId: "test-conversation",
+      config: { enableNativeWebSearch: true },
+      resolveTools: () => [tool],
+    });
+    let prepared: PreparedModelCall | undefined;
+
+    await loop.run({
+      requestId: "test-request",
+      messages: [userMessage],
+      onEvent: collect([]),
+      callSite: "mainAgent",
+      overrideProfile: "conversation-profile",
+      forceOverrideProfile: true,
+      onModelCallPrepared: (value) => {
+        prepared = value;
+      },
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    expect(prepared).toMatchObject({
+      callSite: "mainAgent",
+      overrideProfile: "fast-profile",
+      forceOverrideProfile: true,
+      systemPrompt: "base prompt [EDITED]",
+    });
+    expect(prepared?.tools.map((item) => item.name)).toEqual([
+      "dynamic_tool",
+      "web_search",
+    ]);
+    expect(calls[0].tools).toEqual(prepared?.tools);
+  });
+
+  test("prepared model call carries the finalized cache policy", async () => {
+    setConfig("llm", {
+      callSites: { mainAgent: { disableCache: true } },
+    });
+    const { provider } = createMockProvider([textResponse("hi")]);
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "base prompt",
+      conversationId: "test-conversation",
+    });
+    let prepared: PreparedModelCall | undefined;
+
+    await loop.run({
+      requestId: "test-request",
+      messages: [userMessage],
+      onEvent: collect([]),
+      callSite: "mainAgent",
+      onModelCallPrepared: (value) => {
+        prepared = value;
+      },
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    expect(prepared?.disableCache).toBe(true);
+  });
+
+  test("prepared model call preserves explicit system-prompt removal", async () => {
+    registerOutputHookPlugin({
+      preModelCall: (ctx) => {
+        ctx.systemPrompt = null;
+      },
+    });
+    const { provider, calls } = createMockProvider([textResponse("hi")]);
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "base prompt",
+      conversationId: "test-conversation",
+    });
+    let prepared: PreparedModelCall | undefined;
+
+    await loop.run({
+      requestId: "test-request",
+      messages: [userMessage],
+      onEvent: collect([]),
+      callSite: "mainAgent",
+      onModelCallPrepared: (value) => {
+        prepared = value;
+      },
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    expect(prepared?.systemPrompt).toBeNull();
+    expect(calls[0].options?.systemPrompt).toBeUndefined();
+  });
+
+  test("inference routing preserves the semantic call site for hooks and events", async () => {
+    const preModelCallSites: Array<string | null> = [];
+    const postModelCallSites: Array<string | null> = [];
+    registerOutputHookPlugin({
+      preModelCall: (ctx) => {
+        preModelCallSites.push(ctx.callSite);
+      },
+      postModelCall: (ctx) => {
+        postModelCallSites.push(ctx.callSite);
+      },
+    });
+    const { provider, calls } = createMockProvider([textResponse("hi")]);
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
+    const events: AgentEvent[] = [];
+    let prepared: PreparedModelCall | undefined;
+
+    await loop.run({
+      requestId: "test-request",
+      messages: [userMessage],
+      onEvent: collect(events),
+      callSite: "callAgent",
+      inferenceCallSite: "mainAgent",
+      onModelCallPrepared: (value) => {
+        prepared = value;
+      },
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    expect(calls[0].options?.config?.callSite).toBe("mainAgent");
+    expect(prepared?.callSite).toBe("mainAgent");
+    expect(preModelCallSites).toEqual(["callAgent"]);
+    expect(postModelCallSites).toEqual(["callAgent"]);
+    expect(events).toContainEqual({
+      type: "llm_call_started",
+      callSite: "callAgent",
+    });
+  });
+
   test("pre-model-call seeds modelProfile from the resolved override and clearing it drops the override", async () => {
     // GIVEN a hook that observes the seeded override and then clears it
     let seeded: string | null | undefined;

package/src/__tests__/conversation-agent-loop-disk-pressure.test.ts

@@ -169,6 +169,7 @@ describe("runAgentLoopImpl disk pressure gate", () => {
     const events: AssistantEvent[] = [];
     const activityStates: unknown[][] = [];
     const drainQueue = mock(async (_reason: unknown) => {});
+    const onFirstModelCallPrepared = mock(() => {});
     const ctx = makeCtx({
       emitActivityState: (...args: unknown[]) => {
         activityStates.push(args);
@@ -176,8 +177,12 @@ describe("runAgentLoopImpl disk pressure gate", () => {
       drainQueue,
     });
 
-    await runAgentLoopImpl(ctx, "background task", "msg-1", (event) =>
-      events.push(event),
+    await runAgentLoopImpl(
+      ctx,
+      "background task",
+      "msg-1",
+      (event) => events.push(event),
+      { onFirstModelCallPrepared },
     );
 
     expect(events.find((event) => event.type === "error")).toMatchObject({
@@ -195,5 +200,6 @@ describe("runAgentLoopImpl disk pressure gate", () => {
     expect(ctx.abortController).toBeNull();
     expect(ctx.currentRequestId).toBeUndefined();
     expect(drainQueue).toHaveBeenCalledWith("loop_complete");
+    expect(onFirstModelCallPrepared).not.toHaveBeenCalled();
   });
 });

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

@@ -24,7 +24,12 @@ import { getConversationDirName } from "../persistence/conversation-directories.
 import type { UserPromptSubmitContext } from "../plugin-api/types.js";
 import { resetPluginRegistryAndRegisterDefaults } from "../plugins/defaults/index.js";
 import { registerPlugin } from "../plugins/registry.js";
-import type { Message, Provider, ToolDefinition } from "../providers/types.js";
+import type {
+  Message,
+  Provider,
+  SendMessageOptions,
+  ToolDefinition,
+} from "../providers/types.js";
 import { ContextOverflowError } from "../providers/types.js";
 import {
   resolveUsageAttribution,
@@ -715,7 +720,7 @@ mock.module("../persistence/llm-request-log-store.js", () => ({
 // ── Imports (after mocks) ────────────────────────────────────────────
 
 import { AgentLoop } from "../agent/loop.js";
-import type { Conversation } from "../daemon/conversation.js";
+import { Conversation } from "../daemon/conversation.js";
 import {
   applyCompactionResult,
   runAgentLoopImpl,
@@ -1100,6 +1105,82 @@ beforeEach(() => {
   resetPluginRegistryAndRegisterDefaults();
 });
 
+describe("prompt cache warming", () => {
+  test("attributes provider usage to the conversation", async () => {
+    const sendMessage = mock(
+      async (_messages: Message[], _options?: SendMessageOptions) =>
+        textResponse("unused"),
+    );
+    const conversation = Object.assign(
+      Object.create(Conversation.prototype) as object,
+      {
+        conversationId: "conv-cache-warm-test",
+        messages: [],
+        provider: { name: "mock-provider", sendMessage },
+        agentLoop: { getResolvedTools: () => [] },
+        buildCurrentSystemPrompt: () => "system prompt",
+      },
+    ) as unknown as Conversation;
+
+    await conversation.warmPromptCache();
+
+    expect(sendMessage).toHaveBeenCalledTimes(1);
+    expect(sendMessage.mock.calls[0]?.[1]?.config).toMatchObject({
+      callSite: "mainAgent",
+      conversationId: "conv-cache-warm-test",
+      max_tokens: 16,
+      selectionSeed: "conv-cache-warm-test",
+    });
+    expect(
+      sendMessage.mock.calls[0]?.[1]?.config?.usageTracking,
+    ).toBeUndefined();
+  });
+
+  test("stays non-rejecting when request preparation fails", async () => {
+    const sendMessage = mock(async () => textResponse("unused"));
+    const conversation = Object.assign(
+      Object.create(Conversation.prototype) as object,
+      {
+        conversationId: "conv-cache-warm-test",
+        messages: [],
+        provider: { name: "mock-provider", sendMessage },
+        agentLoop: {
+          getResolvedTools: () => {
+            throw new Error("tool resolution failed");
+          },
+        },
+        buildCurrentSystemPrompt: () => "system prompt",
+      },
+    ) as unknown as Conversation;
+
+    await expect(conversation.warmPromptCache()).resolves.toBeUndefined();
+    expect(sendMessage).not.toHaveBeenCalled();
+  });
+
+  test("does not rebuild a system prompt explicitly removed by a hook", async () => {
+    const sendMessage = mock(
+      async (_messages: Message[], _options?: SendMessageOptions) =>
+        textResponse("unused"),
+    );
+    const buildCurrentSystemPrompt = mock(() => "rebuilt prompt");
+    const conversation = Object.assign(
+      Object.create(Conversation.prototype) as object,
+      {
+        conversationId: "conv-cache-warm-test",
+        messages: [],
+        provider: { name: "mock-provider", sendMessage },
+        agentLoop: { getResolvedTools: () => [] },
+        buildCurrentSystemPrompt,
+      },
+    ) as unknown as Conversation;
+
+    await conversation.warmPromptCache({ systemPrompt: null, tools: [] });
+
+    expect(buildCurrentSystemPrompt).not.toHaveBeenCalled();
+    expect(sendMessage.mock.calls[0]?.[1]?.systemPrompt).toBeUndefined();
+  });
+});
+
 describe("session-agent-loop", () => {
   describe("user-prompt-submit hook failures", () => {
     test("passes the effective profile to hooks even when it was already announced", async () => {
@@ -2165,6 +2246,43 @@ describe("session-agent-loop", () => {
       const call = recordRequestLogMock.mock.calls[0] as unknown as unknown[];
       expect(call[5]).toBe("callAgent");
     });
+
+    test("reports only the first finalized model call", async () => {
+      const tool: ToolDefinition = {
+        name: "echo",
+        description: "Echo",
+        input_schema: { type: "object" },
+      };
+      const onFirstModelCallPrepared = mock(() => {});
+      const ctx = makeCtx({
+        providerResponses: [
+          toolUseResponse("tool-1", "echo", {}),
+          textResponse("done"),
+        ],
+        loopTools: [tool],
+        toolExecutor: async () => ({ content: "ok", isError: false }),
+      });
+      const turnSignal = ctx.abortController?.signal;
+
+      await runAgentLoopImpl(ctx, "hello", "msg-1", () => {}, {
+        callSite: "callAgent",
+        inferenceCallSite: "mainAgent",
+        overrideProfile: "quality-optimized",
+        forceOverrideProfile: true,
+        onFirstModelCallPrepared,
+      });
+
+      expect(onFirstModelCallPrepared).toHaveBeenCalledTimes(1);
+      expect(onFirstModelCallPrepared).toHaveBeenCalledWith({
+        callSite: "mainAgent",
+        overrideProfile: "quality-optimized",
+        forceOverrideProfile: true,
+        signal: turnSignal,
+        systemPrompt: "system prompt",
+        tools: [tool],
+      });
+      expect(ctx.currentCallSite).toBe("callAgent");
+    });
   });
 
   describe("usage accounting", () => {

package/src/agent/loop.ts

@@ -1,4 +1,6 @@
 import type { AnsweredQuestion } from "../api/events/question-answered.js";
+import { resolveCallSiteConfig } from "../config/llm-resolver.js";
+import { getConfig } from "../config/loader.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { SEND_USER_MESSAGE_TOOL_NAME } from "../config/send-user-message-constants.js";
 import { recordEstimate } from "../context/estimator-calibration.js";
@@ -664,6 +666,18 @@ type AgentLoopContextWindowResolver = () => {
   overflowRecovery: { enabled: boolean; safetyMarginRatio: number };
 };
 
+/** Final request surface after the pre-model hook has settled. */
+export interface PreparedModelCall {
+  callSite?: LLMCallSite;
+  overrideProfile?: string;
+  forceOverrideProfile: boolean;
+  /** Present when the finalized route opts out of prompt caching. */
+  disableCache?: true;
+  signal?: AbortSignal;
+  systemPrompt: string | null;
+  tools: ToolDefinition[];
+}
+
 interface AgentLoopRunOptionsBase {
   /** Input history the run starts from; the loop appends its output onto a copy. */
   messages: Message[];
@@ -691,7 +705,10 @@ interface AgentLoopRunOptionsBase {
   onCheckpoint?: (
     checkpoint: CheckpointInfo,
   ) => CheckpointDecision | Promise<CheckpointDecision>;
+  /** Semantic call site exposed to hooks, events, and loop behavior. */
   callSite?: LLMCallSite;
+  /** Provider-resolution call site when it differs from turn semantics. */
+  inferenceCallSite?: LLMCallSite;
   /**
    * Route this run's user-facing text through the `send_user_message` tool
    * instead of streamed assistant text. The daemon sets it for main-agent runs
@@ -741,6 +758,8 @@ interface AgentLoopRunOptionsBase {
    */
   forceOverrideProfile?: boolean;
   resolveOverrideProfile?: () => string | undefined;
+  /** Observe a finalized model request without delaying provider dispatch. */
+  onModelCallPrepared?: (prepared: PreparedModelCall) => void;
   /**
    * When `true`, the loop owns turn-start and mid-loop compaction. The pre-call
    * budget gate runs before the very first provider call — subsuming the
@@ -1430,18 +1449,21 @@ export class AgentLoop {
       requestId,
       onCheckpoint,
       callSite,
+      inferenceCallSite,
       suppressAssistantText = false,
       supportsDynamicUi = true,
       trust,
       overrideProfile,
       forceOverrideProfile = false,
       resolveOverrideProfile,
+      onModelCallPrepared,
       compactInPlace = false,
       isNonInteractive = false,
       model: runModel,
       latencyTracker,
       injectionLedgerResets,
     } = options;
+    const providerCallSite = inferenceCallSite ?? callSite;
     // Snapshot the system prompt once per run. The instance field is mutable
     // (the conversation may update it between turns), but a single run must
     // use one consistent prompt — an aborted run left detached after the
@@ -1887,7 +1909,7 @@ export class AgentLoop {
         // unexecutable client tool. The advisor consult's `advisorProfile` can
         // route `subagentSpawn` to a provider/model whose native-search support
         // differs from the construction-time default, so the gate resolves the
-        // routed target (callSite + overrideProfile) via
+        // routed target (providerCallSite + overrideProfile) via
         // `supportsNativeWebSearchFor` rather than the static
         // `this.provider.supportsNativeWebSearch` snapshot; providers without
         // the routing-aware probe fall back to the static flag. This is a SERVER
@@ -1899,7 +1921,7 @@ export class AgentLoop {
           .supportsNativeWebSearchFor
           ? this.provider.supportsNativeWebSearchFor(
               buildNativeWebSearchProbeOptions(
-                callSite,
+                providerCallSite,
                 resolveEffectiveOverrideProfile(),
                 forceOverrideProfile,
                 this.conversationId,
@@ -1918,11 +1940,11 @@ export class AgentLoop {
         //   1. Per-run explicit (`runModel`)
         //   2. Call-site resolved values (filled by
         //      `RetryProvider.normalizeSendMessageOptions` from
-        //      `resolveCallSiteConfig(callSite, llm)`)
+        //      `resolveCallSiteConfig(providerCallSite, llm)`)
         //   3. Conversation defaults (`this.config.*`, from the resolved
         //      default call-site config)
         //
-        // When `callSite` is present we deliberately leave
+        // When `providerCallSite` is present we deliberately leave
         // `max_tokens`/`thinking`/`effort`/`speed` *unset* in `providerConfig`
         // so the normalizer can fill them from the call-site resolution. The
         // normalizer only writes these fields when they're undefined; if we
@@ -1930,10 +1952,10 @@ export class AgentLoop {
         // for these knobs is silently ignored.
         //
         // `toolChoice` and `cacheTtl` are not part of the call-site schema, so
-        // they always come from `this.config` regardless of `callSite`.
+        // they always come from `this.config` regardless of `providerCallSite`.
         const providerConfig: Record<string, unknown> = {};
 
-        if (!callSite) {
+        if (!providerCallSite) {
           providerConfig.max_tokens = this.config.maxTokens;
         }
 
@@ -1941,7 +1963,7 @@ export class AgentLoop {
           providerConfig.model = runModel;
         }
 
-        if (!callSite) {
+        if (!providerCallSite) {
           const thinking = normalizeThinkingConfigForWire(this.config.thinking);
           if (thinking !== undefined) {
             providerConfig.thinking = thinking;
@@ -1980,9 +2002,9 @@ export class AgentLoop {
         // defaults when absent).
         // User-initiated conversation turns default to `mainAgent` in the
         // agent loop's caller; other invocation contexts (heartbeat, filing,
-        // analyze, etc.) pass their own `callSite`.
-        if (callSite) {
-          providerConfig.callSite = callSite;
+        // analyze, etc.) pass their own provider-resolution site.
+        if (providerCallSite) {
+          providerConfig.callSite = providerCallSite;
           providerConfig.usageTracking = "manual";
           // Per-conversation seed for deterministic `mix`-profile expansion.
           // Sourced from the loop's own conversation id so every LLM call in a
@@ -2010,7 +2032,7 @@ export class AgentLoop {
         // `activeProfile` and any call-site named profile. Threading it on
         // every send (rather than once at construction) keeps subagents that
         // share an `AgentLoop` instance but ought to inherit a different
-        // profile correct — and matches how `callSite` is plumbed.
+        // profile correct, matching how the provider call site is plumbed.
         const effectiveOverrideProfile = resolveEffectiveOverrideProfile();
         if (effectiveOverrideProfile) {
           providerConfig.overrideProfile = effectiveOverrideProfile;
@@ -2234,6 +2256,49 @@ export class AgentLoop {
           );
         }
 
+        if (onModelCallPrepared && !signal?.aborted) {
+          const preparedOverrideProfile =
+            typeof providerConfig.overrideProfile === "string" &&
+            providerConfig.overrideProfile.length > 0
+              ? providerConfig.overrideProfile
+              : undefined;
+          try {
+            const preparedForceOverrideProfile =
+              providerConfig.forceOverrideProfile === true;
+            const disableCache =
+              providerCallSite !== undefined &&
+              resolveCallSiteConfig(providerCallSite, getConfig().llm, {
+                ...(preparedOverrideProfile !== undefined
+                  ? { overrideProfile: preparedOverrideProfile }
+                  : {}),
+                ...(preparedForceOverrideProfile
+                  ? { forceOverrideProfile: true }
+                  : {}),
+                ...(this.conversationId !== undefined
+                  ? { selectionSeed: this.conversationId }
+                  : {}),
+              }).disableCache === true;
+            onModelCallPrepared({
+              ...(providerCallSite !== undefined
+                ? { callSite: providerCallSite }
+                : {}),
+              ...(preparedOverrideProfile !== undefined
+                ? { overrideProfile: preparedOverrideProfile }
+                : {}),
+              forceOverrideProfile: preparedForceOverrideProfile,
+              ...(disableCache ? { disableCache: true as const } : {}),
+              ...(signal !== undefined ? { signal } : {}),
+              systemPrompt: providerOptions.systemPrompt ?? null,
+              tools: currentTools,
+            });
+          } catch (preparedError) {
+            rlog.warn(
+              { err: preparedError },
+              "Prepared model-call observer failed; continuing with provider dispatch",
+            );
+          }
+        }
+
         // Announce the LLM-call boundary so downstream handlers (the
         // daemon's persistence pipeline) can reserve an empty assistant row
         // and stamp the resulting `messageId` onto every streaming event the