@saadnvd1/agent-os 0.3.671 → 0.3.673

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 });
+}

package/lib/attachments/types.ts

@@ -0,0 +1,8 @@
+// A file saved on this machine and attached to a message by reference: the
+// message carries these, never the bytes.
+export interface ChatFile {
+  path: string;
+  name: string;
+  size: number;
+  mediaType: string;
+}

package/lib/chat/client-send.ts

@@ -1,25 +1,29 @@
-import type { ChatImage } from "./events";
+import { resolveFiles } from "../attachments/store";
+import type { ChatFile, ChatImage } from "./events";
 import type { CompactFirst } from "./stale";
 
-// What a browser's send may carry: its text and images, and whether the
+// What a browser's send may carry: its text, images and files, and whether the
 // reader chose to compact a stale chat first. Who a message is from (`from`,
 // `peer`, `origin`) is set by the server alone, never by a client. Its own
 // id for the message is kept only in a shape no server id takes.
 export function clientSend(msg: unknown): {
   text: string;
   images?: ChatImage[];
+  files?: ChatFile[];
   compact?: CompactFirst;
   id?: string;
 } {
   const m = (msg ?? {}) as {
     text?: unknown;
     images?: unknown;
+    files?: unknown;
     compact?: unknown;
     clientId?: unknown;
   };
   return {
     text: typeof m.text === "string" ? m.text : "",
     images: Array.isArray(m.images) ? (m.images as ChatImage[]) : undefined,
+    files: resolveFiles(m.files),
     ...(m.compact === true && { compact: "yes" as const }),
     ...(isClientId(m.clientId) && { id: m.clientId }),
   };

package/lib/chat/driver.ts

@@ -6,6 +6,7 @@ import type {
   ApprovalDecision,
   ChatAccess,
   ChatCommand,
+  ChatFile,
   ChatImage,
   ChatItem,
   ChatModel,
@@ -88,7 +89,9 @@ export interface ChatConversation {
   send(
     text: string,
     images?: ChatImage[],
-    options?: { now?: boolean }
+    // `files`: saved attachments; their paths are already in `text`, and a
+    // driver may also hand some to the model directly.
+    options?: { now?: boolean; files?: ChatFile[] }
   ): string | undefined;
   // A command the driver answers itself, without starting a turn (/mcp):
   // the items to show, or null to send the text as a message.

package/lib/chat/drivers/claude.ts

@@ -1,3 +1,4 @@
+import { documentBlocks } from "../../attachments/message";
 import { sessionBaseEnv } from "../../agents/server-env";
 import { randomUUID } from "crypto";
 import {
@@ -320,6 +321,7 @@ export const claudeDriver: ChatDriver = {
               data: img.data,
             },
           })),
+          ...documentBlocks(sendOptions?.files),
           { type: "text" as const, text },
         ];
         const checkpoint = randomUUID();

package/lib/chat/events.ts

@@ -1,5 +1,8 @@
 import type { CallUsage } from "../usage/types";
 import type { SearchResult } from "./find";
