@f5-sales-demo/xcsh 19.61.0 → 19.61.2

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.61.0",
+	"version": "19.61.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -35,7 +35,8 @@
 		"check": "biome check . && bun run format-prompts -- --check && bun run check:types",
 		"check:types": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
-		"test": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-console-catalog && bun run generate-console-field-metadata && bun test --max-concurrency 4",
+		"check:bundle": "bun scripts/check-bundle.ts",
+		"test": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-console-catalog && bun run generate-console-field-metadata && bun scripts/bun-test-guarded.ts --max-concurrency 4",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-api-spec-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
@@ -55,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.61.0",
-		"@f5-sales-demo/pi-agent-core": "19.61.0",
-		"@f5-sales-demo/pi-ai": "19.61.0",
-		"@f5-sales-demo/pi-natives": "19.61.0",
-		"@f5-sales-demo/pi-resource-management": "19.61.0",
-		"@f5-sales-demo/pi-tui": "19.61.0",
-		"@f5-sales-demo/pi-utils": "19.61.0",
+		"@f5-sales-demo/xcsh-stats": "19.61.2",
+		"@f5-sales-demo/pi-agent-core": "19.61.2",
+		"@f5-sales-demo/pi-ai": "19.61.2",
+		"@f5-sales-demo/pi-natives": "19.61.2",
+		"@f5-sales-demo/pi-resource-management": "19.61.2",
+		"@f5-sales-demo/pi-tui": "19.61.2",
+		"@f5-sales-demo/pi-utils": "19.61.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/api-specs-version.ts

@@ -0,0 +1,20 @@
+/**
+ * Version helpers for selecting the api-specs-enriched source.
+ *
+ * Kept in a dedicated module (no side effects) so the freshness logic is unit-testable
+ * without importing generate-api-spec-index.ts, which runs the generator on load.
+ */
+
+/** Normalize a release tag (`v2.1.167`) or bare version (`2.1.167`) to a bare version. */
+export function normalizeSpecsTag(tag: string): string {
+	return tag.trim().replace(/^v/, "");
+}
+
+/**
+ * Whether a local api-specs-enriched checkout matches the latest release tag.
+ * A stale checkout must NOT be used, or local/dev builds silently pin to old specs.
+ */
+export function isLocalSpecsCurrent(localVersion: string | undefined, latestTag: string): boolean {
+	if (!localVersion) return false;
+	return normalizeSpecsTag(localVersion) === normalizeSpecsTag(latestTag);
+}

package/scripts/bun-test-guarded.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+/**
+ * Guarded `bun test` runner.
+ *
+ * Runs `bun test <args…>` and enforces one extra invariant: if the run exits 0
+ * it MUST have printed a "Ran N tests" summary. A test module that calls
+ * `process.exit(0)` terminates the whole runner with a success code BEFORE the
+ * summary prints, silently masking every failure that already ran (this made the
+ * required CI `test` job a no-op gate — issue #1903). Exit code alone can't catch
+ * that regression; the missing summary can.
+ *
+ * Behaviour:
+ *  - child exits non-zero  → propagate it (real failures already fail the job).
+ *  - child exits 0 WITH a summary ("Ran N tests" / "No tests found") → pass.
+ *  - child exits 0 WITHOUT a summary → fail (exit 1): a test aborted the runner.
+ *
+ * stderr (where bun writes results) is streamed through unchanged so CI logs are
+ * identical; we only tee it to scan for the summary line.
+ */
+const args = process.argv.slice(2);
+
+// Use the running bun (process.execPath), not a PATH lookup of "bun", so the
+// guard works in any environment the parent runs in.
+const proc = Bun.spawn([process.execPath, "test", ...args], {
+	stdout: "inherit",
+	stderr: "pipe",
+	env: process.env,
+});
+
+const SUMMARY = /Ran \d+ tests?\b|No tests found/;
+const decoder = new TextDecoder();
+// Keep a small rolling tail so a summary line split across two chunks is still
+// matched, without buffering the entire (potentially large) stderr stream.
+let tail = "";
+
+for await (const chunk of proc.stderr as ReadableStream<Uint8Array>) {
+	process.stderr.write(chunk); // stream through unchanged
+	tail = (tail + decoder.decode(chunk, { stream: true })).slice(-4096);
+}
+
+const sawSummary = SUMMARY.test(tail);
+const code = await proc.exited;
+
+if (code !== 0) process.exit(code);
+
+if (!sawSummary) {
+	process.stderr.write(
+		'\n\x1b[31mtest-guard: `bun test` exited 0 but printed no "Ran N tests" summary.\x1b[0m\n' +
+			"A test module likely called process.exit() and aborted the runner, masking failures (see #1903).\n",
+	);
+	process.exit(1);
+}
+
+process.exit(0);

