@bivy/bivy 0.19.4-staging.1 → 0.19.4-staging.2

package/dist/apps/review.js

@@ -105,6 +105,36 @@ export function visualChange(before, after) {
     }
     return changed / (a.width * a.height);
 }
+/** Share of a pin's marked region that must differ between the page before a
+ * run and the page after it before the pin is called "changed". Higher than a
+ * whole-page threshold: a region is small, so a handful of antialiased pixels
+ * is a larger share of it, and calling a pin answered when it isn't is worse
+ * than leaving it open. */
+export const PIN_CHANGE = 0.01;
+/** Share of pixels that visibly differ inside one region (0–1). The region is
+ * in page CSS pixels; `scale` maps those to image pixels. Returns undefined
+ * when the region isn't inside both images — a page that grew or shrank says
+ * nothing about the marked spot. */
+export function regionChange(before, after, region, scale) {
+    const a = decodePng(before), b = decodePng(after);
+    if (a.width !== b.width || a.height !== b.height)
+        return undefined;
+    const left = Math.max(0, Math.floor(region.x * scale)), top = Math.max(0, Math.floor(region.y * scale));
+    const right = Math.min(a.width, Math.ceil((region.x + region.width) * scale)), bottom = Math.min(a.height, Math.ceil((region.y + region.height) * scale));
+    const pixels = (right - left) * (bottom - top);
+    if (pixels <= 0)
+        return undefined;
+    let changed = 0;
+    for (let y = top; y < bottom; y++) {
+        for (let x = left; x < right; x++) {
+            const i = (y * a.width + x) * a.channels, j = (y * b.width + x) * b.channels;
+            const delta = Math.abs(a.pixels[i] - b.pixels[j]) + Math.abs(a.pixels[i + 1] - b.pixels[j + 1]) + Math.abs(a.pixels[i + 2] - b.pixels[j + 2]);
+            if (delta > 12)
+                changed++;
+        }
+    }
+    return changed / pixels;
+}
 /** PNG dimensions, from the header. */
 export function pngSize(png) {
     return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };

package/dist/apps/screenshot.js

@@ -122,6 +122,12 @@ export async function takeShots(views, request, outDir, chrome = findChrome()) {
     let ws;
     let browser;
     const deadline = setTimeout(() => browser?.kill("SIGKILL"), 120_000);
+    // How long Chrome gets to print its DevTools line. Generous on purpose: this
+    // only bounds a browser that never comes up, and it costs nothing when one
+    // starts quickly. A tighter bound turned a loaded machine — a shared CI
+    // runner, a laptop mid-build — into "the browser didn't start in time" and a
+    // missing screenshot, which is a worse answer than waiting.
+    const START_MS = 60_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.
@@ -130,7 +136,7 @@ export async function takeShots(views, request, outDir, chrome = findChrome()) {
         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);
+        const timer = setTimeout(() => reject(new Error("The browser didn't start in time.")), START_MS);
         child.stderr.on("data", (chunk) => { text += chunk; const m = /DevTools listening on (ws:\/\/\S+)/.exec(text); if (m) {
             clearTimeout(timer);
             resolve(m[1]);
@@ -188,10 +194,18 @@ export async function takeShots(views, request, outDir, chrome = findChrome()) {
                         const { result } = await cdp.send("Runtime.evaluate", { expression: "[scrollX, scrollY]", returnByValue: true }, sessionId);
                         scroll = { x: Number(result?.value?.[0]) || 0, y: Number(result?.value?.[1]) || 0 };
                     }
+                    let missing;
+                    if (request.selectors?.length) {
+                        // The page's own selectors, evaluated as data: a list of strings in,
+                        // a list of strings out, never anything the page chooses to run.
+                        const wanted = JSON.stringify(request.selectors.slice(0, 50));
+                        const { result } = await cdp.send("Runtime.evaluate", { expression: `(${wanted}).filter(s => { try { return !document.querySelector(s); } catch { return false; } })`, returnByValue: true }, sessionId);
+                        missing = Array.isArray(result?.value) ? result.value.filter((s) => typeof s === "string") : undefined;
+                    }
                     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, ...(scroll ? { scroll } : {}), ...(elementScrollsRestored !== undefined ? { elementScrollsRestored } : {}) });
+                    shots.push({ viewId: entry.view.id, view: entry.view.name, width, theme, file, ...(scroll ? { scroll } : {}), ...(elementScrollsRestored !== undefined ? { elementScrollsRestored } : {}), ...(missing ? { missing } : {}) });
                 }
         }
         return shots;

