@vellumai/assistant 0.8.5 → 0.8.7

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

@@ -0,0 +1,292 @@
+/**
+ * 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 every `call_site = "compactionAgent"` row that ran in the
+ * **same agent turn** as the call 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 across this whole turn?" — regardless of where the
+ * selected call sits within the turn.
+ *
+ * Turn bounds are resolved by `getTurnTimeBounds` in
+ * `memory/conversation-crud.ts`, which walks the `messages` table to
+ * find the real user message that started the turn and the next real
+ * user message (or end-of-conversation) that ends it. Tool-result user
+ * messages are not turn boundaries. When the conversation has no other
+ * messages around the selected call, the window collapses to the
+ * call's own `createdAt` and every compaction strictly before it is
+ * returned — same as the legacy behavior.
+ *
+ * # Why turn-scoped, not call-scoped
+ *
+ * A single turn can run dozens of compactions (mid-loop proactive,
+ * convergence-reducer, and emergency cycles all flow through the same
+ * `compactionAgent` call site). Constraining the trail to the window
+ * between two adjacent calls hides most of that activity from the UI
+ * — especially for the call that *yields* on a budget-exhausted error,
+ * which has no compaction immediately before it but had several
+ * earlier in the same turn. The turn is the right unit of analysis.
+ *
+ * # 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,
+  getTurnTimeBounds,
+} 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 { ACTOR_PRINCIPALS } from "../auth/route-policy.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 turn window from the `messages` table — every
+  // compaction between the user message that started this turn and the
+  // next real user message (or end-of-conversation) is in scope.
+  //
+  // `getCompactionLogsBetween` uses strict `>` / `<` predicates, so we
+  // shift the inclusive bounds by 1ms to capture rows landing on the
+  // boundaries themselves (e.g. an emergency compaction that fires the
+  // same millisecond as the assistant message terminating the turn).
+  //
+  // When `getTurnTimeBounds` returns `null` (the only-message case), the
+  // turn-bound contract isn't established. Fall back to the selected
+  // call's own `createdAt` as the ceiling and an open floor — the same
+  // shape the route exposed before turn-scoping, so callers don't see
+  // a regression on conversations with a single message.
+  const turnBounds = getTurnTimeBounds(conversationId, selectedCall.createdAt);
+  const afterCreatedAt: number | null =
+    turnBounds !== null ? turnBounds.startTime - 1 : null;
+  const beforeCreatedAt: number =
+    turnBounds !== null ? turnBounds.endTime + 1 : selectedCall.createdAt;
+  const logs = await source.getCompactionLogsBetween(
+    conversationId,
+    afterCreatedAt,
+    beforeCreatedAt,
+  );
+
+  return {
+    conversationId,
+    events: logs.map(projectLogRowToCompactionTrailEvent),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "conversations_compaction_trail_get",
+    endpoint: "conversations/:id/compaction",
+    method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get the compaction trail leading up to an LLM call",
+    description:
+      "Return the chronological list of compaction events that ran in the same agent turn as the call identified by `callId`. Turn bounds are walked from the `messages` table (real user messages — tool-result user messages are not boundaries). Projected from `llm_request_logs` rows where `call_site = \"compactionAgent\"`. When the conversation has no other messages around the selected call, every compaction strictly before the call's `createdAt` 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,
+  },
+];

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

@@ -7,6 +7,9 @@
  * GET    /v1/conversations/:id      — conversation detail
  */
 