package/scripts/check-bundle.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+/**
+ * Bundle guard: ensure the CLI entrypoint still bundles.
+ *
+ * Reproduces the `bun build --compile` module-graph analysis in ~1s so a
+ * `require()` into a top-level-await subgraph (or other bundle-breaking graph
+ * change) fails fast in a required CI gate — not only in the slower, optional
+ * install-methods build. See PRs #1888 → #1892 for the regression this guards.
+ *
+ * Runs as a standalone `bun` process (not under `bun test`, whose bundler
+ * resolver cannot resolve some lazily-imported specifiers). Exits non-zero on
+ * any bundle error.
+ */
+import * as path from "node:path";
+
+const cliEntry = path.resolve(import.meta.dir, "../src/cli.ts");
+
+const result = await Bun.build({
+	entrypoints: [cliEntry],
+	target: "bun",
+	define: { PI_COMPILED: "true" },
+	external: ["mupdf"],
+	throw: false,
+});
+
+if (!result.success) {
+	console.error("Bundle check FAILED — the CLI entrypoint does not bundle:\n");
+	for (const log of result.logs) console.error(String(log));
+	process.exit(1);
+}
+
+console.log("Bundle check passed — CLI entrypoint bundles cleanly.");

package/scripts/generate-api-spec-index.ts

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { $ } from "bun";
+import { isLocalSpecsCurrent } from "./api-specs-version";
 
 interface SpecPathOperation {
 	operationId?: string;
@@ -183,15 +184,42 @@ async function downloadFromRelease(): Promise<string> {
 	return extractDir;
 }
 
+function readLocalSpecsVersion(specsDir: string): string | undefined {
+	try {
+		const index = JSON.parse(fs.readFileSync(path.join(specsDir, "index.json"), "utf-8")) as { version?: string };
+		return index.version;
+	} catch {
+		return undefined;
+	}
+}
+
 async function findSpecsDir(): Promise<string> {
 	const envDir = process.env.API_SPECS_DIR;
 	if (envDir && fs.existsSync(envDir)) {
+		// Explicit override — the caller is responsible for its freshness.
 		return envDir;
 	}
 
 	const localCheckout = path.resolve(import.meta.dir, "../../../../api-specs-enriched/docs/specifications/api");
 	if (fs.existsSync(localCheckout)) {
-		return localCheckout;
+		// Only build from the local checkout when it matches the latest release, so a
+		// stale checkout cannot silently pin the build to old specs. If GitHub is
+		// unreachable (offline dev), fall back to the local checkout with a warning.
+		try {
+			const latestTag = await resolveLatestTag();
+			const localVersion = readLocalSpecsVersion(localCheckout);
+			if (isLocalSpecsCurrent(localVersion, latestTag)) {
+				return localCheckout;
+			}
+			console.warn(
+				`Local api-specs-enriched checkout is stale (local ${localVersion ?? "unknown"} != latest ${latestTag}); building against the latest release instead.`,
+			);
+		} catch (err) {
+			console.warn(
+				`Could not verify the latest api-specs version (${err instanceof Error ? err.message : err}); using the local checkout.`,
+			);
+			return localCheckout;
+		}
 	}
 
 	return downloadFromRelease();

package/src/browser/chat-handler.ts

@@ -14,12 +14,16 @@ import {
 import { CONSOLE_ROUTES } from "./console-routes.generated";
 import type { BridgeServer } from "./extension-bridge";
 import { interpretPageState } from "./page-state-interpreter";
+import { chatSpans } from "./ttft-spans";
 
 interface ActiveChat {
 	id: string;
 	seq: number;
 	terminalSent: boolean;
 	unsubscribe: () => void;
+	entryAt: number;
+	promptAt: number | null;
+	spanEmitted: boolean;
 }
 
 export class ChatHandler {
@@ -61,7 +65,15 @@ export class ChatHandler {
 			this.#activeHistoryHint = req.history_hint;
 		}
 
-		const chat: ActiveChat = { id, seq: 0, terminalSent: false, unsubscribe: () => {} };
+		const chat: ActiveChat = {
+			id,
+			seq: 0,
+			terminalSent: false,
+			unsubscribe: () => {},
+			entryAt: Date.now(),
+			promptAt: null,
+			spanEmitted: false,
+		};
 		this.#activeChats.set(id, chat);
 
 		const unsubscribe = this.#session.subscribe((event: AgentSessionEvent) => {
@@ -72,6 +84,7 @@ export class ChatHandler {
 		const prompt = composeChatPrompt(req.text, req.context, req.mode);
 
 		try {
+			chat.promptAt = Date.now();
 			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false });
 		} catch (err: unknown) {
 			const message = err instanceof Error ? err.message : "unknown error";
@@ -121,6 +134,15 @@ export class ChatHandler {
 					seq: chat.seq++,
 					delta: ame.delta,
 				} satisfies ChatDelta);
+				// TTFT Phase 2: first token out — emit the chat-segment spans once, keyed by
+				// the c- turn id. chat.promptAt is set (prompt() was awaited before any event);
+				// guard against re-emit on later deltas.
+				if (!chat.spanEmitted && chat.promptAt !== null) {
+					chat.spanEmitted = true;
+					for (const s of chatSpans(chat.id, chat.entryAt, chat.promptAt, Date.now())) {
+						this.#server.send(s);
+					}
+				}
 			} else if (ame.type === "error") {
 				const errorMsg = ame.error?.errorMessage ?? "LLM error";
 				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: errorMsg });

package/src/browser/ttft-spans.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure TTFT span-frame builders for Phase 2. The worker emits these over the bridge
+ * WS; the extension records them (proc:'xcsh') and summarizeTtft stitches them into
+ * the init->first-token timeline. Chrome-free, so they unit-test in isolation.
+ */
+export interface SpanFrame {
+	type: "span";
+	stage: string;
+	ms: number;
+	id?: string;
+	sid?: string;
+	cold?: boolean;
+}
+
+const clamp = (ms: number): number => (ms > 0 ? ms : 0);
+
+/**
+ * Decompose one chat turn's route->first-token into two disjoint spans that sum to
+ * (firstDeltaAt - entryAt): provider_ttft (prompt issued -> first token) and
+ * chat_handler (the xcsh routing/compose/emit overhead = entry -> prompt issued).
+ */
+export function chatSpans(id: string, entryAt: number, promptAt: number, firstDeltaAt: number): SpanFrame[] {
+	const providerMs = clamp(firstDeltaAt - promptAt);
+	const handlerMs = clamp(firstDeltaAt - entryAt - providerMs);
+	return [
+		{ type: "span", stage: "provider_ttft", ms: providerMs, id },
+		{ type: "span", stage: "chat_handler", ms: handlerMs, id },
+	];
+}
+
+/** Build the per-session cold-start spans, tagged with the session id + authoritative cold. */
+export function coldStartSpans(
+	sid: string,
+	cold: boolean,
+	managerProvisionMs: number,
+	workerBootMs: number,
+): SpanFrame[] {
+	return [
+		{ type: "span", stage: "manager_provision", ms: clamp(managerProvisionMs), sid, cold },
+		{ type: "span", stage: "worker_boot", ms: clamp(workerBootMs), sid, cold },
+	];
+}

package/src/commands/manager.ts

@@ -284,11 +284,17 @@ export default class Manager extends Command {
 		};
 
 		/** Adopt a warm spare for a provision (bind over IPC). Returns false if none available. */
-		const adoptSpare = (msg: { sessionId: string; tenant: string }): boolean => {
+		const adoptSpare = (msg: { sessionId: string; tenant: string }, managerProvisionMs: number): boolean => {
 			const rec = pool.shift();
 			if (!rec) return false;
 			// `send` exists because the spare was spawned with an `ipc` handler.
-			(rec.proc as { send(m: unknown): void }).send({ type: "bind", sessionId: msg.sessionId, tenant: msg.tenant });
+			(rec.proc as { send(m: unknown): void }).send({
+				type: "bind",
+				sessionId: msg.sessionId,
+				tenant: msg.tenant,
+				provisionMs: managerProvisionMs, // TTFT Phase 2: relayed manager_provision (warm)
+				cold: false, // authoritative: warm adopt
+			});
 			reg.set(msg.sessionId, {
 				sessionId: msg.sessionId,
 				tenant: msg.tenant,
@@ -354,7 +360,7 @@ export default class Manager extends Command {
 			process.exit(0);
 		};
 
-		const spawnWorker = (msg: { sessionId: string; tenant: string }): void => {
+		const spawnWorker = (msg: { sessionId: string; tenant: string }, managerProvisionMs: number): void => {
 			// Registry-dedupe (pickPort) over only the ports free at the OS level.
 			const port = pickPort(reg, range.filter(isPortFree));
 			if (port === null) {
@@ -374,6 +380,12 @@ export default class Manager extends Command {
 					// spawned tenant key is authoritative (undefined removes the var in Bun).
 					XCSH_API_URL: undefined,
 					XCSH_API_TOKEN: undefined,
+					// TTFT Phase 2: relay cold-start timing to the worker (only it has a WS to
+					// the extension). Wall-clock spawn instant + manager_provision ms; COLD=1
+					// marks the authoritative cold spawn.
+					XCSH_TTFT_SPAWN_AT: String(Date.now()),
+					XCSH_TTFT_PROVISION_MS: String(managerProvisionMs),
+					XCSH_TTFT_COLD: "1",
 				},
 				stdout: "ignore",
 				stderr: "ignore",
@@ -417,8 +429,10 @@ export default class Manager extends Command {
 					}
 					return;
 				}
+				const provisionReceivedAt = Date.now(); // TTFT Phase 2: start of manager_provision
 				if (needsProvision(reg, msg.sessionId)) {
-					if (!adoptSpare(msg)) spawnWorker(msg); // adopt a warm spare, else cold-spawn (fallback)
+					const managerProvisionMs = Date.now() - provisionReceivedAt;
+					if (!adoptSpare(msg, managerProvisionMs)) spawnWorker(msg, managerProvisionMs); // adopt a warm spare, else cold-spawn (fallback)
 				}
 				const w = reg.get(msg.sessionId);
 				if (w) w.lastSeen = Date.now(); // touch on every provision (keep-alive)

package/src/commands/worker.ts

@@ -19,6 +19,7 @@ import { ChatHandler } from "../browser/chat-handler";
 import { startBridgeServer } from "../browser/extension-bridge";
 import { createExtensionBridgeTools, EXTENSION_AGENT_TOOL_NAMES } from "../browser/extension-bridge-tools";
 import { setSharedBridgeServer } from "../browser/provider";
+import { coldStartSpans, type SpanFrame } from "../browser/ttft-spans";
 import { initializeWithSettings } from "../discovery";
 import { createAgentSession } from "../sdk";
 import { activateTenantContext } from "../services/session-context-binding";
@@ -109,6 +110,12 @@ export default class Worker extends Command {
 		// Spans only accumulate while recording; nothing prints unless PI_TIMING is set,
 		// and each logger.time() returns its wrapped value unchanged — so a normal
 		// `xcsh worker` run is behaviorally identical to before.
+		// TTFT Phase 2: the manager stamps XCSH_TTFT_SPAWN_AT at Bun.spawn for a cold
+		// spawn; worker_boot(cold) = bridge-listening instant - spawn instant (captures
+		// fork + runtime init, which logger.startTiming below misses).
+		const spawnAtEnv = Number(process.env.XCSH_TTFT_SPAWN_AT);
+		const coldSpawn = process.env.XCSH_TTFT_COLD === "1";
+		const managerProvisionMsEnv = Number(process.env.XCSH_TTFT_PROVISION_MS);
 		logger.startTiming();
 
 		process.env.XCSH_BROWSER_PROVIDER = "extension";
@@ -142,15 +149,50 @@ export default class Worker extends Command {
 		bridge.setSessionInfo(sessionInfoForWorker);
 		ContextService.onContextChange(() => bridge.broadcastTenantChanged());
 
+		// TTFT Phase 2: buffer the per-session cold-start spans and flush them once a
+		// client is actually connected. bridge.send() silently no-ops with no client, so
+		// the flush is gated on `clientConnected` — a cold-boot flush before the extension
+		// connects would otherwise burn the once-latch and lose the spans. Cold path is
+		// populated now (env); warm path by the {bind} handler below.
+		let coldStartBuffer: SpanFrame[] = [];
+		let coldStartSent = false;
+		let clientConnected = false;
+		const flushColdStart = (): void => {
+			if (coldStartSent || !clientConnected || coldStartBuffer.length === 0) return;
+			for (const s of coldStartBuffer) bridge.send(s);
+			coldStartSent = true;
+		};
+		// onConnected (raw WS open) is the deliberate flush trigger: no hello hook is exposed
+		// today, and the bridge's origin check already gates opens to the extension.
+		bridge.onConnected(() => {
+			clientConnected = true;
+			flushColdStart();
+		});
+
+		if (coldSpawn && process.env.XCSH_SESSION_ID && Number.isFinite(spawnAtEnv)) {
+			const workerBootMs = Date.now() - spawnAtEnv; // spawn -> bridge listening
+			const mgrMs = Number.isFinite(managerProvisionMsEnv) ? managerProvisionMsEnv : 0;
+			coldStartBuffer = coldStartSpans(process.env.XCSH_SESSION_ID, true, mgrMs, workerBootMs);
+			// No flush here: at cold boot the extension has not connected yet; onConnected flushes.
+		}
+
 		// Pre-warm pool late-bind: the manager (our parent) sends {bind} over Bun IPC to adopt
 		// this spare for a tab. Apply the identity, activate the tenant's context LIVE, then
 		// re-announce via broadcastTenantChanged (now carrying the real sessionId).
 		process.on("message", (raw: unknown) => {
-			const m = raw as { type?: unknown; sessionId?: unknown; tenant?: unknown };
+			const m = raw as {
+				type?: unknown;
+				sessionId?: unknown;
+				tenant?: unknown;
+				provisionMs?: unknown;
+				cold?: unknown;
+			};
 			if (m?.type !== "bind" || typeof m.sessionId !== "string" || typeof m.tenant !== "string") return;
 			// Capture the narrowed values — TS widens `m.*` back to `unknown` inside the async closure.
 			const sessionId = m.sessionId;
 			const tenant = m.tenant;
+			const bindAt = Date.now(); // TTFT Phase 2: start of warm worker_boot (bind -> bound)
+			const relayedProvisionMs = typeof m.provisionMs === "number" ? m.provisionMs : 0;
 			setWorkerIdentity(sessionId, tenant);
 			void (async () => {
 				try {
@@ -162,6 +204,9 @@ export default class Worker extends Command {
 				// Ack adoption complete (identity applied + context activated + re-announced).
 				// The manager ignores it today; the bench uses it to time adoption latency.
 				process.send?.({ type: "bound", sessionId });
+				// TTFT Phase 2: warm adopt cold-start spans (worker_boot = bind -> bound).
+				coldStartBuffer = coldStartSpans(sessionId, false, relayedProvisionMs, Date.now() - bindAt);
+				flushColdStart();
 			})();
 		});
 
@@ -183,6 +228,9 @@ export default class Worker extends Command {
 			enableMCP: false,
 			enableLsp: false,
 			disableExtensionDiscovery: true,
+			// TTFT Phase 3: load the hermetic bench stand-in provider when the benchmark
+			// sets XCSH_BENCH_EXTENSION (absolute path). Inert for normal workers.
+			...(process.env.XCSH_BENCH_EXTENSION ? { additionalExtensionPaths: [process.env.XCSH_BENCH_EXTENSION] } : {}),
 		});
 
 		const chatHandler = new ChatHandler(bridge, session);

package/src/edit/modes/chunk.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as nodePath from "node:path";
 import type { AgentToolResult } from "@f5-sales-demo/pi-agent-core";
+import { StringEnum } from "@f5-sales-demo/pi-ai";
 import {
 	ChunkAnchorStyle,
 	ChunkEditOp,
@@ -12,7 +13,6 @@ import {
 	type EditOperation as NativeEditOperation,
 } from "@f5-sales-demo/pi-natives";
 import { $envpos } from "@f5-sales-demo/pi-utils";
-import { StringEnum } from "@f5-sales-demo/xcsh";
 import { type Static, Type } from "@sinclair/typebox";
 import type { BunFile } from "bun";
 import { LRUCache } from "lru-cache";

package/src/internal-urls/api-spec-resolve.ts

@@ -47,29 +47,25 @@ export function createApiSpecResolver(
 	return {
 		async resolve(url: InternalUrl): Promise<InternalResource> {
 			const pathname = url.rawPathname ?? url.pathname;
-			const domain = pathname.replace(/^\//, "").replace(/\/$/, "");
-
-			if (!domain) {
-				return makeResource(url, renderDomainIndex(index));
-			}
+			const requestedDomain = pathname.replace(/^\//, "").replace(/\/$/, "");
 
 			// Reserved sub-paths — checked before domain lookup
-			if (domain === "workflows" || domain.startsWith("workflows/")) {
-				const workflowId = domain.replace(/^workflows\/?/, "");
+			if (requestedDomain === "workflows" || requestedDomain.startsWith("workflows/")) {
+				const workflowId = requestedDomain.replace(/^workflows\/?/, "");
 				return makeResource(url, workflowId ? renderWorkflowDetail(workflowId, index) : renderWorkflowIndex(index));
 			}
 
-			if (domain === "errors" || domain.startsWith("errors/")) {
-				const errorKey = domain.replace(/^errors\/?/, "");
+			if (requestedDomain === "errors" || requestedDomain.startsWith("errors/")) {
+				const errorKey = requestedDomain.replace(/^errors\/?/, "");
 				return makeResource(url, errorKey ? renderErrorDetail(errorKey, index) : renderErrorIndex(index));
 			}
 
-			if (domain === "glossary" || domain.startsWith("glossary/")) {
+			if (requestedDomain === "glossary" || requestedDomain.startsWith("glossary/")) {
 				return makeResource(url, renderGlossary(index));
 			}
 
-			if (domain === "validation" || domain.startsWith("validation/")) {
-				const resourceKey = domain.replace(/^validation\/?/, "");
+			if (requestedDomain === "validation" || requestedDomain.startsWith("validation/")) {
+				const resourceKey = requestedDomain.replace(/^validation\/?/, "");
 				return makeResource(
 					url,
 					resourceKey
@@ -78,32 +74,55 @@ export function createApiSpecResolver(
 				);
 			}
 
-			const entry = index.domains.find(d => d.domain === domain);
+			const resourceName = url.searchParams.get("resource");
+
+			// Resolve the domain entry. When a resource is named against a wrong or
+			// omitted domain (e.g. `config?resource=http_loadbalancer`), fall back to
+			// the domain that actually owns that resource instead of erroring out.
+			let entry = requestedDomain ? index.domains.find(d => d.domain === requestedDomain) : undefined;
+			let resolutionNote: string | undefined;
+			if (!entry && resourceName) {
+				const owner = findDomainForResource(index, resourceName);
+				if (owner) {
+					entry = owner;
+					resolutionNote = requestedDomain
+						? `> Note: domain \`${requestedDomain}\` not found; resolved resource \`${resourceName}\` in domain \`${owner.domain}\`.`
+						: `> Note: no domain specified; resolved resource \`${resourceName}\` in domain \`${owner.domain}\`.`;
+				}
+			}
+
 			if (!entry) {
-				return makeResource(url, renderUnknownDomain(domain, index));
+				return makeResource(
+					url,
+					requestedDomain ? renderUnknownDomain(requestedDomain, index) : renderDomainIndex(index),
+				);
 			}
 
+			const domain = entry.domain;
+			const withNote = (content: string): string => (resolutionNote ? `${resolutionNote}\n\n${content}` : content);
+
 			try {
-				const resource = url.searchParams.get("resource");
 				const pathFilter = url.searchParams.get("path");
 
-				if (resource) {
+				if (resourceName) {
 					const crud = url.searchParams.get("crud") === "true";
 					const spec = lookup(domain);
-					const matchingPaths = filterPathsByResource(spec, resource, entry);
+					const matchingPaths = filterPathsByResource(spec, resourceName, entry);
 					if (Object.keys(matchingPaths).length === 0) {
-						return makeResource(url, renderUnknownResource(resource, entry, spec));
+						return makeResource(url, withNote(renderUnknownResource(resourceName, entry, spec)));
 					}
 					return makeResource(
 						url,
-						renderResourceSpec(
-							domain,
-							resource,
-							spec,
-							entry,
-							{ crudOnly: crud },
-							enrichments?.[domain],
-							validationData,
+						withNote(
+							renderResourceSpec(
+								domain,
+								resourceName,
+								spec,
+								entry,
+								{ crudOnly: crud },
+								enrichments?.[domain],
+								validationData,
+							),
 						),
 					);
 				}
@@ -123,6 +142,11 @@ export function createApiSpecResolver(
 	};
 }
 
+/** Find the domain entry that owns a resource by name (for cross-domain resolution). */
+function findDomainForResource(index: ApiSpecIndex, resourceName: string): ApiSpecDomainEntry | undefined {
+	return index.domains.find(d => d.resources.some(r => r.name === resourceName));
+}
+
 function makeResource(url: InternalUrl, content: string): InternalResource {
 	return {
 		url: url.href,

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.61.0",
-	"commit": "54faf1b4029f7a7a4251c5cc6776c789b3e1af5c",
-	"shortCommit": "54faf1b",
+	"version": "19.61.2",
+	"commit": "b6923d7302a3f43d8b9600ed4bddd6e26f16fad6",
+	"shortCommit": "b6923d7",
 	"branch": "main",
-	"tag": "v19.61.0",
-	"commitDate": "2026-07-05T20:10:34Z",
-	"buildDate": "2026-07-05T20:32:34.362Z",
+	"tag": "v19.61.2",
+	"commitDate": "2026-07-07T05:10:31Z",
+	"buildDate": "2026-07-07T05:33:53.753Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/54faf1b4029f7a7a4251c5cc6776c789b3e1af5c",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/b6923d7302a3f43d8b9600ed4bddd6e26f16fad6",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.2"
 };