Q28: agents list, read, and update company documents

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

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

@@ -58,7 +58,7 @@ export function createDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, a
  * every deliverable and document lands in the Approvals queue. AI CEO mode
  * ships without review — that autonomy is the mode's contract.
  */
-function requestDeliverableReview(
+export function requestDeliverableReview(
   deps: AgentToolDeps,
   ctx: AgentToolContext,
   input: { title: string; details: string; sourceEntityType: "file" | "document"; sourceEntityId: string },

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

@@ -0,0 +1,100 @@
+import { optionalEnum, optionalLimit, optionalText, requireString } from "./agent-tool-args";
+import { requestDeliverableReview } from "./agent-deliverable-tools";
+import type { AgentToolContext, AgentToolDeps } from "./agent-tools";
+import { DocumentService } from "./document-service";
+import type { JsonRecord } from "./provider-http";
+import type { ToolDefinition } from "./provider-tool-turn";
+import { relevantItems } from "./relevance";
+import { PAGE_TOOL_PROPERTIES, pageText, readPageArgs } from "./text-paging";
+
+export const DOCUMENT_TYPES = ["prd", "spec", "memo", "report", "runbook", "proposal", "policy", "guide"] as const;
+
+interface DocumentRow {
+  id: string;
+  title: string;
+  doc_type: string;
+  status: string;
+  content: string;
+  updated_at: string;
+}
+
+export const DOCUMENT_TOOLS: ToolDefinition[] = [
+  {
+    name: "list_documents",
+    description: "Find company documents (PRDs, specs, reports, ...) by words in their title or body, or by type. Returns doc_ids for read_document.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        query: { type: "string", description: "Words to look for; omit to list the newest documents." },
+        doc_type: { type: "string", enum: [...DOCUMENT_TYPES] },
+        limit: { type: "number", description: "Most documents to return (default 10, max 30)." },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "read_document",
+    description: "Read a company document by doc_id — whole, a range of lines, or only the lines matching a search.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: { doc_id: { type: "string" }, ...PAGE_TOOL_PROPERTIES },
+      required: ["doc_id"],
+    },
+  },
+  {
+    name: "update_document",
+    description: "Replace a company document's content (and optionally its title). Say why in reason.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        doc_id: { type: "string" },
+        content: { type: "string", description: "The full new content in markdown." },
+        title: { type: "string" },
+        reason: { type: "string", description: "What changed and why." },
+      },
+      required: ["doc_id", "content", "reason"],
+    },
+  },
+];
+
+export function listDocumentsTool(deps: AgentToolDeps, ctx: AgentToolContext, args: JsonRecord): string {
+  const query = optionalText(args.query, "query");
+  const docType = args.doc_type === undefined ? null : optionalEnum(args.doc_type, "doc_type", DOCUMENT_TYPES, "");
+  const limit = optionalLimit(args.limit, "limit", 10, 30);
+  const rows = deps.db.prepare(`
+    select id, title, doc_type, status, content, updated_at from documents
+    where org_id = ? and (? is null or doc_type = ?) order by updated_at desc
+  `).all(ctx.orgId, docType, docType) as unknown as DocumentRow[];
+  const found = query ? relevantItems(rows, (row) => `${row.title} ${row.content}`, query, limit) : rows.slice(0, limit);
+  if (found.length === 0) return query ? `No documents match "${query}".` : "No documents yet.";
+  return found.map((row) => `${row.title} (doc_id=${row.id}, ${row.doc_type}, ${row.status}, ${row.content.length} chars, updated ${row.updated_at})`).join("\n");
+}
+
+export function readDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, args: JsonRecord): string {
+  const id = requireString(args.doc_id, "doc_id");
+  const doc = deps.db.prepare("select title, doc_type, status, content from documents where id = ? and org_id = ?")
+    .get(id, ctx.orgId) as { title: string; doc_type: string; status: string; content: string } | undefined;
+  if (!doc) throw new Error(`No document with doc_id "${id}".`);
+  return `${doc.title} (${doc.doc_type}, ${doc.status})\n\n${pageText(doc.title, doc.content, readPageArgs(args))}`;
+}
+
+export function updateDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, args: JsonRecord): string {
+  const id = requireString(args.doc_id, "doc_id");
+  const doc = deps.db.prepare("select title, doc_type, status from documents where id = ? and org_id = ?")
+    .get(id, ctx.orgId) as { title: string; doc_type: string; status: string } | undefined;
+  if (!doc) throw new Error(`No document with doc_id "${id}".`);
+  const content = requireString(args.content, "content");
+  const title = optionalText(args.title, "title") ?? doc.title;
+  const reason = requireString(args.reason, "reason");
+  new DocumentService(deps.db).update({ orgId: ctx.orgId, documentId: id, title, content, status: doc.status });
+  const review = requestDeliverableReview(deps, ctx, {
+    title: `Review ${doc.doc_type} update: ${title}`,
+    details: `Document "${title}" was updated by an agent run (${content.length} chars). Reason: ${reason}`,
+    sourceEntityType: "document",
+    sourceEntityId: id,
+  });
+  return `Updated document "${title}" (doc_id=${id}).${review ? " The update is queued for board review in Approvals." : ""}`;
+}

