@f5-sales-demo/xcsh 19.61.4 → 19.61.5

package/package.json

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

package/src/browser/chat-handler.ts

@@ -31,12 +31,19 @@ export class ChatHandler {
 	#session: AgentSession;
 	#activeChats = new Map<string, ActiveChat>();
 	#activeHistoryHint: string | undefined;
+	#onTurnStart: (() => void) | undefined;
 
 	constructor(server: BridgeServer, session: AgentSession) {
 		this.#server = server;
 		this.#session = session;
 	}
 
+	/** Register a callback fired when a chat turn is accepted (used by the worker's
+	 * manager keepalive to refresh lastSeen at turn start). */
+	onTurnStart(cb: () => void): void {
+		this.#onTurnStart = cb;
+	}
+
 	attach(): void {
 		this.#server.onMessage(msg => {
 			if (isChatRequest(msg)) this.#handleChatRequest(msg as unknown as ChatRequest);
@@ -75,6 +82,7 @@ export class ChatHandler {
 			spanEmitted: false,
 		};
 		this.#activeChats.set(id, chat);
+		this.#onTurnStart?.();
 
 		const unsubscribe = this.#session.subscribe((event: AgentSessionEvent) => {
 			this.#handleSessionEvent(chat, event);

package/src/commands/manager-core.ts

@@ -17,7 +17,9 @@ const SHUTDOWN_REASONS = new Set<string>(["superseded", "updated", "manual"]);
 export type ControlMsg =
 	| { type: "provision"; sessionId: string; tenant: string }
 	| { type: "release"; sessionId: string }
-	| { type: "status" }
+	// An sid-less status is the legacy no-op sink; an sid-carrying status is a
+	// keepalive from an actively-chatting worker (see keepaliveFrame/touchLastSeen).
+	| { type: "status"; sessionId?: string }
 	| { type: "hello" }
 	| { type: "shutdown"; reason: ShutdownReason };
 
@@ -42,7 +44,8 @@ function isNonEmpty(v: unknown): v is string {
 export function parseControlMsg(raw: unknown): ControlMsg | null {
 	if (!raw || typeof raw !== "object") return null;
 	const m = raw as Record<string, unknown>;
-	if (m.type === "status") return { type: "status" };
+	if (m.type === "status")
+		return isNonEmpty(m.sessionId) ? { type: "status", sessionId: m.sessionId } : { type: "status" };
 	if (m.type === "provision" && isNonEmpty(m.sessionId) && isTenant(m.tenant))
 		return { type: "provision", sessionId: m.sessionId, tenant: m.tenant };
 	if (m.type === "release" && isNonEmpty(m.sessionId)) return { type: "release", sessionId: m.sessionId };
@@ -115,6 +118,27 @@ export function staleKeys(reg: Registry, now: number, idleMs: number): string[]
 	return out;
 }
 
+/** Refresh a worker's `lastSeen` from a keepalive/status frame; true iff a known
+ * session was touched. The manager never sees chat traffic (it flows worker↔
+ * bridge↔extension), so an actively-used session would otherwise be idle-reaped
+ * mid-conversation. An actively-chatting worker emits `keepaliveFrame` to drive
+ * this, keeping its session out of `staleKeys`. */
+export function touchLastSeen(reg: Registry, sessionId: string | undefined, now: number): boolean {
+	if (!sessionId) return false;
+	const w = reg.get(sessionId);
+	if (!w) return false;
+	w.lastSeen = now;
+	return true;
+}
+
+/** The NDJSON keepalive an actively-chatting worker writes to the manager control
+ * socket to refresh its `lastSeen` (consumed by `touchLastSeen`). Null for the
+ * unbound `spare` sentinel or an empty id — a spare has no session to keep alive. */
+export function keepaliveFrame(sessionId: string): string | null {
+	if (!sessionId || sessionId === "spare") return null;
+	return `${JSON.stringify({ type: "status", sessionId })}\n`;
+}
+
 /** How many new spares to spawn now to reach `target`, without exceeding the port
  * budget: spares + active workers must fit the discovery range. Never negative. */
 export function sparesToSpawn(

package/src/commands/manager-keepalive.ts

@@ -0,0 +1,117 @@
+/**
+ * Worker→manager keepalive client.
+ *
+ * The manager idle-reaps a worker whose `lastSeen` is older than `IDLE_MS`, and
+ * `lastSeen` is refreshed ONLY when the manager receives a control frame. Chat
+ * traffic flows worker↔bridge↔extension and never reaches the manager, so an
+ * actively-used-then-briefly-idle session used to be reaped mid-conversation
+ * (the "Turn aborted." after a break). This client emits a `status{sessionId}`
+ * keepalive over the manager's UNIX control socket while a turn is in flight and
+ * at each turn start, so the manager's sweep leaves an in-use session alive.
+ *
+ * The socket lifecycle (connect/reconnect) is injected as a `Connector` so the
+ * scheduling/emit logic is unit-testable without a real socket; the worker wires
+ * a `Bun.connect` transport. Best-effort throughout: if the manager socket is
+ * down (e.g. mid-supersede) emits are dropped and the next emit reconnects — so
+ * after a manager handoff the keepalive re-targets the successor manager, which
+ * has already re-adopted this worker.
+ */
+import { keepaliveFrame } from "./manager-core";
+
+/** A live connection to the manager control socket. */
+export interface KeepaliveTransport {
+	write(data: string): void;
+	close(): void;
+}
+
+/** Opens a transport; `onClose` MUST be invoked when the connection drops so the
+ * keepalive knows to reconnect on its next emit. Returns null if it cannot open. */
+export type Connector = (onClose: () => void) => Promise<KeepaliveTransport | null>;
+
+export interface ManagerKeepaliveDeps {
+	connect: Connector;
+	/** Current worker session id (may transition from "spare" to a real id). */
+	sessionId: () => string;
+	/** True while a chat turn is in flight. */
+	busy: () => boolean;
+}
+
+export class ManagerKeepalive {
+	#deps: ManagerKeepaliveDeps;
+	#transport: KeepaliveTransport | null = null;
+	#connecting = false;
+	#pending = false; // a keepalive is due once a connection is (re)established
+	#stopped = false;
+
+	constructor(deps: ManagerKeepaliveDeps) {
+		this.#deps = deps;
+	}
+
+	/** Periodic tick (driven by the worker's interval): emit iff a turn is busy. */
+	tick(): void {
+		if (this.#deps.busy()) this.#emit();
+	}
+
+	/** One-shot emit at the start of each turn — refreshes lastSeen immediately so
+	 * a session with long think-time between turns is never reaped between them. */
+	turnStart(): void {
+		this.#emit();
+	}
+
+	/** Stop emitting and close any open transport. */
+	stop(): void {
+		this.#stopped = true;
+		this.#pending = false;
+		this.#transport?.close();
+		this.#transport = null;
+	}
+
+	#emit(): void {
+		if (this.#stopped) return;
+		const frame = keepaliveFrame(this.#deps.sessionId());
+		if (!frame) return; // spare / unbound → nothing to keep alive (also skips connecting)
+		if (this.#transport) {
+			try {
+				this.#transport.write(frame);
+			} catch {
+				this.#transport = null; // dead socket → drop and reconnect on next emit
+				this.#pending = true;
+				void this.#ensureConnected();
+			}
+			return;
+		}
+		this.#pending = true;
+		void this.#ensureConnected();
+	}
+
+	async #ensureConnected(): Promise<void> {
+		if (this.#stopped || this.#transport || this.#connecting) return;
+		this.#connecting = true;
+		let t: KeepaliveTransport | null = null;
+		try {
+			t = await this.#deps.connect(() => {
+				this.#transport = null; // socket dropped → next emit reconnects
+			});
+		} catch {
+			t = null;
+		}
+		this.#connecting = false;
+		if (!t) return; // manager unreachable — best-effort, a later emit retries
+		if (this.#stopped) {
+			t.close();
+			return;
+		}
+		this.#transport = t;
+		if (this.#pending) {
+			this.#pending = false;
+			const frame = keepaliveFrame(this.#deps.sessionId());
+			if (frame) {
+				try {
+					this.#transport.write(frame);
+				} catch {
+					this.#transport = null;
+				}
+			}
+		}
+	}
+}

package/src/commands/manager.ts

@@ -11,6 +11,8 @@
  *          on sessionId, so two tabs of the SAME tenant get two workers.
  *   {"type":"release","sessionId":"tab-7"}  → kill + forget that session's worker
  *   {"type":"status"}                        → accepted; no-op sink
+ *   {"type":"status","sessionId":"tab-7"}    → keepalive: refresh that worker's
+ *          lastSeen so an actively-chatting session is not idle-reaped
  *
  * All registry/port/idempotency/idle policy is the pure `manager-core`; this file
  * is the thin I/O shell (socket, spawn, kill, timer) around it. A background sweep
@@ -25,7 +27,15 @@ import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { VERSION } from "@f5-sales-demo/pi-utils/dirs";
 import { portCandidates } from "../browser/extension-bridge";
 import { removeManagerState, writeManagerState } from "../services/manager-state";
-import { needsProvision, parseControlMsg, pickPort, type Registry, sparesToSpawn, staleKeys } from "./manager-core";
+import {
+	needsProvision,
+	parseControlMsg,
+	pickPort,
+	type Registry,
+	sparesToSpawn,
+	staleKeys,
+	touchLastSeen,
+} from "./manager-core";
 
 /** Reap a worker idle longer than this (ms). */
 const IDLE_MS = 20 * 60_000;
@@ -434,8 +444,13 @@ export default class Manager extends Command {
 					const managerProvisionMs = Date.now() - provisionReceivedAt;
 					if (!adoptSpare(msg, managerProvisionMs)) spawnWorker(msg, managerProvisionMs); // adopt a warm spare, else cold-spawn (fallback)
 				}
-				const w = reg.get(msg.sessionId);
-				if (w) w.lastSeen = Date.now(); // touch on every provision (keep-alive)
+				touchLastSeen(reg, msg.sessionId, Date.now()); // touch on every provision (keep-alive)
+			} else if (msg.type === "status") {
+				// Keepalive from an actively-chatting worker (#idle-reap): refresh
+				// lastSeen so the idle sweep never reaps a session that is in use.
+				// Chat traffic never reaches the manager, so this is the only signal
+				// that an otherwise-quiet-to-the-manager worker is still working.
+				touchLastSeen(reg, msg.sessionId, Date.now());
 			} else if (msg.type === "release") {
 				reap(msg.sessionId);
 			} else if (msg.type === "shutdown") {
@@ -452,7 +467,6 @@ export default class Manager extends Command {
 					/* client hung up mid-handshake — ignore */
 				}
 			}
-			// "status" is validated but currently a no-op sink.
 		};
 
 		// Per-connection NDJSON buffer: a control frame can be split across two TCP

package/src/commands/worker.ts

@@ -13,6 +13,8 @@
  * `XCSH_SESSION_TENANT` so it advertises its assigned tenant even before a context
  * is bound. This lets the extension panel lock onto the right tenant immediately.
  */
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { getProjectDir, getXCSHConfigDir, logger } from "@f5-sales-demo/pi-utils";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { ChatHandler } from "../browser/chat-handler";
@@ -25,6 +27,7 @@ import { createAgentSession } from "../sdk";
 import { activateTenantContext } from "../services/session-context-binding";
 import { ContextService } from "../services/xcsh-context";
 import { deriveTenantEnv } from "../services/xcsh-env";
+import { type KeepaliveTransport, ManagerKeepalive } from "./manager-keepalive";
 
 /** Mutable worker identity. Seeded from env at spawn (backward compat); replaced by a
  * late IPC bind on a pre-warmed spare. `null` fields fall back to env, then the "spare"
@@ -77,6 +80,16 @@ export function sessionInfoForWorker(): {
 /** Hard ceiling for draining an in-flight chat turn on SIGTERM before teardown (#1874). */
 const WORKER_DRAIN_TIMEOUT_MS = 10_000;
 
+/** How often the worker pings the manager while a turn is in flight, refreshing its
+ * lastSeen so an actively-chatting session is never idle-reaped. Comfortably under
+ * the manager's IDLE_MS (20 min); a turn also pings once at its start. */
+const KEEPALIVE_MS = 60_000;
+
+/** The manager control socket (same derivation as native-host / chrome-cli). */
+function managerSockPath(): string {
+	return process.env.XCSH_MANAGER_SOCK ?? join(homedir(), ".xcsh", "manager.sock");
+}
+
 /** Browser-automation tool set — identical scoping to `main.ts`'s extension path.
  * With scoped tools the ONLY way to create a resource is the form-driven workflow
  * runner, which is exactly what the human watching the browser wants. */
@@ -274,6 +287,38 @@ export default class Worker extends Command {
 		const chatHandler = new ChatHandler(bridge, session);
 		chatHandler.attach();
 
+		// 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,
+			connect: async onClose => {
+				try {
+					const sock = await Bun.connect({
+						unix: managerSockPath(),
+						socket: { data() {}, close: () => onClose(), error: () => onClose() },
+					});
+					const transport: KeepaliveTransport = {
+						write: data => {
+							sock.write(data);
+						},
+						close: () => {
+							sock.end();
+						},
+					};
+					return transport;
+				} catch {
+					return null; // manager not reachable — a later emit retries
+				}
+			},
+		});
+		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.
@@ -287,6 +332,8 @@ export default class Worker extends Command {
 
 		let shuttingDown = false;
 		const teardown = () => {
+			clearInterval(keepaliveTimer);
+			keepalive.stop();
 			chatHandler.dispose();
 			void bridge.close().finally(() => process.exit(0));
 		};

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.61.4",
-	"commit": "8697bc5fee06350b861c8c8bf7bbac1f00f85408",
-	"shortCommit": "8697bc5",
+	"version": "19.61.5",
+	"commit": "e9f45bc1c87e84c1d99060a016ae1e20907e2210",
+	"shortCommit": "e9f45bc",
 	"branch": "main",
-	"tag": "v19.61.4",
-	"commitDate": "2026-07-07T16:14:37Z",
-	"buildDate": "2026-07-07T16:40:48.327Z",
+	"tag": "v19.61.5",
+	"commitDate": "2026-07-08T01:47:55Z",
+	"buildDate": "2026-07-08T02:09:52.692Z",
 	"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/8697bc5fee06350b861c8c8bf7bbac1f00f85408",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.4"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/e9f45bc1c87e84c1d99060a016ae1e20907e2210",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.5"
 };