@oh-my-pi/pi-coding-agent 15.1.3 → 15.1.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [15.1.4] - 2026-05-19
+
+### Fixed
+
+- Fixed `normalizePlanTitle` rejecting plan titles that contain spaces or common punctuation (e.g. "My Feature Plan") — spaces are now converted to hyphens and other invalid characters are dropped, so models that produce natural-language plan titles no longer loop forever trying to call `resolve`. ([#1176](https://github.com/can1357/oh-my-pi/issues/1176))
+- Fixed `ask` tool prompt example showing the legacy `question`/`options` top-level format instead of the current `questions: [{id, question, options}]` array format; models that closely followed the example generated calls that always failed schema validation. ([#1176](https://github.com/can1357/oh-my-pi/issues/1176))
+
+- Fixed ACP command and custom tool-call notifications to carry the original tool arguments in replayed and final updates, so command text is preserved and raw input is no longer wrapped
+- Fixed ACP async-job draining to be scoped by session owner so `getAsyncJobSnapshot` and `drainAsyncJobDeliveriesForAcp` no longer consume or expose jobs from other sessions
+- Fixed async job status reporting to include in-flight completions so queued/delivering indicators remain accurate while callbacks are still running
+- Fixed `deferAgentInitiatedTurns` handling during ACP async-job draining so background completion follow-up turns are delivered even when agent-initiated turns are deferred
+- Fixed ACP ordinary file-editing calls (`edit`, `write`, `ast_edit`) incorrectly requesting `session/request_permission` before every call, while keeping permission prompts for edit operations that delete or move files; permission requests now report the gated tool call as `pending` so clients can render the approval UI instead of returning `Permission request cancelled` without a visible prompt. ([#1134](https://github.com/can1357/oh-my-pi/pull/1134) by [@jiwangyihao](https://github.com/jiwangyihao))
+- Fixed the session tree selector to preserve a readable message column when deeply nested branch gutters would otherwise consume the viewport. ([#1144](https://github.com/can1357/oh-my-pi/issues/1144))
+
 ## [15.1.3] - 2026-05-17
 ### Breaking Changes
 
@@ -44,6 +58,10 @@
 - Fixed auth-gateway request cancellation for requests that are already aborted before dispatch.
 - Fixed `/login` and `/logout` provider selector overflowing tall provider lists off-screen on small terminals. The selector now scrolls a 10-item window centered on the highlighted entry, shows a `(n/total)` indicator when windowed, and accepts PageUp/PageDown for faster navigation.
 
+### Fixed
+
+- Fixed `.env` loading so malformed variable names and NUL-containing values are ignored before they can poison `Bun.env` and break bash/external process execution with `nul byte found in provided data`.
+
 ## [15.1.2] - 2026-05-15
 ### Fixed
 

package/dist/types/async/job-manager.d.ts

@@ -65,8 +65,8 @@ export declare class AsyncJobManager {
     getRunningJobs(filter?: AsyncJobFilter): AsyncJob[];
     getRecentJobs(limit?: number, filter?: AsyncJobFilter): AsyncJob[];
     getAllJobs(filter?: AsyncJobFilter): AsyncJob[];
-    getDeliveryState(): AsyncJobDeliveryState;
-    hasPendingDeliveries(): boolean;
+    getDeliveryState(filter?: AsyncJobFilter): AsyncJobDeliveryState;
+    hasPendingDeliveries(filter?: AsyncJobFilter): boolean;
     watchJobs(jobIds: string[]): number;
     unwatchJobs(jobIds: string[]): number;
     acknowledgeDeliveries(jobIds: string[]): number;
@@ -79,6 +79,7 @@ export declare class AsyncJobManager {
     waitForAll(): Promise<void>;
     drainDeliveries(options?: {
         timeoutMs?: number;
+        filter?: AsyncJobFilter;
     }): Promise<boolean>;
     dispose(options?: {
         timeoutMs?: number;

package/dist/types/main.d.ts

@@ -5,13 +5,22 @@
  * createAgentSession() options. The SDK does the heavy lifting.
  */
 import type { Args } from "./cli/args";
-import { InteractiveMode } from "./modes";
+import { Settings } from "./config/settings";
+import { InteractiveMode, runAcpMode } from "./modes";
 import type { SubmittedUserInput } from "./modes/types";
+import { createAgentSession, discoverAuthStorage } from "./sdk";
 import type { AgentSession } from "./session/agent-session";
 export interface InteractiveModeNotify {
     kind: "warn" | "error" | "info";
     message: string;
 }
 export declare function submitInteractiveInput(mode: Pick<InteractiveMode, "markPendingSubmissionStarted" | "finishPendingSubmission" | "showError" | "checkShutdownRequested">, session: Pick<AgentSession, "prompt" | "promptCustomMessage">, input: SubmittedUserInput): Promise<void>;
-export declare function runRootCommand(parsed: Args, rawArgs: string[]): Promise<void>;
+interface RunRootCommandDependencies {
+    createAgentSession?: typeof createAgentSession;
+    discoverAuthStorage?: typeof discoverAuthStorage;
+    runAcpMode?: typeof runAcpMode;
+    settings?: Settings;
+}
+export declare function runRootCommand(parsed: Args, rawArgs: string[], deps?: RunRootCommandDependencies): Promise<void>;
 export declare function main(args: string[]): Promise<void>;
+export {};

package/dist/types/modes/acp/acp-agent.d.ts

@@ -30,7 +30,7 @@ type CreateAcpSession = (cwd: string) => Promise<AgentSession>;
 export declare function createAcpExtensionUiContext(connection: AgentSideConnection, getSessionId: () => string, clientCapabilities: ClientCapabilities | undefined): ExtensionUIContext;
 export declare class AcpAgent implements Agent {
     #private;
-    constructor(connection: AgentSideConnection, initialSession: AgentSession, createSession: CreateAcpSession);
+    constructor(connection: AgentSideConnection, createSession: CreateAcpSession, initialSession?: AgentSession);
     setCancelCleanupTimeoutForTesting(timeoutMs: number): void;
     initialize(params: InitializeRequest): Promise<InitializeResponse>;
     authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse>;

package/dist/types/modes/acp/acp-event-mapper.d.ts

@@ -1,4 +1,4 @@
-import type { SessionNotification, ToolKind } from "@agentclientprotocol/sdk";
+import type { SessionNotification, SessionUpdate, ToolKind } from "@agentclientprotocol/sdk";
 import type { AgentSessionEvent } from "../../session/agent-session";
 interface MessageProgress {
     textEmitted: boolean;
@@ -7,6 +7,7 @@ interface MessageProgress {
 interface AcpEventMapperOptions {
     getMessageId?: (message: unknown) => string | undefined;
     getMessageProgress?: (message: unknown) => MessageProgress | undefined;
+    getToolArgs?: (toolCallId: string) => unknown;
     /**
      * Session cwd. Tool call locations sent to ACP clients must be absolute
      * (the editor host needs them to open or focus files). When provided,
@@ -17,4 +18,15 @@ interface AcpEventMapperOptions {
 }
 export declare function mapToolKind(toolName: string): ToolKind;
 export declare function mapAgentSessionEventToAcpSessionUpdates(event: AgentSessionEvent, sessionId: string, options?: AcpEventMapperOptions): SessionNotification[];
+export declare function buildToolCallStartUpdate(input: {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    intent?: string;
+    cwd?: string;
+    status?: "pending" | "completed";
+}): SessionUpdate;
+export declare function normalizeReplayToolArguments(value: unknown): {
+    args: unknown;
+};
 export {};

package/dist/types/modes/acp/acp-mode.d.ts

@@ -1,3 +1,5 @@
+import { AgentSideConnection, type Stream } from "@agentclientprotocol/sdk";
 import type { AgentSession } from "../../session/agent-session";
 export type AcpSessionFactory = (cwd: string) => Promise<AgentSession>;
-export declare function runAcpMode(session: AgentSession, createSession: AcpSessionFactory): Promise<never>;
+export declare function createAcpConnection(transport: Stream, createSession: AcpSessionFactory, initialSession?: AgentSession): AgentSideConnection;
+export declare function runAcpMode(createSession: AcpSessionFactory, initialSession?: AgentSession): Promise<never>;

package/dist/types/plan-mode/approved-plan.d.ts

@@ -7,10 +7,12 @@ export interface PlanApprovalDetails {
     title: string;
     planExists: boolean;
 }
-/** Validate the agent-supplied plan title and derive the destination filename.
- *  Filename uses the title with a `.md` suffix; characters are restricted to
- *  letters, numbers, underscores, and hyphens so the value is safe to splice
- *  into a `local://` URL without escaping. */
+/** Validate and normalize the agent-supplied plan title into a safe filename stem.
+ *  Spaces and other URL-safe punctuation are replaced with hyphens so models that
+ *  produce natural-language titles (e.g. "My feature plan") still succeed.
+ *  Characters that cannot be safely represented after replacement are dropped.
+ *  The result is restricted to letters, numbers, underscores, and hyphens so it
+ *  is safe to splice into a `local://` URL without escaping. */
 export declare function normalizePlanTitle(title: string): {
     title: string;
     fileName: string;

package/dist/types/session/agent-session.d.ts

@@ -15,7 +15,7 @@
 import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import { type CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
 import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolChoice, UsageReport } from "@oh-my-pi/pi-ai";
-import { type AsyncJob, AsyncJobManager } from "../async";
+import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
 import { type ModelRegistry } from "../config/model-registry";
 import { type ResolvedModelRoleValue } from "../config/model-resolver";
@@ -111,6 +111,7 @@ export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "la
 export interface AsyncJobSnapshot {
     running: AsyncJobSnapshotItem[];
     recent: AsyncJobSnapshotItem[];
+    delivery: AsyncJobDeliveryState;
 }
 export interface AgentSessionConfig {
     agent: Agent;
@@ -347,6 +348,9 @@ export declare class AgentSession {
     get isStreaming(): boolean;
     /** Wait until streaming and deferred recovery work are fully settled. */
     waitForIdle(): Promise<void>;
+    drainAsyncJobDeliveriesForAcp(options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
     /** Most recent assistant message in agent state. */
     getLastAssistantMessage(): AssistantMessage | undefined;
     /** Current effective system prompt blocks (includes any per-turn extension modifications) */
@@ -495,7 +499,7 @@ export declare class AgentSession {
      *
      * Handles three cases:
      * - Streaming: queue as steer/follow-up or store for next turn
-     * - Not streaming + triggerTurn: appends to state/session, starts new turn
+     * - Not streaming + triggerTurn: appends to state/session, starts new turn unless the client cannot own it
      * - Not streaming + no trigger: appends to state/session, no turn
      */
     sendCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: {

package/dist/types/session/client-bridge.d.ts

@@ -23,6 +23,7 @@ export interface ClientBridgePermissionToolCall {
     toolName: string;
     title: string;
     kind?: string;
+    status?: "pending" | "in_progress" | "completed" | "failed";
     rawInput?: unknown;
     locations?: {
         path: string;
@@ -70,6 +71,8 @@ export interface ClientBridgeCreateTerminalParams {
 }
 export interface ClientBridge {
     readonly capabilities: ClientBridgeCapabilities;
+    /** ACP v1 clients cannot show server-initiated turns as busy after prompt response. */
+    readonly deferAgentInitiatedTurns?: boolean;
     readTextFile?(params: {
         path: string;
         line?: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.1.3",
+	"version": "15.1.4",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -47,12 +47,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/omp-stats": "15.1.3",
-		"@oh-my-pi/pi-agent-core": "15.1.3",
-		"@oh-my-pi/pi-ai": "15.1.3",
-		"@oh-my-pi/pi-natives": "15.1.3",
-		"@oh-my-pi/pi-tui": "15.1.3",
-		"@oh-my-pi/pi-utils": "15.1.3",
+		"@oh-my-pi/omp-stats": "15.1.4",
+		"@oh-my-pi/pi-agent-core": "15.1.4",
+		"@oh-my-pi/pi-ai": "15.1.4",
+		"@oh-my-pi/pi-natives": "15.1.4",
+		"@oh-my-pi/pi-tui": "15.1.4",
+		"@oh-my-pi/pi-utils": "15.1.4",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/async/job-manager.ts

@@ -37,6 +37,8 @@ interface AsyncJobDelivery {
 	attempt: number;
 	nextAttemptAt: number;
 	lastError?: string;
+	ownerId?: string;
+	promise?: Promise<void>;
 }
 
 export interface AsyncJobDeliveryState {
@@ -82,6 +84,7 @@ export class AsyncJobManager {
 
 	readonly #jobs = new Map<string, AsyncJob>();
 	readonly #deliveries: AsyncJobDelivery[] = [];
+	readonly #inFlightDeliveries: AsyncJobDelivery[] = [];
 	readonly #suppressedDeliveries = new Set<string>();
 	readonly #watchedJobs = new Set<string>();
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
@@ -219,22 +222,24 @@ export class AsyncJobManager {
 		return this.#filterJobs(this.#jobs.values(), filter);
 	}
 
-	getDeliveryState(): AsyncJobDeliveryState {
-		const nextRetryAt = this.#deliveries.reduce<number | undefined>((next, delivery) => {
+	getDeliveryState(filter?: AsyncJobFilter): AsyncJobDeliveryState {
+		const deliveries = this.#filterDeliveries(filter);
+		const inFlightDeliveries = this.#filterInFlightDeliveries(filter);
+		const nextRetryAt = deliveries.reduce<number | undefined>((next, delivery) => {
 			if (next === undefined) return delivery.nextAttemptAt;
 			return Math.min(next, delivery.nextAttemptAt);
 		}, undefined);
 
 		return {
-			queued: this.#deliveries.length,
-			delivering: this.#deliveryLoop !== undefined,
+			queued: deliveries.length + inFlightDeliveries.length,
+			delivering: inFlightDeliveries.length > 0 || (this.#deliveryLoop !== undefined && deliveries.length > 0),
 			nextRetryAt,
-			pendingJobIds: this.#deliveries.map(delivery => delivery.jobId),
+			pendingJobIds: deliveries.concat(inFlightDeliveries).map(delivery => delivery.jobId),
 		};
 	}
 
-	hasPendingDeliveries(): boolean {
-		return this.#deliveries.length > 0;
+	hasPendingDeliveries(filter?: AsyncJobFilter): boolean {
+		return this.getDeliveryState(filter).queued > 0;
 	}
 
 	watchJobs(jobIds: string[]): number {
@@ -290,12 +295,25 @@ export class AsyncJobManager {
 		await Promise.all(Array.from(this.#jobs.values()).map(job => job.promise));
 	}
 
-	async drainDeliveries(options?: { timeoutMs?: number }): Promise<boolean> {
+	async drainDeliveries(options?: { timeoutMs?: number; filter?: AsyncJobFilter }): Promise<boolean> {
 		const timeoutMs = options?.timeoutMs;
+		const filter = options?.filter;
 		const hasDeadline = timeoutMs !== undefined;
 		const deadline = hasDeadline ? Date.now() + Math.max(timeoutMs, 0) : Number.POSITIVE_INFINITY;
 
-		while (this.hasPendingDeliveries()) {
+		while (this.hasPendingDeliveries(filter)) {
+			if (filter?.ownerId) {
+				const delivered = await this.#deliverNextFiltered(filter, deadline);
+				if (delivered) continue;
+				return false;
+			}
+			const inFlightDeliveries = this.#filterInFlightDeliveries();
+			if (inFlightDeliveries.length > 0 && this.#filterDeliveries().length === 0) {
+				const delivered = await this.#waitForDeliveryPromise(inFlightDeliveries[0]?.promise, deadline);
+				if (delivered) continue;
+				return false;
+			}
+
 			this.#ensureDeliveryLoop();
 			const loop = this.#deliveryLoop;
 			if (!loop) {
@@ -313,7 +331,7 @@ export class AsyncJobManager {
 			}
 
 			await Promise.race([loop, Bun.sleep(remainingMs)]);
-			if (Date.now() >= deadline && this.hasPendingDeliveries()) {
+			if (Date.now() >= deadline && this.hasPendingDeliveries(filter)) {
 				return false;
 			}
 		}
@@ -330,6 +348,7 @@ export class AsyncJobManager {
 		this.#clearEvictionTimers();
 		this.#jobs.clear();
 		this.#deliveries.length = 0;
+		this.#inFlightDeliveries.length = 0;
 		this.#suppressedDeliveries.clear();
 		this.#watchedJobs.clear();
 		return drained;
@@ -388,6 +407,55 @@ export class AsyncJobManager {
 		this.#evictionTimers.clear();
 	}
 
+	#filterDeliveries(filter?: AsyncJobFilter): AsyncJobDelivery[] {
+		const ownerId = filter?.ownerId;
+		if (!ownerId) return this.#deliveries.filter(delivery => !this.isDeliverySuppressed(delivery.jobId));
+		return this.#deliveries.filter(
+			delivery => delivery.ownerId === ownerId && !this.isDeliverySuppressed(delivery.jobId),
+		);
+	}
+
+	#filterInFlightDeliveries(filter?: AsyncJobFilter): AsyncJobDelivery[] {
+		const ownerId = filter?.ownerId;
+		if (!ownerId) return this.#inFlightDeliveries.filter(delivery => !this.isDeliverySuppressed(delivery.jobId));
+		return this.#inFlightDeliveries.filter(
+			delivery => delivery.ownerId === ownerId && !this.isDeliverySuppressed(delivery.jobId),
+		);
+	}
+
+	async #deliverNextFiltered(filter: AsyncJobFilter, deadline: number): Promise<boolean> {
+		while (true) {
+			let selected: AsyncJobDelivery | undefined;
+			for (const delivery of this.#deliveries) {
+				if (delivery.ownerId !== filter.ownerId) continue;
+				if (this.isDeliverySuppressed(delivery.jobId)) continue;
+				if (!selected || delivery.nextAttemptAt < selected.nextAttemptAt) {
+					selected = delivery;
+				}
+			}
+
+			if (!selected) {
+				const inFlight = this.#filterInFlightDeliveries(filter);
+				if (inFlight.length === 0) return true;
+				return this.#waitForDeliveryPromise(inFlight[0]?.promise, deadline);
+			}
+
+			const now = Date.now();
+			if (selected.nextAttemptAt > now) {
+				if (selected.nextAttemptAt > deadline) return false;
+				await Bun.sleep(selected.nextAttemptAt - now);
+				continue;
+			}
+
+			const index = this.#deliveries.indexOf(selected);
+			if (index === -1) continue;
+			this.#deliveries.splice(index, 1);
+			if (this.isDeliverySuppressed(selected.jobId)) continue;
+
+			return this.#waitForDeliveryPromise(this.#deliverDelivery(selected), deadline);
+		}
+	}
+
 	isDeliverySuppressed(jobId: string): boolean {
 		return this.#suppressedDeliveries.has(jobId) || this.#watchedJobs.has(jobId);
 	}
@@ -402,6 +470,7 @@ export class AsyncJobManager {
 			text,
 			attempt: 0,
 			nextAttemptAt: Date.now(),
+			ownerId: this.#jobs.get(jobId)?.ownerId,
 		});
 		this.#ensureDeliveryLoop();
 	}
@@ -437,20 +506,25 @@ export class AsyncJobManager {
 			if (this.#deliveries[0] !== delivery) {
 				continue;
 			}
-			// Check again after sleep
 			if (this.isDeliverySuppressed(delivery.jobId)) {
 				this.#deliveries.shift();
 				continue;
 			}
 
+			this.#deliveries.shift();
+			await this.#deliverDelivery(delivery);
+		}
+	}
+
+	#deliverDelivery(delivery: AsyncJobDelivery): Promise<void> {
+		const promise = (async () => {
+			this.#inFlightDeliveries.push(delivery);
 			try {
 				await this.#onJobComplete(delivery.jobId, delivery.text, this.#jobs.get(delivery.jobId));
-				this.#deliveries.shift();
 			} catch (error) {
 				delivery.attempt += 1;
 				delivery.lastError = error instanceof Error ? error.message : String(error);
 				delivery.nextAttemptAt = Date.now() + this.#getRetryDelay(delivery.attempt);
-				this.#deliveries.shift();
 				if (!this.isDeliverySuppressed(delivery.jobId)) {
 					this.#deliveries.push(delivery);
 				}
@@ -460,8 +534,32 @@ export class AsyncJobManager {
 					nextRetryAt: delivery.nextAttemptAt,
 					error: delivery.lastError,
 				});
+			} finally {
+				const index = this.#inFlightDeliveries.indexOf(delivery);
+				if (index !== -1) this.#inFlightDeliveries.splice(index, 1);
+				if (this.#deliveries.length > 0) this.#ensureDeliveryLoop();
 			}
+		})();
+		delivery.promise = promise;
+		return promise;
+	}
+
+	async #waitForDeliveryPromise(promise: Promise<void> | undefined, deadline: number): Promise<boolean> {
+		if (!promise) return true;
+		if (deadline === Number.POSITIVE_INFINITY) {
+			await promise;
+			return true;
 		}
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) return false;
+		let timedOut = false;
+		await Promise.race([
+			promise,
+			Bun.sleep(remainingMs).then(() => {
+				timedOut = true;
+			}),
+		]);
+		return !timedOut;
 	}
 
 	#getRetryDelay(attempt: number): number {

package/src/cli/update-cli.ts

@@ -235,11 +235,7 @@ async function printVerification(expectedVersion: string): Promise<void> {
 			chalk.yellow(`\nWarning: could not verify updated version${result.path ? ` at ${result.path}` : ""}`),
 		);
 	}
-	console.log(
-		chalk.yellow(
-			`You may need to reinstall: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash`,
-		),
-	);
+	console.log(chalk.yellow(`You may need to reinstall: curl -fsSL https://omp.sh/install | sh`));
 }
 
 /**

package/src/eval/js/shared/runtime.ts

@@ -38,6 +38,75 @@ export interface RuntimeOptions {
 	extraGlobals?: Record<string, unknown>;
 }
 
+// Strict base64: characters from the standard alphabet plus optional `=` padding, and a
+// length that is a multiple of four. URL-safe base64 and embedded whitespace are not
+// accepted — the Anthropic API only honors strict base64 in image sources.
+const BASE64_STRICT_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+const DECIMAL_CSV_RE = /^\d{1,3}(?:,\d{1,3})*$/;
+
+function isStrictBase64(s: string): boolean {
+	if (s.length === 0 || s.length % 4 !== 0) return false;
+	return BASE64_STRICT_RE.test(s);
+}
+
+/**
+ * Normalize the `data` field of an `{ type: "image", data, mimeType }` display payload
+ * into strict base64. Accepts:
+ *   - already-valid base64 strings (passed through verbatim)
+ *   - `Uint8Array` / `Buffer` / `ArrayBuffer` / typed array views
+ *   - `{ type: "Buffer", data: number[] }` (the shape Node serializes Buffers to via
+ *     `JSON.stringify`)
+ *   - decimal-CSV byte strings (the output of `uint8array.toString("base64")`, which
+ *     silently ignores the encoding argument and returns `Array.prototype.toString` —
+ *     a footgun for callers expecting `Buffer.toString` semantics)
+ * Returns `null` if no recovery is possible.
+ */
+function coerceImageBase64(data: unknown): string | null {
+	if (typeof data === "string") {
+		if (isStrictBase64(data)) return data;
+		if (DECIMAL_CSV_RE.test(data)) {
+			const parts = data.split(",");
+			const bytes = new Uint8Array(parts.length);
+			for (let i = 0; i < parts.length; i++) {
+				const n = Number(parts[i]);
+				if (!Number.isInteger(n) || n < 0 || n > 255) return null;
+				bytes[i] = n;
+			}
+			return Buffer.from(bytes).toString("base64");
+		}
+		return null;
+	}
+	if (data instanceof Uint8Array) return Buffer.from(data).toString("base64");
+	if (data instanceof ArrayBuffer) return Buffer.from(data).toString("base64");
+	if (ArrayBuffer.isView(data)) {
+		const view = data as ArrayBufferView;
+		return Buffer.from(view.buffer, view.byteOffset, view.byteLength).toString("base64");
+	}
+	if (data && typeof data === "object") {
+		const obj = data as { type?: unknown; data?: unknown };
+		if (obj.type === "Buffer" && Array.isArray(obj.data)) {
+			const arr = obj.data as unknown[];
+			const bytes = new Uint8Array(arr.length);
+			for (let i = 0; i < arr.length; i++) {
+				const n = arr[i];
+				if (typeof n !== "number" || !Number.isInteger(n) || n < 0 || n > 255) return null;
+				bytes[i] = n;
+			}
+			return Buffer.from(bytes).toString("base64");
+		}
+	}
+	return null;
+}
+
+function describeDataType(data: unknown): string {
+	if (data === null) return "null";
+	if (data instanceof Uint8Array) return "Uint8Array";
+	if (data instanceof ArrayBuffer) return "ArrayBuffer";
+	if (ArrayBuffer.isView(data)) return data.constructor.name;
+	if (typeof data === "string") return `string(${data.length})`;
+	return typeof data;
+}
+
 /**
  * Shared JS runtime for the eval worker and the browser tab worker. Owns the prelude,
  * helper bag, console bridge, and indirect-eval execution. Emits text/display/tool-call
@@ -109,8 +178,19 @@ export class JsRuntime {
 		if (!hooks) return;
 		if (value && typeof value === "object") {
 			const record = value as Record<string, unknown>;
-			if (record.type === "image" && typeof record.data === "string" && typeof record.mimeType === "string") {
-				hooks.onDisplay({ type: "image", data: record.data, mimeType: record.mimeType });
+			if (record.type === "image" && typeof record.mimeType === "string") {
+				const data = coerceImageBase64(record.data);
+				if (data !== null) {
+					hooks.onDisplay({ type: "image", data, mimeType: record.mimeType });
+					return;
+				}
+				logger.warn("js displayValue: dropping image with unrecognized data shape", {
+					mimeType: record.mimeType,
+					dataType: describeDataType(record.data),
+				});
+				hooks.onText(
+					`[display: image dropped — \`data\` must be a base64 string, Uint8Array/Buffer, or ArrayBuffer; got ${describeDataType(record.data)}]\n`,
+				);
 				return;
 			}
 			try {

package/src/extensibility/typebox.ts

@@ -21,7 +21,7 @@
  * `@sinclair/typebox` directly in their own package.
  */
 
-import { areJsonValuesEqual } from "@oh-my-pi/pi-ai/utils/schema";
+import { areJsonValuesEqual, zodToWireSchema } from "@oh-my-pi/pi-ai/utils/schema";
 import {
 	type ZodArray,
 	type ZodEnum,
@@ -104,19 +104,46 @@ interface ObjectOpts extends Meta {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Stamp a non-enumerable `toJSON()` on a schema so `JSON.stringify(schema)`
+ * yields a clean draft 2020-12 JSON Schema — matching real TypeBox semantics
+ * where the schema object IS already a JSON Schema. Without this, an extension
+ * author who serialises the schema across any JSON boundary (worker
+ * postMessage, MCP transport, config persistence, network hop, structuredClone
+ * fallback) ships the raw Zod internals (`def`, `_zod`, object-shaped `enum`,
+ * `"type":"enum"`) — neither valid JSON Schema nor parseable Zod. See
+ * issue #1101 for the symptoms when this leaks into a tool's `input_schema`.
+ *
+ * Idempotent: re-stamping the same instance is a no-op.
+ */
+function wire<T extends ZodType>(schema: T): T {
+	if (!Object.hasOwn(schema as object, "toJSON")) {
+		Object.defineProperty(schema as object, "toJSON", {
+			value: function toJSON(this: ZodType) {
+				return zodToWireSchema(this);
+			},
+			enumerable: false,
+			writable: true,
+			configurable: true,
+		});
+	}
+	return schema;
+}
+
 function withMeta<T extends ZodType>(schema: T, opts: Meta | undefined): T {
-	if (!opts) return schema;
 	let out: ZodType = schema;
-	if (typeof opts.description === "string") out = out.describe(opts.description);
-	if ("default" in opts) out = out.default(opts.default as never) as unknown as ZodType;
+	if (opts) {
+		if (typeof opts.description === "string") out = out.describe(opts.description);
+		if ("default" in opts) out = out.default(opts.default as never) as unknown as ZodType;
 
-	const metadata: Record<string, unknown> = {};
-	for (const [key, value] of Object.entries(opts)) {
-		if (key === "description" || key === "default" || key === "additionalProperties") continue;
-		metadata[key] = value;
+		const metadata: Record<string, unknown> = {};
+		for (const key in opts) {
+			if (key === "description" || key === "default" || key === "additionalProperties") continue;
+			metadata[key] = opts[key];
+		}
+		if (Object.keys(metadata).length > 0) out = out.meta(metadata);
 	}
-	if (Object.keys(metadata).length > 0) out = out.meta(metadata);
-	return out as T;
+	return wire(out as T);
 }
 
 // ---------------------------------------------------------------------------
@@ -313,7 +340,8 @@ function tRecord<V extends ZodType>(key: ZodType, value: V, opts?: Meta): ZodTyp
 }
 
 function tOptional<E extends ZodType>(schema: E, _opts?: Meta): ZodOptional<E> {
-	return isOptional(schema) ? (schema as unknown as ZodOptional<E>) : (schema.optional() as ZodOptional<E>);
+	if (isOptional(schema)) return wire(schema as unknown as ZodOptional<E>);
+	return wire(schema.optional() as ZodOptional<E>);
 }
 
 function tNullable<E extends ZodType>(schema: E, opts?: Meta): ZodType {
@@ -322,27 +350,26 @@ function tNullable<E extends ZodType>(schema: E, opts?: Meta): ZodType {
 
 function tReadonly<E extends ZodType>(schema: E): E {
 	// TypeBox's `Type.Readonly` is purely a marker; runtime parsing is identical.
-	return schema;
+	return wire(schema);
 }
 
 function tPartial<P extends ZodRawShape>(obj: ZodObject<P>): ZodObject<P> {
-	return obj.partial() as unknown as ZodObject<P>;
+	return wire(obj.partial() as unknown as ZodObject<P>);
 }
 
 function tRequired<P extends ZodRawShape>(obj: ZodObject<P>): ZodObject<P> {
-	return obj.required() as unknown as ZodObject<P>;
+	return wire(obj.required() as unknown as ZodObject<P>);
 }
 
 function tPick<P extends ZodRawShape, K extends keyof P>(obj: ZodObject<P>, keys: readonly K[]): ZodObject<Pick<P, K>> {
 	const mask = Object.fromEntries(keys.map(k => [k as string, true]));
-	return obj.pick(mask as never) as unknown as ZodObject<Pick<P, K>>;
+	return wire(obj.pick(mask as never) as unknown as ZodObject<Pick<P, K>>);
 }
 
 function tOmit<P extends ZodRawShape, K extends keyof P>(obj: ZodObject<P>, keys: readonly K[]): ZodObject<Omit<P, K>> {
 	const mask = Object.fromEntries(keys.map(k => [k as string, true]));
-	return obj.omit(mask as never) as unknown as ZodObject<Omit<P, K>>;
+	return wire(obj.omit(mask as never) as unknown as ZodObject<Omit<P, K>>);
 }
-
 function tComposite(objects: readonly ZodObject<ZodRawShape>[], opts?: Meta): ZodObject<ZodRawShape> {
 	// `Type.Composite([...])` flattens every object schema into one object schema
 	// rather than producing an intersection. Mirror that via repeated `extend`.