@f5-sales-demo/xcsh 21.2.0 → 21.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.2.0",
+	"version": "21.4.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",
@@ -61,13 +61,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
-		"@f5-sales-demo/pi-agent-core": "21.2.0",
-		"@f5-sales-demo/pi-ai": "21.2.0",
-		"@f5-sales-demo/pi-natives": "21.2.0",
-		"@f5-sales-demo/pi-resource-management": "21.2.0",
-		"@f5-sales-demo/pi-tui": "21.2.0",
-		"@f5-sales-demo/pi-utils": "21.2.0",
-		"@f5-sales-demo/xcsh-stats": "21.2.0",
+		"@f5-sales-demo/pi-agent-core": "21.4.0",
+		"@f5-sales-demo/pi-ai": "21.4.0",
+		"@f5-sales-demo/pi-natives": "21.4.0",
+		"@f5-sales-demo/pi-resource-management": "21.4.0",
+		"@f5-sales-demo/pi-tui": "21.4.0",
+		"@f5-sales-demo/pi-utils": "21.4.0",
+		"@f5-sales-demo/xcsh-stats": "21.4.0",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",

package/src/browser/headless-bridge.ts

@@ -1,20 +1,17 @@
 /**
- * Headless chat bridge — the no-TUI extension-bridge host used by `xcsh office
- * serve` so one command yields a working task pane (pane files + a live chat/
- * host-tool bridge). It mirrors the proven `xcsh worker` bootstrap
- * (`commands/worker.ts`) MINUS the fleet concerns (manager keepalive, pre-warm
- * IPC bind, TTFT spans): set the browser-provider env, init Settings + Context,
- * quiet startup, provision the wss cert, start the bridge, publish session info,
- * create ONE agent session scoped to the browser tools, and attach the
- * `ChatHandler`. Office document tools (Excel/Word/PPT) are advertised by the
- * pane at runtime over the bridge (`set_host_tools`), so they need no scoping here.
+ * Shared no-TUI extension-bridge bootstrap for `xcsh office serve` and `xcsh
+ * worker`: initialize the browser-provider environment, Settings, Context, and
+ * discovery; resolve TLS; bind and publish the bridge; create one profile-scoped
+ * agent session; and attach its ChatHandler. Worker fleet behavior stays in
+ * `commands/worker.ts` and is connected through the lifecycle hooks below.
+ * Office document tools are advertised by the pane at runtime over the bridge.
  *
  * The heavy / socket / network calls are injected (defaulting to the real ones)
  * so the wiring is unit-testable without opening real listeners or a session.
  *
  * NOT browser-safe (node/bun): runs inside the full xcsh binary, never the pane.
  */
-import { getProjectDir, getXCSHConfigDir } from "@f5-sales-demo/pi-utils";
+import { getProjectDir, getXCSHConfigDir, logger } from "@f5-sales-demo/pi-utils";
 import { parseModelString } from "../config/model-resolver";
 import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
 import { createAgentSession } from "../sdk";
@@ -24,8 +21,13 @@ import { SessionManager } from "../session/session-manager";
 import { resolveBridgeTls } from "./bridge-cert";
 import { ChatHandler } from "./chat-handler";
 import { isPickPath, type PathPicked } from "./chat-protocol";
-import { type BridgeServer, OFFICE_PORT_RANGE, startBridgeServer } from "./extension-bridge";
-import { OFFICE_TOOL_NAMES } from "./extension-bridge-tools";
+import { type BridgeServer, type BridgeSessionInfo, OFFICE_PORT_RANGE, startBridgeServer } from "./extension-bridge";
+import {
+	BROWSER_TOOL_NAMES,
+	createExtensionBridgeTools,
+	EXTENSION_AGENT_TOOL_NAMES,
+	OFFICE_TOOL_NAMES,
+} from "./extension-bridge-tools";
 import { pickPathNative } from "./native-picker";
 import { setSharedBridgeServer } from "./provider";
 
