@f5-sales-demo/xcsh 21.2.0 → 21.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.2.0",
+	"version": "21.2.1",
 	"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.2.1",
+		"@f5-sales-demo/pi-ai": "21.2.1",
+		"@f5-sales-demo/pi-natives": "21.2.1",
+		"@f5-sales-demo/pi-resource-management": "21.2.1",
+		"@f5-sales-demo/pi-tui": "21.2.1",
+		"@f5-sales-demo/pi-utils": "21.2.1",
+		"@f5-sales-demo/xcsh-stats": "21.2.1",
 		"@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/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "21.2.0",
-	"commit": "d217f62f68fae54fe18d88c7d90a8f7dc4703c0d",
-	"shortCommit": "d217f62",
+	"version": "21.2.1",
+	"commit": "21fcf6e73313274c68dcb1db998bd12b75326489",
+	"shortCommit": "21fcf6e",
 	"branch": "main",
-	"tag": "v21.2.0",
-	"commitDate": "2026-08-30T03:18:04+00:00",
-	"buildDate": "2026-08-30T03:46:25.618Z",
+	"tag": "v21.2.1",
+	"commitDate": "2026-08-31T13:35:12+00:00",
+	"buildDate": "2026-08-31T14:12:39.742Z",
 	"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/d217f62f68fae54fe18d88c7d90a8f7dc4703c0d",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.2.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/21fcf6e73313274c68dcb1db998bd12b75326489",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.2.1"
 };

package/src/internal-urls/docs-index.generated.ts

