@os-eco/overstory-cli 0.6.1

package/src/logging/sanitizer.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import { sanitize, sanitizeObject } from "./sanitizer.ts";
+
+describe("sanitize", () => {
+	test("redacts Anthropic API keys (sk-ant-*)", () => {
+		const input = "Using API key sk-ant-abc123xyz456 for requests";
+		const result = sanitize(input);
+		expect(result).toBe("Using API key [REDACTED] for requests");
+	});
+
+	test("redacts GitHub personal access tokens (github_pat_*)", () => {
+		const input = "Token: github_pat_11ABCDEFGHIJKLMNOP";
+		const result = sanitize(input);
+		expect(result).toBe("Token: [REDACTED]");
+	});
+
+	test("redacts Bearer tokens", () => {
+		const input = "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
+		const result = sanitize(input);
+		expect(result).toBe("Authorization: [REDACTED]");
+	});
+
+	test("redacts GitHub classic tokens (ghp_*)", () => {
+		const input = "Token ghp_1234567890abcdefghijklmnopqrstuvwxyz found in env";
+		const result = sanitize(input);
+		expect(result).toBe("Token [REDACTED] found in env");
+	});
+
+	test("redacts ANTHROPIC_API_KEY environment variable", () => {
+		const input = "export ANTHROPIC_API_KEY=sk-ant-secret123";
+		const result = sanitize(input);
+		expect(result).toBe("export [REDACTED]");
+	});
+
+	test("redacts multiple secrets in the same string", () => {
+		const input = "Config: ANTHROPIC_API_KEY=sk-ant-key1 and github_pat_token2 and Bearer abc123";
+		const result = sanitize(input);
+		expect(result).toBe("Config: [REDACTED] and [REDACTED] and [REDACTED]");
+	});
+
+	test("preserves non-secret text", () => {
+		const input = "This is a normal message with no secrets";
+		const result = sanitize(input);
+		expect(result).toBe(input);
+	});
+
+	test("handles empty string", () => {
+		const result = sanitize("");
+		expect(result).toBe("");
+	});
+
+	test("redacts secrets at the beginning of the string", () => {
+		const input = "sk-ant-secret123 is the API key";
+		const result = sanitize(input);
+		expect(result).toBe("[REDACTED] is the API key");
+	});
+
+	test("redacts secrets at the end of the string", () => {
+		const input = "The API key is sk-ant-secret123";
+		const result = sanitize(input);
+		expect(result).toBe("The API key is [REDACTED]");
+	});
+});
+
+describe("sanitizeObject", () => {
+	test("sanitizes string values in a flat object", () => {
+		const input = {
+			apiKey: "sk-ant-secret123",
+			username: "alice",
+			token: "github_pat_abcdef",
+		};
+		const result = sanitizeObject(input);
+
+		expect(result.apiKey).toBe("[REDACTED]");
+		expect(result.username).toBe("alice");
+		expect(result.token).toBe("[REDACTED]");
+	});
+
+	test("sanitizes nested objects", () => {
+		const input = {
+			config: {
+				auth: {
+					key: "sk-ant-secret123",
+					user: "bob",
+				},
+			},
+		};
+		const result = sanitizeObject(input);
+
+		const config = result.config as Record<string, unknown>;
+		const auth = config.auth as Record<string, unknown>;
+		expect(auth.key).toBe("[REDACTED]");
+		expect(auth.user).toBe("bob");
+	});
+
+	test("sanitizes arrays of strings", () => {
+		const input = {
+			tokens: ["sk-ant-secret1", "safe-value", "github_pat_secret2"],
+		};
+		const result = sanitizeObject(input);
+
+		const tokens = result.tokens as string[];
+		expect(tokens[0]).toBe("[REDACTED]");
+		expect(tokens[1]).toBe("safe-value");
+		expect(tokens[2]).toBe("[REDACTED]");
+	});
+
+	test("sanitizes arrays of objects", () => {
+		const input = {
+			credentials: [
+				{ key: "sk-ant-secret1", name: "alice" },
+				{ key: "safe-key", name: "bob" },
+			],
+		};
+		const result = sanitizeObject(input);
+
+		const credentials = result.credentials as Array<Record<string, unknown>>;
+		expect(credentials[0]?.key).toBe("[REDACTED]");
+		expect(credentials[0]?.name).toBe("alice");
+		expect(credentials[1]?.key).toBe("safe-key");
+		expect(credentials[1]?.name).toBe("bob");
+	});
+
+	test("preserves non-string primitives", () => {
+		const input = {
+			count: 42,
+			enabled: true,
+			ratio: 3.14,
+			missing: null,
+		};
+		const result = sanitizeObject(input);
+
+		expect(result.count).toBe(42);
+		expect(result.enabled).toBe(true);
+		expect(result.ratio).toBe(3.14);
+		expect(result.missing).toBeNull();
+	});
+
+	test("handles deeply nested structures", () => {
+		const input = {
+			level1: {
+				level2: {
+					level3: {
+						secret: "sk-ant-deep-secret",
+						safe: "value",
+					},
+				},
+			},
+		};
+		const result = sanitizeObject(input);
+
+		const level1 = result.level1 as Record<string, unknown>;
+		const level2 = level1.level2 as Record<string, unknown>;
+		const level3 = level2.level3 as Record<string, unknown>;
+		expect(level3.secret).toBe("[REDACTED]");
+		expect(level3.safe).toBe("value");
+	});
+
+	test("handles mixed arrays and objects", () => {
+		const input = {
+			items: [{ key: "sk-ant-secret1" }, ["github_pat_secret2", "safe-value"], "Bearer token123"],
+		};
+		const result = sanitizeObject(input);
+
+		const items = result.items as Array<unknown>;
+		expect((items[0] as Record<string, unknown>).key).toBe("[REDACTED]");
+		expect((items[1] as string[])[0]).toBe("[REDACTED]");
+		expect((items[1] as string[])[1]).toBe("safe-value");
+		expect(items[2]).toBe("[REDACTED]");
+	});
+
+	test("returns a new object (does not mutate input)", () => {
+		const input = {
+			key: "sk-ant-secret123",
+			value: "safe",
+		};
+		const result = sanitizeObject(input);
+
+		// Original should be unchanged
+		expect(input.key).toBe("sk-ant-secret123");
+		// Result should be redacted
+		expect(result.key).toBe("[REDACTED]");
+	});
+
+	test("handles empty object", () => {
+		const input = {};
+		const result = sanitizeObject(input);
+		expect(result).toEqual({});
+	});
+});

