feat(cli): add Zoo automation client

apps/zoo/eslint-suppressions.json

@@ -0,0 +1 @@
+{}

apps/zoo/eslint.config.mjs

@@ -0,0 +1,4 @@
+import { config } from "@roo-code/config-eslint/base"
+
+/** @type {import("eslint").Linter.Config} */
+export default [...config]

apps/zoo/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@zoo-code/cli",
+	"version": "0.1.0",
+	"description": "Zoo Code command-line interface",
+	"type": "module",
+	"main": "dist/index.js",
+	"bin": {
+		"zoo": "dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup",
+		"check-types": "tsc --noEmit",
+		"lint": "eslint src --ext .ts --max-warnings=0",
+		"test": "pnpm build && vitest run",
+		"clean": "rimraf dist .turbo"
+	},
+	"dependencies": {
+		"@roo-code/zoo-protocol": "workspace:^",
+		"commander": "^12.1.0"
+	},
+	"devDependencies": {
+		"@roo-code/config-eslint": "workspace:^",
+		"@roo-code/config-typescript": "workspace:^",
+		"@types/node": "22.20.1",
+		"rimraf": "6.0.1",
+		"tsup": "8.5.1",
+		"vitest": "4.1.9"
+	}
+}

apps/zoo/src/__tests__/fixtures/fake-host.mjs

@@ -0,0 +1,191 @@
+import process from "node:process"
+import { setImmediate } from "node:timers"
+
+let hostSequence = 0
+let publicSequence = 0
+const hostId = "fake-host"
+const scenario = process.env.ZOO_FAKE_SCENARIO ?? "completed"
+const send = (event) => process.send({ v: 1, seq: ++hostSequence, hostId, ...event })
+const stream = (event) =>
+	send({
+		type: "event",
+		event: {
+			v: 1,
+			seq: ++publicSequence,
+			timestamp: new Date().toISOString(),
+			hostId,
+			...event,
+		},
+	})
+
+process.send({
+	type: "hello",
+	hostId,
+	supportedVersions: [1],
+	capabilities: {
+		1: ["task:start", "task:resume", "task:cancel", "history:list", "host:shutdown", "checkpoint:unavailable"],
+	},
+	buildVersion: "test",
+})
+
+process.on("message", (message) => {
+	if (message.type === "hello.select") {
+		stream({
+			type: "system.init",
+			protocol: "zoo-stream",
+			hostProtocolVersion: 1,
+			capabilities: [
+				"task:start",
+				"task:resume",
+				"task:cancel",
+				"history:list",
+				"host:shutdown",
+				"checkpoint:unavailable",
+			],
+			clientVersion: message.clientVersion,
+			hostVersion: "test",
+		})
+		return
+	}
+	send({ type: "command.ack", commandId: message.id })
+	if (message.type === "task.start") {
+		send({
+			type: "command.done",
+			commandId: message.id,
+			data: { commandType: "task.start", task: { rootTaskId: "root-1", taskId: "root-1" } },
+		})
+		stream({ type: "task.created", requestId: message.id, rootTaskId: "root-1", taskId: "root-1" })
+		stream({ type: "task.started", rootTaskId: "root-1", taskId: "root-1" })
+		if (scenario === "crash") {
+			setImmediate(() => process.exit(70))
+			return
+		}
+		if (scenario === "hang") return
+		if (scenario === "needs-input") {
+			stream({
+				type: "ask.required",
+				rootTaskId: "root-1",
+				taskId: "root-1",
+				askId: "ask-1",
+				category: "followup",
+				subject: "Choose a target",
+			})
+			stream({ type: "task.lifecycle", rootTaskId: "root-1", taskId: "root-1", state: "waiting" })
+			stream({
+				type: "task.result",
+				requestId: message.id,
+				rootTaskId: "root-1",
+				taskId: "root-1",
+				result: {
+					schemaVersion: 1,
+					protocol: "zoo-run-result",
+					success: false,
+					outcome: "needs_input",
+					rootTaskId: "root-1",
+					currentTaskId: "root-1",
+					workspace: message.workspace,
+					resumable: true,
+					content: "Choose a target",
+					elapsedMs: 5,
+				},
+			})
+			return
+		}
+		stream({ type: "task.lifecycle", rootTaskId: "root-1", taskId: "root-1", state: "completed" })
+		stream({
+			type: "task.result",
+			requestId: message.id,
+			rootTaskId: "root-1",
+			taskId: "root-1",
+			result: {
+				schemaVersion: 1,
+				protocol: "zoo-run-result",
+				success: true,
+				outcome: "completed",
+				rootTaskId: "root-1",
+				currentTaskId: "root-1",
+				workspace: message.workspace,
+				resumable: false,
+				content: "finished",
+				elapsedMs: 5,
+			},
+		})
+	} else if (message.type === "task.cancel") {
+		send({ type: "command.done", commandId: message.id, data: { commandType: "task.cancel", rootTaskId: message.rootTaskId } })
+		if (scenario === "hang") {
+			stream({
+				type: "task.lifecycle",
+				rootTaskId: message.rootTaskId,
+				taskId: message.rootTaskId,
+				state: "interrupted",
+				cause: "cancelled",
+			})
+			stream({
+				type: "task.result",
+				requestId: message.id,
+				rootTaskId: message.rootTaskId,
+				taskId: message.rootTaskId,
+				result: {
+					schemaVersion: 1,
+					protocol: "zoo-run-result",
+					success: false,
+					outcome: "cancelled",
+					rootTaskId: message.rootTaskId,
+					currentTaskId: message.rootTaskId,
+					workspace: process.cwd(),
+					resumable: true,
+					cancellationReason: message.reason,
+					elapsedMs: 5,
+				},
+			})
+		}
+	} else if (message.type === "history.list") {
+		send({
+			type: "command.done",
+			commandId: message.id,
+			data: {
+				commandType: "history.list",
+				workspace: message.workspace,
+				tasks: [{ rootTaskId: "root-1", currentTaskId: "root-1", workspace: message.workspace, state: "interrupted" }],
+			},
+		})
+	} else if (message.type === "task.resume") {
+		send({
+			type: "command.done",
+			commandId: message.id,
+			data: { commandType: "task.resume", task: { rootTaskId: message.rootTaskId, taskId: message.taskId } },
+		})
+		stream({ type: "task.created", rootTaskId: message.rootTaskId, taskId: message.taskId })
+		stream({ type: "task.lifecycle", rootTaskId: message.rootTaskId, taskId: message.taskId, state: "interrupted" })
+		stream({
+			type: "task.resumed",
+			requestId: message.id,
+			rootTaskId: message.rootTaskId,
+			taskId: message.taskId,
+			previousState: "interrupted",
+		})
+		stream({ type: "task.started", rootTaskId: message.rootTaskId, taskId: message.taskId })
+		stream({ type: "task.lifecycle", rootTaskId: message.rootTaskId, taskId: message.taskId, state: "completed" })
+		stream({
+			type: "task.result",
+			requestId: message.id,
+			rootTaskId: message.rootTaskId,
+			taskId: message.rootTaskId,
+			result: {
+				schemaVersion: 1,
+				protocol: "zoo-run-result",
+				success: true,
+				outcome: "completed",
+				rootTaskId: message.rootTaskId,
+				currentTaskId: message.taskId,
+				workspace: process.cwd(),
+				resumable: false,
+				content: "resumed",
+				elapsedMs: 5,
+			},
+		})
+	} else if (message.type === "host.shutdown") {
+		send({ type: "command.done", commandId: message.id, data: { commandType: "host.shutdown" } })
+		setImmediate(() => process.disconnect())
+	}
+})

