feat(cli): support images in stdin stream commands (#11831)

feat(cli): support images in stdin stream start and message commands

Add optional `images` field (array of base64 data URIs) to the `start` and
`message` CLI stdin stream commands, allowing callers to attach images to
prompts. The images are validated, forwarded through the extension host, and
included in queued messages.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

apps/cli/scripts/integration/cases/message-images-queue-metadata.ts

@@ -0,0 +1,124 @@
+import { runStreamCase, StreamEvent } from "../lib/stream-harness"
+
+const LONG_PROMPT =
+	'Run exactly this command and do not summarize until it finishes: sleep 20 && echo "done". After it finishes, reply with exactly "done".'
+
+async function main() {
+	const startRequestId = `start-${Date.now()}`
+	const messageRequestId = `message-${Date.now()}`
+	const shutdownRequestId = `shutdown-${Date.now()}`
+	const testImage = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB"
+
+	let initSeen = false
+	let startAccepted = false
+	let messageAccepted = false
+	let messageQueued = false
+	let queueImageCountObserved = false
+	let shutdownSent = false
+	let shutdownAck = false
+	let shutdownDone = false
+
+	await runStreamCase({
+		timeoutMs: 180_000,
+		onEvent(event: StreamEvent, context) {
+			if (event.type === "system" && event.subtype === "init" && !initSeen) {
+				initSeen = true
+				context.sendCommand({ command: "start", requestId: startRequestId, prompt: LONG_PROMPT })
+				return
+			}
+
+			if (
+				event.type === "control" &&
+				event.subtype === "ack" &&
+				event.command === "start" &&
+				event.requestId === startRequestId &&
+				!startAccepted
+			) {
+				startAccepted = true
+
+				context.sendCommand({
+					command: "message",
+					requestId: messageRequestId,
+					prompt: "Respond with exactly IMAGE-QUEUED when this message is processed.",
+					images: [testImage],
+				})
+
+				return
+			}
+
+			if (
+				event.type === "control" &&
+				event.subtype === "ack" &&
+				event.command === "message" &&
+				event.requestId === messageRequestId
+			) {
+				messageAccepted = true
+				return
+			}
+
+			if (
+				event.type === "control" &&
+				event.subtype === "done" &&
+				event.command === "message" &&
+				event.requestId === messageRequestId &&
+				event.code === "queued"
+			) {
+				messageQueued = true
+				return
+			}
+
+			if (
+				event.type === "queue" &&
+				(event.subtype === "snapshot" || event.subtype === "enqueued" || event.subtype === "updated") &&
+				Array.isArray(event.queue) &&
+				event.queue.some((item) => item?.imageCount === 1)
+			) {
+				queueImageCountObserved = true
+
+				if (!shutdownSent) {
+					context.sendCommand({ command: "shutdown", requestId: shutdownRequestId })
+					shutdownSent = true
+				}
+
+				return
+			}
+
+			if (
+				event.type === "control" &&
+				event.subtype === "ack" &&
+				event.command === "shutdown" &&
+				event.requestId === shutdownRequestId
+			) {
+				shutdownAck = true
+				return
+			}
+
+			if (
+				event.type === "control" &&
+				event.subtype === "done" &&
+				event.command === "shutdown" &&
+				event.requestId === shutdownRequestId
+			) {
+				shutdownDone = true
+			}
+		},
+		onTimeoutMessage() {
+			return `timed out waiting for queue image metadata (initSeen=${initSeen}, startAccepted=${startAccepted}, messageAccepted=${messageAccepted}, messageQueued=${messageQueued}, queueImageCountObserved=${queueImageCountObserved}, shutdownSent=${shutdownSent}, shutdownAck=${shutdownAck}, shutdownDone=${shutdownDone})`
+		},
+	})
+
+	if (!messageAccepted || !messageQueued || !queueImageCountObserved) {
+		throw new Error(
+			`expected queued message with image metadata (messageAccepted=${messageAccepted}, messageQueued=${messageQueued}, queueImageCountObserved=${queueImageCountObserved})`,
+		)
+	}
+
+	if (!shutdownAck || !shutdownDone) {
+		throw new Error("shutdown control events were not fully observed")
+	}
+}
+
+main().catch((error) => {
+	console.error(`[FAIL] ${error instanceof Error ? error.message : String(error)}`)
+	process.exit(1)
+})

apps/cli/scripts/integration/lib/stream-harness.ts

@@ -30,6 +30,7 @@ export type StreamCommand = {
 	command: "start" | "message" | "cancel" | "ping" | "shutdown"
 	requestId: string
 	prompt?: string
+	images?: string[]
 }
 
 export interface StreamCaseContext {

apps/cli/src/agent/extension-host.ts

@@ -108,7 +108,7 @@ interface WebviewViewProvider {
 export interface ExtensionHostInterface extends IExtensionHost<ExtensionHostEventMap> {
 	client: ExtensionClient
 	activate(): Promise<void>
-	runTask(prompt: string, taskId?: string, configuration?: RooCodeSettings): Promise<void>
+	runTask(prompt: string, taskId?: string, configuration?: RooCodeSettings, images?: string[]): Promise<void>
 	resumeTask(taskId: string): Promise<void>
 	sendToExtension(message: WebviewMessage): void
 	dispose(): Promise<void>
@@ -510,8 +510,19 @@ export class ExtensionHost extends EventEmitter implements ExtensionHostInterfac
 		})
 	}
 
-	public async runTask(prompt: string, taskId?: string, configuration?: RooCodeSettings): Promise<void> {
-		this.sendToExtension({ type: "newTask", text: prompt, taskId, taskConfiguration: configuration })
+	public async runTask(
+		prompt: string,
+		taskId?: string,
+		configuration?: RooCodeSettings,
+		images?: string[],
+	): Promise<void> {
+		this.sendToExtension({
+			type: "newTask",
+			text: prompt,
+			taskId,
+			taskConfiguration: configuration,
+			...(images !== undefined ? { images } : {}),
+		})
 		return this.waitForTaskCompletion()
 	}
 

apps/cli/src/commands/cli/__tests__/parse-stdin-command.test.ts

@@ -18,6 +18,40 @@ describe("parseStdinStreamCommand", () => {
 			expect(result).toEqual({ command: "message", requestId: "req-2", prompt: "follow up" })
 		})
 
+		it("parses start and message images", () => {
+			const start = parseStdinStreamCommand(
+				JSON.stringify({
+					command: "start",
+					requestId: "req-img-start",
+					prompt: "hello",
+					images: ["data:image/jpeg;base64,abc123"],
+				}),
+				1,
+			)
+			expect(start).toEqual({
+				command: "start",
+				requestId: "req-img-start",
+				prompt: "hello",
+				images: ["data:image/jpeg;base64,abc123"],
+			})
+
+			const message = parseStdinStreamCommand(
+				JSON.stringify({
+					command: "message",
+					requestId: "req-img-msg",
+					prompt: "follow up",
+					images: ["data:image/png;base64,xyz456"],
+				}),
+				1,
+			)
+			expect(message).toEqual({
+				command: "message",
+				requestId: "req-img-msg",
+				prompt: "follow up",
+				images: ["data:image/png;base64,xyz456"],
+			})
+		})
+
 		it.each(["cancel", "ping", "shutdown"] as const)("parses a %s command (no prompt required)", (command) => {
 			const result = parseStdinStreamCommand(JSON.stringify({ command, requestId: "req-3" }), 1)
 			expect(result).toEqual({ command, requestId: "req-3" })
@@ -100,5 +134,31 @@ describe("parseStdinStreamCommand", () => {
 				parseStdinStreamCommand(JSON.stringify({ command: "message", requestId: "req", prompt: "  " }), 1),
 			).toThrow('"message" requires non-empty string "prompt"')
 		})
+
+		it("throws when start or message images are not string arrays", () => {
+			expect(() =>
+				parseStdinStreamCommand(
+					JSON.stringify({
+						command: "start",
+						requestId: "req-start-img",
+						prompt: "hello",
+						images: "not-an-array",
+					}),
+					1,
+				),
+			).toThrow('"start" images must be an array of strings')
+
+			expect(() =>
+				parseStdinStreamCommand(
+					JSON.stringify({
+						command: "message",
+						requestId: "req-msg-img",
+						prompt: "follow up",
+						images: ["ok", 123],
+					}),
+					1,
+				),
+			).toThrow('"message" images must be an array of strings')
+		})
 	})
 })

