@vellumai/assistant 0.11.0 → 0.11.1-staging.2

package/src/runtime/routes/errors.ts

@@ -139,6 +139,19 @@ export class GatewayTimeoutError extends RouteError {
   }
 }
 
+/**
+ * An upstream LLM provider call failed. Carries the per-request diagnostics
+ * observed on the wire (resolved URL, model, connection, HTTP status, verbatim
+ * upstream error body) in `details` so a caller diagnosing the failure sees
+ * what was actually sent and what came back, not just the normalized message.
+ */
+export class UpstreamProviderError extends RouteError {
+  constructor(message: string, details: unknown) {
+    super(message, "UPSTREAM_PROVIDER_ERROR", 502, details);
+    this.name = "UpstreamProviderError";
+  }
+}
+
 export class InternalError extends RouteError {
   constructor(message: string) {
     super(message, "INTERNAL_ERROR", 500);

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

@@ -91,7 +91,9 @@ let eventLoopResetTimer: ReturnType<typeof setInterval> | null = null;
  * SSE handler.
  */
 function ensureEventLoopDelayMonitorStarted(): void {
-  if (eventLoopDelay !== null) return;
+  if (eventLoopDelay !== null) {
+    return;
+  }
   try {
     const histogram = monitorEventLoopDelay({
       resolution: EVENT_LOOP_DELAY_RESOLUTION_MS,
@@ -122,7 +124,9 @@ export interface EventLoopDelaySnapshot {
 }
 
 function nsToMs(ns: number): number | null {
-  if (!Number.isFinite(ns)) return null;
+  if (!Number.isFinite(ns)) {
+    return null;
+  }
   // Round to the nearest microsecond, then express in ms (3 decimal places).
   return Math.round(ns / 1e3) / 1e3;
 }
@@ -388,7 +392,9 @@ export function handleSubscribeAssistantEvents(
 
   const callback: AssistantEventCallback = (event) => {
     const controller = controllerRef;
-    if (!controller) return;
+    if (!controller) {
+      return;
+    }
     if (
       event.seq != null &&
       highWaterReplaySeq >= 0 &&

package/src/runtime/routes/global-search-routes.ts

@@ -18,6 +18,7 @@ import {
   embedWithBackend,
   getMemoryBackendStatus,
 } from "../../persistence/embeddings/embedding-backend.js";
+import { tokenize } from "../../persistence/embeddings/sparse-tokenize.js";
 import { rawMemoryAll } from "../../persistence/raw-query.js";
 import { semanticSearch } from "../../plugins/defaults/memory/v1/semantic-search.js";
 import { listSchedules } from "../../schedule/schedule-store.js";
@@ -68,6 +69,11 @@ const globalSearchContactSchema = z.object({
 
 const globalSearchResponseSchema = z.object({
   query: z.string(),
+  /**
+   * Lexical tokens of `query`, from the same tokenizer the sparse index
+   * uses. Clients highlight these instead of re-tokenizing client-side.
+   */
+  queryTokens: z.array(z.string()),
   results: z.object({
     conversations: z.array(globalSearchConversationSchema),
     memories: z.array(globalSearchMemorySchema),
@@ -93,7 +99,9 @@ const ALL_CATEGORIES = [
 type Category = (typeof ALL_CATEGORIES)[number];
 
 function parseCategories(raw: string | undefined): Set<Category> {
-  if (!raw) return new Set(ALL_CATEGORIES);
+  if (!raw) {
+    return new Set(ALL_CATEGORIES);
+  }
   const requested = raw
     .split(",")
     .map((s) => s.trim().toLowerCase())
@@ -126,7 +134,9 @@ function parseSearchQuery(rawQ: string | undefined): {
   term: string;
   archived: boolean;
 } {
-  if (!rawQ) return { term: "", archived: false };
+  if (!rawQ) {
+    return { term: "", archived: false };
+  }
   const tokens = rawQ.split(/\s+/).filter((t) => t.length > 0);
   const termTokens: string[] = [];
   let archived = false;
@@ -155,7 +165,9 @@ function searchMemoryItems(query: string, limit: number): GlobalSearchMemory[] {
   // The memory graph lives in the dedicated memory database. If it cannot be
   // opened, degrade this category to empty rather than failing the whole
   // federated search — conversations, schedules, and contacts still return.
-  if (!getMemorySqlite()) return [];
+  if (!getMemorySqlite()) {
+    return [];
+  }
 
   const likePattern = `%${query.replace(/%/g, "").replace(/_/g, "")}%`;
 
@@ -201,12 +213,16 @@ async function searchMemoriesSemantic(
 ): Promise<GlobalSearchMemory[]> {
   const config = getConfig();
   const backendStatus = await getMemoryBackendStatus(config);
-  if (!backendStatus.provider) return [];
+  if (!backendStatus.provider) {
+    return [];
+  }
 
   try {
     const embedded = await embedWithBackend(config, [query]);
     const queryVector = embedded.vectors[0];
-    if (!queryVector) return [];
+    if (!queryVector) {
+      return [];
+    }
 
     const candidates = await semanticSearch(
       queryVector,
@@ -217,8 +233,12 @@ async function searchMemoriesSemantic(
 
     const results: GlobalSearchMemory[] = [];
     for (const c of candidates) {
-      if (c.type !== "item") continue;
-      if (existingIds.has(c.id)) continue;
+      if (c.type !== "item") {
+        continue;
+      }
+      if (existingIds.has(c.id)) {
+        continue;
+      }
       results.push({
         id: c.id,
         kind: c.kind,
@@ -336,7 +356,7 @@ async function handleGlobalSearch({
     }));
   }
 
-  return { query: term, results };
+  return { query: term, queryTokens: tokenize(term), results };
 }
 
 // ---------------------------------------------------------------------------

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

@@ -26,15 +26,43 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 const groupSchema = z.object({
   id: z.string(),
   name: z.string(),
+  icon: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("Client-chosen icon name; null when the group has none"),
   sortPosition: z.number(),
   isSystemGroup: z.boolean(),
 });
 
+/**
+ * Validate an `icon` field from a request body. Returns the normalized value:
+ * `undefined` = field absent (leave unchanged), `null` = clear the icon,
+ * string = set it. Icon names are client-defined identifiers, not free text.
+ */
+function parseIconField(value: unknown): string | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return null;
+  }
+  if (typeof value !== "string" || value.length > 100) {
+    throw new BadRequestError(
+      "icon must be a string of at most 100 characters or null",
+    );
+  }
+  return value;
+}
+
 function serializeGroup(group: ReturnType<typeof getGroup>) {
-  if (!group) return null;
+  if (!group) {
+    return null;
+  }
   return {
     id: group.id,
     name: group.name,
+    icon: group.icon,
     sortPosition: group.sortPosition,
     isSystemGroup: group.isSystemGroup,
   };
@@ -54,8 +82,9 @@ function handleCreateGroup({ body = {}, headers }: RouteHandlerArgs) {
   if (!name || typeof name !== "string") {
     throw new BadRequestError("Missing or invalid name");
   }
+  const icon = parseIconField(body.icon);
   try {
-    const group = createGroup(name);
+    const group = createGroup(name, icon);
     publishConversationListChanged(
       "created",
       headers?.["x-vellum-client-id"]?.trim() || undefined,
@@ -89,6 +118,7 @@ function handleUpdateGroup({
   if (name !== undefined && typeof name !== "string") {
     throw new BadRequestError("name must be a string");
   }
+  const icon = parseIconField(body.icon);
   if (sortPosition !== undefined && typeof sortPosition !== "number") {
     throw new BadRequestError("sortPosition must be a number");
   }
@@ -103,7 +133,7 @@ function handleUpdateGroup({
   ) {
     throw new BadRequestError("Custom group sort_position must be >= 4");
   }
-  const updated = updateGroup(groupId, { name, sortPosition });
+  const updated = updateGroup(groupId, { name, icon, sortPosition });
   if (!updated) {
     throw new NotFoundError("Group not found");
   }
@@ -139,7 +169,9 @@ function handleReorderGroups({ body = {}, headers }: RouteHandlerArgs) {
   }
   for (const update of updates) {
     const group = getGroup(update.groupId);
-    if (!group) continue;
+    if (!group) {
+      continue;
+    }
     if (group.isSystemGroup) {
       throw new ForbiddenError(
         `Cannot reorder system group: ${update.groupId}`,
@@ -198,6 +230,11 @@ export const ROUTES: RouteDefinition[] = [
     tags: ["groups"],
     requestBody: z.object({
       name: z.string().describe("Group name"),
+      icon: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Client-chosen icon name"),
     }),
     responseBody: groupSchema,
     additionalResponses: {
@@ -217,10 +254,15 @@ export const ROUTES: RouteDefinition[] = [
     },
     handler: handleUpdateGroup,
     summary: "Update group",
-    description: "Update a conversation group's name or sort position.",
+    description: "Update a conversation group's name, icon, or sort position.",
     tags: ["groups"],
     requestBody: z.object({
       name: z.string().optional(),
+      icon: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Client-chosen icon name; null clears it"),
       sortPosition: z.number().optional(),
     }),
     responseBody: groupSchema,

package/src/runtime/routes/guardian-action-routes.ts

@@ -151,8 +151,9 @@ export async function listGuardianDecisionPrompts(params: {
 
   for (const req of pendingRequests) {
     // Skip expired requests
-    if (req.expiresAt && new Date(req.expiresAt).getTime() < Date.now())
+    if (req.expiresAt && new Date(req.expiresAt).getTime() < Date.now()) {
       continue;
+    }
 
     const prompt = mapRequestToPrompt(req, conversationId);
     prompts.push(prompt);

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

@@ -277,24 +277,30 @@ export const ROUTES: RouteDefinition[] = [
       // defaults onto disk, masking later schema changes from the user.
       // Use "key in body" checks for nullable fields so explicit null clears them.
       const heartbeatPatch: Record<string, unknown> = {};
-      if ("enabled" in body && typeof body.enabled === "boolean")
+      if ("enabled" in body && typeof body.enabled === "boolean") {
         heartbeatPatch.enabled = body.enabled;
-      if ("intervalMs" in body && typeof body.intervalMs === "number")
+      }
+      if ("intervalMs" in body && typeof body.intervalMs === "number") {
         heartbeatPatch.intervalMs = body.intervalMs;
-      if ("activeHoursStart" in body)
+      }
+      if ("activeHoursStart" in body) {
         heartbeatPatch.activeHoursStart =
           typeof body.activeHoursStart === "number"
             ? body.activeHoursStart
             : null;
-      if ("activeHoursEnd" in body)
+      }
+      if ("activeHoursEnd" in body) {
         heartbeatPatch.activeHoursEnd =
           typeof body.activeHoursEnd === "number" ? body.activeHoursEnd : null;
-      if ("cronExpression" in body)
+      }
+      if ("cronExpression" in body) {
         heartbeatPatch.cronExpression =
           typeof body.cronExpression === "string" ? body.cronExpression : null;
-      if ("timezone" in body)
+      }
+      if ("timezone" in body) {
         heartbeatPatch.timezone =
           typeof body.timezone === "string" ? body.timezone : null;
+      }
 
       try {
         const raw = loadRawConfig();

package/src/runtime/routes/home-feed-routes.ts

@@ -100,14 +100,22 @@ const bulkStatusResponseSchema = z.object({
 
 export function computeGreeting(now: Date): string {
   const hour = now.getHours();
-  if (hour >= 5 && hour < 12) return "Good morning";
-  if (hour >= 12 && hour < 17) return "Good afternoon";
-  if (hour >= 17 && hour < 22) return "Good evening";
+  if (hour >= 5 && hour < 12) {
+    return "Good morning";
+  }
+  if (hour >= 12 && hour < 17) {
+    return "Good afternoon";
+  }
+  if (hour >= 17 && hour < 22) {
+    return "Good evening";
+  }
   return "Welcome back";
 }
 
 export function formatRelativeTime(seconds: number): string {
-  if (!Number.isFinite(seconds) || seconds < 60) return "just now";
+  if (!Number.isFinite(seconds) || seconds < 60) {
+    return "just now";
+  }
   if (seconds < 3600) {
     const mins = Math.floor(seconds / 60);
     return `${mins} minute${mins === 1 ? "" : "s"} ago`;
@@ -116,16 +124,26 @@ export function formatRelativeTime(seconds: number): string {
     const hours = Math.floor(seconds / 3600);
     return `${hours} hour${hours === 1 ? "" : "s"} ago`;
   }
-  if (seconds < 172800) return "yesterday";
+  if (seconds < 172800) {
+    return "yesterday";
+  }
   const days = Math.floor(seconds / 86400);
   return `${days} day${days === 1 ? "" : "s"} ago`;
 }
 
 function timeAwayBucket(seconds: number): string {
-  if (seconds < 1800) return "<1800";
-  if (seconds < 14400) return "1800-14400";
-  if (seconds < 43200) return "14400-43200";
-  if (seconds < 86400) return "43200-86400";
+  if (seconds < 1800) {
+    return "<1800";
+  }
+  if (seconds < 14400) {
+    return "1800-14400";
+  }
+  if (seconds < 43200) {
+    return "14400-43200";
+  }
+  if (seconds < 86400) {
+    return "43200-86400";
+  }
   return ">=86400";
 }
 
@@ -270,34 +288,49 @@ export function handleListHomeFeed({
   const feed = readHomeFeed();
 
   const filtered = feed.items.filter((item) => {
-    if (statusFilter && !statusFilter.has(item.status)) return false;
+    if (statusFilter && !statusFilter.has(item.status)) {
+      return false;
+    }
     if (urgencySet) {
-      if (!item.urgency || !urgencySet.has(item.urgency)) return false;
+      if (!item.urgency || !urgencySet.has(item.urgency)) {
+        return false;
+      }
     }
     if (categorySet) {
-      if (!item.category || !categorySet.has(item.category)) return false;
+      if (!item.category || !categorySet.has(item.category)) {
+        return false;
+      }
     }
     if (
       params.conversationId !== undefined &&
       item.conversationId !== params.conversationId
-    )
+    ) {
       return false;
+    }
     if (
       params.fromAssistant !== undefined &&
       (item.fromAssistant ?? false) !== params.fromAssistant
-    )
+    ) {
       return false;
+    }
     if (
       params.noteworthy !== undefined &&
       (item.noteworthy ?? false) !== params.noteworthy
-    )
+    ) {
       return false;
+    }
 
     if (beforeMs !== undefined || afterMs !== undefined) {
       const createdMs = Date.parse(item.createdAt);
-      if (Number.isNaN(createdMs)) return false;
-      if (beforeMs !== undefined && createdMs >= beforeMs) return false;
-      if (afterMs !== undefined && createdMs <= afterMs) return false;
+      if (Number.isNaN(createdMs)) {
+        return false;
+      }
+      if (beforeMs !== undefined && createdMs >= beforeMs) {
+        return false;
+      }
+      if (afterMs !== undefined && createdMs <= afterMs) {
+        return false;
+      }
     }
 
     return true;

package/src/runtime/routes/host-app-control-routes.ts

@@ -27,23 +27,54 @@ import {
 import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import * as pendingInteractions from "../pending-interactions.js";
 import { BadRequestError, ForbiddenError } from "./errors.js";
+import { parseBody } from "./parse-body.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
-const VALID_STATES: ReadonlySet<HostAppControlState> = new Set([
+/**
+ * States the client may report. `satisfies` keeps this tuple a subset of
+ * {@link HostAppControlState}, so the wire enum cannot drift past the type.
+ */
+const APP_CONTROL_STATES = [
   "running",
   "missing",
   "minimized",
-]);
+] as const satisfies readonly HostAppControlState[];
+
+/**
+ * Body of `POST /v1/host-app-control-result`, declared as the route's
+ * `requestBody` and parsed by the handler, so the OpenAPI contract and the
+ * runtime check are one schema rather than two hand-kept copies.
+ *
+ * Unknown keys are stripped rather than rejected: the macOS executor forwards
+ * its helper's result through a `.passthrough()` schema, so extra fields can
+ * legitimately ride along.
+ */
+const HostAppControlResultBodySchema = z.object({
+  requestId: z.string().min(1).describe("Pending app-control request ID"),
+  state: z
+    .enum(APP_CONTROL_STATES)
+    .describe("Lifecycle state of the targeted application"),
+  pngBase64: z
+    .string()
+    .describe("Base64 PNG screenshot of the targeted app window")
+    .optional(),
+  windowBounds: z
+    .object({
+      x: z.number(),
+      y: z.number(),
+      width: z.number(),
+      height: z.number(),
+    })
+    .optional(),
+  executionResult: z.string().optional(),
+  executionError: z.string().optional(),
+});
 
 // ---------------------------------------------------------------------------
 // POST /v1/host-app-control-result
 // ---------------------------------------------------------------------------
 
 async function handleHostAppControlResult({ body, headers }: RouteHandlerArgs) {
-  if (!body || typeof body !== "object") {
-    throw new BadRequestError("Request body is required");
-  }
-
   const {
     requestId,
     state,
@@ -51,24 +82,7 @@ async function handleHostAppControlResult({ body, headers }: RouteHandlerArgs) {
     windowBounds,
     executionResult,
     executionError,
-  } = body as {
-    requestId?: string;
-    state?: string;
-    pngBase64?: string;
-    windowBounds?: { x: number; y: number; width: number; height: number };
-    executionResult?: string;
-    executionError?: string;
-  };
-
-  if (!requestId || typeof requestId !== "string") {
-    throw new BadRequestError("requestId is required");
-  }
-
-  if (!state || !VALID_STATES.has(state as HostAppControlState)) {
-    throw new BadRequestError(
-      "state must be one of: running, missing, minimized",
-    );
-  }
+  } = parseBody(HostAppControlResultBodySchema, body);
 
   // Late-delivery tolerance: if the pending interaction is already gone (the
   // proxy timed out, the conversation was disposed, etc.), accept the post
@@ -115,7 +129,7 @@ async function handleHostAppControlResult({ body, headers }: RouteHandlerArgs) {
 
   const payload: HostAppControlResultPayload = {
     requestId,
-    state: state as HostAppControlState,
+    state,
     ...(pngBase64 !== undefined ? { pngBase64 } : {}),
     ...(windowBounds !== undefined ? { windowBounds } : {}),
     ...(executionResult !== undefined ? { executionResult } : {}),
@@ -145,26 +159,7 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Resolve a pending host app-control request by requestId. Returns 200 even when no pending interaction matches (late delivery is tolerated).",
     tags: ["host"],
-    requestBody: z.object({
-      requestId: z.string().describe("Pending app-control request ID"),
-      state: z
-        .enum(["running", "missing", "minimized"])
-        .describe("Lifecycle state of the targeted application"),
-      pngBase64: z
-        .string()
-        .describe("Base64 PNG screenshot of the targeted app window")
-        .optional(),
-      windowBounds: z
-        .object({
-          x: z.number(),
-          y: z.number(),
-          width: z.number(),
-          height: z.number(),
-        })
-        .optional(),
-      executionResult: z.string().optional(),
-      executionError: z.string().optional(),
-    }),
+    requestBody: HostAppControlResultBodySchema,
     responseBody: z.object({
       accepted: z.boolean(),
     }),

package/src/runtime/routes/host-bash-routes.ts

@@ -20,28 +20,43 @@ import {
   ForbiddenError,
   NotFoundError,
 } from "./errors.js";
+import { parseBody } from "./parse-body.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
+/**
+ * Body of `POST /v1/host-bash-result`, declared as the route's `requestBody`
+ * and parsed by the handler, so the OpenAPI contract and the runtime check are
+ * one schema rather than two hand-kept copies.
+ *
+ * `exitCode` is nullable because a process terminated by a signal has no exit
+ * status: the desktop executor forwards Node's `close` argument verbatim, which
+ * is `null` on signal termination (including its own timeout kill). The proxy
+ * result type carries that `null` through to the tool output.
+ *
+ * Unknown keys are stripped rather than rejected, so a desktop client that
+ * reports a newer result field still resolves its pending request.
+ */
+const HostBashResultBodySchema = z.object({
+  requestId: z.string().min(1).describe("Pending bash request ID"),
+  stdout: z.string().optional(),
+  stderr: z.string().optional(),
+  exitCode: z
+    .number()
+    .nullable()
+    .describe("Process exit status, or null when terminated by a signal")
+    .optional(),
+  timedOut: z.boolean().optional(),
+});
+
 // ---------------------------------------------------------------------------
 // POST /v1/host-bash-result
 // ---------------------------------------------------------------------------
 
 async function handleHostBashResult({ body, headers }: RouteHandlerArgs) {
-  if (!body || typeof body !== "object") {
-    throw new BadRequestError("Request body is required");
-  }
-
-  const { requestId, stdout, stderr, exitCode, timedOut } = body as {
-    requestId?: string;
-    stdout?: string;
-    stderr?: string;
-    exitCode?: number | null;
-    timedOut?: boolean;
-  };
-
-  if (!requestId || typeof requestId !== "string") {
-    throw new BadRequestError("requestId is required");
-  }
+  const { requestId, stdout, stderr, exitCode, timedOut } = parseBody(
+    HostBashResultBodySchema,
+    body,
+  );
 
   const submittingClientId =
     headers?.["x-vellum-client-id"]?.trim() || undefined;
@@ -114,13 +129,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Submit host bash result",
     description: "Resolve a pending host bash request by requestId.",
     tags: ["host"],
-    requestBody: z.object({
-      requestId: z.string().describe("Pending bash request ID"),
-      stdout: z.string().optional(),
-      stderr: z.string().optional(),
-      exitCode: z.number().optional(),
-      timedOut: z.boolean().optional(),
-    }),
+    requestBody: HostBashResultBodySchema,
     responseBody: z.object({
       accepted: z.boolean(),
     }),

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

@@ -271,12 +271,15 @@ async function handleHostBrowserResult({ body, headers }: RouteHandlerArgs) {
     headers as Record<string, string | undefined> | undefined,
   );
   if (!resolution.ok) {
-    if (resolution.code === "FORBIDDEN")
+    if (resolution.code === "FORBIDDEN") {
       throw new ForbiddenError(resolution.message);
-    if (resolution.code === "NOT_FOUND")
+    }
+    if (resolution.code === "NOT_FOUND") {
       throw new NotFoundError(resolution.message);
-    if (resolution.code === "CONFLICT")
+    }
+    if (resolution.code === "CONFLICT") {
       throw new ConflictError(resolution.message);
+    }
     throw new BadRequestError(resolution.message);
   }