@f5xc-salesdemos/xcsh 18.66.2 → 18.68.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.66.2",
+	"version": "18.68.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -48,12 +48,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.66.2",
-		"@f5xc-salesdemos/pi-agent-core": "18.66.2",
-		"@f5xc-salesdemos/pi-ai": "18.66.2",
-		"@f5xc-salesdemos/pi-natives": "18.66.2",
-		"@f5xc-salesdemos/pi-tui": "18.66.2",
-		"@f5xc-salesdemos/pi-utils": "18.66.2",
+		"@f5xc-salesdemos/xcsh-stats": "18.68.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.68.0",
+		"@f5xc-salesdemos/pi-ai": "18.68.0",
+		"@f5xc-salesdemos/pi-natives": "18.68.0",
+		"@f5xc-salesdemos/pi-tui": "18.68.0",
+		"@f5xc-salesdemos/pi-utils": "18.68.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.66.2",
-	"commit": "04c64b950d117fc3499dca62d084f30e41545d1e",
-	"shortCommit": "04c64b9",
+	"version": "18.68.0",
+	"commit": "27ddc863792ce7bba1ab75066abeca95cafca4d4",
+	"shortCommit": "27ddc86",
 	"branch": "main",
-	"tag": "v18.66.2",
-	"commitDate": "2026-05-18T07:27:11Z",
-	"buildDate": "2026-05-18T07:51:19.009Z",
+	"tag": "v18.68.0",
+	"commitDate": "2026-05-18T17:51:04Z",
+	"buildDate": "2026-05-18T18:22:44.227Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/04c64b950d117fc3499dca62d084f30e41545d1e",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.66.2"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/27ddc863792ce7bba1ab75066abeca95cafca4d4",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.68.0"
 };

package/src/tools/render-utils.ts

@@ -625,3 +625,44 @@ export function formatParseErrors(errors: string[]): string[] {
 			: "Parse issues:";
 	return [header, ...capped.map(err => `- ${err}`)];
 }
+
+// =============================================================================
+// JSON / Display Utilities (shared with tool renderers)
+// =============================================================================
+
+export function stripEmpty(obj: unknown): unknown {
+	if (Array.isArray(obj)) return obj.map(stripEmpty).filter(v => v != null);
+	if (obj && typeof obj === "object") {
+		const entries = Object.entries(obj as Record<string, unknown>);
+		if (entries.length === 0) return obj;
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of entries) {
+			if (v == null || v === "" || (Array.isArray(v) && v.length === 0)) continue;
+			const cleaned = stripEmpty(v);
+			if (cleaned != null) out[k] = cleaned;
+		}
+		return Object.keys(out).length > 0 ? out : null;
+	}
+	return obj;
+}
+
+export function formatTimestamp(iso: string): string {
+	return iso.replace("T", " ").replace(/:\d{2}(\.\d+)?Z$/, " UTC");
+}
+
+export function addSection(
+	sections: Array<{ label?: string; lines: string[] }>,
+	label: string,
+	lines: string[],
+	theme: Theme,
+	maxLines?: number,
+): void {
+	const titled = theme.fg("toolTitle", label);
+	if (maxLines && lines.length > maxLines) {
+		const truncated = lines.slice(0, maxLines);
+		truncated.push(theme.fg("dim", `… ${lines.length - maxLines} more lines`));
+		sections.push({ label: titled, lines: truncated });
+	} else {
+		sections.push({ label: titled, lines });
+	}
+}

package/src/tools/renderers.ts

@@ -24,6 +24,7 @@ import { notebookToolRenderer } from "./notebook";
 import { pythonToolRenderer } from "./python";
 import { resolveToolRenderer } from "./resolve";
 import { searchToolBm25Renderer } from "./search-tool-bm25";
+import { sfToolRenderer } from "./sf-renderer";
 import { sshToolRenderer } from "./ssh";
 import { todoWriteToolRenderer } from "./todo-write";
 import { writeToolRenderer } from "./write";
