@markjaquith/agency 2.64.0 → 2.65.0

package/README.md

@@ -246,6 +246,55 @@ Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches. Jj workbases always use
 jj workspaces and ignore this Git-specific customization.
 
+### Custom Jj Workspace Command
+
+Jj workbases normally create managed workspaces with `jj workspace add`. Set
+`workspaceCreateCommand` to an argv template when another tool should create or
+adopt a prepared workspace directly at Agency's destination:
+
+```json
+{
+	"version": 2,
+	"vcs": "jj",
+	"workspaceCreateCommand": [
+		"my-prewarm-tool",
+		"adopt",
+		"--repo",
+		"{repo}",
+		"--destination",
+		"{workspace}",
+		"--name",
+		"{name}",
+		"--revision",
+		"{revision}"
+	]
+}
+```
+
+Available placeholders are:
+
+- `{repo}`: absolute repository alias path under `repos/`
+- `{workspace}`: absolute managed workspace path Agency requires
+- `{name}`: unique jj workspace name Agency requires
+- `{revision}`: exact commit the new working copy must be based on
+- `{kind}`: `writable` or `reference`
+- `{requestedRef}`: configured branch, reference, or review commit
+
+`{repo}`, `{workspace}`, `{name}`, and `{revision}` are required. Agency invokes
+the command directly without a shell and sets matching `AGENCY_REPO`,
+`AGENCY_WORKSPACE`, `AGENCY_WORKSPACE_NAME`, `AGENCY_REVISION`,
+`AGENCY_CHECKOUT_KIND`, and `AGENCY_REQUESTED_REF` environment variables. The
+command applies to each new jj checkout and must leave `{workspace}` registered
+under `{name}` with its working-copy parent at `{revision}`. This lets a prewarm
+tool move or adopt a prepared workspace without first paying for Agency's normal
+full checkout.
+
+Agency validates the registration, name, path, and revision before running any
+`postCheckoutCommand`. A failed command or validation removes a partially
+created workspace when possible and otherwise reports manual recovery. Resume
+restoration continues to use Agency's built-in exact-target recovery path.
+Git workbases ignore this jj-specific customization.
+
 ### Post-checkout Commands
 
 Each repository declaration may provide a VCS-neutral `postCheckoutCommand` argv
@@ -267,8 +316,8 @@ shell, with the new checkout as its working directory:
 The hook runs for each newly created managed checkout, including writable and
 reference checkouts, after Git worktree or jj workspace creation has completed
 and Agency has validated the checkout. It does not run for a reused checkout or
-for inspection-only commands. A custom `worktreeCreateCommand` completes and is
-validated before this hook runs.
+for inspection-only commands. A custom `worktreeCreateCommand` or
+`workspaceCreateCommand` completes and is validated before this hook runs.
 
 Available placeholders and matching environment variables are:
 

package/package.json

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

package/src/services/DoctorService.ts

@@ -173,6 +173,15 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 									] as const,
 								]
 							: []),
+						...(config.workspaceCreateCommand
+							? [
+									[
+										"integration.workspace-create",
+										config.workspaceCreateCommand,
+										"Workspace creator",
+									] as const,
+								]
+							: []),
 						...Object.entries(config.repositories ?? {}).flatMap(
 							([alias, repository]) =>
 								repository.postCheckoutCommand

package/src/services/WorkbaseService.test.ts

@@ -371,6 +371,26 @@ status: done
 		).rejects.toThrow("{worktree}")
 	})
 