@@ -33,9 +35,34 @@ import { setSharedBridgeServer } from "./provider";
  *  closes the bridge (both ws + wss listeners). */
 export interface HeadlessChatBridge {
 	bridge: BridgeServer;
+	handler: ChatHandler;
 	dispose: () => Promise<void>;
 }
 
+type Session = Awaited<ReturnType<typeof createAgentSession>>["session"];
+
+export interface HeadlessBridgeLifecycleContext {
+	bridge: BridgeServer;
+	cwd: string;
+}
+
+export interface HeadlessBridgeSessionContext extends HeadlessBridgeLifecycleContext {
+	session: Session;
+}
+
+export type HeadlessBridgeOptions =
+	| {
+			kind?: "office";
+			afterBridgeBind?: (context: HeadlessBridgeLifecycleContext) => void | Promise<void>;
+			afterSessionCreate?: (context: HeadlessBridgeSessionContext) => void | Promise<void>;
+	  }
+	| {
+			kind: "worker";
+			sessionInfo: () => BridgeSessionInfo;
+			afterBridgeBind?: (context: HeadlessBridgeLifecycleContext) => void | Promise<void>;
+			afterSessionCreate?: (context: HeadlessBridgeSessionContext) => void | Promise<void>;
+	  };
+
 /**
  * Tenant identity for the `hello` handshake, contextless-friendly: the active
  * `/context` wins (its apiUrl + name), otherwise fall back to the `XCSH_API_URL`/
@@ -113,20 +140,25 @@ const defaultDeps: HeadlessBridgeDeps = {
  * can connect and chat immediately (no warm-up race). A `configure`-less pane
  * chats over xcsh's already-configured provider.
  */
