@vellumai/assistant 0.8.6 → 0.8.7

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

@@ -26,6 +26,7 @@ import type {
   ContactType,
 } from "../../contacts/types.js";
 import { resolveGuardianName } from "../../prompts/user-reference.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   createIngressInvite,
   listIngressInvites,
@@ -34,11 +35,7 @@ import {
   revokeIngressInvite,
   triggerInviteCall,
 } from "../invite-service.js";
-import {
-  BadRequestError,
-  ConflictError,
-  NotFoundError,
-} from "./errors.js";
+import { BadRequestError, ConflictError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 function withGuardianNameOverride<
@@ -80,6 +77,39 @@ function isChannelPolicy(value: string): value is ChannelPolicy {
   return (VALID_CHANNEL_POLICIES as readonly string[]).includes(value);
 }
 
+// ---------------------------------------------------------------------------
+// Response schemas (drive OpenAPI spec → codegen → typed SDK)
+// ---------------------------------------------------------------------------
+
+const contactChannelSchema = z.object({
+  id: z.string(),
+  contactId: z.string(),
+  type: z.string(),
+  address: z.string(),
+  isPrimary: z.boolean(),
+  externalUserId: z.string().nullable(),
+  status: z.string(),
+  policy: z.string(),
+  verifiedAt: z.number().nullable(),
+  verifiedVia: z.string().nullable(),
+  lastSeenAt: z.number().nullable(),
+  interactionCount: z.number(),
+  lastInteraction: z.number().nullable(),
+  revokedReason: z.string().nullable(),
+  blockedReason: z.string().nullable(),
+});
+
+const contactSchema = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  role: z.string(),
+  notes: z.string().nullable().optional(),
+  contactType: z.string().nullable().optional(),
+  lastInteraction: z.number().nullable().optional(),
+  interactionCount: z.number(),
+  channels: z.array(contactChannelSchema),
+});
+
 // ---------------------------------------------------------------------------
 // Contact handlers (transport-agnostic)
 // ---------------------------------------------------------------------------
@@ -251,6 +281,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listContacts",
     endpoint: "contacts",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List contacts",
     description:
       "Return all contacts, optionally filtered by type or channel status.",
@@ -290,7 +324,7 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       ok: z.boolean(),
       contacts: z
-        .array(z.unknown())
+        .array(contactSchema)
         .describe("Contact objects with channels and metadata"),
     }),
     handler: ({ queryParams }: RouteHandlerArgs) =>
@@ -302,6 +336,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_list",
     endpoint: "contacts/invites",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListInvites,
     summary: "List invites",
     description:
@@ -326,6 +364,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_create",
     endpoint: "contacts/invites",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleCreateInvite,
     responseStatus: "201",
     summary: "Create an invite",
@@ -363,6 +405,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_redeem",
     endpoint: "contacts/invites/redeem",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleRedeemInvite,
     summary: "Redeem an invite",
     description: "Redeem an invite by token or voice code.",
@@ -397,7 +443,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_revoke",
     endpoint: "contacts/invites/:id",
     method: "DELETE",
-    policyKey: "contacts/invites",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleRevokeInvite,
     summary: "Revoke an invite",
     description: "Revoke an invite by ID.",
@@ -412,7 +461,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_trigger_call",
     endpoint: "contacts/invites/:id/call",
     method: "POST",
-    policyKey: "contacts/invites",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleTriggerInviteCall,
     summary: "Trigger invite call",
     description: "Trigger an outbound call for a phone invite.",
@@ -433,6 +485,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "search_contacts",
     endpoint: "contacts/search",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Search contacts",
     description: "Search contacts by query, channel address, or channel type.",
     tags: ["contacts"],
@@ -442,7 +498,7 @@ export const ROUTES: RouteDefinition[] = [
       channelType: z.string().optional(),
       limit: z.number().optional(),
     }),