@@ -144,7 +144,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"en/natives/porting-to-natives.md": "---\ntitle: Porting to pi-natives (Node-API) — Field notes\ndescription: Field notes for migrating Node.js child_process and shell code to the Rust N-API native layer.\nsidebar:\n  order: 9\n  label: Porting to pi-natives\n---\n\nThis guide describes how to migrate performance-critical execution paths to Rust in `crates/pi-natives` and expose them through TypeScript bindings in `@f5-sales-demo/pi-natives`.\n\n## When to port to native modules\n\nPort execution paths to Rust when:\n\n- Execution paths execute within high-frequency rendering loops or large batch data pipelines.\n- JavaScript memory allocations dominate execution time (excessive string allocations, regex backtracking, large array transformations).\n- The operation is CPU-bound or performs blocking I/O that can run on libuv worker threads (`task::blocking`).\n- The operation orchestrates asynchronous I/O that benefits from the Tokio runtime (`task::future`).\n\nAvoid porting operations that require access to JavaScript runtime state or dynamic module imports. Native exports must remain pure, data-in/data-out functions.\n\n## Native export architecture\n\n### Rust implementation layer (`crates/pi-natives/`)\n\n1. Implement core functionality in `crates/pi-natives/src/<MODULE>.rs`.\n2. Register the module in `crates/pi-natives/src/lib.rs`.\n3. Annotate functions with `#[napi]`. Rust `snake_case` function names convert to JavaScript `camelCase` identifiers automatically.\n4. Use `task::blocking` for CPU-bound computation and `task::future` for asynchronous operations. Pass `CancelToken` instances when supporting timeouts or `AbortSignal`.\n\n### TypeScript binding layer (`packages/natives/`)\n\n1. Define interface augmentations in `packages/natives/src/<MODULE>/types.ts` extending `NativeBindings` via declaration merging.\n2. Import `<MODULE>/types.ts` in `packages/natives/src/native.ts` to activate type definitions.\n3. Add validation entries in `validateNative` within `packages/natives/src/native.ts` to enforce required exports at startup.\n4. Implement ergonomic wrappers in `packages/natives/src/<MODULE>/index.ts` and re-export them from `packages/natives/src/index.ts`.\n\n## Step-by-step porting workflow\n\n1. **Implement Rust logic**: Create functions with owned types (`String`, `Vec<String>`, `Uint8Array`) and wrap long loops with `ct.heartbeat()?`.\n2. **Expose TypeScript bindings**: Add types in `<MODULE>/types.ts` and export wrapper functions.\n3. **Register native validation**: Add `checkFn(\"exportName\")` to `validateNative` in `packages/natives/src/native.ts`.\n4. **Create performance benchmarks**: Benchmark JavaScript and Rust implementations side-by-side using `Bun.nanoseconds()`.\n5. **Compile native binaries**: Run `bun --cwd=packages/natives run build`.\n6. **Validate performance**: Verify that the native path outperforms JavaScript before switching production call sites.\n\n## Troubleshooting common issues\n\n### Stale native binaries\n\nThe runtime loader prioritizes platform-tagged binaries (`pi_natives.<PLATFORM>-<ARCH>.node`). If exports fail to update:\n\n```bash\nrm packages/natives/native/pi_natives.*.node\nbun --cwd=packages/natives run build\n```\n\nIf testing against pre-compiled binaries, remove the extraction cache:\n\n```bash\nrm -rf ~/.xcsh/natives/\n```\n\n### Missing export validation errors\n\nIf `validateNative` raises an error indicating missing exports:\n\n- Verify that the Rust export name matches the expected JavaScript camelCase name.\n- Verify that the binary was rebuilt after adding the `#[napi]` attribute.\n- Never disable or weaken `validateNative` checks.\n",
 	"en/office-test-ownership.md": "# Office add-in test ownership\n\nThis document defines the canonical test ownership and execution responsibilities for the `office-pane` package and Office add-in task pane integration tests.\n\n## Test suites and domain ownership\n\n| Test suite / harness | Location | Canonical owner | Execution tier | Description |\n| --- | --- | --- | --- | --- |\n| **Office Task Pane UI Unit Tests** | `packages/office-pane/src/**/*.test.ts` | Frontend / UI Core Team | Local and PR CI | Core Office.js state management and task pane rendering |\n| **Office Host Integration Harness** | `packages/office-pane/test/integration/` | Ecosystem Integrations Team | PR CI Matrix | Simulated Office.js API host binding and event handling |\n| **Acceptance End-to-End Suite** | `packages/office-pane/test/e2e/` | QA and Release Engineering | Nightly Release CI | Headless browser execution against Word and Excel task pane mocks |\n\n## Maintenance responsibilities\n\n- **Frontend / UI Core Team**: Responsible for unit test coverage on UI components in `office-pane`.\n- **Ecosystem Integrations Team**: Responsible for host mock fidelity and API contract alignment.\n- **Release Engineering**: Responsible for end-to-end environment stability and CI matrix runtimes.\n",
 	"en/providers/models.md": "---\ntitle: Model and Provider Configuration\ndescription: Model registry and provider configuration via models.yml with routing, fallback, and pricing.\nsidebar:\n  order: 1\n  label: Models & providers\n---\n\nThis document describes how xcsh loads model registries, applies configuration overrides, resolves API credentials, and manages model selection at runtime.\n\n## Core implementation architecture\n\nModel configuration and runtime resolution are implemented across the following modules:\n\n- `src/config/model-registry.ts`: Loads built-in and custom models, manages provider overrides, discovers local models, and integrates authentication.\n- `src/config/model-resolver.ts`: Parses model patterns, handles canonical coalescing, and selects default, small, and reasoning models.\n- `src/config/settings-schema.ts`: Defines settings schemas for `modelRoles` and transport options.\n- `src/session/auth-storage.ts`: Resolves API keys and OAuth tokens across configuration sources.\n- `packages/ai/src/models.ts` and `packages/ai/src/types.ts`: Defines built-in models and compatibility contracts.\n\n## Configuration file path\n\nDefault configuration path:\n\n- `~/.xcsh/agent/models.yml`\n\n> [!NOTE]\n> If `models.yml` is missing and a legacy `models.json` file exists in the configuration directory, xcsh automatically migrates the settings to `models.yml`.\n\n## Schema structure\n\n```yaml\nconfigVersion: 1\nproviders:\n  <PROVIDER_ID>:\n    baseUrl: https://api.example.com/v1\n    apiKey: MY_API_KEY_ENV_VAR\n    api: openai-completions\n    headers:\n      X-Custom-Header: value\n    auth: apiKey\n    discovery:\n      type: ollama\n    modelOverrides:\n      <MODEL_ID>:\n        name: Custom Model Display Name\n    models:\n      - id: custom-model-id\n        name: Custom Model Name\n        api: openai-completions\n        contextWindow: 128000\n        maxTokens: 16384\n        cost:\n          input: 0\n          output: 0\n          cacheRead: 0\n          cacheWrite: 0\nequivalence:\n  overrides:\n    <PROVIDER_ID>/<MODEL_ID>: <CANONICAL_MODEL_ID>\n  exclude:\n    - <PROVIDER_ID>/<MODEL_ID>\n```\n\n### Supported API protocol types\n\n- `openai-completions`\n- `openai-responses`\n- `openai-codex-responses`\n- `azure-openai-responses`\n- `anthropic-messages`\n- `google-generative-ai`\n- `google-vertex`\n\n## Validation rules\n\n### Custom provider definitions (`models` defined)\n\nThe following fields are required:\n\n- `baseUrl`: Base endpoint URL.\n- `apiKey`: Required unless `auth: none` is explicitly configured.\n- `api`: Protocol type specified at the provider or model level.\n\n### Override-only providers (`models` omitted)\n\nMust specify at least one of:\n\n- `baseUrl`\n- `modelOverrides`\n- `discovery`\n\n## Merge and override hierarchy\n\nWhen initializing or refreshing the model registry, xcsh applies configuration in the following order:\n\n1. **Built-in catalog**: Loads default providers and models from `@f5-sales-demo/pi-ai`.\n2. **Custom configuration**: Parses `~/.xcsh/agent/models.yml`.\n3. **Provider overrides**: Applies custom `baseUrl` and default `headers` to built-in models.\n4. **Model overrides**: Merges custom settings from `modelOverrides`.\n5. **Custom models**: Appends or replaces model definitions matching existing `provider/id` pairs.\n6. **Runtime discovery**: Queries active local endpoints (such as Ollama or LM Studio) and registers discovered models.\n\n## Canonical model equivalence and coalescing\n\nxcsh groups equivalent model checkpoints from different providers under canonical upstream identifiers (for example, `claude-sonnet-4`, `gpt-5.3-codex`):\n\n- **Overrides**: Maps specific provider identifiers to standard canonical names via `equivalence.overrides`.\n- **Exclusions**: Removes specific variants from automatic grouping via `equivalence.exclude`.\n- **Resolution priority**: Selects concrete providers based on credential availability and `modelProviderOrder` precedence.\n\n## Runtime model discovery\n\nxcsh detects local inference runtimes automatically:\n\n- **Ollama**: Probes `http://127.0.0.1:11434/api/tags` (or `OLLAMA_BASE_URL`).\n- **LM Studio**: Probes `http://127.0.0.1:1234/v1/models` (or `LM_STUDIO_BASE_URL`).\n- **llama.cpp**: Probes `http://127.0.0.1:8080/v1/models` (or `LLAMA_CPP_BASE_URL`).\n\n## Credential resolution hierarchy\n\nWhen resolving API keys for a provider, xcsh evaluates sources in the following priority order:\n\n1. CLI flag `--api-key`\n2. Stored API keys in `agent.db`\n3. Stored OAuth tokens in `agent.db`\n4. Standard environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`)\n5. Provider `apiKey` field in `models.yml` (evaluated first as an environment variable name, then as a literal token)\n\n## Model roles and selection\n\nxcsh supports logical role aliases configured via `settings.modelRoles`:\n\n- `default`: Primary interaction model.\n- `smol`: Fast, lightweight model for metadata tasks and short tool evaluations.\n- `slow`: High-reasoning model for complex multi-step planning and analysis.\n- `plan`: Model assigned to interactive planning modes.\n- `commit`: Model assigned to git commit generation.\n\nEach role definition can include thinking intensity suffixes (for example, `pi/smol:minimal`, `claude-sonnet-4:high`).\n\n## Context promotion and fallback\n\nWhen a model context window overflows during a conversation turn (`context_length_exceeded`), xcsh automatically promotes the session to a larger-context sibling model before initiating context compaction:\n\n1. Evaluates explicit `contextPromotionTarget` configurations.\n2. Identifies the smallest available model with a larger context window on the same provider.\n3. Switches the session model temporarily and retries the turn.\n",
