@vellumai/assistant 0.7.1 → 0.7.3

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

@@ -0,0 +1,134 @@
+/**
+ * Route handler for host app-control result submissions.
+ *
+ * Resolves pending host app-control proxy requests by requestId when the
+ * desktop client returns observation/action results via HTTP. App-control
+ * sessions are per-conversation (not a singleton like host-browser), so we
+ * look up the owning conversation through the pending-interactions tracker
+ * and forward the payload to that conversation's `hostAppControlProxy`.
+ *
+ * Late-delivery tolerance: returns 200 even when no pending interaction
+ * matches (e.g. the conversation was disposed before the client reported
+ * back). The proxy is best-effort — there is no consumer to notify, so a
+ * 4xx would only confuse a client that already executed the action.
+ */
+import { z } from "zod";
+
+import { findConversation } from "../../daemon/conversation-store.js";
+import type {
+  HostAppControlResultPayload,
+  HostAppControlState,
+} from "../../daemon/message-types/host-app-control.js";
+import * as pendingInteractions from "../pending-interactions.js";
+import { BadRequestError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const VALID_STATES: ReadonlySet<HostAppControlState> = new Set([
+  "running",
+  "missing",
+  "minimized",
+]);
+
+// ---------------------------------------------------------------------------
+// POST /v1/host-app-control-result
+// ---------------------------------------------------------------------------
+
+function handleHostAppControlResult({ body }: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
+
+  const {
+    requestId,
+    state,
+    pngBase64,
+    windowBounds,
+    executionResult,
+    executionError,
+  } = body as {
+    requestId?: string;
+    state?: string;
+    pngBase64?: string;
+    windowBounds?: { x: number; y: number; width: number; height: number };
+    executionResult?: string;
+    executionError?: string;
+  };
+
+  if (!requestId || typeof requestId !== "string") {
+    throw new BadRequestError("requestId is required");
+  }
+
+  if (!state || !VALID_STATES.has(state as HostAppControlState)) {
+    throw new BadRequestError(
+      "state must be one of: running, missing, minimized",
+    );
+  }
+
+  // Late-delivery tolerance: if the pending interaction is already gone (the
+  // proxy timed out, the conversation was disposed, etc.), accept the post
+  // and move on. There is no consumer left to fail loudly to.
+  const peeked = pendingInteractions.get(requestId);
+  if (!peeked || peeked.kind !== "host_app_control") {
+    return { accepted: true };
+  }
+
+  const interaction = pendingInteractions.resolve(requestId)!;
+  const conversation = findConversation(interaction.conversationId);
+  if (!conversation) {
+    return { accepted: true };
+  }
+
+  const payload: HostAppControlResultPayload = {
+    requestId,
+    state: state as HostAppControlState,
+    ...(pngBase64 !== undefined ? { pngBase64 } : {}),
+    ...(windowBounds !== undefined ? { windowBounds } : {}),
+    ...(executionResult !== undefined ? { executionResult } : {}),
+    ...(executionError !== undefined ? { executionError } : {}),
+  };
+
+  conversation.hostAppControlProxy?.resolve(requestId, payload);
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions (shared HTTP + IPC)
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "host_app_control_result",
+    endpoint: "host-app-control-result",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Submit host app-control result",
+    description:
+      "Resolve a pending host app-control request by requestId. Returns 200 even when no pending interaction matches (late delivery is tolerated).",
+    tags: ["host"],
+    requestBody: z.object({
+      requestId: z.string().describe("Pending app-control request ID"),
+      state: z
+        .enum(["running", "missing", "minimized"])
+        .describe("Lifecycle state of the targeted application"),
+      pngBase64: z
+        .string()
+        .describe("Base64 PNG screenshot of the targeted app window")
+        .optional(),
+      windowBounds: z
+        .object({
+          x: z.number(),
+          y: z.number(),
+          width: z.number(),
+          height: z.number(),
+        })
+        .optional(),
+      executionResult: z.string().optional(),
+      executionError: z.string().optional(),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+    handler: handleHostAppControlResult,
+  },
+];

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

@@ -7,10 +7,16 @@
 import { z } from "zod";
 
 import { HostBashProxy } from "../../daemon/host-bash-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,
+  ForbiddenError,
   NotFoundError,
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -19,7 +25,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 // POST /v1/host-bash-result
 // ---------------------------------------------------------------------------
 
-function handleHostBashResult({ body }: RouteHandlerArgs) {
+function handleHostBashResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -36,11 +42,15 @@ function handleHostBashResult({ body }: RouteHandlerArgs) {
     throw new BadRequestError("requestId is required");
   }
 
+  const submittingClientId =
+    headers?.["x-vellum-client-id"]?.trim() || undefined;
+  const submittingActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+    headers?.["x-vellum-actor-principal-id"]?.trim() || undefined,
+  );
+
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
-    throw new NotFoundError(
-      "No pending interaction found for this requestId",
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   if (peeked.kind !== "host_bash") {
@@ -49,9 +59,33 @@ function handleHostBashResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  pendingInteractions.resolve(requestId);
+  const { targetClientId } = peeked;
+  if (targetClientId) {
+    if (!submittingClientId) {
+      throw new BadRequestError(
+        "x-vellum-client-id header is required for targeted host bash requests",
+      );
+    }
+    if (submittingClientId !== targetClientId) {
+      throw new ForbiddenError(
+        `Client "${submittingClientId}" is not the target for this request (expected "${targetClientId}"). The targeted client must submit the result.`,
+      );
+    }
+
+    // Defense-in-depth on top of the client-id header binding above: the
+    // submitting actor's principal must match the actor principal stored
+    // for the target client at SSE subscription time. This prevents a
+    // cross-user submission even when the attacker can guess or spoof the
+    // target's client ID.
+    enforceSameActorOrThrow({
+      sourceActorPrincipalId: submittingActorPrincipalId,
+      targetActorPrincipalId: peeked.targetActorPrincipalId,
+      targetClientId,
+      op: "host_bash",
+    });
+  }
 
-  HostBashProxy.instance.resolve(requestId, {
+  HostBashProxy.instance.resolveResult(requestId, {
     stdout: stdout ?? "",
     stderr: stderr ?? "",
     exitCode: exitCode ?? null,
@@ -84,6 +118,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 bash request.",
+      },
+      "403": {
+        description: SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+      },
+      "404": {
+        description: "No pending interaction found for the given requestId.",
+      },
+      "409": {
+        description:
+          "Pending interaction exists but is of a different kind (e.g. host_file, host_cu).",
+      },
+    },
     handler: handleHostBashResult,
   },
 ];

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

@@ -11,7 +11,8 @@ import {
   publishCdpEvent,
 } from "../../browser-session/events.js";
 import { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
-import { BadRequestError, NotFoundError } from "./errors.js";
+import * as pendingInteractions from "../pending-interactions.js";
+import { BadRequestError, ConflictError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 /**
@@ -29,21 +30,26 @@ export type HostBrowserResultResolution =
   | { ok: true }
   | {
       ok: false;
-      code: "BAD_REQUEST" | "NOT_FOUND";
-      status: 400 | 404;
+      code: "BAD_REQUEST" | "NOT_FOUND" | "CONFLICT";
+      status: 400 | 404 | 409;
       message: string;
     };
 
 /**
- * Shared resolver used by both the HTTP route handler and the WS
- * `host_browser_result` frame handler. Looks up the pending interaction
- * by requestId, validates its kind, and forwards the response to the
- * owning conversation.
+ * Resolver for the `POST /v1/host-browser-result` HTTP route. Looks up
+ * 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.
  *
  * This function does NOT perform auth — callers are expected to have
  * already authenticated the caller (the HTTP route uses
- * `requireBoundGuardian`, the WS path relies on the JWT check performed
- * at WebSocket upgrade time).
+ * `requireBoundGuardian`).
  */
 export function resolveHostBrowserResultByRequestId(frame: {
   requestId?: unknown;
@@ -61,20 +67,30 @@ export function resolveHostBrowserResultByRequestId(frame: {
     };
   }
 
-  const proxy = HostBrowserProxy.instance;
-  if (!proxy.hasPendingRequest(requestId)) {
+  const peeked = pendingInteractions.get(requestId);
+  if (!peeked) {
     return {
       ok: false,
       code: "NOT_FOUND",
       status: 404,
-      message: "No pending interaction found for this requestId",
+      message: "No pending browser request for this requestId",
+    };
+  }
+
+  if (peeked.kind !== "host_browser") {
+    return {
+      ok: false,
+      code: "CONFLICT",
+      status: 409,
+      message: `Pending interaction is of kind "${peeked.kind}", expected "host_browser"`,
     };
   }
 
   const normalizedContent = typeof content === "string" ? content : "";
   const normalizedIsError = typeof isError === "boolean" ? isError : false;
 
-  proxy.resolve(requestId, {
+  const proxy = HostBrowserProxy.instance;
+  proxy.resolveResult(requestId, {
     content: normalizedContent,
     isError: normalizedIsError,
   });
@@ -181,6 +197,42 @@ function handleHostBrowserResult({ body }: RouteHandlerArgs) {
   if (!resolution.ok) {
     if (resolution.code === "NOT_FOUND")
       throw new NotFoundError(resolution.message);
+    if (resolution.code === "CONFLICT")
+      throw new ConflictError(resolution.message);
+    throw new BadRequestError(resolution.message);
+  }
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/host-browser-event
+// ---------------------------------------------------------------------------
+
+function handleHostBrowserEvent({ body }: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
+
+  const resolution = resolveHostBrowserEvent(body);
+  if (!resolution.ok) {
+    throw new BadRequestError(resolution.message);
+  }
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/host-browser-session-invalidated
+// ---------------------------------------------------------------------------
+
+function handleHostBrowserSessionInvalidated({ body }: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
+
+  const resolution = resolveHostBrowserSessionInvalidated(body);
+  if (!resolution.ok) {
     throw new BadRequestError(resolution.message);
   }
 
@@ -210,4 +262,47 @@ export const ROUTES: RouteDefinition[] = [
     }),
     handler: handleHostBrowserResult,
   },
+  {
+    operationId: "host_browser_event",
+    endpoint: "host-browser-event",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Forward a CDP event from the browser extension",
+    description:
+      "Publishes a chrome.debugger.onEvent firing into the runtime-side browser-session event bus.",
+    tags: ["host"],
+    requestBody: z.object({
+      method: z.string().describe("CDP event method name"),
+      params: z.unknown().optional().describe("CDP event parameters"),
+      cdpSessionId: z
+        .string()
+        .optional()
+        .describe("CDP session ID (if target-scoped)"),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+    handler: handleHostBrowserEvent,
+  },
+  {
+    operationId: "host_browser_session_invalidated",
+    endpoint: "host-browser-session-invalidated",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Notify runtime that a CDP session was invalidated",
+    description:
+      "Marks the target as invalidated in the runtime-side browser session registry.",
+    tags: ["host"],
+    requestBody: z.object({
+      targetId: z
+        .string()
+        .optional()
+        .describe("CDP target that was detached"),
+      reason: z.string().optional().describe("Detach reason"),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+    handler: handleHostBrowserSessionInvalidated,
+  },
 ];

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

@@ -7,10 +7,16 @@
 import { z } from "zod";
 
 import { findConversation } from "../../daemon/conversation-store.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,
+  ForbiddenError,
   NotFoundError,
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -19,7 +25,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 // POST /v1/host-cu-result
 // ---------------------------------------------------------------------------
 
-function handleHostCuResult({ body }: RouteHandlerArgs) {
+function handleHostCuResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -58,9 +64,7 @@ function handleHostCuResult({ body }: RouteHandlerArgs) {
 
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
-    throw new NotFoundError(
-      "No pending interaction found for this requestId",
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   if (peeked.kind !== "host_cu") {
@@ -69,13 +73,50 @@ function handleHostCuResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  const interaction = pendingInteractions.resolve(requestId)!;
-  const conversation = findConversation(interaction.conversationId);
+  // Validate submitting client matches the targeted client (if any).
+  if (peeked.targetClientId != null) {
+    const headerMap = (headers as Record<string, string | undefined>) ?? {};
+    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 CU 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.`,
+      );
+    }
+
+    // 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,
+    );
+    enforceSameActorOrThrow({
+      sourceActorPrincipalId: submittingActorPrincipalId,
+      targetActorPrincipalId: peeked.targetActorPrincipalId,
+      targetClientId: peeked.targetClientId,
+      op: "host_cu",
+    });
+  }
+
+  const conversation = findConversation(peeked.conversationId);
   if (!conversation) {
+    pendingInteractions.resolve(requestId);
     throw new NotFoundError("Conversation not found for host CU result");
   }
 
-  conversation.hostCuProxy?.resolve(requestId, {
+  if (!conversation.hostCuProxy) {
+    pendingInteractions.resolve(requestId);
+    throw new NotFoundError("No host CU proxy for conversation");
+  }
+
+  conversation.hostCuProxy.processObservation(requestId, {
     axTree,
     axDiff,
     screenshot,
@@ -103,8 +144,7 @@ export const ROUTES: RouteDefinition[] = [
     method: "POST",
     requireGuardian: true,
     summary: "Submit host CU result",
-    description:
-      "Resolve a pending host computer-use request by requestId.",
+    description: "Resolve a pending host computer-use request by requestId.",
     tags: ["host"],
     requestBody: z.object({
       requestId: z.string().describe("Pending CU request ID"),
@@ -123,6 +163,23 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       accepted: z.boolean(),
     }),
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted host CU request.",
+      },
+      "403": {
+        description: SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+      },
+      "404": {
+        description:
+          "No pending interaction found for the given requestId, or the conversation/proxy no longer exists.",
+      },
+      "409": {
+        description:
+          "Pending interaction exists but is of a different kind (e.g. host_bash, host_file).",
+      },
+    },
     handler: handleHostCuResult,
   },
 ];

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

@@ -7,10 +7,16 @@
 import { z } from "zod";
 
 import { HostFileProxy } from "../../daemon/host-file-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,
+  ForbiddenError,
   NotFoundError,
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -19,7 +25,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 // POST /v1/host-file-result
 // ---------------------------------------------------------------------------
 
-function handleHostFileResult({ body }: RouteHandlerArgs) {
+function handleHostFileResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -37,9 +43,7 @@ function handleHostFileResult({ body }: RouteHandlerArgs) {
 
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
-    throw new NotFoundError(
-      "No pending interaction found for this requestId",
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   if (peeked.kind !== "host_file") {
@@ -48,7 +52,36 @@ function handleHostFileResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  pendingInteractions.resolve(requestId);
+  // Validate submitting client matches the targeted client (if any).
+  if (peeked.targetClientId != null) {
+    const headerMap = (headers as Record<string, string | undefined>) ?? {};
+    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 file 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.`,
+      );
+    }
+
+    // Defense-in-depth: also require the submitting actor's principal id to
+    // match the actor that opened the target client's SSE stream. This blocks
+    // cross-user submissions even if a different user somehow obtains the
+    // target client id.
+    const submittingActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+      headerMap["x-vellum-actor-principal-id"]?.trim() || undefined,
+    );
+    enforceSameActorOrThrow({
+      sourceActorPrincipalId: submittingActorPrincipalId,
+      targetActorPrincipalId: peeked.targetActorPrincipalId,
+      targetClientId: peeked.targetClientId,
+      op: "host_file",
+    });
+  }
 
   HostFileProxy.instance.resolve(requestId, {
     content: content ?? "",
@@ -90,6 +123,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 file request.",
+      },
+      "403": {
+        description: SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+      },
+      "404": {
+        description: "No pending interaction found for the given requestId.",
+      },
+      "409": {
+        description:
+          "Pending interaction exists but is of a different kind (e.g. host_bash, host_cu).",
+      },
+    },
     handler: handleHostFileResult,
   },
 ];