@vellumai/assistant 0.8.5 → 0.8.6

package/src/runtime/routes/background-wake-routes.ts

@@ -1,14 +1,41 @@
 import { z } from "zod";
 
-import { computeNextBackgroundWakeIntent } from "../../background-wake/next-wake.js";
+import {
+  type BackgroundWakeIntent,
+  computeNextBackgroundWakeIntent,
+} from "../../background-wake/next-wake.js";
+import type { BackgroundWakeRuntime } from "../../background-wake/runtime-registry.js";
 import { getBackgroundWakeRuntime } from "../../background-wake/runtime-registry.js";
+import { getLogger } from "../../util/logger.js";
 import { BadRequestError, ServiceUnavailableError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const PREPARE_SLEEP_DEFER_WINDOW_MS = 60_000;
 const HEARTBEAT_DUE_TOLERANCE_MS = 1_000;
+const MIN_DRAIN_START_BUDGET_MS = 5_000;
+const LEASE_RENEW_INTERVAL_MS = 120_000;
+const log = getLogger("background-wake-routes");
+
+class DrainDeadlineElapsedError extends Error {
+  constructor() {
+    super("background wake lease deadline elapsed before starting work");
+    this.name = "DrainDeadlineElapsedError";
+  }
+}
+
+type RenewWakeLease = (leaseId: string) => Promise<unknown>;
+type CompleteWakeLease = (args: {
+  leaseId: string;
+  status: "completed" | "failed" | "expired";
+  error?: string;
+  nextIntent?: BackgroundWakeIntent | null;
+}) => Promise<unknown>;
 
 let computeWakeIntent = computeNextBackgroundWakeIntent;
+let renewWakeLease: RenewWakeLease = defaultRenewWakeLease;
+let completeWakeLease: CompleteWakeLease = defaultCompleteWakeLease;
+const activeDrainLeases = new Set<string>();
+const activeDrainPromises = new Set<Promise<void>>();
 const timestampInputSchema = z.union([z.number(), z.string()]);
 
 const wakeIntentSchema = z
@@ -66,7 +93,8 @@ function normalizeTimestamp(value: unknown): unknown {
   return Number.isFinite(parsed) ? parsed : value;
 }
 
-function parseDrainDueBody(body: Record<string, unknown>) {
+type DrainDueRequest = z.infer<typeof normalizedDrainDueRequestSchema>;
+function parseDrainDueBody(body: Record<string, unknown>): DrainDueRequest {
   const parsed = normalizedDrainDueRequestSchema.safeParse(
     normalizeDrainDueBody(body),
   );
@@ -78,6 +106,20 @@ function parseDrainDueBody(body: Record<string, unknown>) {
   return parsed.data;
 }
 
+async function defaultRenewWakeLease(leaseId: string): Promise<unknown> {
+  const { renewBackgroundWakeLease } =
+    await import("../../background-wake/platform-client.js");
+  return renewBackgroundWakeLease(leaseId);
+}
+
+async function defaultCompleteWakeLease(
+  args: Parameters<CompleteWakeLease>[0],
+): Promise<unknown> {
+  const { completeBackgroundWakeLease } =
+    await import("../../background-wake/platform-client.js");
+  return completeBackgroundWakeLease(args);
+}
+
 function handleGetIntent() {
   return { intent: computeWakeIntent() };
 }
@@ -102,28 +144,141 @@ async function handleDrainDue(body: Record<string, unknown>) {
     );
   }
 
-  const now = Date.now();
-  const heartbeatDue =
-    runtime.heartbeat.nextRunAt != null &&
-    runtime.heartbeat.nextRunAt <= now + HEARTBEAT_DUE_TOLERANCE_MS;
-  const heartbeatRan = heartbeatDue ? await runtime.heartbeat.runOnce() : false;
-  const scheduledCount = await runtime.scheduler.runOnce();
+  if (!activeDrainLeases.has(request.leaseId)) {
+    activeDrainLeases.add(request.leaseId);
+    const drainPromise = runDrainDueLease(request, runtime);
+    activeDrainPromises.add(drainPromise);
+    void drainPromise.finally(() => activeDrainPromises.delete(drainPromise));
+  }
 
   return {
+    accepted: true,
     leaseId: request.leaseId,
     reason: request.reason,
     sourceGeneration: request.sourceGeneration,
     startedAt: request.startedAt,
     deadlineAt: request.deadlineAt,
-    counts: {
-      heartbeat: heartbeatRan ? 1 : 0,
-      scheduler: scheduledCount,
-      total: (heartbeatRan ? 1 : 0) + scheduledCount,
-    },
-    nextIntent: computeWakeIntent(),
   };
 }
 
+async function runDrainDueLease(
+  request: DrainDueRequest,
+  runtime: BackgroundWakeRuntime,
+): Promise<void> {
+  let renewTimer: ReturnType<typeof setInterval> | undefined;
+  try {
+    renewTimer = setInterval(() => {
+      void renewWakeLease(request.leaseId).catch(() => {});
+    }, LEASE_RENEW_INTERVAL_MS);
+    renewTimer.unref?.();
+
+    assertDrainCanStart(request.deadlineAt);
+    const result = await performDrainDue(request, runtime);
+    await reportLeaseCompletion({
+      leaseId: request.leaseId,
+      status: "completed",
+      nextIntent: result.nextIntent,
+    });
+  } catch (error) {
+    await reportLeaseCompletion({
+      leaseId: request.leaseId,
+      status: completionStatusForError(error),
+      error: error instanceof Error ? error.message : String(error),
+      nextIntent: computeWakeIntent(),
+    });
+  } finally {
+    if (renewTimer) clearInterval(renewTimer);
+    activeDrainLeases.delete(request.leaseId);
+  }
+}
+
+async function reportLeaseCompletion(
+  args: Parameters<CompleteWakeLease>[0],
+): Promise<void> {
+  try {
+    await completeWakeLease(args);
+  } catch (err) {
+    log.warn(
+      { err, leaseId: args.leaseId, status: args.status },
+      "Failed to report background wake lease completion",
+    );
+  }
+}
+
+async function performDrainDue(
+  request: DrainDueRequest,
+  runtime: BackgroundWakeRuntime,
+) {
+  const now = Date.now();
+  const currentIntent = computeWakeIntent(now);
+  const heartbeatDue = isHeartbeatTimerDue(runtime.heartbeat.nextRunAt, now);
+  const schedulerDue =
+    heartbeatDue ||
+    reasonIncludesSource(request.reason, "schedule") ||
+    intentHasDueSource(currentIntent, "schedule", now);
+
+  if (heartbeatDue) {
+    if (hasStartBudget(request.deadlineAt)) {
+      await runtime.heartbeat.runManagedWakeIfDue({
+        now,
+        toleranceMs: HEARTBEAT_DUE_TOLERANCE_MS,
+        scheduledFor: request.startedAt,
+      });
+    }
+  }
+
+  if (schedulerDue) {
+    await runtime.scheduler.runDueWorkOnce({
+      deadlineAt: request.deadlineAt,
+      minStartBudgetMs: MIN_DRAIN_START_BUDGET_MS,
+      includeStillPending: true,
+    });
+  }
+
+  const nextIntent = computeWakeIntent();
+
+  return {
+    nextIntent,
+  };
+}
+
+function assertDrainCanStart(deadlineAt: number): void {
+  if (deadlineAt <= Date.now()) {
+    throw new DrainDeadlineElapsedError();
+  }
+}
+
+function completionStatusForError(error: unknown): "failed" | "expired" {
+  return error instanceof DrainDeadlineElapsedError ? "expired" : "failed";
+}
+
+function reasonIncludesSource(
+  reason: string,
+  source: "heartbeat" | "schedule",
+): boolean {
+  return reason === "mixed" || reason === source;
+}
+
+function isHeartbeatTimerDue(nextRunAt: number | null, now: number): boolean {
+  return nextRunAt != null && nextRunAt <= now + HEARTBEAT_DUE_TOLERANCE_MS;
+}
+
+function intentHasDueSource(
+  intent: BackgroundWakeIntent | null,
+  source: "heartbeat" | "schedule",
+  now: number,
+): boolean {
+  return (
+    intent != null &&
+    intent.actualNextDueAt <= now + HEARTBEAT_DUE_TOLERANCE_MS &&
+    reasonIncludesSource(intent.reason, source)
+  );
+}
+
+function hasStartBudget(deadlineAt: number): boolean {
+  return deadlineAt - Date.now() >= MIN_DRAIN_START_BUDGET_MS;
+}
+
 /** @internal Test helper for route-only tests. */
 export function setBackgroundWakeIntentComputerForTest(
   nextCompute: typeof computeNextBackgroundWakeIntent | null,
@@ -131,6 +286,24 @@ export function setBackgroundWakeIntentComputerForTest(
   computeWakeIntent = nextCompute ?? computeNextBackgroundWakeIntent;
 }
 
+/** @internal Test helper for route-only tests. */
+export function setBackgroundWakeLeaseClientForTest(
+  nextClient: {
+    renew: RenewWakeLease;
+    complete: CompleteWakeLease;
+  } | null,
+): void {
+  renewWakeLease = nextClient?.renew ?? defaultRenewWakeLease;
+  completeWakeLease = nextClient?.complete ?? defaultCompleteWakeLease;
+}
+
+/** @internal Test helper for route-only tests. */
+export async function flushBackgroundWakeDrainsForTest(): Promise<void> {
+  while (activeDrainPromises.size > 0) {
+    await Promise.allSettled([...activeDrainPromises]);
+  }
+}
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "getBackgroundWakeIntent",
@@ -171,17 +344,12 @@ export const ROUTES: RouteDefinition[] = [
     tags: ["background-wake"],
     requestBody: drainDueRequestSchema,
     responseBody: z.object({
+      accepted: z.boolean(),
       leaseId: z.string(),
       reason: z.string(),
       sourceGeneration: z.string(),
       startedAt: z.number(),
       deadlineAt: z.number(),
-      counts: z.object({
-        heartbeat: z.number(),
-        scheduler: z.number(),
-        total: z.number(),
-      }),
-      nextIntent: wakeIntentSchema,
     }),
     handler: ({ body }: RouteHandlerArgs) => handleDrainDue(body ?? {}),
   },

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

@@ -19,9 +19,9 @@ import { z } from "zod";
 import { getConfig } from "../../config/loader.js";
 import { readNowScratchpad } from "../../daemon/conversation-runtime-assembly.js";
 import { getOrCreateConversation } from "../../daemon/conversation-store.js";
-import { buildToolDefinitions } from "../../daemon/conversation-tool-setup.js";
 import { parseIdentityFields } from "../../daemon/handlers/identity.js";
 import { getConversationByKey } from "../../memory/conversation-key-store.js";
+import { getAllToolDefinitions } from "../../tools/registry.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
 import { runBtwSidechain } from "../btw-sidechain.js";
@@ -77,7 +77,7 @@ async function handleBtw({
         fastText = `Hi, I'm ${fields.name}!`;
       }
     }
-    fastText ??= getCachedIntro()?.text;
+    fastText ??= getCachedIntro()?.greetings[0];
     if (fastText) {
       log.debug("Returning identity intro fast-path");
       return new ReadableStream({
@@ -122,7 +122,7 @@ async function handleBtw({
           const result = await runBtwSidechain({
             content: effectiveContent,
             conversation,
-            tools: buildToolDefinitions(),
+            tools: getAllToolDefinitions(),
             signal: abortSignal,
             ...(isGreeting ? { callSite: "emptyStateGreeting" as const } : {}),
             onEvent: (event) => {
@@ -146,7 +146,7 @@ async function handleBtw({
 
           if (isIntroRequest && result.text) {
             try {
-              setCachedIntro(result.text);
+              setCachedIntro([result.text]);
               log.debug("Cached identity intro text");
             } catch {
               // Non-fatal — next request will regenerate.

package/src/runtime/routes/conversation-analysis-routes.ts

@@ -9,8 +9,11 @@
  * errors, and build the success response.
  */
 
+import { z } from "zod";
+
 import { analyzeConversation } from "../services/analyze-conversation.js";
 import { buildConversationDetailResponse } from "../services/conversation-serializer.js";
+import { conversationSummarySchema } from "./conversation-list-routes.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -60,6 +63,9 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Create a new conversation with a structured self-assessment of an existing conversation.",
     tags: ["conversations"],
+    responseBody: z.object({
+      conversation: conversationSummarySchema,
+    }),
     handler: handleAnalyzeConversation,
   },
 ];

package/src/runtime/routes/conversation-compaction-routes.ts

@@ -0,0 +1,263 @@
+/**
+ * Route definitions for the per-conversation **compaction trail** view.
+ *
+ *   GET /v1/conversations/:id/compaction?callId=…
+ *
+ * Reachable via the platform's `RuntimeProxyWildcardView` at
+ * `/v1/assistants/{assistantId}/conversations/{conversationId}/compaction/?callId=…`.
+ *
+ * # Scope
+ *
+ * Returns the set of `call_site = "compactionAgent"` rows in this
+ * conversation that ran in the **window between the previous real LLM
+ * call and the one identified by `callId`**, ordered chronologically.
+ * This is the data the Inspector's "Compaction" tab shows when you
+ * select a call in the rail: it answers "what did the compactor do to
+ * my context before *this specific* call?" — not "what has the
+ * compactor ever done in this conversation".
+ *
+ * The floor is resolved by walking back from the selected call to the
+ * most recent non-`compactionAgent` row in the same conversation. When
+ * the selected call is the *first* real call in the conversation,
+ * there is no floor and every preceding compaction is in scope.
+ *
+ * # Data model decision (in progress)
+ *
+ * Today the trail is projected from `llm_request_logs` rows alone — no
+ * `compaction_logs` table exists yet (#32055 remains a draft). This MVP
+ * route exists precisely to test whether the projected shape is enough.
+ * If real-world use surfaces UX needs that aren't in `llm_request_logs`
+ * (most likely: per-event duration, structured before/after counts,
+ * trigger reason), that becomes the concrete justification for the new
+ * table. Until then, missing fields surface as `null` and the Compaction
+ * tab renders `"Unavailable"` for them.
+ *
+ * In particular, `durationMs` is always `null` for now — the column
+ * doesn't exist on `llm_request_logs` and we deliberately ship the route
+ * without it to surface the gap in the UI.
+ */
+
+import { z } from "zod";
+
+import { getConversation } from "../../memory/conversation-crud.js";
+import { getLlmRequestLogSource } from "../../memory/llm-request-log-source.js";
+import type { LogRow } from "../../memory/llm-request-log-store.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import {
+  type LlmContextSummary,
+  normalizeLlmContextPayloads,
+} from "./llm-context-normalization.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+/**
+ * Wire shape for a single compaction event. Mirrors the React Query
+ * response type at
+ * `apps/web/src/domains/chat/inspector/compaction-trail-types.ts`.
+ * Keep the two in sync — until the OpenAPI client generator picks up
+ * this route, the frontend type is hand-maintained.
+ */
+export interface CompactionTrailEvent {
+  id: string;
+  createdAt: number;
+  model: string | null;
+  provider: string | null;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  /**
+   * Per-call wall-clock latency, in milliseconds. **Always `null` for
+   * now** — `llm_request_logs` doesn't carry a duration column. Surfacing
+   * the gap in the UI is intentional: if engineers consistently miss
+   * having latency here, that's a concrete signal to extend the row
+   * (either as a column on `llm_request_logs` or on a dedicated
+   * `compaction_logs` table per the open data-model decision).
+   */
+  durationMs: number | null;
+  responsePreview: string | null;
+  requestMessageCount: number | null;
+  stopReason: string | null;
+  estimatedCostUsd: number | null;
+}
+
+export interface CompactionTrailResponse {
+  conversationId: string;
+  events: CompactionTrailEvent[];
+}
+
+const compactionTrailEventSchema = z.object({
+  id: z.string(),
+  createdAt: z.number(),
+  model: z.string().nullable(),
+  provider: z.string().nullable(),
+  inputTokens: z.number().nullable(),
+  outputTokens: z.number().nullable(),
+  durationMs: z.number().nullable(),
+  responsePreview: z.string().nullable(),
+  requestMessageCount: z.number().nullable(),
+  stopReason: z.string().nullable(),
+  estimatedCostUsd: z.number().nullable(),
+});
+
+const compactionTrailResponseSchema = z.object({
+  conversationId: z.string(),
+  events: z.array(compactionTrailEventSchema),
+});
+
+// ---------------------------------------------------------------------------
+// Projection — LogRow → CompactionTrailEvent
+// ---------------------------------------------------------------------------
+
+function tryParseJson(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Project a raw `llm_request_logs` row into the compaction-trail wire
+ * shape. Reuses `normalizeLlmContextPayloads` so model/provider/token
+ * extraction stays consistent with what the rest of the inspector shows.
+ *
+ * Fields the normalizer can't derive (today: `durationMs`) land as
+ * `null` — see the `CompactionTrailEvent.durationMs` doc comment for the
+ * rationale.
+ *
+ * Exported only for unit tests; the route handler is the sole production
+ * caller.
+ */
+export function projectLogRowToCompactionTrailEvent(
+  log: LogRow,
+): CompactionTrailEvent {
+  const normalized = normalizeLlmContextPayloads({
+    requestPayload: tryParseJson(log.requestPayload),
+    responsePayload: tryParseJson(log.responsePayload),
+    createdAt: log.createdAt,
+  });
+  const summary: LlmContextSummary | undefined = normalized.summary;
+  return {
+    id: log.id,
+    createdAt: log.createdAt,
+    model: summary?.model ?? null,
+    // Prefer the normalized provider (derived from payload shape) over
+    // the stored column. Stored `provider` is the originating call's
+    // own identifier and matches the normalizer in all cases we ship
+    // today, but the normalizer is the source-of-truth used by sibling
+    // inspector tabs — keep that alignment.
+    provider: summary?.provider ?? log.provider ?? null,
+    inputTokens: summary?.inputTokens ?? null,
+    outputTokens: summary?.outputTokens ?? null,
+    durationMs: null,
+    responsePreview: summary?.responsePreview ?? null,
+    requestMessageCount: summary?.requestMessageCount ?? null,
+    stopReason: summary?.stopReason ?? null,
+    estimatedCostUsd: summary?.estimatedCostUsd ?? null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+async function handleGetCompactionTrail({
+  pathParams = {},
+  queryParams = {},
+}: RouteHandlerArgs): Promise<CompactionTrailResponse> {
+  const conversationId = pathParams.id;
+  const callId = queryParams.callId;
+
+  if (!conversationId) {
+    throw new BadRequestError("conversation id path parameter is required");
+  }
+  if (!callId) {
+    throw new BadRequestError("callId query parameter is required");
+  }
+
+  // Verify the conversation exists before we touch the log source —
+  // a missing conversation should 404, not return an empty trail with
+  // no signal that the caller had the wrong id.
+  const conversation = getConversation(conversationId);
+  if (!conversation) {
+    throw new NotFoundError(`Conversation ${conversationId} not found`);
+  }
+
+  const source = await getLlmRequestLogSource();
+  const selectedCall = await source.getRequestLogById(callId);
+  if (!selectedCall) {
+    throw new NotFoundError(`LLM call ${callId} not found`);
+  }
+  if (selectedCall.conversationId !== conversationId) {
+    // Treat a cross-conversation callId as a bad request rather than
+    // silently filtering against the wrong conversation. The frontend
+    // always pairs (conversationId, callId) from the same rail, so a
+    // mismatch is a real client bug — surface it.
+    throw new BadRequestError(
+      `LLM call ${callId} does not belong to conversation ${conversationId}`,
+    );
+  }
+
+  // Resolve the window floor — the most recent non-`compactionAgent`
+  // call before the selected one. `null` means the selected call is the
+  // first real call in the conversation, so every preceding compaction
+  // is in scope. The store function applies the strict-`>` predicate
+  // (or drops it entirely on null), so the selected call's own
+  // `createdAt` is the only ceiling we pass.
+  const afterCreatedAt = await source.getPreviousNonCompactionCallCreatedAt(
+    conversationId,
+    selectedCall.createdAt,
+  );
+  const logs = await source.getCompactionLogsBetween(
+    conversationId,
+    afterCreatedAt,
+    selectedCall.createdAt,
+  );
+
+  return {
+    conversationId,
+    events: logs.map(projectLogRowToCompactionTrailEvent),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "conversations_compaction_trail_get",
+    endpoint: "conversations/:id/compaction",
+    method: "GET",
+    policyKey: "conversations/compaction",
+    summary: "Get the compaction trail leading up to an LLM call",
+    description:
+      "Return the chronological list of compaction events that ran in this conversation in the open window between the previous non-`compactionAgent` LLM call and the call identified by `callId`. Projected from `llm_request_logs` rows where `call_site = \"compactionAgent\"`. When the selected call is the first real call in the conversation, every preceding compaction is in scope. Drives the Inspector's Compaction tab.",
+    tags: ["conversations"],
+    pathParams: [
+      {
+        name: "id",
+        description: "Internal conversation identifier.",
+      },
+    ],
+    queryParams: [
+      {
+        name: "callId",
+        required: true,
+        schema: { type: "string" },
+        description:
+          "ID of the selected LLM call from the rail. Defines the chronological cutoff for the trail.",
+      },
+    ],
+    responseBody: compactionTrailResponseSchema,
+    additionalResponses: {
+      "400": {
+        description:
+          "Returned when the callId is missing or refers to a call in a different conversation.",
+      },
+      "404": {
+        description:
+          "Returned when the conversation or the referenced LLM call does not exist.",
+      },
+    },
+    handler: handleGetCompactionTrail,
+  },
+];