@markjaquith/agency 2.68.0 → 2.69.0

package/src/services/WorkbaseService.ts

@@ -8,6 +8,7 @@ import { parseFrontmatter } from "../workbase/frontmatter"
 import {
 	EntityId,
 	EpicFrontmatter,
+	GlobalConfig,
 	LegacyWorkbaseRegistry,
 	PhaseFrontmatter,
 	TaskFrontmatter,
@@ -22,7 +23,7 @@ import {
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
 import { validateWorkspaceCreateCommand } from "../workbase/workspace-command"
 import { validatePostCheckoutCommand } from "../workbase/checkout-command"
-import { validateRunners } from "../workbase/runner-command"
+import { validateAgents } from "../workbase/agent-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
 import { validateDelivery } from "../workbase/delivery-command"
 import { preferredVersionControl } from "../workbase/version-control"
@@ -90,6 +91,15 @@ const registryPath = (configDirectory?: string) =>
 		"workbases.json",
 	)
 
+const globalConfigPath = (configDirectory?: string) =>
+	join(
+		configDirectory ||
+			process.env.XDG_CONFIG_HOME ||
+			join(homedir(), ".config"),
+		"agency",
+		"agency.json",
+	)
+
 const registrationId = (path: string) =>
 	`wb-${new Bun.CryptoHasher("sha256").update(path).digest("hex").slice(0, 12)}`
 
@@ -178,6 +188,32 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 	"WorkbaseService",
 	{
 		sync: () => ({
+			loadGlobalConfig: (configDirectory?: string) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const path = globalConfigPath(configDirectory)
+					if (!(yield* fs.exists(path))) return {}
+					const content = yield* fs.readFile(path)
+					let input: unknown
+					try {
+						input = JSON.parse(content)
+					} catch (cause) {
+						return yield* new WorkbaseConfigError({
+							path,
+							message: `Invalid JSON in global Agency configuration ${path}`,
+							cause,
+						})
+					}
+					const decoded = decode(GlobalConfig, input)
+					if (!decoded.success) {
+						return yield* new WorkbaseConfigError({
+							path,
+							message: `Invalid global Agency configuration in ${path}:\n${decoded.error}`,
+						})
+					}
+					return decoded.value
+				}),
+
 			initialize: (path: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
@@ -309,7 +345,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 									}
 								}
 								try {
-									validateRunners(decoded.value.runners)
+									validateAgents(decoded.value.agents)
 									validateDelivery(decoded.value.delivery)
 								} catch (cause) {
 									return yield* new WorkbaseConfigError({
@@ -317,7 +353,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										message:
 											cause instanceof Error
 												? cause.message
-												: "Invalid runner configuration",
+												: "Invalid agent configuration",
 									})
 								}
 								return current

package/src/workbase/AGENTS.md

@@ -121,7 +121,7 @@ Do not rediscover commands that this recipe or a known-current
    prepare the task with
    `agency work prepare <slug> --evidence <creation-json> --dry-run --json`, then
    execute the returned plan through `task-document-split` to prepare the
-   checkout and open or reuse the background tab. Stop before `runner-start`.
+   checkout and open or reuse the background tab. Stop before `agent-start`.
 3. For work/launch/start/kickoff intent, run that same preflight and execute its
    ordered kickoff steps. The plan owns worktree dry-run/preparation, a
    retry-safe background Herdr tab, the side-by-side task document,
@@ -131,8 +131,8 @@ Do not rediscover commands that this recipe or a known-current
    `agency-kickoff-v1` capability, execute the supplied actions directly. Do not
    call Herdr help, skill, or CLI discovery. If capability/version evidence is
    absent or stale, discovery is the compatibility path; then resume the same
-   idempotency key rather than creating another tab, checkout, or runner.
-5. After the one final context verification succeeds, leave the runner in the
+   idempotency key rather than creating another tab, checkout, or agent.
+5. After the one final context verification succeeds, leave the agent in the
    background and stop. Do not inspect, poll, or babysit it unless the user asks.
 
 Validation evidence is a local, auditable optimization, not authority. Preflight
@@ -153,12 +153,12 @@ IDs and remediation commands before retrying.
 
 `agency work` is the human launch flow: it reconciles managed integration,
 selects work, checks readiness, prepares checkouts, marks execution work
-`working` without creating a claim, and starts the runner. Epic and multi-phase
+`working` without creating a claim, and starts the agent. Epic and multi-phase
 task launches remain orchestration-only. External orchestrators instead claim
-an execution unit, launch and monitor their runner separately, and finish or
+an execution unit, launch and monitor their agent separately, and finish or
 release the claim with the current document revision.
 
-An Agency-launched runner receives process-local worker identity through both
+An Agency-launched agent receives process-local worker identity through both
 the `AGENCY_SESSION_ID` and `AGENCY_TARGET` environment variables and a generated
 prompt beginning `Agency worker launch target: <target>.` Treat either form as
 launch evidence only after `agency context . --json` confirms the same target,
@@ -166,7 +166,7 @@ document paths, valid context, and expected write authority. Once confirmed,
 perform the assigned work directly and never invoke `agency work` to start the
 same target again.
 
-Some runner clients attach to a long-lived process and may not preserve launch
+Some agent clients attach to a long-lived process and may not preserve launch
 environment variables. If the variables and prompt marker are absent, fail safe
 when the initial instruction is a generated `Start`, `Continue`, or `Work on`
 prompt whose absolute document paths match the current directory and the active,

package/src/workbase/{runner-command.test.ts → agent-command.test.ts}

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test"
 import {
 	printableEnvironment,
-	resolveRunnerCommand,
-	runnerEnvironment,
-	validateRunners,
-} from "./runner-command"
+	resolveAgentCommand,
+	agentEnvironment,
+	validateAgents,
+} from "./agent-command"
 
 const variables = {
 	prompt: "Read the task.",
@@ -17,45 +17,55 @@ const variables = {
 	claimRevision: "revision-1",
 }
 
-describe("runner commands", () => {
+describe("agent commands", () => {
 	test("uses promptless interactive commands for built-in presets", () => {
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, false).argv,
+			resolveAgentCommand("opencode2", undefined, variables, false).argv,
 		).toEqual(["opencode2"])
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, true).argv,
+			resolveAgentCommand("opencode2", undefined, variables, true).argv,
 		).toEqual(["opencode2", "--continue"])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, false).argv,
+			resolveAgentCommand("opencode", undefined, variables, false).argv,
 		).toEqual(["opencode"])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, true).argv,
