@f5xc-salesdemos/xcsh 18.58.1 → 18.59.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.58.1",
+	"version": "18.59.1",
 	"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.58.1",
-		"@f5xc-salesdemos/pi-agent-core": "18.58.1",
-		"@f5xc-salesdemos/pi-ai": "18.58.1",
-		"@f5xc-salesdemos/pi-natives": "18.58.1",
-		"@f5xc-salesdemos/pi-tui": "18.58.1",
-		"@f5xc-salesdemos/pi-utils": "18.58.1",
+		"@f5xc-salesdemos/xcsh-stats": "18.59.1",
+		"@f5xc-salesdemos/pi-agent-core": "18.59.1",
+		"@f5xc-salesdemos/pi-ai": "18.59.1",
+		"@f5xc-salesdemos/pi-natives": "18.59.1",
+		"@f5xc-salesdemos/pi-tui": "18.59.1",
+		"@f5xc-salesdemos/pi-utils": "18.59.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/autoresearch/tools/log-experiment.ts

@@ -372,7 +372,7 @@ export function createLogExperimentTool(
 		},
 		renderResult(result, _options, theme): Component {
 			const details = result.details;
-			if (!details) {
+			if (!isLogDetails(details)) {
 				return new Text(replaceTabs(result.content.find(part => part.type === "text")?.text ?? ""), 0, 0);
 			}
 			return {
@@ -770,8 +770,16 @@ function truncateAsiValue(value: ASIData[string]): string {
 	return text.length > 120 ? `${text.slice(0, 117)}...` : text;
 }
 
+function isLogDetails(value: unknown): value is LogDetails {
+	if (typeof value !== "object" || value === null) return false;
+	return "experiment" in value && "state" in value;
+}
+
 function renderSummary(details: LogDetails, theme: Theme, width?: number): string {
 	const { experiment, state } = details;
+	if (!experiment || !state) {
+		return theme.fg("dim", "(no experiment data)");
+	}
 	const color = experiment.status === "keep" ? "success" : experiment.status === "discard" ? "warning" : "error";
 	let summary = `${theme.fg(color, experiment.status.toUpperCase())} ${theme.fg("muted", truncateToWidth(replaceTabs(experiment.description ?? ""), Math.max(20, (width ?? 100) - 30)))}`;
 	summary += ` ${theme.fg("contentAccent", `${state.metricName}=${formatNum(experiment.metric, state.metricUnit)}`)}`;

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.58.1",
-	"commit": "771846c0cfc096fabe25f46e54af5ad4660a650d",
-	"shortCommit": "771846c",
+	"version": "18.59.1",
+	"commit": "fa007898365b1a63e38748e06d2c86c13779ff53",
+	"shortCommit": "fa00789",
 	"branch": "main",
-	"tag": "v18.58.1",
-	"commitDate": "2026-05-10T05:27:47Z",
-	"buildDate": "2026-05-10T05:46:22.190Z",
+	"tag": "v18.59.1",
+	"commitDate": "2026-05-10T17:48:40Z",
+	"buildDate": "2026-05-10T18:15:56.886Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/771846c0cfc096fabe25f46e54af5ad4660a650d",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.58.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/fa007898365b1a63e38748e06d2c86c13779ff53",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.59.1"
 };

package/src/prompts/tools/xcsh-api.md

@@ -14,4 +14,12 @@ Payload values like `$F5XC_NAMESPACE` are auto-expanded from the active context.
 
 Use this tool after reading the API catalog to get the endpoint path and payload structure.
 
+Response format:
+- **List**: `{"items": […], "errors": []}` — each item has `name`, `namespace`, `uid`.
+- **Single resource**: `{"metadata": {"name", "namespace"}, "system_metadata": {"uid", "creation_timestamp"}, "spec": {…}}` — noise-reduced in TUI (nulls/empties stripped).
+- **Create/Update**: Returns the full resource object. TUI shows a Created/Updated summary with name, uid, timestamp.
+- **Delete**: Returns `{}`. TUI shows contextual confirmation.
+- **Error**: `{"code": <int>, "message": "…"}` — codes: 3=INVALID_ARGUMENT, 5=NOT_FOUND, 6=ALREADY_EXISTS, 7=PERMISSION_DENIED, 13=INTERNAL.
+
+GET requests auto-retry once on transient errors (429/503) after 1s backoff. POST/PUT/DELETE are never retried.
 API calls to the same F5 XC tenant reuse a single TLS connection — sequential calls are faster than parallel calls. Do not issue multiple xcsh_api calls in the same turn; issue them one at a time.

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

@@ -2,16 +2,19 @@
  * TUI renderer for the xcsh_api tool.
  *
  * Provides rich, context-aware visualization for F5 XC API calls:
- * - renderCall: method badge + path while request is pending
- * - renderResult: bordered output block with syntax-highlighted JSON body,
- *   request details section, and error guidance section
+ * - renderCall: method badge + compact path while request is pending
+ * - renderResult: bordered output with intelligent response rendering:
+ *   - List responses: compact resource name summary (capped at 20 items)
+ *   - Single resources: Summary section (name, uid, created, status) + noise-reduced JSON
+ *   - Create/Update: Created/Updated confirmation with key identity fields
+ *   - Delete: contextual success message with resource name
+ *   - Errors: API error message promoted to Guidance, JSON body suppressed
+ *   - Request payload section for mutating methods (POST/PUT/PATCH)
  *
- * Uses CachedOutputBlock for bordered rendering with state-colored borders
- * (success → dim, error → red, pending → accent). JSON responses are
- * syntax-highlighted via the native pi-natives highlighter with theme colors.
- *
- * Always renders full output — no collapsed mode. This is the primary tool
- * for F5 XC platform operations and benefits from full visibility.
+ * Header meta: context name, colored duration, item count, body size, error code label.
+ * Borders: success=dim, error=red, pending=accent.
+ * JSON noise reduction via stripEmpty (nulls, empty strings, empty arrays stripped;
+ * empty objects preserved for F5 XC protobuf oneof markers).
  */
 import type { Component } from "@f5xc-salesdemos/pi-tui";
 import { Text } from "@f5xc-salesdemos/pi-tui";
@@ -24,6 +27,12 @@ import type { XcshApiToolDetails } from "./xcsh-api";
 
 const TOOL_TITLE = "XC-API";
 
+/** Maximum response body lines before truncation. */
+const MAX_RESPONSE_LINES = 80;
+
+/** Maximum request payload lines before truncation. */
+const MAX_PAYLOAD_LINES = 30;
+
 interface XcshApiRenderArgs {
 	method?: string;
 	path?: string;
@@ -50,6 +59,108 @@ function statusColor(status: number): ThemeColor {
 	return "error";
 }
 
+/** Format byte size to human-readable string (e.g. "1.2 KB", "3.4 MB"). */
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Strip null, empty string, and empty array fields recursively.
+ * Reduces JSON noise from F5 XC API responses which contain many null/empty defaults.
+ * 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 === "") continue;
+			if (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;
+}
+
+/** Format ISO timestamp to human-readable: `2026-05-10T00:02:42.577Z` → `2026-05-10 00:02 UTC`. */
+function formatTimestamp(iso: string): string {
+	return iso
+		.replace("T", " ")
+		.replace(/:\d{2}\.\d+Z$/, " UTC")
+		.replace(/:\d{2}Z$/, " UTC");
+}
+
+/** Push a labeled section with optional line truncation. */
+function pushSection(
+	sections: Array<{ label?: string; lines: string[] }>,
+	label: string,
+	lines: string[],
+	maxLines: number,
+	uiTheme: Theme,
+): void {
+	if (lines.length > maxLines) {
+		const truncated = lines.slice(0, maxLines);
+		truncated.push(uiTheme.fg("dim", `… ${lines.length - maxLines} more lines`));
+		sections.push({ label, lines: truncated });
+	} else {
+		sections.push({ label, lines });
+	}
+}
+
+/** Build a compact summary section for a single F5 XC resource (identity + spec). */
+function buildResourceSummary(
+	parsed: Record<string, unknown>,
+	pathParts: string[],
+	method: string,
+	uiTheme: Theme,
+): { label: string; lines: string[] } | null {
+	const metadata = parsed.metadata as Record<string, unknown> | undefined;
+	const sysMeta = parsed.system_metadata as Record<string, unknown> | undefined;
+	if (!metadata || typeof metadata.name !== "string") return null;
+
+	const lines: string[] = [];
+	lines.push(uiTheme.fg("toolOutput", `  name:      ${metadata.name}`));
+	if (typeof metadata.namespace === "string") lines.push(uiTheme.fg("dim", `  namespace: ${metadata.namespace}`));
+	if (typeof sysMeta?.uid === "string") lines.push(uiTheme.fg("dim", `  uid:       ${sysMeta.uid}`));
+	const createdAt = sysMeta?.creation_timestamp;
+	if (typeof createdAt === "string") lines.push(uiTheme.fg("dim", `  created:   ${formatTimestamp(createdAt)}`));
+	if (metadata.disable === true) lines.push(uiTheme.fg("warning", `  status:    DISABLED`));
+
+	// Compact spec line: resource type from path + key config values
+	const spec = parsed.spec;
+	if (spec && typeof spec === "object") {
+		const specEntries = Object.entries(spec as Record<string, unknown>);
+		// Only show spec line when there are actual entries (skip empty spec: {})
+		if (specEntries.length > 0) {
+			const specScalars = specEntries
+				.filter(
+					([, v]) =>
+						typeof v === "number" ||
+						typeof v === "boolean" ||
+						(typeof v === "string" && v.length > 0 && v.length <= 30),
+				)
+				.slice(0, 4)
+				.map(([k, v]) => `${k}=${v}`)
+				.join(", ");
+			const resourceType = (pathParts.at(-2) ?? "config").replace(/_/g, " ").replace(/s$/, "");
+			const specLine = specScalars ? `${resourceType} (${specScalars})` : resourceType;
+			lines.push(uiTheme.fg("dim", `  spec:      ${specLine}`));
+		}
+	}
+
+	const isMutating = method === "POST" || method === "PUT" || method === "PATCH";
+	const label = isMutating ? (method === "POST" ? "Created" : "Updated") : "Summary";
+	return { label: uiTheme.fg("toolTitle", label), lines };
+}
+
 /**
  * Split the text content from the tool result into its constituent parts.
  *
@@ -103,11 +214,14 @@ export const xcshApiToolRenderer = {
 	renderCall(args: XcshApiRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const method = args.method ?? "???";
 		const apiPath = args.path ?? "…";
+		// Compact long paths for pending state consistency with result header
+		const parts = apiPath.split("/").filter(Boolean);
+		const pendingPath = parts.length > 3 ? `…/${parts.slice(-3).join("/")}` : apiPath;
 		const text = renderStatusLine(
 			{
 				icon: "pending",
 				title: TOOL_TITLE,
-				description: apiPath,
+				description: pendingPath,
 				badge: { label: method, color: methodColor(method) },
 			},
 			uiTheme,
@@ -135,6 +249,9 @@ export const xcshApiToolRenderer = {
 				// Malformed URL — fall through to args.path
 			}
 		}
+		// Path intelligence: extract resource name and compact display path
+		const pathParts = displayPath.split("/").filter(Boolean);
+		const resourceName = pathParts.at(-1) ?? "";
 
 		const status = details?.status ?? 0;
 		const statusText = status > 0 ? `${status}` : "failed";
@@ -145,16 +262,36 @@ export const xcshApiToolRenderer = {
 			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
 		}
 
-		// --- Header ---
+		// --- Header with separate method and status badges ---
+		const methodBadge = { label: method, color: methodColor(method) };
+		const errorLabel = details?.errorCodeLabel;
+		const statusDisplay = errorLabel ? `${statusText} ${errorLabel}` : statusText;
+		const statusBadge = uiTheme.fg(status > 0 ? statusColor(status) : "error", `[${statusDisplay}]`);
+
 		const meta: string[] = [];
+		meta.push(statusBadge);
 		if (details?.contextName) meta.push(uiTheme.fg("statusLineContextF5xcFg", details.contextName));
-		if (details?.durationMs !== undefined) meta.push(uiTheme.fg("dim", `${details.durationMs}ms`));
+		if (details?.durationMs !== undefined) {
+			const durationColor: ThemeColor =
+				details.durationMs < 200 ? "success" : details.durationMs > 1000 ? "warning" : "dim";
+			meta.push(uiTheme.fg(durationColor, `${details.durationMs}ms`));
+		}
+		if (details?.itemCount !== undefined) meta.push(uiTheme.fg("dim", `${details.itemCount} items`));
+		if (details?.bodySize !== undefined) meta.push(uiTheme.fg("dim", formatBytes(details.bodySize)));
+		if (details?.contentType && !details.contentType.includes("json"))
+			meta.push(uiTheme.fg("dim", details.contentType));
+		// Show requestId for errors (useful for support/debugging)
+		if (isError && details?.requestId) meta.push(uiTheme.fg("dim", `req:${details.requestId.slice(0, 8)}`));
+		if (details?.retried) meta.push(uiTheme.fg("warning", "retried"));
+
+		const compactPath = pathParts.length > 3 ? `…/${pathParts.slice(-3).join("/")}` : displayPath;
+
 		const header = renderStatusLine(
 			{
 				title: TOOL_TITLE,
 				titleColor: "contentAccent",
-				description: displayPath,
-				badge: { label: `${method} ${statusText}`, color: status > 0 ? statusColor(status) : "error" },
+				description: compactPath,
+				badge: methodBadge,
 				meta: meta.length > 0 ? meta : undefined,
 			},
 			uiTheme,
@@ -165,17 +302,119 @@ export const xcshApiToolRenderer = {
 		const { json, guidance, raw } = splitResultContent(textContent, isError);
 		const sections: Array<{ label?: string; lines: string[] }> = [];
 
-		// Section 1: Request line (method + full resolved URL)
-		const requestLine = url ? `${method} ${url}` : `${method} ${displayPath}`;
-		sections.push({ lines: [uiTheme.fg("dim", requestLine)] });
+		// Section 2: Request payload (for mutating methods with a body)
+		if (args?.payload && method !== "GET") {
+			try {
+				const prettyPayload = JSON.stringify(args.payload, null, 2);
+				const payloadLines = highlightCode(prettyPayload, "json");
+				const sanitized = payloadLines.map(line => replaceTabs(line));
+				// Show expanded variable substitutions
+				if (details?.expandedVars && details.expandedVars.length > 0) {
+					const varLines = details.expandedVars.map(({ variable, value }) =>
+						uiTheme.fg("dim", `  ${variable} → ${value}`),
+					);
+					sanitized.push(...varLines);
+				}
+				pushSection(sections, uiTheme.fg("toolTitle", "Request"), sanitized, MAX_PAYLOAD_LINES, uiTheme);
+			} catch {
+				// Payload not serializable — skip section
+			}
+		}
+
+		// Section: Response body — syntax-highlighted JSON or plain text
+		// Parse JSON once for all intelligence branches
+		const emptyBody = json === "{}" || (!json && (!raw.trim() || raw.trim() === "{}"));
+		let parsed: Record<string, unknown> | null = null;
+		if (json && !emptyBody) {
+			try {
+				parsed = JSON.parse(json) as Record<string, unknown>;
+			} catch {
+				// Not parseable — render raw
+			}
+		}
+		const emptyList = Array.isArray(parsed?.items) && (parsed!.items as unknown[]).length === 0;
 
-		// Section 2: Response body — syntax-highlighted JSON or plain text
-		if (json) {
-			const highlighted = highlightCode(json, "json");
+		if ((emptyBody || emptyList) && !guidance) {
+			// Contextual success message based on HTTP method and response shape
+			let successMessage = emptyList ? "No items found." : "Empty response";
+			const rn = resourceName ? ` \u2018${resourceName}\u2019` : "";
+			if (!emptyList && status >= 200 && status < 300) {
+				if (method === "DELETE") successMessage = `Resource${rn} deleted successfully.`;
+				else if (method === "POST") successMessage = `Resource${rn} created successfully.`;
+				else if (method === "PUT" || method === "PATCH") successMessage = `Resource${rn} updated successfully.`;
+			}
 			sections.push({
 				label: uiTheme.fg("toolTitle", "Response"),
-				lines: highlighted.map(line => replaceTabs(line)),
+				lines: [uiTheme.fg("dim", successMessage)],
 			});
+		} else if (json && parsed) {
+			// Branch 1: List response with named items — compact summary
+			const items = parsed.items;
+			if (Array.isArray(items) && items.length > 0) {
+				const itemEntries = (items as Array<Record<string, unknown>>)
+					.map(item => {
+						const name = typeof item.name === "string" ? item.name : null;
+						return name ? { name, disabled: item.disabled === true } : null;
+					})
+					.filter(Boolean) as Array<{ name: string; disabled: boolean }>;
+				if (itemEntries.length > 0) {
+					const maxListItems = 20;
+					const displayed = itemEntries.slice(0, maxListItems);
+					const summaryLines = displayed.map(({ name, disabled }) =>
+						disabled
+							? `  ${uiTheme.fg("dim", name)} ${uiTheme.fg("warning", "DISABLED")}`
+							: uiTheme.fg("toolOutput", `  ${name}`),
+					);
+					if (itemEntries.length > maxListItems)
+						summaryLines.push(uiTheme.fg("dim", `  … and ${itemEntries.length - maxListItems} more`));
+					pushSection(
+						sections,
+						uiTheme.fg("toolTitle", `Response (${itemEntries.length} items)`),
+						summaryLines,
+						maxListItems + 1,
+						uiTheme,
+					);
+				}
+			} else {
+				// Branch 2: Single resource with metadata — summary + noise-reduced JSON
+				const summary = !isError ? buildResourceSummary(parsed, pathParts, method, uiTheme) : null;
+				if (summary) sections.push(summary);
+				const isMutating = method === "POST" || method === "PUT" || method === "PATCH";
+
+				// Determine if JSON body should be suppressed
+				let apiErrorMessage: string | undefined;
+				if (isError && typeof parsed.message === "string" && parsed.message) apiErrorMessage = parsed.message;
+				const skipJsonBody = (summary && isMutating) || (isError && (guidance || apiErrorMessage));
+
+				// Show extracted API error for errors without statusGuidance (400, 422, etc.)
+				if (apiErrorMessage && !guidance) {
+					sections.push({
+						label: uiTheme.fg("toolTitle", "Error"),
+						lines: [uiTheme.fg("error", apiErrorMessage)],
+					});
+				}
+
+				if (!skipJsonBody) {
+					const displayJson = JSON.stringify(stripEmpty(parsed), null, 2) ?? json;
+					const jsonLines = displayJson.split("\n");
+					const highlighted = isError
+						? jsonLines.map(line => uiTheme.fg("dim", replaceTabs(line)))
+						: highlightCode(displayJson, "json").map(line => replaceTabs(line));
+
+					let keyCount: number | undefined;
+					if (typeof parsed === "object" && !Array.isArray(parsed)) keyCount = Object.keys(parsed).length;
+					const responseLabel =
+						keyCount !== undefined && keyCount > 0 ? `Response (${keyCount} keys)` : "Response";
+
+					pushSection(sections, uiTheme.fg("toolTitle", responseLabel), highlighted, MAX_RESPONSE_LINES, uiTheme);
+				}
+			}
+		} else if (json) {
+			// Non-parseable JSON — render raw
+			const highlighted = isError
+				? json.split("\n").map(line => uiTheme.fg("dim", replaceTabs(line)))
+				: highlightCode(json, "json").map(line => replaceTabs(line));
+			sections.push({ label: uiTheme.fg("toolTitle", "Response"), lines: highlighted });
 		} else if (raw.trim() && !guidance) {
 			// Non-JSON, non-guidance body
 			sections.push({
@@ -187,12 +426,14 @@ export const xcshApiToolRenderer = {
 			});
 		}
 
-		// Section 3: Error guidance (for HTTP error responses)
+		// Section 4: Error guidance (for HTTP error responses)
 		if (guidance) {
-			sections.push({
-				label: uiTheme.fg("toolTitle", "Guidance"),
-				lines: [uiTheme.fg("warning", guidance)],
-			});
+			// Extract the API's specific error message from JSON body for prominent display
+			const guidanceLines: string[] = [];
+			const apiMessage = parsed && typeof parsed.message === "string" ? parsed.message : undefined;
+			if (apiMessage) guidanceLines.push(uiTheme.fg("error", apiMessage));
+			guidanceLines.push(uiTheme.fg("warning", guidance));
+			sections.push({ label: uiTheme.fg("toolTitle", "Guidance"), lines: guidanceLines });
 		}
 
 		// --- Render with CachedOutputBlock ---

package/src/tools/xcsh-api.ts

@@ -32,10 +32,35 @@ export interface XcshApiToolDetails {
 	durationMs?: number;
 	/** Active context profile name, if available. */
 	contextName?: string;
+	/** Response body size in bytes. */
+	bodySize?: number;
+	/** Number of items in the response `items` array (list operations). */
+	itemCount?: number;
+	/** Response content-type header. */
+	contentType?: string;
+	/** F5 XC gRPC error code label (e.g. NOT_FOUND, ALREADY_EXISTS) when present in response body. */
+	errorCodeLabel?: string;
+	/** Whether the request was automatically retried after a transient error (429/503). */
+	retried?: boolean;
+	/** Payload variables that were expanded (e.g. $F5XC_NAMESPACE → r-mordasiewicz). */
+	expandedVars?: Array<{ variable: string; value: string }>;
 }
 
 type XcshApiResult = AgentToolResult<XcshApiToolDetails> & { isError?: boolean };
 
+/** F5 XC gRPC error code labels for human-readable error display. */
+const F5XC_ERROR_CODES: Record<number, string> = {
+	3: "INVALID_ARGUMENT",
+	5: "NOT_FOUND",
+	6: "ALREADY_EXISTS",
+	7: "PERMISSION_DENIED",
+	8: "RESOURCE_EXHAUSTED",
+	9: "FAILED_PRECONDITION",
+	13: "INTERNAL",
+	14: "UNAVAILABLE",
+	16: "UNAUTHENTICATED",
+};
+
 export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolDetails> {
 	readonly name = "xcsh_api";
 	readonly label = "API";
@@ -93,13 +118,14 @@ export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolD
 				return `Access denied${ctxHint}. The API token may lack the required role or permission for this operation. Check the token's role assignments in the F5 XC console.`;
 			case 404: {
 				const ns = process.env.F5XC_NAMESPACE ?? this.#contextEnv.get("F5XC_NAMESPACE") ?? "default";
-				return `Resource not found. Verify the resource name exists in namespace \`${ns}\`${ctxHint}. Use a GET list operation to check existing resources.`;
+				return `Resource not found in namespace \`${ns}\`${ctxHint}. Use a GET list operation to verify existing resources.`;
 			}
 			case 409:
 				return `Resource already exists${ctxHint}. Use PUT to replace the existing resource, or DELETE it first before creating a new one.`;
 			case 429:
 				return `API rate limit exceeded${ctxHint}. Wait briefly and retry the request.`;
 			default:
+				if (status >= 500) return `Server error (${status})${ctxHint}. This may be transient — retry the request.`;
 				return null;
 		}
 	}
@@ -153,15 +179,45 @@ export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolD
 			signal: fetchSignal,
 		};
 
