@markjaquith/agency 2.8.0 → 2.10.0

package/README.md

@@ -231,12 +231,30 @@ agency repo link backend ~/Dev/backend
 agency task new
 
 agency validate
+agency context tasks/refresh-copy --json
 agency work tasks/refresh-copy
 agency pr create refresh-copy
 ```
 
 ## Commands
 
+### Target Context
+
+`agency context [target] --json` returns the complete bootstrap context for an
+epic, task, or phase without modifying the workbase or fetching repositories.
+The target defaults to the current directory; entity directories, document
+paths, checkout descendants, and bare task IDs are accepted.
+
+The result includes workbase and target identity, ancestor frontmatter and prose
+with SHA-256 hashes, dependency and readiness state, aggregate status, writable
+and reference authority, local checkout and resolved-commit state, recorded PR
+state, and validation warnings. Only `done` satisfies a dependency; `dropped` is
+terminal but remains a blocker.
+
+Complete output is the default. Pass `--compact` explicitly to omit document
+prose and low-level Git details while retaining identity, hashes, authority,
+paths, graph state, materialization state, and validation warnings.
+
 ### Workbase and Repositories
 
 ```text
@@ -302,6 +320,7 @@ agency task create <id> --multi-phase
 ### Noninteractive Use
 
 Agency never prompts when `--no-input` is set or stdin/stderr are not TTYs.
+`--json` also disables prompts and selectors, even when a TTY is available.
 Commands with explicit inputs continue normally. `task new` fails immediately;
 `work` requires an explicit directory, task ID, or `--epic` and must run from a
 workbase; `validate` requires an explicit path or must run from a workbase.
@@ -408,6 +427,66 @@ unknown dependencies, and dependency cycles. YAML duplicate keys, anchors,
 aliases, and custom tags are rejected. When path is omitted outside a workbase,
 Agency prompts for a registered workbase.
 
+## Machine Protocol
+
+`--json` emits exactly one JSON value on stdout for success or failure. It takes
+precedence over `--silent`; progress, warnings, and verbose diagnostics remain on
+stderr. Version 1 success responses have this shape:
+
+```json
+{ "version": 1, "ok": true, "result": { "root": "/work/agency" } }
+```
+
+Failures exit nonzero and use the same versioned envelope:
+
+```json
+{
+	"version": 1,
+	"ok": false,
+	"error": {
+		"code": "CLI_USAGE",
+		"message": "Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
+		"fields": {
+			"detail": "Unknown command 'unknown'.",
+			"usage": "agency <command> [options]"
+		},
+		"retryable": false,
+		"remediation": "Correct the arguments using the usage value in error.fields."
+	}
+}
+```
+
+Every error contains a stable `code`, human-readable `message`, structured
+`fields`, and `retryable`. `remediation` is included when Agency knows a specific
+recovery action. Version 1 defines these codes:
+
+| Code                      | Meaning                                                  |
+| ------------------------- | -------------------------------------------------------- |
+| `CLI_USAGE`               | Invalid command, option, argument, or option combination |
+| `WORKBASE_NOT_FOUND`      | No workbase could be resolved                            |
+| `WORKBASE_CONFIG_INVALID` | Invalid workbase configuration                           |
+| `WORKBASE_REGISTRY_ERROR` | Invalid or inaccessible workbase registry                |
+| `FILE_NOT_FOUND`          | A required path does not exist                           |
+| `FILESYSTEM_ERROR`        | A filesystem operation failed                            |
+| `FRONTMATTER_INVALID`     | A durable document has invalid frontmatter               |
+| `VALIDATION_FAILED`       | Workbase validation reported issues                      |
+| `REPOSITORY_ERROR`        | Repository operation failed                              |
+| `EPIC_ERROR`              | Epic operation failed                                    |
+| `TASK_ERROR`              | Task operation failed                                    |
+| `PHASE_ERROR`             | Phase operation failed                                   |
+| `ARCHIVE_ERROR`           | Archive operation failed                                 |
+| `WORKTREE_ERROR`          | Worktree operation failed                                |
+| `PULL_REQUEST_ERROR`      | Pull request operation failed                            |
+| `PROCESS_ERROR`           | A child process failed and may be retried                |
+| `PROTOCOL_OUTPUT_ERROR`   | A command violated the machine output contract           |
+| `COMMAND_FAILED`          | An otherwise unclassified command failure                |
+
+The Effect schemas are exported from `@markjaquith/agency` and
+`@markjaquith/agency/protocol`. The distributable JSON Schema is exported as
+`@markjaquith/agency/schemas/agency-envelope-v1.json`. Representative payloads
+are exported as `@markjaquith/agency/fixtures/protocol/success.json` and
+`@markjaquith/agency/fixtures/protocol/error.json`.
+
 ## Agent Skill
 
 `skills/agency/SKILL.md` contains an agent-oriented operating guide for Agency.

package/cli.ts

@@ -8,6 +8,7 @@ import { pr, help as prHelp } from "./src/commands/pr"
 import { work, help as workHelp } from "./src/commands/work"
 import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
+import { context, help as contextHelp } from "./src/commands/context"
 import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
