@markjaquith/agency 2.18.0 → 2.20.0

package/src/commands/work.ts

@@ -23,6 +23,11 @@ import {
 	resolveWorkbase,
 	type PickWorkbase,
 } from "../workbase/workbase-choice"
+import {
+	printableEnvironment,
+	resolveRunnerCommand,
+	runnerEnvironment,
+} from "../workbase/runner-command"
 
 interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -31,10 +36,17 @@ interface WorkOptions extends BaseCommandOptions {
 	readonly epicId?: string
 	readonly opencode?: boolean
 	readonly claude?: boolean
+	readonly runner?: string
+	readonly printCommand?: boolean
 	readonly force?: boolean
 }
 
-type LaunchAgent = (cli: string, args: readonly string[], cwd: string) => void
+type LaunchAgent = (
+	cli: string,
+	args: readonly string[],
+	cwd: string,
+	environment: Readonly<Record<string, string>>,
+) => void
 
 const formatCommand = (args: readonly string[]) =>
 	args
@@ -68,13 +80,15 @@ export const work = (
 	pickBase: PickWorkbase = pickWorkbase,
 ) =>
 	Effect.gen(function* () {
-		if (options.opencode && options.claude) {
+		if (
+			(options.opencode && options.claude) ||
+			(options.runner && (options.opencode || options.claude))
+		) {
 			return yield* Effect.fail(
-				new Error("Cannot use both --opencode and --claude"),
+				new Error("Cannot combine --runner, --opencode, and --claude"),
 			)
 		}
-		const previousSessionId = process.env.AGENCY_SESSION_ID
-		const previousClaimRevision = process.env.AGENCY_CLAIM_REVISION
+		const previousEnvironment = { ...process.env }
 		if (
 			options.epicId &&
 			(options.directory || options.taskId || options.phaseId)
@@ -104,6 +118,7 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
+		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null
 		if (options.epicId) {
@@ -199,7 +214,6 @@ export const work = (
 					new Error("No ready work targets found in this workbase"),
 				)
 			}
-			const { config } = yield* workbase.loadConfig(root)
 			target = yield* pick(choices, config.chooserCommand)
 			if (!target) return
 		}
@@ -233,13 +247,49 @@ export const work = (
 			launchPath = workspace.writablePath
 		}
 
-		const requested = options.claude ? "claude" : "opencode"
-		let cli = requested
+		const explicitlyRequested = Boolean(
+			options.runner ||
+			options.opencode ||
+			options.claude ||
+			process.env.AGENCY_RUNNER,
+		)
+		let runner =
+			options.runner ??
+			process.env.AGENCY_RUNNER ??
+			(options.claude ? "claude" : "opencode")
+		const claimant = process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency"
+		const sessionId =
+			process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
+		const resume = process.env.AGENCY_SESSION_ID !== undefined
+		let claimRevision = ""
+		let variables = {
+			prompt,
+			workbase: root,
+			target: targetNodeId(target),
+			task: target.kind === "epic" ? "" : target.taskId,
+			phase: target.kind === "phase" ? target.phaseId : "",
+			claimant,
+			sessionId,
+			claimRevision,
+		}
+		let resolved = resolveRunnerCommand(
+			runner,
+			config.runners,
+			variables,
+			resume,
+		)
+		let cli = resolved.argv[0]!
 		let available = yield* fs.runCommand(["which", cli], {
 			captureOutput: true,
 		})
-		if (available.exitCode !== 0 && !options.opencode && !options.claude) {
-			cli = "claude"
+		if (
+			available.exitCode !== 0 &&
+			!explicitlyRequested &&
+			runner === "opencode"
+		) {
+			runner = "claude"
+			resolved = resolveRunnerCommand(runner, config.runners, variables, resume)
+			cli = resolved.argv[0]!
 			available = yield* fs.runCommand(["which", cli], { captureOutput: true })
 		}
 		if (available.exitCode !== 0) {
@@ -251,36 +301,55 @@ export const work = (
 		) {
 			const phaseId = target.kind === "phase" ? target.phaseId : undefined
 			const current = yield* claims.inspect(target.taskId, phaseId, root)
-			const sessionId =
-				process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
 			const acquired = yield* claims.claim(
 				{
 					taskId: target.taskId,
 					...(phaseId ? { phaseId } : {}),
-					claimant: process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency",
-					runner: process.env.AGENCY_RUNNER ?? cli,
+					claimant,
+					runner,
 					sessionId,
 					revision: current.revision,
 				},
 				root,
 			)
-			process.env.AGENCY_SESSION_ID = sessionId
-			process.env.AGENCY_CLAIM_REVISION = acquired.revision
+			claimRevision = acquired.revision
 		}
 
-		const args =
-			cli === "opencode" ? ["--continue", "--prompt", prompt] : [prompt]
+		variables = { ...variables, claimRevision }
+		resolved = resolveRunnerCommand(runner, config.runners, variables, resume)
+		cli = resolved.argv[0]!
+		const environment = {
+			...resolved.environment,
+			...runnerEnvironment(runner, variables),
+		}
+		if (options.printCommand) {
+			log(
+				JSON.stringify(
+					{
+						cwd: launchPath,
+						argv: resolved.argv,
+						environment: printableEnvironment(environment),
+					},
+					null,
+					2,
+				),
+			)
+			return
+		}
+		for (const [key, value] of Object.entries(environment)) {
+			process.env[key] = value
+		}
 		verboseLog(
-			`Launching command: ${formatCommand([cli, ...args])} (cwd: ${launchPath})`,
+			`Launching command: ${formatCommand(resolved.argv)} (cwd: ${launchPath})`,
 		)
 		try {
-			launch(cli, [cli, ...args], launchPath)
+			launch(cli, resolved.argv, launchPath, environment)
 		} finally {
-			if (previousSessionId === undefined) delete process.env.AGENCY_SESSION_ID
-			else process.env.AGENCY_SESSION_ID = previousSessionId
-			if (previousClaimRevision === undefined)
-				delete process.env.AGENCY_CLAIM_REVISION
-			else process.env.AGENCY_CLAIM_REVISION = previousClaimRevision
+			for (const key of Object.keys(environment)) {
+				const previous = previousEnvironment[key]
+				if (previous === undefined) delete process.env[key]
+				else process.env[key] = previous
+			}
 		}
 	})
 
@@ -344,7 +413,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 	})
 
 export const help = `
-Usage: agency work [<directory-or-task-id> | --epic <epic-id>]
+Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>]
        agency work prepare [target] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
@@ -362,8 +431,10 @@ Options:
   --phase <id>         Work on a phase selected with --task
   --workbase <target>  Select a workbase by ID, name, or path
   --cwd <path>         Resolve context from a specific directory
-  --opencode           Require OpenCode
-  --claude             Require Claude Code
+  --runner <name>      Select a configured runner or built-in preset
+  --print-command      Print cwd, argv, and non-secret environment without launch
+  --opencode           Require the OpenCode preset
+  --claude             Require the Claude Code preset
   --force              Override readiness and terminal-state guards
   --no-input           Never open an interactive selector
 

package/src/services/WorkbaseService.test.ts

@@ -235,6 +235,25 @@ describe("WorkbaseService", () => {
 		).rejects.toThrow("{worktree}")
 	})
 
+	test("rejects an unknown runner command placeholder", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				runners: { custom: { command: ["agent", "{unknown}"] } },
+			}),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.discover(root)),
+				),
+			),
+		).rejects.toThrow("{unknown}")
+	})
+
 	test("validates a workbase with an epic and multi-phase task", async () => {
 		await write(root, "agency.json", '{"version":2}\n')
 		await mkdir(join(root, "repos/agency"), { recursive: true })

package/src/services/WorkbaseService.ts

@@ -21,6 +21,7 @@ import {
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import { validateRunners } from "../workbase/runner-command"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -277,6 +278,17 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								try {
+									validateRunners(decoded.value.runners)
+								} catch (cause) {
+									return yield* new WorkbaseConfigError({
+										path: configPath,
+										message:
+											cause instanceof Error
+												? cause.message
+												: "Invalid runner configuration",
+									})
+								}
 								return current
 							}
 						}

package/src/utils/table.ts

@@ -0,0 +1,19 @@
+export const formatTable = (
+	headings: readonly string[],
+	rows: readonly (readonly string[])[],
+) => {
+	const widths = headings.map((heading, index) =>
+		Math.max(heading.length, ...rows.map((row) => row[index]?.length ?? 0)),
+	)
+	const line = (cells: readonly string[]) =>
+		cells
+			.map((cell, index) => cell.padEnd(widths[index] ?? cell.length))
+			.join("  ")
+			.trimEnd()
+
+	return [
+		line(headings),
+		line(widths.map((width) => "-".repeat(width))),
+		...rows.map(line),
+	].join("\n")
+}

package/src/work-view.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "./test-utils"
+import { getWorkViews } from "./work-view"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+describe("work views", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await write(
+			root,
+			"epics/delivery/EPIC.md",
+			`---
+ticketUrl: https://example.com/delivery
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: zeta
+  - id: alpha
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/TASK.md",
+			`---
+ticketUrl: null
+epic: delivery
+phases:
+  - id: verify
+    dependsOn: [implement]
+  - id: implement
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/phases/verify/PHASE.md",
+			`---
+repo: agency
+branch: feat/verify
+base: main
+pr: null
+status: open
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/phases/implement/PHASE.md",
+			`---
+repo: agency
+branch: feat/implement
+base: main
+pr: https://github.com/example/agency/pull/1
+status: dropped
+---
+`,
+		)
+		await mkdir(join(root, "tasks/zeta/phases/implement/code/agency"), {
+			recursive: true,
+		})
+		await write(
+			root,
+			"tasks/alpha/TASK.md",
+			`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/alpha
+base: main
+pr: null
+status: open
+---
+`,
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	const views = (options: Record<string, unknown> = {}) =>
+		runTestEffect(Effect.suspend(() => getWorkViews({ cwd: root, ...options })))
+
+	test("uses declared graph order and exposes operational state", async () => {
+		const result = await views()
+
+		expect(result.taskRows.map((row) => row.id)).toEqual(["zeta", "alpha"])
+		expect(result.phaseRows.map((row) => row.id)).toEqual([
+			"verify",
+			"implement",
+		])
+		expect(result.executionRows.map((row) => row.key)).toEqual([
+			"zeta/verify",
+			"zeta/implement",
+			"alpha",
+		])
+		expect(result.phaseRows[0]).toMatchObject({
+			parent: "zeta",
+			status: "open",
+			readiness: "blocked",
+			repositories: "agency",
+			branch: "feat/verify",
+			pr: "absent",
+			worktree: "absent",
+		})
+		expect(result.phaseRows[1]).toMatchObject({
+			readiness: "terminal",
+			pr: "present",
+			worktree: "materialized",
+		})
+		expect(result.taskRows[0]).toMatchObject({
+			parent: "delivery",
+			branch: "multiple",
+			pr: "1/2 present",
+			worktree: "1/2 materialized",
+		})
+	})
+
+	test("composes lifecycle, repository, readiness, and PR filters", async () => {
+		expect(
+			(await views({ statuses: ["dropped"] })).executionRows.map(
+				(row) => row.key,
+			),
+		).toEqual(["zeta/implement"])
+		expect(
+			(await views({ repositories: ["agency"], blocked: true })).phaseRows.map(
+				(row) => row.id,
+			),
+		).toEqual(["verify"])
+		expect(
+			(await views({ ready: true, pr: false })).executionRows.map(
+				(row) => row.key,
+			),
+		).toEqual(["alpha"])
+		expect((await views({ pr: true })).phaseRows.map((row) => row.id)).toEqual([
+			"implement",
+		])
+	})
+})

package/src/work-view.ts

@@ -0,0 +1,253 @@
+import { Effect } from "effect"
+import type { GraphNode } from "./graph-schema"
+import { GraphService } from "./services/GraphService"
+import type { WorkStatus } from "./workbase/schemas"
+
+type WorkNode = Extract<
+	GraphNode,
+	{ readonly kind: "epic" | "task" | "phase" | "execution-unit" }
+>
+type EntityNode = Exclude<WorkNode, { readonly kind: "execution-unit" }>
+type ExecutionNode = Extract<WorkNode, { readonly kind: "execution-unit" }>
+
+export interface WorkViewOptions {
+	readonly cwd?: string
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly pr?: boolean
+}
+
+export interface WorkViewRow {
+	readonly kind: "epic" | "task" | "phase"
+	readonly id: string
+	readonly key: string
+	readonly parent: string
+	readonly status: WorkStatus
+	readonly readiness: "ready" | "blocked" | "waiting" | "terminal"
+	readonly repositories: string
+	readonly branch: string
+	readonly pr: string
+	readonly worktree: string
+	readonly hasPr: boolean
+}
+
+const allowedStatuses = new Set<WorkStatus>([
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+])
+
+const validatedStatuses = (values: readonly string[] | undefined) =>
+	(values ?? []).map((value) => {
+		if (!allowedStatuses.has(value as WorkStatus)) {
+			throw new Error(
+				`Invalid --status value '${value}'. Expected one of: ${[...allowedStatuses].join(", ")}`,
+			)
+		}
+		return value as WorkStatus
+	})
+
+const readinessLabel = (node: EntityNode): WorkViewRow["readiness"] =>
+	node.readiness.ready
+		? "ready"
+		: node.readiness.terminal
+			? "terminal"
+			: node.readiness.blocked
+				? "blocked"
+				: "waiting"
+
+const aggregateLabel = (
+	executions: readonly ExecutionNode[],
+	predicate: (node: ExecutionNode) => boolean,
+	singular: readonly [present: string, absent: string],
+) => {
+	if (executions.length === 0) return "-"
+	const count = executions.filter(predicate).length
+	if (executions.length === 1) return count === 1 ? singular[0] : singular[1]
+	return `${count}/${executions.length} ${singular[0]}`
+}
+
+const rowFor = (
+	node: EntityNode,
+	executions: readonly ExecutionNode[],
+): WorkViewRow => {
+	const branches = [
+		...new Set(executions.map((execution) => execution.data.branch)),
+	]
+	const parent =
+		node.kind === "task"
+			? (node.data.epic ?? "-")
+			: node.kind === "phase"
+				? node.key.slice(0, node.key.indexOf("/"))
+				: "-"
+	const id =
+		node.kind === "phase" ? node.key.slice(node.key.indexOf("/") + 1) : node.key
+
+	return {
+		kind: node.kind,
+		id,
+		key: node.key,
+		parent,
+		status: node.status,
+		readiness: readinessLabel(node),
+		repositories: node.repositories.join(",") || "-",
+		branch:
+			branches.length === 0
+				? "-"
+				: branches.length === 1
+					? branches[0]!
+					: "multiple",
+		pr: aggregateLabel(executions, (execution) => Boolean(execution.data.pr), [
+			"present",
+			"absent",
+		]),
+		worktree: aggregateLabel(
+			executions,
+			(execution) => execution.workspace?.materialized === true,
+			["materialized", "absent"],
+		),
+		hasPr: executions.some((execution) => Boolean(execution.data.pr)),
+	}
+}
+
+const orderedTasks = (
+	epics: readonly Extract<EntityNode, { readonly kind: "epic" }>[],
+	tasks: ReadonlyMap<string, Extract<EntityNode, { readonly kind: "task" }>>,
+) => {
+	const ordered: Extract<EntityNode, { readonly kind: "task" }>[] = []
+	const seen = new Set<string>()
+	for (const epic of epics) {
+		for (const item of epic.data.tasks) {
+			const task = tasks.get(item.id)
+			if (task && !seen.has(task.key)) {
+				ordered.push(task)
+				seen.add(task.key)
+			}
+		}
+	}
+	for (const task of [...tasks.values()].sort((a, b) =>
+		a.key.localeCompare(b.key),
+	)) {
+		if (!seen.has(task.key)) ordered.push(task)
+	}
+	return ordered
+}
+
+const orderedPhases = (
+	task: Extract<EntityNode, { readonly kind: "task" }>,
+	phases: ReadonlyMap<string, Extract<EntityNode, { readonly kind: "phase" }>>,
+) => {
+	const ordered: Extract<EntityNode, { readonly kind: "phase" }>[] = []
+	const seen = new Set<string>()
+	if ("phases" in task.data) {
+		for (const item of task.data.phases) {
+			const phase = phases.get(`${task.key}/${item.id}`)
+			if (phase) {
+				ordered.push(phase)
+				seen.add(phase.key)
+			}
+		}
+	}
+	for (const phase of [...phases.values()]
+		.filter((value) => value.key.startsWith(`${task.key}/`))
+		.sort((a, b) => a.key.localeCompare(b.key))) {
+		if (!seen.has(phase.key)) ordered.push(phase)
+	}
+	return ordered
+}
+
+export const getWorkViews = (options: WorkViewOptions = {}) =>
+	Effect.gen(function* () {
+		const graphService = yield* GraphService
+		const statuses = yield* Effect.sync(() =>
+			validatedStatuses(options.statuses),
+		)
+		const graph = yield* graphService.get({
+			cwd: options.cwd,
+			include: ["workspace"],
+		})
+		const workNodes = graph.nodes.filter(
+			(node): node is WorkNode => node.kind !== "repository",
+		)
+		const epics = workNodes
+			.filter(
+				(node): node is Extract<EntityNode, { readonly kind: "epic" }> =>
+					node.kind === "epic",
+			)
+			.sort((a, b) => a.key.localeCompare(b.key))
+		const tasks = new Map(
+			workNodes
+				.filter(
+					(node): node is Extract<EntityNode, { readonly kind: "task" }> =>
+						node.kind === "task",
+				)
+				.map((node) => [node.key, node]),
+		)
+		const phases = new Map(
+			workNodes
+				.filter(
+					(node): node is Extract<EntityNode, { readonly kind: "phase" }> =>
+						node.kind === "phase",
+				)
+				.map((node) => [node.key, node]),
+		)
+		const executions = workNodes.filter(
+			(node): node is ExecutionNode => node.kind === "execution-unit",
+		)
+		const taskOrder = orderedTasks(epics, tasks)
+		const phaseOrder = taskOrder.flatMap((task) => orderedPhases(task, phases))
+		const executionsFor = (node: EntityNode) => {
+			if (node.kind === "phase") {
+				const separator = node.key.indexOf("/")
+				const taskId = node.key.slice(0, separator)
+				const phaseId = node.key.slice(separator + 1)
+				return executions.filter(
+					(execution) =>
+						execution.data.taskId === taskId &&
+						execution.data.phaseId === phaseId,
+				)
+			}
+			if (node.kind === "task") {
+				return executions.filter(
+					(execution) => execution.data.taskId === node.key,
+				)
+			}
+			const taskIds = new Set(node.data.tasks.map((item) => item.id))
+			return executions.filter((execution) =>
+				taskIds.has(execution.data.taskId),
+			)
+		}
+		const makeRows = (nodes: readonly EntityNode[]) =>
+			nodes.map((node) => rowFor(node, executionsFor(node)))
+		const filterRows = (rows: readonly WorkViewRow[]) =>
+			rows
+				.filter((row) => statuses.length === 0 || statuses.includes(row.status))
+				.filter(
+					(row) =>
+						!options.repositories?.length ||
+						row.repositories
+							.split(",")
+							.some((repo) => options.repositories!.includes(repo)),
+				)
+				.filter((row) => options.ready !== true || row.readiness === "ready")
+				.filter(
+					(row) => options.blocked !== true || row.readiness === "blocked",
+				)
+				.filter((row) => options.pr === undefined || row.hasPr === options.pr)
+
+		const epicRows = filterRows(makeRows(epics))
+		const taskRows = filterRows(makeRows(taskOrder))
+		const phaseRows = filterRows(makeRows(phaseOrder))
+		const executionEntities: EntityNode[] = []
+		for (const task of taskOrder) {
+			const taskPhases = orderedPhases(task, phases)
+			executionEntities.push(...(taskPhases.length > 0 ? taskPhases : [task]))
+		}
+		const executionRows = filterRows(makeRows(executionEntities))
+
+		return { epicRows, taskRows, phaseRows, executionRows }
+	})