fix(cli): complete automation safety boundaries

Author: taltas

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

@@ -56,7 +56,6 @@ process.on("message", (message) => {
 		})
 		stream({ type: "task.created", requestId: message.id, rootTaskId: "root-1", taskId: "root-1" })
 		stream({ type: "task.started", rootTaskId: "root-1", taskId: "root-1" })
-		stream({ type: "task.lifecycle", rootTaskId: "root-1", taskId: "root-1", state: "running" })
 		if (scenario === "crash") {
 			setImmediate(() => process.exit(70))
 			return

apps/zoo/src/automation.ts

@@ -17,7 +17,7 @@ import {
 import { runOverrides, type OutputFormat, type SharedOptions } from "./options.js"
 import { initialProjection, reduceSession } from "./projection.js"
 import { createRenderer } from "./render.js"
-import { defaultStorageRoot, HostClient } from "./supervisor.js"
+import { defaultStorageRoot, HostClient, ZooClientError } from "./supervisor.js"
 
 type AutomationOptions = Omit<SharedOptions, "timeout"> & {
 	format: OutputFormat
@@ -54,7 +54,15 @@ export async function runAutomation(
 	const makeResult = (
 		outcome: "needs_input" | "cancelled" | "timed_out" | "failed",
 		rootTaskId: string,
-		input: { currentTaskId?: string; resumable: boolean; code?: ZooErrorCode; message?: string; content?: string },
+		input: {
+			currentTaskId?: string
+			resumable: boolean
+			code?: ZooErrorCode
+			message?: string
+			content?: string
+			kind?: "configuration" | "provider" | "runtime"
+			phase?: string
+		},
 	): ZooRunResult =>
 		zooRunResultSchema.parse({
 			schemaVersion: ZOO_PUBLIC_SCHEMA_VERSION,
@@ -68,7 +76,12 @@ export async function runAutomation(
 			content: input.content,
 			error:
 				outcome === "failed" || outcome === "timed_out"
-					? { code: input.code ?? "task_failed", message: input.message ?? "Task failed", kind: "runtime" }
+					? {
+							code: input.code ?? "task_failed",
+							message: input.message ?? "Task failed",
+							kind: input.kind ?? "runtime",
+							phase: input.phase,
+						}
 					: undefined,
 			elapsedMs: Date.now() - startedAt,
 			cancellationReason: outcome === "cancelled" ? "signal" : undefined,
@@ -106,6 +119,18 @@ export async function runAutomation(
 	let clientStopped = false
 	const deadline = options.timeout === undefined ? undefined : startedAt + options.timeout
 	const remainingDeadline = () => (deadline === undefined ? 7_000 : Math.max(0, deadline - Date.now()))
+	const commandBudget = () => {
+		const remaining = remainingDeadline()
+		if (remaining <= 0) throw new ZooClientError("task_timed_out", "Task deadline exceeded")
+		return Math.max(1, Math.min(15_000, remaining))
+	}
+	const runCommand = <T>(operation: Promise<T>) =>
+		Promise.race([
+			operation,
+			signalPromise.then(() => {
+				throw new ZooClientError("cancel_failed", `Received ${signal}`)
+			}),
+		])
 	const renderFinal = (result: ZooRunResult) => {
 		if (finalRendered) return
 		finalRendered = true
@@ -138,7 +163,11 @@ export async function runAutomation(
 				: result.outcome === "cancelled"
 					? { outcome: "cancelled", signal }
 					: result.outcome === "timed_out"
-						? { outcome: "timed_out", errorCode: result.error?.code === "cleanup_timed_out" ? "cleanup_timed_out" : "task_timed_out" }
+						? {
+								outcome: "timed_out",
+								errorCode:
+									result.error?.code === "cleanup_timed_out" ? "cleanup_timed_out" : "task_timed_out",
+							}
 						: { outcome: result.outcome },
 		)
 	}
@@ -163,7 +192,7 @@ export async function runAutomation(
 	if (options.timeout !== undefined) timeout = setTimeout(() => notifyTimeout?.(), options.timeout)
 	try {
 		const startup = await Promise.race([
-			client.start().then(() => "started" as const),
+			client.start(remainingDeadline()).then(() => "started" as const),
 			timeoutPromise,
 			signalPromise.then(() => "signal" as const),
 		])
@@ -182,28 +211,35 @@ export async function runAutomation(
 				overrides,
 			}
 		} else {
-			let taskId = request.taskId
-			if (!taskId) {
-				const history = await client.command({ type: "history.list", workspace: options.workspace })
-				if (history.data.commandType !== "history.list" || history.data.tasks.length === 0) {
-					throw new Error("No session exists for this workspace")
-				}
-				taskId = history.data.tasks[0]!.rootTaskId
+			const history = await runCommand(
+				client.command({ type: "history.list", workspace: options.workspace }, commandBudget()),
+			)
+			if (history.data.commandType !== "history.list" || history.data.tasks.length === 0) {
+				throw new ZooClientError("invalid_session", "No session exists for this workspace")
 			}
-			command = { type: "task.resume", taskId, rootTaskId: taskId, overrides }
+			const selected = request.taskId
+				? history.data.tasks.find(
+						(task) => task.rootTaskId === request.taskId || task.currentTaskId === request.taskId,
+					)
+				: history.data.tasks[0]
+			if (!selected) throw new ZooClientError("invalid_session", `Unknown session ${request.taskId}`)
+			const taskId = request.taskId === selected.currentTaskId ? request.taskId : selected.currentTaskId
+			command = { type: "task.resume", taskId, rootTaskId: selected.rootTaskId, overrides }
 		}
-		const accepted = await client.command(command)
+		const accepted = await runCommand(client.command(command, commandBudget()))
 		if (accepted.data.commandType !== "task.start" && accepted.data.commandType !== "task.resume") {
 			throw new Error("Host returned an invalid task acceptance")
 		}
 		rootTaskId = accepted.data.task.rootTaskId
 		if (signal) void client.command({ type: "task.cancel", rootTaskId, reason: "signal" }).catch(() => undefined)
 		const localSettlement = Promise.race([
 			timeoutPromise.then(() => {
-				void client.command({ type: "task.cancel", rootTaskId: rootTaskId!, reason: "timeout" }, 1).catch(() => undefined)
+				void client
+					.command({ type: "task.cancel", rootTaskId: rootTaskId!, reason: "timeout" }, 1)
+					.catch(() => undefined)
 				return makeResult("timed_out", rootTaskId!, {
 					currentTaskId: projection.currentTaskId,
-					resumable: true,
+					resumable: false,
 					code: "task_timed_out",
 					message: "Task deadline exceeded",
 				})
@@ -233,8 +269,10 @@ export async function runAutomation(
 				makeResult("failed", rootTaskId!, {
 					currentTaskId: projection.currentTaskId,
 					resumable: false,
-					code: "host_crashed",
+					code: error instanceof ZooClientError ? error.code : "host_crashed",
 					message: error.message,
+					kind: error instanceof ZooClientError ? error.detail?.kind : "runtime",
+					phase: error instanceof ZooClientError ? error.detail?.phase : undefined,
 				}),
 			),
 		])
@@ -254,16 +292,14 @@ export async function runAutomation(
 		return resultExitCode(finalResult)
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error)
-		const parsedCode = zooErrorCodeSchema.safeParse(message.split(":", 1)[0])
+		const parsedCode = zooErrorCodeSchema.safeParse(error instanceof ZooClientError ? error.code : undefined)
 		const code: ZooErrorCode = parsedCode.success
 			? parsedCode.data
-			: message.includes("protocol") || message.includes("negotiat")
-				? "protocol_incompatible"
-				: rootTaskId
-					? "task_failed"
-					: "host_start_failed"
+			: rootTaskId
+				? "task_failed"
+				: "host_start_failed"
 		const result =
-			message.includes("deadline")
+			code === "task_timed_out" || message.includes("deadline")
 				? makeResult("timed_out", rootTaskId ?? "unavailable", {
 						resumable: Boolean(rootTaskId),
 						code: "task_timed_out",
@@ -275,6 +311,8 @@ export async function runAutomation(
 							resumable: false,
 							code,
 							message,
+							kind: error instanceof ZooClientError ? error.detail?.kind : "runtime",
+							phase: error instanceof ZooClientError ? error.detail?.phase : undefined,
 						})
 		renderFinal(result)
 		return resultExitCode(result)

apps/zoo/src/supervisor.ts

@@ -19,6 +19,8 @@ import {
 	type HostHello,
 	type ParentHello,
 	type ZooCapability,
+	type ZooError,
+	type ZooErrorCode,
 	type ZooStreamEvent,
 } from "@roo-code/zoo-protocol"
 
@@ -48,6 +50,17 @@ const requiredCapabilities: ZooCapability[] = [
 	"host:shutdown",
 ]
 
+export class ZooClientError extends Error {
+	constructor(
+		public readonly code: ZooErrorCode,
+		message: string,
+		public readonly detail?: ZooError,
+	) {
+		super(message)
+		this.name = "ZooClientError"
+	}
+}
+
 export class HostClient {
 	private child: ChildProcess | undefined
 	private parser: ReturnType<typeof createHostEventStreamParser> | undefined
@@ -69,7 +82,8 @@ export class HostClient {
 
 	constructor(private readonly options: HostClientOptions) {}
 
-	public async start(): Promise<void> {
+	public async start(timeoutMs = 45_000): Promise<void> {
+		const deadline = Date.now() + timeoutMs
 		const hostPath =
 			process.env.ZOO_HOST_PATH ??
 			fileURLToPath(new URL("../../../packages/zoo-host/dist/child.js", import.meta.url))
@@ -98,10 +112,13 @@ export class HostClient {
 		child.once("exit", (code, signal) => this.fail(new Error(`Zoo host exited (${signal ?? code ?? "unknown"})`)))
 		child.once("error", (error) => this.fail(error))
 
-		const hello = await Promise.race([this.waitForHello(child, 15_000), this.failed])
+		const hello = await Promise.race([
+			this.waitForHello(child, Math.max(1, Math.min(15_000, deadline - Date.now()))),
+			this.failed,
+		])
 		this.hello = hello
 		const negotiation = negotiateProtocol(hello, [ZOO_HOST_PROTOCOL_VERSION], requiredCapabilities)
-		if (!negotiation.ok) throw new Error(negotiation.message)
+		if (!negotiation.ok) throw new ZooClientError("protocol_incompatible", negotiation.message)
 		this.parser = createHostEventStreamParser({ hostId: hello.hostId })
 		child.on("message", (message) => this.receive(message))
 		this.selection = parentHelloSchema.parse({
@@ -119,7 +136,7 @@ export class HostClient {
 				new Promise<never>((_, reject) => {
 					initializationTimer = setTimeout(
 						() => reject(new Error("Zoo host initialization timed out")),
-						30_000,
+						Math.max(1, Math.min(30_000, deadline - Date.now())),
 					)
 				}),
 			])
@@ -142,7 +159,7 @@ export class HostClient {
 		return new Promise<Extract<HostEvent, { type: "command.done" }>>((resolve, reject) => {
 			const timer = setTimeout(() => {
 				this.pending.delete(id)
-				reject(new Error(`Host command timed out: ${command.type}`))
+				reject(new ZooClientError("task_timed_out", `Host command timed out: ${command.type}`))
 			}, timeoutMs)
 			this.pending.set(id, {
 				acknowledged: false,
@@ -219,7 +236,7 @@ export class HostClient {
 						if (!this.hello || !this.selection)
 							throw new Error("Host initialized before protocol negotiation")
 						const validation = validateNegotiatedStreamSession(this.hello, this.selection, [event.event])
-						if (!validation.ok) throw new Error(validation.message)
+						if (!validation.ok) throw new ZooClientError(validation.code, validation.message)
 						this.resolveInitialized?.()
 					}
 					if (event.event.type === "task.result") {
@@ -245,8 +262,9 @@ export class HostClient {
 				if (event.type === "command.error") {
 					const pending = this.pending.get(event.commandId)
 					if (!pending?.acknowledged) throw new Error(`ERROR preceded ACK for command ${event.commandId}`)
-					pending.reject(new Error(`${event.error.code}: ${event.error.message}`))
+					pending.reject(new ZooClientError(event.error.code, event.error.message, event.error))
 					this.pending.delete(event.commandId)
+					this.flushResult()
 				}
 			}
 		} catch (error) {
@@ -261,7 +279,7 @@ export class HostClient {
 			initiatingCommandId: this.initiatingCommandId,
 			commandIds: this.commands.map((command) => command.id),
 		})
-		if (!validation.ok) throw new Error(`${validation.code}: ${validation.message}`)
+		if (!validation.ok) throw new ZooClientError(validation.code, validation.message)
 		const result = this.pendingResult
 		this.pendingResult = undefined
 		this.options.onEvent(result)

packages/types/src/api.ts

@@ -26,6 +26,26 @@ export type RunOverrides = {
 	approval?: "interactive" | "safe" | "auto"
 }
 
+export type HeadlessApiErrorCode =
+	| "invalid_provider"
+	| "invalid_profile"
+	| "invalid_model"
+	| "invalid_mode"
+	| "invalid_session"
+	| "credentials_missing"
+	| "cancel_failed"
+
+export class HeadlessApiError extends Error {
+	constructor(
+		public readonly code: HeadlessApiErrorCode,
+		message: string,
+		public readonly kind: "configuration" | "provider" | "runtime" = "runtime",
+	) {
+		super(message)
+		this.name = "HeadlessApiError"
+	}
+}
+
 export type HeadlessTaskReference = { taskId: string; rootTaskId: string }
 
 export type HeadlessAskResponse =
@@ -66,6 +86,7 @@ export interface RooCodeAPI extends EventEmitter<RooCodeAPIEvents> {
 	}): Promise<HeadlessTaskReference>
 	resumeHeadlessTask(taskId: string, overrides?: RunOverrides): Promise<HeadlessTaskReference>
 	respondToHeadlessAsk(input: { taskId: string; askId: string; response: HeadlessAskResponse }): Promise<void>
+	submitHeadlessTaskInput(input: { taskId: string; text?: string; images?: string[] }): Promise<void>
 	settleHeadlessNeedsInput(input: { rootTaskId: string; taskId: string; content?: string }): Promise<void>
 	cancelHeadlessTask(input: {
 		rootTaskId: string