@@ -70,4 +71,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	web_search: webSearchToolRenderer as ToolRenderer,
 	write: writeToolRenderer as ToolRenderer,
 	xcsh_api: xcshApiToolRenderer as ToolRenderer,
+	sf_setup: sfToolRenderer as ToolRenderer,
+	sf_query: sfToolRenderer as ToolRenderer,
+	sf_org_display: sfToolRenderer as ToolRenderer,
 };

package/src/tools/sf-renderer.ts

@@ -0,0 +1,272 @@
+/** TUI renderer for Salesforce tools — rich visual output at full parity with XC-API. */
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { Text } from "@f5xc-salesdemos/pi-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme, ThemeColor } from "../modes/theme/theme";
+import { CachedOutputBlock, F5_TOOL_BORDER_COLOR, renderStatusLine } from "../tui";
+import { addSection, formatErrorMessage, replaceTabs } from "./render-utils";
+import type { SfErrorType, SfToolDetails } from "./sf";
+import { flattenRecord } from "./sf/formatters";
+import type { SfOrg, SfQueryResult } from "./sf/types";
+
+const TOOL_TITLE = "Salesforce";
+const MAX_COL_WIDTH = 30;
+
+type SfRenderArgs = {
+	action?: string;
+	query?: string;
+	target_org?: string;
+};
+
+const TOOL_ACTION_COLORS: Partial<Record<string, ThemeColor>> = {
+	sf_setup: "chromeAccent",
+	sf_query: "contentAccent",
+};
+
+const ERROR_GUIDANCE: Record<SfErrorType, string> = {
+	auth_required: "Authenticate with: sf org login web --set-default --alias SFDC",
+	session_expired: "Re-authenticate: sf org login web --set-default\nThen run sf_setup action 'status' to confirm",
+	no_default_org: "Run sf_setup with action set_default to choose a default org",
+	invalid_query:
+		"Check field names and object types. Use SELECT ... FROM EntityDefinition to discover available objects",
+	exec_error: "Check sf CLI is installed and configured correctly",
+};
+
+function orgStatusColor(status: string): ThemeColor {
+	const lower = status.toLowerCase();
+	if (lower === "connected") return "success";
+	if (lower.includes("expired")) return "error";
+	return "warning";
+}
+
+function truncateCell(value: string, maxWidth: number): string {
+	if (value.length <= maxWidth) return value;
+	return `${value.slice(0, maxWidth - 1)}…`;
+}
+
+function buildOrgRows(orgs: SfOrg[], uiTheme: Theme): string[] {
+	return orgs.map(org => {
+		const defaultBadge = org.isDefault ? ` ${uiTheme.fg("chromeAccent", "(default)")}` : "";
+		const aliasText = org.alias
+			? uiTheme.fg("toolOutput", org.alias) + defaultBadge
+			: uiTheme.fg("dim", "(none)") + defaultBadge;
+		const username = uiTheme.fg("dim", org.username);
+		const status = uiTheme.fg(orgStatusColor(org.connectedStatus), org.connectedStatus);
+		const sandboxBadge = org.isSandbox ? `  ${uiTheme.fg("warning", "[sandbox]")}` : "";
+		return `  ${aliasText}  ${username}  ${status}${sandboxBadge}`;
+	});
+}
+
+function buildQueryTable(queryResult: SfQueryResult, uiTheme: Theme): string[] {
+	const records = queryResult.records as Record<string, unknown>[];
+	if (records.length === 0) return [uiTheme.fg("dim", "  No records found.")];
+
+	const flatRecords = records.map(r => flattenRecord(r));
+	const allColumns = Array.from(
+		flatRecords.reduce((cols, record) => {
+			for (const key of Object.keys(record)) cols.add(key);
+			return cols;
+		}, new Set<string>()),
+	);
+
+	const colWidths = allColumns.map(col => {
+		const maxData = flatRecords.reduce((max, rec) => {
+			const val = rec[col];
+			return Math.max(max, val == null ? 0 : String(val).replace(/[\n\r\t]+/g, " ").length);
+		}, 0);
+		return Math.min(MAX_COL_WIDTH, Math.max(col.length, maxData));
+	});
+
+	const lines: string[] = [];
+
+	// Header
+	const headerCells = allColumns.map((col, i) => uiTheme.fg("toolTitle", col.padEnd(colWidths[i]!)));
+	lines.push(`  ${headerCells.join("  ")}`);
+
+	// Separator
+	const sepCells = colWidths.map(w => uiTheme.fg("dim", "─".repeat(w)));
+	lines.push(`  ${sepCells.join("  ")}`);
+
+	// Rows
+	for (const rec of flatRecords) {
+		const cells = allColumns.map((col, i) => {
+			const val = rec[col];
+			const raw = val == null ? "" : String(val).replace(/[\n\r\t]+/g, " ");
+			const cell = truncateCell(raw, colWidths[i]!).padEnd(colWidths[i]!);
+			return val == null || raw === "" ? uiTheme.fg("dim", cell) : uiTheme.fg("toolOutput", cell);
+		});
+		lines.push(`  ${cells.join("  ")}`);
+	}
+
+	return lines;
+}
+
+function buildOrgKV(org: SfOrg, uiTheme: Theme): string[] {
+	const line = (label: string, value: string, valueColor: ThemeColor = "toolOutput") =>
+		`  ${uiTheme.fg("dim", label.padEnd(10))}${uiTheme.fg(valueColor, value)}`;
+
+	const lines: string[] = [];
+	if (org.alias) lines.push(line("alias:", org.alias));
+	lines.push(line("username:", org.username));
+	lines.push(line("org id:", org.orgId));
+	lines.push(line("instance:", org.instanceUrl));
+	lines.push(line("status:", org.connectedStatus, orgStatusColor(org.connectedStatus)));
+	if (org.isSandbox) lines.push(line("type:", "Sandbox", "warning"));
+	if (org.isDefault) lines.push(line("default:", "yes", "chromeAccent"));
+	return lines;
+}
+
+export const sfToolRenderer = {
+	renderCall(args: SfRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const action = args.action ?? (args.query !== undefined ? "query" : "org");
+		const text = renderStatusLine(
+			{
+				icon: "pending",
+				title: TOOL_TITLE,
+				badge: { label: action, color: args.query !== undefined ? "contentAccent" : "chromeAccent" },
+			},
+			uiTheme,
+		);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: SfToolDetails; isError?: boolean },
+		options: RenderResultOptions,
+		uiTheme: Theme,
+		_args?: SfRenderArgs,
+	): Component {
+		const details = result.details;
+		const isError = result.isError === true;
+
+		// Fallback: error without structured details
+		if (isError && !details) {
+			const errorText = result.content?.find(c => c.type === "text")?.text;
+			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+		}
+
+		const tool = details?.tool;
+		const action = details?.action;
+		const errorType = details?.errorType;
+		const sections: Array<{ label?: string; lines: string[] }> = [];
+
+		// --- Error path ---
+		if (isError) {
+			const errorText = result.content?.find(c => c.type === "text")?.text ?? "Unknown error";
+			addSection(sections, "Error", [uiTheme.fg("error", errorText)], uiTheme);
+
+			const badgeLabel = errorType ?? "error";
+			if (errorType) {
+				const guidance = ERROR_GUIDANCE[errorType];
+				const guidanceLines = guidance.split("\n").map(l => uiTheme.fg("warning", l));
+				addSection(sections, "Guidance", guidanceLines, uiTheme);
+			}
+
+			const header = renderStatusLine(
+				{
+					title: TOOL_TITLE,
+					titleColor: "contentAccent",
+					badge: { label: badgeLabel, color: "error" },
+				},
+				uiTheme,
+			);
+			const outputBlock = new CachedOutputBlock();
+			return {
+				render(width: number): string[] {
+					return outputBlock.render({ header, state: "error", sections, width }, uiTheme);
+				},
+				invalidate() {
+					outputBlock.invalidate();
+				},
+			};
+		}
+
+		// --- Success path ---
+		let badgeLabel = action ?? tool?.replace("sf_", "") ?? "sf";
+		const badgeColor: ThemeColor = tool ? (TOOL_ACTION_COLORS[tool] ?? "muted") : "muted";
+		const meta: string[] = [];
+
+		if (tool === "sf_setup") {
+			const orgs = details?.orgs;
+			if ((action === "status" || action === "list_orgs") && orgs !== undefined) {
+				const count = orgs.length;
+				meta.push(uiTheme.fg("dim", `${count} org${count !== 1 ? "s" : ""}`));
+				if (count === 0) {
+					addSection(sections, "Orgs", [uiTheme.fg("dim", "No authenticated orgs found.")], uiTheme);
+				} else {
+					addSection(sections, "Orgs", buildOrgRows(orgs, uiTheme), uiTheme);
+				}
+			} else {
+				const text = result.content?.find(c => c.type === "text")?.text ?? "";
+				addSection(
+					sections,
+					"Result",
+					text.split("\n").map(line => replaceTabs(uiTheme.fg("toolOutput", line))),
+					uiTheme,
+				);
+			}
+		} else if (tool === "sf_query") {
+			const queryResult = details?.queryResult;
+			if (queryResult) {
+				const count = queryResult.totalSize;
+				badgeLabel = "query";
+				meta.push(uiTheme.fg("dim", `${count} record${count !== 1 ? "s" : ""}`));
+				addSection(
+					sections,
+					`Results (${count} record${count !== 1 ? "s" : ""})`,
+					buildQueryTable(queryResult, uiTheme),
+					uiTheme,
+				);
+				if (!queryResult.done) {
+					addSection(
+						sections,
+						"Warning",
+						[uiTheme.fg("warning", "Results are incomplete. Use sf data export bulk for the full dataset.")],
+						uiTheme,
+					);
+				}
+			} else {
+				const text = result.content?.find(c => c.type === "text")?.text ?? "";
+				addSection(sections, "Result", [uiTheme.fg("toolOutput", text)], uiTheme);
+			}
+		} else if (tool === "sf_org_display") {
+			const org = details?.orgs?.[0];
+			if (org) {
+				badgeLabel = "org";
+				meta.push(uiTheme.fg("muted", org.alias ?? org.username));
+				meta.push(uiTheme.fg(orgStatusColor(org.connectedStatus), org.connectedStatus));
+				addSection(sections, "Summary", buildOrgKV(org, uiTheme), uiTheme);
+			} else {
+				const text = result.content?.find(c => c.type === "text")?.text ?? "";
+				addSection(sections, "Result", [uiTheme.fg("toolOutput", text)], uiTheme);
+			}
+		} else {
+			const text = result.content?.find(c => c.type === "text")?.text ?? "";
+			addSection(sections, "Result", [uiTheme.fg("toolOutput", text)], uiTheme);
+		}
+
+		const header = renderStatusLine(
+			{
+				title: TOOL_TITLE,
+				titleColor: "contentAccent",
+				badge: { label: badgeLabel, color: badgeColor },
+				meta: meta.length > 0 ? meta : undefined,
+			},
+			uiTheme,
+		);
+
+		const outputBlock = new CachedOutputBlock();
+		return {
+			render(width: number): string[] {
+				const state = options.isPartial ? "pending" : "success";
+				return outputBlock.render({ header, state, sections, width, borderColor: F5_TOOL_BORDER_COLOR }, uiTheme);
+			},
+			invalidate() {
+				outputBlock.invalidate();
+			},
+		};
+	},
+
+	mergeCallAndResult: true,
+	inline: true,
+};