-    responseBody: z.array(z.object({}).passthrough()),
+    responseBody: z.array(contactSchema),
     handler: ({ body = {} }: RouteHandlerArgs) => {
       const parsed = z
         .object({
@@ -461,17 +517,24 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getContact",
     endpoint: "contacts/:id",
     method: "GET",
-    policyKey: "contacts",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get a contact",
     description:
       "Return a single contact with its channels and assistant metadata.",
     tags: ["contacts"],
     responseBody: z.object({
       ok: z.boolean(),
-      contact: z.object({}).passthrough().describe("Contact details"),
+      contact: contactSchema,
       assistantMetadata: z
-        .object({})
-        .passthrough()
+        .object({
+          contactId: z.string(),
+          species: z.string(),
+          metadata: z.object({}).passthrough().nullable(),
+        })
+        .optional()
         .describe("Assistant-side metadata"),
     }),
     handler: ({ pathParams }: RouteHandlerArgs) =>
@@ -481,6 +544,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "merge_contacts",
     endpoint: "contacts/merge",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Merge two contacts",
     description: "Merge two contacts, keeping one and absorbing the other.",
     tags: ["contacts"],
@@ -492,7 +559,7 @@ export const ROUTES: RouteDefinition[] = [
     }),
     responseBody: z.object({
       ok: z.boolean(),
-      contact: z.object({}).passthrough().describe("Merged contact"),
+      contact: contactSchema.describe("Merged contact"),
     }),
     handler: (args: RouteHandlerArgs) => handleMergeContactsRoute(args),
   },
@@ -500,20 +567,22 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "updateContactChannel",
     endpoint: "contact-channels/:contactChannelId",
     method: "PATCH",
-    policyKey: "contact-channels",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Update a contact channel",
     description: "Update status, policy, or reason on a contact's channel.",
     tags: ["contacts"],
     requestBody: z.object({
-      status: z.string().describe("Channel status"),
-      policy: z.string().describe("Channel policy"),
-      reason: z.string().describe("Reason for the change"),
+      status: z.string().optional().describe("Channel status"),
+      policy: z.string().optional().describe("Channel policy"),
+      reason: z.string().optional().describe("Reason for the change"),
     }),
     responseBody: z.object({
       ok: z.boolean(),
-      contact: z
-        .object({})
-        .passthrough()
+      contact: contactSchema
+        .optional()
         .describe("Updated contact (if applicable)"),
     }),
     handler: (args: RouteHandlerArgs) => handleUpdateContactChannelRoute(args),
@@ -603,5 +672,3 @@ function handleUpdateContactChannelRoute(args: RouteHandlerArgs) {
       : undefined,
   };
 }
-
-

package/src/runtime/routes/content-source-routes.ts

@@ -13,6 +13,7 @@ import { dirname, join } from "node:path";
 import { z } from "zod";
 
 import { getWorkspaceDir } from "../../util/platform.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -70,7 +71,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "content_source_set",
     endpoint: "content-source",
     method: "POST",
-    policyKey: "secrets",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Validate and persist a content source URL",
     requestBody: z.object({ url: z.string() }),
     handler: handleContentSource,

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

@@ -11,6 +11,7 @@
 
 import { z } from "zod";
 
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { analyzeConversation } from "../services/analyze-conversation.js";
 import { buildConversationDetailResponse } from "../services/conversation-serializer.js";
 import { conversationSummarySchema } from "./conversation-list-routes.js";
@@ -58,7 +59,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "analyzeConversation",
     endpoint: "conversations/:id/analyze",
     method: "POST",
-    policyKey: "conversations/analyze",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Analyze a conversation",
     description:
       "Create a new conversation with a structured self-assessment of an existing conversation.",

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

@@ -15,6 +15,7 @@ import {
   getMessageById,
 } from "../../memory/conversation-crud.js";
 import { truncate } from "../../util/truncate.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -128,6 +129,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversations_attention_list",
     endpoint: "conversations/attention",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListConversationAttention,
     summary: "List conversation attention states",
     description:

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

@@ -9,6 +9,7 @@
 import { v4 as uuid } from "uuid";
 import { z } from "zod";
 
+import { findConversation } from "../../daemon/conversation-store.js";
 import { clearAllConversations as clearAllActive } from "../../daemon/handlers/conversations.js";
 import { formatJson, formatMarkdown } from "../../export/formatter.js";
 import { ipcCall as ipcCallGateway } from "../../ipc/gateway-client.js";
@@ -23,6 +24,7 @@ import { listConversations } from "../../memory/conversation-queries.js";
 import { getBindingByConversation } from "../../memory/external-conversation-store.js";
 import { sendSlackReply } from "../../messaging/providers/slack/send.js";
 import { getLogger } from "../../util/logger.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadGatewayError, BadRequestError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -35,14 +37,26 @@ const log = getLogger("conversation-cli-routes");
 function handleListCli({ body = {} }: RouteHandlerArgs) {
   const limit =
     body.limit != null ? Number(body.limit) : Number.MAX_SAFE_INTEGER;
+  // CLI flag historically named `includeArchived`. Map onto the new
+  // `archiveStatus` enum: when set, fetch active + archived together so the
+  // user sees archived rows alongside live ones in the picker.
   const includeArchived = (body.includeArchived as boolean) ?? false;
 
-  const rows = listConversations(limit, false, 0, includeArchived);
+  const rows = listConversations(
+    limit,
+    "standard",
+    0,
+    includeArchived ? "all" : "active",
+  );
   return {
     conversations: rows.map((c) => ({
       id: c.id,
       title: c.title,
       updatedAt: c.updatedAt,
+      // `isProcessing` mirrors `Conversation.isProcessing()` from the
+      // in-memory daemon store — true when the agent loop is mid-turn.
+      // Rows not currently in memory (cold / evicted) report `false`.
+      isProcessing: findConversation(c.id)?.isProcessing() ?? false,
     })),
   };
 }
