@os-eco/overstory-cli 0.7.8 → 0.8.0

package/src/commands/coordinator.ts

@@ -21,6 +21,8 @@ import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
+import { createMailClient } from "../mail/client.ts";
+import { createMailStore } from "../mail/store.ts";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
@@ -29,6 +31,7 @@ import type { AgentSession } from "../types.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
 import type { SessionState } from "../worktree/tmux.ts";
 import {
+	capturePaneContent,
 	checkSessionState,
 	createSession,
 	ensureTmuxAvailable,
@@ -37,11 +40,18 @@ import {
 	sendKeys,
 	waitForTuiReady,
 } from "../worktree/tmux.ts";
+import { nudgeAgent } from "./nudge.ts";
 import { isRunningAsRoot } from "./sling.ts";
 
 /** Default coordinator agent name. */
 const COORDINATOR_NAME = "coordinator";
 
+/** Poll interval for the ask subcommand reply loop. */
+const ASK_POLL_INTERVAL_MS = 2_000;
+
+/** Default timeout in seconds for the ask subcommand. */
+const ASK_DEFAULT_TIMEOUT_S = 120;
+
 /**
  * Build the tmux session name for the coordinator.
  * Includes the project name to prevent cross-project collisions (overstory-pcef).
@@ -81,6 +91,15 @@ export interface CoordinatorDeps {
 		stop: () => Promise<boolean>;
 		isRunning: () => Promise<boolean>;
 	};
+	_nudge?: (
+		projectRoot: string,
+		agentName: string,
+		message: string,
+		force: boolean,
+	) => Promise<{ delivered: boolean; reason?: string }>;
+	_capturePaneContent?: (name: string, lines?: number) => Promise<string | null>;
+	/** Override poll interval for ask subcommand (default: ASK_POLL_INTERVAL_MS). Used in tests. */
+	_pollIntervalMs?: number;
 }
 
 /**
@@ -738,6 +757,303 @@ async function statusCoordinator(
 	}
 }
 
+/**
+ * Send a fire-and-forget message to the running coordinator.
+ *
+ * Sends a mail message (from: operator, type: dispatch) and auto-nudges the
+ * coordinator via tmux sendKeys. Replaces the two-step `ov mail send + ov nudge` pattern.
+ */
+async function sendToCoordinator(
+	body: string,
+	opts: { subject: string; json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	const tmux = deps._tmux ?? {
+		createSession,
+		isSessionAlive,
+		checkSessionState,
+		killSession,
+		sendKeys,
+		waitForTuiReady,
+		ensureTmuxAvailable,
+	};
+	const nudge = deps._nudge ?? nudgeAgent;
+
+	const { subject, json } = opts;
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active coordinator session found", {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const alive = await tmux.isSessionAlive(session.tmuxSession);
+		if (!alive) {
+			store.updateState(COORDINATOR_NAME, "zombie");
+			store.updateLastActivity(COORDINATOR_NAME);
+			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		// Send mail
+		const mailDbPath = join(overstoryDir, "mail.db");
+		const mailStore = createMailStore(mailDbPath);
+		const mailClient = createMailClient(mailStore);
+		let id: string;
+		try {
+			id = mailClient.send({
+				from: "operator",
+				to: COORDINATOR_NAME,
+				subject,
+				body,
+				type: "dispatch",
+				priority: "normal",
+			});
+		} finally {
+			mailClient.close();
+		}
+
+		// Auto-nudge (fire-and-forget)
+		const nudgeMessage = `[DISPATCH] ${subject}: ${body.slice(0, 500)}`;
+		let nudged = false;
+		try {
+			const nudgeResult = await nudge(projectRoot, COORDINATOR_NAME, nudgeMessage, true);
+			nudged = nudgeResult.delivered;
+		} catch {
+			// Nudge is fire-and-forget — silently ignore errors
+		}
+
+		if (json) {
+			jsonOutput("coordinator send", { id, nudged });
+		} else {
+			printSuccess("Sent to coordinator", id);
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Send a synchronous request to the coordinator and wait for a reply.
+ *
+ * Sends a mail message (from: operator, type: dispatch) with a correlationId,
+ * auto-nudges the coordinator via tmux, then polls mail.db for a reply in the
+ * same thread. Prints the reply body (or structured JSON) and exits.
+ * Throws AgentError if no reply arrives before the timeout.
+ */
+export async function askCoordinator(
+	body: string,
+	opts: { subject: string; timeout: number; json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	const tmux = deps._tmux ?? {
+		createSession,
+		isSessionAlive,
+		checkSessionState,
+		killSession,
+		sendKeys,
+		waitForTuiReady,
+		ensureTmuxAvailable,
+	};
+	const nudge = deps._nudge ?? nudgeAgent;
+	const pollIntervalMs = deps._pollIntervalMs ?? ASK_POLL_INTERVAL_MS;
+
+	const { subject, timeout, json } = opts;
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active coordinator session found", {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const alive = await tmux.isSessionAlive(session.tmuxSession);
+		if (!alive) {
+			store.updateState(COORDINATOR_NAME, "zombie");
+			store.updateLastActivity(COORDINATOR_NAME);
+			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		// Generate correlation ID for tracking this request/response pair
+		const correlationId = crypto.randomUUID();
+
+		// Send mail with correlationId in payload
+		const mailDbPath = join(overstoryDir, "mail.db");
+		const mailStore = createMailStore(mailDbPath);
+		const mailClient = createMailClient(mailStore);
+		let sentId: string;
+		try {
+			sentId = mailClient.send({
+				from: "operator",
+				to: COORDINATOR_NAME,
+				subject,
+				body,
+				type: "dispatch",
+				priority: "normal",
+				payload: JSON.stringify({ correlationId }),
+			});
+		} finally {
+			mailClient.close();
+		}
+
+		// Auto-nudge (fire-and-forget)
+		const nudgeMessage = `[ASK] ${subject}: ${body.slice(0, 500)}`;
+		try {
+			await nudge(projectRoot, COORDINATOR_NAME, nudgeMessage, true);
+		} catch {
+			// Nudge is fire-and-forget — silently ignore errors
+		}
+
+		// Poll for a reply in the same thread
+		const deadline = Date.now() + timeout * 1000;
+		while (Date.now() < deadline) {
+			await Bun.sleep(pollIntervalMs);
+			// Open a fresh store connection each cycle so we see the latest committed writes
+			const pollStore = createMailStore(mailDbPath);
+			let reply: import("../types.ts").MailMessage | undefined;
+			try {
+				const replies = pollStore.getByThread(sentId);
+				reply = replies.find((m) => m.from === COORDINATOR_NAME && m.to === "operator");
+			} finally {
+				pollStore.close();
+			}
+			if (reply) {
+				if (json) {
+					jsonOutput("coordinator ask", {
+						correlationId,
+						sentId,
+						replyId: reply.id,
+						subject: reply.subject,
+						body: reply.body,
+						payload: reply.payload,
+					});
+				} else {
+					process.stdout.write(`${reply.body}\n`);
+				}
+				return;
+			}
+		}
+
+		throw new AgentError(
+			`Timed out after ${timeout}s waiting for coordinator reply (correlationId: ${correlationId})`,
+			{ agentName: COORDINATOR_NAME },
+		);
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Show recent coordinator tmux pane content without attaching.
+ *
+ * Wraps capturePaneContent() from tmux.ts. Supports --follow for continuous polling.
+ */
+async function outputCoordinator(
+	opts: { follow: boolean; lines: number; interval: number; json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	const tmux = deps._tmux ?? {
+		createSession,
+		isSessionAlive,
+		checkSessionState,
+		killSession,
+		sendKeys,
+		waitForTuiReady,
+		ensureTmuxAvailable,
+	};
+	const capturePane = deps._capturePaneContent ?? capturePaneContent;
+
+	const { follow, lines, interval, json } = opts;
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active coordinator session found", {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const alive = await tmux.isSessionAlive(session.tmuxSession);
+		if (!alive) {
+			store.updateState(COORDINATOR_NAME, "zombie");
+			store.updateLastActivity(COORDINATOR_NAME);
+			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const tmuxSession = session.tmuxSession;
+
+		if (follow) {
+			// Set up SIGINT handler for clean exit
+			let running = true;
+			process.once("SIGINT", () => {
+				running = false;
+			});
+
+			while (running) {
+				const content = await capturePane(tmuxSession, lines);
+				if (json) {
+					jsonOutput("coordinator output", { content, lines });
+				} else {
+					process.stdout.write(content ?? "");
+				}
+				if (running) {
+					await Bun.sleep(interval);
+				}
+			}
+		} else {
+			const content = await capturePane(tmuxSession, lines);
+			if (json) {
+				jsonOutput("coordinator output", { content, lines });
+			} else {
+				process.stdout.write(content ?? "");
+			}
+		}
+	} finally {
+		store.close();
+	}
+}
+
 /**
  * Create the Commander command for `ov coordinator`.
  */
@@ -784,6 +1100,56 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 			await statusCoordinator({ json: opts.json ?? false }, deps);
 		});
 
+	cmd
+		.command("send")
+		.description("Send a message to the coordinator (fire-and-forget)")
+		.requiredOption("--body <text>", "Message body")
+		.option("--subject <text>", "Message subject", "operator dispatch")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { body: string; subject: string; json?: boolean }) => {
+			await sendToCoordinator(opts.body, { subject: opts.subject, json: opts.json ?? false }, deps);
+		});
+
+	cmd
+		.command("ask")
+		.description("Send a request to the coordinator and wait for a reply")
+		.requiredOption("--body <text>", "Message body")
+		.option("--subject <text>", "Message subject", "operator request")
+		.option("--timeout <seconds>", "Timeout in seconds", String(ASK_DEFAULT_TIMEOUT_S))
+		.option("--json", "Output as JSON")
+		.action(async (opts: { body: string; subject: string; timeout?: string; json?: boolean }) => {
+			await askCoordinator(
+				opts.body,
+				{
+					subject: opts.subject,
+					timeout: Number.parseInt(opts.timeout ?? String(ASK_DEFAULT_TIMEOUT_S), 10),
+					json: opts.json ?? false,
+				},
+				deps,
+			);
+		});
+
+	cmd
+		.command("output")
+		.description("Show recent coordinator output (tmux pane content)")
+		.option("--follow, -f", "Continuously poll for new output")
+		.option("--lines <n>", "Number of lines to capture", "50")
+		.option("--interval <ms>", "Poll interval in milliseconds (with --follow)", "2000")
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: { follow?: boolean; lines?: string; interval?: string; json?: boolean }) => {
+				await outputCoordinator(
+					{
+						follow: opts.follow ?? false,
+						lines: Number.parseInt(opts.lines ?? "50", 10),
+						interval: Number.parseInt(opts.interval ?? "2000", 10),
+						json: opts.json ?? false,
+					},
+					deps,
+				);
+			},
+		);
+
 	return cmd;
 }
 

package/src/commands/init.test.ts

@@ -26,6 +26,7 @@ const AGENT_DEF_FILES = [
 	"merger.md",
 	"coordinator.md",
 	"monitor.md",
+	"orchestrator.md",
 ];
 
 /** Resolve the source agents directory (same logic as init.ts). */
@@ -52,7 +53,7 @@ describe("initCommand: agent-defs deployment", () => {
 		await cleanupTempDir(tempDir);
 	});
 
-	test("creates .overstory/agent-defs/ with all 7 agent definition files (supervisor deprecated)", async () => {
+	test("creates .overstory/agent-defs/ with all 8 agent definition files (supervisor deprecated)", async () => {
 		await initCommand({ _spawner: noopSpawner });
 
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
@@ -166,6 +167,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 		expect(content).toContain("!hooks.json\n");
 		expect(content).toContain("!groups.json\n");
 		expect(content).toContain("!agent-defs/\n");
+		expect(content).toContain("!agent-defs/**\n");
 
 		// Verify it matches the exported constant
 		expect(content).toBe(OVERSTORY_GITIGNORE);

package/src/commands/init.ts

@@ -324,7 +324,7 @@ function formatYamlValue(value: unknown): string {
 /**
  * Build the starter agent manifest.
  */
-function buildAgentManifest(): AgentManifest {
+export function buildAgentManifest(): AgentManifest {
 	const agents: AgentManifest["agents"] = {
 		scout: {
 			file: "scout.md",
@@ -407,7 +407,7 @@ function buildAgentManifest(): AgentManifest {
  * {{AGENT_NAME}} placeholders and space indentation). Uses tab indentation
  * to match Biome formatting rules.
  */
-function buildHooksJson(): string {
+export function buildHooksJson(): string {
 	// Tool name extraction: reads hook stdin JSON and extracts tool_name field.
 	// Claude Code sends {"tool_name":"Bash","tool_input":{...}} on stdin for
 	// PreToolUse/PostToolUse hooks.
@@ -588,6 +588,7 @@ export const OVERSTORY_GITIGNORE = `# Wildcard+whitelist: ignore everything, whi
 !hooks.json
 !groups.json
 !agent-defs/
+!agent-defs/**
 !README.md
 `;
 

package/src/commands/prime.test.ts

@@ -366,6 +366,7 @@ recentTasks: []
 !hooks.json
 !groups.json
 !agent-defs/
+!agent-defs/**
 !README.md
 `;