@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/src/tools/renderers.ts

@@ -0,0 +1,68 @@
+/**
+ * TUI renderers for built-in tools.
+ *
+ * These provide rich visualization for tool calls and results in the TUI.
+ */
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { editToolRenderer } from "../edit/renderer";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { lspToolRenderer } from "../lsp/render";
+import type { Theme } from "../modes/theme/theme";
+import { taskToolRenderer } from "../task/render";
+import { webSearchToolRenderer } from "../web/search/render";
+import { askToolRenderer } from "./ask";
+import { astEditToolRenderer } from "./ast-edit";
+import { astGrepToolRenderer } from "./ast-grep";
+import { bashToolRenderer } from "./bash";
+import { calculatorToolRenderer } from "./calculator";
+import { debugToolRenderer } from "./debug";
+import { findToolRenderer } from "./find";
+import { ghRunWatchToolRenderer } from "./gh-renderer";
+import { grepToolRenderer } from "./grep";
+import { inspectImageToolRenderer } from "./inspect-image-renderer";
+import { notebookToolRenderer } from "./notebook";
+import { pythonToolRenderer } from "./python";
+import { readToolRenderer } from "./read";
+import { resolveToolRenderer } from "./resolve";
+import { searchToolBm25Renderer } from "./search-tool-bm25";
+import { sshToolRenderer } from "./ssh";
+import { todoWriteToolRenderer } from "./todo-write";
+import { writeToolRenderer } from "./write";
+
+type ToolRenderer = {
+	renderCall: (args: unknown, options: RenderResultOptions, theme: Theme) => Component;
+	renderResult: (
+		result: { content: Array<{ type: string; text?: string }>; details?: unknown; isError?: boolean },
+		options: RenderResultOptions & { renderContext?: Record<string, unknown> },
+		theme: Theme,
+		args?: unknown,
+	) => Component;
+	mergeCallAndResult?: boolean;
+	/** Render without background box, inline in the response flow */
+	inline?: boolean;
+};
+
+export const toolRenderers: Record<string, ToolRenderer> = {
+	ask: askToolRenderer as ToolRenderer,
+	ast_grep: astGrepToolRenderer as ToolRenderer,
+	ast_edit: astEditToolRenderer as ToolRenderer,
+	bash: bashToolRenderer as ToolRenderer,
+	debug: debugToolRenderer as ToolRenderer,
+	python: pythonToolRenderer as ToolRenderer,
+	calc: calculatorToolRenderer as ToolRenderer,
+	edit: editToolRenderer as ToolRenderer,
+	find: findToolRenderer as ToolRenderer,
+	grep: grepToolRenderer as ToolRenderer,
+	lsp: lspToolRenderer as ToolRenderer,
+	notebook: notebookToolRenderer as ToolRenderer,
+	inspect_image: inspectImageToolRenderer as ToolRenderer,
+	read: readToolRenderer as ToolRenderer,
+	resolve: resolveToolRenderer as ToolRenderer,
+	search_tool_bm25: searchToolBm25Renderer as ToolRenderer,
+	ssh: sshToolRenderer as ToolRenderer,
+	task: taskToolRenderer as ToolRenderer,
+	todo_write: todoWriteToolRenderer as ToolRenderer,
+	gh_run_watch: ghRunWatchToolRenderer as ToolRenderer,
+	web_search: webSearchToolRenderer as ToolRenderer,
+	write: writeToolRenderer as ToolRenderer,
+};

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