apps/zoo/src/__tests__/options.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+
+import { parseDuration, runOverrides } from "../options.js"
+
+describe("automation options", () => {
+	it("parses bounded duration units", () => {
+		expect(parseDuration("250ms")).toBe(250)
+		expect(parseDuration("2m")).toBe(120_000)
+		expect(() => parseDuration("2 minutes")).toThrow("Invalid duration")
+	})
+
+	it("rejects mutually exclusive provider sources", () => {
+		expect(() => runOverrides({ provider: "anthropic", profile: "work" })).toThrow(
+			"profile and provider are mutually exclusive",
+		)
+	})
+})

apps/zoo/src/__tests__/projection.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest"
+
+import { initialProjection, reduceSession } from "../projection.js"
+
+const base = { v: 1 as const, seq: 1, timestamp: "2026-08-05T12:00:00.000Z", hostId: "host" }
+
+describe("SessionProjection", () => {
+	it("upserts messages by canonical identity", () => {
+		const created = reduceSession(initialProjection(), {
+			...base,
+			type: "message.upsert",
+			rootTaskId: "root",
+			taskId: "root",
+			messageId: "message-1",
+			role: "assistant",
+			content: "hel",
+			complete: false,
+		})
+		const updated = reduceSession(created, {
+			...base,
+			seq: 2,
+			type: "message.upsert",
+			rootTaskId: "root",
+			taskId: "root",
+			messageId: "message-1",
+			role: "assistant",
+			content: "hello",
+			complete: true,
+		})
+
+		expect([...updated.messages.values()]).toEqual([{ role: "assistant", content: "hello", complete: true }])
+		expect(created.messages.get("message-1")?.content).toBe("hel")
+	})
+})

