@roamcode.ai/server 1.0.10 → 1.0.12

package/dist/start.js

@@ -6,16 +6,20 @@ import { join as join12 } from "path";
 import { existsSync as existsSync6 } from "fs";
 
 // src/transport.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import { basename as pathBasename } from "path";
+import { createReadStream } from "fs";
 import Fastify from "fastify";
 import websocket from "@fastify/websocket";
 import multipart from "@fastify/multipart";
 
 // src/fs-service.ts
-import { readdir, readFile, stat, realpath, open, mkdir, unlink } from "fs/promises";
+import { createWriteStream } from "fs";
+import { readdir, readFile, stat, realpath, open, mkdir, unlink, rename, rmdir } from "fs/promises";
 import { constants } from "fs";
 import { resolve, join, sep, basename } from "path";
+import { randomUUID } from "crypto";
+import { pipeline } from "stream/promises";
 var FsError = class extends Error {
   code;
   constructor(code, message) {
@@ -107,6 +111,14 @@ var FsService = class {
     const data = await readFile(real);
     return { filename: basename(file), data };
   }
+  /** Validate and describe a real in-root file without reading it into memory. */
+  async describeFile(target) {
+    const file = this.resolveWithinRoot(target);
+    const real = await this.realWithinRoot(file);
+    const info = await stat(real);
+    if (!info.isFile()) throw new FsError("not-found", `not a file: ${target}`);
+    return { path: real, filename: basename(file), size: info.size, mtimeMs: info.mtimeMs };
+  }
   /**
    * Validate that `target` is a real in-root file and describe it for an attachment frame WITHOUT
    * reading its bytes. Reuses the same resolveWithinRoot + realpath defense as readFileForDownload so
@@ -142,6 +154,95 @@ var FsService = class {
     }
     return { path: dest };
   }
+  /** Stream an upload to a same-directory partial and atomically publish it. The caller owns size limits;
+   *  this method guarantees an interrupted upload never leaves a visible half-file. */
+  async writeUploadedStream(targetDir, filename, input, beforeCommit) {
+    if (!filename || filename.includes("/") || filename.includes("\\") || filename.includes(sep)) {
+      throw new Error(`invalid upload filename (no path separators allowed): ${filename}`);
+    }
+    const dir = this.resolveWithinRoot(targetDir);
+    await this.realWithinRoot(dir);
+    const dest = this.resolveWithinRoot(join(dir, filename));
+    const partial = this.resolveWithinRoot(join(dir, `.upload-${randomUUID()}.partial`));
+    try {
+      await pipeline(
+        input,
+        createWriteStream(partial, { flags: "wx", mode: 384 })
+      );
+      if (beforeCommit && !beforeCommit()) throw new Error("upload stream rejected before commit");
+      await rename(partial, dest);
+      const info = await stat(dest);
+      return { path: dest, size: info.size };
+    } catch (err) {
+      await unlink(partial).catch(() => void 0);
+      throw err;
+    }
+  }
+  /** Atomically replace one existing in-root managed file with streamed bytes. */
+  async replaceFileStream(target, input, beforeCommit) {
+    const file = this.resolveWithinRoot(target);
+    const real = await this.realWithinRoot(file);
+    const parent = resolve(real, "..");
+    await this.realWithinRoot(parent);
+    const partial = join(parent, `.edit-${randomUUID()}.partial`);
+    try {
+      await pipeline(
+        input,
+        createWriteStream(partial, { flags: "wx", mode: 384 })
+      );
+      if (beforeCommit && !beforeCommit()) throw new Error("replacement stream rejected before commit");
+      await rename(partial, real);
+      const info = await stat(real);
+      return { path: real, size: info.size };
+    } catch (err) {
+      await unlink(partial).catch(() => void 0);
+      throw err;
+    }
+  }
+  /** Best-effort removal used only for server-owned managed attachment copies. */
+  async removeManagedPath(target) {
+    const file = this.resolveWithinRoot(target);
+    const real = await this.realWithinRoot(file);
+    await unlink(real);
+    await rmdir(resolve(real, "..")).catch(() => void 0);
+  }
+  /** Discover regular files in an app-owned directory for one-time legacy attachment backfill. Symlinks
+   *  are ignored and traversal is deliberately shallow: old uploads are direct children, current uploads
+   *  add exactly one id directory. */
+  async discoverManagedFiles(target, maxDepth = 1) {
+    let root;
+    try {
+      root = this.resolveWithinRoot(target);
+      await this.realWithinRoot(root);
+    } catch {
+      return [];
+    }
+    const found = [];
+    const walk = async (dir, depth) => {
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.isSymbolicLink() || entry.name.endsWith(".partial")) continue;
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (depth < maxDepth) await walk(path, depth + 1);
+          continue;
+        }
+        if (!entry.isFile()) continue;
+        try {
+          const info = await stat(path);
+          found.push({ path, filename: entry.name, size: info.size, mtimeMs: info.mtimeMs });
+        } catch {
+        }
+      }
+    };
+    await walk(root, 0);
+    return found;
+  }
   /** Ensure a directory (confined to root) exists, creating parents as needed; returns its absolute path. */
   async ensureDirWithinRoot(target) {
     const dir = this.resolveWithinRoot(target);
@@ -231,30 +332,35 @@ var FsService = class {
     let removed = 0;
     for (const e of entries) {
       if (!e.isDirectory()) continue;
-      removed += await this.pruneOlderThan(join(dir, e.name), maxAgeMs, now);
+      removed += await this.pruneOlderThan(join(dir, e.name), maxAgeMs, now, true);
     }
     return removed;
   }
   /** Delete top-level regular files in `target` (confined to root) whose mtime is older than `maxAgeMs`.
    *  Best-effort — returns how many were removed; a missing dir / unreadable entry is skipped, not thrown.
    *  Subdirectories are left untouched. Used to give terminal shared-files uploads a bounded lifetime. */
-  async pruneOlderThan(target, maxAgeMs, now = Date.now()) {
+  async pruneOlderThan(target, maxAgeMs, now = Date.now(), recursive = false) {
     let dir;
     try {
       dir = this.resolveWithinRoot(target);
     } catch {
       return 0;
     }
-    let names;
+    let entries;
     try {
-      names = await readdir(dir);
+      entries = await readdir(dir, { withFileTypes: true });
     } catch {
       return 0;
     }
     let removed = 0;
-    for (const name of names) {
-      const p = join(dir, name);
+    for (const entry of entries) {
+      const p = join(dir, entry.name);
       try {
+        if (recursive && entry.isDirectory()) {
+          removed += await this.pruneOlderThan(p, maxAgeMs, now, true);
+          await rmdir(p).catch(() => void 0);
+          continue;
+        }
         const s = await stat(p);
         if (s.isFile() && now - s.mtimeMs > maxAgeMs) {
           await unlink(p);
@@ -653,7 +759,7 @@ function terminalSharedDir(opts) {
 
 // src/updater.ts
 import { spawn as nodeSpawn } from "child_process";
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import {
   chmodSync as nodeChmodSync,
   existsSync as nodeExistsSync,
@@ -667,7 +773,7 @@ import { fileURLToPath } from "url";
 
 // src/managed-runtime.ts
 import { spawn } from "child_process";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import {
   chmodSync as chmodSync3,
   existsSync as existsSync4,
@@ -765,7 +871,7 @@ function readPreviousVersion(root) {
 }
 
 // src/updater.ts
-var RUNNING_VERSION = "1.0.10" ? "1.0.10".replace(/^v/, "") : packageVersion();
+var RUNNING_VERSION = "1.0.12" ? "1.0.12".replace(/^v/, "") : packageVersion();
 var RELEASES_API = "https://api.github.com/repos/burakgon/roamcode/releases?per_page=100";
 var RELEASE_MANIFEST_ASSET = "roamcode-release.json";
 var CHECK_CACHE_MS = 15 * 6e4;
@@ -1064,7 +1170,7 @@ var Updater = class {
     const path = join6(this.dataDir, "update-status.json");
     const value = JSON.stringify(status, null, 2) + "\n";
     if (this.fs.renameSync) {
-      const temp = `${path}.${process.pid}.${randomUUID2()}.tmp`;
+      const temp = `${path}.${process.pid}.${randomUUID3()}.tmp`;
       this.fs.writeFileSync(temp, value, 384);
       this.fs.renameSync(temp, path);
     } else {
@@ -1127,7 +1233,7 @@ var Updater = class {
         return { started: false, reason: error instanceof Error ? error.message : String(error) };
       }
     }
-    const operationId = randomUUID2();
+    const operationId = randomUUID3();
     const status = {
       operationId,
       state: "starting",
@@ -1811,6 +1917,25 @@ function brandSessionStore(store) {
   concreteSessionStores.add(store);
   return store;
 }
+function sessionFileRowToStored(row) {
+  return {
+    id: row.id,
+    sessionId: row.session_id,
+    direction: row.direction,
+    storage: row.storage,
+    name: row.name,
+    path: row.path,
+    mimeType: row.mime_type,
+    size: row.size,
+    kind: row.kind,
+    ...row.caption ? { caption: row.caption } : {},
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    expiresAt: row.expires_at,
+    ...row.derived_from_id ? { derivedFromId: row.derived_from_id } : {},
+    ...row.hidden_at !== null ? { hiddenAt: row.hidden_at } : {}
+  };
+}
 function parseSpawnArgs(raw) {
   if (typeof raw !== "string" || raw.length === 0) return void 0;
   try {
@@ -1919,6 +2044,9 @@ function cloneStoredSessionDefaults(value) {
     updatedAt: value.updatedAt
   };
 }
+function cloneStoredSessionFile(value) {
+  return { ...value };
+}
 function appSettingRowToSessionDefaults(row) {
   if (!row) return void 0;
   try {
@@ -1933,6 +2061,7 @@ function appSettingRowToSessionDefaults(row) {
 }
 function inMemoryStore() {
   const map = /* @__PURE__ */ new Map();
+  const files = /* @__PURE__ */ new Map();
   const provisionalProviderSessionIds = /* @__PURE__ */ new Map();
   let sessionDefaults;
   const write = (s) => {
@@ -2031,13 +2160,38 @@ function inMemoryStore() {
       };
       return cloneStoredSessionDefaults(sessionDefaults);
     },
+    putFile: (file) => files.set(`${file.sessionId}:${file.id}`, cloneStoredSessionFile(file)),
+    getFile: (sessionId, id) => {
+      const value = files.get(`${sessionId}:${id}`);
+      return value ? cloneStoredSessionFile(value) : void 0;
+    },
+    listFiles: (sessionId, includeHidden = false) => [...files.values()].filter((file) => file.sessionId === sessionId && (includeHidden || file.hiddenAt === void 0)).sort((a, b) => b.createdAt - a.createdAt || b.id.localeCompare(a.id)).map(cloneStoredSessionFile),
+    setFileHidden: (sessionId, id, hiddenAt) => {
+      const file = files.get(`${sessionId}:${id}`);
+      if (!file) return;
+      if (hiddenAt === void 0) delete file.hiddenAt;
+      else file.hiddenAt = hiddenAt;
+      file.updatedAt = Date.now();
+    },
+    deleteFile: (sessionId, id) => void files.delete(`${sessionId}:${id}`),
+    pruneFiles: (expiredBefore) => {
+      const removed = [];
+      for (const [key, file] of files) {
+        if (file.expiresAt > expiredBefore) continue;
+        removed.push(cloneStoredSessionFile(file));
+        files.delete(key);
+      }
+      return removed;
+    },
     delete: (id) => {
       provisionalProviderSessionIds.delete(id);
       map.delete(id);
+      for (const [key, file] of files) if (file.sessionId === id) files.delete(key);
     },
     close: () => {
       provisionalProviderSessionIds.clear();
       map.clear();
+      files.clear();
       sessionDefaults = void 0;
     },
     mode: "memory-fallback"
@@ -2115,6 +2269,28 @@ function openSessionStore(opts) {
       revision INTEGER NOT NULL CHECK (revision > 0),
       updated_at INTEGER NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS session_files (
+      id TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      direction TEXT NOT NULL CHECK (direction IN ('sent', 'received')),
+      storage TEXT NOT NULL CHECK (storage IN ('managed', 'workspace')),
+      name TEXT NOT NULL,
+      path TEXT NOT NULL,
+      mime_type TEXT NOT NULL,
+      size INTEGER NOT NULL,
+      kind TEXT NOT NULL CHECK (kind IN ('image', 'pdf', 'text', 'binary')),
+      caption TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      derived_from_id TEXT,
+      hidden_at INTEGER,
+      PRIMARY KEY (session_id, id)
+    );
+    CREATE INDEX IF NOT EXISTS session_files_session_created_idx
+      ON session_files(session_id, created_at DESC);
+    CREATE INDEX IF NOT EXISTS session_files_expiry_idx ON session_files(expires_at);
   `);
   try {
     db.exec("ALTER TABLE provider_sessions ADD COLUMN provisional_provider_session_id TEXT");
@@ -2194,6 +2370,33 @@ function openSessionStore(opts) {
     ON CONFLICT(key) DO UPDATE SET
       value_json=excluded.value_json, revision=excluded.revision, updated_at=excluded.updated_at
   `);
+  const filePutStmt = db.prepare(`
+    INSERT INTO session_files (
+      id, session_id, direction, storage, name, path, mime_type, size, kind, caption,
+      created_at, updated_at, expires_at, derived_from_id, hidden_at
+    ) VALUES (
+      @id, @session_id, @direction, @storage, @name, @path, @mime_type, @size, @kind, @caption,
+      @created_at, @updated_at, @expires_at, @derived_from_id, @hidden_at
+    ) ON CONFLICT(session_id, id) DO UPDATE SET
+      direction=excluded.direction, storage=excluded.storage, name=excluded.name, path=excluded.path,
+      mime_type=excluded.mime_type, size=excluded.size, kind=excluded.kind, caption=excluded.caption,
+      updated_at=excluded.updated_at, expires_at=excluded.expires_at,
+      derived_from_id=excluded.derived_from_id, hidden_at=excluded.hidden_at
+  `);
+  const fileGetStmt = db.prepare("SELECT * FROM session_files WHERE session_id = ? AND id = ?");
+  const fileListStmt = db.prepare(
+    "SELECT * FROM session_files WHERE session_id = ? AND hidden_at IS NULL ORDER BY created_at DESC, id DESC"
+  );
+  const fileListAllStmt = db.prepare(
+    "SELECT * FROM session_files WHERE session_id = ? ORDER BY created_at DESC, id DESC"
+  );
+  const fileHideStmt = db.prepare(
+    "UPDATE session_files SET hidden_at = ?, updated_at = ? WHERE session_id = ? AND id = ?"
+  );
+  const fileDeleteStmt = db.prepare("DELETE FROM session_files WHERE session_id = ? AND id = ?");
+  const filesForSessionDeleteStmt = db.prepare("DELETE FROM session_files WHERE session_id = ?");
+  const expiredFilesStmt = db.prepare("SELECT * FROM session_files WHERE expires_at <= ?");
+  const pruneFilesStmt = db.prepare("DELETE FROM session_files WHERE expires_at <= ?");
   const ownerOf = (id) => {
     const hasLegacy = legacyGetStmt.get(id) !== void 0;
     const hasProvider = providerGetStmt.get(id) !== void 0;
@@ -2370,10 +2573,45 @@ function openSessionStore(opts) {
     },
     getSessionDefaults: () => appSettingRowToSessionDefaults(sessionDefaultsGetStmt.get()),
     putSessionDefaults: (defaults, expectedRevision, updatedAt) => putSessionDefaultsAtomically.immediate(normalizeSessionDefaults(defaults), expectedRevision, updatedAt),
+    putFile: (file) => {
+      filePutStmt.run({
+        id: file.id,
+        session_id: file.sessionId,
+        direction: file.direction,
+        storage: file.storage,
+        name: file.name,
+        path: file.path,
+        mime_type: file.mimeType,
+        size: file.size,
+        kind: file.kind,
+        caption: file.caption ?? null,
+        created_at: file.createdAt,
+        updated_at: file.updatedAt,
+        expires_at: file.expiresAt,
+        derived_from_id: file.derivedFromId ?? null,
+        hidden_at: file.hiddenAt ?? null
+      });
+    },
+    getFile: (sessionId, id) => {
+      const row = fileGetStmt.get(sessionId, id);
+      return row ? sessionFileRowToStored(row) : void 0;
+    },
+    listFiles: (sessionId, includeHidden = false) => {
+      const rows = includeHidden ? fileListAllStmt.all(sessionId) : fileListStmt.all(sessionId);
+      return rows.map(sessionFileRowToStored);
+    },
+    setFileHidden: (sessionId, id, hiddenAt) => fileHideStmt.run(hiddenAt ?? null, Date.now(), sessionId, id),
+    deleteFile: (sessionId, id) => void fileDeleteStmt.run(sessionId, id),
+    pruneFiles: (expiredBefore) => {
+      const rows = expiredFilesStmt.all(expiredBefore);
+      pruneFilesStmt.run(expiredBefore);
+      return rows.map(sessionFileRowToStored);
+    },
     delete: (id) => {
       const owner = ownerOf(id);
       if (owner === "claude") legacyDeleteStmt.run(id);
       else if (owner === "codex") providerDeleteStmt.run(id);
+      filesForSessionDeleteStmt.run(id);
     },
     close: () => db.close(),
     mode: "sqlite"
@@ -4004,6 +4242,92 @@ var MAX_PENDING_TERMINAL_INPUT_FRAMES = 64;
 var MAX_PENDING_TERMINAL_INPUT_BYTES = 1e6;
 var MAX_TERMINAL_WS_BUFFER = 16e6;
 var TERMINAL_WS_PING_MS = 25e3;
+var TEXT_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "txt",
+  "md",
+  "markdown",
+  "json",
+  "jsonl",
+  "yaml",
+  "yml",
+  "toml",
+  "xml",
+  "csv",
+  "tsv",
+  "log",
+  "js",
+  "jsx",
+  "ts",
+  "tsx",
+  "css",
+  "scss",
+  "html",
+  "htm",
+  "sql",
+  "sh",
+  "bash",
+  "zsh",
+  "py",
+  "rb",
+  "go",
+  "rs",
+  "java",
+  "kt",
+  "swift",
+  "c",
+  "h",
+  "cpp",
+  "hpp",
+  "env",
+  "ini",
+  "conf"
+]);
+var IMAGE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "svg",
+  "bmp",
+  "avif",
+  "apng",
+  "heic",
+  "heif"
+]);
+var FILE_HISTORY_BACKFILL_BUDGET_MS = 150;
+var FILE_HISTORY_AVAILABILITY_BUDGET_MS = 150;
+function completionWithin(task, timeoutMs) {
+  return new Promise((resolve7) => {
+    let settled = false;
+    const finish = (completed) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve7(completed);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    void task.then(
+      () => finish(true),
+      () => finish(false)
+    );
+  });
+}
+function attachmentMedia(filename, declared = "application/octet-stream") {
+  const ext = filename.includes(".") ? filename.slice(filename.lastIndexOf(".") + 1).toLowerCase() : "";
+  if (declared.startsWith("image/") || IMAGE_FILE_EXTENSIONS.has(ext)) {
+    const inferred = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : ext === "svg" ? "image/svg+xml" : ext ? `image/${ext}` : declared;
+    return { mimeType: declared.startsWith("image/") ? declared : inferred, kind: "image" };
+  }
+  if (declared === "application/pdf" || ext === "pdf") return { mimeType: "application/pdf", kind: "pdf" };
+  if (declared.startsWith("text/") || TEXT_FILE_EXTENSIONS.has(ext)) {
+    return { mimeType: "text/plain; charset=utf-8", kind: "text" };
+  }
+  return { mimeType: declared || "application/octet-stream", kind: "binary" };
+}
+function publicSessionFile(file, available = true) {
+  return { ...file, isImage: file.kind === "image", available };
+}
 function isDisallowedPushHost(hostname) {
   const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
   if (host === "localhost" || host.endsWith(".localhost")) return true;
@@ -4059,8 +4383,69 @@ function createServer(config, deps = {}) {
   });
   const fsService = new FsService({ root: config.fsRoot });
   const terminalSharedRoot = terminalSharedBase({ dataDir: config.dataDir, fsRoot: config.fsRoot });
+  const backfilledFileSessions = /* @__PURE__ */ new Set();
+  const fileBackfillsInFlight = /* @__PURE__ */ new Map();
+  const backfillManagedFiles = (sessionId) => {
+    if (backfilledFileSessions.has(sessionId)) return Promise.resolve();
+    const existing = fileBackfillsInFlight.get(sessionId);
+    if (existing) return existing;
+    const task = (async () => {
+      const sessionDir = terminalSharedDir({ dataDir: config.dataDir, fsRoot: config.fsRoot, sessionId });
+      const discovered = await fsService.discoverManagedFiles(sessionDir);
+      const knownPaths = new Set(store.listFiles(sessionId, true).map((file) => file.path));
+      for (const file of discovered) {
+        if (knownPaths.has(file.path)) continue;
+        const expiresAt = file.mtimeMs + TERMINAL_FILE_TTL_MS;
+        if (expiresAt <= Date.now()) continue;
+        const now = Date.now();
+        const media = attachmentMedia(file.filename);
+        store.putFile({
+          id: randomUUID4(),
+          sessionId,
+          direction: "sent",
+          storage: "managed",
+          name: file.filename,
+          path: file.path,
+          mimeType: media.mimeType,
+          size: file.size,
+          kind: media.kind,
+          createdAt: file.mtimeMs,
+          updatedAt: now,
+          expiresAt
+        });
+        knownPaths.add(file.path);
+      }
+      backfilledFileSessions.add(sessionId);
+    })();
+    fileBackfillsInFlight.set(sessionId, task);
+    void task.catch(() => void 0).finally(() => fileBackfillsInFlight.delete(sessionId));
+    return task;
+  };
+  const fileAvailableWithinBudget = async (file) => {
+    if (file.expiresAt <= Date.now()) return false;
+    return new Promise((resolve7) => {
+      let settled = false;
+      const finish = (available) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve7(available);
+      };
+      const timer = setTimeout(() => finish(true), FILE_HISTORY_AVAILABILITY_BUDGET_MS);
+      void fsService.describeFile(file.path).then(
+        () => finish(true),
+        () => finish(false)
+      );
+    });
+  };
   const sweepSharedFiles = () => {
-    void fsService.pruneChildDirsOlderThan(terminalSharedRoot, TERMINAL_FILE_TTL_MS).catch(() => 0);
+    void (async () => {
+      const expired = typeof store.pruneFiles === "function" ? store.pruneFiles(Date.now()) : [];
+      await Promise.all(
+        expired.filter((file) => file.storage === "managed").map((file) => fsService.removeManagedPath(file.path).catch(() => void 0))
+      );
+      await fsService.pruneChildDirsOlderThan(terminalSharedRoot, TERMINAL_FILE_TTL_MS).catch(() => 0);
+    })();
   };
   sweepSharedFiles();
   const sharedSweepTimer = setInterval(sweepSharedFiles, TERMINAL_SWEEP_INTERVAL_MS);
@@ -4305,7 +4690,7 @@ function createServer(config, deps = {}) {
       reply.code(400).send({ error: `cwd does not exist: ${body.cwd}` });
       return;
     }
-    const id = randomUUID3();
+    const id = randomUUID4();
     const rawOptions = body.options ?? (provider === "claude" ? {
       ...typeof body.model === "string" ? { model: body.model } : {},
       ...typeof body.effort === "string" ? { effort: body.effort } : {},
@@ -4529,8 +4914,10 @@ function createServer(config, deps = {}) {
       }
       const caption = typeof body.caption === "string" ? body.caption : void 0;
       let described;
+      let fileInfo;
       try {
         described = await fsService.describeForAttachment(body.path);
+        fileInfo = await fsService.describeFile(body.path);
       } catch (err) {
         if (err instanceof FsError) {
           reply.code(err.code === "forbidden" ? 403 : 404).send({ error: err.message });
@@ -4540,14 +4927,28 @@ function createServer(config, deps = {}) {
         return;
       }
       const isImage = body.kind === "image" ? true : body.kind === "file" ? false : described.isImage;
-      const id = randomUUID3();
-      terminalManager.pushControl(sessionId, {
-        t: "attach",
+      const id = randomUUID4();
+      const now = Date.now();
+      const media = attachmentMedia(described.name);
+      const stored = {
         id,
-        path: body.path,
+        sessionId,
+        direction: "received",
+        storage: "workspace",
         name: described.name,
-        caption,
-        isImage
+        path: body.path,
+        mimeType: media.mimeType,
+        size: fileInfo.size,
+        kind: isImage ? "image" : media.kind,
+        ...caption ? { caption } : {},
+        createdAt: now,
+        updatedAt: now,
+        expiresAt: now + TERMINAL_FILE_TTL_MS
+      };
+      store.putFile(stored);
+      terminalManager.pushControl(sessionId, {
+        t: "attach",
+        ...publicSessionFile(stored)
       });
       dispatchPush({ kind: "file", sessionId, detail: described.name });
       reply.code(200).send({ ok: true, id });
@@ -5078,23 +5479,126 @@ function createServer(config, deps = {}) {
       reply.code(400).send({ error: err.message });
     }
   });
+  app.get("/sessions/:id/files", async (request, reply) => {
+    if (!terminalManager.get(request.params.id)) {
+      reply.code(404).send({ error: "terminal session not found" });
+      return;
+    }
+    await completionWithin(backfillManagedFiles(request.params.id), FILE_HISTORY_BACKFILL_BUDGET_MS);
+    const files = await Promise.all(
+      store.listFiles(request.params.id).map(async (file) => {
+        const available = await fileAvailableWithinBudget(file);
+        return publicSessionFile(file, available);
+      })
+    );
+    return {
+      files,
+      policy: {
+        maxUploadBytes: config.maxUploadBytes,
+        retentionMs: TERMINAL_FILE_TTL_MS,
+        durable: store.mode === "sqlite"
+      }
+    };
+  });
+  app.get(
+    "/sessions/:id/files/:fileId/content",
+    async (request, reply) => {
+      const file = store.getFile(request.params.id, request.params.fileId);
+      if (!file || file.hiddenAt !== void 0) {
+        reply.code(404).send({ error: "file not found" });
+        return;
+      }
+      if (file.expiresAt <= Date.now()) {
+        reply.code(410).send({ error: "file has expired" });
+        return;
+      }
+      try {
+        const info = await fsService.describeFile(file.path);
+        const disposition = request.query.disposition === "inline" ? "inline" : "attachment";
+        reply.header("accept-ranges", "bytes").header("content-type", file.mimeType).header("x-content-type-options", "nosniff").header(
+          "content-security-policy",
+          "sandbox; default-src 'none'; img-src 'self' data: blob:; style-src 'unsafe-inline'"
+        ).header("content-disposition", contentDisposition(info.filename, disposition));
+        const range = request.headers.range;
+        if (range) {
+          const match = /^bytes=(\d+)-(\d*)$/.exec(range);
+          if (!match) {
+            reply.code(416).header("content-range", `bytes */${info.size}`).send();
+            return;
+          }
+          const start = Number(match[1]);
+          const end = match[2] ? Math.min(Number(match[2]), info.size - 1) : info.size - 1;
+          if (!Number.isSafeInteger(start) || start < 0 || start > end || start >= info.size) {
+            reply.code(416).header("content-range", `bytes */${info.size}`).send();
+            return;
+          }
+          return reply.code(206).header("content-range", `bytes ${start}-${end}/${info.size}`).header("content-length", String(end - start + 1)).send(createReadStream(info.path, { start, end }));
+        }
+        return reply.header("content-length", String(info.size)).send(createReadStream(info.path));
+      } catch (err) {
+        const code = err instanceof FsError && err.code === "forbidden" ? 403 : 404;
+        reply.code(code).send({ error: err.message });
+      }
+    }
+  );
   app.post("/sessions/:id/upload", async (request, reply) => {
-    const meta = terminalManager.get(request.params.id);
-    if (!meta) {
+    const sessionId = request.params.id;
+    if (!terminalManager.get(sessionId)) {
       reply.code(404).send({ error: "terminal session not found" });
       return;
     }
-    let dir;
+    let data;
+    try {
+      data = await request.file();
+    } catch (err) {
+      reply.code(400).send({ error: err.message });
+      return;
+    }
+    if (!data) {
+      reply.code(400).send({ error: "no file field in the upload" });
+      return;
+    }
+    const id = randomUUID4();
     try {
-      dir = await fsService.ensureDirWithinRoot(
-        terminalSharedDir({ dataDir: config.dataDir, fsRoot: config.fsRoot, sessionId: meta.id })
+      const dir = await fsService.ensureDirWithinRoot(
+        `${terminalSharedDir({ dataDir: config.dataDir, fsRoot: config.fsRoot, sessionId })}/${id}`
       );
+      const written = await fsService.writeUploadedStream(dir, data.filename, data.file, () => !data.file.truncated);
+      const now = Date.now();
+      const media = attachmentMedia(data.filename, data.mimetype);
+      const stored = {
+        id,
+        sessionId,
+        direction: "sent",
+        storage: "managed",
+        name: data.filename,
+        path: written.path,
+        mimeType: media.mimeType,
+        size: written.size,
+        kind: media.kind,
+        createdAt: now,
+        updatedAt: now,
+        expiresAt: now + TERMINAL_FILE_TTL_MS
+      };
+      store.putFile(stored);
+      terminalManager.pushControl(sessionId, { t: "file", op: "added", file: publicSessionFile(stored) });
+      reply.code(201).send({ path: stored.path, file: publicSessionFile(stored) });
     } catch (err) {
-      const code = err instanceof FsError && err.code === "forbidden" ? 403 : 400;
-      reply.code(code).send({ error: err.message });
+      reply.code(data.file.truncated ? 413 : 400).send({
+        error: data.file.truncated ? "file exceeds the upload size limit" : err.message
+      });
+    }
+  });
+  app.post("/sessions/:id/files/:fileId/derive", async (request, reply) => {
+    const source = store.getFile(request.params.id, request.params.fileId);
+    if (!source || source.hiddenAt !== void 0 || source.kind !== "image") {
+      reply.code(404).send({ error: "source image not found" });
+      return;
+    }
+    if (source.expiresAt <= Date.now()) {
+      reply.code(410).send({ error: "source image has expired" });
       return;
     }
-    await fsService.pruneOlderThan(dir, TERMINAL_FILE_TTL_MS).catch(() => 0);
     let data;
     try {
       data = await request.file();
@@ -5102,28 +5606,134 @@ function createServer(config, deps = {}) {
       reply.code(400).send({ error: err.message });
       return;
     }
-    if (!data) {
-      reply.code(400).send({ error: "no file field in the upload" });
+    if (!data || !data.mimetype.startsWith("image/")) {
+      reply.code(400).send({ error: "an edited image is required" });
       return;
     }
-    let buffer;
+    const id = randomUUID4();
     try {
-      buffer = await data.toBuffer();
+      const dir = await fsService.ensureDirWithinRoot(
+        `${terminalSharedDir({ dataDir: config.dataDir, fsRoot: config.fsRoot, sessionId: source.sessionId })}/${id}`
+      );
+      const written = await fsService.writeUploadedStream(dir, data.filename, data.file, () => !data.file.truncated);
+      const now = Date.now();
+      const media = attachmentMedia(data.filename, data.mimetype);
+      const stored = {
+        id,
+        sessionId: source.sessionId,
+        direction: "sent",
+        storage: "managed",
+        name: data.filename,
+        path: written.path,
+        mimeType: media.mimeType,
+        size: written.size,
+        kind: "image",
+        createdAt: now,
+        updatedAt: now,
+        expiresAt: now + TERMINAL_FILE_TTL_MS,
+        derivedFromId: source.id
+      };
+      store.putFile(stored);
+      terminalManager.pushControl(source.sessionId, { t: "file", op: "added", file: publicSessionFile(stored) });
+      reply.code(201).send({ path: stored.path, file: publicSessionFile(stored) });
     } catch (err) {
-      reply.code(413).send({ error: err.message });
+      reply.code(data.file.truncated ? 413 : 400).send({
+        error: data.file.truncated ? "file exceeds the upload size limit" : err.message
+      });
+    }
+  });
+  app.put("/sessions/:id/files/:fileId/content", async (request, reply) => {
+    const file = store.getFile(request.params.id, request.params.fileId);
+    if (!file || file.hiddenAt !== void 0) {
+      reply.code(404).send({ error: "file not found" });
       return;
     }
-    if (data.file.truncated) {
-      reply.code(413).send({ error: "file exceeds the upload size limit" });
+    if (file.expiresAt <= Date.now()) {
+      reply.code(410).send({ error: "file has expired" });
+      return;
+    }
+    if (file.direction !== "sent" || file.storage !== "managed" || file.kind !== "image") {
+      reply.code(409).send({ error: "only managed sent images can be replaced" });
       return;
     }
+    let data;
     try {
-      const written = await fsService.writeUploadedFile(dir, data.filename, buffer);
-      reply.code(201).send({ path: written.path });
+      data = await request.file();
     } catch (err) {
       reply.code(400).send({ error: err.message });
+      return;
+    }
+    if (!data || !data.mimetype.startsWith("image/")) {
+      reply.code(400).send({ error: "an image file is required" });
+      return;
+    }
+    try {
+      const written = await fsService.replaceFileStream(file.path, data.file, () => !data.file.truncated);
+      const now = Date.now();
+      const updated = {
+        ...file,
+        mimeType: data.mimetype,
+        size: written.size,
+        updatedAt: now,
+        expiresAt: now + TERMINAL_FILE_TTL_MS
+      };
+      store.putFile(updated);
+      terminalManager.pushControl(file.sessionId, { t: "file", op: "updated", file: publicSessionFile(updated) });
+      reply.send({ file: publicSessionFile(updated) });
+    } catch (err) {
+      reply.code(data.file.truncated ? 413 : 400).send({
+        error: data.file.truncated ? "file exceeds the upload size limit" : err.message
+      });
     }
   });
+  app.patch(
+    "/sessions/:id/files/:fileId",
+    async (request, reply) => {
+      const file = store.getFile(request.params.id, request.params.fileId);
+      if (!file) {
+        reply.code(404).send({ error: "file not found" });
+        return;
+      }
+      store.setFileHidden(file.sessionId, file.id, request.body?.hidden === false ? void 0 : Date.now());
+      terminalManager.pushControl(file.sessionId, {
+        t: "file",
+        op: request.body?.hidden === false ? "restored" : "hidden",
+        id: file.id
+      });
+      reply.code(204).send();
+    }
+  );
+  app.delete(
+    "/sessions/:id/files/:fileId",
+    async (request, reply) => {
+      const file = store.getFile(request.params.id, request.params.fileId);
+      if (!file) {
+        reply.code(204).send();
+        return;
+      }
+      if (request.query.content === "true") {
+        if (file.direction !== "sent" || file.storage !== "managed") {
+          reply.code(409).send({ error: "workspace files cannot be deleted by RoamCode" });
+          return;
+        }
+        try {
+          await fsService.removeManagedPath(file.path);
+        } catch (err) {
+          if (!(err instanceof FsError && err.code === "not-found")) {
+            reply.code(err instanceof FsError && err.code === "forbidden" ? 403 : 500).send({
+              error: "managed file could not be deleted"
+            });
+            return;
+          }
+        }
+        store.deleteFile(file.sessionId, file.id);
+      } else {
+        store.setFileHidden(file.sessionId, file.id, Date.now());
+      }
+      terminalManager.pushControl(file.sessionId, { t: "file", op: "removed", id: file.id });
+      reply.code(204).send();
+    }
+  );
   if (deps.webDir) registerStatic(app, { webDir: deps.webDir });
   app.addHook("onClose", async () => {
     clearInterval(sharedSweepTimer);
@@ -5154,10 +5764,10 @@ function createServer(config, deps = {}) {
   });
   return { app, authGate, terminalManager, terminalAvailable };
 }
-function contentDisposition(filename) {
+function contentDisposition(filename, disposition = "attachment") {
   const ascii = filename.replace(/[\x00-\x1f\x7f"\\]/g, "_");
   const encoded = encodeURIComponent(filename);
-  return `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+  return `${disposition}; filename="${ascii}"; filename*=UTF-8''${encoded}`;
 }
 
 // src/server-config.ts
@@ -5540,7 +6150,7 @@ function createUsageService(opts) {
 
 // src/claude-auth-service.ts
 import { spawn as nodeSpawn2 } from "child_process";
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 function parseAuthStatus(stdout) {
   try {
     const o = JSON.parse(stdout);
@@ -5617,7 +6227,7 @@ var ClaudeAuthService = class {
         reject(err instanceof Error ? err : new Error("failed to spawn claude"));
         return;
       }
-      const id = randomUUID4();
+      const id = randomUUID5();
       let settled = false;
       let buf = "";
       const onData = (d) => {
@@ -6979,7 +7589,7 @@ var CodexMetadataService = class {
 
 // src/providers/claude-metadata-service.ts
 import { execFile as nodeExecFile2, spawn as nodeSpawn3 } from "child_process";
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 import { StringDecoder } from "string_decoder";
 var SAFE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:/\u005b\u005d-]*$/;
 var MAX_MODELS = 64;
@@ -7187,7 +7797,7 @@ function createClaudeMetadataRunner(options) {
           reject(metadataUnavailable2());
           return;
         }
-        const requestId = `roamcode-models-${randomUUID5()}`;
+        const requestId = `roamcode-models-${randomUUID6()}`;
         const decoder = new StringDecoder("utf8");
         let stdoutBuffer = "";
         let outputBytes = 0;