package/dist/apps/service.js

@@ -2,18 +2,27 @@
 // Copyright (c) 2026 Petter André Sjulstad
 import { SHARE_DURATIONS } from "./types.js";
 import { randomBytes } from "node:crypto";
-import { REVIEW_MODES, shouldReview, visualChange } from "./review.js";
+import { PIN_CHANGE, REVIEW_MODES, regionChange, 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, readElementScrolls } from "./annotate.js";
+import { approximate, composite, crop, noteAnchor, readNotes, readStrokes, readElementScrolls } 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_PINS = { publish: (pin) => pin };
+/** A pin's region is in the page CSS pixels of the viewport it was marked in.
+ * Run screenshots are taken at this width, so a pin marked at a very different
+ * one sat on a different layout: its region says nothing about these pixels,
+ * and it stays open rather than being answered wrongly. */
+const PIN_SHOT_WIDTH = 390;
+const PIN_WIDTH_TOLERANCE = 0.1;
+/** How long a drawn picture is kept for the pin that may follow it. */
+const MARK_TTL_MS = 10 * 60_000;
 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;
@@ -40,6 +49,12 @@ export class AppService {
     displays;
     shooting = Promise.resolve();
     reviews;
+    pinSink;
+    /** Pins made in this node's lifetime, newest last, by view. */
+    pins = [];
+    /** The last picture drawn on a view, kept briefly for the pin that may
+     *  follow it: the person is still typing their words when it is made. */
+    lastMark = new Map();
     settleMs;
     runs = new Map();
     /** The latest card per view: a newer one expires its images. */
@@ -57,6 +72,7 @@ export class AppService {
         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.pinSink = options.pins ?? NO_PINS;
         this.settleMs = options.settleMs ?? COMPARE_SETTLE_MS;
     }
     /** A session's apps, or every app on this machine when no session is given. */
@@ -151,10 +167,15 @@ export class AppService {
         this.inflight.set(key, pending);
         return pending;
     }
-    /** Web views of a session whose app wants review cards on their own. */
+    hasOpenPins(viewId) {
+        return this.pins.some((pin) => pin.viewId === viewId && pin.state === "open");
+    }
+    /** Web views a run watches: those whose app wants review cards, and those
+     * carrying a pin still waiting for an answer. */
     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);
