@f5-sales-demo/xcsh 19.91.0 → 19.92.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.91.0",
+	"version": "19.92.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -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.92.0",
+		"@f5-sales-demo/pi-agent-core": "19.92.0",
+		"@f5-sales-demo/pi-ai": "19.92.0",
+		"@f5-sales-demo/pi-natives": "19.92.0",
+		"@f5-sales-demo/pi-resource-management": "19.92.0",
+		"@f5-sales-demo/pi-tui": "19.92.0",
+		"@f5-sales-demo/pi-utils": "19.92.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/chat-handler.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import type { AssistantMessage, ImageContent } from "@f5-sales-demo/pi-ai";
 import { settings } from "../config/settings";
 import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
+import { toSkillSummaries } from "../extensibility/skills";
 import {
 	isRpcHostToolResult,
 	isRpcHostToolUpdate,
@@ -428,8 +429,8 @@ export class ChatHandler {
 	 *  already loaded on the session; the model actions them via the read tool + the
 	 *  system prompt (Phase 2A enabled `read`), so this is enumeration only. */
 	#handleListSkills(): void {
-		const skills = this.#session.skills.map(s => ({ name: s.name, description: s.description }));
-		this.#server.send({ type: "skills", skills } satisfies SkillsList);
+		// Shared projection: one place decides what crosses to a client (never paths).
+		this.#server.send({ type: "skills", skills: toSkillSummaries(this.#session.skills) } satisfies SkillsList);
 	}
 
 	#sendTerminal(chat: ActiveChat, frame: ChatDone | ChatError): void {

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/extensibility/skills.ts

@@ -19,6 +19,26 @@ export interface Skill {
 	_source?: SourceMeta;
 }
 
+/** A skill as a CLIENT sees it: enough to render a menu entry, nothing more. */
+export interface SkillSummary {
+	name: string;
+	description: string;
+}
+
+/**
+ * Project loaded skills onto the client-facing summary.
+ *
+ * `Skill` also carries `filePath`, `baseDir`, `source` and `_source` — the
+ * operator's on-disk layout. A UI surface (Office pane, Chrome side panel, VS Code
+ * webview) needs only the name and description to populate a menu, so this is the
+ * one place that decides what crosses the boundary. Shared by every transport
+ * (the `list_skills` bridge frame and the `list_skills` RPC command) so they can't
+ * drift into leaking different amounts.
+ */
+export function toSkillSummaries(skills: readonly Skill[]): SkillSummary[] {
+	return skills.map(s => ({ name: s.name, description: s.description }));
+}
+
 export interface SkillWarning {
 	skillPath: string;
 	message: string;

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.92.0",
+	"commit": "65c380d28a5d308cd6cc8382555be0498001e306",
+	"shortCommit": "65c380d",
 	"branch": "main",
-	"tag": "v19.91.0",
-	"commitDate": "2026-07-25T15:33:10Z",
-	"buildDate": "2026-07-25T15:59:23.847Z",
+	"tag": "v19.92.0",
+	"commitDate": "2026-07-25T23:53:03Z",
+	"buildDate": "2026-07-26T00:14:01.234Z",
 	"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/65c380d28a5d308cd6cc8382555be0498001e306",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.92.0"
 };

package/src/modes/rpc/rpc-client.ts

@@ -389,6 +389,15 @@ export class RpcClient {
 		return this.#getData(response);
 	}
 
+	/**
+	 * List the session's loaded skills (name + description) so a host can populate a
+	 * skills menu. Enumeration only — invoking one is just a prompt beginning `/name`.
+	 */
+	async listSkills(): Promise<{ skills: Array<{ name: string; description: string }> }> {
+		const response = await this.#send({ type: "list_skills" });
+		return this.#getData(response);
+	}
+
 	/**
 	 * Set thinking level.
 	 */

package/src/modes/rpc/rpc-mode.ts

@@ -16,6 +16,7 @@ import type {
 	ExtensionUIDialogOptions,
 	ExtensionWidgetOptions,
 } from "../../extensibility/extensions";
+import { toSkillSummaries } from "../../extensibility/skills";
 import {
 	isRpcHostToolResult,
 	isRpcHostToolUpdate,
@@ -636,6 +637,13 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				});
 			}
 
