@oh-my-pi/pi-coding-agent 15.13.1 → 15.13.2

package/src/config/settings-schema.ts

@@ -1719,6 +1719,48 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"tools.format": {
+		type: "enum",
+		values: [
+			"auto",
+			"native",
+			"glm",
+			"hermes",
+			"kimi",
+			"xml",
+			"anthropic",
+			"deepseek",
+			"harmony",
+			"pi",
+			"qwen3",
+		] as const,
+		default: "auto",
+		ui: {
+			tab: "context",
+			group: "Experimental",
+			label: "Tool Call Format",
+			description:
+				"Controls how tools are exposed to the model. Auto uses native tool calls unless the selected model is marked as not supporting tools, then falls back to GLM-style in-band tool calls. Native forces provider-native tools; the other values force the named in-band syntax. Applies on session start.",
+			options: [
+				{
+					value: "auto",
+					label: "Auto",
+					description: "Use native tool calls unless the model is known not to support them.",
+				},
+				{ value: "native", label: "Native", description: "Use provider-native tool calls." },
+				{ value: "glm", label: "GLM", description: "Use GLM-style in-band tool calls." },
+				{ value: "hermes", label: "Hermes", description: "Use Hermes-style in-band tool calls." },
+				{ value: "kimi", label: "Kimi", description: "Use Kimi-style in-band tool calls." },
+				{ value: "xml", label: "XML", description: "Use generic XML in-band tool calls." },
+				{ value: "anthropic", label: "Anthropic", description: "Use Anthropic-style in-band tool calls." },
+				{ value: "deepseek", label: "DeepSeek", description: "Use DeepSeek-style in-band tool calls." },
+				{ value: "harmony", label: "Harmony", description: "Use Harmony-style in-band tool calls." },
+				{ value: "pi", label: "Pi", description: "Use Pi-style in-band tool calls." },
+				{ value: "qwen3", label: "Qwen3", description: "Use Qwen3-style in-band tool calls." },
+			],
+		},
+	},
+
 	"snapcompact.shape": {
 		type: "enum",
 		values: ["auto", ...SHAPE_VARIANT_NAMES] as const,
@@ -3183,6 +3225,17 @@ export const SETTINGS_SCHEMA = {
 			description: "Ask the agent to describe the intent of each tool call before executing it",
 		},
 	},
