@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/commands/run.ts

@@ -12,39 +12,12 @@
  */
 
 import { join } from "node:path";
+import { Command, CommanderError } from "commander";
 import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
 import { createRunStore, createSessionStore } from "../sessions/store.ts";
 import type { AgentSession, Run } from "../types.ts";
 
-const RUN_HELP = `overstory run -- Manage runs (coordinator session groupings)
-
-Usage: overstory run [subcommand] [options]
-
-Subcommands:
-  (default)          Show current run status
-  list [--last <n>]  List recent runs (default last 10)
-  complete           Mark current run as completed
-  show <id>          Show run details (agents, duration)
-
-Options:
-  --json             Output as JSON
-  --help, -h         Show this help`;
-
-/**
- * Parse a named flag value from args.
- */
-function getFlag(args: string[], flag: string): string | undefined {
-	const idx = args.indexOf(flag);
-	if (idx === -1 || idx + 1 >= args.length) {
-		return undefined;
-	}
-	return args[idx + 1];
-}
-
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
 /**
  * Format milliseconds as human-readable duration.
  */
@@ -90,6 +63,18 @@ function runDuration(run: Run): string {
 	return formatDuration(end - start);
 }
 
+/**
+ * Format an agent's duration from startedAt to now (or completion).
+ */
+function formatAgentDuration(agent: AgentSession): string {
+	const start = new Date(agent.startedAt).getTime();
+	const end =
+		agent.state === "completed" || agent.state === "zombie"
+			? new Date(agent.lastActivity).getTime()
+			: Date.now();
+	return formatDuration(end - start);
+}
+
 /**
  * Show current run status (default subcommand).
  */
@@ -291,61 +276,96 @@ async function showRun(overstoryDir: string, runId: string, json: boolean): Prom
 	}
 }
 
