@oh-my-pi/pi-coding-agent 14.3.0 → 14.4.1

package/src/tools/bash.ts

@@ -42,20 +42,19 @@ async function saveBashOriginalArtifact(session: ToolSession, originalText: stri
 }
 
 const bashSchemaBase = Type.Object({
-	command: Type.String({ description: "Command to execute" }),
+	command: Type.String({ description: "command to execute", examples: ["ls -la", "echo hi"] }),
 	env: Type.Optional(
 		Type.Record(Type.String({ pattern: BASH_ENV_NAME_PATTERN.source }), Type.String(), {
-			description:
-				"Additional environment variables passed to the command and rendered inline as shell assignments; prefer this for multiline or quote-heavy content",
+			description: "extra env vars",
 		}),
 	),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds", default: 300 })),
-	cwd: Type.Optional(Type.String({ description: "Working directory (default: cwd)" })),
-	head: Type.Optional(Type.Number({ description: "Return only first N lines of output" })),
-	tail: Type.Optional(Type.Number({ description: "Return only last N lines of output" })),
+	timeout: Type.Optional(Type.Number({ description: "timeout in seconds", default: 300 })),
+	cwd: Type.Optional(Type.String({ description: "working directory", examples: ["src/", "/tmp"] })),
+	head: Type.Optional(Type.Number({ description: "first n lines of output" })),
+	tail: Type.Optional(Type.Number({ description: "last n lines of output" })),
 	pty: Type.Optional(
 		Type.Boolean({
-			description: "Run in PTY mode when command needs a real terminal (e.g. sudo/ssh/top/less); default: false",
+			description: "run in pty mode",
 		}),
 	),
 });
@@ -64,7 +63,7 @@ const bashSchemaWithAsync = Type.Object({
 	...bashSchemaBase.properties,
 	async: Type.Optional(
 		Type.Boolean({
-			description: "Run in background; returns immediately with a job ID. Result delivered as follow-up.",
+			description: "run in background",
 		}),
 	),
 });

package/src/tools/browser.ts

