@markjaquith/agency 3.2.2 → 3.2.4

package/src/cli-parser.test.ts

@@ -7,6 +7,25 @@ const expectUsageError = (args: string[], usage: string) => {
 }
 
 describe("strict CLI parsing", () => {
+	test("returns canonical paths without positional values", () => {
+		expect(parseCli(["task", "show", "private-task-id"]).commandPath).toBe(
+			"task/show",
+		)
+		expect(parseCli(["validate", "/private/customer/path"]).commandPath).toBe(
+			"validate",
+		)
+		expect(parseCli(["work", "prepare", "private-task-id"]).commandPath).toBe(
+			"work/prepare",
+		)
+		expect(parseCli(["pr", "view", "private-task-id"]).commandPath).toBe("pr")
+		try {
+			parseCli(["task", "create", "private-task-id"])
+			expect.unreachable()
+		} catch (error) {
+			expect(error).toMatchObject({ commandPath: "task/create" })
+		}
+	})
+
 	test("parses act selectors, dry-run, and JSON options", () => {
 		expect(
 			parseCli([
@@ -338,51 +357,6 @@ describe("strict CLI parsing", () => {
 			[["graph", "extra"], "agency graph"],
 			[["next", "extra"], "agency next"],
 			[["sync", "one", "two", "three"], "agency sync"],
-			[
-				[
-					"claim",
-					"one",
-					"two",
-					"three",
-					"--claimant",
-					"a",
-					"--agent",
-					"r",
-					"--session-id",
-					"s",
-					"--revision",
-					"0".repeat(64),
-				],
-				"agency claim",
-			],
-			[
-				[
-					"release",
-					"one",
-					"two",
-					"three",
-					"--session-id",
-					"s",
-					"--revision",
-					"0".repeat(64),
-				],
-				"agency release",
-			],
-			[
-				[
-					"finish",
-					"one",
-					"two",
-					"three",
-					"--session-id",
-					"s",
-					"--revision",
-					"0".repeat(64),
-					"--outcome",
-					"done",
-				],
-				"agency finish",
-			],
 		] as const) {
 			expectUsageError([...args], usage)
 		}
@@ -408,6 +382,7 @@ describe("strict CLI parsing", () => {
 		const args = ["create", "--title", "two words", "--", "--literal"]
 		expect(parseCli(["--cwd", "/workbase", "pr", ...args])).toEqual({
 			commandName: "pr",
+			commandPath: "pr",
 			args,
 			passthrough: true,
 			values: { cwd: "/workbase" },
@@ -427,6 +402,7 @@ describe("strict CLI parsing", () => {
 			]),
 		).toEqual({
 			commandName: "pr",
+			commandPath: "pr/create",
 			args: ["create", "ship", "release"],
 			values: { draft: true, force: true, json: true },
 		})
@@ -500,76 +476,10 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
-	test("validates revision-guarded claim operations", () => {
-		const revision = "0".repeat(64)
-		expect(
-			parseCli([
-				"claim",
-				"task",
-				"phase",
-				"--claimant",
-				"orchestrator",
-				"--agent",
-				"agent",
-				"--session-id",
-				"job-1",
-				"--revision",
-				revision,
-				"--expires-at",
-				"2026-07-17T13:00:00.000Z",
-			]),
-		).toMatchObject({ commandName: "claim", args: ["task", "phase"] })
-		expect(() =>
-			parseCli(["release", "task", "--session-id", "job-1"]),
-		).toThrow("--revision' is required")
-		expect(() =>
-			parseCli([
-				"finish",
-				"task",
-				"--session-id",
-				"job-1",
-				"--revision",
-				revision,
-				"--outcome",
-				"working",
-			]),
-		).toThrow("must be 'done' or 'dropped'")
-		expect(
-			parseCli([
-				"finish",
-				"task",
-				"--session-id",
-				"job-1",
-				"--revision",
-				revision,
-				"--outcome",
-				"done",
-				"--no-pull-request",
-				"--summary",
-				"Investigation completed",
-				"--evidence-url",
-				"https://example.com/result",
-			]),
-		).toMatchObject({
-			values: {
-				"no-pull-request": true,
-				summary: "Investigation completed",
-				"evidence-url": "https://example.com/result",
-			},
-		})
-		expect(() =>
-			parseCli([
-				"finish",
-				"task",
-				"--session-id",
-				"job-1",
-				"--revision",
-				revision,
-				"--outcome",
-				"done",
-				"--no-pull-request",
-			]),
-		).toThrow("--summary' is required")
+	test("rejects removed claim protocol commands", () => {
+		for (const command of ["claim", "release", "finish"]) {
+			expect(() => parseCli([command])).toThrow(`Unknown command '${command}'`)
+		}
 		expect(() =>
 			parseCli([
 				"task",
@@ -649,6 +559,15 @@ describe("strict CLI parsing", () => {
 		expect(() => parseCli(["work", "prepare", "--opencode"])).toThrow(
 			"cannot be combined",
 		)
+		expect(() => parseCli(["work", "prepare", "first", "second"])).toThrow(
+			"Expected 0-2 positional arguments",
+		)
+		expect(() =>
+			parseCli(["work", "prepare", "example", "--task", "other"]),
+		).toThrow("Entity selector options cannot be combined")
+		expect(() => parseCli(["work", "prepare", "--phase", "build"])).toThrow(
+			"requires '--task'",
+		)
 	})
 
 	test("parses worktree lifecycle commands and selectors", () => {
@@ -977,23 +896,6 @@ describe("strict CLI parsing", () => {
 			commandName: "phase",
 			args: ["status", "ship", "release", "done"],
 		})
-		expect(
-			parseCli([
-				"claim",
-				"--task",
-				"ship",
-				"--phase",
-				"release",
-				"--claimant",
-				"agent",
-				"--agent",
-				"opencode",
-				"--session-id",
-				"session",
-				"--revision",
-				"0".repeat(64),
-			]),
-		).toMatchObject({ args: ["ship", "release"] })
 		expect(parseCli(["context", "--epic", "delivery"]).values.epic).toBe(
 			"delivery",
 		)

package/src/cli-parser.ts

@@ -114,21 +114,6 @@ const mutationOptions = {
 	"no-epic": { type: "boolean" },
 } satisfies OptionConfig
 
-const claimOptions = {
-	...outputOptions,
-	claimant: { type: "string" },
-	agent: { type: "string" },
-	"session-id": { type: "string" },
-	revision: { type: "string" },
-	"expires-at": { type: "string" },
-} satisfies OptionConfig
-
-const ownedClaimOptions = {
-	...outputOptions,
-	"session-id": { type: "string" },
-	revision: { type: "string" },
-} satisfies OptionConfig
-
 const nonPrCompletionOptions = {
 	"no-pull-request": { type: "boolean" },
 	summary: { type: "string" },
@@ -679,75 +664,6 @@ const commands = {
 			},
 		},
 	},
-	claim: {
-		usage: "agency claim <task-id> [phase-id] [options]",
-		options: {
-			...claimOptions,
-			task: { type: "string" },
-			phase: { type: "string" },
-		},
-		command: {
-			usage:
-				"agency claim <task-id> [phase-id] --claimant <id> --agent <id> --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]",
-			minArgs: 1,
-			maxArgs: 2,
-			options: [
-				"claimant",
-				"agent",
-				"session-id",
-				"revision",
-				"expires-at",
-				"json",
-				"task",
-				"phase",
-			],
-			required: ["claimant", "agent", "session-id", "revision"],
-		},
-	},
-	release: {
-		usage: "agency release <task-id> [phase-id] [options]",
-		options: {
-			...ownedClaimOptions,
-			task: { type: "string" },
-			phase: { type: "string" },
-		},
-		command: {
-			usage:
-				"agency release <task-id> [phase-id] --session-id <id> --revision <sha256> [--json]",
-			minArgs: 1,
-			maxArgs: 2,
-			options: ["session-id", "revision", "json", "task", "phase"],
-			required: ["session-id", "revision"],
-		},
-	},
-	finish: {
-		usage: "agency finish <task-id> [phase-id] [options]",
-		options: {
-			...ownedClaimOptions,
-			...nonPrCompletionOptions,
-			outcome: { type: "string" },
-			task: { type: "string" },
-			phase: { type: "string" },
-		},
-		command: {
-			usage:
-				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [options] [--json]",
-			minArgs: 1,
-			maxArgs: 2,
-			options: [
-				"session-id",
-				"revision",
-				"outcome",
-				"no-pull-request",
-				"summary",
-				"evidence-url",
-				"json",
-				"task",
-				"phase",
-			],
-			required: ["session-id", "revision", "outcome"],
-		},
-	},
 	sync: {
 		usage: "agency sync [<task-id> [phase-id]] [--dry-run] [--json]",
 		options: {
@@ -1116,6 +1032,7 @@ const preCommandValueOptions = new Set(["--workbase", "--cwd"])
 
 export interface ParsedCli {
 	readonly commandName?: keyof typeof commands
+	readonly commandPath: string
 	readonly args: string[]
 	readonly passthrough?: boolean
 	readonly values: Record<
@@ -1124,8 +1041,14 @@ export interface ParsedCli {
 	>
 }
 
+const canonicalCommandPath = (
+	commandName: string,
+	subcommand: string | undefined,
+) => (subcommand ? `${commandName}/${subcommand}` : commandName)
+
 class CliUsageError extends Error {
 	readonly _tag = "CliUsageError"
+	readonly commandPath: string
 
 	constructor(
 		readonly detail: string,
@@ -1133,6 +1056,15 @@ class CliUsageError extends Error {
 	) {
 		super(`${detail}\n\nUsage: ${usage}`)
 		this.name = "CliUsageError"
+		const [, commandName, subcommand] = usage.split(/\s+/)
+		const definition: CommandDefinition | undefined =
+			commands[commandName as keyof typeof commands]
+		this.commandPath = !definition
+			? "invalid"
+			: subcommand && definition.subcommands?.[subcommand]
+				? `${commandName}/${subcommand}`
+				: commandName!
+		Object.defineProperty(this, "commandPath", { enumerable: false })
 	}
 }
 
@@ -1177,8 +1109,6 @@ const targetSlots = (
 		return ["task"]
 	if (commandName === "phase")
 		return subcommand === "list" ? ["task"] : ["task", "phase"]
-	if (["claim", "release", "finish"].includes(commandName))
-		return ["task", "phase"]
 	if (["archive", "restore"].includes(commandName))
 		return subcommand === "epic"
 			? ["epic"]
@@ -1409,7 +1339,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 				"agency <command> [options]",
 			)
 		}
-		return { args: [], values: parsed.values }
+		return { commandPath: "root", args: [], values: parsed.values }
 	}
 
 	const commandName = args[commandIndex]!
@@ -1454,6 +1384,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		}
 		return {
 			commandName,
+			commandPath: "pr",
 			args: prArgs,
 			passthrough: true,
 			values: parsed.values,
@@ -1477,6 +1408,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		assertNoDuplicateOptions(parsed.tokens, new Set(), definition.usage)
 		return {
 			commandName: commandName as keyof typeof commands,
+			commandPath: commandName,
 			args: parsed.positionals,
 			values: parsed.values,
 		}
@@ -1527,6 +1459,10 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (parsed.values.version) {
 		return {
 			commandName: commandName as keyof typeof commands,
+			commandPath: canonicalCommandPath(
+				commandName,
+				selectedSubcommand ? subcommand : undefined,
+			),
 			args: parsed.positionals,
 			values: parsed.values,
 		}
@@ -1534,6 +1470,10 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (parsed.values.help) {
 		return {
 			commandName: commandName as keyof typeof commands,
+			commandPath: canonicalCommandPath(
+				commandName,
+				selectedSubcommand ? subcommand : undefined,
+			),
 			args: parsed.positionals,
 			values: parsed.values,
 		}
@@ -1637,16 +1577,6 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	) {
 		validateViewOptions(parsed.values, spec)
 	}
-	if (
-		commandName === "finish" &&
-		parsed.values.outcome !== "done" &&
-		parsed.values.outcome !== "dropped"
-	) {
-		throw usageError(
-			"Option '--outcome' must be 'done' or 'dropped'.",
-			spec.usage,
-		)
-	}
 	const nonPrCompletion = parsed.values["no-pull-request"] === true
 	const completionSummary = parsed.values.summary
 	const completionEvidenceUrl = parsed.values["evidence-url"]
@@ -1670,19 +1600,24 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			)
 		}
 		const completesDone =
-			(commandName === "finish" && parsed.values.outcome === "done") ||
-			(["task", "phase"].includes(commandName) &&
-				subcommand === "status" &&
-				commandPositionals.at(-1) === "done")
+			["task", "phase"].includes(commandName) &&
+			subcommand === "status" &&
+			commandPositionals.at(-1) === "done"
 		if (!completesDone) {
 			throw usageError(
-				"Option '--no-pull-request' is valid only with a done status or outcome.",
+				"Option '--no-pull-request' is valid only with a done status.",
 				spec.usage,
 			)
 		}
 	}
 	if (commandName === "work") {
 		const preparing = commandPositionals[0] === "prepare"
+		if (preparing && parsed.values.phase && !parsed.values.task) {
+			throw usageError(
+				"Option '--phase' requires '--task' with work preparation.",
+				spec.usage,
+			)
+		}
 		if (
 			(!preparing && commandPositionals.length > 1) ||
 			(preparing &&
@@ -1713,6 +1648,14 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	return {
 		commandName: commandName as keyof typeof commands,
+		commandPath: canonicalCommandPath(
+			commandName,
+			selectedSubcommand
+				? subcommand
+				: commandName === "work" && commandPositionals[0] === "prepare"
+					? "prepare"
+					: undefined,
+		),
 		args: selectedSubcommand
 			? [subcommand!, ...commandPositionals]
 			: commandPositionals,

package/src/cli.test.ts

@@ -179,10 +179,31 @@ describe("CLI", () => {
 			XDG_STATE_HOME: state,
 			AGENCY_SESSION_ID: "cli-session",
 			AGENCY_NO_USAGE_LOG: "0",
+			AGENCY_INVOCATION_SOURCE: "automation",
+			AGENCY_USAGE_TEST: "1",
 		}
 		expect((await runCli(["--version"], projectRoot, env)).exitCode).toBe(0)
 		expect(
-			(await runCli(["unknown", "--cwd", "/private/value"], projectRoot, env))
+			(
+				await runCli(
+					[
+						"task",
+						"create",
+						"private-customer-id",
+						"--repo",
+						"private-repository",
+						"--description",
+						"private free-form input",
+						"--cwd",
+						"/private/customer/path",
+					],
+					projectRoot,
+					env,
+				)
+			).exitCode,
+		).toBe(1)
+		expect(
+			(await runCli(["unknown", "--private-flag=value"], projectRoot, env))
 				.exitCode,
 		).toBe(1)
 
@@ -194,147 +215,60 @@ describe("CLI", () => {
 			.map((line) => JSON.parse(line))
 		expect(events).toEqual([
 			expect.objectContaining({
-				sessionId: "cli-session",
-				sessionSequence: 1,
+				journeyId: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+				journeySequence: 1,
+				invocationSource: "automation",
+				isTest: true,
 				commandPath: "version",
 				flagNames: ["version"],
 				outcome: "success",
+				outcomeCode: "SUCCESS",
 			}),
 			expect.objectContaining({
-				sessionSequence: 2,
+				journeySequence: 2,
+				commandPath: "task/create",
+				flagNames: ["cwd", "description", "repo"],
+				outcome: "failure",
+				outcomeCode: "WORKBASE_NOT_FOUND",
+			}),
+			expect.objectContaining({
+				journeySequence: 3,
 				commandPath: "invalid",
-				flagNames: ["cwd"],
+				flagNames: [],
 				outcome: "failure",
+				outcomeCode: "CLI_USAGE",
 			}),
 		])
-		expect(exported.stdout).not.toContain("/private/value")
+		for (const value of [
+			"cli-session",
+			"private-customer-id",
+			"private-repository",
+			"private free-form input",
+			"/private/customer/path",
+			"private-flag",
+			"value",
+		]) {
+			expect(exported.stdout).not.toContain(value)
+		}
 	})
 
-	test("coordinates claims through revision-guarded machine commands", async () => {
+	test("records status-based non-PR completion", async () => {
 		const root = await createTempDir()
 		tempDirs.push(root)
 		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
 		await mkdir(join(root, "repos", "agency"), { recursive: true })
-		parseJson(
-			await runCli(
-				["task", "create", "claimed", "--repo", "agency", "--json"],
-				root,
-			),
-		)
-		const context = parseJson(
-			await runCli(["context", "tasks/claimed", "--json"], root),
-		)
-		const revision = context.documents.task.sha256
-		const claimed = parseJson(
-			await runCli(
-				[
-					"claim",
-					"claimed",
-					"--claimant",
-					"orchestrator",
-					"--agent",
-					"agent",
-					"--session-id",
-					"job-1",
-					"--revision",
-					revision,
-					"--json",
-				],
-				root,
-			),
-		)
-		expect(claimed.claim).toMatchObject({
-			claimant: "orchestrator",
-			agent: "agent",
-			sessionId: "job-1",
-			state: "active",
-		})
-
-		const conflict = await runCli(
-			[
-				"claim",
-				"claimed",
-				"--claimant",
-				"other",
-				"--agent",
-				"other-agent",
-				"--session-id",
-				"job-2",
-				"--revision",
-				claimed.revision,
-				"--json",
-			],
-			root,
-		)
-		expect(conflict.exitCode).toBe(1)
-		expect(JSON.parse(conflict.stdout)).toMatchObject({
-			ok: false,
-			error: {
-				code: "CLAIM_CONFLICT",
-				retryable: true,
-				fields: { claim: { agent: "agent", sessionId: "job-1" } },
-			},
-		})
-
-		const finished = parseJson(
-			await runCli(
-				[
-					"finish",
-					"claimed",
-					"--session-id",
-					"job-1",
-					"--revision",
-					claimed.revision,
-					"--outcome",
-					"done",
-					"--json",
-				],
-				root,
-			),
-		)
-		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
-		expect(
-			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
-				.status,
-		).toBe("working")
-
 		parseJson(
 			await runCli(
 				["task", "create", "non-pr", "--repo", "agency", "--json"],
 				root,
 			),
 		)
-		const nonPrContext = parseJson(
-			await runCli(["context", "tasks/non-pr", "--json"], root),
-		)
-		const nonPrClaim = parseJson(
-			await runCli(
-				[
-					"claim",
-					"non-pr",
-					"--claimant",
-					"orchestrator",
-					"--agent",
-					"agent",
-					"--session-id",
-					"job-2",
-					"--revision",
-					nonPrContext.documents.task.sha256,
-					"--json",
-				],
-				root,
-			),
-		)
 		parseJson(
 			await runCli(
 				[
-					"finish",
+					"task",
+					"status",
 					"non-pr",
-					"--session-id",
-					"job-2",
-					"--revision",
-					nonPrClaim.revision,
-					"--outcome",
 					"done",
 					"--no-pull-request",
 					"--summary",
@@ -1073,6 +1007,15 @@ status: open
 				],
 			}),
 		])
+		const preparedAgain = parseJson(
+			await runCli(
+				["work", "prepare", join(root, "tasks/example/TASK.md"), "--json"],
+				parent,
+			),
+		)
+		expect(preparedAgain.checkouts).toEqual([
+			expect.objectContaining({ action: "reused", kind: "writable" }),
+		])
 		const rebuild = parseJson(
 			await runCli(
 				["worktree", "rebuild", "example", "--dry-run", "--json"],