@bivy/bivy 0.3.0-staging.46 → 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/repo-workspace.js

@@ -29,15 +29,60 @@ export function parseGitHubRemote(input) {
         return parseRepo(`${ssh[1]}/${ssh[2]}`);
     return undefined;
 }
-/** Infer owner/repo from a workspace's origin remote, if it is a GitHub checkout. */
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * A git failure that DEFINITIVELY means "this workspace is not a GitHub-connected
+ * checkout" — a genuine `undefined` answer — as opposed to a transient failure we
+ * must not mistake for one. `git remote get-url origin` reports "not a git
+ * repository" (no repo) or "No such remote" (a repo with no origin); both are
+ * real, stable answers. Anything else (notably `index.lock`/`config.lock`
+ * contention when many sessions touch the same shared clone at once) is transient.
+ */
+function isDefinitiveNonGitHubError(error) {
+    const e = error;
+    const text = `${e?.stderr ?? ""} ${e?.message ?? String(error)}`;
+    return /not a git repository|No such remote|does not appear to be a git repository/i.test(text);
+}
+/**
+ * Infer owner/repo from a workspace's origin remote, if it is a GitHub checkout.
+ *
+ * Retries transient git failures before giving up. Misclassifying a momentarily
+ * busy GitHub checkout as "not a repo" is what let a session skip worktree
+ * isolation and run directly in the shared clone root, where its `git
+ * checkout`/`git stash` collided with a concurrent session (the "sessions
+ * mixing" bug). So: a DEFINITIVE non-GitHub result (not a repo / no origin)
+ * resolves to `undefined` as before, but a transient error is retried and then
+ * THROWN — the caller must fail loudly rather than silently degrade to running
+ * the agent in the shared root.
+ */
 export async function inferGitHubRepoFromWorkspace(workspace) {
-    try {
-        const { stdout } = await exec("git", ["-C", workspace, "remote", "get-url", "origin"], { cwd: workspace });
-        return parseGitHubRemote(stdout);
-    }
-    catch {
-        return undefined;
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const { stdout } = await exec("git", ["-C", workspace, "remote", "get-url", "origin"], { cwd: workspace });
+            return parseGitHubRemote(stdout);
+        }
+        catch (error) {
+            if (isDefinitiveNonGitHubError(error))
+                return undefined;
+            lastError = error;
+            if (attempt < 2)
+                await delay(50 * (attempt + 1));
+        }
     }