+import { z } from "zod";
+
+import { findConversation } from "../../daemon/conversation-store.js";
 import {
   type Confidence,
   getAttentionStateByConversationIds,
@@ -24,10 +27,12 @@ import {
   listConversations,
   listPinnedConversations,
 } from "../../memory/conversation-queries.js";
+import type { ConversationType } from "../../memory/conversation-types.js";
 import { getBindingsForConversations } from "../../memory/external-conversation-store.js";
 import { listGroups } from "../../memory/group-crud.js";
 import { UserError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   buildConversationDetailResponse,
   serializeConversationSummary,
@@ -43,6 +48,118 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("conversation-list-routes");
 
+// ---------------------------------------------------------------------------
+// Response schemas
+// ---------------------------------------------------------------------------
+
+const channelIdSchema = z.enum([
+  "telegram",
+  "phone",
+  "vellum",
+  "whatsapp",
+  "slack",
+  "email",
+  "platform",
+  "a2a",
+]);
+
+const assistantAttentionSchema = z.object({
+  hasUnseenLatestAssistantMessage: z.boolean(),
+  latestAssistantMessageAt: z.number().optional(),
+  lastSeenAssistantMessageAt: z.number().optional(),
+  lastSeenConfidence: z.enum(["explicit", "inferred"]).optional(),
+  lastSeenSignalType: z
+    .enum([
+      "macos_notification_view",
+      "macos_conversation_opened",
+      "ios_conversation_opened",
+      "telegram_inbound_message",
+      "telegram_callback",
+      "slack_inbound_message",
+      "slack_callback",
+    ])
+    .optional(),
+});
+
+const slackThreadSchema = z.object({
+  channelId: z.string(),
+  threadTs: z.string(),
+  link: z
+    .object({
+      appUrl: z.string().optional(),
+      webUrl: z.string().optional(),
+    })
+    .optional(),
+});
+
+const slackChannelSchema = z.object({
+  channelId: z.string(),
+  name: z.string().optional(),
+  link: z.object({ webUrl: z.string() }).optional(),
+});
+
+const channelBindingSchema = z.object({
+  sourceChannel: z.string(),
+  externalChatId: z.string(),
+  externalChatName: z.string().optional(),
+  externalThreadId: z.string().optional(),
+  externalUserId: z.string().nullable(),
+  displayName: z.string().nullable(),
+  username: z.string().nullable(),
+  slackThread: slackThreadSchema.optional(),
+  slackChannel: slackChannelSchema.optional(),
+});
+
+const forkParentSchema = z.object({
+  conversationId: z.string(),
+  messageId: z.string(),
+  title: z.string(),
+});
+
+export const conversationSummarySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  lastMessageAt: z.number().nullable(),
+  conversationType: z.enum(["standard", "background", "scheduled"]),
+  source: z.string(),
+  scheduleJobId: z.string().optional(),
+  channelBinding: channelBindingSchema.optional(),
+  conversationOriginChannel: channelIdSchema.nullable().optional(),
+  assistantAttention: assistantAttentionSchema.optional(),
+  isPinned: z.literal(true).optional(),
+  displayOrder: z.number().nullable().optional(),
+  groupId: z.string().nullable(),
+  forkParent: forkParentSchema.optional(),
+  archivedAt: z.number().optional(),
+  inferenceProfile: z.string().optional(),
+  /**
+   * True when the agent loop is currently mid-turn for this conversation.
+   * Mirrors the in-memory `Conversation.isProcessing()` flag on the daemon
+   * — `false` for rows that are cold (not currently resident in memory).
+   */
+  isProcessing: z.boolean(),
+});
+
+const groupSummarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  sortPosition: z.number(),
+  isSystemGroup: z.boolean(),
+});
+
+const listConversationsResponseSchema = z.object({
+  conversations: z.array(conversationSummarySchema),
+  nextOffset: z.number(),
+  hasMore: z.boolean(),
+  groups: z.array(groupSummarySchema).optional(),
+});
+
+const conversationDetailResponseSchema = z.object({
+  conversation: conversationSummarySchema,
+});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -60,15 +177,48 @@ function resolveOrThrow(rawId: string): string {
 function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
   const limit = Number(queryParams.limit ?? 50);
   const offset = Number(queryParams.offset ?? 0);
-  const backgroundOnly = queryParams.conversationType === "background";
+  // "background" is the back-compat umbrella (background + scheduled); newer
+  // clients can pass "scheduled" to load only the Scheduled section. Absent
+  // defaults to the standard foreground list. Any other value is rejected so
+  // an unrecognized type surfaces as a 400 rather than being silently coerced
+  // to the foreground list (which would mask client/daemon version skew).
+  const rawConversationType = queryParams.conversationType;
+  let conversationType: ConversationType = "standard";
+  if (rawConversationType !== undefined && rawConversationType !== "") {
+    if (
+      rawConversationType === "background" ||
+      rawConversationType === "scheduled"
+    ) {
+      conversationType = rawConversationType;
+    } else {
+      throw new BadRequestError(
+        `Unknown conversationType "${rawConversationType}"; expected "background" or "scheduled".`,
+      );
+    }
+  }
+  // Defaults to `active` so sidebar restores no longer pull archived rows.
+  // The Archive page opts into `archived` to render only archived rows
+  // without dragging the entire live history through pagination first.
+  const archiveStatus =
+    queryParams.archiveStatus === "archived"
+      ? "archived"
+      : queryParams.archiveStatus === "all"
+        ? "all"
+        : "active";
 
-  let rows = listConversations(limit, backgroundOnly, offset);
-  const totalCount = countConversations(backgroundOnly);
+  let rows = listConversations(limit, conversationType, offset, archiveStatus);
+  const totalCount = countConversations(conversationType, archiveStatus);
 
   // On the first page, ensure all pinned conversations are included
-  // even if they fall outside the paginated window.
-  if (offset === 0 && !backgroundOnly) {
-    const pinned = listPinnedConversations();
+  // even if they fall outside the paginated window. Pinned injection is
+  // skipped in archived/all views since the Archive page renders archived
+  // rows in archive-time order, not pin order.
+  if (
+    offset === 0 &&
+    conversationType === "standard" &&
+    archiveStatus === "active"
+  ) {
+    const pinned = listPinnedConversations(archiveStatus);
     const seen = new Set(rows.map((c) => c.id));
     const missing = pinned.filter((c) => !seen.has(c.id));
     if (missing.length > 0) {
@@ -91,6 +241,12 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
         attentionState: attentionStates.get(conversation.id),
         displayMeta: displayMeta.get(conversation.id),
         parentCache,
+        // Cold (evicted / never-loaded) rows aren't in the in-memory
+        // store, so `findConversation` returns `undefined` and they
+        // report `isProcessing: false` — by definition they aren't
+        // mid-turn since the agent loop only runs on resident convs.
+        isProcessing:
+          findConversation(conversation.id)?.isProcessing() ?? false,
       }),
     ),
     nextOffset,
@@ -199,41 +355,101 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listConversations",
     endpoint: "conversations",
     method: "GET",
-    policyKey: "conversations",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List conversations",
     description:
       "Paginated list of conversations with attention state and display metadata.",
     tags: ["conversations"],
+    queryParams: [
+      {
+        name: "limit",
+        type: "integer",
+        required: false,
+        description: "Maximum number of conversations to return (default 50).",
+      },
+      {
+        name: "offset",
+        type: "integer",
+        required: false,
+        description: "Number of conversations to skip (default 0).",
+      },
+      {
+        name: "conversationType",
+        type: "string",
+        required: false,
+        description:
+          'Filter by conversation type. Pass "background" to list background and scheduled conversations together (the back-compat umbrella), or "scheduled" to list only scheduled conversations.',
+        schema: { type: "string", enum: ["background", "scheduled"] },
+      },
+      {
+        name: "archiveStatus",
+        type: "string",
+        required: false,
+        description:
+          'Filter by archive state. Defaults to "active" (non-archived rows only). Pass "archived" to list only archived rows (for the Archive page) or "all" to include both.',
+        schema: { type: "string", enum: ["active", "archived", "all"] },
+      },
+    ],
+    responseBody: listConversationsResponseSchema,
     handler: handleListConversations,
   },
   {
     operationId: "recordConversationSeen",
     endpoint: "conversations/seen",
     method: "POST",
-    policyKey: "conversations/seen",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Record a seen signal",
     description: "Mark a conversation as seen, advancing the attention cursor.",
     tags: ["conversations"],
+    requestBody: z.object({
+      conversationId: z.string(),
+      sourceChannel: z.string().optional(),
+      signalType: z.string().optional(),
+      confidence: z.enum(["explicit", "inferred"]).optional(),
+      source: z.string().optional(),
+      evidenceText: z.string().optional(),
+      metadata: z.record(z.string(), z.unknown()).optional(),
+      observedAt: z.number().optional(),
+    }),
+    responseBody: z.object({ ok: z.boolean() }),
     handler: handleRecordSeen,
   },
   {
     operationId: "markConversationUnread",
     endpoint: "conversations/unread",
     method: "POST",
-    policyKey: "conversations/unread",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Mark conversation unread",
     description: "Reset the seen cursor so the conversation appears unread.",
     tags: ["conversations"],
+    requestBody: z.object({
+      conversationId: z.string(),
+    }),
+    responseBody: z.object({ ok: z.boolean() }),
     handler: handleMarkUnread,
   },
   {
     operationId: "getConversation",
     endpoint: "conversations/:id",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     pathParams: [{ name: "id", type: "uuid" }],
     summary: "Get conversation detail",
     description: "Retrieve a single conversation with full metadata.",
     tags: ["conversations"],
+    responseBody: conversationDetailResponseSchema,
     handler: handleGetConversation,
   },
 ];