@@ -0,0 +1,80 @@
+/**
+ * report_tool_issue — automated QA tool for tracking unexpected tool behavior.
+ *
+ * Enabled when PI_AUTO_QA=1 or the dev.autoqa setting is on.
+ * Always injected into every agent (including subagents) regardless of tool selection.
+ * Records grievances to a local SQLite database; never throws.
+ */
+import { Database } from "bun:sqlite";
+import path from "node:path";
+import type { AgentTool } from "@f5xc-salesdemos/pi-agent-core";
+import { $env, getAgentDir, logger, VERSION } from "@f5xc-salesdemos/pi-utils";
+import { Type } from "@sinclair/typebox";
+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" }),
+});
+
+export function isAutoQaEnabled(settings?: Settings): boolean {
+	return $env.PI_AUTO_QA === "1" || !!settings?.get("dev.autoqa");
+}
+
+export function getAutoQaDbPath(): string {
+	return path.join(getAgentDir(), "autoqa.db");
+}
+
+let cachedDb: Database | null = null;
+
+function openDb(): Database | null {
+	if (cachedDb) return cachedDb;
+	try {
+		const db = new Database(getAutoQaDbPath());
+		db.run(`
+			PRAGMA journal_mode=WAL;
+			PRAGMA synchronous=NORMAL;
+			PRAGMA busy_timeout=5000;
+			CREATE TABLE IF NOT EXISTS grievances (
+				id INTEGER PRIMARY KEY AUTOINCREMENT,
+				model TEXT NOT NULL,
+				version TEXT NOT NULL,
+				tool TEXT NOT NULL,
+				report TEXT NOT NULL
+			);
+		`);
+		cachedDb = db;
+		return db;
+	} catch {
+		return null;
+	}
+}
+
+export function createReportToolIssueTool(session: ToolSession): AgentTool {
+	const getModel = () => session.getActiveModelString?.() ?? "unknown";
+
+	return {
+		name: "report_tool_issue",
+		label: "Report Tool Issue",
+		description: "Report unexpected tool behavior for automated QA tracking.",
+		parameters: ReportToolIssueParams,
+		async execute(_toolCallId, rawParams) {
+			try {
+				const params = rawParams as { tool: string; report: string };
+				const db = openDb();
+				db?.prepare("INSERT INTO grievances (model, version, tool, report) VALUES (?, ?, ?, ?)").run(
+					getModel(),
+					VERSION,
+					params.tool,
+					params.report,
+				);
+			} catch (error) {
+				logger.error("Failed to record tool issue", { error });
+			}
+			return {
+				content: [{ type: "text", text: "Noted, thanks!" }],
+			};
+		},
+	};
+}

package/src/tools/resolve.ts

