@bivy/bivy 0.3.0-staging.47 → 0.3.0-staging.48

package/bin/bivy.mjs

@@ -1528,7 +1528,7 @@ function cmdCompletions(args = []) {
   const shell = (args[0] || "").toLowerCase();
   const commands = [
     "run", "sessions", "ls", "resume", "promote", "rename", "nodes", "agents", "agents:install", "shim", "takeover", "token", "exec",
-    "send", "kill", "setup", "start", "stop", "restart", "status", "doctor", "logs", "login",
+    "send", "attach", "kill", "setup", "start", "stop", "restart", "status", "doctor", "logs", "login",
     "update", "update:log", "open", "service", "secrets", "voice", "link", "relay:setup",
     "github:connect", "github:app-create", "github:app-connect", "github:app-sync", "prune", "uninstall", "help", "version",
   ];
@@ -1974,6 +1974,62 @@ async function cmdSend(args = []) {
   process.exit(code);
 }
 
+// `bivy attach <file> [--caption "…"] [--session <id>]` — surface a file the
+// agent produced into the chat as an image/file attachment (the reverse of the
+// composer paperclip). The universal path: any agent that can run a shell command
+// can call this. The session id defaults to $BIVY_SESSION_ID, which the daemon
+// injects into the agent's subprocess env. The file is resolved to an absolute
+// path here (the CLI's cwd is the agent's workdir) and confined to the session
+// workspace server-side.
+async function cmdAttach(args = []) {
+  const flag = (name) => {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+  };
+  const sessionId = flag("--session") || process.env.BIVY_SESSION_ID;
+  const caption = flag("--caption");
+  const name = flag("--name");
+  const mimeType = flag("--mime") || flag("--mimeType");
+  const flagsWithValue = new Set(["--session", "--caption", "--name", "--mime", "--mimeType"]);
+  // First positional that isn't a flag or a flag's value.
+  let file;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("-")) { if (flagsWithValue.has(a)) i++; continue; }
+    if (i > 0 && flagsWithValue.has(args[i - 1])) continue;
+    file = a;
+    break;
+  }
+  if (!file) { console.error(c.red('Usage: bivy attach <file> [--caption "…"] [--session <id>]')); process.exit(1); return; }
+  if (!sessionId) { console.error(c.red("No session id. Set --session <id> or run inside an agent session ($BIVY_SESSION_ID).")); process.exit(1); return; }
+  const absPath = path.resolve(process.cwd(), file);
+  if (!fs.existsSync(absPath)) { console.error(c.red(`File not found: ${file}`)); process.exit(1); return; }
+
+  const config = loadConfig();
+  if (!(await ensureNodeRunning(config))) { console.error(c.red(`Could not reach the Bivy node at ${url(config)}.`)); process.exit(1); return; }
+  // A token isn't required on a single-user host (loopback bypasses auth), but
+  // include it when available so multi-user hosts work too.
+  let token;
+  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const headers = { "content-type": "application/json" };
+  if (token) headers.authorization = `Bearer ${token}`;
+  let res;
+  try {
+    res = await fetch(`${url(config)}/api/session/${encodeURIComponent(sessionId)}/attach`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ path: absPath, caption, name, mimeType }),
+    });
+  } catch (error) {
+    console.error(c.red(`Could not reach the Bivy node: ${error?.message || String(error)}`));
+    process.exit(1);
+    return;
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) { console.error(c.red(`Attach failed (${res.status}): ${body?.error || "unknown error"}`)); process.exit(1); return; }
+  console.log(c.green(`Attached ${body.name} (${body.kind}, ${body.size} bytes) to the chat.`));
+}
+
 // Map a saved session's runtime id to the `bivy run` agent whose native CLI can
 // resume it in a terminal. Only agents with a real native resume qualify; other
 // runtimes (generic-cli, SDK-only) have no terminal resume and open in the web app.
@@ -4128,6 +4184,9 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "send":
       await cmdSend(args);
       break;
+    case "attach":
+      await cmdAttach(args);
+      break;
     case "completions":
     case "completion":
       cmdCompletions(args);

package/dist/runtime/claude-code.js

