@f5-sales-demo/xcsh 19.91.0 → 19.91.1

package/package.json

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

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

@@ -29,6 +29,24 @@ import type { ExtensionAPI, ExtensionContext } from "@f5-sales-demo/xcsh";
  * The extension is completely inert unless it is running inside a herdr pane
  * (detected via `HERDR_PANE_ID`), so it has zero effect for users who do not run
  * xcsh under herdr.
+ *
+ * Sequencing contract with herdr — do not regress. herdr keeps one monotonic
+ * `seq` per *source*, shared across every method, and silently discards any frame
+ * whose `seq` is not greater than the last it accepted for `herdr:xcsh`. Two
+ * consequences drive the design below, and both previously cost panes their
+ * resume reference:
+ *
+ *   1. `seq` is seeded from the wall clock, not 0, so a restarted xcsh always
+ *      outranks its predecessor in the same pane. With a per-process counter from
+ *      0, every frame from the second xcsh in a pane looks stale and is dropped.
+ *   2. Frames go out one at a time through `enqueue`. They used to be
+ *      fire-and-forget on independent sockets, so ordering was left to chance.
+ *   3. The state frame is always sent *before* the session frame. herdr discards a
+ *      `pane.report_agent_session` for a pane whose agent it does not yet own, so
+ *      the state frame has to establish `herdr:xcsh` as the pane's agent first.
+ *      Verified against a live herdr: session-then-state (even with a correctly
+ *      ascending `seq`) leaves `agent_session` null, while state-then-session
+ *      records it.
  */
 
 const HERDR_AGENT_LABEL = "xcsh";
@@ -42,26 +60,43 @@ const SOCKET_TIMEOUT_MS = 2000;
 
 /**
  * Write one newline-delimited JSON-RPC request to herdr's unix socket and close.
- * Fire-and-forget: the response is ignored and every failure path is reported
- * via `onError` without throwing, so a dead socket never disturbs the agent.
+ * The response is ignored and every failure path is reported via `onError`
+ * without throwing, so a dead socket never disturbs the agent.
+ *
+ * Resolves once the frame has been flushed (or the attempt failed or timed out),
+ * which is what lets callers order frames relative to one another.
  */
 function sendToHerdrSocket(
 	socketPath: string,
 	method: string,
 	params: Record<string, unknown>,
 	onError: (err: unknown) => void,
-): void {
-	const conn = connect({ path: socketPath });
-	// Never let a report keep xcsh's event loop alive.
-	conn.unref();
-	conn.once("error", err => {
-		onError(err);
-		conn.destroy();
-	});
-	conn.once("connect", () => {
-		conn.end(`${JSON.stringify({ id: "xcsh:herdr-reporter", method, params })}\n`);
+): Promise<void> {
+	return new Promise<void>(resolve => {
+		let settled = false;
+		const settle = (): void => {
+			if (settled) {
+				return;
+			}
+			settled = true;
+			resolve();
+		};
+		const conn = connect({ path: socketPath });
+		// Never let a report keep xcsh's event loop alive.
+		conn.unref();
+		conn.once("error", err => {
+			onError(err);
+			conn.destroy();
+			settle();
+		});
+		conn.once("connect", () => {
+			conn.end(`${JSON.stringify({ id: "xcsh:herdr-reporter", method, params })}\n`, settle);
+		});
+		conn.setTimeout(SOCKET_TIMEOUT_MS, () => {
+			conn.destroy();
+			settle();
+		});
 	});
-	conn.setTimeout(SOCKET_TIMEOUT_MS, () => conn.destroy());
 }
 
 /** Translate a JSON-RPC report/release into `herdr` CLI arguments (fallback). */
@@ -90,10 +125,19 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 		return;
 	}
 
-	let seq = 0;
+	// Seeded from the wall clock at microsecond scale rather than 0 so a new xcsh
+	// process in a pane always starts above whatever the previous process reached.
+	// Matches the pi/omp reporters and stays well inside Number.MAX_SAFE_INTEGER.
+	let seq = Date.now() * 1000;
 	// Tracks whether an interactive prompt is currently awaiting the user, so an
 	// agent_end that fires while a prompt is open is reported as blocked, not idle.
 	let promptOpen = false;
+	// Last session ref already delivered, so repeated lifecycle events do not
+	// re-send an unchanged ref every turn.
+	let lastSessionRefKey: string | undefined;
+	// Serializes frames: herdr compares `seq` across all methods for this source,
+	// so frames must reach it in the order they were generated.
+	let queue: Promise<void> = Promise.resolve();
 
 	pi.setLabel(HERDR_AGENT_LABEL);
 
@@ -103,17 +147,27 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 		});
 	};
 
