@vellumai/assistant 0.8.6 → 0.8.7

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

@@ -23,6 +23,7 @@ import {
   FFPROBE_TIMEOUT_MS,
   spawnWithTimeout,
 } from "../../util/spawn.js";
+import { ACTOR_PRINCIPALS, LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadGatewayError,
   BadRequestError,
@@ -382,8 +383,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "stt_providers",
     endpoint: "stt/providers",
     method: "GET",
-    policyKey: "stt/providers",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List STT providers",
     description:
       "Return the catalog of available STT providers with client-facing metadata.",
@@ -408,8 +411,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "stt_transcribe",
     endpoint: "stt/transcribe",
     method: "POST",
-    policyKey: "stt/transcribe",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Transcribe audio to text",
     description:
       "Transcribe base64-encoded audio to text using the configured STT provider.",
@@ -441,8 +446,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "stt_transcribe_file",
     endpoint: "stt/transcribe-file",
     method: "POST",
-    policyKey: "stt/transcribe-file",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Transcribe audio/video file to text",
     description:
       "Transcribe an audio or video file to text using the configured STT provider. Handles ffmpeg conversion, large-file chunking, and sequential chunk transcription.",

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

@@ -7,6 +7,7 @@
  */
 import { z } from "zod";
 
+import { SubagentDetailResponseSchema } from "../../api/responses/subagent-detail.js";
 import {
   getMessages,
   type MessageRow,
@@ -14,6 +15,7 @@ import {
 import { getConversationUsageTotals } from "../../memory/llm-usage-store.js";
 import { getSubagentManager } from "../../subagent/index.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 
@@ -192,7 +194,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "reconcileSubagents",
     endpoint: "subagents/reconcile",
     method: "GET",
-    policyKey: "subagents",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Reconcile subagent live status",
     description:
       "Returns the live in-memory status of all subagents known to the daemon for a given parent conversation. Subagents not in the response are orphaned.",
@@ -233,7 +238,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getSubagentDetail",
     endpoint: "subagents/:id",
     method: "GET",
-    policyKey: "subagents",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get subagent detail",
     description: "Return subagent objective and event history.",
     tags: ["subagents"],
@@ -244,18 +252,7 @@ export const ROUTES: RouteDefinition[] = [
         description: "Parent conversation ID (required)",
       },
     ],
-    responseBody: z.object({
-      subagentId: z.string(),
-      objective: z.string(),
-      usage: z
-        .object({
-          inputTokens: z.number(),
-          outputTokens: z.number(),
-          estimatedCost: z.number(),
-        })
-        .optional(),
-      events: z.array(z.unknown()).describe("Subagent event objects"),
-    }),
+    responseBody: SubagentDetailResponseSchema,
     handler: ({ pathParams, queryParams }) => {
       const conversationId = queryParams?.conversationId;
       if (!conversationId) {
@@ -263,9 +260,12 @@ export const ROUTES: RouteDefinition[] = [
       }
 
       const manager = getSubagentManager();
-      manager.getState(pathParams!.id);
+      const state = manager.getState(pathParams!.id);
 
-      return getSubagentDetail(pathParams!.id, conversationId);
+      return {
+        ...getSubagentDetail(pathParams!.id, conversationId),
+        status: state?.status,
+      };
     },
   },
 
@@ -273,7 +273,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "abortSubagent",
     endpoint: "subagents/:id/abort",
     method: "POST",
-    policyKey: "subagents/abort",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Abort subagent",
     description: "Abort a running subagent.",
     tags: ["subagents"],
@@ -313,7 +316,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "sendSubagentMessage",
     endpoint: "subagents/:id/message",
     method: "POST",
-    policyKey: "subagents/message",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Send message to subagent",
     description: "Send a text message to a running subagent.",
     tags: ["subagents"],

package/src/runtime/routes/suggest-trust-rule-routes.ts

@@ -14,6 +14,7 @@ import {
   getConfiguredProvider,
   userMessage,
 } from "../../providers/provider-send-message.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ── Request / response shapes ─────────────────────────────────────────
@@ -183,9 +184,9 @@ async function handleSuggestTrustRule({
   try {
     const response = await provider.sendMessage(
       [userMessage(buildUserMessage(req))],
-      [SUGGEST_RULE_TOOL],
-      SYSTEM_PROMPT,
       {
+        tools: [SUGGEST_RULE_TOOL],
+        systemPrompt: SYSTEM_PROMPT,
         config: {
           callSite: "trustRuleSuggestion",
           max_tokens: 512,
@@ -264,6 +265,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "suggest_trust_rule",
     endpoint: "trust-rules/suggest",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleSuggestTrustRule,
     summary: "Suggest a trust rule",
     description:

package/src/runtime/routes/surface-action-routes.ts

@@ -13,6 +13,7 @@ import type { ChannelId } from "../../channels/types.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { healGuardianBindingDrift } from "../guardian-vellum-migration.js";
 import { resolveLocalTrustContext } from "../local-actor-identity.js";
 import {
@@ -225,6 +226,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "triggerSurfaceAction",
     endpoint: "surface-actions",
     method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Trigger a surface action",
     description:
       "Execute an interactive action on a surface (e.g. button click, form submit).",
@@ -257,6 +262,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "undoSurfaceAction",
     endpoint: "surfaces/:id/undo",
     method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Undo last surface action",
     description: "Revert the most recent action on a surface.",
     tags: ["surfaces"],

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

@@ -10,6 +10,7 @@
 import { z } from "zod";
 
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
 import { resolveSurfaceConversation } from "./surface-conversation-resolver.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -39,7 +40,10 @@ async function handleGetSurfaceContent({
   // owning Conversation has been evicted or the daemon was restarted. The
   // DB scan uses the surfaceId itself as the existence check so a stale
   // or made-up conversationId can't materialize a phantom conversation.
-  const conversation = await resolveSurfaceConversation(conversationId, surfaceId);
+  const conversation = await resolveSurfaceConversation(
+    conversationId,
+    surfaceId,
+  );
   if (!conversation) {
     throw new NotFoundError(
       "No active conversation found for this conversationId",
@@ -91,6 +95,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "surfaces_get_content",
     endpoint: "surfaces/:surfaceId",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get surface content",
     description:
       "Return the full surface payload from the conversation's in-memory surface state.",
@@ -106,7 +114,7 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       surfaceId: z.string(),
       surfaceType: z.string(),
-      title: z.string(),
+      title: z.string().nullable(),
       data: z.object({}).passthrough().describe("Surface data payload"),
     }),
     handler: handleGetSurfaceContent,

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

@@ -8,6 +8,7 @@ import { z } from "zod";
 import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
 import type { ToolContext } from "../../tools/types.js";
 import { getWorkspaceDir } from "../../util/platform.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -255,6 +256,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_save",
     endpoint: "tasks/save",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskSave,
     summary: "Save a task template",
     description: "Save the current conversation as a reusable task template.",
@@ -266,6 +271,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_list",
     endpoint: "tasks/list",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskList,
     summary: "List task templates",
     description: "List all saved task templates.",
@@ -276,6 +285,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_run",
     endpoint: "tasks/run",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskRun,
     summary: "Run a task template",
     description: "Execute a saved task template by name or ID.",
@@ -287,6 +300,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_delete",
     endpoint: "tasks/delete",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskDelete,
     summary: "Delete task templates",
     description: "Delete one or more task templates by ID.",
@@ -300,6 +317,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_show",
     endpoint: "tasks/queue/show",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueShow,
     summary: "Show task queue",
     description: "List work items in the task queue, optionally filtered by status.",
@@ -311,6 +332,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_add",
     endpoint: "tasks/queue/add",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueAdd,
     summary: "Add to task queue",
     description: "Add a new work item to the task queue.",
@@ -322,6 +347,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_update",
     endpoint: "tasks/queue/update",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueUpdate,
     summary: "Update a task queue item",
     description: "Update an existing work item in the task queue.",
@@ -333,6 +362,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_remove",
     endpoint: "tasks/queue/remove",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueRemove,
     summary: "Remove from task queue",
     description: "Remove a work item from the task queue.",
@@ -344,6 +377,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_run",
     endpoint: "tasks/queue/run",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueRun,
     summary: "Run next task queue item",
     description: "Pick up and execute the next work item from the queue.",

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

@@ -9,6 +9,7 @@ import { z } from "zod";
 import { recordLifecycleEvent } from "../../memory/lifecycle-events-store.js";
 import { getUsageTelemetryReporter } from "../../telemetry/usage-telemetry-reporter.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";
 
@@ -47,6 +48,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "telemetry_lifecycle",
     endpoint: "telemetry/lifecycle",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Record lifecycle event",
     description: "Record a telemetry lifecycle event (app_open, hatch).",
     tags: ["telemetry"],
@@ -72,6 +77,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "telemetry_flush",
     endpoint: "telemetry/flush",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Flush pending telemetry events",
     description:
       "Force-flush all pending usage, turn, and lifecycle telemetry events to the platform.",

package/src/runtime/routes/trace-event-routes.ts

@@ -7,9 +7,46 @@
 import { z } from "zod";
 
 import { getTraceEvents } from "../../memory/trace-event-store.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
+const traceEventKindSchema = z.enum([
+  "request_received",
+  "request_queued",
+  "request_dequeued",
+  "llm_call_started",
+  "llm_call_finished",
+  "assistant_message",
+  "tool_started",
+  "tool_permission_requested",
+  "tool_permission_decided",
+  "tool_finished",
+  "tool_failed",
+  "generation_handoff",
+  "message_complete",
+  "generation_cancelled",
+  "request_error",
+  "tool_profiling_summary",
+]);
+
+const traceEventRowSchema = z.object({
+  eventId: z.string(),
+  conversationId: z.string(),
+  requestId: z.string().optional(),
+  timestampMs: z.number(),
+  sequence: z.number(),
+  kind: traceEventKindSchema,
+  status: z.enum(["info", "success", "warning", "error"]).optional(),
+  summary: z.string(),
+  attributes: z
+    .record(
+      z.string(),
+      z.union([z.string(), z.number(), z.boolean(), z.null()]),
+    )
+    .optional(),
+});
+
 function handleListTraceEvents({ queryParams }: RouteHandlerArgs) {
   const conversationId = queryParams?.conversationId;
   if (!conversationId) {
@@ -44,6 +81,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "trace_events_list",
     endpoint: "trace-events",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List trace events",
     description: "Return persisted trace events for a conversation.",
     tags: ["trace"],
@@ -64,7 +105,7 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      events: z.array(z.unknown()).describe("Trace event objects"),
+      events: z.array(traceEventRowSchema).describe("Trace event objects"),
     }),
     handler: handleListTraceEvents,
   },

package/src/runtime/routes/trust-rules-routes.ts

@@ -7,6 +7,7 @@
 import { z } from "zod";
 
 import { getGatewayInternalBaseUrl } from "../../config/env.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ── Shared helper ───────────────────────────────────────────────────────
@@ -62,6 +63,10 @@ export const ROUTES: RouteDefinition[] = [
   {
     operationId: "trust_rules_list",
     method: "GET",
+    policy: {
+      requiredScopes: ["approval.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     endpoint: "trust-rules",
     handler: handleList,
     summary: "List trust rules",

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

@@ -22,6 +22,7 @@ import {
 import { resolveTtsConfig } from "../../tts/tts-config-resolver.js";
 import type { TtsUseCase } from "../../tts/types.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS, LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadGatewayError,
   BadRequestError,
@@ -229,8 +230,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "messages_tts",
     endpoint: "messages/:messageId/tts",
     method: "POST",
-    policyKey: "messages/tts",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Synthesize message to speech",
     description:
       "Synthesize a message's text content to audio using the configured TTS provider.",
@@ -249,8 +252,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "tts_synthesize",
     endpoint: "tts/synthesize",
     method: "POST",
-    policyKey: "tts/synthesize",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Synthesize text to speech",
     description:
       "Synthesize arbitrary text to audio using the configured TTS provider.",
@@ -275,8 +280,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "tts_synthesize_cli",
     endpoint: "tts/synthesize-cli",
     method: "POST",
-    policyKey: "tts/synthesize-cli",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Synthesize text to speech (CLI)",
     description:
       "Synthesize arbitrary text to audio. Returns base64-encoded audio + content type for CLI consumption.",

package/src/runtime/routes/types.ts

@@ -4,6 +4,8 @@
 
 import type { z } from "zod";
 
+import type { RoutePolicy } from "../auth/route-policy.js";
+
 export interface RouteQueryParam {
   name: string;
   type?: string;
@@ -79,8 +81,22 @@ export interface RouteDefinition {
   operationId: string;
   endpoint: string;
   method: string;
+  /**
+   * Scope + principal-type policy for this route.
+   *
+   * `null` means the route is intentionally unprotected — health
+   * probes, public capability-token endpoints, and the like.
+   *
+   * A `RoutePolicy` object declares the scopes a caller must hold
+   * and which principal types are allowed. Both the HTTP server
+   * (`enforcePolicy()`) and the gateway IPC proxy (via the route
+   * schema served from `get_route_schema`) read this field.
+   *
+   * Required so the type system catches every new route — there is
+   * no separate registry to forget to update.
+   */
+  policy: RoutePolicy | null;
   handler: (args: RouteHandlerArgs) => unknown | Promise<unknown>;
-  policyKey?: string;
   summary?: string;
   description?: string;
   tags?: string[];
@@ -112,13 +128,6 @@ export interface RouteDefinition {
    * will be served directly by the gateway (ATL-314).
    */
   isPublic?: boolean;
-  /**
-   * When true, the route requires scope-based policy enforcement.
-   * The HTTP server enforces via `enforcePolicy()`. The IPC adapter
-   * includes the resolved policy in the route schema so the gateway's
-   * IPC proxy enforces equivalent scope/principal checks.
-   */
-  requirePolicyEnforcement?: boolean;
   /**
    * Response headers for this route. Can be:
    * - A static map of header name → value

package/src/runtime/routes/ui-request-routes.ts

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { requestInteractiveUi } from "../interactive-ui.js";
 import { RESERVED_ACTION_IDS } from "../interactive-ui-types.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -46,6 +47,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "ui_request",
     endpoint: "ui/request",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleUiRequest,
     summary: "Present an interactive UI surface",
     description:

package/src/runtime/routes/upgrade-broadcast-routes.ts

@@ -12,6 +12,7 @@ import type {
 } from "../../daemon/message-types/upgrades.js";
 import { buildAssistantEvent } from "../assistant-event.js";
 import { assistantEventHub } from "../assistant-event-hub.js";
+import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -124,6 +125,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "upgrade_broadcast",
     endpoint: "admin/upgrade-broadcast",
     method: "POST",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Broadcast upgrade lifecycle event",
     description:
       "Publish a service group update lifecycle event (starting, progress, or complete) to all connected SSE clients.",