@markjaquith/agency 2.63.0 → 2.64.0

package/README.md

@@ -517,12 +517,13 @@ pull request, dropping, reopening, or archiving. Cancelling either chooser makes
 no changes, and the command refreshes the graph before dispatch so a stale
 selection cannot act on changed work.
 
-Use `--epic <id>`, `--task <id>`, or `--task <id> --phase <id>` to skip work-item
-selection. `--dry-run` still prompts for an action but prints the exact Agency
-command instead of executing it. `--json` never prompts or executes; it returns
-matching targets, status and readiness details, document revisions, and each
-available action's command argv. With no selector, JSON includes every active
-work item.
+Use an existing directory, a positional task ID, `--epic <id>`, `--task <id>`,
+or `--task <id> --phase <id>` to skip work-item selection. For example,
+`agency act .` selects the current task or phase. `--dry-run` still prompts for
+an action but prints the exact Agency command instead of executing it. `--json`
+never prompts or executes; it returns matching targets, status and readiness
+details, document revisions, and each available action's command argv. With no
+selector, JSON includes every active work item.
 
 `--auto` is included in generated or executed work commands, and `--draft` is
 included in generated or executed pull request commands.

package/cli-main.ts

@@ -177,10 +177,11 @@ const VERSION = packageJson.version
 // Define commands
 const commands: Record<string, Command> = {
 	act: {
-		run: async (_args: string[], options: Record<string, any>) => {
+		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(actHelp)
 			await runCommand(
 				act({
+					directory: args[0],
 					auto: options.auto,
 					draft: options.draft,
 					dryRun: options["dry-run"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.63.0",
+  "version": "2.64.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/cli-parser.test.ts

@@ -31,7 +31,10 @@ describe("strict CLI parsing", () => {
 			},
 		})
 		expect(parseCli(["act", "--json"]).values.json).toBe(true)
-		expectUsageError(["act", "task-id"], "agency act")
+		expect(parseCli(["act", "task-id"]).args).toEqual(["task-id"])
+		expect(parseCli(["act", "."]).args).toEqual(["."])
+		expectUsageError(["act", "one", "two"], "agency act")
+		expectUsageError(["act", ".", "--task", "example"], "agency act")
 		expectUsageError(["act", "--phase", "build"], "agency act")
 		expectUsageError(
 			["act", "--epic", "roadmap", "--task", "example"],

package/src/cli-parser.ts

@@ -148,7 +148,7 @@ const commands = {
 	},
 	act: {
 		usage:
-			"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+			"agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
@@ -158,9 +158,9 @@ const commands = {
 		},
 		command: {
 			usage:
-				"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+				"agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
 			minArgs: 0,
-			maxArgs: 0,
+			maxArgs: 1,
 			options: ["epic", "task", "phase", "dry-run", "json", "auto", "draft"],
 			conflicts: [
 				["dry-run", "json"],
@@ -1198,7 +1198,7 @@ function applyEntitySelectors(
 			spec.usage,
 		)
 	}
-	if (commandName === "work" || commandName === "context") {
+	if (["act", "work", "context"].includes(commandName)) {
 		if (
 			positionals.length >
 			(commandName === "work" && positionals[0] === "prepare" ? 1 : 0)

package/src/commands/act.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureLogs,
@@ -118,6 +119,100 @@ describe("act command", () => {
 		expect(await readTaskStatus("example")).toBe("open")
 	})
 
+	test("resolves a positional path and task ID without prompting for an item", async () => {
+		await createTask("example")
+		await mkdir(join(root, "tasks/example/code/agency"), { recursive: true })
+		for (const options of [
+			{ cwd: join(root, "tasks/example"), directory: "." },
+			{ cwd: join(root, "tasks/example"), directory: "code/agency" },
+			{ cwd: root, directory: "example" },
+		]) {
+			const prompts: string[] = []
+			await runTestEffect(
+				act(
+					{ ...options, inputAllowed: true, dryRun: true, silent: true },
+					scriptedInteraction(["drop"], (prompt) => prompts.push(prompt)),
+				),
+			)
+			expect(prompts).toEqual(["Act on task example"])
+		}
+	})
+
+	test("resolves a positional phase path without prompting for an item", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["multi"],
+				multiPhase: true,
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "create",
+				args: ["multi", "build"],
+				repo: "agency",
+				branch: "task/multi-build",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		const prompts: string[] = []
+		await runTestEffect(
+			act(
+				{
+					cwd: join(root, "tasks/multi/phases/build"),
+					directory: ".",
+					inputAllowed: true,
+					dryRun: true,
+					silent: true,
+				},
+				scriptedInteraction(["drop"], (prompt) => prompts.push(prompt)),
+			),
+		)
+
+		expect(prompts).toEqual(["Act on phase multi/build"])
+	})
+
+	test("orders owned items hierarchically and omits items without actions", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["multi"],
+				multiPhase: true,
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "create",
+				args: ["multi", "build"],
+				repo: "agency",
+				branch: "task/multi-build",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		let choices: readonly Choice<unknown>[] = []
+		await runTestEffect(
+			act(
+				{ cwd: root, inputAllowed: true },
+				scriptedInteraction([null], (_prompt, offered) => {
+					choices = offered
+				}),
+			),
+		)
+
+		expect(choices.map((choice) => [choice.value, choice.depth])).toEqual([
+			["task:multi", 0],
+			["phase:multi/build", 1],
+		])
+	})
+
 	test("returns structured actions and argv for agents", async () => {
 		await createTask("example")
 		const logs = await captureLogs(() =>

package/src/commands/act.ts

@@ -1,6 +1,8 @@
 import { Effect } from "effect"
+import { isAbsolute, relative, resolve, sep } from "node:path"
 import type { GraphNode } from "../graph-schema"
 import { isTerminalStatus } from "../readiness"
+import { FileSystemService } from "../services/FileSystemService"
 import { GraphService } from "../services/GraphService"
 import { WorkbaseService } from "../services/WorkbaseService"
 import type { BaseCommandOptions } from "../utils/command"
@@ -29,6 +31,7 @@ export interface ActInteraction {
 }
 
 interface ActOptions extends BaseCommandOptions {
+	readonly directory?: string
 	readonly auto?: boolean
 	readonly draft?: boolean
 	readonly dryRun?: boolean
@@ -49,13 +52,49 @@ const entityDescription = (node: EntityNode) =>
 		? ` - ${node.data.description}`
 		: ""
 
+const orderedEntities = (
+	nodes: readonly EntityNode[],
+	edges: readonly {
+		readonly kind: string
+		readonly from: string
+		readonly to: string
+	}[],
+) => {
+	const byId = new Map(nodes.map((node) => [node.id, node]))
+	const children = new Map<string, EntityNode[]>()
+	const owned = new Set<string>()
+	for (const edge of edges) {
+		if (edge.kind !== "owns") continue
+		const parent = byId.get(edge.from)
+		const child = byId.get(edge.to)
+		if (!parent || !child) continue
+		children.set(edge.from, [...(children.get(edge.from) ?? []), child])
+		owned.add(child.id)
+	}
+
+	const ordered: { readonly node: EntityNode; readonly depth: number }[] = []
+	const append = (node: EntityNode, depth: number) => {
+		ordered.push({ node, depth })
+		for (const child of children.get(node.id) ?? []) append(child, depth + 1)
+	}
+	for (const node of nodes) {
+		if (!owned.has(node.id)) append(node, 0)
+	}
+	return ordered
+}
+
 const entityChoices = (
 	nodes: readonly EntityNode[],
+	edges: readonly {
+		readonly kind: string
+		readonly from: string
+		readonly to: string
+	}[],
 ): readonly Choice<string>[] =>
-	nodes.map((node, index) => ({
+	orderedEntities(nodes, edges).map(({ node, depth }, index) => ({
 		key: String(index),
 		label: `[${node.status}] ${node.kind} ${node.key}${entityDescription(node)}`,
-		depth: node.kind === "phase" ? 1 : 0,
+		depth,
 		segments: [
 			{ text: `[${node.status}] `, color: macchiato.overlay1 },
 			{ text: `${node.kind} `, color: macchiato.sapphire },
@@ -229,6 +268,26 @@ const selectedEntityKey = (options: ActOptions) =>
 				? `task:${options.taskId}`
 				: undefined
 
+const pathEntityKey = (
+	directory: string | undefined,
+	isDirectory: boolean,
+	root: string,
+	startPath: string,
+) => {
+	if (!directory) return undefined
+	if (!isDirectory) return `task:${directory}`
+	const path = relative(root, startPath)
+	const parts =
+		!path || isAbsolute(path) || path.startsWith(`..${sep}`)
+			? []
+			: path.split(sep)
+	if (parts[0] === "epics" && parts[1]) return `epic:${parts[1]}`
+	if (parts[0] !== "tasks" || !parts[1]) return undefined
+	return parts[2] === "phases" && parts[3]
+		? `phase:${parts[1]}/${parts[3]}`
+		: `task:${parts[1]}`
+}
+
 const sameActions = (
 	left: readonly Choice<ActAction>[],
 	right: readonly Choice<ActAction>[],
@@ -250,11 +309,19 @@ export const act = (
 			)
 		}
 		const cwd = options.cwd ?? process.cwd()
+		const fs = yield* FileSystemService
 		const workbase = yield* WorkbaseService
 		const graphs = yield* GraphService
 		const { log } = createLoggers(options)
-		const { config } = yield* workbase.loadConfig(cwd)
-		const graph = yield* graphs.get({ cwd })
+		const directoryPath = options.directory
+			? resolve(cwd, options.directory)
+			: undefined
+		const isDirectory = directoryPath
+			? yield* fs.isDirectory(directoryPath)
+			: false
+		const startPath = isDirectory && directoryPath ? directoryPath : cwd
+		const { root, config } = yield* workbase.loadConfig(startPath)
+		const graph = yield* graphs.get({ cwd: root })
 		const nodes = graph.nodes.filter(
 			(node): node is EntityNode =>
 				node.kind === "epic" || node.kind === "task" || node.kind === "phase",
@@ -269,7 +336,9 @@ export const act = (
 			)
 		}
 
-		const requestedKey = selectedEntityKey(options)
+		const requestedKey =
+			selectedEntityKey(options) ??
+			pathEntityKey(options.directory, isDirectory, root, startPath)
 		const matchingNodes = requestedKey
 			? nodes.filter((node) => entityKey(node) === requestedKey)
 			: nodes
@@ -293,11 +362,21 @@ export const act = (
 			return
 		}
 
+		const selectableNodes = nodes.filter(
+			(node) => actionChoices(node, graph.nodes).length > 0,
+		)
+		if (!requestedKey && selectableNodes.length === 0) {
+			return yield* Effect.fail(
+				new Error(
+					"No work items with available actions found in this workbase",
+				),
+			)
+		}
 		const selectedKey =
 			requestedKey ??
 			(yield* interaction.select(
 				"Act on",
-				entityChoices(nodes),
+				entityChoices(selectableNodes, graph.edges),
 				config.chooserCommand,
 			))
 		if (selectedKey === null) return
@@ -424,10 +503,12 @@ export const act = (
 	})
 
 export const help = `
-Usage: agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]
+Usage: agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]
 
 Interactively choose an active work item and a state-aware lifecycle action.
-Selectors skip work-item selection. --dry-run prints the selected action's exact
+An existing positional directory selects its containing epic, task, or phase;
+otherwise the positional value is a task ID. Selectors skip work-item selection.
+--dry-run prints the selected action's exact
 Agency command without executing it. --json lists targets, available actions,
 and command argv without prompting or executing.
 

package/src/services/IntegrationService.test.ts

@@ -174,6 +174,18 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"Do not invoke agency work for this target",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"as the default implementation directory",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Set each tool's working directory to that checkout when supported",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Run Agency lifecycle and context commands from the task or phase directory",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"reference checkouts reported by Agency context are read-only",
+		)
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			".map((path) => `${path}${sep}.`)",
 		)
@@ -187,23 +199,39 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
-	test("binds validated worker identity to an OpenCode session", async () => {
+	const testWorkerIdentity = async ({
+		target,
+		launchTarget,
+		phase,
+	}: {
+		readonly target:
+			| { readonly kind: "task"; readonly taskId: string }
+			| {
+					readonly kind: "phase"
+					readonly taskId: string
+					readonly phaseId: string
+			  }
+		readonly launchTarget: string
+		readonly phase?: string
+	}) => {
 		const path = join(root, "agency-repository-skills.ts")
+		const checkoutPath = join(root, "code/agency")
 		const contextResponse = JSON.stringify({
 			version: 1,
 			ok: true,
 			result: {
 				workbase: { root },
 				target: {
-					kind: "task",
-					taskId: "example",
-					path: join(root, "TASK.md"),
+					...target,
+					path: join(root, phase ? "PHASE.md" : "TASK.md"),
 				},
 				authority: {
 					mode: "execution",
-					writable: { checkoutPath: join(root, "tasks/example/code/agency") },
+					writable: { checkoutPath },
 				},
-				documents: { task: { data: { status: "working" } } },
+				documents: phase
+					? { phase: { data: { status: "working" } } }
+					: { task: { data: { status: "working" } } },
 				validation: { valid: true, warnings: [] },
 			},
 		})
@@ -225,27 +253,28 @@ describe("IntegrationService", () => {
 			}) as ReturnType<typeof Bun.spawn>) as typeof Bun.spawn
 		try {
 			const generated = await import(
-				`${pathToFileURL(path).href}?worker-identity`
+				`${pathToFileURL(path).href}?worker-identity=${encodeURIComponent(launchTarget)}`
 			)
 			expect(
 				generated.workerLaunchTarget([
 					{
 						type: "text",
-						text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+						text: `Agency worker launch target: ${launchTarget}. Start the task.`,
 					},
 				]),
-			).toBe("execution-unit:task/example")
+			).toBe(launchTarget)
 			expect(generated.workerLaunchTarget(undefined)).toBeUndefined()
 			expect(
 				generated.contextTarget({
-					target: { kind: "task", taskId: "example" },
+					target,
 					authority: { mode: "execution" },
 				}),
-			).toBe("execution-unit:task/example")
+			).toBe(launchTarget)
 			expect(await generated.agencyContext(root)).toMatchObject({
 				root,
-				target: "execution-unit:task/example",
+				target: launchTarget,
 				task: "example",
+				phase,
 			})
 			const hooks = await generated.default({ directory: root } as never)
 			await hooks["chat.message"]!(
@@ -254,7 +283,7 @@ describe("IntegrationService", () => {
 					parts: [
 						{
 							type: "text",
-							text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+							text: `Agency worker launch target: ${launchTarget}. Start the task.`,
 						},
 					],
 				} as never,
@@ -276,11 +305,17 @@ describe("IntegrationService", () => {
 				{ sessionID: "worker-session" } as never,
 				system,
 			)
-			expect(system.system).toEqual([
-				expect.stringContaining(
-					"active worker for execution-unit:task/example",
-				),
-			])
+			expect(system.system).toHaveLength(1)
+			expect(system.system[0]).toContain(`active worker for ${launchTarget}`)
+			expect(system.system[0]).toContain(
+				`${checkoutPath} as the default implementation directory`,
+			)
+			expect(system.system[0]).toContain(
+				"Run Agency lifecycle and context commands from the task or phase directory",
+			)
+			expect(system.system[0]).toContain(
+				"reference checkouts reported by Agency context are read-only",
+			)
 			const mismatchedSystem = { system: [] as string[] }
 			await hooks["experimental.chat.system.transform"]!(
 				{ sessionID: "mismatched-session" } as never,
@@ -292,15 +327,29 @@ describe("IntegrationService", () => {
 			await hooks["shell.env"]!({ sessionID: "worker-session" } as never, shell)
 			expect(shell.env).toMatchObject({
 				AGENCY_SESSION_ID: "worker-session",
-				AGENCY_TARGET: "execution-unit:task/example",
+				AGENCY_TARGET: launchTarget,
 				AGENCY_WORKBASE: root,
 				AGENCY_TASK_ID: "example",
-				AGENCY_WRITABLE_CHECKOUT: join(root, "tasks/example/code/agency"),
+				AGENCY_WRITABLE_CHECKOUT: checkoutPath,
 			})
+			if (phase) expect(shell.env.AGENCY_PHASE_ID).toBe(phase)
 		} finally {
 			Bun.spawn = originalSpawn
 		}
-	})
+	}
+
+	test("binds validated task worker identity to an OpenCode session", () =>
+		testWorkerIdentity({
+			target: { kind: "task", taskId: "example" },
+			launchTarget: "execution-unit:task/example",
+		}))
+
+	test("binds validated phase worker identity to an OpenCode session", () =>
+		testWorkerIdentity({
+			target: { kind: "phase", taskId: "example", phaseId: "build" },
+			launchTarget: "execution-unit:phase/example/build",
+			phase: "build",
+		}))
 
 	test("registers a TUI-only /agency-debug diagnostic", async () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))

package/src/workbase/opencode-plugin-file.ts

@@ -164,7 +164,12 @@ const plugin: Plugin = async ({ directory }) => {
       const context = workerSessions.get(sessionID)
       if (!context?.target) return
       output.system.push(
-        \`Agency verified this OpenCode session as the active worker for \${context.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+        [
+          \`Agency verified this OpenCode session as the active worker for \${context.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+          context.checkout
+            ? \`OpenCode remains rooted in the task or phase directory for Agency instructions and context. Treat \${context.checkout} as the default implementation directory: use it for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Set each tool's working directory to that checkout when supported; otherwise use absolute paths. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.\`
+            : undefined,
+        ].filter(Boolean).join(" "),
       )
     },
     "shell.env": async ({ sessionID }, output) => {