@agentplate/cli 1.0.0

package/src/mail/client.test.ts

@@ -0,0 +1,192 @@
+// Tests for the high-level mail client. Uses a REAL temp project root and a REAL
+// SQLite mail database (no mocks) per the project's testing philosophy: the only
+// thing we exercise is observable client behavior, so the underlying store runs for
+// real against a throwaway file.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createMailClient, resolveRecipients } from "./client.ts";
+
+let root: string;
+let client: ReturnType<typeof createMailClient>;
+
+beforeEach(() => {
+	// A fresh temp project root with the .agentplate dir the client expects.
+	root = mkdtempSync(join(tmpdir(), "agentplate-mail-"));
+	mkdirSync(join(root, ".agentplate"), { recursive: true });
+	client = createMailClient(root);
+});
+
+afterEach(() => {
+	client.close();
+	rmSync(root, { recursive: true, force: true });
+});
+
+describe("createMailClient", () => {
+	test("rejects an empty root", () => {
+		expect(() => createMailClient("")).toThrow();
+		expect(() => createMailClient("   ")).toThrow();
+	});
+
+	test("send then check returns the message as unread", () => {
+		const sent = client.send({
+			from: "orchestrator",
+			to: "builder-1",
+			subject: "start",
+			body: "begin task",
+			type: "dispatch",
+		});
+
+		expect(sent.id).toBeTruthy();
+
+		const inbox = client.check("builder-1");
+		expect(inbox.length).toBe(1);
+		expect(inbox[0]?.id).toBe(sent.id);
+
+		const unread = client.check("builder-1", { unreadOnly: true });
+		expect(unread.length).toBe(1);
+		expect(unread[0]?.read).toBe(false);
+	});
+
+	test("check only returns the addressed agent's mail", () => {
+		client.send({ from: "a", to: "builder-1", subject: "s1", body: "b1", type: "status" });
+		client.send({ from: "a", to: "builder-2", subject: "s2", body: "b2", type: "status" });
+
+		expect(client.check("builder-1").length).toBe(1);
+		expect(client.check("builder-2").length).toBe(1);
+		expect(client.check("nobody").length).toBe(0);
+	});
+
+	test("checkInject formats unread mail and marks it read", () => {
+		client.send({
+			from: "scout-1",
+			to: "lead",
+			subject: "found it",
+			body: "the bug is in foo.ts",
+			type: "result",
+		});
+		client.send({
+			from: "scout-2",
+			to: "lead",
+			subject: "second",
+			body: "also check bar.ts",
+			type: "status",
+		});
+
+		const block = client.checkInject("lead");
+
+		// Header reflects the count.
+		expect(block).toContain("You have 2 new message(s):");
+		// Per-message metadata is present.
+		expect(block).toContain("From: scout-1");
+		expect(block).toContain("Subject: found it");
+		expect(block).toContain("Type: result");
+		// Bodies are included.
+		expect(block).toContain("the bug is in foo.ts");
+		expect(block).toContain("also check bar.ts");
+
+		// Side effect: the injected mail is now read, so a second inject is empty...
+		expect(client.checkInject("lead")).toBe("");
+		// ...and an unread-only check confirms nothing remains unread.
+		expect(client.check("lead", { unreadOnly: true }).length).toBe(0);
+		// The messages still exist (read, not deleted).
+		expect(client.check("lead").length).toBe(2);
+	});
+
+	test("checkInject returns empty string when there is no unread mail", () => {
+		expect(client.checkInject("ghost")).toBe("");
+	});
+
+	test("reply keeps the conversation in the same thread", () => {
+		const original = client.send({
+			from: "builder-1",
+			to: "lead",
+			subject: "question",
+			body: "which branch?",
+			type: "question",
+		});
+
+		// The store's reply takes the replying agent as the third argument and routes
+		// the reply back to the original sender.
+		const replied = client.reply(original.id, "use main", "lead");
+
+		// The reply is a real, distinct message.
+		expect(replied.id).toBeTruthy();
+		expect(replied.id).not.toBe(original.id);
+		// It is addressed back to the original sender.
+		expect(replied.to).toBe("builder-1");
+		expect(replied.from).toBe("lead");
+
+		// It belongs to the same thread as the original. The original started a new
+		// thread (threadId === null), so the store adopts the original's id as the
+		// shared thread root.
+		const expectedThread = original.threadId ?? original.id;
+		expect(replied.threadId).toBe(expectedThread);
+
+		// The original sender now has the reply waiting (unread).
+		const builderInbox = client.check("builder-1", { unreadOnly: true });
+		expect(builderInbox.some((m) => m.id === replied.id)).toBe(true);
+	});
+
+	test("markRead marks a single message read", () => {
+		const sent = client.send({
+			from: "a",
+			to: "builder-9",
+			subject: "s",
+			body: "b",
+			type: "status",
+		});
+		expect(client.check("builder-9", { unreadOnly: true }).length).toBe(1);
+
+		client.markRead(sent.id);
+		expect(client.check("builder-9", { unreadOnly: true }).length).toBe(0);
+		// Still present, just read.
+		expect(client.check("builder-9").length).toBe(1);
+	});
+
+	test("list is a passthrough to the store", () => {
+		client.send({ from: "a", to: "x", subject: "s", body: "b", type: "status" });
+		client.send({ from: "a", to: "y", subject: "s", body: "b", type: "status" });
+		expect(client.list().length).toBe(2);
+		expect(client.list({ to: "x" }).length).toBe(1);
+	});
+
+	test("purge removes messages and reports the count", () => {
+		client.send({ from: "a", to: "x", subject: "s", body: "b", type: "status" });
+		client.send({ from: "a", to: "y", subject: "s", body: "b", type: "status" });
+
+		const removed = client.purge({ all: true });
+		expect(removed).toBe(2);
+		expect(client.list().length).toBe(0);
+	});
+});
+
+describe("resolveRecipients", () => {
+	test("expands @all to every known agent", () => {
+		const agents = ["builder-1", "scout-1", "lead"];
+		expect(client.resolveRecipients("@all", agents)).toEqual(agents);
+		// Pure helper behaves identically.
+		expect(resolveRecipients("@all", agents)).toEqual(agents);
+	});
+
+	test("@all de-duplicates and drops blanks", () => {
+		expect(resolveRecipients("@all", ["a", "a", "", "  ", "b"])).toEqual(["a", "b"]);
+	});
+
+	test("@all over an empty roster yields no recipients", () => {
+		expect(resolveRecipients("@all", [])).toEqual([]);
+	});
+
+	test("a concrete address routes to itself", () => {
+		expect(resolveRecipients("builder-1", ["builder-1", "scout-1"])).toEqual(["builder-1"]);
+		// Unknown-but-concrete addresses still route to themselves (roster is advisory).
+		expect(resolveRecipients("ghost", ["builder-1"])).toEqual(["ghost"]);
+	});
+
+	test("trims surrounding whitespace on the address", () => {
+		expect(resolveRecipients("  builder-1  ", [])).toEqual(["builder-1"]);
+	});
+});

