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

package/src/session/unexpected-stop-classifier.ts

@@ -0,0 +1,129 @@
+import { type AssistantMessage, completeSimple } from "@oh-my-pi/pi-ai";
+import { logger, prompt } from "@oh-my-pi/pi-utils";
+
+import type { ModelRegistry } from "../config/model-registry";
+import { resolveRoleSelection } from "../config/model-resolver";
+import type { Settings } from "../config/settings";
+import unexpectedStopClassifierPrompt from "../prompts/system/unexpected-stop-classifier.md" with { type: "text" };
+import { isTinyMemoryLocalModelKey, ONLINE_MEMORY_MODEL_KEY } from "../tiny/models";
+import { tinyModelClient } from "../tiny/title-client";
+
+const CLASSIFIER_SYSTEM_PROMPT = prompt.render(unexpectedStopClassifierPrompt);
+
+/**
+ * The answer is a single word. OpenAI-compatible endpoints reject values below
+ * 16, so 16 is the smallest portable budget for this classifier.
+ */
+const ANSWER_MAX_TOKENS = 16;
+/**
+ * Reasoning backends ignore `disableReasoning` on some providers, so reserve
+ * enough output room for the keyword to still land after unavoidable thinking.
+ */
+const REASONING_SAFE_MAX_TOKENS = 1024;
+
+export interface ClassifyUnexpectedStopDeps {
+	settings: Settings;
+	registry: ModelRegistry;
+	sessionId: string;
+	metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+	signal?: AbortSignal;
+}
+
+export function isUnexpectedStopCandidate(message: AssistantMessage): boolean {
+	if (message.stopReason !== "stop") return false;
+	let hasText = false;
+	for (const content of message.content) {
+		if (content.type === "toolCall") return false;
+		if (content.type === "text" && /\S/.test(content.text)) {
+			hasText = true;
+		}
+	}
+	return hasText;
+}
+
+export async function classifyUnexpectedStop(
+	text: string,
+	deps: ClassifyUnexpectedStopDeps,
+): Promise<boolean | undefined> {
+	const backend = deps.settings.get("providers.unexpectedStopModel");
+	try {
+		if (backend === ONLINE_MEMORY_MODEL_KEY) {
+			return await classifyOnline(text, deps);
+		}
+		if (isTinyMemoryLocalModelKey(backend)) {
+			return await classifyLocal(text, backend, deps);
+		}
+		return undefined;
+	} catch (error) {
+		logger.debug("unexpected-stop: classification failed", {
+			error: error instanceof Error ? error.message : String(error),
+			backend,
+		});
+		return undefined;
+	}
+}
+
+async function classifyOnline(text: string, deps: ClassifyUnexpectedStopDeps): Promise<boolean | undefined> {
+	const resolved = resolveRoleSelection(["smol"], deps.settings, deps.registry.getAvailable(), deps.registry);
+	const model = resolved?.model;
+	if (!model) {
+		throw new Error("unexpected-stop: no smol model available for classification");
+	}
+	const apiKey = await deps.registry.getApiKey(model, deps.sessionId);
+	if (!apiKey) {
+		throw new Error(`unexpected-stop: no API key for ${model.provider}/${model.id}`);
+	}
+	const metadata = deps.metadataResolver?.(model.provider);
+	const maxTokens = model.reasoning ? Math.max(ANSWER_MAX_TOKENS, REASONING_SAFE_MAX_TOKENS) : ANSWER_MAX_TOKENS;
+
+	const response = await completeSimple(
+		model,
+		{
+			systemPrompt: [CLASSIFIER_SYSTEM_PROMPT],
+			messages: [{ role: "user", content: text, timestamp: Date.now() }],
+		},
+		{
+			apiKey: deps.registry.resolver(model, deps.sessionId),
+			maxTokens,
+			disableReasoning: true,
+			metadata,
+			signal: deps.signal,
+		},
+	);
+
+	if (response.stopReason === "error") {
+		throw new Error(`unexpected-stop: online classification failed: ${response.errorMessage ?? "unknown error"}`);
+	}
+
+	const outputText = response.content
+		.filter((part): part is { type: "text"; text: string } => part.type === "text")
+		.map(part => part.text)
+		.join("\n");
+	return parseUnexpectedStopClassification(outputText);
+}
+
+async function classifyLocal(
+	text: string,
+	modelKey: string,
+	deps: ClassifyUnexpectedStopDeps,
+): Promise<boolean | undefined> {
+	if (!isTinyMemoryLocalModelKey(modelKey)) {
+		throw new Error(`unexpected-stop: unsupported local classifier model: ${modelKey}`);
+	}
+	const builtPrompt = prompt.render(unexpectedStopClassifierPrompt, { message: text });
+	const output = await tinyModelClient.complete(modelKey, builtPrompt, {
+		maxTokens: ANSWER_MAX_TOKENS,
+		signal: deps.signal,
+	});
+	if (!output) {
+		return undefined;
+	}
+	return parseUnexpectedStopClassification(output);
+}
+
+export function parseUnexpectedStopClassification(text: string): boolean | undefined {
+	const trimmed = text.trim().toLowerCase();
+	if (trimmed.startsWith("yes")) return true;
+	if (trimmed.startsWith("no")) return false;
+	return undefined;
+}

