@vellumai/assistant 0.8.7 → 0.8.8

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

@@ -243,6 +243,10 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Export a document as PDF",
     description: "Render a document to PDF and return the binary content.",
     tags: ["documents"],
+    responseBody: {
+      contentType: "application/pdf",
+      schema: { type: "string", format: "binary" },
+    },
     handler: async ({ pathParams }) => {
       const doc = getDocumentById(pathParams!.id);
       if (!doc) {

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

@@ -5,6 +5,8 @@
  * the subdomain to local config so getAssistantDomain() can use it.
  */
 
+import { z } from "zod";
+
 import { getApexDomain } from "../../config/env.js";
 import {
   loadRawConfig,
@@ -19,18 +21,36 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("domain-routes");
 
-// ── Helpers ───────────────────────────────────────────────────────────
+// ── Schemas ───────────────────────────────────────────────────────────
 
-interface DomainListResponse {
-  next?: string | null;
-  results: {
-    id: string;
-    subdomain?: string;
-    domain?: string;
-    created_at?: string;
-    created?: string;
-  }[];
-}
+const DomainEntrySchema = z.object({
+  id: z.string(),
+  subdomain: z.string().optional(),
+  domain: z.string().optional(),
+  created_at: z.string().optional(),
+  created: z.string().optional(),
+});
+
+const DomainListResponseSchema = z.object({
+  count: z.number(),
+  next: z.string().nullable().optional(),
+  previous: z.string().nullable().optional(),
+  results: z.array(DomainEntrySchema),
+});
+type DomainListResponse = z.infer<typeof DomainListResponseSchema>;
+
+const DomainRegisterResponseSchema = DomainEntrySchema.extend({
+  email_error: z.object({ detail: z.string(), code: z.string() }).optional(),
+});
+type DomainRegisterResponse = z.infer<typeof DomainRegisterResponseSchema>;
+
+const DomainVerificationStatusResponseSchema = z.object({
+  domain: z.string(),
+  status: z.string(),
+  message: z.string(),
+});
+
+// ── Helpers ───────────────────────────────────────────────────────────
 
 async function requireClient(): Promise<VellumPlatformClient> {
   const client = await VellumPlatformClient.create();
@@ -113,20 +133,11 @@ async function handleDomainRegister({ body = {} }: RouteHandlerArgs) {
     throw new BadRequestError(String(detail));
   }
 
-  const data = (await response.json()) as {
-    id: string;
-    subdomain?: string;
-    domain?: string;
-    created_at?: string;
-    created?: string;
-    email_error?: { detail: string; code: string };
-  };
+  const data = (await response.json()) as DomainRegisterResponse;
 
   // Persist the subdomain to config so getAssistantDomain() can use it
   const registeredSubdomain =
-    data.subdomain ??
-    data.domain?.replace(`.${apexDomain}`, "") ??
-    subdomain;
+    data.subdomain ?? data.domain?.replace(`.${apexDomain}`, "") ?? subdomain;
   if (registeredSubdomain) {
     const raw = loadRawConfig();
     setNestedValue(raw, "platform.subdomain", registeredSubdomain);
@@ -146,12 +157,11 @@ async function handleDomainStatus(_args: RouteHandlerArgs) {
   // Sync subdomain to config if not already cached
   if (domains.length > 0) {
     const first = domains[0];
-    const sub =
-      first.subdomain ?? first.domain?.replace(`.${apexDomain}`, "");
+    const sub = first.subdomain ?? first.domain?.replace(`.${apexDomain}`, "");
     if (sub) {
       const raw = loadRawConfig();
-      const existing = (raw as Record<string, Record<string, unknown>>)
-        .platform?.subdomain;
+      const existing = (raw as Record<string, Record<string, unknown>>).platform
+        ?.subdomain;
       if (existing !== sub) {
         setNestedValue(raw, "platform.subdomain", sub);
         saveRawConfig(raw);
@@ -162,9 +172,7 @@ async function handleDomainStatus(_args: RouteHandlerArgs) {
   return data;
 }
 
-async function handleDomainVerificationStatus({
-  body = {},
-}: RouteHandlerArgs) {
+async function handleDomainVerificationStatus({ body = {} }: RouteHandlerArgs) {
   const { domain_id } = body as { domain_id?: string };
   if (!domain_id) {
     throw new BadRequestError("domain_id is required");
@@ -179,9 +187,7 @@ async function handleDomainVerificationStatus({
     );
   }
   if (!results?.some((d) => d.id === domain_id)) {
-    throw new BadRequestError(
-      "domain_id is not registered for this assistant",
-    );
+    throw new BadRequestError("domain_id is not registered for this assistant");
   }
 
   const response = await client.fetch(
@@ -201,11 +207,9 @@ async function handleDomainVerificationStatus({
     );
   }
 
-  return (await response.json()) as {
-    domain: string;
-    status: string;
-    message: string;
-  };
+  return (await response.json()) as z.infer<
+    typeof DomainVerificationStatusResponseSchema
+  >;
 }
 
 // ── Route definitions ─────────────────────────────────────────────────
@@ -222,6 +226,11 @@ export const ROUTES: RouteDefinition[] = [
     handler: handleDomainRegister,
     summary: "Register a subdomain for this assistant",
     tags: ["domain"],
+    requestBody: z.object({
+      subdomain: z.string().optional(),
+      email_username: z.string().optional(),
+    }),
+    responseBody: DomainRegisterResponseSchema,
   },
   {
     operationId: "domain_status",
@@ -234,6 +243,7 @@ export const ROUTES: RouteDefinition[] = [
     handler: handleDomainStatus,
     summary: "Show domain registration and health",
     tags: ["domain"],
+    responseBody: DomainListResponseSchema,
   },
   {
     operationId: "domain_verification_status",
@@ -246,5 +256,9 @@ export const ROUTES: RouteDefinition[] = [
     handler: handleDomainVerificationStatus,
     summary: "Get live DNS verification status for a domain",
     tags: ["domain"],
+    requestBody: z.object({
+      domain_id: z.string(),
+    }),
+    responseBody: DomainVerificationStatusResponseSchema,
   },
 ];

package/src/runtime/routes/epoch-millis-range.ts

@@ -0,0 +1,34 @@
+import { BadRequestError } from "./errors.js";
+
+export interface EpochMillisRange {
+  from: number;
+  to: number;
+}
+
+export function parseEpochMillisRange(
+  queryParams: Record<string, string>,
+): EpochMillisRange {
+  const fromRaw = queryParams.from;
+  const toRaw = queryParams.to;
+
+  if (!fromRaw || !toRaw) {
+    throw new BadRequestError(
+      'Missing required query parameters: "from" and "to" (epoch milliseconds)',
+    );
+  }
+
+  const from = Number(fromRaw);
+  const to = Number(toRaw);
+
+  if (!Number.isFinite(from) || !Number.isFinite(to)) {
+    throw new BadRequestError(
+      '"from" and "to" must be valid numbers (epoch milliseconds)',
+    );
+  }
+
+  if (from > to) {
+    throw new BadRequestError('"from" must be less than or equal to "to"');
+  }
+
+  return { from, to };
+}

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

@@ -39,9 +39,9 @@ import {
   AssistantEventHub,
   assistantEventHub,
 } from "../assistant-event-hub.js";
+import type { ReplaySubscriber } from "../assistant-stream-state.js";
+import { getReplayWindow } from "../assistant-stream-state.js";
 import { ACTOR_PRINCIPALS, GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
-import type { ReplaySubscriber } from "../conversation-stream-state.js";
-import { getReplayWindow } from "../conversation-stream-state.js";
 import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import {
   BadRequestError,
@@ -143,6 +143,12 @@ export interface SseSubscriberInstrumentation {
   clientId: string | null;
   interfaceId: string | null;
   conversationKey: string | null;
+  /**
+   * Per-connection id assigned by the hub. Distinguishes connections
+   * sharing a `clientId` (old vs reconnected) so a shed can be attributed
+   * to a specific connection. `null` until the hub subscription is created.
+   */
+  connectionId: string | null;
 }
 
 export type SseShedReason = "callback_backpressure" | "heartbeat_backpressure";
@@ -177,6 +183,7 @@ export function buildSseShedSentryContext(
     heartbeats_sent: inst.heartbeatsSent,
     client_id: inst.clientId,
     interface_id: inst.interfaceId,
+    connection_id: inst.connectionId,
     event_loop_delay_mean_ms: elDelay.mean_ms,
     event_loop_delay_p99_ms: elDelay.p99_ms,
     event_loop_delay_max_ms: elDelay.max_ms,
@@ -216,6 +223,7 @@ const defaultSseShedReporter: SseShedReporter = (reason, inst) => {
       scope.setTag("sse_shed_reason", reason);
       if (inst.clientId) scope.setTag("client_id", inst.clientId);
       if (inst.interfaceId) scope.setTag("interface_id", inst.interfaceId);
+      if (inst.connectionId) scope.setTag("connection_id", inst.connectionId);
       scope.setContext("sse_shed", sentryContext);
       Sentry.captureMessage(`sse_subscriber_shed:${reason}`);
     });
@@ -371,6 +379,7 @@ export function handleSubscribeAssistantEvents(
     clientId,
     interfaceId,
     conversationKey: scopeConversationKey,
+    connectionId: null,
   };
 
   ensureEventLoopDelayMonitorStarted();
@@ -394,19 +403,6 @@ export function handleSubscribeAssistantEvents(
   // replay window we just drained.
   let highWaterReplaySeq = -1;
 
-  // Per-conversation subscriber-filtered sequence counters. Incremented
-  // for each conversation-scoped event this specific subscriber receives
-  // (after capability/client/interface targeting), producing a gap-free
-  // sequence from the subscriber's perspective. Clients use `clientSeq`
-  // for gap detection instead of the global `seq` to avoid false
-  // positives from targeted events they never receive.
-  const clientSeqCounters = new Map<string, number>();
-  function nextClientSeqFor(conversationId: string): number {
-    const next = (clientSeqCounters.get(conversationId) ?? 0) + 1;
-    clientSeqCounters.set(conversationId, next);
-    return next;
-  }
-
   const callback: AssistantEventCallback = (event) => {
     const controller = controllerRef;
     if (!controller) return;
@@ -425,11 +421,7 @@ export function handleSubscribeAssistantEvents(
         cleanup();
         return;
       }
-      const frame =
-        event.conversationId != null && event.seq != null
-          ? { ...event, clientSeq: nextClientSeqFor(event.conversationId) }
-          : event;
-      controller.enqueue(encoder.encode(formatSseFrame(frame)));
+      controller.enqueue(encoder.encode(formatSseFrame(event)));
       instrumentation.eventsDelivered += 1;
     } catch {
       sub.dispose();
@@ -461,6 +453,9 @@ export function handleSubscribeAssistantEvents(
             ...subscriberBase,
             type: "process" as const,
           });
+    // Stamp the hub-assigned connection id so a later backpressure shed can be
+    // tied back to this specific connection in logs and Sentry.
+    instrumentation.connectionId = sub.connectionId;
   } catch (err) {
     if (err instanceof RangeError) {
       throw new ServiceUnavailableError("Too many concurrent connections");
@@ -479,16 +474,22 @@ export function handleSubscribeAssistantEvents(
           return;
         }
 
-        // Reconnect replay: when the caller passed lastSeenSeq and the
-        // subscription is scoped to a single conversation, deliver any
-        // buffered events the client missed before the first heartbeat.
+        // Reconnect replay: when the caller passed lastSeenSeq, deliver
+        // any buffered events the client missed before the first
+        // heartbeat. `seq` is a single global per-assistant counter, so
+        // one cursor resumes the stream regardless of how many
+        // conversations are multiplexed on an unfiltered connection.
+        // Replay re-applies the subscriber's targeting filter; a
+        // conversation-scoped subscription additionally scopes replay to
+        // its own conversation (other conversations are never delivered
+        // live on that connection, so replaying them would be wrong).
         //
         // If the cursor is older than the ring's oldest entry,
         // `getReplayWindow` returns `null`. We do not surface that to
         // the client over the wire -- the connection just goes live.
         // The client detects the gap from the seq jump on its first
         // live event and refetches via the existing messages API.
-        if (lastSeenSeq != null && filter.conversationId) {
+        if (lastSeenSeq != null) {
           const replaySubscriber: ReplaySubscriber =
             clientId && interfaceId
               ? {
@@ -501,20 +502,13 @@ export function handleSubscribeAssistantEvents(
                 }
               : { type: "process" };
           const window = getReplayWindow(
-            filter.conversationId,
             lastSeenSeq,
             replaySubscriber,
+            filter.conversationId,
           );
           if (window !== null) {
             for (const replayed of window) {
-              const frame =
-                replayed.conversationId != null && replayed.seq != null
-                  ? {
-                      ...replayed,
-                      clientSeq: nextClientSeqFor(replayed.conversationId),
-                    }
-                  : replayed;
-              controller.enqueue(encoder.encode(formatSseFrame(frame)));
+              controller.enqueue(encoder.encode(formatSseFrame(replayed)));
               instrumentation.eventsDelivered += 1;
               if (replayed.seq != null && replayed.seq > highWaterReplaySeq) {
                 highWaterReplaySeq = replayed.seq;
@@ -621,7 +615,7 @@ export const ROUTES: RouteDefinition[] = [
       {
         name: "lastSeenSeq",
         description:
-          "Optional reconnect cursor: the highest per-conversation event seq the client has already applied. When set together with a conversation scope, the daemon replays any buffered events with seq > lastSeenSeq before going live. If the cursor is older than the ring buffer's oldest entry the connection simply goes live; the client is expected to detect the gap from the next event's seq and refetch via the messages API. Must be a non-negative integer.",
+          "Optional reconnect cursor: the highest global event seq the client has already applied. `seq` is a single per-assistant counter shared across all conversations, so one cursor resumes the stream regardless of how many conversations are multiplexed on the connection. When set, the daemon replays any buffered events with seq > lastSeenSeq (re-applying the subscriber's targeting/scope filter) before going live. If the cursor is older than the ring buffer's oldest entry the connection simply goes live; the client is expected to detect the gap from the next event's seq and refetch via the messages API. Must be a non-negative integer.",
       },
     ],
     responseHeaders: {

package/src/runtime/routes/gateway-log-routes.ts

@@ -35,7 +35,14 @@ async function gatewayFetch(
 
 // ── Schemas ─────────────────────────────────────────────────────────────
 
-const LEVEL_NAMES = ["trace", "debug", "info", "warn", "error", "fatal"] as const;
+const LEVEL_NAMES = [
+  "trace",
+  "debug",
+  "info",
+  "warn",
+  "error",
+  "fatal",
+] as const;
 
 const GatewayLogsTailParams = z
   .object({
@@ -45,9 +52,18 @@ const GatewayLogsTailParams = z
   })
   .strict();
 
+const GatewayLogsTailResponseSchema = z.object({
+  lines: z.array(z.record(z.string(), z.unknown())),
+  truncated: z.boolean(),
+});
+type GatewayLogsTailResponse = z.infer<typeof GatewayLogsTailResponseSchema>;
+
 // ── Handlers ────────────────────────────────────────────────────────────
 
-async function handleGatewayLogsTail({ queryParams = {}, body = {} }: RouteHandlerArgs) {
+async function handleGatewayLogsTail({
+  queryParams = {},
+  body = {},
+}: RouteHandlerArgs): Promise<GatewayLogsTailResponse> {
   // HTTP GET delivers filters via queryParams; CLI IPC puts them in body.
   const source = Object.keys(queryParams).length > 0 ? queryParams : body;
   const p = GatewayLogsTailParams.parse(source);
@@ -56,7 +72,9 @@ async function handleGatewayLogsTail({ queryParams = {}, body = {} }: RouteHandl
   if (p.level !== undefined) qs.set("level", p.level);
   if (p.module !== undefined) qs.set("module", p.module);
   const query = qs.toString();
-  return gatewayFetch(`/v1/logs/tail${query ? `?${query}` : ""}`);
+  return gatewayFetch(
+    `/v1/logs/tail${query ? `?${query}` : ""}`,
+  ) as Promise<GatewayLogsTailResponse>;
 }
 
 // ── Route definitions ───────────────────────────────────────────────────
@@ -75,8 +93,12 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Return the last N structured log entries from the gateway log files.",
     tags: ["gateway-logs"],
+    responseBody: GatewayLogsTailResponseSchema,
     queryParams: [
-      { name: "n", description: "Number of lines to return (1–1000, default: 10)" },
+      {
+        name: "n",
+        description: "Number of lines to return (1–1000, default: 10)",
+      },
       { name: "level", description: "Minimum pino level name (default: info)" },
       { name: "module", description: "Filter to exact pino module name" },
     ],

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

@@ -18,6 +18,8 @@ import {
 } from "../../config/loader.js";
 import { listHeartbeatRuns } from "../../heartbeat/heartbeat-run-store.js";
 import { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
+import { getConversation } from "../../memory/conversation-crud.js";
+import { getUsageCostForConversationWindow } from "../../memory/llm-usage-store.js";
 import { readTextFileSync } from "../../util/fs.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
@@ -38,19 +40,34 @@ function handleListRuns(queryParams: Record<string, string>) {
     : 20;
 
   const runs = listHeartbeatRuns(limit);
+  const now = Date.now();
   return {
-    runs: runs.map((r) => ({
-      id: r.id,
-      scheduledFor: r.scheduledFor,
-      startedAt: r.startedAt,
-      finishedAt: r.finishedAt,
-      durationMs: r.durationMs,
-      status: r.status,
-      skipReason: r.skipReason,
-      error: r.error,
-      conversationId: r.conversationId,
-      createdAt: r.createdAt,
-    })),
+    runs: runs.map((r) => {
+      const conversation = r.conversationId
+        ? getConversation(r.conversationId)
+        : null;
+      return {
+        id: r.id,
+        scheduledFor: r.scheduledFor,
+        startedAt: r.startedAt,
+        finishedAt: r.finishedAt,
+        durationMs: r.durationMs,
+        status: r.status,
+        skipReason: r.skipReason,
+        error: r.error,
+        conversationId: r.conversationId,
+        conversationExists: conversation != null,
+        conversationArchivedAt: conversation?.archivedAt ?? null,
+        estimatedCostUsd: r.conversationId
+          ? getUsageCostForConversationWindow({
+              conversationId: r.conversationId,
+              from: r.startedAt ?? r.scheduledFor,
+              to: r.finishedAt ?? now,
+            })
+          : 0,
+        createdAt: r.createdAt,
+      };
+    }),
   };
 }
 
@@ -116,6 +133,9 @@ export const ROUTES: RouteDefinition[] = [
             skipReason: z.string().nullable(),
             error: z.string().nullable(),
             conversationId: z.string().nullable(),
+            conversationExists: z.boolean(),
+            conversationArchivedAt: z.number().nullable(),
+            estimatedCostUsd: z.number(),
             createdAt: z.number(),
           }),
         )

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

@@ -3,38 +3,33 @@
  *
  * Greetings are sourced from (in priority order):
  * 1. A `## Greetings` section in SOUL.md (user-defined bullet list)
- * 2. A cached greetings array (populated by the BTW side-chain LLM call)
- * 3. Fallback: the assistant name from IDENTITY.md
+ * 2. A cached greetings array (populated by the empty-state greeting callsite)
+ * 3. A generic fallback when generation is unavailable
  *
- * Cache uses TTL + content-hash invalidation: when IDENTITY.md, SOUL.md, or
- * the guardian persona change, the cache is busted.
+ * Cache invalidation is intentionally TTL-only. User-authored SOUL.md
+ * greetings are read before cache, so manual overrides still take priority
+ * without coupling cache validity to prompt-file edits.
  *
  * Storage uses the existing `memory_checkpoints` table (simple key-value store).
  */
 
-import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 
 import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
 } from "../../memory/checkpoints.js";
-import { resolveGuardianPersona } from "../../prompts/persona-resolver.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+const CACHE_TTL_MS = 2 * 24 * 60 * 60 * 1000; // 2 days
 
 const CHECKPOINT_KEY_GREETINGS = "identity:intro:greetings";
-const CHECKPOINT_KEY_HASH = "identity:intro:content_hash";
 const CHECKPOINT_KEY_TIMESTAMP = "identity:intro:cached_at";
 
-/** Workspace files whose content influences the identity intro. */
-const IDENTITY_FILES = ["IDENTITY.md", "SOUL.md"] as const;
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -125,14 +120,6 @@ export function readWorkspaceGreetings(): string[] | null {
   return parseGreetingsSection(soulContent);
 }
 
-/** Compute a SHA-256 hex hash of the concatenated identity file contents. */
-export function computeIdentityContentHash(): string {
-  const staticFiles = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
-  const guardianPersona = resolveGuardianPersona() ?? "";
-  const combined = staticFiles + "\n---\n" + guardianPersona;
-  return createHash("sha256").update(combined).digest("hex");
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -142,27 +129,22 @@ export interface CachedIntro {
 }
 
 /**
- * Retrieve the cached greetings array if it exists, is within the TTL window,
- * and the identity files have not changed since it was generated.
+ * Retrieve the cached greetings array if it exists and is within the TTL
+ * window.
  *
- * Returns `null` when the cache is missing, expired, or invalidated.
+ * Returns `null` when the cache is missing or expired.
  */
 export function getCachedIntro(): CachedIntro | null {
   try {
     const raw = getMemoryCheckpoint(CHECKPOINT_KEY_GREETINGS);
-    const hash = getMemoryCheckpoint(CHECKPOINT_KEY_HASH);
     const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
 
-    if (!raw || !hash || !timestampStr) return null;
+    if (!raw || !timestampStr) return null;
 
     // TTL check
     const cachedAt = Number(timestampStr);
     if (isNaN(cachedAt) || Date.now() - cachedAt > CACHE_TTL_MS) return null;
 
-    // Content-hash check — bust cache when identity files change
-    const currentHash = computeIdentityContentHash();
-    if (currentHash !== hash) return null;
-
     // Parse stored value — handles both JSON array and legacy single string
     let greetings: string[];
     try {
@@ -178,16 +160,11 @@ export function getCachedIntro(): CachedIntro | null {
   }
 }
 
-/**
- * Store a greetings array in the cache along with the current content hash
- * and timestamp.
- */
+/** Store a greetings array in the cache along with the current timestamp. */
 export function setCachedIntro(greetings: string[]): void {
   try {
-    const hash = computeIdentityContentHash();
     const now = String(Date.now());
     setMemoryCheckpoint(CHECKPOINT_KEY_GREETINGS, JSON.stringify(greetings));
-    setMemoryCheckpoint(CHECKPOINT_KEY_HASH, hash);
     setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, now);
   } catch {
     // Cache write failure is non-fatal — next request will regenerate.