@vellumai/assistant 0.7.0 → 0.7.2

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

@@ -6,10 +6,12 @@
  */
 import { z } from "zod";
 
+import { HostBashProxy } from "../../daemon/host-bash-proxy.js";
 import * as pendingInteractions from "../pending-interactions.js";
 import {
   BadRequestError,
   ConflictError,
+  ForbiddenError,
   NotFoundError,
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -18,7 +20,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");
   }
@@ -35,11 +37,11 @@ function handleHostBashResult({ body }: RouteHandlerArgs) {
     throw new BadRequestError("requestId is required");
   }
 
+  const submittingClientId = headers?.["x-vellum-client-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") {
@@ -48,9 +50,21 @@ function handleHostBashResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  const interaction = 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.`,
+      );
+    }
+  }
 
-  interaction.conversation!.resolveHostBash(requestId, {
+  HostBashProxy.instance.resolveResult(requestId, {
     stdout: stdout ?? "",
     stderr: stderr ?? "",
     exitCode: exitCode ?? null,
@@ -83,6 +97,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 bash request.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this request.",
+      },
+      "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

@@ -10,6 +10,7 @@ import {
   markTargetInvalidated,
   publishCdpEvent,
 } from "../../browser-session/events.js";
+import { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
 import * as pendingInteractions from "../pending-interactions.js";
 import { BadRequestError, ConflictError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -35,15 +36,20 @@ export type HostBrowserResultResolution =
     };
 
 /**
- * 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,15 +67,13 @@ export function resolveHostBrowserResultByRequestId(frame: {
     };
   }
 
-  // Peek first (non-destructive) so we can validate the interaction kind
-  // without accidentally consuming a confirmation or secret interaction.
   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",
     };
   }
 
@@ -82,23 +86,11 @@ export function resolveHostBrowserResultByRequestId(frame: {
     };
   }
 
-  // Validation passed — consume the pending interaction.
-  const interaction = pendingInteractions.resolve(requestId)!;
-
   const normalizedContent = typeof content === "string" ? content : "";
   const normalizedIsError = typeof isError === "boolean" ? isError : false;
 
-  if (!interaction.conversation) {
-    return {
-      ok: false,
-      code: "BAD_REQUEST",
-      status: 400,
-      message:
-        "host_browser pending interaction has no associated conversation",
-    };
-  }
-
-  interaction.conversation.resolveHostBrowser(requestId, {
+  const proxy = HostBrowserProxy.instance;
+  proxy.resolveResult(requestId, {
     content: normalizedContent,
     isError: normalizedIsError,
   });
@@ -203,8 +195,44 @@ function handleHostBrowserResult({ body }: RouteHandlerArgs) {
 
   const resolution = resolveHostBrowserResultByRequestId(body);
   if (!resolution.ok) {
-    if (resolution.code === "NOT_FOUND") throw new NotFoundError(resolution.message);
-    if (resolution.code === "CONFLICT") throw new ConflictError(resolution.message);
+    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);
   }
 
@@ -234,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

@@ -6,19 +6,16 @@
  */
 import { z } from "zod";
 
+import { findConversation } from "../../daemon/conversation-store.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";
 
 // ---------------------------------------------------------------------------
 // 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");
   }
@@ -57,9 +54,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") {
@@ -68,9 +63,32 @@ function handleHostCuResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  const interaction = pendingInteractions.resolve(requestId)!;
+  // Validate submitting client matches the targeted client (if any).
+  if (peeked.targetClientId != null) {
+    const rawClientId = (headers as Record<string, string | undefined>)?.["x-vellum-client-id"];
+    const submittingClientId = rawClientId?.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.`,
+      );
+    }
+  }
+
+  const conversation = findConversation(peeked.conversationId);
+  if (!conversation) {
+    pendingInteractions.resolve(requestId);
+    throw new NotFoundError("Conversation not found for host CU result");
+  }
+
+  if (!conversation.hostCuProxy) {
+    pendingInteractions.resolve(requestId);
+    throw new NotFoundError("No host CU proxy for conversation");
+  }
 
-  interaction.conversation!.resolveHostCu(requestId, {
+  conversation.hostCuProxy.processObservation(requestId, {
     axTree,
     axDiff,
     screenshot,
@@ -98,8 +116,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"),
@@ -118,6 +135,24 @@ 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:
+          "Submitting client does not match the targeted client for this request.",
+      },
+      "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

@@ -6,19 +6,16 @@
  */
 import { z } from "zod";
 
+import { HostFileProxy } from "../../daemon/host-file-proxy.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";
 
 // ---------------------------------------------------------------------------
 // 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");
   }
@@ -36,9 +33,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") {
@@ -47,9 +42,21 @@ function handleHostFileResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  const interaction = pendingInteractions.resolve(requestId)!;
+  // Validate submitting client matches the targeted client (if any).
+  if (peeked.targetClientId != null) {
+    const rawClientId = (headers as Record<string, string | undefined>)?.["x-vellum-client-id"];
+    const submittingClientId = rawClientId?.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.`,
+      );
+    }
+  }
 
-  interaction.conversation!.resolveHostFile(requestId, {
+  HostFileProxy.instance.resolve(requestId, {
     content: content ?? "",
     isError: isError ?? false,
     imageData,
@@ -89,6 +96,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 file request.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this request.",
+      },
+      "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,
   },
 ];