@bivy/bivy 0.17.3-staging.2 → 0.17.3-staging.3

package/dist/apps/gateway.js

@@ -15,7 +15,25 @@ const MIME = {
 const COOKIE = "__Host-bivy-preview";
 const OPEN_PATH = "/__bivy/open";
 const REDEEM_PATH = "/__bivy/redeem";
+const REVISION_PATH = "/__bivy/revision";
 const HOUR = 60 * 60_000;
+/** Marks gateway-generated "server not answering" responses, so recovery
+ * polling can tell them apart from an app's own 502s. */
+const UPSTREAM_DOWN = "x-bivy-upstream-down";
+/** A top-level or framed page load. Browsers without Fetch Metadata still ask for HTML. */
+function isPageLoad(req) {
+    const dest = req.headers["sec-fetch-dest"];
+    return req.method === "GET" && (dest ? ["document", "iframe"].includes(dest) : /text\/html/.test(req.headers.accept ?? ""));
+}
+/** Served on the app's origin in place of a blank frame. It reloads itself once
+ * the server answers, and tells a framing shell so it can offer next steps. */
+function upstreamDownPage(nonce, port, shellOrigin) {
+    return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Waiting for the app server</title>
+<style nonce="${nonce}">:root{color-scheme:light dark;font-family:system-ui,sans-serif}body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px;box-sizing:border-box;text-align:center}main{max-width:32rem}h1{font-size:1.25rem;margin:0 0 8px}p{margin:0;opacity:.75;line-height:1.5}</style>
+<main><h1>Nothing is answering on port ${port}</h1><p role="status">The app server stopped or hasn’t started yet. This page reloads by itself when it’s back.</p></main>
+<script nonce="${nonce}">const tell=state=>{if(parent!==window)parent.postMessage({type:'bivy:upstream',state,port:${port}},${JSON.stringify(shellOrigin)});};tell('down');
+const poll=async()=>{try{const r=await fetch(location.href,{method:'HEAD',cache:'no-store'});if(!r.headers.has('${UPSTREAM_DOWN}')){tell('up');location.reload();return;}}catch{}setTimeout(poll,2000);};setTimeout(poll,2000);</script></html>`;
+}
 /** Copied links are reusable until revoked, capped so a forgotten one lapses. */
 export const SHARE_TTL = 24 * HOUR;
 const HOP = new Set(["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade"]);
@@ -176,7 +194,7 @@ export class AppGateway {
         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'`);
+        res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; connect-src 'self' ${this.origin(id)}; 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));
@@ -297,6 +315,13 @@ export class AppGateway {
             return;
         }
         this.track(id, req.socket, expires);
