@saadnvd1/agent-os 0.3.672 → 0.3.673

package/components/Chat/composer/paste.ts

@@ -8,7 +8,8 @@ export interface PasteHandlers {
   plain: boolean;
   // Cmd/Ctrl+Shift+V was pressed just before this paste.
   asText: boolean;
-  onImages: (files: File[]) => void;
+  // Files pasted: images, documents, anything the composer may attach.
+  onFiles: (files: File[]) => void;
   onLongPaste: (text: string, language?: string) => void;
 }
 
@@ -58,9 +59,9 @@ export function handlePaste(
 ): boolean {
   const data = event.clipboardData;
   if (!data) return false;
-  const images = [...data.files].filter(isImage);
-  if (images.length) {
-    h.onImages(images);
+  const files = [...data.files];
+  if (files.length) {
+    h.onFiles(files);
     return true;
   }
   const text = data.getData("text/plain").replace(/\r\n?/g, "\n");

package/components/Chat/composer/useAttachFiles.ts

@@ -0,0 +1,142 @@
+"use client";
+
+import { useRef, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+import {
+  clientConfigQuery,
+  useClientConfig,
+} from "@/data/client-config/queries";
+import {
+  acceptAttr,
+  tooBigMessage,
+  typeFor,
+  unsupportedMessage,
+} from "@/lib/attachments/policy";
+import type { ChatFile, ChatImage } from "@/lib/chat/events";
+import { uploadFile } from "@/lib/file-upload";
+import { isImage } from "./paste";
+
+export interface Upload {
+  key: string;
+  file: ChatFile;
+  uploading?: boolean;
+}
+
+function readImage(file: File): Promise<ChatImage> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const [meta, data] = String(reader.result).split(",");
+      resolve({ mediaType: meta.slice(5, meta.indexOf(";")), data });
+    };
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+  });
+}
+
+const carriesFiles = (e: React.DragEvent) =>
+  [...e.dataTransfer.types].includes("Files");
+
+let seq = 0;
+
+// Files picked, pasted or dropped onto the composer, and the outline shown
+// while something is dragged over it. Images are read in and sent with the
+// message; any other file is uploaded to the session's attachments folder
+// at once, so a wrong type or a too-big file fails here, not at send. The
+// types and sizes come from the server (/api/client-config).
+export function useAttachFiles({
+  scope,
+  imageCount,
+  onImages,
+}: {
+  // The session's id, or "draft" for a chat that hasn't started.
+  scope: string;
+  imageCount: number;
+  onImages: (images: ChatImage[]) => void;
+}) {
+  const queryClient = useQueryClient();
+  const types = useClientConfig().data?.attachments.types;
+  const [dragging, setDragging] = useState(false);
+  const [uploads, setUploads] = useState<Upload[]>([]);
+  const held = useRef(0);
+  held.current = imageCount + uploads.length;
+
+  const addFiles = async (picked: Iterable<File>) => {
+    // Copied first: a file input's live list is emptied right after the pick.
+    const list = [...picked];
+    let limits;
+    try {
+      limits = (await queryClient.fetchQuery(clientConfigQuery)).attachments;
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Couldn't attach");
+      return;
+    }
+    const images: File[] = [];
+    const others: File[] = [];
+    for (const f of list) {
+      let error: string | null = null;
+      if (held.current + images.length + others.length >= limits.max)
+        error = `You can attach up to ${limits.max} files to one message.`;
+      else if (isImage(f)) {
+        if (f.size > limits.maxImageBytes)
+          error = tooBigMessage(f.name, f.size, limits.maxImageBytes);
+        else images.push(f);
+      } else if (!typeFor(f.name, limits.types))
+        error = unsupportedMessage(f.name);
+      else if (f.size > limits.maxBytes)
+        error = tooBigMessage(f.name, f.size, limits.maxBytes);
+      else others.push(f);
+      if (error) toast.error(error);
+    }
+    if (images.length) onImages(await Promise.all(images.map(readImage)));
+    for (const f of others) {
+      const key = `up-${++seq}`;
+      const file = { path: "", name: f.name, size: f.size, mediaType: f.type };
+      setUploads((prev) => [...prev, { key, file, uploading: true }]);
+      const done = await uploadFile(f, scope);
+      if (done.ok)
+        setUploads((prev) =>
+          prev.map((u) => (u.key === key ? { key, file: done.file } : u))
+        );
+      else {
+        setUploads((prev) => prev.filter((u) => u.key !== key));
+        toast.error(done.error);
+      }
+    }
+  };
+
+  const dropProps = {
+    onDragOver: (e: React.DragEvent) => {
+      if (!carriesFiles(e)) return;
+      e.preventDefault();
+      e.dataTransfer.dropEffect = "copy";
+      setDragging(true);
+    },
+    onDragLeave: (e: React.DragEvent) => {
+      if (!e.currentTarget.contains(e.relatedTarget as Node | null))
+        setDragging(false);
+    },
+    onDrop: (e: React.DragEvent) => {
+      if (!carriesFiles(e)) return;
+      e.preventDefault();
+      setDragging(false);
+      void addFiles(e.dataTransfer.files);
+    },
+  };
+
+  return {
+    dragging,
+    dropProps,
+    addFiles,
+    uploads,
+    // Until the limits are read, the picker offers images only.
+    accept: types ? `image/*,${acceptAttr(types)}` : "image/*",
+    uploading: uploads.some((u) => u.uploading),
+    remove: (key: string) =>
+      setUploads((prev) => prev.filter((u) => u.key !== key)),
+    clear: () => setUploads([]),
+    restore: (files: ChatFile[]) =>
+      setUploads(files.map((file) => ({ key: `up-${++seq}`, file }))),
+  };
+}

