@markjaquith/agency 2.8.0 → 2.9.0

package/README.md

@@ -302,6 +302,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 +409,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

@@ -28,6 +28,12 @@ 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 {
+	collectCommandResult,
+	errorEnvelope,
+	successEnvelope,
+	writeEnvelope,
+} from "./src/protocol"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -76,7 +82,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
@@ -346,13 +352,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 +377,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.9.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.ts

@@ -363,8 +363,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)
@@ -178,6 +220,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)

package/src/commands/validate.ts

@@ -15,6 +15,11 @@ interface ValidateOptions extends BaseCommandOptions {
 
 class ValidationFailedError extends Data.TaggedError("ValidationFailedError")<{
 	readonly message: string
+	readonly root: string
+	readonly issues: readonly {
+		readonly path: string
+		readonly message: string
+	}[]
 }> {}
 
 export const validate = (
@@ -46,6 +51,8 @@ export const validate = (
 				.join("\n")
 			return yield* new ValidationFailedError({
 				message: `Workbase validation failed with ${report.issues.length} issue${report.issues.length === 1 ? "" : "s"}:\n${details}`,
+				root: report.root,
+				issues: report.issues,
 			})
 		}
 

package/src/commands/work.test.ts

@@ -6,7 +6,7 @@ import { EpicService } from "../services/EpicService"
 import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
-import { captureLogs } from "../test-utils"
+import { captureErrors, captureLogs } from "../test-utils"
 import { work } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
 import type { PickWorkbase } from "../workbase/workbase-choice"
@@ -568,7 +568,7 @@ describe("work command", () => {
 
 	test("respects silent and verbose logging options", async () => {
 		const verboseHarness = createHarness()
-		const verboseLogs = await captureLogs(() =>
+		const verboseLogs = await captureErrors(() =>
 			verboseHarness.run({ taskId: "example", verbose: true }),
 		)
 		expect(verboseLogs).toEqual([
@@ -577,7 +577,7 @@ describe("work command", () => {
 		expect(verboseHarness.materializeOptions[0]?.verbose).toBe(true)
 
 		const silentHarness = createHarness()
-		const silentLogs = await captureLogs(() =>
+		const silentLogs = await captureErrors(() =>
 			silentHarness.run({
 				taskId: "example",
 				verbose: true,

package/src/protocol.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "@effect/schema"
+import errorFixture from "../fixtures/protocol/error.json"
+import successFixture from "../fixtures/protocol/success.json"
+import jsonSchema from "../schemas/agency-envelope-v1.schema.json"
+import {
+	AgencyEnvelope,
+	collectCommandResult,
+	emitCommandResult,
+	errorEnvelope,
+	successEnvelope,
+} from "./protocol"
+
+describe("machine protocol", () => {
+	test("accepts the representative success and error fixtures", () => {
+		for (const fixture of [successFixture, errorFixture]) {
+			const decoded = Schema.decodeUnknownSync(AgencyEnvelope, {
+				onExcessProperty: "error",
+			})(fixture)
+			expect(JSON.stringify(decoded)).toBe(JSON.stringify(fixture))
+		}
+	})
+
+	test("publishes the matching v1 JSON Schema", () => {
+		expect(jsonSchema).toMatchObject({
+			$schema: "https://json-schema.org/draft/2020-12/schema",
+			title: "Agency machine result envelope v1",
+			oneOf: [
+				{ properties: { version: { const: 1 }, ok: { const: true } } },
+				{ properties: { version: { const: 1 }, ok: { const: false } } },
+			],
+		})
+	})
+
+	test("collects one command result without writing it", async () => {
+		const result = await collectCommandResult(async () => {
+			emitCommandResult('{"value":42}')
+		})
+		expect(successEnvelope(result)).toEqual({
+			version: 1,
+			ok: true,
+			result: { value: 42 },
+		})
+		expect(successEnvelope(undefined).result).toBeNull()
+	})
+
+	test("rejects commands that emit multiple machine results", async () => {
+		await expect(
+			collectCommandResult(async () => {
+				emitCommandResult("first")
+				emitCommandResult("second")
+			}),
+		).rejects.toThrow("more than one result")
+	})
+
+	test("normalizes unknown failures into stable error details", () => {
+		expect(errorEnvelope(new Error("boom"))).toEqual({
+			version: 1,
+			ok: false,
+			error: {
+				code: "COMMAND_FAILED",
+				message: "boom",
+				fields: {},
+				retryable: false,
+			},
+		})
+	})
+
+	test("preserves relevant fields from classified errors", () => {
+		expect(
+			errorEnvelope({
+				_tag: "ValidationFailedError",
+				message: "invalid workbase",
+				root: "/work/agency",
+				issues: [{ path: "TASK.md", message: "invalid status" }],
+			}),
+		).toMatchObject({
+			error: {
+				code: "VALIDATION_FAILED",
+				fields: {
+					root: "/work/agency",
+					issues: [{ path: "TASK.md", message: "invalid status" }],
+				},
+			},
+		})
+	})
+})

package/src/protocol.ts

@@ -0,0 +1,211 @@
+import { Schema } from "@effect/schema"
+
+export const PROTOCOL_VERSION = 1 as const
+
+const ErrorFields = Schema.Record({
+	key: Schema.String,
+	value: Schema.Unknown,
+})
+
+export const SuccessEnvelope = Schema.Struct({
+	version: Schema.Literal(PROTOCOL_VERSION),
+	ok: Schema.Literal(true),
+	result: Schema.Unknown,
+})
+
+export const ErrorDetail = Schema.Struct({
+	code: Schema.String,
+	message: Schema.String,
+	fields: ErrorFields,
+	retryable: Schema.Boolean,
+	remediation: Schema.optional(Schema.String),
+})
+
+export const ErrorEnvelope = Schema.Struct({
+	version: Schema.Literal(PROTOCOL_VERSION),
+	ok: Schema.Literal(false),
+	error: ErrorDetail,
+})
+
+export const AgencyEnvelope = Schema.Union(SuccessEnvelope, ErrorEnvelope)
+
+export type SuccessEnvelope = Schema.Schema.Type<typeof SuccessEnvelope>
+export type ErrorEnvelope = Schema.Schema.Type<typeof ErrorEnvelope>
+export type AgencyEnvelope = Schema.Schema.Type<typeof AgencyEnvelope>
+
+interface ErrorMetadata {
+	readonly code: string
+	readonly retryable: boolean
+	readonly remediation?: string
+}
+
+const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
+	CliUsageError: {
+		code: "CLI_USAGE",
+		retryable: false,
+		remediation: "Correct the arguments using the usage value in error.fields.",
+	},
+	WorkbaseNotFoundError: {
+		code: "WORKBASE_NOT_FOUND",
+		retryable: false,
+		remediation:
+			"Run the command from an Agency workbase or provide an explicit workbase path.",
+	},
+	WorkbaseConfigError: {
+		code: "WORKBASE_CONFIG_INVALID",
+		retryable: false,
+		remediation: "Correct the workbase configuration and retry the command.",
+	},
+	WorkbaseRegistryError: {
+		code: "WORKBASE_REGISTRY_ERROR",
+		retryable: false,
+		remediation: "Correct the registered workbase entry and retry the command.",
+	},
+	FileNotFoundError: {
+		code: "FILE_NOT_FOUND",
+		retryable: false,
+		remediation: "Restore the required file or correct the supplied path.",
+	},
+	FileSystemError: { code: "FILESYSTEM_ERROR", retryable: false },
+	FrontmatterParseError: {
+		code: "FRONTMATTER_INVALID",
+		retryable: false,
+		remediation: "Correct the document frontmatter and retry the command.",
+	},
+	ValidationFailedError: {
+		code: "VALIDATION_FAILED",
+		retryable: false,
+		remediation: "Resolve the validation issues in error.fields and retry.",
+	},
+	RepositoryError: { code: "REPOSITORY_ERROR", retryable: false },
+	EpicError: { code: "EPIC_ERROR", retryable: false },
+	TaskError: { code: "TASK_ERROR", retryable: false },
+	PhaseError: { code: "PHASE_ERROR", retryable: false },
+	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
+	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
+	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },
+	ProcessError: { code: "PROCESS_ERROR", retryable: true },
+	ProtocolOutputError: {
+		code: "PROTOCOL_OUTPUT_ERROR",
+		retryable: false,
+		remediation: "Report this Agency protocol violation.",
+	},
+}
+
+class ProtocolOutputError extends Error {
+	readonly _tag = "ProtocolOutputError"
+}
+
+let resultCollector: ((value: unknown) => void) | undefined
+
+const parseCommandResult = (value: unknown): unknown => {
+	if (typeof value !== "string") return value
+	try {
+		return JSON.parse(value)
+	} catch {
+		return value
+	}
+}
+
+export const emitCommandResult = (value: unknown): void => {
+	if (resultCollector) {
+		resultCollector(parseCommandResult(value))
+		return
+	}
+	console.log(value)
+}
+
+export const collectCommandResult = async (
+	run: () => Promise<void>,
+): Promise<unknown> => {
+	if (resultCollector) {
+		throw new ProtocolOutputError(
+			"A machine result collector is already active.",
+		)
+	}
+
+	let emitted = false
+	let result: unknown = null
+	const originalLog = console.log
+	resultCollector = (value) => {
+		if (emitted) {
+			throw new ProtocolOutputError(
+				"A machine command emitted more than one result.",
+			)
+		}
+		emitted = true
+		result = value
+	}
+	console.log = (...values) => {
+		resultCollector?.(
+			parseCommandResult(values.length === 1 ? values[0] : values.join(" ")),
+		)
+	}
+
+	try {
+		await run()
+		return result
+	} finally {
+		console.log = originalLog
+		resultCollector = undefined
+	}
+}
+
+const errorTag = (error: unknown): string | undefined => {
+	if (typeof error !== "object" || error === null) return undefined
+	if ("_tag" in error && typeof error._tag === "string") return error._tag
+	if (error instanceof Error && error.name !== "Error") return error.name
+	return undefined
+}
+
+const errorMessage = (error: unknown): string => {
+	if (
+		typeof error === "object" &&
+		error !== null &&
+		"message" in error &&
+		typeof error.message === "string"
+	) {
+		return error.message
+	}
+	return String(error)
+}
+
+const errorFields = (error: unknown): Record<string, unknown> => {
+	if (typeof error !== "object" || error === null) return {}
+	return Object.fromEntries(
+		Object.entries(error).filter(
+			([key, value]) =>
+				!key.startsWith("_") &&
+				key !== "name" &&
+				key !== "message" &&
+				key !== "cause" &&
+				value !== undefined,
+		),
+	)
+}
+
+export const successEnvelope = (result: unknown): SuccessEnvelope => ({
+	version: PROTOCOL_VERSION,
+	ok: true,
+	result: result === undefined ? null : result,
+})
+
+export const errorEnvelope = (error: unknown): ErrorEnvelope => {
+	const metadata = errorMetadata[errorTag(error) ?? ""] ?? {
+		code: "COMMAND_FAILED",
+		retryable: false,
+	}
+	return {
+		version: PROTOCOL_VERSION,
+		ok: false,
+		error: {
+			...metadata,
+			message: errorMessage(error),
+			fields: errorFields(error),
+		},
+	}
+}
+
+export const writeEnvelope = (envelope: AgencyEnvelope): void => {
+	process.stdout.write(`${JSON.stringify(envelope)}\n`)
+}

package/src/services/WorktreeService.test.ts

@@ -3,7 +3,7 @@ import { Effect } from "effect"
 import { mkdir, rm } from "node:fs/promises"
 import { join } from "node:path"
 import {
-	captureLogs,
+	captureErrors,
 	cleanupTempDir,
 	createTempDir,
 	runTestEffect,
@@ -287,7 +287,7 @@ describe("WorktreeService", () => {
 			),
 		)
 
-		const logs = await captureLogs(() =>
+		const logs = await captureErrors(() =>
 			runTestEffect(
 				WorktreeService.pipe(
 					Effect.flatMap((service) =>

package/src/test-utils.ts

@@ -45,17 +45,24 @@ export async function runTestEffect<A, E>(
 	return Effect.runPromise(program)
 }
 
-export async function captureLogs(
+async function captureConsole(
+	method: "log" | "error",
 	run: () => Promise<unknown>,
 ): Promise<string[]> {
 	const logs: string[] = []
-	const log = spyOn(console, "log").mockImplementation((...args) => {
+	const output = spyOn(console, method).mockImplementation((...args) => {
 		logs.push(args.join(" "))
 	})
 	try {
 		await run()
 		return logs
 	} finally {
-		log.mockRestore()
+		output.mockRestore()
 	}
 }
+
+export const captureLogs = (run: () => Promise<unknown>) =>
+	captureConsole("log", run)
+
+export const captureErrors = (run: () => Promise<unknown>) =>
+	captureConsole("error", run)

package/src/utils/effect.test.ts

@@ -1,24 +1,30 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, spyOn, test } from "bun:test"
 import { captureLogs } from "../test-utils"
 import { createLoggers } from "./effect"
 
 describe("createLoggers", () => {
 	test("keeps JSON output machine-readable when verbose is enabled", async () => {
+		const errors: string[] = []
+		const error = spyOn(console, "error").mockImplementation((...args) => {
+			errors.push(args.join(" "))
+		})
 		const logs = await captureLogs(async () => {
 			const { log, verboseLog } = createLoggers({ json: true, verbose: true })
 			verboseLog("debug")
 			log('{"ok":true}')
 		})
+		error.mockRestore()
 
 		expect(logs).toEqual(['{"ok":true}'])
+		expect(errors).toEqual(["debug"])
 	})
 
-	test("lets silent suppress JSON output", async () => {
+	test("lets JSON output override silent", async () => {
 		const logs = await captureLogs(async () => {
 			const { log } = createLoggers({ json: true, silent: true })
 			log('{"ok":true}')
 		})
 
-		expect(logs).toEqual([])
+		expect(logs).toEqual(['{"ok":true}'])
 	})
 })

package/src/utils/effect.ts

@@ -1,3 +1,5 @@
+import { emitCommandResult } from "../protocol"
+
 export function createLoggers(options: {
 	readonly silent?: boolean
 	readonly verbose?: boolean
@@ -5,7 +7,7 @@ export function createLoggers(options: {
 }) {
 	const { silent = false, verbose = false, json = false } = options
 	return {
-		log: silent ? () => {} : console.log,
-		verboseLog: verbose && !silent && !json ? console.log : () => {},
+		log: json ? emitCommandResult : silent ? () => {} : console.log,
+		verboseLog: verbose && !silent ? console.error : () => {},
 	}
 }