-	"en/providers/openai-api-access.md": "---\ntitle: OpenAI access\ndescription: Choose ChatGPT subscription or usage-based OpenAI Platform access in xcsh.\nsidebar:\n  order: 4\n  label: OpenAI access\n---\n\nxcsh supports two distinct access methods for OpenAI services, depending on whether you authenticate with a ChatGPT subscription or an OpenAI Platform API key.\n\n## 1. ChatGPT subscription (OAuth)\n\nTo use your ChatGPT Plus or Pro subscription, run `/login openai-codex` or select **ChatGPT Plus/Pro (Codex Subscription)** in the `/login` interactive picker. xcsh stores the OAuth credentials securely in `agent.db` and discovers advertised subscription models.\n\n### Headless and SSH remote login\n\nWhen running inside an SSH session or headless terminal, xcsh automatically initiates device-code authentication:\n\n1. xcsh displays `https://auth.openai.com/codex/device` and a one-time verification code.\n2. Open the URL in any web browser and log in with your ChatGPT account credentials.\n3. Enter the one-time verification code.\n4. The remote xcsh process detects authorization automatically and completes authentication.\n\n> [!NOTE]\n> Device-code authentication requires enabling the beta feature in ChatGPT under **Settings → Security**, or via workspace administrator settings under **Workspace settings → Permissions & roles**.\n\n### Local desktop browser callback\n\nOn local workstations with graphical desktop environments, run `/login openai-codex-browser` (or select **ChatGPT Plus/Pro (Browser callback)**). This workflow opens your default browser and receives tokens through a local loopback listener on port 1455 (`http://localhost:1455/auth/callback`).\n\n## 2. OpenAI Platform API (usage-based billing)\n\nTo use pay-as-you-go OpenAI Platform access, configure the `OPENAI_API_KEY` environment variable or provide it in `models.yml`:\n\n```bash\nexport OPENAI_API_KEY=\"<OPENAI_API_KEY>\"\nxcsh\n```\n\nAfter starting xcsh, select an OpenAI model using `/model`.\n",
+	"en/providers/openai-api-access.md": "---\ntitle: OpenAI access\ndescription: Choose ChatGPT subscription or usage-based OpenAI Platform access in xcsh.\nsidebar:\n  order: 4\n  label: OpenAI access\n---\n\nxcsh supports two distinct access methods for OpenAI services, depending on whether you authenticate with a ChatGPT subscription or an OpenAI Platform API key.\n\n## 1. ChatGPT subscription (OAuth)\n\nTo use your ChatGPT Plus or Pro subscription, run `/login openai-codex` or select **ChatGPT Plus/Pro (Codex Subscription)** in the `/login` interactive picker. xcsh stores the OAuth credentials securely in `agent.db` and discovers advertised subscription models.\n\n### Headless and SSH remote login\n\nWhen running inside an SSH session or headless terminal, xcsh automatically initiates device-code authentication:\n\n1. xcsh displays `https://auth.openai.com/codex/device` and a one-time verification code.\n2. Open the URL in any web browser and log in with your ChatGPT account credentials.\n3. Enter the one-time verification code.\n4. The remote xcsh process detects authorization automatically and completes authentication.\n\n> [!NOTE]\n> Device-code authentication requires enabling the beta feature in ChatGPT under **Settings → Security**, or via workspace administrator settings under **Workspace settings → Permissions & roles**.\n\n### Local desktop browser callback\n\nOn local workstations with graphical desktop environments, the same `/login openai-codex` command opens your default browser and receives tokens through a local loopback listener on port 1455 (`http://localhost:1455/auth/callback`).\n\nIf device authorization is unavailable in an SSH or headless session, the same login flow offers browser/manual redirect authentication. Open the displayed URL locally, then paste the redirect URL into `/login <redirect URL>` on the remote host.\n\n## 2. OpenAI Platform API (usage-based billing)\n\nTo use pay-as-you-go OpenAI Platform access, configure the `OPENAI_API_KEY` environment variable or provide it in `models.yml`:\n\n```bash\nexport OPENAI_API_KEY=\"<OPENAI_API_KEY>\"\nxcsh\n```\n\nAfter starting xcsh, select an OpenAI model using `/model`.\n",
 	"en/providers/provider-streaming-internals.md": "---\ntitle: Provider Streaming Internals\ndescription: Provider streaming implementation with SSE parsing, token counting, and backpressure handling.\nsidebar:\n  order: 2\n  label: Streaming internals\n---\n\nThis document describes how token and tool call streams from diverse LLM providers are normalized in `@f5-sales-demo/pi-ai` and propagated through `@f5-sales-demo/pi-agent-core` to `coding-agent` session events.\n\n## End-to-end streaming architecture\n\n1. **Stream dispatch**: `streamSimple()` in `packages/ai/src/stream.ts` maps provider-agnostic request options and dispatches them to the selected provider driver.\n2. **Provider normalization**: Provider stream drivers (`anthropic.ts`, `openai-responses.ts`, `google.ts`) translate vendor-specific Server-Sent Events (SSE) into a unified `AssistantMessageEvent` stream.\n3. **Event throttling**: `AssistantMessageEventStream` (`packages/ai/src/utils/event-stream.ts`) buffers and coalesces rapid delta events (~50ms cadence) to smooth UI rendering.\n4. **Agent loop consumption**: `agentLoop` (`packages/agent/src/agent-loop.ts`) processes events, updates in-flight message state, and emits `message_update` events.\n5. **Session event integration**: `AgentSession` (`packages/coding-agent/src/session/agent-session.ts`) handles user aborts, automated retries, context compaction, and tool call execution guards.\n\n## Unified stream contract (`AssistantMessageEvent`)\n\nAll provider drivers emit events conforming to the `AssistantMessageEvent` union:\n\n- `start`: Initiates stream processing.\n- Content block lifecycle triplets:\n  - Text: `text_start` → `text_delta`* → `text_end`\n  - Thinking / reasoning: `thinking_start` → `thinking_delta`* → `thinking_end`\n  - Tool invocation: `toolcall_start` → `toolcall_delta`* → `toolcall_end`\n- Terminal events:\n  - `done`: Emits termination reasons (`stop`, `length`, `toolUse`).\n  - `error`: Emits failure reasons (`aborted`, `error`).\n\n## Provider-specific normalization logic\n\n### Anthropic (`anthropic-messages`)\n\n- Maps `message_start` to token usage metadata.\n- Maps `content_block_start` and `content_block_delta` to unified text, thinking, and tool invocation blocks.\n- Accumulates streamed JSON fragments in `partialJson` and reparses arguments incrementally via `parseStreamingJson()`.\n\n### OpenAI Responses (`openai-responses`)\n\n- Maps `response.output_item.added` to text or reasoning blocks.\n- Maps `response.reasoning_summary_text.delta` to `thinking_delta`.\n- Translates `response.function_call_arguments.delta` into `toolcall_delta`.\n- Normalizes tool call identifiers into `<CALL_ID>|<ITEM_ID>`.\n\n### Google Generative AI (`google-generative-ai`)\n\n- Parses `candidate.content.parts`, distinguishing thinking blocks via `isThinkingPart()`.\n- Emits synthetic `toolcall_delta` containing serialized JSON strings for structured tool call events.\n\n## Tool call JSON accumulation and error recovery\n\nIncremental tool arguments are parsed via `parseStreamingJson()` (`packages/ai/src/utils/json-parse.ts`):\n\n1. Attempts standard `JSON.parse`.\n2. Falls back to partial JSON parsing to evaluate incomplete streamed fragments.\n3. If partial parsing fails, returns `{}` temporarily until subsequent deltas provide valid JSON structures.\n4. Performs a final parse pass on `toolcall_end`.\n\n## Cancellation and lifecycle boundaries\n\n- **Provider HTTP request**: `options.signal` aborts the active HTTP transport connection.\n- **Agent loop**: Evaluates `signal.aborted` prior to processing each streamed event.\n- **Session abortion**: Calling `AgentSession.abort()` propagates cancellations to active tool subprocesses.\n- **Tool execution interrupts**: Tool runners listen to `AbortSignal.any([agentSignal, steeringAbortSignal])`, allowing users to interrupt long-running tools without discarding prior turns.\n\n## Related implementation files\n\n- `packages/ai/src/stream.ts`: Provider stream dispatcher and option normalizer.\n- `packages/ai/src/utils/event-stream.ts`: Stream queueing and delta event throttling.\n- `packages/ai/src/utils/json-parse.ts`: Incremental streaming JSON parser.\n- `packages/ai/src/providers/anthropic.ts`: Anthropic SSE event transformer.\n- `packages/ai/src/providers/openai-responses.ts`: OpenAI Responses event transformer.\n- `packages/ai/src/providers/google.ts`: Google Gemini event transformer.\n- `packages/agent/src/agent-loop.ts`: Agent event processing loop.\n- `packages/coding-agent/src/session/agent-session.ts`: Session lifecycle, retry policies, and persistence.\n",
 	"en/providers/python-repl.md": "---\ntitle: Python Tool and IPython Runtime\ndescription: Python REPL tool runtime with IPython kernel management, execution, and output capture.\nsidebar:\n  order: 3\n  label: Python & IPython\n---\n\nThis document describes the Python execution architecture in `packages/coding-agent`, covering tool parameters, Jupyter Kernel Gateway lifecycles, environment isolation, execution semantics, and troubleshooting procedures.\n\n## Architecture overview\n\nPython execution is managed across several core modules:\n\n- `src/tools/python.ts`: Tool interface definition and interactive cell renderers.\n- `src/ipy/executor.ts`: Session-level kernel orchestration and execution scheduling.\n- `src/ipy/kernel.ts`: Kernel lifecycle management and WebSocket communication protocol.\n- `src/ipy/gateway-coordinator.ts`: Shared local Jupyter Kernel Gateway process coordinator.\n- `src/ipy/runtime.ts`: Python environment discovery, virtualenv resolution, and environment variable filtering.\n\n## Tool parameter schema\n\n```typescript\ninterface PythonToolParams {\n  cells: Array<{\n    code: string;\n    title?: string;\n  }>;\n  timeout?: number; // Execution timeout in seconds (1–600, default: 30)\n  cwd?: string; // Working directory for execution\n  reset?: boolean; // Reset kernel state prior to executing first cell\n}\n```\n\nThe tool executes with `concurrency: \"exclusive\"`, ensuring sequential execution per session.\n\n## Gateway lifecycle management\n\n### Gateway operational modes\n\n1. **Local shared gateway (default)**:\n   - Coordinates a single shared process under `~/.xcsh/agent/python-gateway/`.\n   - Synchronizes access via `gateway.lock` and tracks state in `gateway.json`.\n   - Starts `python -m kernel_gateway` bound to an ephemeral port on `127.0.0.1`.\n2. **External gateway**:\n   - Configured via `PI_PYTHON_GATEWAY_URL`.\n   - Authenticates requests with `PI_PYTHON_GATEWAY_TOKEN` when required.\n   - Bypasses local process management.\n\n### Kernel lifecycle\n\n1. **Creation**: Allocates a new kernel session via `POST /api/kernels`.\n2. **Connection**: Establishes a WebSocket channel (`/api/kernels/:id/channels`).\n3. **Initialization**: Configures `cwd`, applies sanitized environment variables, and executes runtime preludes.\n4. **Module loading**: Imports custom modules from `~/.xcsh/agent/modules/*.py` and project-specific `<CWD>/.xcsh/modules/*.py`.\n5. **Termination**: Issues `DELETE /api/kernels/:id` and closes WebSocket connections upon session cleanup.\n\n## Environment isolation and security\n\nBefore launching Python runtimes, xcsh filters environment variables:\n\n- **Retained variables**: Core system variables (`PATH`, `HOME`, `VIRTUAL_ENV`, `PYTHONPATH`) and whitelisted prefixes (`LC_*`, `XDG_*`, `PI_*`).\n- **Sanitized variables**: Strips sensitive LLM API keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`) to prevent accidental leaks.\n\n### Python environment resolution order\n\n1. Active virtual environment (`VIRTUAL_ENV` or `<CWD>/.venv`)\n2. Managed xcsh virtual environment (`~/.xcsh/python-env`)\n3. System `python3` or `python` on `PATH`\n\n## Output capture and MIME rendering\n\nThe runtime captures structured output across multiple MIME types:\n\n- `text/markdown`: Rendered directly in interactive output panes.\n- `text/plain`: Standard console output and tracebacks.\n- `application/json`: Formatted JSON inspector trees.\n- `image/png`: Inline image payloads.\n- `application/x-xcsh-status`: Structured progress and execution status events.\n\n## Troubleshooting\n\n### Python tool unavailable\n\n- Verify that `jupyter_kernel_gateway` and `ipykernel` are installed in the resolved Python environment:\n\n  ```bash\n  python -m pip install jupyter_kernel_gateway ipykernel\n  ```\n\n- Verify that `python.toolMode` or `PI_PY` is not set to `bash-only`.\n\n### Execution timeouts or hangs\n\n- Python does not support interactive standard input (`input()`). Avoid invoking interactive prompts.\n- To handle long-running workloads, increase the `timeout` parameter (up to 600 seconds).\n",
 	"en/runtime-tools/bash-tool-runtime.md": "---\ntitle: Bash Tool Runtime\ndescription: Bash tool runtime with shell process management, sandboxing, timeout, and output streaming.\nsidebar:\n  order: 1\n  label: Bash tool\n---\n\nThis document describes the execution pipeline of the `bash` tool in `packages/coding-agent`, covering command normalization, interception rules, process sandboxing, output truncation, and UI rendering across execution modes.\n\n## Execution entry points\n\nxcsh provides two distinct shell execution interfaces:\n\n1. **Agent tool interface (`bash`)**: Invoked by LLMs during conversation turns. Supports command normalization, security interception, PTY emulation, and structured output formatting.\n   - Entry point: `BashTool.execute()`\n2. **User shell execution (`!cmd`)**: Direct shell execution triggered by user input in the TUI or RPC mode.\n   - Entry point: `AgentSession.executeBash()`\n\nBoth execution paths utilize the underlying `executeBash()` engine in `src/exec/bash-executor.ts` for non-interactive execution.\n\n## Execution pipeline\n\n### 1. Command normalization and argument parsing\n\nWhen a tool call occurs, `BashTool.execute()` normalizes command strings via `normalizeBashCommand()`:\n\n- Extracts trailing pipe limits (`| head -n N`, `| tail -n N`) into structured pagination parameters.\n- Trims outer whitespace while preserving internal arguments and heredocs.\n- Merges extracted limits with explicit `head` or `tail` parameters (explicit arguments take precedence).\n\n### 2. Command interception and rule enforcement\n\nIf `bashInterceptor.enabled` is active, the tool checks the command against configured regex rules before spawning processes:\n\n- **Rule evaluation**: Blocks commands when patterns match (e.g., using `cat` or `grep` when specialized tools exist) and the suggested alternative tool is present in active context (`ctx.toolNames`).\n- **Rejection behavior**: Raises a `ToolError` containing the blocking reason and guidance toward preferred tools (`view_file`, `grep_search`, `list_dir`, `replace_file_content`).\n\n### 3. Working directory validation and timeouts\n\n- Resolves working directories relative to session root (`resolveToCwd`).\n- Validates that directory paths exist and are accessible directories prior to execution.\n- Clamps timeout durations to the range of 1 to 3600 seconds (default: 30 seconds).\n\n### 4. Interactive PTY vs. non-interactive execution\n\nxcsh chooses PTY execution (`runInteractiveBashPty`) when all of the following conditions are met:\n\n- `bash.virtualTerminal` is configured to `on`.\n- `PI_NO_PTY` is not set to `1`.\n- The session has an active graphical/TUI terminal context (`ctx.hasUI === true`).\n\nIn headless, print, or RPC modes, xcsh always uses non-interactive execution.\n\n## Output streaming, truncation, and artifact spill\n\nOutput is processed through `OutputSink` in `src/session/streaming-output.ts`:\n\n- **Memory buffer**: Maintains a UTF-8-safe tail buffer (default: 50 KB).\n- **Artifact spillover**: When output exceeds the buffer threshold, xcsh writes the full stream to disk in artifact storage (`artifact://<ID>`).\n- **Truncation notice**: Injects truncation summaries into tool results, including total byte/line counts and artifact links for full-output retrieval.\n\n## Filesystem sandboxing and containment\n\nxcsh enforces filesystem containment boundaries using platform-native security primitives:\n\n| Platform | Kernel version | Security backend | Boundary enforcement |\n| -------- | -------------- | ---------------- | -------------------- |\n| macOS | Any | `seatbelt` | OS-enforced kernel sandbox |\n| Linux (modern) | Kernel ≥ 6.1 (Debian 12, Ubuntu 24.04, Fedora) | `landlock` (ABI ≥ 2) | OS-enforced kernel sandbox |\n| Linux (legacy) | Kernel < 6.1 (RHEL 9, Ubuntu 22.04 GA) | `scanner-only` | Command-text static analysis |\n\n> [!IMPORTANT]\n> On legacy Linux kernels with Landlock ABI 1 (kernel < 6.1), xcsh operates in `scanner-only` mode because ABI 1 lacks `LANDLOCK_ACCESS_FS_REFER` (which prevents `git` and `mv` operations). For full OS-enforced isolation, deploy on Linux kernels 6.1 or newer.\n\n## Related implementation files\n\n- `src/tools/bash.ts`: Tool definition, normalization, and rendering logic.\n- `src/tools/bash-normalize.ts`: Command string normalization and line limit extraction.\n- `src/tools/bash-interceptor.ts`: Pattern matching rules for command redirection.\n- `src/exec/bash-executor.ts`: Process execution engine and shell session reuse.\n- `src/tools/bash-interactive.ts`: Virtual PTY runtime and terminal input handling.\n- `src/session/streaming-output.ts`: `OutputSink` buffer management and artifact spillover.\n",