package/src/mail/client.ts

@@ -0,0 +1,188 @@
+// High-level mail client. Wraps the low-level SQLite mail store (createMailStore)
+// with the operations the orchestrator and agents actually use: sending, checking
+// an inbox, formatting unread mail for prompt injection, threading replies, and
+// expanding broadcast recipients like "@all".
+//
+// WHY a separate layer over the store: the store is intentionally a thin,
+// schema-faithful persistence API (rows in/rows out). The ergonomics callers want
+// -- "give me an injectable markdown block of my unread mail and mark it read", or
+// "expand @all into the live agent list" -- are policy, not storage, so they live
+// here. This keeps the store reusable and unopinionated.
+
+import { join } from "node:path";
+
+import { AGENTPLATE_DIR } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import type { MailMessage, NewMail } from "../types.ts";
+import { createMailStore, type MailListFilter, type MailPurgeOptions } from "./store.ts";
+
+// Broadcast sentinel: a recipient address that fans out to every known agent.
+// Mirrors the agentplate mail convention. Kept as a single constant so the
+// expansion rule and any future group sentinels have one source of truth.
+const BROADCAST_ALL = "@all";
+
+/** Optional filters when checking an inbox. */
+export interface CheckOptions {
+	/** Return only unread messages (default: all). */
+	unreadOnly?: boolean;
+}
+
+/** The high-level mail client surface returned by {@link createMailClient}. */
+export interface MailClient {
+	/** Persist a new message. Delegates to the store. */
+	send(mail: NewMail): MailMessage;
+	/** Messages addressed to `agent`, newest first (optionally unread-only). */
+	check(agent: string, opts?: CheckOptions): MailMessage[];
+	/**
+	 * Format an agent's UNREAD messages as a compact markdown block suitable for
+	 * injecting into the agent's prompt, THEN mark those messages read. Returns ""
+	 * when there is nothing unread. The mark-as-read side effect is intentional:
+	 * once mail is in the prompt it is considered delivered, so a later inject for
+	 * the same agent won't re-surface it.
+	 */
+	checkInject(agent: string): string;
+	/** List messages with optional filters (passthrough to the store). */
+	list(filter?: MailListFilter): MailMessage[];
+	/**
+	 * Reply to a message in the same thread. `from` is the replying agent; the
+	 * store routes the reply back to the original sender. Passthrough to the store.
+	 */
+	reply(id: string, body: string, from: string): MailMessage;
+	/** Mark a single message read (passthrough). */
+	markRead(id: string): void;
+	/** Delete messages per the given criteria; returns how many were removed. */
+	purge(opts?: MailPurgeOptions): number;
+	/**
+	 * Expand a recipient address against the live agent roster. "@all" becomes the
+	 * full `knownAgents` list; any other address is returned as a single recipient.
+	 */
+	resolveRecipients(to: string, knownAgents: string[]): string[];
+	/** Close the underlying database handle. */
+	close(): void;
+}
+
+/**
+ * Create a mail client rooted at a project directory. Opens (and owns) the mail
+ * database at `<root>/.agentplate/mail.db`.
+ *
+ * @param root Absolute path to the project root containing `.agentplate/`.
+ */
+export function createMailClient(root: string): MailClient {
+	if (!root || root.trim().length === 0) {
+		throw new ValidationError("createMailClient requires a non-empty project root");
+	}
+
+	const dbPath = join(root, AGENTPLATE_DIR, "mail.db");
+	const store = createMailStore(dbPath);
+
+	function check(agent: string, opts?: CheckOptions): MailMessage[] {
+		const recipient = normalizeAgent(agent);
+		// Let the store filter on both recipient and (optionally) unread so we lean on
+		// its indexed query rather than re-implementing the predicate. The store treats
+		// an absent `unread` filter as "all", which matches our default.
+		const filter: MailListFilter = { to: recipient };
+		if (opts?.unreadOnly) {
+			filter.unread = true;
+		}
+		return store.list(filter);
+	}
+
+	function checkInject(agent: string): string {
+		const unread = check(agent, { unreadOnly: true });
+		if (unread.length === 0) {
+			return "";
+		}
+
+		const block = formatInjection(unread);
+
+		// Mark each injected message read AFTER formatting, so a failure mid-format
+		// does not silently consume mail the agent never saw.
+		for (const message of unread) {
+			store.markRead(message.id);
+		}
+
+		return block;
+	}
+
+	return {
+		send(mail: NewMail): MailMessage {
+			return store.send(mail);
+		},
+		check,
+		checkInject,
+		list(filter?: MailListFilter): MailMessage[] {
+			return store.list(filter);
+		},
+		reply(id: string, body: string, from: string): MailMessage {
+			return store.reply(id, body, from);
+		},
+		markRead(id: string): void {
+			store.markRead(id);
+		},
+		purge(opts?: MailPurgeOptions): number {
+			return store.purge(opts);
+		},
+		resolveRecipients(to: string, knownAgents: string[]): string[] {
+			return resolveRecipients(to, knownAgents);
+		},
+		close(): void {
+			store.close();
+		},
+	};
+}
+
+/**
+ * Expand a recipient address. "@all" fans out to every known agent (de-duplicated,
+ * blanks dropped); any other address routes to itself. Exported as a pure helper so
+ * callers (and tests) can use the expansion rule without opening a database.
+ */
+export function resolveRecipients(to: string, knownAgents: string[]): string[] {
+	const target = normalizeAgent(to);
+	if (target === BROADCAST_ALL) {
+		// Dedupe while preserving roster order; skip blank entries defensively.
+		const seen = new Set<string>();
+		const expanded: string[] = [];
+		for (const agent of knownAgents) {
+			const name = agent.trim();
+			if (name.length === 0 || seen.has(name)) {
+				continue;
+			}
+			seen.add(name);
+			expanded.push(name);
+		}
+		return expanded;
+	}
+	return [target];
+}
+
+/** Trim and validate an agent/recipient identifier. */
+function normalizeAgent(agent: string): string {
+	const name = agent?.trim();
+	if (!name) {
+		throw new ValidationError("mail recipient must be a non-empty string");
+	}
+	return name;
+}
+
+/**
+ * Render unread messages as a compact markdown block for prompt injection.
+ * Shape (per the agent mail convention):
+ *
+ *   You have 2 new message(s):
+ *
+ *   1. From: alice | Subject: build done | Type: status
+ *      <body>
+ *
+ *   2. From: bob | ...
+ */
+function formatInjection(messages: MailMessage[]): string {
+	const header = `You have ${messages.length} new message(s):`;
+	const entries = messages.map((m, index) => {
+		const meta = `${index + 1}. From: ${m.from} | Subject: ${m.subject} | Type: ${m.type}`;
+		// Indent the body two spaces so it reads as part of the numbered item; a blank
+		// body (allowed by the schema) just omits the body line.
+		const indentedBody = m.body.length > 0 ? `\n   ${m.body.split("\n").join("\n   ")}` : "";
+		return `${meta}${indentedBody}`;
+	});
+	return `${header}\n\n${entries.join("\n\n")}`;
+}

