diff --git a/src/main/database/migrations/065-document-versions.ts b/src/main/database/migrations/065-document-versions.ts new file mode 100644 index 00000000..789402b9 --- /dev/null +++ b/src/main/database/migrations/065-document-versions.ts @@ -0,0 +1,26 @@ +export const documentVersionsSchema = ` + alter table documents add column version integer not null default 1; + + create table if not exists document_versions ( + id text primary key, + org_id text not null references organizations(id) on delete cascade, + document_id text not null, + version integer not null, + title text not null, + content text not null, + status text not null, + changed_by_type text not null, + changed_by_id text, + reason text not null, + created_at text not null, + unique (document_id, version) + ); + + insert into document_versions(id, org_id, document_id, version, title, content, status, changed_by_type, changed_by_id, reason, created_at) + select 'dov_' || lower(hex(randomblob(16))), org_id, id, 1, title, content, status, + case when author_agent_id is null then 'employee' else 'agent' end, author_agent_id, 'created', created_at + from documents; + + insert into schema_migrations(version, name, applied_at) + values (65, 'document_versions', datetime('now')); +`; diff --git a/src/main/database/schema.ts b/src/main/database/schema.ts index e5f1d5b8..181c35cd 100644 --- a/src/main/database/schema.ts +++ b/src/main/database/schema.ts @@ -63,6 +63,7 @@ import { taskRunContextSchema } from "./migrations/061-task-run-context"; import { providerContextWindowSchema } from "./migrations/062-provider-context-window"; import { knowledgeScopeSchema } from "./migrations/063-knowledge-scope"; import { knowledgeRevisionsSchema } from "./migrations/064-knowledge-revisions"; +import { documentVersionsSchema } from "./migrations/065-document-versions"; interface Migration { version: number; @@ -135,6 +136,7 @@ const MIGRATIONS: Migration[] = [ { version: 62, name: "provider_context_window", sql: providerContextWindowSchema }, { version: 63, name: "knowledge_scope", sql: knowledgeScopeSchema }, { version: 64, name: "knowledge_revisions", sql: knowledgeRevisionsSchema }, + { version: 65, name: "document_versions", sql: documentVersionsSchema }, ]; const SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version; diff --git a/src/main/services/agent-document-tools.ts b/src/main/services/agent-document-tools.ts index 02415a49..9b3d6447 100644 --- a/src/main/services/agent-document-tools.ts +++ b/src/main/services/agent-document-tools.ts @@ -7,6 +7,8 @@ import type { ToolDefinition } from "./provider-tool-turn"; import { relevantItems } from "./relevance"; import { PAGE_TOOL_PROPERTIES, pageText, readPageArgs } from "./text-paging"; +const PAGE_ARGUMENTS = ["version", "start_line", "line_count", "start_column", "search"] as const; + export const DOCUMENT_TYPES = ["prd", "spec", "memo", "report", "runbook", "proposal", "policy", "guide"] as const; interface DocumentRow { @@ -15,6 +17,7 @@ interface DocumentRow { doc_type: string; status: string; content: string; + version: number; updated_at: string; task_id: string | null; task_title: string | null; @@ -37,11 +40,16 @@ export const DOCUMENT_TOOLS: ToolDefinition[] = [ }, { name: "read_document", - description: "Read a company document by doc_id — whole, a range of lines, or only the lines matching a search.", + description: "Read a company document by doc_id — whole, a range of lines, or only the lines matching a search. Pass version to read an earlier version; pass history=true to list every version.", parameters: { type: "object", additionalProperties: false, - properties: { doc_id: { type: "string" }, ...PAGE_TOOL_PROPERTIES }, + properties: { + doc_id: { type: "string" }, + version: { type: "number", description: "An earlier version number; omit for the current one." }, + history: { type: "boolean", description: "List every version with who changed it and why." }, + ...PAGE_TOOL_PROPERTIES, + }, required: ["doc_id"], }, }, @@ -67,21 +75,35 @@ export function listDocumentsTool(deps: AgentToolDeps, ctx: AgentToolContext, ar 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 d.id, d.title, d.doc_type, d.status, d.content, d.updated_at, d.task_id, t.title as task_title + select d.id, d.title, d.doc_type, d.status, d.content, d.version, d.updated_at, d.task_id, t.title as task_title from documents d left join tasks t on t.id = d.task_id where d.org_id = ? and (? is null or d.doc_type = ?) order by d.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}${producedBy(row)})`).join("\n"); + return found.map((row) => `${row.title} (doc_id=${row.id}, ${row.doc_type}, ${row.status}, v${row.version}, ${row.content.length} chars, updated ${row.updated_at}${producedBy(row)})`).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))}`; + const page = readPageArgs(args); + if (args.history !== undefined && typeof args.history !== "boolean") throw new Error('"history" must be true or false.'); + const doc = deps.db.prepare("select doc_type, version from documents where id = ? and org_id = ?") + .get(id, ctx.orgId) as { doc_type: string; version: number } | undefined; + const versions = new DocumentService(deps.db).versions(ctx.orgId, id); + if (versions.length === 0) throw new Error(`No document with doc_id "${id}".`); + const latest = versions[versions.length - 1].version; + const kind = doc ? doc.doc_type : "deleted"; + if (args.history === true) { + if (PAGE_ARGUMENTS.some((name) => args[name] !== undefined)) { + throw new Error("history=true lists versions; it takes no version or paging arguments."); + } + return versions.map((v) => `v${v.version} ${v.created_at} by ${v.changed_by_type}${v.changed_by_id ? ` ${v.changed_by_id}` : ""} — ${v.reason} (${v.content.length} chars)`).join("\n"); + } + const wanted = optionalLimit(args.version, "version", latest, latest); + const picked = versions.find((v) => v.version === wanted); + if (!picked) throw new Error(`Document ${id} has no version ${wanted}.`); + return `${picked.title} (${kind}, ${picked.status}, v${picked.version} of ${latest})\n\n${pageText(picked.title, picked.content, page)}`; } export function updateDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, args: JsonRecord): string { @@ -92,14 +114,16 @@ export function updateDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, a 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 version = new DocumentService(deps.db).update({ + orgId: ctx.orgId, documentId: id, title, content, status: doc.status, reason, changedByType: "agent", changedById: ctx.agent.id, + }); 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}`, + details: `Document "${title}" v${version} 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." : ""}`; + return `Updated document "${title}" to v${version} (doc_id=${id}).${review ? " The update is queued for board review in Approvals." : ""}`; } function producedBy(row: DocumentRow): string { diff --git a/src/main/services/document-service.ts b/src/main/services/document-service.ts index 5ef6df18..b4877ac8 100644 --- a/src/main/services/document-service.ts +++ b/src/main/services/document-service.ts @@ -3,6 +3,17 @@ import type { CreateDocumentInput, UpdateDocumentInput, DeleteDocumentInput } fr import { createId } from "../../shared/ids"; import { AuditService } from "./audit-service"; +export interface DocumentVersion { + version: number; + title: string; + content: string; + status: string; + changed_by_type: string; + changed_by_id: string | null; + reason: string; + created_at: string; +} + export class DocumentService { private readonly audit: AuditService; @@ -14,9 +25,13 @@ export class DocumentService { const id = createId("doc"); const now = new Date().toISOString(); this.db.prepare(` - insert into documents(id, org_id, title, doc_type, content, status, author_agent_id, reviewer_agent_id, project_id, goal_id, task_id, created_at, updated_at) - values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) + insert into documents(id, org_id, title, doc_type, content, status, author_agent_id, reviewer_agent_id, project_id, goal_id, task_id, version, created_at, updated_at) + values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?) `).run(id, input.orgId, input.title.trim(), input.docType, input.content, "draft", input.authorAgentId, input.reviewerAgentId, input.projectId, input.goalId, input.taskId, now, now); + this.writeVersion({ + orgId: input.orgId, documentId: id, version: 1, title: input.title.trim(), content: input.content, status: "draft", + changedByType: input.authorAgentId ? "agent" : "employee", changedById: input.authorAgentId, reason: "created", at: now, + }); this.audit.record({ orgId: input.orgId, entityType: "document", @@ -29,15 +44,44 @@ export class DocumentService { return id; } - update(input: UpdateDocumentInput): void { - const result = this.db.prepare(` - update documents set title = ?, content = ?, status = ?, updated_at = ? where id = ? and org_id = ? - `).run(input.title.trim(), input.content, input.status, new Date().toISOString(), input.documentId, input.orgId); - if (result.changes === 0) throw new Error("Document was not found."); + /** Saves a new version; earlier versions stay readable. */ + update(input: UpdateDocumentInput): number { + const reason = input.reason.trim(); + if (!reason) throw new Error("A document update needs a reason."); + const current = this.db.prepare("select version from documents where id = ? and org_id = ?") + .get(input.documentId, input.orgId) as { version: number } | undefined; + if (!current) throw new Error("Document was not found."); + const version = current.version + 1; + const now = new Date().toISOString(); + this.db.prepare(` + update documents set title = ?, content = ?, status = ?, version = ?, updated_at = ? where id = ? and org_id = ? + `).run(input.title.trim(), input.content, input.status, version, now, input.documentId, input.orgId); + this.writeVersion({ + orgId: input.orgId, documentId: input.documentId, version, title: input.title.trim(), content: input.content, status: input.status, + changedByType: input.changedByType, changedById: input.changedById, reason, at: now, + }); + return version; + } + + versions(orgId: string, documentId: string): DocumentVersion[] { + return this.db.prepare(` + select version, title, content, status, changed_by_type, changed_by_id, reason, created_at + from document_versions where document_id = ? and org_id = ? order by version asc + `).all(documentId, orgId) as unknown as DocumentVersion[]; } delete(input: DeleteDocumentInput): void { const result = this.db.prepare("delete from documents where id = ? and org_id = ?").run(input.documentId, input.orgId); if (result.changes === 0) throw new Error("Document was not found."); } + + private writeVersion(input: { + orgId: string; documentId: string; version: number; title: string; content: string; status: string; + changedByType: string; changedById: string | null; reason: string; at: string; + }): void { + this.db.prepare(` + insert into document_versions(id, org_id, document_id, version, title, content, status, changed_by_type, changed_by_id, reason, created_at) + values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) + `).run(createId("dov"), input.orgId, input.documentId, input.version, input.title, input.content, input.status, input.changedByType, input.changedById, input.reason, input.at); + } } diff --git a/src/shared/commands/collaboration.ts b/src/shared/commands/collaboration.ts index c070b1f9..8c0524c4 100644 --- a/src/shared/commands/collaboration.ts +++ b/src/shared/commands/collaboration.ts @@ -16,6 +16,10 @@ export interface UpdateDocumentInput { title: string; content: string; status: string; + /** Why it changed; kept with the new version. */ + reason: string; + changedByType: "employee" | "agent"; + changedById: string | null; } export interface DeleteDocumentInput { diff --git a/src/shared/domain.ts b/src/shared/domain.ts index f99fad91..58cce05c 100644 --- a/src/shared/domain.ts +++ b/src/shared/domain.ts @@ -406,6 +406,7 @@ export interface DocumentRecord { projectId: string | null; goalId: string | null; taskId: string | null; + version: number; createdAt: string; updatedAt: string; } diff --git a/tests/unit/agent-document-tools.test.ts b/tests/unit/agent-document-tools.test.ts index e0396c38..5d2cbeff 100644 --- a/tests/unit/agent-document-tools.test.ts +++ b/tests/unit/agent-document-tools.test.ts @@ -62,21 +62,32 @@ describe("agent document tools", () => { 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", { query: "booking" })).toMatch(new RegExp(`^Booking PRD \\(doc_id=${docId}, prd, draft, v1, \\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.startsWith("Booking PRD (prd, draft, v1 of 1)\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: "Requirement 1: rebooking", reason: "Scope cut" })).toBe(`Updated document "Booking PRD" to v2 (doc_id=${docId}).`); + expect(h.run("read_document", { doc_id: docId })).toBe("Booking PRD (prd, draft, v2 of 2)\n\nRequirement 1: rebooking"); + expect(h.run("read_document", { doc_id: docId, version: 1, search: "Requirement 2999:" })).toContain("v1 of 2"); + expect(h.run("read_document", { doc_id: docId, version: 1, search: "Requirement 2999:" })).toContain("2999: Requirement 2999: booking flow"); + expect(h.run("read_document", { doc_id: docId, history: true })).toMatch(/^v1 .* by agent agt_\w+ — created \(\d+ chars\)\nv2 .* by agent agt_\w+ — Scope cut \(24 chars\)$/); + expect(h.run("read_document", { doc_id: docId, version: 3 })).toBe('ERROR: "version" must be a whole number from 1 to 2.'); + expect(h.run("read_document", { doc_id: docId, history: "yes" })).toBe('ERROR: "history" must be true or false.'); + expect(h.run("read_document", { doc_id: docId, history: true, version: 0 })).toBe("ERROR: history=true lists versions; it takes no version or paging arguments."); + expect(h.run("read_document", { doc_id: docId, history: true, search: 123 })).toBe('ERROR: "search" is required.'); 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.db.prepare("delete from documents where id = ?").run(docId); + expect(h.run("read_document", { doc_id: docId, history: true }).split("\n")).toHaveLength(2); + expect(h.run("read_document", { doc_id: docId, version: 1, line_count: 1 })).toMatch(/^Booking PRD \(deleted, draft, v1 of 2\)/); h.connection.close(); }); diff --git a/tests/unit/document-versions.test.ts b/tests/unit/document-versions.test.ts new file mode 100644 index 00000000..069fe7b1 --- /dev/null +++ b/tests/unit/document-versions.test.ts @@ -0,0 +1,48 @@ +import { randomUUID } from "node:crypto"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { DatabaseSync } from "node:sqlite"; +import { describe, expect, test } from "vitest"; +import { DatabaseConnection } from "../../src/main/database/connection"; +import { OrganizationService } from "../../src/main/services/organization-service"; +import { DocumentService } from "../../src/main/services/document-service"; +import { documentVersionsSchema } from "../../src/main/database/migrations/065-document-versions"; + +describe("document versions", () => { + test("every update is a new version; earlier versions stay intact, even after deletion", () => { + const connection = new DatabaseConnection(join(tmpdir(), `ac-docver-${randomUUID()}.db`)); + let orgId = ""; + connection.transaction(() => { + orgId = new OrganizationService(connection.db).createOrganization({ organizationName: "V", employeeName: "Y", mission: "m", goal: "g" }); + }); + const documents = new DocumentService(connection.db); + const id = documents.create({ orgId, title: "Spec", docType: "spec", content: "v1 body", authorAgentId: null, reviewerAgentId: null, projectId: null, goalId: null, taskId: null }); + expect(documents.update({ orgId, documentId: id, title: "Spec", content: "v2 body", status: "review", reason: "Added API", changedByType: "employee", changedById: null })).toBe(2); + expect(() => documents.update({ orgId, documentId: id, title: "Spec", content: "v3", status: "review", reason: " ", changedByType: "employee", changedById: null })) + .toThrow("A document update needs a reason."); + expect(documents.versions(orgId, id).map((v) => [v.version, v.content, v.status, v.reason])).toEqual([ + [1, "v1 body", "draft", "created"], + [2, "v2 body", "review", "Added API"], + ]); + expect(connection.db.prepare("select version, content from documents where id = ?").get(id)).toEqual({ version: 2, content: "v2 body" }); + documents.delete({ orgId, documentId: id }); + expect(documents.versions(orgId, id)).toHaveLength(2); + connection.close(); + }); + + test("the migration records each existing document as version 1", () => { + const db = new DatabaseSync(join(tmpdir(), `ac-docmig-${randomUUID()}.db`)); + db.exec(` + create table organizations(id text primary key); + create table schema_migrations(version integer primary key, name text not null, applied_at text not null); + create table documents(id text primary key, org_id text, title text, content text, status text, author_agent_id text, created_at text); + insert into organizations values ('org_1'); + insert into documents values ('doc_1', 'org_1', 'T', 'C', 'approved', 'agt_1', '2026-01-01T00:00:00.000Z'); + `); + db.exec(documentVersionsSchema); + expect(db.prepare("select document_id, version, content, status, changed_by_type, changed_by_id, reason from document_versions").all()) + .toEqual([{ document_id: "doc_1", version: 1, content: "C", status: "approved", changed_by_type: "agent", changed_by_id: "agt_1", reason: "created" }]); + expect(db.prepare("select version from documents").get()).toEqual({ version: 1 }); + db.close(); + }); +}); diff --git a/tests/unit/domain-services.test.ts b/tests/unit/domain-services.test.ts index 9bf96806..666cb81a 100644 --- a/tests/unit/domain-services.test.ts +++ b/tests/unit/domain-services.test.ts @@ -24,7 +24,7 @@ describe("domain services", () => { const connection = createConnection(); const rows = connection.db.prepare("select version from schema_migrations order by version asc").all() as Array<{ version: number }>; - expect(rows.map((row) => row.version)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64]); + expect(rows.map((row) => row.version)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65]); connection.close(); });