+	test("rejects an invalid workspace command template", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: ["tool", "{repo}", "{workspace}", "{name}"],
+			}),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.discover(root)),
+				),
+			),
+		).rejects.toThrow("{revision}")
+	})
+
 	test("rejects an unknown post-checkout command placeholder", async () => {
 		await write(
 			root,

package/src/services/WorkbaseService.ts

@@ -20,6 +20,7 @@ import {
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
 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 { findDependencyCycles } from "../workbase/dependency-graph"
@@ -275,6 +276,21 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								if (decoded.value.workspaceCreateCommand) {
+									try {
+										validateWorkspaceCreateCommand(
+											decoded.value.workspaceCreateCommand,
+										)
+									} catch (cause) {
+										return yield* new WorkbaseConfigError({
+											path: configPath,
+											message:
+												cause instanceof Error
+													? cause.message
+													: "Invalid workspaceCreateCommand",
+										})
+									}
+								}
 								for (const [alias, repository] of Object.entries(
 									decoded.value.repositories ?? {},
 								)) {

package/src/services/WorktreeService.test.ts

@@ -319,6 +319,198 @@ describe("WorktreeService", () => {
 		expect(await Bun.file(workspace.writablePath!).exists()).toBe(false)
 	})
 
+	test("uses a custom jj workspace creator before the post-checkout hook", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: [
+					"sh",
+					"-c",
+					'jj -R "$1" workspace add --name "$3" -r "$4" "$2" && printf "%s\\n%s\\n" "$AGENCY_CHECKOUT_KIND" "$AGENCY_REQUESTED_REF" > "$2/creator-finished"',
+					"workspace-creator",
+					"{repo}",
+					"{workspace}",
+					"{name}",
+					"{revision}",
+					"{kind}",
+					"{requestedRef}",
+				],
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: [
+							"sh",
+							"-c",
+							'test -f creator-finished && printf "post-checkout" > hook-finished',
+						],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-custom",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-custom",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-custom", undefined, root),
+				),
+			),
+		)
+		expect(
+			await Bun.file(join(workspace.writablePath!, "creator-finished")).text(),
+		).toBe("writable\ntask/jj-custom\n")
+		expect(
+			await Bun.file(join(workspace.writablePath!, "hook-finished")).text(),
+		).toBe("post-checkout")
+		expect(workspace.operations[0]).toMatchObject({
+			action: "create-workspace",
+			command: expect.arrayContaining(["writable", "task/jj-custom"]),
+			status: "completed",
+		})
+	})
+
+	test("rolls back a jj workspace partially created by a custom command", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: [
+					"sh",
+					"-c",
+					'jj -R "$1" workspace add --name "$3" -r "$4" "$2" && echo adoption-failed >&2; exit 7',
+					"workspace-creator",
+					"{repo}",
+					"{workspace}",
+					"{name}",
+					"{revision}",
+				],
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-custom-failure",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-custom-failure",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspacePath = join(root, "tasks/jj-custom-failure/code/agency")
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("jj-custom-failure", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("adoption-failed")
+		expect(await Bun.file(workspacePath).exists()).toBe(false)
+		expect(
+			await jjOutput(["workspace", "list", "-T", 'name ++ "\\n"'], repository),
+		).not.toContain("agency-jj-custom-failure-task-agency")
+	})
+
+	test("rejects and rolls back a custom jj workspace at the wrong revision", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		const hookMarker = join(root, "wrong-revision-hook")
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: [
+					"sh",
+					"-c",
+					'jj -R "$1" workspace add --name "$3" -r "root()" "$2"',
+					"workspace-creator",
+					"{repo}",
+					"{workspace}",
+					"{name}",
+					"{revision}",
+				],
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: ["sh", "-c", 'touch "$1"', "hook", hookMarker],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-custom-wrong-revision",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-custom-wrong-revision",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspacePath = join(
+			root,
+			"tasks/jj-custom-wrong-revision/code/agency",
+		)
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("jj-custom-wrong-revision", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("failed validation")
+		expect(await Bun.file(workspacePath).exists()).toBe(false)
+		expect(await Bun.file(hookMarker).exists()).toBe(false)
+	})
+
 	test("suspends and resumes the exact jj working-copy target", async () => {
 		if (!Bun.which("jj")) return
 		const repository = join(root, "repos/agency")

package/src/services/WorktreeService.ts

@@ -8,6 +8,10 @@ import {
 	expandWorktreeCreateCommand,
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
+import {
+	expandWorkspaceCreateCommand,
+	workspaceCommandEnvironment,
+} from "../workbase/workspace-command"
 import {
 	expandPostCheckoutCommand,
 	postCheckoutCommandEnvironment,
@@ -1157,7 +1161,7 @@ const materializeJj = (options: {
 		const created: {
 			repositoryPath: string
 			workspacePath: string
-			workspaceName: string
+			workspaceName: string | null
 		}[] = []
 		const resumePath = jjResumePath(options.taskPath, options.phasePath)
 		const resume = yield* readJjResumeState(resumePath)
@@ -1227,9 +1231,14 @@ const materializeJj = (options: {
 				const canonicalPath = exists
 					? yield* fs.realPath(workspacePath)
 					: resolve(workspacePath)
-				const registered = (yield* backend.listWorkspaces(repositoryPath)).find(
+				const registeredWorkspaces =
+					yield* backend.listWorkspaces(repositoryPath)
+				const registered = registeredWorkspaces.find(
 					(workspace) => workspace.path === canonicalPath,
 				)
+				const registeredByName = registeredWorkspaces.find(
+					(workspace) => workspace.name === workspaceName,
+				)
 				if (exists && !registered && resumeCheckout) {
 					const residual = yield* inspectJjResidual(
 						options.root,
@@ -1256,6 +1265,11 @@ const materializeJj = (options: {
 						message: `Workspace registry contains a missing checkout at ${workspacePath}`,
 					})
 				}
+				if (!exists && registeredByName) {
+					return yield* new WorktreeError({
+						message: `Jj workspace name '${workspaceName}' is already registered at ${registeredByName.path}`,
+					})
+				}
 				if (exists && registered) {
 					const actualCommit = resumeCheckout
 						? ((yield* jjIdentity(workspacePath, "@"))?.commitId ?? null)
@@ -1313,7 +1327,7 @@ const materializeJj = (options: {
 					})
 				}
 
-				const command = [
+				const defaultCommand = [
 					"jj",
 					"-R",
 					repositoryPath,
@@ -1325,6 +1339,36 @@ const materializeJj = (options: {
 					revision,
 					workspacePath,
 				]
+				const workspaceVariables = {
+					repo: repositoryPath,
+					workspace: workspacePath,
+					name: workspaceName,
+					revision,
+					kind:
+						"branch" in checkout
+							? ("writable" as const)
+							: ("reference" as const),
+					requestedRef: requestedRevision,
+				}
+				let command = defaultCommand
+				let commandEnvironment: Record<string, string> | undefined
+				if (options.config.workspaceCreateCommand && !resumeCheckout) {
+					try {
+						command = expandWorkspaceCreateCommand(
+							options.config.workspaceCreateCommand,
+							workspaceVariables,
+						)
+						commandEnvironment = workspaceCommandEnvironment(workspaceVariables)
+					} catch (cause) {
+						return yield* new WorktreeError({
+							message:
+								cause instanceof Error
+									? cause.message
+									: "Invalid workspaceCreateCommand",
+							cause,
+						})
+					}
+				}
 				operations.push({
 					action: "create-workspace",
 					repo: checkout.repo,
@@ -1353,6 +1397,38 @@ const materializeJj = (options: {
 							workspaceName,
 							commitId: resumeCheckout.commitId,
 						})
+					} else if (options.config.workspaceCreateCommand) {
+						verboseLog(`Running workspace command: ${formatCommand(command)}`)
+						const result = yield* fs.runCommand(command, {
+							cwd: repositoryPath,
+							captureOutput: true,
+							forwardOutput: forwardCommandOutput,
+							env: commandEnvironment,
+						})
+						const createdPath = yield* fs.isDirectory(workspacePath)
+						const canonicalCreatedPath = createdPath
+							? yield* fs.realPath(workspacePath)
+							: resolve(workspacePath)
+						const registeredAfterCommand = (yield* backend.listWorkspaces(
+							repositoryPath,
+						)).find((workspace) => workspace.path === canonicalCreatedPath)
+						if (createdPath || registeredAfterCommand) {
+							created.push({
+								repositoryPath,
+								workspacePath,
+								workspaceName: registeredAfterCommand?.name ?? null,
+							})
+						}
+						if (result.exitCode !== 0) {
+							return yield* new WorktreeError({
+								message: `Failed to create jj workspace for '${checkout.repo}': ${result.stderr.trim() || result.stdout.trim()}`,
+							})
+						}
+						if (!createdPath) {
+							return yield* new WorktreeError({
+								message: `Workspace command did not create ${workspacePath}`,
+							})
+						}
 					} else {
 						yield* backend.createWorkspace({
 							repositoryPath,
@@ -1362,7 +1438,9 @@ const materializeJj = (options: {
 							...("branch" in checkout ? { branch: checkout.branch } : {}),
 						})
 					}
-					created.push({ repositoryPath, workspacePath, workspaceName })
+					if (!options.config.workspaceCreateCommand || resumeCheckout) {
+						created.push({ repositoryPath, workspacePath, workspaceName })
+					}
 					const canonicalWorkspacePath = yield* fs.realPath(workspacePath)
 					const registeredAfterCreate = (yield* backend.listWorkspaces(
 						repositoryPath,
@@ -1370,7 +1448,10 @@ const materializeJj = (options: {
 					const head = resumeCheckout
 						? ((yield* jjIdentity(workspacePath, "@"))?.commitId ?? null)
 						: yield* backend.workspaceHead(workspacePath)
-					if (!registeredAfterCreate || head !== revision) {
+					if (
+						registeredAfterCreate?.name !== workspaceName ||
+						head !== revision
+					) {
 						return yield* new WorktreeError({
 							message: `Created jj workspace for '${checkout.repo}' failed validation`,
 						})
@@ -1445,16 +1526,18 @@ const materializeJj = (options: {
 					const rolledBack: string[] = []
 					const manualRecovery: string[] = []
 					for (const workspace of [...created].reverse()) {
-						const removed = yield* backend
-							.removeWorkspace({
-								repositoryPath: workspace.repositoryPath,
-								workspacePath: workspace.workspacePath,
-								workspaceName: workspace.workspaceName,
-							})
-							.pipe(
-								Effect.as(true),
-								Effect.catchAll(() => Effect.succeed(false)),
-							)
+						const removed = yield* (
+							workspace.workspaceName
+								? backend.removeWorkspace({
+										repositoryPath: workspace.repositoryPath,
+										workspacePath: workspace.workspacePath,
+										workspaceName: workspace.workspaceName,
+									})
+								: fs.deleteDirectory(workspace.workspacePath)
+						).pipe(
+							Effect.as(true),
+							Effect.catchAll(() => Effect.succeed(false)),
+						)
 						if (removed)
 							rolledBack.push(`create-workspace ${workspace.workspaceName}`)
 						else

package/src/workbase/schemas.test.ts

@@ -257,6 +257,25 @@ describe("repository post-checkout configuration", () => {
 	})
 })
 
+describe("workspace creation configuration", () => {
+	test("accepts a jj workspace argv command", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			vcs: "jj",
+			workspaceCreateCommand: [
+				"prewarm",
+				"adopt",
+				"{repo}",
+				"{workspace}",
+				"{name}",
+				"{revision}",
+			],
+		})
+
+		expect(config.workspaceCreateCommand?.[0]).toBe("prewarm")
+	})
+})
+
 describe("runner configuration", () => {
 	test("accepts named argv commands with resume commands and environment", () => {
 		const config = Schema.decodeUnknownSync(WorkbaseConfig)({

package/src/workbase/schemas.ts

@@ -109,6 +109,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(
 		Schema.Record({
 			key: EntityId,

package/src/workbase/workspace-command.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test"
+import {
+	expandWorkspaceCreateCommand,
+	workspaceCommandEnvironment,
+} from "./workspace-command"
+
+const variables = {
+	repo: "/work/repos/app",
+	workspace: "/work/tasks/example/code/app",
+	name: "agency-example-task-app",
+	revision: "0123456789abcdef",
+	kind: "writable" as const,
+	requestedRef: "task/example",
+}
+
+describe("workspace command templates", () => {
+	test("expands argv placeholders without shell interpolation", () => {
+		expect(
+			expandWorkspaceCreateCommand(
+				[
+					"tool",
+					"--repo={repo}",
+					"--workspace={workspace}",
+					"--name={name}",
+					"--revision={revision}",
+					"{kind}",
+					"{requestedRef}",
+				],
+				variables,
+			),
+		).toEqual([
+			"tool",
+			"--repo=/work/repos/app",
+			"--workspace=/work/tasks/example/code/app",
+			"--name=agency-example-task-app",
+			"--revision=0123456789abcdef",
+			"writable",
+			"task/example",
+		])
+	})
+
+	test("requires creation identity placeholders", () => {
+		expect(() =>
+			expandWorkspaceCreateCommand(
+				["tool", "{repo}", "{workspace}", "{name}"],
+				variables,
+			),
+		).toThrow("{revision}")
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			expandWorkspaceCreateCommand(
+				["tool", "{repo}", "{workspace}", "{name}", "{revision}", "{base}"],
+				variables,
+			),
+		).toThrow("{base}")
+	})
+
+	test("provides equivalent environment variables", () => {
+		expect(workspaceCommandEnvironment(variables)).toEqual({
+			AGENCY_REPO: variables.repo,
+			AGENCY_WORKSPACE: variables.workspace,
+			AGENCY_WORKSPACE_NAME: variables.name,
+			AGENCY_REVISION: variables.revision,
+			AGENCY_CHECKOUT_KIND: variables.kind,
+			AGENCY_REQUESTED_REF: variables.requestedRef,
+		})
+	})
+})

package/src/workbase/workspace-command.ts

@@ -0,0 +1,63 @@
+interface WorkspaceCommandVariables {
+	readonly repo: string
+	readonly workspace: string
+	readonly name: string
+	readonly revision: string
+	readonly kind: "writable" | "reference"
+	readonly requestedRef: string
+}
+
+const REQUIRED_PLACEHOLDERS = ["repo", "workspace", "name", "revision"] as const
+const PLACEHOLDERS = new Set([
+	"repo",
+	"workspace",
+	"name",
+	"revision",
+	"kind",
+	"requestedRef",
+])
+
+export const validateWorkspaceCreateCommand = (command: readonly string[]) => {
+	const template = command.join("\u0000")
+	for (const placeholder of REQUIRED_PLACEHOLDERS) {
+		if (!template.includes(`{${placeholder}}`)) {
+			throw new Error(
+				`workspaceCreateCommand must include the {${placeholder}} placeholder`,
+			)
+		}
+	}
+	for (const argument of command) {
+		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
+			const placeholder = match[1]!
+			if (!PLACEHOLDERS.has(placeholder)) {
+				throw new Error(
+					`Unknown workspaceCreateCommand placeholder: {${placeholder}}`,
+				)
+			}
+		}
+	}
+}
+
+export const expandWorkspaceCreateCommand = (
+	command: readonly string[],
+	variables: WorkspaceCommandVariables,
+): string[] => {
+	validateWorkspaceCreateCommand(command)
+
+	return command.map((argument) =>
+		argument.replaceAll(/\{([^{}]+)\}/g, (match, placeholder: string) => {
+			return variables[placeholder as keyof WorkspaceCommandVariables] ?? match
+		}),
+	)
+}
+
+export const workspaceCommandEnvironment = (
+	variables: WorkspaceCommandVariables,
+): Record<string, string> => ({
+	AGENCY_REPO: variables.repo,
+	AGENCY_WORKSPACE: variables.workspace,
+	AGENCY_WORKSPACE_NAME: variables.name,
+	AGENCY_REVISION: variables.revision,
+	AGENCY_CHECKOUT_KIND: variables.kind,
+	AGENCY_REQUESTED_REF: variables.requestedRef,
+})