@markjaquith/agency 2.18.0 → 2.20.0

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({