@bivy/bivy 0.1.0-staging.13 → 0.1.0-staging.14

package/dist/server.js

@@ -66,6 +66,7 @@ import { thinkingTextFromContent } from "./session/transcript-merge.js";
 import { normalizeMessages } from "./session/transcript-normal.js";
 import { buildNativeImportSeedPrompt } from "./session/native-import.js";
 import { EventLog } from "./session/event-log.js";
+import { AttachmentStore, isValidAttachmentHash } from "./session/attachment-store.js";
 import { ReplicationService } from "./session/replication-service.js";
 import { createSessionNewDedupe } from "./session/session-new-dedupe.js";
 import { evaluateForkPrereqs, blockingForkPrereqs, missingForkPrereqs } from "./session/fork-prereqs.js";
@@ -855,9 +856,12 @@ function safeAttachmentName(value) {
     return String(value || "attachment").replace(/[\r\n]/g, " ").slice(0, 180);
 }
 /**
- * Split composer attachments into three channels:
+ * Split composer attachments into channels:
  *   - `images`     — base64 blobs passed to the model as vision.
  *   - `imageNotes` — one prose line per image for the persisted transcript.
+ *   - `imageRefs`  — durable AttachmentStore references for the images, persisted
+ *                    in the event log so they rehydrate after a reload / on
+ *                    another device (images used to be vision-only, then lost).
  *   - `files`      — decoded file attachments (bytes or text) to be written to
  *                    disk by materializeAttachments so the agent can open them
  *                    with its normal file tools. Any file type is supported;
@@ -865,9 +869,10 @@ function safeAttachmentName(value) {
  */
 function attachmentsFrom(value) {
     if (!Array.isArray(value))
-        return { images: [], imageNotes: [], files: [] };
+        return { images: [], imageNotes: [], imageRefs: [], files: [] };
     const images = [];
     const imageNotes = [];
+    const imageRefs = [];
     const files = [];
     for (const raw of value.slice(0, 12)) {
         if (!raw || typeof raw !== "object")
@@ -877,8 +882,17 @@ function attachmentsFrom(value) {
         const size = Number(attachment.size || 0);
         const mimeType = typeof attachment.mimeType === "string" && attachment.mimeType ? attachment.mimeType : undefined;
         if (attachment.kind === "image" && typeof attachment.data === "string") {
-            images.push({ type: "image", data: attachment.data, mimeType: mimeType ?? "image/png" });
+            const imgMime = mimeType ?? "image/png";
+            images.push({ type: "image", data: attachment.data, mimeType: imgMime });
             imageNotes.push(`[Image attachment: ${name}${size ? ` (${size} bytes)` : ""}]`);
+            // Persist the image bytes durably (dedup by hash). Best-effort: a store
+            // failure must not break vision for the turn, so it only costs the ref.
+            try {
+                imageRefs.push(attachmentStore.put(Buffer.from(attachment.data, "base64"), { name, mimeType: imgMime, kind: "image" }));
+            }
+            catch (error) {
+                console.warn("[attachments] failed to store image:", error instanceof Error ? error.message : String(error));
+            }
         }
         else if (attachment.kind === "file") {
             if (typeof attachment.data === "string" && attachment.data) {
@@ -891,7 +905,7 @@ function attachmentsFrom(value) {
             // nothing to write, so there is nothing to hand the agent — skip it.
         }
     }
-    return { images, imageNotes, files };
+    return { images, imageNotes, imageRefs, files };
 }
 /** Strip a user-supplied filename to a safe basename — no path traversal, no
  * characters that would break the placeholder note or the filesystem. */
@@ -914,7 +928,22 @@ function sanitizeAttachmentFilename(name) {
  */
 function materializeAttachments(record, files) {
     if (!files.length)
-        return "";
+        return { note: "", refs: [] };
+    const refs = [];
+    // Store every file durably in the global content-addressed store first (for
+    // re-findability), independent of the per-workdir copy below. Best-effort per
+    // file so one bad blob doesn't lose the others.
+    for (const file of files) {
+        const bytes = file.bytes ?? (typeof file.text === "string" ? Buffer.from(file.text, "utf8") : undefined);
+        if (!bytes)
+            continue;
+        try {
+            refs.push(attachmentStore.put(bytes, { name: sanitizeAttachmentFilename(file.name), mimeType: file.mimeType, kind: "file" }));
+        }
+        catch (error) {
+            console.warn("[attachments] failed to store file:", error instanceof Error ? error.message : String(error));
+        }
+    }
     const workdir = harnessDirFor(record);
     const dir = path.join(workdir, ".bivy-attachments");
     try {
@@ -922,7 +951,7 @@ function materializeAttachments(record, files) {
     }
     catch (error) {
         const why = error instanceof Error ? error.message : String(error);
-        return files.map((f) => `[File attachment: ${sanitizeAttachmentFilename(f.name)} could not be saved: ${why}]`).join("\n");
+        return { note: files.map((f) => `[File attachment: ${sanitizeAttachmentFilename(f.name)} could not be saved: ${why}]`).join("\n"), refs };
     }
     const notes = [];
     const used = new Set();
@@ -953,7 +982,7 @@ function materializeAttachments(record, files) {
             notes.push(`[File attachment: ${label} could not be saved: ${error instanceof Error ? error.message : String(error)}]`);
         }
     }
-    return notes.join("\n");
+    return { note: notes.join("\n"), refs };
 }
 function approvalModeFrom(value) {
     return value === "never" || value === "risky" || value === "always" || value === "autonomous" ? value : undefined;
@@ -1971,6 +2000,12 @@ function eventLogPath(sessionId) {
 // eventLog.deriveHistory. `redactSecrets` scrubs credentials at the single flush
 // choke point before anything lands on the synced-to-PWA disk.
 const eventLog = new EventLog(eventLogDir, eventLogPath, redactSecrets);
+// Global content-addressed store for message attachments (images + files). Unlike
+// the per-session `.bivy-attachments/` worktree copy (kept so the agent can open
+// files with its tools), this is durable, session-independent, and re-findable:
+// the transcript references blobs by hash, and clients rehydrate thumbnails by
+// hash after a reload or on another device. See src/session/attachment-store.ts.
+const attachmentStore = new AttachmentStore(path.join(appDir, "attachments"));
 // --- Warm session replication (docs/session-replication.md) -----------------
 // A standby's replica repo lives under appDir/replicas/<id>: a self-contained git
 // repo that receives checkpoint bundles and is checked out on promotion. Created
@@ -2228,6 +2263,9 @@ function buildHistoryEvent(opts) {
         prUrl: record?.prUrl ?? opts.prUrl,
         prs: record?.prs ?? opts.prs,
         bivySession: bSess,
+        // Durable attachment references (text→refs), so a client that never sent the
+        // attachment (a reload, or a different device) rehydrates thumbnails by hash.
+        attachmentRefs: opts.sessionId ? eventLog.readAttachments(opts.sessionId) : [],
     };
 }
 // Idempotency for `session.new` keyed by requestId: a client's post-reconnect
@@ -2248,6 +2286,27 @@ const RELAY_COMMANDS = {
     ping(msg, ctx) {
         ctx.reply({ type: "pong", requestId: typeof msg.requestId === "string" ? msg.requestId : undefined });
     },
+    // Fetch a stored attachment's bytes by content hash. The relay client (a phone
+    // not on the LAN) can't reach the GET /api/attachment endpoint, so it fetches
+    // over the encrypted tunnel instead; the relay framing chunks the base64 payload
+    // (the same mechanism that carries large image uploads). Direct/LAN clients use
+    // the HTTP endpoint. Both are authenticated — the relay tunnel by enrollment,
+    // the HTTP route by /api's authMiddleware.
+    "attachment.fetch"(msg, ctx) {
+        const requestId = typeof msg.requestId === "string" ? msg.requestId : undefined;
+        const hash = typeof msg.hash === "string" ? String(msg.hash) : "";
+        if (!isValidAttachmentHash(hash)) {
+            ctx.reply({ type: "attachment.error", requestId, hash, error: "Invalid attachment id" });
+            return;
+        }
+        const bytes = attachmentStore.read(hash);
+        if (!bytes) {
+            ctx.reply({ type: "attachment.error", requestId, hash, error: "Attachment not found" });
+            return;
+        }
+        const meta = attachmentStore.readMeta(hash);
+        ctx.reply({ type: "attachment.data", requestId, hash, mimeType: meta?.mimeType ?? "application/octet-stream", name: meta?.name, data: bytes.toString("base64") });
+    },
     "session.pause"(msg) {
         const record = resolveSession(msg.sessionId);
         if (record)
@@ -3039,7 +3098,7 @@ const RELAY_COMMANDS = {
     },
     async prompt(msg) {
         const text = String(msg.text ?? "").trim();
-        const { images, imageNotes, files } = attachmentsFrom(msg.attachments);
+        const { images, imageNotes, imageRefs, files } = attachmentsFrom(msg.attachments);
         if (!text && !images.length && !files.length)
             return;
         // Title/naming can only see what we have before the session exists; the file
@@ -3077,9 +3136,12 @@ const RELAY_COMMANDS = {
         touchSession(record);
         // Now that the session (and its workdir) exists, write file attachments to
         // disk and fold their path notes into the prompt the agent actually sees.
-        const fileNote = materializeAttachments(record, files);
+        const { note: fileNote, refs: fileRefs } = materializeAttachments(record, files);
         const promptText = [text, imageNotes.join("\n"), fileNote].filter(Boolean).join("\n\n") ||
             (images.length ? "Please review the attached image(s)." : files.length ? "Please review the attached file(s)." : "");
+        // Persist durable attachment refs keyed by the exact text the transcript
+        // stores for this user message, so history rehydrates thumbnails by hash.
+        eventLog.appendAttachments(record.id, promptText, [...imageRefs, ...fileRefs]);
         const agentPrompt = promptForAgent(record, promptText);
         const cmid = typeof msg.clientMessageId === "string" && msg.clientMessageId ? msg.clientMessageId : undefined;
         void dedupePrompt(cmid, async () => {
@@ -6340,7 +6402,10 @@ function maybeRenameWorktreeBranch(record, name) {
     const result = spawnSync("git", ["-C", wt.path, "branch", "-m", wt.branch, next], { encoding: "utf8", timeout: 10_000 });
     if (result.error || result.status !== 0) {
         const detail = String(result.stderr || result.error || "git branch rename failed").trim();
-        console.warn(`[branch-rename] could not rename ${wt.branch} to ${next}:`, detail);
+        // Pass the branch names as args, not spliced into the format string: a branch
+        // name containing a %-specifier would otherwise be interpreted by console.warn
+        // (CodeQL js/tainted-format-string).
+        console.warn("[branch-rename] could not rename %s to %s:", wt.branch, next, detail);
         return;
     }
     wt.branch = next;
@@ -9023,13 +9088,31 @@ app.get("/api/repos", async (_req, res) => {
 app.get("/api/repos/branches", async (req, res) => {
     res.json(await listRepoBranches(String(req.query.repo || "").trim()));
 });
+// Serve a stored attachment's bytes by content hash (direct/LAN clients). Behind
+// /api's authMiddleware. Content-addressed, so responses are immutably cacheable.
+// The hash is validated to a 64-char hex before it ever touches a path.
+app.get("/api/attachment/:hash", (req, res) => {
+    const hash = String(req.params.hash || "");
+    if (!isValidAttachmentHash(hash))
+        return res.status(400).json({ error: "Invalid attachment id" });
+    const bytes = attachmentStore.read(hash);
+    if (!bytes)
+        return res.status(404).json({ error: "Attachment not found" });
+    const meta = attachmentStore.readMeta(hash);
+    res.setHeader("Content-Type", meta?.mimeType || "application/octet-stream");
+    res.setHeader("Content-Length", String(bytes.length));
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    // Content-addressed: the bytes for a hash never change, so cache aggressively.
+    res.setHeader("Cache-Control", "private, max-age=31536000, immutable");
+    res.end(bytes);
+});
 app.post("/api/session/prompt", async (req, res, next) => {
     try {
         const text = String(req.body?.text ?? "").trim();
         if (text === "/login" || text.startsWith("/login ")) {
             return res.status(400).json({ error: "Use the Login / API tokens dialog from the phone UI. If it is not visible, refresh this page after updating Bivy." });
         }
-        const { images, imageNotes, files } = attachmentsFrom(req.body?.attachments);
+        const { images, imageNotes, imageRefs, files } = attachmentsFrom(req.body?.attachments);
         if (!text && !images.length && !files.length)
             return res.status(400).json({ error: "Missing text" });
         // File notes (with on-disk paths) are folded in once the workdir exists; the
@@ -9052,9 +9135,10 @@ app.post("/api/session/prompt", async (req, res, next) => {
             return res.status(409).json({ error: record.tuiRefreshing ? "This session is returning from the terminal. Try again in a moment." : "This session is open in the terminal (TUI). Close the TUI to chat here." });
         }
         const session = record.session;
-        const fileNote = materializeAttachments(record, files);
+        const { note: fileNote, refs: fileRefs } = materializeAttachments(record, files);
         const promptText = [text, imageNotes.join("\n"), fileNote].filter(Boolean).join("\n\n") ||
             (images.length ? "Please review the attached image(s)." : files.length ? "Please review the attached file(s)." : "");
+        eventLog.appendAttachments(record.id, promptText, [...imageRefs, ...fileRefs]);
         const agentPrompt = promptForAgent(record, promptText);
         const cmid = typeof req.body?.clientMessageId === "string" && req.body.clientMessageId ? req.body.clientMessageId : undefined;
         markSessionWorking(record, { type: "agent_start" });

package/dist/session/attachment-store.js

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Content-addressed blob store for message attachments (images + files).
+//
+// Attachments used to be fragile and un-refindable: image bytes were passed to
+// the model as vision for a single turn and then dropped entirely (never written
+// anywhere), while file attachments were written only into the session's
+// ephemeral worktree at `<workdir>/.bivy-attachments/`. Nothing survived in a
+// stable, session-independent location, so a reload on another device — or after
+// the client's in-memory attachment cache aged out — showed only a bare
+// "[Image attachment: …]" placeholder.
+//
+// This store fixes that: every attachment is written ONCE to a global folder
+// under `<appDir>/attachments/`, addressed by the SHA-256 of its bytes. Identical
+// bytes dedupe for free (same hash → same path), the location is stable and
+// re-findable, and the transcript references a blob by hash instead of carrying
+// (or losing) the bytes. Paths are two-level sharded (`ab/cd/<hash>`) so a busy
+// node never piles millions of entries into one directory. A small sidecar
+// `<hash>.json` remembers a human name / mime / size for the blob.
+//
+// Out of scope for now (tracked as TODOs): garbage-collecting blobs no transcript
+// references any more, and a global size cap / LRU eviction on the store.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/** A 64-char lowercase-hex SHA-256, the only shape a valid hash can take. */
+const HASH_RE = /^[0-9a-f]{64}$/;
+/** Whether `value` is a well-formed content hash (guards path building). */
+export function isValidAttachmentHash(value) {
+    return typeof value === "string" && HASH_RE.test(value);
+}
+/**
+ * A global, content-addressed attachment store rooted at a single directory.
+ * All methods are best-effort and synchronous, matching the surrounding
+ * server code (EventLog, SidecarStore) — attachment persistence must never sink
+ * a turn, so a write failure surfaces as a thrown error the caller degrades to a
+ * text note rather than a crash.
+ */
+export class AttachmentStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** `<dir>/ab/cd` for a hash beginning `abcd…`. */
+    shardDir(hash) {
+        return path.join(this.dir, hash.slice(0, 2), hash.slice(2, 4));
+    }
+    blobPath(hash) {
+        return path.join(this.shardDir(hash), hash);
+    }
+    metaPath(hash) {
+        return path.join(this.shardDir(hash), `${hash}.json`);
+    }
+    /**
+     * Store `bytes` and return a durable reference. Content-addressed, so calling
+     * this twice with identical bytes writes the blob once and returns the same
+     * hash. The blob write is skipped when the file already exists (dedupe); the
+     * sidecar is written only the first time so the earliest name/mime wins.
+     */
+    put(bytes, opts) {
+        const hash = crypto.createHash("sha256").update(bytes).digest("hex");
+        const ref = { hash, name: opts.name, mimeType: opts.mimeType, size: bytes.length, kind: opts.kind };
+        fs.mkdirSync(this.shardDir(hash), { recursive: true });
+        const blob = this.blobPath(hash);
+        if (!fs.existsSync(blob))
+            fs.writeFileSync(blob, bytes);
+        if (!fs.existsSync(this.metaPath(hash))) {
+            const meta = { ...ref, createdAt: Date.now() };
+            try {
+                fs.writeFileSync(this.metaPath(hash), JSON.stringify(meta));
+            }
+            catch {
+                // A missing sidecar only costs us the remembered name/mime — the blob is
+                // what matters, so never let a sidecar write failure fail the store.
+            }
+        }
+        return ref;
+    }
+    /** The blob's metadata, or null if the hash is unknown/malformed. */
+    readMeta(hash) {
+        if (!isValidAttachmentHash(hash))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(this.metaPath(hash), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The on-disk path of a stored blob, or null if absent/malformed. */
+    getPath(hash) {
+        if (!isValidAttachmentHash(hash))
+            return null;
+        const blob = this.blobPath(hash);
+        return fs.existsSync(blob) ? blob : null;
+    }
+    /** Read a stored blob's raw bytes, or null if absent/malformed. */
+    read(hash) {
+        const p = this.getPath(hash);
+        if (!p)
+            return null;
+        try {
+            return fs.readFileSync(p);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/session/event-log.js

@@ -40,8 +40,35 @@ function isBase(value) {
     const record = value;
     return record.bivyKind === "base" && Array.isArray(record.messages) && typeof record.reset === "boolean";
 }
+function isAttachment(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.bivyKind === "attachment" && typeof record.text === "string" && Array.isArray(record.refs);
+}
 function isRecord(value) {
-    return isOverlay(value) || isBase(value);
+    return isOverlay(value) || isBase(value) || isAttachment(value);
+}
+/**
+ * Fold attachment records into a text→refs list: last write wins per text (a
+ * resent identical prompt re-keys onto the newest refs), preserving first-seen
+ * order. `mergeTranscript` never sees these — the client matches them onto the
+ * user messages by their persisted text, exactly as its in-memory attachment
+ * cache did, but now sourced durably from the log.
+ */
+export function replayAttachments(entries) {
+    const byText = new Map();
+    for (const entry of entries) {
+        if (entry.bivyKind !== "attachment")
+            continue;
+        if (!entry.text || !entry.refs.length)
+            continue;
+        // delete+set so a re-keyed text moves to the end (newest), matching the
+        // client's rememberAttachments last-wins semantics.
+        byText.delete(entry.text);
+        byText.set(entry.text, entry.refs);
+    }
+    return [...byText.entries()];
 }
 /**
  * Fold the intermediate-reasoning entries exactly as the legacy incremental
@@ -243,6 +270,22 @@ export class EventLog {
         this.baseKeys.set(id, nextKeys);
         this.enqueue(id, this.syntheticKey(id), record);
     }
+    /**
+     * Record the attachment references a user sent with a prompt, keyed by the
+     * prompt's persisted text. Id-less (synthetic key) so successive prompts never
+     * coalesce. A no-op when there are no refs.
+     */
+    appendAttachments(id, text, refs) {
+        if (!text || !refs.length)
+            return;
+        this.load(id);
+        const record = { bivyKind: "attachment", createdAt: Date.now(), text, refs: refs.map((r) => ({ ...r })) };
+        this.enqueue(id, this.syntheticKey(id), record);
+    }
+    /** Replay the attachment records (disk + pending) into a text→refs list. */
+    readAttachments(id) {
+        return replayAttachments(this.entries(id));
+    }
     /** Replay the overlay entries (disk + pending) into the flat `extras` list. */
     read(id) {
         return replayExtras(this.entries(id));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.1.0-staging.13",
+  "version": "0.1.0-staging.14",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",