@f5xc-salesdemos/xcsh 18.66.2 → 18.69.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.66.2",
+	"version": "18.69.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.69.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.69.0",
+		"@f5xc-salesdemos/pi-ai": "18.69.0",
+		"@f5xc-salesdemos/pi-natives": "18.69.0",
+		"@f5xc-salesdemos/pi-tui": "18.69.0",
+		"@f5xc-salesdemos/pi-utils": "18.69.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.69.0",
+	"commit": "309ca5b1b28a5530f01b83381e69f8a6c94f83c8",
+	"shortCommit": "309ca5b",
 	"branch": "main",
-	"tag": "v18.66.2",
-	"commitDate": "2026-05-18T07:27:11Z",
-	"buildDate": "2026-05-18T07:51:19.009Z",
+	"tag": "v18.69.0",
+	"commitDate": "2026-05-18T23:00:56Z",
+	"buildDate": "2026-05-18T23:27:04.429Z",
 	"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/309ca5b1b28a5530f01b83381e69f8a6c94f83c8",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.69.0"
 };

package/src/pipeline-report/benchmark.ts

@@ -0,0 +1,405 @@
+/**
+ * pipeline-report/benchmark.ts
+ *
+ * Autoresearch benchmark harness for the pipeline report.
+ * Generates a real pipeline report against the live Salesforce org
+ * and scores it deterministically across 6 quality dimensions.
+ *
+ * Primary metric: report_quality_score (0–100, higher is better)
+ *
+ * OFF LIMITS to autoresearch modifications — this is the ground-truth evaluator.
+ */
+
+import { loadSalesforceContext } from "../internal-urls/salesforce-context";
+import { loadProfile } from "../internal-urls/user-profile";
+import { generatePipelineReport } from "./generator";
+import { renderPipelineReport } from "./renderer";
+import type { PipelineReportData } from "./types";
+
+// ─── Fiscal quarter helpers ───────────────────────────────────────────
+// F5 fiscal year starts November 1. Quarters:
+//   Q1: Nov–Jan   Q2: Feb–Apr   Q3: May–Jul   Q4: Aug–Oct
+
+function fiscalQuarterDates(): { start: string; end: string } {
+	const now = new Date();
+	const m = now.getMonth(); // 0-indexed
+	const y = now.getFullYear();
+
+	let start: Date;
+	let end: Date;
+
+	if (m >= 10) {
+		// Nov–Dec → Q1 starts this year Nov, ends Jan next year
+		start = new Date(y, 10, 1);
+		end = new Date(y + 1, 1, 0);
+	} else if (m === 0) {
+		// Jan → still Q1 (Nov prev year – Jan this year)
+		start = new Date(y - 1, 10, 1);
+		end = new Date(y, 1, 0);
+	} else if (m <= 3) {
+		// Feb–Apr → Q2
+		start = new Date(y, 1, 1);
+		end = new Date(y, 4, 0);
+	} else if (m <= 6) {
+		// May–Jul → Q3
+		start = new Date(y, 4, 1);
+		end = new Date(y, 7, 0);
+	} else {
+		// Aug–Oct → Q4
+		start = new Date(y, 7, 1);
+		end = new Date(y, 10, 0);
+	}
+
+	const fmt = (d: Date) => d.toISOString().split("T")[0]!;
+	return { start: fmt(start), end: fmt(end) };
+}
+
+// ─── Scoring helpers ──────────────────────────────────────────────────
+
+interface DimScore {
+	score: number;
+	max: number;
+	notes: string[];
+}
+
+function scoreSectionPresence(report: string): DimScore {
+	const checks: Array<{ re: RegExp; label: string; pts: number }> = [
+		{ re: /^# F5 Distributed Cloud Pipeline Report/m, label: "report header", pts: 2 },
+		{ re: /\*\*Generated:\*\*/m, label: "generated timestamp", pts: 2 },
+		{ re: /\*\*Quarter:\*\*/m, label: "quarter range", pts: 2 },
+		{ re: /\*\*Summary:\*\*/m, label: "executive summary", pts: 3 },
+		{ re: /Closed.*Booked/m, label: "booked section", pts: 3 },
+		{ re: /Open Pipeline.*Net New/m, label: "net new section", pts: 3 },
+		{ re: /Open Pipeline.*Renewals/m, label: "renewals section", pts: 3 },
+		{ re: /Forecast Summary/m, label: "forecast summary", pts: 3 },
+		{ re: /\*\*Line items:\*\*/m, label: "line item count", pts: 1 },
+		{ re: /\*\*SKUs:\*\*/m, label: "SKU count", pts: 1 },
+		{ re: /\*\*Model:\*\*/m, label: "value model description", pts: 1 },
+	];
+	let score = 0;
+	let max = 0;
+	const notes: string[] = [];
+	for (const c of checks) {
+		max += c.pts;
+		if (c.re.test(report)) {
+			score += c.pts;
+		} else {
+			notes.push(`Missing: ${c.label}`);
+		}
+	}
+	return { score, max, notes };
+}
+
+function scoreDollarFormatting(report: string): DimScore {
+	const notes: string[] = [];
+	let score = 0;
+	const max = 20;
+
+	// Compact dollar amounts in summaries ($1.2M, $45K)
+	if (/\$[\d,.]+[MK]\b/.test(report)) {
+		score += 5;
+	} else {
+		notes.push("No compact dollar amounts ($XM/$XK) in summary lines");
+	}
+
+	// Precise dollar amounts in tables (1,234.56)
+	if (/[\d,]+\.\d{2}/.test(report)) {
+		score += 5;
+	} else {
+		notes.push("No precise dollar amounts (X,XXX.XX) in tables");
+	}
+
+	// Em-dash (—) for zero values instead of literal $0
+	if (/\|\s*—\s*\|/.test(report)) {
+		score += 3;
+	}
+
+	// No unformatted large numbers in table context
+	const rawLarge = [...(report.matchAll(/(?<!\$)(?<!\d[,.])\b\d{5,}\b(?!\.\d{2})(?![MK%])/g) ?? [])].filter(m => {
+		const ctx = report.slice(Math.max(0, m.index! - 20), m.index! + m[0].length + 20);
+		return ctx.includes("|");
+	});
+	if (rawLarge.length === 0) {
+		score += 4;
+	} else {
+		notes.push(`${rawLarge.length} unformatted large number(s) in table context`);
+	}
+
+	// No undefined/null/NaN in output
+	const badValues = (report.match(/\bundefined\b|\bnull\b|\bNaN\b/g) ?? []).length;
+	if (badValues === 0) {
+		score += 3;
+	} else {
+		notes.push(`${badValues} occurrence(s) of undefined/null/NaN in output`);
+	}
+
+	return { score, max, notes };
+}
+
+function scoreDateFormatting(report: string): DimScore {
+	const notes: string[] = [];
+	let score = 0;
+	const max = 10;
+
+	// Generated timestamp: human-readable, not raw ISO
+	const generatedMatch = report.match(/\*\*Generated:\*\*\s*(.+)/);
+	if (generatedMatch) {
+		const d = generatedMatch[1]!.trim();
+		if (/^\d{4}-\d{2}-\d{2}T/.test(d)) {
+			notes.push("Generated date uses raw ISO 8601 (should be locale string)");
+		} else {
+			score += 3;
+		}
+	}
+
+	// Quarter line present and reasonably readable
+	const quarterMatch = report.match(/\*\*Quarter:\*\*\s*(.+)/);
+	if (quarterMatch) {
+		score += quarterMatch[1]!.includes("-") ? 3 : 4;
+	}
+
+	// No raw ISO timestamps (2026-05-18T...) in the report body
+	const rawTs = (report.match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/g) ?? []).length;
+	if (rawTs === 0) {
+		score += 3;
+	} else {
+		notes.push(`${rawTs} raw ISO timestamp(s) in report body`);
+	}
+
+	return { score, max, notes };
+}
+
+function scoreTableQuality(report: string): DimScore {
+	const notes: string[] = [];
+	let score = 0;
+	const max = 15;
+
+	const tables = report.match(/\|.+\|[\n\r]+\|[-:|]+\|/g) ?? [];
+	if (tables.length === 0) {
+		notes.push("No properly formatted markdown tables found");
+		return { score: 0, max, notes };
+	}
+	score += 3;
+
+	// All tables have separator rows (already implied by regex, this checks alignment chars)
+	const hasRightAlign = /---:\|/.test(report);
+	if (hasRightAlign) {
+		score += 3;
+	} else {
+		notes.push("No right-aligned columns (amounts should be right-aligned with ---:|)");
+	}
+
+	// Tables have left-aligned label columns
+	if (/:---\|/.test(report)) {
+		score += 3;
+	}
+
+	// Territory grouping separators (bold em-dash rows)
+	if (/\*\*.*—.*\*\*/.test(report)) {
+		score += 3;
+	}
+
+	// Total rows (bold)
+	if (/\|\s*\*\*Total\*\*\s*\|/.test(report)) {
+		score += 3;
+	} else {
+		notes.push("No bold Total rows in tables");
+	}
+
+	return { score, max, notes };
+}
+
+function scoreDataDensity(data: PipelineReportData, report: string): DimScore {
+	const notes: string[] = [];
+	let score = 0;
+	const max = 20;
+
+	if (data.lineItemCount > 0) {
+		score += 4;
+	} else {
+		notes.push("Zero line items processed");
+	}
+
+	const totalAccounts = data.netNew.accounts.length + data.booked.accounts.length + data.renewals.accounts.length;
+	if (totalAccounts > 0) {
+		score += 4;
+	} else {
+		notes.push("No accounts in any section");
+	}
+
+	const fc = data.forecast;
+	const fcCount = [fc.commit, fc.bestCase, fc.pipeline].filter(v => v > 0).length;
+	score += Math.min(5, fcCount * 2);
+	if (fcCount === 0) {
+		notes.push("No forecast category amounts populated");
+	}
+
+	if (data.skusFound.length > 0) {
+		score += 3;
+	} else {
+		notes.push("No SKUs discovered");
+	}
+
+	// Anomaly detection running (even 0 anomalies means the engine ran)
+	score += 2;
+	if (data.anomalies.length > 0 && /Data Quality/.test(report)) {
+		score += 2;
+	}
+
+	return { score, max, notes };
+}
+
+function scoreInformationValue(report: string): DimScore {
+	const notes: string[] = [];
+	let score = 0;
+	const max = 10;
+
+	// Quota total callouts (actionable for sales professionals)
+	if (/Quota Total/i.test(report)) {
+		score += 3;
+	} else {
+		notes.push("No quota total callouts");
+	}
+
+	// Forecast category breakdown visible (Commit, Best Case, Pipeline)
+	if (/Commit/m.test(report) && /Best Case/m.test(report)) {
+		score += 2;
+	}
+
+	// Platform vs Point product split (critical for overlay SE reporting)
+	if (/Platform.*Distributed Cloud/m.test(report) || /Point.*Shape/m.test(report)) {
+		score += 3;
+	} else {
+		notes.push("Platform/Point product split not visible");
+	}
+
+	// Territory context present
+	if (/Territories:/m.test(report) || /Territory/m.test(report)) {
+		score += 2;
+	}
+
+	return { score, max, notes };
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────
+
+const profile = await loadProfile();
+const sfContext = await loadSalesforceContext();
+
+if (!profile.identifiers?.salesforceId) {
+	console.error("ERROR: No salesforceId in user profile. Run: xcsh://salesforce?refresh=true");
+	process.exit(1);
+}
+
+if (!sfContext) {
+	console.error("ERROR: No cached Salesforce context. Run: xcsh://salesforce?refresh=true");
+	process.exit(1);
+}
+
+const userId = profile.identifiers.salesforceId;
+const partnerId = profile.partner?.id;
+const userIds = partnerId ? [userId, partnerId] : [userId];
+const { start, end } = fiscalQuarterDates();
+
+// Stale cutoff: 12 months ago to include non-stale pipeline beyond current quarter
+const staleDate = new Date();
+staleDate.setFullYear(staleDate.getFullYear() - 1);
+const staleCutoff = staleDate.toISOString().split("T")[0]!;
+
+const partnerName = profile.partner?.name;
+const selfName = [profile.givenName, profile.familyName].filter(Boolean).join(" ").trim();
+const teamMemberNames = partnerName && selfName ? [selfName, partnerName] : undefined;
+
+const options = {
+	userIds,
+	orgAlias: sfContext.orgAlias,
+	quarterStart: start,
+	quarterEnd: end,
+	staleCutoff,
+	confirmedTerritories: profile.territories ?? sfContext.confirmedTerritories ?? sfContext.territories,
+	teamMemberNames,
+};
+
+// ─── Generate and time ────────────────────────────────────────────────
+
+const genStart = performance.now();
+const data = await generatePipelineReport(options);
+const generateMs = Math.round(performance.now() - genStart);
+
+const renderStart = performance.now();
+const report = renderPipelineReport(data, sfContext.instanceUrl);
+const renderMs = Math.round(performance.now() - renderStart);
+
+const totalMs = generateMs + renderMs;
+
+// ─── Score ────────────────────────────────────────────────────────────
+
+const sections = scoreSectionPresence(report);
+const dollars = scoreDollarFormatting(report);
+const dates = scoreDateFormatting(report);
+const tables = scoreTableQuality(report);
+const density = scoreDataDensity(data, report);
+const infoVal = scoreInformationValue(report);
+
+const rawScore = sections.score + dollars.score + dates.score + tables.score + density.score + infoVal.score;
+const rawMax = sections.max + dollars.max + dates.max + tables.max + density.max + infoVal.max;
+const qualityScore = Math.round((rawScore / rawMax) * 100);
+
+const dataCompletenessPct = Math.round(
+	([
+		data.generated,
+		data.quarter.start,
+		data.quarter.end,
+		data.lineItemCount > 0,
+		data.skusFound.length > 0,
+		data.netNew.accounts.length > 0 || data.booked.accounts.length > 0,
+		data.forecast.commit > 0 || data.forecast.bestCase > 0 || data.forecast.pipeline > 0,
+		data.territories.length > 0,
+	].filter(Boolean).length /
+		8) *
+		100,
+);
+
+// Baseline generator makes 3 queries: net new + booked (parallel) + renewals (sequential)
+const queryCount = 3;
+
+const totalAccounts = data.netNew.accounts.length + data.booked.accounts.length + data.renewals.accounts.length;
+
+// ─── Output METRIC lines ──────────────────────────────────────────────
+
+console.log(`METRIC report_quality_score=${qualityScore}`);
+console.log(`METRIC query_count=${queryCount}`);
+console.log(`METRIC total_time_ms=${totalMs}`);
+console.log(`METRIC generate_time_ms=${generateMs}`);
+console.log(`METRIC render_time_ms=${renderMs}`);
+console.log(`METRIC data_completeness_pct=${dataCompletenessPct}`);
+console.log(`METRIC section_score=${sections.score}`);
+console.log(`METRIC dollar_format_score=${dollars.score}`);
+console.log(`METRIC date_format_score=${dates.score}`);
+console.log(`METRIC table_alignment_score=${tables.score}`);
+console.log(`METRIC data_density_score=${density.score}`);
+console.log(`METRIC info_value_score=${infoVal.score}`);
+console.log(`METRIC line_item_count=${data.lineItemCount}`);
+console.log(`METRIC account_count=${totalAccounts}`);
+console.log(`METRIC report_length=${report.length}`);
+console.log(
+	`ASI scoring_breakdown={"sections":${sections.score}/${sections.max},"dollars":${dollars.score}/${dollars.max},"dates":${dates.score}/${dates.max},"tables":${tables.score}/${tables.max},"density":${density.score}/${density.max},"infoValue":${infoVal.score}/${infoVal.max},"total":${rawScore}/${rawMax}}`,
+);
+
+const allNotes = [
+	...sections.notes.map(n => `[sections] ${n}`),
+	...dollars.notes.map(n => `[dollars] ${n}`),
+	...dates.notes.map(n => `[dates] ${n}`),
+	...tables.notes.map(n => `[tables] ${n}`),
+	...density.notes.map(n => `[density] ${n}`),
+	...infoVal.notes.map(n => `[info-value] ${n}`),
+];
+
+if (allNotes.length > 0) {
+	console.log(`ASI deduction_notes=${JSON.stringify(allNotes)}`);
+	console.log("");
+	console.log("Deduction notes:");
+	for (const note of allNotes) {
+		console.log(`  - ${note}`);
+	}
+}

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)