@markjaquith/agency 2.30.1 → 2.32.0

package/src/utils/interactive.test.tsx

@@ -0,0 +1,258 @@
+import { describe, expect, test } from "bun:test"
+import { testRender } from "@opentui/solid"
+import {
+	fuzzyChoices,
+	InteractiveSelectPrompt,
+	InteractiveTextPrompt,
+	interactiveRendererConfig,
+} from "./interactive"
+
+describe("OpenTUI interaction", () => {
+	test("uses the split-footer renderer contract", () => {
+		expect(interactiveRendererConfig).toMatchObject({
+			screenMode: "split-footer",
+			footerHeight: 4,
+			externalOutputMode: "capture-stdout",
+			clearOnShutdown: false,
+		})
+	})
+
+	test("ranks case-insensitive fuzzy matches", () => {
+		const choices = [
+			{ key: "nested", label: "Manage Agency" },
+			{ key: "prefix", label: "Agency" },
+			{ key: "other", label: "Website" },
+		]
+
+		expect(fuzzyChoices(choices, "AG").map((choice) => choice.key)).toEqual([
+			"prefix",
+			"nested",
+		])
+		expect(fuzzyChoices(choices, "mgy").map((choice) => choice.key)).toEqual([
+			"nested",
+		])
+		expect(fuzzyChoices(choices, "zzz")).toEqual([])
+	})
+
+	test("selects choices with ctrl-p, ctrl-n, and arrow navigation", async () => {
+		const selectAfter = async (key: "p" | "n" | "up" | "down") => {
+			let selected: string | null | undefined
+			const setup = await testRender(
+				() => (
+					<InteractiveSelectPrompt
+						prompt="Repository"
+						choices={[
+							{ key: "agency", label: "agency" },
+							{ key: "web", label: "web" },
+							{ key: "docs", label: "docs" },
+						]}
+						onDone={(value) => {
+							selected = value
+						}}
+					/>
+				),
+				{ width: 60, height: 4 },
+			)
+			try {
+				await setup.renderer.setupTerminal()
+				await setup.renderOnce()
+				await Bun.sleep(0)
+				if (key === "up" || key === "down") {
+					setup.mockInput.pressArrow(key)
+				} else {
+					setup.mockInput.pressKey(key, { ctrl: true })
+				}
+				setup.mockInput.pressEnter()
+				await setup.waitFor(() => selected !== undefined)
+				return selected
+			} finally {
+				setup.renderer.destroy()
+			}
+		}
+
+		expect(await selectAfter("p")).toBe("docs")
+		expect(await selectAfter("n")).toBe("web")
+		expect(await selectAfter("up")).toBe("docs")
+		expect(await selectAfter("down")).toBe("web")
+	})
+
+	test("uses printable j, k, and q characters as the fuzzy query", async () => {
+		for (const query of ["j", "k", "q"]) {
+			let selected: string | null | undefined
+			const setup = await testRender(
+				() => (
+					<InteractiveSelectPrompt
+						prompt="Repository"
+						choices={[
+							{ key: query, label: `${query} target` },
+							{ key: "other", label: "Other" },
+						]}
+						onDone={(value) => {
+							selected = value
+						}}
+					/>
+				),
+				{ width: 60, height: 4 },
+			)
+			try {
+				await setup.renderer.setupTerminal()
+				await setup.renderOnce()
+				await Bun.sleep(0)
+				await setup.mockInput.typeText(query)
+				setup.mockInput.pressEnter()
+				await setup.waitFor(() => selected !== undefined)
+				expect(selected).toBe(query)
+			} finally {
+				setup.renderer.destroy()
+			}
+		}
+	})
+
+	test("does not select an empty result and supports ctrl-u editing", async () => {
+		let selected: string | null | undefined
+		const setup = await testRender(
+			() => (
+				<InteractiveSelectPrompt
+					prompt="Repository"
+					choices={[
+						{ key: "agency", label: "agency" },
+						{ key: "web", label: "web" },
+					]}
+					onDone={(value) => {
+						selected = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4 },
+		)
+		try {
+			await setup.renderer.setupTerminal()
+			await setup.renderOnce()
+			await Bun.sleep(0)
+			await setup.mockInput.typeText("zzz")
+			setup.mockInput.pressEnter()
+			await Bun.sleep(0)
+			expect(selected).toBeUndefined()
+			setup.mockInput.pressKey("u", { ctrl: true })
+			await setup.mockInput.typeText("web")
+			setup.mockInput.pressEnter()
+			await setup.waitFor(() => selected !== undefined)
+			expect(selected).toBe("web")
+		} finally {
+			setup.renderer.destroy()
+		}
+	})
+
+	test("resets and navigates selection after filtering", async () => {
+		let selected: string | null | undefined
+		const setup = await testRender(
+			() => (
+				<InteractiveSelectPrompt
+					prompt="Repository"
+					choices={[
+						{ key: "agency", label: "agency" },
+						{ key: "web-one", label: "web one" },
+						{ key: "web-two", label: "web two" },
+						{ key: "docs", label: "docs" },
+					]}
+					onDone={(value) => {
+						selected = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4 },
+		)
+		try {
+			await setup.renderer.setupTerminal()
+			await setup.renderOnce()
+			await Bun.sleep(0)
+			setup.mockInput.pressArrow("down")
+			setup.mockInput.pressArrow("down")
+			setup.mockInput.pressArrow("down")
+			await setup.mockInput.typeText("web")
+			setup.mockInput.pressKey("n", { ctrl: true })
+			setup.mockInput.pressEnter()
+			await setup.waitFor(() => selected !== undefined)
+			expect(selected).toBe("web-two")
+		} finally {
+			setup.renderer.destroy()
+		}
+	})
+
+	test("submits text and cancels with ctrl-c or escape", async () => {
+		let submitted: string | null | undefined
+		const input = await testRender(
+			() => (
+				<InteractiveTextPrompt
+					prompt="Task ID"
+					onDone={(value) => {
+						submitted = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4 },
+		)
+		try {
+			await input.renderer.setupTerminal()
+			await input.renderOnce()
+			await Bun.sleep(0)
+			expect(input.renderer.keyInput.listenerCount("keypress")).toBeGreaterThan(
+				0,
+			)
+			await input.mockInput.typeText("improve-ui")
+			input.mockInput.pressEnter()
+			await input.waitFor(() => submitted !== undefined)
+			expect(submitted).toBe("improve-ui")
+		} finally {
+			input.renderer.destroy()
+		}
+
+		let cancelled: string | null | undefined
+		const select = await testRender(
+			() => (
+				<InteractiveSelectPrompt
+					prompt="Cancel"
+					choices={[{ key: "one", label: "One" }]}
+					onDone={(value) => {
+						cancelled = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4 },
+		)
+		try {
+			await select.renderer.setupTerminal()
+			await select.renderOnce()
+			await Bun.sleep(0)
+			select.mockInput.pressCtrlC()
+			await select.waitFor(() => cancelled !== undefined)
+			expect(cancelled).toBeNull()
+		} finally {
+			select.renderer.destroy()
+		}
+
+		let escaped: string | null | undefined
+		const escape = await testRender(
+			() => (
+				<InteractiveSelectPrompt
+					prompt="Cancel"
+					choices={[{ key: "one", label: "One" }]}
+					onDone={(value) => {
+						escaped = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4, kittyKeyboard: true },
+		)
+		try {
+			await escape.renderer.setupTerminal()
+			await escape.renderOnce()
+			await Bun.sleep(0)
+			escape.mockInput.pressEscape()
+			await escape.waitFor(() => escaped !== undefined)
+			expect(escaped).toBeNull()
+		} finally {
+			escape.renderer.destroy()
+		}
+	})
+})

package/src/utils/interactive.tsx

@@ -0,0 +1,290 @@
+import {
+	createCliRenderer,
+	type CliRenderer,
+	type CliRendererConfig,
+	type InputRenderable,
+} from "@opentui/core"
+import { render, useKeyboard, type JSX } from "@opentui/solid"
+import { createMemo, createSignal, For } from "solid-js"
+
+export interface InteractiveChoice {
+	readonly key: string
+	readonly label: string
+}
+
+export const interactiveRendererConfig = {
+	screenMode: "split-footer",
+	footerHeight: 4,
+	externalOutputMode: "capture-stdout",
+	consoleMode: "disabled",
+	clearOnShutdown: false,
+	exitOnCtrlC: false,
+	useMouse: false,
+	autoFocus: false,
+	openConsoleOnError: false,
+} satisfies CliRendererConfig
+
+interface PromptProps<T> {
+	readonly prompt: string
+	readonly onDone: (value: T | null) => void
+}
+
+const isCancel = (key: { name: string; ctrl: boolean }) =>
+	key.name === "escape" || (key.ctrl && key.name === "c")
+
+export const InteractiveTextPrompt = (props: PromptProps<string>) => {
+	let input: InputRenderable | undefined
+	let value = ""
+	useKeyboard((key) => {
+		if (isCancel(key)) {
+			key.preventDefault()
+			key.stopPropagation()
+			props.onDone(null)
+			return
+		}
+		if (key.name !== "return") return
+		key.preventDefault()
+		key.stopPropagation()
+		props.onDone(value)
+	})
+
+	return (
+		<box flexDirection="column" width="100%" height="100%">
+			<text fg="#7aa2f7">{props.prompt}</text>
+			<input
+				focused
+				onInput={(next) => {
+					value = next
+				}}
+				ref={(next) => {
+					input = next
+					queueMicrotask(() => {
+						if (input && !input.isDestroyed) input.focus()
+					})
+				}}
+			/>
+			<text fg="#6c7086">enter submit | esc cancel</text>
+		</box>
+	)
+}
+
+interface SelectPromptProps extends PromptProps<string> {
+	readonly choices: readonly InteractiveChoice[]
+}
+
+const isWordBoundary = (value: string, index: number) =>
+	index === 0 || /[\s/_.:-]/.test(value[index - 1]!)
+
+const fuzzyScore = (value: string, query: string) => {
+	const candidate = value.toLowerCase()
+	const needle = query.toLowerCase()
+	let previous = new Float64Array(candidate.length)
+	let current = new Float64Array(candidate.length)
+	previous.fill(Number.NEGATIVE_INFINITY)
+	let bestScore = Number.NEGATIVE_INFINITY
+
+	for (let queryIndex = 0; queryIndex < needle.length; queryIndex++) {
+		current.fill(Number.NEGATIVE_INFINITY)
+		let bestEarlier = Number.NEGATIVE_INFINITY
+		bestScore = Number.NEGATIVE_INFINITY
+		for (let index = 0; index < candidate.length; index++) {
+			if (queryIndex > 0 && index > 0) {
+				bestEarlier = Math.max(bestEarlier, previous[index - 1]! + index - 1)
+			}
+			if (candidate[index] !== needle[queryIndex]) continue
+
+			const boundaryBonus = isWordBoundary(candidate, index) ? 8 : 0
+			if (queryIndex === 0) {
+				current[index] = 10 + boundaryBonus - index
+				bestScore = Math.max(bestScore, current[index]!)
+				continue
+			}
+
+			const contiguous =
+				index > 0 ? previous[index - 1]! + 12 : Number.NEGATIVE_INFINITY
+			const gapped = bestEarlier - index + 1
+			current[index] = Math.max(contiguous, gapped) + 10 + boundaryBonus
+			bestScore = Math.max(bestScore, current[index]!)
+		}
+		if (!Number.isFinite(bestScore)) return null
+		const swap = previous
+		previous = current
+		current = swap
+	}
+
+	return bestScore - candidate.length / 1000
+}
+
+export const fuzzyChoices = (
+	choices: readonly InteractiveChoice[],
+	query: string,
+) => {
+	if (!query) return choices
+	return choices
+		.map((choice, index) => ({
+			choice,
+			index,
+			score: fuzzyScore(choice.label, query),
+		}))
+		.filter(
+			(
+				match,
+			): match is typeof match & {
+				score: number
+			} => match.score !== null,
+		)
+		.sort((left, right) => right.score - left.score || left.index - right.index)
+		.map((match) => match.choice)
+}
+
+export const InteractiveSelectPrompt = (props: SelectPromptProps) => {
+	let input: InputRenderable | undefined
+	const [query, setQuery] = createSignal("")
+	const [selected, setSelected] = createSignal(0)
+	const choices = createMemo(() => fuzzyChoices(props.choices, query()))
+	const move = (offset: -1 | 1) => {
+		const count = choices().length
+		if (count === 0) return
+		setSelected((current) => (current + offset + count) % count)
+	}
+	useKeyboard((key) => {
+		if (isCancel(key)) {
+			key.preventDefault()
+			key.stopPropagation()
+			props.onDone(null)
+			return
+		}
+		if (key.name === "up" || (key.ctrl && key.name === "p")) {
+			key.preventDefault()
+			key.stopPropagation()
+			move(-1)
+			return
+		}
+		if (key.name === "down" || (key.ctrl && key.name === "n")) {
+			key.preventDefault()
+			key.stopPropagation()
+			move(1)
+			return
+		}
+		if (key.name !== "return") return
+		key.preventDefault()
+		key.stopPropagation()
+		const choice = choices()[selected()]
+		if (choice) props.onDone(choice.key)
+	})
+
+	const visible = () => {
+		const start = Math.min(
+			Math.max(selected() - 1, 0),
+			Math.max(choices().length - 2, 0),
+		)
+		return choices()
+			.slice(start, start + 2)
+			.map((choice, offset) => ({
+				choice,
+				index: start + offset,
+			}))
+	}
+
+	return (
+		<box flexDirection="column" width="100%" height="100%">
+			<box flexDirection="row" width="100%">
+				<text fg="#7aa2f7" flexShrink={1} wrapMode="none">
+					{props.prompt}
+				</text>
+				<text fg="#7aa2f7">{" > "}</text>
+				<input
+					focused
+					flexGrow={1}
+					minWidth={8}
+					placeholder="filter"
+					onInput={(next) => {
+						setQuery(next)
+						setSelected(0)
+					}}
+					ref={(next) => {
+						input = next
+						queueMicrotask(() => {
+							if (input && !input.isDestroyed) input.focus()
+						})
+					}}
+				/>
+			</box>
+			<box flexDirection="column" height={2}>
+				<For each={visible()} fallback={<text fg="#6c7086">No matches</text>}>
+					{({ choice, index }) => (
+						<text
+							fg={index === selected() ? "#c0caf5" : "#6c7086"}
+							wrapMode="none"
+						>
+							{index === selected() ? "> " : "  "}
+							{choice.label}
+						</text>
+					)}
+				</For>
+			</box>
+			<text fg="#6c7086" wrapMode="none">
+				enter select | esc cancel | ctrl-n/p or arrows
+			</text>
+		</box>
+	)
+}
+
+const shutdown = async (renderer: CliRenderer) => {
+	await renderer.idle().catch(() => undefined)
+	if (renderer.externalOutputMode === "capture-stdout") {
+		renderer.externalOutputMode = "passthrough"
+	}
+	if (renderer.screenMode === "split-footer")
+		renderer.screenMode = "main-screen"
+	if (!renderer.isDestroyed) renderer.destroy()
+}
+
+async function runInteractive<T>(
+	view: (finish: (value: T | null) => void) => JSX.Element,
+) {
+	let finish!: (value: T | null) => void
+	let settled = false
+	const result = new Promise<T | null>((resolve) => {
+		finish = (value) => {
+			if (settled) return
+			settled = true
+			resolve(value)
+		}
+	})
+	let renderer: CliRenderer | undefined
+	try {
+		renderer = await createCliRenderer({
+			...interactiveRendererConfig,
+			onDestroy: () => finish(null),
+		})
+		await render(() => view(finish), renderer)
+		renderer.requestRender()
+		return await result
+	} finally {
+		if (renderer) {
+			await shutdown(renderer)
+			process.stdout.write("\n")
+		}
+	}
+}
+
+export const promptText = async (prompt: string) => {
+	const result = await runInteractive<string>((finish) => (
+		<InteractiveTextPrompt prompt={prompt} onDone={finish} />
+	))
+	if (result === null) throw new Error("Interactive input cancelled")
+	return result
+}
+
+export const promptSelect = (
+	prompt: string,
+	choices: readonly InteractiveChoice[],
+) =>
+	runInteractive<string>((finish) => (
+		<InteractiveSelectPrompt
+			prompt={prompt}
+			choices={choices}
+			onDone={finish}
+		/>
+	))

package/src/workbase/AGENTS.md

@@ -35,8 +35,8 @@ reason to edit `agency.json` or `repos/` by hand.
 
 - Stop on validation errors, dependency blockers, an unexpected writable
   repository, or a conflicting active claim.
-- Do not begin execution without a claim. `agency work` claims before launch;
-  external orchestrators use `agency claim` with the revision from context.
+- `agency work` is the local launch flow and marks execution units `working`
+  without claiming them. External orchestrators claim before launching runners.
 - Do not manually create, move, or remove worktrees under `code/`.
 - Use `agency archive`, rather than moving work item folders manually.
 - Do not edit bare repositories or repository symlinks under `repos/`.
@@ -56,9 +56,9 @@ is open; if merge was requested, merge remains delivery work.
 At each closeout trigger (creating or updating a PR, marking it ready, completing
 a refinement loop, or pausing or handing off completed implementation work):
 
-- Use `agency task status` or `agency phase status` to set the execution unit's
-  current status. Finish an active claim with the current revision via
-  `agency finish`.
+- Finish an active claim with the current revision via `agency finish`.
+  Otherwise use `agency task status` or `agency phase status` to set the
+  execution unit's current status.
 - Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
   PR state, current head, diff summary, and verification results after later
   pushes when those details are maintained there.

package/src/workbase/frontmatter.ts

@@ -81,3 +81,20 @@ export const parseFrontmatter = (content: string, path: string) =>
 
 export const formatMarkdownDocument = (data: object, body: string) =>
 	`---\n${stringify(data, { lineWidth: 0 }).trimEnd()}\n---\n\n${body.trim()}\n`
+
+export const formatWorkDocumentBody = (
+	title: string,
+	kind: "epic" | "task" | "phase",
+) => `# ${title}
+
+## Outcome
+
+Describe the ${kind} outcome.
+
+## Plan
+
+Describe the current approach.
+
+## Important Decisions
+
+Record consequential decisions and their rationale.`

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

@@ -18,15 +18,27 @@ const variables = {
 }
 
 describe("runner commands", () => {
-	test("uses deterministic fresh and resume commands for built-in presets", () => {
+	test("uses promptless interactive commands for built-in presets", () => {
 		expect(
 			resolveRunnerCommand("opencode", undefined, variables, false).argv,
-		).toEqual(["opencode", "--prompt", "Read the task."])
+		).toEqual(["opencode"])
 		expect(
 			resolveRunnerCommand("opencode", undefined, variables, true).argv,
-		).toEqual(["opencode", "--continue", "--prompt", "Read the task."])
+		).toEqual(["opencode", "--continue"])
 		expect(
 			resolveRunnerCommand("claude", undefined, variables, true).argv,
+		).toEqual(["claude", "--continue"])
+	})
+
+	test("uses autonomous commands when a prompt is requested", () => {
+		expect(
+			resolveRunnerCommand("opencode", undefined, variables, false, true).argv,
+		).toEqual(["opencode", "--prompt", "Read the task."])
+		expect(
+			resolveRunnerCommand("opencode", undefined, variables, true, true).argv,
+		).toEqual(["opencode", "--continue", "--prompt", "Read the task."])
+		expect(
+			resolveRunnerCommand("claude", undefined, variables, true, true).argv,
 		).toEqual(["claude", "--continue", "Read the task."])
 	})
 
@@ -35,12 +47,14 @@ describe("runner commands", () => {
 			"custom",
 			{
 				custom: {
-					command: ["agent", "--target={target}", "{prompt}"],
+					command: ["agent"],
+					autoCommand: ["agent", "--target={target}", "{prompt}"],
 					environment: { CUSTOM_SESSION: "{sessionId}" },
 				},
 			},
 			variables,
 			false,
+			true,
 		)
 
 		expect(resolved).toEqual({
@@ -53,6 +67,18 @@ describe("runner commands", () => {
 		})
 	})
 
+	test("rejects --auto for configured runners without an auto command", () => {
+		expect(() =>
+			resolveRunnerCommand(
+				"custom",
+				{ custom: { command: ["agent"] } },
+				variables,
+				false,
+				true,
+			),
+		).toThrow("Runner 'custom' does not support --auto")
+	})
+
 	test("rejects unknown placeholders", () => {
 		expect(() =>
 			validateRunners({ custom: { command: ["agent", "{unknown}"] } }),