@@ -0,0 +1,192 @@
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@f5xc-salesdemos/pi-agent-core";
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { Text } from "@f5xc-salesdemos/pi-tui";
+import { prompt, untilAborted } from "@f5xc-salesdemos/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import resolveDescription from "../prompts/tools/resolve.md" with { type: "text" };
+import { Ellipsis, padToWidth, renderStatusLine, truncateToWidth } from "../tui";
+import type { ToolSession } from ".";
+import { replaceTabs } from "./render-utils";
+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" }),
+});
+
+type ResolveParams = Static<typeof resolveSchema>;
+
+export interface ResolveToolDetails {
+	action: "apply" | "discard";
+	reason: string;
+	sourceToolName?: string;
+	label?: string;
+}
+
+function resolveReasonPreview(reason?: string): string | undefined {
+	const trimmed = reason?.trim();
+	if (!trimmed) return undefined;
+	return truncateToWidth(trimmed, 72, Ellipsis.Omit);
+}
+
+/**
+ * Queue a resolve-protocol handler on the tool-choice queue. Forces the next
+ * LLM call to invoke the hidden `resolve` tool, wraps the caller's apply/reject
+ * callbacks into an onInvoked closure that matches the resolve schema, and
+ * steers a preview reminder so the model understands why.
+ *
+ * This is the canonical entry point for any tool that wants preview/apply
+ * semantics. No session-level abstraction is needed: callers pass their
+ * apply/reject functions directly.
+ */
+export function queueResolveHandler(
+	session: ToolSession,
+	options: {
+		label: string;
+		sourceToolName: string;
+		apply(reason: string): Promise<AgentToolResult<unknown>>;
+		reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>;
+	},
+): void {
+	const queue = session.getToolChoiceQueue?.();
+	const forced = session.buildToolChoice?.("resolve");
+	if (!queue || !forced || typeof forced === "string") return;
+
+	const detailsFor = (params: ResolveParams): ResolveToolDetails => ({
+		action: params.action,
+		reason: params.reason,
+		sourceToolName: options.sourceToolName,
+		label: options.label,
+	});
+
+	queue.pushOnce(forced, {
+		label: `pending-action:${options.sourceToolName}`,
+		now: true,
+		onRejected: () => "requeue",
+		onInvoked: async (input: unknown) => {
+			const params = input as ResolveParams;
+			if (params.action === "apply") {
+				const result = await options.apply(params.reason);
+				return { ...result, details: detailsFor(params) };
+			}
+			if (params.action === "discard" && options.reject != null) {
+				const result = await options.reject(params.reason);
+				if (result != null) {
+					return { ...result, details: detailsFor(params) };
+				}
+			}
+			return {
+				content: [{ type: "text" as const, text: `Discarded: ${options.label}. Reason: ${params.reason}` }],
+				details: detailsFor(params),
+			};
+		},
+	});
+
+	session.steer?.({
+		customType: "resolve-reminder",
+		content: [
+			"<system-reminder>",
+			"This is a preview. Call the `resolve` tool to apply or discard these changes.",
+			"</system-reminder>",
+		].join("\n"),
+		details: { toolName: options.sourceToolName },
+	});
+}
+
+export class ResolveTool implements AgentTool<typeof resolveSchema, ResolveToolDetails> {
+	readonly name = "resolve";
+	readonly label = "Resolve";
+	readonly hidden = true;
+	readonly description: string;
+	readonly parameters = resolveSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {
+		this.description = prompt.render(resolveDescription);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: ResolveParams,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<ResolveToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<ResolveToolDetails>> {
+		return untilAborted(signal, async () => {
+			const invoker = this.session.peekQueueInvoker?.();
+			if (!invoker) {
+				throw new ToolError("No pending action to resolve. Nothing to apply or discard.");
+			}
+			const result = (await invoker(params)) as AgentToolResult<ResolveToolDetails>;
+			return result;
+		});
+	}
+}
+
+export const resolveToolRenderer = {
+	renderCall(args: ResolveParams, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const reason = resolveReasonPreview(args.reason);
+		const text = renderStatusLine(
+			{
+				icon: "pending",
+				title: "Resolve",
+				description: args.action,
+				badge: {
+					label: args.action === "apply" ? "proposed -> resolved" : "proposed -> rejected",
+					color: args.action === "apply" ? "success" : "warning",
+				},
+				meta: reason ? [uiTheme.fg("muted", reason)] : undefined,
+			},
+			uiTheme,
+		);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: ResolveToolDetails; isError?: boolean },
+		_options: RenderResultOptions,
+		uiTheme: Theme,
+	): Component {
+		const details = result.details;
+		const label = replaceTabs(details?.label ?? "pending action");
+		const reason = replaceTabs(details?.reason?.trim() || "No reason provided");
+		const action = details?.action ?? "apply";
+		const isApply = action === "apply" && !result.isError;
+		const bgColor = result.isError ? "error" : isApply ? "success" : "warning";
+		const icon = isApply ? uiTheme.status.success : uiTheme.status.error;
+		const verb = isApply ? "Accept" : "Discard";
+		const separator = ": ";
+		const separatorIndex = label.indexOf(separator);
+		const sourceLabel = separatorIndex > 0 ? label.slice(0, separatorIndex).trim() : undefined;
+		const summaryLabel = separatorIndex > 0 ? label.slice(separatorIndex + separator.length).trim() : label;
+		const sourceBadge = sourceLabel
+			? uiTheme.bold(`${uiTheme.format.bracketLeft}${sourceLabel}${uiTheme.format.bracketRight}`)
+			: undefined;
+		const headerLine = `${icon} ${uiTheme.bold(`${verb}:`)} ${summaryLabel}${sourceBadge ? ` ${sourceBadge}` : ""}`;
+		const lines = ["", headerLine, "", uiTheme.italic(reason), ""];
+
+		return {
+			render(width: number) {
+				const lineWidth = Math.max(3, width);
+				const innerWidth = Math.max(1, lineWidth - 2);
+				return lines.map(line => {
+					const truncated = truncateToWidth(line, innerWidth, Ellipsis.Omit);
+					const framed = ` ${padToWidth(truncated, innerWidth)} `;
+					const padded = padToWidth(framed, lineWidth);
+					return uiTheme.inverse(uiTheme.fg(bgColor, padded));
+				});
+			},
+			invalidate() {},
+		};
+	},
+
+	inline: true,
+	mergeCallAndResult: true,
+};

