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

package/dist/apps/x11.js

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import net from "node:net";
+import fs from "node:fs";
+import { randomBytes } from "node:crypto";
+/** An X authority file with one MIT-MAGIC-COOKIE-1 for any display number, so
+ * only processes Bivy hands the file to can connect. */
+export function writeXauthority(file, cookie = randomBytes(16)) {
+    const field = (data) => { const len = Buffer.alloc(2); len.writeUInt16BE(data.length); return Buffer.concat([len, data]); };
+    const family = Buffer.from([0xff, 0xff]); // FamilyWild
+    fs.writeFileSync(file, Buffer.concat([family, field(Buffer.alloc(0)), field(Buffer.alloc(0)), field(Buffer.from("MIT-MAGIC-COOKIE-1")), field(cookie)]), { mode: 0o600 });
+    return cookie;
+}
+const pad = (n) => (4 - (n % 4)) % 4;
+// Core protocol numbers used below (X11 protocol, little-endian client).
+const OP = { ChangeWindowAttributes: 2, MapWindow: 8, ConfigureWindow: 12, GetGeometry: 14, ChangeProperty: 18, GetProperty: 20, SendEvent: 25, SetInputFocus: 42, QueryExtension: 98 };
+/** RandR minor opcodes. */
+const RR = { QueryVersion: 0, SetScreenSize: 7 };
+const EV = { DestroyNotify: 17, UnmapNotify: 18, MapRequest: 20, ConfigureNotify: 22, ConfigureRequest: 23 };
+const MASK = { StructureNotify: 1 << 17, SubstructureNotify: 1 << 19, SubstructureRedirect: 1 << 20 };
+const CFG = { x: 1, y: 2, width: 4, height: 8, border: 16 };
+const ATOM = { STRING: 31, RESOURCE_MANAGER: 23, WM_NORMAL_HINTS: 40, WM_SIZE_HINTS: 41, WINDOW: 33, WM_TRANSIENT_FOR: 68 };
+/** WM_SIZE_HINTS flag: the program set a minimum size. */
+const P_MIN_SIZE = 1 << 4;
+/** A window manager with one rule, sized for previews: every top-level window
+ * fills the screen, dialogs are centered at their own size, and everything is
+ * refit when the viewer resizes the display. A window that can't shrink to the
+ * viewer's size grows the screen instead, and the viewer scales it down, so
+ * nothing is cut off. Pure protocol, no dependencies. */
+export class FitWindowManager {
+    socket;
+    buffer = Buffer.alloc(0);
+    seq = 0;
+    root = 0;
+    width = 0;
+    height = 0;
+    ready = false;
+    /** Pending replies by sequence number: the raw reply, or undefined on error. */
+    replies = new Map();
+    /** Mapped windows we manage; `size` is what the app asked for (dialogs keep
+     * it), `min` the smallest it can draw. */
+    windows = new Map();
+    /** The size the viewer asked for, and the size we last set ourselves. */
+    viewer = [0, 0];
+    own;
+    randr = 0;
+    /** Resolves once the WM owns the root window; rejects if another WM does. */
+    /** `dpi` is published as Xft.dpi, which Chromium/Electron and others scale by. */
+    start(socketPath, cookie, dpi = 96) {
+        return new Promise((resolve, reject) => {
+            const socket = net.connect(socketPath);
+            this.socket = socket;
+            socket.on("error", (error) => { if (!this.ready)
+                reject(error); });
+            socket.on("close", () => { if (!this.ready)
+                reject(new Error("The display closed the window manager's connection.")); });
+            const name = Buffer.from("MIT-MAGIC-COOKIE-1");
+            const setup = Buffer.alloc(12);
+            setup.write("l", 0);
+            setup.writeUInt16LE(11, 2);
+            setup.writeUInt16LE(0, 4);
+            setup.writeUInt16LE(name.length, 6);
+            setup.writeUInt16LE(cookie.length, 8);
+            socket.write(Buffer.concat([setup, name, Buffer.alloc(pad(name.length)), cookie, Buffer.alloc(pad(cookie.length))]));
+            socket.on("data", (chunk) => {
+                this.buffer = Buffer.concat([this.buffer, chunk]);
+                try {
+                    if (!this.ready) {
+                        if (this.buffer.length < 8)
+                            return;
+                        const total = 8 + this.buffer.readUInt16LE(6) * 4;
+                        if (this.buffer.length < total)
+                            return;
+                        const reply = this.buffer.subarray(0, total);
+                        this.buffer = this.buffer.subarray(total);
+                        if (reply[0] !== 1) {
+                            reject(new Error(`The display refused the window manager: ${reply.subarray(8, 8 + reply[1]).toString()}`));
+                            socket.destroy();
+                            return;
+                        }
+                        this.parseSetup(reply);
+                        this.ready = true;
+                        this.viewer = [this.width, this.height];
+                        const resources = Buffer.from(`Xft.dpi:\t${dpi}\n`);
+                        this.request(OP.ChangeProperty, 0, Buffer.concat([u32(this.root, ATOM.RESOURCE_MANAGER, ATOM.STRING, 8, resources.length), resources, Buffer.alloc(pad(resources.length))]));
+                        const name = Buffer.from("RANDR");
+                        this.query(OP.QueryExtension, Buffer.concat([u16pair(name.length, 0), name, Buffer.alloc(pad(name.length))]), (reply) => {
+                            if (!reply?.[8])
+                                return;
+                            this.randr = reply[9];
+                            this.request(this.randr, RR.QueryVersion, u32(1, 5));
+                        });
+                        // Redirecting the root's substructure is what makes us the WM.
+                        const seq = this.request(OP.ChangeWindowAttributes, 0, u32(this.root, 0x800, MASK.SubstructureRedirect | MASK.SubstructureNotify | MASK.StructureNotify));
+                        this.replies.set(seq, () => reject(new Error("Another window manager already runs on this display.")));
+                        // A no-reply request can't be confirmed directly; a reply to the next
+                        // request arrives in order, so it means the first one passed.
+                        this.query(OP.GetGeometry, u32(this.root), () => { this.replies.delete(seq); resolve(); });
+                    }
+                    this.drain();
+                }
+                catch {
+                    socket.destroy();
+                }
+            });
+        });
+    }
+    stop() { this.socket?.destroy(); this.socket = undefined; }
+    get size() { return [this.width, this.height]; }
+    /** Top-level windows currently shown. */
+    get count() { return this.windows.size; }
+    parseSetup(reply) {
+        const vendorLength = reply.readUInt16LE(24);
+        const formats = reply[29];
+        const screen = 40 + vendorLength + pad(vendorLength) + formats * 8;
+        this.root = reply.readUInt32LE(screen);
+        this.width = reply.readUInt16LE(screen + 20);
+        this.height = reply.readUInt16LE(screen + 22);
+    }
+    request(opcode, data, body) {
+        const header = Buffer.alloc(4);
+        header[0] = opcode;
+        header[1] = data;
+        header.writeUInt16LE(1 + body.length / 4, 2);
+        this.socket?.write(Buffer.concat([header, body]));
+        this.seq = (this.seq + 1) & 0xffff;
+        return this.seq;
+    }
+    query(opcode, body, done) {
+        this.replies.set(this.request(opcode, 0, body), done);
+    }
+    drain() {
+        while (this.buffer.length >= 32) {
+            const kind = this.buffer[0];
+            const length = kind === 1 ? 32 + this.buffer.readUInt32LE(4) * 4 : 32;
+            if (this.buffer.length < length)
+                return;
+            const packet = this.buffer.subarray(0, length);
+            this.buffer = this.buffer.subarray(length);
+            const seq = packet.readUInt16LE(2);
+            if (kind === 0 || kind === 1) {
+                const done = this.replies.get(seq);
+                this.replies.delete(seq);
+                done?.(kind === 1 ? packet : undefined);
+                continue;
+            }
+            this.event(kind & 0x7f, packet);
+        }
+    }
+    event(code, e) {
+        if (code === EV.MapRequest) {
+            const window = e.readUInt32LE(8);
+            // The size it was created (or last configured) with, and whether it's a
+            // dialog: dialogs name their parent and keep their size, centered.
+            let size = [0, 0], min = [0, 0];
+            this.query(OP.GetGeometry, u32(window), (reply) => { if (reply)
+                size = [reply.readUInt16LE(16), reply.readUInt16LE(18)]; });
+            this.query(OP.GetProperty, u32(window, ATOM.WM_NORMAL_HINTS, ATOM.WM_SIZE_HINTS, 0, 18), (reply) => {
+                if (reply && reply.readUInt32LE(16) >= 7 && reply.readUInt32LE(32) & P_MIN_SIZE)
+                    min = [reply.readInt32LE(32 + 20), reply.readInt32LE(32 + 24)];
+            });
+            this.query(OP.GetProperty, u32(window, ATOM.WM_TRANSIENT_FOR, ATOM.WINDOW, 0, 1), (reply) => {
+                if (!reply)
+                    return; // gone already
+                const dialog = reply.readUInt32LE(16) > 0 && reply.readUInt32LE(32) > 0;
+                this.windows.set(window, { dialog, size, min: min.map((v) => Math.max(0, Math.min(v, 8192))) });
+                if (!this.resize())
+                    this.fit(window);
+                this.request(OP.MapWindow, 0, u32(window));
+                this.request(OP.SetInputFocus, 2, u32(window, 0));
+            });
+        }
+        else if (code === EV.ConfigureRequest) {
+            const window = e.readUInt32LE(8);
+            const size = [e.readUInt16LE(20), e.readUInt16LE(22)];
+            const managed = this.windows.get(window);
+            if (managed) {
+                managed.size = size;
+                this.fit(window);
+                return;
+            }
+            // Not shown yet: honour it; the map request decides the final geometry.
+            this.configure(window, e.readInt16LE(16), e.readInt16LE(18), size[0], size[1]);
+        }
+        else if (code === EV.DestroyNotify || code === EV.UnmapNotify) {
+            const window = e.readUInt32LE(8);
+            if (e.readUInt32LE(4) === this.root && this.windows.delete(window))
+                this.resize();
+        }
+        else if (code === EV.ConfigureNotify && e.readUInt32LE(8) === this.root) {
+            // The display changed size: refit everything to the new screen. If the
+            // viewer did it (not us), remember what it asked for.
+            this.width = e.readUInt16LE(20);
+            this.height = e.readUInt16LE(22);
+            if (!this.own || this.own[0] !== this.width || this.own[1] !== this.height) {
+                this.viewer = [this.width, this.height];
+                this.own = undefined;
+            }
+            if (this.resize())
+                return;
+            for (const window of this.windows.keys())
+                this.fit(window);
+        }
+    }
+    /** Grow the screen past the viewer's size when a window can't shrink that
+     * far; back to the viewer's size when it can. True if a resize was sent (the
+     * refit follows when the display reports its new size). */
+    resize() {
+        if (!this.randr)
+            return false;
+        let [w, h] = this.viewer;
+        for (const { dialog, min } of this.windows.values())
+            if (!dialog) {
+                w = Math.max(w, min[0]);
+                h = Math.max(h, min[1]);
+            }
+        if (w === this.width && h === this.height)
+            return false;
+        this.own = [w, h];
+        const body = Buffer.alloc(16);
+        body.writeUInt32LE(this.root, 0);
+        body.writeUInt16LE(w, 4);
+        body.writeUInt16LE(h, 6);
+        body.writeUInt32LE(Math.round(w * 25.4 / 96), 8);
+        body.writeUInt32LE(Math.round(h * 25.4 / 96), 12);
+        const seq = this.request(this.randr, RR.SetScreenSize, body);
+        // Refused (e.g. too large): stop resizing and fit to the screen we have.
+        // A later reply means it was accepted, so drop the error handler.
+        this.replies.set(seq, () => { this.randr = 0; this.own = undefined; for (const window of this.windows.keys())
+            this.fit(window); });
+        this.query(OP.GetGeometry, u32(this.root), () => this.replies.delete(seq));
+        return true;
+    }
+    fit(window) {
+        const managed = this.windows.get(window);
+        if (!managed)
+            return;
+        if (!managed.dialog) {
+            this.configure(window, 0, 0, this.width, this.height);
+            return;
+        }
+        const w = Math.min(Math.max(managed.size[0], 1), this.width), h = Math.min(Math.max(managed.size[1], 1), this.height);
+        this.configure(window, Math.floor((this.width - w) / 2), Math.floor((this.height - h) / 2), w, h);
+    }
+    configure(window, x, y, width, height) {
+        const body = Buffer.alloc(28);
+        body.writeUInt32LE(window, 0);
+        body.writeUInt16LE(CFG.x | CFG.y | CFG.width | CFG.height | CFG.border, 4);
+        body.writeInt32LE(x, 8);
+        body.writeInt32LE(y, 12);
+        body.writeUInt32LE(Math.max(1, width), 16);
+        body.writeUInt32LE(Math.max(1, height), 20);
+        body.writeUInt32LE(0, 24);
+        this.request(OP.ConfigureWindow, 0, body);
+        // ICCCM: tell the client its geometry even when nothing changed, or
+        // toolkits that asked for another size wait for an answer and never paint.
+        const event = Buffer.alloc(32);
+        event[0] = EV.ConfigureNotify;
+        event.writeUInt32LE(window, 4);
+        event.writeUInt32LE(window, 8);
+        event.writeInt16LE(x, 16);
+        event.writeInt16LE(y, 18);
+        event.writeUInt16LE(Math.max(1, width), 20);
+        event.writeUInt16LE(Math.max(1, height), 22);
+        this.request(OP.SendEvent, 0, Buffer.concat([u32(window, MASK.StructureNotify), event]));
+    }
+}
+function u16pair(a, b) { const out = Buffer.alloc(4); out.writeUInt16LE(a, 0); out.writeUInt16LE(b, 2); return out; }
+function u32(...values) {
+    const out = Buffer.alloc(values.length * 4);
+    values.forEach((value, i) => out.writeUInt32LE(value >>> 0, i * 4));
+    return out;
+}

