@ag-eco/agentplate-cli 0.13.0

package/src/agents/lifecycle.ts

@@ -0,0 +1,183 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { LifecycleError } from "../errors.ts";
+import type { SessionCheckpoint, SessionHandoff } from "../types.ts";
+import { clearCheckpoint, loadCheckpoint, saveCheckpoint } from "./checkpoint.ts";
+
+const HANDOFFS_FILENAME = "handoffs.json";
+
+/**
+ * Load handoffs array from disk.
+ * Returns an empty array if the file doesn't exist.
+ */
+async function loadHandoffs(agentsDir: string, agentName: string): Promise<SessionHandoff[]> {
+	const filePath = join(agentsDir, agentName, HANDOFFS_FILENAME);
+	const file = Bun.file(filePath);
+	const exists = await file.exists();
+
+	if (!exists) {
+		return [];
+	}
+
+	try {
+		const text = await file.text();
+		return JSON.parse(text) as SessionHandoff[];
+	} catch (err) {
+		throw new LifecycleError(`Failed to read handoffs: ${filePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}
+
+/**
+ * Write handoffs array to disk.
+ */
+async function writeHandoffs(
+	agentsDir: string,
+	agentName: string,
+	handoffs: SessionHandoff[],
+): Promise<void> {
+	const filePath = join(agentsDir, agentName, HANDOFFS_FILENAME);
+	const dir = dirname(filePath);
+
+	try {
+		await mkdir(dir, { recursive: true });
+	} catch (err) {
+		throw new LifecycleError(`Failed to create handoffs directory: ${dir}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		await Bun.write(filePath, `${JSON.stringify(handoffs, null, "\t")}\n`);
+	} catch (err) {
+		throw new LifecycleError(`Failed to write handoffs: ${filePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}
+
+/**
+ * Initiate a session handoff.
+ *
+ * 1. Builds a SessionCheckpoint from options
+ * 2. Saves the checkpoint to disk
+ * 3. Builds a SessionHandoff record
+ * 4. Appends to handoffs.json
+ * 5. Returns the handoff
+ */
+export async function initiateHandoff(options: {
+	agentsDir: string;
+	agentName: string;
+	sessionId: string;
+	taskId: string;
+	reason: SessionHandoff["reason"];
+	progressSummary: string;
+	pendingWork: string;
+	currentBranch: string;
+	filesModified: string[];
+	loamDomains: string[];
+}): Promise<SessionHandoff> {
+	const checkpoint: SessionCheckpoint = {
+		agentName: options.agentName,
+		taskId: options.taskId,
+		sessionId: options.sessionId,
+		timestamp: new Date().toISOString(),
+		progressSummary: options.progressSummary,
+		filesModified: options.filesModified,
+		currentBranch: options.currentBranch,
+		pendingWork: options.pendingWork,
+		loamDomains: options.loamDomains,
+	};
+
+	await saveCheckpoint(options.agentsDir, checkpoint);
+
+	const handoff: SessionHandoff = {
+		fromSessionId: options.sessionId,
+		toSessionId: null,
+		checkpoint,
+		reason: options.reason,
+		handoffAt: new Date().toISOString(),
+	};
+
+	const handoffs = await loadHandoffs(options.agentsDir, options.agentName);
+	handoffs.push(handoff);
+	await writeHandoffs(options.agentsDir, options.agentName, handoffs);
+
+	return handoff;
+}
+
+/**
+ * Resume from a pending handoff.
+ *
+ * Finds the most recent handoff where `toSessionId` is null,
+ * loads the associated checkpoint, and returns both.
+ * Returns null if no pending handoff exists.
+ */
+export async function resumeFromHandoff(options: {
+	agentsDir: string;
+	agentName: string;
+}): Promise<{ checkpoint: SessionCheckpoint; handoff: SessionHandoff } | null> {
+	const handoffs = await loadHandoffs(options.agentsDir, options.agentName);
+
+	// Find most recent pending handoff (search from end)
+	let pendingHandoff: SessionHandoff | undefined;
+	for (let i = handoffs.length - 1; i >= 0; i--) {
+		const h = handoffs[i];
+		if (h !== undefined && h.toSessionId === null) {
+			pendingHandoff = h;
+			break;
+		}
+	}
+
+	if (pendingHandoff === undefined) {
+		return null;
+	}
+
+	const checkpoint = await loadCheckpoint(options.agentsDir, options.agentName);
+	if (checkpoint === null) {
+		return null;
+	}
+
+	return { checkpoint, handoff: pendingHandoff };
+}
+
+/**
+ * Complete a pending handoff.
+ *
+ * 1. Loads handoffs.json
+ * 2. Finds the most recent handoff with toSessionId === null
+ * 3. Sets toSessionId to the new session ID
+ * 4. Writes back handoffs.json
+ * 5. Clears the checkpoint
+ */
+export async function completeHandoff(options: {
+	agentsDir: string;
+	agentName: string;
+	newSessionId: string;
+}): Promise<void> {
+	const handoffs = await loadHandoffs(options.agentsDir, options.agentName);
+
+	// Find most recent pending handoff (search from end)
+	let found = false;
+	for (let i = handoffs.length - 1; i >= 0; i--) {
+		const h = handoffs[i];
+		if (h !== undefined && h.toSessionId === null) {
+			h.toSessionId = options.newSessionId;
+			found = true;
+			break;
+		}
+	}
+
+	if (!found) {
+		throw new LifecycleError("No pending handoff to complete", {
+			agentName: options.agentName,
+		});
+	}
+
+	await writeHandoffs(options.agentsDir, options.agentName, handoffs);
+	await clearCheckpoint(options.agentsDir, options.agentName);
+}

package/src/agents/mail-poll-detect.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+import { detectMailPollPattern } from "./mail-poll-detect.ts";
+
+describe("detectMailPollPattern", () => {
+	describe("matched patterns", () => {
+		test("until ap mail list with sleep body", () => {
+			const result = detectMailPollPattern("until ap mail list; do sleep 1; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ap mail loop");
+		});
+
+		test("while ! ap mail check with sleep body", () => {
+			const result = detectMailPollPattern("while ! ap mail check; do sleep 5; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("while-not ap mail loop");
+		});
+
+		test("while ! ap mail list --unread with sleep body", () => {
+			const result = detectMailPollPattern("while ! ap mail list --unread; do sleep 2; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("while-not ap mail loop");
+		});
+
+		test("until ap mail check with extra args and sleep body", () => {
+			const result = detectMailPollPattern("until ap mail check --agent foo; do sleep 1; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ap mail loop");
+		});
+
+		test("until [ ... $(ap mail list ... | wc -l) ... ] piped condition", () => {
+			const result = detectMailPollPattern(
+				`until [ "$(ap mail list --unread | wc -l)" -gt 0 ]; do sleep 1; done`,
+			);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("ap mail piped condition");
+		});
+
+		test("while [ -z $(ap mail check | jq) ] piped condition", () => {
+			const result = detectMailPollPattern(
+				`while [ -z "$(ap mail check | jq '.id')" ]; do sleep 2; done`,
+			);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("ap mail piped condition");
+		});
+
+		test("multi-line with leading whitespace and tabs is detected", () => {
+			const cmd = "\t\tuntil ap mail list;\n\t\tdo\n\t\t\tsleep 1;\n\t\tdone";
+			const result = detectMailPollPattern(cmd);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ap mail loop");
+		});
+
+		test("multi-line newline-separated (no semicolons before do/done) is detected", () => {
+			const cmd = "until ap mail list\ndo\n  sleep 1\ndone";
+			const result = detectMailPollPattern(cmd);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ap mail loop");
+		});
+
+		test("while loop with negated ap mail and pipe-through is the piped variant", () => {
+			// `while [ ... ]` (no `!`) with `ap mail` substituted inside the test
+			// expression is the piped form, not while-not.
+			const result = detectMailPollPattern(
+				`while [ "$(ap mail list --unread --json)" = "[]" ]; do sleep 3; done`,
+			);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("ap mail piped condition");
+		});
+
+		test("until with extra padding around ! does not derail kind detection", () => {
+			// Note: `until !` is unusual but the spec says `!` may have surrounding
+			// spaces; we only assert that `until` direct form still classifies.
+			const result = detectMailPollPattern("until   ap mail check  ;  do  sleep 1 ;  done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ap mail loop");
+		});
+
+		test("while !ap (no space after !) still classifies as while-not", () => {
+			const result = detectMailPollPattern("while !ap mail check; do sleep 1; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("while-not ap mail loop");
+		});
+	});
+
+	describe("not matched", () => {
+		test("ap mail check (no loop wrapper)", () => {
+			expect(detectMailPollPattern("ap mail check").matched).toBe(false);
+		});
+
+		test("ap mail list --unread --json (no loop wrapper)", () => {
+			expect(detectMailPollPattern("ap mail list --unread --json").matched).toBe(false);
+		});
+
+		test("for loop sending mail (bounded, not a wait-poll)", () => {
+			const cmd =
+				"for i in 1 2 3; do ap mail send --to lead --subject hi --body x --type status; done";
+			expect(detectMailPollPattern(cmd).matched).toBe(false);
+		});
+
+		test("while read line over a file (no ap mail reference)", () => {
+			expect(detectMailPollPattern("while read line; do echo $line; done < file.txt").matched).toBe(
+				false,
+			);
+		});
+
+		test("until-loop with ap mail in condition but no sleep in body (not a poll)", () => {
+			// Without `sleep` the body is a one-shot reaction, not a wait-poll.
+			expect(detectMailPollPattern("until ap mail check; do echo got-mail; done").matched).toBe(
+				false,
+			);
+		});
+
+		test("non-string command (undefined) returns matched=false without throwing", () => {
+			expect(() => detectMailPollPattern(undefined)).not.toThrow();
+			expect(detectMailPollPattern(undefined).matched).toBe(false);
+		});
+
+		test("non-string command (null) returns matched=false", () => {
+			expect(detectMailPollPattern(null).matched).toBe(false);
+		});
+
+		test("non-string command (number) returns matched=false", () => {
+			expect(detectMailPollPattern(42).matched).toBe(false);
+		});
+
+		test("empty string returns matched=false", () => {
+			expect(detectMailPollPattern("").matched).toBe(false);
+		});
+
+		test("for loop with sleep but no ap mail reference is not a poll", () => {
+			expect(detectMailPollPattern("for i in 1 2 3; do sleep 1; echo hi; done").matched).toBe(
+				false,
+			);
+		});
+	});
+
+	describe("regex statefulness", () => {
+		test("repeated calls return consistent results (no lastIndex leakage)", () => {
+			const cmd = "until ap mail list; do sleep 1; done";
+			for (let i = 0; i < 5; i++) {
+				const result = detectMailPollPattern(cmd);
+				expect(result.matched).toBe(true);
+				expect(result.reason).toBe("until ap mail loop");
+			}
+		});
+
+		test("matched call followed by non-match returns non-match correctly", () => {
+			expect(detectMailPollPattern("until ap mail list; do sleep 1; done").matched).toBe(true);
+			expect(detectMailPollPattern("ap mail check").matched).toBe(false);
+			expect(detectMailPollPattern("until ap mail list; do sleep 1; done").matched).toBe(true);
+		});
+	});
+});

package/src/agents/mail-poll-detect.ts

@@ -0,0 +1,73 @@
+/**
+ * Defense-in-depth detector for Bash mail-poll patterns (agentplate-c92c).
+ *
+ * The lead.md prompt forbids Bash polling for mail (agentplate-fa84) — the
+ * primary mitigation. This helper is the runtime backstop: if a future custom
+ * overlay or contributed agent definition silently reintroduces the pattern,
+ * the turn-runner emits a warning and a custom event so it surfaces in
+ * `ap logs` / `ap feed` / the UI. Warn-only by design; the seed's P3 severity
+ * is met without aborting the turn.
+ *
+ * What counts as a wait-poll:
+ *   1. A `until` or `while` loop construct.
+ *   2. The loop condition references `ap mail check` or `ap mail list`
+ *      (directly, negated with `!`, or wrapped in `[ "$(...)" ... ]`).
+ *   3. The loop body contains `sleep` (otherwise it's bounded work, not a
+ *      poll).
+ *
+ * `for` loops are bounded and never classified as wait-polls — `for i in 1 2 3;
+ * do ap mail send ...; done` is a legitimate batched send, not a poll.
+ */
+
+const LOOP_PATTERN =
+	/\b(until|while)\b([\s\S]*?)\s*(?:;|\n)\s*do\b([\s\S]*?)\s*(?:;|\n)\s*\bdone\b/g;
+const SLEEP_IN_BODY = /\bsleep\b/;
+const AP_MAIL_REF = /\bap\s+mail\s+(?:check|list)\b/;
+const DIRECT_AP_MAIL = /^ap\s+mail\s+(?:check|list)\b/;
+const NEGATED_AP_MAIL = /^!\s*ap\s+mail\s+(?:check|list)\b/;
+
+export interface MailPollDetectionResult {
+	matched: boolean;
+	reason?: string;
+}
+
+/**
+ * Pure detector — no I/O, no side effects. Accepts any input and returns
+ * `{ matched: false }` for non-string values so callers can pass the raw
+ * `event.input.command` field without pre-validation.
+ */
+export function detectMailPollPattern(command: unknown): MailPollDetectionResult {
+	if (typeof command !== "string") return { matched: false };
+
+	// Reset lastIndex because the regex is module-level with the `g` flag.
+	LOOP_PATTERN.lastIndex = 0;
+	let match: RegExpExecArray | null = LOOP_PATTERN.exec(command);
+	while (match !== null) {
+		const kind = match[1] as "until" | "while";
+		const condition = (match[2] ?? "").trim();
+		const body = match[3] ?? "";
+
+		if (!SLEEP_IN_BODY.test(body)) {
+			match = LOOP_PATTERN.exec(command);
+			continue;
+		}
+		if (!AP_MAIL_REF.test(condition)) {
+			match = LOOP_PATTERN.exec(command);
+			continue;
+		}
+
+		if (kind === "until") {
+			if (DIRECT_AP_MAIL.test(condition)) {
+				return { matched: true, reason: "until ap mail loop" };
+			}
+			return { matched: true, reason: "ap mail piped condition" };
+		}
+
+		if (NEGATED_AP_MAIL.test(condition)) {
+			return { matched: true, reason: "while-not ap mail loop" };
+		}
+		return { matched: true, reason: "ap mail piped condition" };
+	}
+
+	return { matched: false };
+}