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

package/src/tools/read.ts

@@ -8,7 +8,7 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { getRemoteDir, prompt, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { computeLineHash } from "../edit/line-hash";
+import { formatHashLines } from "../edit/line-hash";
 import {
 	type ChunkReadTarget,
 	formatChunkedRead,
@@ -89,19 +89,11 @@ function isRemoteMountPath(absolutePath: string): boolean {
 
 function prependLineNumbers(text: string, startNum: number): string {
 	const textLines = text.split("\n");
-	const lastLineNum = startNum + textLines.length - 1;
-	const padWidth = String(lastLineNum).length;
-	return textLines
-		.map((line, i) => {
-			const lineNum = String(startNum + i).padStart(padWidth, " ");
-			return `${lineNum}|${line}`;
-		})
-		.join("\n");
+	return textLines.map((line, i) => `${startNum + i}|${line}`).join("\n");
 }
 
 function prependHashLines(text: string, startNum: number): string {
-	const textLines = text.split("\n");
-	return textLines.map((line, i) => `${startNum + i}#${computeLineHash(startNum + i, line)}:${line}`).join("\n");
+	return formatHashLines(text, startNum);
 }
 
 function formatTextWithMode(
@@ -369,9 +361,9 @@ function prependSuffixResolutionNotice(text: string, suffixResolution?: { from:
 }
 
 const readSchema = Type.Object({
-	path: Type.String({ description: "Path or URL to read" }),
-	sel: Type.Optional(Type.String({ description: "Selector: chunk path, L10-L50, or raw" })),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds", default: 20 })),
+	path: Type.String({ description: "path or url", examples: ["src/foo.ts", "https://example.com"] }),
+	sel: Type.Optional(Type.String({ description: "line range or mode", examples: ["L50", "L50-L120", "raw"] })),
+	timeout: Type.Optional(Type.Number({ description: "timeout in seconds", default: 20 })),
 });
 
 export type ReadToolInput = Static<typeof readSchema>;
@@ -389,6 +381,10 @@ export interface ReadToolDetails {
 	method?: string;
 	notes?: string[];
 	meta?: OutputMeta;
+	/** Raw text + start line for user-visible TUI rendering, set when content is text-like.
+	 * Mirrors the same lines the model receives but without hashline/line-number prefixes,
+	 * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
+	displayContent?: { text: string; startLine: number };
 }
 
 type ReadParams = ReadToolInput;
@@ -599,9 +595,10 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			sourceInternal?: string;
 			entityLabel: string;
 			ignoreResultLimits?: boolean;
+			raw?: boolean;
 		},
 	): AgentToolResult<ReadToolDetails> {
-		const displayMode = resolveFileDisplayMode(this.session);
+		const displayMode = resolveFileDisplayMode(this.session, { raw: options.raw });
 		const details = options.details ?? {};
 		const allLines = text.split("\n");
 		const totalLines = allLines.length;
@@ -640,8 +637,10 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const shouldAddHashLines = displayMode.hashLines;
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
-		const formatText = (content: string, startNum: number): string =>
-			formatTextWithMode(content, startNum, shouldAddHashLines, shouldAddLineNumbers);
+		const formatText = (content: string, startNum: number): string => {
+			details.displayContent = { text: content, startLine: startNum };
+			return formatTextWithMode(content, startNum, shouldAddHashLines, shouldAddLineNumbers);
+		};
 
 		let outputText: string;
 		let truncationInfo:
@@ -743,6 +742,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		limit: number | undefined,
 		resolvedArchivePath: ResolvedArchiveReadPath,
 		signal?: AbortSignal,
+		options?: { raw?: boolean },
 	): Promise<AgentToolResult<ReadToolDetails>> {
 		throwIfAborted(signal);
 		const archive = await openArchive(resolvedArchivePath.absolutePath);
@@ -787,6 +787,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			details,
 			sourcePath: resolvedArchivePath.absolutePath,
 			entityLabel: "archive entry",
+			raw: options?.raw,
 		});
 		const firstText = result.content.find((content): content is TextContent => content.type === "text");
 		if (firstText) {
@@ -978,7 +979,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const archivePath = await this.#resolveArchiveReadPath(localReadPath, signal);
 		if (archivePath) {
 			const { offset, limit } = selToOffsetLimit(parsed);
-			return this.#readArchive(readPath, offset, limit, archivePath, signal);
+			return this.#readArchive(readPath, offset, limit, archivePath, signal, { raw: parsed.kind === "raw" });
 		}
 
 		const sqlitePath = await this.#resolveSqliteReadPath(readPath, signal);
@@ -1247,9 +1248,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				firstLineExceedsLimit,
 			};
 
-			const shouldAddHashLines = displayMode.hashLines;
-			const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
+			const isRawMode = parsed.kind === "raw";
+			const shouldAddHashLines = !isRawMode && displayMode.hashLines;
+			const shouldAddLineNumbers = isRawMode ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
+			let capturedDisplayContent: { text: string; startLine: number } | undefined;
 			const formatText = (text: string, startNum: number): string => {
+				capturedDisplayContent = { text, startLine: startNum };
 				return formatTextWithMode(text, startNum, shouldAddHashLines, shouldAddLineNumbers);
 			};
 
@@ -1300,6 +1304,10 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				sourcePath = absolutePath;
 			}
 
+			if (capturedDisplayContent) {
+				details.displayContent = capturedDisplayContent;
+			}
+
 			content = [{ type: "text", text: outputText }];
 		}
 
@@ -1494,7 +1502,10 @@ export const readToolRenderer = {
 		}
 
 		const details = result.details;
-		const contentText = result.content?.find(c => c.type === "text")?.text ?? "";
+		const rawText = result.content?.find(c => c.type === "text")?.text ?? "";
+		// Prefer structured `displayContent` from details when available so the TUI
+		// shows clean file content (no model-only hashline anchors) without parsing the formatted text.
+		const contentText = details?.displayContent?.text ?? rawText;
 		const imageContent = result.content?.find(c => c.type === "image");
 		const rawPath = args?.file_path || args?.path || "";
 		const filePath = shortenPath(rawPath);

package/src/tools/render-mermaid.ts

@@ -5,7 +5,7 @@ import renderMermaidDescription from "../prompts/tools/render-mermaid.md" with {
 import type { ToolSession } from "./index";
 
 const renderMermaidSchema = Type.Object({
-	mermaid: Type.String({ description: "Mermaid graph source text" }),
+	mermaid: Type.String({ description: "mermaid source", examples: ["graph TD; A-->B"] }),
 	config: Type.Optional(
 		Type.Object({
 			useAscii: Type.Optional(Type.Boolean()),

package/src/tools/render-utils.ts

@@ -182,6 +182,24 @@ export function formatEmptyMessage(message: string, theme: Theme): string {
 	return `${theme.styledSymbol("status.warning", "warning")} ${theme.fg("muted", message)}`;
 }
 
+// =============================================================================
+// Code Frame Formatting
+// =============================================================================
+
+export type CodeFrameMarker = "" | " " | "*" | "+" | "-" | ">";
+
+export function formatCodeFrameLine(
+	marker: CodeFrameMarker,
+	lineNumber: string | number,
+	content: string,
+	lineNumberWidth: number,
+): string {
+	const markerText = marker.trim();
+	const lineNumberText = String(lineNumber).trim();
+	const gutterText = markerText && lineNumberText ? `${markerText}${lineNumberText}` : lineNumberText || markerText;
+	return `${gutterText.padStart(lineNumberWidth + 1, " ")}│${content}`;
+}
+
 // =============================================================================
 // Tool UI Helpers
 // =============================================================================

package/src/tools/renderers.ts

@@ -17,7 +17,7 @@ import { bashToolRenderer } from "./bash";
 import { calculatorToolRenderer } from "./calculator";
 import { debugToolRenderer } from "./debug";
 import { findToolRenderer } from "./find";
-import { ghRunWatchToolRenderer } from "./gh-renderer";
+import { githubToolRenderer } from "./gh-renderer";
 import { grepToolRenderer } from "./grep";
 import { inspectImageToolRenderer } from "./inspect-image-renderer";
 import { notebookToolRenderer } from "./notebook";
@@ -63,7 +63,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	ssh: sshToolRenderer as ToolRenderer,
 	task: taskToolRenderer as ToolRenderer,
 	todo_write: todoWriteToolRenderer as ToolRenderer,
-	gh_run_watch: ghRunWatchToolRenderer as ToolRenderer,
+	github: githubToolRenderer as ToolRenderer,
 	web_search: webSearchToolRenderer as ToolRenderer,
 	write: writeToolRenderer as ToolRenderer,
 };

package/src/tools/report-tool-issue.ts

@@ -14,8 +14,8 @@ import type { Settings } from "..";
 import type { ToolSession } from "./index";
 
 const ReportToolIssueParams = Type.Object({
-	tool: Type.String({ description: "Name of the tool that behaved unexpectedly" }),
-	report: Type.String({ description: "Description of what was unexpected about the tool's behavior" }),
+	tool: Type.String({ description: "tool name", examples: ["bash", "read"] }),
+	report: Type.String({ description: "unexpected behavior" }),
 });
 
 export function isAutoQaEnabled(settings?: Settings): boolean {
@@ -57,6 +57,7 @@ export function createReportToolIssueTool(session: ToolSession): AgentTool {
 	return {
 		name: "report_tool_issue",
 		label: "Report Tool Issue",
+		strict: false,
 		description: "Report unexpected tool behavior for automated QA tracking.",
 		parameters: ReportToolIssueParams,
 		async execute(_toolCallId, rawParams) {

package/src/tools/resolve.ts

@@ -13,7 +13,7 @@ import { ToolError } from "./tool-errors";
 
 const resolveSchema = Type.Object({
 	action: Type.Union([Type.Literal("apply"), Type.Literal("discard")]),
-	reason: Type.String({ description: "Why you're applying or discarding" }),
+	reason: Type.String({ description: "reason for action", examples: ["approved by user"] }),
 });
 
 type ResolveParams = Static<typeof resolveSchema>;

package/src/tools/review.ts

@@ -3,7 +3,7 @@
  *
  * Used by the reviewer agent to report findings in a structured way.
  * Hidden by default - only enabled when explicitly listed in agent's tools.
- * Reviewers finish via `submit_result` tool with SubmitReviewDetails schema.
+ * Reviewers finish via `yield` tool with SubmitReviewDetails schema.
  */
 // ─────────────────────────────────────────────────────────────────────────────
 // Subprocess tool handlers - registered for extraction/rendering in task tool
@@ -55,22 +55,24 @@ function getPriorityDisplay(
 // report_finding schema
 const ReportFindingParams = Type.Object({
 	title: Type.String({
-		description: "≤80 chars, imperative, prefixed with [P0-P3]. E.g., '[P1] Un-padding slices along wrong dimension'",
+		description: "prefixed imperative title",
+		examples: ["[P1] un-padding wrong dimension"],
 	}),
 	body: Type.String({
-		description: "Markdown explaining why this is a problem. One paragraph max.",
+		description: "problem explanation",
 	}),
 	priority: StringEnum(["P0", "P1", "P2", "P3"], {
-		description: "0=P0 (critical), 1=P1 (urgent), 2=P2 (normal), 3=P3 (low)",
+		description: "priority 0-3",
 	}),
 	confidence: Type.Number({
 		minimum: 0,
 		maximum: 1,
-		description: "Confidence score 0.0-1.0",
+		description: "confidence score",
+		examples: [0.0, 0.5, 1.0],
 	}),
-	file_path: Type.String({ description: "Absolute path to the file" }),
-	line_start: Type.Number({ description: "Start line of the issue" }),
-	line_end: Type.Number({ description: "End line of the issue" }),
+	file_path: Type.String({ description: "file path" }),
+	line_start: Type.Number({ description: "start line" }),
+	line_end: Type.Number({ description: "end line" }),
 });
 
 interface ReportFindingDetails {
@@ -131,7 +133,7 @@ export function parseReportFindingDetails(value: unknown): ReportFindingDetails
 export const reportFindingTool: AgentTool<typeof ReportFindingParams, ReportFindingDetails, Theme> = {
 	name: "report_finding",
 	label: "Report Finding",
-	description: "Report a code review finding. Use this for each issue found. Call submit_result when done.",
+	description: "Report a code review finding. Use this for each issue found. Call yield when done.",
 	parameters: ReportFindingParams,
 	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
 		const { title, body, priority, confidence, file_path, line_start, line_end } = params;
@@ -186,7 +188,7 @@ export const reportFindingTool: AgentTool<typeof ReportFindingParams, ReportFind
 	},
 };
 
-/** SubmitReviewDetails - used for rendering review results from submit_result tool */
+/** SubmitReviewDetails - used for rendering review results from yield tool */
 export interface SubmitReviewDetails {
 	overall_correctness: "correct" | "incorrect";
 	explanation: string;

package/src/tools/search-tool-bm25.ts

@@ -25,10 +25,8 @@ const MATCH_LABEL_LEN = 72;
 const MATCH_DESCRIPTION_LEN = 96;
 
 const searchToolBm25Schema = Type.Object({
-	query: Type.String({ description: "Search query for hidden MCP tool metadata" }),
-	limit: Type.Optional(
-		Type.Integer({ description: "Max matching tools to activate and return (default 8)", minimum: 1 }),
-	),
+	query: Type.String({ description: "mcp search query", examples: ["kubernetes pod", "image processing"] }),
+	limit: Type.Optional(Type.Integer({ description: "max matches", minimum: 1 })),
 });
 
 type SearchToolBm25Params = Static<typeof searchToolBm25Schema>;

package/src/tools/ssh.ts

@@ -22,10 +22,10 @@ import { toolResult } from "./tool-result";
 import { clampTimeout } from "./tool-timeouts";
 
 const sshSchema = Type.Object({
-	host: Type.String({ description: "Host name from managed SSH config or discovered ssh.json files" }),
-	command: Type.String({ description: "Command to execute on the remote host" }),
-	cwd: Type.Optional(Type.String({ description: "Remote working directory (optional)" })),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds", default: 60 })),
+	host: Type.String({ description: "ssh host", examples: ["my-server", "prod-1"] }),
+	command: Type.String({ description: "remote command", examples: ["ls -la", "uptime"] }),
+	cwd: Type.Optional(Type.String({ description: "remote working directory", examples: ["/var/log"] })),
+	timeout: Type.Optional(Type.Number({ description: "timeout in seconds", default: 60 })),
 });
 
 export interface SSHToolDetails {