package/components/Chat/composer/useComposerEditor.ts

@@ -13,7 +13,7 @@ import { docToMarkdown } from "@/lib/chat/markdown/serialize";
 import { plainExtensions, richExtensions } from "./extensions";
 import { loadMarkdown } from "./load";
 import { handleKeyDown, type KeyHandlers } from "./keys";
-import { handlePaste, isImage, type PasteHandlers } from "./paste";
+import { handlePaste, type PasteHandlers } from "./paste";
 import { usePlainMode } from "./usePlainMode";
 
 export type ComposerHandlers = Omit<
@@ -120,9 +120,9 @@ export function useComposerEditor({
             asText,
           });
         },
-        // Dropped images are the composer's to take, not the document's.
+        // Dropped files are the composer's to take, not the document's.
         handleDrop: (view, event) =>
-          [...(event.dataTransfer?.files ?? [])].some(isImage),
+          (event.dataTransfer?.files.length ?? 0) > 0,
       },
       // Only edits change the text: not loading a draft, not setEditable.
       onUpdate: ({ editor: ed, transaction }) => {

package/components/Chat/useDraft.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useRef } from "react";
-import type { ChatImage } from "@/lib/chat/events";
+import type { ChatFile, ChatImage } from "@/lib/chat/events";
 import type { TextAttachment } from "@/lib/chat/paste";
 
 // `text` is the composer's markdown, so a reload restores its formatting.
@@ -9,6 +9,8 @@ interface Draft {
   text: string;
   images: ChatImage[];
   files?: TextAttachment[];
+  // Attached files, saved on the server: references only.
+  uploads?: ChatFile[];
 }
 
 const keyFor = (id: string) => `agentos:draft:${id}`;