+        return this.registry.list(sessionId)
+            .flatMap((app) => app.views.filter((view) => view.kind === "web").map((view) => this.registry.getView(view.id))).filter(Boolean)
+            .filter((entry) => REVIEW_MODES[this.registry.reviewMode(entry.app.id)].minChange !== undefined || this.hasOpenPins(entry.view.id));
     }
     /** 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
@@ -187,10 +208,15 @@ export class AppService {
             if (!entry || !this.screenshots.enabled())
                 continue;
             const mode = this.registry.reviewMode(entry.app.id);
-            if (run.muted || REVIEW_MODES[mode].minChange === undefined)
-                continue;
+            const cards = !run.muted && REVIEW_MODES[mode].minChange !== undefined;
             const before = run.baseline.get(entry.view.id);
-            const after = await this.shotOf(entry);
+            // Pins are answered from evidence even where cards are off or muted:
+            // turning cards off means "stop showing me the app", not "forget what I
+            // asked for".
+            const after = cards || this.hasOpenPins(entry.view.id) ? await this.shotOf(entry) : undefined;
+            await this.resolvePins(entry, before, after);
+            if (!cards)
+                continue;
             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);
@@ -440,7 +466,10 @@ export class AppService {
         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);
+        // Several notes, each owning its strokes; one unnumbered mark is the same
+        // thing with a single entry, so there is one path through here.
+        const grouped = readNotes(input.notes);
+        const strokes = grouped.length ? grouped.flatMap((note) => note.strokes) : readStrokes(input.strokes);
         const elementScrolls = readElementScrolls(input.elementScrolls);
         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.
@@ -450,8 +479,22 @@ export class AppService {
         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 box = (of) => {
+            const xs = of.flatMap((stroke) => stroke.points.map(([x]) => x));
+            const ys = of.flatMap((stroke) => stroke.points.map(([, y]) => y));
+            return { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) };
+        };
+        const loose = (Array.isArray(input.selectors) ? input.selectors : []).filter((value) => typeof value === "string" && value.length > 0 && value.length <= 300).slice(0, 8);
+        // What each note covers, in the page pixels it was drawn in, so a later
+        // screenshot can be compared exactly there (see resolvePins).
+        const held = grouped.length
+            ? grouped.map((note) => ({ n: note.n, words: note.words, selectors: note.selectors, region: box(note.strokes) }))
+            : [{ n: 1, words: "", selectors: loose, region: box(strokes) }];
+        const badges = grouped.length > 1 ? grouped.map((note) => ({ n: note.n, ...noteAnchor(note) })) : [];
         const finish = (base, offset, approx) => {
-            const png = composite(base, strokes, { scale: pngSize(base).width / viewport.width, offset });
+            const png = composite(base, strokes, { scale: pngSize(base).width / viewport.width, offset }, badges);
+            // Keep it for the pins that may follow: the person is still writing.
+            this.lastMark.set(entry.view.id, { at: Date.now(), png, path: page, viewport, notes: held });
             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.
@@ -485,6 +528,87 @@ export class AppService {
         // Marks stay on the content they were drawn on, wherever the retake scrolled.
         return finish(base, landed, approximate("retake", input.signals, scrolledTo && shot.elementScrollsRestored !== false));
     }
+    /** A pin: the marks the person just sent, kept as a thing with a state
+     * rather than a paragraph in a message. Made only when the message is
+     * actually sent, so nothing appears in the chat that the person didn't send.
+     * The picture is the one `annotate` already made for the message. */
+    pin(sessionId, input) {
+        const entry = this.registry.requireView(sessionId, input.appId, input.viewId);
+        const mark = this.lastMark.get(input.viewId);
+        if (!mark || Date.now() - mark.at > MARK_TTL_MS)
+            throw new Error("That mark is no longer held. Mark the preview again.");
+        this.lastMark.delete(input.viewId);
+        const scale = pngSize(mark.png).width / mark.viewport.width;
+        const fallback = String(input.words ?? "").trim().slice(0, 2000);
+        const made = mark.notes.map((note) => {
+            // The card shows what that note marked, not the whole page it sat on.
+            // The message keeps the full picture; this is the pin's own thumbnail.
+            let picture = mark.png;
+            try {
+                picture = crop(mark.png, note.region, scale);
+            }
+            catch { /* the whole picture still tells the story */ }
+            const pin = this.pinSink.publish({
+                id: `pin-${randomBytes(8).toString("hex")}`, sessionId, appId: entry.app.id, viewId: entry.view.id,
+                name: entry.app.name, view: entry.view.name, path: mark.path,
+                words: note.words || fallback, at: Date.now(),
+                ...(mark.notes.length > 1 ? { number: note.n } : {}),
+                selectors: note.selectors, region: note.region, viewport: mark.viewport, state: "open",
+            }, picture);
+            this.pins = [...this.pins, pin].slice(-200);
+            return pin;
+        });
+        return { pins: made };
+    }
+    /** The person's own verdict on a pin. Only they can say "done". */
+    setPinState(sessionId, pinId, state) {
+        const current = this.pins.find((pin) => pin.id === pinId && pin.sessionId === sessionId);
+        if (!current)
+            throw new Error("That pin is no longer held on this machine.");
+        return { pin: this.updatePin(current, state) };
+    }
+    updatePin(pin, state) {
+        const next = this.pinSink.publish({ ...pin, state, stateAt: Date.now() });
+        this.pins = this.pins.map((item) => (item.id === pin.id ? next : item));
+        return next;
+    }
+    /** After a run, say what became of the pins on a view — from evidence only.
+     * "gone" when what a pin named is no longer on the page; "changed" when the
+     * pixels it marked differ from before the run. A run that changed nothing
+     * there leaves the pin open: it has not been answered. */
+    async resolvePins(entry, before, after) {
+        const open = this.pins.filter((pin) => pin.viewId === entry.view.id && pin.state === "open");
+        if (!open.length)
+            return;
+        const selectors = [...new Set(open.flatMap((pin) => pin.selectors))];
+        let missing;
+        if (selectors.length && this.screenshots.enabled()) {
+            const outDir = path.join(os.tmpdir(), "bivy-shots", "pins", entry.view.id);
+            try {
+                const run = this.shooting.catch(() => { }).then(() => this.screenshots.take([entry], { widths: [PIN_SHOT_WIDTH], themes: ["light"], path: entry.lastPath ?? "/", selectors }, outDir));
+                this.shooting = run;
+                missing = (await run)[0]?.missing;
+            }
+            catch { /* no answer is not an answer: the pins stay open */ }
+            finally {
+                fs.rmSync(outDir, { recursive: true, force: true });
+            }
+        }
+        for (const pin of open) {
+            if (missing && pin.selectors.length && pin.selectors.every((selector) => missing.includes(selector))) {
+                this.updatePin(pin, "gone");
+                continue;
+            }
+            if (!before || !after || pin.path !== (entry.lastPath ?? "/"))
+                continue;
+            // A pin marked at a very different width sat on a different layout.
+            if (Math.abs(pin.viewport.width - PIN_SHOT_WIDTH) > PIN_SHOT_WIDTH * PIN_WIDTH_TOLERANCE)
+                continue;
+            const change = regionChange(before, after, pin.region, pngSize(after).width / pin.viewport.width);
+            if (change !== undefined && change > PIN_CHANGE)
+                this.updatePin(pin, "changed");
+        }
+    }
     /** 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);

package/dist/apps/styles.css

@@ -3161,6 +3161,11 @@ p.setup-note .btn.link { min-height: 44px; margin-block: calc((1lh - 44px) / 2);
 .review-actions { display: flex; flex-wrap: wrap; gap: var(--space-1); padding: var(--space-3); }
 .review-actions .btn { min-block-size: var(--space-7); }
 
+/* Pin card (PinCard.tsx): the review card's layout, carrying what someone
+   marked instead of what a run produced. The state is one .badge, and the
+   words are the same quoted block a review note uses. */
+.pin-card .review-note { margin-block-start: 0; }
+
 /* Apps sheet (AppsSheet.tsx): one card per app, its views nested, one primary
    action per view; secondary tools as quiet icon buttons; rare or destructive
    actions behind ⋯ (MoreMenu, the canonical .menu). Status uses .banner. */