@@ -671,6 +671,11 @@ class ClaudeSession {
         const env = { ...process.env, ...depCacheEnv(), ...this.runtimeOptions.env };
         const credEnv = await this.resolveCredentialEnv();
         Object.assign(env, credEnv);
+        // Let the agent's own shell surface a file into the chat via `bivy attach`
+        // (POST /api/session/:id/attach). The session id is otherwise invisible to
+        // the subprocess. Other runtimes should set this the same way to enable the
+        // universal attach path for their agents.
+        env.BIVY_SESSION_ID = this.id;
         this.spawnedToken = authTokenFromEnv(credEnv);
         const options = {
             cwd: this.cwd,

package/dist/server.js

@@ -71,6 +71,7 @@ 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 { planAttachment, isAttachPlanError } from "./session/attach-to-chat.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";
@@ -1032,6 +1033,40 @@ function materializeAttachments(record, files) {
     }
     return { note: notes.join("\n"), refs };
 }
+/**
+ * Surface an AGENT-produced file into the chat as an attachment (image or file)
+ * — the reverse of the composer paperclip. Confines to the session workspace,
+ * stores the bytes in the content-addressed AttachmentStore, persists a durable
+ * outbound reference anchored at the current transcript position (so a reload or
+ * another device shows it), and emits the live `attachment` event so attached
+ * devices render the chip/thumbnail immediately. Shared by the HTTP endpoint and
+ * the `bivy attach` CLI. Returns the stored ref, or a human-readable error.
+ */
+function attachToChat(record, opts) {
+    const plan = planAttachment({
+        workspaceDir: harnessDirFor(record),
+        filePath: opts.filePath,
+        mimeType: opts.mimeType,
+        name: opts.name,
+    });
+    if (isAttachPlanError(plan))
+        return { error: plan.error };
+    let ref;
+    try {
+        ref = attachmentStore.put(plan.bytes, { name: plan.name, mimeType: plan.mimeType, kind: plan.kind });
+    }
+    catch (error) {
+        return { error: `Could not store the attachment: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const entryId = `att-${randomBytes(8).toString("hex")}`;
+    const caption = opts.caption ? String(opts.caption).slice(0, 2000) : undefined;
+    // Anchor at the current base length so history replay interleaves the
+    // attachment where it was emitted (see event-log outbound projection).
+    const afterMessageCount = record.session.getMessages().length;
+    eventLog.appendOutboundAttachment(record.id, { afterMessageCount, id: entryId, ref, caption });
+    broadcast({ type: "session.event", sessionId: record.id, event: { type: "attachment", id: entryId, ref, caption } });
+    return { ref };
+}
 function approvalModeFrom(value) {
     return value === "never" || value === "risky" || value === "always" || value === "autonomous" ? value : undefined;
 }
@@ -9523,6 +9558,29 @@ app.get("/api/attachment/:hash", (req, res) => {
     res.setHeader("Cache-Control", "private, max-age=31536000, immutable");
     res.end(bytes);
 });
+// Let an AGENT push a file into the chat as an attachment (image/file) — the
+// reverse of the composer upload. Called by the agent's own shell (`bivy attach`)
+// or any local tool; on a single-user host the loopback bypass means no token is
+// needed. Behind /api's authMiddleware. `path` is resolved inside — and confined
+// to — the session's workspace (see planAttachment's security note).
+app.post("/api/session/:id/attach", (req, res) => {
+    const record = openSessions.get(String(req.params.id));
+    if (!record)
+        return res.status(404).json({ error: "Session not found" });
+    const filePath = String(req.body?.path ?? req.body?.filePath ?? "").trim();
+    if (!filePath)
+        return res.status(400).json({ error: "Missing file path" });
+    const result = attachToChat(record, {
+        filePath,
+        caption: typeof req.body?.caption === "string" ? req.body.caption : undefined,
+        mimeType: typeof req.body?.mimeType === "string" ? req.body.mimeType : undefined,
+        name: typeof req.body?.name === "string" ? req.body.name : undefined,
+    });
+    if ("error" in result)
+        return res.status(400).json({ error: result.error });
+    const { hash, name, mimeType, size, kind } = result.ref;
+    res.json({ ok: true, hash, name, mimeType, size, kind });
+});
 app.post("/api/session/prompt", async (req, res, next) => {
     try {
         const text = String(req.body?.text ?? "").trim();

package/dist/session/attach-to-chat.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Plan an AGENT-sent chat attachment: the reverse of the composer paperclip.
+// An agent points at a file it produced in the workspace (a rendered chart, a
+// screenshot, a report), and Bivy surfaces it into the chat as an image/file
+// chip. This module is the PURE, testable half — path confinement, size cap, and
+// mime/kind classification — returning bytes + metadata (or a human-readable
+// error). The server half stores the bytes in the content-addressed
+// AttachmentStore, emits the live `attachment` event, and persists the outbound
+// reference for durable history.
+//
+// Security posture: the resolved file MUST live inside the session's working
+// directory. An agent is a semi-trusted process; without confinement, a prompt
+// injection could turn "attach a file to the chat" into "exfiltrate /etc/passwd
+// (or ~/.ssh/id_rsa) to the user's phone". Symlinks are resolved before the
+// check so a symlink inside the workspace can't point out of it.
+import fs from "node:fs";
+import path from "node:path";
+/** Ceiling for a single agent attachment. Kept comfortably under the relay's
+ *  32 MiB reassembly limit (see packages/core/src/wire-format.ts) so a large
+ *  attachment still travels to a phone over the encrypted relay in chunks. */
+export const MAX_AGENT_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+export function isAttachPlanError(value) {
+    return typeof value.error === "string";
+}
+const EXT_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".avif": "image/avif",
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".zip": "application/zip",
+};
+/** Sniff a mime type from the leading magic bytes for the common image/PDF
+ *  formats, so a mislabeled or extension-less file still classifies correctly.
+ *  Returns "" when nothing matches (caller falls back to extension/default). */
+export function sniffMime(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return "image/png";
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    if (bytes.length >= 6 && (bytes.subarray(0, 6).toString("latin1") === "GIF87a" || bytes.subarray(0, 6).toString("latin1") === "GIF89a"))
+        return "image/gif";
+    if (bytes.length >= 12 && bytes.subarray(0, 4).toString("latin1") === "RIFF" && bytes.subarray(8, 12).toString("latin1") === "WEBP")
+        return "image/webp";
+    if (bytes.length >= 5 && bytes.subarray(0, 5).toString("latin1") === "%PDF-")
+        return "application/pdf";
+    return "";
+}
+/** Strip directory components and control/path characters from a filename so it
+ *  is safe to show and to store as an attachment display name. */
+export function sanitizeAttachmentName(name) {
+    const base = path.basename(String(name || "").trim());
+    const cleaned = base
+        .replace(/[/\\]+/g, "_")
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f]+/g, "")
+        .trim();
+    return cleaned.slice(0, 200) || "attachment";
+}
+/**
+ * Resolve, confine, size-check, read, and classify a file the agent asked to
+ * attach. `filePath` may be absolute or relative to `workspaceDir`; either way
+ * the resolved real path must sit inside `workspaceDir`.
+ */
+export function planAttachment(opts) {
+    const raw = String(opts.filePath || "").trim();
+    if (!raw)
+        return { error: "No file path given." };
+    const workspaceDir = path.resolve(opts.workspaceDir);
+    const resolved = path.resolve(workspaceDir, raw);
+    // Confinement, symlink-safe: resolve the real path of the file before comparing
+    // against the real workspace root. realpathSync also fails cleanly for a missing
+    // file.
+    let realFile;
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync(workspaceDir);
+    }
+    catch {
+        return { error: "Workspace directory is unavailable." };
+    }
+    try {
+        realFile = fs.realpathSync(resolved);
+    }
+    catch {
+        return { error: `File not found: ${raw}` };
+    }
+    const rel = path.relative(realRoot, realFile);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+        return { error: "Refusing to attach a file outside the session workspace." };
+    }
+    let stat;
+    try {
+        stat = fs.statSync(realFile);
+    }
+    catch {
+        return { error: `File not found: ${raw}` };
+    }
+    if (stat.isDirectory())
+        return { error: `Not a file: ${raw}` };
+    const maxBytes = opts.maxBytes ?? MAX_AGENT_ATTACHMENT_BYTES;
+    if (stat.size > maxBytes) {
+        return { error: `File is too large to attach (${stat.size} bytes; limit ${maxBytes}).` };
+    }
+    if (stat.size === 0)
+        return { error: "Refusing to attach an empty file." };
+    let bytes;
+    try {
+        bytes = fs.readFileSync(realFile);
+    }
+    catch {
+        return { error: `Could not read file: ${raw}` };
+    }
+    const ext = path.extname(realFile).toLowerCase();
+    const mimeType = (opts.mimeType && String(opts.mimeType).trim()) ||
+        sniffMime(bytes) ||
+        EXT_MIME[ext] ||
+        "application/octet-stream";
+    const kind = mimeType.startsWith("image/") ? "image" : "file";
+    const name = sanitizeAttachmentName(opts.name || path.basename(realFile));
+    return { bytes, name, mimeType, kind };
+}

package/dist/session/event-log.js

@@ -28,6 +28,10 @@
 // interleaved in any order on disk; each replay reads only its own kind.
 import fs from "node:fs";
 import { normalizedIntermediateText, thinkingTextFromContent, mergeTranscript } from "./transcript-merge.js";
+/** Content-block type carried by a folded outbound attachment. MUST match
+ *  `AGENT_ATTACHMENT_BLOCK` in packages/core/src/store-render.ts — the client's
+ *  renderHistory keys on this exact string to render the chip. */
+const AGENT_ATTACHMENT_BLOCK = "bivy_attachment";
 function isOverlay(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -46,8 +50,19 @@ function isAttachment(value) {
     const record = value;
     return record.bivyKind === "attachment" && typeof record.text === "string" && Array.isArray(record.refs);
 }
+function isOutboundAttachment(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (record.bivyKind === "outbound-attachment" &&
+        typeof record.afterMessageCount === "number" &&
+        typeof record.id === "string" &&
+        !!record.ref &&
+        typeof record.ref === "object" &&
+        typeof record.ref.hash === "string");
+}
 function isRecord(value) {
-    return isOverlay(value) || isBase(value) || isAttachment(value);
+    return isOverlay(value) || isBase(value) || isAttachment(value) || isOutboundAttachment(value);
 }
 /**
  * Fold attachment records into a text→refs list: last write wins per text (a
@@ -132,7 +147,32 @@ export function replayExtras(entries) {
         else if (entry.bivyKind === "tool")
             tool.push(entry);
     }
-    return [...foldIntermediate(intermediate), ...foldTool(tool)];
+    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries)];
+}
+/**
+ * Fold the outbound (agent-sent) attachment records into time-anchored synthetic
+ * assistant messages `mergeTranscript` interleaves into the transcript. Last write
+ * wins per id (a re-emitted id updates in place, matching the log's coalescing),
+ * preserving first-seen order. Each becomes one `bivy_attachment` block the client
+ * renders as a chip/thumbnail.
+ */
+export function replayOutboundAttachments(entries) {
+    const byId = new Map();
+    for (const entry of entries) {
+        if (entry.bivyKind !== "outbound-attachment")
+            continue;
+        // set() on an existing key updates the value in place (Map keeps first-seen
+        // insertion order), so last write wins while position is stable. Final
+        // placement is by time in mergeTranscript regardless.
+        byId.set(entry.id, entry);
+    }
+    return [...byId.values()].map((entry) => ({
+        role: "assistant",
+        content: [{ type: AGENT_ATTACHMENT_BLOCK, ref: entry.ref, caption: entry.caption }],
+        afterMessageCount: entry.afterMessageCount,
+        createdAt: entry.createdAt,
+        id: entry.id,
+    }));
 }
 /**
  * Replay a session's base records into the base transcript: `reset` replaces the
@@ -286,6 +326,23 @@ export class EventLog {
     readAttachments(id) {
         return replayAttachments(this.entries(id));
     }
+    /**
+     * Record an agent-sent (outbound) attachment, anchored at the current base
+     * length so history replay interleaves it where it was emitted. Coalesces on
+     * the transcript-entry id so a re-emit of the same attachment updates in place.
+     */
+    appendOutboundAttachment(id, entry) {
+        this.load(id);
+        const record = {
+            bivyKind: "outbound-attachment",
+            createdAt: Date.now(),
+            afterMessageCount: entry.afterMessageCount,
+            id: entry.id,
+            ref: { ...entry.ref },
+            ...(entry.caption ? { caption: entry.caption } : {}),
+        };
+        this.enqueue(id, `oa:${entry.id}`, record);
+    }
     /** 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.3.0-staging.47",
+  "version": "0.3.0-staging.48",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",