-/**
- * Format an agent's duration from startedAt to now (or completion).
- */
-function formatAgentDuration(agent: AgentSession): string {
-	const start = new Date(agent.startedAt).getTime();
-	const end =
-		agent.state === "completed" || agent.state === "zombie"
-			? new Date(agent.lastActivity).getTime()
-			: Date.now();
-	return formatDuration(end - start);
+interface RunDefaultOpts {
+	json?: boolean;
 }
 
-/**
- * Entry point for `overstory run [subcommand] [options]`.
- */
-export async function runCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${RUN_HELP}\n`);
-		return;
-	}
+interface RunListOpts {
+	last?: string;
+	json?: boolean;
+}
 
-	const json = hasFlag(args, "--json");
-	const cwd = process.cwd();
-	const config = await loadConfig(cwd);
-	const overstoryDir = join(config.project.root, ".overstory");
+interface RunShowOpts {
+	json?: boolean;
+}
 
-	const subcommand = args[0];
+interface RunCompleteOpts {
+	json?: boolean;
+}
 
-	switch (subcommand) {
-		case "list": {
-			const lastStr = getFlag(args, "--last");
+export function createRunCommand(): Command {
+	const cmd = new Command("run").description("Manage runs (coordinator session groupings)");
+
+	// Default action (bare `overstory run`)
+	cmd.option("--json", "Output as JSON").action(async (opts: RunDefaultOpts) => {
+		const cwd = process.cwd();
+		const config = await loadConfig(cwd);
+		const overstoryDir = join(config.project.root, ".overstory");
+		await showCurrentRun(overstoryDir, opts.json ?? false);
+	});
+
+	// `overstory run list`
+	cmd
+		.command("list")
+		.description("List recent runs")
+		.option("--last <n>", "Number of recent runs to show (default: 10)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: RunListOpts) => {
+			const lastStr = opts.last;
 			const limit = lastStr ? Number.parseInt(lastStr, 10) : 10;
-			await listRuns(overstoryDir, limit, json);
-			break;
-		}
-		case "complete":
-			await completeCurrentRun(overstoryDir, json);
-			break;
-		case "show": {
-			const runId = args[1];
-			if (!runId || runId.startsWith("--")) {
-				if (json) {
-					process.stdout.write('{"error":"Missing run ID. Usage: overstory run show <id>"}\n');
-				} else {
-					process.stderr.write("Missing run ID. Usage: overstory run show <id>\n");
-				}
-				process.exitCode = 1;
-				return;
+			if (Number.isNaN(limit) || limit < 1) {
+				throw new ValidationError("--last must be a positive integer", {
+					field: "last",
+					value: lastStr,
+				});
 			}
-			await showRun(overstoryDir, runId, json);
-			break;
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const overstoryDir = join(config.project.root, ".overstory");
+			await listRuns(overstoryDir, limit, opts.json ?? false);
+		});
+
+	// `overstory run show <id>`
+	cmd
+		.command("show")
+		.description("Show run details (agents, duration)")
+		.argument("<id>", "Run ID")
+		.option("--json", "Output as JSON")
+		.action(async (id: string, opts: RunShowOpts) => {
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const overstoryDir = join(config.project.root, ".overstory");
+			await showRun(overstoryDir, id, opts.json ?? false);
+		});
+
+	// `overstory run complete`
+	cmd
+		.command("complete")
+		.description("Mark current run as completed")
+		.option("--json", "Output as JSON")
+		.action(async (opts: RunCompleteOpts) => {
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const overstoryDir = join(config.project.root, ".overstory");
+			await completeCurrentRun(overstoryDir, opts.json ?? false);
+		});
+
+	return cmd;
+}
+
+export async function runCommand(args: string[]): Promise<void> {
+	const program = new Command("overstory").exitOverride().configureOutput({
+		writeOut: (str) => process.stdout.write(str),
+		writeErr: (str) => process.stderr.write(str),
+	});
+	program.addCommand(createRunCommand());
+	try {
+		await program.parseAsync(["node", "overstory", "run", ...args]);
+	} catch (err: unknown) {
+		if (err instanceof CommanderError) {
+			if (err.code === "commander.helpDisplayed" || err.code === "commander.version") return;
+			throw new ValidationError(err.message, { field: "args" });
 		}
-		default:
-			// Default: show current run status
-			await showCurrentRun(overstoryDir, json);
-			break;
+		throw err;
 	}
 }

package/src/commands/sling.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
+import { resolveModel, resolveProviderEnv } from "../agents/manifest.ts";
 import { HierarchyError } from "../errors.ts";
+import type { AgentManifest, OverstoryConfig } from "../types.ts";
 import {
 	type BeaconOptions,
 	buildBeacon,
@@ -655,3 +657,197 @@ describe("checkRunSessionLimit", () => {
 		expect(checkRunSessionLimit(-1, 100)).toBe(false);
 	});
 });
+
+/**
+ * Tests for sling provider env injection building blocks.
+ *
+ * In slingCommand, resolveModel() is called to get the { model, env } for the
+ * spawned agent. The env dict is then spread into createSession's env parameter
+ * alongside OVERSTORY_AGENT_NAME and OVERSTORY_WORKTREE_PATH:
+ *
+ *   const { model, env } = resolveModel(config, manifest, capability, agentDef.model);
+ *   const pid = await createSession(tmuxSessionName, worktreePath, claudeCmd, {
+ *       ...env,
+ *       OVERSTORY_AGENT_NAME: name,
+ *       OVERSTORY_WORKTREE_PATH: worktreePath,
+ *   });
+ *
+ * These tests verify the building blocks: that resolveModel and resolveProviderEnv
+ * produce the correct env dicts for the provider scenarios sling will encounter.
+ */
+
+function makeConfig(
+	models: OverstoryConfig["models"] = {},
+	providers: OverstoryConfig["providers"] = { anthropic: { type: "native" } },
+): OverstoryConfig {
+	return {
+		project: { name: "test", root: "/tmp/test", canonicalBranch: "main" },
+		agents: {
+			manifestPath: ".overstory/agent-manifest.json",
+			baseDir: ".overstory/agent-defs",
+			maxConcurrent: 5,
+			staggerDelayMs: 0,
+			maxDepth: 2,
+			maxSessionsPerRun: 0,
+		},
+		worktrees: { baseDir: ".overstory/worktrees" },
+		taskTracker: { backend: "auto", enabled: false },
+		mulch: { enabled: false, domains: [], primeFormat: "markdown" },
+		merge: { aiResolveEnabled: false, reimagineEnabled: false },
+		providers,
+		watchdog: {
+			tier0Enabled: false,
+			tier0IntervalMs: 30_000,
+			tier1Enabled: false,
+			tier2Enabled: false,
+			staleThresholdMs: 300_000,
+			zombieThresholdMs: 600_000,
+			nudgeIntervalMs: 60_000,
+		},
+		models,
+		logging: { verbose: false, redactSecrets: true },
+	};
+}
+
+function makeManifest(): AgentManifest {
+	return {
+		version: "1.0",
+		agents: {
+			builder: {
+				file: "builder.md",
+				model: "opus",
+				tools: ["Read", "Write", "Edit", "Bash"],
+				capabilities: ["implement"],
+				canSpawn: false,
+				constraints: [],
+			},
+			coordinator: {
+				file: "coordinator.md",
+				model: "sonnet",
+				tools: ["Read", "Bash"],
+				capabilities: ["coordinate"],
+				canSpawn: true,
+				constraints: [],
+			},
+		},
+		capabilityIndex: { implement: ["builder"], coordinate: ["coordinator"] },
+	};
+}
+
+describe("sling provider env injection building blocks", () => {
+	test("resolveModel produces env for gateway provider in config override scenario", () => {
+		const config = makeConfig(
+			{ builder: "openrouter/anthropic/claude-3-5-sonnet" },
+			{ openrouter: { type: "gateway", baseUrl: "https://openrouter.ai/api/v1" } },
+		);
+		const manifest = makeManifest();
+
+		const result = resolveModel(config, manifest, "builder", "sonnet");
+
+		expect(result.model).toBe("sonnet");
+		expect(result.env).toBeDefined();
+		expect(result.env?.ANTHROPIC_BASE_URL).toBe("https://openrouter.ai/api/v1");
+		expect(result.env?.ANTHROPIC_API_KEY).toBe("");
+		expect(result.env?.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe("anthropic/claude-3-5-sonnet");
+	});
+
+	test("env dict from resolveModel can be spread with OVERSTORY_AGENT_NAME and OVERSTORY_WORKTREE_PATH", () => {
+		const config = makeConfig(
+			{ builder: "openrouter/anthropic/claude-3-5-sonnet" },
+			{ openrouter: { type: "gateway", baseUrl: "https://openrouter.ai/api/v1" } },
+		);
+		const manifest = makeManifest();
+
+		const { env } = resolveModel(config, manifest, "builder", "sonnet");
+		// Simulates the spread in slingCommand: { ...env, OVERSTORY_AGENT_NAME: name, OVERSTORY_WORKTREE_PATH: wt }
+		const combined: Record<string, string> = {
+			...(env ?? {}),
+			OVERSTORY_AGENT_NAME: "test-builder",
+			OVERSTORY_WORKTREE_PATH: "/tmp/wt",
+		};
+
+		expect(combined.ANTHROPIC_BASE_URL).toBe("https://openrouter.ai/api/v1");
+		expect(combined.ANTHROPIC_API_KEY).toBe("");
+		expect(combined.OVERSTORY_AGENT_NAME).toBe("test-builder");
+		expect(combined.OVERSTORY_WORKTREE_PATH).toBe("/tmp/wt");
+	});
+
+	test("resolveModel returns no env for native anthropic provider", () => {
+		const config = makeConfig({ builder: "sonnet" }, { anthropic: { type: "native" } });
+		const manifest = makeManifest();
+
+		const result = resolveModel(config, manifest, "builder", "sonnet");
+
+		expect(result.model).toBe("sonnet");
+		expect(result.env).toBeUndefined();
+	});
+
+	test("resolveModel returns no env when model is a simple alias from manifest default", () => {
+		// No models override: manifest builder model "opus" is a simple alias
+		const config = makeConfig({}, {});
+		const manifest = makeManifest();
+
+		const result = resolveModel(config, manifest, "builder", "sonnet");
+
+		expect(result.model).toBe("opus");
+		expect(result.env).toBeUndefined();
+	});
+
+	test("resolveProviderEnv includes ANTHROPIC_AUTH_TOKEN when authTokenEnv var is set", () => {
+		const providers = {
+			openrouter: {
+				type: "gateway" as const,
+				baseUrl: "https://openrouter.ai/api/v1",
+				authTokenEnv: "MY_API_KEY",
+			},
+		};
+		const env = { MY_API_KEY: "sk-test-123" };
+
+		const result = resolveProviderEnv("openrouter", "anthropic/claude-3-5-sonnet", providers, env);
+
+		expect(result).not.toBeNull();
+		expect(result?.ANTHROPIC_AUTH_TOKEN).toBe("sk-test-123");
+	});
+
+	test("resolveProviderEnv omits ANTHROPIC_AUTH_TOKEN when authTokenEnv var is absent", () => {
+		const providers = {
+			openrouter: {
+				type: "gateway" as const,
+				baseUrl: "https://openrouter.ai/api/v1",
+				authTokenEnv: "MY_API_KEY",
+			},
+		};
+		const env: Record<string, string | undefined> = {};
+
+		const result = resolveProviderEnv("openrouter", "anthropic/claude-3-5-sonnet", providers, env);
+
+		expect(result).not.toBeNull();
+		expect(result?.ANTHROPIC_AUTH_TOKEN).toBeUndefined();
+	});
+
+	test("resolveModel produces different env dicts for coordinator and builder with different gateway providers", () => {
+		const config = makeConfig(
+			{
+				coordinator: "openrouter/anthropic/claude-3-5-sonnet",
+				builder: "litellm/anthropic/claude-3-5-haiku",
+			},
+			{
+				openrouter: { type: "gateway", baseUrl: "https://openrouter.ai/api/v1" },
+				litellm: { type: "gateway", baseUrl: "https://litellm.example.com/v1" },
+			},
+		);
+		const manifest = makeManifest();
+
+		const coordinatorResult = resolveModel(config, manifest, "coordinator", "sonnet");
+		const builderResult = resolveModel(config, manifest, "builder", "sonnet");
+
+		expect(coordinatorResult.model).toBe("sonnet");
+		expect(builderResult.model).toBe("sonnet");
+		expect(coordinatorResult.env?.ANTHROPIC_BASE_URL).toBe("https://openrouter.ai/api/v1");
+		expect(builderResult.env?.ANTHROPIC_BASE_URL).toBe("https://litellm.example.com/v1");
+		expect(coordinatorResult.env?.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe(
+			"anthropic/claude-3-5-sonnet",
+		);
+		expect(builderResult.env?.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe("anthropic/claude-3-5-haiku");
+	});
+});

package/src/commands/sling.ts

@@ -98,15 +98,17 @@ export function inferDomainsFromFiles(
 	return [...inferred].sort();
 }
 
-/**
- * Parse a named flag value from an args array.
- */
-function getFlag(args: string[], flag: string): string | undefined {
-	const idx = args.indexOf(flag);
-	if (idx === -1 || idx + 1 >= args.length) {
-		return undefined;
-	}
-	return args[idx + 1];
+export interface SlingOptions {
+	capability?: string;
+	name?: string;
+	spec?: string;
+	files?: string;
+	parent?: string;
+	depth?: string;
+	skipScout?: boolean;
+	skipTaskCheck?: boolean;
+	forceHierarchy?: boolean;
+	json?: boolean;
 }
 
 /**
@@ -225,58 +227,26 @@ export function validateHierarchy(
 /**
  * Entry point for `overstory sling <task-id> [flags]`.
  *
- * Flags:
- *   --capability <type>    builder | scout | reviewer | lead | merger
- *   --name <name>          Unique agent name
- *   --spec <path>          Path to task spec file
- *   --files <f1,f2,...>    Exclusive file scope
- *   --parent <agent-name>  Parent agent (for hierarchy tracking)
- *   --depth <n>            Current hierarchy depth (default 0)
- *   --force-hierarchy      Bypass hierarchy validation (debugging only)
+ * @param taskId - The task ID to assign to the agent
+ * @param opts - Command options
  */
-const SLING_HELP = `overstory sling — Spawn a worker agent
-
-Usage: overstory sling <task-id> [flags]
-
-Arguments:
-  <task-id>                  Beads task ID to assign
-
-Options:
-  --capability <type>        Agent type: builder | scout | reviewer | lead | merger (default: builder)
-  --name <name>              Unique agent name (required)
-  --spec <path>              Path to task spec file
-  --files <f1,f2,...>        Exclusive file scope (comma-separated)
-  --parent <agent-name>      Parent agent for hierarchy tracking
-  --depth <n>                Current hierarchy depth (default: 0)
-  --skip-scout                 Skip scout phase for lead agents (jump to build)
-  --skip-task-check              Skip task existence validation (for worktree-created issues)
-  --force-hierarchy            Bypass hierarchy validation (debugging only)
-  --json                     Output result as JSON
-  --help, -h                 Show this help`;
-
-export async function slingCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${SLING_HELP}\n`);
-		return;
-	}
-
-	const taskId = args.find((a) => !a.startsWith("--"));
+export async function slingCommand(taskId: string, opts: SlingOptions): Promise<void> {
 	if (!taskId) {
 		throw new ValidationError("Task ID is required: overstory sling <task-id>", {
 			field: "taskId",
 		});
 	}
 
-	const capability = getFlag(args, "--capability") ?? "builder";
-	const name = getFlag(args, "--name");
-	const specPath = getFlag(args, "--spec") ?? null;
-	const filesRaw = getFlag(args, "--files");
-	const parentAgent = getFlag(args, "--parent") ?? null;
-	const depthStr = getFlag(args, "--depth");
+	const capability = opts.capability ?? "builder";
+	const name = opts.name;
+	const specPath = opts.spec ?? null;
+	const filesRaw = opts.files;
+	const parentAgent = opts.parent ?? null;
+	const depthStr = opts.depth;
 	const depth = depthStr !== undefined ? Number.parseInt(depthStr, 10) : 0;
-	const forceHierarchy = args.includes("--force-hierarchy");
-	const skipScout = args.includes("--skip-scout");
-	const skipTaskCheck = args.includes("--skip-task-check");
+	const forceHierarchy = opts.forceHierarchy ?? false;
+	const skipScout = opts.skipScout ?? false;
+	const skipTaskCheck = opts.skipTaskCheck ?? false;
 
 	if (!name || name.trim().length === 0) {
 		throw new ValidationError("--name is required for sling", { field: "name" });
@@ -645,7 +615,7 @@ export async function slingCommand(args: string[]): Promise<void> {
 			pid,
 		};
 
-		if (args.includes("--json")) {
+		if (opts.json ?? false) {
 			process.stdout.write(`${JSON.stringify(output)}\n`);
 		} else {
 			process.stdout.write(`🚀 Agent "${name}" launched!\n`);

package/src/commands/spec.test.ts

@@ -9,7 +9,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
-import { specCommand, writeSpec } from "./spec.ts";
+import { specWriteCommand, writeSpec } from "./spec.ts";
 
 let tempDir: string;
 let overstoryDir: string;
@@ -55,47 +55,21 @@ afterEach(async () => {
 	await cleanupTempDir(tempDir);
 });
 
-// === help ===
-
-describe("help", () => {
-	test("--help shows usage", async () => {
-		await specCommand(["--help"]);
-		expect(stdoutOutput).toContain("overstory spec");
-		expect(stdoutOutput).toContain("write");
-		expect(stdoutOutput).toContain("--body");
-		expect(stdoutOutput).toContain("--agent");
-	});
-
-	test("-h shows usage", async () => {
-		await specCommand(["-h"]);
-		expect(stdoutOutput).toContain("overstory spec");
-	});
-
-	test("no args shows help", async () => {
-		await specCommand([]);
-		expect(stdoutOutput).toContain("overstory spec");
-	});
-});
-
 // === validation ===
 
 describe("validation", () => {
-	test("unknown subcommand throws ValidationError", async () => {
-		await expect(specCommand(["unknown"])).rejects.toThrow("Unknown spec subcommand");
-	});
-
 	test("write without bead-id throws ValidationError", async () => {
-		await expect(specCommand(["write"])).rejects.toThrow("Bead ID is required");
+		await expect(specWriteCommand("", {})).rejects.toThrow("Bead ID is required");
 	});
 
 	test("write without body throws ValidationError", async () => {
-		await expect(specCommand(["write", "task-abc", "--agent", "scout-1"])).rejects.toThrow(
+		await expect(specWriteCommand("task-abc", { agent: "scout-1" })).rejects.toThrow(
 			"Spec body is required",
 		);
 	});
 
 	test("write with empty body throws ValidationError", async () => {
-		await expect(specCommand(["write", "task-abc", "--body", "  "])).rejects.toThrow(
+		await expect(specWriteCommand("task-abc", { body: "  " })).rejects.toThrow(
 			"Spec body is required",
 		);
 	});
@@ -165,11 +139,11 @@ describe("writeSpec", () => {
 	});
 });
 
-// === specCommand (CLI integration) ===
+// === specWriteCommand (CLI integration) ===
 
-describe("specCommand write", () => {
+describe("specWriteCommand (integration)", () => {
 	test("writes spec and prints path", async () => {
-		await specCommand(["write", "task-cmd", "--body", "# CLI Spec"]);
+		await specWriteCommand("task-cmd", { body: "# CLI Spec" });
 
 		// Path may differ due to macOS /var -> /private/var symlink resolution
 		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-cmd.md");
@@ -180,7 +154,7 @@ describe("specCommand write", () => {
 	});
 
 	test("writes spec with agent attribution", async () => {
-		await specCommand(["write", "task-attr", "--body", "# Attributed", "--agent", "scout-2"]);
+		await specWriteCommand("task-attr", { body: "# Attributed", agent: "scout-2" });
 
 		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-attr.md");
 
@@ -190,14 +164,14 @@ describe("specCommand write", () => {
 		expect(content).toContain("# Attributed");
 	});
 
-	test("flags can appear in any order", async () => {
-		await specCommand(["write", "--agent", "scout-3", "--body", "# Content", "task-order"]);
+	test("writes spec without agent when agent is omitted", async () => {
+		await specWriteCommand("task-noagent", { body: "# No Agent" });
 
-		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-order.md");
+		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-noagent.md");
 
 		const specPath = stdoutOutput.trim();
 		const content = await Bun.file(specPath).text();
-		expect(content).toContain("<!-- written-by: scout-3 -->");
-		expect(content).toContain("# Content");
+		expect(content).not.toContain("written-by");
+		expect(content).toBe("# No Agent\n");
 	});
 });