+			resolveAgentCommand("opencode", undefined, variables, true).argv,
 		).toEqual(["opencode", "--continue"])
+		expect(resolveAgentCommand("pi", undefined, variables, false).argv).toEqual(
+			["pi"],
+		)
+		expect(resolveAgentCommand("pi", undefined, variables, true).argv).toEqual([
+			"pi",
+			"--continue",
+		])
 		expect(
-			resolveRunnerCommand("claude", undefined, variables, true).argv,
+			resolveAgentCommand("claude", undefined, variables, true).argv,
 		).toEqual(["claude", "--continue"])
 	})
 
 	test("uses autonomous commands when a prompt is requested", () => {
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, false, true).argv,
+			resolveAgentCommand("opencode2", undefined, variables, false, true).argv,
 		).toEqual(["opencode2", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, true, true).argv,
+			resolveAgentCommand("opencode2", undefined, variables, true, true).argv,
 		).toEqual(["opencode2", "--continue", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, false, true).argv,
+			resolveAgentCommand("opencode", undefined, variables, false, true).argv,
 		).toEqual(["opencode", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, true, true).argv,
+			resolveAgentCommand("opencode", undefined, variables, true, true).argv,
 		).toEqual(["opencode", "--continue", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("claude", undefined, variables, true, true).argv,
+			resolveAgentCommand("pi", undefined, variables, false, true).argv,
+		).toEqual(["pi", "Read the task."])
+		expect(
+			resolveAgentCommand("claude", undefined, variables, true, true).argv,
 		).toEqual(["claude", "--continue", "Read the task."])
 	})
 
 	test("expands configured argv and environment without a shell", () => {
-		const resolved = resolveRunnerCommand(
+		const resolved = resolveAgentCommand(
 			"custom",
 			{
 				custom: {
@@ -79,33 +89,33 @@ describe("runner commands", () => {
 		})
 	})
 
-	test("rejects --auto for configured runners without an auto command", () => {
+	test("rejects --auto for configured agents without an auto command", () => {
 		expect(() =>
-			resolveRunnerCommand(
+			resolveAgentCommand(
 				"custom",
 				{ custom: { command: ["agent"] } },
 				variables,
 				false,
 				true,
 			),
-		).toThrow("Runner 'custom' does not support --auto")
+		).toThrow("Agent 'custom' does not support --auto")
 	})
 
 	test("rejects unknown placeholders", () => {
 		expect(() =>
-			validateRunners({ custom: { command: ["agent", "{unknown}"] } }),
-		).toThrow("Unknown runner 'custom' placeholder: {unknown}")
+			validateAgents({ custom: { command: ["agent", "{unknown}"] } }),
+		).toThrow("Unknown agent 'custom' placeholder: {unknown}")
 	})
 
 	test("provides normalized Agency environment and filters secret values", () => {
 		const environment = {
-			...runnerEnvironment("custom", variables),
+			...agentEnvironment("custom", variables),
 			VISIBLE: "yes",
 			ACCESS_TOKEN: "secret",
 		}
 
 		expect(environment).toMatchObject({
-			AGENCY_RUNNER: "custom",
+			AGENCY_AGENT: "custom",
 			AGENCY_CLAIMANT: "orchestrator",
 			AGENCY_SESSION_ID: "session-1",
 			AGENCY_WORKBASE: "/workbase",

package/src/workbase/{runner-command.ts → agent-command.ts}

@@ -1,6 +1,6 @@
 import type { WorkbaseConfig } from "./schemas"
 
-export interface RunnerCommandVariables {
+export interface AgentCommandVariables {
 	readonly prompt: string
 	readonly workbase: string
 	readonly target: string
@@ -11,7 +11,7 @@ export interface RunnerCommandVariables {
 	readonly claimRevision: string
 }
 
-interface RunnerDefinition {
+interface AgentDefinition {
 	readonly command: readonly string[]
 	readonly autoCommand?: readonly string[]
 	readonly resumeCommand?: readonly string[]
@@ -19,7 +19,7 @@ interface RunnerDefinition {
 	readonly environment?: Readonly<Record<string, string>>
 }
 
-const PLACEHOLDERS = new Set<keyof RunnerCommandVariables>([
+const PLACEHOLDERS = new Set<keyof AgentCommandVariables>([
 	"prompt",
 	"workbase",
 	"target",
@@ -30,7 +30,7 @@ const PLACEHOLDERS = new Set<keyof RunnerCommandVariables>([
 	"claimRevision",
 ])
 
-const BUILTIN_RUNNERS: Readonly<Record<string, RunnerDefinition>> = {
+const BUILTIN_AGENTS: Readonly<Record<string, AgentDefinition>> = {
 	opencode2: {
 		command: ["opencode2"],
 		autoCommand: ["opencode2", "--prompt", "{prompt}"],
@@ -43,6 +43,12 @@ const BUILTIN_RUNNERS: Readonly<Record<string, RunnerDefinition>> = {
 		resumeCommand: ["opencode", "--continue"],
 		autoResumeCommand: ["opencode", "--continue", "--prompt", "{prompt}"],
 	},
+	pi: {
+		command: ["pi"],
+		autoCommand: ["pi", "{prompt}"],
+		resumeCommand: ["pi", "--continue"],
+		autoResumeCommand: ["pi", "--continue", "{prompt}"],
+	},
 	claude: {
 		command: ["claude"],
 		autoCommand: ["claude", "{prompt}"],
@@ -51,48 +57,46 @@ const BUILTIN_RUNNERS: Readonly<Record<string, RunnerDefinition>> = {
 	},
 }
 
-const validateTemplate = (runner: string, value: string) => {
+const validateTemplate = (agent: 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}}`,
-			)
+		if (!PLACEHOLDERS.has(placeholder as keyof AgentCommandVariables)) {
+			throw new Error(`Unknown agent '${agent}' placeholder: {${placeholder}}`)
 		}
 	}
 }
 
-export const validateRunners = (runners: WorkbaseConfig["runners"]): void => {
-	for (const [name, runner] of Object.entries(runners ?? {})) {
+export const validateAgents = (agents: WorkbaseConfig["agents"]): void => {
+	for (const [name, agent] of Object.entries(agents ?? {})) {
 		for (const value of [
-			...runner.command,
-			...(runner.autoCommand ?? []),
-			...(runner.resumeCommand ?? []),
-			...(runner.autoResumeCommand ?? []),
-			...Object.values(runner.environment ?? {}),
+			...agent.command,
+			...(agent.autoCommand ?? []),
+			...(agent.resumeCommand ?? []),
+			...(agent.autoResumeCommand ?? []),
+			...Object.values(agent.environment ?? {}),
 		]) {
 			validateTemplate(name, value)
 		}
 	}
 }
 
-const expand = (value: string, variables: RunnerCommandVariables) =>
+const expand = (value: string, variables: AgentCommandVariables) =>
 	value.replaceAll(
 		/\{([^{}]+)\}/g,
 		(match, placeholder: string) =>
-			variables[placeholder as keyof RunnerCommandVariables] ?? match,
+			variables[placeholder as keyof AgentCommandVariables] ?? match,
 	)
 
-export const resolveRunnerCommand = (
+export const resolveAgentCommand = (
 	name: string,
-	configured: WorkbaseConfig["runners"],
-	variables: RunnerCommandVariables,
+	configured: WorkbaseConfig["agents"],
+	variables: AgentCommandVariables,
 	resume: boolean,
 	auto = false,
 ) => {
-	validateRunners(configured)
-	const definition = configured?.[name] ?? BUILTIN_RUNNERS[name]
-	if (!definition) throw new Error(`Unknown runner: ${name}`)
+	validateAgents(configured)
+	const definition = configured?.[name] ?? BUILTIN_AGENTS[name]
+	if (!definition) throw new Error(`Unknown agent: ${name}`)
 	const template = auto
 		? resume
 			? (definition.autoResumeCommand ?? definition.autoCommand)
@@ -101,7 +105,7 @@ export const resolveRunnerCommand = (
 			? definition.resumeCommand
 			: definition.command
 	if (!template) {
-		throw new Error(`Runner '${name}' does not support --auto`)
+		throw new Error(`Agent '${name}' does not support --auto`)
 	}
 	const argv = template.map((argument) => expand(argument, variables))
 	const environment = Object.fromEntries(
@@ -113,11 +117,11 @@ export const resolveRunnerCommand = (
 	return { argv, environment }
 }
 
-export const runnerEnvironment = (
-	runner: string,
-	variables: RunnerCommandVariables,
+export const agentEnvironment = (
+	agent: string,
+	variables: AgentCommandVariables,
 ): Record<string, string> => ({
-	AGENCY_RUNNER: runner,
+	AGENCY_AGENT: agent,
 	AGENCY_CLAIMANT: variables.claimant,
 	AGENCY_SESSION_ID: variables.sessionId,
 	AGENCY_CLAIM_REVISION: variables.claimRevision,

package/src/workbase/kickoff-contract.ts

@@ -325,11 +325,11 @@ export const buildKickoffPlan = (input: {
 				recovery: "Reuse the existing split when present.",
 			},
 			{
-				id: "runner-start",
+				id: "agent-start",
 				cwd: taskDirectory,
 				argv: ["agency", "work", ".", "--auto"],
 				recovery:
-					"Inspect the recorded tab before retrying; a working runner must not be duplicated.",
+					"Inspect the recorded tab before retrying; a working agent must not be duplicated.",
 			},
 			{
 				id: "final-context-verification",
@@ -341,7 +341,7 @@ export const buildKickoffPlan = (input: {
 				],
 				exactlyOnce: true,
 				recovery:
-					"If verification fails, inspect the existing tab; do not launch another runner.",
+					"If verification fails, inspect the existing tab; do not launch another agent.",
 			},
 		],
 		successFields: [
@@ -351,7 +351,7 @@ export const buildKickoffPlan = (input: {
 			"preparedCheckout",
 			"herdrWorkspace",
 			"herdrTab",
-			"runnerStart",
+			"agentStart",
 			"contextVerification",
 		],
 	}

package/src/workbase/opencode-file.ts

@@ -31,7 +31,7 @@ const body = () =>
 						"Handles Agency workbase orchestration and workflow operations with the Agency CLI",
 					mode: "subagent",
 					prompt:
-						"You are the Agency workflow specialist. Use the Agency CLI to handle delegated workbase orchestration and workflow operations. Always start with `agency context . --json`, follow the managed Agency instructions and reported authority, use Agency commands for durable mutations, and report the resulting state concisely. When delegated to start or kick off work in another agent, launch it, verify that the runner started successfully, and return without waiting for the task to finish.",
+						"You are the Agency workflow specialist. Use the Agency CLI to handle delegated workbase orchestration and workflow operations. Always start with `agency context . --json`, follow the managed Agency instructions and reported authority, use Agency commands for durable mutations, and report the resulting state concisely. When delegated to start or kick off work in another agent, launch it, verify that the agent started successfully, and return without waiting for the task to finish.",
 				},
 				plan: {
 					disable: true,

package/src/workbase/schemas.test.ts

@@ -276,11 +276,11 @@ describe("workspace creation configuration", () => {
 	})
 })
 
-describe("runner configuration", () => {
+describe("agent configuration", () => {
 	test("accepts named argv commands with resume commands and environment", () => {
 		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
 			version: 2,
-			runners: {
+			agents: {
 				custom: {
 					command: ["agent"],
 					autoCommand: ["agent", "{prompt}"],
@@ -291,14 +291,14 @@ describe("runner configuration", () => {
 			},
 		})
 
-		expect(config.runners?.custom?.autoCommand).toEqual(["agent", "{prompt}"])
+		expect(config.agents?.custom?.autoCommand).toEqual(["agent", "{prompt}"])
 	})
 
 	test("rejects shell strings in place of argv arrays", () => {
 		expect(() =>
 			Schema.decodeUnknownSync(WorkbaseConfig)({
 				version: 2,
-				runners: { custom: { command: "agent {prompt}" } },
+				agents: { custom: { command: "agent {prompt}" } },
 			}),
 		).toThrow()
 	})
@@ -423,7 +423,7 @@ describe("work status", () => {
 describe("claim records", () => {
 	const record = {
 		claimant: "orchestrator",
-		runner: "agent",
+		agent: "agent",
 		sessionId: "job-1",
 		startedAt: "2026-07-17T12:00:00.000Z",
 		targetRevision: "0".repeat(64),

package/src/workbase/schemas.ts

@@ -52,7 +52,7 @@ export const DocumentRevision = Schema.String.pipe(
 
 export const ClaimRecord = Schema.Struct({
 	claimant: NonEmptyString,
-	runner: NonEmptyString,
+	agent: NonEmptyString,
 	sessionId: NonEmptyString,
 	startedAt: IsoTimestamp,
 	targetRevision: DocumentRevision,
@@ -110,7 +110,7 @@ export const WorkbaseConfig = Schema.Struct({
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	workspaceCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
-	runners: Schema.optional(
+	agents: Schema.optional(
 		Schema.Record({
 			key: EntityId,
 			value: Schema.Struct({
@@ -146,6 +146,12 @@ export const WorkbaseRegistry = Schema.Struct({
 	defaultId: Schema.optional(EntityId),
 })
 
+export const GlobalConfig = Schema.Struct({
+	agent: Schema.optional(
+		Schema.Literal("opencode2", "opencode", "pi", "claude"),
+	),
+})
+
 export const Dependency = Schema.Struct({
 	id: EntityId,
 	dependsOn: Schema.optional(Schema.Array(EntityId)),