+    throw new Error(`Could not determine the GitHub repo for ${workspace} (the checkout may be busy): ` +
+        `${lastError?.message ?? String(lastError)}`);
+}
+/**
+ * True when `dir` is a Bivy-managed shared clone root — a direct child of the
+ * repos root, i.e. `<reposRoot>/owner__repo` (see `cloneOrUpdateRepo`). Every
+ * session for a repo shares that one checkout, so an agent must NEVER run
+ * directly in it; it runs in a per-session worktree instead. Worktree paths live
+ * DEEPER (`<clone>/.bivy/worktrees/<slug>`) and are intentionally not matched, so
+ * this cleanly distinguishes "the shared root" from "an isolated worktree".
+ */
+export function isSharedCloneRoot(dir, reposRoot) {
+    return path.resolve(path.dirname(path.resolve(dir))) === path.resolve(reposRoot);
 }
 /** A GitHub token from env or the local `gh` login, or undefined (public only). */
 export async function resolveGitHubToken(env = process.env) {

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

@@ -47,7 +47,7 @@ import { createCheckpointBundle, applyCheckpointBundle, materializeCheckpoint }
 import { PolicyEngine } from "./policy/policy-engine.js";
 import { TerminalManager } from "./terminal.js";
 import { listMultiplexerSessions, attachCommand } from "./multiplexer.js";
-import { createWorktree, removeWorktree, branchSlug } from "./worktree.js";
+import { createWorktree, removeWorktree, branchSlug, gitRepoRoot } from "./worktree.js";
 import { HarnessManager } from "./harness/manager.js";
 import { startEgressProxyIfEnabled } from "./harness/egress.js";
 import { initSharedDepCache, sharedDepCacheRoot } from "./harness/dep-cache.js";
@@ -55,7 +55,7 @@ import { evictToCap, dirSizeBytes } from "./harness/cache-evict.js";
 import { checkDiskAdmission } from "./harness/disk-admission.js";
 import { sandboxTier, setConfiguredSandboxTier, normalizeSandboxTier } from "./harness/sandbox.js";
 import { injectMcpProxyForSession } from "./harness/mcp-inject.js";
-import { parseRepo, inferGitHubRepoFromWorkspace, resolveGitHubToken, cloneOrUpdateRepo, resolveDefaultBaseRef, resolveBranchBaseRef, fetchOrigin } from "./repo-workspace.js";
+import { parseRepo, inferGitHubRepoFromWorkspace, isSharedCloneRoot, resolveGitHubToken, cloneOrUpdateRepo, resolveDefaultBaseRef, resolveBranchBaseRef, fetchOrigin } from "./repo-workspace.js";
 import { configureGitAuth, writeGitCredentialEndpoint } from "./git-auth.js";
 import { GitHubTaskPoller, resolveGitHubTaskConfig, buildTaskPrompt, buildResumePrompt, buildInteractiveResumePrompt, DEFAULT_ISSUE_INSTRUCTIONS, parseBivyDirectives, commitAll, pushBranch, mergeBaseIntoBranch, completeMerge, abortMerge, findOpenPullRequestForBranch, findPullRequestsForBranch, findMergedPullRequestForBranch, issueBranchName, getPullRequest, commentIssue, listOpenLabelledIssues, selectActionableIssues, getIssue, getIssueCommentBody, addLabel, removeLabel, announcePickup, } from "./github-tasks.js";
 import { buildLinearTaskPrompt, getLinearIssue, linearBranchName } from "./linear-tasks.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;
 }
@@ -5525,6 +5560,22 @@ async function standUpFork(opts) {
         cwd = wt.path;
         worktree = wt;
     }
+    else {
+        // Non-repo-backed source. The fork would otherwise reuse the PARENT's cwd,
+        // putting two sessions in one working tree — so when that cwd is itself a git
+        // checkout (a local repo without a GitHub origin), cut the fork its own
+        // worktree on a fresh branch. Best-effort: a non-git workspace has no tree to
+        // isolate, so the fork keeps the fallback cwd (no git collisions possible).
+        const forkRepoRoot = await gitRepoRoot(cwd);
+        if (forkRepoRoot) {
+            const forkBranch = `bivy/fork-${randomBytes(6).toString("hex")}`;
+            const wt = await createWorktree({ repoDir: forkRepoRoot, id: forkBranch, branch: forkBranch });
+            applyDirtyPatch(wt.path, bundle.dirtyPatch);
+            workspace = forkRepoRoot;
+            cwd = wt.path;
+            worktree = wt;
+        }
+    }
     // Materialise the transcript, then stand the session up — resume the imported
     // transcript (full) or a fresh session the caller seeds with plan.seedPrompt.
     const plan = await materializeFork({ bundle, targetRuntime, ctx: { workspace, cwd }, seed: { transcriptUrl: opts.transcriptUrl } });
@@ -7164,9 +7215,52 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
         if (!admission.allowed)
             throw new Error(`Not enough disk to start a new worktree session: ${admission.reason}`);
         const wtOpts = typeof opts.worktree === "object" ? opts.worktree : {};
-        worktree = await createWorktree({ repoDir: workspace, id: wtOpts.branch ?? `session-${Date.now()}`, branch: wtOpts.branch, base: wtOpts.base });
+        // A random suffix, never a timestamp: two sessions started in the same
+        // millisecond would otherwise resolve to the same slug → same worktree path
+        // and branch, and `createWorktree` would ADOPT the first's worktree, dropping
+        // the second session into a directory another session already owns.
+        worktree = await createWorktree({ repoDir: workspace, id: wtOpts.branch ?? `session-${randomBytes(6).toString("hex")}`, branch: wtOpts.branch, base: wtOpts.base });
         runtimeWorkspace = worktree.path;
     }
