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

package/dist/apps/screenshot.js

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import http from "node:http";
+import { once } from "node:events";
+import { spawn, execFileSync } from "node:child_process";
+import { WebSocket } from "ws";
+/** Browsers tried in order; BIVY_CHROME overrides. Any Chromium works. */
+const CANDIDATES = [
+    "google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+];
+export function findChrome(env = process.env) {
+    if (env.BIVY_CHROME)
+        return fs.existsSync(env.BIVY_CHROME) ? env.BIVY_CHROME : undefined;
+    for (const candidate of CANDIDATES) {
+        if (candidate.startsWith("/")) {
+            if (fs.existsSync(candidate))
+                return candidate;
+            continue;
+        }
+        try {
+            return execFileSync("which", [candidate], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+        }
+        catch { /* next */ }
+    }
+    // A Playwright install (common on dev machines) ships a headless shell.
+    const cache = path.join(os.homedir(), ".cache", "ms-playwright");
+    for (const dir of fs.existsSync(cache) ? fs.readdirSync(cache).sort().reverse() : []) {
+        for (const bin of ["chrome-headless-shell-linux64/chrome-headless-shell", "chrome-linux/chrome"]) {
+            const file = path.join(cache, dir, bin);
+            if (dir.startsWith("chromium") && fs.existsSync(file))
+                return file;
+        }
+    }
+    return undefined;
+}
+/** Serves a static snapshot on loopback for the duration of a shot. */
+async function serveSnapshot(files) {
+    const server = http.createServer((req, res) => {
+        let file = decodeURIComponent((req.url ?? "/").split("?")[0]);
+        if (file.endsWith("/"))
+            file += "index.html";
+        const data = files.get(file) ?? (path.extname(file) ? undefined : files.get("/index.html"));
+        if (!data) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        res.end(data);
+    });
+    server.listen(0, "127.0.0.1");
+    await once(server, "listening");
+    return { origin: `http://127.0.0.1:${server.address().port}`, close: () => { server.close(); server.closeAllConnections(); } };
+}
+/** Minimal CDP client over one browser-level WebSocket (flattened sessions). */
+class Cdp {
+    ws;
+    next = 0;
+    pending = new Map();
+    listeners = new Set();
+    constructor(ws) {
+        this.ws = ws;
+        ws.on("message", (raw) => {
+            const msg = JSON.parse(raw.toString());
+            if (msg.id !== undefined) {
+                const call = this.pending.get(msg.id);
+                this.pending.delete(msg.id);
+                if (msg.error)
+                    call?.reject(new Error(msg.error.message));
+                else
+                    call?.resolve(msg.result);
+            }
+            else
+                for (const fn of this.listeners)
+                    fn(msg.method, msg.params, msg.sessionId);
+        });
+    }
+    send(method, params = {}, sessionId) {
+        const id = ++this.next;
+        return new Promise((resolve, reject) => { this.pending.set(id, { resolve, reject }); this.ws.send(JSON.stringify({ id, method, params, sessionId })); });
+    }
+    once(method, sessionId, ms) {
+        return new Promise((resolve) => {
+            const fn = (m, _p, s) => { if (m === method && s === sessionId)
+                finish(); };
+            const finish = () => { clearTimeout(timer); this.listeners.delete(fn); resolve(); };
+            const timer = setTimeout(finish, ms);
+            this.listeners.add(fn);
+        });
+    }
+}
+/** Screenshots web views with one headless browser, one shot at a time, so
+ * small machines cope. Service views are loaded straight from loopback;
+ * static views from a throwaway loopback server. Files are PNGs in `outDir`. */
+export async function takeShots(views, request, outDir, chrome = findChrome()) {
+    if (!chrome)
+        throw new Error("No Chrome or Chromium found on this machine. Install one, or set BIVY_CHROME to its path.");
+    fs.mkdirSync(outDir, { recursive: true });
+    const profile = fs.mkdtempSync(path.join(os.tmpdir(), "bivy-shot-"));
+    const servers = [];
+    let ws;
+    let browser;
+    const deadline = setTimeout(() => browser?.kill("SIGKILL"), 120_000);
+    // Chromium's sandbox is unavailable as root and where AppArmor blocks user
+    // namespaces (Ubuntu 23.10+). The pages are the session's own apps, already
+    // running as this user, so retrying without it doesn't widen what they can do.
+    const launch = (sandbox) => new Promise((resolve, reject) => {
+        const args = ["--headless=new", "--remote-debugging-port=0", `--user-data-dir=${profile}`, "--no-first-run", "--no-default-browser-check", "--disable-gpu", "--hide-scrollbars", "--mute-audio", ...(sandbox ? [] : ["--no-sandbox"]), "about:blank"];
+        const child = spawn(chrome, args, { stdio: ["ignore", "ignore", "pipe"] });
+        browser = child;
+        let text = "";
+        const timer = setTimeout(() => reject(new Error("The browser didn't start in time.")), 20_000);
+        child.stderr.on("data", (chunk) => { text += chunk; const m = /DevTools listening on (ws:\/\/\S+)/.exec(text); if (m) {
+            clearTimeout(timer);
+            resolve(m[1]);
+        } });
+        child.once("exit", () => { clearTimeout(timer); reject(Object.assign(new Error("The browser exited before it was ready."), { noSandbox: /No usable sandbox|--no-sandbox/i.test(text) })); });
+    });
+    try {
+        const endpoint = await launch(process.getuid?.() !== 0).catch((error) => {
+            if (error.noSandbox)
+                return launch(false);
+            throw error;
+        });
+        ws = new WebSocket(endpoint, { perMessageDeflate: false, maxPayload: 256 * 1024 * 1024 });
+        await once(ws, "open");
+        const cdp = new Cdp(ws);
+        const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
+        const { sessionId } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
+        await cdp.send("Page.enable", {}, sessionId);
+        const shots = [];
+        for (const entry of views) {
+            let origin;
+            if (entry.target.kind === "service")
+                origin = `http://127.0.0.1:${entry.target.port}`;
+            else if (entry.target.kind === "static") {
+                const server = await serveSnapshot(entry.target.files);
+                servers.push(server);
+                origin = server.origin;
+            }
+            else
+                continue;
+            for (const width of request.widths)
+                for (const theme of request.themes) {
+                    const mobile = width < 600;
+                    await cdp.send("Emulation.setDeviceMetricsOverride", { width, height: mobile ? 844 : 800, deviceScaleFactor: mobile ? 2 : 1, mobile }, sessionId);
+                    await cdp.send("Emulation.setEmulatedMedia", { features: [{ name: "prefers-color-scheme", value: theme }] }, sessionId);
+                    const loaded = cdp.once("Page.loadEventFired", sessionId, 15_000);
+                    await cdp.send("Page.navigate", { url: origin + request.path }, sessionId);
+                    await loaded;
+                    await new Promise((r) => setTimeout(r, 400)); // let fonts and first effects settle
+                    const { data } = await cdp.send("Page.captureScreenshot", { format: "png" }, sessionId);
+                    const file = path.join(outDir, `${entry.view.id.slice(0, 8)}-${width}-${theme}.png`);
+                    fs.writeFileSync(file, Buffer.from(data, "base64"));
+                    shots.push({ viewId: entry.view.id, view: entry.view.name, width, theme, file });
+                }
+        }
+        return shots;
+    }
+    finally {
+        clearTimeout(deadline);
+        ws?.terminate();
+        for (const server of servers)
+            server.close();
+        // Wait for the browser to exit before removing its profile: a killed
+        // Chrome can still be writing into it. Cleanup never fails a shot.
+        if (browser && browser.exitCode === null && browser.signalCode === null) {
+            const exited = once(browser, "exit").catch(() => { });
+            browser.kill("SIGKILL");
+            await exited;
+        }
+        try {
+            fs.rmSync(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+        }
+        catch { /* temp dir; the OS reclaims it */ }
+    }
+}

package/dist/apps/service.js

@@ -1,23 +1,110 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { scanListeners } from "./listeners.js";
+import { takeShots } from "./screenshot.js";
 /** Composes view providers; registry never spawns processes and the gateway
  * never knows about terminals. New providers can extend open/remove here. */
+/** A managed server that keeps exiting is left down after this many restarts
+ * in RESTART_WINDOW; opening the view again tries afresh. */
+const MAX_RESTARTS = 5;
+/** Compare keeps this many shots per view, taken after servers settle. */
+const COMPARE_KEEP = 4;
+const COMPARE_SETTLE_MS = 1_500;
+const RESTART_WINDOW = 10 * 60_000;
 export class AppService {
     registry;
     gateway;
     terminals;
     terminalStarts = new Map();
-    constructor(registry, gateway, terminals) {
+    servers = new Map();
+    scan;
+    serverWatchMs;
+    screenshots;
+    shooting = Promise.resolve();
+    constructor(registry, gateway, terminals, options = {}) {
         this.registry = registry;
         this.gateway = gateway;
         this.terminals = terminals;
+        this.scan = options.scan ?? scanListeners;
+        this.serverWatchMs = options.serverWatchMs ?? 5_000;
+        this.screenshots = { enabled: options.screenshots?.enabled ?? (() => false), take: options.screenshots?.take ?? takeShots };
+    }
+    list(sessionId) {
+        const available = Boolean(this.gateway) && this.gateway?.available !== false;
+        const apps = this.registry.list(sessionId);
+        for (const app of apps)
+            for (const view of app.views) {
+                if (view.kind !== "web")
+                    continue;
+                if (available)
+                    view.address = this.gateway?.address?.(view.id);
+                const notes = this.registry.getView(view.id)?.notes;
+                if (notes?.length)
+                    view.notes = structuredClone(notes);
+            }
+        return { apps, previewAvailable: available };
     }
-    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); }
-    async open(sessionId, appId, viewId, returnTo) {
+    /** An agent turn changed files in this session's workspace. With agent
+     * screenshots on, Compare gets an "after" shot once servers have rebuilt. */
+    turnChanged(sessionId) {
+        const bumped = this.registry.touch(sessionId);
+        if (bumped.length && this.screenshots.enabled())
+            setTimeout(() => void this.capture(bumped), COMPARE_SETTLE_MS).unref?.();
+        return bumped;
+    }
+    /** One phone-width shot per view of the page last viewed, kept for Compare. */
+    async capture(viewIds) {
+        for (const id of viewIds) {
+            const entry = this.registry.getView(id);
+            if (!entry || entry.view.kind !== "web")
+                continue;
+            const outDir = path.join(os.tmpdir(), "bivy-shots", "compare", id);
+            const run = this.shooting.catch(() => { }).then(() => this.screenshots.take([entry], { widths: [390], themes: ["light"], path: entry.lastPath ?? "/" }, outDir));
+            this.shooting = run;
+            try {
+                const [shot] = await run;
+                if (!shot)
+                    continue;
+                const png = fs.readFileSync(shot.file);
+                fs.rmSync(outDir, { recursive: true, force: true });
+                entry.shots = [...(entry.shots ?? []), { revision: entry.revision, at: Date.now(), png }].slice(-COMPARE_KEEP);
+            }
+            catch { /* a failed shot just leaves Compare without this turn */ }
+        }
+    }
+    /** 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 } }] });
+    }
+    /** `direct` opens the app origin itself (no shell): a signed-in device
+     * returning to a view's stable address. */
+    async open(sessionId, appId, viewId, returnTo, direct = false) {
         const entry = this.registry.requireView(sessionId, appId, viewId);
         if (entry.view.kind === "web") {
             if (!this.gateway)
                 throw new Error("Bivy's preview service is unavailable on this connection.");
-            return { kind: "web", url: this.gateway.open(viewId, returnTo) };
+            if (direct && !this.gateway.openDirect)
+                throw new Error("This machine can't open previews directly.");
+            const url = direct ? this.gateway.openDirect(viewId) : this.gateway.open(viewId, returnTo);
+            // Don't wait for a managed server to boot: the preview shows it starting
+            // and reloads itself once it answers.
+            if (this.servers.get(viewId))
+                this.servers.get(viewId).restarts = [];
+            void this.ensureServer(entry).catch(() => { });
+            // Compare needs a "before": take a baseline the first time it's opened.
+            if (!entry.shots?.length && this.screenshots.enabled())
+                setTimeout(() => void this.capture([viewId]), COMPARE_SETTLE_MS).unref?.();
+            return { kind: "web", url };
         }
         if (entry.target.kind !== "terminal")
             throw new Error("Unsupported app view provider.");
@@ -48,6 +135,89 @@ export class AppService {
             throw error;
         }
     }
+    /** Screenshots of a session's web views (one app, or all), for agents to
+     * check their own UI. One browser at a time node-wide; PNGs in a temp dir. */
+    async shot(sessionId, appId, input) {
+        if (!this.screenshots.enabled())
+            throw new Error("Agent screenshots are off on this machine. Turn on “Let agents screenshot their app previews” in Bivy → Settings → this machine, or run: bivy config set sessions.appScreenshots true");
+        const widths = input.widths ?? [390, 1280];
+        const themes = input.themes ?? ["light"];
+        const page = input.path ?? "/";
+        if (!Array.isArray(widths) || !widths.length || widths.length > 4 || widths.some((w) => !Number.isInteger(w) || w < 240 || w > 2560))
+            throw new Error("Widths must be 1–4 whole numbers between 240 and 2560.");
+        if (!Array.isArray(themes) || !themes.length || themes.some((t) => t !== "light" && t !== "dark"))
+            throw new Error("Themes must be light and/or dark.");
+        if (typeof page !== "string" || !page.startsWith("/") || page.startsWith("//") || page.length > 2048)
+            throw new Error("Path must start with /.");
+        const apps = appId ? [this.registry.require(sessionId, appId)] : this.registry.list(sessionId);
+        const views = apps.flatMap((app) => app.views).filter((view) => view.kind === "web").map((view) => this.registry.getView(view.id)).filter(Boolean);
+        if (!views.length)
+            throw new Error("This session has no web views to screenshot. Publish one with bivy app publish, or preview a detected server.");
+        const outDir = path.join(os.tmpdir(), "bivy-shots", sessionId.replace(/[^A-Za-z0-9_-]/g, "_"), String(Date.now()));
+        const run = this.shooting.catch(() => { }).then(() => this.screenshots.take(views, { widths, themes: [...new Set(themes)], path: page }, outDir));
+        this.shooting = run;
+        return { shots: await run };
+    }
+    /** The managed server's output, as an attachable terminal (starts it if needed). */
+    async logs(sessionId, appId, viewId) {
+        const entry = this.registry.requireView(sessionId, appId, viewId);
+        const termId = await this.ensureServer(entry);
+        if (!termId)
+            throw new Error("Only views with a start command have server logs.");
+        return { kind: "terminal", termId };
+    }
+    ensureServer(entry) {
+        if (entry.target.kind !== "service" || !entry.target.start)
+            return Promise.resolve(undefined);
+        const id = entry.view.id, start = entry.target.start;
+        let state = this.servers.get(id);
+        if (!state) {
+            state = { restarts: [] };
+            this.servers.set(id, state);
+        }
+        const server = state;
+        if (server.termId && this.terminals.has(server.termId))
+            return Promise.resolve(server.termId);
+        server.pending ??= this.terminals.start({ ...start, name: `${entry.app.name} · ${entry.view.name} server` })
+            .then((termId) => {
+            if (!this.registry.getView(id)) {
+                this.terminals.close(termId);
+                throw new Error("App was removed while starting.");
+            }
+            server.termId = termId;
+            return termId;
+        })
+            .finally(() => { server.pending = undefined; });
+        // Watch for exits and restart, backing off a crash loop.
+        server.timer ??= setInterval(() => {
+            const current = this.registry.getView(id);
+            if (!current) {
+                this.stopServer(id);
+                return;
+            }
+            if (server.pending || !server.termId || this.terminals.has(server.termId))
+                return;
+            const now = Date.now();
+            server.restarts = server.restarts.filter((at) => now - at < RESTART_WINDOW);
+            if (server.restarts.length >= MAX_RESTARTS)
+                return;
+            server.restarts.push(now);
+            server.termId = undefined;
+            void this.ensureServer(current).catch(() => { });
+        }, this.serverWatchMs);
+        server.timer.unref?.();
+        return server.pending;
+    }
+    stopServer(id) {
+        const server = this.servers.get(id);
+        if (!server)
+            return;
+        clearInterval(server.timer);
+        if (server.termId)
+            this.terminals.close(server.termId);
+        void server.pending?.then((termId) => this.terminals.close(termId)).catch(() => { });
+        this.servers.delete(id);
+    }
     share(sessionId, appId, viewId) {
         if (this.registry.requireView(sessionId, appId, viewId).view.kind !== "web")
             throw new Error("Only web views have preview links.");
@@ -55,6 +225,10 @@ export class AppService {
             throw new Error("Bivy's preview service is unavailable on this connection.");
         return this.gateway.share(viewId);
     }
+    clearNotes(sessionId, appId, viewId) {
+        delete this.registry.requireView(sessionId, appId, viewId).notes;
+        return { ok: true };
+    }
     /** Ends every link, browser session and open connection for one view; the app stays. */
     revoke(sessionId, appId, viewId) {
         this.registry.requireView(sessionId, appId, viewId);
@@ -66,6 +240,7 @@ export class AppService {
         this.registry.remove(sessionId, appId);
         for (const view of app.views) {
             this.gateway?.revoke(view.id);
+            this.stopServer(view.id);
             const pending = this.terminalStarts.get(view.id);
             this.terminalStarts.delete(view.id);
             if (pending)

package/dist/apps/styles.css

@@ -2957,6 +2957,9 @@ select.picker-search { appearance: auto; }
 .app-views-heading > .btn, .app-view-actions .btn { min-block-size: var(--space-7); flex-shrink: 0; }
 .app-view-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: var(--space-2); margin-inline-start: auto; }
 .app-view-notice { display: flex; flex-direction: column; gap: var(--space-2); flex-basis: 100%; min-width: 0; }
+.app-view-notes { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: var(--space-1); font-size: var(--text-sm); overflow-wrap: anywhere; }
+/* Peek: an app preview framed in a drawer over the chat (PreviewPeek.tsx). */
+.preview-peek { display: block; inline-size: 100%; block-size: 100%; border: 0; border-radius: var(--radius-md); background: var(--bg); }
 .app-terminal-status { padding: var(--space-2) var(--space-4); margin: 0; color: var(--muted); font-size: var(--text-sm); }
 .app-view-command { overflow-wrap: anywhere; white-space: pre-wrap; font-size: var(--text-xs); color: var(--muted); }
 .app-view-row .artifact-main { flex-basis: 60%; }

package/dist/config-cli.js

@@ -108,6 +108,7 @@ const ENV_FOR_KEY = {
     "defaults.sandbox": "BIVY_SANDBOX",
     "defaults.approval": "BIVY_APPROVAL_MODE",
     "sessions.autoAttachToolImages": "BIVY_AUTO_ATTACH_TOOL_IMAGES",
+    "sessions.appScreenshots": "BIVY_APP_SCREENSHOTS",
     "automation.checks": "BIVY_AUTOMATION_CHECKS",
     "automation.checkTimeoutMinutes": "BIVY_AUTOMATION_CHECK_TIMEOUT_MS",
 };
@@ -122,6 +123,7 @@ const BUILTIN_VALUES = {
     "sessions.worktreeSync": false,
     "sessions.resume": "auto",
     "sessions.autoAttachToolImages": false,
+    "sessions.appScreenshots": false,
     "automation.checks": ["test", "lint", "typecheck"],
     "automation.checkTimeoutMinutes": 10,
 };

package/dist/controllers/app-commands.js

@@ -1,16 +1,29 @@
 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 };
         },
-        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined),
+        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined, msg.direct === true),
+        "apps.shot": (msg) => service.shot(String(msg.sessionId), typeof msg.appId === "string" ? msg.appId : undefined, { widths: msg.widths, themes: msg.themes, path: typeof msg.path === "string" ? msg.path : undefined }),
+        "apps.clearNotes": (msg) => service.clearNotes(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
+        "apps.logs": (msg) => service.logs(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.share": (msg) => service.share(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.revoke": (msg) => service.revoke(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.remove": (msg) => { service.remove(String(msg.sessionId), String(msg.appId)); return { ok: true }; },
@@ -18,7 +31,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/node-config.js

@@ -74,7 +74,7 @@ export function validateNodeConfig(value) {
     const node = section(root, "node", ["workspace", "port", "maxConcurrentAutomations", "capabilities"], errors);
     const defaults = section(root, "defaults", ["agent", "model", "sandbox", "approval"], errors);
     const safety = section(root, "safety", ["maxSandbox", "approvalFloor"], errors);
-    const sessions = section(root, "sessions", ["sync", "worktreeSync", "standbyNodeId", "resume", "autoAttachToolImages", "forkWorkspaceMaxBytes", "wedgedTurnMinutes"], errors);
+    const sessions = section(root, "sessions", ["sync", "worktreeSync", "standbyNodeId", "resume", "autoAttachToolImages", "appScreenshots", "forkWorkspaceMaxBytes", "wedgedTurnMinutes"], errors);
     const github = section(root, "github", ["issuePrompt"], errors);
     const automation = section(root, "automation", ["checks", "checkTimeoutMinutes"], errors);
     const agentsRaw = section(root, "agents", Object.keys(record(root.agents) ?? {}), errors);
@@ -133,6 +133,7 @@ export function validateNodeConfig(value) {
     if (resume !== undefined && resume !== "auto" && resume !== "manual")
         errors.push("sessions.resume must be auto or manual");
     const autoAttachToolImages = optionalBoolean(sessions.autoAttachToolImages, "sessions.autoAttachToolImages", errors);
+    const appScreenshots = optionalBoolean(sessions.appScreenshots, "sessions.appScreenshots", errors);
     const forkWorkspaceMaxBytes = optionalInteger(sessions.forkWorkspaceMaxBytes, "sessions.forkWorkspaceMaxBytes", errors, 1_048_576, 1_073_741_824);
     // Upper bound is the wall-clock turn cap (60 min): a wedged window at/above it
     // would never fire before the cap. 0 disables the band.
@@ -216,7 +217,7 @@ export function validateNodeConfig(value) {
         ...(Object.keys(node).length ? { node: { workspace, port, maxConcurrentAutomations, capabilities } } : {}),
         ...(Object.keys(defaults).length ? { defaults: { agent, model, sandbox, approval } } : {}),
         ...(Object.keys(safety).length ? { safety: { maxSandbox, approvalFloor } } : {}),
-        ...(Object.keys(sessions).length ? { sessions: { sync, worktreeSync, standbyNodeId, resume, autoAttachToolImages, forkWorkspaceMaxBytes, wedgedTurnMinutes } } : {}),
+        ...(Object.keys(sessions).length ? { sessions: { sync, worktreeSync, standbyNodeId, resume, autoAttachToolImages, appScreenshots, forkWorkspaceMaxBytes, wedgedTurnMinutes } } : {}),
         ...(Object.keys(github).length ? { github: { issuePrompt } } : {}),
         ...(Object.keys(automation).length ? { automation: { checks, checkTimeoutMinutes } } : {}),
         ...(Object.keys(agents).length ? { agents } : {}),
@@ -272,6 +273,7 @@ export function configToLegacySettings(config) {
         ...(config.sessions?.standbyNodeId ? { syncStandbyNodeId: config.sessions.standbyNodeId } : {}),
         ...(config.sessions?.resume ? { sessionResumeMode: config.sessions.resume } : {}),
         ...(config.sessions?.autoAttachToolImages !== undefined ? { autoAttachToolImages: config.sessions.autoAttachToolImages } : {}),
+        ...(config.sessions?.appScreenshots !== undefined ? { appScreenshots: config.sessions.appScreenshots } : {}),
         ...(config.sessions?.forkWorkspaceMaxBytes !== undefined ? { forkWorkspaceMaxBytes: config.sessions.forkWorkspaceMaxBytes } : {}),
     };
 }
@@ -335,6 +337,7 @@ export function mergeLegacyIntoNodeConfig(cli, settings) {
             standbyNodeId: typeof settings.syncStandbyNodeId === "string" ? settings.syncStandbyNodeId : undefined,
             resume: settings.sessionResumeMode === "manual" ? "manual" : "auto",
             autoAttachToolImages: settings.autoAttachToolImages === true,
+            appScreenshots: settings.appScreenshots === true,
             forkWorkspaceMaxBytes: Number.isInteger(settings.forkWorkspaceMaxBytes) ? Number(settings.forkWorkspaceMaxBytes) : undefined,
         },
         github: { issuePrompt: typeof settings.githubIssuePrompt === "string" ? settings.githubIssuePrompt : undefined },
@@ -361,7 +364,7 @@ export function setConfigValue(config, dotted, value) {
         "node.workspace", "node.port", "node.maxConcurrentAutomations", "node.capabilities",
         "defaults.agent", "defaults.model", "defaults.sandbox", "defaults.approval",
         "safety.maxSandbox", "safety.approvalFloor",
-        "sessions.sync", "sessions.worktreeSync", "sessions.standbyNodeId", "sessions.resume", "sessions.autoAttachToolImages", "sessions.forkWorkspaceMaxBytes", "sessions.wedgedTurnMinutes",
+        "sessions.sync", "sessions.worktreeSync", "sessions.standbyNodeId", "sessions.resume", "sessions.autoAttachToolImages", "sessions.appScreenshots", "sessions.forkWorkspaceMaxBytes", "sessions.wedgedTurnMinutes",
         "github.issuePrompt", "automation.checks", "automation.checkTimeoutMinutes",
     ]);
     if (!allowed.has(dotted) && !/^agents\.[a-z][a-z0-9-]{1,47}$/.test(dotted) && !/^environment\.[A-Z][A-Z0-9_]+$/.test(dotted))

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", "logs", "shot", "clearNotes", "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,7 +10,12 @@ 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.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })) }),
+    "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 })), direct: Type.Optional(Type.Boolean()) }),
+    "apps.shot": Type.Object({ ...request, ...session, appId: Type.Optional(Type.String()), widths: Type.Optional(Type.Array(Type.Integer(), { maxItems: 4 })), themes: Type.Optional(Type.Array(Type.Union([Type.Literal("light"), Type.Literal("dark")]), { maxItems: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })) }),
+    "apps.clearNotes": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
+    "apps.logs": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.share": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.revoke": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.remove": Type.Object({ ...request, ...session, appId: 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,
@@ -1332,6 +1334,7 @@ function writeSettings(settings) {
         ...("syncStandbyNodeId" in settings ? { standbyNodeId: typeof settings.syncStandbyNodeId === "string" ? settings.syncStandbyNodeId || undefined : undefined } : {}),
         ...(settings.sessionResumeMode === "auto" || settings.sessionResumeMode === "manual" ? { resume: settings.sessionResumeMode } : {}),
         ...(typeof settings.autoAttachToolImages === "boolean" ? { autoAttachToolImages: settings.autoAttachToolImages } : {}),
+        ...(typeof settings.appScreenshots === "boolean" ? { appScreenshots: settings.appScreenshots } : {}),
         ...(Number.isInteger(settings.forkWorkspaceMaxBytes) ? { forkWorkspaceMaxBytes: Number(settings.forkWorkspaceMaxBytes) } : {}),
     };
     next.github = {
@@ -1418,6 +1421,15 @@ function nodeConfiguredDefaultAgent() {
 }
 /** How interactive sessions recover after a restart interrupted them mid-turn.
  *  Defaults to "auto" (re-drive the turn); "manual" waits for a user tap. */
+/** Agents may screenshot app previews: the node setting, or BIVY_APP_SCREENSHOTS. */
+function appScreenshotsEnabled() {
+    const env = process.env.BIVY_APP_SCREENSHOTS;
+    if (env === "1" || env === "true")
+        return true;
+    if (env === "0" || env === "false")
+        return false;
+    return readSettings().appScreenshots === true;
+}
 function nodeSessionResumeMode() {
     return readSettings().sessionResumeMode === "manual" ? "manual" : "auto";
 }
@@ -1451,6 +1463,7 @@ function nodeSettingsSnapshot() {
         })(),
         sessionResumeMode: nodeSessionResumeMode(),
         autoAttachToolImages: readSettings().autoAttachToolImages === true,
+        appScreenshots: appScreenshotsEnabled(),
         forkWorkspaceMaxBytes: Number.isInteger(readSettings().forkWorkspaceMaxBytes) ? Number(readSettings().forkWorkspaceMaxBytes) : 50 * 1024 * 1024,
     };
 }