+	"tools.abortOnFabricatedResult": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "tools",
+			group: "Execution",
+			label: "Abort On Fabricated Tool Result",
+			description:
+				"With in-band tool calls, stop the model immediately when it starts hallucinating a tool result mid-turn. Disable to let the model finish generating and discard the fabricated continuation instead.",
+		},
+	},
 
 	"tools.maxTimeout": {
 		type: "number",

package/src/edit/hashline/block-resolver.ts

@@ -1,5 +1,5 @@
 /**
- * Tree-sitter-backed {@link BlockResolver} for the hashline `replace block N:`
+ * Tree-sitter-backed {@link BlockResolver} for the hashline block replace
  * operator. Bridges the pure hashline seam to the native `blockRangeAt`
  * primitive in `@oh-my-pi/pi-natives`, which infers the language from the file
  * path and returns the 1-indexed line span of the syntactic block beginning on

package/src/edit/hashline/execute.ts

@@ -98,12 +98,7 @@ interface RenderedSection {
 }
 
 function formatBlockResolution(resolution: BlockResolution): string {
-	const op =
-		resolution.op === "delete"
-			? "delete block"
-			: resolution.op === "insert_after"
-				? "insert after block"
-				: "replace block";
+	const op = resolution.op === "delete" ? "DEL.BLK" : resolution.op === "insert_after" ? "INS.BLK.POST" : "SWAP.BLK";
 	const lines = resolution.end - resolution.start + 1;
 	const span =
 		resolution.start === resolution.end ? `line ${resolution.start}` : `lines ${resolution.start}-${resolution.end}`;

package/src/edit/index.ts

@@ -2,7 +2,9 @@ import { MismatchError as HashlineMismatchError } from "@oh-my-pi/hashline";
 import hashlineGrammar from "@oh-my-pi/hashline/grammar.lark" with { type: "text" };
 import hashlineDescription from "@oh-my-pi/hashline/prompt.md" with { type: "text" };
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
+import type { z } from "zod/v4";
 import {
 	createLspWritethrough,
 	type FileDiagnosticsResult,
@@ -50,6 +52,7 @@ type EditParams = ReplaceParams | PatchParams | HashlineParams | ApplyPatchParam
 type EditModeDefinition = {
 	description: (session: ToolSession) => string;
 	parameters: TInput;
+	examples?: readonly ToolExample[];
 	execute: (
 		tool: EditTool,
 		params: EditParams,
@@ -356,6 +359,10 @@ export class EditTool implements AgentTool<TInput> {
 		return this.#getModeDefinition().parameters;
 	}
 
+	get examples(): readonly ToolExample[] | undefined {
+		return this.#getModeDefinition().examples;
+	}
+
 	/**
 	 * When in `apply_patch` mode, expose the Codex Lark grammar so providers
 	 * that support OpenAI-style custom tools can emit a grammar-constrained
@@ -404,6 +411,39 @@ export class EditTool implements AgentTool<TInput> {
 			patch: {
 				description: () => prompt.render(patchDescription),
 				parameters: patchEditSchema,
+				examples: [
+					{
+						caption: "Create",
+						call: { path: "hello.txt", edits: [{ op: "create", diff: "Hello\n" }] },
+					},
+					{
+						caption: "Update",
+						call: {
+							path: "src/app.py",
+							edits: [
+								{
+									op: "update",
+									diff: "@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n",
+								},
+							],
+						},
+					},
+					{
+						caption: "Rename",
+						call: {
+							path: "src/app.py",
+							edits: [{ op: "update", rename: "src/main.py", diff: "@@\n …\n" }],
+						},
+					},
+					{
+						caption: "Delete",
+						call: { path: "obsolete.txt", edits: [{ op: "delete" }] },
+					},
+					{
+						caption: "Multiple entries",
+						note: "All entries in one call apply to the top-level `path`; use separate calls for different files.",
+					},
+				] satisfies readonly ToolExample<z.input<typeof patchEditSchema>>[],
 				execute: (
 					tool: EditTool,
 					params: EditParams,
@@ -432,6 +472,14 @@ export class EditTool implements AgentTool<TInput> {
 			apply_patch: {
 				description: () => prompt.render(applyPatchDescription),
 				parameters: applyPatchSchema,
+				examples: [
+					{
+						caption: "Apply a combined patch file",
+						call: {
+							input: '*** Begin Patch\n*** Add File: hello.txt\n+Hello world\n*** Update File: src/app.py\n*** Move to: src/main.py\n@@ def greet():\n-print("Hi")\n+print("Hello, world!")\n*** Delete File: obsolete.txt\n*** End Patch\n',
+						},
+					},
+				] satisfies readonly ToolExample<z.input<typeof applyPatchSchema>>[],
 				execute: (
 					tool: EditTool,
 					params: EditParams,

package/src/eval/__tests__/js-context-manager.test.ts

@@ -15,6 +15,7 @@ interface FakeWorkerStats {
 interface FakeWorkerBehavior {
 	exitOnClose: boolean;
 	settleRuns: boolean;
+	errorOnStart?: boolean;
 }
 
 function makeSession(cwd: string): ToolSession {
@@ -70,6 +71,7 @@ async function waitForRealWorkerExitAfterClose(cwd: string): Promise<void> {
 	worker.addEventListener("close", () => workerClosed.resolve());
 
 	try {
+		worker.postMessage({ type: "init", snapshot });
 		await withTimeout(ready.promise, 1_000, "worker ready");
 		worker.postMessage({
 			type: "run",
@@ -91,6 +93,7 @@ function installFakeWorker(stats: FakeWorkerStats, behavior: FakeWorkerBehavior)
 	class FakeWorker {
 		#messageListeners = new Set<(event: MessageEvent) => void>();
 		#closeListeners = new Set<(event: Event) => void>();
+		#errorListeners = new Set<(event: Event) => void>();
 		#readyQueued = false;
 		#exited = false;
 
@@ -115,11 +118,18 @@ function installFakeWorker(stats: FakeWorkerStats, behavior: FakeWorkerBehavior)
 				this.#closeListeners.add(listener as (event: Event) => void);
 				return;
 			}
+			if (type === "error") {
+				this.#errorListeners.add(listener as (event: Event) => void);
+				return;
+			}
 			if (type !== "message") return;
 			this.#messageListeners.add(listener as (event: MessageEvent) => void);
 			if (!this.#readyQueued) {
 				this.#readyQueued = true;
-				queueMicrotask(() => this.#emitMessage({ type: "ready" }));
+				queueMicrotask(() => {
+					if (behavior.errorOnStart) this.#emitError();
+					else this.#emitMessage({ type: "ready" });
+				});
 			}
 		}
 
@@ -128,6 +138,10 @@ function installFakeWorker(stats: FakeWorkerStats, behavior: FakeWorkerBehavior)
 				this.#closeListeners.delete(listener as (event: Event) => void);
 				return;
 			}
+			if (type === "error") {
+				this.#errorListeners.delete(listener as (event: Event) => void);
+				return;
+			}
 			if (type !== "message") return;
 			this.#messageListeners.delete(listener as (event: MessageEvent) => void);
 		}
@@ -148,6 +162,14 @@ function installFakeWorker(stats: FakeWorkerStats, behavior: FakeWorkerBehavior)
 			const event = new Event("close");
 			for (const listener of this.#closeListeners) listener(event);
 		}
+
+		#emitError(): void {
+			const event = new ErrorEvent("error", {
+				message: "fake worker failed to start",
+				error: new Error("fake worker failed to start"),
+			});
+			for (const listener of this.#errorListeners) listener(event);
+		}
 	}
 
 	Object.defineProperty(globalThis, "Worker", {
@@ -238,4 +260,22 @@ describe("JavaScript eval worker lifecycle", () => {
 		expect(stats.closeRequests).toBe(0);
 		expect(stats.terminateCalls).toBe(1);
 	});
+
+	it("falls back to the inline worker when the spawned worker errors during startup", async () => {
+		using tempDir = TempDir.createSync("@omp-js-worker-error-");
+		const stats: FakeWorkerStats = { closeRequests: 0, terminateCalls: 0 };
+		installFakeWorker(stats, { exitOnClose: true, settleRuns: true, errorOnStart: true });
+
+		const session = makeSession(tempDir.path());
+		const sessionId = `js-worker-error:${crypto.randomUUID()}`;
+
+		// The spawned worker emits an `error` event instead of `ready`. Without fail-fast
+		// error handling the handshake would stall until WORKER_INIT_TIMEOUT_MS (15s); with
+		// it, the handshake rejects at once and the inline worker runs the cell.
+		const result = await executeJs("return String(6 * 7);", { cwd: tempDir.path(), sessionId, session });
+		expect(result.exitCode).toBe(0);
+		expect(result.output.trim()).toBe("42");
+		// The errored primary worker is torn down before the inline retry takes over.
+		expect(stats.terminateCalls).toBe(1);
+	});
 });

package/src/eval/js/context-manager.ts

@@ -27,6 +27,7 @@ interface WorkerHandle {
 	mode: "worker" | "inline";
 	send(msg: WorkerInbound): void;
 	onMessage(handler: (msg: WorkerOutbound) => void): () => void;
+	onError(handler: (error: Error) => void): () => void;
 	close(): Promise<boolean>;
 	terminate(): Promise<void>;
 }
@@ -186,41 +187,45 @@ async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, tim
 	if (starting) return await starting;
 
 	const startup = (async (): Promise<JsSession> => {
-		const worker = await spawnJsWorker();
+		// The message listener must be attached synchronously after `new Worker`:
+		// Bun drops messages posted before a listener exists, and WorkerCore emits
+		// `ready` from its constructor on load. `spawnJsWorker` + `initWorker` run with
+		// no intervening await, so `ready` can never race the attach.
+		const worker = spawnJsWorker();
 		const session: JsSession = {
 			sessionKey,
 			worker,
 			state: "alive",
 			pending: new Map(),
 		};
-		const { promise: readyPromise, resolve: resolveReady, reject: rejectReady } = Promise.withResolvers<void>();
-		let resolved = false;
-		const unsubscribe = worker.onMessage(msg => {
-			if (!resolved && msg.type === "ready") {
-				resolved = true;
-				resolveReady();
-				return;
-			}
-			if (!resolved && msg.type === "init-failed") {
-				resolved = true;
-				rejectReady(errorFromPayload(msg.error));
-				return;
-			}
-			handleSessionMessage(session, msg);
-		});
+		// Init headroom is the fixed infrastructure floor; the caller's per-cell timeout
+		// dominates when larger so users can grant more by raising `timeout` on a cell.
+		const readyTimeoutMs = Math.max(WORKER_INIT_TIMEOUT_MS, timeoutMs ?? 0);
 		try {
-			// Init headroom is the fixed infrastructure floor; the caller's per-cell timeout
-			// dominates when larger so users can grant more by raising `timeout` on a cell.
-			const readyTimeoutMs = Math.max(WORKER_INIT_TIMEOUT_MS, timeoutMs ?? 0);
-			await raceWithTimeout(readyPromise, readyTimeoutMs, "Timed out initializing JS eval worker");
-			worker.send({ type: "init", snapshot });
-			sessions.set(sessionKey, session);
-			return session;
+			await initWorker(session, snapshot, readyTimeoutMs);
 		} catch (error) {
-			unsubscribe();
+			// Worker-thread crash/load failures surface asynchronously via the worker
+			// `error` event — after `spawnJsWorker`'s synchronous try/catch already
+			// returned — so the only signal is the rejected handshake. Retry on the
+			// inline worker so a broken module graph fails fast instead of stalling
+			// every cell on the init timeout and then dying with exitCode 1.
 			await worker.terminate().catch(() => undefined);
-			throw error;
+			if (worker.mode === "inline") throw error;
+			logger.warn("JS eval worker init failed; retrying with inline worker (no sync-loop guard)", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			const inline = spawnInlineWorker();
+			session.worker = inline;
+			session.state = "alive";
+			try {
+				await initWorker(session, snapshot, readyTimeoutMs);
+			} catch (inlineError) {
+				await inline.terminate().catch(() => undefined);
+				throw inlineError;
+			}
 		}
+		sessions.set(sessionKey, session);
+		return session;
 	})();
 	startingSessions.set(sessionKey, startup);
 	try {
@@ -230,6 +235,49 @@ async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, tim
 	}
 }
 
+async function initWorker(session: JsSession, snapshot: SessionSnapshot, timeoutMs: number): Promise<void> {
+	const worker = session.worker;
+	const { promise: readyPromise, resolve: resolveReady, reject: rejectReady } = Promise.withResolvers<void>();
+	let resolved = false;
+	const unsubscribeMessage = worker.onMessage(msg => {
+		if (!resolved && msg.type === "ready") {
+			resolved = true;
+			resolveReady();
+			return;
+		}
+		if (!resolved && msg.type === "init-failed") {
+			resolved = true;
+			rejectReady(errorFromPayload(msg.error));
+			return;
+		}
+		handleSessionMessage(session, msg);
+	});
+	const unsubscribeError = worker.onError(error => {
+		if (!resolved) {
+			resolved = true;
+			rejectReady(error);
+			return;
+		}
+		// Worker died after a successful handshake: tear the session down so the
+		// in-flight run (and the next acquire) fail fast instead of hanging on a
+		// worker that will never reply.
+		void killSessionFor(session, error, { force: true });
+	});
+	try {
+		// Attach listeners and send init before awaiting ready. The worker now
+		// emits ready only in response to init, so this ordering is race-free.
+		worker.send({ type: "init", snapshot });
+		await raceWithTimeout(readyPromise, timeoutMs, "Timed out initializing JS eval worker");
+	} catch (error) {
+		// Handshake failed (timeout, init-failed, or worker error): drop both listeners
+		// so the abandoned worker can't keep routing messages into a session the caller
+		// is about to discard or retry on the inline fallback.
+		unsubscribeMessage();
+		unsubscribeError();
+		throw error;
+	}
+}
+
 function handleSessionMessage(session: JsSession, msg: WorkerOutbound): void {
 	switch (msg.type) {
 		case "text": {
@@ -379,7 +427,7 @@ async function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number, reason
 	}
 }
 
-async function spawnJsWorker(): Promise<WorkerHandle> {
+function spawnJsWorker(): WorkerHandle {
 	try {
 		const hostEntry = workerHostEntry();
 		const worker = hostEntry
@@ -405,6 +453,17 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 			worker.addEventListener("message", wrap);
 			return () => worker.removeEventListener("message", wrap);
 		},
+		onError(handler) {
+			const onError = (event: ErrorEvent): void => handler(errorFromWorkerEvent(event));
+			const onMessageError = (event: MessageEvent): void =>
+				handler(new ToolError(`JS eval worker message error: ${String(event.data)}`));
+			worker.addEventListener("error", onError);
+			worker.addEventListener("messageerror", onMessageError);
+			return () => {
+				worker.removeEventListener("error", onError);
+				worker.removeEventListener("messageerror", onMessageError);
+			};
+		},
 		async close() {
 			const { promise: closed, resolve } = Promise.withResolvers<boolean>();
 			let settled = false;
@@ -443,6 +502,12 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 	};
 }
 
+function errorFromWorkerEvent(event: ErrorEvent): Error {
+	if (event.error instanceof Error) return event.error;
+	if (event.message) return new Error(event.message);
+	return new Error("Unknown JS eval worker error");
+}
+
 /**
  * Inline fallback for environments where Bun cannot spawn the worker entry
  * (e.g. some test runners). Preserves behavior but cannot interrupt synchronous
@@ -473,6 +538,7 @@ function spawnInlineWorker(): WorkerHandle {
 			hostListeners.add(handler);
 			return () => hostListeners.delete(handler);
 		},
+		onError: () => () => {},
 		async close() {
 			const { promise: closed, resolve } = Promise.withResolvers<boolean>();
 			let settled = false;

package/src/eval/js/worker-core.ts

@@ -43,13 +43,13 @@ export class WorkerCore {
 	constructor(transport: Transport) {
 		this.#transport = transport;
 		this.#unsubscribe = transport.onMessage(msg => this.#handle(msg));
-		transport.send({ type: "ready" });
 	}
 
 	#handle(msg: WorkerInbound): void {
 		switch (msg.type) {
 			case "init":
 				this.#ensureRuntime(msg.snapshot);
+				this.#transport.send({ type: "ready" });
 				return;
 			case "run":
 				void this.#runOne(msg.runId, msg.code, msg.filename, msg.snapshot);