Fix Buzz ACP replies and document harness setup

README.md

@@ -94,15 +94,41 @@ Codebase speaks the [Agent Client Protocol](https://agentclientprotocol.com/) ov
 codebase acp
 ```
 
-For a Buzz custom harness, use:
+### Buzz
+
+Buzz accepts Codebase as a custom ACP harness. Current Buzz builds only attach
+their channel-publishing MCP to recognized runtime names, so use this small
+compatibility launcher until Buzz supports MCP injection for every custom
+harness:
+
+```sh
+mkdir -p ~/.local/share/codebase-buzz
+cat > ~/.local/share/codebase-buzz/codex-acp <<'SH'
+#!/bin/sh
+if [ "$#" -eq 1 ] && [ "$1" = "--version" ]; then
+  echo "codebase-acp 1.1.7"
+  exit 0
+fi
+[ "$#" -gt 0 ] || set -- acp
+exec codebase "$@"
+SH
+chmod +x ~/.local/share/codebase-buzz/codex-acp
+```
+
+Then add the Buzz custom harness:
 
 ```text
 Name: Codebase
-Command: codebase
-Arguments: acp
+Command: /Users/YOU/.local/share/codebase-buzz/codex-acp
+Arguments: (leave empty)
 ```
 
-Buzz can then discover the models available to your Codebase account. Each ACP
+The launcher still runs Codebase; the `codex-acp` filename lets current Buzz
+versions supply the MCP tools an agent needs to publish its answer into the
+channel. Without that bridge, Buzz may show Codebase's generated text in agent
+activity but never post it as a message.
+
+Buzz can discover the models available to your Codebase account. Each ACP
 session gets its own working directory and conversation, accepts client-supplied
 MCP servers, streams assistant and tool progress, supports cancellation, and
 routes write/shell approvals through the client's permission UI.

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codebase-cli",
-	"version": "2.0.0-pre.81",
+	"version": "2.0.0-pre.82",
 	"description": "Codebase CLI — a TypeScript coding agent on the pi-mono runtime. OAuth-aware, any LLM provider, single install.",
 	"keywords": [
 		"ai",

src/acp/server.test.ts

@@ -135,4 +135,60 @@ describe("runAcpServer", () => {
 		toAgent.end();
 		await serverDone;
 	});
+
+	it("streams provider failures as visible ACP messages", async () => {
+		faux.setResponses([
+			fauxAssistantMessage([], {
+				stopReason: "error",
+				errorMessage: '402 "insufficient_credits"',
+			}),
+		]);
+
+		const toAgent = new PassThrough();
+		const fromAgent = new PassThrough();
+		const serverDone = runAcpServer({
+			stdin: toAgent,
+			stdout: fromAgent,
+			configOverride: { model, apiKey: "faux-key", source: "byok" },
+		});
+		const updates: acp.SessionNotification[] = [];
+		const stream = acp.ndJsonStream(Writable.toWeb(toAgent), Readable.toWeb(fromAgent) as ReadableStream<Uint8Array>);
+
+		const result = await acp
+			.client({ name: "buzz-error-test" })
+			.onNotification(acp.methods.client.session.update, (ctx) => {
+				updates.push(ctx.params);
+			})
+			.connectWith(stream, async (client) => {
+				await client.request(acp.methods.agent.initialize, {
+					protocolVersion: acp.PROTOCOL_VERSION,
+					clientInfo: { name: "buzz-acp", version: "test" },
+				});
+				const session = await client.request(acp.methods.agent.session.new, {
+					cwd,
+					mcpServers: [],
+				});
+				return client.request(acp.methods.agent.session.prompt, {
+					sessionId: session.sessionId,
+					prompt: [{ type: "text", text: "Reply even if the provider fails." }],
+				});
+			});
+
+		expect(result.stopReason).toBe("end_turn");
+		const text = updates
+			.filter(
+				(
+					event,
+				): event is acp.SessionNotification & {
+					update: { sessionUpdate: "agent_message_chunk"; content: { type: "text"; text: string } };
+				} => event.update.sessionUpdate === "agent_message_chunk" && event.update.content.type === "text",
+			)
+			.map((event) => event.update.content.text)
+			.join("");
+		expect(text).toContain("Codebase couldn't complete this turn");
+		expect(text).toContain("Codebase credits are exhausted");
+
+		toAgent.end();
+		await serverDone;
+	});
 });

src/acp/server.ts

@@ -7,6 +7,7 @@ import type { AgentEvent } from "@earendil-works/pi-agent-core";
 import type { ImageContent } from "@earendil-works/pi-ai";
 import { type AgentBundle, type CreateAgentOptions, createAgent } from "../agent/agent.js";
 import type { ModelOption } from "../agent/model-list.js";
+import { latestAssistantError, userFacingErrorMessage } from "../errors/user-facing.js";
 import type { NamedServer } from "../mcp/config.js";
 import type { PermissionRequest, ResponseChoice } from "../permissions/store.js";
 import { VERSION } from "../version.js";
@@ -165,7 +166,14 @@ export async function runAcpServer(options: AcpServerOptions = {}): Promise<numb
 				await session.notificationQueue;
 				return { stopReason: "refusal" };
 			}
-			if (result.error) throw new Error(result.error);
+			const turnError = result.error ?? latestAssistantError(session.bundle.agent.state.messages);
+			if (turnError) {
+				const prefix = session.assistantText
+					? "\n\nCodebase couldn't complete this turn: "
+					: "Codebase couldn't complete this turn: ";
+				await notifyText(session, client, `${prefix}${userFacingErrorMessage(turnError)}`);
+				await session.notificationQueue;
+			}
 			return { stopReason: "end_turn" };
 		} finally {
 			unsubscribeEvents();

src/errors/user-facing.ts

@@ -1,3 +1,5 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
 const PROVIDER_AUTH_PATTERNS = [
 	/\bauthentication_error\b/i,
 	/\binvalid[_ -]?(?:x-)?api[_ -]?key\b/i,
@@ -16,6 +18,24 @@ export function providerAuthRecoveryMessage(raw: string): string | undefined {
 	].join(" ");
 }
 
+export function providerCreditsRecoveryMessage(raw: string): string | undefined {
+	const trimmed = raw.trim();
+	if (!trimmed || !/(\b402\b|insufficient[_ -]?credits?)/i.test(trimmed)) return undefined;
+	return [
+		"Codebase credits are exhausted.",
+		"Run `codebase usage` to check the balance, add credits in Codebase Settings, wait for the plan reset, or switch to a BYOK model.",
+	].join(" ");
+}
+
 export function userFacingErrorMessage(raw: string): string {
-	return providerAuthRecoveryMessage(raw) ?? raw.trim();
+	return providerAuthRecoveryMessage(raw) ?? providerCreditsRecoveryMessage(raw) ?? raw.trim();
+}
+
+export function latestAssistantError(messages: AgentMessage[]): string | undefined {
+	const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+	if (!lastAssistant) return undefined;
+	const candidate = lastAssistant as { stopReason?: unknown; errorMessage?: unknown };
+	if (typeof candidate.errorMessage === "string" && candidate.errorMessage.trim()) return candidate.errorMessage;
+	if (candidate.stopReason === "error") return "Agent turn ended with an error.";
+	return undefined;
 }

src/headless/run.ts

@@ -3,7 +3,7 @@ import type { Usage } from "@earendil-works/pi-ai";
 import { type AgentBundle, type CreateAgentOptions, createAgent } from "../agent/agent.js";
 import { ConfigError } from "../agent/config.js";
 import { visibleMessages } from "../agent/visible-messages.js";
-import { userFacingErrorMessage } from "../errors/user-facing.js";
+import { latestAssistantError, userFacingErrorMessage } from "../errors/user-facing.js";
 import { ReceiptStore } from "./receipt-store.js";
 import {
 	formatReliabilityFailure,
@@ -535,15 +535,6 @@ function extractText(message: { content?: unknown }): string {
 	return parts.join("");
 }
 
-function latestAssistantError(messages: AgentMessage[]): string | undefined {
-	const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant");
-	if (!lastAssistant) return undefined;
-	const candidate = lastAssistant as { stopReason?: unknown; errorMessage?: unknown };
-	if (typeof candidate.errorMessage === "string" && candidate.errorMessage.trim()) return candidate.errorMessage;
-	if (candidate.stopReason === "error") return "Agent turn ended with an error.";
-	return undefined;
-}
-
 function latestAssistantText(messages: AgentMessage[]): string {
 	const lastAssistant = [...messages]
 		.reverse()