package/src/stt/asr-client.ts

@@ -72,7 +72,7 @@ const SMOKE_TEST_TIMEOUT_MS = 30_000;
  * Hidden subcommand on the main CLI that boots the speech-recognition worker in
  * the spawned subprocess. Kept in sync with the dispatch in `cli.ts`.
  */
-export const STT_WORKER_ARG = "__omp_stt_worker";
+export const STT_WORKER_ARG = "__omp_worker_stt";
 
 function readTinyModelSetting(key: "providers.tinyModelDevice" | "providers.tinyModelDtype"): string | undefined {
 	try {

package/src/system-prompt.ts

@@ -4,6 +4,8 @@
 
 import * as os from "node:os";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample, TSchema } from "@oh-my-pi/pi-ai";
+import { renderToolInventory } from "@oh-my-pi/pi-ai/grammar";
 import { $env, getGpuCachePath, getProjectDir, hasFsCode, isEnoent, logger, prompt } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";
@@ -330,6 +332,10 @@ export interface SystemPromptToolMetadata {
 	description: string;
 	/** Tool name the model sees on the provider wire. Defaults to the internal tool name. */
 	wireName?: string;
+	/** Tool parameters schema (Zod or JSON Schema), fed to the verbose inventory renderer. */
+	parameters?: TSchema;
+	/** Illustrative examples rendered into the verbose inventory. */
+	examples?: readonly ToolExample[];
 }
 
 export function buildSystemPromptToolMetadata(
@@ -349,6 +355,8 @@ export function buildSystemPromptToolMetadata(
 					label: override?.label ?? (typeof toolRecord.label === "string" ? toolRecord.label : ""),
 					description:
 						override?.description ?? (typeof toolRecord.description === "string" ? toolRecord.description : ""),
+					parameters: toolRecord.parameters,
+					examples: toolRecord.examples,
 					wireName,
 				},
 			] as const;
@@ -367,6 +375,12 @@ export interface BuildSystemPromptOptions {
 	appendSystemPrompt?: string;
 	/** Repeat full tool descriptions in system prompt. Default: false */
 	repeatToolDescriptions?: boolean;
+	/**
+	 * Whether provider-native tool calling is active (no owned/in-band syntax).
+	 * When true and `repeatToolDescriptions` is false, the inventory renders as a
+	 * compact tool-name list; otherwise it renders full `# Tool:` sections. Default: true
+	 */
+	nativeTools?: boolean;
 	/** Skills settings for discovery. */
 	skillsSettings?: SkillsSettings;
 	/** Working directory. Default: getProjectDir() */
@@ -420,6 +434,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		tools,
 		appendSystemPrompt,
 		repeatToolDescriptions = false,
+		nativeTools = true,
 		skillsSettings,
 		toolNames: providedToolNames,
 		cwd,
@@ -575,6 +590,20 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		label: tools?.get(name)?.label ?? "",
 		description: tools?.get(name)?.description ?? "",
 	}));