-	const send = (method: string, params: Record<string, unknown>): void => {
+	/** Chain a frame onto the tail of the send queue. Never rejects. */
+	const enqueue = (task: () => Promise<void>): Promise<void> => {
+		queue = queue.then(task, task).catch(onError);
+		return queue;
+	};
+
+	const send = (method: string, params: Record<string, unknown>): Promise<void> => {
 		const socketPath = process.env.HERDR_SOCKET_PATH;
 		if (socketPath) {
-			sendToHerdrSocket(socketPath, method, params, onError);
-			return;
+			return enqueue(() => sendToHerdrSocket(socketPath, method, params, onError));
 		}
 		// Fallback for the rare case herdr did not inject a socket path.
-		pi.exec("herdr", toCliArgs(method, params)).catch(onError);
+		return enqueue(() =>
+			pi
+				.exec("herdr", toCliArgs(method, params))
+				.then(() => undefined)
+				.catch(onError),
+		);
 	};
 
-	const report = (state: "idle" | "working" | "blocked"): void => {
+	const report = (state: "idle" | "working" | "blocked"): Promise<void> =>
 		send(REPORT_METHOD, {
 			pane_id: paneId,
 			source: HERDR_SOURCE,
@@ -121,7 +175,6 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 			state,
 			seq: seq++,
 		});
-	};
 
 	// Report the current session's identity so herdr can resume this pane
 	// (`xcsh --resume=<session>`) after a server restart. This is sent only over
@@ -129,10 +182,16 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 	// reports via the CLI fallback). Prefer the absolute session file path, which
 	// herdr resumes directly; fall back to the session id for non-persisted
 	// sessions (e.g. print/RPC mode, where getSessionFile() is undefined).
-	const reportSession = (ctx: ExtensionContext): void => {
+	//
+	// Called from every lifecycle handler because xcsh creates the session file
+	// lazily: getSessionFile() can still be undefined at session_start and even at
+	// agent_start, and a ref missed there would otherwise be lost until the next
+	// turn — long enough for a restart to lose the pane. Unchanged refs are
+	// suppressed, so the extra call sites cost nothing on the wire.
+	const reportSession = (ctx: ExtensionContext): Promise<void> => {
 		const socketPath = process.env.HERDR_SOCKET_PATH;
 		if (!socketPath) {
-			return;
+			return Promise.resolve();
 		}
 		let sessionRef: Record<string, unknown> | undefined;
 		try {
@@ -147,58 +206,63 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 			}
 		} catch (err) {
 			onError(err);
-			return;
+			return Promise.resolve();
 		}
 		if (!sessionRef) {
-			return;
+			return Promise.resolve();
 		}
-		sendToHerdrSocket(
-			socketPath,
-			SESSION_METHOD,
-			{
-				pane_id: paneId,
-				source: HERDR_SOURCE,
-				agent: HERDR_AGENT_LABEL,
-				seq: seq++,
-				...sessionRef,
-			},
-			onError,
-		);
+		const refKey = JSON.stringify(sessionRef);
+		if (refKey === lastSessionRefKey) {
+			return Promise.resolve();
+		}
+		lastSessionRefKey = refKey;
+		const frame = {
+			pane_id: paneId,
+			source: HERDR_SOURCE,
+			agent: HERDR_AGENT_LABEL,
+			seq: seq++,
+			...sessionRef,
+		};
+		return enqueue(() => sendToHerdrSocket(socketPath, SESSION_METHOD, frame, onError));
 	};
 
 	// Announce presence and session identity as soon as the session is initialized.
-	pi.on("session_start", (_event, ctx) => {
-		reportSession(ctx);
-		report("idle");
+	pi.on("session_start", async (_event, ctx) => {
+		await report("idle");
+		await reportSession(ctx);
 	});
 
 	// Busy while the agent loop is streaming a response. Re-report session identity
 	// in case the active session file changed (e.g. after /new, /resume, or /fork).
-	pi.on("agent_start", (_event, ctx) => {
-		reportSession(ctx);
-		report("working");
+	pi.on("agent_start", async (_event, ctx) => {
+		await report("working");
+		await reportSession(ctx);
 	});
 
 	// Back to idle when the loop ends — unless we are waiting on a user prompt.
-	pi.on("agent_end", () => {
-		report(promptOpen ? "blocked" : "idle");
+	// This is also the first point where a lazily-created session file is certain
+	// to exist, so it is the backstop for capturing the resume ref.
+	pi.on("agent_end", async (_event, ctx) => {
+		await report(promptOpen ? "blocked" : "idle");
+		await reportSession(ctx);
 	});
 
 	// An interactive prompt (permission gate, ask tool, confirm/input) is
 	// awaiting the user: that is herdr's "needs attention" (blocked) state.
 	pi.on("user_prompt_start", () => {
 		promptOpen = true;
-		report("blocked");
+		void report("blocked");
 	});
 
-	pi.on("user_prompt_end", (_event, ctx) => {
+	pi.on("user_prompt_end", async (_event, ctx) => {
 		promptOpen = false;
-		report(ctx.isIdle() ? "idle" : "working");
+		await report(ctx.isIdle() ? "idle" : "working");
+		await reportSession(ctx);
 	});
 
 	// Relinquish pane authority so herdr stops showing xcsh once we exit.
 	pi.on("session_shutdown", () => {
-		send(RELEASE_METHOD, {
+		void send(RELEASE_METHOD, {
 			pane_id: paneId,
 			source: HERDR_SOURCE,
 			agent: HERDR_AGENT_LABEL,

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.91.0",
-	"commit": "37a9e074a2203b5faeee3e41f7a2d7704f120c4f",
-	"shortCommit": "37a9e07",
+	"version": "19.91.1",
+	"commit": "cb975aa015ff199ecdc38c20544471ebf32e3737",
+	"shortCommit": "cb975aa",
 	"branch": "main",
-	"tag": "v19.91.0",
-	"commitDate": "2026-07-25T15:33:10Z",
-	"buildDate": "2026-07-25T15:59:23.847Z",
+	"tag": "v19.91.1",
+	"commitDate": "2026-07-25T17:10:56Z",
+	"buildDate": "2026-07-25T17:31:09.895Z",
 	"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/37a9e074a2203b5faeee3e41f7a2d7704f120c4f",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.91.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/cb975aa015ff199ecdc38c20544471ebf32e3737",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.91.1"
 };