src/main/services/agent-tools.ts

@@ -12,6 +12,7 @@ import { createDocumentTool, writeDeliverableTool } from "./agent-deliverable-to
 import { companyStatusTool, GOAL_TOOLS, updateGoalTool } from "./agent-goal-tools";
 import { ATTACHMENT_TOOLS, readAttachmentTool } from "./agent-attachment-tools";
 import { KNOWLEDGE_TOOLS, recordKnowledgeTool, reviseKnowledgeTool, searchKnowledgeTool } from "./agent-knowledge-tools";
+import { DOCUMENT_TOOLS, DOCUMENT_TYPES, listDocumentsTool, readDocumentTool, updateDocumentTool } from "./agent-document-tools";
 import { sendMessageTool } from "./agent-send-message";
 import { withSavepoint } from "../database/connection";
 import { optionalString, optionalStringArray, requireString } from "./agent-tool-args";
@@ -160,7 +161,7 @@ export const AGENT_TOOLS: ToolDefinition[] = [
       additionalProperties: false,
       properties: {
         title: { type: "string" },
-        doc_type: { type: "string", enum: ["prd", "spec", "memo", "report", "runbook", "proposal", "policy", "guide"] },
+        doc_type: { type: "string", enum: [...DOCUMENT_TYPES] },
         content: { type: "string", description: "Full document content in markdown." },
       },
       required: ["title", "doc_type", "content"],
@@ -231,6 +232,7 @@ export const AGENT_TOOLS: ToolDefinition[] = [
   ...GOAL_TOOLS,
   ...ATTACHMENT_TOOLS,
   ...KNOWLEDGE_TOOLS,
+  ...DOCUMENT_TOOLS,
 ];
 
 export function dispatchAgentTool(
@@ -255,6 +257,12 @@ export function dispatchAgentTool(
         return readMessagesTool(deps, ctx, call.arguments);
       case "create_document":
         return createDocumentTool(deps, ctx, call.arguments);
+      case "list_documents":
+        return listDocumentsTool(deps, ctx, call.arguments);
+      case "read_document":
+        return readDocumentTool(deps, ctx, call.arguments);
+      case "update_document":
+        return updateDocumentTool(deps, ctx, call.arguments);
       case "list_connectors":
         return listConnectorsTool(deps, ctx);
       case "grant_connector":

src/main/services/task-prompts.ts

@@ -106,7 +106,7 @@ export function buildAgentInstructions(input: AgentInstructionContext): string {
     `You are ${agent.name}, ${agent.title || agent.role} in ${agent.department} at ${input.companyName}. You are a real member of this company with your own judgment and voice — a colleague, not a generic assistant.`,
     roleVoice(input),
     "Work like a sharp person: take in what is actually in front of you, decide the smallest real next step, do it, then tell whoever needs to know. Do not narrate busywork.",
-    `Your tools are how you act: hire_agent builds your team, create_task delegates and assigns work by name (set requires_filesystem for engineering work that must change code or run commands), update_task_status tracks it, list_files and read_file explore the company workspace, write_deliverable produces real files, run_command builds and tests for real on filesystem tasks, create_document writes versioned company documents (PRDs, specs, memos, reports), search_knowledge and record_knowledge read and grow what the company has learned, read_messages catches you up on what teammates said, and send_message is how you talk to everyone. web_search and fetch_url reach the live web — look up APIs, docs, and facts instead of guessing them.`,
+    `Your tools are how you act: hire_agent builds your team, create_task delegates and assigns work by name (set requires_filesystem for engineering work that must change code or run commands), update_task_status tracks it, list_files and read_file explore the company workspace, write_deliverable produces real files, run_command builds and tests for real on filesystem tasks, create_document writes company documents (PRDs, specs, memos, reports) and list_documents, read_document, update_document find and revise them, search_knowledge and record_knowledge read and grow what the company has learned, read_messages catches you up on what teammates said, and send_message is how you talk to everyone. web_search and fetch_url reach the live web — look up APIs, docs, and facts instead of guessing them.`,
     ...(input.language === "zh"
       ? ["公司的工作语言是简体中文：你写的每一条消息、任务标题与描述、文档和交付物都用中文表达（代码、命令、API 名称等技术标识保持原样）。工具名称和工具参数的字段名仍按定义使用英文。"]
       : []),

src/main/services/text-paging.ts

@@ -1,3 +1,4 @@
+import { optionalText } from "./agent-tool-args";
 import type { JsonRecord } from "./provider-http";
 
 const PAGE_CHAR_LIMIT = 24_000;
@@ -18,7 +19,7 @@ export const PAGE_TOOL_PROPERTIES = {
 } as const;
 
 export function readPageArgs(args: JsonRecord): PageRequest {
-  const search = typeof args.search === "string" && args.search.trim() ? args.search.trim() : null;
+  const search = optionalText(args.search, "search");
   return {
     startLine: positiveInteger(args.start_line, "start_line") ?? 1,
     startColumn: positiveInteger(args.start_column, "start_column") ?? 1,

tests/unit/agent-document-tools.test.ts

@@ -0,0 +1,62 @@
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { DatabaseConnection } from "../../src/main/database/connection";
+import { OrganizationService } from "../../src/main/services/organization-service";
+import { ChatService } from "../../src/main/services/chat-service";
+import { dispatchAgentTool, type AgentToolContext } from "../../src/main/services/agent-tools";
+
+function harness(reviewDeliverables: boolean) {
+  const connection = new DatabaseConnection(join(tmpdir(), `ac-docs-${randomUUID()}.db`));
+  const organization = new OrganizationService(connection.db);
+  let orgId = "";
+  let agentId = "";
+  connection.transaction(() => {
+    orgId = organization.createOrganization({ organizationName: "D", employeeName: "Y", mission: "m", goal: "g" });
+    agentId = organization.createAgent({ orgId, name: "Ana", role: "PM", department: "Product", modelProviderId: null, modelId: null, budgetCents: 1000, managerAgentId: null });
+  });
+  connection.db.prepare("update organizations set review_deliverables = ? where id = ?").run(reviewDeliverables ? 1 : 0, orgId);
+  const ctx: AgentToolContext = {
+    orgId, agent: { id: agentId, modelProviderId: null, modelId: null },
+    taskProjectId: null, taskGoalId: null, taskId: null, sourceThreadId: null, workspace: null,
+  };
+  const run = (name: string, args: Record<string, unknown>) =>
+    dispatchAgentTool({ db: connection.db, organization, chat: new ChatService(connection.db) }, ctx, { id: `c_${randomUUID()}`, name, arguments: args });
+  return { connection, orgId, run };
+}
+
+describe("agent document tools", () => {
+  test("documents an agent wrote can be found, read in pages, and updated", () => {
+    const h = harness(false);
+    const created = h.run("create_document", { title: "Booking PRD", doc_type: "prd", content: Array.from({ length: 3000 }, (_, i) => `Requirement ${i + 1}: booking flow`).join("\n") });
+    const docId = /doc_id=(doc_\w+)/.exec(created)![1];
+    h.run("create_document", { title: "Q3 Report", doc_type: "report", content: "Revenue grew." });
+
+    expect(h.run("list_documents", { query: "booking" })).toMatch(new RegExp(`^Booking PRD \\(doc_id=${docId}, prd, draft, \\d+ chars`));
+    expect(h.run("list_documents", { doc_type: "report" })).toMatch(/^Q3 Report \(doc_id=doc_\w+, report/);
+    expect(h.run("list_documents", { query: "kubernetes" })).toBe('No documents match "kubernetes".');
+
+    const page = h.run("read_document", { doc_id: docId });
+    expect(page.startsWith("Booking PRD (prd, draft)\n\n[lines 1-")).toBe(true);
+    expect(page).toContain("[more: pass start_line=");
+    expect(h.run("read_document", { doc_id: docId, search: "Requirement 2999:" })).toContain("2999: Requirement 2999: booking flow");
+
+    expect(h.run("update_document", { doc_id: docId, content: "Requirement 1: rebooking", reason: "Scope cut" })).toBe(`Updated document "Booking PRD" (doc_id=${docId}).`);
+    expect(h.run("read_document", { doc_id: docId })).toBe("Booking PRD (prd, draft)\n\nRequirement 1: rebooking");
+    expect(h.run("update_document", { doc_id: docId, content: "x" })).toBe('ERROR: "reason" is required.');
+    expect(h.run("read_document", { doc_id: "doc_missing" })).toBe('ERROR: No document with doc_id "doc_missing".');
+    expect(h.run("read_document", { doc_id: docId, search: 123 })).toBe('ERROR: "search" is required.');
+    expect(h.run("list_documents", { doc_type: "novel" })).toBe('ERROR: "doc_type" must be one of: prd, spec, memo, report, runbook, proposal, policy, guide.');
+    h.connection.close();
+  });
+
+  test("in review mode an update goes to Approvals", () => {
+    const h = harness(true);
+    const docId = /doc_id=(doc_\w+)/.exec(h.run("create_document", { title: "Policy", doc_type: "policy", content: "v1" }))![1];
+    expect(h.run("update_document", { doc_id: docId, content: "v2", reason: "Tighter wording" })).toContain("queued for board review");
+    const approvals = h.connection.db.prepare("select title from approvals where org_id = ? and kind = 'deliverable_review' order by created_at").all(h.orgId);
+    expect(approvals).toEqual([{ title: "Review policy: Policy" }, { title: "Review policy update: Policy" }]);
+    h.connection.close();
+  });
+});

tests/unit/text-paging.test.ts

@@ -53,6 +53,8 @@ describe("text paging", () => {
   test("bad ranges fail loudly", () => {
     expect(() => readPageArgs({ start_line: 0 })).toThrow('"start_line" must be a positive whole number.');
     expect(() => readPageArgs({ line_count: 2.5 })).toThrow('"line_count" must be a positive whole number.');
+    expect(() => readPageArgs({ search: 123 })).toThrow('"search" is required.');
+    expect(() => readPageArgs({ search: "  " })).toThrow('"search" is required.');
     expect(() => pageText("a.md", "one", readPageArgs({ start_line: 3 }))).toThrow("a.md has only 1 lines.");
   });
 });