@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/runtime/routes/desktop-setup-routes.test.ts

@@ -9,25 +9,22 @@ import {
 } from "bun:test";
 
 import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
-import { desktopDependencyInstaller } from "../../desktop/desktop-dependencies.js";
+import { desktopDependencies } from "../../desktop/desktop-dependencies.js";
 import { ROUTES } from "./desktop-setup-routes.js";
 import { NotFoundError } from "./errors.js";
 
 const originalContainerized = process.env.IS_CONTAINERIZED;
 const originalPlatform = process.env.IS_PLATFORM;
-const status = spyOn(desktopDependencyInstaller, "getStatus");
-const start = spyOn(desktopDependencyInstaller, "start");
+const status = spyOn(desktopDependencies, "getStatus");
 
 afterAll(() => {
   status.mockRestore();
-  start.mockRestore();
 });
 
 beforeEach(() => {
   process.env.IS_CONTAINERIZED = "true";
   process.env.IS_PLATFORM = "true";
-  status.mockReturnValue({ state: "required" });
-  start.mockReturnValue({ state: "installing", stage: "packages" });
+  status.mockReturnValue({ state: "ready" });
 });
 
 afterEach(() => {
@@ -43,7 +40,6 @@ afterEach(() => {
   }
   setOverridesForTesting({});
   status.mockClear();
-  start.mockClear();
 });
 
 describe("desktop setup route feature gate", () => {
@@ -55,7 +51,6 @@ describe("desktop setup route feature gate", () => {
         );
         expect(() => route.handler({})).toThrow(NotFoundError);
         expect(status).not.toHaveBeenCalled();
-        expect(start).not.toHaveBeenCalled();
       });
     }
 
@@ -64,26 +59,22 @@ describe("desktop setup route feature gate", () => {
       setOverridesForTesting({ "assistant-desktop": true });
       expect(() => route.handler({})).toThrow(NotFoundError);
       expect(status).not.toHaveBeenCalled();
-      expect(start).not.toHaveBeenCalled();
     });
 
-    test(`${route.method} rejects self-hosted Docker assistants without inspecting or installing dependencies`, () => {
+    test(`${route.method} rejects self-hosted Docker assistants without inspecting dependencies`, () => {
       process.env.IS_PLATFORM = "false";
       setOverridesForTesting({ "assistant-desktop": true });
       expect(() => route.handler({})).toThrow(NotFoundError);
       expect(status).not.toHaveBeenCalled();
-      expect(start).not.toHaveBeenCalled();
     });
 
     test(`${route.method} serves setup only for enabled platform containers`, () => {
       setOverridesForTesting({ "assistant-desktop": true });
-      expect(route.handler({})).toEqual(
-        route.method === "GET"
-          ? { state: "required" }
-          : { state: "installing", stage: "packages" },
-      );
-      expect(route.method === "GET" ? status : start).toHaveBeenCalledTimes(1);
-      expect(route.method === "GET" ? start : status).not.toHaveBeenCalled();
+      expect(route.handler({})).toEqual({
+        state: "ready",
+        automationActive: false,
+      });
+      expect(status).toHaveBeenCalledTimes(1);
     });
   }
 });

package/src/runtime/routes/desktop-setup-routes.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
-import { getConfig } from "../../config/loader.js";
-import { desktopDependencyInstaller } from "../../desktop/desktop-dependencies.js";
+import { desktopAutomationLease } from "../../desktop/desktop-automation-lease.js";
+import { desktopDependencies } from "../../desktop/desktop-dependencies.js";
 import { isVirtualDesktopEnabled } from "../../desktop/virtual-desktop-feature.js";
 import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
@@ -9,9 +9,11 @@ import type { RouteDefinition } from "./types.js";
 
 const statusSchema = z.object({
   state: z.enum(["required", "installing", "ready", "failed", "unsupported"]),
+  automationActive: z.boolean().optional(),
   stage: z.enum(["packages", "chrome", "checking"]).optional(),
 });
 
