codehost 0.15.0 → 0.17.0

package/src/shared/signaling-client.ts

@@ -161,6 +161,16 @@ export class SignalingClient {
     this.ws?.send(JSON.stringify(msg));
   }
 
+  /** Replace the advertised metadata: a live socket pushes it to the room now,
+   *  and every future (re)connect's `hello` carries it. */
+  updateMeta(meta: PeerMeta): void {
+    this.opts.meta = meta;
+    if (this.ws?.readyState === 1 /* OPEN */) {
+      const msg: ClientMessage = { type: "meta", meta };
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
   close(): void {
     this.closed = true;
     this.stopHeartbeat();

package/src/shared/signaling.ts

@@ -4,6 +4,34 @@
 
 export type Role = "server" | "viewer";
 
+/** One live agent CLI session on the daemon's machine (sourced from agent-yes's
+ *  registry) — advertised so clients can see which agents run where. Interact
+ *  with it over the tunnel's `/__codehost/agent-yes/*` proxy. */
+export interface AgentInfo {
+  pid: number;
+  /** CLI the agent runs, e.g. "claude", "codex". */
+  tool: string;
+  /** Prompt/note snippet for display. */
+  title?: string;
+  /** Working directory (?folder= form) — ties an agent to a workspace. */
+  cwd: string;
+  state: "active" | "idle";
+  /** Unix ms when the agent started. */
+  startedAt?: number;
+}
+
+/** One checkout a root daemon found on disk under its layout — advertised so
+ *  clients can list and exactly match real workspaces instead of synthesizing
+ *  optimistic paths. */
+export interface WorkspaceInfo {
+  /** ?folder= form path of the checkout (see toPosixPath). */
+  path: string;
+  /** Host-agnostic repo identity, e.g. "github.com/owner/repo". */
+  repo?: string;
+  /** Branch from the layout path, e.g. "main". */
+  branch?: string;
+}
+
 /** Metadata a `codehost serve`/`dev` daemon advertises about itself. */
 export interface PeerMeta {
   /** Human label, defaults to hostname. */
@@ -12,6 +40,13 @@ export interface PeerMeta {
   cwd: string;
   /** Hostname of the machine running the daemon. */
   host: string;
+  /**
+   * Stable machine identity (UUID persisted in ~/.codehost/config.json). All
+   * daemons on one machine share it, unlike the per-process peerId, so clients
+   * can group peers by host and keep history across daemon restarts. Absent on
+   * older daemons — fall back to `host`.
+   */
+  hostId?: string;
   /**
    * "repo": serves a single folder (`codehost dev`), git-identified when possible.
    * "root": serves a workspace root (`codehost serve`) whose repos live under it.
@@ -28,6 +63,17 @@ export interface PeerMeta {
    * `cwd + "/" + fill(layout, target)`.
    */
   layout?: string;
+  /**
+   * root kind: the checkouts that actually exist under `cwd` (enumerated on
+   * start, after each provision, and on a slow rescan). Capped server-side;
+   * absent on older daemons and on repo/expose kinds.
+   */
+  workspaces?: WorkspaceInfo[];
+  /**
+   * Live agent CLI sessions on this machine (from the agent-yes plugin).
+   * Advertised by root daemons; capped server-side.
+   */
+  agents?: AgentInfo[];
 }
 
 export interface PeerInfo {
@@ -61,7 +107,15 @@ export interface PingMessage {
   type: "ping";
 }
 
-export type ClientMessage = HelloMessage | SignalMessage | PingMessage;
+/** Replace this peer's advertised metadata mid-session (e.g. a provision
+ *  created a new workspace) — the room re-broadcasts the peer list. Older
+ *  workers ignore it; the meta still lands via `hello` on the next reconnect. */
+export interface MetaMessage {
+  type: "meta";
+  meta: PeerMeta;
+}
+
+export type ClientMessage = HelloMessage | SignalMessage | PingMessage | MetaMessage;
 
 // ---- Server -> Client ----
 

package/src/web/discovery.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from "react";
-import type { PeerInfo } from "../shared/signaling";
+import type { AgentInfo, PeerInfo, WorkspaceInfo } from "../shared/signaling";
 import { TOKEN_REQUIREMENTS, validateToken } from "../shared/token";
 import { SignalingClient } from "../shared/signaling-client";
 import type { RtcSignal } from "../shared/rtc";
@@ -10,6 +10,8 @@ import { connBroker } from "./conn-broker";
 import {
   DEFAULT_BRANCH,
   type DeepLink,
+  type RepoTarget,
+  type ResolvePrefs,
   type RoomMatch,
   gitUrlToPath,
   parseDeepLink,
@@ -24,7 +26,7 @@ import { deriveTags, matchQuery, shortRoomLabel, tagKey } from "../shared/tags";
 
 const TOKEN_KEY = "codehost.token";
 
-type ConnState = "idle" | "connecting" | "connected" | "failed";
+type ConnState = "idle" | "connecting" | "provisioning" | "connected" | "failed";
 
 /** A server discovered in a specific room (its token routes the signaling). */
 type RoomedServer = { server: PeerInfo; room: string };
@@ -90,7 +92,7 @@ function findRoomForDeepLink(dl: DeepLink, tokens: string[], timeoutMs = 6000):
           const res =
             dl.type === "repo" ? resolveRepoTarget(servers, dl.target) : resolveDevTarget(servers, dl.target);
           if (!res) return;
-          if (!res.folder) finish(tok); // exact match — take it now
+          if (!res.folder || res.exact) finish(tok); // exact match — take it now
           else if (!fallbacks.some((f) => f.token === tok)) fallbacks.push({ token: tok, resolution: res });
         },
       });
@@ -180,6 +182,8 @@ export function Discovery() {
   const [activePeerId, setActivePeerId] = useState<string | null>(null);
   const [connState, setConnState] = useState<ConnState>("idle");
   const [iframeSrc, setIframeSrc] = useState<string | null>(null);
+  // Streamed setup.sh output shown while connState === "provisioning".
+  const [provisionLog, setProvisionLog] = useState("");
 
   const rtcRef = useRef<RtcClient | null>(null);
   const activePeerRef = useRef<string | null>(null);
@@ -351,7 +355,13 @@ export function Discovery() {
     sendersRef.current.delete(t);
   }
 
-  async function connectTo(server: PeerInfo, room: string, folder?: string, fromHistory = false) {
+  async function connectTo(
+    server: PeerInfo,
+    room: string,
+    folder?: string,
+    fromHistory = false,
+    repoTarget?: RepoTarget,
+  ) {
     const send = sendersRef.current.get(room);
     if (!send) return;
     dialingRef.current = true; // synchronous gate against concurrent triggers
@@ -374,7 +384,7 @@ export function Discovery() {
       // handshake) and push a history entry, so Back returns to the list and
       // Forward returns here. When `fromHistory`, the browser already set the URL
       // (back/forward/reconnect) — don't push again, but a prior entry exists.
-      const openFolder = folder ?? server.meta?.cwd;
+      let openFolder = folder ?? server.meta?.cwd;
       if (fromHistory) {
         pushedRef.current = true;
         sharePathRef.current = window.location.pathname;
@@ -425,10 +435,23 @@ export function Discovery() {
         });
 
       await connBroker.connect(server.peerId, establish);
+
+      // For a repo deep link, ask the daemon to provision (run .codehost/setup.sh
+      // and hand back the authoritative workspace path) before opening. Streams
+      // the log under the "provisioning" state. Daemons without the route (older
+      // builds) return no path → fall back to the browser-computed folder.
+      if (repoTarget) {
+        setConnState("provisioning");
+        setProvisionLog("");
+        const ws = await runProvision(server.peerId, repoTarget);
+        if (activePeerRef.current !== server.peerId) return; // cancelled/switched mid-provision
+        if (ws) openFolder = ws;
+      }
+
       setConnState("connected");
       // The daemon no longer sets a default folder (current VS Code serve-web
       // dropped that flag), so open the served workspace from here: the
-      // deep-link folder if we have one, else the server's reported cwd.
+      // provisioned/deep-link folder if we have one, else the server's reported cwd.
       activeFolderRef.current = openFolder;
       setIframeSrc(`/vs/${server.peerId}/${folderQuery(openFolder)}`);
       setResolving(null);
@@ -446,6 +469,48 @@ export function Discovery() {
     }
   }
 
+  // Ask the daemon to provision a repo workspace over the tunnel: stream
+  // setup.sh's output into `provisionLog` and return the daemon-authoritative
+  // path (the `x-codehost-workspace` header). Returns null when the daemon has
+  // no provision route (older build) or the call fails — caller falls back.
+  async function runProvision(peerId: string, t: RepoTarget): Promise<string | null> {
+    const params = new URLSearchParams({
+      owner: t.owner,
+      repo: t.name,
+      branch: t.branch ?? DEFAULT_BRANCH,
+      host: t.host,
+    });
+    let res: Response;
+    try {
+      res = await connBroker.tunnelFor(peerId).fetch("GET", `/__codehost/provision?${params}`, {});
+    } catch {
+      return null;
+    }
+    const ws = res.headers.get("x-codehost-workspace");
+    if (!ws) {
+      await res.body?.cancel().catch(() => {});
+      return null;
+    }
+    let buf = `[codehost] provisioning ${t.owner}/${t.name}@${t.branch ?? DEFAULT_BRANCH}…\n`;
+    setProvisionLog(buf);
+    if (res.body) {
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          // Hide the internal exit sentinel from the displayed log.
+          setProvisionLog(buf.replace(/\n::codehost:exit=\d+\n?/, "\n"));
+        }
+      } catch {
+        // stream interrupted (channel closed) — return the path anyway
+      }
+    }
+    return ws;
+  }
+
   // Shareable deep-link pathname for a server+folder, with no side effects (no
   // token — Share adds that). Keeps an existing deep-link path as-is; otherwise
   // derives /gh|/git|/dev from the server's repo identity or opened folder.
@@ -481,6 +546,14 @@ export function Discovery() {
     setTimeout(() => setCopied(false), 1500);
   }
 
+  // The machine history says served this repo last — break resolution ties
+  // toward it (stable hostId when recorded, hostname for older entries).
+  function preferFor(dl: DeepLink): ResolvePrefs | undefined {
+    if (dl?.type !== "repo") return undefined;
+    const h = historyFor(repoKey(dl.target));
+    return h ? { hostId: h.hostId, host: h.host } : undefined;
+  }
+
   // Deep-link auto-connect: when servers arrive, pick the best match (exact repo
   // daemon, else a root daemon's subfolder) across all rooms and open it once.
   function tryAutoConnect() {
@@ -488,12 +561,13 @@ export function Discovery() {
     const dl = deepLinkRef.current;
     if (dl) {
       const peers = allServers.map((x) => x.server);
-      const res = dl.type === "repo" ? resolveRepoTarget(peers, dl.target) : resolveDevTarget(peers, dl.target);
+      const res =
+        dl.type === "repo" ? resolveRepoTarget(peers, dl.target, preferFor(dl)) : resolveDevTarget(peers, dl.target);
       if (!res) return;
       const match = allServers.find((x) => x.server.peerId === res.peerId);
       if (!match) return;
       resolvedRef.current = true;
-      void connectTo(match.server, match.room, res.folder);
+      void connectTo(match.server, match.room, res.folder, false, dl.type === "repo" ? dl.target : undefined);
       return;
     }
     // No deep link, but a token arrived via the URL: open that room's server
@@ -512,7 +586,7 @@ export function Discovery() {
   function recordConnect(server: PeerInfo, room: string, folder?: string) {
     const base = {
       token: room,
-      peerId: server.peerId,
+      hostId: server.meta?.hostId,
       kind: server.meta?.kind,
       name: server.meta?.name,
       host: server.meta?.host,
@@ -543,7 +617,8 @@ export function Discovery() {
   function findServerForDeepLink(dl: DeepLink): (RoomedServer & { folder?: string }) | null {
     if (!dl) return null;
     const peers = allServersRef.current.map((x) => x.server);
-    const res = dl.type === "repo" ? resolveRepoTarget(peers, dl.target) : resolveDevTarget(peers, dl.target);
+    const res =
+      dl.type === "repo" ? resolveRepoTarget(peers, dl.target, preferFor(dl)) : resolveDevTarget(peers, dl.target);
     if (!res) return null;
     const match = allServersRef.current.find((x) => x.server.peerId === res.peerId);
     return match ? { ...match, folder: res.folder } : null;
@@ -563,7 +638,20 @@ export function Discovery() {
     const target = findServerForDeepLink(dl);
     if (!target) return; // its server isn't present (yet) — wait for it to appear
     if (activePeerRef.current === target.server.peerId && connStateRef.current === "connected") return;
-    void connectTo(target.server, target.room, target.folder, true);
+    void connectTo(target.server, target.room, target.folder, true, dl.type === "repo" ? dl.target : undefined);
+  }
+
+  // Open an enumerated checkout via its deep link, reusing the URL-driven
+  // resolution (provisioning, history, machine preference) instead of dialing
+  // the card's peer directly.
+  function openWorkspace(server: PeerInfo, w: WorkspaceInfo) {
+    const path = w.repo
+      ? shareableDeepLink({ repo: w.repo, branch: w.branch })
+      : shareableDeepLink({ folder: w.path, host: server.meta?.host });
+    if (!path) return;
+    history.pushState(null, "", path);
+    setResolving(deepLinkLabel(parseDeepLink(path)));
+    syncToUrl();
   }
 
   function disconnect() {
@@ -600,6 +688,23 @@ export function Discovery() {
   }));
   const query = [...activeTags, filter].join(" ");
   const filtered = tagged.filter((t) => matchQuery({ name: t.name, tags: t.tags }, query));
+  // Group workspaces by machine: the stable hostId when the daemon advertises
+  // one, else the hostname string (older daemons), else the peer stands alone.
+  // Agents are machine-level (advertised by the host's root daemon) — collect
+  // them per group, deduped by pid across peers.
+  const hostGroups: { key: string; label: string; items: typeof filtered; agents: AgentInfo[] }[] = [];
+  for (const t of filtered) {
+    const key = t.server.meta?.hostId ?? t.server.meta?.host ?? t.server.peerId;
+    let group = hostGroups.find((g) => g.key === key);
+    if (!group) {
+      group = { key, label: t.server.meta?.host ?? t.name, items: [], agents: [] };
+      hostGroups.push(group);
+    }
+    group.items.push(t);
+    for (const a of t.server.meta?.agents ?? []) {
+      if (!group.agents.some((x) => x.pid === a.pid)) group.agents.push(a);
+    }
+  }
   const toggleTag = (t: string) =>
     setActiveTags((a) => (a.includes(t) ? a.filter((x) => x !== t) : [...a, t]));
   const addTag = (t: string) => setActiveTags((a) => (a.includes(t) ? a : [...a, t]));
@@ -630,6 +735,27 @@ export function Discovery() {
     />
   ));
 
+  // Provisioning view: the daemon's setup.sh is running; stream its log.
+  if (connState === "provisioning") {
+    return (
+      <>
+        {roomClients}
+        <div style={styles.page}>
+          <header style={styles.header}>
+            <span style={styles.brand}>codehost</span>
+            <span style={styles.dim}>·</span>
+            <span style={styles.dim}>provisioning…</span>
+            <span style={{ flex: 1 }} />
+            <button style={styles.connectBtn} onClick={disconnect}>
+              Cancel
+            </button>
+          </header>
+          <pre style={styles.provLog}>{provisionLog || "starting…"}</pre>
+        </div>
+      </>
+    );
+  }
+
   // Connected view: VS Code in an iframe, served over the tunnel.
   if (iframeSrc && connState === "connected") {
     return (
@@ -820,42 +946,85 @@ export function Discovery() {
               )}
             </>
           )}
-          <ul style={styles.list}>
-            {filtered.map(({ server: s, room, name, tags }) => {
-              const isActive = s.peerId === activePeerId;
-              return (
-                <li key={s.peerId} style={styles.card}>
-                  <div style={styles.cardMain}>
-                    <div style={styles.cardName}>{name}</div>
-                    <div style={styles.tagRow}>
-                      {tags.map((tag) => (
-                        <button key={tag} style={styles.tag} onClick={() => addTag(tag)} title={`filter by ${tag}`}>
-                          {tag}
-                        </button>
-                      ))}
-                    </div>
-                    <div style={styles.idLine}>peer {s.peerId.slice(0, 8)}</div>
-                    {isActive && (
-                      <div style={styles.echo}>
-                        {connState === "connecting" && "negotiating WebRTC…"}
-                        {connState === "failed" && "connection failed"}
-                      </div>
-                    )}
+          <div>
+            {hostGroups.map((g) => (
+              <section key={g.key}>
+                <div style={styles.hostHead}>
+                  <span style={styles.hostName}>{g.label}</span>
+                  <span style={styles.count}>
+                    {g.items.length} workspace{g.items.length === 1 ? "" : "s"}
+                    {g.agents.length > 0 && ` · ${g.agents.length} agent${g.agents.length === 1 ? "" : "s"}`}
+                  </span>
+                </div>
+                {g.agents.length > 0 && (
+                  <div style={styles.agentRow}>
+                    {g.agents.map((a) => (
+                      <span
+                        key={a.pid}
+                        style={styles.agentChip}
+                        title={`${a.cwd}${a.title ? `\n${a.title}` : ""}`}
+                      >
+                        <span style={{ color: a.state === "active" ? "#4ec9b0" : "#777" }}>●</span> {a.tool}{" "}
+                        {a.pid}
+                      </span>
+                    ))}
                   </div>
-                  <button
-                    style={styles.connectBtn}
-                    onClick={() => connectTo(s, room)}
-                    disabled={isActive && connState === "connecting"}
-                  >
-                    {isActive && connState === "connecting" ? "…" : "Connect"}
-                  </button>
-                </li>
-              );
-            })}
+                )}
+                <ul style={styles.list}>
+                  {g.items.map(({ server: s, room, name, tags }) => {
+                    const isActive = s.peerId === activePeerId;
+                    return (
+                      <li key={s.peerId} style={styles.card}>
+                        <div style={styles.cardMain}>
+                          <div style={styles.cardName}>{name}</div>
+                          <div style={styles.tagRow}>
+                            {tags.map((tag) => (
+                              <button key={tag} style={styles.tag} onClick={() => addTag(tag)} title={`filter by ${tag}`}>
+                                {tag}
+                              </button>
+                            ))}
+                          </div>
+                          {(s.meta?.workspaces?.length ?? 0) > 0 && (
+                            <div style={styles.wsRow}>
+                              {s.meta!.workspaces!.map((w) => (
+                                <button
+                                  key={w.path}
+                                  style={styles.wsLink}
+                                  onClick={() => openWorkspace(s, w)}
+                                  title={w.path}
+                                >
+                                  {w.repo
+                                    ? `${w.repo.split("/").slice(1).join("/")}${w.branch ? ` @${w.branch}` : ""}`
+                                    : w.path}
+                                </button>
+                              ))}
+                            </div>
+                          )}
+                          <div style={styles.idLine}>peer {s.peerId.slice(0, 8)}</div>
+                          {isActive && (
+                            <div style={styles.echo}>
+                              {connState === "connecting" && "negotiating WebRTC…"}
+                              {connState === "failed" && "connection failed"}
+                            </div>
+                          )}
+                        </div>
+                        <button
+                          style={styles.connectBtn}
+                          onClick={() => connectTo(s, room)}
+                          disabled={isActive && connState === "connecting"}
+                        >
+                          {isActive && connState === "connecting" ? "…" : "Connect"}
+                        </button>
+                      </li>
+                    );
+                  })}
+                </ul>
+              </section>
+            ))}
             {serverCount > 0 && filtered.length === 0 && (
               <p style={styles.dim}>No workspace matches your filter.</p>
             )}
-          </ul>
+          </div>
         </main>
       </div>
     </>
@@ -900,8 +1069,20 @@ const styles: Record<string, React.CSSProperties> = {
     border: "1px solid #3d3d3d", background: "transparent", color: "#9aa4af", cursor: "pointer",
   },
   idLine: { fontFamily: "monospace", fontSize: 11, color: "#666", marginTop: 6 },
+  wsRow: { display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 3, marginTop: 8 },
+  wsLink: {
+    fontFamily: "monospace", fontSize: 12, padding: "2px 0", border: "none", background: "transparent",
+    color: "#75beff", cursor: "pointer", textAlign: "left",
+  },
   code: { background: "#252525", padding: "2px 6px", borderRadius: 4, fontFamily: "monospace", fontSize: 12 },
-  list: { listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 8 },
+  list: { listStyle: "none", margin: "0 0 14px", padding: 0, display: "flex", flexDirection: "column", gap: 8 },
+  hostHead: { display: "flex", alignItems: "baseline", gap: 10, margin: "0 0 8px" },
+  hostName: { fontSize: 13, fontWeight: 600, color: "#dcdcaa", fontFamily: "monospace" },
+  agentRow: { display: "flex", flexWrap: "wrap", gap: 6, margin: "0 0 8px" },
+  agentChip: {
+    fontFamily: "monospace", fontSize: 11.5, padding: "2px 8px", borderRadius: 999,
+    border: "1px solid #3d3d3d", color: "#9aa4af",
+  },
   card: { display: "flex", alignItems: "center", gap: 12, background: "#252525", border: "1px solid #3d3d3d", borderRadius: 8, padding: "12px 14px" },
   cardMain: { flex: 1, minWidth: 0 },
   cardName: { fontSize: 14, fontWeight: 600, color: "#fff" },
@@ -910,4 +1091,5 @@ const styles: Record<string, React.CSSProperties> = {
   echo: { marginTop: 6, fontSize: 12, color: "#4ec9b0", fontFamily: "monospace" },
   connectBtn: { background: "#0e639c", border: "none", color: "#fff", padding: "6px 14px", borderRadius: 6, cursor: "pointer", fontSize: 13 },
   shareBtn: { background: "transparent", border: "1px solid #3d3d3d", color: "#ccc", padding: "6px 14px", borderRadius: 6, cursor: "pointer", fontSize: 13 },
+  provLog: { flex: 1, margin: 0, padding: "14px 18px", overflow: "auto", background: "#1e1e1e", color: "#ccc", fontFamily: "monospace", fontSize: 12.5, lineHeight: 1.5, whiteSpace: "pre-wrap" },
 };

package/src/web/history.ts

@@ -7,11 +7,14 @@ const HISTORY_KEY = "codehost.history";
 
 export interface HistoryEntry {
   token: string;
-  peerId?: string;
+  /** Stable machine id of the server that opened it — unlike a peerId it
+   *  survives daemon restarts, so reconnect prefers the same machine. */
+  hostId?: string;
   kind?: "repo" | "root";
   /** For root-kind opens, the ?folder= path used. */
   folder?: string;
   name?: string;
+  /** Hostname — display + match fallback for pre-hostId daemons/entries. */
   host?: string;
   lastConnected: number;
 }

package/src/web/room-client.ts

@@ -0,0 +1,114 @@
+import { SignalingClient } from "../shared/signaling-client";
+import type { PeerInfo } from "../shared/signaling";
+import type { RtcSignal } from "../shared/rtc";
+import { RtcClient } from "./rtc-client";
+import { TunnelClient } from "./tunnel-client";
+
+// Embeddable codehost room client for OTHER sites (agent-yes.com first): join a
+// room as a viewer, watch the peer list (hosts advertise workspaces + agents in
+// PeerMeta), and speak HTTP to any server peer over a lazily-dialed WebRTC
+// tunnel. No Service Worker, no React, no cross-tab broker — one module that
+// `bun build --target browser` bundles standalone (see scripts.build:lib).
+
+export type { AgentInfo, PeerInfo, PeerMeta, WorkspaceInfo } from "../shared/signaling";
+
+export const DEFAULT_SIGNAL_URL = "wss://signal.codehost.dev";
+
+export interface RoomOptions {
+  /** Room token (bearer secret — same one `codehost serve -t` uses). */
+  token: string;
+  /** Signaling server (default wss://signal.codehost.dev). */
+  signalUrl?: string;
+  /** Live server-peer list, fired on every room membership/meta change. */
+  onPeers?: (peers: PeerInfo[]) => void;
+  /** Signaling socket state. */
+  onStatus?: (open: boolean) => void;
+}
+
+export class CodehostRoom {
+  /** Server peers currently in the room (viewers filtered out). */
+  peers: PeerInfo[] = [];
+  private signaling: SignalingClient;
+  private rtcs = new Map<string, RtcClient>();
+  private tunnels = new Map<string, Promise<TunnelClient>>();
+  private closed = false;
+
+  constructor(opts: RoomOptions) {
+    this.signaling = new SignalingClient({
+      url: opts.signalUrl ?? DEFAULT_SIGNAL_URL,
+      token: opts.token,
+      role: "viewer",
+      onOpen: () => opts.onStatus?.(true),
+      onClose: () => opts.onStatus?.(false),
+      onPeers: (peers) => {
+        this.peers = peers.filter((p) => p.role === "server");
+        opts.onPeers?.(this.peers);
+      },
+      onSignal: (from, data) => void this.rtcs.get(from)?.handleSignal(data),
+    });
+    this.signaling.connect();
+  }
+
+  /** HTTP over the peer's tunnel (dialed on first use, reused after). The
+   *  response streams — long-lived SSE bodies work. */
+  async fetch(
+    peerId: string,
+    method: string,
+    path: string,
+    init: { headers?: Record<string, string>; body?: Uint8Array | string } = {},
+  ): Promise<Response> {
+    const tunnel = await this.dial(peerId);
+    const body = typeof init.body === "string" ? new TextEncoder().encode(init.body) : init.body;
+    return tunnel.fetch(method, path, init.headers ?? {}, body);
+  }
+
+  private dial(peerId: string): Promise<TunnelClient> {
+    const existing = this.tunnels.get(peerId);
+    if (existing) return existing;
+    const drop = () => {
+      this.tunnels.delete(peerId);
+      this.rtcs.get(peerId)?.close();
+      this.rtcs.delete(peerId);
+    };
+    const dialing = new Promise<TunnelClient>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        drop();
+        reject(new Error("dial timed out"));
+      }, 15000);
+      const rtc = new RtcClient({
+        sendSignal: (data: RtcSignal) => this.signaling.sendSignal(peerId, data),
+        onOpen: (channel) => {
+          clearTimeout(timer);
+          resolve(new TunnelClient(channel));
+        },
+        onClose: drop,
+        onState: (state) => {
+          if (state === "failed" || state === "disconnected") drop();
+        },
+      });
+      this.rtcs.set(peerId, rtc);
+      rtc.start().catch((err) => {
+        clearTimeout(timer);
+        drop();
+        reject(err);
+      });
+    });
+    this.tunnels.set(peerId, dialing);
+    dialing.catch(() => this.tunnels.delete(peerId));
+    return dialing;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const rtc of this.rtcs.values()) rtc.close();
+    this.rtcs.clear();
+    this.tunnels.clear();
+    this.signaling.close();
+  }
+}
+
+/** Join a codehost room as a viewer. */
+export function joinRoom(opts: RoomOptions): CodehostRoom {
+  return new CodehostRoom(opts);
+}

package/worker/room.ts

@@ -71,6 +71,15 @@ export class Room implements DurableObject {
       return;
     }
 
+    if (msg.type === "meta") {
+      const att = this.touch(ws);
+      if (!att) return; // never said hello
+      att.meta = msg.meta ?? null;
+      ws.serializeAttachment(att);
+      this.broadcastPeers();
+      return;
+    }
+
     if (msg.type === "signal") {
       const att = this.touch(ws);
       if (!att) return;