package/src/logging/sanitizer.ts

@@ -0,0 +1,57 @@
+/**
+ * Secret redaction for log output.
+ *
+ * Scans strings and objects for known secret patterns (API keys, tokens, etc.)
+ * and replaces them with "[REDACTED]" to prevent accidental credential leakage.
+ */
+
+const REDACT_PATTERNS: RegExp[] = [
+	/sk-ant-[a-zA-Z0-9_-]+/g,
+	/github_pat_[a-zA-Z0-9_]+/g,
+	/Bearer\s+[a-zA-Z0-9._-]+/g,
+	/ghp_[a-zA-Z0-9]+/g,
+	/ANTHROPIC_API_KEY=[^\s]+/g,
+];
+
+const REDACTED = "[REDACTED]";
+
+/**
+ * Replace all known secret patterns in a string with "[REDACTED]".
+ */
+export function sanitize(input: string): string {
+	let result = input;
+	for (const pattern of REDACT_PATTERNS) {
+		// Reset lastIndex since we reuse global regexps
+		pattern.lastIndex = 0;
+		result = result.replace(pattern, REDACTED);
+	}
+	return result;
+}
+
+/**
+ * Deep-clone an object and sanitize all string values within it.
+ * Handles nested objects and arrays. Non-string primitives are passed through.
+ */
+export function sanitizeObject(obj: Record<string, unknown>): Record<string, unknown> {
+	return sanitizeValue(obj) as Record<string, unknown>;
+}
+
+function sanitizeValue(value: unknown): unknown {
+	if (typeof value === "string") {
+		return sanitize(value);
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(sanitizeValue);
+	}
+
+	if (value !== null && typeof value === "object") {
+		const result: Record<string, unknown> = {};
+		for (const key of Object.keys(value as Record<string, unknown>)) {
+			result[key] = sanitizeValue((value as Record<string, unknown>)[key]);
+		}
+		return result;
+	}
+
+	return value;
+}