+// POST and its wire schema support released clients; both methods only read readiness.
 export const ROUTES: RouteDefinition[] = ["GET", "POST"].map((method) => ({
   operationId:
     method === "GET" ? "desktop_setup_status" : "desktop_setup_install",
@@ -19,19 +21,18 @@ export const ROUTES: RouteDefinition[] = ["GET", "POST"].map((method) => ({
   method,
   policy: { requiredScopes: [], allowedPrincipalTypes: GATEWAY_PRINCIPALS },
   handler: () => {
-    if (!isVirtualDesktopEnabled(getConfig())) {
+    if (!isVirtualDesktopEnabled()) {
       throw new NotFoundError(
         "Virtual desktop is available only on enabled platform-hosted assistants",
       );
     }
-    return method === "GET"
-      ? desktopDependencyInstaller.getStatus()
-      : desktopDependencyInstaller.start();
+    const status = desktopDependencies.getStatus();
+    return { ...status, automationActive: desktopAutomationLease.isActive };
   },
   summary:
     method === "GET"
       ? "Get virtual desktop setup status"
-      : "Install virtual desktop components",
+      : "Check virtual desktop readiness (legacy POST)",
   tags: ["desktop"],
   responseBody: statusSchema,
 }));

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

@@ -8,10 +8,13 @@ import { z } from "zod";
 
 import {
   addDocumentConversation,
+  createDocument,
+  DEFAULT_DOCUMENT_TITLE,
   getDocumentById,
   getDocumentsForConversation,
   saveDocument,
 } from "../../documents/document-store.js";
+import { getConversation } from "../../persistence/conversation-crud.js";
 import { rawAll } from "../../persistence/raw-query.js";
 import { getLogger } from "../../util/logger.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
@@ -214,6 +217,54 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
 
+  {
+    operationId: "createDocument",
+    endpoint: "documents/create",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Create a document",
+    description:
+      "Create an empty document owned by a conversation and return it with its new surface ID.",
+    tags: ["documents"],
+    requestBody: z.object({
+      conversationId: z.string().describe("Owning conversation"),
+      title: z
+        .string()
+        .optional()
+        .describe(`Document title. Defaults to "${DEFAULT_DOCUMENT_TITLE}".`),
+    }),
+    responseBody: documentPayloadSchema,
+    handler: ({ body, headers }) => {
+      const { conversationId, title } = (body ?? {}) as {
+        conversationId?: string;
+        title?: string;
+      };
+      if (!conversationId || typeof conversationId !== "string") {
+        throw new BadRequestError("conversationId is required");
+      }
+      if (title !== undefined && typeof title !== "string") {
+        throw new BadRequestError("title must be a string");
+      }
+      if (!getConversation(conversationId)) {
+        throw new NotFoundError("Conversation not found");
+      }
+
+      const result = createDocument({ conversationId, title: title?.trim() });
+      if (!result.success) {
+        throw new InternalError(result.error);
+      }
+      const doc = getDocumentById(result.surfaceId);
+      if (!doc) {
+        throw new InternalError("Created document could not be read back");
+      }
+      publishDocumentsChanged(getOriginClientId(headers));
+      return { success: true, ...doc };
+    },
+  },
+
   {
     operationId: "linkDocumentConversation",
     endpoint: "documents/:id/conversations",

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

@@ -169,7 +169,7 @@ async function handleEmailStatus(_args: RouteHandlerArgs) {
     );
   }
 
-  const statusData = (await statusResponse.json()) as {
+  return (await statusResponse.json()) as {
     address: string;
     status: string;
     created_at: string;
@@ -181,8 +181,6 @@ async function handleEmailStatus(_args: RouteHandlerArgs) {
       received_this_month: number;
     };
   };
-
-  return statusData;
 }
 
 async function handleEmailList({ queryParams = {} }: RouteHandlerArgs) {
@@ -239,8 +237,7 @@ async function handleEmailDownload({ queryParams = {} }: RouteHandlerArgs) {
     throw new RouteError(String(detail), "DOWNLOAD_FAILED", response.status);
   }
 
-  const msg = await response.json();
-  return msg;
+  return response.json();
 }
 
 async function handleEmailSend({ body = {} }: RouteHandlerArgs) {
@@ -323,11 +320,10 @@ async function handleEmailSend({ body = {} }: RouteHandlerArgs) {
     throw new BadRequestError(String(detail));
   }
 
-  const data = (await response.json()) as {
+  return (await response.json()) as {
     delivery_id: string;
     status: string;
   };
-  return data;
 }
 
 // ── Attachment handlers ───────────────────────────────────────────────

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

@@ -20,9 +20,10 @@
 
 import { type IntervalHistogram, monitorEventLoopDelay } from "node:perf_hooks";
 
+import { sanitizeClientMetadataValue } from "@vellumai/service-contracts/client-metadata";
 import { z } from "zod";
 
-import type { HostProxyCapability } from "../../channels/types.js";
+import type { HostProxyCapability, InterfaceId } from "../../channels/types.js";
 import { parseInterfaceId, supportsHostProxy } from "../../channels/types.js";
 import { notifyContactsChanged } from "../../contacts/notify-contacts-changed.js";
 import { getConversation } from "../../persistence/conversation-crud.js";
@@ -38,7 +39,7 @@ import {
   AssistantEventHub,
   assistantEventHub,
 } from "../assistant-event-hub.js";
-import type { ReplaySubscriber } from "../assistant-stream-state.js";
+import type { SubscriberIdentity } from "../assistant-event-targeting.js";
 import { getReplayWindow } from "../assistant-stream-state.js";
 import { ACTOR_PRINCIPALS, GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { DEFAULT_HEARTBEAT_INTERVAL_MS } from "../client-health.js";
@@ -248,12 +249,14 @@ const defaultSseShedReporter: SseShedReporter = (reason, inst) => {
  *   conversations for this assistant.
  *
  * Headers (optional):
- *   X-Vellum-Client-Id    -- stable per-install UUID identifying this client.
- *   X-Vellum-Interface-Id -- interface type (e.g. "macos", "ios", "web").
+ *   X-Vellum-Client-Id      -- stable per-install UUID identifying this client.
+ *   X-Vellum-Interface-Id   -- interface type (e.g. "macos", "ios", "web").
+ *   X-Vellum-Client-Version -- optional build/manifest version fingerprint.
+ *   X-Vellum-Sse-Watchdog   -- optional "1" when the client has an SSE idle watchdog.
  *
- *   When both are present, the subscriber is registered as a client in the
- *   event hub with metadata (interfaceId, capabilities). The hub handles
- *   lifecycle — dispose() unregisters the client automatically.
+ *   When both identity headers are present, the subscriber is registered as a
+ *   client in the event hub with metadata (interfaceId, capabilities). The hub
+ *   handles lifecycle. dispose() unregisters the client automatically.
  *
  * Options (for testing):
  *   hub               -- override the event hub (defaults to process singleton).
@@ -300,25 +303,18 @@ export function handleSubscribeAssistantEvents(
   }
 
   // ── Client identity from headers ──────────────────────────────────────
-  const rawClientId = headers?.["x-vellum-client-id"];
-  const rawInterfaceId = headers?.["x-vellum-interface-id"];
   const rawMachineName = headers?.["x-vellum-machine-name"];
   const rawActorPrincipalId = headers?.["x-vellum-actor-principal-id"];
-  const clientId = rawClientId?.trim() || null;
-  const interfaceId = clientId
-    ? parseInterfaceId(rawInterfaceId?.trim())
-    : null;
-  // Verified by RuntimeHttpServer and forwarded by the http-adapter from the
-  // bearer token's AuthContext. May be absent for legacy / service-token
-  // connections that have no principal. See `resolveActorPrincipalId` for the
-  // dev-bypass translation rationale.
-  const actorPrincipalId = resolveActorPrincipalIdForLocalGuardianSync(
-    rawActorPrincipalId?.trim() || undefined,
+  const { clientId, interfaceId, actorPrincipalId } =
+    readClientIdentity(headers);
+  const clientVersion = sanitizeClientMetadataValue(
+    headers?.["x-vellum-client-version"],
   );
+  const sseWatchdog = headers?.["x-vellum-sse-watchdog"]?.trim() === "1";
 
   if (clientId && !interfaceId) {
     log.error(
-      { clientId, rawInterfaceId },
+      { clientId, rawInterfaceId: headers?.["x-vellum-interface-id"] },
       "client registration failed: invalid or missing X-Vellum-Interface-Id",
     );
     throw new BadRequestError(
@@ -410,7 +406,7 @@ export function handleSubscribeAssistantEvents(
     try {
       if (controller.desiredSize != null && controller.desiredSize <= 0) {
         shedReporter("callback_backpressure", instrumentation);
-        sub.dispose();
+        sub.dispose("shed_backpressure");
         cleanup();
         return;
       }
@@ -455,6 +451,8 @@ export function handleSubscribeAssistantEvents(
             ],
             machineName: rawMachineName?.trim() || undefined,
             actorPrincipalId,
+            clientVersion,
+            sseWatchdog: sseWatchdog || undefined,
           })
         : hub.subscribe({
             ...subscriberBase,
@@ -521,20 +519,9 @@ export function handleSubscribeAssistantEvents(
         // The client detects the gap from the seq jump on its first
         // live event and refetches via the existing messages API.
         if (lastSeenSeq != null) {
-          const replaySubscriber: ReplaySubscriber =
-            clientId && interfaceId
-              ? {
-                  type: "client",
-                  clientId,
-                  interfaceId,
-                  capabilities: ALL_CAPABILITIES.filter((cap) =>
-                    supportsHostProxy(interfaceId, cap),
-                  ),
-                }
-              : { type: "process" };
           const window = getReplayWindow(
             lastSeenSeq,
-            replaySubscriber,
+            replaySubscriberFor(clientId, interfaceId, actorPrincipalId),
             filter.conversationId,
           );
           if (window !== null) {
@@ -555,7 +542,7 @@ export function handleSubscribeAssistantEvents(
           try {
             if (controller.desiredSize != null && controller.desiredSize <= 0) {
               shedReporter("heartbeat_backpressure", instrumentation);
-              sub.dispose();
+              sub.dispose("shed_backpressure");
               cleanup();
               return;
             }
@@ -590,6 +577,53 @@ export function handleSubscribeAssistantEvents(
   return stream;
 }
 
+/**
+ * The caller's client identity, read the same way by the SSE subscribe route
+ * and the tail route. The principal is verified by RuntimeHttpServer and
+ * forwarded by the http-adapter from the bearer token's AuthContext; it is
+ * absent for legacy and service-token connections, and a dev-bypass header
+ * resolves to the local guardian (see `resolveActorPrincipalIdForLocalGuardianSync`).
+ */
+function readClientIdentity(headers: Record<string, string> | undefined): {
+  clientId: string | null;
+  interfaceId: InterfaceId | null;
+  actorPrincipalId: string | undefined;
+} {
+  const clientId = headers?.["x-vellum-client-id"]?.trim() || null;
+  const interfaceId = clientId
+    ? parseInterfaceId(headers?.["x-vellum-interface-id"]?.trim())
+    : null;
+  const actorPrincipalId = resolveActorPrincipalIdForLocalGuardianSync(
+    headers?.["x-vellum-actor-principal-id"]?.trim() || undefined,
+  );
+  return { clientId, interfaceId, actorPrincipalId };
+}
+
+/**
+ * The identity a replay filter checks targeted events against: the client a
+ * live SSE subscription with these headers would register, or a process
+ * subscriber when the caller names no client. Shared by the reconnect replay
+ * and the tail route so both deliver exactly what live fanout would have.
+ */
+function replaySubscriberFor(
+  clientId: string | null,
+  interfaceId: InterfaceId | null,
+  actorPrincipalId: string | undefined,
+): SubscriberIdentity {
+  if (!clientId || !interfaceId) {
+    return { type: "process" };
+  }
+  return {
+    type: "client",
+    clientId,
+    interfaceId,
+    capabilities: ALL_CAPABILITIES.filter((cap) =>
+      supportsHostProxy(interfaceId, cap),
+    ),
+    actorPrincipalId,
+  };
+}
+
 /**
  * Replay-by-request companion to the SSE `lastSeenSeq` resume: return the
  * ring-buffered event tail for one conversation with `seq > fromSeq`.
@@ -641,26 +675,13 @@ function handleEventsTail({
     toSeq = parsed;
   }
 
-  // Same client-identity resolution as the SSE subscribe handler, so the
-  // replay filter matches what a live subscription would have delivered.
-  const rawClientId = headers?.["x-vellum-client-id"];
-  const clientId = rawClientId?.trim() || null;
-  const interfaceId = clientId
-    ? parseInterfaceId(headers?.["x-vellum-interface-id"]?.trim())
-    : null;
-  const subscriber: ReplaySubscriber | undefined =
-    clientId && interfaceId
-      ? {
-          type: "client",
-          clientId,
-          interfaceId,
-          capabilities: ALL_CAPABILITIES.filter((cap) =>
-            supportsHostProxy(interfaceId, cap),
-          ),
-        }
-      : undefined;
-
-  const window = getReplayWindow(fromSeq, subscriber, conversationId);
+  const { clientId, interfaceId, actorPrincipalId } =
+    readClientIdentity(headers);
+  const window = getReplayWindow(
+    fromSeq,
+    replaySubscriberFor(clientId, interfaceId, actorPrincipalId),
+    conversationId,
+  );
   if (window === null) {
     return { events: [], complete: false, frontier: null };
   }

package/src/runtime/routes/guardian-approval-interception.ts

@@ -299,6 +299,30 @@ export async function handleApprovalInterception(
 
       return { handled: true, type: "stale_ignored" };
     }
+
+    // An approval callback that names no approval action is a button press
+    // the daemon does not serve (an id outside the decision vocabulary, or an
+    // answer token aimed at a card this rail does not resolve). It is never
+    // text: the channel normalizers copy callback data into `content`, so
+    // letting it fall through would hand the raw callback to the
+    // conversational and natural-language parsers, which can read a token
+    // like `approve_always` as an approval. Consume it as a stale button.
+    if (callbackData.startsWith("apr:")) {
+      log.warn(
+        { conversationId, callbackData },
+        "Approval callback carries no approval action, ignoring stale button press",
+      );
+      if (approvalMessageId) {
+        editStaleApprovalMessage({
+          replyCallbackUrl,
+          chatId: conversationExternalId,
+          messageId: approvalMessageId,
+          assistantId,
+          conversationId,
+        });
+      }
+      return { handled: true, type: "stale_ignored" };
+    }
   }
 
   // ── Conversational approval engine for plain-text messages ──

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

@@ -228,7 +228,7 @@ function getIdentity() {
 
   const version = APP_VERSION;
 
-  const createdAt = resolveIdentityCreatedAt(identityPath);
+  const createdAt = resolveHatchedAtReadOnly(identityPath);
 
   return {
     name: fields.name ?? "",
@@ -241,10 +241,6 @@ function getIdentity() {
   };
 }
 
-function resolveIdentityCreatedAt(identityPath: string): string | undefined {
-  return resolveHatchedAtReadOnly(identityPath);
-}
-
 // ---------------------------------------------------------------------------
 // Zod schemas for profiler health metadata
 // ---------------------------------------------------------------------------

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

@@ -5,10 +5,7 @@ import {
   resolveImageGenCredentials,
   resolveImageGenRouting,
 } from "../../media/image-credentials.js";
-import {
-  describeImageModels,
-  resolveImageModel,
-} from "../../media/image-models.js";
+import { resolveRequestedImageModel } from "../../media/image-models.js";
 import { generateImage, mapImageGenError } from "../../media/image-service.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
@@ -80,18 +77,15 @@ async function handleImageGenerationGenerate(
   const config = getConfig();
   const svc = config.services["image-generation"];
 
-  // Resolve tier aliases (fast, quality, openai) to concrete model IDs via
-  // the registry; reject unknown values with the current catalog so the
-  // error is self-describing rather than a stale enum.
+  // Resolve aliases and OpenRouter slugs against the configured provider.
+  // Built-in providers still list the current catalog on unknown values.
   let resolvedModel = model as string | undefined;
   if (typeof resolvedModel === "string" && resolvedModel) {
-    const entry = resolveImageModel(resolvedModel);
-    if (!entry) {
-      throw new BadRequestError(
-        `Unknown model "${resolvedModel}". Available models and aliases:\n${describeImageModels()}`,
-      );
+    const resolved = resolveRequestedImageModel(resolvedModel, svc.provider);
+    if (resolved.error) {
+      throw new BadRequestError(resolved.error);
     }
-    resolvedModel = entry.id;
+    resolvedModel = resolved.model;
   }
 
   // Backend and managed-ness resolve together; an explicit model override
@@ -154,7 +148,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Generate or edit images using AI",
     description:
-      "Calls the configured image-generation provider (Gemini or OpenAI) to produce one or more images.",
+      "Calls the configured image-generation provider (Gemini, OpenAI, or OpenRouter) to produce one or more images.",
     tags: ["image-generation"],
     requestBody: ImageGenerationRequestSchema,
     responseBody: ImageGenerationResponseSchema,