@f5-sales-demo/xcsh 19.54.0 → 19.55.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.54.0",
+	"version": "19.55.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -55,13 +55,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.54.0",
-		"@f5-sales-demo/pi-agent-core": "19.54.0",
-		"@f5-sales-demo/pi-ai": "19.54.0",
-		"@f5-sales-demo/pi-natives": "19.54.0",
-		"@f5-sales-demo/pi-resource-management": "19.54.0",
-		"@f5-sales-demo/pi-tui": "19.54.0",
-		"@f5-sales-demo/pi-utils": "19.54.0",
+		"@f5-sales-demo/xcsh-stats": "19.55.0",
+		"@f5-sales-demo/pi-agent-core": "19.55.0",
+		"@f5-sales-demo/pi-ai": "19.55.0",
+		"@f5-sales-demo/pi-natives": "19.55.0",
+		"@f5-sales-demo/pi-resource-management": "19.55.0",
+		"@f5-sales-demo/pi-tui": "19.55.0",
+		"@f5-sales-demo/pi-utils": "19.55.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/generate-extension-capabilities.ts

@@ -54,6 +54,7 @@ const output = [
 	"export interface ExtensionCapabilities {",
 	"\treadonly version: string;",
 	"\treadonly contractVersion: string;",
+	"\treadonly multiPortDiscovery?: boolean;",
 	"\treadonly protocol: string;",
 	"\treadonly tools: readonly ExtensionToolDef[];",
 	"\treadonly features: Record<string, unknown>;",

package/src/browser/capabilities.generated.ts

@@ -18,6 +18,7 @@ export interface ExtensionToolDef {
 export interface ExtensionCapabilities {
 	readonly version: string;
 	readonly contractVersion: string;
+	readonly multiPortDiscovery?: boolean;
 	readonly protocol: string;
 	readonly tools: readonly ExtensionToolDef[];
 	readonly features: Record<string, unknown>;
@@ -25,7 +26,8 @@ export interface ExtensionCapabilities {
 
 export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	"version": "0.1.0",
-	"contractVersion": "1.4.0",
+	"contractVersion": "1.5.0",
+	"multiPortDiscovery": true,
 	"protocol": "tool_request/result",
 	"tools": [
 		{
@@ -613,6 +615,16 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 			},
 			"flags": {}
 		},
+		{
+			"name": "diag_bridges",
+			"summary": "List discovered xcsh bridges (port, tenant, env, sessionId, lastSeen) for multi-session diagnostics.",
+			"category": "read",
+			"params": {
+				"type": "object",
+				"properties": {}
+			},
+			"flags": {}
+		},
 		{
 			"name": "capture_login_flow",
 			"summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",
@@ -813,6 +825,6 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	}
 };
 
-export const EXTENSION_CONTRACT_VERSION = "1.4.0";
+export const EXTENSION_CONTRACT_VERSION = "1.5.0";
 
-export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","set_bridge_port","navigate","login","scroll_to","resize_window","tabs_list","tabs_create","tabs_close","click","click_element","click_xy","type_text","form_input","key_press","select_option","label_select","file_upload","read_ax","get_page_text","query_dom","find","wait_for","assert_text","screenshot","read_console","read_network","diag_suspension","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];
+export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","set_bridge_port","navigate","login","scroll_to","resize_window","tabs_list","tabs_create","tabs_close","click","click_element","click_xy","type_text","form_input","key_press","select_option","label_select","file_upload","read_ax","get_page_text","query_dom","find","wait_for","assert_text","screenshot","read_console","read_network","diag_suspension","diag_bridges","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];

package/src/browser/capabilities.json

@@ -1,6 +1,7 @@
 {
   "version": "0.1.0",
-  "contractVersion": "1.4.0",
+  "contractVersion": "1.5.0",
+  "multiPortDiscovery": true,
   "protocol": "tool_request/result",
   "tools": [
     {
@@ -539,6 +540,16 @@
       },
       "flags": {}
     },
+    {
+      "name": "diag_bridges",
+      "summary": "List discovered xcsh bridges (port, tenant, env, sessionId, lastSeen) for multi-session diagnostics.",
+      "category": "read",
+      "params": {
+        "type": "object",
+        "properties": {}
+      },
+      "flags": {}
+    },
     {
       "name": "capture_login_flow",
       "summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",

package/src/browser/chat-conformance.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.4.0",
+  "contractVersion": "1.5.0",
   "schemas": {
     "chat_request": {
       "type": "object",

package/src/browser/extension-bridge.ts

@@ -67,6 +67,25 @@ export function resolvePort(port?: number): number {
 	return DEFAULT_PORT;
 }
 
+/** Inclusive loopback discovery range for auto-selected bridge ports. */
+export const PORT_RANGE_START = 19222;
+export const PORT_RANGE_END = 19241;
+
+/** Every port in the discovery range, lowest first. */
+export function portCandidates(): number[] {
+	const out: number[] = [];
+	for (let p = PORT_RANGE_START; p <= PORT_RANGE_END; p++) out.push(p);
+	return out;
+}
+
+/** The explicitly forced port (arg → XCSH_BRIDGE_PORT), or null to auto-select. */
+export function resolveForcedPort(port?: number): number | null {
+	if (typeof port === "number" && Number.isFinite(port) && port > 0) return port;
+	const env = Number(process.env.XCSH_BRIDGE_PORT);
+	if (Number.isFinite(env) && env > 0) return env;
+	return null;
+}
+
 /**
  * Loopback WebSocket server bridging xcsh to the Chrome extension. Speaks JSON
  * over WS frames: requests `{type:"tool_request",...}`, replies
@@ -159,56 +178,58 @@ export class BridgeServer {
 		this.#resolveClient(channelId)?.send(JSON.stringify(payload));
 	}
 
-	/** Bind the WebSocket server to a loopback port. Called by {@link startBridgeServer}. */
-	listen(port: number, opts?: { skipOriginCheck?: boolean }): void {
-		this.#server = Bun.serve({
-			port,
-			hostname: "127.0.0.1",
-			fetch: (req, server) => {
-				// Validate the Origin header: only the xcsh Chrome extension may connect.
-				// This restores the access-control guarantee that the Unix socket's 0o600
-				// permissions previously provided.
-				if (!opts?.skipOriginCheck) {
-					const origin = req.headers.get("origin") ?? "";
-					const { EXTENSION_ID } = require("../cli/chrome-cli");
-					if (origin !== `chrome-extension://${EXTENSION_ID}`) {
-						return new Response("Forbidden", { status: 403 });
+	#onOpen(ws: ServerWebSocket<undefined>): void {
+		// Assign a channel ID to each connection. For backwards compat (single
+		// extension), the first connection gets "default". Additional connections
+		// get "ch-1", "ch-2", etc. — supporting multi-tab parallelism.
+		const channelId = this.#clients.size === 0 ? "default" : `ch-${++this.#nextChannelIndex}`;
+		(ws as unknown as { channelId: string }).channelId = channelId;
+		this.#clients.set(channelId, ws);
+		// Start a heartbeat ping to keep the MV3 service worker alive.
+		// Chrome suspends idle SWs after ~30s; a ping every 15s prevents that.
+		if (!this.#heartbeat) {
+			this.#heartbeat = setInterval(() => {
+				for (const c of this.#clients.values()) {
+					try {
+						c.send(JSON.stringify({ type: "ping" }));
+					} catch {
+						/* client may have dropped */
 					}
 				}
-				if (server.upgrade(req)) return undefined;
-				return new Response("xcsh bridge: WebSocket only", { status: 426 });
-			},
-			websocket: {
-				open: ws => {
-					// Assign a channel ID to each connection. For backwards compat (single
-					// extension), the first connection gets "default". Additional connections
-					// get "ch-1", "ch-2", etc. — supporting multi-tab parallelism.
-					const channelId = this.#clients.size === 0 ? "default" : `ch-${++this.#nextChannelIndex}`;
-					(ws as unknown as { channelId: string }).channelId = channelId;
-					this.#clients.set(channelId, ws);
-					// Start a heartbeat ping to keep the MV3 service worker alive.
-					// Chrome suspends idle SWs after ~30s; a ping every 15s prevents that.
-					if (!this.#heartbeat) {
-						this.#heartbeat = setInterval(() => {
-							for (const c of this.#clients.values()) {
-								try {
-									c.send(JSON.stringify({ type: "ping" }));
-								} catch {
-									/* client may have dropped */
-								}
-							}
-						}, 15_000);
+			}, 15_000);
+		}
+		for (const cb of this.#onConnected) cb();
+	}
+
+	/** Try to bind the loopback WS server to `port`. Returns false on EADDRINUSE
+	 * (so the caller can try the next candidate); rethrows any other error. */
+	listen(port: number, opts?: { skipOriginCheck?: boolean }): boolean {
+		try {
+			this.#server = Bun.serve({
+				port,
+				hostname: "127.0.0.1",
+				fetch: (req, server) => {
+					if (!opts?.skipOriginCheck) {
+						const origin = req.headers.get("origin") ?? "";
+						const { EXTENSION_ID } = require("../cli/chrome-cli");
+						if (origin !== `chrome-extension://${EXTENSION_ID}`) {
+							return new Response("Forbidden", { status: 403 });
+						}
 					}
-					for (const cb of this.#onConnected) cb();
-				},
-				message: (ws, message) => {
-					this.#handleMessage(ws, message);
+					if (server.upgrade(req)) return undefined;
+					return new Response("xcsh bridge: WebSocket only", { status: 426 });
 				},
-				close: ws => {
-					this.#onClose(ws);
+				websocket: {
+					open: ws => this.#onOpen(ws),
+					message: (ws, message) => this.#handleMessage(ws, message),
+					close: ws => this.#onClose(ws),
 				},
-			},
-		});
+			});
+			return true;
+		} catch (e) {
+			if (e instanceof Error && /EADDRINUSE|address already in use|in use/i.test(e.message)) return false;
+			throw e;
+		}
 	}
 
 	#handleMessage(ws: ServerWebSocket<undefined>, message: string | Buffer): void {
@@ -229,10 +250,12 @@ export class BridgeServer {
 		} else if (msg.type === "hello") {
 			// Identity handshake: tell the extension which tenant this process serves.
 			const info = this.#sessionInfo?.() ?? { tenant: null, env: null, apiUrl: null };
+			const { EXTENSION_CONTRACT_VERSION } = require("./capabilities.generated");
 			ws.send(
 				JSON.stringify({
 					type: "hello_ack",
 					sessionId: this.#sessionId,
+					contractVersion: EXTENSION_CONTRACT_VERSION,
 					tenant: info.tenant,
 					env: info.env,
 					apiUrl: info.apiUrl,
@@ -293,12 +316,23 @@ export class BridgeServer {
 }
 
 /**
- * Start the {@link BridgeServer} on the resolved loopback port (explicit arg,
- * then `XCSH_BRIDGE_PORT`, then {@link DEFAULT_PORT}). The WebSocket transport
+ * Start the {@link BridgeServer} on the resolved loopback port. If a port is
+ * forced (explicit arg or `XCSH_BRIDGE_PORT`) it must be free — throws loudly
+ * if taken. Otherwise, auto-selects the lowest free port in the discovery range
+ * ({@link PORT_RANGE_START}–{@link PORT_RANGE_END}). The WebSocket transport
  * needs no filesystem setup — Chrome connects directly to `ws://127.0.0.1:<port>`.
  */
 export async function startBridgeServer(port?: number, opts?: { skipOriginCheck?: boolean }): Promise<BridgeServer> {
 	const server = new BridgeServer();
-	server.listen(resolvePort(port), opts);
-	return server;
+	const forced = resolveForcedPort(port);
+	if (forced !== null) {
+		if (!server.listen(forced, opts)) {
+			throw new Error(`XCSH_BRIDGE_PORT ${forced} is already in use — free it or pick another port`);
+		}
+		return server;
+	}
+	for (const candidate of portCandidates()) {
+		if (server.listen(candidate, opts)) return server;
+	}
+	throw new Error(`no free xcsh bridge port in ${PORT_RANGE_START}-${PORT_RANGE_END} — is another app on the range?`);
 }

package/src/browser/extension-page-actions.ts

@@ -501,7 +501,6 @@ export class ExtensionPageActions implements PageActions {
 		throw new Error(`waitFor "${selector}" timed out after ${ms}ms`);
 	}
 
-	// biome-ignore lint/suspicious/useAwait: signature is async (PageActions contract)
 	async screenshot(_file: string): Promise<void> {
 		// Intentionally a no-op for the extension provider. CDP captureScreenshot
 		// transiently FREEZES the MV3 service worker; in observable mode the runner

package/src/cli/chrome-cli.ts

@@ -7,7 +7,7 @@
  */
 
 import { acquirePage, type BrowserProviderStatus, CdpBrowserProvider } from "../browser";
-import { resolvePort } from "../browser/extension-bridge";
+import { PORT_RANGE_END, PORT_RANGE_START, resolveForcedPort } from "../browser/extension-bridge";
 
 type Settings = { get(key: string): unknown };
 
@@ -43,12 +43,17 @@ export async function runChromeCommand(action: ChromeAction, settings: Settings)
 	if (action === "status") return renderStatus(await provider.status());
 	if (action === "setup") {
 		// The extension connects directly over a loopback WebSocket — no native-messaging
-		// host manifest to install. Report the port so the user can point the extension at it.
-		const port = resolvePort();
+		// host manifest to install. A forced port is reported exactly; otherwise xcsh
+		// auto-selects the lowest free port in the discovery range at launch.
+		const forced = resolveForcedPort();
+		const where =
+			forced !== null
+				? `ws://127.0.0.1:${forced} (forced via XCSH_BRIDGE_PORT)`
+				: `the lowest free port in ${PORT_RANGE_START}-${PORT_RANGE_END} (printed in the xcsh startup banner)`;
 		return (
-			`The xcsh Chrome extension connects directly to xcsh over a loopback WebSocket on ` +
-			`ws://127.0.0.1:${port} (override with XCSH_BRIDGE_PORT).\n` +
-			`Install/keep the xcsh Chrome extension from the Web Store, then it can drive your real Chrome:\n  ${WEB_STORE_URL}`
+			`The xcsh Chrome extension connects directly to xcsh over a loopback WebSocket on ${where}.\n` +
+			`The extension scans that range and links each tenant's xcsh automatically.\n` +
+			`Install/keep the xcsh Chrome extension from the Web Store:\n  ${WEB_STORE_URL}`
 		);
 	}
 	// relaunch: self-consented rung 3 — force allowRelaunch regardless of the setting.

package/src/extensibility/extensions/bundled/herdr-reporter.ts

@@ -0,0 +1,102 @@
+import type { ExtensionAPI } from "@f5-sales-demo/xcsh";
+
+/**
+ * herdr integration (bundled, default-on).
+ *
+ * Reports xcsh's live agent state to the herdr terminal multiplexer over its
+ * socket API so an xcsh pane shows up as a first-class "xcsh" assistant with an
+ * idle / working / blocked indicator.
+ *
+ * xcsh is a fork of pi; a user may have both installed, so this reporter always
+ * identifies itself as "xcsh" (never "pi") and claims pane authority via
+ * `--source xcsh` so herdr's passive pi-detection heuristics cannot mislabel the
+ * pane.
+ *
+ * The extension is completely inert unless it is running inside a herdr pane
+ * (detected via the `HERDR_PANE_ID` environment variable herdr injects), so it
+ * has zero effect for users who do not run xcsh under herdr.
+ */
+
+const HERDR_AGENT_LABEL = "xcsh";
+
+export default function herdrReporter(pi: ExtensionAPI): void {
+	const paneId = process.env.HERDR_PANE_ID;
+	if (!paneId) {
+		// Not running under herdr — do not register anything.
+		return;
+	}
+
+	let seq = 0;
+	// Tracks whether an interactive prompt is currently awaiting the user, so an
+	// agent_end that fires while a prompt is open is reported as blocked, not idle.
+	let promptOpen = false;
+
+	pi.setLabel(HERDR_AGENT_LABEL);
+
+	// Fire-and-forget: a missing or failing herdr CLI must never disturb the agent.
+	const runHerdr = (args: string[]): void => {
+		pi.exec("herdr", args).catch((err: unknown) => {
+			pi.logger.debug("herdr report failed", {
+				error: err instanceof Error ? err.message : String(err),
+			});
+		});
+	};
+
+	const report = (state: "idle" | "working" | "blocked"): void => {
+		runHerdr([
+			"pane",
+			"report-agent",
+			paneId,
+			"--source",
+			HERDR_AGENT_LABEL,
+			"--agent",
+			HERDR_AGENT_LABEL,
+			"--state",
+			state,
+			"--seq",
+			String(seq++),
+		]);
+	};
+
+	// Announce presence as soon as the session is initialized.
+	pi.on("session_start", () => {
+		report("idle");
+	});
+
+	// Busy while the agent loop is streaming a response.
+	pi.on("agent_start", () => {
+		report("working");
+	});
+
+	// Back to idle when the loop ends — unless we are waiting on a user prompt.
+	pi.on("agent_end", () => {
+		report(promptOpen ? "blocked" : "idle");
+	});
+
+	// An interactive prompt (permission gate, ask tool, confirm/input) is
+	// awaiting the user: that is herdr's "needs attention" (blocked) state.
+	pi.on("user_prompt_start", () => {
+		promptOpen = true;
+		report("blocked");
+	});
+
+	pi.on("user_prompt_end", (_event, ctx) => {
+		promptOpen = false;
+		report(ctx.isIdle() ? "idle" : "working");
+	});
+
+	// Relinquish pane authority so herdr stops showing xcsh once we exit.
+	pi.on("session_shutdown", () => {
+		runHerdr([
+			"pane",
+			"release-agent",
+			paneId,
+			"--source",
+			HERDR_AGENT_LABEL,
+			"--agent",
+			HERDR_AGENT_LABEL,
+			"--seq",
+			String(seq++),
+		]);
+	});
+}

package/src/extensibility/extensions/loader.ts

@@ -20,6 +20,7 @@ import type { CustomMessage } from "../../session/messages";
 import { EventBus } from "../../utils/event-bus";
 import { getAllPluginExtensionPaths } from "../plugins/loader";
 import { resolvePath } from "../utils";
+import herdrReporter from "./bundled/herdr-reporter";
 import type {
 	Extension,
 	ExtensionAPI,
@@ -480,6 +481,37 @@ async function discoverExtensionsInDir(dir: string): Promise<string[]> {
 /**
  * Discover and load extensions from standard locations.
  */
+/** Extensions bundled with xcsh and loaded by default (before user extensions). */
+const BUNDLED_EXTENSIONS: ReadonlyArray<{ name: string; factory: ExtensionFactory }> = [
+	{ name: "herdr-reporter", factory: herdrReporter },
+];
+
+/**
+ * Load the extensions that ship with xcsh. They share the runtime and event bus
+ * of the discovered user extensions and are prepended so user extensions keep the
+ * ability to override. A bundled extension that throws is recorded as an error
+ * but never aborts the overall load.
+ */
+async function loadBundledExtensions(
+	result: LoadExtensionsResult,
+	cwd: string,
+	eventBus: EventBus,
+	isDisabled: (name: string) => boolean,
+): Promise<void> {
+	for (const { name, factory } of BUNDLED_EXTENSIONS) {
+		if (isDisabled(name)) continue;
+		try {
+			const extension = await loadExtensionFromFactory(factory, cwd, eventBus, result.runtime, `bundled:${name}`);
+			result.extensions.unshift(extension);
+		} catch (err) {
+			result.errors.push({
+				path: `bundled:${name}`,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
+}
+
 export async function discoverAndLoadExtensions(
 	configuredPaths: string[],
 	cwd: string,
@@ -568,5 +600,8 @@ export async function discoverAndLoadExtensions(
 		addPath(resolved);
 	}
 
-	return loadExtensions(allPaths, cwd, eventBus);
+	const resolvedEventBus = eventBus ?? new EventBus();
+	const result = await loadExtensions(allPaths, cwd, resolvedEventBus);
+	await loadBundledExtensions(result, cwd, resolvedEventBus, isDisabledName);
+	return result;
 }

package/src/extensibility/extensions/types.ts

@@ -541,6 +541,26 @@ export interface MessageEndEvent {
 	message: AgentMessage;
 }
 
+/** Kind of interactive prompt currently awaiting the user. */
+export type UserPromptKind = "select" | "confirm" | "input";
+
+/**
+ * Fired when an interactive prompt (permission gate, `ask` tool, confirm/input
+ * dialog) is shown and is awaiting the user. Signals a "blocked / needs
+ * attention" state that is otherwise not observable from the agent event stream,
+ * since the session stays `isStreaming` while a prompt is open.
+ */
+export interface UserPromptStartEvent {
+	type: "user_prompt_start";
+	kind: UserPromptKind;
+}
+
+/** Fired when an interactive prompt resolves (answered, cancelled, or timed out). */
+export interface UserPromptEndEvent {
+	type: "user_prompt_end";
+	kind: UserPromptKind;
+}
+
 /** Fired when a tool starts executing */
 export interface ToolExecutionStartEvent {
 	type: "tool_execution_start";
@@ -817,6 +837,8 @@ export type ExtensionEvent =
 	| MessageStartEvent
 	| MessageUpdateEvent
 	| MessageEndEvent
+	| UserPromptStartEvent
+	| UserPromptEndEvent
 	| ToolExecutionStartEvent
 	| ToolExecutionUpdateEvent
 	| ToolExecutionEndEvent
@@ -1011,6 +1033,8 @@ export interface ExtensionAPI {
 	on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): void;
 	on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): void;
 	on(event: "message_end", handler: ExtensionHandler<MessageEndEvent>): void;
+	on(event: "user_prompt_start", handler: ExtensionHandler<UserPromptStartEvent>): void;
+	on(event: "user_prompt_end", handler: ExtensionHandler<UserPromptEndEvent>): void;
 	on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): void;
 	on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): void;
 	on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): void;

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.54.0",
-	"commit": "adc80f2ff5554dd9a0359ce4b1ed170be3af79e7",
-	"shortCommit": "adc80f2",
+	"version": "19.55.0",
+	"commit": "d4705fb3ced007a59e110d11971eb25c3dc9e83f",
+	"shortCommit": "d4705fb",
 	"branch": "main",
-	"tag": "v19.54.0",
-	"commitDate": "2026-07-02T03:04:58Z",
-	"buildDate": "2026-07-02T03:37:42.022Z",
+	"tag": "v19.55.0",
+	"commitDate": "2026-07-02T22:38:12Z",
+	"buildDate": "2026-07-02T23:02:06.036Z",
 	"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/adc80f2ff5554dd9a0359ce4b1ed170be3af79e7",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.54.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/d4705fb3ced007a59e110d11971eb25c3dc9e83f",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.55.0"
 };

package/src/main.ts

@@ -617,16 +617,14 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 	const cwd = getProjectDir();
 	await logger.time("settings:init", Settings.init, { cwd });
 
-	// F5 XC context loading — optional, never blocks startup.
-	// NOTE: This runs in the CLI path only. SDK consumers using createAgentSession()
-	// directly must call ContextService.init(configDir).loadActive() themselves.
+	// F5 XC context is session-scoped: nothing loads at startup. We still init the
+	// ContextService singleton so /context commands and the session bootstrap work.
 	try {
 		const { ContextService } = await import("./services/xcsh-context");
 		const { getXCSHConfigDir } = await import("@f5-sales-demo/pi-utils");
-		const contextService = ContextService.init(getXCSHConfigDir());
-		await contextService.loadActive(cwd);
+		ContextService.init(getXCSHConfigDir());
 	} catch {
-		// F5 XC auth is optional — silently continue if anything fails
+		// ContextService optional (SDK consumers / tests) — continue.
 	}
 
 	if (parsedArgs.mode === "rpc") {
@@ -816,6 +814,7 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 	let sessionReady = false;
 	if (process.env.XCSH_BROWSER_PROVIDER?.toLowerCase() === "extension") {
 		bridgeServer = await startBridgeServer();
+		console.error(`[xcsh] extension bridge listening on ws://127.0.0.1:${bridgeServer.port}`);
 		// Make the bridge globally available so ALL selectProvider() calls reuse it
 		// (prevents starting a conflicting second bridge on the same port).
 		setSharedBridgeServer(bridgeServer);

package/src/modes/controllers/extension-ui-controller.ts

@@ -13,6 +13,7 @@ import type {
 	ExtensionWidgetContent,
 	ExtensionWidgetOptions,
 	TerminalInputHandler,
+	UserPromptKind,
 } from "../../extensibility/extensions";
 import { HookEditorComponent } from "../../modes/components/hook-editor";
 import { HookInputComponent } from "../../modes/components/hook-input";
@@ -652,6 +653,15 @@ export class ExtensionUiController {
 	/**
 	 * Show a selector for hooks.
 	 */
+	/**
+	 * Notify extensions that an interactive prompt is awaiting the user
+	 * (blocked / needs-attention) and, via the returned promise's settlement,
+	 * when it resolves. Fire-and-forget: reporting must never disturb the prompt.
+	 */
+	#emitPromptSignal(type: "user_prompt_start" | "user_prompt_end", kind: UserPromptKind): void {
+		this.ctx.session.extensionRunner?.emit({ type, kind }).catch(() => {});
+	}
+
 	showHookSelector(
 		title: string,
 		options: string[],
@@ -713,6 +723,7 @@ export class ExtensionUiController {
 		this.ctx.editorContainer.addChild(this.ctx.hookSelector);
 		this.ctx.ui.setFocus(this.ctx.hookSelector);
 		this.ctx.ui.requestRender();
+		this.#emitPromptSignal("user_prompt_start", "select");
 		if (dialogOptions?.signal) {
 			if (dialogOptions.signal.aborted) {
 				onAbort();
@@ -720,7 +731,7 @@ export class ExtensionUiController {
 				dialogOptions.signal.addEventListener("abort", onAbort, { once: true });
 			}
 		}
-		return promise;
+		return promise.finally(() => this.#emitPromptSignal("user_prompt_end", "select"));
 	}
 	/**
 	 * Hide the hook selector.
@@ -786,6 +797,7 @@ export class ExtensionUiController {
 		this.ctx.editorContainer.addChild(this.ctx.hookInput);
 		this.ctx.ui.setFocus(this.ctx.hookInput);
 		this.ctx.ui.requestRender();
+		this.#emitPromptSignal("user_prompt_start", "input");
 		if (dialogOptions?.signal) {
 			if (dialogOptions.signal.aborted) {
 				onAbort();
@@ -793,7 +805,7 @@ export class ExtensionUiController {
 				dialogOptions.signal.addEventListener("abort", onAbort, { once: true });
 			}
 		}
-		return promise;
+		return promise.finally(() => this.#emitPromptSignal("user_prompt_end", "input"));
 	}
 
 	/**

package/src/sdk.ts

@@ -771,6 +771,41 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const existingSession = logger.time("loadSessionContext", () =>
 		deobfuscateSessionContext(sessionManager.buildSessionContext(), obfuscator),
 	);
+
+	// --- Session-scoped context bootstrap ------------------------------------
+	// No context is auto-loaded at startup. The session decides: a RESUMED session
+	// re-activates the context recorded in its context_change log; a NEW session
+	// smart-auto-binds (folder-local, else the single context, else ask). Loading
+	// is via the existing activate(); auth is validated but never blocks resume.
+	try {
+		const { ContextService } = await import("./services/xcsh-context");
+		const { resolveAutoBind, chooseSessionContext } = await import("./services/session-context-binding");
+		const svc = ContextService.instance; // inited in main.ts (throws for SDK/tests → caught)
+		if (!process.env.XCSH_API_URL) {
+			const bound = existingSession.activeContextName; // resumed binding, if any
+			const available = (await svc.listContexts()).map(c => c.name);
+			const folderContext = await svc.resolveFolderContextName(cwd);
+			const autoBind = resolveAutoBind({ kind: "cli", availableContexts: available, folderContext });
+			const choice = chooseSessionContext(bound, autoBind);
+			if ("activate" in choice) {
+				try {
+					await svc.activate(choice.activate); // fires onContextChange → records context_change
+					await svc.validateToken(); // authenticate; non-blocking
+				} catch (err) {
+					// Context deleted since last use, or auth failed → surface, never block.
+					logger.warn("XCSH: session context bootstrap could not fully activate", {
+						context: choice.activate,
+						error: String(err),
+					});
+				}
+			}
+			// choice.needsSelection / choice.none → leave unbound; the /context status
+			// line and tools already prompt "run /context activate".
+		}
+	} catch {
+		// ContextService not initialized (SDK consumers / tests) — skip bootstrap.
+	}
+
 	const existingBranch = logger.time("getSessionBranch", () => sessionManager.getBranch());
 	const hasExistingSession = existingBranch.length > 0;
 	const hasThinkingEntry = existingBranch.some(entry => entry.type === "thinking_level_change");

package/src/services/session-context-binding.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure decisions for session-scoped context binding. No I/O — the caller
+ * gathers inputs (available contexts, folder-local context, tenant key) and
+ * performs the activation. Key-agnostic so the deferred extension/daemon phase
+ * reuses it unchanged.
+ */
+
+export type SessionKind = "cli" | "extension";
+
+export interface AutoBindInput {
+	kind: SessionKind;
+	/** Names of all available (global) contexts. */
+	availableContexts: string[];
+	/** CLI: the folder-local context name resolved from `.xcsh/`, if any. */
+	folderContext?: string | null;
+	/** Extension: the tenant|env key of the focused tab. */
+	tenantKey?: string | null;
+	/** Extension: contextName → its tenant|env key (derived from apiUrl). */
+	contextTenantKeys?: Record<string, string>;
+}
+
+export type AutoBindResult = { kind: "bind"; contextName: string } | { kind: "needsSelection" } | { kind: "none" };
+
+/** Decide which context (if any) a NEW session should auto-bind. */
+export function resolveAutoBind(input: AutoBindInput): AutoBindResult {
+	if (input.kind === "extension") {
+		if (!input.tenantKey) return { kind: "none" };
+		const match = Object.entries(input.contextTenantKeys ?? {}).find(([, key]) => key === input.tenantKey);
+		return match ? { kind: "bind", contextName: match[0] } : { kind: "needsSelection" };
+	}
+	// cli
+	if (input.folderContext) return { kind: "bind", contextName: input.folderContext };
+	if (input.availableContexts.length === 1) return { kind: "bind", contextName: input.availableContexts[0] };
+	if (input.availableContexts.length === 0) return { kind: "none" };
+	return { kind: "needsSelection" };
+}
+
+export type SessionContextChoice = { activate: string } | { needsSelection: true } | { none: true };
+
+/** Resume (boundContextName present) wins; otherwise fall back to the auto-bind result. */
+export function chooseSessionContext(
+	boundContextName: string | undefined,
+	autoBind: AutoBindResult,
+): SessionContextChoice {
+	if (boundContextName) return { activate: boundContextName };
+	if (autoBind.kind === "bind") return { activate: autoBind.contextName };
+	if (autoBind.kind === "needsSelection") return { needsSelection: true };
+	return { none: true };
+}

package/src/services/xcsh-context.ts

@@ -363,6 +363,19 @@ export class ContextService {
 		return this.#activeContext?.defaultNamespace ?? null;
 	}
 
+	/** The project-local (`.xcsh/`) context NAME for `cwd`, or null. No activation,
+	 * no settings mutation — a pure lookup used by the session bootstrap. */
+	async resolveFolderContextName(cwd: string): Promise<string | null> {
+		try {
+			const resolver = new ContextResolver({ paths: xcshContextPaths });
+			const local = await resolver.resolve(cwd);
+			if (local && local.source === "local") return (local.context as XCSHContext).name ?? null;
+		} catch {
+			/* no local context */
+		}
+		return null;
+	}
+
 	async loadActive(cwd?: string): Promise<XCSHContext | null> {
 		// FR-102: XCSH_API_URL is the signal to skip context loading entirely.
 		// Subprocesses inherit process.env, so they already see the env vars directly.
@@ -429,19 +442,10 @@ export class ContextService {
 		// sync form keeps createContext/deleteContext race-free with no coordination.
 		await this.listContexts();
 
-		let contextName = this.#readActiveContextName();
-
-		// FR-104: auto-activate if exactly one context exists
-		let autoActivated = false;
-		if (!contextName) {
-			const contexts = this.#listContextFiles();
-			if (contexts.length === 1) {
-				contextName = contexts[0].replace(/\.json$/, "");
-				autoActivated = true;
-			} else {
-				return null;
-			}
-		}
+		const contextName = this.#readActiveContextName();
+		// Session-scoped: no auto-activate of a lone context. Without an explicit
+		// active_context pointer there is no global default to load.
+		if (!contextName) return null;
 
 		// Read the context JSON
 		const context = this.#readContext(contextName);
@@ -460,12 +464,6 @@ export class ContextService {
 			return null;
 		}
 
-		// Only persist active_context after the context validates
-		if (autoActivated) {
-			this.#atomicWrite(this.activeContextPath, contextName);
-			logger.debug("XCSH: auto-activated single context", { name: contextName });
-		}
-
 		this.#activeContext = context;
 		this.#applyToSettings(context);
 		// Detect mixed source: context loaded but some fields come from process.env
@@ -495,9 +493,6 @@ export class ContextService {
 
 		this.#assertCompatibleVersion(context);
 
-		// NFR-402: write active_context first — if it fails, don't update settings
-		this.#atomicWrite(this.activeContextPath, name);
-
 		if (this.#activeContext && this.#activeContext.name !== name) {
 			this.#previousContextName = this.#activeContext.name;
 		}