@markjaquith/agency 2.67.0 → 2.69.0

package/src/services/IntegrationService.test.ts

@@ -16,6 +16,10 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
+import {
+	canUpdateManagedWorkbasePiExtension,
+	managedWorkbasePiExtension,
+} from "../workbase/pi-extension-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -65,6 +69,7 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -81,12 +86,18 @@ describe("IntegrationService", () => {
 			".opencode/tui/agency-debug.ts",
 			managedWorkbaseOpencodeTuiPlugin,
 		)
+		await write(
+			root,
+			".pi/extensions/agency-workbase.ts",
+			managedWorkbasePiExtension,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
 			"managed",
 			"managed",
+			"managed",
 		])
 	})
 
@@ -104,6 +115,7 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
 		])
 	})
 
@@ -119,7 +131,7 @@ describe("IntegrationService", () => {
 			"call Herdr help, skill, or CLI discovery",
 		)
 		expect(managedWorkbaseAgents).toContain("exactly one final")
-		expect(managedWorkbaseAgents).toContain("leave the runner in the")
+		expect(managedWorkbaseAgents).toContain("leave the agent in the")
 	})
 
 	test("generates a dynamic workbase plugin", () => {
@@ -208,6 +220,131 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
+	test("generates a Pi extension with workbase context and checkout skills", async () => {
+		expect(managedWorkbasePiExtension).toContain(
+			'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
+		)
+		expect(managedWorkbasePiExtension).toContain('pi.on("resources_discover"')
+		expect(managedWorkbasePiExtension).toContain('pi.on("before_agent_start"')
+		expect(managedWorkbasePiExtension).toContain(
+			'join(checkout, ".agents", "skills")',
+		)
+		expect(managedWorkbasePiExtension).toContain(
+			'join(checkout, CONFIG_DIR_NAME, "skills")',
+		)
+		expect(managedWorkbasePiExtension).toContain(
+			"The complete Agency workbase is available",
+		)
+		expect(managedWorkbasePiExtension).toContain(
+			"Agency context remains the authority for writes",
+		)
+		expect(
+			canUpdateManagedWorkbasePiExtension(managedWorkbasePiExtension),
+		).toBe(true)
+		expect(
+			canUpdateManagedWorkbasePiExtension(
+				managedWorkbasePiExtension.replace("resources_discover", "discover"),
+			),
+		).toBe(false)
+
+		const taskDirectory = join(root, "tasks/example")
+		const checkoutPath = join(taskDirectory, "code/agency")
+		await write(root, ".agency/AGENTS.md", "# Managed Agency instructions\n")
+		await write(
+			root,
+			"tasks/example/TASK.md",
+			"---\nrepo: agency\nstatus: working\n---\n",
+		)
+		await write(
+			root,
+			"tasks/example/code/agency/.agents/skills/example/SKILL.md",
+			"---\nname: example\ndescription: Example.\n---\n",
+		)
+		await write(
+			root,
+			"tasks/example/code/agency/.pi/skills/pi-example/SKILL.md",
+			"---\nname: pi-example\ndescription: Pi example.\n---\n",
+		)
+		const path = join(root, ".pi/extensions/agency-workbase.ts")
+		await write(
+			root,
+			".pi/extensions/agency-workbase.ts",
+			managedWorkbasePiExtension.replace(
+				'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
+				'const CONFIG_DIR_NAME = ".pi"\ntype ExtensionAPI = any',
+			),
+		)
+
+		const contextResponse = JSON.stringify({
+			version: 1,
+			ok: true,
+			result: {
+				workbase: { root },
+				target: {
+					kind: "task",
+					taskId: "example",
+					path: join(taskDirectory, "TASK.md"),
+				},
+				authority: {
+					mode: "execution",
+					writable: { checkoutPath },
+				},
+				documents: { task: { data: { status: "working" } } },
+				validation: { valid: true, warnings: [] },
+			},
+		})
+		const handlers = new Map<string, (...args: any[]) => any>()
+		const pi = {
+			exec: async () => ({ code: 0, stdout: contextResponse, stderr: "" }),
+			on: (name: string, handler: (...args: any[]) => any) => {
+				handlers.set(name, handler)
+			},
+		}
+		const previousTarget = process.env.AGENCY_TARGET
+		const previousWorkbase = process.env.AGENCY_WORKBASE
+		const previousCheckout = process.env.AGENCY_WRITABLE_CHECKOUT
+		delete process.env.AGENCY_WORKBASE
+		delete process.env.AGENCY_WRITABLE_CHECKOUT
+		process.env.AGENCY_TARGET = "execution-unit:task/example"
+		try {
+			const generated = await import(
+				`${pathToFileURL(path).href}?pi-extension=${Date.now()}`
+			)
+			generated.default(pi)
+			const resources = await handlers.get("resources_discover")?.({
+				cwd: taskDirectory,
+				reason: "startup",
+			})
+			expect(resources.skillPaths).toEqual([
+				join(checkoutPath, ".agents/skills"),
+				join(checkoutPath, ".pi/skills"),
+			])
+
+			const prompt = await handlers.get("before_agent_start")?.(
+				{ systemPrompt: "Base prompt" },
+				{ cwd: taskDirectory },
+			)
+			expect(prompt.systemPrompt).toContain("# Managed Agency instructions")
+			expect(prompt.systemPrompt).toContain(
+				`The complete Agency workbase is available at ${root}`,
+			)
+			expect(prompt.systemPrompt).toContain(
+				"active worker for execution-unit:task/example",
+			)
+			expect(prompt.systemPrompt).toContain(
+				`${checkoutPath} as the default implementation directory`,
+			)
+		} finally {
+			if (previousTarget === undefined) delete process.env.AGENCY_TARGET
+			else process.env.AGENCY_TARGET = previousTarget
+			if (previousWorkbase === undefined) delete process.env.AGENCY_WORKBASE
+			else process.env.AGENCY_WORKBASE = previousWorkbase
+			if (previousCheckout === undefined)
+				delete process.env.AGENCY_WRITABLE_CHECKOUT
+			else process.env.AGENCY_WRITABLE_CHECKOUT = previousCheckout
+		}
+	})
+
 	const testWorkerIdentity = async ({
 		target,
 		launchTarget,
@@ -640,7 +777,7 @@ describe("IntegrationService", () => {
 		expect(config.agent.agency.hidden).toBeUndefined()
 		expect(config.agent.agency.steps).toBeUndefined()
 		expect(config.agent.agency.prompt).toContain(
-			"verify that the runner started successfully",
+			"verify that the agent started successfully",
 		)
 		expect(config.agent.agency.prompt).toContain(
 			"return without waiting for the task to finish",
@@ -733,6 +870,7 @@ describe("IntegrationService", () => {
 			{ name: "opencode-plugin", state: "managed", changed: true },
 			{ name: "opencode-tui", state: "managed", changed: true },
 			{ name: "opencode-tui-plugin", state: "managed", changed: true },
+			{ name: "pi-extension", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -757,6 +895,9 @@ describe("IntegrationService", () => {
 		expect(
 			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
 		).toBe(managedWorkbaseOpencodeTuiPlugin)
+		expect(
+			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
+		).toBe(managedWorkbasePiExtension)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -850,6 +991,21 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(legacyPath).exists()).toBe(false)
 	})
 
+	test("preserves a user-owned Pi extension", async () => {
+		const custom = "export default function customPiExtension() {}\n"
+		await write(root, ".pi/extensions/agency-workbase.ts", custom)
+
+		const result = await sync(root)
+		expect(result.files[5]).toMatchObject({
+			name: "pi-extension",
+			state: "customized",
+			changed: false,
+		})
+		expect(
+			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
+		).toBe(custom)
+	})
+
 	test("preserves user-owned TUI config and diagnostic plugin", async () => {
 		const customConfig = '{"theme":"custom"}\n'
 		const customPlugin =

package/src/services/IntegrationService.ts

@@ -23,6 +23,10 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
+import {
+	canUpdateManagedWorkbasePiExtension,
+	managedWorkbasePiExtension,
+} from "../workbase/pi-extension-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
@@ -33,6 +37,7 @@ interface IntegrationFileStatus {
 		| "opencode-plugin"
 		| "opencode-tui"
 		| "opencode-tui-plugin"
+		| "pi-extension"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -131,6 +136,26 @@ const describe = (
 							"Run 'agency integration sync' to install /agency-debug.",
 					}
 	}
+	if (name === "pi-extension") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed Pi extension provides whole-workbase context and exposes writable-checkout skills.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned Pi workbase extension is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed Pi workbase extension needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to provide workbase context and expose writable-checkout skills in Pi.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -190,6 +215,12 @@ const inspect = (root: string) =>
 			"agency-repository-skills.ts",
 		)
 		const tuiPluginPath = join(opencodeDirectory, "tui", "agency-debug.ts")
+		const piExtensionPath = join(
+			root,
+			".pi",
+			"extensions",
+			"agency-workbase.ts",
+		)
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -294,6 +325,22 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "missing"))
 		}
 
+		if ((yield* fs.readSymlinkTarget(piExtensionPath)) !== null) {
+			files.push(fileStatus("pi-extension", piExtensionPath, "customized"))
+		} else if (yield* fs.exists(piExtensionPath)) {
+			files.push(
+				classify(
+					"pi-extension",
+					piExtensionPath,
+					yield* fs.readFile(piExtensionPath),
+					managedWorkbasePiExtension,
+					canUpdateManagedWorkbasePiExtension,
+				),
+			)
+		} else {
+			files.push(fileStatus("pi-extension", piExtensionPath, "missing"))
+		}
+
 		return files
 	})
 
@@ -389,12 +436,15 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							} else if (status.name === "opencode-tui") {
 								yield* fs.createDirectory(join(root, ".opencode"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodeTui)
-							} else {
+							} else if (status.name === "opencode-tui-plugin") {
 								yield* fs.createDirectory(join(root, ".opencode", "tui"))
 								yield* fs.writeFile(
 									status.path,
 									managedWorkbaseOpencodeTuiPlugin,
 								)
+							} else {
+								yield* fs.createDirectory(join(root, ".pi", "extensions"))
+								yield* fs.writeFile(status.path, managedWorkbasePiExtension)
 							}
 						}
 						files.push({

package/src/services/ReadinessService.test.ts

@@ -235,7 +235,7 @@ pr: null
 status: working
 claim:
   claimant: orchestrator
-  runner: opencode
+  agent: opencode
   sessionId: session-1
   startedAt: 2026-07-20T00:00:00.000Z
   targetRevision: ${"a".repeat(64)}

package/src/services/ReviewService.test.ts

@@ -275,7 +275,7 @@ describe("ReviewService", () => {
 						{
 							taskId: "review",
 							claimant: "reviewer",
-							runner: "opencode",
+							agent: "opencode",
 							sessionId: "session",
 							revision: task.revision,
 						},
@@ -311,7 +311,7 @@ describe("ReviewService", () => {
 						{
 							taskId: "review",
 							claimant: "reviewer",
-							runner: "opencode",
+							agent: "opencode",
 							sessionId: "active",
 							revision: task.revision,
 						},

package/src/services/SyncService.test.ts

@@ -238,7 +238,7 @@ pr: null
 						{
 							taskId: "example",
 							claimant: "orchestrator",
-							runner: "agent",
+							agent: "agent",
 							sessionId: "session-1",
 							revision: inspected.revision,
 							expiresAt: "2099-01-01T00:00:00.000Z",
@@ -523,7 +523,7 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 						{
 							taskId: "finished-claim",
 							claimant: "orchestrator",
-							runner: "agent",
+							agent: "agent",
 							sessionId: "session-1",
 							revision: initial.revision,
 						},

package/src/services/VcsMigrationService.test.ts

@@ -288,7 +288,7 @@ describe("VcsMigrationService", () => {
 						{
 							taskId: "example",
 							claimant: "orchestrator",
-							runner: "agent",
+							agent: "agent",
 							sessionId: "session-1",
 							revision: inspected.revision,
 						},

package/src/services/WorkbaseService.test.ts

@@ -41,6 +41,37 @@ describe("WorkbaseService", () => {
 		).toBe(false)
 	})
 
+	test("loads and validates the global agent", async () => {
+		const configDirectory = join(root, "config")
+		await write(
+			configDirectory,
+			"agency/agency.json",
+			JSON.stringify({ agent: "pi" }),
+		)
+
+		const config = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) => service.loadGlobalConfig(configDirectory)),
+			),
+		)
+		expect(config).toEqual({ agent: "pi" })
+
+		await write(
+			configDirectory,
+			"agency/agency.json",
+			JSON.stringify({ agent: "codex" }),
+		)
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) =>
+						service.loadGlobalConfig(configDirectory),
+					),
+				),
+			),
+		).rejects.toThrow("Invalid global Agency configuration")
+	})
+
 	test("treats declared but missing repositories as valid aliases", async () => {
 		await write(
 			root,
@@ -415,13 +446,13 @@ status: done
 		).rejects.toThrow("Repository 'agency'")
 	})
 
-	test("rejects an unknown runner command placeholder", async () => {
+	test("rejects an unknown agent command placeholder", async () => {
 		await write(
 			root,
 			"agency.json",
 			JSON.stringify({
 				version: 2,
-				runners: { custom: { command: ["agent", "{unknown}"] } },
+				agents: { custom: { command: ["agent", "{unknown}"] } },
 			}),
 		)
 

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,