@@ -39,7 +41,12 @@ export function useSaveDraft(id: string | undefined, draft: Draft): void {
     clearTimeout(timer.current);
     timer.current = setTimeout(() => {
       const key = keyFor(id);
-      if (!draft.text.trim() && !draft.images.length && !draft.files?.length) {
+      if (
+        !draft.text.trim() &&
+        !draft.images.length &&
+        !draft.files?.length &&
+        !draft.uploads?.length
+      ) {
         localStorage.removeItem(key);
         return;
       }

package/components/Draft/DraftPanel.tsx

@@ -5,7 +5,7 @@ import { useSnapshot } from "valtio";
 import { toast } from "sonner";
 import { Composer } from "@/components/Chat/Composer";
 import { Button } from "@/components/ui/button";
-import type { ChatImage } from "@/lib/chat/events";
+import type { ChatFile, ChatImage } from "@/lib/chat/events";
 import type { Project } from "@/lib/db";
 import { draftComposerKey, type Draft } from "@/lib/drafts";
 import { getModelOptions } from "@/lib/model-catalog";
@@ -57,11 +57,12 @@ export function DraftPanel({
       </div>
     );
 
-  const send = async (text: string, images: ChatImage[]) => {
+  const send = async (text: string, images: ChatImage[], files: ChatFile[]) => {
     try {
       if (draft.openPr) {
         if (!project) throw new Error("Pick a project for a task");
-        if (images.length) throw new Error("A task takes text only");
+        if (images.length || files.length)
+          throw new Error("A task takes text only");
         const { session, queued } = await createTask.mutateAsync({
           projectId: project.id,
           prompt: text,
@@ -96,6 +97,7 @@ export function DraftPanel({
         baseBranch: draft.baseBranch,
         prompt: text,
         images: images.length ? images : undefined,
+        files: files.length ? files : undefined,
       });
       // A resend whose first answer was lost: the terminal still needs its
       // first prompt, and this is the text that was sent.
@@ -134,6 +136,7 @@ export function DraftPanel({
         />
         <Composer
           draftKey={draftComposerKey(draft.id)}
+          attachScope="draft"
           running={false}
           disabled={pending}
           placeholder={
@@ -143,7 +146,7 @@ export function DraftPanel({
                 ? "Describe the task"
                 : `Message ${project?.name ?? "a new chat"}`
           }
-          onSend={(text, images) => void send(text, images)}
+          onSend={(text, images, files) => void send(text, images, files)}
           onStop={() => {}}
           models={getModelOptions(draft.agentType)}
           model={draft.model}

package/components/Terminal/index.tsx

@@ -19,7 +19,8 @@ import { useTerminalConnection, useTerminalSearch } from "./hooks";
 import type { TerminalScrollState } from "./hooks";
 import { useViewport } from "@/hooks/useViewport";
 import { useFileDrop } from "@/hooks/useFileDrop";
-import { uploadFileToTemp } from "@/lib/file-upload";
+import { toast } from "sonner";
+import { uploadFile } from "@/lib/file-upload";
 import { FilePicker } from "@/components/FilePicker";
 import type { AttachSpec } from "@/lib/hosts/attach";
 
@@ -121,11 +122,11 @@ export const Terminal = forwardRef<TerminalHandle, TerminalProps>(
       async (file: File) => {
         setIsUploading(true);
         try {
-          const path = await uploadFileToTemp(file);
-          if (path) {
-            sendInput(path);
+          const done = await uploadFile(file);
+          if (done.ok) {
+            sendInput(done.file.path);
             focus();
-          }
+          } else toast.error(done.error);
         } catch (err) {
           console.error("Failed to upload file:", err);
         } finally {

package/data/chat/useChat.ts

@@ -9,6 +9,7 @@ import type {
   ChatAccess,
   ChatCommand,
   ChatContext,
+  ChatFile,
   ChatImage,
   ChatItem,
   ChatModel,
@@ -34,12 +35,13 @@ import { usePending } from "./usePending";
 
 // A pending send as the socket's `send`, under its own id.
 const sendFrame = (
-  p: Pick<PendingSend, "id" | "text" | "images" | "compact">
+  p: Pick<PendingSend, "id" | "text" | "images" | "files" | "compact">
 ) =>
   JSON.stringify({
     type: "send",
     text: p.text,
     images: p.images,
+    files: p.files,
     clientId: p.id,
     ...(p.compact && { compact: true }),
   });
@@ -400,8 +402,13 @@ export function useChat(
   const send = useCallback(
     // `compact`: the reader let a stale chat compact first (lib/chat/stale).
     // It shows as a pending bubble at once, until it's in the chat.
-    (text: string, images?: ChatImage[], compact?: boolean) => {
-      const p = { id: clientId(), text, images, compact };
+    (
+      text: string,
+      images?: ChatImage[],
+      compact?: boolean,
+      files?: ChatFile[]
+    ) => {
+      const p = { id: clientId(), text, images, files, compact };
       pend({ type: "add", send: p, now: Date.now() });
       const ws = wsRef.current;
       if (ws?.readyState !== WebSocket.OPEN) {

package/data/client-config/queries.ts

@@ -0,0 +1,18 @@
+import { queryOptions, useQuery } from "@tanstack/react-query";
+import type { ClientConfig } from "@/lib/config/client-config-types";
+
+export const clientConfigKeys = { all: ["client-config"] as const };
+
+// What the server says clients render with and are limited by; it only
+// changes with a server release, so one read per page load.
+export const clientConfigQuery = queryOptions({
+  queryKey: clientConfigKeys.all,
+  queryFn: async (): Promise<ClientConfig> => {
+    const res = await fetch("/api/client-config");
+    if (!res.ok) throw new Error("Couldn't read the server's limits");
+    return res.json();
+  },
+  staleTime: Infinity,
+});
+
+export const useClientConfig = () => useQuery(clientConfigQuery);

package/data/sessions/queries.ts

@@ -1,7 +1,7 @@
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
 import type { Session, Group } from "@/lib/db";
 import type { AgentType } from "@/lib/providers";
-import type { ChatAccess, ChatImage } from "@/lib/chat/events";
+import type { ChatAccess, ChatFile, ChatImage } from "@/lib/chat/events";
 import { sessionKeys } from "./keys";
 import { usePollWhenOffline, usePushConnected } from "../push/connection";
 
@@ -192,6 +192,7 @@ export interface LaunchSessionInput {
   baseBranch: string | null;
   prompt: string;
   images?: ChatImage[];
+  files?: ChatFile[];
 }
 
 interface LaunchSessionResponse {

package/lib/attachments/check.ts

@@ -0,0 +1,50 @@
+import { isText, sniff } from "../intake/sniff";
+import {
+  ATTACHMENT_LIMITS,
+  tooBigMessage,
+  typeFor,
+  unsupportedMessage,
+  type AttachmentType,
+} from "./policy";
+
+export type UploadCheck =
+  | { ok: true; type: AttachmentType }
+  | { ok: false; status: 400 | 413 | 415; error: string };
+
+const ZIP = [0x50, 0x4b, 0x03, 0x04];
+const OLE = [0xd0, 0xcf, 0x11, 0xe0];
+const OOXML_ZIP = new Set(["xlsx", "docx", "pptx", "ods", "odt"]);
+const OLE_EXTS = new Set(["xls", "doc"]);
+
+const starts = (b: Buffer, sig: number[]) => sig.every((v, i) => b[i] === v);
+
+const bad = (name: string): UploadCheck => ({
+  ok: false,
+  status: 400,
+  error: `${name} doesn't look like a real .${name.split(".").pop()?.toLowerCase()} file.`,
+});
+
+/** Whether a file's name, size and bytes are something a chat accepts. */
+export function checkUpload(name: string, data: Buffer): UploadCheck {
+  const type = typeFor(name);
+  if (!type) return { ok: false, status: 415, error: unsupportedMessage(name) };
+  const limit =
+    type.kind === "image"
+      ? ATTACHMENT_LIMITS.maxImageBytes
+      : ATTACHMENT_LIMITS.maxBytes;
+  if (data.length > limit)
+    return {
+      ok: false,
+      status: 413,
+      error: tooBigMessage(name, data.length, limit),
+    };
+  if (!data.length)
+    return { ok: false, status: 400, error: `${name} is empty.` };
+  let real: boolean;
+  if (type.kind === "image" || type.kind === "pdf")
+    real = sniff(data, name)?.mediaType === type.mediaType;
+  else if (OOXML_ZIP.has(type.ext)) real = starts(data, ZIP);
+  else if (OLE_EXTS.has(type.ext)) real = starts(data, OLE);
+  else real = isText(data);
+  return real ? { ok: true, type } : bad(name);
+}

package/lib/attachments/message.ts

@@ -0,0 +1,49 @@
+import fs from "fs";
+import { ATTACHMENT_LIMITS, formatBytes } from "./policy";
+import type { ChatFile } from "./types";
+
+/**
+ * What the agent reads: the message plus where each file is. Every driver
+ * gets this, so any agent can open the files with its own tools (a
+ * spreadsheet through a script, a docx through pandoc). The chat keeps the
+ * plain text and shows the files as chips.
+ */
+export function agentText(text: string, files?: ChatFile[]): string {
+  if (!files?.length) return text;
+  const list = files
+    .map((f) => `- ${f.path} (${f.mediaType}, ${formatBytes(f.size)})`)
+    .join("\n");
+  return [
+    text,
+    `Attached files, saved on this machine. Open them with your own tools:\n${list}`,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+/** Claude reads a PDF itself, as a document block, when it's small enough. */
+export function documentBlocks(files?: ChatFile[]) {
+  const out: {
+    type: "document";
+    title: string;
+    source: { type: "base64"; media_type: "application/pdf"; data: string };
+  }[] = [];
+  for (const f of files ?? []) {
+    if (f.mediaType !== "application/pdf") continue;
+    if (f.size > ATTACHMENT_LIMITS.pdfInlineBytes) continue;
+    try {
+      out.push({
+        type: "document",
+        title: f.name,
+        source: {
+          type: "base64",
+          media_type: "application/pdf",
+          data: fs.readFileSync(f.path).toString("base64"),
+        },
+      });
+    } catch {
+      // Unreadable: the agent still has the path.
+    }
+  }
+  return out;
+}

package/lib/attachments/policy.ts

@@ -0,0 +1,116 @@
+// What a chat may carry besides typed text, and how big. The server owns it:
+// the upload route enforces it and /api/client-config hands it to clients, so
+// no client keeps its own copy. No Node imports: the browser reads this too.
+
+export type AttachmentKind = "image" | "pdf" | "sheet" | "doc" | "text";
+
+export interface AttachmentType {
+  ext: string;
+  mediaType: string;
+  kind: AttachmentKind;
+}
+
+const t = (
+  kind: AttachmentKind,
+  mediaType: string,
+  ...exts: string[]
+): AttachmentType[] => exts.map((ext) => ({ ext, mediaType, kind }));
+
+const OOXML = "application/vnd.openxmlformats-officedocument";
+
+export const ATTACHMENT_TYPES: AttachmentType[] = [
+  ...t("image", "image/png", "png"),
+  ...t("image", "image/jpeg", "jpg", "jpeg"),
+  ...t("image", "image/gif", "gif"),
+  ...t("image", "image/webp", "webp"),
+  ...t("pdf", "application/pdf", "pdf"),
+  ...t("sheet", `${OOXML}.spreadsheetml.sheet`, "xlsx"),
+  ...t("sheet", "application/vnd.ms-excel", "xls"),
+  ...t("sheet", "text/csv", "csv"),
+  ...t("sheet", "text/tab-separated-values", "tsv"),
+  ...t("sheet", "application/vnd.oasis.opendocument.spreadsheet", "ods"),
+  ...t("doc", `${OOXML}.wordprocessingml.document`, "docx"),
+  ...t("doc", "application/msword", "doc"),
+  ...t("doc", `${OOXML}.presentationml.presentation`, "pptx"),
+  ...t("doc", "application/vnd.oasis.opendocument.text", "odt"),
+  ...t("doc", "application/rtf", "rtf"),
+  ...t("text", "text/plain", "txt", "log", "env"),
+  ...t("text", "text/markdown", "md", "markdown"),
+  ...t("text", "application/json", "json", "jsonl", "ipynb"),
+  ...t(
+    "text",
+    "text/plain",
+    "yaml",
+    "yml",
+    "toml",
+    "xml",
+    "html",
+    "css",
+    "sql",
+    "ts",
+    "tsx",
+    "js",
+    "jsx",
+    "mjs",
+    "cjs",
+    "py",
+    "rb",
+    "go",
+    "rs",
+    "java",
+    "kt",
+    "swift",
+    "c",
+    "h",
+    "cpp",
+    "hpp",
+    "cs",
+    "php",
+    "diff",
+    "patch"
+  ),
+];
+
+export const ATTACHMENT_LIMITS = {
+  // Files and images on one message.
+  max: 8,
+  // One non-image file.
+  maxBytes: 25_000_000,
+  // One image, under the 5 MB a model accepts once base64'd.
+  maxImageBytes: 3_750_000,
+  // A PDF up to this goes to Claude as a document block; bigger ones, and
+  // every other file, are opened by the agent from their path.
+  pdfInlineBytes: 10_000_000,
+  types: ATTACHMENT_TYPES,
+};
+
+export type AttachmentLimits = typeof ATTACHMENT_LIMITS;
+
+const BY_EXT = new Map(ATTACHMENT_TYPES.map((x) => [x.ext, x]));
+
+export const extOf = (name: string): string =>
+  /\.([A-Za-z0-9]+)$/.exec(name)?.[1].toLowerCase() ?? "";
+
+export const typeFor = (
+  name: string,
+  types: AttachmentType[] = ATTACHMENT_TYPES
+): AttachmentType | null =>
+  types === ATTACHMENT_TYPES
+    ? (BY_EXT.get(extOf(name)) ?? null)
+    : (types.find((x) => x.ext === extOf(name)) ?? null);
+
+// For <input accept>: every extension, so the picker greys out the rest.
+export const acceptAttr = (types: AttachmentType[] = ATTACHMENT_TYPES) =>
+  types.map((x) => `.${x.ext}`).join(",");
+
+export const formatBytes = (n: number): string =>
+  n >= 1_000_000
+    ? `${(n / 1_000_000).toFixed(1)} MB`
+    : `${Math.max(1, Math.round(n / 1000))} KB`;
+
+// What a person is told when a file can't be attached.
+export const unsupportedMessage = (name: string): string =>
+  `${name}: this file type can't be attached. Supported: PDF, spreadsheets (xlsx, xls, csv), Word (docx), text, markdown, JSON, code and images.`;
+
+export const tooBigMessage = (name: string, size: number, limit: number) =>
+  `${name} is ${formatBytes(size)}; the limit is ${formatBytes(limit)}.`;

package/lib/attachments/store.ts

@@ -0,0 +1,92 @@
+import fs from "fs";
+import path from "path";
+import { dataRoot } from "../db/path";
+import { ATTACHMENT_LIMITS, typeFor } from "./policy";
+import type { ChatFile } from "./types";
+
+// Outside every repo and worktree, so an agent's `git add -A` never picks a
+// file up; a folder per session, `new` for a draft that has no session yet.
+export const attachmentsRoot = () => path.join(dataRoot(), "attachments");
+
+const segment = (s: string) => s.replace(/[^\w-]/g, "_");
+
+/** A client's filename as one safe path segment, unique among `taken`. */
+export function safeName(name: string, taken: Set<string>, n: number): string {
+  let base = path.basename(name.replace(/\\/g, "/"));
+  base = base
+    .replace(/[^a-zA-Z0-9.-]/g, "_")
+    .replace(/^\.+/, "")
+    .slice(0, 80);
+  if (!base) base = `file-${n}`;
+  let out = base;
+  for (let i = 2; taken.has(out); i++) {
+    const dot = base.lastIndexOf(".");
+    out =
+      dot > 0 ? `${base.slice(0, dot)}-${i}${base.slice(dot)}` : `${base}-${i}`;
+  }
+  taken.add(out);
+  return out;
+}
+
+export function scopeDir(scope: string): string {
+  return path.join(attachmentsRoot(), segment(scope) || "new");
+}
+
+export function saveAttachment(
+  scope: string,
+  name: string,
+  data: Buffer,
+  mediaType: string
+): ChatFile {
+  const dir = scopeDir(scope);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const taken = new Set(fs.readdirSync(dir));
+  const file = safeName(name, taken, taken.size + 1);
+  const full = path.join(dir, file);
+  fs.writeFileSync(full, data, { mode: 0o600 });
+  return { path: full, name: file, size: data.length, mediaType };
+}
+
+function inside(root: string, p: string): boolean {
+  const rel = path.relative(root, p);
+  return !!rel && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * The files a client says it attached, kept only where they really are a
+ * file inside the attachments folder (symlinks followed): a client can name
+ * any path, and the agent is told to open what's named here. Size and type
+ * come from the disk, not the client.
+ */
+export function resolveFiles(raw: unknown): ChatFile[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  let root: string;
+  try {
+    root = fs.realpathSync(attachmentsRoot());
+  } catch {
+    return undefined;
+  }
+  const out: ChatFile[] = [];
+  for (const f of raw.slice(0, ATTACHMENT_LIMITS.max)) {
+    const p = (f as { path?: unknown } | null)?.path;
+    if (typeof p !== "string") continue;
+    try {
+      const real = fs.realpathSync(p);
+      const stat = fs.statSync(real);
+      if (!inside(root, real) || !stat.isFile()) continue;
+      out.push({
+        path: real,
+        name: path.basename(real),
+        size: stat.size,
+        mediaType: typeFor(real)?.mediaType ?? "application/octet-stream",
+      });
+    } catch {
+      // Gone or unreadable: dropped.
+    }
+  }
+  return out.length ? out : undefined;
+}
+
+export function removeSessionAttachments(sessionId: string): Promise<void> {
+  return fs.promises.rm(scopeDir(sessionId), { recursive: true, force: true });
+}