@f5xc-salesdemos/xcsh 18.54.0 → 18.56.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.54.0",
+	"version": "18.56.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.54.0",
-		"@f5xc-salesdemos/pi-agent-core": "18.54.0",
-		"@f5xc-salesdemos/pi-ai": "18.54.0",
-		"@f5xc-salesdemos/pi-natives": "18.54.0",
-		"@f5xc-salesdemos/pi-tui": "18.54.0",
-		"@f5xc-salesdemos/pi-utils": "18.54.0",
+		"@f5xc-salesdemos/xcsh-stats": "18.56.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.56.0",
+		"@f5xc-salesdemos/pi-ai": "18.56.0",
+		"@f5xc-salesdemos/pi-natives": "18.56.0",
+		"@f5xc-salesdemos/pi-tui": "18.56.0",
+		"@f5xc-salesdemos/pi-utils": "18.56.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.54.0",
-	"commit": "cc0ce8cb044cde5a7ccfcdbd4ba82603fb8dbf66",
-	"shortCommit": "cc0ce8c",
+	"version": "18.56.0",
+	"commit": "d61f41711c0498bf98d02028b9b49159e3dcf415",
+	"shortCommit": "d61f417",
 	"branch": "main",
-	"tag": "v18.54.0",
-	"commitDate": "2026-05-09T17:34:09Z",
-	"buildDate": "2026-05-09T17:58:06.189Z",
+	"tag": "v18.56.0",
+	"commitDate": "2026-05-09T21:11:13Z",
+	"buildDate": "2026-05-09T21:32:38.103Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/cc0ce8cb044cde5a7ccfcdbd4ba82603fb8dbf66",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.54.0"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/d61f41711c0498bf98d02028b9b49159e3dcf415",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.56.0"
 };

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

@@ -1,10 +1,16 @@
 Execute an F5 Distributed Cloud API call directly.
 
 Handles authentication, URL construction, and HTTP execution.
-Requires `F5XC_API_URL` and `F5XC_API_TOKEN` environment variables.
+Credentials are resolved from the active context profile (`/context`). Environment variables
+`F5XC_API_URL` and `F5XC_API_TOKEN` override context values when set.
+
+Path parameters like `{namespace}` are auto-resolved from the active context when not
+explicitly provided in `params`. For example, `{namespace}` resolves to the context's
+default namespace (`F5XC_NAMESPACE`).
 
 Pass all path `{placeholder}` values via `params`, e.g. `{ namespace: "default", name: "example-lb", vh_name: "example-vh" }`.
 Body is sent for all methods except GET when `payload` is provided — including DELETE operations that require a body.
+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.
 

package/src/services/context-env.ts

@@ -1,12 +1,27 @@
 import { SECRET_ENV_PATTERNS } from "../secrets/index";
-import { F5XC_API_TOKEN, F5XC_API_URL, F5XC_NAMESPACE, F5XC_TENANT } from "./f5xc-env";
+import { F5XC_API_TOKEN, F5XC_API_URL, F5XC_CONTEXT_NAME, F5XC_NAMESPACE, F5XC_TENANT } from "./f5xc-env";
 
 /** Keys excluded from the system prompt context variables listing. */
-const PROMPT_HIDDEN: ReadonlySet<string> = new Set([F5XC_API_TOKEN, F5XC_API_URL, F5XC_TENANT, F5XC_NAMESPACE]);
+const PROMPT_HIDDEN: ReadonlySet<string> = new Set([
+	F5XC_API_TOKEN,
+	F5XC_API_URL,
+	F5XC_TENANT,
+	F5XC_NAMESPACE,
+	F5XC_CONTEXT_NAME,
+]);
 
 /** Keys never expanded in payloads — credentials that must not leak into request bodies. */
 const PAYLOAD_HIDDEN: ReadonlySet<string> = new Set([F5XC_API_TOKEN, F5XC_API_URL]);
 