@@ -28,6 +29,13 @@ import { WorktreeService } from "./src/services/WorktreeService"
 import { PullRequestService } from "./src/services/PullRequestService"
 import { ArchiveService } from "./src/services/ArchiveService"
 import { IntegrationService } from "./src/services/IntegrationService"
+import { ContextService } from "./src/services/ContextService"
+import {
+	collectCommandResult,
+	errorEnvelope,
+	successEnvelope,
+	writeEnvelope,
+} from "./src/protocol"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -41,6 +49,7 @@ const CliLayer = Layer.mergeAll(
 	PullRequestService.Default,
 	ArchiveService.Default,
 	IntegrationService.Default,
+	ContextService.Default,
 )
 
 /**
@@ -76,7 +85,7 @@ async function runCommand<E>(
 			Effect.either,
 		),
 	)
-	if (Either.isLeft(result)) throw toError(result.left)
+	if (Either.isLeft(result)) throw result.left
 }
 
 // Read version from package.json
@@ -307,6 +316,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	context: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(contextHelp)
+				return
+			}
+			await runCommand(
+				context({
+					target: args[0],
+					compact: options.compact,
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 }
 
 function showMainHelp() {
@@ -328,6 +354,7 @@ Commands:
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
   validate [path]        Validate a workbase
+  context [target]       Return complete target context
 
 Global Options:
   -h, --help             Show help for a command
@@ -346,13 +373,19 @@ For more information about a command, run:
 	`)
 }
 
+const machineMode = process.argv.slice(2).includes("--json")
+
 try {
 	const args = process.argv.slice(2)
 	const { commandName, args: commandArgs, values } = parseCli(args)
 
 	// Handle global flags
 	if (values.version) {
-		console.log(`v${VERSION}`)
+		if (machineMode) {
+			writeEnvelope(successEnvelope({ version: VERSION }))
+		} else {
+			console.log(`v${VERSION}`)
+		}
 		process.exit(0)
 	}
 
@@ -365,9 +398,22 @@ try {
 
 	const command = commands[commandName]!
 	const inputAllowed =
-		!values["no-input"] && Boolean(process.stdin.isTTY && process.stderr.isTTY)
-	await command.run(commandArgs, { ...values, inputAllowed })
+		!values.json &&
+		!values["no-input"] &&
+		Boolean(process.stdin.isTTY && process.stderr.isTTY)
+	if (values.json) {
+		const result = await collectCommandResult(() =>
+			command.run(commandArgs, { ...values, inputAllowed }),
+		)
+		writeEnvelope(successEnvelope(result))
+	} else {
+		await command.run(commandArgs, { ...values, inputAllowed })
+	}
 } catch (error) {
+	if (machineMode) {
+		writeEnvelope(errorEnvelope(error))
+		process.exit(1)
+	}
 	if (error instanceof Error) {
 		let message = error.message
 

package/fixtures/protocol/error.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "ok": false,
+  "error": {
+    "code": "CLI_USAGE",
+    "message": "Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
+    "fields": {
+      "detail": "Unknown command 'unknown'.",
+      "usage": "agency <command> [options]"
+    },
+    "retryable": false,
+    "remediation": "Correct the arguments using the usage value in error.fields."
+  }
+}

package/fixtures/protocol/success.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "ok": true,
+  "result": {
+    "root": "/work/agency"
+  }
+}

package/index.ts

@@ -1 +1,2 @@
 export * from "./src/workbase/schemas"
+export * from "./src/protocol"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -21,6 +21,8 @@
     "index.ts",
     "cli.ts",
     "src",
+    "schemas",
+    "fixtures/protocol",
     "skills",
     "README.md",
     "LICENSE"
@@ -31,6 +33,19 @@
     ".": {
       "types": "./index.ts",
       "import": "./index.ts"
+    },
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "import": "./src/protocol.ts"
+    },
+    "./schemas/agency-envelope-v1.json": {
+      "default": "./schemas/agency-envelope-v1.schema.json"
+    },
+    "./fixtures/protocol/success.json": {
+      "default": "./fixtures/protocol/success.json"
+    },
+    "./fixtures/protocol/error.json": {
+      "default": "./fixtures/protocol/error.json"
     }
   },
   "publishConfig": {

package/schemas/agency-envelope-v1.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/markjaquith/agency/schemas/agency-envelope-v1.schema.json",
+  "title": "Agency machine result envelope v1",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "ok", "result"],
+      "properties": {
+        "version": { "const": 1 },
+        "ok": { "const": true },
+        "result": true
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "ok", "error"],
+      "properties": {
+        "version": { "const": 1 },
+        "ok": { "const": false },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message", "fields", "retryable"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string" },
+            "fields": { "type": "object" },
+            "retryable": { "type": "boolean" },
+            "remediation": { "type": "string" }
+          }
+        }
+      }
+    }
+  ]
+}

package/src/cli-parser.test.ts

@@ -139,11 +139,21 @@ describe("strict CLI parsing", () => {
 			[["pr", "create", "one", "two", "three"], "agency pr create"],
 			[["status", "extra"], "agency status"],
 			[["validate", "one", "two"], "agency validate"],
+			[["context", "one", "two"], "agency context"],
 		] as const) {
 			expectUsageError([...args], usage)
 		}
 	})
 
+	test("accepts context projections and keeps compact command-local", () => {
+		expect(parseCli(["context", ".", "--json", "--compact"])).toMatchObject({
+			commandName: "context",
+			args: ["."],
+			values: { json: true, compact: true },
+		})
+		expectUsageError(["status", "--compact"], "agency status")
+	})
+
 	test("reports unknown subcommands with parent usage", () => {
 		expect(() => parseCli(["task", "crate"])).toThrow(
 			"Unknown subcommand 'crate'",

package/src/cli-parser.ts

@@ -338,6 +338,19 @@ const commands = {
 			options: ["json"],
 		},
 	},
+	context: {
+		usage: "agency context [target] [--json] [--compact]",
+		options: {
+			...outputOptions,
+			compact: { type: "boolean" },
+		},
+		command: {
+			usage: "agency context [target] [--json] [--compact]",
+			minArgs: 0,
+			maxArgs: 1,
+			options: ["json", "compact"],
+		},
+	},
 } satisfies Readonly<Record<string, CommandDefinition>>
 
 const rootOptions = commonOptions
@@ -363,8 +376,20 @@ export interface ParsedCli {
 	>
 }
 
+class CliUsageError extends Error {
+	readonly _tag = "CliUsageError"
+
+	constructor(
+		readonly detail: string,
+		readonly usage: string,
+	) {
+		super(`${detail}\n\nUsage: ${usage}`)
+		this.name = "CliUsageError"
+	}
+}
+
 const usageError = (message: string, usage: string) =>
-	new Error(`${message}\n\nUsage: ${usage}`)
+	new CliUsageError(message, usage)
 
 const optionLabel = (name: string) => `--${name}`
 

package/src/cli.test.ts

@@ -34,7 +34,9 @@ async function runCli(
 function parseJson(result: CliResult) {
 	expect(result.exitCode).toBe(0)
 	expect(result.stderr).toBe("")
-	return JSON.parse(result.stdout)
+	const envelope = JSON.parse(result.stdout)
+	expect(envelope).toMatchObject({ version: 1, ok: true })
+	return envelope.result
 }
 
 describe("CLI", () => {
@@ -79,6 +81,46 @@ describe("CLI", () => {
 		expect(taggedError.stderr).not.toContain("An error has occurred")
 	})
 
+	test("emits one versioned error envelope for usage and command failures", async () => {
+		const usage = await runCli(["unknown", "--json"])
+		expect(usage.exitCode).toBe(1)
+		expect(usage.stderr).toBe("")
+		expect(usage.stdout.trim().split("\n")).toHaveLength(1)
+		expect(JSON.parse(usage.stdout)).toEqual({
+			version: 1,
+			ok: false,
+			error: {
+				code: "CLI_USAGE",
+				message:
+					"Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
+				fields: {
+					detail: "Unknown command 'unknown'.",
+					usage: "agency <command> [options]",
+				},
+				retryable: false,
+				remediation:
+					"Correct the arguments using the usage value in error.fields.",
+			},
+		})
+
+		const cwd = await createTempDir()
+		tempDirs.push(cwd)
+		const commandFailure = await runCli(
+			["repo", "list", "--json", "--silent"],
+			cwd,
+		)
+		expect(commandFailure.exitCode).toBe(1)
+		expect(commandFailure.stderr).toBe("")
+		expect(JSON.parse(commandFailure.stdout)).toMatchObject({
+			version: 1,
+			ok: false,
+			error: {
+				code: "WORKBASE_NOT_FOUND",
+				retryable: false,
+			},
+		})
+	})
+
 	test("rejects malformed input before running a command", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)
@@ -116,6 +158,7 @@ describe("CLI", () => {
 			["pr", "Usage: agency pr"],
 			["status", "Usage: agency status"],
 			["validate", "Usage: agency validate"],
+			["context", "Usage: agency context"],
 		] as const) {
 			const result = await runCli([command, "--help"])
 			expect(result.exitCode).toBe(0)
@@ -178,6 +221,30 @@ describe("CLI", () => {
 		).toEqual([await realpath(root)])
 	})
 
+	test("lets JSON override silent and disables interactive task input", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		const result = await runCli(["init", root, "--json", "--silent"])
+		expect(parseJson(result)).toEqual({ root })
+
+		const interactive = await runCli(["task", "new", "--json"])
+		expect(interactive.exitCode).toBe(1)
+		expect(interactive.stderr).toBe("")
+		expect(JSON.parse(interactive.stdout)).toMatchObject({
+			version: 1,
+			ok: false,
+			error: { code: "COMMAND_FAILED", retryable: false },
+		})
+	})
+
+	test("envelopes help and version output in machine mode", async () => {
+		const help = await runCli(["status", "--help", "--json"])
+		expect(parseJson(help)).toContain("Usage: agency status")
+
+		const version = await runCli(["status", "--version", "--json"])
+		expect(parseJson(version)).toEqual({ version: "0.0.0-development" })
+	})
+
 	test("runs a multi-phase domain workflow through subprocesses", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)