apps/zoo/src/__tests__/subprocess.test.ts

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { describe, expect, it } from "vitest"
+
+const packageRoot = path.resolve(fileURLToPath(new URL("../../", import.meta.url)))
+const cliPath = path.join(packageRoot, "dist/index.js")
+const hostPath = fileURLToPath(new URL("./fixtures/fake-host.mjs", import.meta.url))
+
+async function runCli(args: string[], scenario = "completed", signal?: NodeJS.Signals) {
+	return new Promise<{ stdout: string; stderr: string; code: number }>((resolve, reject) => {
+		const child = spawn(process.execPath, [cliPath, ...args], {
+			env: { ...process.env, ZOO_HOST_PATH: hostPath, ZOO_FAKE_SCENARIO: scenario },
+			stdio: ["ignore", "pipe", "pipe"],
+		})
+		let stdout = ""
+		let stderr = ""
+		child.stdout.setEncoding("utf8").on("data", (chunk: string) => (stdout += chunk))
+		child.stderr.setEncoding("utf8").on("data", (chunk: string) => (stderr += chunk))
+		child.once("error", reject)
+		child.once("close", (code) => resolve({ stdout, stderr, code: code ?? 70 }))
+		if (signal) setTimeout(() => child.kill(signal), 100)
+	})
+}
+
+describe("packaged zoo automation", () => {
+	it("negotiates with the host and writes exactly one final JSON value", async () => {
+		const { stdout, stderr } = await runCli(["run", "finish the task", "--format", "json", "-C", packageRoot])
+		const result = JSON.parse(stdout) as { outcome: string; content: string }
+
+		expect(result).toMatchObject({ outcome: "completed", content: "finished" })
+		expect(stdout.trim().split("\n")).toHaveLength(1)
+		expect(stderr).toBe("")
+	})
+
+	it("settles a host crash as one runtime-failure JSON value", async () => {
+		const { stdout, code } = await runCli(["run", "crash", "--format", "json", "-C", packageRoot], "crash")
+		const lines = stdout.trim().split("\n")
+
+		expect(code).toBe(70)
+		expect(lines).toHaveLength(1)
+		expect(JSON.parse(lines[0]!)).toMatchObject({ outcome: "failed", error: { code: "host_crashed" } })
+	})
+
+	it("returns immediately and resumably for a safe unattended ask", async () => {
+		const { stdout, code } = await runCli(
+			["run", "ask", "--format", "stream-json", "--approval", "safe", "-C", packageRoot],
+			"needs-input",
+		)
+		const events = stdout
+			.trim()
+			.split("\n")
+			.map((line) => JSON.parse(line) as { type: string; result?: { outcome: string } })
+
+		expect(code).toBe(3)
+		expect(events.at(-1)).toMatchObject({ type: "task.result", result: { outcome: "needs_input" } })
+		expect(events.filter((event) => event.type === "task.result")).toHaveLength(1)
+	})
+
+	it("enforces the whole-task timeout and exit code", async () => {
+		const { stdout, code } = await runCli(
+			["run", "wait", "--format", "json", "--timeout", "50ms", "-C", packageRoot],
+			"hang",
+		)
+
+		expect(code).toBe(124)
+		expect(JSON.parse(stdout)).toMatchObject({ outcome: "timed_out", error: { code: "task_timed_out" } })
+	})
+
+	it("cancels canonically on SIGTERM and preserves the signal exit code", async () => {
+		const { stdout, code } = await runCli(["run", "wait", "--format", "json", "-C", packageRoot], "hang", "SIGTERM")
+
+		expect(code).toBe(143)
+		expect(JSON.parse(stdout)).toMatchObject({ outcome: "cancelled", cancellationReason: "signal" })
+	})
+
+	it("lists and resumes the latest workspace session", async () => {
+		const listed = await runCli(["sessions", "list", "--format", "json", "-C", packageRoot])
+		const resumed = await runCli(["resume", "--format", "json", "-C", packageRoot])
+
+		expect(JSON.parse(listed.stdout)).toMatchObject([{ rootTaskId: "root-1", state: "interrupted" }])
+		expect(JSON.parse(resumed.stdout)).toMatchObject({ outcome: "completed", content: "resumed" })
+	})
+})