+	const inventoryTools = toolNames.map(name => {
+		const meta = tools?.get(name);
+		return {
+			name: toolPromptNames.get(name) ?? name,
+			description: meta?.description ?? "",
+			parameters: meta?.parameters ?? ({ type: "object" } as TSchema),
+			examples: meta?.examples,
+		};
+	});
+	// List mode shows a compact tool-name list; it only applies when descriptions
+	// are not repeated AND native tool calling is active (the model already has the
+	// schemas). Otherwise render full `# Tool:` sections.
+	const toolListMode = !repeatToolDescriptions && nativeTools;
+	const toolInventory = toolListMode ? "" : renderToolInventory(inventoryTools, model ?? "");
 
 	// Filter skills for the rendered system prompt:
 	// - require the `read` tool so the model can actually fetch skill content;
@@ -596,7 +625,9 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		appendPrompt: resolvedAppendPrompt ?? "",
 		tools: toolNames,
 		toolInfo,
+		toolInventory,
 		repeatToolDescriptions,
+		toolListMode,
 		toolRefs,
 		environment,
 		contextFiles,

package/src/tiny/title-client.ts

@@ -69,7 +69,7 @@ function normalizeTinyTitleGenerateOptions(
  * Hidden subcommand on the main CLI that boots the tiny-model worker in the
  * spawned subprocess. Kept in sync with the dispatch in `cli.ts`.
  */
-export const TINY_WORKER_ARG = "--tiny-worker";
+export const TINY_WORKER_ARG = "__omp_worker_tiny_inference";
 
 function readTinyModelSetting(path: "providers.tinyModelDevice" | "providers.tinyModelDtype"): string | undefined {
 	try {

package/src/tools/ask.ts

@@ -16,6 +16,7 @@
  */
 
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import { type Component, Markdown, type MarkdownTheme, renderInlineMarkdown, TERMINAL, Text } from "@oh-my-pi/pi-tui";
 import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
@@ -422,6 +423,46 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 	readonly description: string;
 	readonly parameters = askSchema;
 	readonly strict = true;
+
+	readonly examples: readonly ToolExample<z.input<typeof askSchema>>[] = [
+		{
+			caption: "Single question",
+			call: {
+				questions: [
+					{
+						id: "auth_method",
+						question: "Which authentication method should this API use?",
+						options: [
+							{ label: "JWT", description: "Bearer tokens for stateless API clients." },
+							{ label: "OAuth2", description: "Delegated authorization with external identity providers." },
+							{
+								label: "Session cookies",
+								description: "Browser-first authentication backed by server-side sessions.",
+							},
+						],
+						recommended: 0,
+					},
+				],
+			},
+		},
+		{
+			caption: "Multiple questions",
+			call: {
+				questions: [
+					{
+						id: "storage_type",
+						question: "Which storage backend?",
+						options: [{ label: "SQLite" }, { label: "PostgreSQL" }],
+					},
+					{
+						id: "auth_method",
+						question: "Which auth method?",
+						options: [{ label: "JWT" }, { label: "Session cookies" }],
+					},
+				],
+			},
+		},
+	];
 	// Run alone in its tool batch. The interactive selector/editor is a single
 	// shared UI surface (`ExtensionUiController.showHookSelector` has no queue and
 	// overwrites `ctx.hookSelector` on each call), so two concurrent `ask` calls

package/src/tools/ast-edit.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import { formatHashlineHeader } from "@oh-my-pi/hashline";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import { type AstReplaceChange, type AstReplaceFileChange, astEdit } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { replaceTabs, Text } from "@oh-my-pi/pi-tui";
@@ -194,6 +195,51 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 	readonly description: string;
 	readonly parameters = astEditSchema;
 	readonly strict = true;
+
+	readonly examples: readonly ToolExample<z.input<typeof astEditSchema>>[] = [
+		{
+			caption: "Rename a call site across TypeScript files",
+			call: {
+				ops: [{ pat: "oldApi($$$ARGS)", out: "newApi($$$ARGS)" }],
+				paths: ["src/**/*.ts"],
+			},
+		},
+		{
+			caption: "Delete matching calls",
+			call: {
+				ops: [{ pat: "console.log($$$ARGS)", out: "" }],
+				paths: ["src/**/*.ts"],
+			},
+		},
+		{
+			caption: "Rewrite import source path",
+			call: {
+				ops: [{ pat: 'import { $$$IMPORTS } from "old-package"', out: 'import { $$$IMPORTS } from "new-package"' }],
+				paths: ["src/**/*.ts"],
+			},
+		},
+		{
+			caption: "Modernize to optional chaining (same metavariable enforces identity)",
+			call: {
+				ops: [{ pat: "$A && $A()", out: "$A?.()" }],
+				paths: ["src/**/*.ts"],
+			},
+		},
+		{
+			caption: "Swap two arguments using captures",
+			call: {
+				ops: [{ pat: "assertEqual($A, $B)", out: "assertEqual($B, $A)" }],
+				paths: ["tests/**/*.ts"],
+			},
+		},
+		{
+			caption: "Python — convert print calls to logging",
+			call: {
+				ops: [{ pat: "print($$$ARGS)", out: "logger.info($$$ARGS)" }],
+				paths: ["src/**/*.py"],
+			},
+		},
+	];
 	readonly deferrable = true;
 	readonly loadMode = "discoverable";
 	constructor(private readonly session: ToolSession) {

package/src/tools/ast-grep.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import { formatHashlineHeader } from "@oh-my-pi/hashline";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import { type AstFindMatch, astGrep } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
@@ -130,6 +131,29 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 	readonly description: string;
 	readonly parameters = astGrepSchema;
 	readonly strict = true;
+
+	readonly examples: readonly ToolExample<z.input<typeof astGrepSchema>>[] = [
+		{
+			caption: "Search TypeScript files under src",
+			call: { pat: "console.log($$$)", paths: ["src/**/*.ts"] },
+		},
+		{
+			caption: "Named imports from a specific package",
+			call: { pat: 'import { $$$IMPORTS } from "react"', paths: ["src/**/*.ts"] },
+		},
+		{
+			caption: "Arrow functions assigned to a const",
+			call: { pat: "const $NAME = ($$$ARGS) => $BODY", paths: ["src/utils/**/*.ts"] },
+		},
+		{
+			caption: "Method call on any object, ignoring method name with `$_`",
+			call: { pat: "logger.$_($$$ARGS)", paths: ["src/**/*.ts"] },
+		},
+		{
+			caption: "Loosest existence check for a symbol in one file",
+			call: { pat: "processItems", paths: ["src/worker.ts"] },
+		},
+	];
 	readonly loadMode = "discoverable";
 
 	constructor(private readonly session: ToolSession) {

package/src/tools/browser/tab-supervisor.ts

@@ -685,7 +685,7 @@ async function spawnTabWorker(): Promise<WorkerHandle> {
 	try {
 		const hostEntry = workerHostEntry();
 		const worker = hostEntry
-			? new Worker(hostEntry, { type: "module", argv: ["__omp_tab_worker"] })
+			? new Worker(hostEntry, { type: "module", argv: ["__omp_worker_tab"] })
 			: new Worker(new URL("./tab-worker-entry.ts", import.meta.url).href, { type: "module" });
 		return wrapBunWorker(worker);
 	} catch (err) {

package/src/tools/browser/tab-worker-entry.ts

@@ -1,20 +1,28 @@
 import { parentPort } from "node:worker_threads";
+import { consumeWorkerInbox } from "@oh-my-pi/pi-utils/worker-host";
 import type { Transport, WorkerInbound, WorkerOutbound } from "./tab-protocol";
 import { WorkerCore } from "./tab-worker";
 
 if (!parentPort) throw new Error("tab-worker-entry: missing parentPort");
 
+const port = parentPort;
+// When the CLI host pre-buffered messages (it imports this module dynamically),
+// bind that inbox so the parent's already-delivered `init` is replayed. Loaded
+// directly (test/SDK fallback), this module's top-level runs synchronously at
+// worker start, so the direct `parentPort.on` below wins the flush on its own.
+const inbox = consumeWorkerInbox();
 const transport: Transport = {
 	send(msg, transferList) {
-		parentPort!.postMessage(msg, transferList ?? []);
+		port.postMessage(msg, transferList ?? []);
 	},
 	onMessage(handler) {
+		if (inbox) return inbox.bind(data => handler(data as WorkerOutbound | WorkerInbound));
 		const wrap = (message: unknown): void => handler(message as WorkerOutbound | WorkerInbound);
-		parentPort!.on("message", wrap);
-		return () => parentPort!.off("message", wrap);
+		port.on("message", wrap);
+		return () => port.off("message", wrap);
 	},
 	close() {
-		parentPort!.close();
+		port.close();
 	},
 };
 

package/src/tools/browser.ts

@@ -1,4 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
 import browserDescription from "../prompts/tools/browser.md" with { type: "text" };
@@ -118,6 +119,57 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 	readonly parameters = browserSchema;
 	readonly strict = true;
 
+	readonly examples: readonly ToolExample<z.input<typeof browserSchema>>[] = [
+		{
+			caption: "Open a tab",
+			call: { action: "open", name: "docs", url: "https://example.com" },
+		},
+		{
+			caption: "Read structured page data in the opened tab",
+			call: {
+				action: "run",
+				name: "docs",
+				code: "const obs = await tab.observe(); display(obs); return obs.elements.length;",
+			},
+		},
+		{
+			caption: "Click an observed element by id",
+			call: {
+				action: "run",
+				name: "docs",
+				code: "const obs = await tab.observe(); const link = obs.elements.find(e => e.role === 'link' && e.name === 'Sign in'); assert(link, 'Sign in link missing'); await (await tab.id(link.id)).click();",
+			},
+		},
+		{
+			caption: "Fill and submit a form via selectors",
+			call: {
+				action: "run",
+				name: "docs",
+				code: "await tab.fill('input[name=email]', 'me@example.com'); await tab.click('text/Continue');",
+			},
+		},
+		{
+			caption: "Screenshot to look at the page — no save path",
+			call: {
+				action: "run",
+				name: "docs",
+				code: "await tab.screenshot();",
+			},
+		},
+		{
+			caption: "Attach to an existing Electron app",
+			call: {
+				action: "open",
+				name: "cursor",
+				app: { path: "/Applications/Cursor.app/Contents/MacOS/Cursor" },
+			},
+		},
+		{
+			caption: "Close every tab and kill spawned-app processes",
+			call: { action: "close", all: true, kill: true },
+		},
+	];
+
 	constructor(private readonly session: ToolSession) {}
 	#description?: string;
 	get description(): string {

package/src/tools/debug.ts

@@ -7,6 +7,7 @@ import type {
 	RenderResultOptions,
 	ToolApprovalDecision,
 } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { isEnoent, prompt } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
@@ -659,6 +660,22 @@ export class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails
 	readonly description: string;
 	readonly parameters = debugSchema;
 	readonly strict = true;
+
+	readonly examples: readonly ToolExample<z.input<typeof debugSchema>>[] = [
+		{
+			caption: "Launch and inspect hang",
+			note: '1. debug(action: "launch", program: "./my_app")\n2. debug(action: "set_breakpoint", file: "src/main.c", line: 42)\n3. debug(action: "continue")\n4. If the program appears hung: debug(action: "pause")\n5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`',
+		},
+		{
+			caption: "Launch a Python script with debugpy",
+			call: { action: "launch", adapter: "debugpy", program: "scripts/job.py", args: ["--flag"] },
+		},
+		{
+			caption: "Raw debugger command through repl",
+			call: { action: "evaluate", expression: "info registers", context: "repl" },
+		},
+	];
+
 	readonly concurrency = "exclusive";
 	readonly loadMode = "discoverable";
 

package/src/tools/eval.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import type { ImageContent } from "@oh-my-pi/pi-ai";
+import type { ImageContent, ToolExample } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
 import { jsBackend, pythonBackend } from "../eval";
@@ -183,6 +183,25 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 		const spawnsAllowed = sessionSpawns !== "" && sessionSpawns !== null;
 		return getEvalToolDescription({ py: backends.python, js: backends.js, spawns: spawnsAllowed });
 	}
+	readonly examples: readonly ToolExample<z.input<typeof evalSchema>>[] = [
+		{
+			call: {
+				cells: [
+					{
+						language: "py",
+						title: "imports",
+						timeout: 10,
+						code: "import json\nfrom pathlib import Path",
+					},
+					{
+						language: "py",
+						title: "load config",
+						code: "data = json.loads(read('package.json'))\ndisplay(data)",
+					},
+				],
+			},
+		},
+	];
 	readonly parameters = evalSchema;
 	readonly concurrency = "exclusive";
 	readonly strict = true;

package/src/tools/find.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import * as natives from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
@@ -106,6 +107,29 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 	readonly label = "Find";
 	readonly description: string;
 	readonly parameters = findSchema;
+
+	readonly examples: readonly ToolExample<z.input<typeof findSchema>>[] = [
+		{
+			caption: "Find files",
+			call: { paths: ["src/**/*.ts"] },
+		},
+		{
+			caption: "Multiple targets — separate array elements",
+			call: { paths: ["src/**/*.ts", "test/**/*.ts"] },
+		},
+		{
+			caption: "Find gitignored files like .env",
+			call: { paths: [".env*"], gitignore: false },
+		},
+		{
+			caption: "Find directories matching a name (returns both files and dirs; directories are suffixed with `/`)",
+			call: { paths: ["**/tests"] },
+		},
+		{
+			caption: "Long-running search on a slow volume",
+			call: { paths: ["/Volumes/Storage/**/*.py"], timeout: 30 },
+		},
+	];
 	readonly strict = true;
 
 	readonly #customOps?: FindOperations;

package/src/tools/inspect-image.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent-core";
-import { type Api, completeSimple, type Model } from "@oh-my-pi/pi-ai";
+import { type Api, completeSimple, type Model, type ToolExample } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
 import { extractTextContent } from "../commit/utils";
@@ -43,6 +43,32 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 	readonly parameters = inspectImageSchema;
 	readonly strict = false;
 
+	readonly examples: readonly ToolExample<z.input<typeof inspectImageSchema>>[] = [
+		{
+			caption: "OCR with strict formatting",
+			call: {
+				path: "screenshots/error.png",
+				question: "Extract all visible text verbatim. Return as bullet list in reading order.",
+			},
+		},
+		{
+			caption: "Screenshot debugging",
+			call: {
+				path: "screenshots/settings.png",
+				question:
+					"Identify the likely cause of the disabled Save button. Return: (1) observations, (2) likely cause, (3) confidence.",
+			},
+		},
+		{
+			caption: "Scene/object question",
+			call: {
+				path: "photos/shelf.jpg",
+				question:
+					"List all clearly visible product labels and their shelf positions (top/middle/bottom). If unreadable, say unreadable.",
+			},
+		},
+	];
+
 	constructor(
 		private readonly session: ToolSession,
 		private readonly completeImageRequest: typeof completeSimple = completeSimple,