+		let expandedVars: Array<{ variable: string; value: string }> | undefined;
 		if (params.payload && params.method !== "GET") {
 			headers["Content-Type"] = "application/json";
 			const payloadJson = JSON.stringify(params.payload);
-			init.body = this.#contextEnv.resolvePayloadVars(payloadJson);
+			const resolved = this.#contextEnv.resolvePayloadVars(payloadJson);
+			init.body = resolved;
+			// Track which $F5XC_* variables were expanded
+			if (resolved !== payloadJson) {
+				expandedVars = [];
+				const env = this.#contextEnv;
+				for (const match of payloadJson.matchAll(/\$F5XC_([A-Z0-9_]+)/g)) {
+					const key = `F5XC_${match[1]}`;
+					const value = env.get(key) ?? process.env[key];
+					if (value) expandedVars.push({ variable: `$${key}`, value });
+				}
+			}
 		}
 
 		const startMs = performance.now();
 		try {
-			const response = await fetch(url, init);
+			let response = await fetch(url, init);
+
+			// Auto-retry idempotent GET requests on transient errors (429/503)
+			let retried = false;
+			if (params.method === "GET" && (response.status === 429 || response.status === 503) && !fetchSignal.aborted) {
+				// Parse Retry-After header: seconds (integer) or HTTP-date
+				const retryAfter = response.headers.get("retry-after");
+				let delayMs = 1000;
+				if (retryAfter) {
+					const seconds = Number.parseInt(retryAfter, 10);
+					if (Number.isFinite(seconds) && seconds > 0) delayMs = Math.min(seconds * 1000, 10_000);
+				}
+				await Bun.sleep(delayMs);
+				if (!fetchSignal.aborted) {
+					response = await fetch(url, init);
+					retried = true;
+				}
+			}
+
 			const raw = await response.text();
 			const durationMs = Math.round(performance.now() - startMs);
 			const contentType = response.headers.get("content-type") ?? "";
@@ -176,12 +232,41 @@ export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolD
 			const statusLine = `${response.status} ${response.statusText}`;
 
 			const contextName = this.#contextEnv.getContextName();
-			const detail = { status: response.status, url, method: params.method, requestId, durationMs, contextName };
+			const bodySize = raw.length;
+			// Parse response JSON once for item count, error code label, etc.
+			let parsedBody: Record<string, unknown> | null = null;
+			let itemCount: number | undefined;
+			try {
+				parsedBody = JSON.parse(raw) as Record<string, unknown>;
+				if (Array.isArray(parsedBody?.items)) itemCount = (parsedBody.items as unknown[]).length;
+			} catch {
+				// Not JSON — skip structured extraction
+			}
+			const detail: XcshApiToolDetails = {
+				status: response.status,
+				url,
+				method: params.method,
+				requestId,
+				durationMs,
+				contextName,
+				bodySize,
+				itemCount,
+				contentType: contentType || undefined,
+				retried: retried || undefined,
+				expandedVars,
+			};
 
 			// Context-aware CRUD error guidance for common HTTP status codes
 			const guidance = this.#statusGuidance(response.status);
 			if (guidance) {
-				return this.#errorResult(`${statusLine}\n\n${bodyText}\n\n${guidance}`, detail);
+				// Enrich with F5 XC error code label when present in response body
+				let errorCodePrefix = "";
+				const codeLabel = parsedBody ? F5XC_ERROR_CODES[parsedBody.code as number] : undefined;
+				if (codeLabel) {
+					errorCodePrefix = `[${codeLabel}] `;
+					detail.errorCodeLabel = codeLabel;
+				}
+				return this.#errorResult(`${statusLine}\n\n${bodyText}\n\n${errorCodePrefix}${guidance}`, detail);
 			}
 
 			return {