-export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = defaultDeps): Promise<HeadlessChatBridge> {
+export async function startHeadlessChatBridge(
+	deps: HeadlessBridgeDeps = defaultDeps,
+	options: HeadlessBridgeOptions = { kind: "office" },
+): Promise<HeadlessChatBridge> {
 	const { cwd } = await deps.initEnv();
+	const kind = options.kind ?? "office";
 
 	// Provision the wss cert before binding (warm boot = on-disk cache hit);
 	// `undefined` (offline) → the bridge starts ws-only.
 	const tls = await deps.resolveBridgeTls();
-	// Office-serve binds the DEDICATED office range (disjoint from the Chrome worker
-	// range) so the two can never collide on a port.
-	const bridge = await deps.startBridgeServer(undefined, {
-		serveKind: "office",
-		sessionInfo: sessionInfoForOfficeServe,
-		...(tls ? { tls } : {}),
-		range: OFFICE_PORT_RANGE,
-	});
+	const start = () =>
+		deps.startBridgeServer(undefined, {
+			serveKind: kind === "worker" ? "browser" : "office",
+			sessionInfo: options.kind === "worker" ? options.sessionInfo : sessionInfoForOfficeServe,
+			...(tls ? { tls } : {}),
+			...(kind === "office" ? { range: OFFICE_PORT_RANGE } : {}),
+		});
+	const bridge = kind === "worker" ? await logger.time("session:bridgeListen", start) : await start();
+
 	// Reuse this bridge for any in-process selectProvider() (no conflicting second bridge).
 	deps.setSharedBridgeServer(bridge);
 	// Re-announce the tenant when the active context changes (best-effort).
@@ -136,72 +168,72 @@ export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = default
 		/* ContextService not initialized (tests) — the tenant is static. */
 	}
 
-	// Everything past the bind can throw (createAgentSession on a misconfigured
-	// provider, etc.). If it does, close the already-bound bridge and clear the
-	// shared-bridge global before rethrowing — otherwise the ws/wss listeners leak
-	// (keeping the event loop alive so Ctrl+C can't exit) and a later in-process
-	// selectProvider() reuses a dead bridge. The caller (startOfficeServe) treats
-	// the rethrow as a non-fatal "pane only" fallback.
+	let chatHandler: ChatHandler | undefined;
 	try {
-		const officeDefault = parseModelString(DEFAULT_MODEL_ROLE);
-		if (!officeDefault) {
-			throw new Error("Invalid baked Office default model selector");
+		await options.afterBridgeBind?.({ bridge, cwd });
+
+		let session: Session;
+		if (kind === "worker") {
+			const create = () =>
+				deps.createAgentSession({
+					cwd,
+					hasUI: false,
+					toolNames: [...new Set([...BROWSER_TOOL_NAMES, ...EXTENSION_AGENT_TOOL_NAMES])],
+					customTools: createExtensionBridgeTools(bridge),
+					enableMCP: false,
+					enableLsp: false,
+					disableExtensionDiscovery: true,
+					...(process.env.XCSH_BENCH_EXTENSION
+						? { additionalExtensionPaths: [process.env.XCSH_BENCH_EXTENSION] }
+						: {}),
+				});
+			({ session } = await logger.time("session:createAgentSession", create));
+		} else {
+			const officeDefault = parseModelString(DEFAULT_MODEL_ROLE);
+			if (!officeDefault) {
+				throw new Error("Invalid baked Office default model selector");
+			}
+			({ session } = await deps.createAgentSession({
+				cwd,
+				hasUI: false,
+				modelPattern: DEFAULT_MODEL_ROLE,
+				thinkingLevel: officeDefault.thinkingLevel,
+				sessionManager: SessionManager.inMemory(cwd),
+				toolNames: [...OFFICE_TOOL_NAMES],
+				customTools: [],
+				enableMCP: false,
+				enableLsp: false,
+				disableExtensionDiscovery: true,
+				bundledExtensions: ["sandbox-guard"],
+			}));
 		}
-		// Create ONE headless Office session with the full CLI-parity builtin set
-		// (OFFICE_TOOL_NAMES: bash/read/write/edit/grep/inspect_image/… — NO browser tools, which
-		// would be hallucinated in a document task pane). The document's own tools
-		// (Excel/Word/PowerPoint) arrive at runtime via set_host_tools.
-		const { session } = await deps.createAgentSession({
-			cwd,
-			hasUI: false,
-			// Office must open on the production GPT profile regardless of a stale
-			// global/default role or resumable session. A saved pane model is applied
-			// afterward by its explicit configure frame and remains authoritative.
-			modelPattern: DEFAULT_MODEL_ROLE,
-			thinkingLevel: officeDefault.thinkingLevel,
-			// Office conversations can contain private workbook and working-directory
-			// data. Keep the entire headless session ephemeral instead of inheriting
-			// createAgentSession's file-backed default.
-			sessionManager: SessionManager.inMemory(cwd),
-			toolNames: [...OFFICE_TOOL_NAMES],
-			customTools: [],
-			// Headless: no MCP/LSP/extension discovery — lean, no network/blocking prompts.
-			enableMCP: false,
-			enableLsp: false,
-			disableExtensionDiscovery: true,
-			// …but DO load the bundled filesystem sandbox: the pane runs full CLI-parity
-			// tools (bash/read/write), so it needs the CLI's safety net confining file
-			// tools + the shell's cwd to the launch directory subtree (sandbox.enabled
-			// defaults true). Without this, a discovery-disabled session ran ungated.
-			bundledExtensions: ["sandbox-guard"],
-		});
 
-		const chatHandler = new deps.ChatHandlerCtor(bridge, session);
+		await options.afterSessionCreate?.({ bridge, session, cwd });
+		chatHandler = new deps.ChatHandlerCtor(bridge, session);
 		chatHandler.attach();
 
-		// Second bridge subscriber (the bridge fans out to all): serve `pick_path` by
-		// opening a native OS picker and replying `path_picked`. Pure — it only returns
-		// the chosen path; the sandbox grant + prompt note happen in ChatHandler when the
-		// path rides the next `chat_request.contextPaths` (kept atomic there). `disposed`
-		// guards against a superseded serve firing the picker on a closed bridge.
 		let disposed = false;
-		bridge.onMessage(async msg => {
-			if (disposed || !isPickPath(msg)) return;
-			const { path, canceled, unsupported } = await deps.pickPath((msg as { mode: "file" | "folder" }).mode);
-			if (disposed) return;
-			bridge.send({ type: "path_picked", path, canceled, unsupported } satisfies PathPicked);
-		});
+		if (kind === "office") {
+			bridge.onMessage(async msg => {
+				if (disposed || !isPickPath(msg)) return;
+				const { path, canceled, unsupported } = await deps.pickPath((msg as { mode: "file" | "folder" }).mode);
+				if (disposed) return;
+				bridge.send({ type: "path_picked", path, canceled, unsupported } satisfies PathPicked);
+			});
+		}
 
 		return {
 			bridge,
+			handler: chatHandler,
 			dispose: async () => {
 				disposed = true;
-				chatHandler.dispose();
+				chatHandler?.dispose();
 				deps.setSharedBridgeServer(null);
 				await bridge.close();
 			},
 		};
 	} catch (err) {
+		chatHandler?.dispose();
 		deps.setSharedBridgeServer(null);
 		await bridge.close();
 		throw err;

package/src/commands/worker.ts

@@ -15,20 +15,11 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { getProjectDir, getXCSHConfigDir, logger } from "@f5-sales-demo/pi-utils";
+import { logger } from "@f5-sales-demo/pi-utils";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
-import { LOCALIP_HOST, resolveBridgeTls } from "../browser/bridge-cert";
-import { ChatHandler } from "../browser/chat-handler";
-import { startBridgeServer } from "../browser/extension-bridge";
-import {
-	BROWSER_TOOL_NAMES,
-	createExtensionBridgeTools,
-	EXTENSION_AGENT_TOOL_NAMES,
-} from "../browser/extension-bridge-tools";
-import { setSharedBridgeServer } from "../browser/provider";
+import { LOCALIP_HOST } from "../browser/bridge-cert";
+import { startHeadlessChatBridge } from "../browser/headless-bridge";
 import { coldStartSpans, type SpanFrame, sessionBuildSpan } from "../browser/ttft-spans";
-import { initializeWithSettings } from "../discovery";
-import { createAgentSession } from "../sdk";
 import { activateTenantContext } from "../services/session-context-binding";
 import { ContextService } from "../services/xcsh-context";
 import { deriveTenantEnv } from "../services/xcsh-env";
@@ -102,197 +93,113 @@ export default class Worker extends Command {
 	static description = "Run a headless extension-bridge worker (no TUI); blocks until SIGTERM";
 
 	async run(): Promise<void> {
-		// Record the per-tab session-boot timeline (parity with main.ts:runRootCommand).
-		// 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";
-
-		const cwd = getProjectDir();
-		const { Settings, settings } = await import("../config/settings");
-		await Settings.init({ cwd });
-
-		// Init the ContextService singleton so the session-context bootstrap (Task 3)
-		// can match XCSH_SESSION_TENANT to a stored context, and so sessionInfoForWorker
-		// can read the active apiUrl once bound.
-		try {
-			ContextService.init(getXCSHConfigDir());
-		} catch {
-			/* already initialized / unavailable — continue. */
-		}
-
-		// Provider persistence for model discovery (parity with main.ts).
-		initializeWithSettings(settings);
-
-		// Quiet startup: skip the welcome screen + blocking plugin "Fix now?" prompts.
-		settings.override("startup.quiet", true);
-
-		// Provision the wss cert BEFORE the session:bridgeListen span — its only
-		// network path (a cold/stale-cache fetch) must NOT inflate the measured
-		// bridge-ready time; a warm boot is a fast on-disk cache hit. `undefined`
-		// (offline / local-ip.sh unreachable) → the bridge starts ws-only (no crash).
-		const tls = await resolveBridgeTls();
-
-		// INSTANT-ON: start the bridge before the heavy session init so the extension
-		// can connect immediately. Honors XCSH_BRIDGE_PORT (forced) or auto-selects.
-		// session:bridgeListen — time-to-"bridge-ready": the extension can connect and
-		// complete the hello/hello_ack handshake once this resolves (INSTANT-ON path).
-		const bridge = await logger.time("session:bridgeListen", () =>
-			startBridgeServer(undefined, {
-				serveKind: "browser",
-				sessionInfo: sessionInfoForWorker,
-				...(tls ? { tls } : {}),
-			}),
-		);
-		console.error(
-			`[xcsh worker] extension bridge listening on ws://127.0.0.1:${bridge.port}` +
-				(bridge.wssPort ? ` + wss://${LOCALIP_HOST}:${bridge.wssPort}` : ""),
-		);
-		if (process.connected) {
-			process.send?.({ type: "ready", sessionId: sessionInfoForWorker().sessionId });
-		}
-		setSharedBridgeServer(bridge);
-		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;
-		};
-		// TTFT: the session_build span (createAgentSession seam) is computed after the
-		// bridge is listening but possibly before the extension connects — buffer it and
-		// flush on connect, same as the cold-start spans.
 		let sessionBuildFrame: SpanFrame | null = null;
 		let sessionBuildSent = false;
-		const flushSessionBuild = (): void => {
-			if (sessionBuildSent || !clientConnected || !sessionBuildFrame) return;
-			bridge.send(sessionBuildFrame);
-			sessionBuildSent = 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();
-			flushSessionBuild();
-		});
+		let sessionBuildStart = 0;
 
-		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.
-		}
+		const running = await startHeadlessChatBridge(undefined, {
+			kind: "worker",
+			sessionInfo: sessionInfoForWorker,
+			afterBridgeBind: ({ bridge }) => {
+				console.error(
+					`[xcsh worker] extension bridge listening on ws://127.0.0.1:${bridge.port}` +
+						(bridge.wssPort ? ` + wss://${LOCALIP_HOST}:${bridge.wssPort}` : ""),
+				);
+				if (process.connected) {
+					process.send?.({ type: "ready", sessionId: sessionInfoForWorker().sessionId });
+				}
 
-		// 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;
-				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 {
-					await activateTenantContext(tenant);
-				} catch {
-					console.error("[xcsh worker] late tenant-bind failed");
+				const flushColdStart = (): void => {
+					if (coldStartSent || !clientConnected || coldStartBuffer.length === 0) return;
+					for (const span of coldStartBuffer) bridge.send(span);
+					coldStartSent = true;
+				};
+				const flushSessionBuild = (): void => {
+					if (sessionBuildSent || !clientConnected || !sessionBuildFrame) return;
+					bridge.send(sessionBuildFrame);
+					sessionBuildSent = true;
+				};
+
+				bridge.onConnected(() => {
+					clientConnected = true;
+					flushColdStart();
+					flushSessionBuild();
+				});
+
+				if (coldSpawn && process.env.XCSH_SESSION_ID && Number.isFinite(spawnAtEnv)) {
+					const workerBootMs = Date.now() - spawnAtEnv;
+					const managerMs = Number.isFinite(managerProvisionMsEnv) ? managerProvisionMsEnv : 0;
+					coldStartBuffer = coldStartSpans(process.env.XCSH_SESSION_ID, true, managerMs, workerBootMs);
 				}
-				bridge.broadcastTenantChanged();
-				// The standalone benchmark retains IPC to measure adoption latency. A real
-				// manager disconnects after binding so the worker survives manager handoff.
-				if (process.connected) 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();
-			})();
-		});
 
-		// The extension's browser actions (navigate/click/read_ax/…) are not builtin
-		// tools — turn each into a bridge-proxying CustomTool so the agent can drive
-		// the browser (without this the agent only has catalog_workflow_runner and
-		// merely narrates "Navigating…"). Include their names in the tool scope.
-		const extensionTools = createExtensionBridgeTools(bridge);
-		// session:createAgentSession — the heavy step between bridge-ready and
-		// session-ready (model registry, tools, context bootstrap). Wrapped as a span
-		// (parity with main.ts:892) so PI_TIMING reveals the per-tab session-load split.
-		const sessionBuildStart = Date.now();
-		const { session } = await logger.time("session:createAgentSession", createAgentSession, {
-			cwd,
-			hasUI: false,
-			toolNames: [...new Set([...BROWSER_TOOL_NAMES, ...EXTENSION_AGENT_TOOL_NAMES])],
-			customTools: extensionTools,
-			// Headless worker: no MCP discovery, no LSP warmup, no extension discovery —
-			// keep startup lean and free of network calls / blocking prompts.
-			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] } : {}),
-		});
-		// TTFT: emit the session_build stage (createAgentSession seam) as a WS span so the
-		// bench and diagnostics panel stop hiding plugin/discovery/registry-load cost inside
-		// total ttft_ms. Buffered + flushed on connect (parity with cold-start spans).
-		sessionBuildFrame = sessionBuildSpan(
-			process.env.XCSH_SESSION_ID ?? "",
-			coldSpawn,
-			Date.now() - sessionBuildStart,
-		);
-		flushSessionBuild();
+				process.on("message", (raw: unknown) => {
+					const message = raw as {
+						type?: unknown;
+						sessionId?: unknown;
+						tenant?: unknown;
+						provisionMs?: unknown;
+						cold?: unknown;
+					};
+					if (
+						message?.type !== "bind" ||
+						typeof message.sessionId !== "string" ||
+						typeof message.tenant !== "string"
+					)
+						return;
+					const sessionId = message.sessionId;
+					const tenant = message.tenant;
+					const bindAt = Date.now();
+					const relayedProvisionMs = typeof message.provisionMs === "number" ? message.provisionMs : 0;
+					setWorkerIdentity(sessionId, tenant);
+					void (async () => {
+						try {
+							await activateTenantContext(tenant);
+						} catch {
+							console.error("[xcsh worker] late tenant-bind failed");
+						}
+						bridge.broadcastTenantChanged();
+						if (process.connected) process.send?.({ type: "bound", sessionId });
+						coldStartBuffer = coldStartSpans(sessionId, false, relayedProvisionMs, Date.now() - bindAt);
+						flushColdStart();
+					})();
+				});
 