package/src/mail/store.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Tests for the low-level SQLite mail store.
+ *
+ * Uses a real temp-file SQLite database (not a mock and not `:memory:`) so the
+ * tests exercise the same WAL-mode file path agents use in production. Each test
+ * gets a fresh file via beforeEach/afterEach.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openDatabase } from "../db/sqlite.ts";
+import { NotFoundError, ValidationError } from "../errors.ts";
+import type { NewMail } from "../types.ts";
+import { createMailStore, type MailStore } from "./store.ts";
+
+/** Minimal valid NewMail with overridable fields. */
+function newMail(overrides: Partial<NewMail> = {}): NewMail {
+	return {
+		from: "alice",
+		to: "bob",
+		subject: "hello",
+		body: "world",
+		type: "status",
+		...overrides,
+	};
+}
+
+describe("mail store", () => {
+	let tmpRoot: string;
+	let dbPath: string;
+	let store: MailStore;
+
+	beforeEach(() => {
+		tmpRoot = mkdtempSync(join(tmpdir(), "agentplate-mail-"));
+		dbPath = join(tmpRoot, "mail.db");
+		store = createMailStore(dbPath);
+	});
+
+	afterEach(() => {
+		store.close();
+		rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	describe("send", () => {
+		test("assigns id, createdAt, read=false and default priority/threadId", () => {
+			const msg = store.send(newMail());
+			expect(msg.id).toBeTruthy();
+			expect(msg.read).toBe(false);
+			expect(msg.priority).toBe("normal");
+			expect(msg.threadId).toBeNull();
+			expect(msg.payload).toBeNull();
+			// createdAt is an ISO-8601 string the Date constructor round-trips.
+			expect(new Date(msg.createdAt).toISOString()).toBe(msg.createdAt);
+		});
+
+		test("assigns unique ids across sends", () => {
+			const a = store.send(newMail());
+			const b = store.send(newMail());
+			expect(a.id).not.toBe(b.id);
+		});
+
+		test("honors explicit priority, threadId and payload", () => {
+			const msg = store.send(
+				newMail({ priority: "urgent", threadId: "thread-1", payload: '{"k":1}' }),
+			);
+			expect(msg.priority).toBe("urgent");
+			expect(msg.threadId).toBe("thread-1");
+			expect(msg.payload).toBe('{"k":1}');
+		});
+
+		test("persists across a reopen of the same db file", () => {
+			const sent = store.send(newMail({ subject: "persisted" }));
+			store.close();
+			const reopened = createMailStore(dbPath);
+			try {
+				const fetched = reopened.getById(sent.id);
+				expect(fetched?.subject).toBe("persisted");
+			} finally {
+				reopened.close();
+			}
+		});
+
+		test("rejects empty to/from addresses", () => {
+			expect(() => store.send(newMail({ to: "" }))).toThrow(ValidationError);
+			expect(() => store.send(newMail({ from: "  " }))).toThrow(ValidationError);
+		});
+	});
+
+	describe("getInbox", () => {
+		test("returns only messages addressed to the agent, newest first", () => {
+			store.send(newMail({ to: "bob", subject: "first" }));
+			store.send(newMail({ to: "carol", subject: "other" }));
+			const second = store.send(newMail({ to: "bob", subject: "second" }));
+
+			const inbox = store.getInbox("bob");
+			expect(inbox).toHaveLength(2);
+			// Newest first: the last "bob" message leads.
+			expect(inbox[0]?.id).toBe(second.id);
+			expect(inbox.every((m) => m.to === "bob")).toBe(true);
+		});
+
+		test("unreadOnly filters out read messages", () => {
+			const a = store.send(newMail({ to: "bob" }));
+			store.send(newMail({ to: "bob" }));
+			store.markRead(a.id);
+
+			const unread = store.getInbox("bob", { unreadOnly: true });
+			expect(unread).toHaveLength(1);
+			expect(unread[0]?.read).toBe(false);
+
+			// Without the filter, both messages come back.
+			expect(store.getInbox("bob")).toHaveLength(2);
+		});
+
+		test("returns an empty array for an unknown agent", () => {
+			expect(store.getInbox("nobody")).toEqual([]);
+		});
+	});
+
+	describe("markRead / getById", () => {
+		test("markRead flips the read flag", () => {
+			const msg = store.send(newMail());
+			expect(store.getById(msg.id)?.read).toBe(false);
+			store.markRead(msg.id);
+			expect(store.getById(msg.id)?.read).toBe(true);
+		});
+
+		test("markRead on a missing id is a no-op", () => {
+			expect(() => store.markRead("does-not-exist")).not.toThrow();
+		});
+
+		test("getById returns null for a missing id", () => {
+			expect(store.getById("missing")).toBeNull();
+		});
+	});
+
+	describe("reply", () => {
+		test("starts a thread from a thread-less original (adopts original id)", () => {
+			const original = store.send(newMail({ from: "alice", to: "bob", subject: "ping" }));
+			const reply = store.reply(original.id, "pong", "bob");
+
+			expect(reply.threadId).toBe(original.id);
+			expect(reply.to).toBe("alice"); // routed back to the sender
+			expect(reply.from).toBe("bob");
+			expect(reply.type).toBe("result");
+			expect(reply.subject).toBe("ping"); // inherits the subject
+		});
+
+		test("propagates an existing threadId across replies", () => {
+			const original = store.send(newMail({ from: "alice", to: "bob", threadId: "t-42" }));
+			const reply = store.reply(original.id, "re", "bob");
+			expect(reply.threadId).toBe("t-42");
+
+			// A reply to the reply stays on the same thread.
+			const second = store.reply(reply.id, "re re", "alice");
+			expect(second.threadId).toBe("t-42");
+			expect(second.to).toBe("bob");
+		});
+
+		test("throws NotFoundError when the original is missing", () => {
+			expect(() => store.reply("missing", "body", "bob")).toThrow(NotFoundError);
+		});
+	});
+
+	describe("list", () => {
+		beforeEach(() => {
+			store.send(newMail({ from: "alice", to: "bob", subject: "a" }));
+			store.send(newMail({ from: "carol", to: "bob", subject: "b" }));
+			store.send(newMail({ from: "alice", to: "dave", subject: "c" }));
+		});
+
+		test("filters by from", () => {
+			const fromAlice = store.list({ from: "alice" });
+			expect(fromAlice).toHaveLength(2);
+			expect(fromAlice.every((m) => m.from === "alice")).toBe(true);
+		});
+
+		test("filters by to", () => {
+			const toBob = store.list({ to: "bob" });
+			expect(toBob).toHaveLength(2);
+			expect(toBob.every((m) => m.to === "bob")).toBe(true);
+		});
+
+		test("combines from + to filters", () => {
+			const combined = store.list({ from: "alice", to: "bob" });
+			expect(combined).toHaveLength(1);
+			expect(combined[0]?.subject).toBe("a");
+		});
+
+		test("filters by unread", () => {
+			const all = store.list();
+			expect(all).toHaveLength(3);
+			const first = all[0];
+			expect(first).toBeDefined();
+			if (first) store.markRead(first.id);
+
+			expect(store.list({ unread: true })).toHaveLength(2);
+			expect(store.list({ unread: false })).toHaveLength(1);
+		});
+
+		test("applies a limit (newest first)", () => {
+			const limited = store.list({ limit: 2 });
+			expect(limited).toHaveLength(2);
+			// The most recently inserted message ("c") should lead.
+			expect(limited[0]?.subject).toBe("c");
+		});
+
+		test("with no filter returns everything", () => {
+			expect(store.list()).toHaveLength(3);
+		});
+	});
+
+	describe("purge", () => {
+		test("all deletes every message and reports the count", () => {
+			store.send(newMail());
+			store.send(newMail());
+			expect(store.purge({ all: true })).toBe(2);
+			expect(store.list()).toHaveLength(0);
+		});
+
+		test("agent deletes messages the agent sent or received", () => {
+			store.send(newMail({ from: "alice", to: "bob" }));
+			store.send(newMail({ from: "carol", to: "alice" }));
+			store.send(newMail({ from: "carol", to: "dave" }));
+
+			const deleted = store.purge({ agent: "alice" });
+			expect(deleted).toBe(2);
+
+			const remaining = store.list();
+			expect(remaining).toHaveLength(1);
+			expect(remaining[0]?.from).toBe("carol");
+			expect(remaining[0]?.to).toBe("dave");
+		});
+
+		test("olderThanDays deletes only sufficiently old messages", () => {
+			const fresh = store.send(newMail({ subject: "fresh" }));
+			const old = store.send(newMail({ subject: "old" }));
+
+			// Backdate the "old" message 30 days into the past by writing created_at
+			// directly. We use a real second connection to the same file (allowed —
+			// these are real-SQLite tests, no mocks) because the public API
+			// intentionally has no "set timestamp" surface.
+			const backdated = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+			const raw = openDatabase(dbPath);
+			try {
+				raw.query("UPDATE messages SET created_at = $ts WHERE id = $id").run({
+					$ts: backdated,
+					$id: old.id,
+				});
+			} finally {
+				raw.close();
+			}
+
+			// Purge anything older than 7 days: only the backdated message qualifies.
+			expect(store.purge({ olderThanDays: 7 })).toBe(1);
+			expect(store.getById(old.id)).toBeNull();
+			expect(store.getById(fresh.id)).not.toBeNull();
+
+			// A 10-year window now matches nothing (the only old row is gone).
+			expect(store.purge({ olderThanDays: 3650 })).toBe(0);
+		});
+
+		test("with no options deletes nothing (all flag required to wipe)", () => {
+			store.send(newMail());
+			expect(store.purge()).toBe(0);
+			expect(store.purge({})).toBe(0);
+			expect(store.list()).toHaveLength(1);
+		});
+
+		test("combines olderThanDays + agent (returns 0 when nothing matches)", () => {
+			store.send(newMail({ from: "alice", to: "bob", subject: "recent" }));
+			// Nothing is both old AND involving zoe, so count is 0 and the row stays.
+			expect(store.purge({ olderThanDays: 1, agent: "zoe" })).toBe(0);
+			expect(store.list()).toHaveLength(1);
+		});
+	});
+});