@bivy/bivy 0.16.25-staging.35 → 0.16.25-staging.37

package/README.md

@@ -206,6 +206,9 @@ answer questions, approve supported tool calls, or stop the agent.
 
 - Send screenshots, images, logs, and other files from your phone.
 - Download reports and artifacts the agent creates.
+- Publish [session apps](docs/apps.md) with web and CLI/TUI views using
+  `bivy app publish bivy.app.json`. Web previews require a separately configured
+  HTTPS preview domain; terminal views use the existing connection.
 - Use voice input and read-aloud where supported; provider-backed voice may
   send audio or text to the selected provider.
 - Keep a native terminal workflow or use structured chat, depending on the agent.

package/bin/bivy.mjs

@@ -2418,6 +2418,57 @@ async function cmdAttach(args = []) {
   console.log(c.green(`Attached ${body.name} (${body.kind}, ${body.size} bytes) to the chat.`));
 }
 
+// Universal app publishing: every agent that can write JSON and run a command
+// uses the same contract. Relative static directories are manifest-relative.
+async function cmdApp(args = []) {
+  const [action, ...rest] = args;
+  if (!action || rest.some((arg) => arg === "--help" || arg === "-h") || ["help", "--help", "-h"].includes(action)) {
+    console.log(`Usage: bivy app publish <manifest.json> [--session <id>]
+       bivy app list [--session <id>]
+       bivy app remove <app-id> [--session <id>]
+
+Manifest: {"version":1,"name":"My app","views":[
+  {"kind":"web","name":"Website","source":{"kind":"service","port":3000}},
+  {"kind":"terminal","name":"Console","command":"bin/rails","args":["console"]}
+]}
+
+Static web source: {"kind":"static","directory":"./dist"}
+Publishing does not start commands. Open Apps in the session menu to view or run.
+Terminal commands run with the node user's permissions, not in a new sandbox.
+Web previews require operator setup; see docs/apps.md.`);
+    return;
+  }
+  if (!["publish", "list", "remove"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
+  const sessionIndex = rest.indexOf("--session");
+  if (sessionIndex >= 0 && (!rest[sessionIndex + 1] || rest[sessionIndex + 1].startsWith("--"))) throw new Error("--session requires an id.");
+  const sessionId = resolveAttachSessionId({ sessionFlag: sessionIndex >= 0 ? rest[sessionIndex + 1] : undefined, env: process.env });
+  if (!sessionId) throw new Error("Set --session <id> or run inside a Bivy agent session.");
+  const positional = rest.filter((_, i) => i !== sessionIndex && (sessionIndex < 0 || i !== sessionIndex + 1));
+  if (positional.some((a) => a.startsWith("-")) || positional.length !== (action === "list" ? 0 : 1)) throw new Error("Invalid arguments. Run bivy app --help.");
+  const body = { sessionId };
+  if (action === "publish") {
+    const file = path.resolve(positional[0]);
+    if (fs.statSync(file).size > 64 * 1024) throw new Error("App manifest exceeds 64 KiB.");
+    const manifest = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!manifest || typeof manifest !== "object") throw new Error("App manifest must be a JSON object.");
+    if (Array.isArray(manifest.views)) for (const view of manifest.views) {
+      if (view?.kind === "web" && view.source?.kind === "static" && typeof view.source.directory === "string") {
+        view.source.directory = path.resolve(path.dirname(file), view.source.directory);
+      }
+    }
+    body.manifest = manifest;
+  } else if (action === "remove") body.appId = positional[0];
+  const config = loadConfig();
+  if (!(await ensureNodeRunning(config))) throw new Error("Could not reach the Bivy node.");
+  const token = await localDeviceToken(config);
+  const response = await fetch(`${url(config)}/api/apps/${action}`, {
+    method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify(body),
+  });
+  const result = await response.json();
+  if (!response.ok || result.error) throw new Error(result.error || `App command failed (${response.status}).`);
+  console.log(JSON.stringify(result, null, 2));
+}
+
 // Map a saved session's runtime id to the `bivy run` agent whose native CLI can
 // resume it in a terminal. Only agents with a real native resume qualify; other
 // runtimes (generic-cli, SDK-only) have no terminal resume and open in the web app.
@@ -5045,6 +5096,7 @@ ${c.bold("bivy")} — Bivy node CLI
   ${c.cyan("bivy token")}       Print a device token for this node (for 'bivy nodes add' elsewhere)
   ${c.cyan("bivy sessions")}     List recent sessions (live + saved) and resume one (alias: ls)
   ${c.cyan("bivy resume")} [n|id] Resume a session directly (default: most recent)
+  ${c.cyan("bivy app")}             Publish and list session apps (web and terminal views)
   ${c.cyan("bivy send <id>")} "..."  Send a prompt to an existing session and stream the reply
   ${c.cyan("bivy kill <id>")}    Stop a session/terminal (--delete also removes a saved session)
   ${c.cyan("bivy prune")}         Delete old sessions/workspaces/worktrees (--keep N, --older-than 7d, --dry-run)
@@ -5167,6 +5219,9 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "send":
       await cmdSend(args);
       break;
+    case "app":
+      await cmdApp(args);
+      break;
     case "attach":
       await cmdAttach(args);
       break;

package/dist/apps/gateway.js

@@ -0,0 +1,357 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import http from "node:http";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { previewShell } from "./preview-shell.js";
+const MIME = {
+    ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png",
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".ico": "image/x-icon",
+    ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".wasm": "application/wasm",
+    ".txt": "text/plain; charset=utf-8", ".pdf": "application/pdf", ".mp4": "video/mp4", ".webm": "video/webm",
+};
+const COOKIE = "__Host-bivy-preview";
+const OPEN_PATH = "/__bivy/open";
+const REDEEM_PATH = "/__bivy/redeem";
+const HOUR = 60 * 60_000;
+const HOP = new Set(["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade"]);
+/** Separate per-app origins are mandatory. TLS terminates at the operator's
+ * reverse proxy, which must preserve Host and reach ONLY this gateway port. */
+export function previewOriginTemplate(raw) {
+    const parsed = new URL(raw.replace("{app}", "a"));
+    if (!/^https:\/\/\{app\}\.[a-z0-9.-]+\/?$/.test(raw) || raw.split("{app}").length !== 2 || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash || parsed.port) {
+        throw new Error("BIVY_APPS_ORIGIN must be https://{app}.<dedicated-preview-domain> (no path or port).");
+    }
+    return raw.replace(/\/$/, "").toLowerCase();
+}
+function cleanHeaders(headers) {
+    const blocked = new Set([...HOP, ...(headers.connection ?? "").toLowerCase().split(",").map((s) => s.trim())]);
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => !blocked.has(key) && !key.startsWith("x-forwarded-") && key !== "forwarded"));
+}
+function upstreamHeaders(req, origin) {
+    const headers = cleanHeaders(req.headers);
+    // The preview credential is never disclosed to generated code/backends.
+    headers.cookie = (req.headers.cookie ?? "").split(";").filter((part) => part.trim().split("=", 1)[0] !== COOKIE).join(";");
+    headers.host = new URL(origin).host;
+    headers["x-forwarded-host"] = headers.host;
+    headers["x-forwarded-proto"] = "https";
+    return headers;
+}
+function responseHeaders(headers, shellOrigin) {
+    const result = cleanHeaders(headers);
+    if (headers["set-cookie"]) {
+        result["set-cookie"] = headers["set-cookie"].filter((cookie) => cookie.split("=", 1)[0].trim() !== COOKIE)
+            .map((cookie) => cookie.replace(/;\s*domain=[^;]*/ig, ""));
+    }
+    // Preview data must not become a shared proxy cache entry. Apps cannot frame
+    // Bivy, retain an opener, or cache an offline service-worker copy of the gate.
+    result["cache-control"] = "no-store";
+    result["referrer-policy"] = "no-referrer";
+    result["cross-origin-opener-policy"] = "same-origin";
+    result["x-content-type-options"] = "nosniff";
+    // The preview shell is the only allowed ancestor. Preserve the app's other
+    // CSP directives, but replace framing restrictions with this narrower host.
+    delete result["x-frame-options"];
+    const csp = result["content-security-policy"];
+    const policies = (Array.isArray(csp) ? csp : csp ? [String(csp)] : []).map((policy) => policy.replace(/(^|[;,])\s*frame-ancestors[^;,]*/gi, "$1"));
+    result["content-security-policy"] = [...policies, `frame-ancestors ${shellOrigin}; worker-src 'none'`].join(", ");
+    return result;
+}
+export class AppGateway {
+    registry;
+    returnOrigins;
+    server;
+    template;
+    tickets = new Map();
+    styles = new Map([
+        ["/__bivy/tokens.css", readFileSync(new URL("./tokens.css", import.meta.url))],
+        ["/__bivy/styles.css", readFileSync(new URL("./styles.css", import.meta.url))],
+    ]);
+    sessions = new Map();
+    sockets = new Map();
+    constructor(registry, originTemplate, returnOrigins = () => []) {
+        this.registry = registry;
+        this.returnOrigins = returnOrigins;
+        this.template = previewOriginTemplate(originTemplate);
+        this.server = http.createServer((req, res) => { void this.handle(req, res).catch(() => { if (!res.headersSent)
+            res.writeHead(502); res.end("Preview request failed."); }); });
+        this.server.maxConnections = 256;
+        this.server.headersTimeout = 15_000;
+        this.server.requestTimeout = 60_000;
+        this.server.on("upgrade", (req, socket, head) => this.upgrade(req, socket, head));
+    }
+    origin(id) { return this.template.replace("{app}", id); }
+    shellOrigin(id) { return this.template.replace("{app}", `view-${id}`); }
+    open(id, returnTo) {
+        const entry = this.registry.getView(id);
+        if (entry?.view.kind !== "web")
+            throw new Error("Web view not found.");
+        if (returnTo) {
+            const url = new URL(returnTo);
+            const safeScheme = url.protocol === "https:" || (url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname));
+            if (!this.returnOrigins().includes(url.origin))
+                throw new Error("Return-to-chat origin is not configured on this machine. Set BIVY_APPS_RETURN_ORIGINS for an additional Bivy client origin.");
+            if (!safeScheme || url.username || url.password || url.search || url.hash || url.pathname !== `/sessions/${encodeURIComponent(entry.app.sessionId)}`)
+                throw new Error("Invalid return-to-chat URL.");
+            returnTo = url.href;
+        }
+        this.sweep();
+        if (this.tickets.size >= 500 || this.sessions.size >= 500)
+            throw new Error("Too many preview grants. Try again later.");
+        const ticket = randomBytes(32).toString("hex");
+        this.tickets.set(ticket, { appId: id, expires: Date.now() + 60_000, returnTo });
+        // Fragment never reaches reverse-proxy access logs or the application.
+        return `${this.shellOrigin(id)}${OPEN_PATH}#${ticket}`;
+    }
+    revoke(id) {
+        for (const map of [this.tickets, this.sessions])
+            for (const [key, grant] of map)
+                if (grant.appId === id)
+                    map.delete(key);
+        for (const socket of this.sockets.get(id) ?? [])
+            socket.destroy();
+        this.sockets.delete(id);
+    }
+    close() {
+        for (const id of this.sockets.keys())
+            this.revoke(id);
+        this.tickets.clear();
+        this.sessions.clear();
+        this.server.close();
+        this.server.closeAllConnections();
+    }
+    sweep() {
+        for (const map of [this.tickets, this.sessions])
+            for (const [key, grant] of map)
+                if (grant.expires <= Date.now())
+                    map.delete(key);
+    }
+    entry(req) {
+        const host = req.headers.host ?? "";
+        const id = host.split(".")[0];
+        if (!/^[a-f0-9]{32}$/.test(id) || host !== new URL(this.origin(id)).host)
+            return undefined;
+        const entry = this.registry.getView(id);
+        return entry?.view.kind === "web" ? entry : undefined;
+    }
+    authorize(req, id) {
+        this.sweep();
+        const token = (req.headers.cookie ?? "").split(";").map((part) => part.trim()).find((part) => part.startsWith(`${COOKIE}=`))?.slice(COOKIE.length + 1);
+        const session = token && this.sessions.get(token);
+        return session && session.appId === id ? session.expires : undefined;
+    }
+    track(id, socket, expires) {
+        let sockets = this.sockets.get(id);
+        if (!sockets) {
+            sockets = new Set();
+            this.sockets.set(id, sockets);
+        }
+        if (sockets.has(socket))
+            return;
+        sockets.add(socket);
+        const timer = setTimeout(() => socket.destroy(), Math.max(1, expires - Date.now()));
+        timer.unref();
+        socket.once("close", () => { clearTimeout(timer); sockets.delete(socket); if (!sockets.size)
+            this.sockets.delete(id); });
+    }
+    async handleShell(req, res, id) {
+        const origin = this.shellOrigin(id);
+        const nonce = randomBytes(16).toString("hex");
+        res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+        res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; connect-src 'self'; frame-src ${this.origin(id)}; frame-ancestors 'none'; base-uri 'none'; form-action 'none'`);
+        if (req.method === "GET" && this.styles.has(req.url ?? "")) {
+            res.setHeader("Content-Type", "text/css; charset=utf-8");
+            res.end(this.styles.get(req.url));
+            return;
+        }
+        if (req.url === OPEN_PATH && req.method === "GET") {
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.end(previewShell(nonce));
+            return;
+        }
+        if (req.url === "/__bivy/launch" && req.method === "POST") {
+            if (req.headers.origin !== origin) {
+                res.writeHead(403);
+                res.end();
+                return;
+            }
+            let ticket = "";
+            for await (const chunk of req) {
+                ticket += chunk.toString();
+                if (ticket.length > 128) {
+                    res.writeHead(413);
+                    res.end();
+                    return;
+                }
+            }
+            this.sweep();
+            const grant = this.tickets.get(ticket);
+            const entry = this.registry.getView(id);
+            if (!grant || grant.appId !== id || !entry) {
+                res.writeHead(401);
+                res.end();
+                return;
+            }
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ name: entry.app.name, origin: this.origin(id), returnTo: grant.returnTo }));
+            return;
+        }
+        res.writeHead(404);
+        res.end("Preview shell route not found.");
+    }
+    async handle(req, res) {
+        const entry = this.entry(req);
+        res.setHeader("Cache-Control", "no-store");
+        res.setHeader("Referrer-Policy", "no-referrer");
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        const shellId = /^view-([a-f0-9]{32})\./.exec(req.headers.host ?? "")?.[1];
+        if (shellId && req.headers.host === new URL(this.shellOrigin(shellId)).host) {
+            await this.handleShell(req, res, shellId);
+            return;
+        }
+        if (!entry) {
+            res.writeHead(404);
+            res.end("App unavailable. Republish from your Bivy session.");
+            return;
+        }
+        const id = entry.view.id;
+        if (req.url === OPEN_PATH && req.method === "GET") {
+            const nonce = randomBytes(16).toString("hex");
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+            res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${this.shellOrigin(id)}; base-uri 'none'`);
+            res.end(`<!doctype html><html lang="en"><meta name="viewport" content="width=device-width"><title>Open Bivy preview</title><p id="status" role="status">Opening preview…</p><script nonce="${nonce}">const ticket=location.hash.slice(1);history.replaceState(null,'',location.pathname);fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body:ticket}).then(r=>{if(!r.ok)throw Error();location.replace('/');}).catch(()=>{document.getElementById('status').textContent='Preview link expired or cookies are blocked. Open a new link from Bivy.';});</script></html>`);
+            return;
+        }
+        if (req.url === REDEEM_PATH && req.method === "POST") {
+            if (req.headers.origin !== this.origin(id)) {
+                res.writeHead(403);
+                res.end();
+                return;
+            }
+            let body = "";
+            for await (const chunk of req) {
+                body += chunk.toString();
+                if (body.length > 128) {
+                    res.writeHead(413);
+                    res.end();
+                    return;
+                }
+            }
+            this.sweep();
+            const grant = this.tickets.get(body);
+            if (!grant || grant.appId !== id || this.sessions.size >= 500) {
+                res.writeHead(401);
+                res.end();
+                return;
+            }
+            this.tickets.delete(body);
+            const token = randomBytes(32).toString("hex");
+            this.sessions.set(token, { appId: id, expires: Date.now() + HOUR });
+            res.setHeader("Set-Cookie", `${COOKIE}=${token}; Secure; HttpOnly; SameSite=Lax; Path=/; Max-Age=3600`);
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const expires = this.authorize(req, id);
+        if (!expires) {
+            res.writeHead(401);
+            res.end("Preview access expired. Open a new preview link from Bivy.");
+            return;
+        }
+        // Block cross-site mutations even if a client sends the preview cookie.
+        if (!["GET", "HEAD"].includes(req.method ?? "") && req.headers.origin !== this.origin(id)) {
+            res.writeHead(403);
+            res.end("Forbidden origin.");
+            return;
+        }
+        if (req.headers["sec-fetch-dest"] === "serviceworker") {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        if (!req.url?.startsWith("/") || req.url.startsWith("//")) {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        this.track(id, req.socket, expires);
+        if (entry.target.kind === "static") {
+            if (!["GET", "HEAD"].includes(req.method ?? "")) {
+                res.writeHead(405, { Allow: "GET, HEAD" });
+                res.end();
+                return;
+            }
+            let file;
+            try {
+                file = decodeURIComponent(req.url.split("?")[0]);
+            }
+            catch {
+                res.writeHead(400);
+                res.end();
+                return;
+            }
+            if (file.endsWith("/"))
+                file += "index.html";
+            const data = entry.target.files.get(file);
+            if (!data) {
+                res.writeHead(404);
+                res.end("File not found.");
+                return;
+            }
+            const headers = responseHeaders({}, this.shellOrigin(id));
+            headers["content-type"] = MIME[path.extname(file).toLowerCase()] || "application/octet-stream";
+            res.writeHead(200, { ...headers, "content-length": data.length });
+            res.end(req.method === "HEAD" ? undefined : data);
+            return;
+        }
+        if (entry.target.kind !== "service") {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const upstream = http.request({ hostname: "127.0.0.1", port: entry.target.port, path: req.url, method: req.method, headers: upstreamHeaders(req, this.origin(id)) }, (response) => {
+            res.writeHead(response.statusCode ?? 502, responseHeaders(response.headers, this.shellOrigin(id)));
+            response.on("error", () => res.destroy());
+            response.pipe(res);
+        });
+        upstream.setTimeout(60_000, () => upstream.destroy(new Error("Preview timed out")));
+        upstream.on("error", () => { if (!res.headersSent)
+            res.writeHead(502, { "content-type": "text/plain" }); res.end("App server unavailable. Start it on the registered port, then reload."); });
+        res.on("close", () => upstream.destroy());
+        req.pipe(upstream);
+    }
+    upgrade(req, socket, head) {
+        const entry = this.entry(req);
+        const expires = entry && this.authorize(req, entry.view.id);
+        if (!entry || !expires || entry.target.kind !== "service" || req.headers.origin !== this.origin(entry.view.id) || req.headers.upgrade?.toLowerCase() !== "websocket" || !req.url?.startsWith("/") || req.url.startsWith("//")) {
+            socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+            return;
+        }
+        this.track(entry.view.id, socket, expires);
+        const upstream = http.request({ hostname: "127.0.0.1", port: entry.target.port, path: req.url, headers: { ...upstreamHeaders(req, this.origin(entry.view.id)), connection: "Upgrade", upgrade: "websocket" } });
+        upstream.setTimeout(10_000, () => upstream.destroy());
+        upstream.on("upgrade", (response, peer, upstreamHead) => {
+            peer.setTimeout(0);
+            this.track(entry.view.id, peer, expires);
+            const headers = cleanHeaders(response.headers);
+            delete headers["set-cookie"];
+            socket.write(`HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n${Object.entries(headers).filter(([, value]) => value !== undefined).map(([key, value]) => `${key}: ${value}\r\n`).join("")}\r\n`);
+            if (upstreamHead.length)
+                socket.write(upstreamHead);
+            if (head.length)
+                peer.write(head);
+            socket.on("error", () => peer.destroy());
+            peer.on("error", () => socket.destroy());
+            socket.on("close", () => peer.destroy());
+            peer.on("close", () => socket.destroy());
+            socket.pipe(peer).pipe(socket);
+        });
+        upstream.on("response", (response) => { response.resume(); socket.end("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n"); });
+        upstream.on("error", () => socket.destroy());
+        socket.on("close", () => upstream.destroy());
+        upstream.end();
+    }
+}

package/dist/apps/preview-shell.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+/** This document lives on a different origin from app code. Never put a
+ * generated document on the shell host or let the frame navigate its parent. */
+export function previewShell(nonce) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Bivy · App preview</title>
+<link rel="stylesheet" href="/__bivy/tokens.css"><link rel="stylesheet" href="/__bivy/styles.css">
+<style nonce="${nonce}">
+html,body { margin:0; width:100%; height:100%; }
+body { display:flex; flex-direction:column; background:var(--bg); color:var(--ink); font-family:var(--font-sans); }
+nav { display:flex; align-items:center; gap:var(--space-2); padding:var(--space-2) var(--space-3); border-bottom:thin solid var(--line); background:var(--surface); flex-shrink:0; }
+nav .btn { min-height:var(--space-7); flex-shrink:0; }
+#title { flex:1; min-width:0; font-size:var(--text-sm); font-weight:var(--weight-semibold); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+#status { padding:var(--space-4); margin:0; font-size:var(--text-sm); }
+iframe { flex:1; min-height:0; width:100%; border:0; background:var(--bg); }
+[hidden] { display:none !important; }
+</style></head><body>
+<nav aria-label="Bivy preview controls"><button class="btn ghost" id="back">‹ Back to chat</button><span id="title">App preview</span><button class="btn ghost" id="reload" disabled>Reload</button></nav>
+<p id="status" role="status">Opening app…</p>
+<iframe id="app" title="App preview" hidden sandbox="allow-scripts allow-same-origin allow-forms allow-downloads allow-popups" referrerpolicy="no-referrer"></iframe>
+<script nonce="${nonce}">
+const frame=document.getElementById('app'),status=document.getElementById('status'),back=document.getElementById('back'),reload=document.getElementById('reload');
+const ticket=location.hash.slice(1);history.replaceState(null,'',location.pathname);
+let metadata;
+const storageKey='bivy-preview';
+function show(data,launch){
+  metadata=data;
+  document.getElementById('title').textContent=data.name;
+  document.getElementById('title').title=data.name;
+  document.title='Bivy · '+data.name;
+  back.title=data.returnTo?'Return to '+new URL(data.returnTo).host:'Close preview';
+  frame.title=data.name;
+  frame.hidden=false;
+  frame.src=data.origin+(launch?'/__bivy/open#'+launch:'/');
+  reload.disabled=false;
+  status.textContent='Loading app…';
+  frame.onload=()=>{status.hidden=true;};
+  // Store navigation metadata only, never tickets or cookies.
+  try{sessionStorage.setItem(storageKey,JSON.stringify(data));}catch{}
+}
+back.onclick=()=>{if(metadata?.returnTo){window.close();setTimeout(()=>location.replace(metadata.returnTo),100);}else{window.close();status.hidden=false;status.textContent='You can close this tab to return to Bivy.';}};
+reload.onclick=()=>{if(metadata){status.hidden=false;status.textContent='Reloading app…';frame.src=metadata.origin+'/';}};
+(async()=>{
+  if(ticket){
+    const response=await fetch('/__bivy/launch',{method:'POST',headers:{'Content-Type':'text/plain'},body:ticket});
+    if(!response.ok)throw Error();
+    show(await response.json(),ticket);
+  }else{
+    const stored=JSON.parse(sessionStorage.getItem(storageKey)||'null');
+    if(!stored)throw Error();
+    show(stored);
+  }
+})().catch(()=>{status.hidden=false;status.textContent='This preview link expired or the app was removed. Open a fresh preview from your Bivy chat.';});
+</script></body></html>`;
+}

package/dist/apps/registry.js

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+const MAX_BYTES = 25 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 100 * 1024 * 1024;
+const MAX_FILES = 2000;
+/** Snapshot, not a live filesystem server: symlinks and hidden files are never published. */
+function snapshot(workspace, directory) {
+    const base = fs.realpathSync(workspace);
+    const root = fs.realpathSync(path.resolve(base, directory));
+    const relative = path.relative(base, root);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        throw new Error("Static directory must be inside the session workspace.");
+    if (!fs.statSync(root).isDirectory())
+        throw new Error("Static entry must be a directory.");
+    const files = new Map();
+    let bytes = 0;
+    let entries = 0;
+    function walk(dir, prefix, depth) {
+        if (depth > 32)
+            throw new Error("Static directory is too deeply nested.");
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (++entries > MAX_FILES * 2)
+                throw new Error("Static directory contains too many entries.");
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const full = path.join(dir, entry.name);
+            const key = `${prefix}/${entry.name}`;
+            if (entry.isSymbolicLink())
+                throw new Error("Static snapshots cannot contain symlinks.");
+            if (entry.isDirectory())
+                walk(full, key, depth + 1);
+            else if (entry.isFile()) {
+                if (files.size >= MAX_FILES)
+                    throw new Error("Static snapshot exceeds 2,000 files.");
+                // O_NOFOLLOW closes the final-component symlink race. Verify the opened
+                // file's size, then bound the read even if another process grows it.
+                const fd = fs.openSync(full, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+                try {
+                    const stat = fs.fstatSync(fd);
+                    const resolved = fs.realpathSync(full);
+                    const rel = path.relative(root, resolved);
+                    const current = fs.statSync(resolved);
+                    if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel) || !stat.isFile() || stat.dev !== current.dev || stat.ino !== current.ino)
+                        throw new Error("Static file changed or escaped its directory during publication.");
+                    const size = stat.size;
+                    if (bytes + size > MAX_BYTES)
+                        throw new Error("Static snapshot exceeds 25 MiB.");
+                    const data = Buffer.alloc(size);
+                    let offset = 0;
+                    while (offset < size) {
+                        const n = fs.readSync(fd, data, offset, size - offset, offset);
+                        if (!n)
+                            break;
+                        offset += n;
+                    }
+                    files.set(key, data.subarray(0, offset));
+                    bytes += offset;
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+            }
+            else
+                throw new Error("Static snapshots can only contain regular files.");
+        }
+    }
+    walk(root, "", 0);
+    if (!files.has("/index.html"))
+        throw new Error("Static directory needs an index.html entry point.");
+    return { kind: "static", files, bytes };
+}
+/** Deliberately ephemeral: restart invalidates apps rather than trusting reused local ports. */
+export class AppRegistry {
+    reservedPorts;
+    apps = new Map();
+    views = new Map();
+    constructor(reservedPorts = []) {
+        this.reservedPorts = reservedPorts;
+    }
+    publish(sessionId, workspace, input) {
+        const name = (value) => {
+            if (typeof value !== "string" || !value.trim() || value.length > 100)
+                throw new Error("App and view names must contain 1–100 characters.");
+            return value.trim();
+        };
+        if (!input || input.version !== 1 || !Array.isArray(input.views) || !input.views.length || input.views.length > 8)
+            throw new Error("Expected manifest version 1 with 1–8 views.");
+        if (this.apps.size >= 50)
+            throw new Error("Remove an app before publishing more (limit: 50).");
+        const app = { id: randomBytes(16).toString("hex"), sessionId, name: name(input.name), views: [], createdAt: Date.now() };
+        const entries = [];
+        let total = [...this.views.values()].reduce((sum, item) => sum + (item.target.kind === "static" ? item.target.bytes : 0), 0);
+        for (const spec of input.views) {
+            const base = { id: randomBytes(16).toString("hex"), name: name(spec?.name) };
+            let target;
+            let view;
+            if (spec.kind === "web" && spec.source?.kind === "service") {
+                const port = spec.source.port;
+                if (!Number.isInteger(port) || port < 1024 || port > 65535 || this.reservedPorts.includes(port))
+                    throw new Error("Choose a non-reserved local service port between 1024 and 65535.");
+                target = { kind: "service", port };
+                view = { ...base, kind: "web", source: "service" };
+            }
+            else if (spec.kind === "web" && spec.source?.kind === "static") {
+                if (typeof spec.source.directory !== "string" || !spec.source.directory)
+                    throw new Error("Static directory is required.");
+                target = snapshot(workspace, spec.source.directory);
+                if (target.kind === "static")
+                    total += target.bytes;
+                if (total > MAX_TOTAL_BYTES)
+                    throw new Error("Static apps exceed the node's 100 MiB snapshot budget.");
+                view = { ...base, kind: "web", source: "static" };
+            }
+            else if (spec.kind === "terminal") {
+                if (typeof spec.command !== "string" || !spec.command.trim() || spec.command.length > 1000 || spec.command.includes("\u0000"))
+                    throw new Error("Terminal view requires an executable command.");
+                if (spec.args !== undefined && (!Array.isArray(spec.args) || spec.args.length > 100 || spec.args.some((arg) => typeof arg !== "string" || arg.length > 4000 || arg.includes("\u0000"))))
+                    throw new Error("Invalid terminal arguments.");
+                const args = [...(spec.args ?? [])];
+                target = { kind: "terminal", command: spec.command, args, workspace: fs.realpathSync(workspace) };
+                view = { ...base, kind: "terminal", command: spec.command, args };
+            }
+            else
+                throw new Error("Unsupported app view. This machine supports web and terminal views.");
+            app.views.push(view);
+            entries.push({ app, view, target });
+        }
+        // Commit all views together: a bad later view cannot leave a partial app.
+        this.apps.set(app.id, app);
+        for (const entry of entries)
+            this.views.set(entry.view.id, entry);
+        return structuredClone(app);
+    }
+    list(sessionId) {
+        return structuredClone([...this.apps.values()].filter((app) => app.sessionId === sessionId));
+    }
+    getView(id) { return this.views.get(id); }
+    require(sessionId, id) {
+        const app = this.apps.get(id);
+        if (!app || app.sessionId !== sessionId)
+            throw new Error("App not found in this session. Republish after a machine restart.");
+        return app;
+    }
+    requireView(sessionId, appId, viewId) {
+        this.require(sessionId, appId);
+        const view = this.views.get(viewId);
+        if (!view || view.app.id !== appId)
+            throw new Error("View not found in this app.");
+        return view;
+    }
+    remove(sessionId, id) {
+        const app = this.require(sessionId, id);
+        for (const view of app.views)
+            this.views.delete(view.id);
+        this.apps.delete(id);
+    }
+}