+			case "list_skills": {
+				// Enumeration only: skills already work through the read tool + system
+				// prompt. Mirrors the `list_skills` bridge frame the Office pane uses, via
+				// the same shared projection so neither transport can leak on-disk paths.
+				return success(id, "list_skills", { skills: toSkillSummaries(session.skills) });
+			}
+
 			// =================================================================
 			// Model
 			// =================================================================

package/src/modes/rpc/rpc-types.ts

@@ -7,6 +7,7 @@
 import type { AgentMessage, ThinkingLevel } from "@f5-sales-demo/pi-agent-core";
 import type { Effort, ImageContent, Model } from "@f5-sales-demo/pi-ai";
 import type { BashResult } from "../../exec/bash-executor";
+import type { SkillSummary } from "../../extensibility/skills";
 // The host-tool wire types are transport-neutral and live in the shared host-tool
 // core so both the stdio RPC driver and the WS chat bridge use one vocabulary.
 import type {
@@ -48,6 +49,7 @@ export type RpcCommand =
 	| { id?: string; type: "set_todos"; phases: TodoPhase[] }
 	| { id?: string; type: "set_host_tools"; tools: RpcHostToolDefinition[] }
 	| { id?: string; type: "get_integrations" }
+	| { id?: string; type: "list_skills" }
 
 	// Model
 	| { id?: string; type: "set_model"; provider: string; modelId: string }
@@ -132,6 +134,13 @@ export type RpcResponse =
 	| { id?: string; type: "response"; command: "get_state"; success: true; data: RpcSessionState }
 	| { id?: string; type: "response"; command: "set_todos"; success: true; data: { todoPhases: TodoPhase[] } }
 	| { id?: string; type: "response"; command: "set_host_tools"; success: true; data: { toolNames: string[] } }
+	| {
+			id?: string;
+			type: "response";
+			command: "list_skills";
+			success: true;
+			data: { skills: SkillSummary[] };
+	  }
 	| {
 			id?: string;
 			type: "response";

package/src/system-prompt.ts

@@ -6,7 +6,16 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentTool } from "@f5-sales-demo/pi-agent-core";
-import { $env, getGpuCachePath, getProjectDir, hasFsCode, isEnoent, logger, prompt } from "@f5-sales-demo/pi-utils";
+import {
+	$env,
+	getGpuCachePath,
+	getProjectDir,
+	hasFsCode,
+	isEnoent,
+	logger,
+	prompt,
+	withTimeout,
+} from "@f5-sales-demo/pi-utils";
 import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";
 import { systemPromptCapability } from "./capability/system-prompt";
@@ -125,13 +134,42 @@ export interface AgentsMdSearch {
 	files: string[];
 }
 
-/** Mutable traversal budget shared across the recursive walk. */
-interface WalkBudget {
+/** Reads one directory. Injectable so tests can simulate a readdir that never settles. */
+type ReaddirFn = (dir: string) => Promise<fs.Dirent[]>;
+
+/** Mutable traversal budget + the reader, shared across the recursive walk. */
+interface WalkContext {
 	readonly maxDirs: number;
 	readonly deadline: number;
+	readonly readdir: ReaddirFn;
 	dirsVisited: number;
 }
 
+/**
+ * Read one directory, giving up when the walk's deadline passes.
+ *
+ * The budget checks between directories are NOT enough on their own: a `readdir`
+ * that never settles — a TCC-protected or cloud-synced directory such as
+ * ~/Documents on a managed Mac — would park the walk forever at zero CPU, hanging
+ * `createAgentSession` and with it the Office pane's `set_host_tools` (#2399). The
+ * deadline has to be enforced HERE, around the syscall itself.
+ *
+ * Returns null when the directory could not be read in time (or at all); the
+ * caller treats that as "nothing here" and moves on.
+ *
+ * The abandoned read keeps a thread-pool slot until the OS releases it. That is
+ * bounded by the number of pathological directories and is strictly better than
+ * never returning.
+ */
+async function readdirWithinBudget(dir: string, ctx: WalkContext): Promise<fs.Dirent[] | null> {
+	const remaining = ctx.deadline - Date.now();
+	if (remaining <= 0) return null;
+	// `withTimeout` rejects on expiry and clears its own timer; here expiry is an
+	// ordinary outcome, so both it and a real read failure collapse to null — the
+	// caller treats either as "nothing here".
+	return await withTimeout(ctx.readdir(dir), remaining, `readdir exceeded the walk budget: ${dir}`).catch(() => null);
+}
+
 function normalizePath(value: string): string {
 	return value.replace(/\\/g, "/");
 }
@@ -148,7 +186,7 @@ async function collectAgentsMdFiles(
 	limit: number,
 	maxDepth: number,
 	discovered: Set<string>,
-	budget: WalkBudget,
+	budget: WalkContext,
 ): Promise<void> {
 	// Stop on any bound: depth, enough matches, the directory-visit budget, or the
 	// wall-clock deadline. The last two keep a match-poor tree (e.g. $HOME) bounded.
@@ -165,12 +203,9 @@ async function collectAgentsMdFiles(
 	// sibling sees the updated count before it yields, making the cap effectively hard.
 	budget.dirsVisited++;
 
-	let entries: fs.Dirent[];
-	try {
-		entries = await fs.promises.readdir(dir, { withFileTypes: true });
-	} catch {
-		return;
-	}
+	// Deadline-guarded: a directory that never answers must not park the whole walk.
+	const entries = await readdirWithinBudget(dir, budget);
+	if (!entries) return;
 
 	if (depth >= AGENTS_MD_MIN_DEPTH) {
 		const hasAgentsMd = entries.some(entry => entry.isFile() && entry.name === "XCSH.md");
@@ -208,12 +243,18 @@ export interface DiscoverAgentsMdOptions {
 	maxDepth?: number;
 	maxDirs?: number;
 	budgetMs?: number;
+	/** Directory reader; defaults to `fs.promises.readdir`. A test seam for
+	 *  simulating a filesystem that never answers. */
+	readdir?: ReaddirFn;
 }
 
 /**
  * Walk `root` (bounded by depth, match-limit, directory budget, and a wall-clock
  * deadline) collecting nested `XCSH.md` paths. Returns the sorted matches plus the
  * number of directories visited (for observability/tests). Never throws.
+ *
+ * The deadline is PREEMPTIVE: it bounds each `readdir` as well as the walk as a
+ * whole, so a directory that never answers cannot stall startup (#2399).
  */
 export async function discoverAgentsMdFiles(
 	root: string,
@@ -221,17 +262,18 @@ export async function discoverAgentsMdFiles(
 ): Promise<{ files: string[]; dirsVisited: number }> {
 	const limit = opts.limit ?? AGENTS_MD_LIMIT;
 	const maxDepth = opts.maxDepth ?? AGENTS_MD_MAX_DEPTH;
-	const budget: WalkBudget = {
+	const ctx: WalkContext = {
 		maxDirs: opts.maxDirs ?? AGENTS_MD_MAX_DIRS,
 		deadline: Date.now() + (opts.budgetMs ?? AGENTS_MD_WALK_BUDGET_MS),
+		readdir: opts.readdir ?? ((dir: string) => fs.promises.readdir(dir, { withFileTypes: true })),
 		dirsVisited: 0,
 	};
 	try {
 		const discovered = new Set<string>();
-		await collectAgentsMdFiles(root, root, 0, limit, maxDepth, discovered, budget);
-		return { files: Array.from(discovered).sort().slice(0, limit), dirsVisited: budget.dirsVisited };
+		await collectAgentsMdFiles(root, root, 0, limit, maxDepth, discovered, ctx);
+		return { files: Array.from(discovered).sort().slice(0, limit), dirsVisited: ctx.dirsVisited };
 	} catch {
-		return { files: [], dirsVisited: budget.dirsVisited };
+		return { files: [], dirsVisited: ctx.dirsVisited };
 	}
 }