package/dist/apps/types.js

@@ -17,6 +17,22 @@ export function isAppReview(value) {
         && (review.note === undefined || typeof review.note === "string")
         && (review.notes === undefined || (Number.isInteger(review.notes) && review.notes >= 0));
 }
+export const APP_PIN_STATES = ["open", "changed", "gone", "done"];
+export const APP_PIN_BLOCK = "bivy_app_pin";
+export function isAppPin(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const pin = value;
+    const box = (v, keys) => !!v && typeof v === "object" && keys.every((k) => typeof v[k] === "number");
+    return typeof pin.id === "string" && typeof pin.sessionId === "string" && typeof pin.appId === "string" && /^[a-f0-9]{32}$/.test(pin.appId)
+        && typeof pin.viewId === "string" && typeof pin.name === "string" && typeof pin.view === "string" && typeof pin.path === "string"
+        && typeof pin.words === "string" && typeof pin.at === "number"
+        && (pin.number === undefined || (Number.isInteger(pin.number) && pin.number >= 1))
+        && Array.isArray(pin.selectors) && pin.selectors.every((s) => typeof s === "string")
+        && box(pin.region, ["x", "y", "width", "height"]) && box(pin.viewport, ["width", "height"])
+        && APP_PIN_STATES.includes(pin.state)
+        && (pin.shot === undefined || isShot(pin.shot));
+}
 export const APP_PUBLICATION_BLOCK = "bivy_app";
 export function isAppReference(value) {
     if (!value || typeof value !== "object")

package/dist/controllers/app-commands.js

@@ -29,6 +29,10 @@ export function createAppCommands(service, workspaceFor, published = () => { })
         "apps.mute": (msg) => service.mute(String(msg.sessionId)),
         "apps.reviewMode": (msg) => service.setReviewMode(String(msg.sessionId), String(msg.appId), msg.mode),
         "apps.annotate": (msg) => service.annotate(String(msg.sessionId), msg),
+        // A pin is made only once the person has actually sent the message the
+        // marks went into, so nothing appears in the chat that they didn't send.
+        "apps.pin": (msg) => service.pin(String(msg.sessionId), { appId: String(msg.appId), viewId: String(msg.viewId), words: typeof msg.words === "string" ? msg.words : "" }),
+        "apps.pinState": (msg) => service.setPinState(String(msg.sessionId), String(msg.pinId), msg.state),
         "apps.clearNotes": (msg) => service.clearNotes(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.agentNotes": (msg) => service.setAgentNotes(String(msg.sessionId), String(msg.appId), msg.enabled === true),
         "apps.notes": (msg) => service.notes(String(msg.sessionId), { app: typeof msg.appId === "string" ? msg.appId : undefined, view: typeof msg.view === "string" ? msg.view : undefined, since: typeof msg.since === "number" ? msg.since : undefined }),

package/dist/server.js

@@ -1856,7 +1856,7 @@ function referencedAttachmentHashes() {
     // `scan`, not `entries`: this visits every session ever created, and must not pin
     // each one's full log in the event-log cache.
     for (const id of ids) {
-        for (const entry of eventLog.scan(id, ["attachment", "outbound-attachment", "inline-image", "app-review"])) {
+        for (const entry of eventLog.scan(id, ["attachment", "outbound-attachment", "inline-image", "app-review", "app-pin"])) {
             if (entry.bivyKind === "attachment")
                 for (const ref of entry.refs)
                     hashes.add(ref.hash);
@@ -1865,6 +1865,10 @@ function referencedAttachmentHashes() {
                     if (shot)
                         hashes.add(shot.hash);
             }
+            else if (entry.bivyKind === "app-pin") {
+                if (entry.pin.shot)
+                    hashes.add(entry.pin.shot.hash);
+            }
             else if (entry.bivyKind === "outbound-attachment" || entry.bivyKind === "inline-image")
                 hashes.add(entry.ref.hash);
         }
@@ -2146,6 +2150,32 @@ function createReviewSink() {
         },
     };
 }
+/** Pins: the picture becomes an encrypted attachment like a review card's, and
+ * the pin is logged where it was made, so it keeps its place in the chat while
+ * only its state moves. */
+function createPinSink() {
+    const anchors = new Map();
+    return {
+        publish(pin, image) {
+            const record = resolveSession(pin.sessionId);
+            if (!record)
+                return pin;
+            const card = { ...pin };
+            if (image && !card.shot) {
+                try {
+                    const ref = attachmentStore.put(image, { name: `${pin.name} ${pin.path} pinned.png`, mimeType: "image/png", kind: "image" });
+                    card.shot = { hash: ref.hash, size: ref.size, ...pngSize(image) };
+                }
+                catch { /* a pin without a picture still carries the words and the marks */ }
+            }
+            const at = anchors.get(card.id) ?? { afterMessageCount: record.session.getMessages().length, createdAt: Date.now() };
+            anchors.set(card.id, at);
+            eventLog.appendAppPin(record.id, { ...at, pin: card });
+            broadcast(stampSessionEvent({ type: "session.event", sessionId: record.id, event: { type: "app_pin", id: card.id, pin: card } }));
+            return card;
+        },
+    };
+}
 const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     start: async (spec) => {
         let failure = "Could not start the app terminal.";
@@ -2160,7 +2190,7 @@ const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     },
     has: (id) => terminals.has(id),
     close: (id) => { terminals.close(id); },
-}, { screenshots: { enabled: appScreenshotsEnabled }, displays: appDisplays, reviews: createReviewSink() });
+}, { screenshots: { enabled: appScreenshotsEnabled }, displays: appDisplays, reviews: createReviewSink(), pins: createPinSink() });
 // A reviewer's note shows up in an open Apps sheet without reopening it, and
 // the owner gets one push per burst of notes on a view ("2 notes on
 // Storefront"), which opens the Apps sheet at that app. Counts, names and IDs

