@bivy/bivy 0.17.3-staging.9 → 0.18.0

package/dist/apps/service.js

@@ -1,11 +1,21 @@
+import { randomBytes } from "node:crypto";
+import { REVIEW_MODES, shouldReview, visualChange } from "./review.js";
 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";
+import { approximate, composite, readStrokes } from "./annotate.js";
+import { captureFrame, encodePng, sendInput } from "./rfb.js";
+import { inputEvents, readAction } from "./input.js";
+import { pressMenu, readMenuPath, readMenus } from "./menu.js";
+import { pngSize } from "./review.js";
+const NO_REVIEWS = { publish: (review) => review, expire: () => { } };
 const NO_DISPLAYS = { unavailable: () => "Desktop app views aren't available on this machine.", ensure: () => Promise.reject(new Error("Desktop app views aren't available on this machine.")), stop: () => { } };
 /** How long a screenshot waits for a desktop app's first window. */
 const WINDOW_WAIT_MS = 15_000;
+/** How long an app gets to react to input before its picture is taken. */
+const AFTER_INPUT_MS = 400;
 /** 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
@@ -26,6 +36,15 @@ export class AppService {
     screenshots;
     displays;
     shooting = Promise.resolve();
+    reviews;
+    settleMs;
+    runs = new Map();
+    /** The latest card per view: a newer one expires its images. */
+    latest = new Map();
+    /** Per view: the newest reviewer note a run-end card has already counted. */
+    handedOver = new Map();
+    /** Screenshots in progress, so a card, Compare and a baseline share one browser run. */
+    inflight = new Map();
     constructor(registry, gateway, terminals, options = {}) {
         this.registry = registry;
         this.gateway = gateway;
@@ -34,7 +53,10 @@ export class AppService {
         this.serverWatchMs = options.serverWatchMs ?? 5_000;
         this.screenshots = { enabled: options.screenshots?.enabled ?? (() => false), take: options.screenshots?.take ?? takeShots };
         this.displays = options.displays ?? NO_DISPLAYS;
+        this.reviews = options.reviews ?? NO_REVIEWS;
+        this.settleMs = options.settleMs ?? COMPARE_SETTLE_MS;
     }
+    /** A session's apps, or every app on this machine when no session is given. */
     list(sessionId) {
         const available = Boolean(this.gateway) && this.gateway?.available !== false;
         const apps = this.registry.list(sessionId);
@@ -49,6 +71,8 @@ export class AppService {
                     view.notes = structuredClone(entry.notes);
                 if (entry?.stats)
                     view.stats = structuredClone(entry.stats);
+                if (entry?.lastPath)
+                    view.lastPath = entry.lastPath;
             }
         return { apps, previewAvailable: available };
     }
@@ -74,29 +98,200 @@ export class AppService {
             void this.ensureServer(entry).catch(() => { });
         }
         if (bumped.length && this.screenshots.enabled())
-            setTimeout(() => void this.capture(bumped), COMPARE_SETTLE_MS).unref?.();
+            setTimeout(() => void this.capture(bumped), this.settleMs).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;
+            if (entry?.view.kind === "web")
+                await this.shotOf(entry);
+        }
+    }
+    /** A phone-width screenshot of a page at the view's current revision: one
+     * already taken (Compare's after-turn shot), one in progress, or a new one.
+     * Undefined when it fails; a card then goes without a picture. */
+    shotOf(entry, page = entry.lastPath ?? "/") {
+        const revision = entry.revision;
+        const taken = [...entry.shots ?? []].reverse().find((shot) => shot.revision === revision && (shot.path ?? "/") === page);
+        if (taken)
+            return Promise.resolve(taken.png);
+        const key = `${entry.view.id}:${revision}:${page}`;
+        let pending = this.inflight.get(key);
+        if (pending)
+            return pending;
+        pending = (async () => {
             await this.windowShown(entry).catch(() => { });
-            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));
+            const outDir = path.join(os.tmpdir(), "bivy-shots", "compare", entry.view.id);
+            const run = this.shooting.catch(() => { }).then(() => this.screenshots.take([entry], { widths: [390], themes: ["light"], path: page }, outDir));
             this.shooting = run;
             try {
                 const [shot] = await run;
                 if (!shot)
-                    continue;
+                    return undefined;
                 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);
+                entry.shots = [...(entry.shots ?? []), { revision, at: Date.now(), png, path: page }].slice(-COMPARE_KEEP);
+                return png;
             }