+import type { ChatFile } from "../attachments/types";
+
+export type { ChatFile };
 
 /**
  * The provider-neutral shape of a chat conversation. Every driver (Claude
@@ -152,6 +155,8 @@ export type ChatItem =
       kind: "user";
       text: string;
       images?: ChatImage[];
+      // Saved in the session's attachments folder, by reference.
+      files?: ChatFile[];
       // Who sent it through the agent bus, when not typed here.
       from?: string;
       // Sent by another agent session: shown as its body, while the agent
@@ -282,6 +287,7 @@ export interface QueuedMessage {
   id: string;
   text: string;
   imageCount?: number;
+  fileCount?: number;
   createdAt: number;
 }
 
@@ -413,7 +419,13 @@ export type ChatServerMessage =
 // What a browser sends.
 export type ChatClientMessage =
   // `clientId` (`user-c-…`) becomes the message's id: a resend is a no-op.
-  | { type: "send"; text: string; images?: ChatImage[]; clientId?: string }
+  | {
+      type: "send";
+      text: string;
+      images?: ChatImage[];
+      files?: ChatFile[];
+      clientId?: string;
+    }
   | { type: "queue_edit"; id: string; text: string }
   | { type: "queue_move"; id: string; by: -1 | 1 }
   | { type: "queue_delete"; id: string }

package/lib/chat/pending.ts

@@ -1,4 +1,4 @@
-import type { ChatImage, ChatState } from "./events";
+import type { ChatFile, ChatImage, ChatState } from "./events";
 
 // A message the composer sent that isn't in the chat or its queue yet. It
 // shows as a bubble at once, and stays (as failed, with Retry) if it never
@@ -7,6 +7,7 @@ export interface PendingSend {
   id: string;
   text: string;
   images?: ChatImage[];
+  files?: ChatFile[];
   compact?: boolean;
   // "sending": not taken in yet. "accepted": the server has it and is
   // starting the agent.

package/lib/chat/queued.ts

@@ -1,6 +1,6 @@
 import { db } from "../db";
 import { HELD_SQL } from "./hold";
-import type { ChatImage, QueuedMessage, SentBy } from "./events";
+import type { ChatFile, ChatImage, QueuedMessage, SentBy } from "./events";
 
 // Messages written while a turn runs, kept in SQLite so a reload or a
 // restart never loses them. The worker sends them in order when the turn
@@ -15,6 +15,7 @@ interface Row {
   id: string;
   text: string;
   images: string | null;
+  files: string | null;
   sent_by: string | null;
   created_at: number;
 }
@@ -25,19 +26,21 @@ export function listQueue(sessionId: string): QueuedMessage[] {
   return (
     db
       .prepare(
-        `SELECT id, text, image_count, created_at
+        `SELECT id, text, image_count, files, created_at
          FROM chat_queue WHERE session_id = ? ORDER BY position, created_at`
       )
       .all(sessionId) as {
       id: string;
       text: string;
       image_count: number;
+      files: string | null;
       created_at: number;
     }[]
   ).map((r) => ({
     id: r.id,
     text: r.text,
     imageCount: r.image_count || undefined,
+    fileCount: r.files ? (JSON.parse(r.files) as unknown[]).length : undefined,
     createdAt: r.created_at,
   }));
 }
@@ -45,7 +48,12 @@ export function listQueue(sessionId: string): QueuedMessage[] {
 // At the back. A retried send with the same id is only queued once.
 export function enqueue(
   sessionId: string,
-  m: { id: string; text: string; images?: ChatImage[] } & SentBy
+  m: {
+    id: string;
+    text: string;
+    images?: ChatImage[];
+    files?: ChatFile[];
+  } & SentBy
 ): void {
   const images = m.images?.length ? JSON.stringify(m.images) : null;
   const sentBy: SentBy = { from: m.from, peer: m.peer, origin: m.origin };
@@ -59,8 +67,8 @@ export function enqueue(
   if (n >= MAX_QUEUED)
     throw new Error(`The queue is full (${MAX_QUEUED} messages)`);
   db.prepare(
-    `INSERT OR IGNORE INTO chat_queue (id, session_id, position, text, images, image_count, sent_by, created_at)
-     VALUES (?, ?, (SELECT COALESCE(MAX(position), 0) + 1 FROM chat_queue WHERE session_id = ?), ?, ?, ?, ?, ?)`
+    `INSERT OR IGNORE INTO chat_queue (id, session_id, position, text, images, image_count, files, sent_by, created_at)
+     VALUES (?, ?, (SELECT COALESCE(MAX(position), 0) + 1 FROM chat_queue WHERE session_id = ?), ?, ?, ?, ?, ?, ?)`
   ).run(
     m.id,
     sessionId,
@@ -68,6 +76,7 @@ export function enqueue(
     m.text,
     images,
     m.images?.length ?? 0,
+    m.files?.length ? JSON.stringify(m.files) : null,
     m.from || m.peer || m.origin ? JSON.stringify(sentBy) : null,
     Date.now()
   );
@@ -80,13 +89,20 @@ export function claimNext(
   sessionId: string,
   // That message only, if it's still there.
   id?: string
-): ({ id: string; text: string; images?: ChatImage[] } & SentBy) | null {
+):
+  | ({
+      id: string;
+      text: string;
+      images?: ChatImage[];
+      files?: ChatFile[];
+    } & SentBy)
+  | null {
   const row = db
     .prepare(
       `DELETE FROM chat_queue WHERE session_id = @sid AND NOT ${HELD_SQL} AND id = (
          SELECT id FROM chat_queue WHERE session_id = @sid AND (@id IS NULL OR id = @id)
          ORDER BY position, created_at LIMIT 1
-       ) RETURNING id, text, images, sent_by, created_at`
+       ) RETURNING id, text, images, files, sent_by, created_at`
     )
     .get({ sid: sessionId, id: id ?? null }) as Row | undefined;
   if (!row) return null;
@@ -94,6 +110,7 @@ export function claimNext(
     id: row.id,
     text: row.text,
     images: row.images ? (JSON.parse(row.images) as ChatImage[]) : undefined,
+    files: row.files ? (JSON.parse(row.files) as ChatFile[]) : undefined,
     ...(row.sent_by ? (JSON.parse(row.sent_by) as SentBy) : {}),
   };
 }

package/lib/chat/runner.ts

@@ -19,6 +19,7 @@ import type { CompactFirst } from "./stale";
 import type {
   ApprovalDecision,
   ChatContext,
+  ChatFile,
   ChatImage,
   ChatServerMessage,
   ChatState,
@@ -405,7 +406,12 @@ function refuseAway(sessionId: string): void {
 // started): the message waits in the queue instead of starting a turn.
 function queuedIfHeld(
   sessionId: string,
-  m: { id: string; text: string; images?: ChatImage[] } & SentBy
+  m: {
+    id: string;
+    text: string;
+    images?: ChatImage[];
+    files?: ChatFile[];
+  } & SentBy
 ): boolean {
   refuseAway(sessionId);
   if (!chatHold(sessionId)) return false;
@@ -429,6 +435,7 @@ export async function sendChat(
   input: {
     text: string;
     images?: ChatImage[];
+    files?: ChatFile[];
     // Typed in the composer: waits in the queue while a turn runs.
     queue?: boolean;
     // Compact a stale chat first (lib/chat/stale).
@@ -438,7 +445,7 @@ export async function sendChat(
   } & SentBy
 ): Promise<void> {
   const text = input.text.trim();
-  if (!text && !input.images?.length) return;
+  if (!text && !input.images?.length && !input.files?.length) return;
   if (input.id && taken(sessionId, input.id)) return;
   refuseAway(sessionId);
   const id = input.id ?? `user-${Date.now()}-${randomUUID().slice(0, 5)}`;
@@ -449,6 +456,7 @@ export async function sendChat(
       id,
       text,
       images: input.images,
+      files: input.files,
       ...sentBy(input),
     });
     emitQueue(sessionId);
@@ -463,6 +471,7 @@ export async function sendChat(
     id,
     text,
     images: input.images,
+    files: input.files,
     ...sentBy(input),
     queue: input.queue,
     compact: input.compact,

package/lib/chat/worker/host.ts

@@ -10,10 +10,12 @@ import { agentEnv } from "../../agents/launch";
 import { sessionRunningBrief } from "../../project-config/session";
 import { BUS_BRIEF } from "../../agents/brief";
 import { resolveModelForAgent } from "../../model-catalog";
+import { agentText } from "../../attachments/message";
 import { chatDriverFor } from "../drivers";
 import type { ChatConversation } from "../driver";
 import type {
   ChatContext,
+  ChatFile,
   ChatImage,
   ChatItem,
   ChatState,
@@ -560,6 +562,7 @@ export class ChatHost {
       id: string;
       text: string;
       images?: ChatImage[];
+      files?: ChatFile[];
     } & SentBy,
     now = false
   ): void {
@@ -577,7 +580,7 @@ export class ChatHost {
     if (now) this.nowPending++;
     this.stopping = null;
     const note = this.refreshedNote ?? (this.restartedNote && RESTARTED_NOTE);
-    const text = note ? `${note}\n\n${m.text}` : m.text;
+    const text = agentText(note ? `${note}\n\n${m.text}` : m.text, m.files);
     if (this.refreshedNote) {
       this.refreshedNote = null;
       db.prepare(`UPDATE sessions SET chat_refreshed = 0 WHERE id = ?`).run(
@@ -592,13 +595,14 @@ export class ChatHost {
     }
     if (/^\/compact\b/.test(m.text.trimStart())) this.setCompacting(true);
     const checkpoint = now
-      ? this.conversation.send(text, m.images, { now })
-      : this.conversation.send(text, m.images);
+      ? this.conversation.send(text, m.images, { now, files: m.files })
+      : this.conversation.send(text, m.images, { files: m.files });
     const user: ChatItem = {
       id: m.id,
       kind: "user",
       text: m.text,
       images: m.images,
+      files: m.files,
       from: m.from,
       peer: m.peer,
       origin: m.origin,

package/lib/chat/worker/protocol.ts

@@ -9,6 +9,7 @@ import path from "path";
 import type {
   ApprovalDecision,
   ChatAccess,
+  ChatFile,
   ChatImage,
   ChatItem,
   ChatState,
@@ -32,6 +33,7 @@ export type WorkerCommand =
       id: string;
       text: string;
       images?: ChatImage[];
+      files?: ChatFile[];
       from?: string;
       peer?: PeerMessage;
       origin?: ChatOrigin;

package/lib/config/client-config-types.ts

@@ -28,10 +28,23 @@ export interface ClientConfig {
   runTriggers: Record<string, string>;
   features: ClientFeatures;
   intake: IntakeLimits;
-  attachments: { max: number };
+  attachments: AttachmentConfig;
   voice: VoiceLimits;
 }
 
+// What a chat accepts, served from lib/attachments/policy.ts. Sizes in bytes.
+export interface AttachmentConfig {
+  max: number;
+  maxBytes: number;
+  maxImageBytes: number;
+  pdfInlineBytes: number;
+  types: {
+    ext: string;
+    mediaType: string;
+    kind: "image" | "pdf" | "sheet" | "doc" | "text";
+  }[];
+}
+
 // Server kill switches for the phone's new sends.
 export interface ClientFeatures {
   shakeToReport: boolean;
@@ -66,8 +79,6 @@ export const INTAKE_LIMITS: IntakeLimits = {
   logMaxLines: 200,
 };
 
-export const ATTACHMENT_LIMITS = { max: 8 };
-
 export const VOICE_LIMITS: VoiceLimits = {
   maxPhrases: 100,
   holdMinMs: 250,

package/lib/config/client-config.ts

@@ -1,3 +1,4 @@
+import { ATTACHMENT_LIMITS } from "../attachments/policy";
 import { ACCESS_LEVELS, DEFAULT_NEW_CHAT_ACCESS } from "../chat/access-levels";
 import { CHAT_ACCESS } from "../chat/events";
 import {
@@ -7,7 +8,6 @@ import {
 import { TASK_STATE_LABELS } from "../tasks/state-labels";
 import { cachedCheck } from "../updates/check";
 import {
-  ATTACHMENT_LIMITS,
   CLIENT_CONFIG_VERSION,
   INTAKE_LIMITS,
   VOICE_LIMITS,