@vellumai/assistant 0.8.6 → 0.8.7

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

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 
+import { DictationRequestSchema } from "../../api/requests/dictation.js";
 import {
   type ProfileResolution,
   resolveProfile,
@@ -22,6 +23,7 @@ import {
   userMessage,
 } from "../../providers/provider-send-message.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -266,35 +268,35 @@ async function handleDictation(body: DictationBody): Promise<DictationResult> {
     try {
       const response = await provider.sendMessage(
         [userMessage(`Transcription: "${transcription}"`)],
-        [
-          {
-            name: "process_dictation",
-            description: "Classify the voice input and return cleaned text",
-            input_schema: {
-              type: "object" as const,
-              properties: {
-                mode: {
-                  type: "string",
-                  enum: ["dictation", "action"],
-                  description:
-                    "dictation = user wants text inserted/cleaned up for typing. action = user wants the assistant to perform a task.",
-                },
-                text: {
-                  type: "string",
-                  description:
-                    "If dictation: the cleaned/formatted text ready for insertion. If action: the raw transcription unchanged.",
-                },
-                reasoning: {
-                  type: "string",
-                  description: "Brief reasoning for the classification",
+        {
+          tools: [
+            {
+              name: "process_dictation",
+              description: "Classify the voice input and return cleaned text",
+              input_schema: {
+                type: "object" as const,
+                properties: {
+                  mode: {
+                    type: "string",
+                    enum: ["dictation", "action"],
+                    description:
+                      "dictation = user wants text inserted/cleaned up for typing. action = user wants the assistant to perform a task.",
+                  },
+                  text: {
+                    type: "string",
+                    description:
+                      "If dictation: the cleaned/formatted text ready for insertion. If action: the raw transcription unchanged.",
+                  },
+                  reasoning: {
+                    type: "string",
+                    description: "Brief reasoning for the classification",
+                  },
                 },
+                required: ["mode", "text", "reasoning"],
               },
-              required: ["mode", "text", "reasoning"],
             },
-          },
-        ],
-        systemPrompt,
-        {
+          ],
+          systemPrompt,
           config: {
             callSite: "interactionClassifier",
             max_tokens: maxTokens,
@@ -405,9 +407,9 @@ async function handleCommandMode(
 
     const response = await provider.sendMessage(
       [userMessage(body.transcription)],
-      [],
-      systemPrompt,
       {
+        tools: [],
+        systemPrompt,
         config: { callSite: "interactionClassifier", max_tokens: maxTokens },
       },
     );
@@ -446,32 +448,21 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "dictation_post",
     endpoint: "dictation",
     method: "POST",
-    policyKey: "dictation",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Process dictation",
     description:
       "Classify voice input as dictation or action, clean up text, and apply user style preferences.",
     tags: ["diagnostics"],
-    requirePolicyEnforcement: true,
-    requestBody: z.object({
-      transcription: z.string().describe("Raw speech transcription"),
-      context: z
-        .object({})
-        .passthrough()
-        .describe(
-          "Dictation context (app name, window title, bundle ID, cursor state, selected text)",
-        ),
-      profileId: z
-        .string()
-        .describe("Optional dictation profile ID")
-        .optional(),
-    }),
+    requestBody: DictationRequestSchema,
     responseBody: z.object({
       text: z.string().describe("Processed text output"),
-      mode: z
-        .string()
-        .describe("Detected mode: dictation, command, or action"),
+      mode: z.string().describe("Detected mode: dictation, command, or action"),
       actionPlan: z
         .string()
+        .optional()
         .describe("Action plan (only when mode is action)"),
       resolvedProfileId: z.string().describe("Resolved dictation profile ID"),
       profileSource: z.string().describe("How the profile was resolved"),

package/src/runtime/routes/disk-pressure-routes.ts

@@ -1,36 +1,16 @@
 import { z } from "zod";
 
+import { DiskPressureStatusResponseSchema } from "../../api/responses/disk-pressure-status.js";
 import {
   acknowledgeDiskPressureLock,
   DISK_PRESSURE_OVERRIDE_CONFIRMATION,
   getDiskPressureStatus,
   overrideDiskPressureLock,
 } from "../../daemon/disk-pressure-guard.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { RouteError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 
-const DiskPressureStatusSchema = z.object({
-  enabled: z.boolean(),
-  state: z.enum(["disabled", "ok", "warning", "critical", "unknown"]),
-  locked: z.boolean(),
-  acknowledged: z.boolean(),
-  overrideActive: z.boolean(),
-  effectivelyLocked: z.boolean(),
-  lockId: z.string().nullable(),
-  usagePercent: z.number().nullable(),
-  thresholdPercent: z.number(),
-  path: z.string().nullable(),
-  lastCheckedAt: z.string().nullable(),
-  blockedCapabilities: z.array(
-    z.enum(["agent-turns", "background-work", "remote-ingress"]),
-  ),
-  error: z.string().nullable(),
-});
-
-const DiskPressureActionResponseSchema = z.object({
-  status: DiskPressureStatusSchema,
-});
-
 const OverrideRequestSchema = z.object({
   confirmation: z.string(),
 });
@@ -52,26 +32,30 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getDiskPressureStatus",
     endpoint: "disk-pressure/status",
     method: "GET",
-    policyKey: "disk-pressure/status",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get disk pressure status",
     description:
       "Return the current disk pressure status snapshot. When safe storage limits are disabled, returns a disabled status.",
     tags: ["disk-pressure"],
-    responseBody: DiskPressureActionResponseSchema,
+    responseBody: DiskPressureStatusResponseSchema,
     handler: () => statusResponse(),
   },
   {
     operationId: "acknowledgeDiskPressure",
     endpoint: "disk-pressure/acknowledge",
     method: "POST",
-    policyKey: "disk-pressure/acknowledge",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Acknowledge disk pressure",
     description:
       "Acknowledge the current disk pressure lock and enter cleanup mode without overriding assistant protections.",
     tags: ["disk-pressure"],
-    responseBody: DiskPressureActionResponseSchema,
+    responseBody: DiskPressureStatusResponseSchema,
     additionalResponses: {
       "409": { description: "No active lock or lock already acknowledged." },
     },
@@ -92,13 +76,15 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "overrideDiskPressure",
     endpoint: "disk-pressure/override",
     method: "POST",
-    policyKey: "disk-pressure/override",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Override disk pressure",
     description: `Override the current disk pressure lock only after confirming "${DISK_PRESSURE_OVERRIDE_CONFIRMATION}".`,
     tags: ["disk-pressure"],
     requestBody: OverrideRequestSchema,
-    responseBody: DiskPressureActionResponseSchema,
+    responseBody: DiskPressureStatusResponseSchema,
     additionalResponses: {
       "400": { description: "Confirmation phrase is invalid." },
       "409": { description: "No active lock or lock already overridden." },

package/src/runtime/routes/document-comments-routes.ts

@@ -17,6 +17,7 @@ import {
 } from "../../documents/document-comments-store.js";
 import { getLogger } from "../../util/logger.js";
 import { broadcastMessage } from "../assistant-event-hub.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 
@@ -35,7 +36,11 @@ const listQuerySchema = z.object({
 
 const createBodySchema = z.object({
   content: z.string().min(1).describe("Comment text content"),
-  author: z.literal("user").optional().default("user").describe("Comment author"),
+  author: z
+    .literal("user")
+    .optional()
+    .default("user")
+    .describe("Comment author"),
   anchorStart: z
     .number()
     .nullable()
@@ -68,6 +73,33 @@ const updateBodySchema = z
     message: "At least one of status or content must be provided",
   });
 
+// ---------------------------------------------------------------------------
+// Response schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Wire shape of a stored comment, mirroring the `CommentRecord` returned by
+ * the store layer. Shared by the list, create, and update responses so the
+ * generated client and OpenAPI spec describe the full comment rather than an
+ * erased `unknown`.
+ */
+const documentCommentSchema = z.object({
+  id: z.string(),
+  surfaceId: z.string(),
+  conversationId: z.string(),
+  author: z.string(),
+  content: z.string(),
+  anchorStart: z.number().nullable(),
+  anchorEnd: z.number().nullable(),
+  anchorText: z.string().nullable(),
+  parentCommentId: z.string().nullable(),
+  status: z.enum(["open", "resolved"]),
+  resolvedBy: z.string().nullable(),
+  resolvedAt: z.number().nullable(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -77,8 +109,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listDocumentComments",
     endpoint: "documents/:id/comments",
     method: "GET",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List comments for a document",
     description:
       "Return comments for a document, optionally filtered by status.",
@@ -91,7 +125,7 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      comments: z.array(z.unknown()).describe("Comment records"),
+      comments: z.array(documentCommentSchema).describe("Comment records"),
     }),
     handler: ({ pathParams, queryParams }) => {
       const parsed = listQuerySchema.safeParse(queryParams ?? {});
@@ -108,22 +142,15 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "createDocumentComment",
     endpoint: "documents/:id/comments",
     method: "POST",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Create a comment on a document",
     description: "Add a new comment to a document.",
     tags: ["documents"],
     requestBody: createBodySchema,
-    responseBody: z.object({
-      id: z.string(),
-      surfaceId: z.string(),
-      conversationId: z.string(),
-      author: z.string(),
-      content: z.string(),
-      status: z.string(),
-      createdAt: z.number(),
-      updatedAt: z.number(),
-    }),
+    responseBody: documentCommentSchema,
     handler: ({ pathParams, body }) => {
       const parsed = createBodySchema.safeParse(body ?? {});
       if (!parsed.success) {
@@ -181,19 +208,12 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "updateDocumentComment",
     endpoint: "documents/:id/comments/:commentId",
     method: "PATCH",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: null,
     summary: "Update a document comment",
     description: "Update the status or content of a comment.",
     tags: ["documents"],
     requestBody: updateBodySchema,
-    responseBody: z.object({
-      id: z.string(),
-      surfaceId: z.string(),
-      content: z.string(),
-      status: z.string(),
-      updatedAt: z.number(),
-    }),
+    responseBody: documentCommentSchema,
     handler: ({ pathParams, body }) => {
       const parsed = updateBodySchema.safeParse(body ?? {});
       if (!parsed.success) {
@@ -253,8 +273,7 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "deleteDocumentComment",
     endpoint: "documents/:id/comments/:commentId",
     method: "DELETE",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: null,
     summary: "Delete a document comment",
     description: "Permanently delete a comment.",
     tags: ["documents"],

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

@@ -14,6 +14,7 @@ import {
 } from "../../documents/document-store.js";
 import { rawAll } from "../../memory/raw-query.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { renderMarkdownToPDF } from "./document-pdf-renderer.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
@@ -69,8 +70,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listDocuments",
     endpoint: "documents",
     method: "GET",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List documents",
     description: "Return all documents, optionally filtered by conversation.",
     tags: ["documents"],
@@ -106,8 +109,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getDocument",
     endpoint: "documents/:id",
     method: "GET",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get a document",
     description: "Return a single document by surface ID.",
     tags: ["documents"],
@@ -134,8 +139,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "saveDocument",
     endpoint: "documents",
     method: "POST",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Save a document",
     description: "Create or upsert a document (by surfaceId).",
     tags: ["documents"],
@@ -195,8 +202,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "linkDocumentConversation",
     endpoint: "documents/:id/conversations",
     method: "POST",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Link a document to a conversation",
     description:
       "Associate a document with a conversation so the assistant sees it as context.",
@@ -227,8 +236,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "exportDocumentPDF",
     endpoint: "documents/:id/pdf",
     method: "GET",
-    policyKey: "documents",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Export a document as PDF",
     description: "Render a document to PDF and return the binary content.",
     tags: ["documents"],

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

@@ -12,11 +12,26 @@ import {
   setNestedValue,
 } from "../../config/loader.js";
 import { VellumPlatformClient } from "../../platform/client.js";
+import { getLogger } from "../../util/logger.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, RouteError, UnauthorizedError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
+const log = getLogger("domain-routes");
+
 // ── Helpers ───────────────────────────────────────────────────────────
 
+interface DomainListResponse {
+  next?: string | null;
+  results: {
+    id: string;
+    subdomain?: string;
+    domain?: string;
+    created_at?: string;
+    created?: string;
+  }[];
+}
+
 async function requireClient(): Promise<VellumPlatformClient> {
   const client = await VellumPlatformClient.create();
   if (!client) {
@@ -32,6 +47,25 @@ async function requireClient(): Promise<VellumPlatformClient> {
   return client;
 }
 
+async function fetchDomains(
+  client: VellumPlatformClient,
+): Promise<DomainListResponse> {
+  const response = await client.fetch(
+    `/v1/assistants/${client.platformAssistantId}/domains/`,
+  );
+
+  if (!response.ok) {
+    const respBody = (await response.json().catch(() => ({}))) as Record<
+      string,
+      unknown
+    >;
+    const detail = respBody.detail ?? `HTTP ${response.status}`;
+    throw new RouteError(String(detail), "LIST_FAILED", response.status);
+  }
+
+  return (await response.json()) as DomainListResponse;
+}
+
 // ── Handlers ──────────────────────────────────────────────────────────
 
 async function handleDomainRegister({ body = {} }: RouteHandlerArgs) {
@@ -106,33 +140,7 @@ async function handleDomainStatus(_args: RouteHandlerArgs) {
   const client = await requireClient();
   const apexDomain = getApexDomain();
 
-  const response = await client.fetch(
-    `/v1/assistants/${client.platformAssistantId}/domains/`,
-  );
-
-  if (!response.ok) {
-    const respBody = (await response.json().catch(() => ({}))) as Record<
-      string,
-      unknown
-    >;
-    const detail = respBody.detail ?? `HTTP ${response.status}`;
-    throw new RouteError(
-      String(detail),
-      "LIST_FAILED",
-      response.status,
-    );
-  }
-
-  const data = (await response.json()) as {
-    results: {
-      id: string;
-      subdomain?: string;
-      domain?: string;
-      created_at?: string;
-      created?: string;
-    }[];
-  };
-
+  const data = await fetchDomains(client);
   const domains = data.results ?? [];
 
   // Sync subdomain to config if not already cached
@@ -163,8 +171,21 @@ async function handleDomainVerificationStatus({
   }
   const client = await requireClient();
 
+  const { results, next } = await fetchDomains(client);
+  if (next) {
+    log.error(
+      { extra: { domain_id, next } },
+      "Domain list is paginated; ownership check may produce false negatives",
+    );
+  }
+  if (!results?.some((d) => d.id === domain_id)) {
+    throw new BadRequestError(
+      "domain_id is not registered for this assistant",
+    );
+  }
+
   const response = await client.fetch(
-    `/v1/assistants/${client.platformAssistantId}/domains/${domain_id}/verification-status/`,
+    `/v1/assistants/${client.platformAssistantId}/domains/${encodeURIComponent(domain_id)}/verification-status/`,
   );
 
   if (!response.ok) {
@@ -194,6 +215,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "domain_register",
     endpoint: "domain/register",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleDomainRegister,
     summary: "Register a subdomain for this assistant",
     tags: ["domain"],
@@ -202,6 +227,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "domain_status",
     endpoint: "domain/status",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleDomainStatus,
     summary: "Show domain registration and health",
     tags: ["domain"],
@@ -210,6 +239,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "domain_verification_status",
     endpoint: "domain/verification-status",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleDomainVerificationStatus,
     summary: "Get live DNS verification status for a domain",
     tags: ["domain"],

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

@@ -9,6 +9,7 @@ import { z } from "zod";
 
 import { markdownToEmailHtml } from "../../email/html-renderer.js";
 import { VellumPlatformClient } from "../../platform/client.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
   NotFoundError,
@@ -419,6 +420,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_register",
     endpoint: "email/register",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailRegister,
     summary: "Register an email address",
     description:
@@ -440,6 +445,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_unregister",
     endpoint: "email/unregister",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailUnregister,
     summary: "Unregister the email address",
     description:
@@ -453,6 +462,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_status",
     endpoint: "email/status",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailStatus,
     summary: "Get email address status and usage",
     description:
@@ -475,6 +488,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_list",
     endpoint: "email/list",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailList,
     summary: "List email messages",
     description:
@@ -509,6 +526,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_download",
     endpoint: "email/download",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailDownload,
     summary: "Download a specific email message",
     description: "Download a specific email message by ID.",
@@ -527,6 +548,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_send",
     endpoint: "email/send",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailSend,
     summary: "Send an email",
     description:
@@ -553,6 +578,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_attachment_list",
     endpoint: "email/attachment-list",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailAttachmentList,
     summary: "List attachments for an email message",
     description:
@@ -583,6 +612,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "email_attachment_get",
     endpoint: "email/attachment-get",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleEmailAttachmentGet,
     summary: "Stream-download an email attachment",
     description: