@markjaquith/agency 2.19.0 → 2.21.0

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

@@ -13,7 +13,6 @@ import {
 	TaskFrontmatter,
 	WorkbaseConfig,
 	WorkbaseRegistry,
-	type Dependency,
 	type EpicFrontmatter as EpicData,
 	type PhaseFrontmatter as PhaseData,
 	type TaskFrontmatter as TaskData,
@@ -21,6 +20,8 @@ import {
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import { validateRunners } from "../workbase/runner-command"
+import { findDependencyCycles } from "../workbase/dependency-graph"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -144,40 +145,6 @@ const writeRegistry = (
 		yield* fs.writeJSON(path, registry)
 	})
 
-const findCycles = (nodes: readonly Dependency[]): readonly string[] => {
-	const dependencies = new Map(
-		nodes.map((node) => [node.id, [...(node.dependsOn ?? [])]]),
-	)
-	const visiting = new Set<string>()
-	const visited = new Set<string>()
-	const cycles = new Set<string>()
-
-	const visit = (id: string) => {
-		if (visiting.has(id)) {
-			cycles.add(id)
-			return
-		}
-		if (visited.has(id)) {
-			return
-		}
-
-		visiting.add(id)
-		for (const dependency of dependencies.get(id) ?? []) {
-			if (dependencies.has(dependency)) {
-				visit(dependency)
-			}
-		}
-		visiting.delete(id)
-		visited.add(id)
-	}
-
-	for (const id of dependencies.keys()) {
-		visit(id)
-	}
-
-	return [...cycles].sort()
-}
-
 export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 	"WorkbaseService",
 	{
@@ -277,6 +244,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
 							}
 						}
@@ -681,7 +659,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								}
 							}
 						}
-						for (const cycle of findCycles(epic.data.tasks)) {
+						for (const cycle of findDependencyCycles(epic.data.tasks)) {
 							issue(epic.path, `Task dependency cycle includes '${cycle}'`)
 						}
 					}
@@ -727,7 +705,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 									issue(task.path, `Unlisted phase '${phaseId}'`)
 								}
 							}
-							for (const cycle of findCycles(task.data.phases)) {
+							for (const cycle of findDependencyCycles(task.data.phases)) {
 								issue(task.path, `Phase dependency cycle includes '${cycle}'`)
 							}
 						} else if (actualPhaseIds.length > 0) {

package/src/test-utils.ts

@@ -18,6 +18,7 @@ import { GraphService } from "./services/GraphService"
 import { ClaimService } from "./services/ClaimService"
 import { SyncService } from "./services/SyncService"
 import { ReadinessService } from "./services/ReadinessService"
+import { GraphMutationService } from "./services/GraphMutationService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -40,6 +41,7 @@ const TestLayer = Layer.mergeAll(
 	ClaimService.Default,
 	SyncService.Default,
 	ReadinessService.Default,
+	GraphMutationService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/workbase/dependency-graph.ts

@@ -0,0 +1,51 @@
+import type { Dependency } from "./schemas"
+
+export const findDependencyCycles = (
+	nodes: readonly Dependency[],
+): readonly string[] => {
+	const dependencies = new Map(
+		nodes.map((node) => [node.id, [...(node.dependsOn ?? [])]]),
+	)
+	const visiting = new Set<string>()
+	const visited = new Set<string>()
+	const cycles = new Set<string>()
+
+	const visit = (id: string) => {
+		if (visiting.has(id)) {
+			cycles.add(id)
+			return
+		}
+		if (visited.has(id)) return
+
+		visiting.add(id)
+		for (const dependency of dependencies.get(id) ?? []) {
+			if (dependencies.has(dependency)) visit(dependency)
+		}
+		visiting.delete(id)
+		visited.add(id)
+	}
+
+	for (const id of dependencies.keys()) visit(id)
+	return [...cycles].sort()
+}
+
+export const validateDependencies = (
+	nodes: readonly Dependency[],
+	label: string,
+): string | undefined => {
+	const singular = label.endsWith("s") ? label.slice(0, -1) : label
+	const ids = new Set(nodes.map((node) => node.id))
+	if (ids.size !== nodes.length) return `${label} IDs must be unique`
+	for (const node of nodes) {
+		for (const dependency of node.dependsOn ?? []) {
+			if (dependency === node.id) {
+				return `${singular} '${node.id}' cannot depend on itself`
+			}
+			if (!ids.has(dependency)) {
+				return `Unknown ${singular.toLowerCase()} dependency '${dependency}'`
+			}
+		}
+	}
+	const cycle = findDependencyCycles(nodes)[0]
+	return cycle ? `${singular} dependency cycle includes '${cycle}'` : undefined
+}

package/src/workbase/runner-command.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test"
+import {
+	printableEnvironment,
+	resolveRunnerCommand,
+	runnerEnvironment,
+	validateRunners,
+} from "./runner-command"
+
+const variables = {
+	prompt: "Read the task.",
+	workbase: "/workbase",
+	target: "execution-unit:phase/task/build",
+	task: "task",
+	phase: "build",
+	claimant: "orchestrator",
+	sessionId: "session-1",
+	claimRevision: "revision-1",
+}
+
+describe("runner commands", () => {
+	test("uses deterministic fresh and resume commands for built-in presets", () => {
+		expect(
+			resolveRunnerCommand("opencode", undefined, variables, false).argv,
+		).toEqual(["opencode", "--prompt", "Read the task."])
+		expect(
+			resolveRunnerCommand("opencode", undefined, variables, true).argv,
+		).toEqual(["opencode", "--continue", "--prompt", "Read the task."])
+		expect(
+			resolveRunnerCommand("claude", undefined, variables, true).argv,
+		).toEqual(["claude", "--continue", "Read the task."])
+	})
+
+	test("expands configured argv and environment without a shell", () => {
+		const resolved = resolveRunnerCommand(
+			"custom",
+			{
+				custom: {
+					command: ["agent", "--target={target}", "{prompt}"],
+					environment: { CUSTOM_SESSION: "{sessionId}" },
+				},
+			},
+			variables,
+			false,
+		)
+
+		expect(resolved).toEqual({
+			argv: [
+				"agent",
+				"--target=execution-unit:phase/task/build",
+				"Read the task.",
+			],
+			environment: { CUSTOM_SESSION: "session-1" },
+		})
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			validateRunners({ custom: { command: ["agent", "{unknown}"] } }),
+		).toThrow("Unknown runner 'custom' placeholder: {unknown}")
+	})
+
+	test("provides normalized Agency environment and filters secret values", () => {
+		const environment = {
+			...runnerEnvironment("custom", variables),
+			VISIBLE: "yes",
+			ACCESS_TOKEN: "secret",
+		}
+
+		expect(environment).toMatchObject({
+			AGENCY_RUNNER: "custom",
+			AGENCY_CLAIMANT: "orchestrator",
+			AGENCY_TARGET: "execution-unit:phase/task/build",
+			AGENCY_TASK_ID: "task",
+			AGENCY_PHASE_ID: "build",
+		})
+		expect(printableEnvironment(environment).VISIBLE).toBe("yes")
+		expect(printableEnvironment(environment).ACCESS_TOKEN).toBeUndefined()
+	})
+})

package/src/workbase/runner-command.ts

@@ -0,0 +1,118 @@
+import type { WorkbaseConfig } from "./schemas"
+
+export interface RunnerCommandVariables {
+	readonly prompt: string
+	readonly workbase: string
+	readonly target: string
+	readonly task: string
+	readonly phase: string
+	readonly claimant: string
+	readonly sessionId: string
+	readonly claimRevision: string
+}
+
+interface RunnerDefinition {
+	readonly command: readonly string[]
+	readonly resumeCommand?: readonly string[]
+	readonly environment?: Readonly<Record<string, string>>
+}
+
+const PLACEHOLDERS = new Set<keyof RunnerCommandVariables>([
+	"prompt",
+	"workbase",
+	"target",
+	"task",
+	"phase",
+	"claimant",
+	"sessionId",
+	"claimRevision",
+])
+
+const BUILTIN_RUNNERS: Readonly<Record<string, RunnerDefinition>> = {
+	opencode: {
+		command: ["opencode", "--prompt", "{prompt}"],
+		resumeCommand: ["opencode", "--continue", "--prompt", "{prompt}"],
+	},
+	claude: {
+		command: ["claude", "{prompt}"],
+		resumeCommand: ["claude", "--continue", "{prompt}"],
+	},
+}
+
+const validateTemplate = (runner: string, value: string) => {
+	for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+		const placeholder = match[1]!
+		if (!PLACEHOLDERS.has(placeholder as keyof RunnerCommandVariables)) {
+			throw new Error(
+				`Unknown runner '${runner}' placeholder: {${placeholder}}`,
+			)
+		}
+	}
+}
+
+export const validateRunners = (runners: WorkbaseConfig["runners"]): void => {
+	for (const [name, runner] of Object.entries(runners ?? {})) {
+		for (const value of [
+			...runner.command,
+			...(runner.resumeCommand ?? []),
+			...Object.values(runner.environment ?? {}),
+		]) {
+			validateTemplate(name, value)
+		}
+	}
+}
+
+const expand = (value: string, variables: RunnerCommandVariables) =>
+	value.replaceAll(
+		/\{([^{}]+)\}/g,
+		(match, placeholder: string) =>
+			variables[placeholder as keyof RunnerCommandVariables] ?? match,
+	)
+
+export const resolveRunnerCommand = (
+	name: string,
+	configured: WorkbaseConfig["runners"],
+	variables: RunnerCommandVariables,
+	resume: boolean,
+) => {
+	validateRunners(configured)
+	const definition = configured?.[name] ?? BUILTIN_RUNNERS[name]
+	if (!definition) throw new Error(`Unknown runner: ${name}`)
+	const template =
+		resume && definition.resumeCommand
+			? definition.resumeCommand
+			: definition.command
+	const argv = template.map((argument) => expand(argument, variables))
+	const environment = Object.fromEntries(
+		Object.entries(definition.environment ?? {}).map(([key, value]) => [
+			key,
+			expand(value, variables),
+		]),
+	)
+	return { argv, environment }
+}
+
+export const runnerEnvironment = (
+	runner: string,
+	variables: RunnerCommandVariables,
+): Record<string, string> => ({
+	AGENCY_RUNNER: runner,
+	AGENCY_CLAIMANT: variables.claimant,
+	AGENCY_SESSION_ID: variables.sessionId,
+	AGENCY_CLAIM_REVISION: variables.claimRevision,
+	AGENCY_WORKBASE: variables.workbase,
+	AGENCY_TARGET: variables.target,
+	AGENCY_TASK_ID: variables.task,
+	AGENCY_PHASE_ID: variables.phase,
+	AGENCY_PROMPT: variables.prompt,
+})
+
+const SECRET_NAME =
+	/(secret|token|password|credential|api[_-]?key|private[_-]?key)/i
+
+export const printableEnvironment = (environment: Record<string, string>) =>
+	Object.fromEntries(
+		Object.entries(environment)
+			.filter(([key]) => !SECRET_NAME.test(key))
+			.sort(([left], [right]) => left.localeCompare(right)),
+	)

package/src/workbase/schemas.test.ts

@@ -78,6 +78,32 @@ describe("body-of-work descriptions", () => {
 	})
 })
 
+describe("runner configuration", () => {
+	test("accepts named argv commands with resume commands and environment", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			runners: {
+				custom: {
+					command: ["agent", "{prompt}"],
+					resumeCommand: ["agent", "resume", "{sessionId}"],
+					environment: { CUSTOM_TARGET: "{target}" },
+				},
+			},
+		})
+
+		expect(config.runners?.custom?.command).toEqual(["agent", "{prompt}"])
+	})
+
+	test("rejects shell strings in place of argv arrays", () => {
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseConfig)({
+				version: 2,
+				runners: { custom: { command: "agent {prompt}" } },
+			}),
+		).toThrow()
+	})
+})
+
 describe("work status", () => {
 	const supportedStatuses: Record<WorkStatus, true> = {
 		open: true,

package/src/workbase/schemas.ts

@@ -1,6 +1,9 @@
 import { Schema } from "@effect/schema"
 
 const NonEmptyString = Schema.String.pipe(Schema.minLength(1))
+const EnvironmentName = NonEmptyString.pipe(
+	Schema.pattern(/^[A-Za-z_][A-Za-z0-9_]*$/),
+)
 
 const Description = Schema.optional(NonEmptyString)
 
@@ -52,6 +55,18 @@ export const WorkbaseConfig = Schema.Struct({
 	version: Schema.Literal(2),
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+	runners: Schema.optional(
+		Schema.Record({
+			key: EntityId,
+			value: Schema.Struct({
+				command: Schema.NonEmptyArray(NonEmptyString),
+				resumeCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+				environment: Schema.optional(
+					Schema.Record({ key: EnvironmentName, value: Schema.String }),
+				),
+			}),
+		}),
+	),
 })
 
 export const LegacyWorkbaseRegistry = Schema.Struct({