package/src/tools/review.ts

@@ -0,0 +1,238 @@
+/**
+ * Review tools - report_finding for structured code review.
+ *
+ * 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.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Subprocess tool handlers - registered for extraction/rendering in task tool
+// ─────────────────────────────────────────────────────────────────────────────
+import path from "node:path";
+import type { AgentTool } from "@f5xc-salesdemos/pi-agent-core";
+import { StringEnum } from "@f5xc-salesdemos/pi-ai";
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { Container, Text } from "@f5xc-salesdemos/pi-tui";
+import { isRecord } from "@f5xc-salesdemos/pi-utils";
+import { Type } from "@sinclair/typebox";
+import type { Theme, ThemeColor } from "../modes/theme/theme";
+import { subprocessToolRegistry } from "../task/subprocess-tool-registry";
+
+export type FindingPriority = "P0" | "P1" | "P2" | "P3";
+
+export interface FindingPriorityInfo {
+	ord: 0 | 1 | 2 | 3;
+	symbol: "status.error" | "status.warning" | "status.info";
+	color: ThemeColor;
+}
+
+const PRIORITY_INFO: Record<FindingPriority, FindingPriorityInfo> = {
+	P0: { ord: 0, symbol: "status.error", color: "error" },
+	P1: { ord: 1, symbol: "status.warning", color: "warning" },
+	P2: { ord: 2, symbol: "status.warning", color: "muted" },
+	P3: { ord: 3, symbol: "status.info", color: "accent" },
+};
+
+export const PRIORITY_LABELS: FindingPriority[] = ["P0", "P1", "P2", "P3"];
+
+export function getPriorityInfo(priority: FindingPriority): FindingPriorityInfo {
+	return PRIORITY_INFO[priority] ?? { ord: 3, symbol: "status.info", color: "muted" };
+}
+
+function getPriorityDisplay(
+	priority: FindingPriority,
+	theme: Theme,
+): { label: string; icon: string; color: ThemeColor } {
+	const label = priority;
+	const meta = PRIORITY_INFO[priority] ?? { symbol: "status.info", color: "muted" as const };
+	return {
+		label,
+		icon: theme.styledSymbol(meta.symbol, meta.color),
+		color: meta.color,
+	};
+}
+
+// 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'",
+	}),
+	body: Type.String({
+		description: "Markdown explaining why this is a problem. One paragraph max.",
+	}),
+	priority: StringEnum(["P0", "P1", "P2", "P3"], {
+		description: "0=P0 (critical), 1=P1 (urgent), 2=P2 (normal), 3=P3 (low)",
+	}),
+	confidence: Type.Number({
+		minimum: 0,
+		maximum: 1,
+		description: "Confidence score 0.0-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" }),
+});
+
+interface ReportFindingDetails {
+	title: string;
+	body: string;
+	priority: FindingPriority;
+	confidence: number;
+	file_path: string;
+	line_start: number;
+	line_end: number;
+}
+
+function isFindingPriority(value: unknown): value is FindingPriority {
+	return value === "P0" || value === "P1" || value === "P2" || value === "P3";
+}
+
+export function parseReportFindingDetails(value: unknown): ReportFindingDetails | undefined {
+	if (!isRecord(value)) return undefined;
+
+	const title = typeof value.title === "string" ? value.title : undefined;
+	const body = typeof value.body === "string" ? value.body : undefined;
+	const priority = isFindingPriority(value.priority) ? value.priority : undefined;
+	const confidence =
+		typeof value.confidence === "number" &&
+		Number.isFinite(value.confidence) &&
+		value.confidence >= 0 &&
+		value.confidence <= 1
+			? value.confidence
+			: undefined;
+	const filePath = typeof value.file_path === "string" && value.file_path.length > 0 ? value.file_path : undefined;
+	const lineStart =
+		typeof value.line_start === "number" && Number.isFinite(value.line_start) ? value.line_start : undefined;
+	const lineEnd = typeof value.line_end === "number" && Number.isFinite(value.line_end) ? value.line_end : undefined;
+
+	if (
+		title === undefined ||
+		body === undefined ||
+		priority === undefined ||
+		confidence === undefined ||
+		filePath === undefined ||
+		lineStart === undefined ||
+		lineEnd === undefined
+	) {
+		return undefined;
+	}
+
+	return {
+		title,
+		body,
+		priority,
+		confidence,
+		file_path: filePath,
+		line_start: lineStart,
+		line_end: lineEnd,
+	};
+}
+
+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.",
+	parameters: ReportFindingParams,
+	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		const { title, body, priority, confidence, file_path, line_start, line_end } = params;
+		const location = `${file_path}:${line_start}${line_end !== line_start ? `-${line_end}` : ""}`;
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Finding recorded: ${priority} ${title}\nLocation: ${location}\nConfidence: ${(
+						confidence * 100
+					).toFixed(0)}%`,
+				},
+			],
+			details: { title, body, priority, confidence, file_path, line_start, line_end },
+		};
+	},
+
+	renderCall(args, _options, theme): Component {
+		const { label, icon, color } = getPriorityDisplay(args.priority, theme);
+		const titleText = String(args.title).replace(/^\[P\d\]\s*/, "");
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("report_finding "))}${icon} ${theme.fg(color, `[${label}]`)} ${theme.fg(
+				"dim",
+				titleText,
+			)}`,
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, _options, theme): Component {
+		const { details } = result;
+		if (!details) {
+			const text = result.content[0];
+			return new Text(text?.type === "text" ? text.text : "", 0, 0);
+		}
+
+		const { label, icon, color } = getPriorityDisplay(details.priority, theme);
+		const location = `${details.file_path}:${details.line_start}${
+			details.line_end !== details.line_start ? `-${details.line_end}` : ""
+		}`;
+
+		return new Text(
+			`${theme.fg("success", theme.status.success)} ${icon} ${theme.fg(color, `[${label}]`)} ${theme.fg(
+				"dim",
+				location,
+			)}`,
+			0,
+			0,
+		);
+	},
+};
+
+/** SubmitReviewDetails - used for rendering review results from submit_result tool */
+export interface SubmitReviewDetails {
+	overall_correctness: "correct" | "incorrect";
+	explanation: string;
+	confidence: number;
+}
+
+// Re-export types for external use
+export type { ReportFindingDetails };
+
+// Register report_finding handler
+subprocessToolRegistry.register<ReportFindingDetails>("report_finding", {
+	extractData: event => {
+		if (event.isError) return undefined;
+		return parseReportFindingDetails(event.result?.details);
+	},
+
+	renderInline: (data, theme) => {
+		const { label, icon, color } = getPriorityDisplay(data.priority, theme);
+		const titleText = data.title.replace(/^\[P\d\]\s*/, "");
+		const loc = `${path.basename(data.file_path)}:${data.line_start}`;
+		return new Text(`${icon} ${theme.fg(color, `[${label}]`)} ${titleText} ${theme.fg("dim", loc)}`, 0, 0);
+	},
+
+	renderFinal: (allData, theme, expanded) => {
+		const container = new Container();
+		const displayCount = expanded ? allData.length : Math.min(3, allData.length);
+
+		for (let i = 0; i < displayCount; i++) {
+			const data = allData[i];
+			const { label, icon, color } = getPriorityDisplay(data.priority, theme);
+			const titleText = data.title.replace(/^\[P\d\]\s*/, "");
+			const loc = `${path.basename(data.file_path)}:${data.line_start}`;
+
+			container.addChild(
+				new Text(`  ${icon} ${theme.fg(color, `[${label}]`)} ${titleText} ${theme.fg("dim", loc)}`, 0, 0),
+			);
+
+			if (expanded && data.body) {
+				container.addChild(new Text(`    ${theme.fg("dim", data.body)}`, 0, 0));
+			}
+		}
+
+		if (allData.length > displayCount) {
+			container.addChild(new Text(theme.fg("dim", `  … ${allData.length - displayCount} more findings`), 0, 0));
+		}
+
+		return container;
+	},
+});