package/dist/attach.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright (c) 2026 Petter André Sjulstad
+import { hostname } from "node:os";
 import { StringDecoder } from "node:string_decoder";
 import { WebSocket } from "ws";
 /**
@@ -50,6 +51,9 @@ const TTY_MODE_RESET = "\x1b[?1049l" + // leave the alternate screen
     "\x1b[?1l\x1b>" + // cursor keys + keypad back to normal mode
     "\x1b[?25h" + // cursor visible
     "\x1b[0m"; // reset colors/attributes
+/** How this terminal names itself to the node, so other devices can say where a
+ *  session was last driven ("Terminal on my-laptop"). */
+const DEVICE = { id: `terminal:${hostname()}`, label: `Terminal on ${hostname()}` };
 function parseArgs(argv) {
     let url = process.env.BIVY_URL || `http://localhost:${process.env.PORT || "4317"}`;
     let token = process.env.BIVY_DEVICE_TOKEN || undefined;
@@ -102,6 +106,9 @@ function bridge(args, open) {
         let bound = false;
         let detachArmed = 0;
         let settled = false;
+        // Set while the session this terminal showed is continuing as a chat in the
+        // app: the next key decides whether to take it back here or leave.
+        let handedToChat;
         const inputDecoder = new StringDecoder("utf8");
         const stdin = process.stdin;
         const wasRaw = stdin.isTTY ? stdin.isRaw : false;
@@ -144,6 +151,21 @@ function bridge(args, open) {
                 socket.send(JSON.stringify(payload));
         };
         const onInput = (data) => {
+            if (handedToChat) {
+                const sessionId = handedToChat;
+                handedToChat = undefined;
+                if (data[0] !== 0x0d && data[0] !== 0x0a) {
+                    finish(0);
+                    return;
+                }
+                // Reopen the chat's own TUI, resuming the same conversation; the node
+                // locks the chat again and every device sees the handoff.
+                process.stdout.write(c.dim("Taking it back…\r\n"));
+                modesReset = false;
+                const { cols, rows } = termSize();
+                send({ kind: "terminal.open.tui", sessionId, cols, rows });
+                return;
+            }
             // Ctrl-\ (0x1c) twice in a row detaches, leaving the daemon session alive.
             if (data.length === 1 && data[0] === 0x1c) {
                 const now = Date.now();
@@ -212,6 +234,17 @@ function bridge(args, open) {
                 if (typeof msg.data === "string")
                     process.stdout.write(msg.data);
             }
+            else if (type === "terminal.closed" && msg.reason === "chat" && msg.termId === termId) {
+                resetModes();
+                termId = undefined;
+                process.stdout.write(c.dim("\r\n[continued as chat in the Bivy app]\r\n"));
+                if (typeof msg.sessionId !== "string" || !msg.sessionId) {
+                    finish(0);
+                    return;
+                }
+                handedToChat = msg.sessionId;
+                process.stdout.write(`Press ${c.bold("Enter")} to take it back here, or any other key to leave.\r\n`);
+            }
             else if ((type === "terminal.exit" || type === "terminal.closed") && msg.termId === termId) {
                 const code = typeof msg.code === "number" ? msg.code : 0;
                 resetModes();
@@ -220,7 +253,7 @@ function bridge(args, open) {
             }
             else if (type === "terminal.error") {
                 process.stderr.write(c.red(`\r\n${String(msg.error || "Terminal error")}\r\n`));
-                if (!bound)
+                if (!bound || !termId)
                     finish(1);
             }
         });
@@ -247,7 +280,7 @@ function openDetached(args, spec, cols, rows) {
             catch { }
             resolve(code);
         };
-        socket.on("open", () => socket.send(JSON.stringify({ kind: "terminal.open.run", agent: spec.agent, label: spec.label, name: spec.name, model: spec.model, command: spec.command, args: spec.args ?? [], workspace: spec.workspace, sessionId: spec.sessionId, cols, rows })));
+        socket.on("open", () => socket.send(JSON.stringify({ kind: "terminal.open.run", agent: spec.agent, label: spec.label, name: spec.name, model: spec.model, command: spec.command, args: spec.args ?? [], workspace: spec.workspace, sessionId: spec.sessionId, cols, rows, device: DEVICE })));
         socket.on("error", (err) => {
             process.stderr.write(c.red(`Connection error: ${err instanceof Error ? err.message : String(err)}\n`));
             finish(1);
@@ -283,7 +316,7 @@ async function main() {
             process.exit(await openDetached(args, spec, cols, rows));
         }
         process.stdout.write(c.dim(`Starting ${c.cyan(spec.name || spec.label || spec.agent || spec.command)} — Ctrl-\\ Ctrl-\\ to detach\r\n`));
-        const code = await bridge(args, (ws) => ws.send(JSON.stringify({ kind: "terminal.open.run", agent: spec.agent, label: spec.label, name: spec.name, model: spec.model, command: spec.command, args: spec.args ?? [], workspace: spec.workspace, sessionId: spec.sessionId, cols, rows })));
+        const code = await bridge(args, (ws) => ws.send(JSON.stringify({ kind: "terminal.open.run", agent: spec.agent, label: spec.label, name: spec.name, model: spec.model, command: spec.command, args: spec.args ?? [], workspace: spec.workspace, sessionId: spec.sessionId, cols, rows, device: DEVICE })));
         process.exit(code);
     }
     // attach
@@ -297,7 +330,7 @@ async function main() {
 async function attachById(args, termId) {
     const { cols, rows } = termSize();
     process.stdout.write(c.dim(`Attaching to ${c.cyan(termId)} — Ctrl-\\ Ctrl-\\ to detach\r\n`));
-    const code = await bridge({ ...args, termId }, (ws) => ws.send(JSON.stringify({ kind: "terminal.attach", termId, cols, rows })));
+    const code = await bridge({ ...args, termId }, (ws) => ws.send(JSON.stringify({ kind: "terminal.attach", termId, cols, rows, device: DEVICE })));
     process.exit(code);
 }
 main().catch((error) => {

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.list": (msg) => service.list(typeof msg.sessionId === "string" ? msg.sessionId : undefined),
         "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, typeof msg.scale === "number" ? msg.scale : undefined),
+        "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/controllers/artifact-commands.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// The machine-wide Artifacts index behind the sidebar's Artifacts page: every
+// file an agent sent into a chat (`bivy attach` / `attach_to_chat`), across all
+// of this machine's sessions. Built from the same event-log records attachment
+// GC already sweeps, so there is no second index to keep in sync. Only what can
+// still be opened is listed: the session exists and the blob is still stored.
+/** Newest first, bounded like the per-session projection. */
+export const MAX_MACHINE_ARTIFACTS = 500;
+/** One entry per content hash — the newest send wins, so the same report sent
+ * to two sessions links to where it was sent last. */
+export function listMachineArtifacts(deps) {
+    const byHash = new Map();
+    for (const sessionId of deps.sessionIds()) {
+        for (const record of deps.scan(sessionId)) {
+            if (record.bivyKind !== "outbound-attachment")
+                continue;
+            const { ref } = record;
+            const existing = byHash.get(ref.hash);
+            if (existing && existing.createdAt >= record.createdAt)
+                continue;
+            byHash.set(ref.hash, {
+                sessionId, hash: ref.hash, name: ref.name, mimeType: ref.mimeType, kind: ref.kind, size: ref.size,
+                ...(record.caption ? { caption: record.caption } : {}),
+                createdAt: record.createdAt,
+                artifact: Boolean(record.artifact || existing?.artifact),
+            });
+        }
+    }
+    return [...byHash.values()]
+        .filter((item) => deps.stored(item.hash))
+        .sort((a, b) => b.createdAt - a.createdAt)
+        .slice(0, MAX_MACHINE_ARTIFACTS);
+}
+export function createArtifactCommands(deps) {
+    return {
+        "artifacts.list"(msg, ctx) {
+            ctx.reply({ type: "artifacts.list.ok", requestId: msg.requestId, artifacts: listMachineArtifacts(deps) });
+        },
+    };
+}

package/dist/controllers/presence-commands.js

@@ -0,0 +1,19 @@
+import { deviceFrom } from "../session/presence.js";
+/** Device handoff presence, shared by relay and HTTP: read a session's driver
+ * and carried-over draft, and publish this device's unsent draft. */
+export function createPresenceCommands(book, publish) {
+    return {
+        "session.presence.get"(input, ctx) {
+            const requestId = typeof input.requestId === "string" ? input.requestId : undefined;
+            ctx.reply({ type: "session.presence.get.ok", requestId, presence: book.get(String(input.sessionId)) });
+        },
+        "session.presence.draft"(input, ctx) {
+            const requestId = typeof input.requestId === "string" ? input.requestId : undefined;
+            const device = deviceFrom(input.device);
+            if (!device)
+                return ctx.reply({ type: "session.presence.draft.error", httpStatus: 400, requestId, error: "Missing device" });
+            publish(book.draft(String(input.sessionId), device, String(input.text ?? "")));
+            ctx.reply({ type: "session.presence.draft.ok", requestId });
+        },
+    };
+}

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/policy/session-limit.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Session limit recovery — the user-driven counterpart to the policy's automatic
+// resume (session-reroute.ts planResume).
+//
+// When a turn ends because the agent hit a provider usage/rate limit and no
+// ruleset recovered it automatically, the session shouldn't just show a dead
+// error. This decides whether the failure IS such a limit, and what the user can
+// do about it: fork the work to another agent right away, or opt in to retrying
+// the same prompt automatically once the window resets. The caller (server.ts)
+// surfaces the offer as a notice with action buttons and, when the user accepts
+// the retry, schedules it through the same durable resume machinery the
+// automatic path uses.
+import { classifyFailure } from "./conditions.js";
+/** The conditions a user can route around (fork) or wait out (retry at reset),
+ *  with how the notice describes each. Adding a limit-like condition is a row. */
+const LIMIT_COPY = {
+    credits_exhausted: "reached its usage limit",
+    rate_limited: "is being rate-limited",
+};
+/** Retry a little after the stated reset: providers round reset times and a
+ *  re-send that lands a few seconds early just hits the same limit again. */
+const RESET_GRACE_MS = 60_000;
+/** Classify a turn error; returns the limit it represents, or undefined when it
+ *  is some other failure. `resetsAtHint` is the provider's structured reset time
+ *  (see ClassifyOptions) and wins over anything scraped from the text. */
+export function detectSessionLimit(error, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const classified = classifyFailure(error, { now, resetsAtHint: opts.resetsAtHint });
+    if (!LIMIT_COPY[classified.condition])
+        return undefined;
+    const resetsAt = classified.resetsAt
+        ?? (classified.retryAfterMs !== undefined ? new Date(now + classified.retryAfterMs).toISOString() : undefined);
+    return { condition: classified.condition, ...(resetsAt ? { resetsAt } : {}) };
+}
+/** The notice offering the user a way past the limit. Actions are client
+ *  action ids: `fork` opens the fork sheet; `retry-at-reset:<iso>` opts in to an
+ *  automatic retry (the timestamp is only for the button's label — the daemon
+ *  schedules from its own remembered limit). */
+export function sessionLimitNotice(agentName, limit) {
+    const what = `${agentName} ${LIMIT_COPY[limit.condition] ?? "hit a limit"}.`;
+    return limit.resetsAt
+        ? {
+            message: `${what} Fork to another agent to keep going, or retry automatically when the limit resets.`,
+            actions: ["fork", `retry-at-reset:${limit.resetsAt}`],
+        }
+        : { message: `${what} Fork to another agent to keep going.`, actions: ["fork"] };
+}
+/** A resume plan for a user who opted in to retrying at reset. Undefined when
+ *  the reset time is unknown. A reset already in the past retries shortly. */
+export function limitResumePlan(limit, now = Date.now()) {
+    const reset = limit.resetsAt ? Date.parse(limit.resetsAt) : NaN;
+    if (!Number.isFinite(reset))
+        return undefined;
+    const dueMs = Math.max(reset, now) + RESET_GRACE_MS;
+    return {
+        condition: limit.condition,
+        summary: `${limit.condition}: retrying when the limit resets at ${limit.resetsAt}.`,
+        delayMs: dueMs - now,
+        resumeAt: new Date(dueMs).toISOString(),
+    };
+}

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

@@ -3,10 +3,12 @@
 /** 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/artifacts/list", kind: "artifacts.list" },
     { 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" },
+    ...["get", "draft"].map((action) => ({ method: "post", path: `/api/session/presence/${action}`, kind: `session.presence.${action}` })),
     { method: "post", path: "/api/session/resume", kind: "session.resume" },
     { method: "post", path: "/api/session/question/answer", kind: "session.question.answer" },
 ];