-            catch { /* a failed shot just leaves Compare without this turn */ }
+            catch {
+                return undefined; /* a failed shot just leaves Compare without this turn */
+            }
+            finally {
+                this.inflight.delete(key);
+            }
+        })();
+        this.inflight.set(key, pending);
+        return pending;
+    }
+    /** Web views of a session whose app wants review cards on their own. */
+    reviewable(sessionId) {
+        return this.registry.list(sessionId).filter((app) => REVIEW_MODES[this.registry.reviewMode(app.id)].minChange !== undefined)
+            .flatMap((app) => app.views.filter((view) => view.kind === "web").map((view) => this.registry.getView(view.id))).filter(Boolean);
+    }
+    /** An agent run started. Remembers each view's revision, and the page as
+     * it is now, so the end of the run can tell whether anything visibly
+     * changed. A baseline is only taken when no screenshot of this revision
+     * exists yet — after the first run, the last run's screenshot serves. */
+    runStarted(sessionId) {
+        const views = this.reviewable(sessionId);
+        const run = { start: new Map(views.map((entry) => [entry.view.id, entry.revision])), baseline: new Map(), reviews: new Map(), muted: false, ended: false };
+        this.runs.set(sessionId, run);
+        if (!this.screenshots.enabled())
+            return;
+        for (const entry of views)
+            void this.shotOf(entry).then((png) => { if (png && entry.revision === run.start.get(entry.view.id))
+                run.baseline.set(entry.view.id, png); });
+    }
+    /** The run ended (done, or waiting for the user). Views whose revision
+     * changed are screenshotted and compared with the page before the run; a
+     * visible change makes (or updates) this run's card. Returns the run's
+     * latest card, for the "session finished" notification. */
+    async runEnded(sessionId) {
+        const run = this.runs.get(sessionId);
+        if (!run || run.ended)
+            return undefined;
+        run.ended = true;
+        let latest;
+        const changed = [...run.start].map(([id, revision]) => ({ entry: this.registry.getView(id), revision })).filter(({ entry, revision }) => entry && entry.revision !== revision);
+        if (changed.length && this.screenshots.enabled() && !run.muted)
+            await new Promise((r) => setTimeout(r, this.settleMs));
+        for (const { entry } of changed) {
+            if (!entry || !this.screenshots.enabled())
+                continue;
+            const mode = this.registry.reviewMode(entry.app.id);
+            if (run.muted || REVIEW_MODES[mode].minChange === undefined)
+                continue;
+            const before = run.baseline.get(entry.view.id);
+            const after = await this.shotOf(entry);
+            const change = before && after ? visualChange(before, after) : undefined;
+            // A card the agent presented earlier in the run is refreshed if the page changed since.
+            const current = this.latest.get(entry.view.id);
+            const presented = current && run.reviews.get(entry.app.id) === current.id;
+            if (!shouldReview({ trigger: "run", mode, muted: run.muted, revisionChanged: true, change }) && !(presented && after))
+                continue;
+            latest = this.review(entry, run, { trigger: presented ? current.trigger : "run", note: presented ? current.note : undefined, path: entry.lastPath ?? "/", shot: after, before });
+        }
+        // Reviewer notes that arrived since the last hand-over ride on the view's
+        // card for this run, or get a card of their own. A count only: the notes
+        // stay on the machine until the owner drafts them into a message.
+        for (const entry of this.webViews(sessionId)) {
+            const waiting = (entry.notes ?? []).filter((note) => note.at > (this.handedOver.get(entry.view.id) ?? 0));
+            if (!waiting.length || run.muted || this.registry.reviewMode(entry.app.id) === "off")
+                continue;
+            this.handedOver.set(entry.view.id, Math.max(...waiting.map((note) => note.at)));
+            const notes = entry.notes.length;
+            const current = this.latest.get(entry.view.id);
+            if (current && run.reviews.get(entry.app.id) === current.id) {
+                const card = this.reviews.publish({ ...current, notes, at: Date.now() }, {});
+                this.latest.set(entry.view.id, card);
+                if (!latest || latest.id === card.id)
+                    latest = card;
+            }
+            else {
+                // Cards are one per app per run: another view's card keeps its own; these notes get a new one.
+                const card = this.review(entry, run.reviews.has(entry.app.id) ? undefined : run, { trigger: "notes", path: entry.lastPath ?? "/", notes });
+                // A visible change stays what "finished" talks about; notes fill in when there's nothing else.
+                latest ??= card;
+            }
+        }
+        if (!latest) {
+            const id = [...run.reviews.values()].at(-1);
+            latest = [...this.latest.values()].find((review) => review.id === id);
+        }
+        return latest;
+    }
+    /** `bivy app present`, or Show me ("asked"): a card for one view now. */
+    async present(sessionId, input) {
+        const trigger = input.trigger ?? "present";
+        const page = input.path;
+        if (page !== undefined && (typeof page !== "string" || !page.startsWith("/") || page.startsWith("//") || page.length > 2048))
+            throw new Error("Path must start with /.");
+        const note = typeof input.note === "string" ? input.note.trim().slice(0, 500) : undefined;
+        const entry = this.pickView(sessionId, input.target);
+        const mode = this.registry.reviewMode(entry.app.id);
+        const active = this.runs.get(sessionId);
+        const run = active && !active.ended ? active : undefined;
+        if (!shouldReview({ trigger, mode, muted: run?.muted ?? false, revisionChanged: true })) {
+            return { message: run?.muted ? "The user muted preview cards for this run. They can still open the preview from the chat." : `Preview cards are off for ${entry.app.name}. The user can still open the preview from the chat.` };
+        }
+        // Presenting means the change is ready: pick up files written since the
+        // turn began, so the picture (and any open preview) shows them.
+        if (trigger === "present" && this.turnChanged(sessionId).includes(entry.view.id) && this.screenshots.enabled())
+            await new Promise((r) => setTimeout(r, this.settleMs));
+        const enabled = this.screenshots.enabled();
+        const path = page ?? entry.lastPath ?? "/";
+        const shot = enabled ? await this.shotOf(entry, path) : undefined;
+        const baseline = run?.baseline.get(entry.view.id);
+        const before = baseline && shot && !baseline.equals(shot) && path === (entry.lastPath ?? "/") ? baseline : undefined;
+        const review = this.review(entry, run, { trigger, note, path, shot, before, screenshotsOff: !enabled });
+        return { review, message: enabled ? (shot ? "The user sees it in the chat." : "The user sees a card in the chat, but the screenshot failed.") : "The user sees a card in the chat. Screenshots are off on this machine, so it has no picture." };
+    }
+    /** No more cards for the rest of the session's current run. */
+    mute(sessionId) {
+        const run = this.runs.get(sessionId);
+        if (run && !run.ended)
+            run.muted = true;
+        return { ok: true };
+    }
+    setReviewMode(sessionId, appId, mode) {
+        this.registry.setReviewMode(sessionId, appId, mode);
+        return { ok: true };
+    }
+    /** A view by app or view ID or name; by default the one opened last, else the newest app's first. */
+    webViews(sessionId) {
+        return this.registry.list(sessionId).flatMap((app) => app.views.filter((view) => view.kind === "web").map((view) => this.registry.getView(view.id))).filter(Boolean);
+    }
+    pickView(sessionId, target, desktop = false) {
+        const views = this.webViews(sessionId).filter((entry) => !desktop || entry.target.kind === "display");
+        const noun = desktop ? "desktop app" : "web view";
+        if (!views.length)
+            throw new Error(desktop ? "This session has no desktop apps. Publish one with bivy app run -- <command>." : "This session has no web views to present. Publish one with bivy app publish, or preview a detected server.");
+        if (target) {
+            const wanted = target.trim().toLowerCase();
+            const found = views.find((entry) => [entry.app.id, entry.view.id].includes(wanted))
+                ?? views.find((entry) => entry.view.name.toLowerCase() === wanted) ?? views.find((entry) => entry.app.name.toLowerCase() === wanted);
+            if (!found)
+                throw new Error(`No ${noun} called "${target}" in this session. Run bivy app list to see them.`);
+            return found;
         }
+        return views.reduce((best, entry) => (entry.openedAt ?? 0) > (best.openedAt ?? 0) || ((entry.openedAt ?? 0) === (best.openedAt ?? 0) && entry.app.createdAt > best.app.createdAt) ? entry : best);
+    }
+    /** Makes or updates a card, keeping each view's images to the latest card. */
+    review(entry, run, fields) {
+        const id = (run && run.reviews.get(entry.app.id)) ?? `review-${randomBytes(8).toString("hex")}`;
+        const { shot, before, ...rest } = fields;
+        const review = this.reviews.publish({
+            id, sessionId: entry.app.sessionId, appId: entry.app.id, viewId: entry.view.id, name: entry.app.name, view: entry.view.name,
+            at: Date.now(), ...Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined && value !== false)),
+        }, { shot, before });
+        const previous = this.latest.get(entry.view.id);
+        if (previous && previous.id !== review.id)
+            this.reviews.expire(previous, new Set([review.shot?.hash, review.before?.hash].filter((hash) => Boolean(hash))));
+        this.latest.set(entry.view.id, review);
+        run?.reviews.set(entry.app.id, review.id);
+        return review;
     }
     /** Servers running in the workspace that this session doesn't preview yet. */
     async offers(sessionId, workspace) {
@@ -113,7 +308,8 @@ export class AppService {
     /** `direct` opens the app origin itself (no shell): a signed-in device
      * returning to a view's stable address. */
     /** `scale`: the opening device's pixel density, used if this starts a display. */
-    async open(sessionId, appId, viewId, returnTo, direct = false, scale) {
+    /** `page`: start on this page instead of the app's root (a review card's page). */
+    async open(sessionId, appId, viewId, returnTo, direct = false, scale, page) {
         const entry = this.registry.requireView(sessionId, appId, viewId);
         if (entry.target.kind === "display" && !entry.display)
             entry.displayScale = scale === 2 ? 2 : 1;
@@ -122,15 +318,18 @@ export class AppService {
                 throw new Error("Bivy's preview service is unavailable on this connection.");
             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);
+            let url = direct ? this.gateway.openDirect(viewId) : this.gateway.open(viewId, returnTo);
+            if (page && page.startsWith("/") && !page.startsWith("//") && page.length <= 2048)
+                url += `~${encodeURIComponent(page).replace(/~/g, "%7E")}`;
             // 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(() => { });
+            entry.openedAt = Date.now();
             // 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?.();
+                setTimeout(() => void this.capture([viewId]), this.settleMs).unref?.();
             return { kind: "web", url };
         }
         if (entry.target.kind !== "terminal")
@@ -186,6 +385,99 @@ export class AppService {
         this.shooting = run;
         return { shots: await run };
     }
+    /** Computer use: an agent clicks, types, presses keys and scrolls in one of
+     * its desktop apps, in the pixels of the app's screenshot, the way a viewer
+     * would. Starts the app if needed. With screenshots on, returns the app as
+     * it looks afterwards, so the agent sees what its action did. */
+    async act(sessionId, target, input) {
+        const action = readAction(input);
+        const entry = this.pickView(sessionId, target, true);
+        if (!entry.display)
+            await this.windowShown(entry);
+        if (!entry.display)
+            throw new Error("The app isn't running. Check its Logs in the Apps sheet.");
+        const { width, height } = await sendInput(entry.display, inputEvents(action));
+        if (!this.screenshots.enabled())
+            return { width, height, message: "Done. Agent screenshots are off on this machine, so there's no picture of the result: bivy config set sessions.appScreenshots true" };
+        return { width, height, shot: await this.after(entry, sessionId), message: "Done. The shot is the app now." };
+    }
+    /** A desktop app's menu bar: listed, or one item chosen by its path of
+     * titles ("File > Save"). Choosing returns the app afterwards, like `act`. */
+    async menu(sessionId, target, path) {
+        const item = path === undefined ? undefined : readMenuPath(path);
+        const entry = this.pickView(sessionId, target, true);
+        if (!entry.display)
+            await this.windowShown(entry);
+        if (!entry.displayControl)
+            throw new Error("This machine's desktop apps don't expose their menus (macOS only). Use keyboard shortcuts: bivy app key.");
+        if (!item)
+            return { menus: await readMenus(entry.displayControl) };
+        await pressMenu(entry.displayControl, item);
+        if (!this.screenshots.enabled())
+            return { message: "Chosen. Agent screenshots are off on this machine, so there's no picture of the result." };
+        return { shot: await this.after(entry, sessionId), message: "Chosen. The shot is the app now." };
+    }
+    /** The app a moment after an action, as a screenshot. */
+    async after(entry, sessionId) {
+        await new Promise((r) => setTimeout(r, AFTER_INPUT_MS));
+        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([entry], { widths: [], themes: [], path: "/" }, outDir));
+        this.shooting = run;
+        return (await run)[0];
+    }
+    /** Draw on the preview: the user's marks on a picture of what they saw.
+     * The picture is the Compare screenshot they drew on, a desktop app's
+     * current frame, or a web page retaken at their viewport, pixel ratio and
+     * scroll — "approximate" when the page may hold state a fresh browser
+     * doesn't. Returned to the client (over the session channel) as a PNG. */
+    async annotate(sessionId, input) {
+        const entry = this.registry.requireView(sessionId, input.appId, input.viewId);
+        if (entry.view.kind !== "web")
+            throw new Error("Only previews can be drawn on.");
+        const strokes = readStrokes(input.strokes);
+        const whole = (n, min, max) => typeof n === "number" && Number.isFinite(n) && n >= min && n <= max;
+        // Compare's shot is drawn on at its on-screen size, which can be small.
+        if (!whole(input.viewport?.width, 40, 4000) || !whole(input.viewport?.height, 40, 8000))
+            throw new Error("Invalid viewport.");
+        const viewport = { width: Math.round(input.viewport.width), height: Math.round(input.viewport.height) };
+        const page = typeof input.path === "string" && input.path.startsWith("/") && !input.path.startsWith("//") && input.path.length <= 2048 ? input.path : entry.lastPath ?? "/";
+        const scroll = { x: whole(input.scroll?.x, 0, 1e6) ? input.scroll.x : 0, y: whole(input.scroll?.y, 0, 1e6) ? input.scroll.y : 0 };
+        const name = `${entry.app.name} ${page === "/" ? "" : page} marked.png`.replace(/[^\w .()-]+/g, "-").replace(/\s+/g, " ").trim();
+        const finish = (base, offset, approx) => {
+            const png = composite(base, strokes, { scale: pngSize(base).width / viewport.width, offset });
+            return { image: { data: png.toString("base64"), mimeType: "image/png", name, ...pngSize(png) }, approximate: approx };
+        };
+        // Compare: the exact frame they drew on, in its own coordinates.
+        if (input.compare !== undefined) {
+            const shot = Number.isInteger(input.compare) ? entry.shots?.[input.compare] : undefined;
+            if (!shot)
+                throw new Error("That Compare screenshot is no longer kept. Open Compare again.");
+            return finish(shot.png, { x: 0, y: 0 }, approximate("exact"));
+        }
+        if (!this.screenshots.enabled())
+            return { approximate: false, screenshotsOff: true };
+        // A desktop app: its display's current frame is exactly what they saw.
+        if (entry.target.kind === "display") {
+            await this.windowShown(entry).catch(() => { });
+            if (!entry.display)
+                throw new Error("The app isn't running, so there's nothing to draw on.");
+            const frame = await captureFrame(entry.display);
+            return finish(encodePng(frame.width, frame.height, frame.rgb), { x: 0, y: 0 }, approximate("exact"));
+        }
+        const outDir = path.join(os.tmpdir(), "bivy-shots", "annotate", entry.view.id);
+        const dpr = whole(input.dpr, 1, 3) ? Math.round(input.dpr * 4) / 4 : 2;
+        const run = this.shooting.catch(() => { }).then(() => this.screenshots.take([entry], { widths: [viewport.width], themes: [input.theme === "dark" ? "dark" : "light"], path: page, height: viewport.height, scale: dpr, scroll }, outDir));
+        this.shooting = run;
+        const [shot] = await run;
+        if (!shot)
+            throw new Error("Couldn't take a picture of the page.");
+        const base = fs.readFileSync(shot.file);
+        fs.rmSync(outDir, { recursive: true, force: true });
+        const landed = shot.scroll ?? scroll;
+        const scrolledTo = Math.abs(landed.x - scroll.x) <= 2 && Math.abs(landed.y - scroll.y) <= 2;
+        // Marks stay on the content they were drawn on, wherever the retake scrolled.
+        return finish(base, landed, approximate("retake", input.signals, scrolledTo));
+    }
     /** 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);
@@ -215,7 +507,9 @@ export class AppService {
             throw new Error("This view has no program.");
         return this.displays.ensure(entry.view.id, entry.app.name, entry.displayScale).then((display) => {
             entry.display = display.socket;
-            return { command: target.command, args: target.args, workspace: target.workspace, env: display.env, name: `${entry.app.name} · ${entry.view.name}` };
+            entry.displayControl = display.control;
+            const [command, ...args] = [...display.launch ?? [], target.command, ...target.args];
+            return { command: command, args, workspace: target.workspace, env: display.env, name: `${entry.app.name} · ${entry.view.name}` };
         });
     }
     /** Services start synchronously; a desktop app waits for its display. */
@@ -270,6 +564,7 @@ export class AppService {
         const entry = this.registry.getView(id);
         if (entry) {
             entry.display = undefined;
+            entry.displayControl = undefined;
             entry.displayScale = undefined;
         }
         const server = this.servers.get(id);
@@ -288,10 +583,45 @@ export class AppService {
             throw new Error("Bivy's preview service is unavailable on this connection.");
         return this.gateway.share(viewId);
     }
+    /** `bivy app share`: mints a share link for a web view picked by app and/or
+     * view ID or name, like `present` (default: the one opened last). */
+    shareView(sessionId, input) {
+        const entry = this.pickTarget(sessionId, input);
+        return { ...this.share(sessionId, entry.app.id, entry.view.id), appId: entry.app.id, viewId: entry.view.id, app: entry.app.name, view: entry.view.name };
+    }
     clearNotes(sessionId, appId, viewId) {
-        delete this.registry.requireView(sessionId, appId, viewId).notes;
+        this.registry.requireView(sessionId, appId, viewId);
+        this.registry.clearNotes(viewId);
+        return { ok: true };
+    }
+    /** The owner's choice (never the agent's): may agents read this app's notes? */
+    setAgentNotes(sessionId, appId, enabled) {
+        this.registry.setAgentNotes(sessionId, appId, enabled);
         return { ok: true };
     }
+    /** `bivy app notes`: reviewer notes for an agent, only on apps whose owner
+     * allowed it. Picked like `bivy app share`. Untrusted text, and labelled so. */
+    notes(sessionId, input) {
+        const entry = this.pickTarget(sessionId, input);
+        if (!this.registry.agentNotes(entry.app.id))
+            throw new Error(`Reviewer notes on ${entry.app.name} are private to its owner. They can allow agents to read them in Apps → ${entry.app.name} → ⋯ → Agents can read notes.`);
+        const since = typeof input.since === "number" && Number.isFinite(input.since) ? input.since : 0;
+        return { app: entry.app.name, view: entry.view.name, appId: entry.app.id, viewId: entry.view.id, untrusted: true, notes: structuredClone((entry.notes ?? []).filter((note) => note.at > since)) };
+    }
+    /** An app and/or view by ID or name (`bivy app share`, `bivy app notes`); by default the view opened last. */
+    pickTarget(sessionId, input) {
+        if (!input.view)
+            return this.pickView(sessionId, input.app);
+        const wantedApp = input.app?.trim().toLowerCase();
+        const scope = this.webViews(sessionId).filter((candidate) => !wantedApp || candidate.app.id === wantedApp || candidate.app.name.toLowerCase() === wantedApp);
+        if (wantedApp && !scope.length)
+            throw new Error(`No app called "${input.app}" with web views in this session. Run bivy app list to see them.`);
+        const wanted = input.view.trim().toLowerCase();
+        const found = scope.find((candidate) => candidate.view.id === wanted) ?? scope.find((candidate) => candidate.view.name.toLowerCase() === wanted);
+        if (!found)
+            throw new Error(`No web view called "${input.view}"${input.app ? ` in "${input.app}"` : ""}. Run bivy app list to see them.`);
+        return found;
+    }
     /** Ends every link, browser session and open connection for one view; the app stays. */
     revoke(sessionId, appId, viewId) {
         this.registry.requireView(sessionId, appId, viewId);