@oh-my-pi/pi-coding-agent 17.0.0 → 17.0.1

package/src/internal-urls/agent-protocol.ts

@@ -8,7 +8,11 @@
  *
  * URL forms:
  * - agent://<id> - Full output content
- * - agent://<id>/<path> - JSON extraction via path form
+ * - agent://<id>/<child> - Nested subagent output (hierarchy separator; the
+ *   registry allocates a subagent's own children as dot-qualified ids, so
+ *   `agent://Parent/Child` resolves `Parent.Child.md`)
+ * - agent://<id>/<path> - JSON extraction via path form (fallback when no
+ *   nested output matches the path)
  * - agent://<id>?q=<query> - JSON extraction via query form
  */
 import * as fs from "node:fs/promises";
@@ -44,65 +48,56 @@ export class AgentProtocolHandler implements ProtocolHandler {
 		}
 
 		const dirs = artifactsDirsFromRegistry();
-
 		if (dirs.length === 0) {
 			throw new Error("No session - agent outputs unavailable");
 		}
 
-		let foundPath: string | undefined;
-		let anyDirExists = false;
-		const availableIds = new Set<string>();
-
-		for (const dir of dirs) {
-			try {
-				await fs.stat(dir);
-				anyDirExists = true;
-			} catch (err) {
-				if (isEnoent(err)) continue;
-				throw err;
-			}
-			const candidate = path.join(dir, `${outputId}.md`);
+		// A subagent allocates its own children as dot-qualified ids
+		// (`Parent.Child`), so the slash path form is first tried as a hierarchy
+		// separator: `agent://Parent/Child` resolves `Parent.Child.md`. Only when
+		// no such nested output exists does the path fall back to jq-style JSON
+		// extraction on `<outputId>.md`. Query form (`?q=`) is always extraction.
+		const pathSegments = hasPathExtraction ? urlPath.split("/").filter(Boolean) : [];
+		const decodedSegments = pathSegments.map(segment => {
 			try {
-				await fs.stat(candidate);
-				foundPath = candidate;
-				break;
-			} catch (err) {
-				if (!isEnoent(err)) throw err;
-				try {
-					const files = await fs.readdir(dir);
-					for (const f of files) {
-						if (f.endsWith(".md")) availableIds.add(f.replace(/\.md$/, ""));
-					}
-				} catch {
-					// Listing failures are non-fatal; continue searching.
-				}
+				return decodeURIComponent(segment);
+			} catch {
+				return segment;
 			}
-		}
+		});
+		const nestedId =
+			decodedSegments.length > 0 && decodedSegments.every(segment => !segment.includes("."))
+				? [outputId, ...decodedSegments].join(".")
+				: undefined;
 
