@vellumai/assistant 0.12.0-staging.1 → 0.12.0

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

@@ -0,0 +1,172 @@
+/**
+ * Route handlers for the activation checklist.
+ *
+ * GET  /v1/activation/progress            : read the progress resource
+ * POST /v1/activation/tasks/:taskId/start : link a task to a conversation
+ * POST /v1/activation/dismiss             : record a dismissed surface
+ *
+ * Every route returns the full progress resource so a client never has to
+ * follow a write with a read. The task catalog itself is client-side: the
+ * daemon only stores opaque task and list identifiers.
+ */
+
+import type { z } from "zod";
+
+import {
+  dismissActivation,
+  readActivationProgress,
+  startActivationTask,
+} from "../../activation/progress-store.js";
+import {
+  ActivationDismissRequestSchema,
+  ActivationProgressSchema,
+  ActivationTaskStartRequestSchema,
+} from "../../api/responses/activation.js";
+import { getConversation } from "../../persistence/conversation-crud.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { getOriginClientId } from "../sync/resource-sync-events.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+function parseBody<S extends z.ZodType>(
+  schema: S,
+  body: Record<string, unknown> | undefined,
+): z.infer<S> {
+  const parsed = schema.safeParse(body ?? {});
+  if (!parsed.success) {
+    throw new BadRequestError(
+      `Invalid activation request body: ${parsed.error.issues[0]?.message ?? "unknown field"}`,
+    );
+  }
+  return parsed.data;
+}
+
+function handleGetActivationProgress() {
+  return readActivationProgress();
+}
+
+/**
+ * Link a task to the conversation its prompt is being sent to.
+ *
+ * The conversation is looked up the same way `POST /v1/messages` looks up an
+ * explicit `conversationId`, and a miss is the same 404, because the two
+ * calls are two halves of one launch: a link recorded against a row that no
+ * longer exists leaves the task stuck on Working with an action that opens
+ * nothing, while the send that follows fails anyway. Answering 404 instead
+ * tells the client the link was refused outright, which is the one answer
+ * that lets it take its freshly created conversation back.
+ *
+ * The store asks the same question again inside its lock, because the answer
+ * can change while a contended mutation waits its turn: a deletion that
+ * lands in that window has already run its own activation cleanup, so a link
+ * written afterwards is the one nothing will ever clear. The check here is
+ * the fast path that answers without taking a lock at all.
+ */
+async function handleStartActivationTask({
+  pathParams = {},
+  body,
+  headers,
+}: RouteHandlerArgs) {
+  const { conversationId, listId } = parseBody(
+    ActivationTaskStartRequestSchema,
+    body,
+  );
+  const conversationExists = () => getConversation(conversationId) !== null;
+  if (!conversationExists()) {
+    throw new NotFoundError(`Conversation ${conversationId} not found`);
+  }
+  const originClientId = getOriginClientId(headers);
+  return startActivationTask({
+    taskId: pathParams.taskId ?? "",
+    conversationId,
+    verify: conversationExists,
+    ...(listId !== undefined ? { listId } : {}),
+    ...(originClientId !== undefined ? { originClientId } : {}),
+  });
+}
+
+async function handleDismissActivation({ body, headers }: RouteHandlerArgs) {
+  const { kind, listId } = parseBody(ActivationDismissRequestSchema, body);
+  const originClientId = getOriginClientId(headers);
+  return dismissActivation({
+    kind,
+    ...(listId !== undefined ? { listId } : {}),
+    ...(originClientId !== undefined ? { originClientId } : {}),
+  });
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "activation_progress_get",
+    endpoint: "activation/progress",
+    method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get activation progress",
+    description:
+      "Return the activation checklist progress: the frozen list, dismissed surfaces, and per-task state.",
+    tags: ["activation"],
+    responseBody: ActivationProgressSchema,
+    handler: handleGetActivationProgress,
+  },
+  {
+    operationId: "activation_task_start_post",
+    endpoint: "activation/tasks/:taskId/start",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Start an activation task",
+    description:
+      "Link an activation task to the conversation its prompt was sent to. Idempotent per task; a different conversation replaces the link only while the task is not done.",
+    tags: ["activation"],
+    pathParams: [
+      { name: "taskId", description: "Catalog id of the launched task" },
+    ],
+    requestBody: ActivationTaskStartRequestSchema,
+    responseBody: ActivationProgressSchema,
+    handler: handleStartActivationTask,
+    additionalResponses: {
+      "400": { description: "Malformed task id, list id, or conversation id" },
+      "404": { description: "No such conversation; the link was not recorded" },
+      "409": {
+        description:
+          "Stored progress was written by a newer build; the link was not recorded",
+      },
+      "503": {
+        description:
+          "Stored progress is locked by another process; the link was not recorded",
+      },
+    },
+  },
+  {
+    operationId: "activation_dismiss_post",
+    endpoint: "activation/dismiss",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Dismiss an activation surface",
+    description:
+      "Record that the welcome modal or the celebration modal was dismissed.",
+    tags: ["activation"],
+    requestBody: ActivationDismissRequestSchema,
+    responseBody: ActivationProgressSchema,
+    handler: handleDismissActivation,
+    additionalResponses: {
+      "400": { description: "Malformed dismiss kind or list id" },
+      "409": {
+        description:
+          "Stored progress was written by a newer build; the dismissal was not recorded",
+      },
+      "503": {
+        description:
+          "Stored progress is locked by another process; the dismissal was not recorded",
+      },
+    },
+  },
+];

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

