@vellumai/assistant 0.4.13 → 0.4.15

package/src/runtime/http-server.ts

@@ -30,39 +30,34 @@ import {
 import { parseChannelId } from "../channels/types.js";
 import {
   getGatewayInternalBaseUrl,
-  getRuntimeGatewayOriginSecret,
   hasUngatedHttpAuthDisabled,
   isHttpAuthDisabled,
-} from "../config/env.js";
-import type { ServerMessage } from "../daemon/ipc-contract.js";
-import { PairingStore } from "../daemon/pairing-store.js";
-import {
-  type Confidence,
-  getAttentionStateByConversationIds,
-  recordConversationSeenSignal,
-  type SignalType,
-} from "../memory/conversation-attention-store.js";
-import * as conversationStore from "../memory/conversation-store.js";
-import * as externalConversationStore from "../memory/external-conversation-store.js";
-import {
-  consumeCallback,
-  consumeCallbackError,
-} from "../security/oauth-callback-registry.js";
-import { getLogger } from "../util/logger.js";
-import { buildAssistantEvent } from "./assistant-event.js";
-import { assistantEventHub } from "./assistant-event-hub.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
-import { sweepFailedEvents } from "./channel-retry-sweep.js";
-import { httpError } from "./http-errors.js";
+} from '../config/env.js';
+import type { ServerMessage } from '../daemon/ipc-contract.js';
+import { PairingStore } from '../daemon/pairing-store.js';
+import { type Confidence, getAttentionStateByConversationIds, recordConversationSeenSignal, type SignalType } from '../memory/conversation-attention-store.js';
+import * as conversationStore from '../memory/conversation-store.js';
+import * as externalConversationStore from '../memory/external-conversation-store.js';
+import { consumeCallback, consumeCallbackError } from '../security/oauth-callback-registry.js';
+import { getLogger } from '../util/logger.js';
+import { buildAssistantEvent } from './assistant-event.js';
+import { assistantEventHub } from './assistant-event-hub.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
+// Auth
+import { authenticateRequest } from './auth/middleware.js';
+import { enforcePolicy, getPolicy } from './auth/route-policy.js';
+import { verifyToken } from './auth/token-service.js';
+import type { AuthContext } from './auth/types.js';
+import { sweepFailedEvents } from './channel-retry-sweep.js';
+import { httpError } from './http-errors.js';
 // Middleware
 import {
   extractBearerToken,
   isLoopbackHost,
   isPrivateNetworkOrigin,
   isPrivateNetworkPeer,
-  verifyBearerToken,
-} from "./middleware/auth.js";
-import { withErrorHandling } from "./middleware/error-handler.js";
+} from './middleware/auth.js';
+import { withErrorHandling } from './middleware/error-handler.js';
 import {
   apiRateLimiter,
   extractClientIp,
@@ -241,6 +236,68 @@ const DEFAULT_HOSTNAME = "127.0.0.1";
 /** Global hard cap on request body size (50 MB). */
 const MAX_REQUEST_BODY_BYTES = 50 * 1024 * 1024;
 
+// ---------------------------------------------------------------------------
+// Parameterized endpoint normalization for policy lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Patterns that map parameterized URLs back to their policy registry keys.
+ * Order matters: more specific patterns must come before general ones so
+ * that e.g. `attachments/{id}/content` matches before `attachments/{id}`.
+ */
+const PARAMETERIZED_ROUTE_PATTERNS: Array<{ re: RegExp; policyBase: string }> = [
+  // calls/{id}/cancel, calls/{id}/answer, calls/{id}/instruction
+  { re: /^calls\/[^/]+\/(cancel|answer|instruction)$/, policyBase: 'calls/$1' },
+  // calls/{id} (GET status)
+  { re: /^calls\/[^/]+$/, policyBase: 'calls' },
+  // contacts/{id}
+  { re: /^contacts\/[^/]+$/, policyBase: 'contacts' },
+  // ingress/members/{id}/block
+  { re: /^ingress\/members\/[^/]+\/block$/, policyBase: 'ingress/members/block' },
+  // ingress/members/{id}
+  { re: /^ingress\/members\/[^/]+$/, policyBase: 'ingress/members' },
+  // ingress/invites/{id}
+  { re: /^ingress\/invites\/[^/]+$/, policyBase: 'ingress/invites' },
+  // integrations/twilio/sms/compliance/tollfree/{sid}
+  { re: /^integrations\/twilio\/sms\/compliance\/tollfree\/[^/]+$/, policyBase: 'integrations/twilio/sms/compliance/tollfree' },
+  // attachments/{id}/content
+  { re: /^attachments\/[^/]+\/content$/, policyBase: 'attachments/content' },
+  // attachments/{id}
+  { re: /^attachments\/[^/]+$/, policyBase: 'attachments' },
+  // trust-rules/manage/{id}
+  { re: /^trust-rules\/manage\/[^/]+$/, policyBase: 'trust-rules/manage' },
+  // interfaces/{path}
+  { re: /^interfaces\/.+$/, policyBase: 'interfaces' },
+];
+
+/**
+ * Strip parameterized segments from an endpoint string so it matches
+ * the base route name used in the policy registry.
+ *
+ * For example, `calls/abc123` becomes `calls`, and
+ * `attachments/abc123/content` becomes `attachments/content`.
+ *
+ * If the raw endpoint already has a direct policy registered (either
+ * bare or with a method qualifier), normalization is skipped. This
+ * prevents literal sub-routes like `calls/start` from being
+ * incorrectly collapsed to `calls`.
+ */
+function normalizeEndpointForPolicy(endpoint: string, method: string): string {
+  // If the exact endpoint (with or without method) has a direct policy, don't normalize
+  if (getPolicy(`${endpoint}:${method}`) || getPolicy(endpoint)) {
+    return endpoint;
+  }
+
+  for (const { re, policyBase } of PARAMETERIZED_ROUTE_PATTERNS) {
+    const match = endpoint.match(re);
+    if (match) {
+      // Support capture-group substitution (e.g. calls/$1 -> calls/cancel)
+      return policyBase.replace(/\$(\d+)/g, (_, idx) => match[Number(idx)] ?? '');
+    }
+  }
+  return endpoint;
+}
+
 export class RuntimeHttpServer {
   private server: ReturnType<typeof Bun.serve> | null = null;
   private port: number;
@@ -260,9 +317,15 @@ export class RuntimeHttpServer {
   private pairingStore = new PairingStore();
   private pairingBroadcast?: (msg: ServerMessage) => void;
   private sendMessageDeps?: SendMessageDeps;
-  private findSession?: (
-    sessionId: string,
-  ) => import("../daemon/session.js").Session | undefined;
+  private findSession?: (sessionId: string) =>
+    | {
+        handleSurfaceAction(
+          surfaceId: string,
+          actionId: string,
+          data?: Record<string, unknown>,
+        ): void;
+      }
+    | undefined;
 
   constructor(options: RuntimeHttpServerOptions = {}) {
     this.port = options.port ?? DEFAULT_PORT;
@@ -528,13 +591,25 @@ export class RuntimeHttpServer {
       return handlePairingStatus(url, this.pairingContext);
     }
 
-    // Require bearer token when configured
-    if (!isHttpAuthDisabled() && this.bearerToken) {
-      const token = extractBearerToken(req);
-      if (!token || !verifyBearerToken(token, this.bearerToken)) {
-        return httpError("UNAUTHORIZED", "Unauthorized", 401);
-      }
+    // Guardian bootstrap and refresh endpoints — before JWT auth because
+    // bootstrap is the first endpoint called to obtain a JWT, and refresh
+    // needs to work when the access token is expired. Bootstrap has its
+    // own loopback IP validation; refresh is secured by the refresh token
+    // in the request body (32 random bytes, hash-only storage).
+    if (path === '/v1/integrations/guardian/vellum/bootstrap' && req.method === 'POST') {
+      return await handleGuardianBootstrap(req, server);
+    }
+    if (path === '/v1/integrations/guardian/vellum/refresh' && req.method === 'POST') {
+      return await handleGuardianRefresh(req);
+    }
+
+    // JWT bearer authentication — replaces the old shared-secret comparison.
+    // authenticateRequest handles dev bypass (DISABLE_HTTP_AUTH) internally.
+    const authResult = authenticateRequest(req);
+    if (!authResult.ok) {
+      return authResult.response;
     }
+    const authContext = authResult.context;
 
     // Per-client-IP rate limiting for /v1/* endpoints. Authenticated requests
     // get a higher limit; unauthenticated requests get a lower limit to reduce
@@ -551,12 +626,7 @@ export class RuntimeHttpServer {
         return rateLimitResponse(result);
       }
       // Attach rate limit headers to the eventual response
-      const originalResponse = await this.handleAuthenticatedRequest(
-        req,
-        url,
-        path,
-        server,
-      );
+      const originalResponse = await this.handleAuthenticatedRequest(req, url, path, server, authContext);
       const headers = new Headers(originalResponse.headers);
       for (const [k, v] of Object.entries(rateLimitHeaders(result))) {
         headers.set(k, v);
@@ -568,20 +638,17 @@ export class RuntimeHttpServer {
       });
     }
 
-    return this.handleAuthenticatedRequest(req, url, path, server);
+    return this.handleAuthenticatedRequest(req, url, path, server, authContext);
   }
 
   /**
    * Handle requests that have already passed auth and rate limiting.
    */
-  private async handleAuthenticatedRequest(
-    req: Request,
-    url: URL,
-    path: string,
-    server: ReturnType<typeof Bun.serve>,
-  ): Promise<Response> {
+  private async handleAuthenticatedRequest(req: Request, url: URL, path: string, server: ReturnType<typeof Bun.serve>, authContext: AuthContext): Promise<Response> {
     // Pairing registration (bearer-authenticated)
-    if (path === "/v1/pairing/register" && req.method === "POST") {
+    if (path === '/v1/pairing/register' && req.method === 'POST') {
+      const policyDenied = enforcePolicy('pairing/register', authContext);
+      if (policyDenied) return policyDenied;
       return await handlePairingRegister(req, this.pairingContext);
     }
 
@@ -600,79 +667,68 @@ export class RuntimeHttpServer {
     }
 
     // Cloud sharing endpoints
-    if (path === "/v1/apps/share" && req.method === "POST") {
-      try {
-        return await handleShareApp(req);
-      } catch (err) {
-        log.error({ err }, "Runtime HTTP handler error sharing app");
-        return httpError("INTERNAL_ERROR", "Internal server error", 500);
+    if (path === '/v1/apps/share' && req.method === 'POST') {
+      const policyDenied = enforcePolicy('apps/share', authContext);
+      if (policyDenied) return policyDenied;
+      try { return await handleShareApp(req); } catch (err) {
+        log.error({ err }, 'Runtime HTTP handler error sharing app');
+        return httpError('INTERNAL_ERROR', 'Internal server error', 500);
       }
     }
 
     const sharedTokenMatch = path.match(/^\/v1\/apps\/shared\/([^/]+)$/);
     if (sharedTokenMatch) {
       const shareToken = sharedTokenMatch[1];
-      if (req.method === "GET") {
-        try {
-          return handleDownloadSharedApp(shareToken);
-        } catch (err) {
-          log.error(
-            { err, shareToken },
-            "Runtime HTTP handler error downloading shared app",
-          );
-          return httpError("INTERNAL_ERROR", "Internal server error", 500);
+      if (req.method === 'GET') {
+        const policyDenied = enforcePolicy('apps/shared:GET', authContext);
+        if (policyDenied) return policyDenied;
+        try { return handleDownloadSharedApp(shareToken); } catch (err) {
+          log.error({ err, shareToken }, 'Runtime HTTP handler error downloading shared app');
+          return httpError('INTERNAL_ERROR', 'Internal server error', 500);
         }
       }
-      if (req.method === "DELETE") {
-        try {
-          return handleDeleteSharedApp(shareToken);
-        } catch (err) {
-          log.error(
-            { err, shareToken },
-            "Runtime HTTP handler error deleting shared app",
-          );
-          return httpError("INTERNAL_ERROR", "Internal server error", 500);
+      if (req.method === 'DELETE') {
+        const policyDenied = enforcePolicy('apps/shared:DELETE', authContext);
+        if (policyDenied) return policyDenied;
+        try { return handleDeleteSharedApp(shareToken); } catch (err) {
+          log.error({ err, shareToken }, 'Runtime HTTP handler error deleting shared app');
+          return httpError('INTERNAL_ERROR', 'Internal server error', 500);
         }
       }
     }
 
-    const sharedMetadataMatch = path.match(
-      /^\/v1\/apps\/shared\/([^/]+)\/metadata$/,
-    );
-    if (sharedMetadataMatch && req.method === "GET") {
-      try {
-        return handleGetSharedAppMetadata(sharedMetadataMatch[1]);
-      } catch (err) {
-        log.error(
-          { err, shareToken: sharedMetadataMatch[1] },
-          "Runtime HTTP handler error getting shared app metadata",
-        );
-        return httpError("INTERNAL_ERROR", "Internal server error", 500);
+    const sharedMetadataMatch = path.match(/^\/v1\/apps\/shared\/([^/]+)\/metadata$/);
+    if (sharedMetadataMatch && req.method === 'GET') {
+      const policyDenied = enforcePolicy('apps/shared/metadata', authContext);
+      if (policyDenied) return policyDenied;
+      try { return handleGetSharedAppMetadata(sharedMetadataMatch[1]); } catch (err) {
+        log.error({ err, shareToken: sharedMetadataMatch[1] }, 'Runtime HTTP handler error getting shared app metadata');
+        return httpError('INTERNAL_ERROR', 'Internal server error', 500);
       }
     }
 
     // Secret management endpoint
-    if (path === "/v1/secrets" && req.method === "POST") {
-      try {
-        return await handleAddSecret(req);
-      } catch (err) {
-        log.error({ err }, "Runtime HTTP handler error adding secret");
-        return httpError("INTERNAL_ERROR", "Internal server error", 500);
+    if (path === '/v1/secrets' && req.method === 'POST') {
+      const policyDenied = enforcePolicy('secrets', authContext);
+      if (policyDenied) return policyDenied;
+      try { return await handleAddSecret(req); } catch (err) {
+        log.error({ err }, 'Runtime HTTP handler error adding secret');
+        return httpError('INTERNAL_ERROR', 'Internal server error', 500);
       }
     }
-    if (path === "/v1/secrets" && req.method === "DELETE") {
-      try {
-        return await handleDeleteSecret(req);
-      } catch (err) {
-        log.error({ err }, "Runtime HTTP handler error deleting secret");
-        return httpError("INTERNAL_ERROR", "Internal server error", 500);
+    if (path === '/v1/secrets' && req.method === 'DELETE') {
+      const policyDenied = enforcePolicy('secrets', authContext);
+      if (policyDenied) return policyDenied;
+      try { return await handleDeleteSecret(req); } catch (err) {
+        log.error({ err }, 'Runtime HTTP handler error deleting secret');
+        return httpError('INTERNAL_ERROR', 'Internal server error', 500);
       }
     }
 
     // Runtime routes: /v1/<endpoint>
     const routeMatch = path.match(/^\/v1\/(.+)$/);
     if (routeMatch) {
-      return this.dispatchEndpoint(routeMatch[1], req, url, server);
+      return this.dispatchEndpoint(routeMatch[1], req, url, server, authContext);
     }
 
     return httpError("NOT_FOUND", "Not found", 404);
@@ -693,11 +749,15 @@ export class RuntimeHttpServer {
       );
     }
 
-    if (!isHttpAuthDisabled() && this.bearerToken) {
+    if (!isHttpAuthDisabled()) {
       const wsUrl = new URL(req.url);
-      const token = wsUrl.searchParams.get("token");
-      if (!token || !verifyBearerToken(token, this.bearerToken)) {
-        return httpError("UNAUTHORIZED", "Unauthorized", 401);
+      const token = wsUrl.searchParams.get('token');
+      if (!token) {
+        return httpError('UNAUTHORIZED', 'Unauthorized', 401);
+      }
+      const jwtResult = verifyToken(token, 'vellum-daemon');
+      if (!jwtResult.ok) {
+        return httpError('UNAUTHORIZED', 'Unauthorized', 401);
       }
     }
 
@@ -788,8 +848,23 @@ export class RuntimeHttpServer {
     req: Request,
     url: URL,
     server: ReturnType<typeof Bun.serve>,
+    authContext: AuthContext,
   ): Promise<Response> {
     const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+
+    // Normalize parameterized endpoints to their base policy key so that
+    // routes like `calls/abc123` match the registered key `calls` and
+    // `attachments/abc123/content` matches `attachments/content`.
+    const normalizedEndpoint = normalizeEndpointForPolicy(endpoint, req.method);
+
+    // Enforce route-level scope/principal policy before invoking any handler.
+    // Try method-specific key first (e.g. "messages:POST"); fall back to the
+    // plain endpoint key only when no method-specific policy is registered.
+    const methodKey = `${normalizedEndpoint}:${req.method}`;
+    const policyKey = getPolicy(methodKey) ? methodKey : normalizedEndpoint;
+    const policyDenied = enforcePolicy(policyKey, authContext);
+    if (policyDenied) return policyDenied;
+
     return withErrorHandling(endpoint, async () => {
       if (endpoint === "health" && req.method === "GET") return handleHealth();
       if (endpoint === "debug" && req.method === "GET") return handleDebug();
@@ -933,28 +1008,20 @@ export class RuntimeHttpServer {
       if (endpoint === "search" && req.method === "GET")
         return handleSearchConversations(url);
 
-      if (endpoint === "messages" && req.method === "POST") {
-        return await handleSendMessage(
-          req,
-          {
-            processMessage: this.processMessage,
-            persistAndProcessMessage: this.persistAndProcessMessage,
-            sendMessageDeps: this.sendMessageDeps,
-            approvalConversationGenerator: this.approvalConversationGenerator,
-          },
-          server,
-        );
+      if (endpoint === 'messages' && req.method === 'POST') {
+        return await handleSendMessage(req, {
+          processMessage: this.processMessage,
+          persistAndProcessMessage: this.persistAndProcessMessage,
+          sendMessageDeps: this.sendMessageDeps,
+          approvalConversationGenerator: this.approvalConversationGenerator,
+        }, authContext);
       }
 
       // Standalone approval endpoints — keyed by requestId, orthogonal to message sending
-      if (endpoint === "confirm" && req.method === "POST")
-        return await handleConfirm(req, server);
-      if (endpoint === "secret" && req.method === "POST")
-        return await handleSecret(req, server);
-      if (endpoint === "trust-rules" && req.method === "POST")
-        return await handleTrustRule(req, server);
-      if (endpoint === "pending-interactions" && req.method === "GET")
-        return handleListPendingInteractions(url, req, server);
+      if (endpoint === 'confirm' && req.method === 'POST') return await handleConfirm(req, authContext);
+      if (endpoint === 'secret' && req.method === 'POST') return await handleSecret(req, authContext);
+      if (endpoint === 'trust-rules' && req.method === 'POST') return await handleTrustRule(req, authContext);
+      if (endpoint === 'pending-interactions' && req.method === 'GET') return handleListPendingInteractions(url, authContext);
 
       // Trust rule CRUD — standalone management (not approval-flow)
       if (endpoint === "trust-rules/manage" && req.method === "GET")
@@ -982,10 +1049,8 @@ export class RuntimeHttpServer {
       }
 
       // Guardian action endpoints — deterministic button-based decisions
-      if (endpoint === "guardian-actions/pending" && req.method === "GET")
-        return handleGuardianActionsPending(req, server);
-      if (endpoint === "guardian-actions/decision" && req.method === "POST")
-        return await handleGuardianActionDecision(req, server);
+      if (endpoint === 'guardian-actions/pending' && req.method === 'GET') return handleGuardianActionsPending(url, authContext);
+      if (endpoint === 'guardian-actions/decision' && req.method === 'POST') return await handleGuardianActionDecision(req, authContext);
 
       // Contacts
       if (endpoint === "contacts" && req.method === "GET")
@@ -1080,17 +1145,8 @@ export class RuntimeHttpServer {
       )
         return await handleCancelOutbound(req);
 
-      // Guardian vellum channel bootstrap
-      if (
-        endpoint === "integrations/guardian/vellum/bootstrap" &&
-        req.method === "POST"
-      )
-        return await handleGuardianBootstrap(req, server);
-      if (
-        endpoint === "integrations/guardian/vellum/refresh" &&
-        req.method === "POST"
-      )
-        return await handleGuardianRefresh(req);
+      // Guardian vellum channel bootstrap and refresh are handled before
+      // JWT auth in routeRequest() — they are not dispatched here.
 
       // Integrations — Twilio config
       if (endpoint === "integrations/twilio/config" && req.method === "GET")
@@ -1187,19 +1243,9 @@ export class RuntimeHttpServer {
       if (endpoint === "channels/conversation" && req.method === "DELETE")
         return await handleDeleteConversation(req, assistantId);
 
-      if (endpoint === "channels/inbound" && req.method === "POST") {
-        const gatewayOriginSecret = getRuntimeGatewayOriginSecret();
-        return await handleChannelInbound(
-          req,
-          this.processMessage,
-          this.bearerToken,
-          assistantId,
-          gatewayOriginSecret,
-          this.approvalCopyGenerator,
-          this.approvalConversationGenerator,
-          this.guardianActionCopyGenerator,
-          this.guardianFollowUpConversationGenerator,
-        );
+      if (endpoint === 'channels/inbound' && req.method === 'POST') {
+        // Route policy enforces svc_gateway principal type.
+        return await handleChannelInbound(req, this.processMessage, assistantId, this.approvalCopyGenerator, this.approvalConversationGenerator, this.guardianActionCopyGenerator, this.guardianFollowUpConversationGenerator);
       }
 
       if (endpoint === "channels/delivery-ack" && req.method === "POST")
@@ -1233,15 +1279,10 @@ export class RuntimeHttpServer {
         }
       }
 
-      // Internal Twilio forwarding endpoints (gateway -> runtime)
-      if (
-        endpoint === "internal/twilio/voice-webhook" &&
-        req.method === "POST"
-      ) {
-        const json = (await req.json()) as {
-          params: Record<string, string>;
-          originalUrl?: string;
-        };
+      // Internal Twilio forwarding endpoints (gateway -> runtime).
+      // Route policy enforces svc_gateway principal type.
+      if (endpoint === 'internal/twilio/voice-webhook' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string>; originalUrl?: string };
         const formBody = new URLSearchParams(json.params).toString();
         const reconstructedUrl = json.originalUrl ?? req.url;
         const fakeReq = new Request(reconstructedUrl, {
@@ -1252,8 +1293,8 @@ export class RuntimeHttpServer {
         return await handleVoiceWebhook(fakeReq);
       }
 
-      if (endpoint === "internal/twilio/status" && req.method === "POST") {
-        const json = (await req.json()) as { params: Record<string, string> };
+      if (endpoint === 'internal/twilio/status' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string> };
         const formBody = new URLSearchParams(json.params).toString();
         const fakeReq = new Request(req.url, {
           method: "POST",
@@ -1263,11 +1304,8 @@ export class RuntimeHttpServer {
         return await handleStatusCallback(fakeReq);
       }
 
-      if (
-        endpoint === "internal/twilio/connect-action" &&
-        req.method === "POST"
-      ) {
-        const json = (await req.json()) as { params: Record<string, string> };
+      if (endpoint === 'internal/twilio/connect-action' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string> };
         const formBody = new URLSearchParams(json.params).toString();
         const fakeReq = new Request(req.url, {
           method: "POST",
@@ -1277,26 +1315,16 @@ export class RuntimeHttpServer {
         return await handleConnectAction(fakeReq);
       }
 
-      if (endpoint === "identity" && req.method === "GET")
-        return handleGetIdentity();
-      if (endpoint === "brain-graph" && req.method === "GET")
-        return handleGetBrainGraph();
-      if (endpoint === "brain-graph-ui" && req.method === "GET")
-        return handleServeBrainGraphUI(this.bearerToken);
-      if (endpoint === "home-base-ui" && req.method === "GET")
-        return handleServeHomeBaseUI(this.bearerToken);
-      if (endpoint === "events" && req.method === "GET")
-        return handleSubscribeAssistantEvents(req, url, { server });
+      if (endpoint === 'identity' && req.method === 'GET') return handleGetIdentity();
+      if (endpoint === 'brain-graph' && req.method === 'GET') return handleGetBrainGraph();
+      if (endpoint === 'brain-graph-ui' && req.method === 'GET') return handleServeBrainGraphUI(this.bearerToken);
+      if (endpoint === 'home-base-ui' && req.method === 'GET') return handleServeHomeBaseUI(this.bearerToken);
+      if (endpoint === 'events' && req.method === 'GET') return handleSubscribeAssistantEvents(req, url, { authContext });
 
       // Internal OAuth callback endpoint (gateway -> runtime)
-      if (endpoint === "internal/oauth/callback" && req.method === "POST") {
-        const json = (await req.json()) as {
-          state: string;
-          code?: string;
-          error?: string;
-        };
-        if (!json.state)
-          return httpError("BAD_REQUEST", "Missing state parameter", 400);
+      if (endpoint === 'internal/oauth/callback' && req.method === 'POST') {
+        const json = await req.json() as { state: string; code?: string; error?: string };
+        if (!json.state) return httpError('BAD_REQUEST', 'Missing state parameter', 400);
         if (json.error) {
           const consumed = consumeCallbackError(json.state, json.error);
           return consumed

package/src/runtime/http-types.ts

@@ -30,6 +30,8 @@ export type ApprovalCopyGenerator = (
 export type ApprovalConversationDisposition =
   | "keep_pending"
   | "approve_once"
+  | "approve_10m"
+  | "approve_thread"
   | "approve_always"
   | "reject";
 
@@ -184,7 +186,15 @@ export interface RuntimeHttpServerOptions {
   /** Dependencies for the POST /v1/messages queue-if-busy handler. */
   sendMessageDeps?: SendMessageDeps;
   /** Lookup an active session by ID (for surface actions). Returns undefined if not found. */
-  findSession?: (sessionId: string) => Session | undefined;
+  findSession?: (sessionId: string) =>
+    | {
+        handleSurfaceAction(
+          surfaceId: string,
+          actionId: string,
+          data?: Record<string, unknown>,
+        ): void;
+      }
+    | undefined;
 }
 
 export interface RuntimeAttachmentMetadata {

package/src/runtime/local-actor-identity.ts

@@ -12,10 +12,12 @@
  */
 
 import type { ChannelId } from '../channels/types.js';
+import { buildIpcAuthContext } from '../daemon/ipc-handler.js';
 import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 import { getActiveBinding } from '../memory/guardian-bindings.js';
 import { getLogger } from '../util/logger.js';
 import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
+import type { AuthContext } from './auth/types.js';
 import { resolveGuardianContext } from './guardian-context-resolver.js';
 import { ensureVellumGuardianBinding } from './guardian-vellum-migration.js';
 
@@ -78,3 +80,26 @@ export function resolveLocalIpcGuardianContext(
   // so downstream consumers see the correct channel provenance.
   return { ...guardianCtx, sourceChannel };
 }
+
+/**
+ * Build an AuthContext for a local IPC connection.
+ *
+ * Produces the same AuthContext shape that HTTP routes receive from JWT
+ * verification, using the `ipc_v1` scope profile. The `actorPrincipalId`
+ * is populated from the vellum guardian binding when available, enabling
+ * downstream code to resolve guardian context using the same
+ * `authContext.actorPrincipalId` path as HTTP sessions.
+ */
+export function resolveLocalIpcAuthContext(sessionId: string): AuthContext {
+  const authContext = buildIpcAuthContext(sessionId);
+
+  // Enrich with the guardian principal ID when a vellum binding exists,
+  // so downstream guardian resolution can use authContext.actorPrincipalId.
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+  const binding = getActiveBinding(assistantId, 'vellum');
+  if (binding) {
+    return { ...authContext, actorPrincipalId: binding.guardianExternalUserId };
+  }
+
+  return authContext;
+}

package/src/runtime/pending-interactions.ts

@@ -18,6 +18,7 @@ export interface ConfirmationDetails {
   allowlistOptions: Array<{ label: string; description: string; pattern: string }>;
   scopeOptions: Array<{ label: string; scope: string }>;
   persistentDecisionsAllowed?: boolean;
+  temporaryOptionsAvailable?: Array<'allow_10m' | 'allow_thread'>;
 }
 
 export interface PendingInteraction {