-		// TTFT Phase 3 hermeticity: the bench-instant stand-in provider is registered while
-		// createAgentSession loads the bench extension (additionalExtensionPaths), which is
-		// AFTER the default-model role is resolved — so the worker would otherwise fall back
-		// to a real provider and the benchmark would measure live network TTFT, not xcsh
-		// overhead. In bench mode, explicitly select bench-instant now that it is registered.
-		// Gated on XCSH_BENCH_EXTENSION → completely inert for a normal `xcsh worker`.
-		if (process.env.XCSH_BENCH_EXTENSION) {
-			const benchModel = session.modelRegistry.find("bench-instant", "bench-instant");
-			if (benchModel) {
-				await session.setModel(benchModel);
-			} else {
-				console.error(
-					"[xcsh worker] BENCH ERROR: bench-instant model not registered — benchmark would measure a real provider",
+				// The shared bootstrap creates the session immediately after this hook.
+				sessionBuildStart = Date.now();
+			},
+			afterSessionCreate: async ({ bridge, session }) => {
+				sessionBuildFrame = sessionBuildSpan(
+					process.env.XCSH_SESSION_ID ?? "",
+					coldSpawn,
+					Date.now() - sessionBuildStart,
 				);
-			}
-		}
+				if (clientConnected && !sessionBuildSent) {
+					bridge.send(sessionBuildFrame);
+					sessionBuildSent = true;
+				}
 
-		const chatHandler = new ChatHandler(bridge, session);
-		chatHandler.attach();
+				if (process.env.XCSH_BENCH_EXTENSION) {
+					const benchModel = session.modelRegistry.find("bench-instant", "bench-instant");
+					if (benchModel) {
+						await session.setModel(benchModel);
+					} else {
+						console.error(
+							"[xcsh worker] BENCH ERROR: bench-instant model not registered — benchmark would measure a real provider",
+						);
+					}
+				}
+			},
+		});
+		const { handler: chatHandler } = running;
 
