@vellumai/assistant 0.8.0 → 0.8.1

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

@@ -18,6 +18,9 @@
  *   handles registration, touch (heartbeat), and unregistration (dispose).
  */
 
+import { type IntervalHistogram, monitorEventLoopDelay } from "node:perf_hooks";
+
+import * as Sentry from "@sentry/node";
 import { z } from "zod";
 
 import type { HostProxyCapability } from "../../channels/types.js";
@@ -44,6 +47,175 @@ const log = getLogger("events-routes");
 /** Keep-alive comment sent to idle clients every 7 s by default. */
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 7_000;
 
+/**
+ * Resolution of the event-loop delay histogram, per
+ * https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions.
+ * A 20 ms resolution gives sub-tick visibility while keeping overhead near zero.
+ */
+const EVENT_LOOP_DELAY_RESOLUTION_MS = 20;
+
+/**
+ * How often we reset the cumulative event-loop delay histogram so subsequent
+ * percentile snapshots reflect recent behavior rather than the entire process
+ * lifetime. Matches the default window used by `@fastify/under-pressure` and
+ * `prom-client` for runtime-pressure metrics.
+ */
+const EVENT_LOOP_DELAY_RESET_INTERVAL_MS = 60_000;
+
+let eventLoopDelay: IntervalHistogram | null = null;
+let eventLoopResetTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Lazily start a cumulative event-loop delay histogram on the first SSE
+ * subscriber, and schedule a periodic reset so percentile readings stay
+ * meaningful across long-lived daemon processes.
+ *
+ * Guarded with try/catch because `node:perf_hooks.monitorEventLoopDelay`
+ * was a stub in some older Bun versions; if the runtime ever regresses,
+ * we still emit the shed log + Sentry capture without lag stats rather
+ * than crashing the SSE handler.
+ */
+function ensureEventLoopDelayMonitorStarted(): void {
+  if (eventLoopDelay !== null) return;
+  try {
+    const histogram = monitorEventLoopDelay({
+      resolution: EVENT_LOOP_DELAY_RESOLUTION_MS,
+    });
+    histogram.enable();
+    eventLoopDelay = histogram;
+    eventLoopResetTimer = setInterval(() => {
+      try {
+        histogram.reset();
+      } catch {
+        if (eventLoopResetTimer) {
+          clearInterval(eventLoopResetTimer);
+          eventLoopResetTimer = null;
+        }
+      }
+    }, EVENT_LOOP_DELAY_RESET_INTERVAL_MS);
+    eventLoopResetTimer.unref?.();
+  } catch (err) {
+    log.warn({ err }, "failed to start event-loop delay monitor");
+    eventLoopDelay = null;
+  }
+}
+
+export interface EventLoopDelaySnapshot {
+  mean_ms: number | null;
+  p99_ms: number | null;
+  max_ms: number | null;
+}
+
+function nsToMs(ns: number): number | null {
+  if (!Number.isFinite(ns)) return null;
+  // Round to the nearest microsecond, then express in ms (3 decimal places).
+  return Math.round(ns / 1e3) / 1e3;
+}
+
+function sampleEventLoopDelay(): EventLoopDelaySnapshot {
+  const histogram = eventLoopDelay;
+  if (histogram === null) {
+    return { mean_ms: null, p99_ms: null, max_ms: null };
+  }
+  try {
+    return {
+      mean_ms: nsToMs(histogram.mean),
+      p99_ms: nsToMs(histogram.percentile(99)),
+      max_ms: nsToMs(histogram.max),
+    };
+  } catch {
+    return { mean_ms: null, p99_ms: null, max_ms: null };
+  }
+}
+
+export interface SseSubscriberInstrumentation {
+  subscribedAtMs: number;
+  eventsDelivered: number;
+  heartbeatsSent: number;
+  clientId: string | null;
+  interfaceId: string | null;
+  conversationKey: string | null;
+}
+
+export type SseShedReason = "callback_backpressure" | "heartbeat_backpressure";
+
+export type SseShedReporter = (
+  reason: SseShedReason,
+  inst: SseSubscriberInstrumentation,
+) => void;
+
+/**
+ * Build the structured payload sent to Sentry when an SSE subscriber is
+ * shed under backpressure.
+ *
+ * The conversation key is deliberately excluded: for channel-backed
+ * conversations (WhatsApp, Telegram, etc.) the key embeds external
+ * identifiers — phone numbers, chat IDs — and Sentry contexts are not
+ * run through the PII redactor in `instrument.ts` (only
+ * `exception.values`, `breadcrumbs`, and `extra` are). Correlation
+ * with the client-side `sse_watchdog_fired` event is achieved via the
+ * `client_id` tag + timestamp instead.
+ */
+export function buildSseShedSentryContext(
+  reason: SseShedReason,
+  inst: SseSubscriberInstrumentation,
+  elDelay: EventLoopDelaySnapshot,
+  nowMs: number,
+): Record<string, unknown> {
+  return {
+    reason,
+    subscription_age_ms: nowMs - inst.subscribedAtMs,
+    events_delivered: inst.eventsDelivered,
+    heartbeats_sent: inst.heartbeatsSent,
+    client_id: inst.clientId,
+    interface_id: inst.interfaceId,
+    event_loop_delay_mean_ms: elDelay.mean_ms,
+    event_loop_delay_p99_ms: elDelay.p99_ms,
+    event_loop_delay_max_ms: elDelay.max_ms,
+  };
+}
+
+/**
+ * Report a backpressure-shed event from an SSE subscriber to logs and Sentry.
+ *
+ * SSE subscribers are shed when `controller.desiredSize <= 0`: the consumer
+ * has stopped reading and the stream's bounded queue is full. From the
+ * daemon's side this looks identical to a hung client — and the visible
+ * symptom on the client side is the 45 s idle-watchdog firing (Sentry
+ * issue `sse_watchdog_fired`). Surfacing the shed lets us time-correlate
+ * the two sides and attribute stalls to either backpressure or another
+ * cause (network drop, event-loop starvation, etc.).
+ *
+ * The Sentry call uses level="warning" intentionally: a shed is a
+ * saturation event, not an internal error.
+ */
+const defaultSseShedReporter: SseShedReporter = (reason, inst) => {
+  const elDelay = sampleEventLoopDelay();
+  const sentryContext = buildSseShedSentryContext(
+    reason,
+    inst,
+    elDelay,
+    Date.now(),
+  );
+  log.warn(
+    { ...sentryContext, conversation_key: inst.conversationKey },
+    "sse subscriber shed under backpressure",
+  );
+
+  try {
+    Sentry.withScope((scope) => {
+      scope.setLevel("warning");
+      scope.setTag("sse_shed_reason", reason);
+      if (inst.clientId) scope.setTag("client_id", inst.clientId);
+      if (inst.interfaceId) scope.setTag("interface_id", inst.interfaceId);
+      scope.setContext("sse_shed", sentryContext);
+      Sentry.captureMessage(`sse_subscriber_shed:${reason}`);
+    });
+  } catch {
+    // Never let a telemetry failure break the SSE path.
+  }
+};
+
 /**
  * Stream assistant events as Server-Sent Events.
  *
@@ -63,12 +235,15 @@ const DEFAULT_HEARTBEAT_INTERVAL_MS = 7_000;
  * Options (for testing):
  *   hub               -- override the event hub (defaults to process singleton).
  *   heartbeatIntervalMs -- how often to emit keep-alive comments (default 7 s).
+ *   shedReporter      -- override the callback invoked when a subscriber is shed
+ *                        under backpressure (defaults to log + Sentry capture).
  */
 export function handleSubscribeAssistantEvents(
   args: RouteHandlerArgs,
   options?: {
     hub?: AssistantEventHub;
     heartbeatIntervalMs?: number;
+    shedReporter?: SseShedReporter;
   },
 ): ReadableStream<Uint8Array> {
   const { queryParams, headers, abortSignal } = args;
@@ -108,6 +283,7 @@ export function handleSubscribeAssistantEvents(
   const hub = options?.hub ?? assistantEventHub;
   const heartbeatIntervalMs =
     options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+  const shedReporter = options?.shedReporter ?? defaultSseShedReporter;
 
   const ALL_CAPABILITIES: HostProxyCapability[] = [
     "host_bash",
@@ -134,6 +310,17 @@ export function handleSubscribeAssistantEvents(
   let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   let sub!: AssistantEventSubscription;
 
+  const instrumentation: SseSubscriberInstrumentation = {
+    subscribedAtMs: Date.now(),
+    eventsDelivered: 0,
+    heartbeatsSent: 0,
+    clientId,
+    interfaceId,
+    conversationKey: conversationKey ?? null,
+  };
+
+  ensureEventLoopDelayMonitorStarted();
+
   function cleanup() {
     if (heartbeatTimer) {
       clearInterval(heartbeatTimer);
@@ -151,11 +338,13 @@ export function handleSubscribeAssistantEvents(
     if (!controller) return;
     try {
       if (controller.desiredSize != null && controller.desiredSize <= 0) {
+        shedReporter("callback_backpressure", instrumentation);
         sub.dispose();
         cleanup();
         return;
       }
       controller.enqueue(encoder.encode(formatSseFrame(event)));
+      instrumentation.eventsDelivered += 1;
     } catch {
       sub.dispose();
       cleanup();
@@ -205,10 +394,12 @@ export function handleSubscribeAssistantEvents(
         }
 
         controller.enqueue(encoder.encode(formatSseHeartbeat()));
+        instrumentation.heartbeatsSent += 1;
 
         heartbeatTimer = setInterval(() => {
           try {
             if (controller.desiredSize != null && controller.desiredSize <= 0) {
+              shedReporter("heartbeat_backpressure", instrumentation);
               sub.dispose();
               cleanup();
               return;
@@ -217,6 +408,7 @@ export function handleSubscribeAssistantEvents(
               hub.touchClient(clientId);
             }
             controller.enqueue(encoder.encode(formatSseHeartbeat()));
+            instrumentation.heartbeatsSent += 1;
           } catch {
             sub.dispose();
             cleanup();

package/src/runtime/routes/home-feed-routes.ts

@@ -26,11 +26,9 @@ import {
   type FeedItem,
   feedItemSchema,
   type FeedItemStatus,
-  lowPriorityCollapsedSchema,
   suggestedPromptSchema,
 } from "../../home/feed-types.js";
 import { patchFeedItemStatus, readHomeFeed } from "../../home/feed-writer.js";
-import { runRollupProducer } from "../../home/rollup-producer.js";
 import { getSuggestedPrompts } from "../../home/suggested-prompts.js";
 import {
   addMessage,
@@ -42,26 +40,6 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("home-feed-routes");
 
-/**
- * Debounce window for the on-visit rollup refresh. A GET on the feed
- * route fires the rollup producer fire-and-forget at most once per
- * window — repeat GETs within this interval (e.g. from a client that
- * polls aggressively, or from multiple panels opening in rapid
- * succession) skip the trigger and just return the cached feed.
- */
-const ON_VISIT_REFRESH_DEBOUNCE_MS = 10 * 60 * 1000;
-
-let lastOnVisitRefreshAt = 0;
-
-/**
- * Reset the on-visit debounce gate. Test-only — production callers
- * should never touch this. Exported with an underscore-prefixed name
- * so lint rules can flag misuse.
- */
-export function __resetOnVisitRefreshStateForTests(): void {
-  lastOnVisitRefreshAt = 0;
-}
-
 // ---------------------------------------------------------------------------
 // Response / request schemas
 // ---------------------------------------------------------------------------
@@ -77,7 +55,6 @@ const getHomeFeedResponseSchema = z.object({
   updatedAt: z.string(),
   contextBanner: contextBannerSchema,
   suggestedPrompts: z.array(suggestedPromptSchema),
-  lowPriorityCollapsed: lowPriorityCollapsedSchema,
 });
 
 const patchFeedItemRequestSchema = z.object({
@@ -139,15 +116,11 @@ export async function handleGetHomeFeed({
   const timeAwaySeconds = parsed;
 
   const feed = readHomeFeed();
-  const filtered = feed.items.filter((item) => {
-    if (item.minTimeAway === undefined) return true;
-    return item.minTimeAway <= timeAwaySeconds;
-  });
-
-  const LOW_PRIORITY_THRESHOLD = 30;
-  const lowPriorityItems = filtered.filter(
-    (item) => item.priority < LOW_PRIORITY_THRESHOLD,
-  );
+  // v2 schema dropped per-item `minTimeAway` gating; surface every item
+  // and let the client decide what to render based on its own
+  // session state. `timeAwaySeconds` survives only to feed the
+  // context-banner relative-time label.
+  const filtered = feed.items;
 
   const now = new Date();
   const contextBanner = {
@@ -156,11 +129,6 @@ export async function handleGetHomeFeed({
     newCount: filtered.filter((i) => i.status === "new").length,
   };
 
-  const lowPriorityCollapsed = {
-    count: lowPriorityItems.length,
-    itemIds: lowPriorityItems.map((item) => item.id),
-  };
-
   const suggestedPrompts = await getSuggestedPrompts();
 
   log.debug(
@@ -168,60 +136,20 @@ export async function handleGetHomeFeed({
       timeAwayBucket: timeAwayBucket(timeAwaySeconds),
       totalItems: feed.items.length,
       filteredItems: filtered.length,
-      lowPriorityCount: lowPriorityItems.length,
       newCount: contextBanner.newCount,
       suggestedPromptsCount: suggestedPrompts.length,
     },
     "GET /v1/home/feed",
   );
 
-  maybeTriggerOnVisitRollupRefresh(now);
-
   return {
     items: filtered,
     updatedAt: feed.updatedAt,
     contextBanner,
     suggestedPrompts,
-    lowPriorityCollapsed,
   };
 }
 
-function maybeTriggerOnVisitRollupRefresh(now: Date): void {
-  const nowMs = now.getTime();
-  if (nowMs - lastOnVisitRefreshAt < ON_VISIT_REFRESH_DEBOUNCE_MS) return;
-  const previousRefreshAt = lastOnVisitRefreshAt;
-  lastOnVisitRefreshAt = nowMs;
-  void runRollupProducer(now)
-    .then((result) => {
-      const skippedBeforeLLM =
-        result.skippedReason === "no_provider" ||
-        result.skippedReason === "no_actions" ||
-        result.skippedReason === "in_flight";
-      if (skippedBeforeLLM) {
-        if (lastOnVisitRefreshAt === nowMs) {
-          lastOnVisitRefreshAt = previousRefreshAt;
-        }
-        log.debug(
-          { skippedReason: result.skippedReason },
-          "On-visit rollup refresh skipped; debounce gate rolled back",
-        );
-      } else if (result.skippedReason !== null) {
-        log.debug(
-          { skippedReason: result.skippedReason },
-          "On-visit rollup refresh skipped",
-        );
-      } else {
-        log.info(
-          { wroteCount: result.wroteCount },
-          "On-visit rollup refresh completed",
-        );
-      }
-    })
-    .catch((err) => {
-      log.warn({ err }, "On-visit rollup refresh failed");
-    });
-}
-
 export async function handlePatchFeedItem({
   pathParams = {},
   body,
@@ -309,7 +237,7 @@ export const ROUTES: RouteDefinition[] = [
         type: "integer",
         required: true,
         description:
-          "Seconds since the user was last active in the client. Used to filter items with a `minTimeAway` gate and to compute the context-banner relative-time label.",
+          "Seconds since the user was last active in the client. Used to compute the context-banner relative-time label.",
       },
     ],
     responseBody: getHomeFeedResponseSchema,

package/src/runtime/routes/host-app-control-routes.ts

@@ -19,8 +19,13 @@ import type {
   HostAppControlResultPayload,
   HostAppControlState,
 } from "../../daemon/message-types/host-app-control.js";
+import {
+  enforceSameActorOrThrow,
+  SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+} from "../auth/same-actor.js";
+import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import * as pendingInteractions from "../pending-interactions.js";
-import { BadRequestError } from "./errors.js";
+import { BadRequestError, ForbiddenError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const VALID_STATES: ReadonlySet<HostAppControlState> = new Set([
@@ -33,7 +38,7 @@ const VALID_STATES: ReadonlySet<HostAppControlState> = new Set([
 // POST /v1/host-app-control-result
 // ---------------------------------------------------------------------------
 
-function handleHostAppControlResult({ body }: RouteHandlerArgs) {
+function handleHostAppControlResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -72,6 +77,34 @@ function handleHostAppControlResult({ body }: RouteHandlerArgs) {
     return { accepted: true };
   }
 
+  // Same-actor binding: when the pending interaction has a targetClientId,
+  // validate the submitting client matches and the actor principals align.
+  // Mirrors host-browser / host-cu / host-bash result routes.
+  if (peeked.targetClientId != null) {
+    const headerMap = headers ?? {};
+    const submittingClientId =
+      headerMap["x-vellum-client-id"]?.trim() || undefined;
+    if (!submittingClientId) {
+      throw new BadRequestError(
+        "x-vellum-client-id header is missing for a targeted host app-control request.",
+      );
+    }
+    if (submittingClientId !== peeked.targetClientId) {
+      throw new ForbiddenError(
+        `Client "${submittingClientId}" is not the target for this request (expected "${peeked.targetClientId}"). The targeted client must submit the result.`,
+      );
+    }
+    const submittingActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+      headerMap["x-vellum-actor-principal-id"]?.trim() || undefined,
+    );
+    enforceSameActorOrThrow({
+      sourceActorPrincipalId: submittingActorPrincipalId,
+      targetActorPrincipalId: peeked.targetActorPrincipalId,
+      targetClientId: peeked.targetClientId,
+      op: "host_app_control",
+    });
+  }
+
   const interaction = pendingInteractions.resolve(requestId)!;
   const conversation = findConversation(interaction.conversationId);
   if (!conversation) {
@@ -129,6 +162,15 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       accepted: z.boolean(),
     }),
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted host app-control request.",
+      },
+      "403": {
+        description: SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+      },
+    },
     handler: handleHostAppControlResult,
   },
 ];

package/src/runtime/routes/host-browser-routes.ts

@@ -10,15 +10,22 @@ import {
   markTargetInvalidated,
   publishCdpEvent,
 } from "../../browser-session/events.js";
-import { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
+import {
+  enforceSameActorOrThrow,
+  SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+} from "../auth/same-actor.js";
+import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import * as pendingInteractions from "../pending-interactions.js";
-import { BadRequestError, ConflictError, NotFoundError } from "./errors.js";
+import {
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+} from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 /**
- * Result of attempting to resolve a host browser result frame. Used by both
- * the HTTP endpoint and the WS relay path so they share the same validation
- * and resolution semantics.
+ * Result of attempting to resolve a host browser result frame.
  *
  * Success → the pending interaction was consumed and the conversation was
  * notified.
@@ -30,8 +37,8 @@ export type HostBrowserResultResolution =
   | { ok: true }
   | {
       ok: false;
-      code: "BAD_REQUEST" | "NOT_FOUND" | "CONFLICT";
-      status: 400 | 404 | 409;
+      code: "BAD_REQUEST" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT";
+      status: 400 | 403 | 404 | 409;
       message: string;
     };
 
@@ -40,22 +47,26 @@ export type HostBrowserResultResolution =
  * the pending interaction by requestId, validates its kind is
  * `host_browser`, and forwards the response to the owning conversation.
  *
- * NOTE: The WebSocket `host_browser_result` frame path does NOT go
- * through this function — it is handled by `HostBrowserProxy.resolveResult`
- * directly, which only consults `pendingInteractions` and does not
- * currently perform a kind check. That asymmetry is pre-existing; if
- * the WS path is ever opened to less-trusted clients, it should adopt
- * the same kind-check guard added here.
+ * Same-actor binding: when the pending interaction has a
+ * `targetClientId` (set by the proxy at request time when an actor is
+ * known), the submitting client must (a) identify itself via
+ * `x-vellum-client-id` matching the captured target, and (b) the
+ * submitting actor's principal must match the actor captured for that
+ * client at registration time. Mirrors the host-cu / host-bash result
+ * routes.
  *
  * This function does NOT perform auth — callers are expected to have
  * already authenticated the caller (the HTTP route uses
  * `requireBoundGuardian`).
  */
-export function resolveHostBrowserResultByRequestId(frame: {
-  requestId?: unknown;
-  content?: unknown;
-  isError?: unknown;
-}): HostBrowserResultResolution {
+export function resolveHostBrowserResultByRequestId(
+  frame: {
+    requestId?: unknown;
+    content?: unknown;
+    isError?: unknown;
+  },
+  headers?: Record<string, string | undefined>,
+): HostBrowserResultResolution {
   const { requestId, content, isError } = frame;
 
   if (!requestId || typeof requestId !== "string") {
@@ -86,11 +97,60 @@ export function resolveHostBrowserResultByRequestId(frame: {
     };
   }
 
+  // Validate submitting client matches the targeted client (if any).
+  if (peeked.targetClientId != null) {
+    const headerMap = headers ?? {};
+    const submittingClientId =
+      headerMap["x-vellum-client-id"]?.trim() || undefined;
+    if (!submittingClientId) {
+      return {
+        ok: false,
+        code: "BAD_REQUEST",
+        status: 400,
+        message:
+          "x-vellum-client-id header is missing for a targeted host browser request.",
+      };
+    }
+    if (submittingClientId !== peeked.targetClientId) {
+      return {
+        ok: false,
+        code: "FORBIDDEN",
+        status: 403,
+        message: `Client "${submittingClientId}" is not the target for this request (expected "${peeked.targetClientId}"). The targeted client must submit the result.`,
+      };
+    }
+
+    // Defense-in-depth: require the submitting actor's principal id to match
+    // the actor principal id captured when the target client opened its SSE
+    // stream. This prevents a different authenticated user with knowledge of
+    // both the requestId and target clientId from submitting a result on
+    // behalf of the targeted client.
+    const submittingActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+      headerMap["x-vellum-actor-principal-id"]?.trim() || undefined,
+    );
+    try {
+      enforceSameActorOrThrow({
+        sourceActorPrincipalId: submittingActorPrincipalId,
+        targetActorPrincipalId: peeked.targetActorPrincipalId,
+        targetClientId: peeked.targetClientId,
+        op: "host_browser",
+      });
+    } catch (err) {
+      // enforceSameActorOrThrow throws ForbiddenError on rejection.
+      return {
+        ok: false,
+        code: "FORBIDDEN",
+        status: 403,
+        message: err instanceof Error ? err.message : "Same-actor check failed",
+      };
+    }
+  }
+
   const normalizedContent = typeof content === "string" ? content : "";
   const normalizedIsError = typeof isError === "boolean" ? isError : false;
 
-  const proxy = HostBrowserProxy.instance;
-  proxy.resolveResult(requestId, {
+  const interaction = pendingInteractions.resolve(requestId);
+  interaction?.rpcResolve?.({
     content: normalizedContent,
     isError: normalizedIsError,
   });
@@ -188,13 +248,18 @@ export function resolveHostBrowserSessionInvalidated(frame: {
 // POST /v1/host-browser-result
 // ---------------------------------------------------------------------------
 
-function handleHostBrowserResult({ body }: RouteHandlerArgs) {
+function handleHostBrowserResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
 
-  const resolution = resolveHostBrowserResultByRequestId(body);
+  const resolution = resolveHostBrowserResultByRequestId(
+    body,
+    headers as Record<string, string | undefined> | undefined,
+  );
   if (!resolution.ok) {
+    if (resolution.code === "FORBIDDEN")
+      throw new ForbiddenError(resolution.message);
     if (resolution.code === "NOT_FOUND")
       throw new NotFoundError(resolution.message);
     if (resolution.code === "CONFLICT")
@@ -260,6 +325,22 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       accepted: z.boolean(),
     }),
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted host browser request.",
+      },
+      "403": {
+        description: SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+      },
+      "404": {
+        description: "No pending browser request for the given requestId.",
+      },
+      "409": {
+        description:
+          "Pending interaction kind is not host_browser (mismatched proxy ID space).",
+      },
+    },
     handler: handleHostBrowserResult,
   },
   {

package/src/runtime/routes/http-adapter.ts

@@ -35,6 +35,7 @@ export function routeDefinitionsToHTTPRoutes(
   return routes.map((r) => ({
     endpoint: r.endpoint,
     method: r.method,
+    operationId: r.operationId,
     policyKey:
       r.policyKey ?? r.endpoint.replace(/\/:[^/]+/g, "").replace(/^:/, ""),
     pathParams: r.pathParams,
@@ -47,6 +48,7 @@ export function routeDefinitionsToHTTPRoutes(
     responseStatus:
       typeof r.responseStatus === "string" ? r.responseStatus : undefined,
     additionalResponses: r.additionalResponses,
+    logging: r.logging,
     handler: async ({ req, url, params, authContext }) => {
       try {
         if (r.requireGuardian) {