-		if (!anyDirExists) {
+		const scan = await this.#findOutput(dirs, nestedId ? [nestedId, outputId] : [outputId]);
+		if (!scan.anyDirExists) {
 			throw new Error("No artifacts directory found");
 		}
-
-		if (!foundPath) {
-			const availableStr = availableIds.size > 0 ? [...availableIds].join(", ") : "none";
-			throw new Error(`Not found: ${outputId}\nAvailable: ${availableStr}`);
+		if (!scan.foundPath) {
+			const target = nestedId ?? outputId;
+			const availableStr = scan.availableIds.size > 0 ? [...scan.availableIds].join(", ") : "none";
+			throw new Error(`Not found: ${target}\nAvailable: ${availableStr}`);
 		}
 
-		const rawContent = await Bun.file(foundPath).text();
+		const rawContent = await Bun.file(scan.foundPath).text();
 		const notes: string[] = [];
 		let content = rawContent;
 		let contentType: InternalResource["contentType"] = "text/markdown";
 
-		if (hasPathExtraction || hasQueryExtraction) {
+		// Extraction applies only when the URL did NOT resolve to a nested output
+		// (a slash that named a real child is a hierarchy hop, not a jq path).
+		const extract = hasQueryExtraction || (hasPathExtraction && scan.matchedId !== nestedId);
+		if (extract) {
 			let jsonValue: unknown;
 			try {
 				jsonValue = JSON.parse(rawContent);
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
-				throw new Error(`Output ${outputId} is not valid JSON: ${message}`);
+				throw new Error(`Output ${scan.matchedId} is not valid JSON: ${message}`);
 			}
 
-			const query = hasPathExtraction ? pathToQuery(urlPath) : queryParam!;
+			const query = hasQueryExtraction ? queryParam! : pathToQuery(urlPath);
 			if (query) {
 				const extracted = applyQuery(jsonValue, query);
 				try {
@@ -122,11 +117,50 @@ export class AgentProtocolHandler implements ProtocolHandler {
 			content,
 			contentType,
 			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: foundPath,
+			sourcePath: scan.foundPath,
 			notes,
 		};
 	}
 
+	/**
+	 * Scan every registered artifacts dir for the first `<id>.md` among
+	 * `candidateIds` (tried in order, so a hierarchy match wins over the base
+	 * id). Returns the resolved path and the id it matched, plus the set of
+	 * available ids gathered from the scanned dirs for the not-found message.
+	 */
+	async #findOutput(
+		dirs: string[],
+		candidateIds: string[],
+	): Promise<{ foundPath?: string; matchedId?: string; anyDirExists: boolean; availableIds: Set<string> }> {
+		// Build a full id→path map across every registered dir before picking, so
+		// candidate priority is global: a nested id in a deeper dir must win over
+		// the base id even when the base id's dir is scanned first.
+		const byId = new Map<string, string>();
+		let anyDirExists = false;
+		for (const dir of dirs) {
+			let files: string[];
+			try {
+				files = await fs.readdir(dir);
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			anyDirExists = true;
+			for (const f of files) {
+				if (!f.endsWith(".md")) continue;
+				const id = f.slice(0, -3);
+				if (!byId.has(id)) byId.set(id, path.join(dir, f));
+			}
+		}
+		for (const id of candidateIds) {
+			const foundPath = byId.get(id);
+			if (foundPath) {
+				return { foundPath, matchedId: id, anyDirExists, availableIds: new Set(byId.keys()) };
+			}
+		}
+		return { anyDirExists, availableIds: new Set(byId.keys()) };
+	}
+
 	async complete(): Promise<UrlCompletion[]> {
 		const ids = new Set<string>();
 		for (const dir of artifactsDirsFromRegistry()) {

package/src/lib/xai-http.ts

@@ -16,7 +16,14 @@ export function ohMyPiXAIUserAgent(): string {
 	return "oh-my-pi/xai";
 }
 
-type XAIProvider = "xai-oauth" | "xai";
+/** xAI provider ids supported by shared HTTP tool transport resolution. */
+export type XAIHttpProvider = "xai-oauth" | "xai";
+
+/** Resolved endpoint and configured headers for an xAI HTTP tool request. */
+export interface XAIHttpTransport {
+	baseURL: string;
+	headers?: Record<string, string>;
+}
 
 /**
  * Resolve the HTTP base URL for an xAI tool call.
@@ -48,7 +55,11 @@ type XAIProvider = "xai-oauth" | "xai";
  * let xai-oauth entries hijack a xai tool call (or vice versa) when the
  * same model id ships under both descriptors.
  */
-function resolveXAIBaseURL(modelRegistry: ModelRegistry, provider: XAIProvider, modelId: string | undefined): string {
+function resolveXAIBaseURL(
+	modelRegistry: ModelRegistry,
+	provider: XAIHttpProvider,
+	modelId: string | undefined,
+): string {
 	if (modelId) {
 		const merged = modelRegistry.getAll().find(m => m.id === modelId && m.provider === provider);
 		if (merged?.baseUrl) {
@@ -68,6 +79,21 @@ function resolveXAIBaseURL(modelRegistry: ModelRegistry, provider: XAIProvider,
 	}
 	return ($env.XAI_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
 }
+/**
+ * Resolve an xAI tool endpoint and its provider/model header overrides.
+ */
+export function resolveXAIHttpTransport(
+	modelRegistry: ModelRegistry,
+	provider: XAIHttpProvider,
+	modelId?: string,
+): XAIHttpTransport {
+	return {
+		baseURL: resolveXAIBaseURL(modelRegistry, provider, modelId),
+		headers:
+			(modelId ? modelRegistry.find(provider, modelId)?.headers : undefined) ??
+			modelRegistry.getProviderHeaders(provider),
+	};
+}
 
 /**
  * Resolve xAI credentials for HTTP tool calls.

package/src/modes/acp/acp-agent.ts

@@ -42,7 +42,7 @@ import {
 } from "@agentclientprotocol/sdk";
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
-import { getBlobsDir, isEnoent, logger, VERSION } from "@oh-my-pi/pi-utils";
+import { getBlobsDir, isEnoent, logger, type postmortem, VERSION } from "@oh-my-pi/pi-utils";
 import { disableProvider, enableProvider, reset as resetCapabilities } from "../../capability";
 import { Settings } from "../../config/settings";
 import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
@@ -1027,7 +1027,7 @@ export class AcpAgent implements Agent {
 		this.#connection.signal.addEventListener(
 			"abort",
 			() => {
-				void this.#disposeAllSessions();
+				void this.dispose();
 			},
 			{ once: true },
 		);
@@ -1912,6 +1912,7 @@ export class AcpAgent implements Agent {
 		const projectPath = await resolveActiveProjectRegistryPath(cwd);
 		clearPluginRootsAndCaches(projectPath ? [projectPath] : undefined);
 		resetCapabilities();
+		await record.session.refreshSkills();
 		const fileCommands = await loadSlashCommands({ cwd });
 		record.session.setSlashCommands(fileCommands);
 		await this.#emitAvailableCommandsUpdate(record);
@@ -2109,6 +2110,23 @@ export class AcpAgent implements Agent {
 					});
 					continue;
 				}
+				if (
+					item.type === "image" &&
+					"data" in item &&
+					typeof item.data === "string" &&
+					"mimeType" in item &&
+					typeof item.mimeType === "string"
+				) {
+					notifications.push({
+						sessionId,
+						update: {
+							sessionUpdate: "agent_message_chunk",
+							content: { type: "image", data: item.data, mimeType: item.mimeType },
+							messageId,
+						},
+					});
+					continue;
+				}
 				if (item.type === "thinking" && "thinking" in item && typeof item.thinking === "string") {
 					const thinking = canonicalizeMessage(item.thinking);
 					if (thinking.length === 0) continue;
@@ -2443,7 +2461,7 @@ export class AcpAgent implements Agent {
 		}
 	}
 
-	async #disposeSessionRecord(record: ManagedSessionRecord): Promise<void> {
+	async #disposeSessionRecord(record: ManagedSessionRecord, reason?: postmortem.Reason): Promise<void> {
 		record.lifetimeUnsubscribe?.();
 		if (record.mcpManager) {
 			try {
@@ -2454,21 +2472,22 @@ export class AcpAgent implements Agent {
 			record.mcpManager = undefined;
 		}
 		try {
-			await record.session.dispose();
+			await record.session.dispose({ reason });
 		} catch (error) {
 			logger.warn("Failed to dispose ACP session", { error });
 		}
 	}
 
-	async #disposeStandaloneSession(session: AgentSession): Promise<void> {
+	async #disposeStandaloneSession(session: AgentSession, reason?: postmortem.Reason): Promise<void> {
 		try {
-			await session.dispose();
+			await session.dispose({ reason });
 		} catch (error) {
 			logger.warn("Failed to dispose ACP session", { error });
 		}
 	}
 
-	async #disposeAllSessions(): Promise<void> {
+	/** Dispose every session owned by this ACP connection and await persisted teardown. */
+	async dispose(reason?: postmortem.Reason): Promise<void> {
 		if (this.#disposePromise) {
 			await this.#disposePromise;
 			return;
@@ -2484,7 +2503,7 @@ export class AcpAgent implements Agent {
 							"ACP agent disposed before queued prompt could run",
 						);
 						await this.#cancelPromptForClose(record);
-						await this.#disposeSessionRecord(record);
+						await this.#disposeSessionRecord(record, reason);
 					} catch (error) {
 						logger.warn("Failed to clean up ACP session", { sessionId, error });
 					}
@@ -2494,7 +2513,7 @@ export class AcpAgent implements Agent {
 			const initialSession = this.#initialSession;
 			this.#initialSession = undefined;
 			if (initialSession) {
-				await this.#disposeStandaloneSession(initialSession);
+				await this.#disposeStandaloneSession(initialSession, reason);
 			}
 		})();
 

package/src/modes/acp/acp-event-mapper.ts

@@ -272,6 +272,14 @@ function mapAssistantMessageUpdate(
 	let text: string;
 	const progress = options.getMessageProgress?.(event.message);
 	switch (event.assistantMessageEvent.type) {
+		case "image_end":
+			return [
+				toSessionNotification(sessionId, {
+					sessionUpdate: "agent_message_chunk",
+					content: event.assistantMessageEvent.content,
+					messageId: options.getMessageId?.(event.message),
+				}),
+			];
 		case "text_delta":
 			sessionUpdate = "agent_message_chunk";
 			text = event.assistantMessageEvent.delta;

package/src/modes/acp/acp-mode.ts

@@ -1,19 +1,28 @@
 import * as stream from "node:stream";
 import { AgentSideConnection, ndJsonStream, type Stream } from "@agentclientprotocol/sdk";
+import { postmortem } from "@oh-my-pi/pi-utils";
 import type { AgentSession } from "../../session/agent-session";
 import { AcpAgent } from "./acp-agent";
 
+/** Creates sessions requested by an ACP client. */
 export type AcpSessionFactory = (cwd: string) => Promise<AgentSession>;
 
+/** Creates an ACP connection and exposes its agent when process-level teardown must own it. */
 export function createAcpConnection(
 	transport: Stream,
 	createSession: AcpSessionFactory,
 	initialSession?: AgentSession,
+	onAgent?: (agent: AcpAgent) => void,
 ): AgentSideConnection {
-	return new AgentSideConnection(conn => new AcpAgent(conn, createSession, initialSession), transport);
+	return new AgentSideConnection(connection => {
+		const agent = new AcpAgent(connection, createSession, initialSession);
+		onAgent?.(agent);
+		return agent;
+	}, transport);
 }
 
-export async function runAcpMode(createSession: AcpSessionFactory, initialSession?: AgentSession): Promise<never> {
+/** Serves ACP over stdio until the peer disconnects, then awaits session teardown before exit. */
+export async function runAcpMode(createSession: AcpSessionFactory, initialSession?: AgentSession): Promise<void> {
 	// Humans who run `omp acp` by hand see a silent process and assume it is
 	// broken (stdout is the JSON-RPC transport, so nothing may be printed
 	// there). When stdin is a TTY no ACP client is attached — say so on stderr
@@ -25,10 +34,15 @@ export async function runAcpMode(createSession: AcpSessionFactory, initialSessio
 				"Waiting for protocol frames on stdin; logs: ~/.omp/logs/\n",
 		);
 	}
+	let agent: AcpAgent | undefined;
+	postmortem.register("acp-session-teardown", reason => agent?.dispose(reason));
+	postmortem.registerStdioDisconnectHandling();
 	const input = stream.Writable.toWeb(process.stdout);
 	const output = stream.Readable.toWeb(process.stdin);
 	const transport = ndJsonStream(input, output);
-	const connection = createAcpConnection(transport, createSession, initialSession);
+	const connection = createAcpConnection(transport, createSession, initialSession, createdAgent => {
+		agent = createdAgent;
+	});
 	await connection.closed;
-	process.exit(0);
+	await postmortem.quit(0);
 }

package/src/modes/components/assistant-message.ts

@@ -173,6 +173,7 @@ export class AssistantMessageComponent extends Container {
 	#lastMessage?: AssistantMessage;
 	#toolImagesByCallId = new Map<string, ImageContent[]>();
 	#convertedKittyImages = new Map<string, ImageContent>();
+	#showImages = true;
 	#kittyConversionsInFlight = new Set<string>();
 	#transcriptBlockFinalized: boolean;
 	/**
@@ -497,6 +498,15 @@ export class AssistantMessageComponent extends Container {
 		}
 	}
 
+	/** Toggle rendering for assistant-native and tool-result images. */
+	setImagesVisible(visible: boolean): void {
+		if (this.#showImages === visible) return;
+		this.#showImages = visible;
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
 	setToolResultImages(toolCallId: string, images: ImageContent[]): void {
 		if (!toolCallId) return;
 		const validImages = images.filter(img => img.type === "image" && img.data && img.mimeType);
@@ -514,19 +524,17 @@ export class AssistantMessageComponent extends Container {
 			this.#toolImagesByCallId.delete(toolCallId);
 		} else {
 			this.#toolImagesByCallId.set(toolCallId, validImages);
-			this.#convertToolImagesForKitty(toolCallId, validImages);
+			this.#convertImagesForKitty(validImages.map((image, index) => ({ image, key: `${toolCallId}:${index}` })));
 		}
 		if (this.#lastMessage) {
 			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
 		}
 	}
 
-	#convertToolImagesForKitty(toolCallId: string, images: ImageContent[]): void {
+	#convertImagesForKitty(entries: Array<{ image: ImageContent; key: string }>): void {
 		if (TERMINAL.imageProtocol !== ImageProtocol.Kitty) return;
-		for (let index = 0; index < images.length; index++) {
-			const image = images[index];
-			if (!image || image.mimeType === "image/png") continue;
-			const key = `${toolCallId}:${index}`;
+		for (const { image, key } of entries) {
+			if (image.mimeType === "image/png") continue;
 			if (this.#convertedKittyImages.has(key) || this.#kittyConversionsInFlight.has(key)) continue;
 			this.#kittyConversionsInFlight.add(key);
 			new Bun.Image(Buffer.from(image.data, "base64"))
@@ -550,14 +558,12 @@ export class AssistantMessageComponent extends Container {
 		}
 	}
 
-	#renderToolImages(): void {
-		const imageEntries = Array.from(this.#toolImagesByCallId.entries()).flatMap(([toolCallId, images]) =>
-			images.map((image, index) => ({ image, key: `${toolCallId}:${index}` })),
-		);
-		if (imageEntries.length === 0) return;
+	#renderImageEntries(entries: Array<{ image: ImageContent; key: string }>, withLeadingSpacer: boolean): void {
+		if (!this.#showImages || entries.length === 0) return;
+		this.#convertImagesForKitty(entries);
 
-		this.#contentContainer.addChild(new Spacer(1));
-		for (const { image, key } of imageEntries) {
+		if (withLeadingSpacer) this.#contentContainer.addChild(new Spacer(1));
+		for (const { image, key } of entries) {
 			const displayImage =
 				TERMINAL.imageProtocol === ImageProtocol.Kitty && image.mimeType !== "image/png"
 					? this.#convertedKittyImages.get(key)
@@ -577,6 +583,13 @@ export class AssistantMessageComponent extends Container {
 		}
 	}
 
+	#renderToolImages(): void {
+		const entries = Array.from(this.#toolImagesByCallId.entries()).flatMap(([toolCallId, images]) =>
+			images.map((image, index) => ({ image, key: `${toolCallId}:${index}` })),
+		);
+		this.#renderImageEntries(entries, true);
+	}
+
 	#appendThinkingExtensions(contentIndex: number, thinkingIndex: number, text: string): void {
 		for (const renderer of this.thinkingRenderers) {
 			try {
@@ -620,7 +633,7 @@ export class AssistantMessageComponent extends Container {
 
 	#canFastPath(message: AssistantMessage): boolean {
 		for (const content of message.content) {
-			if (content.type === "toolCall") return false;
+			if (content.type === "toolCall" || content.type === "image") return false;
 		}
 		if (this.#toolImagesByCallId.size > 0) return false;
 		const errorPresentation = resolveAssistantErrorPresentation(message);
@@ -769,6 +782,7 @@ export class AssistantMessageComponent extends Container {
 		const hasVisibleContent = message.content.some(
 			c =>
 				(c.type === "text" && canonicalizeMessage(c.text)) ||
+				(c.type === "image" && c.data && c.mimeType) ||
 				(!this.hideThinkingBlock &&
 					c.type === "thinking" &&
 					resolveThinkingDisplay(c, this.proseOnlyThinking).visible),
@@ -776,6 +790,7 @@ export class AssistantMessageComponent extends Container {
 
 		// Render content in order
 		let thinkingIndex = 0;
+		let hasRenderedContent = false;
 		for (let i = 0; i < message.content.length; i++) {
 			const content = message.content[i];
 			if (content.type === "text" && canonicalizeMessage(content.text)) {
@@ -785,6 +800,7 @@ export class AssistantMessageComponent extends Container {
 				md.transientRenderCache = this.#lastUpdateTransient;
 				this.#contentContainer.addChild(md);
 				captureItems?.push({ md, contentIndex: i, blockType: "text", lastText: trimmed });
+				hasRenderedContent = true;
 			} else if (content.type === "thinking" && resolveThinkingDisplay(content, this.proseOnlyThinking).visible) {
 				const thinkingText = resolveThinkingDisplay(content, this.proseOnlyThinking).text;
 				if (this.hideThinkingBlock) {
@@ -798,6 +814,7 @@ export class AssistantMessageComponent extends Container {
 					.some(
 						c =>
 							(c.type === "text" && canonicalizeMessage(c.text)) ||
+							(c.type === "image" && c.data && c.mimeType) ||
 							(c.type === "thinking" && resolveThinkingDisplay(c, this.proseOnlyThinking).visible),
 					);
 
@@ -810,10 +827,14 @@ export class AssistantMessageComponent extends Container {
 				this.#contentContainer.addChild(md);
 				captureItems?.push({ md, contentIndex: i, blockType: "thinking", lastText: thinkingText });
 				this.#appendThinkingExtensions(i, thinkingIndex, thinkingText);
+				hasRenderedContent = true;
 				thinkingIndex += 1;
 				if (hasVisibleContentAfter) {
 					this.#contentContainer.addChild(new Spacer(1));
 				}
+			} else if (content.type === "image" && content.data && content.mimeType) {
+				this.#renderImageEntries([{ image: content, key: `native:${i}` }], hasRenderedContent);
+				hasRenderedContent ||= this.#showImages;
 			}
 		}
 

package/src/modes/components/chat-transcript-builder.ts

@@ -283,6 +283,7 @@ export class ChatTranscriptBuilder {
 			this.deps.ui.imageBudget,
 			proseOnlyThinking,
 		);
+		assistantComponent.setImagesVisible(settings.get("terminal.showImages"));
 		this.container.addChild(assistantComponent);
 
 		if (settings.get("display.cacheMissMarker")) {
@@ -313,6 +314,7 @@ export class ChatTranscriptBuilder {
 				undefined,
 				proseOnlyThinking,
 			);
+			component.setImagesVisible(settings.get("terminal.showImages"));
 			this.container.addChild(component);
 		};
 

package/src/modes/components/custom-editor-plugin-ctor.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import { ProcessTerminal, TUI } from "@oh-my-pi/pi-tui";
+import { getEditorTheme, initTheme } from "../theme/theme";
+import { CustomEditor } from "./custom-editor";
+
+/**
+ * Regression for issue #4766: plugins written against upstream pi subclass
+ * `CustomEditor`/`Editor` and forward `super(tui, theme, keybindings)`. omp's
+ * `setEditorComponent` factory contract advertises exactly that arg order, so
+ * the base constructor must resolve the real theme by shape (not position) or
+ * every render throws `undefined is not an object (evaluating
+ * 'this.#theme.symbols.boxRound')`.
+ */
+describe("CustomEditor upstream-pi constructor compatibility (#4766)", () => {
+	it("renders when constructed as (tui, theme, keybindings)", async () => {
+		await initTheme();
+		const tui = new TUI(new ProcessTerminal());
+		const editor = new CustomEditor(tui, getEditorTheme(), {});
+		editor.setText("run this workflow");
+		expect(() => editor.render(80)).not.toThrow();
+		// The rounded border glyphs from the resolved theme must reach the frame.
+		const frame = editor.render(80).join("\n");
+		expect(frame).toContain(getEditorTheme().symbols.boxRound.horizontal);
+		// The leading TUI is captured so plugin overrides calling
+		// `this.tui.requestRender()` keep working.
+		expect(editor.tui).toBe(tui);
+	});
+
+	it("still accepts omp's own (theme) constructor", async () => {
+		await initTheme();
+		const editor = new CustomEditor(getEditorTheme());
+		editor.setText("hello");
+		expect(() => editor.render(80)).not.toThrow();
+		expect(editor.tui).toBeUndefined();
+	});
+});

package/src/modes/components/custom-editor.ts

@@ -1,6 +1,15 @@
 import { fileURLToPath } from "node:url";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
-import { addKeyAliases, canonicalKeyId, Editor, type KeyId, parseKey, parseKittySequence } from "@oh-my-pi/pi-tui";
+import {
+	addKeyAliases,
+	canonicalKeyId,
+	Editor,
+	type EditorTheme,
+	type KeyId,
+	parseKey,
+	parseKittySequence,
+	TUI,
+} from "@oh-my-pi/pi-tui";
 import { BracketedPasteHandler } from "@oh-my-pi/pi-tui/bracketed-paste";
 import type { AppKeybinding } from "../../config/keybindings";
 import { isSettingsInitialized, settings } from "../../config/settings";
@@ -284,6 +293,31 @@ export function extractImagePathFromText(text: string): string | undefined {
 	return undefined;
 }
 
+/**
+ * Resolve the {@link EditorTheme} from a `CustomEditor`/`Editor` constructor
+ * argument list, tolerating both the omp `(theme)` and upstream-pi
+ * `(tui, theme, keybindings)` conventions (see {@link CustomEditor}'s
+ * constructor). A real `EditorTheme` is identified structurally — it exposes a
+ * `borderColor` function and a `symbols` object — so a `TUI` passed in the first
+ * slot is skipped rather than mistaken for the theme.
+ */
+function pickEditorTheme(args: readonly unknown[]): EditorTheme {
+	for (const arg of args) {
+		if (isEditorTheme(arg)) return arg;
+	}
+	// Fall back to the first argument so a caller passing a bare theme that
+	// somehow fails the shape probe still reaches the base constructor.
+	return args[0] as EditorTheme;
+}
+
+function isEditorTheme(value: unknown): value is EditorTheme {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value as Partial<EditorTheme>;
+	return (
+		typeof candidate.borderColor === "function" && typeof candidate.symbols === "object" && candidate.symbols !== null
+	);
+}
+
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
@@ -297,6 +331,33 @@ export class CustomEditor extends Editor {
 	 *  `undefined` entries are images without a backing reference yet. */
 	pendingImageLinks: (string | undefined)[] = [];
 
+	/**
+	 * The host {@link TUI}, captured when a plugin constructs this editor through
+	 * the upstream-pi `(tui, theme, keybindings)` convention. Undefined for omp's
+	 * own `new CustomEditor(theme)` callers (they drive repaints through the
+	 * interactive-mode wiring instead). Plugins that call `this.tui.requestRender()`
+	 * in their overrides read it here (issue #4766).
+	 */
+	tui?: TUI;
+
+	/**
+	 * Accept both the omp constructor convention — `new CustomEditor(theme)` —
+	 * and the upstream-pi `Editor` convention — `new Editor(tui, theme, keybindings)`
+	 * — that {@link ExtensionUIContext.setEditorComponent}'s factory contract
+	 * advertises `(tui, theme, keybindings)`. Plugins written against upstream pi
+	 * subclass `CustomEditor`/`Editor` and forward `super(tui, theme, keybindings)`;
+	 * without this shim the `TUI` lands in the `theme` slot and every render throws
+	 * `undefined is not an object (evaluating 'this.#theme.symbols.boxRound')`
+	 * (issue #4766). We locate the real {@link EditorTheme} among the args by shape
+	 * (it carries `symbols`/`borderColor`) rather than by position, and capture a
+	 * leading {@link TUI} so plugin overrides calling `this.tui.requestRender()`
+	 * keep working.
+	 */
+	constructor(...args: readonly unknown[]) {
+		super(pickEditorTheme(args));
+		if (args[0] instanceof TUI) this.tui = args[0];
+	}
+
 	/** Clear the composer draft: optionally commit `historyText` to history, then
 	 *  reset the editor text and all pending draft-image state. The shared tail of
 	 *  every "message submitted" path; pass no argument for a plain discard. */