@os-eco/overstory-cli 0.6.1

package/src/events/tool-filter.ts

@@ -0,0 +1,126 @@
+/**
+ * Smart tool argument filter for observability events.
+ *
+ * Reduces tool invocation payloads from ~20KB to ~200 bytes by keeping only
+ * the fields useful for post-mortem analysis. Each tool type has a custom
+ * filter that preserves identifying information while dropping bulky content.
+ */
+
+export interface FilteredToolArgs {
+	args: Record<string, unknown>;
+	summary: string;
+}
+
+/**
+ * Filter tool arguments down to what matters for observability.
+ *
+ * Keeps identifying fields (paths, patterns, commands) and drops bulk content
+ * (file bodies, old/new strings, timeouts). Returns a compact summary string
+ * suitable for log lines.
+ */
+export function filterToolArgs(
+	toolName: string,
+	toolInput: Record<string, unknown>,
+): FilteredToolArgs {
+	const handler = TOOL_FILTERS[toolName];
+	if (handler) {
+		return handler(toolInput);
+	}
+	return { args: {}, summary: toolName };
+}
+
+type ToolFilter = (input: Record<string, unknown>) => FilteredToolArgs;
+
+function pickDefined(input: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	for (const key of keys) {
+		if (key in input && input[key] !== undefined) {
+			result[key] = input[key];
+		}
+	}
+	return result;
+}
+
+function truncate(value: unknown, maxLen: number): string {
+	const str = typeof value === "string" ? value : String(value ?? "");
+	if (str.length <= maxLen) {
+		return str;
+	}
+	return `${str.slice(0, maxLen)}...`;
+}
+
+const TOOL_FILTERS: Record<string, ToolFilter> = {
+	Bash: (input) => {
+		const args = pickDefined(input, ["command", "description"]);
+		const cmd = typeof input.command === "string" ? input.command : "";
+		return { args, summary: `bash: ${truncate(cmd, 80)}` };
+	},
+
+	Read: (input) => {
+		const args = pickDefined(input, ["file_path", "offset", "limit"]);
+		const filePath = typeof input.file_path === "string" ? input.file_path : "";
+		const offset = typeof input.offset === "number" ? input.offset : undefined;
+		const limit = typeof input.limit === "number" ? input.limit : undefined;
+		let summary: string;
+		if (offset !== undefined && limit !== undefined) {
+			summary = `read: ${filePath} (lines ${offset}-${offset + limit})`;
+		} else if (offset !== undefined) {
+			summary = `read: ${filePath} (from line ${offset})`;
+		} else if (limit !== undefined) {
+			summary = `read: ${filePath} (first ${limit} lines)`;
+		} else {
+			summary = `read: ${filePath}`;
+		}
+		return { args, summary };
+	},
+
+	Write: (input) => {
+		const args = pickDefined(input, ["file_path"]);
+		const filePath = typeof input.file_path === "string" ? input.file_path : "";
+		return { args, summary: `write: ${filePath}` };
+	},
+
+	Edit: (input) => {
+		const args = pickDefined(input, ["file_path"]);
+		const filePath = typeof input.file_path === "string" ? input.file_path : "";
+		return { args, summary: `edit: ${filePath}` };
+	},
+
+	Glob: (input) => {
+		const args = pickDefined(input, ["pattern", "path"]);
+		const pattern = typeof input.pattern === "string" ? input.pattern : "";
+		const path = typeof input.path === "string" ? input.path : "";
+		const summary = path ? `glob: ${pattern} in ${path}` : `glob: ${pattern}`;
+		return { args, summary };
+	},
+
+	Grep: (input) => {
+		const args = pickDefined(input, ["pattern", "path", "glob", "output_mode"]);
+		const pattern = typeof input.pattern === "string" ? input.pattern : "";
+		const path = typeof input.path === "string" ? input.path : "";
+		const summary = path ? `grep: "${pattern}" in ${path}` : `grep: "${pattern}"`;
+		return { args, summary };
+	},
+
+	WebFetch: (input) => {
+		const args = pickDefined(input, ["url"]);
+		const url = typeof input.url === "string" ? input.url : "";
+		return { args, summary: `fetch: ${url}` };
+	},
+
+	WebSearch: (input) => {
+		const args = pickDefined(input, ["query"]);
+		const query = typeof input.query === "string" ? input.query : "";
+		return { args, summary: `search: ${query}` };
+	},
+
+	Task: (input) => {
+		const args = pickDefined(input, ["description", "subagent_type"]);
+		const description = typeof input.description === "string" ? input.description : "";
+		const subagentType = typeof input.subagent_type === "string" ? input.subagent_type : "";
+		const summary = subagentType
+			? `task: ${description} (${subagentType})`
+			: `task: ${description}`;
+		return { args, summary };
+	},
+};