+    // Resume with a reaped worktree. When a repo-backed session is resumed but its
+    // worktree directory was removed while it was closed (disk cleanup, a manual
+    // rm, `git worktree remove`), restoredWorktree is undefined and we'd otherwise
+    // fall back to the shared clone root — which the invariant below then rejects.
+    // Re-provision a fresh worktree on the SAME branch instead (branches survive
+    // `git worktree remove`, so the agent's committed history is intact), restoring
+    // isolation so the resumed session is usable again. Best-effort: if the clone
+    // or branch is gone, we leave it to the invariant to fail safe rather than
+    // corrupt a neighbour. The clone root is reconstructed from `source`
+    // (`repo:owner/repo`) because stored `workspace` is the old worktree path.
+    if (requestedSessionFile && !worktree && storedMeta?.worktree && storedMeta?.branch) {
+        const parsedSource = parseRepoSource(storedMeta.source);
+        if (parsedSource) {
+            const repoDir = path.join(reposRoot, `${parsedSource.owner}__${parsedSource.repo}`);
+            try {
+                // Clear any stale registration left by a dir that was rm'd out from under
+                // git, so re-adding the branch's worktree doesn't hit "already checked out".
+                runGit(["worktree", "prune"], repoDir);
+                const reprovisioned = await createWorktree({ repoDir, id: storedMeta.branch, branch: storedMeta.branch });
+                worktree = reprovisioned;
+                runtimeWorkspace = reprovisioned.path;
+            }
+            catch (error) {
+                console.warn(`Could not re-provision worktree for resumed session on ${storedMeta.branch}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    // Isolation invariant. A session must NEVER run directly in a Bivy-managed
+    // shared clone root (`<reposRoot>/owner__repo`): every session for that repo
+    // shares that one checkout, so an agent running there collides with concurrent
+    // sessions on `git checkout`/`git stash` — exactly the "sessions mixing" bug.
+    // A GitHub-backed session is supposed to get its own worktree; reaching here
+    // without one means an earlier step degraded (e.g. a transient repo-inference
+    // failure, or a resume whose worktree was reaped). Fail loudly instead of
+    // silently sharing the tree and corrupting a neighbouring session's work.
+    if (!worktree && isSharedCloneRoot(runtimeWorkspace, reposRoot)) {
+        throw new Error(`Refusing to start a session in the shared clone root ${runtimeWorkspace} without an isolated worktree — ` +
+            `this would collide with concurrent sessions on the same repo. Retry; if it persists the checkout may be busy.`);
+    }
     const runtimeSessionOptions = { workspace: runtimeWorkspace, toolProvider: integrations.toolProvider(), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
     // Stage 2/3: prefer re-attaching to a still-live remote session — routed to its
     // OWN agent service — over re-opening a fresh copy from disk. Falls back to
@@ -7194,8 +7288,12 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
     if (requestedSessionFile && storedMeta?.name && !session.getName())
         session.setName(storedMeta.name);
     const sessionWorkspace = session.cwd || runtimeWorkspace;
-    const inferredRepo = opts.source || storedMeta?.source ? undefined : await inferGitHubRepoFromWorkspace(sessionWorkspace);
-    if (!worktree && requestedSessionFile && inferredRepo) {
+    // Best-effort here (unlike createWorkspaceSession, which must fail loudly):
+    // this only decides whether to ADOPT an already-checked-out branch as the
+    // session's worktree label, so a transient inference failure should quietly
+    // skip adoption rather than break resuming the session.
+    const inferredRepo = opts.source || storedMeta?.source ? undefined : await inferGitHubRepoFromWorkspace(sessionWorkspace).catch(() => undefined);
+    if (!worktree && requestedSessionFile && inferredRepo && !isSharedCloneRoot(sessionWorkspace, reposRoot)) {
         const branch = runGit(["branch", "--show-current"], sessionWorkspace) || runGit(["rev-parse", "--short", "HEAD"], sessionWorkspace) || undefined;
         if (branch) {
             const mainWorktree = runGit(["worktree", "list", "--porcelain"], sessionWorkspace)?.split("\n").find((line) => line.startsWith("worktree "))?.slice("worktree ".length);
@@ -9460,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.46",
+  "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.",