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

package/src/session/agent-session.ts

@@ -46,7 +46,9 @@ import {
 	collectEntriesForBranchSummary,
 	collectShakeRegions,
 	compact,
+	createCompactionSummaryMessage,
 	DEFAULT_SHAKE_CONFIG,
+	effectiveReserveTokens,
 	estimateTokens,
 	generateBranchSummary,
 	generateHandoff,
@@ -6423,6 +6425,37 @@ export class AgentSession {
 			let tokensBefore: number;
 			let details: unknown;
 
+			// Snapcompact runs locally first; if its frame archive plus the kept
+			// history still overflows the model window, fall back to an LLM summary
+			// (far cheaper than ~FRAME_TOKEN_ESTIMATE per frame).
+			let snapcompactResult: snapcompact.CompactionResult | undefined;
+			if (snapcompactReady) {
+				snapcompactResult = await snapcompact.compact(preparation, {
+					convertToLlm,
+					model: this.model,
+					shape: snapcompact.resolveShape(this.model, this.settings.get("snapcompact.shape")),
+					// Providers with hard image caps (OpenRouter: 8) silently drop
+					// frames past the cap — keep the archive within budget.
+					maxFrames: snapcompact.providerFrameBudget(this.model?.provider),
+				});
+				const ctxWindow = this.model?.contextWindow ?? 0;
+				const budget =
+					ctxWindow > 0
+						? ctxWindow - effectiveReserveTokens(ctxWindow, compactionSettings)
+						: Number.POSITIVE_INFINITY;
+				if (this.#projectSnapcompactContextTokens(preparation, snapcompactResult) > budget) {
+					logger.warn("Snapcompact still overflows the window; falling back to an LLM summary", {
+						model: this.model?.id,
+					});
+					this.emitNotice(
+						"warning",
+						"snapcompact could not bring the context under the limit — using an LLM summary instead",
+						"compaction",
+					);
+					snapcompactResult = undefined;
+				}
+			}
+
 			if (compactionPrep.kind === "fromHook") {
 				summary = compactionPrep.summary;
 				shortSummary = compactionPrep.shortSummary;
@@ -6430,15 +6463,7 @@ export class AgentSession {
 				tokensBefore = compactionPrep.tokensBefore;
 				details = compactionPrep.details;
 				preserveData = compactionPrep.preserveData;
-			} else if (snapcompactReady) {
-				const snapcompactResult = await snapcompact.compact(preparation, {
-					convertToLlm,
-					model: this.model,
-					shape: snapcompact.resolveShape(this.model, this.settings.get("snapcompact.shape")),
-					// Providers with hard image caps (OpenRouter: 8) silently drop
-					// frames past the cap — keep the archive within budget.
-					maxFrames: snapcompact.providerFrameBudget(this.model.provider),
-				});
+			} else if (snapcompactResult) {
 				summary = snapcompactResult.summary;
 				shortSummary = snapcompactResult.shortSummary;
 				firstKeptEntryId = snapcompactResult.firstKeptEntryId;
@@ -6755,6 +6780,19 @@ export class AgentSession {
 		const contextTokens = this.#estimatePendingPromptTokens(messages);
 		if (!shouldCompact(contextTokens, contextWindow, compactionSettings)) return;
 
+		// Auto-promote first: switching to a larger-context model avoids compacting
+		// the history at all. The post-turn threshold path already promotes before
+		// compacting; without this, the pre-prompt path would pre-empt promotion and
+		// compact (snapcompact/summary) a session that should have just been promoted.
+		if (await this.#promoteContextModel()) {
+			logger.debug("Pre-prompt context promotion avoided compaction", {
+				contextTokens,
+				contextWindow,
+				model: `${model.provider}/${model.id}`,
+			});
+			return;
+		}
+
 		logger.debug("Pre-prompt context maintenance triggered by pending prompt size", {
 			contextTokens,
 			contextWindow,
@@ -7324,12 +7362,28 @@ export class AgentSession {
 	 * Returns true if promotion succeeded (caller should retry without compacting).
 	 */
 	async #tryContextPromotion(assistantMessage: AssistantMessage): Promise<boolean> {
-		const promotionSettings = this.settings.getGroup("contextPromotion");
-		if (!promotionSettings.enabled) return false;
 		const currentModel = this.model;
 		if (!currentModel) return false;
+		// The overflow/length error may have come from a model the user already
+		// switched away from; only promote when the failing turn was this model.
 		if (assistantMessage.provider !== currentModel.provider || assistantMessage.model !== currentModel.id)
 			return false;
+		return this.#promoteContextModel();
+	}
+
+	/**
+	 * Switch to a larger-context sibling when context promotion is enabled and a
+	 * target with a strictly larger window (and a usable key) exists. Returns true
+	 * when the model was switched, so the caller can retry without compacting.
+	 * Message-independent core shared by the post-turn overflow path
+	 * ({@link #tryContextPromotion}) and the pre-prompt threshold path
+	 * ({@link #runPrePromptCompactionIfNeeded}).
+	 */
+	async #promoteContextModel(): Promise<boolean> {
+		const promotionSettings = this.settings.getGroup("contextPromotion");
+		if (!promotionSettings.enabled) return false;
+		const currentModel = this.model;
+		if (!currentModel) return false;
 		const contextWindow = currentModel.contextWindow ?? 0;
 		if (contextWindow <= 0) return false;
 		const targetModel = await this.#resolveContextPromotionTarget(currentModel, contextWindow);
@@ -7806,6 +7860,32 @@ export class AgentSession {
 		return { kind: "needsLlm", hookContext, hookPrompt, preserveData };
 	}
 
+	/**
+	 * Project the post-compaction context size of a snapcompact result: kept
+	 * recent messages + the summary message with its re-attached frames + the
+	 * fixed non-message overhead (system prompt + tools). Mirrors how the
+	 * compacted context is rebuilt, so the estimate matches the wire shape, and
+	 * lets the caller decide whether snapcompact brought the context under the
+	 * window or should fall back to an LLM summary.
+	 */
+	#projectSnapcompactContextTokens(preparation: CompactionPreparation, result: snapcompact.CompactionResult): number {
+		const archive = snapcompact.getPreservedArchive(result.preserveData);
+		const frames = archive ? snapcompact.images(archive) : undefined;
+		const summaryMessage = createCompactionSummaryMessage(
+			result.summary,
+			result.tokensBefore,
+			new Date().toISOString(),
+			result.shortSummary,
+			undefined,
+			frames,
+		);
+		let tokens = computeNonMessageTokens(this) + estimateTokens(summaryMessage);
+		for (const message of preparation.recentMessages) {
+			tokens += estimateTokens(message);
+		}
+		return tokens;
+	}
+
 	/**
 	 * Internal: Run auto-compaction with events.
 	 *
@@ -8018,6 +8098,39 @@ export class AgentSession {
 			let tokensBefore: number;
 			let details: unknown;
 
+			// Snapcompact runs locally first; if its frame archive plus the kept
+			// history still overflows the model window (frames are capped by the
+			// image budget and cost ~FRAME_TOKEN_ESTIMATE each), an LLM summary is
+			// far cheaper — downgrade to context-full and take the summarizer path.
+			let snapcompactResult: snapcompact.CompactionResult | undefined;
+			if (action === "snapcompact" && compactionPrep.kind !== "fromHook") {
+				snapcompactResult = await snapcompact.compact(preparation, {
+					convertToLlm,
+					model: this.model,
+					maxFrames: snapcompact.providerFrameBudget(this.model?.provider),
+				});
+				const ctxWindow = this.model?.contextWindow ?? 0;
+				const budget =
+					ctxWindow > 0
+						? ctxWindow - effectiveReserveTokens(ctxWindow, compactionSettings)
+						: Number.POSITIVE_INFINITY;
+				const projected = this.#projectSnapcompactContextTokens(preparation, snapcompactResult);
+				if (projected > budget) {
+					logger.warn("Snapcompact still overflows the window; falling back to an LLM summary", {
+						model: this.model?.id,
+						projected,
+						budget,
+					});
+					this.emitNotice(
+						"warning",
+						"snapcompact could not bring the context under the limit — using an LLM summary instead",
+						"compaction",
+					);
+					action = "context-full";
+					snapcompactResult = undefined;
+				}
+			}
+
 			if (compactionPrep.kind === "fromHook") {
 				summary = compactionPrep.summary;
 				shortSummary = compactionPrep.shortSummary;
@@ -8025,14 +8138,7 @@ export class AgentSession {
 				tokensBefore = compactionPrep.tokensBefore;
 				details = compactionPrep.details;
 				preserveData = compactionPrep.preserveData;
-			} else if (action === "snapcompact") {
-				// Local, deterministic: render discarded history onto PNG frames.
-				// No model candidates, no API key, no retry loop.
-				const snapcompactResult = await snapcompact.compact(preparation, {
-					convertToLlm,
-					model: this.model,
-					maxFrames: snapcompact.providerFrameBudget(this.model?.provider),
-				});
+			} else if (snapcompactResult) {
 				summary = snapcompactResult.summary;
 				shortSummary = snapcompactResult.shortSummary;
 				firstKeptEntryId = snapcompactResult.firstKeptEntryId;

package/src/session/session-dump-format.ts

@@ -3,8 +3,8 @@
  */
 import type { AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import { INTENT_FIELD } from "@oh-my-pi/pi-agent-core";
-import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
-import { isZodSchema, zodToWireSchema } from "@oh-my-pi/pi-ai/utils/schema";
+import type { AssistantMessage, Model, ToolExample, TSchema } from "@oh-my-pi/pi-ai";
+import { renderToolInventory } from "@oh-my-pi/pi-ai/grammar";
 import { getVisibleThinkingText } from "../utils/thinking-display";
 import {
 	type BashExecutionMessage,
@@ -23,6 +23,7 @@ export interface SessionDumpToolInfo {
 	name: string;
 	description: string;
 	parameters: unknown;
+	examples?: readonly ToolExample[];
 }
 
 export interface FormatSessionDumpTextOptions {
@@ -33,28 +34,6 @@ export interface FormatSessionDumpTextOptions {
 	tools?: readonly SessionDumpToolInfo[];
 }
 
-function stripTypeBoxFields(obj: unknown): unknown {
-	if (Array.isArray(obj)) {
-		return obj.map(stripTypeBoxFields);
-	}
-	if (obj && typeof obj === "object") {
-		const result: Record<string, unknown> = {};
-		for (const [k, v] of Object.entries(obj)) {
-			if (!k.startsWith("TypeBox.")) {
-				result[k] = stripTypeBoxFields(v);
-			}
-		}
-		return result;
-	}
-	return obj;
-}
-
-/** Resolve tool parameters to a plain JSON Schema object for dump output. */
-function toolParametersToJsonSchema(parameters: unknown): unknown {
-	if (isZodSchema(parameters)) return zodToWireSchema(parameters);
-	return stripTypeBoxFields(parameters);
-}
-
 /** Serialize an object as XML parameter elements, one per key. */
 function formatArgsAsXml(args: Record<string, unknown>, indent = "\t"): string {
 	const parts: string[] = [];
@@ -94,13 +73,13 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 	const tools = options.tools ?? [];
 	if (tools.length > 0) {
 		lines.push("## Available Tools\n");
-		for (const tool of tools) {
-			lines.push(`<tool name="${tool.name}">`);
-			lines.push(tool.description);
-			const parametersClean = toolParametersToJsonSchema(tool.parameters);
-			lines.push(`\nParameters:\n${formatArgsAsXml(parametersClean as Record<string, unknown>)}`);
-			lines.push("<" + "/tool>\n");
-		}
+		const inventoryTools = tools.map(tool => ({
+			name: tool.name,
+			description: tool.description,
+			parameters: tool.parameters as TSchema,
+			examples: tool.examples,
+		}));
+		lines.push(renderToolInventory(inventoryTools, options.model?.id ?? ""));
 		lines.push("\n");
 	}
 

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/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.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;