@@ -361,12 +361,12 @@ function resolvePageClient(page: Page): PuppeteerCdpClient | null {
 const puppeteerGetArgsSchema = Type.Array(
 	Type.Object({
 		selector: Type.String({
-			description:
-				"Selector for the target element (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "target element selector",
+			examples: ["aria/Sign in", "text/Continue", "xpath/...", "pierce/..."],
 		}),
-		attribute: Type.Optional(Type.String({ description: "Attribute name (get_attribute)" })),
+		attribute: Type.Optional(Type.String({ description: "attribute name", examples: ["href", "data-id"] })),
 	}),
-	{ description: "Batch arguments for get_* actions", minItems: 1 },
+	{ description: "batch get_* args", minItems: 1 },
 );
 
 const browserSchema = Type.Object({
@@ -393,56 +393,58 @@ const browserSchema = Type.Object({
 			"screenshot",
 			"close",
 		],
-		{ description: "Action to perform" },
+		{ description: "action to perform" },
 	),
-	url: Type.Optional(Type.String({ description: "URL to navigate to (goto)" })),
+	url: Type.Optional(Type.String({ description: "url to navigate to", examples: ["https://example.com"] })),
 	selector: Type.Optional(
 		Type.String({
-			description:
-				"Selector for the target element (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "target element selector",
+			examples: ["aria/Sign in", "text/Continue", "xpath/...", "pierce/..."],
 		}),
 	),
-	element_id: Type.Optional(Type.Number({ description: "Element ID from observe" })),
-	include_all: Type.Optional(Type.Boolean({ description: "Include non-interactive nodes in observe" })),
-	viewport_only: Type.Optional(Type.Boolean({ description: "Limit observe output to elements in the viewport" })),
+	element_id: Type.Optional(Type.Number({ description: "observed element id" })),
+	include_all: Type.Optional(Type.Boolean({ description: "include non-interactive nodes" })),
+	viewport_only: Type.Optional(Type.Boolean({ description: "limit to viewport" })),
 	args: Type.Optional(puppeteerGetArgsSchema),
-	script: Type.Optional(Type.String({ description: "JavaScript to evaluate (evaluate)" })),
-	text: Type.Optional(Type.String({ description: "Text to type (type)" })),
-	value: Type.Optional(Type.String({ description: "Value to set (fill)" })),
-	attribute: Type.Optional(Type.String({ description: "Attribute name to read (get_attribute)" })),
-	key: Type.Optional(Type.String({ description: "Keyboard key to press (press)" })),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds", default: 30 })),
+	script: Type.Optional(
+		Type.String({ description: "javascript expression", examples: ["document.title", "window.location.href"] }),
+	),
+	text: Type.Optional(Type.String({ description: "text to type", examples: ["hello world"] })),
+	value: Type.Optional(Type.String({ description: "value to set", examples: ["hello"] })),
+	attribute: Type.Optional(Type.String({ description: "attribute to read", examples: ["href", "data-id"] })),
+	key: Type.Optional(Type.String({ description: "keyboard key", examples: ["Enter", "Tab", "Escape"] })),
+	timeout: Type.Optional(Type.Number({ description: "timeout in seconds", default: 30 })),
 	wait_until: Type.Optional(
 		StringEnum(["load", "domcontentloaded", "networkidle0", "networkidle2"], {
-			description: "Navigation wait condition (goto)",
+			description: "navigation wait condition",
 		}),
 	),
-	full_page: Type.Optional(Type.Boolean({ description: "Capture full page screenshot (screenshot)" })),
+	full_page: Type.Optional(Type.Boolean({ description: "full page screenshot" })),
 	format: Type.Optional(
 		StringEnum(["text", "markdown"], {
-			description: "Output format for extract_readable (text/markdown)",
+			description: "output format",
 		}),
 	),
-	path: Type.Optional(Type.String({ description: "Optional path to save screenshot (relative to cwd)" })),
+	path: Type.Optional(Type.String({ description: "screenshot save path", examples: ["out.png"] })),
 	viewport: Type.Optional(
 		Type.Object({
-			width: Type.Number({ description: "Viewport width in pixels" }),
-			height: Type.Number({ description: "Viewport height in pixels" }),
-			device_scale_factor: Type.Optional(Type.Number({ description: "Device scale factor" })),
+			width: Type.Number({ description: "viewport width" }),
+			height: Type.Number({ description: "viewport height" }),
+			device_scale_factor: Type.Optional(Type.Number({ description: "device scale factor" })),
 		}),
 	),
-	delta_x: Type.Optional(Type.Number({ description: "Scroll delta X (scroll)" })),
-	delta_y: Type.Optional(Type.Number({ description: "Scroll delta Y (scroll)" })),
+	delta_x: Type.Optional(Type.Number({ description: "scroll delta x" })),
+	delta_y: Type.Optional(Type.Number({ description: "scroll delta y" })),
 	from_selector: Type.Optional(
 		Type.String({
-			description:
-				"Drag start selector (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "drag start selector",
+			examples: ["aria/Drag handle"],
 		}),
 	),
 	to_selector: Type.Optional(
 		Type.String({
-			description:
-				"Drag end selector (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "drag end selector",
+			examples: ["text/Drop zone"],
 		}),
 	),
 });

package/src/tools/calculator.ts

@@ -31,11 +31,11 @@ type Token =
 const calculatorSchema = Type.Object({
 	calculations: Type.Array(
 		Type.Object({
-			expression: Type.String({ description: "Math expression to evaluate" }),
-			prefix: Type.String({ description: "Text to prepend to the result" }),
-			suffix: Type.String({ description: "Text to append to the result" }),
+			expression: Type.String({ description: "math expression", examples: ["2 + 2", "sqrt(16)"] }),
+			prefix: Type.String({ description: "prefix text" }),
+			suffix: Type.String({ description: "suffix text" }),
 		}),
-		{ description: "List of calculations to evaluate" },
+		{ description: "calculations to evaluate" },
 	),
 });
 

package/src/tools/cancel-job.ts

@@ -6,7 +6,7 @@ import cancelJobDescription from "../prompts/tools/cancel-job.md" with { type: "
 import type { ToolSession } from "./index";
 
 const cancelJobSchema = Type.Object({
-	job_id: Type.String({ description: "Background job ID" }),
+	job_id: Type.String({ description: "background job id", examples: ["job-1234"] }),
 });
 
 type CancelJobParams = Static<typeof cancelJobSchema>;

package/src/tools/checkpoint.ts

@@ -18,13 +18,13 @@ export interface CheckpointState {
 }
 
 const checkpointSchema = Type.Object({
-	goal: Type.String({ description: "What you are investigating and why" }),
+	goal: Type.String({ description: "investigation goal", examples: ["investigate retry logic"] }),
 });
 
 type CheckpointParams = Static<typeof checkpointSchema>;
 
 const rewindSchema = Type.Object({
-	report: Type.String({ description: "Concise investigation findings to retain after rewind" }),
+	report: Type.String({ description: "investigation findings" }),
 });
 
 type RewindParams = Static<typeof rewindSchema>;

package/src/tools/debug.ts

@@ -83,51 +83,55 @@ const debugSchema = Type.Object({
 			"terminate",
 			"sessions",
 		],
-		{ description: "DAP debugger action" },
+		{ description: "dap debugger action" },
 	),
-	program: Type.Optional(Type.String({ description: "Program or script path for launch" })),
-	args: Type.Optional(Type.Array(Type.String(), { description: "Program arguments for launch" })),
-	adapter: Type.Optional(Type.String({ description: "Debugger adapter override (gdb, lldb-dap, debugpy, dlv)" })),
-	cwd: Type.Optional(Type.String({ description: "Working directory for launch or attach" })),
-	file: Type.Optional(Type.String({ description: "Source file for source breakpoints" })),
-	line: Type.Optional(Type.Number({ description: "1-indexed source line for source breakpoints" })),
-	function: Type.Optional(Type.String({ description: "Function name for function breakpoints" })),
-	name: Type.Optional(Type.String({ description: "Variable or data name for data breakpoint info" })),
-	condition: Type.Optional(Type.String({ description: "Breakpoint condition expression" })),
-	hit_condition: Type.Optional(Type.String({ description: "Breakpoint hit condition expression" })),
-	expression: Type.Optional(Type.String({ description: "Expression to evaluate in debugger context" })),
-	context: Type.Optional(Type.String({ description: "Evaluate context (watch, repl, hover, variables, clipboard)" })),
-	frame_id: Type.Optional(Type.Number({ description: "Stack frame ID for scopes/evaluate" })),
-	scope_id: Type.Optional(Type.Number({ description: "Scope variablesReference for variables requests" })),
-	variable_ref: Type.Optional(Type.Number({ description: "Variable reference for variables requests" })),
-	pid: Type.Optional(Type.Number({ description: "Process ID for attach" })),
-	port: Type.Optional(Type.Number({ description: "Port for remote attach when adapter supports it" })),
-	host: Type.Optional(Type.String({ description: "Host for remote attach when adapter supports it" })),
-	levels: Type.Optional(Type.Number({ description: "Maximum stack frames to fetch" })),
-	memory_reference: Type.Optional(Type.String({ description: "Memory reference or address" })),
-	instruction_reference: Type.Optional(
-		Type.String({ description: "Instruction address/reference for instruction breakpoints" }),
+	program: Type.Optional(Type.String({ description: "program path", examples: ["./my_app", "src/main.py"] })),
+	args: Type.Optional(Type.Array(Type.String(), { description: "program arguments", examples: [["--verbose"]] })),
+	adapter: Type.Optional(
+		Type.String({ description: "debugger adapter", examples: ["gdb", "lldb-dap", "debugpy", "dlv"] }),
 	),
-	instruction_count: Type.Optional(Type.Number({ description: "Number of instructions to disassemble" })),
-	instruction_offset: Type.Optional(Type.Number({ description: "Instruction offset for disassembly" })),
-	count: Type.Optional(Type.Number({ description: "Number of bytes to read from memory" })),
-	data: Type.Optional(Type.String({ description: "Base64-encoded memory payload for write_memory" })),
-	data_id: Type.Optional(Type.String({ description: "DAP data breakpoint identifier" })),
+	cwd: Type.Optional(Type.String({ description: "working directory", examples: ["src/"] })),
+	file: Type.Optional(Type.String({ description: "source file", examples: ["src/main.c"] })),
+	line: Type.Optional(Type.Number({ description: "source line", examples: [42] })),
+	function: Type.Optional(Type.String({ description: "function name", examples: ["main", "handle_request"] })),
+	name: Type.Optional(Type.String({ description: "variable or data name", examples: ["counter", "buffer"] })),
+	condition: Type.Optional(Type.String({ description: "breakpoint condition", examples: ["i == 10", "x > 0"] })),
+	hit_condition: Type.Optional(Type.String({ description: "hit condition" })),
+	expression: Type.Optional(Type.String({ description: "expression to evaluate", examples: ["x + 1", "obj.field"] })),
+	context: Type.Optional(
+		Type.String({ description: "evaluate context", examples: ["watch", "repl", "hover", "variables", "clipboard"] }),
+	),
+	frame_id: Type.Optional(Type.Number({ description: "stack frame id" })),
+	scope_id: Type.Optional(Type.Number({ description: "scope variables reference" })),
+	variable_ref: Type.Optional(Type.Number({ description: "variable reference" })),
+	pid: Type.Optional(Type.Number({ description: "process id for attach", examples: [12345] })),
+	port: Type.Optional(Type.Number({ description: "remote attach port", examples: [4711] })),
+	host: Type.Optional(Type.String({ description: "remote attach host", examples: ["127.0.0.1"] })),
+	levels: Type.Optional(Type.Number({ description: "max stack frames" })),
+	memory_reference: Type.Optional(
+		Type.String({ description: "memory reference or address", examples: ["0x7ffd1234"] }),
+	),
+	instruction_reference: Type.Optional(Type.String({ description: "instruction address or reference" })),
+	instruction_count: Type.Optional(Type.Number({ description: "instructions to disassemble" })),
+	instruction_offset: Type.Optional(Type.Number({ description: "instruction offset" })),
+	count: Type.Optional(Type.Number({ description: "bytes to read" })),
+	data: Type.Optional(Type.String({ description: "base64 memory payload" })),
+	data_id: Type.Optional(Type.String({ description: "data breakpoint id" })),
 	access_type: Type.Optional(
-		StringEnum(["read", "write", "readWrite"], { description: "Data breakpoint access type" }),
+		StringEnum(["read", "write", "readWrite"], { description: "data breakpoint access type" }),
 	),
-	command: Type.Optional(Type.String({ description: "Custom DAP request command" })),
+	command: Type.Optional(Type.String({ description: "custom dap request command" })),
 	arguments: Type.Optional(
 		Type.Record(Type.String(), Type.Any(), {
-			description: "Arguments object for custom_request",
+			description: "custom request arguments",
 		}),
 	),
-	offset: Type.Optional(Type.Number({ description: "Memory or instruction offset" })),
-	resolve_symbols: Type.Optional(Type.Boolean({ description: "Resolve symbols during disassembly" })),
-	allow_partial: Type.Optional(Type.Boolean({ description: "Allow partial writes for write_memory" })),
-	start_module: Type.Optional(Type.Number({ description: "Modules request start index" })),
-	module_count: Type.Optional(Type.Number({ description: "Maximum modules to fetch" })),
-	timeout: Type.Optional(Type.Number({ description: "Per-request timeout in seconds" })),
+	offset: Type.Optional(Type.Number({ description: "memory or instruction offset" })),
+	resolve_symbols: Type.Optional(Type.Boolean({ description: "resolve symbols during disassembly" })),
+	allow_partial: Type.Optional(Type.Boolean({ description: "allow partial writes" })),
+	start_module: Type.Optional(Type.Number({ description: "modules start index" })),
+	module_count: Type.Optional(Type.Number({ description: "max modules to fetch" })),
+	timeout: Type.Optional(Type.Number({ description: "per-request timeout seconds" })),
 });
 
 export type DebugParams = Static<typeof debugSchema>;

package/src/tools/exit-plan-mode.ts

@@ -8,7 +8,7 @@ import { resolvePlanPath } from "./plan-mode-guard";
 import { ToolError } from "./tool-errors";
 
 const exitPlanModeSchema = Type.Object({
-	title: Type.String({ description: "Final plan title, e.g. WP_MIGRATION_PLAN" }),
+	title: Type.String({ description: "final plan title", examples: ["WP_MIGRATION_PLAN"] }),
 });
 
 type ExitPlanModeParams = Static<typeof exitPlanModeSchema>;

package/src/tools/find.ts

@@ -30,11 +30,11 @@ import { toolResult } from "./tool-result";
 
 const findSchema = Type.Object({
 	pattern: Type.String({
-		description:
-			"Glob pattern including the search path (no separate path param), e.g. 'src/**/*.ts', 'lib/*.json'. Supports comma-separated lists like 'apps/,packages/,phases/'. Simple patterns like '*.ts' recurse from cwd.",
+		description: "glob including search path",
+		examples: ["src/**/*.ts", "lib/*.json", "apps/,packages/", "*.ts"],
 	}),
-	hidden: Type.Optional(Type.Boolean({ description: "Include hidden files and directories", default: true })),
-	limit: Type.Optional(Type.Number({ description: "Max results", default: 1000 })),
+	hidden: Type.Optional(Type.Boolean({ description: "include hidden files", default: true })),
+	limit: Type.Optional(Type.Number({ description: "max results", default: 1000 })),
 });
 
 export type FindToolInput = Static<typeof findSchema>;

package/src/tools/gh-renderer.ts

@@ -19,7 +19,8 @@ import {
 	truncateToWidth as truncateVisualWidth,
 } from "./render-utils";
 
-type GhRunWatchRenderArgs = {
+type GithubToolRenderArgs = {
+	op?: string;
 	run?: string;
 	branch?: string;
 };
@@ -238,11 +239,11 @@ function renderFallbackText(
 	return new Text(header, 0, 0);
 }
 
-export const ghRunWatchToolRenderer = {
-	renderCall(args: GhRunWatchRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
+export const githubToolRenderer = {
+	renderCall(args: GithubToolRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
 		const lines: string[] = [];
 
-		// Header with spinner: "⠋ GitHub Run Watch"
+		// Header with spinner reflecting the dispatched op
 		const icon =
 			options.spinnerFrame !== undefined
 				? formatStatusIcon("running", uiTheme, options.spinnerFrame)
@@ -252,6 +253,13 @@ export const ghRunWatchToolRenderer = {
 		const runId = typeof args.run === "string" && args.run.trim().length > 0 ? args.run.trim() : undefined;
 		const branch = typeof args.branch === "string" && args.branch.trim().length > 0 ? args.branch.trim() : undefined;
 
+		const op = typeof args.op === "string" && args.op.trim().length > 0 ? args.op.trim() : undefined;
+		if (op && op !== "run_watch") {
+			const title = uiTheme.fg("accent", `GitHub ${op}`);
+			lines.push(`${icon} ${title}`);
+			return new Text(lines.join("\n"), 0, 0);
+		}
+
 		if (runId) {
 			// "⠋ GitHub Run Watch  run #12345"
 			const title = uiTheme.fg("accent", "GitHub Run Watch");