+        if (req.url.startsWith(`${REVISION_PATH}?`) && req.method === "GET") {
+            this.revision(req, res, entry);
+            return;
+        }
+        // Remember the framed page so a turn reload lands where the user was.
+        if (req.method === "GET" && req.headers["sec-fetch-dest"] === "iframe" && req.url.length <= 2048)
+            entry.lastPath = req.url;
         if (entry.target.kind === "static") {
             if (!["GET", "HEAD"].includes(req.method ?? "")) {
                 res.writeHead(405, { Allow: "GET, HEAD" });
@@ -314,7 +339,17 @@ export class AppGateway {
             }
             if (file.endsWith("/"))
                 file += "index.html";
-            const data = entry.target.files.get(file);
+            let data = entry.target.files.get(file);
+            let status = 200;
+            // Client-side routes: an extensionless page load falls back like common
+            // static hosts do — to 404.html (status 404) when present, else index.html.
+            if (!data && !path.extname(file) && isPageLoad(req)) {
+                const notFound = entry.target.files.get("/404.html");
+                file = notFound ? "/404.html" : "/index.html";
+                data = notFound ?? entry.target.files.get(file);
+                if (notFound)
+                    status = 404;
+            }
             if (!data) {
                 res.writeHead(404);
                 res.end("File not found.");
@@ -322,7 +357,7 @@ export class AppGateway {
             }
             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.writeHead(status, { ...headers, "content-length": data.length });
             res.end(req.method === "HEAD" ? undefined : data);
             return;
         }
@@ -331,17 +366,54 @@ export class AppGateway {
             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) => {
+        const port = entry.target.port;
+        const upstream = http.request({ hostname: "127.0.0.1", 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."); });
+        upstream.on("error", () => {
+            if (res.headersSent) {
+                res.destroy();
+                return;
+            }
+            if (!isPageLoad(req)) {
+                res.writeHead(502, { "content-type": "text/plain", [UPSTREAM_DOWN]: "1" });
+                res.end("App server unavailable. Start it on the registered port, then reload.");
+                return;
+            }
+            const nonce = randomBytes(16).toString("hex");
+            res.writeHead(502, { "content-type": "text/html; charset=utf-8", [UPSTREAM_DOWN]: "1", "content-security-policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${this.shellOrigin(id)}; base-uri 'none'` });
+            res.end(upstreamDownPage(nonce, port, this.shellOrigin(id)));
+        });
         res.on("close", () => upstream.destroy());
         req.pipe(upstream);
     }
+    /** Long poll from the trusted shell (same-site, credentialed CORS): answers
+     * when the view's revision differs from `after`, or after 25 seconds. */
+    revision(req, res, entry) {
+        const id = entry.view.id;
+        const after = Number(new URL(req.url, "http://gateway").searchParams.get("after"));
+        let timer;
+        const onRevision = (viewId) => { if (viewId === id)
+            send(); };
+        const cleanup = () => { clearTimeout(timer); this.registry.off("revision", onRevision); };
+        const send = () => {
+            cleanup();
+            if (res.writableEnded || res.destroyed)
+                return;
+            res.writeHead(200, { "content-type": "application/json", "access-control-allow-origin": this.shellOrigin(id), "access-control-allow-credentials": "true", vary: "Origin" });
+            res.end(JSON.stringify({ revision: entry.revision, path: entry.lastPath ?? "/" }));
+        };
+        if (entry.revision !== after) {
+            send();
+            return;
+        }
+        this.registry.on("revision", onRevision);
+        timer = setTimeout(send, 25_000);
+        res.on("close", cleanup);
+    }
     upgrade(req, socket, head) {
         const entry = this.entry(req);
         const expires = entry && this.authorize(req, entry.view.id);
@@ -350,7 +422,8 @@ export class AppGateway {
             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" } });
+        const port = entry.target.port;
+        const upstream = http.request({ hostname: "127.0.0.1", 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);

package/dist/apps/listeners.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+/** Loopback or wildcard TCP listeners whose process runs inside a workspace.
+ * Agent-neutral by design: every framework and agent starts servers the same
+ * way, so the process table is the one hook that works for all of them. A
+ * listener is only an offer — access still needs a user's tap and a grant. */
+export async function scanListeners(workspace, platform = process.platform) {
+    let root;
+    try {
+        root = await fs.realpath(workspace);
+    }
+    catch {
+        return [];
+    }
+    const found = platform === "linux" ? await scanProc(root) : platform === "darwin" ? await scanLsof(root) : [];
+    const byPort = new Map();
+    for (const offer of found)
+        if (offer.pid !== process.pid && offer.port >= 1024 && !byPort.has(offer.port))
+            byPort.set(offer.port, offer);
+    return [...byPort.values()].sort((a, b) => a.port - b.port);
+}
+const inside = (root, dir) => dir === root || dir.startsWith(root + path.sep);
+/** `local_address` in /proc/net/tcp{,6}: hex address in little-endian 32-bit words. */
+export function listenPort(line) {
+    const cols = line.trim().split(/\s+/);
+    if (cols.length < 10 || cols[3] !== "0A")
+        return undefined; // 0A = LISTEN
+    const [address, portHex] = cols[1].split(":");
+    const words = address.match(/.{8}/g) ?? [];
+    const last = words[words.length - 1] ?? "";
+    const zero = /^0+$/.test(address);
+    const v4Loopback = last.endsWith("7F") && (words.length === 1 || words.slice(0, 3).join("") === "0000000000000000FFFF0000");
+    const v6Loopback = address === "00000000000000000000000001000000";
+    if (!zero && !v4Loopback && !v6Loopback)
+        return undefined;
+    return { inode: cols[9], port: parseInt(portHex, 16) };
+}
+async function scanProc(root) {
+    const sockets = new Map();
+    for (const file of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+        const text = await fs.readFile(file, "utf8").catch(() => "");
+        for (const line of text.split("\n").slice(1)) {
+            const hit = listenPort(line);
+            if (hit && hit.inode !== "0")
+                sockets.set(hit.inode, hit.port);
+        }
+    }
+    if (!sockets.size)
+        return [];
+    const offers = [];
+    const pids = (await fs.readdir("/proc").catch(() => [])).filter((name) => /^\d+$/.test(name));
+    // cwd first: other users' processes fail here, and only workspace processes
+    // pay for an fd walk.
+    await Promise.all(pids.map(async (pid) => {
+        const cwd = await fs.readlink(`/proc/${pid}/cwd`).catch(() => "");
+        if (!cwd || !inside(root, cwd))
+            return;
+        const fds = await fs.readdir(`/proc/${pid}/fd`).catch(() => []);
+        const ports = new Set();
+        for (const fd of fds) {
+            const target = await fs.readlink(`/proc/${pid}/fd/${fd}`).catch(() => "");
+            const inode = /^socket:\[(\d+)\]$/.exec(target)?.[1];
+            const port = inode ? sockets.get(inode) : undefined;
+            if (port)
+                ports.add(port);
+        }
+        if (!ports.size)
+            return;
+        const argv = (await fs.readFile(`/proc/${pid}/cmdline`, "utf8").catch(() => "")).split("\0").filter(Boolean);
+        for (const port of ports)
+            offers.push({ port, pid: Number(pid), command: commandLabel(argv) });
+    }));
+    return offers;
+}
+/** `lsof -F` field output: p<pid>, c<command>, n<name> records. */
+export function parseLsof(stdout) {
+    const records = [];
+    for (const line of stdout.split("\n")) {
+        if (line.startsWith("p"))
+            records.push({ pid: Number(line.slice(1)), values: [] });
+        else if (line.startsWith("n") && records.length)
+            records[records.length - 1].values.push(line.slice(1));
+    }
+    return records;
+}
+async function scanLsof(root) {
+    const run = (args) => execFileP("lsof", args, { timeout: 4000, maxBuffer: 4 * 1024 * 1024 }).then((r) => r.stdout, (e) => e.stdout ?? "");
+    const listening = parseLsof(await run(["-nP", "-iTCP", "-sTCP:LISTEN", "-Fpn"]));
+    if (!listening.length)
+        return [];
+    const cwds = new Map(parseLsof(await run(["-a", "-d", "cwd", "-Fpn", "-p", listening.map((r) => r.pid).join(",")])).map((r) => [r.pid, r.values[0] ?? ""]));
+    const offers = [];
+    for (const { pid, values } of listening) {
+        const cwd = await fs.realpath(cwds.get(pid) ?? "").catch(() => "");
+        if (!cwd || !inside(root, cwd))
+            continue;
+        const args = (await execFileP("ps", ["-p", String(pid), "-o", "args="], { timeout: 4000 }).then((r) => r.stdout, () => "")).trim();
+        for (const name of values) {
+            const match = /^(\*|127\.[\d.]+|\[::1\]|\[::\]|localhost):(\d+)$/.exec(name);
+            if (match)
+                offers.push({ port: Number(match[2]), pid, command: commandLabel(args.split(/\s+/)) });
+        }
+    }
+    return offers;
+}
+/** "node /x/node_modules/.bin/vite --port 5173" → "node vite --port 5173". */
+function commandLabel(argv) {
+    const label = argv.slice(0, 4).map((arg) => arg.startsWith("/") || arg.startsWith(".") ? path.basename(arg) : arg).join(" ");
+    return label.length > 60 ? `${label.slice(0, 59)}…` : label || "server";
+}

package/dist/apps/preview-shell.js

@@ -10,12 +10,15 @@ 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; }
+#stamp { font-size:var(--text-xs); white-space:nowrap; }
 #title { flex:1; min-width:0; font-size:var(--text-sm); font-weight:var(--weight-semibold); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+#down { flex-shrink:0; }
 #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>
+<nav aria-label="Bivy preview controls"><button class="btn ghost" id="back">‹ Back to chat</button><span id="title">App preview</span><span id="stamp" class="muted" role="status"></span><button class="btn ghost" id="reload" disabled>Reload</button></nav>
+<div class="banner" data-tone="warn" id="down" hidden><span class="banner-text" id="down-text" role="status"></span><span class="banner-actions"><button class="btn sm" id="ask" hidden>Ask agent to fix</button></span></div>
 <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}">
@@ -34,10 +37,44 @@ function show(data,launch){
   frame.src=data.origin+(launch?'/__bivy/open#'+launch:'/');
   reload.disabled=false;
   status.textContent='Loading app…';
-  frame.onload=()=>{status.hidden=true;};
+  frame.onload=()=>{status.hidden=true;if(revision===null){revision=-1;watch();}else if(wake)wake();};
   // Store navigation metadata only, never tickets or cookies.
   try{sessionStorage.setItem(storageKey,JSON.stringify(data));}catch{}
 }
+// Reload when an agent turn changes files, returning to the last framed page.
+// Until the frame has redeemed its access cookie, polls fail; back off, and
+// let the next frame load retry at once.
+let revision=null,retry=0,wake=null;
+async function watch(){
+  wake=null;
+  try{
+    const r=await fetch(metadata.origin+'/__bivy/revision?after='+revision,{credentials:'include',cache:'no-store'});
+    if(!r.ok)throw Error();
+    const d=await r.json();
+    if(revision>=0&&d.revision!==revision){
+      const path=typeof d.path==='string'&&d.path.startsWith('/')&&!d.path.startsWith('//')?d.path:'/';
+      frame.src=metadata.origin+path;
+      document.getElementById('stamp').textContent='Updated after the agent’s turn';
+    }
+    revision=d.revision;retry=0;setTimeout(watch,0);
+  }catch{retry=Math.min(30000,(retry||1000)*2);const t=setTimeout(watch,retry);wake=()=>{clearTimeout(t);watch();};}
+}
+// The app origin reports when its server stops answering. Its content is
+// untrusted: the port is only ever placed in a draft the user reviews.
+const down=document.getElementById('down'),downText=document.getElementById('down-text'),ask=document.getElementById('ask');
+let downPort=0;
+addEventListener('message',e=>{
+  if(!metadata||e.origin!==metadata.origin||e.source!==frame.contentWindow||e.data?.type!=='bivy:upstream')return;
+  downPort=Number(e.data.port)||0;
+  down.hidden=e.data.state!=='down';
+  downText.textContent='Nothing is answering on port '+downPort+'.';
+  ask.hidden=!metadata.returnTo;
+});
+ask.onclick=()=>{
+  const to=new URL(metadata.returnTo),session=to.pathname.split('/').pop();
+  const text='The app preview "'+metadata.name+'" isn’t loading: nothing is answering on port '+downPort+'. Please find out why the server stopped, restart it, and tell me when it’s back.';
+  location.assign(to.origin+'/share?session='+encodeURIComponent(session)+'&text='+encodeURIComponent(text));
+};
 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()=>{

package/dist/apps/registry.js

@@ -3,9 +3,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
 const MAX_BYTES = 25 * 1024 * 1024;
 const MAX_TOTAL_BYTES = 100 * 1024 * 1024;
 const MAX_FILES = 2000;
+const sameFiles = (a, b) => a.size === b.size && [...a].every(([key, data]) => b.get(key)?.equals(data));
 /** Snapshot, not a live filesystem server: symlinks and hidden files are never published. */
 function snapshot(workspace, directory) {
     const base = fs.realpathSync(workspace);
@@ -73,12 +75,14 @@ function snapshot(workspace, directory) {
     return { kind: "static", files, bytes };
 }
 /** Deliberately ephemeral: restart invalidates apps rather than trusting reused local ports. */
-export class AppRegistry {
+export class AppRegistry extends EventEmitter {
     reservedPorts;
     apps = new Map();
     views = new Map();
     constructor(reservedPorts = []) {
+        super();
         this.reservedPorts = reservedPorts;
+        this.setMaxListeners(0);
     }
     publish(sessionId, workspace, input) {
         const name = (value) => {
@@ -97,6 +101,7 @@ export class AppRegistry {
             const base = { id: randomBytes(16).toString("hex"), name: name(spec?.name) };
             let target;
             let view;
+            let source;
             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))
@@ -108,8 +113,8 @@ export class AppRegistry {
                 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;
+                source = { workspace, directory: spec.source.directory };
+                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" };
@@ -126,7 +131,7 @@ export class AppRegistry {
             else
                 throw new Error("Unsupported app view. This machine supports web and terminal views.");
             app.views.push(view);
-            entries.push({ app, view, target });
+            entries.push({ app, view, target, revision: 0, source });
         }
         // Commit all views together: a bad later view cannot leave a partial app.
         this.apps.set(app.id, app);
@@ -138,6 +143,44 @@ export class AppRegistry {
         return structuredClone([...this.apps.values()].filter((app) => app.sessionId === sessionId));
     }
     getView(id) { return this.views.get(id); }
+    /** An agent turn changed files: re-take changed static snapshots and bump
+     * every affected web view (emits `revision`). Returns the bumped view IDs. */
+    touch(sessionId) {
+        const bumped = [];
+        let total = [...this.views.values()].reduce((sum, item) => sum + (item.target.kind === "static" ? item.target.bytes : 0), 0);
+        for (const entry of this.views.values()) {
+            if (entry.app.sessionId !== sessionId || entry.view.kind !== "web")
+                continue;
+            if (entry.target.kind === "static") {
+                if (!entry.source)
+                    continue;
+                let next;
+                // A broken build keeps the last good snapshot rather than blanking the preview.
+                try {
+                    next = snapshot(entry.source.workspace, entry.source.directory);
+                }
+                catch {
+                    continue;
+                }
+                if (sameFiles(entry.target.files, next.files) || total - entry.target.bytes + next.bytes > MAX_TOTAL_BYTES)
+                    continue;
+                total += next.bytes - entry.target.bytes;
+                entry.target = next;
+            }
+            entry.revision++;
+            bumped.push(entry.view.id);
+            this.emit("revision", entry.view.id);
+        }
+        return bumped;
+    }
+    /** Ports a session already previews, and ports no app may claim. */
+    claimedPorts(sessionId) {
+        const ports = new Set(this.reservedPorts);
+        for (const { app, target } of this.views.values())
+            if (app.sessionId === sessionId && target.kind === "service")
+                ports.add(target.port);
+        return ports;
+    }
     require(sessionId, id) {
         const app = this.apps.get(id);
         if (!app || app.sessionId !== sessionId)

package/dist/apps/service.js

@@ -1,17 +1,34 @@
+import { scanListeners } from "./listeners.js";
 /** Composes view providers; registry never spawns processes and the gateway
  * never knows about terminals. New providers can extend open/remove here. */
 export class AppService {
     registry;
     gateway;
     terminals;
+    scan;
     terminalStarts = new Map();
-    constructor(registry, gateway, terminals) {
+    constructor(registry, gateway, terminals, scan = scanListeners) {
         this.registry = registry;
         this.gateway = gateway;
         this.terminals = terminals;
+        this.scan = scan;
     }
     list(sessionId) { return { apps: this.registry.list(sessionId), previewAvailable: Boolean(this.gateway) && this.gateway?.available !== false }; }
     publish(sessionId, workspace, manifest) { return this.registry.publish(sessionId, workspace, manifest); }
+    /** An agent turn changed files in this session's workspace. */
+    turnChanged(sessionId) { return this.registry.touch(sessionId); }
+    /** Servers running in the workspace that this session doesn't preview yet. */
+    async offers(sessionId, workspace) {
+        const claimed = this.registry.claimedPorts(sessionId);
+        return { offers: (await this.scan(workspace)).filter((offer) => !claimed.has(offer.port)) };
+    }
+    /** Publish a detected server. Re-scanned so a client can't adopt an arbitrary port. */
+    async adopt(sessionId, workspace, port) {
+        const offer = (await this.offers(sessionId, workspace)).offers.find((item) => item.port === port);
+        if (!offer)
+            throw new Error(`Nothing in this session's workspace is listening on port ${port} any more.`);
+        return this.registry.publish(sessionId, workspace, { version: 1, name: `${offer.command} · :${port}`.slice(0, 100), views: [{ kind: "web", name: `Port ${port}`, source: { kind: "service", port } }] });
+    }
     async open(sessionId, appId, viewId, returnTo) {
         const entry = this.registry.requireView(sessionId, appId, viewId);
         if (entry.view.kind === "web") {

package/dist/controllers/app-commands.js

@@ -1,12 +1,22 @@
 export function createAppCommands(service, workspaceFor, published = () => { }) {
+    const workspaceOf = (sessionId) => {
+        const workspace = workspaceFor(sessionId);
+        if (!workspace)
+            throw new Error("Open the session on this machine before publishing an app.");
+        return workspace;
+    };
     const operations = {
         "apps.list": (msg) => service.list(String(msg.sessionId)),
         "apps.publish": (msg) => {
             const sessionId = String(msg.sessionId);
-            const workspace = workspaceFor(sessionId);
-            if (!workspace)
-                throw new Error("Open the session on this machine before publishing an app.");
-            const app = service.publish(sessionId, workspace, msg.manifest);
+            const app = service.publish(sessionId, workspaceOf(sessionId), msg.manifest);
+            published(app);
+            return { app };
+        },
+        "apps.offers": (msg) => service.offers(String(msg.sessionId), workspaceOf(String(msg.sessionId))),
+        "apps.adopt": async (msg) => {
+            const sessionId = String(msg.sessionId);
+            const app = await service.adopt(sessionId, workspaceOf(sessionId), Number(msg.port));
             published(app);
             return { app };
         },
@@ -18,7 +28,7 @@ export function createAppCommands(service, workspaceFor, published = () => { })
     return Object.fromEntries(Object.entries(operations).map(([kind, execute]) => [kind, async (msg, ctx) => {
             try {
                 ctx.reply({ type: `${kind}.ok`, requestId: msg.requestId, ...await execute(msg) });
-                if (kind === "apps.publish" || kind === "apps.remove")
+                if (kind === "apps.publish" || kind === "apps.adopt" || kind === "apps.remove")
                     ctx.broadcast({ type: "apps.changed", sessionId: msg.sessionId });
             }
             catch (error) {

package/dist/protocol/client-command-routes.js

@@ -3,7 +3,7 @@
 /** Direct-mode adapters for operations whose canonical implementation is the
  * client command registry. Relay and HTTP now differ only in framing. */
 export const CLIENT_COMMAND_ROUTES = [
-    ...["list", "publish", "open", "share", "revoke", "remove"].map((action) => ({ method: "post", path: `/api/apps/${action}`, kind: `apps.${action}` })),
+    ...["list", "publish", "offers", "adopt", "open", "share", "revoke", "remove"].map((action) => ({ method: "post", path: `/api/apps/${action}`, kind: `apps.${action}` })),
     { method: "post", path: "/api/auth/credentials/native-preview", kind: "credentials.native.preview" },
     { method: "post", path: "/api/auth/credentials/native-import", kind: "credentials.native.import" },
     { method: "post", path: "/api/session/pause", kind: "session.pause" },

package/dist/protocol/client-command-schemas.js

@@ -10,6 +10,8 @@ export const CLIENT_COMMAND_SCHEMAS = {
     ping: Type.Object(request),
     "apps.list": Type.Object({ ...request, ...session }),
     "apps.publish": Type.Object({ ...request, ...session, manifest: Type.Unknown() }),
+    "apps.offers": Type.Object({ ...request, ...session }),
+    "apps.adopt": Type.Object({ ...request, ...session, port: Type.Integer({ minimum: 1024, maximum: 65535 }) }),
     "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })) }),
     "apps.share": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.revoke": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),

package/dist/server.js

@@ -963,6 +963,8 @@ async function harnessEndTurn(record) {
         record.workspaceState = (await harness.isDirty(record.id)) ? "dirty" : "clean";
         if (!result || result.changes.length === 0)
             return;
+        // Open previews of this session reload; static snapshots are re-taken.
+        appService.turnChanged(record.id);
         broadcast({
             type: "session.changes",
             sessionId: record.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.17.3-staging.2",
+  "version": "0.17.3-staging.3",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",