@@ -59,7 +59,12 @@ import {
   invalidateConnectionsAfterCredentialDelete,
 } from "./credential-in-use.js";
 import { InjectionTemplateSchema } from "./credential-prompt-routes.js";
-import { BadRequestError, InternalError } from "./errors.js";
+import { BadRequestError, ForbiddenError, InternalError } from "./errors.js";
+import {
+  isPlatformManagedCredential,
+  type PlatformManagedCredentialAction,
+  platformManagedCredentialRefusal,
+} from "./platform-managed-credentials.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -157,7 +162,12 @@ interface CredentialLookup {
 
 /**
  * Resolve a credential lookup from service+field or UUID.
- * Throws BadRequestError when neither is provided or the UUID is not found.
+ * Throws BadRequestError when neither is provided or the UUID is not found,
+ * and ForbiddenError for a credential the platform owns.
+ *
+ * Every read handler that returns credential material (inspect, reveal)
+ * resolves through here, so the platform-managed refusal sits at the single
+ * point they share and cannot drift apart from the list filter.
  */
 function resolveCredentialLookup(
   body: Record<string, unknown>,
@@ -169,6 +179,7 @@ function resolveCredentialLookup(
   };
 
   if (service && field) {
+    assertNotPlatformManaged(service, field, "read");
     return {
       storageKey: credentialKey(service, field),
       metadata: getCredentialMetadata(service, field),
@@ -182,6 +193,7 @@ function resolveCredentialLookup(
     if (!metadata) {
       throw new BadRequestError("Credential not found");
     }
+    assertNotPlatformManaged(metadata.service, metadata.field, "read");
     return {
       storageKey: credentialKey(metadata.service, metadata.field),
       metadata,
@@ -193,6 +205,29 @@ function resolveCredentialLookup(
   throw new BadRequestError("Either service+field or id is required");
 }
 
+/**
+ * Refuse any use of a credential the platform provisions for itself, whatever
+ * the calling principal. Reads are refused because the API key spends
+ * inference on Vellum's account. Writes are refused because they are a read
+ * by another name: repointing `vellum:platform_base_url` sends the next
+ * platform call, bearing that same key, to a host of the writer's choosing.
+ *
+ * The platform's own provisioning does not come through here. It writes over
+ * `POST /v1/secrets` (Django to vembda to the pod), as does the CLI and the
+ * local-mode connect flow in the web client.
+ */
+function assertNotPlatformManaged(
+  service: string,
+  field: string,
+  action: PlatformManagedCredentialAction,
+): void {
+  if (isPlatformManagedCredential(service, field)) {
+    throw new ForbiddenError(
+      platformManagedCredentialRefusal(service, field, action),
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -200,7 +235,11 @@ function resolveCredentialLookup(
 async function handleCredentialsList({ body }: RouteHandlerArgs) {
   const search = (body as { search?: string } | undefined)?.search;
 
-  let allMetadata = listCredentialMetadata();
+  // Platform-provisioned credentials are not the user's to act on, so they
+  // never become a Settings row (and never a click-to-reveal).
+  let allMetadata = listCredentialMetadata().filter(
+    (m) => !isPlatformManagedCredential(m.service, m.field),
+  );
 
   if (search) {
     const query = search.toLowerCase();
@@ -453,6 +492,8 @@ async function handleCredentialsSet({ body }: RouteHandlerArgs) {
     throw new BadRequestError("value is required");
   }
 
+  assertNotPlatformManaged(service, field, "change");
+
   try {
     return await storeCredentialValue({
       service,
@@ -496,6 +537,8 @@ async function handleCredentialsDelete({ body }: RouteHandlerArgs) {
     throw new BadRequestError("field is required");
   }
 
+  assertNotPlatformManaged(service, field, "change");
+
   assertMetadataWritable();
 
   // The Slack user_token only grants read access to channels the bot isn't a

package/src/runtime/routes/index.ts

@@ -17,6 +17,7 @@ import { ROUTES as MEMORY_V3_ROUTES } from "../../plugins/defaults/memory/src/me
 import { ROUTES as MEMORY_WORKER_ROUTES } from "../../plugins/defaults/memory/src/memory-worker-routes.js";
 import { ROUTES as ACP_CLAUDE_AUTH_ROUTES } from "./acp-claude-auth-routes.js";
 import { ROUTES as ACP_ROUTES } from "./acp-routes.js";
+import { ROUTES as ACTIVATION_ROUTES } from "./activation-routes.js";
 import { ROUTES as APP_MANAGEMENT_ROUTES } from "./app-management-routes.js";
 import { ROUTES as APP_ROUTES } from "./app-routes.js";
 import { ROUTES as APPROVAL_ROUTES } from "./approval-routes.js";
@@ -213,6 +214,7 @@ export const ROUTES: RouteDefinition[] = [
   ...CONVERSATION_COMPACTION_ROUTES,
   ...CONVERSATION_QUERY_ROUTES,
   ...CONVERSATION_STARTER_ROUTES,
+  ...ACTIVATION_ROUTES,
   ...DEBUG_BASH_ROUTES,
   ...DEBUG_ROUTES,
   ...DEFAULT_PROVIDER_ROUTES,

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

@@ -7,6 +7,8 @@
 
 import { readFileSync } from "node:fs";
 
+import { channelForBotProvider } from "@vellumai/service-contracts/channels";
+
 import {
   getConfig,
   loadRawConfig,
@@ -19,7 +21,10 @@ import {
   ServicesSchema,
 } from "../../config/schemas/services.js";
 import type { OAuthConnectionRequest } from "../../oauth/connection.js";
-import { isBinaryOAuthBody, jsonSafeOAuthBody } from "../../oauth/connection.js";
+import {
+  isBinaryOAuthBody,
+  jsonSafeOAuthBody,
+} from "../../oauth/connection.js";
 import {
   resolveOAuthConnection,
   type ResolveOAuthConnectionOptions,
@@ -966,13 +971,21 @@ export async function handleRequest({ body = {} }: RouteHandlerArgs) {
   }
 
   if (response.status === 401 || response.status === 403) {
-    result.hint = managed
-      ? `Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
-        `Run 'assistant oauth status ${b.provider}' to check connection health.\n` +
-        `To reconnect, run 'assistant oauth connect --help'.`
-      : `Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
-        `Run 'assistant oauth status ${b.provider}' to check connection status.\n` +
-        `To reconnect, run 'assistant oauth connect --help'.`;
+    // The recovery steps follow the credential's kind, not the door the
+    // request came through: a channel bot's token was stored by the channel's
+    // setup, so the OAuth status and connect commands cannot repair it.
+    const botChannel = channelForBotProvider(b.provider);
+    result.hint = botChannel
+      ? `Request returned HTTP ${response.status}. The ${botChannel} bot credential was rejected; it may have been revoked or reinstalled with fewer scopes.\n\n` +
+        `Run 'assistant channels get ${botChannel}' to re-probe the channel and see what it reports.\n` +
+        `To reconnect, run the channel's setup skill again.`
+      : managed
+        ? `Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
+          `Run 'assistant oauth status ${b.provider}' to check connection health.\n` +
+          `To reconnect, run 'assistant oauth connect --help'.`
+        : `Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
+          `Run 'assistant oauth status ${b.provider}' to check connection status.\n` +
+          `To reconnect, run 'assistant oauth connect --help'.`;
   } else if (response.status === 404 && isHtmlResponse(response.headers)) {
     // An HTML 404 (rather than a JSON API error) is the signature of a request
     // reaching a valid host but a path that host does not serve — e.g. a

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

@@ -0,0 +1,48 @@
+/**
+ * Credentials the Vellum platform provisions onto a managed assistant pod for
+ * its own use: the API key the daemon authenticates to the managed LLM proxy
+ * with, and the base URL that proxy lives at.
+ *
+ * The platform writes them over `POST /v1/secrets`, and the daemon, the
+ * gateway, and CES read them straight out of the vault. The user never sets
+ * them through the credentials API and can do nothing useful with them there,
+ * so that API treats the pair as neither readable nor writable: omitted from
+ * listings, and refused by inspect, reveal, set, and delete, whatever the
+ * calling principal.
+ *
+ * The two fields travel together because they are one capability. The API key
+ * spends inference on Vellum's account, and the base URL decides which host
+ * receives it: the gateway resolves the platform host from
+ * `vellum:platform_base_url` (see `gateway/src/platform-url.ts`) and then
+ * sends `vellum:assistant_api_key` to it as the bearer. Leaving the URL
+ * writable while hiding the key would hand back the same key by another
+ * route, pointed at a host of the writer's choosing.
+ */
+const MANAGED_PROXY_CREDENTIALS = [
+  { service: "vellum", field: "assistant_api_key" },
+  { service: "vellum", field: "platform_base_url" },
+] as const;
+
+export function isPlatformManagedCredential(
+  service: string,
+  field: string,
+): boolean {
+  return MANAGED_PROXY_CREDENTIALS.some(
+    (c) => c.service === service && c.field === field,
+  );
+}
+
+/** What a caller was trying to do with a platform-managed credential. */
+export type PlatformManagedCredentialAction = "read" | "change";
+
+/** Message the credentials API refuses one of these with. */
+export function platformManagedCredentialRefusal(
+  service: string | undefined,
+  field: string | undefined,
+  action: PlatformManagedCredentialAction,
+): string {
+  const name = service && field ? `${service}:${field}` : "This credential";
+  const verb =
+    action === "read" ? "inspected or revealed" : "changed or deleted";
+  return `${name} is provisioned and owned by the Vellum platform. It cannot be ${verb} through the credentials API.`;
+}

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

@@ -71,19 +71,10 @@ import {
   NotFoundError,
   RouteError,
 } from "./errors.js";
+import { isPlatformManagedCredential } from "./platform-managed-credentials.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("runtime-http");
-const MANAGED_PROXY_CREDENTIALS = [
-  { service: "vellum", field: "assistant_api_key" },
-  { service: "vellum", field: "platform_base_url" },
-] as const;
-
-function isManagedProxyCredential(service: string, field: string): boolean {
-  return MANAGED_PROXY_CREDENTIALS.some(
-    (c) => c.service === service && c.field === field,
-  );
-}
 
 const CES_READY_POLL_INTERVAL_MS = 500;
 const CES_READY_POLL_TIMEOUT_MS = 30_000;
@@ -401,7 +392,7 @@ async function handleAddSecret({ body }: RouteHandlerArgs) {
           setPlatformUserId(effectiveValue || undefined);
         }
       }
-      if (isManagedProxyCredential(service, field)) {
+      if (isPlatformManagedCredential(service, field)) {
         await refreshProvidersAfterSecretChange();
         // Close the first-boot race where the startup capability seed ran before
         // the managed embedding credential was provisioned, leaving skill/CLI
@@ -645,7 +636,7 @@ async function handleDeleteSecret({ body }: RouteHandlerArgs) {
       if (service === "vellum" && field === "platform_user_id") {
         setPlatformUserId(undefined);
       }
-      if (isManagedProxyCredential(service, field)) {
+      if (isPlatformManagedCredential(service, field)) {
         await refreshProvidersAfterSecretChange();
       }
       invalidateConnectionsAfterCredentialDelete(affectedConnections);

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

@@ -22,8 +22,11 @@
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";
+import { posix } from "node:path";
 import { join, relative, resolve, sep } from "node:path";
 
+import { PLUGIN_NOTICES_ROUTE_PREFIX } from "@vellumai/gateway-client";
+
 import {
   getDefaultPluginRouteRoots,
   getDefaultPluginRoutesDir,
@@ -197,6 +200,24 @@ export function isReservedWorkspaceRoutePath(routePath: string): boolean {
   );
 }
 
+/**
+ * True when an `/x/` route path lands in a plugin's `notices/` namespace, the
+ * namespace root included.
+ *
+ * Judged on the path as the handler lookup will see it, not as it was
+ * spelled: the lookup joins the path onto the routes directory, which folds
+ * doubled slashes and `.` segments, and a case-insensitive filesystem serves
+ * `Notices/x` from `notices/x.ts`. Any spelling that resolves into the
+ * namespace counts, so the reservation cannot be sidestepped by respelling.
+ */
+export function isPluginNoticeRoutePath(routePath: string): boolean {
+  const segments = posix.normalize(routePath.replace(/^\/+/, "")).split("/");
+  return (
+    segments[0] === PLUGIN_ROUTE_SEGMENT &&
+    segments[2]?.toLowerCase() === PLUGIN_NOTICES_ROUTE_PREFIX
+  );
+}
+
 /**
  * Enumerate enabled plugins that ship a `routes/` directory, for route
  * discovery. Mirrors {@link resolveRouteLocation}'s plugin resolution — same

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

@@ -15,10 +15,17 @@
  * over both HTTP and IPC.
  */
 
-import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { PLUGIN_NOTICES_ROUTE_PREFIX } from "@vellumai/gateway-client";
+
+import { ACTOR_PRINCIPALS, GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
+import { httpError } from "../http-errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { IDENTITY_HEADERS, RouteResponse } from "./types.js";
 import { UserRouteDispatcher } from "./user-route-dispatcher.js";
+import {
+  isPluginNoticeRoutePath,
+  PLUGIN_ROUTE_SEGMENT,
+} from "./user-route-resolution.js";
 
 const dispatcher = new UserRouteDispatcher();
 
@@ -156,7 +163,88 @@ const METHODS = [
   "OPTIONS",
 ] as const;
 
-export const ROUTES: RouteDefinition[] = METHODS.map((method) => ({
+/**
+ * Serve one request from the handler file at `/x/<routePath>`.
+ *
+ * The matched path is written back as the single `path` param before the
+ * request is synthesized, so a handler sees the same URL whichever route
+ * definition matched and whichever transport carried the request (the IPC
+ * path rebuilds the URL from that param; see {@link reconstructUrl}).
+ */
+async function serveUserRoute(
+  method: string,
+  args: RouteHandlerArgs,
+  routePath: string,
+): Promise<RouteResponse> {
+  const request = synthesizeRequest(method, {
+    ...args,
+    pathParams: { path: routePath },
+  });
+  const response = await dispatcher.dispatch(routePath, request);
+  return decomposeResponse(response);
+}
+
+/**
+ * A plugin's `notices/` routes, served to the gateway alone.
+ *
+ * The gateway posts a notice there when it has decided something on the
+ * plugin's behalf and the plugin has to act on it with its own vendor
+ * credentials, without running a turn (`PLUGIN_ADMISSION_DENIED_NOTICE_PATH`
+ * is the first). An actor client reaching the same path would hand the plugin
+ * a forged decision, so the whole prefix takes the gateway's service
+ * principal only, for every method.
+ *
+ * Listed ahead of the catch-all below: the HTTP router and the gateway's IPC
+ * proxy both take the first definition whose pattern matches, so this policy
+ * only holds while these come first. Two patterns, because a catch-all param
+ * needs at least one character and the namespace root (`routes/notices.ts`,
+ * `routes/notices/index.ts`) is a handler too.
+ *
+ * These patterns match the request as spelled, and only the plain spelling.
+ * A percent-encoded, doubled-slash, `.`-segment or case-folded spelling of
+ * the same path reaches the catch-all instead, which is why the catch-all
+ * refuses the namespace outright (see {@link isPluginNoticeRoutePath}).
+ */
+const PLUGIN_NOTICE_ROUTES: RouteDefinition[] = METHODS.flatMap((method) => {
+  const policy: RouteDefinition["policy"] = {
+    requiredScopes: ["internal.write"],
+    allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+  };
+  const namespace = `x/${PLUGIN_ROUTE_SEGMENT}/:plugin/${PLUGIN_NOTICES_ROUTE_PREFIX}`;
+  const routePath = (args: RouteHandlerArgs, rest?: string) =>
+    [
+      PLUGIN_ROUTE_SEGMENT,
+      args.pathParams?.plugin ?? "",
+      PLUGIN_NOTICES_ROUTE_PREFIX,
+      ...(rest === undefined ? [] : [rest]),
+    ].join("/");
+  return [
+    {
+      operationId: `plugin_notice_root_${method.toLowerCase()}`,
+      endpoint: namespace,
+      method,
+      summary: `Gateway ${method} notice to a plugin (namespace root)`,
+      description: `Dispatches ${method} requests to the root handler of a plugin's reserved ${PLUGIN_NOTICES_ROUTE_PREFIX}/ namespace. Served to the gateway's service principal only: a notice is the gateway's own decision, never a client's.`,
+      tags: ["user-routes"],
+      policy,
+      handler: (args: RouteHandlerArgs) =>
+        serveUserRoute(method, args, routePath(args)),
+    },
+    {
+      operationId: `plugin_notice_route_${method.toLowerCase()}`,
+      endpoint: `${namespace}/:path*`,
+      method,
+      summary: `Gateway ${method} notice to a plugin`,
+      description: `Dispatches ${method} requests under a plugin's reserved ${PLUGIN_NOTICES_ROUTE_PREFIX}/ namespace to that plugin's handler files. Served to the gateway's service principal only: a notice is the gateway's own decision, never a client's.`,
+      tags: ["user-routes"],
+      policy,
+      handler: (args: RouteHandlerArgs) =>
+        serveUserRoute(method, args, routePath(args, args.pathParams?.path)),
+    },
+  ];
+});
+
+const USER_ROUTES: RouteDefinition[] = METHODS.map((method) => ({
   operationId: `user_route_${method.toLowerCase()}`,
   endpoint: "x/:path*",
   method,
@@ -167,12 +255,27 @@ export const ROUTES: RouteDefinition[] = METHODS.map((method) => ({
     requiredScopes: ["settings.read"],
     allowedPrincipalTypes: ACTOR_PRINCIPALS,
   },
-  handler: async (args: RouteHandlerArgs) => {
-    const request = synthesizeRequest(method, args);
-    const response = await dispatcher.dispatch(
-      args.pathParams?.path ?? "",
-      request,
-    );
-    return decomposeResponse(response);
+  handler: (args: RouteHandlerArgs) => {
+    const routePath = args.pathParams?.path ?? "";
+    if (isPluginNoticeRoutePath(routePath)) {
+      // Another spelling of a reserved path. The notice definitions above are
+      // the only ones that serve the namespace, and they saw a request that
+      // did not match them, so this is refused rather than dispatched under
+      // the actor policy. Same answer the policy check gives the plain
+      // spelling, so a prober learns nothing from the respelling.
+      return decomposeResponse(
+        httpError(
+          "FORBIDDEN",
+          "Principal type not permitted for this endpoint",
+          403,
+        ),
+      );
+    }
+    return serveUserRoute(method, args, routePath);
   },
 }));
+
+export const ROUTES: RouteDefinition[] = [
+  ...PLUGIN_NOTICE_ROUTES,
+  ...USER_ROUTES,
+];