Q13: messages carry their attachments; agents read them by file_id

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/main/services/agent-attachment-tools.ts

@@ -0,0 +1,54 @@
+import type { DatabaseSync } from "node:sqlite";
+import { readFileSync } from "node:fs";
+import { FILE_SCAN_STATE } from "../../shared/domain";
+import { requireString } from "./agent-tool-args";
+import type { AgentToolContext, AgentToolDeps } from "./agent-tools";
+import type { JsonRecord } from "./provider-http";
+import type { ToolDefinition } from "./provider-tool-turn";
+
+const ATTACHMENT_CHAR_LIMIT = 24_000;
+
+export const ATTACHMENT_TOOLS: ToolDefinition[] = [
+  {
+    name: "read_attachment",
+    description: "Read a file attached to a message or handed off to you, by the file_id shown next to the message.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: { file_id: { type: "string" } },
+      required: ["file_id"],
+    },
+  },
+];
+
+/** " [attachments: a.md (file_id=…)]" for a message, or "". */
+export function attachmentNote(db: DatabaseSync, messageId: string): string {
+  const files = db.prepare(`
+    select f.id, f.name from chat_attachments ca join file_objects f on f.id = ca.file_id
+    where ca.message_id = ? order by f.name
+  `).all(messageId) as Array<{ id: string; name: string }>;
+  if (files.length === 0) return "";
+  return ` [attachments: ${files.map((file) => `${file.name} (file_id=${file.id})`).join(", ")}]`;
+}
+
+export function readAttachmentTool(deps: AgentToolDeps, ctx: AgentToolContext, args: JsonRecord): string {
+  const fileId = requireString(args.file_id, "file_id");
+  const file = deps.db.prepare("select name, storage_path, scan_state from file_objects where id = ? and org_id = ?")
+    .get(fileId, ctx.orgId) as { name: string; storage_path: string; scan_state: string } | undefined;
+  if (!file) throw new Error(`No file with file_id "${fileId}".`);
+  if (file.scan_state !== FILE_SCAN_STATE.APPROVED) throw new Error(`${file.name} was blocked by the file scan and cannot be read.`);
+  const bytes = readFileSync(file.storage_path);
+  const content = utf8Text(bytes);
+  if (content === null) return `${file.name} is a binary file (${bytes.length} bytes); it has no text to read.`;
+  if (content.length <= ATTACHMENT_CHAR_LIMIT) return content;
+  return `${content.slice(0, ATTACHMENT_CHAR_LIMIT)}\n\n[truncated: showing the first ${ATTACHMENT_CHAR_LIMIT} of ${content.length} characters]`;
+}
+
+function utf8Text(bytes: Buffer): string | null {
+  if (bytes.includes(0)) return null;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}

src/main/services/agent-read-messages.ts

@@ -1,3 +1,4 @@
+import { attachmentNote } from "./agent-attachment-tools";
 import { optionalString } from "./agent-tool-args";
 import type { AgentToolContext, AgentToolDeps } from "./agent-tools";
 import type { JsonRecord } from "./provider-http";
@@ -75,14 +76,14 @@ function messagePage(
   ) as Array<{ id: string; row_id: number; body_md: string; created_at: string; thread_id: string; sender_name: string }>;
   if (rows.length === 0) return `No messages${filter.query ? ` matching "${filter.query}"` : ""}${filter.before ? " before that point" : ""} in ${label}.`;
   const page = rows.slice(0, filter.limit).reverse();
-  const lines = page.map((m) => `[${m.created_at}] ${m.sender_name} (thread=${m.thread_id}): ${m.body_md}`);
+  const lines = page.map((m) => `[${m.created_at}] ${m.sender_name} (thread=${m.thread_id}): ${m.body_md}${attachmentNote(deps.db, m.id)}`);
   if (rows.length > filter.limit) lines.unshift(`(Older messages exist: pass before="${page[0].id}" to read them.)`);
   return lines.join("\n");
 }
 
 function unansweredMentions(deps: AgentToolDeps, ctx: AgentToolContext, limit: number): string {
   const rows = deps.db.prepare(`
-    select m.body_md,
+    select m.id, m.body_md,
            coalesce(a.name, e.display_name, m.sender_type) as sender_name,
            m.thread_id, s.name as channel_name, s.space_type
     from chat_mentions cm
@@ -98,11 +99,11 @@ function unansweredMentions(deps: AgentToolDeps, ctx: AgentToolContext, limit: n
       )
     order by m.created_at desc
     limit ?
-  `).all(ctx.agent.id, ctx.orgId, limit) as Array<{ body_md: string; sender_name: string; thread_id: string; channel_name: string; space_type: string }>;
+  `).all(ctx.agent.id, ctx.orgId, limit) as Array<{ id: string; body_md: string; sender_name: string; thread_id: string; channel_name: string; space_type: string }>;
   if (rows.length === 0) return "No unanswered mentions.";
   return rows.reverse().map((m) => {
     const where = m.space_type === "direct" ? "in your direct conversation" : `in #${m.channel_name}`;
-    return `[${m.sender_name} ${where}] (thread=${m.thread_id}): ${m.body_md}`;
+    return `[${m.sender_name} ${where}] (thread=${m.thread_id}): ${m.body_md}${attachmentNote(deps.db, m.id)}`;
   }).join("\n");
 }
 

