@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/runtime/migrations/vbundle-streaming-importer.ts

@@ -698,7 +698,10 @@ export async function streamCommitImport(
         // Retired-feature paths (see `policy.RETIRED_ARCHIVE_PATHS`) are
         // expected in legacy bundles and skip silently so the import report
         // matches preflight; anything else unresolvable earns a warning.
-        if (!policy.isRetiredArchivePath(archivePath)) {
+        if (
+          !policy.isRetiredArchivePath(archivePath) &&
+          !policy.isGatewayArchivePath(archivePath)
+        ) {
           warnings.push(
             `Skipped "${archivePath}": no known disk target for this archive path`,
           );

package/src/runtime/migrations/vbundle-validator.ts

@@ -53,6 +53,7 @@ const ExportOptions = z.object({
   include_logs: z.boolean(),
   include_browser_state: z.boolean(),
   include_memory_vectors: z.boolean(),
+  include_gateway: z.boolean().optional(),
 });
 
 export const ManifestSchema = z

package/src/runtime/pending-interactions-mode-session.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { Conversation } from "../daemon/conversation.js";
+import {
+  clearConversations,
+  setConversation,
+} from "../daemon/conversation-registry.js";
+import * as pendingInteractions from "./pending-interactions.js";
+
+describe("pending interaction mode-session waits", () => {
+  const invalidateStructuralWait = mock(() => true);
+
+  beforeEach(() => {
+    pendingInteractions.clear();
+    clearConversations();
+    invalidateStructuralWait.mockClear();
+    setConversation("conv-1", {
+      modeSessions: { invalidateStructuralWait },
+    } as unknown as Conversation);
+  });
+
+  afterEach(() => {
+    pendingInteractions.clear();
+    clearConversations();
+  });
+
+  test.each([
+    ["question", "question"],
+    ["confirmation", "confirmation"],
+    ["acp_confirmation", "confirmation"],
+    ["secret", "secret"],
+  ] as const)(
+    "resolving %s invalidates its exact structural wait",
+    (interactionKind, structuralKind) => {
+      pendingInteractions.register("request-1", {
+        conversationId: "conv-1",
+        kind: interactionKind,
+      });
+
+      expect(pendingInteractions.resolve("request-1", "answered")).toEqual(
+        expect.objectContaining({ kind: interactionKind }),
+      );
+      expect(invalidateStructuralWait).toHaveBeenCalledTimes(1);
+      expect(invalidateStructuralWait).toHaveBeenCalledWith({
+        kind: structuralKind,
+        responseId: "request-1",
+      });
+    },
+  );
+
+  test("does not invalidate for a missing or non-structural interaction", () => {
+    expect(pendingInteractions.resolve("missing", "answered")).toBeUndefined();
+    pendingInteractions.register("host-request", {
+      conversationId: "conv-1",
+      kind: "host_cu",
+    });
+
+    pendingInteractions.resolve("host-request", "answered");
+
+    expect(invalidateStructuralWait).not.toHaveBeenCalled();
+  });
+});

package/src/runtime/pending-interactions.ts

@@ -20,6 +20,7 @@
 
 import type { InteractionResolutionState } from "../api/events/interaction-resolved.js";
 import type { QuestionEntry } from "../api/events/question-request.js";
+import { findConversationOrSubagent } from "../daemon/conversation-registry.js";
 import type { UserDecision } from "../permissions/types.js";
 import { getLogger } from "../util/logger.js";
 import { broadcastMessage } from "./assistant-event-hub.js";
@@ -135,6 +136,33 @@ export interface PendingInteraction {
 
 const pending = new Map<string, PendingInteraction>();
 
+function invalidateModeSessionStructuralWait(
+  requestId: string,
+  interaction: PendingInteraction,
+): void {
+  const kind =
+    interaction.kind === "acp_confirmation"
+      ? "confirmation"
+      : interaction.kind === "confirmation" ||
+          interaction.kind === "question" ||
+          interaction.kind === "secret"
+        ? interaction.kind
+        : undefined;
+  if (!kind) {
+    return;
+  }
+  try {
+    findConversationOrSubagent(
+      interaction.conversationId,
+    )?.modeSessions.invalidateStructuralWait({ kind, responseId: requestId });
+  } catch (err) {
+    log.warn(
+      { err, requestId, conversationId: interaction.conversationId, kind },
+      "Could not invalidate mode session structural wait",
+    );
+  }
+}
+
 export function register(
   requestId: string,
   interaction: PendingInteraction,
@@ -162,6 +190,7 @@ export function resolve(
     return undefined;
   }
   pending.delete(requestId);
+  invalidateModeSessionStructuralWait(requestId, interaction);
   if (interaction.timer != null) {
     clearTimeout(interaction.timer);
   }

package/src/runtime/routes/__tests__/client-history-routes.test.ts

@@ -0,0 +1,104 @@
+import { afterAll, describe, expect, mock, test } from "bun:test";
+
+const historyResult = {
+  events: [
+    {
+      id: "evt-1",
+      clientId: "client-123",
+      interfaceId: "chrome-extension",
+      connectionId: "conn-1",
+      reason: "sse_open" as const,
+      occurredAt: Date.parse("2026-09-16T12:00:00.000Z"),
+      actorPrincipalId: "user-123",
+      clientVersion: "0.12.1",
+      sseWatchdog: true,
+      machineName: null,
+    },
+  ],
+  sessions: [
+    {
+      clientId: "client-123",
+      interfaceId: "chrome-extension",
+      startedAt: Date.parse("2026-09-16T12:00:00.000Z"),
+      endedAt: null,
+      durationMs: 60_000,
+      flapCount: 1,
+      openReason: "sse_open" as const,
+      closeReason: null,
+      clientVersion: "0.12.1",
+      sseWatchdog: true,
+      machineName: null,
+      connectionIds: ["conn-1", "conn-2"],
+    },
+  ],
+};
+
+const listHistory = mock((params: Record<string, unknown>) => {
+  if (params.actorPrincipalId === "user-123") {
+    return historyResult;
+  }
+  return { events: [], sessions: [] };
+});
+
+mock.module("../../../config/env.js", () => ({
+  isHttpAuthDisabled: () => false,
+  hasUngatedHttpAuthDisabled: () => false,
+}));
+
+mock.module("../../../persistence/client-connection-events-store.js", () => ({
+  listClientConnectionHistory: listHistory,
+}));
+
+import { ROUTES } from "../client-routes.js";
+import { BadRequestError } from "../errors.js";
+import type { RouteDefinition } from "../types.js";
+
+afterAll(() => {
+  mock.restore();
+});
+
+function findHandler(operationId: string): RouteDefinition["handler"] {
+  const route = ROUTES.find((r) => r.operationId === operationId);
+  if (!route) {
+    throw new Error(`Route ${operationId} not found`);
+  }
+  return route.handler;
+}
+
+describe("list_client_history", () => {
+  test("returns ISO timestamps for the calling actor", () => {
+    const handler = findHandler("list_client_history");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-123" },
+      queryParams: { clientId: "client-123" },
+    }) as {
+      sessions: Array<{ startedAt: string; endedAt: string | null }>;
+      events: Array<{ occurredAt: string }>;
+    };
+
+    expect(listHistory).toHaveBeenCalled();
+    expect(result.sessions[0].startedAt).toBe("2026-09-16T12:00:00.000Z");
+    expect(result.sessions[0].endedAt).toBeNull();
+    expect(result.events[0].occurredAt).toBe("2026-09-16T12:00:00.000Z");
+  });
+
+  test("hides other actors' history", () => {
+    const handler = findHandler("list_client_history");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-other" },
+    }) as { sessions: unknown[]; events: unknown[] };
+
+    expect(result.sessions).toEqual([]);
+    expect(result.events).toEqual([]);
+  });
+
+  test("rejects an invalid since value", () => {
+    const handler = findHandler("list_client_history");
+    expect(() =>
+      handler({
+        headers: { "x-vellum-actor-principal-id": "user-123" },
+        queryParams: { since: "not-a-date" },
+      }),
+    ).toThrow(BadRequestError);
+  });
+});

package/src/runtime/routes/__tests__/image-generation-routes.test.ts

@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { setConfig } from "../../../__tests__/helpers/set-config.js";
+import { BadRequestError } from "../errors.js";
+
+let lastGenerateProvider: unknown = null;
+let lastGenerateRequest: Record<string, unknown> | null = null;
+
+mock.module("../../../media/image-service.js", () => ({
+  generateImage: async (
+    provider: unknown,
+    _credentials: unknown,
+    request: Record<string, unknown>,
+  ) => {
+    lastGenerateProvider = provider;
+    lastGenerateRequest = request;
+    return {
+      images: [{ mimeType: "image/png", dataBase64: "generated" }],
+      resolvedModel: request.model,
+    };
+  },
+  mapImageGenError: () => "mapped",
+}));
+
+mock.module("../../../media/image-credentials.js", () => ({
+  resolveImageGenRouting: (
+    svc: { provider: string },
+    _model?: unknown,
+  ) => ({
+    backendProvider: svc.provider === "openrouter" ? "openrouter" : "gemini",
+    managed: false,
+  }),
+  resolveImageGenCredentials: async () => ({
+    credentials: { type: "direct", apiKey: "test-key" },
+  }),
+}));
+
+const { ROUTES } = await import("../image-generation-routes.js");
+const route = ROUTES[0];
+
+beforeEach(() => {
+  lastGenerateProvider = null;
+  lastGenerateRequest = null;
+  setConfig("services", {
+    "image-generation": {
+      provider: "openrouter",
+      model: "google/gemini-3.1-flash-image-preview",
+    },
+  });
+});
+
+describe("image-generation generate route", () => {
+  test("mentions OpenRouter in the route description", () => {
+    expect(route.description).toContain("OpenRouter");
+  });
+
+  test("accepts an arbitrary OpenRouter slug", async () => {
+    const result = await route.handler({
+      body: {
+        prompt: "a nebula",
+        model: "black-forest-labs/flux",
+      },
+    });
+
+    expect(lastGenerateProvider).toBe("openrouter");
+    expect(lastGenerateRequest?.model).toBe("black-forest-labs/flux");
+    expect(result).toMatchObject({
+      resolvedModel: "black-forest-labs/flux",
+    });
+  });
+
+  test("qualifies a built-in alias for OpenRouter", async () => {
+    await route.handler({
+      body: { prompt: "a robot", model: "fast" },
+    });
+
+    expect(lastGenerateRequest?.model).toBe(
+      "google/gemini-3.1-flash-image-preview",
+    );
+  });
+
+  test("rejects an unknown model when the provider is not OpenRouter", async () => {
+    setConfig("services", {
+      "image-generation": {
+        provider: "gemini",
+        model: "gemini-3.1-flash-image-preview",
+      },
+    });
+
+    await expect(
+      route.handler({
+        body: { prompt: "a cat", model: "black-forest-labs/flux" },
+      }),
+    ).rejects.toThrow(BadRequestError);
+    expect(lastGenerateProvider).toBeNull();
+  });
+});

package/src/runtime/routes/__tests__/inference-profiles-routes.test.ts

@@ -927,7 +927,7 @@ describe("PUT inference/active-profile validation", () => {
       profiles: {
         jev: {
           source: "user",
-          provider: "jev",
+          provider: "typesafe",
           model: "jev-latest",
           status: "active",
         },

package/src/runtime/routes/__tests__/roadmap-routes.test.ts

@@ -334,12 +334,35 @@ describe("roadmap writes", () => {
     });
   });
 
-  test("update can clear every tag", async () => {
+  test("update refuses the staff-only fields before calling out", async () => {
     stubFetch(UPSTREAM_ITEM);
 
-    await update({ pathParams: { slug: "dark-mode" }, body: { tags: [] } });
+    await expect(
+      update({
+        pathParams: { slug: "dark-mode" },
+        body: { title: "Dark mode", status: "planned" },
+      }),
+    ).rejects.toThrow(
+      "An assistant can change only an item's title and description; status is set by Vellum staff.",
+    );
+    await expect(
+      update({ pathParams: { slug: "dark-mode" }, body: { tags: [] } }),
+    ).rejects.toThrow("tags is set by Vellum staff");
+    expect(calls).toHaveLength(0);
+  });
 
-    expect(calls[0].body).toEqual({ tags: [] });
+  test("update names an unknown field as unknown, not as staff-only", async () => {
+    stubFetch(UPSTREAM_ITEM);
+
+    await expect(
+      update({
+        pathParams: { slug: "dark-mode" },
+        body: { titel: "Dark mode", status: "planned" },
+      }),
+    ).rejects.toThrow(
+      "An assistant can change only an item's title and description; status is set by Vellum staff; titel is not a roadmap update field.",
+    );
+    expect(calls).toHaveLength(0);
   });
 
   test("create rejects a blank title before calling out", async () => {
@@ -365,11 +388,11 @@ describe("roadmap writes", () => {
 
     await update({
       pathParams: { slug: "dark-mode" },
-      body: { status: "planned" },
+      body: { description: "Follow the OS setting" },
     });
 
     expect(calls[0].method).toBe("PATCH");
-    expect(calls[0].body).toEqual({ status: "planned" });
+    expect(calls[0].body).toEqual({ description: "Follow the OS setting" });
   });
 
   test("delete reports the removed slug", async () => {
@@ -403,7 +426,7 @@ describe("roadmap writes", () => {
     const writes = [
       () => create({ body: { title: "Add dark mode" } }),
       () =>
-        update({ pathParams: { slug: "dark-mode" }, body: { status: "open" } }),
+        update({ pathParams: { slug: "dark-mode" }, body: { title: "Dark" } }),
       () => remove({ pathParams: { slug: "dark-mode" } }),
       () => upvote({ pathParams: { slug: "dark-mode" } }),
       () => unvote({ pathParams: { slug: "dark-mode" } }),

package/src/runtime/routes/browser-context.ts

@@ -1,3 +1,4 @@
+import type { Conversation } from "../../daemon/conversation.js";
 import { resolveTurnClientOs } from "../../daemon/conversation-client-surface.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
 import type { ToolContext } from "../../tools/types.js";
@@ -13,6 +14,22 @@ export async function resolveBrowserContext(
   headers: Record<string, string>,
   abortSignal?: AbortSignal,
 ): Promise<ToolContext> {
+  return (
+    await resolveBrowserExecutionContext(
+      conversationId,
+      sessionId,
+      headers,
+      abortSignal,
+    )
+  ).context;
+}
+
+export async function resolveBrowserExecutionContext(
+  conversationId: string | undefined,
+  sessionId: string,
+  headers: Record<string, string>,
+  abortSignal?: AbortSignal,
+): Promise<{ context: ToolContext; conversation?: Conversation }> {
   const conversation = conversationId
     ? findConversation(conversationId)
     : undefined;
@@ -24,16 +41,19 @@ export async function resolveBrowserContext(
     (signal): signal is AbortSignal => signal !== undefined,
   );
   return {
-    workingDir: process.cwd(),
-    conversationId: conversation
-      ? conversationId!
-      : browserCliConversationKey(sessionId),
-    trustClass: conversation?.trustContext?.trustClass ?? "unknown",
-    transportInterface: conversation?.transportInterface,
-    clientOs: conversation
-      ? resolveTurnClientOs(conversation).clientOs
-      : undefined,
-    sourceActorPrincipalId: actor,
-    signal: signals.length ? AbortSignal.any(signals) : undefined,
+    context: {
+      workingDir: process.cwd(),
+      conversationId: conversation
+        ? conversationId!
+        : browserCliConversationKey(sessionId),
+      trustClass: conversation?.trustContext?.trustClass ?? "unknown",
+      transportInterface: conversation?.transportInterface,
+      clientOs: conversation
+        ? resolveTurnClientOs(conversation).clientOs
+        : undefined,
+      sourceActorPrincipalId: actor,
+      signal: signals.length ? AbortSignal.any(signals) : undefined,
+    },
+    ...(conversation ? { conversation } : {}),
   };
 }

package/src/runtime/routes/browser-routes.ts

@@ -11,16 +11,20 @@
 
 import { z } from "zod";
 
-import { executeBrowserOperation } from "../../browser/operations.js";
+import {
+  browserOperationLifecycle,
+  executeBrowserOperation,
+} from "../../browser/operations.js";
 import {
   BROWSER_OPERATIONS,
   type BrowserOperation,
 } from "../../browser/types.js";
 import { shouldUseVirtualDesktopBrowser } from "../../browser/virtual-desktop-target.js";
+import { bestEffortModeSessionTracking } from "../../daemon/mode-session-tracking.js";
 import { executeDesktopBrowserOperation } from "../../desktop/desktop-browser-operations.js";
 import type { ContentBlock } from "../../providers/types.js";
 import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
-import { resolveBrowserContext } from "./browser-context.js";
+import { resolveBrowserExecutionContext } from "./browser-context.js";
 export { browserCliConversationKey } from "./browser-context.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -68,16 +72,51 @@ async function handleBrowserExecute({
   const { operation, input, sessionId, conversationId, desktop } =
     BrowserExecuteParams.parse(body);
 
-  const context = await resolveBrowserContext(
+  const resolved = await resolveBrowserExecutionContext(
     conversationId,
     sessionId,
     headers,
     abortSignal,
   );
+  const { context, conversation } = resolved;
+  const typedOperation = operation as BrowserOperation;
+  const operationToken = conversation?.currentRequestId
+    ? bestEffortModeSessionTracking("browser admission", () =>
+        conversation.browserModeSessions.beginOperation({
+          turnId: conversation.currentRequestId!,
+          lifecycle: browserOperationLifecycle(typedOperation),
+          at: Date.now(),
+        }),
+      )
+    : undefined;
   const execute = shouldUseVirtualDesktopBrowser(desktop, input, context)
     ? executeDesktopBrowserOperation
     : executeBrowserOperation;
-  const result = await execute(operation as BrowserOperation, input, context);
+  const finishOperationTracking = (isError: boolean) => {
+    if (!operationToken) {
+      return;
+    }
+    bestEffortModeSessionTracking("browser completion", () =>
+      conversation?.browserModeSessions.finishOperation(operationToken, {
+        at: Date.now(),
+        isError,
+        cancelled: context.signal?.aborted === true,
+        ...(typedOperation === "close"
+          ? { terminalReason: "browser_closed" as const }
+          : typedOperation === "detach"
+            ? { terminalReason: "browser_detached" as const }
+            : {}),
+      }),
+    );
+  };
+  let result;
+  try {
+    result = await execute(typedOperation, input, context);
+  } catch (error) {
+    finishOperationTracking(true);
+    throw error;
+  }
+  finishOperationTracking(result.isError);
 
   const screenshots = extractScreenshots(result.contentBlocks);
 

package/src/runtime/routes/btw-routes.ts

@@ -2,9 +2,10 @@
  * Route handler for the POST /v1/btw SSE-streaming side-chain endpoint.
  *
  * Runs an ephemeral LLM call that reuses the conversation's provider, tool
- * definitions, and message history for prompt-cache efficiency. Uses the
- * conversation's system prompt when a conversation-specific override is active;
- * otherwise builds a fresh prompt excluding BOOTSTRAP.md so first-run
+ * definitions, and message history for prompt-cache efficiency; the
+ * empty-state greeting targets no real conversation and sends no tools. Uses
+ * the conversation's system prompt when a conversation-specific override is
+ * active; otherwise builds a fresh prompt excluding BOOTSTRAP.md so first-run
  * onboarding instructions don't leak into cosmetic UI calls like identity
  * intro generation. The response is streamed as SSE events (`btw_text_delta`,
  * `btw_complete`, `btw_error`).
@@ -145,7 +146,11 @@ async function handleBtw({
           const result = await runBtwSidechain({
             content: effectiveContent,
             conversation,
-            tools: getAllToolDefinitions(),
+            // The side-chain forces `tool_choice: none`, so tool definitions
+            // only earn their tokens as a shared cache prefix with a real
+            // conversation. The greeting runs against an ephemeral one with its
+            // own system prompt, so it shares nothing and sends no tools.
+            tools: isGreeting ? [] : getAllToolDefinitions(),
             signal: abortSignal,
             ...(isGreeting ? { callSite: "emptyStateGreeting" as const } : {}),
             onEvent: (event) => {