feat(browser): hosted browser + WebMCP runtime — W2 through W7-prep

mcpjam-inspector/client/src/components/computer/BrowserPanel.tsx

@@ -0,0 +1,248 @@
+/**
+ * Browser Panel — watch the browser an agent is driving, and take it when a
+ * login or a challenge needs a person.
+ *
+ * Two states that matter, and the difference between them is the whole
+ * feature:
+ *
+ *   WATCHING (default) — the noVNC stream is embedded view-only. Anyone with
+ *     the panel open can see what the agent is doing. This is deliberately the
+ *     default (L10): making people take control just to look would push them
+ *     into the disruptive action every time.
+ *
+ *   HOLDING — the person clicked "Take control". The daemon now refuses every
+ *     model-driven command AND every observation (a 423 before the queue), so
+ *     nothing captures the screen while a password is on it. The stream turns
+ *     interactive. Handing back is explicit, and the agent is told the page may
+ *     have changed.
+ *
+ * A lease that stops being heartbeaten PARKS rather than freeing: if this tab
+ * is closed mid-login, the agent does not resume underneath the person. That
+ * is a deliberate bias toward "stuck" over "surprising"; the panel says so.
+ *
+ * Nothing here is persisted. The stream is live only.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useMintBrowserToken } from "@/hooks/useProjectComputer";
+
+/** Heartbeat cadence while holding the lease (the daemon TTL is 2 minutes). */
+const LEASE_HEARTBEAT_MS = 30_000;
+/** Keepalive cadence while merely watching. */
+const KEEPALIVE_MS = 60_000;
+
+type LeaseState =
+  | { state: "free" }
+  | { state: "held"; holder: string; expiresAt?: number }
+  | { state: "parked"; holder: string }
+  | { state: "unknown" };
+
+interface SessionInfo {
+  bootId: string;
+  streamUrl: string;
+  streamPassword: string;
+  lease: LeaseState;
+}
+
+export interface BrowserPanelProps {
+  projectId: string;
+  /** Boot a browser if none is running yet. Off by default: opening a panel
+   *  should not start a machine's browser behind the user's back. */
+  ensure?: boolean;
+}
+
+export function BrowserPanel({ projectId, ensure = false }: BrowserPanelProps) {
+  const mintBrowserToken = useMintBrowserToken();
+  const [session, setSession] = useState<SessionInfo | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [holding, setHolding] = useState(false);
+  // A tab that is not visible must not keep a machine awake.
+  const visibleRef = useRef(true);
+
+  /** Every call mints its own token: they last ~60s, so caching one across a
+   *  panel's lifetime would just produce expiry failures. */
+  const authorized = useCallback(
+    async (path: string, init: RequestInit = {}): Promise<Response> => {
+      const { token } = await mintBrowserToken({ projectId });
+      const headers = new Headers(init.headers);
+      headers.set("authorization", `Bearer ${token}`);
+      if (init.body) headers.set("content-type", "application/json");
+      return fetch(`/api/web/computers/browser${path}`, { ...init, headers });
+    },
+    [mintBrowserToken, projectId],
+  );
+
+  const refresh = useCallback(async () => {
+    try {
+      const res = await authorized(`/session${ensure ? "?ensure=1" : ""}`);
+      const body = await res.json();
+      if (!res.ok) {
+        setSession(null);
+        setError(
+          body?.error === "no_browser_session"
+            ? "No browser is running on this computer yet."
+            : (body?.detail ?? body?.error ?? "Could not reach the browser."),
+        );
+        return;
+      }
+      setSession(body as SessionInfo);
+      setError(null);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    }
+  }, [authorized, ensure]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  useEffect(() => {
+    const onVisibility = () => {
+      visibleRef.current = document.visibilityState === "visible";
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => document.removeEventListener("visibilitychange", onVisibility);
+  }, []);
+
+  // Keepalive while watching — only while the tab is actually visible, and the
+  // server decides whether an open panel still counts at all.
+  useEffect(() => {
+    if (!session) return;
+    const timer = setInterval(() => {
+      if (!visibleRef.current) return;
+      void authorized("/keepalive", { method: "POST" }).catch(() => {});
+    }, KEEPALIVE_MS);
+    return () => clearInterval(timer);
+  }, [authorized, session]);
+
+  // Heartbeat while holding. Stopping (closing the tab, losing the network)
+  // parks the lease rather than freeing it, so the agent stays stopped.
+  useEffect(() => {
+    if (!holding) return;
+    const timer = setInterval(() => {
+      void authorized("/lease", {
+        method: "POST",
+        body: JSON.stringify({ action: "heartbeat" }),
+      }).catch(() => {});
+    }, LEASE_HEARTBEAT_MS);
+    return () => clearInterval(timer);
+  }, [authorized, holding]);
+
+  const changeLease = useCallback(
+    async (action: "acquire" | "resume") => {
+      setBusy(true);
+      try {
+        const res = await authorized("/lease", {
+          method: "POST",
+          body: JSON.stringify({ action }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+          setError(
+            body?.lease?.holder
+              ? "Someone else is using this browser right now."
+              : "Could not change control of the browser.",
+          );
+          return;
+        }
+        setHolding(action === "acquire");
+        setError(null);
+        await refresh();
+      } finally {
+        setBusy(false);
+      }
+    },
+    [authorized, refresh],
+  );
+
+  if (error && !session) {
+    return (
+      <div className="p-4 text-sm text-muted-foreground">
+        <p>{error}</p>
+        <button
+          className="mt-2 underline"
+          onClick={() => void refresh()}
+          type="button"
+        >
+          Try again
+        </button>
+      </div>
+    );
+  }
+
+  if (!session) {
+    return (
+      <div className="p-4 text-sm text-muted-foreground">
+        Connecting to the browser…
+      </div>
+    );
+  }
+
+  const heldByOther =
+    session.lease.state === "held" &&
+    !holding &&
+    session.lease.holder !== undefined;
+  const parked = session.lease.state === "parked";
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex items-center gap-3 border-b px-3 py-2 text-sm">
+        <span className="font-medium">
+          {holding ? "You have control" : "Watching"}
+        </span>
+        {heldByOther && (
+          <span className="text-muted-foreground">
+            Someone else is using this browser.
+          </span>
+        )}
+        {parked && !holding && (
+          <span className="text-muted-foreground">
+            Paused — a person took control and has not handed it back.
+          </span>
+        )}
+        <div className="ml-auto flex gap-2">
+          {holding ? (
+            <button
+              type="button"
+              disabled={busy}
+              onClick={() => void changeLease("resume")}
+              className="rounded border px-2 py-1"
+            >
+              Hand back to the agent
+            </button>
+          ) : (
+            <button
+              type="button"
+              disabled={busy || heldByOther}
+              onClick={() => void changeLease("acquire")}
+              className="rounded border px-2 py-1"
+            >
+              Take control
+            </button>
+          )}
+        </div>
+      </div>
+
+      {holding && (
+        <p className="border-b px-3 py-2 text-xs text-muted-foreground">
+          While you have control, the agent is stopped and nothing is being
+          captured — no screenshots, no page text. Hand control back when you
+          are done; the agent will be told the page may have changed.
+        </p>
+      )}
+
+      <iframe
+        // `view_only` is the interaction gate; the daemon-side lease is the
+        // real one. Both, deliberately: this stops a stray click, the 423
+        // stops everything else.
+        src={`${session.streamUrl}?autoconnect=true&resize=scale&password=${encodeURIComponent(
+          session.streamPassword,
+        )}${holding ? "" : "&view_only=true"}`}
+        title="Computer browser"
+        className="min-h-0 flex-1 border-0"
+      />
+    </div>
+  );
+}
+
+export default BrowserPanel;

mcpjam-inspector/client/src/components/webmcp-inspector/WebmcpInspectorTab.tsx

@@ -15,18 +15,25 @@ import {
 import type {
   WebMcpActivityEntry,
   WebMcpSessionStatus,
+  WebMcpViewportTransport,
 } from "@/shared/webmcp-inspector-protocol";
 
 /**
  * The WebMCP workspace: a URL bar, the live tool registry, one tool's schema
  * and invoke form, and the activity timeline.
  *
- * There is no embedded viewport, and that is the design rather than a gap. The
- * browser opens as a real window on this machine, so the developer drives their
- * own page with their own devtools open; this screen is the instrument panel
- * beside it. A streamed viewport is what the hosted stage needs, and the
- * session already reports which transport it is on so this screen can render
- * one when a provider offers it.
+ * There is no embedded viewport, and for the LOCAL provider that is the design
+ * rather than a gap: the browser opens as a real window on this machine, so the
+ * developer drives their own page with their own devtools open, and this screen
+ * is the instrument panel beside it.
+ *
+ * The hosted provider changes where the browser is, not what this screen does.
+ * Its session reports `remote-interactive-url`, and the viewport lives in the
+ * Browser panel, which can both show the stream and hand control to a person.
+ * So the notice at the top of this screen has to say which of those situations
+ * the viewer is actually in — see `viewportNotice`. Telling someone driving a
+ * datacenter browser to look at a window on their own desk sends them hunting
+ * for something that is not there.
  */
 export function WebmcpInspectorTab() {
   const {
@@ -204,11 +211,12 @@ export function WebmcpInspectorTab() {
 
       {live ? (
         <p className="border-b bg-muted/30 px-3 py-1.5 text-xs text-muted-foreground">
-          {/* Never promise a window that does not exist: a headless session
-              has no viewport to point anyone at. */}
-          {session?.viewportTransport.kind === "headless"
-            ? "Running headless — no window to interact with. Tools, invocation and screenshots all work; use the Screenshot button to see the page."
-            : "A browser window is open on this machine — interact with the page there. Tools it registers appear here as they register."}
+          {/* Never promise a window that does not exist. A headless session has
+              no viewport at all, and a HOSTED one has a browser running on a
+              machine in a datacenter — telling someone to look at a window on
+              their own desk would send them hunting for something that is not
+              there. */}
+          {viewportNotice(session?.viewportTransport.kind)}
           {session?.url ? (
             <span className="ml-1 font-mono">{session.url}</span>
           ) : null}
@@ -337,3 +345,21 @@ function ErrorBanner({
     </div>
   );
 }
+
+/**
+ * What to tell someone about where the browser they are driving actually is.
+ * Each branch is a different physical situation, and getting it wrong sends
+ * people looking for a window that does not exist.
+ */
+function viewportNotice(kind: WebMcpViewportTransport["kind"] | undefined): string {
+  switch (kind) {
+    case "headless":
+      return "Running headless — no window to interact with. Tools, invocation and screenshots all work; use the Screenshot button to see the page.";
+    case "remote-interactive-url":
+      return "This browser is running on your MCPJam computer, not on this machine. Open the Browser panel to watch it, or to take control when a sign-in needs you.";
+    case "frame-stream":
+      return "This browser is streaming its viewport here. Tools it registers appear as they register.";
+    default:
+      return "A browser window is open on this machine — interact with the page there. Tools it registers appear here as they register.";
+  }
+}

mcpjam-inspector/client/src/hooks/useProjectComputer.ts

@@ -138,6 +138,18 @@ export function useMintTerminalToken(): (args: {
   return useAction("projectComputers:mintTerminalToken" as never) as never;
 }
 
+/**
+ * Mint a short-lived (~60s) BROWSER token authorizing the Browser Panel's
+ * data-plane calls. Separate from the terminal token on purpose: it resolves
+ * the desktop computer, and its `purpose` claim means a terminal token cannot
+ * be replayed to open a live view of someone's screen.
+ */
+export function useMintBrowserToken(): (args: {
+  projectId: string;
+}) => Promise<TerminalTokenResult> {
+  return useAction("projectComputers:mintBrowserToken" as never) as never;
+}
+
 /**
  * Which data plane serves this inspector (GET /api/web/computers/config):
  * itself (`localConfigured` — it holds the vendor key + secrets) or a

mcpjam-inspector/package.json

@@ -129,6 +129,7 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
+    "@e2b/desktop": "^2.3.3",
     "@hono/node-server": "^1.13.7",
     "@hono/node-ws": "^1.3.1",
     "@hookform/resolvers": "^3.10.0",