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

package/src/runtime/routes/oauth-providers.ts

@@ -6,7 +6,10 @@
  * the standard runtime auth middleware.
  */
 
+import { z } from "zod";
+
 import { loadConfig } from "../../config/loader.js";
+import { getOAuthCallbackUrl } from "../../inbound/public-ingress-urls.js";
 import {
   deleteApp,
   deleteConnection,
@@ -25,6 +28,7 @@ import {
 } from "../../oauth/provider-serializer.js";
 import { isProviderVisible } from "../../oauth/provider-visibility.js";
 import { SEEDED_PROVIDER_KEYS } from "../../oauth/seed-providers.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
   ConflictError,
@@ -84,13 +88,24 @@ function handleGetProvider({ pathParams = {} }: RouteHandlerArgs) {
     );
   }
 
-  if (!isProviderVisible(row, loadConfig())) {
+  const config = loadConfig();
+  if (!isProviderVisible(row, config)) {
     throw new NotFoundError(
       `No OAuth provider registered for "${providerKey}"`,
     );
   }
 
-  return { provider: serializeProviderFull(row) };
+  let oauthCallbackUrl: string | null = null;
+  try {
+    oauthCallbackUrl = getOAuthCallbackUrl(config);
+  } catch {
+    // Ingress not configured or disabled — callback URL unavailable
+  }
+
+  return {
+    provider: serializeProviderFull(row),
+    oauth_callback_url: oauthCallbackUrl,
+  };
 }
 
 function handleRegisterProvider({ body = {} }: RouteHandlerArgs) {
@@ -207,7 +222,8 @@ function handleUpdateProvider({
   if (b.default_scopes !== undefined) params.defaultScopes = b.default_scopes;
   if (b.available_scopes !== undefined)
     params.availableScopes = b.available_scopes;
-  if (b.scope_separator !== undefined) params.scopeSeparator = b.scope_separator;
+  if (b.scope_separator !== undefined)
+    params.scopeSeparator = b.scope_separator;
   if (b.token_endpoint_auth_method !== undefined)
     params.tokenEndpointAuthMethod = b.token_endpoint_auth_method;
   if (b.token_exchange_body_format !== undefined)
@@ -232,13 +248,15 @@ function handleUpdateProvider({
     params.injectionTemplates = b.injection_templates;
   if (b.app_type !== undefined) params.appType = b.app_type;
   if (b.identity_url !== undefined) params.identityUrl = b.identity_url;
-  if (b.identity_method !== undefined) params.identityMethod = b.identity_method;
+  if (b.identity_method !== undefined)
+    params.identityMethod = b.identity_method;
   if (b.identity_headers !== undefined)
     params.identityHeaders = b.identity_headers;
   if (b.identity_body !== undefined) params.identityBody = b.identity_body;
   if (b.identity_response_paths !== undefined)
     params.identityResponsePaths = b.identity_response_paths;
-  if (b.identity_format !== undefined) params.identityFormat = b.identity_format;
+  if (b.identity_format !== undefined)
+    params.identityFormat = b.identity_format;
   if (b.identity_ok_field !== undefined)
     params.identityOkField = b.identity_ok_field;
   if (b.setup_notes !== undefined) params.setupNotes = b.setup_notes;
@@ -308,16 +326,49 @@ async function handleDeleteProvider({
 // Route definitions
 // ---------------------------------------------------------------------------
 
+/**
+ * Lightweight summary projection of an OAuth provider returned by the catalog
+ * list endpoint. Mirrors `SerializedProviderSummary` from the provider
+ * serializer (snake_case to match the HTTP API convention).
+ */
+export const oauthProviderSummarySchema = z.object({
+  provider_key: z.string(),
+  display_name: z.string().nullable(),
+  description: z.string().nullable(),
+  dashboard_url: z.string().nullable(),
+  client_id_placeholder: z.string().nullable(),
+  requires_client_secret: z.boolean(),
+  logo_url: z.string().nullable(),
+  supports_managed_mode: z.boolean(),
+  managed_service_is_paid: z.boolean(),
+  feature_flag: z.string().nullable(),
+});
+
+/**
+ * Response for the single-provider detail endpoint. The `provider` field is the
+ * full serialized provider configuration — an open-ended, admin-defined object
+ * whose keys depend on the stored row (parsed JSON blobs, identity templates,
+ * and forwarded columns), so it is intentionally typed as an open record rather
+ * than a closed schema. `oauth_callback_url` is the ingress callback URL the
+ * web UI consumes (null when ingress is not configured).
+ */
+export const oauthProviderDetailSchema = z.object({
+  provider: z.record(z.string(), z.unknown()),
+  oauth_callback_url: z.string().nullable(),
+});
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "oauth_providers_get",
     endpoint: "oauth/providers",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List OAuth providers",
-    description:
-      "List all registered OAuth providers with optional filtering.",
+    description: "List all registered OAuth providers with optional filtering.",
     tags: ["oauth"],
-    requirePolicyEnforcement: true,
     handler: handleListProviders,
     queryParams: [
       {
@@ -326,26 +377,35 @@ export const ROUTES: RouteDefinition[] = [
         description: "Filter by managed mode support (true/false)",
       },
     ],
+    responseBody: z.object({
+      providers: z.array(oauthProviderSummarySchema),
+    }),
   },
   {
     operationId: "oauth_providers_by_providerKey_get",
     endpoint: "oauth/providers/:providerKey",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get OAuth provider",
     description: "Get a single OAuth provider by key.",
     tags: ["oauth"],
-    requirePolicyEnforcement: true,
     handler: handleGetProvider,
+    responseBody: oauthProviderDetailSchema,
   },
   {
     operationId: "oauth_providers_post",
     endpoint: "oauth/providers",
     method: "POST",
-    policyKey: "oauth/providers.register",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Register OAuth provider",
     description: "Register a new OAuth provider configuration.",
     tags: ["oauth"],
-    requirePolicyEnforcement: true,
     responseStatus: "201",
     handler: handleRegisterProvider,
   },
@@ -353,23 +413,27 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "oauth_providers_by_providerKey_patch",
     endpoint: "oauth/providers/:providerKey",
     method: "PATCH",
-    policyKey: "oauth/providers.update",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Update OAuth provider",
     description: "Update an existing custom OAuth provider configuration.",
     tags: ["oauth"],
-    requirePolicyEnforcement: true,
     handler: handleUpdateProvider,
   },
   {
     operationId: "oauth_providers_by_providerKey_delete",
     endpoint: "oauth/providers/:providerKey",
     method: "DELETE",
-    policyKey: "oauth/providers.delete",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Delete OAuth provider",
     description:
       "Delete a custom OAuth provider and optionally cascade-delete its apps and connections.",
     tags: ["oauth"],
-    requirePolicyEnforcement: true,
     handler: handleDeleteProvider,
   },
 ];

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

@@ -14,6 +14,8 @@
  *     registered callback routes for this assistant.
  */
 
+import { z } from "zod";
+
 import { isPlatformRemote } from "../../config/env-registry.js";
 import {
   registerCallbackRoute,
@@ -27,6 +29,7 @@ import {
 } from "../../security/secure-keys.js";
 import { buildAssistantEvent } from "../assistant-event.js";
 import { assistantEventHub } from "../assistant-event-hub.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
   InternalError,
@@ -46,13 +49,80 @@ const CREDENTIAL_KEYS = {
   userId: { service: "vellum", field: "platform_user_id" },
 } as const;
 
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const VelayTunnelStatusSchema = z.object({
+  connected: z.boolean(),
+  publicUrl: z.string().nullable(),
+});
+
+const PlatformStatusResponseSchema = z.object({
+  isPlatform: z.boolean(),
+  baseUrl: z.string(),
+  assistantId: z.string(),
+  hasAssistantApiKey: z.boolean(),
+  hasWebhookSecret: z.boolean(),
+  available: z.boolean(),
+  organizationId: z.string().nullable(),
+  userId: z.string().nullable(),
+  velayTunnel: VelayTunnelStatusSchema.nullable(),
+});
+type PlatformStatusResponse = z.infer<typeof PlatformStatusResponseSchema>;
+
+const PlatformConnectResponseSchema = z.object({
+  alreadyConnected: z.boolean().optional(),
+  baseUrl: z.string().optional(),
+  showPlatformLogin: z.boolean().optional(),
+});
+type PlatformConnectResponse = z.infer<typeof PlatformConnectResponseSchema>;
+
+const PlatformDisconnectResponseSchema = z.object({
+  disconnected: z.literal(true),
+  previousBaseUrl: z.string().nullable(),
+});
+type PlatformDisconnectResponse = z.infer<
+  typeof PlatformDisconnectResponseSchema
+>;
+
+const CallbackRouteRegisterRequestSchema = z.object({
+  path: z.string(),
+  type: z.string(),
+});
+
+const CallbackRouteRegisterResponseSchema = z.object({
+  callbackUrl: z.string(),
+  callbackPath: z.string(),
+  type: z.string(),
+});
+type CallbackRouteRegisterResponse = z.infer<
+  typeof CallbackRouteRegisterResponseSchema
+>;
+
+const CallbackRouteSchema = z.object({
+  id: z.string(),
+  assistant_id: z.string(),
+  type: z.string(),
+  callback_path: z.string(),
+  callback_url: z.string(),
+  source_identifier: z.string().nullable(),
+});
+
+const CallbackRoutesListResponseSchema = z.object({
+  routes: z.array(CallbackRouteSchema),
+});
+type CallbackRoutesListResponse = z.infer<
+  typeof CallbackRoutesListResponseSchema
+>;
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 
 async function handlePlatformStatus(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformStatusResponse> {
   const [context, velayTunnel] = await Promise.all([
     resolvePlatformCallbackRegistrationContext(),
     ipcGetVelayStatus().catch(() => null),
@@ -93,7 +163,7 @@ async function handlePlatformStatus(
 
 async function handlePlatformConnect(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformConnectResponse> {
   // Check if already connected
   const [existingUrl, existingApiKey] = await Promise.all([
     getSecureKeyAsync(
@@ -127,7 +197,7 @@ async function handlePlatformConnect(
 
 async function handlePlatformDisconnect(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformDisconnectResponse> {
   // Reject if running inside a platform host
   if (isPlatformRemote()) {
     throw new UnprocessableEntityError(
@@ -196,7 +266,7 @@ async function handlePlatformDisconnect(
 
 async function handleCallbackRoutesRegister(
   args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<CallbackRouteRegisterResponse> {
   const { path, type } = (args.body ?? {}) as {
     path?: string;
     type?: string;
@@ -234,7 +304,7 @@ async function handleCallbackRoutesRegister(
 
 async function handleCallbackRoutesList(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<CallbackRoutesListResponse> {
   const context = await resolvePlatformCallbackRegistrationContext();
 
   if (!context.platformBaseUrl || !context.authHeader) {
@@ -273,6 +343,7 @@ async function handleCallbackRoutesList(
     type: string;
     callback_path: string;
     callback_url: string;
+    source_identifier: string | null;
   }>;
 
   return { routes };
@@ -287,50 +358,76 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "platform_status",
     endpoint: "platform/status",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Get platform deployment context and connection status",
     description:
       "Aggregates platform context, credentials, assistant ID, webhook secret, and Velay tunnel status.",
     tags: ["platform"],
     handler: handlePlatformStatus,
+    responseBody: PlatformStatusResponseSchema,
   },
   {
     operationId: "platform_connect",
     endpoint: "platform/connect",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Connect to the Vellum Platform",
     description:
       "Checks existing credentials and emits the show_platform_login signal for connected clients to show a login UI.",
     tags: ["platform"],
     handler: handlePlatformConnect,
+    responseBody: PlatformConnectResponseSchema,
   },
   {
     operationId: "platform_disconnect",
     endpoint: "platform/disconnect",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Disconnect from the Vellum Platform",
     description:
       "Deletes stored platform credentials and emits platform_disconnected signal to connected clients.",
     tags: ["platform"],
     handler: handlePlatformDisconnect,
+    responseBody: PlatformDisconnectResponseSchema,
   },
   {
     operationId: "platform_callback_routes_register",
     endpoint: "platform/callback-routes/register",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "Register a platform callback route",
     description:
       "Registers a callback route with the platform gateway for inbound provider webhooks.",
     tags: ["platform"],
     handler: handleCallbackRoutesRegister,
+    requestBody: CallbackRouteRegisterRequestSchema,
+    responseBody: CallbackRouteRegisterResponseSchema,
   },
   {
     operationId: "platform_callback_routes_list",
     endpoint: "platform/callback-routes",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     summary: "List registered platform callback routes",
     description:
       "Lists all callback routes registered with the platform for this assistant.",
     tags: ["platform"],
     handler: handleCallbackRoutesList,
+    responseBody: CallbackRoutesListResponseSchema,
   },
 ];

package/src/runtime/routes/playground/__tests__/force-compact.test.ts

@@ -65,8 +65,12 @@ function makeFakeConversation(
     ...options.result,
   };
 
+  let processing = options.processing ?? false;
   const fake = {
-    processing: options.processing ?? false,
+    isProcessing: () => processing,
+    setProcessing: (value: boolean) => {
+      processing = value;
+    },
     getMessages(): Message[] {
       if (!returnedAfter && calls === 0) return messagesBefore;
       return messagesAfter;
@@ -85,9 +89,7 @@ function makeFakeConversation(
 }
 
 function findRoute() {
-  const route = ROUTES.find(
-    (r) => r.operationId === "playgroundForceCompact",
-  );
+  const route = ROUTES.find((r) => r.operationId === "playgroundForceCompact");
   if (!route) throw new Error("force-compact route not registered");
   return route;
 }
@@ -97,11 +99,12 @@ function findRoute() {
 // ---------------------------------------------------------------------------
 
 describe("playgroundForceCompact", () => {
-  test("exposes a single POST route with the expected endpoint + policy key", () => {
+  test("exposes a single POST route with the expected endpoint", () => {
     const route = findRoute();
     expect(route.endpoint).toBe("conversations/:id/playground/compact");
     expect(route.method).toBe("POST");
-    expect(route.policyKey).toBe("conversations/playground/compact");
+    // Intentionally unprotected — handler gates on assertPlaygroundEnabled()
+    expect(route.policy).toBeNull();
   });
 
   test("throws RouteError with conversation_not_found code when the conversation is missing", async () => {

package/src/runtime/routes/playground/__tests__/inject-failures.test.ts

@@ -45,10 +45,14 @@ mock.module("../helpers.js", () => ({
 import { RouteError } from "../../errors.js";
 import { ROUTES } from "../index.js";
 
-interface MockConversation {
-  readonly conversationId: string;
+interface MockCompactionCircuit {
   consecutiveCompactionFailures: number;
   compactionCircuitOpenUntil: number | null;
+}
+
+interface MockConversation {
+  readonly conversationId: string;
+  agentLoop: { compactionCircuit: MockCompactionCircuit };
   contextCompactedMessageCount: number;
   contextCompactedAt: number | null;
   sentMessages: ServerMessage[];
@@ -60,8 +64,12 @@ function makeConversation(id = "conv-playground-test"): MockConversation {
   const sentMessages: ServerMessage[] = [];
   return {
     conversationId: id,
-    consecutiveCompactionFailures: 0,
-    compactionCircuitOpenUntil: null,
+    agentLoop: {
+      compactionCircuit: {
+        consecutiveCompactionFailures: 0,
+        compactionCircuitOpenUntil: null,
+      },
+    },
     contextCompactedMessageCount: 0,
     contextCompactedAt: null,
     sentMessages,
@@ -109,9 +117,10 @@ describe("POST /v1/conversations/:id/playground/inject-compaction-failures", ()
     })) as Record<string, unknown>;
     const afterNow = Date.now();
 
-    expect(conversation.consecutiveCompactionFailures).toBe(3);
-    expect(conversation.compactionCircuitOpenUntil).not.toBeNull();
-    const openUntil = conversation.compactionCircuitOpenUntil!;
+    const circuit = conversation.agentLoop.compactionCircuit;
+    expect(circuit.consecutiveCompactionFailures).toBe(3);
+    expect(circuit.compactionCircuitOpenUntil).not.toBeNull();
+    const openUntil = circuit.compactionCircuitOpenUntil!;
     expect(openUntil).toBeGreaterThanOrEqual(beforeNow + 60_000);
     expect(openUntil).toBeLessThanOrEqual(afterNow + 60_000);
 
@@ -128,16 +137,18 @@ describe("POST /v1/conversations/:id/playground/inject-compaction-failures", ()
 
   test("clears the circuit and emits compaction_circuit_closed on circuitOpenForMs: 0", async () => {
     const conversation = makeConversation("conv-close");
-    conversation.compactionCircuitOpenUntil = Date.now() + 10_000;
-    conversation.consecutiveCompactionFailures = 3;
+    conversation.agentLoop.compactionCircuit.compactionCircuitOpenUntil =
+      Date.now() + 10_000;
+    conversation.agentLoop.compactionCircuit.consecutiveCompactionFailures = 3;
     _mockConversation = conversation;
 
     await invoke(conversation.conversationId, {
       circuitOpenForMs: 0,
     });
 
-    expect(conversation.compactionCircuitOpenUntil).toBeNull();
-    expect(conversation.consecutiveCompactionFailures).toBe(3);
+    const circuit = conversation.agentLoop.compactionCircuit;
+    expect(circuit.compactionCircuitOpenUntil).toBeNull();
+    expect(circuit.consecutiveCompactionFailures).toBe(3);
 
     expect(conversation.sentMessages).toHaveLength(1);
     expect(conversation.sentMessages[0]).toEqual({
@@ -148,14 +159,18 @@ describe("POST /v1/conversations/:id/playground/inject-compaction-failures", ()
 
   test("is a no-op on the event channel when circuitOpenForMs: 0 but the breaker is already closed", async () => {
     const conversation = makeConversation("conv-already-closed");
-    expect(conversation.compactionCircuitOpenUntil).toBeNull();
+    expect(
+      conversation.agentLoop.compactionCircuit.compactionCircuitOpenUntil,
+    ).toBeNull();
     _mockConversation = conversation;
 
     const body = (await invoke(conversation.conversationId, {
       circuitOpenForMs: 0,
     })) as Record<string, unknown>;
 
-    expect(conversation.compactionCircuitOpenUntil).toBeNull();
+    expect(
+      conversation.agentLoop.compactionCircuit.compactionCircuitOpenUntil,
+    ).toBeNull();
     expect(conversation.sentMessages).toHaveLength(0);
     expect(body.compactionCircuitOpenUntil).toBeNull();
     expect(body.isCircuitOpen).toBe(false);
@@ -175,7 +190,9 @@ describe("POST /v1/conversations/:id/playground/inject-compaction-failures", ()
       expect((err as RouteError).statusCode).toBe(400);
     }
 
-    expect(conversation.consecutiveCompactionFailures).toBe(0);
+    expect(
+      conversation.agentLoop.compactionCircuit.consecutiveCompactionFailures,
+    ).toBe(0);
     expect(conversation.sentMessages).toHaveLength(0);
   });
 
@@ -193,7 +210,9 @@ describe("POST /v1/conversations/:id/playground/inject-compaction-failures", ()
       expect((err as RouteError).statusCode).toBe(400);
     }
 
-    expect(conversation.compactionCircuitOpenUntil).toBeNull();
+    expect(
+      conversation.agentLoop.compactionCircuit.compactionCircuitOpenUntil,
+    ).toBeNull();
     expect(conversation.sentMessages).toHaveLength(0);
   });
 
@@ -210,7 +229,9 @@ describe("POST /v1/conversations/:id/playground/inject-compaction-failures", ()
       expect(err).toBeInstanceOf(RouteError);
       expect((err as RouteError).statusCode).toBe(400);
     }
-    expect(conversation.consecutiveCompactionFailures).toBe(0);
+    expect(
+      conversation.agentLoop.compactionCircuit.consecutiveCompactionFailures,
+    ).toBe(0);
   });
 
   test("response body includes the full CompactionStateResponse shape", async () => {

package/src/runtime/routes/playground/__tests__/reset-circuit.test.ts

@@ -69,8 +69,7 @@ function makeFakeConversation(
     ...overrides,
   };
   const sent: ServerMessage[] = [];
-  const fake = {
-    conversationId: "conv-abc",
+  const compactionCircuit = {
     get consecutiveCompactionFailures(): number {
       return state.consecutiveCompactionFailures;
     },
@@ -83,6 +82,10 @@ function makeFakeConversation(
     set compactionCircuitOpenUntil(value: number | null) {
       state.compactionCircuitOpenUntil = value;
     },
+  };
+  const fake = {
+    conversationId: "conv-abc",
+    agentLoop: { compactionCircuit },
     get contextCompactedMessageCount(): number {
       return state.contextCompactedMessageCount;
     },
@@ -113,7 +116,8 @@ describe("reset-circuit route — metadata", () => {
       "conversations/:id/playground/reset-compaction-circuit",
     );
     expect(route.method).toBe("POST");
-    expect(route.policyKey).toBe("conversations/playground/reset-circuit");
+    // Intentionally unprotected — handler gates on assertPlaygroundEnabled()
+    expect(route.policy).toBeNull();
     expect(route.tags).toContain("playground");
   });
 });

package/src/runtime/routes/playground/__tests__/state.test.ts

@@ -53,8 +53,14 @@ function makeFakeConversation(
     getMessages: () => messages,
     contextCompactedMessageCount: overrides.contextCompactedMessageCount ?? 0,
     contextCompactedAt: overrides.contextCompactedAt ?? null,
-    consecutiveCompactionFailures: overrides.consecutiveCompactionFailures ?? 0,
-    compactionCircuitOpenUntil: overrides.compactionCircuitOpenUntil ?? null,
+    agentLoop: {
+      compactionCircuit: {
+        consecutiveCompactionFailures:
+          overrides.consecutiveCompactionFailures ?? 0,
+        compactionCircuitOpenUntil:
+          overrides.compactionCircuitOpenUntil ?? null,
+      },
+    },
   } as unknown as Conversation;
 }
 
@@ -74,7 +80,8 @@ async function invokeRoute(id = "conv-abc") {
 describe("GET conversations/:id/playground/compaction-state", () => {
   test("registers the expected route definition", () => {
     const route = findRoute();
-    expect(route.policyKey).toBe("conversations/playground/state");
+    // Intentionally unprotected — handler gates on assertPlaygroundEnabled()
+    expect(route.policy).toBeNull();
     expect(route.tags).toEqual(["playground"]);
   });
 

package/src/runtime/routes/playground/force-compact.ts

@@ -22,7 +22,7 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "playgroundForceCompact",
     endpoint: "conversations/:id/playground/compact",
     method: "POST",
-    policyKey: "conversations/playground/compact",
+    policy: null,
     summary: "Force compaction on a conversation (dev-only playground)",
     tags: ["playground"],
     pathParams: [{ name: "id", type: "uuid" }],
@@ -35,7 +35,7 @@ export const ROUTES: RouteDefinition[] = [
         throwConversationNotFound(id);
       }
 
-      if (conversation.processing) {
+      if (conversation.isProcessing()) {
         throw new ConflictError(
           "Compaction already in progress for this conversation",
         );

package/src/runtime/routes/playground/helpers.ts

@@ -7,9 +7,9 @@
  */
 
 import type { Conversation } from "../../../daemon/conversation.js";
+import { findConversation } from "../../../daemon/conversation-registry.js";
 import {
   destroyActiveConversation,
-  findConversation,
   getOrCreateConversation,
 } from "../../../daemon/conversation-store.js";
 import {
@@ -96,7 +96,6 @@ export async function addPlaygroundMessage(
     conversationId,
     role,
     contentJson,
-    undefined,
     options,
   );
   return { id: persisted.id };