@os-eco/overstory-cli 0.6.1

package/src/agents/identity.ts

@@ -0,0 +1,384 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AgentError } from "../errors.ts";
+import type { AgentIdentity } from "../types.ts";
+
+const IDENTITY_FILENAME = "identity.yaml";
+const MAX_RECENT_TASKS = 20;
+
+// === YAML Serialization ===
+
+/**
+ * Serialize an AgentIdentity to a YAML string.
+ *
+ * Produces simple key-value pairs with proper indentation.
+ * Arrays of scalars use `- item` syntax.
+ * Arrays of objects use `- key: value` with indented continuation lines.
+ */
+function serializeIdentityYaml(identity: AgentIdentity): string {
+	const lines: string[] = [];
+
+	lines.push(`name: ${quoteIfNeeded(identity.name)}`);
+	lines.push(`capability: ${quoteIfNeeded(identity.capability)}`);
+	lines.push(`created: ${quoteIfNeeded(identity.created)}`);
+	lines.push(`sessionsCompleted: ${identity.sessionsCompleted}`);
+
+	// expertiseDomains
+	if (identity.expertiseDomains.length === 0) {
+		lines.push("expertiseDomains: []");
+	} else {
+		lines.push("expertiseDomains:");
+		for (const domain of identity.expertiseDomains) {
+			lines.push(`\t- ${quoteIfNeeded(domain)}`);
+		}
+	}
+
+	// recentTasks (array of objects)
+	if (identity.recentTasks.length === 0) {
+		lines.push("recentTasks: []");
+	} else {
+		lines.push("recentTasks:");
+		for (const task of identity.recentTasks) {
+			lines.push(`\t- beadId: ${quoteIfNeeded(task.beadId)}`);
+			lines.push(`\t\tsummary: ${quoteIfNeeded(task.summary)}`);
+			lines.push(`\t\tcompletedAt: ${quoteIfNeeded(task.completedAt)}`);
+		}
+	}
+
+	return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Quote a string value if it contains characters that could be misinterpreted
+ * by a YAML parser (colons, hashes, leading/trailing whitespace, etc.).
+ */
+function quoteIfNeeded(value: string): string {
+	if (
+		value === "" ||
+		value.includes(": ") ||
+		value.includes("#") ||
+		value.startsWith(" ") ||
+		value.endsWith(" ") ||
+		value.startsWith('"') ||
+		value.startsWith("'") ||
+		value === "true" ||
+		value === "false" ||
+		value === "null" ||
+		value === "~" ||
+		/^\d/.test(value)
+	) {
+		// Use double quotes, escaping internal double quotes
+		const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+		return `"${escaped}"`;
+	}
+	return value;
+}
+
+// === YAML Deserialization ===
+
+/**
+ * Parse an AgentIdentity YAML file into a structured object.
+ *
+ * This is a purpose-built parser for the identity YAML format. It handles:
+ * - Simple key: value pairs (strings, numbers)
+ * - Arrays of scalars (expertiseDomains)
+ * - Arrays of objects (recentTasks with beadId, summary, completedAt)
+ * - Empty arrays (`[]`)
+ * - Quoted strings
+ * - Tab indentation
+ */
+function parseIdentityYaml(text: string): AgentIdentity {
+	const lines = text.split("\n");
+
+	let name = "";
+	let capability = "";
+	let created = "";
+	let sessionsCompleted = 0;
+	const expertiseDomains: string[] = [];
+	const recentTasks: Array<{ beadId: string; summary: string; completedAt: string }> = [];
+
+	let currentSection: "none" | "expertiseDomains" | "recentTasks" = "none";
+	let currentTask: { beadId: string; summary: string; completedAt: string } | null = null;
+
+	for (const rawLine of lines) {
+		const trimmed = rawLine.trim();
+
+		// Skip empty lines and comments
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+
+		// Top-level key: value (no leading whitespace)
+		if (!rawLine.startsWith("\t") && !rawLine.startsWith(" ")) {
+			// Flush any pending task
+			if (currentTask !== null) {
+				recentTasks.push(currentTask);
+				currentTask = null;
+			}
+
+			const colonIndex = trimmed.indexOf(":");
+			if (colonIndex === -1) continue;
+
+			const key = trimmed.slice(0, colonIndex).trim();
+			const rawValue = trimmed.slice(colonIndex + 1).trim();
+
+			switch (key) {
+				case "name":
+					name = parseScalar(rawValue);
+					currentSection = "none";
+					break;
+				case "capability":
+					capability = parseScalar(rawValue);
+					currentSection = "none";
+					break;
+				case "created":
+					created = parseScalar(rawValue);
+					currentSection = "none";
+					break;
+				case "sessionsCompleted":
+					sessionsCompleted = Number.parseInt(parseScalar(rawValue), 10) || 0;
+					currentSection = "none";
+					break;
+				case "expertiseDomains":
+					if (rawValue === "[]") {
+						currentSection = "none";
+					} else {
+						currentSection = "expertiseDomains";
+					}
+					break;
+				case "recentTasks":
+					if (rawValue === "[]") {
+						currentSection = "none";
+					} else {
+						currentSection = "recentTasks";
+					}
+					break;
+			}
+			continue;
+		}
+
+		// Indented line: array items or nested object properties
+		if (currentSection === "expertiseDomains") {
+			if (trimmed.startsWith("- ")) {
+				expertiseDomains.push(parseScalar(trimmed.slice(2).trim()));
+			}
+			continue;
+		}
+
+		if (currentSection === "recentTasks") {
+			if (trimmed.startsWith("- ")) {
+				// New array item — flush previous task
+				if (currentTask !== null) {
+					recentTasks.push(currentTask);
+				}
+				currentTask = { beadId: "", summary: "", completedAt: "" };
+
+				// Parse the key-value on the same line as the dash
+				const itemContent = trimmed.slice(2).trim();
+				const itemColonIdx = itemContent.indexOf(":");
+				if (itemColonIdx !== -1) {
+					const itemKey = itemContent.slice(0, itemColonIdx).trim();
+					const itemValue = parseScalar(itemContent.slice(itemColonIdx + 1).trim());
+					assignTaskField(currentTask, itemKey, itemValue);
+				}
+			} else if (currentTask !== null) {
+				// Continuation line for current task object
+				const colonIdx = trimmed.indexOf(":");
+				if (colonIdx !== -1) {
+					const fieldKey = trimmed.slice(0, colonIdx).trim();
+					const fieldValue = parseScalar(trimmed.slice(colonIdx + 1).trim());
+					assignTaskField(currentTask, fieldKey, fieldValue);
+				}
+			}
+		}
+	}
+
+	// Flush final pending task
+	if (currentTask !== null) {
+		recentTasks.push(currentTask);
+	}
+
+	return {
+		name,
+		capability,
+		created,
+		sessionsCompleted,
+		expertiseDomains,
+		recentTasks,
+	};
+}
+
+/**
+ * Assign a parsed field value to a task object by key name.
+ */
+function assignTaskField(
+	task: { beadId: string; summary: string; completedAt: string },
+	key: string,
+	value: string,
+): void {
+	switch (key) {
+		case "beadId":
+			task.beadId = value;
+			break;
+		case "summary":
+			task.summary = value;
+			break;
+		case "completedAt":
+			task.completedAt = value;
+			break;
+	}
+}
+
+/**
+ * Parse a scalar YAML value, stripping quotes if present.
+ */
+function parseScalar(raw: string): string {
+	if (raw.length >= 2) {
+		if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+			return raw.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+		}
+	}
+	return raw;
+}
+
+// === Public API ===
+
+/**
+ * Create a new agent identity file.
+ *
+ * Writes the identity to `{baseDir}/{identity.name}/identity.yaml`,
+ * creating the directory if it doesn't exist.
+ *
+ * @param baseDir - Absolute path to the agents base directory (e.g., `.overstory/agents`)
+ * @param identity - The AgentIdentity to persist
+ */
+export async function createIdentity(baseDir: string, identity: AgentIdentity): Promise<void> {
+	const filePath = join(baseDir, identity.name, IDENTITY_FILENAME);
+	const dir = dirname(filePath);
+
+	try {
+		await mkdir(dir, { recursive: true });
+	} catch (err) {
+		throw new AgentError(`Failed to create identity directory: ${dir}`, {
+			agentName: identity.name,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	const yaml = serializeIdentityYaml(identity);
+
+	try {
+		await Bun.write(filePath, yaml);
+	} catch (err) {
+		throw new AgentError(`Failed to write identity file: ${filePath}`, {
+			agentName: identity.name,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}
+
+/**
+ * Load an existing agent identity from disk.
+ *
+ * Reads from `{baseDir}/{name}/identity.yaml`. Returns null if the file
+ * does not exist.
+ *
+ * @param baseDir - Absolute path to the agents base directory
+ * @param name - Agent name (used as subdirectory)
+ * @returns The loaded AgentIdentity, or null if not found
+ */
+export async function loadIdentity(baseDir: string, name: string): Promise<AgentIdentity | null> {
+	const filePath = join(baseDir, name, IDENTITY_FILENAME);
+	const file = Bun.file(filePath);
+	const exists = await file.exists();
+
+	if (!exists) {
+		return null;
+	}
+
+	let text: string;
+	try {
+		text = await file.text();
+	} catch (err) {
+		throw new AgentError(`Failed to read identity file: ${filePath}`, {
+			agentName: name,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		return parseIdentityYaml(text);
+	} catch (err) {
+		throw new AgentError(`Failed to parse identity YAML: ${filePath}`, {
+			agentName: name,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}
+
+/**
+ * Update an existing agent identity.
+ *
+ * Loads the identity, applies updates, writes back, and returns the result.
+ *
+ * Supported updates:
+ * - `sessionsCompleted`: Incremented by the given value (additive)
+ * - `expertiseDomains`: Merged with existing (deduplicating)
+ * - `completedTask`: Appended to `recentTasks` with a current ISO timestamp
+ *
+ * The `recentTasks` list is capped at 20 entries; oldest entries are dropped.
+ *
+ * @param baseDir - Absolute path to the agents base directory
+ * @param name - Agent name
+ * @param update - Partial update to apply
+ * @returns The updated AgentIdentity
+ * @throws AgentError if the identity does not exist
+ */
+export async function updateIdentity(
+	baseDir: string,
+	name: string,
+	update: Partial<Pick<AgentIdentity, "sessionsCompleted" | "expertiseDomains">> & {
+		completedTask?: { beadId: string; summary: string };
+	},
+): Promise<AgentIdentity> {
+	const identity = await loadIdentity(baseDir, name);
+
+	if (identity === null) {
+		throw new AgentError(`Agent identity not found: ${name}`, {
+			agentName: name,
+		});
+	}
+
+	// Increment sessionsCompleted
+	if (update.sessionsCompleted !== undefined) {
+		identity.sessionsCompleted += update.sessionsCompleted;
+	}
+
+	// Merge expertiseDomains (deduplicate)
+	if (update.expertiseDomains !== undefined) {
+		const existing = new Set(identity.expertiseDomains);
+		for (const domain of update.expertiseDomains) {
+			existing.add(domain);
+		}
+		identity.expertiseDomains = [...existing];
+	}
+
+	// Append completed task
+	if (update.completedTask !== undefined) {
+		identity.recentTasks.push({
+			beadId: update.completedTask.beadId,
+			summary: update.completedTask.summary,
+			completedAt: new Date().toISOString(),
+		});
+
+		// Cap at MAX_RECENT_TASKS, dropping oldest
+		if (identity.recentTasks.length > MAX_RECENT_TASKS) {
+			identity.recentTasks = identity.recentTasks.slice(
+				identity.recentTasks.length - MAX_RECENT_TASKS,
+			);
+		}
+	}
+
+	// Write back
+	await createIdentity(baseDir, identity);
+
+	return identity;
+}

package/src/agents/lifecycle.test.ts

@@ -0,0 +1,196 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import type { SessionHandoff } from "../types.ts";
+import { loadCheckpoint } from "./checkpoint.ts";
+import { completeHandoff, initiateHandoff, resumeFromHandoff } from "./lifecycle.ts";
+
+describe("lifecycle", () => {
+	let agentsDir: string;
+
+	beforeEach(async () => {
+		agentsDir = await mkdtemp(join(tmpdir(), "overstory-lifecycle-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(agentsDir);
+	});
+
+	test("initiateHandoff creates checkpoint and handoff record", async () => {
+		const handoff = await initiateHandoff({
+			agentsDir,
+			agentName: "builder-1",
+			sessionId: "session-100",
+			beadId: "overstory-xyz1",
+			reason: "compaction",
+			progressSummary: "Built the widget",
+			pendingWork: "Tests remain",
+			currentBranch: "overstory/builder-1/overstory-xyz1",
+			filesModified: ["src/widget.ts"],
+			mulchDomains: ["agents"],
+		});
+
+		// Handoff record is correct
+		expect(handoff.fromSessionId).toBe("session-100");
+		expect(handoff.toSessionId).toBeNull();
+		expect(handoff.reason).toBe("compaction");
+		expect(handoff.checkpoint.agentName).toBe("builder-1");
+		expect(handoff.checkpoint.progressSummary).toBe("Built the widget");
+
+		// Checkpoint was saved to disk
+		const checkpoint = await loadCheckpoint(agentsDir, "builder-1");
+		expect(checkpoint).not.toBeNull();
+		expect(checkpoint?.sessionId).toBe("session-100");
+
+		// Handoffs file was created
+		const handoffsFile = Bun.file(join(agentsDir, "builder-1", "handoffs.json"));
+		expect(await handoffsFile.exists()).toBe(true);
+		const handoffs = JSON.parse(await handoffsFile.text()) as SessionHandoff[];
+		expect(handoffs).toHaveLength(1);
+	});
+
+	test("resumeFromHandoff returns pending handoff", async () => {
+		await initiateHandoff({
+			agentsDir,
+			agentName: "builder-2",
+			sessionId: "session-200",
+			beadId: "overstory-abc2",
+			reason: "crash",
+			progressSummary: "Halfway done",
+			pendingWork: "Finish implementation",
+			currentBranch: "overstory/builder-2/overstory-abc2",
+			filesModified: ["src/foo.ts"],
+			mulchDomains: [],
+		});
+
+		const result = await resumeFromHandoff({
+			agentsDir,
+			agentName: "builder-2",
+		});
+
+		expect(result).not.toBeNull();
+		expect(result?.checkpoint.sessionId).toBe("session-200");
+		expect(result?.checkpoint.progressSummary).toBe("Halfway done");
+		expect(result?.handoff.reason).toBe("crash");
+		expect(result?.handoff.toSessionId).toBeNull();
+	});
+
+	test("completeHandoff updates toSessionId and clears checkpoint", async () => {
+		await initiateHandoff({
+			agentsDir,
+			agentName: "builder-3",
+			sessionId: "session-300",
+			beadId: "overstory-def3",
+			reason: "manual",
+			progressSummary: "Done with phase 1",
+			pendingWork: "Phase 2",
+			currentBranch: "overstory/builder-3/overstory-def3",
+			filesModified: [],
+			mulchDomains: [],
+		});
+
+		await completeHandoff({
+			agentsDir,
+			agentName: "builder-3",
+			newSessionId: "session-301",
+		});
+
+		// Checkpoint should be cleared
+		const checkpoint = await loadCheckpoint(agentsDir, "builder-3");
+		expect(checkpoint).toBeNull();
+
+		// Handoff should have toSessionId set
+		const handoffsFile = Bun.file(join(agentsDir, "builder-3", "handoffs.json"));
+		const handoffs = JSON.parse(await handoffsFile.text()) as SessionHandoff[];
+		expect(handoffs).toHaveLength(1);
+		const first = handoffs[0];
+		expect(first).toBeDefined();
+		expect(first?.toSessionId).toBe("session-301");
+	});
+
+	test("multiple handoffs accumulate in handoffs.json", async () => {
+		// First handoff
+		await initiateHandoff({
+			agentsDir,
+			agentName: "builder-4",
+			sessionId: "session-400",
+			beadId: "overstory-ghi4",
+			reason: "compaction",
+			progressSummary: "First session work",
+			pendingWork: "Continue",
+			currentBranch: "overstory/builder-4/overstory-ghi4",
+			filesModified: ["a.ts"],
+			mulchDomains: [],
+		});
+
+		// Complete the first handoff
+		await completeHandoff({
+			agentsDir,
+			agentName: "builder-4",
+			newSessionId: "session-401",
+		});
+
+		// Second handoff
+		await initiateHandoff({
+			agentsDir,
+			agentName: "builder-4",
+			sessionId: "session-401",
+			beadId: "overstory-ghi4",
+			reason: "timeout",
+			progressSummary: "Second session work",
+			pendingWork: "Finish up",
+			currentBranch: "overstory/builder-4/overstory-ghi4",
+			filesModified: ["a.ts", "b.ts"],
+			mulchDomains: [],
+		});
+
+		const handoffsFile = Bun.file(join(agentsDir, "builder-4", "handoffs.json"));
+		const handoffs = JSON.parse(await handoffsFile.text()) as SessionHandoff[];
+		expect(handoffs).toHaveLength(2);
+
+		const first = handoffs[0];
+		expect(first).toBeDefined();
+		expect(first?.toSessionId).toBe("session-401");
+
+		const second = handoffs[1];
+		expect(second).toBeDefined();
+		expect(second?.toSessionId).toBeNull();
+	});
+
+	test("resumeFromHandoff returns null when no pending handoff exists", async () => {
+		const result = await resumeFromHandoff({
+			agentsDir,
+			agentName: "nonexistent-agent",
+		});
+		expect(result).toBeNull();
+	});
+
+	test("resumeFromHandoff returns null when all handoffs are completed", async () => {
+		await initiateHandoff({
+			agentsDir,
+			agentName: "builder-5",
+			sessionId: "session-500",
+			beadId: "overstory-jkl5",
+			reason: "compaction",
+			progressSummary: "Done",
+			pendingWork: "Nothing",
+			currentBranch: "overstory/builder-5/overstory-jkl5",
+			filesModified: [],
+			mulchDomains: [],
+		});
+
+		await completeHandoff({
+			agentsDir,
+			agentName: "builder-5",
+			newSessionId: "session-501",
+		});
+
+		const result = await resumeFromHandoff({
+			agentsDir,
+			agentName: "builder-5",
+		});
+		expect(result).toBeNull();
+	});
+});