@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

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

@@ -15,6 +15,7 @@ import { sanitizeForTts } from "../../calls/tts-text-sanitizer.js";
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { getMessageContent } from "../../daemon/handlers/conversation-history.js";
+import { listCatalogProvidersForDisplay } from "../../tts/provider-catalog.js";
 import {
   synthesizeText,
   TtsSynthesisError,
@@ -22,6 +23,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,
@@ -135,6 +137,10 @@ const ttsResponseHeaders = () => ({
 // Handlers
 // ---------------------------------------------------------------------------
 
+function handleListTtsProviders() {
+  return { providers: listCatalogProvidersForDisplay() };
+}
+
 async function handleMessageTts({ pathParams, queryParams }: RouteHandlerArgs) {
   const config = getConfig();
 
@@ -225,12 +231,44 @@ async function handleSynthesizeCliTts({ body }: RouteHandlerArgs) {
 // ---------------------------------------------------------------------------
 
 export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "tts_providers",
+    endpoint: "tts/providers",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List TTS providers",
+    description:
+      "Return the catalog of available TTS providers with client-facing metadata.",
+    tags: ["tts"],
+    responseBody: z.object({
+      providers: z.array(
+        z.object({
+          id: z.string(),
+          displayName: z.string(),
+          subtitle: z.string(),
+          supportsVoiceSelection: z.boolean(),
+          apiKeyPlaceholder: z.string(),
+          credentialsGuide: z.object({
+            description: z.string(),
+            url: z.string(),
+            linkLabel: z.string(),
+          }),
+        }),
+      ),
+    }),
+    handler: handleListTtsProviders,
+  },
   {
     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 +287,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 +315,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;
@@ -29,6 +31,70 @@ export interface RoutePathParam {
   description?: string;
 }
 
+/**
+ * Content types a route can declare a request body for. `application/json`
+ * is the implicit default when `requestBody` is a bare Zod schema, so it is
+ * only spelled out here for the explicit `{ contentType, schema }` form.
+ */
+export type RouteRequestContentType =
+  | "application/json"
+  | "application/octet-stream"
+  | "multipart/form-data";
+
+/**
+ * A route's request body. Either:
+ * - a bare Zod schema, which is advertised as `application/json`, or
+ * - an explicit `{ contentType, schema }` pair for non-JSON bodies (e.g. a
+ *   raw `application/octet-stream` upload). `schema` may be a Zod schema or a
+ *   plain JSON Schema fragment (e.g. `{ type: "string", format: "binary" }`).
+ *
+ * The OpenAPI generator turns this into the operation's `requestBody`, so the
+ * generated client SDK describes a real body type instead of `never`. The HTTP
+ * adapter parses the body off the request `Content-Type` header, so this field
+ * is a codegen signal only and does not change runtime request handling.
+ */
+export type RouteRequestBody =
+  | z.ZodType
+  | {
+      contentType: RouteRequestContentType;
+      schema: z.ZodType | Record<string, unknown>;
+    };
+
+/**
+ * Content types a route can declare a success response body for.
+ * `application/json` is the implicit default when `responseBody` is a bare
+ * Zod schema, so it is only spelled out here for the explicit
+ * `{ contentType, schema }` form (e.g. a binary `application/octet-stream`
+ * download or an `application/gzip` archive).
+ */
+export type RouteResponseContentType =
+  | "application/json"
+  | "application/octet-stream"
+  | "application/gzip"
+  | "application/pdf"
+  | "application/zip";
+
+/**
+ * A route's success response body. Either:
+ * - a bare Zod schema, which is advertised as `application/json`, or
+ * - an explicit `{ contentType, schema }` pair for non-JSON responses (e.g. a
+ *   binary download). `schema` may be a Zod schema or a plain JSON Schema
+ *   fragment (e.g. `{ type: "string", format: "binary" }`, which is not
+ *   expressible as a bare Zod type).
+ *
+ * The OpenAPI generator turns this into the operation's success response, so
+ * the generated client SDK describes a real response type (e.g. `Blob`)
+ * instead of `unknown`. Handlers serialize their own bytes via `RouteResponse`,
+ * so this field is a codegen signal only and does not change runtime
+ * response handling.
+ */
+export type RouteResponseBody =
+  | z.ZodType
+  | {
+      contentType: RouteResponseContentType;
+      schema: z.ZodType | Record<string, unknown>;
+    };
+
 export interface RouteHandlerArgs {
   pathParams?: Record<string, string>;
   queryParams?: Record<string, string>;
@@ -79,15 +145,29 @@ 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[];
   pathParams?: RoutePathParam[];
   queryParams?: RouteQueryParam[];
-  requestBody?: z.ZodType;
-  responseBody?: z.ZodType;
+  requestBody?: RouteRequestBody;
+  responseBody?: RouteResponseBody;
   /**
    * HTTP status code for the success response. Defaults to "200".
    * Use "201" for resource creation, "204" for no-content responses.
@@ -112,13 +192,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
@@ -136,12 +209,6 @@ export interface RouteDefinition {
    * RouteError subclasses rather than explicit Response objects.
    */
   additionalResponses?: Record<string, { description: string }>;
-  /**
-   * When true, the route expects a raw binary body (e.g. file uploads).
-   * The HTTP adapter already reads `rawBody` for non-JSON content types;
-   * this flag is a declarative signal for documentation and tooling.
-   */
-  rawBody?: boolean;
   /**
    * Per-route request-log control. Routes that opt in can suppress the
    * per-request INFO log line after a confirmed run of successful

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.",

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

@@ -1,10 +1,10 @@
 /**
  * Route handlers for usage and cost summary endpoints.
  *
- * GET /v1/usage/totals?from=&to=              — aggregate totals for a time range
- * GET /v1/usage/daily?from=&to=               — per-day buckets for a time range
- * GET /v1/usage/breakdown?from=&to=&groupBy=  — grouped breakdown
- * GET /v1/usage/series?from=&to=&granularity=&groupBy= — grouped time-series buckets
+ * GET /v1/usage/totals?from=&to=&scheduleId=  — aggregate totals for a time range
+ * GET /v1/usage/daily?from=&to=&scheduleId=   — per-day buckets for a time range
+ * GET /v1/usage/breakdown?from=&to=&groupBy=&scheduleId=  — grouped breakdown
+ * GET /v1/usage/series?from=&to=&granularity=&groupBy=&scheduleId= — grouped time-series buckets
  */
 
 import { z } from "zod";
@@ -18,9 +18,12 @@ import {
   type GroupByDimension,
   USAGE_GROUP_BY_DIMENSIONS,
   USAGE_SERIES_GROUP_BY_DIMENSIONS,
+  type UsageAggregationFilter,
   type UsageGranularity,
 } from "../../memory/llm-usage-store.js";
 import { validateTimezone } from "../../memory/usage-buckets.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { parseEpochMillisRange } from "./epoch-millis-range.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -28,6 +31,54 @@ const VALID_GROUP_BY = new Set<string>(USAGE_GROUP_BY_DIMENSIONS);
 const VALID_SERIES_GROUP_BY = new Set<string>(USAGE_SERIES_GROUP_BY_DIMENSIONS);
 const GROUP_BY_DESCRIPTION = USAGE_GROUP_BY_DIMENSIONS.join(", ");
 const SERIES_GROUP_BY_DESCRIPTION = USAGE_SERIES_GROUP_BY_DIMENSIONS.join(", ");
+const SCHEDULE_ID_FILTER_DESCRIPTION =
+  "Optional schedule id. When set, usage is attributed by cron run windows for that schedule.";
+
+const usageTotalsSchema = z.object({
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalCacheCreationTokens: z.number(),
+  totalCacheReadTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+  pricedEventCount: z.number(),
+  unpricedEventCount: z.number(),
+});
+
+const usageDayBucketSchema = z.object({
+  bucketId: z.string(),
+  date: z.string(),
+  displayLabel: z.string().optional(),
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+});
+
+const usageGroupBreakdownSchema = z.object({
+  group: z.string(),
+  groupId: z.string().nullable(),
+  groupKey: z.string().nullable().optional(),
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalCacheCreationTokens: z.number(),
+  totalCacheReadTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+});
+
+const usageSeriesGroupValueSchema = z.object({
+  group: z.string(),
+  groupKey: z.string().nullable(),
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+});
+
+const usageSeriesBucketSchema = usageDayBucketSchema.extend({
+  groups: z.record(z.string(), usageSeriesGroupValueSchema),
+});
 
 function resolveTimezone(queryParams: Record<string, string>): string {
   const tz = queryParams.tz ?? "UTC";
@@ -39,43 +90,23 @@ function resolveTimezone(queryParams: Record<string, string>): string {
   return tz;
 }
 
-function parseTimeRange(queryParams: Record<string, string>): {
-  from: number;
-  to: number;
-} {
-  const fromRaw = queryParams.from;
-  const toRaw = queryParams.to;
-
-  if (!fromRaw || !toRaw) {
-    throw new BadRequestError(
-      'Missing required query parameters: "from" and "to" (epoch milliseconds)',
-    );
-  }
-
-  const from = Number(fromRaw);
-  const to = Number(toRaw);
-
-  if (!Number.isFinite(from) || !Number.isFinite(to)) {
-    throw new BadRequestError(
-      '"from" and "to" must be valid numbers (epoch milliseconds)',
-    );
-  }
-
-  if (from > to) {
-    throw new BadRequestError('"from" must be less than or equal to "to"');
-  }
-
-  return { from, to };
+function parseUsageAggregationFilter(
+  queryParams: Record<string, string>,
+): UsageAggregationFilter {
+  const scheduleId = queryParams.scheduleId?.trim();
+  return scheduleId ? { scheduleId } : {};
 }
 
 function handleUsageTotals({ queryParams }: RouteHandlerArgs) {
-  const range = parseTimeRange(queryParams ?? {});
-  return getUsageTotals(range);
+  const qp = queryParams ?? {};
+  const range = parseEpochMillisRange(qp);
+  const filter = parseUsageAggregationFilter(qp);
+  return getUsageTotals(range, filter);
 }
 
 function handleUsageDaily({ queryParams }: RouteHandlerArgs) {
   const qp = queryParams ?? {};
-  const range = parseTimeRange(qp);
+  const range = parseEpochMillisRange(qp);
   const granularity = qp.granularity ?? "daily";
   if (granularity !== "daily" && granularity !== "hourly") {
     throw new BadRequestError(
@@ -83,16 +114,17 @@ function handleUsageDaily({ queryParams }: RouteHandlerArgs) {
     );
   }
   const tz = resolveTimezone(qp);
+  const filter = parseUsageAggregationFilter(qp);
   const buckets =
     granularity === "hourly"
-      ? getUsageHourBuckets(range, tz, { fillEmpty: true })
-      : getUsageDayBuckets(range, tz, { fillEmpty: true });
+      ? getUsageHourBuckets(range, tz, { fillEmpty: true }, filter)
+      : getUsageDayBuckets(range, tz, { fillEmpty: true }, filter);
   return { buckets };
 }
 
 function handleUsageBreakdown({ queryParams }: RouteHandlerArgs) {
   const qp = queryParams ?? {};
-  const range = parseTimeRange(qp);
+  const range = parseEpochMillisRange(qp);
 
   const groupBy = qp.groupBy;
   if (!groupBy) {
@@ -106,13 +138,18 @@ function handleUsageBreakdown({ queryParams }: RouteHandlerArgs) {
     );
   }
 
-  const breakdown = getUsageGroupBreakdown(range, groupBy as GroupByDimension);
+  const filter = parseUsageAggregationFilter(qp);
+  const breakdown = getUsageGroupBreakdown(
+    range,
+    groupBy as GroupByDimension,
+    filter,
+  );
   return { breakdown };
 }
 
 function handleUsageSeries({ queryParams }: RouteHandlerArgs) {
   const qp = queryParams ?? {};
-  const range = parseTimeRange(qp);
+  const range = parseEpochMillisRange(qp);
   const granularity = qp.granularity ?? "daily";
   if (granularity !== "daily" && granularity !== "hourly") {
     throw new BadRequestError(
@@ -133,12 +170,14 @@ function handleUsageSeries({ queryParams }: RouteHandlerArgs) {
   }
 
   const tz = resolveTimezone(qp);
+  const filter = parseUsageAggregationFilter(qp);
   const buckets = getUsageGroupedSeries(
     range,
     groupBy as Exclude<GroupByDimension, "conversation">,
     granularity as UsageGranularity,
     tz,
     { fillEmpty: true },
+    filter,
   );
   return { buckets };
 }
@@ -148,6 +187,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "usage_totals",
     endpoint: "usage/totals",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get usage totals",
     description: "Return aggregate usage totals for a time range.",
     tags: ["usage"],
@@ -162,13 +205,22 @@ export const ROUTES: RouteDefinition[] = [
         type: "integer",
         description: "End epoch millis (required)",
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
+    responseBody: usageTotalsSchema,
     handler: handleUsageTotals,
   },
   {
     operationId: "usage_daily",
     endpoint: "usage/daily",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get daily usage",
     description: "Return per-day usage buckets for a time range.",
     tags: ["usage"],
@@ -193,9 +245,13 @@ export const ROUTES: RouteDefinition[] = [
         description:
           'IANA timezone identifier (e.g. "America/Los_Angeles"). Bucket boundaries and display labels are computed in this timezone. Defaults to "UTC" for backwards compatibility.',
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
     responseBody: z.object({
-      buckets: z.array(z.unknown()).describe("Usage bucket objects"),
+      buckets: z.array(usageDayBucketSchema).describe("Usage bucket objects"),
     }),
     handler: handleUsageDaily,
   },
@@ -203,6 +259,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "usage_breakdown",
     endpoint: "usage/breakdown",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get usage breakdown",
     description:
       "Return grouped usage breakdown. Prefer call_site for user-facing task breakdowns; actor is a legacy/internal dimension.",
@@ -222,9 +282,15 @@ export const ROUTES: RouteDefinition[] = [
         name: "groupBy",
         description: `Group by: ${GROUP_BY_DESCRIPTION} (required)`,
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
     responseBody: z.object({
-      breakdown: z.array(z.unknown()).describe("Grouped usage entries"),
+      breakdown: z
+        .array(usageGroupBreakdownSchema)
+        .describe("Grouped usage entries"),
     }),
     handler: handleUsageBreakdown,
   },
@@ -232,6 +298,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "usage_series",
     endpoint: "usage/series",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get grouped usage series",
     description:
       "Return usage buckets with per-group values for stacked charts. Prefer call_site for user-facing task stacks.",
@@ -261,9 +331,15 @@ export const ROUTES: RouteDefinition[] = [
         description:
           'IANA timezone identifier (e.g. "America/Los_Angeles"). Bucket boundaries and display labels are computed in this timezone. Defaults to "UTC".',
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
     responseBody: z.object({
-      buckets: z.array(z.unknown()).describe("Grouped usage bucket objects"),
+      buckets: z
+        .array(usageSeriesBucketSchema)
+        .describe("Grouped usage bucket objects"),
     }),
     handler: handleUsageSeries,
   },

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

@@ -14,6 +14,7 @@ import { z } from "zod";
 import { getConfig } from "../../config/loader.js";
 import { getPublicBaseUrl } from "../../inbound/public-ingress-urls.js";
 import { getWorkspaceRoutesDir } from "../../util/platform.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -222,6 +223,10 @@ export const ROUTES: RouteDefinition[] = [
   {
     operationId: "user_routes_list",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     endpoint: "user-routes/list",
     handler: handleUserRoutesList,
     summary: "List user-defined route handlers",
@@ -232,6 +237,10 @@ export const ROUTES: RouteDefinition[] = [
   {
     operationId: "user_routes_inspect",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     endpoint: "user-routes/inspect",
     handler: handleUserRoutesInspect,
     summary: "Inspect a user-defined route handler",

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

@@ -14,6 +14,7 @@
 
 import { assistantEventHub } from "../assistant-event-hub.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { RouteResponse } from "./types.js";
 import { UserRouteDispatcher } from "./user-route-dispatcher.js";
@@ -108,10 +109,13 @@ export const ROUTES: RouteDefinition[] = METHODS.map((method) => ({
   operationId: `user_route_${method.toLowerCase()}`,
   endpoint: "x/:path*",
   method,
-  policyKey: "x",
   summary: `User-defined ${method} route`,
   description: `Dispatches ${method} requests to user-defined handler files in the workspace routes directory.`,
   tags: ["user-routes"],
+  policy: {
+    requiredScopes: ["settings.read"],
+    allowedPrincipalTypes: ACTOR_PRINCIPALS,
+  },
   handler: async (args: RouteHandlerArgs) => {
     const request = synthesizeRequest(method, args);
     const response = await dispatcher.dispatch(

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

@@ -8,6 +8,7 @@ import { z } from "zod";
 
 import { getConversation } from "../../memory/conversation-crud.js";
 import { wakeAgentForOpportunity } from "../agent-wake.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 
@@ -22,6 +23,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "wake_conversation",
     endpoint: "conversations/wake",
     method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Wake a conversation",
     description:
       "Invoke the agent loop for a conversation with an opportunity hint.",