+/**
+ * Bridge between F5 XC context profiles and the xcsh_api tool.
+ *
+ * Reads from `Settings.bash.environment` (populated by ContextService on profile
+ * activation) and provides credential resolution, path parameter auto-filling,
+ * and payload variable expansion. Consumed by:
+ * - `XcshApiTool` for credential and namespace resolution during API calls
+ * - `sdk.ts` for surfacing non-sensitive context vars in the system prompt
+ */
 export interface ContextEnv {
 	/** Get a single env var value from bash.environment, or undefined. */
 	get(key: string): string | undefined;
@@ -32,6 +47,9 @@ export interface ContextEnv {
 	 * matching SECRET_ENV_PATTERNS, and explicitly provided sensitiveKeys.
 	 */
 	getNonSensitiveVars(): Record<string, string>;
+
+	/** Return the active context profile name, or undefined if not set. */
+	getContextName(): string | undefined;
 }
 
 export interface ContextEnvOptions {
@@ -63,6 +81,10 @@ export function createContextEnv(settings: { get(key: string): unknown }, option
 			return bashEnv()[key];
 		},
 
+		getContextName(): string | undefined {
+			return bashEnv()[F5XC_CONTEXT_NAME] || undefined;
+		},
+
 		resolvePath(path: string, explicitParams?: Record<string, string>): string {
 			let resolved = path;
 

package/src/services/f5xc-context.ts

@@ -8,6 +8,7 @@ import {
 	deriveTenantFromUrl,
 	F5XC_API_TOKEN,
 	F5XC_API_URL,
+	F5XC_CONTEXT_NAME,
 	F5XC_NAMESPACE,
 	F5XC_TENANT,
 	hasEnvOverride,
@@ -1328,6 +1329,9 @@ export class ContextService {
 			if (tenant) merged[F5XC_TENANT] = tenant;
 		}
 
+		// Inject context profile name for API tool identity surfacing
+		merged[F5XC_CONTEXT_NAME] = context.name;
+
 		// Inject all additional env vars from context.env map
 		if (context.env) {
 			for (const [key, value] of Object.entries(context.env)) {

package/src/services/f5xc-env.ts

@@ -9,6 +9,8 @@ export const F5XC_NAMESPACE = "F5XC_NAMESPACE" as const;
 export const F5XC_TENANT = "F5XC_TENANT" as const;
 export const F5XC_USERNAME = "F5XC_USERNAME" as const;
 export const F5XC_CONSOLE_PASSWORD = "F5XC_CONSOLE_PASSWORD" as const;
+/** Active context profile name. Read-only metadata injected by ContextService. */
+export const F5XC_CONTEXT_NAME = "F5XC_CONTEXT_NAME" as const;
 
 export const RESERVED_ENV_KEYS: ReadonlySet<string> = new Set([
 	F5XC_NAMESPACE,

package/src/session/messages.ts

@@ -292,14 +292,14 @@ function repairToolResultOrdering(messages: Message[]): Message[] {
 		}
 	}
 
-	// Track which toolResult messages have been placed by repair
-	const placedToolResultIndices = new Set<number>();
+	// Track which message indices have been consumed (placed or displaced) by repair
+	const consumedIndices = new Set<number>();
 
 	for (let i = 0; i < messages.length; i++) {
 		const msg = messages[i];
 
-		// Skip toolResult messages that were already placed by repair
-		if (msg.role === "toolResult" && placedToolResultIndices.has(i)) {
+		// Skip toolResult messages that were already consumed (placed elsewhere or displaced)
+		if (msg.role === "toolResult" && consumedIndices.has(i)) {
 			continue;
 		}
 
@@ -326,7 +326,7 @@ function repairToolResultOrdering(messages: Message[]): Message[] {
 				if (requiredIds.has(trMsg.toolCallId)) {
 					// This tool_result belongs here — place it
 					result.push(next);
-					placedToolResultIndices.add(j);
+					consumedIndices.add(j);
 					requiredIds.delete(trMsg.toolCallId);
 					if (displaced.length > 0) repaired = true;
 					j++;
@@ -335,7 +335,7 @@ function repairToolResultOrdering(messages: Message[]): Message[] {
 			}
 			// Non-matching message between tool_use and tool_result — displace it
 			displaced.push(next);
-			placedToolResultIndices.add(j); // Mark original index as consumed
+			consumedIndices.add(j); // Mark original index as consumed
 			j++;
 		}
 
@@ -345,9 +345,9 @@ function repairToolResultOrdering(messages: Message[]): Message[] {
 		// Any remaining required IDs: find them later in the array or synthesize
 		for (const id of requiredIds) {
 			const found = toolResultsByCallId.get(id);
-			if (found && !placedToolResultIndices.has(found.originalIndex)) {
+			if (found && !consumedIndices.has(found.originalIndex)) {
 				result.push(found.message);
-				placedToolResultIndices.add(found.originalIndex);
+				consumedIndices.add(found.originalIndex);
 				repaired = true;
 			} else {
 				// Missing tool_result entirely — inject synthetic error result
@@ -370,6 +370,55 @@ function repairToolResultOrdering(messages: Message[]): Message[] {
 		}
 	}
 
+	// Second pass: repair displaced assistant messages whose tool calls were never processed.
+	// When an assistant-with-tool-calls gets displaced (wedged between another assistant's
+	// tool_use and its tool_result), the first pass pushes it to result but the outer loop
+	// jumps past it — so its own tool_results are never resolved.
+	for (let i = 0; i < result.length; i++) {
+		const msg = result[i];
+		if (msg.role !== "assistant") continue;
+		const assistantMsg = msg as AssistantMessage;
+		const toolCalls = assistantMsg.content.filter((c): c is ToolCall => c.type === "toolCall");
+		if (toolCalls.length === 0) continue;
+
+		// Check if every tool call has a toolResult immediately following
+		const expectedIds = new Set(toolCalls.map(tc => tc.id));
+		let j = i + 1;
+		while (j < result.length && result[j].role === "toolResult") {
+			expectedIds.delete((result[j] as ToolResultMessage).toolCallId);
+			j++;
+		}
+
+		if (expectedIds.size === 0) continue;
+
+		// For missing tool calls: relocate existing result from later in array, or synthesize
+		const toInsert: ToolResultMessage[] = [];
+		for (const id of expectedIds) {
+			// Check if a toolResult for this ID exists later in result
+			const laterIndex = result.findIndex(
+				(m, idx) => idx > j && m.role === "toolResult" && (m as ToolResultMessage).toolCallId === id,
+			);
+			if (laterIndex !== -1) {
+				// Relocate the existing result to right after the assistant
+				const [relocated] = result.splice(laterIndex, 1);
+				toInsert.push(relocated as ToolResultMessage);
+			} else {
+				const toolCall = toolCalls.find(tc => tc.id === id);
+				toInsert.push({
+					role: "toolResult",
+					toolCallId: id,
+					toolName: toolCall?.name ?? "unknown",
+					content: [{ type: "text", text: "Tool execution was interrupted (session recovery)." }],
+					isError: true,
+					timestamp: Date.now(),
+				} as ToolResultMessage);
+			}
+		}
+		result.splice(i + 1, 0, ...toInsert);
+		i += toInsert.length; // Skip past inserted results
+		repaired = true;
+	}
+
 	if (repaired) {
 		logger.warn("Repaired tool_use/tool_result ordering in conversation history");
 	}

package/src/tools/renderers.ts

@@ -27,6 +27,7 @@ import { searchToolBm25Renderer } from "./search-tool-bm25";
 import { sshToolRenderer } from "./ssh";
 import { todoWriteToolRenderer } from "./todo-write";
 import { writeToolRenderer } from "./write";
+import { xcshApiToolRenderer } from "./xcsh-api-renderer";
 
 type ToolRenderer = {
 	renderCall: (args: unknown, options: RenderResultOptions, theme: Theme) => Component;
@@ -68,4 +69,5 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	gh_run_watch: ghRunWatchToolRenderer as ToolRenderer,
 	web_search: webSearchToolRenderer as ToolRenderer,
 	write: writeToolRenderer as ToolRenderer,
+	xcsh_api: xcshApiToolRenderer as ToolRenderer,
 };

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

@@ -0,0 +1,147 @@
+/**
+ * TUI renderer for the xcsh_api tool.
+ *
+ * Provides context-aware visualization for F5 XC API calls:
+ * - renderCall: method badge + path while request is pending
+ * - renderResult: status code badge + JSON body preview (collapsed/expanded)
+ */
+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 { Ellipsis, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
+import { formatErrorMessage, PREVIEW_LIMITS, replaceTabs } from "./render-utils";
+import type { XcshApiToolDetails } from "./xcsh-api";
+
+interface XcshApiRenderArgs {
+	method?: string;
+	path?: string;
+	params?: Record<string, string>;
+	payload?: unknown;
+}
+
+/** Map HTTP method to a theme color for the badge. */
+function methodColor(method: string): ThemeColor {
+	switch (method) {
+		case "GET":
+			return "accent";
+		case "DELETE":
+			return "error";
+		default:
+			return "warning";
+	}
+}
+
+/** Map HTTP status code to a theme color. */
+function statusColor(status: number): ThemeColor {
+	if (status < 300) return "success";
+	if (status < 400) return "warning";
+	return "error";
+}
+
+const COLLAPSED_BODY_LINES = PREVIEW_LIMITS.OUTPUT_COLLAPSED;
+
+export const xcshApiToolRenderer = {
+	renderCall(args: XcshApiRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const method = args.method ?? "???";
+		const apiPath = args.path ?? "…";
+		const text = renderStatusLine(
+			{
+				icon: "pending",
+				title: "API",
+				description: apiPath,
+				badge: { label: method, color: methodColor(method) },
+			},
+			uiTheme,
+		);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: XcshApiToolDetails; isError?: boolean },
+		options: RenderResultOptions,
+		uiTheme: Theme,
+		args?: XcshApiRenderArgs,
+	): Component {
+		const details = result.details;
+		const method = details?.method ?? args?.method ?? "???";
+		const url = details?.url;
+		// Show resolved path (from URL) or the original template path
+		let displayPath = args?.path ?? "…";
+		if (url) {
+			try {
+				displayPath = new URL(url).pathname;
+			} catch {
+				// Malformed URL — fall through to args.path
+			}
+		}
+		const status = details?.status ?? 0;
+		const statusText = status > 0 ? `${status}` : "failed";
+
+		if (result.isError && !details) {
+			const errorText = result.content?.find(c => c.type === "text")?.text;
+			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+		}
+
+		const meta: string[] = [];
+		if (details?.contextName) meta.push(uiTheme.fg("muted", details.contextName));
+		if (details?.durationMs !== undefined) meta.push(uiTheme.fg("dim", `${details.durationMs}ms`));
+		const header = renderStatusLine(
+			{
+				title: "API",
+				description: displayPath,
+				badge: { label: `${method} ${statusText}`, color: status > 0 ? statusColor(status) : "error" },
+				meta: meta.length > 0 ? meta : undefined,
+			},
+			uiTheme,
+		);
+
+		const textContent = result.content?.find(c => c.type === "text")?.text ?? "";
+		// Split off the status line prefix (e.g. "200 OK\n\n") from the body
+		const bodyStart = textContent.indexOf("\n\n");
+		let body = bodyStart >= 0 ? textContent.slice(bodyStart + 2) : textContent;
+		// Format JSON bodies for readable TUI display (error bodies include guidance text and won't parse)
+		try {
+			body = JSON.stringify(JSON.parse(body.trim()), null, 2);
+		} catch {
+			// Not valid JSON — keep as-is
+		}
+		const bodyLines = body.trim() ? replaceTabs(body).split("\n") : [];
+
+		let cached: RenderCache | undefined;
+		return {
+			render(width: number): string[] {
+				const { expanded } = options;
+				const key = new Hasher().bool(expanded).u32(width).digest();
+				if (cached?.key === key) return cached.lines;
+
+				const lines: string[] = [header];
+
+				if (bodyLines.length > 0) {
+					if (expanded) {
+						for (const line of bodyLines) {
+							lines.push(truncateToWidth(uiTheme.fg("toolOutput", line), width, Ellipsis.Omit));
+						}
+					} else {
+						const maxLines = COLLAPSED_BODY_LINES;
+						const display = bodyLines.slice(0, maxLines);
+						const remaining = bodyLines.length - maxLines;
+						for (const line of display) {
+							lines.push(truncateToWidth(uiTheme.fg("toolOutput", line), width, Ellipsis.Omit));
+						}
+						if (remaining > 0) {
+							lines.push(uiTheme.fg("dim", `… (${remaining} more lines) (ctrl+o to expand)`));
+						}
+					}
+				}
+
+				cached = { key, lines };
+				return lines;
+			},
+			invalidate() {
+				cached = undefined;
+			},
+		};
+	},
+	mergeCallAndResult: true,
+};

package/src/tools/xcsh-api.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolResult } from "@f5xc-salesdemos/pi-agent-core"
 import { prompt } from "@f5xc-salesdemos/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import xcshApiDescription from "../prompts/tools/xcsh-api.md" with { type: "text" };
-import { createContextEnv } from "../services/context-env";
+import { type ContextEnv, createContextEnv } from "../services/context-env";
 import type { ToolSession } from ".";
 
 const xcshApiSchema = Type.Object({
@@ -28,6 +28,10 @@ export interface XcshApiToolDetails {
 	url: string;
 	method: string;
 	requestId: string;
+	/** Round-trip duration in milliseconds. */
+	durationMs?: number;
+	/** Active context profile name, if available. */
+	contextName?: string;
 }
 
 type XcshApiResult = AgentToolResult<XcshApiToolDetails> & { isError?: boolean };
@@ -38,15 +42,23 @@ export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolD
 	readonly description: string;
 	readonly parameters = xcshApiSchema;
 
-	#contextEnv: ReturnType<typeof createContextEnv>;
+	#contextEnv: ContextEnv;
+	/** Tracks the last API base for context-switch detection and TLS re-warm. */
+	#lastApiBase = "";
 
 	constructor(session: ToolSession) {
 		this.description = prompt.render(xcshApiDescription);
 		this.#contextEnv = createContextEnv(session.settings);
 
+		this.#warmTls();
+	}
+
+	/** Pre-warm TLS connection to the current context's API endpoint. */
+	#warmTls(): void {
 		const apiBase = this.#resolveApiBase();
 		const apiToken = this.#resolveApiToken();
 		if (apiBase && apiToken) {
+			this.#lastApiBase = apiBase;
 			fetch(`${apiBase}/api/web/namespaces`, {
 				method: "HEAD",
 				headers: { Authorization: `APIToken ${apiToken}` },
@@ -62,25 +74,67 @@ export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolD
 		return process.env.F5XC_API_TOKEN ?? this.#contextEnv.get("F5XC_API_TOKEN") ?? "";
 	}
 
-	async execute(_toolCallId: string, params: XcshApiParams): Promise<XcshApiResult> {
+	#errorResult(text: string, details?: XcshApiToolDetails): XcshApiResult {
+		return {
+			content: [{ type: "text", text }],
+			...(details ? { details } : {}),
+			isError: true,
+		};
+	}
+
+	/** Context-aware guidance appended to HTTP error responses for common CRUD failures. */
+	#statusGuidance(status: number): string | null {
+		const ctx = this.#contextEnv.getContextName();
+		const ctxHint = ctx ? ` (context: \`${ctx}\`)` : "";
+		switch (status) {
+			case 401:
+				return `Token may be expired or invalid${ctxHint}. Run \`/context validate\` to check credentials, or \`/context create\` to set up a new context with fresh credentials.`;
+			case 403:
+				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 = 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.`;
+			}
+			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:
+				return null;
+		}
+	}
+
+	async execute(_toolCallId: string, params: XcshApiParams, signal?: AbortSignal): Promise<XcshApiResult> {
 		const apiBase = this.#resolveApiBase();
+		// Detect context switch: API base changed since last call → re-warm TLS
+		if (apiBase && apiBase !== this.#lastApiBase) {
+			this.#warmTls();
+		}
 		if (!apiBase) {
-			return {
-				content: [{ type: "text", text: "Error: F5XC_API_URL environment variable is not set." }],
-				isError: true,
-			};
+			const ctx = this.#contextEnv.getContextName();
+			const ctxNote = ctx ? ` Active context \`${ctx}\` has no API URL.` : "";
+			return this.#errorResult(
+				`Error: No API URL configured.${ctxNote} Activate a context with \`/context activate <name>\` or \`/context create\`, or set the F5XC_API_URL environment variable.`,
+			);
 		}
-
 		const apiToken = this.#resolveApiToken();
 		if (!apiToken) {
-			return {
-				content: [{ type: "text", text: "Error: F5XC_API_TOKEN environment variable is not set." }],
-				isError: true,
-			};
+			const ctx = this.#contextEnv.getContextName();
+			const ctxNote = ctx ? ` Active context \`${ctx}\` has no API token.` : "";
+			return this.#errorResult(
+				`Error: No API token configured.${ctxNote} Activate a context with \`/context activate <name>\` or \`/context create\`, or set the F5XC_API_TOKEN environment variable.`,
+			);
 		}
-
 		const resolvedPath = this.#contextEnv.resolvePath(params.path, params.params);
 
+		// Guard: detect unresolved {placeholder} params still remaining in the path.
+		// Regex matches \w+ (same as ContextEnv.resolvePath) to avoid misaligned detection.
+		const unresolvedPlaceholders = resolvedPath.match(/\{\w+\}/g);
+		if (unresolvedPlaceholders) {
+			return this.#errorResult(
+				`Error: Unresolved path parameter(s): ${unresolvedPlaceholders.join(", ")}. Provide them via \`params\` or ensure they are configured in the active context.`,
+			);
+		}
 		const url = `${apiBase}${resolvedPath}`;
 		const requestId = crypto.randomUUID();
 		const headers: Record<string, string> = {
@@ -89,10 +143,14 @@ export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolD
 			"X-Request-ID": requestId,
 		};
 
+		// Combine user abort signal with 30s timeout. User Ctrl+C is respected.
+		const timeoutSignal = AbortSignal.timeout(30_000);
+		const fetchSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
 		const init: RequestInit = {
 			method: params.method,
 			headers,
-			signal: AbortSignal.timeout(30_000),
+			signal: fetchSignal,
 		};
 
 		if (params.payload && params.method !== "GET") {
@@ -101,9 +159,11 @@ export class XcshApiTool implements AgentTool<typeof xcshApiSchema, XcshApiToolD
 			init.body = this.#contextEnv.resolvePayloadVars(payloadJson);
 		}
 
+		const startMs = performance.now();
 		try {
 			const response = await fetch(url, init);
 			const raw = await response.text();
+			const durationMs = Math.round(performance.now() - startMs);
 			const contentType = response.headers.get("content-type") ?? "";
 			let bodyText = raw;
 			if (contentType.includes("application/json")) {
@@ -115,18 +175,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 };
+
+			// 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);
+			}
+
 			return {
 				content: [{ type: "text", text: `${statusLine}\n\n${bodyText}` }],
-				details: { status: response.status, url, method: params.method, requestId },
+				details: detail,
 				...(response.status >= 400 ? { isError: true } : {}),
 			};
 		} catch (err) {
+			const durationMs = Math.round(performance.now() - startMs);
+			const contextName = this.#contextEnv.getContextName();
+			const detail = { status: 0, url, method: params.method, requestId, durationMs, contextName };
+			// Classify error: timeout vs DNS/network vs generic
+			const ctxLabel = contextName ? ` (context: \`${contextName}\`)` : "";
+			if (err instanceof Error && err.name === "AbortError") {
+				// User abort vs 30s timeout produce different AbortErrors
+				const message = signal?.aborted
+					? "Request cancelled."
+					: `Request timed out after 30s${ctxLabel}. The API endpoint may be unreachable. Verify the API URL with \`/context show\`.`;
+				return this.#errorResult(message, detail);
+			}
 			const message = err instanceof Error ? err.message : String(err);
-			return {
-				content: [{ type: "text", text: `Request failed: ${message}` }],
-				details: { status: 0, url, method: params.method, requestId },
-				isError: true,
-			};
+			if (/ENOTFOUND|ECONNREFUSED|EAI_AGAIN|dns/i.test(message)) {
+				return this.#errorResult(
+					`Network error${ctxLabel}: ${message}. The API URL may be incorrect. Check with \`/context show\`.`,
+					detail,
+				);
+			}
+			return this.#errorResult(`Request failed${ctxLabel}: ${message}`, detail);
 		}
 	}
 }