package/src/mail/broadcast.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentSession } from "../types.ts";
+import { isGroupAddress, resolveGroupAddress } from "./broadcast.ts";
+
+describe("isGroupAddress", () => {
+	test("returns true for addresses starting with @", () => {
+		expect(isGroupAddress("@all")).toBe(true);
+		expect(isGroupAddress("@builders")).toBe(true);
+		expect(isGroupAddress("@scouts")).toBe(true);
+		expect(isGroupAddress("@Builder")).toBe(true); // case-insensitive input allowed
+	});
+
+	test("returns false for regular agent names", () => {
+		expect(isGroupAddress("orchestrator")).toBe(false);
+		expect(isGroupAddress("my-builder-agent")).toBe(false);
+		expect(isGroupAddress("scout-001")).toBe(false);
+	});
+
+	test("returns false for empty string", () => {
+		expect(isGroupAddress("")).toBe(false);
+	});
+});
+
+describe("resolveGroupAddress", () => {
+	// Helper to create minimal AgentSession fixtures
+	function createSession(agentName: string, capability: string): AgentSession {
+		return {
+			id: `session-${agentName}`,
+			agentName,
+			capability,
+			worktreePath: `/worktrees/${agentName}`,
+			branchName: `branch-${agentName}`,
+			beadId: "bead-001",
+			tmuxSession: `overstory-test-${agentName}`,
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-001",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+	}
+
+	const activeSessions: AgentSession[] = [
+		createSession("orchestrator", "coordinator"),
+		createSession("builder-1", "builder"),
+		createSession("builder-2", "builder"),
+		createSession("scout-1", "scout"),
+		createSession("reviewer-1", "reviewer"),
+		createSession("lead-1", "lead"),
+	];
+
+	describe("@all group", () => {
+		test("resolves to all active agents except sender", () => {
+			const recipients = resolveGroupAddress("@all", activeSessions, "orchestrator");
+			expect(recipients).toEqual(["builder-1", "builder-2", "scout-1", "reviewer-1", "lead-1"]);
+		});
+
+		test("excludes sender from recipients", () => {
+			const recipients = resolveGroupAddress("@all", activeSessions, "builder-1");
+			expect(recipients).toContain("orchestrator");
+			expect(recipients).toContain("builder-2");
+			expect(recipients).not.toContain("builder-1"); // sender excluded
+		});
+
+		test("throws when group resolves to zero recipients", () => {
+			const singleSession = [createSession("solo", "builder")];
+			expect(() => resolveGroupAddress("@all", singleSession, "solo")).toThrow(
+				"resolved to zero recipients",
+			);
+		});
+
+		test("is case-insensitive", () => {
+			const recipients = resolveGroupAddress("@ALL", activeSessions, "orchestrator");
+			expect(recipients.length).toBe(5);
+		});
+	});
+
+	describe("capability groups", () => {
+		test("resolves @builders to all builder agents", () => {
+			const recipients = resolveGroupAddress("@builders", activeSessions, "orchestrator");
+			expect(recipients).toEqual(["builder-1", "builder-2"]);
+		});
+
+		test("resolves @scouts to all scout agents", () => {
+			const recipients = resolveGroupAddress("@scouts", activeSessions, "orchestrator");
+			expect(recipients).toEqual(["scout-1"]);
+		});
+
+		test("resolves @reviewers to all reviewer agents", () => {
+			const recipients = resolveGroupAddress("@reviewers", activeSessions, "orchestrator");
+			expect(recipients).toEqual(["reviewer-1"]);
+		});
+
+		test("resolves @leads to all lead agents", () => {
+			const recipients = resolveGroupAddress("@leads", activeSessions, "orchestrator");
+			expect(recipients).toEqual(["lead-1"]);
+		});
+
+		test("excludes sender from capability group", () => {
+			const recipients = resolveGroupAddress("@builders", activeSessions, "builder-1");
+			expect(recipients).toEqual(["builder-2"]);
+		});
+
+		test("throws when capability group has no matching agents", () => {
+			const noMergers = activeSessions.filter((s) => s.capability !== "merger");
+			expect(() => resolveGroupAddress("@mergers", noMergers, "orchestrator")).toThrow(
+				"resolved to zero recipients",
+			);
+		});
+
+		test("throws when all matching agents are the sender", () => {
+			const singleBuilder = [createSession("solo-builder", "builder")];
+			expect(() => resolveGroupAddress("@builders", singleBuilder, "solo-builder")).toThrow(
+				"resolved to zero recipients",
+			);
+		});
+	});
+
+	describe("singular aliases", () => {
+		test("@builder resolves same as @builders", () => {
+			const singular = resolveGroupAddress("@builder", activeSessions, "orchestrator");
+			const plural = resolveGroupAddress("@builders", activeSessions, "orchestrator");
+			expect(singular).toEqual(plural);
+		});
+
+		test("@scout resolves same as @scouts", () => {
+			const singular = resolveGroupAddress("@scout", activeSessions, "orchestrator");
+			const plural = resolveGroupAddress("@scouts", activeSessions, "orchestrator");
+			expect(singular).toEqual(plural);
+		});
+
+		test("@reviewer resolves same as @reviewers", () => {
+			const singular = resolveGroupAddress("@reviewer", activeSessions, "orchestrator");
+			const plural = resolveGroupAddress("@reviewers", activeSessions, "orchestrator");
+			expect(singular).toEqual(plural);
+		});
+
+		test("@lead resolves same as @leads", () => {
+			const singular = resolveGroupAddress("@lead", activeSessions, "orchestrator");
+			const plural = resolveGroupAddress("@leads", activeSessions, "orchestrator");
+			expect(singular).toEqual(plural);
+		});
+
+		test("@merger resolves same as @mergers", () => {
+			const withMerger = [...activeSessions, createSession("merger-1", "merger")];
+			const singular = resolveGroupAddress("@merger", withMerger, "orchestrator");
+			const plural = resolveGroupAddress("@mergers", withMerger, "orchestrator");
+			expect(singular).toEqual(plural);
+		});
+
+		test("@supervisor resolves same as @supervisors", () => {
+			const withSupervisor = [...activeSessions, createSession("supervisor-1", "supervisor")];
+			const singular = resolveGroupAddress("@supervisor", withSupervisor, "orchestrator");
+			const plural = resolveGroupAddress("@supervisors", withSupervisor, "orchestrator");
+			expect(singular).toEqual(plural);
+		});
+
+		test("@coordinator resolves same as @coordinators", () => {
+			const singular = resolveGroupAddress("@coordinator", activeSessions, "builder-1");
+			const plural = resolveGroupAddress("@coordinators", activeSessions, "builder-1");
+			expect(singular).toEqual(plural);
+		});
+
+		test("@monitor resolves same as @monitors", () => {
+			const withMonitor = [...activeSessions, createSession("monitor-1", "monitor")];
+			const singular = resolveGroupAddress("@monitor", withMonitor, "orchestrator");
+			const plural = resolveGroupAddress("@monitors", withMonitor, "orchestrator");
+			expect(singular).toEqual(plural);
+		});
+	});
+
+	describe("unknown groups", () => {
+		test("throws for unknown group address", () => {
+			expect(() => resolveGroupAddress("@unknown", activeSessions, "orchestrator")).toThrow(
+				"Unknown group address",
+			);
+		});
+
+		test("error message lists valid groups", () => {
+			expect(() => resolveGroupAddress("@invalid", activeSessions, "orchestrator")).toThrow("@all");
+		});
+	});
+
+	describe("edge cases", () => {
+		test("handles empty active sessions list", () => {
+			expect(() => resolveGroupAddress("@all", [], "orchestrator")).toThrow(
+				"resolved to zero recipients",
+			);
+		});
+
+		test("handles sessions with mixed case capability names", () => {
+			const mixedCase = [createSession("builder-1", "Builder")];
+			// Capability groups match exact string — "Builder" !== "builder"
+			expect(() => resolveGroupAddress("@builders", mixedCase, "orchestrator")).toThrow(
+				"resolved to zero recipients",
+			);
+		});
+	});
+});

package/src/mail/broadcast.ts

@@ -0,0 +1,92 @@
+/**
+ * Group address resolution for broadcast messaging.
+ *
+ * Provides pure logic for resolving group addresses (e.g., @all, @builders)
+ * into lists of individual agent names. No I/O — takes active sessions as
+ * input and returns agent names as output.
+ */
+
+import type { AgentSession } from "../types.ts";
+
+/**
+ * Check if a recipient address is a group address.
+ * Group addresses start with '@'.
+ */
+export function isGroupAddress(recipient: string): boolean {
+	return recipient.startsWith("@");
+}
+
+/**
+ * Capability group prefixes. Matches singular and plural forms.
+ * E.g., @builder and @builders both resolve to agents with capability "builder".
+ */
+const CAPABILITY_GROUPS: Record<string, string> = {
+	"@builder": "builder",
+	"@builders": "builder",
+	"@scout": "scout",
+	"@scouts": "scout",
+	"@reviewer": "reviewer",
+	"@reviewers": "reviewer",
+	"@lead": "lead",
+	"@leads": "lead",
+	"@merger": "merger",
+	"@mergers": "merger",
+	"@supervisor": "supervisor",
+	"@supervisors": "supervisor",
+	"@coordinator": "coordinator",
+	"@coordinators": "coordinator",
+	"@monitor": "monitor",
+	"@monitors": "monitor",
+};
+
+/**
+ * Resolve a group address to a list of agent names.
+ *
+ * @param groupAddress - The group address to resolve (e.g., "@all", "@builders")
+ * @param activeSessions - List of active agent sessions
+ * @param senderName - Name of the sender (excluded from recipients)
+ * @returns Array of agent names that match the group
+ * @throws Error if the group address is unknown or resolves to zero recipients
+ */
+export function resolveGroupAddress(
+	groupAddress: string,
+	activeSessions: AgentSession[],
+	senderName: string,
+): string[] {
+	const normalized = groupAddress.toLowerCase();
+
+	// Handle @all — all active agents except sender
+	if (normalized === "@all") {
+		const recipients = activeSessions.map((s) => s.agentName).filter((name) => name !== senderName);
+
+		if (recipients.length === 0) {
+			throw new Error(
+				`Group address "${groupAddress}" resolved to zero recipients (sender excluded)`,
+			);
+		}
+
+		return recipients;
+	}
+
+	// Handle capability groups
+	const capability = CAPABILITY_GROUPS[normalized];
+	if (capability !== undefined) {
+		const recipients = activeSessions
+			.filter((s) => s.capability === capability)
+			.map((s) => s.agentName)
+			.filter((name) => name !== senderName);
+
+		if (recipients.length === 0) {
+			throw new Error(
+				`Group address "${groupAddress}" resolved to zero recipients (no active ${capability} agents)`,
+			);
+		}
+
+		return recipients;
+	}
+
+	// Unknown group
+	throw new Error(
+		`Unknown group address: "${groupAddress}". Valid groups: @all, ${Object.keys(CAPABILITY_GROUPS).join(", ")}`,
+	);
+}