@markjaquith/agency 2.67.0 → 2.69.0

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/pi-extension-file.ts

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const body = `import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"
+
+type AgencyContext = {
+  root?: string
+  checkout?: string
+  target?: string
+}
+
+const contextTarget = (result: Record<string, any>): string | undefined => {
+  const target = result.target
+  if (target?.kind === "epic") return \`epic:\${target.epicId}\`
+  if (target?.kind === "phase") {
+    return \`execution-unit:phase/\${target.taskId}/\${target.phaseId}\`
+  }
+  if (target?.kind === "task") {
+    return result.authority?.mode === "execution"
+      ? \`execution-unit:task/\${target.taskId}\`
+      : \`task:\${target.taskId}\`
+  }
+}
+
+const discoverWorkbase = (directory: string) => {
+  let current = directory
+  while (true) {
+    if (existsSync(join(current, "agency.json"))) return current
+    const parent = dirname(current)
+    if (parent === current) return
+    current = parent
+  }
+}
+
+const discoverCheckout = (directory: string, root: string | undefined) => {
+  if (!root) return
+  let current = directory
+  while (current.startsWith(root)) {
+    for (const name of ["PHASE.md", "TASK.md"]) {
+      const document = join(current, name)
+      if (!existsSync(document)) continue
+      const repo = readFileSync(document, "utf8").match(/^repo:\\s*([^\\s]+)\\s*$/m)?.[1]
+      if (!repo) return
+      const checkout = join(current, "code", repo.replace(/^['\"]|['\"]$/g, ""))
+      return existsSync(checkout) ? checkout : undefined
+    }
+    if (current === root) return
+    current = dirname(current)
+  }
+}
+
+const agencyContext = async (
+  pi: ExtensionAPI,
+  directory: string,
+): Promise<AgencyContext | undefined> => {
+  const task = process.env.AGENCY_TASK_ID
+  const phase = process.env.AGENCY_PHASE_ID
+  const args = task
+    ? ["context", "--task", task, ...(phase ? ["--phase", phase] : []), "--compact", "--json"]
+    : ["context", ".", "--compact", "--json"]
+  const command = await pi.exec("agency", args, { timeout: 5000 })
+  if (command.code !== 0) return
+  const envelope = JSON.parse(command.stdout)
+  if (envelope.ok !== true) return
+  const result = envelope.result ?? {}
+  const target = contextTarget(result)
+  const document = result.target?.path
+  const status = result.documents?.phase?.data?.status ?? result.documents?.task?.data?.status
+  if (
+    result.validation?.valid !== true ||
+    !target ||
+    !document ||
+    dirname(document) !== resolve(directory) ||
+    (target.startsWith("execution-unit:") &&
+      (!result.authority?.writable?.checkoutPath || status !== "working"))
+  ) return
+  return {
+    root: result.workbase?.root,
+    checkout: result.authority?.writable?.checkoutPath,
+    target,
+  }
+}
+
+const extension = (pi: ExtensionAPI) => {
+  const contexts = new Map<string, Promise<AgencyContext | undefined>>()
+  const runtimeContext = (directory: string) => {
+    let context = contexts.get(directory)
+    if (!context) {
+      context = agencyContext(pi, directory).catch(() => undefined)
+      contexts.set(directory, context)
+    }
+    return context
+  }
+
+  pi.on("resources_discover", async (event) => {
+    const context = await runtimeContext(event.cwd)
+    const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(event.cwd)
+    const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(event.cwd, root)
+    if (!checkout) return
+
+    const skillPaths = [
+      join(checkout, ".claude", "skills"),
+      join(checkout, ".agents", "skills"),
+      join(checkout, ".opencode", "skill"),
+      join(checkout, ".opencode", "skills"),
+      join(checkout, CONFIG_DIR_NAME, "skills"),
+    ].filter(existsSync)
+    if (skillPaths.length === 0) return
+    return { skillPaths: [...new Set(skillPaths)] }
+  })
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const context = await runtimeContext(ctx.cwd)
+    const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(ctx.cwd)
+    if (!root) return
+    const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(ctx.cwd, root)
+    const instructionsPath = join(root, ".agency", "AGENTS.md")
+    const instructions = existsSync(instructionsPath)
+      ? readFileSync(instructionsPath, "utf8").trim()
+      : undefined
+    const activeTarget = process.env.AGENCY_TARGET
+    const worker = activeTarget && context?.target === activeTarget
+      ? \`Agency verified this Pi session as the active worker for \${activeTarget}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`
+      : undefined
+    const access = \`The complete Agency workbase is available at \${root}. Use absolute paths under that root when workbase context is needed. Agency context remains the authority for writes.\`
+    const implementation = checkout
+      ? \`Pi remains rooted in the task or phase directory for Agency instructions and context. Treat \${checkout} as the default implementation directory for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.\`
+      : undefined
+
+    return {
+      systemPrompt: [event.systemPrompt, instructions, access, worker, implementation]
+        .filter(Boolean)
+        .join("\\n\\n"),
+    }
+  })
+}
+
+export default extension
+`
+
+const renderManagedWorkbasePiExtension = (content: string) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbasePiExtension = renderManagedWorkbasePiExtension(body)
+
+export const canUpdateManagedWorkbasePiExtension = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}

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)),