@@ -1508,6 +1521,8 @@ async function applyNodeSettings(patch) {
     if ("sessionResumeMode" in patch) {
         settings.sessionResumeMode = patch.sessionResumeMode === "manual" ? "manual" : "auto";
     }
+    if ("appScreenshots" in patch)
+        settings.appScreenshots = patch.appScreenshots === true;
     if ("autoAttachToolImages" in patch) {
         settings.autoAttachToolImages = patch.autoAttachToolImages === true;
         setConfiguredAutoAttachToolImages(settings.autoAttachToolImages);
@@ -1906,14 +1921,24 @@ const appPreviewPort = Number(process.env.BIVY_APPS_PORT || 4318);
 if (process.env.BIVY_APPS_ORIGIN && (!Number.isInteger(appPreviewPort) || appPreviewPort < 1024 || appPreviewPort > 65535 || appPreviewPort === port)) {
     throw new Error("BIVY_APPS_PORT must be between 1024 and 65535 and different from the node API port.");
 }
-const appRegistry = new AppRegistry([port, ...(process.env.BIVY_APPS_ORIGIN ? [appPreviewPort] : [])]);
+// Apps persist with their IDs, so chat launchers and preview addresses survive
+// restarts; see AppRegistry for which views are restored.
+const appRegistry = new AppRegistry([port, ...(process.env.BIVY_APPS_ORIGIN ? [appPreviewPort] : [])], path.join(appDir, "apps.json"));
 const appReturnOrigins = () => {
     const config = loadRelayConfig(appDir);
     return [config?.clientBaseUrl, config?.controlPlaneUrl, ...(process.env.BIVY_APPS_RETURN_ORIGINS ?? "").split(",")]
         .filter((value) => Boolean(value?.trim())).map((value) => new URL(value.trim()).origin);
 };
-const appGateway = process.env.BIVY_APPS_ORIGIN ? new AppGateway(appRegistry, process.env.BIVY_APPS_ORIGIN, appReturnOrigins) : undefined;
-const remotePreview = new RemotePreview(appRegistry, appReturnOrigins);
+// A signed-out visit to a preview's stable address goes through the Bivy
+// client: open the session on this node, then the client re-opens the view.
+const appSignIn = (view, pagePath) => {
+    const client = loadRelayConfig(appDir)?.clientBaseUrl;
+    if (!client)
+        return undefined;
+    return `${new URL(client).origin}/sessions/${encodeURIComponent(view.app.sessionId)}?node=${encodeURIComponent(identity.nodeId)}#preview=${view.app.id}.${view.view.id}.${encodeURIComponent(pagePath)}`;
+};
+const appGateway = process.env.BIVY_APPS_ORIGIN ? new AppGateway(appRegistry, process.env.BIVY_APPS_ORIGIN, appReturnOrigins, appSignIn) : undefined;
+const remotePreview = new RemotePreview(appRegistry, appReturnOrigins, appSignIn);
 const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     start: async (spec) => {
         let failure = "Could not start the app terminal.";
@@ -1928,7 +1953,7 @@ const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     },
     has: (id) => terminals.has(id),
     close: (id) => { terminals.close(id); },
-});
+}, { screenshots: { enabled: appScreenshotsEnabled } });
 const RELAY_COMMANDS = {
     ...createAppCommands(appService, (id) => { const record = resolveSession(id); return record ? harnessDirFor(record) : undefined; }, (app) => {
         const record = resolveSession(app.sessionId);