package/dist/session/event-log.js

@@ -30,7 +30,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { normalizedIntermediateText, thinkingTextFromContent, mergeTranscript } from "./transcript-merge.js";
 import { DELEGATION_BLOCK, isDelegationCard } from "./delegations.js";
-import { APP_PUBLICATION_BLOCK, APP_REVIEW_BLOCK, isAppReference, isAppReview } from "../apps/types.js";
+import { APP_PIN_BLOCK, APP_PUBLICATION_BLOCK, APP_REVIEW_BLOCK, isAppPin, isAppReference, isAppReview } from "../apps/types.js";
 import { SUGGESTION_BLOCK, isTaskSuggestion } from "./suggestions.js";
 /**
  * Decompose a transcript message into serialization-independent "atoms": the
@@ -267,8 +267,14 @@ function isAppReviewEntry(value) {
     const entry = value;
     return entry.bivyKind === "app-review" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isAppReview(entry.review);
 }
+function isAppPinEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return entry.bivyKind === "app-pin" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isAppPin(entry.pin);
+}
 function isRecord(value) {
-    return isDelegationEntry(value) || isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isSuggestionEntry(value);
+    return isDelegationEntry(value) || isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isAppPinEntry(value) || isSuggestionEntry(value);
 }
 /**
  * Fold attachment records into a text→refs list: last write wins per text (a
@@ -390,6 +396,15 @@ export function replayExtras(entries) {
         role: "assistant", content: [{ type: APP_REVIEW_BLOCK, review: entry.review }],
         id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
     }));
+    // A pin keeps where it was made and shows its latest state.
+    const pins = new Map();
+    for (const entry of entries)
+        if (entry.bivyKind === "app-pin")
+            pins.set(entry.id, entry);
+    const pinCards = [...pins.values()].map((entry) => ({
+        role: "assistant", content: [{ type: APP_PIN_BLOCK, pin: entry.pin }],
+        id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
+    }));
     // A delegation card keeps the place it was created and shows its latest state.
     const delegations = new Map();
     for (const entry of entries) {
@@ -406,7 +421,7 @@ export function replayExtras(entries) {
         role: "assistant", content: [{ type: SUGGESTION_BLOCK, suggestion: entry.suggestion }],
         id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
     }));
-    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...delegationCards, ...suggestions];
+    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...pinCards, ...delegationCards, ...suggestions];
 }
 /**
  * Fold the outbound (agent-sent) attachment records into time-anchored synthetic
@@ -719,6 +734,10 @@ export class EventLog {
         this.load(id);
         this.enqueue(id, `review:${entry.review.id}`, { bivyKind: "app-review", createdAt: entry.createdAt ?? Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.review.id, review: structuredClone(entry.review) });
     }
+    appendAppPin(id, entry) {
+        this.load(id);
+        this.enqueue(id, `pin:${entry.pin.id}`, { bivyKind: "app-pin", createdAt: entry.createdAt ?? Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.pin.id, pin: structuredClone(entry.pin) });
+    }
     appendSuggestion(id, entry) {
         this.load(id);
         this.enqueue(id, `suggestion:${entry.suggestion.id}`, { bivyKind: "suggestion", createdAt: Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.suggestion.id, suggestion: { ...entry.suggestion } });

package/package.json

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