@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/agents/headless-prompt.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from "bun:test";
+import {
+	buildInitialHeadlessPrompt,
+	encodeUserTurn,
+	formatMailSection,
+} from "./headless-prompt.ts";
+
+describe("encodeUserTurn", () => {
+	test("produces a valid NDJSON line", () => {
+		const line = encodeUserTurn("hello world");
+		expect(line).toEndWith("\n");
+		const parsed = JSON.parse(line.trim());
+		expect(parsed.type).toBe("user");
+		expect(parsed.message.role).toBe("user");
+		expect(parsed.message.content).toHaveLength(1);
+		expect(parsed.message.content[0].type).toBe("text");
+		expect(parsed.message.content[0].text).toBe("hello world");
+	});
+
+	test("handles multi-line text", () => {
+		const text = "line one\nline two\nline three";
+		const line = encodeUserTurn(text);
+		const parsed = JSON.parse(line.trim());
+		expect(parsed.message.content[0].text).toBe(text);
+	});
+});
+
+describe("formatMailSection", () => {
+	test("returns empty string for no messages", () => {
+		expect(formatMailSection([])).toBe("");
+	});
+
+	test("formats a single message", () => {
+		const result = formatMailSection([
+			{ from: "coordinator", subject: "dispatch", priority: "normal", body: "Start working." },
+		]);
+		expect(result).toContain("[MAIL] From: coordinator");
+		expect(result).toContain("Subject: dispatch");
+		expect(result).toContain("Start working.");
+	});
+
+	test("separates multiple messages with dividers", () => {
+		const result = formatMailSection([
+			{ from: "lead", subject: "task-1", priority: "high", body: "First task." },
+			{ from: "orchestrator", subject: "context", priority: "low", body: "Extra context." },
+		]);
+		expect(result).toContain("---");
+		expect(result).toContain("First task.");
+		expect(result).toContain("Extra context.");
+	});
+});
+
+describe("buildInitialHeadlessPrompt", () => {
+	test("combines all three sections", () => {
+		const result = buildInitialHeadlessPrompt(
+			"## Prime Context\nExpertise here.",
+			"[MAIL] From: orchestrator | Subject: dispatch\n\nDo the thing.",
+			"Read your overlay and begin immediately.",
+		);
+		const parsed = JSON.parse(result.trim());
+		const text: string = parsed.message.content[0].text;
+		expect(text).toContain("Prime Context");
+		expect(text).toContain("[MAIL]");
+		expect(text).toContain("Read your overlay and begin immediately.");
+		expect(text).toContain("---");
+	});
+
+	test("omits primeContext when undefined", () => {
+		const result = buildInitialHeadlessPrompt(
+			undefined,
+			"[MAIL] From: lead | Subject: dispatch\n\nTask body.",
+			"Begin.",
+		);
+		const parsed = JSON.parse(result.trim());
+		const text: string = parsed.message.content[0].text;
+		expect(text).not.toContain("Prime Context");
+		expect(text).toContain("[MAIL]");
+		expect(text).toContain("Begin.");
+	});
+
+	test("omits dispatchMail when undefined", () => {
+		const result = buildInitialHeadlessPrompt("## Prime Context", undefined, "Begin.");
+		const parsed = JSON.parse(result.trim());
+		const text: string = parsed.message.content[0].text;
+		expect(text).toContain("Prime Context");
+		expect(text).not.toContain("[MAIL]");
+		expect(text).toContain("Begin.");
+	});
+
+	test("always includes beacon even when other sections are empty", () => {
+		const result = buildInitialHeadlessPrompt(undefined, undefined, "Start now.");
+		const parsed = JSON.parse(result.trim());
+		const text: string = parsed.message.content[0].text;
+		expect(text).toBe("Start now.");
+	});
+
+	test("output is valid NDJSON ending with newline", () => {
+		const result = buildInitialHeadlessPrompt("ctx", "mail", "go");
+		expect(result).toEndWith("\n");
+		expect(() => JSON.parse(result.trim())).not.toThrow();
+	});
+});

package/src/agents/headless-prompt.ts

@@ -0,0 +1,68 @@
+/**
+ * Build the initial stdin prompt for a headless Claude Code agent.
+ *
+ * In headless mode (--input-format stream-json), the orchestrator owns stdin.
+ * Rather than relying on SessionStart hooks (which don't fire in headless mode),
+ * the orchestrator writes the prime context, pending dispatch mail, and activation
+ * beacon as the agent's first user turn immediately after spawn.
+ */
+
+/**
+ * Encode text as a stream-json user turn for Claude Code's --input-format stream-json.
+ *
+ * Format matches the Claude Code headless stdin protocol:
+ * {"type":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}}
+ */
+export function encodeUserTurn(text: string): string {
+	const message = {
+		type: "user",
+		message: { role: "user", content: [{ type: "text", text }] },
+	};
+	return `${JSON.stringify(message)}\n`;
+}
+
+/**
+ * Build the initial stdin prompt for a headless Claude agent.
+ *
+ * Combines prime context (mulch expertise, session state), pending dispatch mail,
+ * and the activation beacon into a single user turn. Replaces the SessionStart
+ * hook equivalents (ov prime + ov mail check --inject) for headless agents.
+ *
+ * Sections are separated by "---" dividers. Empty sections are omitted.
+ *
+ * @param primeContext - Output of `ov prime --agent <name>` (may be empty/undefined)
+ * @param dispatchMail - Pre-formatted dispatch mail body (may be empty/undefined)
+ * @param beacon - Activation phrase sent via tmux send-keys in interactive mode
+ * @returns NDJSON line ready to write to the agent's stdin
+ */
+export function buildInitialHeadlessPrompt(
+	primeContext: string | undefined,
+	dispatchMail: string | undefined,
+	beacon: string,
+): string {
+	const parts: string[] = [];
+	if (primeContext) parts.push(primeContext);
+	if (dispatchMail) parts.push(dispatchMail);
+	parts.push(beacon);
+
+	const text = parts.join("\n\n---\n\n");
+	return encodeUserTurn(text);
+}
+
+/**
+ * Format a list of pending mail messages as a dispatch mail section.
+ *
+ * Used to inline pending inbox messages into the initial stdin prompt so
+ * the agent starts with all pre-dispatch mail already in context.
+ */
+export function formatMailSection(
+	messages: ReadonlyArray<{ from: string; subject: string; priority: string; body: string }>,
+): string {
+	if (messages.length === 0) return "";
+	return messages
+		.map(
+			(m) =>
+				`[MAIL] From: ${m.from} | Subject: ${m.subject} | Priority: ${m.priority}\n\n${m.body}`,
+		)
+		.join("\n\n---\n\n");
+}