apps/cli/src/commands/cli/stdin-stream.ts

@@ -63,20 +63,38 @@ export function parseStdinStreamCommand(line: string, lineNumber: number): Stdin
 
 	if (command === "start" || command === "message") {
 		const promptRaw = parsed.prompt
+
 		if (typeof promptRaw !== "string" || promptRaw.trim().length === 0) {
 			throw new Error(`stdin command line ${lineNumber}: "${command}" requires non-empty string "prompt"`)
 		}
 
+		const imagesRaw = parsed.images
+		let images: string[] | undefined
+
+		if (imagesRaw !== undefined) {
+			if (!Array.isArray(imagesRaw) || !imagesRaw.every((image) => typeof image === "string")) {
+				throw new Error(`stdin command line ${lineNumber}: "${command}" images must be an array of strings`)
+			}
+
+			images = imagesRaw
+		}
+
 		if (command === "start" && isRecord(parsed.configuration)) {
 			return {
 				command,
 				requestId,
 				prompt: promptRaw,
+				...(images !== undefined ? { images } : {}),
 				configuration: parsed.configuration as RooCliStartCommand["configuration"],
 			}
 		}
 
-		return { command, requestId, prompt: promptRaw }
+		return {
+			command,
+			requestId,
+			prompt: promptRaw,
+			...(images !== undefined ? { images } : {}),
+		}
 	}
 
 	return { command, requestId }