@@ -78,7 +92,6 @@ async function handleCreateCli({ body = {} }: RouteHandlerArgs) {
       conversation.id,
       message.role,
       textContentJson(message.content),
-      undefined,
       { skipIndexing: true },
     );
   }
@@ -111,10 +124,16 @@ function handleExportCli({ body = {} }: RouteHandlerArgs) {
     conversationId = all[0].id;
   }
 
-  // Support prefix matching
+  // Support prefix matching. `archiveStatus: "all"` preserves the pre-default
+  // behavior of letting `vellum export <prefix>` resolve an archived row.
   let conversation = getConversation(conversationId);
   if (!conversation) {
-    const all = listConversations(Number.MAX_SAFE_INTEGER);
+    const all = listConversations(
+      Number.MAX_SAFE_INTEGER,
+      "standard",
+      0,
+      "all",
+    );
     const match = all.find((c) => c.id.startsWith(conversationId!));
     if (match) {
       conversation = match;
@@ -143,8 +162,15 @@ function handleExportCli({ body = {} }: RouteHandlerArgs) {
 // clear (CLI)
 // ---------------------------------------------------------------------------
 
-async function handleClearCli(_args: RouteHandlerArgs) {
-  // Tear down in-memory conversation state before DB clear.
+async function handleClearCli({ headers = {} }: RouteHandlerArgs) {
+  const confirm = headers["x-confirm-destructive"];
+  if (confirm !== "clear-all-conversations") {
+    throw new BadRequestError(
+      "POST /v1/conversations/cli/clear permanently deletes ALL conversations, messages, and memory. " +
+        "To confirm, set header X-Confirm-Destructive: clear-all-conversations",
+    );
+  }
+
   const cleared = await clearAllActive();
   log.info(
     { cleared },
@@ -292,6 +318,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversation_list_cli",
     endpoint: "conversations/cli/list",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "List conversations (CLI)",
     description:
       "Simplified conversation list for CLI output — returns id, title, updatedAt.",
@@ -306,6 +336,7 @@ export const ROUTES: RouteDefinition[] = [
           id: z.string(),
           title: z.string().nullable(),
           updatedAt: z.number(),
+          isProcessing: z.boolean(),
         }),
       ),
     }),
@@ -315,6 +346,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversation_create_cli",
     endpoint: "conversations/cli/create",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Create a conversation (CLI)",
     description:
       "Create a new conversation with an optional title and seeded messages.",
@@ -335,6 +370,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversation_export_cli",
     endpoint: "conversations/cli/export",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Export a conversation (CLI)",
     description:
       "Export a conversation as markdown or JSON. Returns the formatted output string.",
@@ -353,10 +392,14 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversations_clear_cli",
     endpoint: "conversations/cli/clear",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Clear all conversations (CLI)",
     description:
       "Tear down all active conversations and clear the database. " +
-      "The confirmation prompt is handled client-side by the CLI.",
+      "Requires X-Confirm-Destructive: clear-all-conversations.",
     tags: ["conversations"],
     responseBody: z.object({
       cleared: z.number().int(),
@@ -367,6 +410,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversation_slack_detach_cli",
     endpoint: "conversations/cli/slack/detach",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Detach the assistant from a Slack thread (CLI)",
     description:
       "Stops Slack active-thread listening for a Slack thread. The CLI resolves current conversation defaults.",

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

@@ -8,18 +8,31 @@
  *
  * # 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".
+ * 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.
  *
- * 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.
+ * 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)
  *
@@ -39,9 +52,13 @@
 
 import { z } from "zod";
 
-import { getConversation } from "../../memory/conversation-crud.js";
+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,
@@ -196,20 +213,29 @@ async function handleGetCompactionTrail({
     );
   }
 
-  // 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,
-  );
+  // 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,
-    selectedCall.createdAt,
+    beforeCreatedAt,
   );
 
   return {
@@ -227,10 +253,13 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversations_compaction_trail_get",
     endpoint: "conversations/:id/compaction",
     method: "GET",
-    policyKey: "conversations/compaction",
+    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 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.",
+      "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: [
       {