src/main/services/agent-tools.ts

@@ -10,6 +10,7 @@ import { grantConnectorTool, listConnectorsTool } from "./agent-connector-tools"
 import { bindSkillSlugs, grantSkillTool, listSkillsTool } from "./agent-skill-tools";
 import { createDocumentTool, writeDeliverableTool } from "./agent-deliverable-tools";
 import { companyStatusTool, GOAL_TOOLS, updateGoalTool } from "./agent-goal-tools";
+import { ATTACHMENT_TOOLS, readAttachmentTool } from "./agent-attachment-tools";
 import { sendMessageTool } from "./agent-send-message";
 import { withSavepoint } from "../database/connection";
 import { optionalString, optionalStringArray, requireString } from "./agent-tool-args";
@@ -227,6 +228,7 @@ export const AGENT_TOOLS: ToolDefinition[] = [
     },
   },
   ...GOAL_TOOLS,
+  ...ATTACHMENT_TOOLS,
 ];
 
 export function dispatchAgentTool(
@@ -257,6 +259,8 @@ export function dispatchAgentTool(
         return grantConnectorTool(deps, ctx, call.arguments, "grant");
       case "revoke_connector":
         return grantConnectorTool(deps, ctx, call.arguments, "revoke");
+      case "read_attachment":
+        return readAttachmentTool(deps, ctx, call.arguments);
       case "company_status":
         return companyStatusTool(deps, ctx);
       case "update_goal":

src/main/services/chat-wake-context.ts

@@ -1,10 +1,11 @@
 import type { DatabaseSync } from "node:sqlite";
 import type { ChatContextBlock } from "./task-prompts";
+import { attachmentNote } from "./agent-attachment-tools";
 
 const HISTORY_LIMIT = 20;
 
 const MESSAGE_SELECT = `
-  select m.body_md, m.created_at, m.edited_at, m.sender_type, m.sender_id,
+  select m.id, m.body_md, m.created_at, m.edited_at, m.sender_type, m.sender_id,
          coalesce(a.name, e.display_name, m.sender_type) as sender_name,
          coalesce(a.role, e.role) as sender_role
   from chat_messages m
@@ -12,6 +13,7 @@ const MESSAGE_SELECT = `
   left join employees e on e.id = m.sender_id and m.sender_type = 'employee'`;
 
 interface ThreadMessageRow {
+  id: string;
   body_md: string;
   created_at: string;
   edited_at: string | null;
@@ -46,15 +48,15 @@ export function loadChatWakeContext(db: DatabaseSync, orgId: string, agentId: st
   return {
     threadId: scope.sourceThreadId,
     spaceId: thread.space_id,
-    history: [...(omitted > 0 ? [`(${omitted} earlier messages in this thread are not shown.)`] : []), ...history.map(formatMessage)].join("\n"),
-    fresh: fresh.map(formatMessage).join("\n"),
+    history: [...(omitted > 0 ? [`(${omitted} earlier messages in this thread are not shown.)`] : []), ...history.map((m) => formatMessage(db, m))].join("\n"),
+    fresh: fresh.map((m) => formatMessage(db, m)).join("\n"),
   };
 }
 
-function formatMessage(m: ThreadMessageRow): string {
+function formatMessage(db: DatabaseSync, m: ThreadMessageRow): string {
   const who = m.sender_role ? `${m.sender_name} (${m.sender_type}, ${m.sender_role})` : `${m.sender_name} (${m.sender_type})`;
   const edited = m.edited_at ? ` (edited ${utcMinute(m.edited_at)})` : "";
-  return `[${utcMinute(m.created_at)}] ${who}${edited}: ${m.body_md}`;
+  return `[${utcMinute(m.created_at)}] ${who}${edited}: ${m.body_md}${attachmentNote(db, m.id)}`;
 }
 
 function utcMinute(iso: string): string {
@@ -80,6 +82,6 @@ export function createRunMessagePoller(
     if (rows.length === 0) return null;
     watermark = rows[rows.length - 1].created_at;
     console.info(`[run-inbox] agent ${input.agentId}: ${rows.length} new message(s) injected mid-run`);
-    return ["Messages that arrived while you were working (they may change what you should do):", ...rows.map(formatMessage)].join("\n");
+    return ["Messages that arrived while you were working (they may change what you should do):", ...rows.map((m) => formatMessage(db, m))].join("\n");
   };
 }