package/src/modes/components/model-selector.ts

@@ -67,6 +67,29 @@ interface ScopedModelItem {
 	thinkingLevel?: string;
 }
 
+export interface DefaultPickerModelPresentation {
+	model: Model;
+	displaySelector: string;
+	selector: string;
+}
+
+const OPENAI_CODEX_GPT56_TIERS = new Set(["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol"]);
+
+/** Collapse subscription tiers only in the ordinary picker; explicit --models scopes keep raw access. */
+export function presentModelsForDefaultPicker(
+	models: readonly Model[],
+	explicitlyScoped = false,
+): DefaultPickerModelPresentation[] {
+	return models.flatMap(model => {
+		const selector = `${model.provider}/${model.id}`;
+		if (explicitlyScoped || model.provider !== "openai-codex" || !OPENAI_CODEX_GPT56_TIERS.has(model.id)) {
+			return [{ model, displaySelector: selector, selector }];
+		}
+		if (model.id !== "gpt-5.6-sol") return [];
+		return [{ model, displaySelector: "openai-codex/gpt-5.6", selector }];
+	});
+}
+
 interface RoleAssignment {
 	model: Model;
 	thinkingLevel: ThinkingLevel;
@@ -359,12 +382,15 @@ export class ModelSelectorComponent extends Container {
 
 		// Use scoped models if provided via --models flag
 		if (this.#scopedModels.length > 0) {
-			models = this.#scopedModels.map(scoped => ({
+			models = presentModelsForDefaultPicker(
+				this.#scopedModels.map(scoped => scoped.model),
+				true,
+			).map(item => ({
 				kind: "provider",
-				provider: scoped.model.provider,
-				id: scoped.model.id,
-				model: scoped.model,
-				selector: `${scoped.model.provider}/${scoped.model.id}`,
+				provider: item.model.provider,
+				id: item.displaySelector.slice(item.displaySelector.indexOf("/") + 1),
+				model: item.model,
+				selector: item.selector,
 			}));
 		} else {
 			// Reload config and cached discovery state without blocking on live provider refresh
@@ -381,12 +407,12 @@ export class ModelSelectorComponent extends Container {
 			// Load available models (built-in models still work even if models.json failed)
 			try {
 				const availableModels = this.#modelRegistry.getAvailable();
-				models = availableModels.map((model: Model) => ({
+				models = presentModelsForDefaultPicker(availableModels).map(item => ({
 					kind: "provider",
-					provider: model.provider,
-					id: model.id,
-					model,
-					selector: `${model.provider}/${model.id}`,
+					provider: item.model.provider,
+					id: item.displaySelector.slice(item.displaySelector.indexOf("/") + 1),
+					model: item.model,
+					selector: item.selector,
 				}));
 			} catch (error) {
 				this.#allModels = [];
@@ -428,7 +454,28 @@ export class ModelSelectorComponent extends Container {
 					compactSearchText: compactSearchText(searchText),
 				};
 			})
-			.filter((item): item is CanonicalModelItem => item !== undefined);
+			.filter((item): item is CanonicalModelItem => item !== undefined)
+			.filter(
+				item =>
+					this.#scopedModels.length > 0 ||
+					item.model.provider !== "openai-codex" ||
+					!OPENAI_CODEX_GPT56_TIERS.has(item.model.id),
+			);
+		if (this.#scopedModels.length === 0) {
+			const friendly = models.find(item => item.provider === "openai-codex" && item.id === "gpt-5.6");
+			if (friendly) {
+				canonicalModels.push({
+					kind: "canonical",
+					id: "openai-codex/gpt-5.6",
+					model: friendly.model,
+					selector: friendly.selector,
+					variantCount: 1,
+					searchText: "openai-codex/gpt-5.6 GPT-5.6 Sol",
+					normalizedSearchText: normalizeSearchText("openai-codex/gpt-5.6 GPT-5.6 Sol"),
+					compactSearchText: compactSearchText("openai-codex/gpt-5.6 GPT-5.6 Sol"),
+				});
+			}
+		}
 
 		this.#sortModels(models);
 		this.#sortCanonicalModels(canonicalModels);

package/src/modes/controllers/login-model.ts

@@ -1,5 +1,6 @@
 import { ThinkingLevel } from "@f5-sales-demo/pi-agent-core";
 import { canonicalizeOAuthProviderId, type Model } from "@f5-sales-demo/pi-ai";
+import type { Settings } from "../../config/settings";
 import type { VllmDiscoveredModel } from "../../config/vllm-config";
 import { applySubscriptionProfileRoles, type SubscriptionProfileId } from "../../routing/subscription-profiles";
 
@@ -42,10 +43,10 @@ export const GOOGLE_ANTIGRAVITY_LOGIN_MODEL_CHOICE: LoginModelChoice = {
 };
 
 export const OPENAI_CODEX_LOGIN_MODEL_CHOICE: LoginModelChoice = {
-	label: "GPT-5.6 Terra",
-	description: "Balanced OpenAI Codex subscription model with medium reasoning",
+	label: "GPT-5.6",
+	description: "OpenAI Codex subscription model with medium reasoning",
 	provider: "openai-codex",
-	modelId: "gpt-5.6-terra",
+	modelId: "gpt-5.6-sol",
 	thinkingLevel: ThinkingLevel.Medium,
 };
 
@@ -83,12 +84,7 @@ interface ModelApplicableSession extends BaseModelApplicableSession {
 		getAll(): Model[];
 		getProviderDiscoveryState?(provider: string): { status: string; stale: boolean } | undefined;
 	};
-	settings?: {
-		getModelRoles(): Readonly<Record<string, string | undefined>>;
-		get?(key: "routing.profile"): "none" | SubscriptionProfileId;
-		set(key: "modelRoles", value: Record<string, string>): void;
-		set(key: "routing.profile", value: "none" | SubscriptionProfileId): void;
-	};
+	settings?: Pick<Settings, "getModelRoles" | "get" | "set">;
 }
 
 /**
@@ -138,7 +134,12 @@ export async function applyOAuthLoginModel(
 	}
 
 	const settings = session.settings;
-	const previousProfile = settings?.get?.("routing.profile") ?? "none";
+	const storedProfile = settings?.get("routing.profile");
+	const previousProfile: "none" | SubscriptionProfileId =
+		storedProfile === "google-antigravity" || storedProfile === "openai-codex" ? storedProfile : "none";
+	const storedRoutingMode = settings?.get("routing.mode");
+	const previousRoutingMode =
+		storedRoutingMode === "shadow" || storedRoutingMode === "auto" ? storedRoutingMode : "off";
 	const previousRoles = settings
 		? Object.fromEntries(
 				Object.entries(settings.getModelRoles()).filter(
@@ -155,6 +156,7 @@ export async function applyOAuthLoginModel(
 		);
 		if (!profile.applied) return undefined;
 		settings.set("modelRoles", profile.roles);
+		settings.set("routing.mode", "off");
 		settings.set("routing.profile", canonicalProvider as SubscriptionProfileId);
 	}
 
@@ -162,12 +164,14 @@ export async function applyOAuthLoginModel(
 		const applied = await applyModelAfterLogin(session, choice);
 		if (!applied && settings) {
 			settings.set("modelRoles", previousRoles);
+			settings.set("routing.mode", previousRoutingMode);
 			settings.set("routing.profile", previousProfile);
 		}
 		return applied ? choice : undefined;
 	} catch (error) {
 		if (settings) {
 			settings.set("modelRoles", previousRoles);
+			settings.set("routing.mode", previousRoutingMode);
 			settings.set("routing.profile", previousProfile);
 		}
 		throw error;

package/src/modes/controllers/selector-controller.ts

@@ -86,7 +86,6 @@ import { commitVllmLogin } from "./vllm-login-transaction";
 
 const CALLBACK_SERVER_PROVIDERS = new Set<OAuthProvider>([
 	"anthropic",
-	"openai-codex-browser",
 	"gitlab-duo",
 	"google-gemini-cli",
 	"google-antigravity",
@@ -1225,8 +1224,7 @@ export class SelectorController {
 		this.ctx.showStatus(`Logging in to ${providerId}…`);
 		const manualInput = this.ctx.oauthManualInput;
 		const useManualInput =
-			CALLBACK_SERVER_PROVIDERS.has(providerId as OAuthProvider) ||
-			(providerId === "openai-codex" && resolveOpenAICodexLoginMethod() === "browser");
+			CALLBACK_SERVER_PROVIDERS.has(providerId as OAuthProvider) || providerId === "openai-codex";
 		const shouldOpenBrowser = providerId !== "openai-codex" || resolveOpenAICodexLoginMethod() === "browser";
 		const loginCallbacks = {
 			onAuth: (info: { url: string; instructions?: string }) => {

package/src/routing/subscription-profiles.ts

@@ -39,7 +39,7 @@ export const SUBSCRIPTION_ROUTING_PROFILES: Readonly<Record<SubscriptionProfileI
 		provider: "openai-codex",
 		roles: {
 			smol: "openai-codex/gpt-5.6-luna:low",
-			default: "openai-codex/gpt-5.6-terra:medium",
+			default: "openai-codex/gpt-5.6-sol:medium",
 			slow: "openai-codex/gpt-5.6-sol:high",
 			plan: "openai-codex/gpt-5.6-sol:high",
 		},