package/src/tools/sf.ts

@@ -12,7 +12,14 @@ import sfQueryDescription from "../prompts/tools/sf-query.md" with { type: "text
 import sfSetupDescription from "../prompts/tools/sf-setup.md" with { type: "text" };
 import type { ToolSession } from ".";
 import type { SfExecApi } from "./sf/exec";
-import { execSfJson, execSfRaw } from "./sf/exec";
+import {
+	execSfJson,
+	execSfRaw,
+	SfAuthError,
+	SfNoDefaultOrgError,
+	SfQueryError,
+	SfSessionExpiredError,
+} from "./sf/exec";
 import { formatOrgDetail, formatOrgTable, formatQueryResults } from "./sf/formatters";
 import type { SfOrg, SfQueryResult, SfRawResult } from "./sf/types";
 import { ORG_ALIAS_PATTERN } from "./sf/types";
@@ -80,15 +87,34 @@ type SfSetupInput = Static<typeof sfSetupSchema>;
 type SfQueryInput = Static<typeof sfQuerySchema>;
 type SfOrgDisplayInput = Static<typeof sfOrgDisplaySchema>;
 
-interface SfToolDetails {
+export type SfErrorType = "auth_required" | "session_expired" | "no_default_org" | "invalid_query" | "exec_error";
+
+export interface SfToolDetails {
+	tool: "sf_setup" | "sf_query" | "sf_org_display";
+	action?: string;
 	orgs?: SfOrg[];
 	queryResult?: SfQueryResult;
+	errorType?: SfErrorType;
 }
 
-function textResult(text: string, details?: SfToolDetails): AgentToolResult<SfToolDetails> {
+type SfResult = AgentToolResult<SfToolDetails> & { isError?: boolean };
+
+function textResult(text: string, details: SfToolDetails): SfResult {
 	return { content: [{ type: "text", text }], details };
 }
 
+function errorResult(text: string, details: SfToolDetails): SfResult {
+	return { content: [{ type: "text", text }], isError: true, details };
+}
+
+function detectErrorType(err: unknown): SfErrorType {
+	if (err instanceof SfAuthError) return "auth_required";
+	if (err instanceof SfSessionExpiredError) return "session_expired";
+	if (err instanceof SfNoDefaultOrgError) return "no_default_org";
+	if (err instanceof SfQueryError) return "invalid_query";
+	return "exec_error";
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
 export function normalizeOrg(raw: Record<string, unknown>): SfOrg {
@@ -150,65 +176,76 @@ export class SfSetupTool implements AgentTool<typeof sfSetupSchema, SfToolDetail
 		signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<SfToolDetails>,
 		_context?: AgentToolContext,
-	): Promise<AgentToolResult<SfToolDetails>> {
+	): Promise<SfResult> {
 		const api = this.#testApi ?? makeExecApi(this.session.cwd);
+		const base = { tool: "sf_setup" as const, action: params.action };
 
-		switch (params.action) {
-			case "check": {
-				const result = await execSfRaw(api, ["--version"], signal);
-				return textResult(`sf is installed: ${result.stdout}`);
-			}
-
-			case "status": {
-				const orgResult = await execSfJson(api, ["org", "list"], signal);
-				const allOrgs = collectAllOrgs(orgResult.result as Record<string, unknown[]>);
-				let output = formatOrgTable(allOrgs);
-
-				const userProfile = await loadProfile();
-				if (userProfile.givenName || userProfile.familyName) {
-					const name = [userProfile.givenName, userProfile.familyName].filter(Boolean).join(" ");
-					output += `\n\nUser profile: **${name}** (${userProfile.email ?? "no email"})`;
+		try {
+			switch (params.action) {
+				case "check": {
+					const result = await execSfRaw(api, ["--version"], signal);
+					return textResult(`sf is installed: ${result.stdout}`, base);
 				}
 
-				return textResult(output, { orgs: allOrgs });
-			}
+				case "status": {
+					const orgResult = await execSfJson(api, ["org", "list"], signal);
+					const allOrgs = collectAllOrgs(orgResult.result as Record<string, unknown[]>);
+					let output = formatOrgTable(allOrgs);
 
-			case "login": {
-				const orgResult = await execSfJson(api, ["org", "list"], signal);
-				const allOrgs = collectAllOrgs(orgResult.result as Record<string, unknown[]>);
-				if (allOrgs.length > 0) {
-					return textResult("Already authenticated. Use 'status' action to see your orgs and profile.", {
-						orgs: allOrgs,
-					});
-				}
-				return textResult(
-					"No authenticated orgs found.\n\nRun one of these commands to authenticate:\n" +
-						"- **Workstation**: `sf org login web --set-default --alias SFDC`\n" +
-						'- **Container**: `echo "$SFDX_AUTH_URL" | sf org login sfdx-url --sfdx-url-stdin=- --set-default --alias f5`\n\n' +
-						"After authenticating, call sf_setup with action 'status' to confirm.",
-				);
-			}
+					const userProfile = await loadProfile();
+					if (userProfile.givenName || userProfile.familyName) {
+						const name = [userProfile.givenName, userProfile.familyName].filter(Boolean).join(" ");
+						output += `\n\nUser profile: **${name}** (${userProfile.email ?? "no email"})`;
+					}
 
-			case "list_orgs": {
-				const orgResult = await execSfJson(api, ["org", "list"], signal);
-				const allOrgs = collectAllOrgs(orgResult.result as Record<string, unknown[]>);
-				return textResult(formatOrgTable(allOrgs), { orgs: allOrgs });
-			}
-
-			case "set_default": {
-				if (!params.org) {
-					return textResult("Error: org parameter is required for set_default action.");
+					return textResult(output, { ...base, orgs: allOrgs });
 				}
-				if (!ORG_ALIAS_PATTERN.test(params.org)) {
+
+				case "login": {
+					const orgResult = await execSfJson(api, ["org", "list"], signal);
+					const allOrgs = collectAllOrgs(orgResult.result as Record<string, unknown[]>);
+					if (allOrgs.length > 0) {
+						return textResult("Already authenticated. Use 'status' action to see your orgs and profile.", {
+							...base,
+							orgs: allOrgs,
+						});
+					}
 					return textResult(
-						`Error: invalid org alias "${params.org}". Only alphanumeric characters, dots, underscores, hyphens, and @ are allowed.`,
+						"No authenticated orgs found.\n\nRun one of these commands to authenticate:\n" +
+							"- **Workstation**: `sf org login web --set-default --alias SFDC`\n" +
+							'- **Container**: `echo "$SFDX_AUTH_URL" | sf org login sfdx-url --sfdx-url-stdin=- --set-default --alias f5`\n\n' +
+							"After authenticating, call sf_setup with action 'status' to confirm.",
+						base,
 					);
 				}
-				await execSfRaw(api, ["config", "set", "target-org", params.org, "--global"], signal);
-				return textResult(`Default org set to: **${params.org}**`);
+
+				case "list_orgs": {
+					const orgResult = await execSfJson(api, ["org", "list"], signal);
+					const allOrgs = collectAllOrgs(orgResult.result as Record<string, unknown[]>);
+					return textResult(formatOrgTable(allOrgs), { ...base, orgs: allOrgs });
+				}
+
+				case "set_default": {
+					if (!params.org) {
+						return errorResult("Error: org parameter is required for set_default action.", base);
+					}
+					if (!ORG_ALIAS_PATTERN.test(params.org)) {
+						return errorResult(
+							`Error: invalid org alias "${params.org}". Only alphanumeric characters, dots, underscores, hyphens, and @ are allowed.`,
+							base,
+						);
+					}
+					await execSfRaw(api, ["config", "set", "target-org", params.org, "--global"], signal);
+					return textResult(`Default org set to: **${params.org}**`, base);
+				}
+
+				default:
+					return textResult(`Unknown action: ${params.action}`, base);
 			}
-			default:
-				return textResult(`Unknown action: ${params.action}`);
+		} catch (err) {
+			const errorType = detectErrorType(err);
+			const message = err instanceof Error ? err.message : String(err);
+			return errorResult(message, { ...base, errorType });
 		}
 	}
 }
@@ -240,41 +277,42 @@ export class SfQueryTool implements AgentTool<typeof sfQuerySchema, SfToolDetail
 		signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<SfToolDetails>,
 		_context?: AgentToolContext,
-	): Promise<AgentToolResult<SfToolDetails>> {
+	): Promise<SfResult> {
 		const api = this.#testApi ?? makeExecApi(this.session.cwd);
+		const base = { tool: "sf_query" as const, action: "query" };
 
 		if (params.target_org && !ORG_ALIAS_PATTERN.test(params.target_org)) {
-			return textResult(
+			return errorResult(
 				`Error: invalid org alias "${params.target_org}". Only alphanumeric characters, dots, underscores, hyphens, and @ are allowed.`,
+				base,
 			);
 		}
 
 		const args = ["data", "query", "--query", params.query];
-		if (params.target_org) {
-			args.push("--target-org", params.target_org);
-		}
-		if (params.use_tooling_api) {
-			args.push("--use-tooling-api");
-		}
-		if (params.all_rows) {
-			args.push("--all-rows");
-		}
-
-		const result = await execSfJson(api, args, signal, params.query);
-		const queryData = result.result as SfQueryResult<Record<string, unknown>>;
-
-		const queryResult: SfQueryResult = {
-			totalSize: queryData.totalSize ?? 0,
-			done: queryData.done ?? true,
-			records: queryData.records ?? [],
-		};
+		if (params.target_org) args.push("--target-org", params.target_org);
+		if (params.use_tooling_api) args.push("--use-tooling-api");
+		if (params.all_rows) args.push("--all-rows");
+
+		try {
+			const result = await execSfJson(api, args, signal, params.query);
+			const queryData = result.result as SfQueryResult<Record<string, unknown>>;
+			const queryResult: SfQueryResult = {
+				totalSize: queryData.totalSize ?? 0,
+				done: queryData.done ?? true,
+				records: queryData.records ?? [],
+			};
 
-		let output = formatQueryResults(queryResult);
-		if (!queryResult.done) {
-			output +=
-				"\n\n**Warning**: Results are incomplete. The query returned more records than the API limit. Use `sf data export bulk` for the full dataset.";
+			let output = formatQueryResults(queryResult);
+			if (!queryResult.done) {
+				output +=
+					"\n\n**Warning**: Results are incomplete. The query returned more records than the API limit. Use `sf data export bulk` for the full dataset.";
+			}
+			return textResult(output, { ...base, queryResult });
+		} catch (err) {
+			const errorType = detectErrorType(err);
+			const message = err instanceof Error ? err.message : String(err);
+			return errorResult(message, { ...base, errorType });
 		}
-		return textResult(output, { queryResult });
 	}
 }
 
@@ -305,34 +343,40 @@ export class SfOrgDisplayTool implements AgentTool<typeof sfOrgDisplaySchema, Sf
 		signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<SfToolDetails>,
 		_context?: AgentToolContext,
-	): Promise<AgentToolResult<SfToolDetails>> {
+	): Promise<SfResult> {
 		const api = this.#testApi ?? makeExecApi(this.session.cwd);
+		const base = { tool: "sf_org_display" as const };
 
 		if (params.target_org && !ORG_ALIAS_PATTERN.test(params.target_org)) {
-			return textResult(
+			return errorResult(
 				`Error: invalid org alias "${params.target_org}". Only alphanumeric characters, dots, underscores, hyphens, and @ are allowed.`,
+				base,
 			);
 		}
 
 		const args = ["org", "display"];
-		if (params.target_org) {
-			args.push("--target-org", params.target_org);
-		}
+		if (params.target_org) args.push("--target-org", params.target_org);
+
+		try {
+			const result = await execSfJson(api, args, signal);
+			const raw = result.result as Record<string, unknown>;
+
+			// SECURITY: only extract whitelisted fields
+			const org: SfOrg = {
+				username: String(raw.username ?? ""),
+				orgId: String(raw.id ?? raw.orgId ?? ""),
+				instanceUrl: String(raw.instanceUrl ?? ""),
+				connectedStatus: String(raw.connectedStatus ?? "Connected"),
+				alias: raw.alias ? String(raw.alias) : undefined,
+				isDefault: false,
+				isSandbox: Boolean(raw.isSandbox ?? false),
+			};
 
-		const result = await execSfJson(api, args, signal);
-		const raw = result.result as Record<string, unknown>;
-
-		// SECURITY: only extract whitelisted fields
-		const org: SfOrg = {
-			username: String(raw.username ?? ""),
-			orgId: String(raw.id ?? raw.orgId ?? ""),
-			instanceUrl: String(raw.instanceUrl ?? ""),
-			connectedStatus: String(raw.connectedStatus ?? "Connected"),
-			alias: raw.alias ? String(raw.alias) : undefined,
-			isDefault: false,
-			isSandbox: Boolean(raw.isSandbox ?? false),
-		};
-
-		return textResult(formatOrgDetail(org), { orgs: [org] });
+			return textResult(formatOrgDetail(org), { ...base, orgs: [org] });
+		} catch (err) {
+			const errorType = detectErrorType(err);
+			const message = err instanceof Error ? err.message : String(err);
+			return errorResult(message, { ...base, errorType });
+		}
 	}
 }

package/src/tools/xcsh-api-renderer.ts

@@ -5,7 +5,13 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme, ThemeColor } from "../modes/theme/theme";
 import { highlightCode } from "../modes/theme/theme";
 import { CachedOutputBlock, F5_TOOL_BORDER_COLOR, renderStatusLine } from "../tui";
-import { formatErrorMessage, replaceTabs } from "./render-utils";
+import {
+	formatErrorMessage,
+	formatTimestamp,
+	addSection as pushSection,
+	replaceTabs,
+	stripEmpty,
+} from "./render-utils";
 import type { XcshApiToolDetails } from "./xcsh-api";
 
 const TOOL_TITLE = "XC-API";
@@ -31,30 +37,6 @@ function statusColor(status: number): ThemeColor {
 	return status < 300 ? "success" : status < 400 ? "warning" : "error";
 }
 
-/**
- * Strip null, empty string, and empty array fields recursively.
- * Preserves empty objects `{}` — these are F5 XC protobuf oneof presence markers
- * (e.g. `use_origin_server_name: {}` means that option is selected).
- */
-function stripEmpty(obj: unknown): unknown {
-	if (Array.isArray(obj)) return obj.map(stripEmpty).filter(v => v != null);
-	if (obj && typeof obj === "object") {
-		const entries = Object.entries(obj as Record<string, unknown>);
-		// Preserve source-empty objects (F5 XC oneof presence markers)
-		if (entries.length === 0) return obj;
-		const out: Record<string, unknown> = {};
-		for (const [k, v] of entries) {
-			if (v == null || v === "" || (Array.isArray(v) && v.length === 0)) continue;
-			const cleaned = stripEmpty(v);
-			if (cleaned != null) out[k] = cleaned;
-		}
-		return Object.keys(out).length > 0 ? out : null;
-	}
-	return obj;
-}
-function formatTimestamp(iso: string): string {
-	return iso.replace("T", " ").replace(/:\d{2}(\.\d+)?Z$/, " UTC");
-}
 function stripProtobufPrefix(message: string): string {
 	return message.replace(/^ves\.io\.schema\.\S+:\s*/i, "");
 }
@@ -247,14 +229,7 @@ export const xcshApiToolRenderer = {
 		const sections: Array<{ label?: string; lines: string[] }> = [];
 
 		const addSection = (label: string, lines: string[], maxLines?: number): void => {
-			const titled = uiTheme.fg("toolTitle", label);
-			if (maxLines && lines.length > maxLines) {
-				const truncated = lines.slice(0, maxLines);
-				truncated.push(uiTheme.fg("dim", `… ${lines.length - maxLines} more lines`));
-				sections.push({ label: titled, lines: truncated });
-			} else {
-				sections.push({ label: titled, lines });
-			}
+			pushSection(sections, label, lines, uiTheme, maxLines);
 		};
 
 		// Section: Request payload — show resolved body (actual JSON sent to API)