@@ -601,7 +619,7 @@ export async function runStdinStreamMode({ host, jsonEmitter, setStreamRequestId
 					}
 
 					activeTaskPromise = host
-						.runTask(stdinCommand.prompt, latestTaskId, taskConfiguration)
+						.runTask(stdinCommand.prompt, latestTaskId, taskConfiguration, stdinCommand.images)
 						.catch((error) => {
 							const message = error instanceof Error ? error.message : String(error)
 
@@ -691,7 +709,11 @@ export async function runStdinStreamMode({ host, jsonEmitter, setStreamRequestId
 						success: true,
 					})
 
-					host.sendToExtension({ type: "queueMessage", text: stdinCommand.prompt })
+					host.sendToExtension({
+						type: "queueMessage",
+						text: stdinCommand.prompt,
+						images: stdinCommand.images,
+					})
 					pendingQueuedMessageRequestIds.push(stdinCommand.requestId)
 					if (host.isWaitingForInput()) {
 						setStreamRequestId(stdinCommand.requestId)

packages/types/src/__tests__/cli.test.ts

@@ -12,12 +12,24 @@ describe("CLI types", () => {
 				command: "start",
 				requestId: "req-1",
 				prompt: "hello",
+				images: ["data:image/png;base64,abc"],
 				configuration: {},
 			})
 
 			expect(result.success).toBe(true)
 		})
 
+		it("validates a message command with images", () => {
+			const result = rooCliInputCommandSchema.safeParse({
+				command: "message",
+				requestId: "req-2a",
+				prompt: "follow up",
+				images: ["data:image/png;base64,xyz"],
+			})
+
+			expect(result.success).toBe(true)
+		})
+
 		it("rejects a message command without prompt", () => {
 			const result = rooCliInputCommandSchema.safeParse({
 				command: "message",

packages/types/src/cli.ts

@@ -22,6 +22,7 @@ export type RooCliCommandBase = z.infer<typeof rooCliCommandBaseSchema>
 export const rooCliStartCommandSchema = rooCliCommandBaseSchema.extend({
 	command: z.literal("start"),
 	prompt: z.string(),
+	images: z.array(z.string()).optional(),
 	configuration: rooCodeSettingsSchema.optional(),
 })
 
@@ -30,6 +31,7 @@ export type RooCliStartCommand = z.infer<typeof rooCliStartCommandSchema>
 export const rooCliMessageCommandSchema = rooCliCommandBaseSchema.extend({
 	command: z.literal("message"),
 	prompt: z.string(),
+	images: z.array(z.string()).optional(),
 })
 
 export type RooCliMessageCommand = z.infer<typeof rooCliMessageCommandSchema>