package/src/index.ts

@@ -0,0 +1,316 @@
+#!/usr/bin/env bun
+
+/**
+ * Overstory CLI — main entry point and command router.
+ *
+ * Routes subcommands to their respective handlers in src/commands/.
+ * Usage: overstory <command> [args...]
+ */
+
+import { agentsCommand } from "./commands/agents.ts";
+import { cleanCommand } from "./commands/clean.ts";
+import { completionsCommand } from "./commands/completions.ts";
+import { coordinatorCommand } from "./commands/coordinator.ts";
+import { costsCommand } from "./commands/costs.ts";
+import { dashboardCommand } from "./commands/dashboard.ts";
+import { doctorCommand } from "./commands/doctor.ts";
+import { errorsCommand } from "./commands/errors.ts";
+import { feedCommand } from "./commands/feed.ts";
+import { groupCommand } from "./commands/group.ts";
+import { hooksCommand } from "./commands/hooks.ts";
+import { initCommand } from "./commands/init.ts";
+import { inspectCommand } from "./commands/inspect.ts";
+import { logCommand } from "./commands/log.ts";
+import { logsCommand } from "./commands/logs.ts";
+import { mailCommand } from "./commands/mail.ts";
+import { mergeCommand } from "./commands/merge.ts";
+import { metricsCommand } from "./commands/metrics.ts";
+import { monitorCommand } from "./commands/monitor.ts";
+import { nudgeCommand } from "./commands/nudge.ts";
+import { primeCommand } from "./commands/prime.ts";
+import { replayCommand } from "./commands/replay.ts";
+import { runCommand } from "./commands/run.ts";
+import { slingCommand } from "./commands/sling.ts";
+import { specCommand } from "./commands/spec.ts";
+import { statusCommand } from "./commands/status.ts";
+import { stopCommand } from "./commands/stop.ts";
+import { supervisorCommand } from "./commands/supervisor.ts";
+import { traceCommand } from "./commands/trace.ts";
+import { watchCommand } from "./commands/watch.ts";
+import { worktreeCommand } from "./commands/worktree.ts";
+import { OverstoryError, WorktreeError } from "./errors.ts";
+import { setQuiet } from "./logging/color.ts";
+
+const VERSION = "0.6.1";
+
+const HELP = `overstory v${VERSION} — Multi-agent orchestration for Claude Code
+
+Usage: overstory <command> [args...]
+
+Commands:
+  agents <sub>            Discover and query agents (discover)
+  init                    Initialize .overstory/ in current project
+  sling <task-id>         Spawn a worker agent
+  spec <sub>              Manage task specs (write)
+  prime                   Load context for orchestrator/agent
+  stop <agent>            Terminate a running agent
+  status                  Show all active agents and project state
+  dashboard               Live TUI dashboard for agent monitoring
+  inspect <agent>         Deep inspection of a single agent
+  coordinator <sub>       Persistent coordinator agent (start/stop/status)
+  supervisor <sub>        Per-project supervisor agent (start/stop/status)
+  hooks <sub>             Manage orchestrator hooks (install/uninstall/status)
+  mail <sub>              Mail system (send/check/list/read/reply)
+  monitor <sub>           Tier 2 monitor agent (start/stop/status)
+  merge                   Merge agent branches into canonical
+  nudge <agent> [msg]     Send a text nudge to an agent
+  group <sub>             Task groups (create/status/add/remove/list)
+  clean                   Wipe runtime state (nuclear cleanup)
+  doctor                  Run health checks on overstory setup
+  worktree <sub>          Manage worktrees (list/clean)
+  log <event>             Log a hook event
+  logs [options]          Query NDJSON logs across agents
+  watch                   Start watchdog daemon
+  feed [options]          Unified real-time event stream across all agents
+  trace <target>         Chronological event timeline for agent/bead
+  errors [options]        Aggregated error view across agents
+  run [sub]               Manage runs (list/show/complete)
+  replay [options]        Interleaved chronological replay across agents
+  costs [options]          Token/cost analysis and breakdown
+  metrics                 Show session metrics
+
+Options:
+  --help, -h              Show this help
+  --version, -v           Show version
+  --quiet, -q             Suppress non-error output
+  --completions <shell>   Generate shell completions (bash, zsh, fish)
+
+Run 'overstory <command> --help' for command-specific help.`;
+
+const COMMANDS = [
+	"agents",
+	"init",
+	"sling",
+	"spec",
+	"prime",
+	"stop",
+	"status",
+	"dashboard",
+	"inspect",
+	"clean",
+	"doctor",
+	"coordinator",
+	"supervisor",
+	"hooks",
+	"monitor",
+	"mail",
+	"merge",
+	"nudge",
+	"group",
+	"worktree",
+	"log",
+	"logs",
+	"watch",
+	"trace",
+	"feed",
+	"errors",
+	"replay",
+	"run",
+	"costs",
+	"metrics",
+];
+
+function editDistance(a: string, b: string): number {
+	const m = a.length;
+	const n = b.length;
+	// Use a flat 1D array to avoid nested indexing warnings
+	const dp = new Array<number>((m + 1) * (n + 1)).fill(0);
+	const idx = (i: number, j: number) => i * (n + 1) + j;
+	for (let i = 0; i <= m; i++) dp[idx(i, 0)] = i;
+	for (let j = 0; j <= n; j++) dp[idx(0, j)] = j;
+	for (let i = 1; i <= m; i++) {
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			const del = (dp[idx(i - 1, j)] ?? 0) + 1;
+			const ins = (dp[idx(i, j - 1)] ?? 0) + 1;
+			const sub = (dp[idx(i - 1, j - 1)] ?? 0) + cost;
+			dp[idx(i, j)] = Math.min(del, ins, sub);
+		}
+	}
+	return dp[idx(m, n)] ?? 0;
+}
+
+function suggestCommand(input: string): string | undefined {
+	let bestMatch: string | undefined;
+	let bestDist = 3; // Only suggest if distance <= 2
+	for (const cmd of COMMANDS) {
+		const dist = editDistance(input, cmd);
+		if (dist < bestDist) {
+			bestDist = dist;
+			bestMatch = cmd;
+		}
+	}
+	return bestMatch;
+}
+
+async function main(): Promise<void> {
+	const args = process.argv.slice(2);
+
+	// Parse global flags before command routing
+	const quietIndex = args.indexOf("--quiet");
+	const qIndex = args.indexOf("-q");
+	if (quietIndex !== -1 || qIndex !== -1) {
+		setQuiet(true);
+		// Remove the flag from args so commands do not see it
+		if (quietIndex !== -1) args.splice(quietIndex, 1);
+		if (qIndex !== -1) {
+			const idx = args.indexOf("-q");
+			if (idx !== -1) args.splice(idx, 1);
+		}
+	}
+
+	const command = args[0];
+	const commandArgs = args.slice(1);
+
+	if (!command || command === "--help" || command === "-h") {
+		process.stdout.write(`${HELP}\n`);
+		return;
+	}
+
+	if (command === "--version" || command === "-v") {
+		process.stdout.write(`overstory v${VERSION}\n`);
+		return;
+	}
+
+	if (command === "--completions") {
+		completionsCommand(commandArgs);
+		return;
+	}
+
+	switch (command) {
+		case "agents":
+			await agentsCommand(commandArgs);
+			break;
+		case "init":
+			await initCommand(commandArgs);
+			break;
+		case "sling":
+			await slingCommand(commandArgs);
+			break;
+		case "spec":
+			await specCommand(commandArgs);
+			break;
+		case "prime":
+			await primeCommand(commandArgs);
+			break;
+		case "stop":
+			await stopCommand(commandArgs);
+			break;
+		case "status":
+			await statusCommand(commandArgs);
+			break;
+		case "dashboard":
+			await dashboardCommand(commandArgs);
+			break;
+		case "inspect":
+			await inspectCommand(commandArgs);
+			break;
+		case "clean":
+			await cleanCommand(commandArgs);
+			break;
+		case "doctor": {
+			const exitCode = await doctorCommand(commandArgs);
+			if (exitCode !== undefined) {
+				process.exitCode = exitCode;
+			}
+			break;
+		}
+		case "coordinator":
+			await coordinatorCommand(commandArgs);
+			break;
+		case "supervisor":
+			await supervisorCommand(commandArgs);
+			break;
+		case "hooks":
+			await hooksCommand(commandArgs);
+			break;
+		case "monitor":
+			await monitorCommand(commandArgs);
+			break;
+		case "mail":
+			await mailCommand(commandArgs);
+			break;
+		case "merge":
+			await mergeCommand(commandArgs);
+			break;
+		case "nudge":
+			await nudgeCommand(commandArgs);
+			break;
+		case "group":
+			await groupCommand(commandArgs);
+			break;
+		case "worktree":
+			await worktreeCommand(commandArgs);
+			break;
+		case "log":
+			await logCommand(commandArgs);
+			break;
+		case "logs":
+			await logsCommand(commandArgs);
+			break;
+		case "watch":
+			await watchCommand(commandArgs);
+			break;
+		case "trace":
+			await traceCommand(commandArgs);
+			break;
+		case "feed":
+			await feedCommand(commandArgs);
+			break;
+		case "errors":
+			await errorsCommand(commandArgs);
+			break;
+		case "replay":
+			await replayCommand(commandArgs);
+			break;
+		case "run":
+			await runCommand(commandArgs);
+			break;
+		case "costs":
+			await costsCommand(commandArgs);
+			break;
+		case "metrics":
+			await metricsCommand(commandArgs);
+			break;
+		default: {
+			process.stderr.write(`Unknown command: ${command}\n`);
+			const suggestion = suggestCommand(command);
+			if (suggestion) {
+				process.stderr.write(`Did you mean '${suggestion}'?\n`);
+			}
+			process.stderr.write(`Run 'overstory --help' for usage.\n`);
+			process.exit(1);
+		}
+	}
+}
+
+main().catch((err: unknown) => {
+	// Friendly message when running outside a git repository
+	if (err instanceof WorktreeError && err.message.includes("not a git repository")) {
+		process.stderr.write("Not in an overstory project. Run 'overstory init' first.\n");
+		process.exit(1);
+	}
+	if (err instanceof OverstoryError) {
+		process.stderr.write(`Error [${err.code}]: ${err.message}\n`);
+		process.exit(1);
+	}
+	if (err instanceof Error) {
+		process.stderr.write(`Error: ${err.message}\n`);
+		if (process.argv.includes("--verbose")) {
+			process.stderr.write(`${err.stack}\n`);
+		}
+		process.exit(1);
+	}
+	process.stderr.write(`Unknown error: ${String(err)}\n`);
+	process.exit(1);
+});