-		// Manager keepalive: while a turn is in flight (and at each turn start), ping
-		// the manager control socket so it refreshes this worker's lastSeen and its
-		// idle sweep does not reap an actively-used session mid-conversation. Chat
-		// traffic never reaches the manager, so this is the only liveness signal.
-		// Best-effort + self-reconnecting: a dropped socket (e.g. manager supersede)
-		// is re-opened on the next emit, re-targeting the successor manager.
 		const keepalive = new ManagerKeepalive({
 			sessionId: () => sessionInfoForWorker().sessionId ?? "spare",
 			busy: () => chatHandler.busy,
@@ -312,16 +219,13 @@ export default class Worker extends Command {
 					};
 					return transport;
 				} catch {
-					return null; // manager not reachable — a later emit retries
+					return null;
 				}
 			},
 		});
 		chatHandler.onTurnStart(() => keepalive.turnStart());
 		const keepaliveTimer = setInterval(() => keepalive.tick(), KEEPALIVE_MS);
 
-		// session-ready. Emit the per-tab boot breakdown when requested (parity with
-		// main.ts:1002-1009). PI_TIMING=x prints then exits — used by bench/extension-session.ts
-		// to measure total worker cold-start; otherwise this is a no-op.
 		if (process.env.PI_TIMING) {
 			logger.printTimings();
 			if (process.env.PI_TIMING === "x") {
@@ -334,16 +238,11 @@ export default class Worker extends Command {
 		const teardown = () => {
 			clearInterval(keepaliveTimer);
 			keepalive.stop();
-			chatHandler.dispose();
-			void bridge.close().finally(() => process.exit(0));
+			void running.dispose().finally(() => process.exit(0));
 		};
 		const shutdown = () => {
 			if (shuttingDown) return;
 			shuttingDown = true;
-			// Bounded drain (#1874): if a chat turn is in flight (e.g. the manager is
-			// recycling for an upgrade), let it finish before teardown instead of
-			// aborting the running agent turn — with a hard ceiling so a hung turn can
-			// never wedge shutdown. An idle worker tears down immediately.
 			if (!chatHandler.busy) return teardown();
 			const deadline = Date.now() + WORKER_DRAIN_TIMEOUT_MS;
 			const tick = () => {
@@ -355,7 +254,6 @@ export default class Worker extends Command {
 		process.on("SIGTERM", shutdown);
 		process.on("SIGINT", shutdown);
 
-		// Block until a signal tears us down.
 		await Promise.withResolvers<never>().promise;
 	}
 }

package/src/config/settings-schema.ts

@@ -1976,6 +1976,24 @@ export const SETTINGS_SCHEMA = {
 	"sandbox.allowWrite": { type: "array", default: [] as string[] },
 
 	// Provider selection
+	"providers.vertexProject": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "providers",
+			label: "Vertex AI Project",
+			description: "Non-secret corporate Google Cloud project selected by /login",
+		},
+	},
+	"providers.vertexLocation": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "providers",
+			label: "Vertex AI Location",
+			description: "Non-secret Vertex AI location selected by /login",
+		},
+	},
 	"providers.webSearch": {
 		type: "enum",
 		values: [