@f5-sales-demo/xcsh 19.83.0 → 19.85.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.83.0",
+	"version": "19.85.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": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.83.0",
-		"@f5-sales-demo/pi-agent-core": "19.83.0",
-		"@f5-sales-demo/pi-ai": "19.83.0",
-		"@f5-sales-demo/pi-natives": "19.83.0",
-		"@f5-sales-demo/pi-resource-management": "19.83.0",
-		"@f5-sales-demo/pi-tui": "19.83.0",
-		"@f5-sales-demo/pi-utils": "19.83.0",
+		"@f5-sales-demo/xcsh-stats": "19.85.0",
+		"@f5-sales-demo/pi-agent-core": "19.85.0",
+		"@f5-sales-demo/pi-ai": "19.85.0",
+		"@f5-sales-demo/pi-natives": "19.85.0",
+		"@f5-sales-demo/pi-resource-management": "19.85.0",
+		"@f5-sales-demo/pi-tui": "19.85.0",
+		"@f5-sales-demo/pi-utils": "19.85.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/chat-handler.ts

@@ -555,7 +555,18 @@ function titleFromUrl(url: string): string {
 	}
 }
 
-function extractReferences(msg: AssistantMessage): ChatReference[] {
+/**
+ * Trailing characters a bare-URL match may greedily swallow at a markdown/prose
+ * boundary — markdown emphasis (`*_~`) and sentence/wrap punctuation. A real URL
+ * effectively never ends in these, so trimming them yields the intended link
+ * (e.g. `**https://…/llms.txt**` → `https://…/llms.txt`). The markdown-link branch
+ * is bounded by its closing `)` and needs no trimming.
+ */
+function trimTrailingMarkup(url: string): string {
+	return url.replace(/[*_~,.;:!?'")\]]+$/, "");
+}
+
+export function extractReferences(msg: AssistantMessage): ChatReference[] {
 	const refs: ChatReference[] = [];
 	const seen = new Set<string>();
 
@@ -572,7 +583,7 @@ function extractReferences(msg: AssistantMessage): ChatReference[] {
 
 		const bareUrlRegex = /(?<!\()(https?:\/\/[^\s)>\]]+)/g;
 		for (let match = bareUrlRegex.exec(block.text); match !== null; match = bareUrlRegex.exec(block.text)) {
-			const url = match[1];
+			const url = trimTrailingMarkup(match[1]);
 			if (seen.has(url)) continue;
 			seen.add(url);
 			refs.push({ kind: classifyReferenceKind(url), title: titleFromUrl(url), url });

package/src/browser/office-serve-lifecycle.ts

@@ -0,0 +1,118 @@
+/**
+ * Supersede / recycle a foreground `xcsh office serve`.
+ *
+ * `office serve` binds a FIXED :8444 listener, so after a `brew upgrade` the old
+ * serve squats the port on the stale binary and a fresh `office serve` dies with
+ * "port 8444 in use". These helpers let the new serve step the old one down on
+ * start (supersede), and give `office recycle` (run from brew post_install) a way
+ * to stop the stale serve so the next start is clean — the office analog of
+ * `chrome recycle`.
+ *
+ * Safety: we only ever signal a PID that (a) actually holds :8444 AND (b) looks
+ * like an `office serve` (its `ps` command line contains "office serve"). A
+ * foreign holder is reported, never killed — so PID reuse can't make us signal an
+ * unrelated process.
+ */
+import { OFFICE_PANE_PORT } from "./office-pane-server";
+
+/** Injectable seams so the wait/signal logic is unit-testable without real procs. */
+export interface ServeLifecycleDeps {
+	/** PID listening on `port`, or 0 if none/unknown (best-effort via lsof). */
+	pidListeningOn: (port: number) => number;
+	/** Whether `pid`'s command line is an `xcsh office serve`. */
+	isOfficeServe: (pid: number) => boolean;
+	/** Send a signal to `pid` (process.kill). */
+	signal: (pid: number, sig: NodeJS.Signals) => void;
+	/** Await `ms` (setTimeout in prod; immediate in tests). */
+	sleep: (ms: number) => Promise<void>;
+}
+
+export interface SupersedeResult {
+	/** True when a stale serve was found and stepped down. */
+	superseded: boolean;
+	/** The stale PID we signalled (present only when superseded). */
+	pid?: number;
+}
+
+const WAIT_MS = 3000;
+const POLL_MS = 100;
+
+/** PID listening on `port`, or 0 (best-effort; lsof unavailable → 0). */
+function pidListeningOn(port: number): number {
+	try {
+		const out = Bun.spawnSync(["lsof", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"])
+			.stdout.toString()
+			.trim()
+			.split("\n")[0];
+		const pid = Number(out);
+		return Number.isInteger(pid) && pid > 0 ? pid : 0;
+	} catch {
+		return 0;
+	}
+}
+
+/** Whether `pid`'s full command line is an `xcsh office serve` (ps, best-effort). */
+function isOfficeServe(pid: number): boolean {
+	try {
+		const out = Bun.spawnSync(["ps", "-p", String(pid), "-o", "command="]).stdout.toString();
+		return /office\s+serve/.test(out);
+	} catch {
+		return false;
+	}
+}
+
+const defaultDeps: ServeLifecycleDeps = {
+	pidListeningOn,
+	isOfficeServe,
+	signal: (pid, sig) => process.kill(pid, sig),
+	sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+};
+
+/** SIGTERM `pid` and poll until `port` is released by it, or throw on timeout. */
+async function signalAndWait(pid: number, port: number, deps: ServeLifecycleDeps): Promise<void> {
+	deps.signal(pid, "SIGTERM");
+	for (let waited = 0; waited < WAIT_MS; waited += POLL_MS) {
+		await deps.sleep(POLL_MS);
+		const now = deps.pidListeningOn(port);
+		if (now <= 0 || now !== pid) return; // freed (or a different serve took over)
+	}
+	throw new Error(`Timed out waiting for the stale office serve (PID ${pid}) to release port ${port}.`);
+}
+
+/**
+ * Step down a stale `office serve` holding `port` so a fresh serve can bind.
+ * No-op when the port is free. Throws (without signalling) when the holder is not
+ * an office serve — the caller should surface that rather than kill a stranger.
+ */
+export async function supersedeStaleServe(
+	port = OFFICE_PANE_PORT,
+	deps: ServeLifecycleDeps = defaultDeps,
+): Promise<SupersedeResult> {
+	const pid = deps.pidListeningOn(port);
+	if (pid <= 0 || pid === process.pid) return { superseded: false };
+	if (!deps.isOfficeServe(pid)) {
+		throw new Error(
+			`Port ${port} is held by PID ${pid}, which isn't an xcsh office serve. Stop it manually, then retry.`,
+		);
+	}
+	await signalAndWait(pid, port, deps);
+	return { superseded: true, pid };
+}
+
+/**
+ * Stop a running `office serve` (if any) — used by `office recycle` and brew
+ * post_install so an upgrade clears the stale serve. Returns a human message;
+ * never throws for the ordinary cases (nothing running / foreign holder).
+ */
+export async function recycleOfficeServe(
+	port = OFFICE_PANE_PORT,
+	deps: ServeLifecycleDeps = defaultDeps,
+): Promise<string> {
+	const pid = deps.pidListeningOn(port);
+	if (pid <= 0) return "No xcsh office serve is running.";
+	if (!deps.isOfficeServe(pid)) {
+		return `Port ${port} is held by PID ${pid}, which isn't an xcsh office serve — leaving it alone.`;
+	}
+	await signalAndWait(pid, port, deps);
+	return `Stopped the running office serve (PID ${pid}). Start it again with \`xcsh office serve\`.`;
+}

package/src/cli/office-cli.ts

@@ -13,13 +13,15 @@ import { LOCALIP_HOST } from "../browser/bridge-cert";
 import { type HeadlessChatBridge, startHeadlessChatBridge } from "../browser/headless-bridge";
 import {
 	getOfficePaneDir,
+	OFFICE_PANE_PORT,
 	type OfficePaneServer,
 	readManifest,
 	startOfficePaneServer,
 } from "../browser/office-pane-server";
+import { recycleOfficeServe, supersedeStaleServe } from "../browser/office-serve-lifecycle";
 
 /** The subcommands `xcsh office` accepts (also the Args `options` constraint). */
-export const OFFICE_ACTIONS = ["serve", "manifest", "sideload"] as const;
+export const OFFICE_ACTIONS = ["serve", "manifest", "sideload", "recycle"] as const;
 export type OfficeAction = (typeof OFFICE_ACTIONS)[number];
 
 /** Desktop Office apps a sideload can target. */
@@ -50,9 +52,10 @@ export async function writeManifest(outPath?: string): Promise<string> {
 export interface OfficeServeDeps {
 	startOfficePaneServer: typeof startOfficePaneServer;
 	startHeadlessChatBridge: typeof startHeadlessChatBridge;
+	supersedeStaleServe: typeof supersedeStaleServe;
 }
 
-const defaultServeDeps: OfficeServeDeps = { startOfficePaneServer, startHeadlessChatBridge };
+const defaultServeDeps: OfficeServeDeps = { startOfficePaneServer, startHeadlessChatBridge, supersedeStaleServe };
 
 /** A running `office serve`: the pane file server, the (optional) chat bridge, and
  *  a teardown that disposes both. */
@@ -70,6 +73,14 @@ export interface OfficeServeHandle {
  * Extracted from {@link runServe} so the start/teardown wiring is unit-testable.
  */
 export async function startOfficeServe(deps: OfficeServeDeps = defaultServeDeps): Promise<OfficeServeHandle> {
+	// Step down a stale serve squatting :8444 (e.g. left over from before a
+	// `brew upgrade`) so this start binds cleanly instead of "port 8444 in use".
+	const superseded = await deps.supersedeStaleServe(OFFICE_PANE_PORT);
+	if (superseded.superseded) {
+		console.log(
+			`Superseded a previous office serve (PID ${superseded.pid}) that was holding port ${OFFICE_PANE_PORT}.`,
+		);
+	}
 	const server = await deps.startOfficePaneServer();
 	let chat: HeadlessChatBridge | null = null;
 	try {
@@ -170,5 +181,8 @@ export async function runOfficeCommand(args: OfficeCommandArgs): Promise<void> {
 		case "sideload":
 			await runSideload(args.app ?? "excel");
 			return;
+		case "recycle":
+			console.log(await recycleOfficeServe());
+			return;
 	}
 }

package/src/commands/office.ts

@@ -9,7 +9,7 @@ export default class Office extends Command {
 
 	static args = {
 		action: Args.string({
-			description: "serve | manifest | sideload",
+			description: "serve | manifest | sideload | recycle",
 			required: false,
 			options: OFFICE_ACTIONS,
 		}),
@@ -31,6 +31,7 @@ export default class Office extends Command {
 			console.log("  serve     Start the https://127-0-0-1.local-ip.sh:8444 task-pane listener");
 			console.log("  manifest  Print (or -o write) the add-in manifest.json");
 			console.log("  sideload  Sideload the add-in into a desktop Office app");
+			console.log("  recycle   Stop a running serve (so the next `serve` starts clean after an upgrade)");
 			return;
 		}
 		await runOfficeCommand({

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.83.0",
-	"commit": "a0d8a930a0b6f8bba3730223529fbd078cc06ee9",
-	"shortCommit": "a0d8a93",
+	"version": "19.85.0",
+	"commit": "6e7e1972db24c3151be8dceff0e37d424d674edd",
+	"shortCommit": "6e7e197",
 	"branch": "main",
-	"tag": "v19.83.0",
-	"commitDate": "2026-07-23T13:56:27Z",
-	"buildDate": "2026-07-23T14:21:15.547Z",
+	"tag": "v19.85.0",
+	"commitDate": "2026-07-23T16:36:07Z",
+	"buildDate": "2026-07-23T16:59:32.962Z",
 	"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/a0d8a930a0b6f8bba3730223529fbd078cc06ee9",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.83.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/6e7e1972db24c3151be8dceff0e37d424d674edd",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.85.0"
 };

package/src/sdk.ts

@@ -112,6 +112,7 @@ import { SessionManager } from "./session/session-manager";
 import { closeAllConnections } from "./ssh/connection-manager";
 import { unmountAll } from "./ssh/sshfs-mount";
 import {
+	buildAgentsMdSearch,
 	buildSystemPrompt as buildSystemPromptInternal,
 	buildSystemPromptToolMetadata,
 	loadProjectContextFiles as loadContextFilesInternal,
@@ -965,6 +966,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		async () => options.contextFiles ?? (await discoverContextFiles(cwd, agentDir)),
 	);
 
+	// Walk the CWD for nested XCSH.md ONCE per session — the walk is bounded but not
+	// free, so hoisting it here keeps every tool-refresh prompt rebuild off the tree
+	// (a large cwd like $HOME must never re-stall on set_host_tools). #2245.
+	const agentsMdSearch = await logger.time("buildAgentsMdSearch", buildAgentsMdSearch, cwd);
+
 	let agent: Agent;
 	let session!: AgentSession;
 	let hasSession = false;
@@ -1596,6 +1602,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				cwd,
 				skills,
 				contextFiles,
+				agentsMdSearch,
 				tools: promptTools,
 				toolNames,
 				rules: rulebookRules,
@@ -1626,6 +1633,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					cwd,
 					skills,
 					contextFiles,
+					agentsMdSearch,
 					tools: promptTools,
 					toolNames,
 					rules: rulebookRules,

package/src/system-prompt.ts

@@ -108,15 +108,30 @@ const AGENTS_MD_MIN_DEPTH = 1;
 const AGENTS_MD_MAX_DEPTH = 4;
 const AGENTS_MD_LIMIT = 200;
 const SYSTEM_PROMPT_PREP_TIMEOUT_MS = 5000;
+// The walk's `limit` caps DISCOVERED files, not directories VISITED — so a dir
+// with ~no XCSH.md (e.g. serving from $HOME) would otherwise traverse the entire
+// tree to AGENTS_MD_MAX_DEPTH and stall prep. These bound the traversal itself:
+// a directory-visit budget AND a wall-clock deadline, both well inside the 5s
+// prep timeout, so discovery stays fast regardless of how few matches exist.
+const AGENTS_MD_MAX_DIRS = 4000;
+const AGENTS_MD_WALK_BUDGET_MS = 1500;
 const AGENTS_MD_EXCLUDED_DIRS = new Set(["node_modules", ".git"]);
 
-interface AgentsMdSearch {
+/** A cited context-file search result (the nested XCSH.md files under the cwd). */
+export interface AgentsMdSearch {
 	scopePath: string;
 	limit: number;
 	pattern: string;
 	files: string[];
 }
 
+/** Mutable traversal budget shared across the recursive walk. */
+interface WalkBudget {
+	readonly maxDirs: number;
+	readonly deadline: number;
+	dirsVisited: number;
+}
+
 function normalizePath(value: string): string {
 	return value.replace(/\\/g, "/");
 }
@@ -131,11 +146,24 @@ async function collectAgentsMdFiles(
 	dir: string,
 	depth: number,
 	limit: number,
+	maxDepth: number,
 	discovered: Set<string>,
+	budget: WalkBudget,
 ): Promise<void> {
-	if (depth > AGENTS_MD_MAX_DEPTH || discovered.size >= limit) {
+	// 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.
+	if (
+		depth > maxDepth ||
+		discovered.size >= limit ||
+		budget.dirsVisited >= budget.maxDirs ||
+		Date.now() >= budget.deadline
+	) {
 		return;
 	}
+	// Reserve this directory's slot SYNCHRONOUSLY (before the readdir await) so a
+	// concurrent Promise.all fan-out can't blow past the budget: every scheduled
+	// sibling sees the updated count before it yields, making the cap effectively hard.
+	budget.dirsVisited++;
 
 	let entries: fs.Dirent[];
 	try {
@@ -157,7 +185,7 @@ async function collectAgentsMdFiles(
 		}
 	}
 
-	if (depth === AGENTS_MD_MAX_DEPTH) {
+	if (depth === maxDepth) {
 		return;
 	}
 
@@ -168,24 +196,47 @@ async function collectAgentsMdFiles(
 
 	await Promise.all(
 		childDirs.map(async child => {
-			if (discovered.size >= limit) return;
-			await collectAgentsMdFiles(root, path.join(dir, child), depth + 1, limit, discovered);
+			if (discovered.size >= limit || budget.dirsVisited >= budget.maxDirs || Date.now() >= budget.deadline) return;
+			await collectAgentsMdFiles(root, path.join(dir, child), depth + 1, limit, maxDepth, discovered, budget);
 		}),
 	);
 }
 
-async function listAgentsMdFiles(root: string, limit: number): Promise<string[]> {
+/** Options for {@link discoverAgentsMdFiles} (all bounded by defaults). */
+export interface DiscoverAgentsMdOptions {
+	limit?: number;
+	maxDepth?: number;
+	maxDirs?: number;
+	budgetMs?: number;
+}
+
+/**
+ * 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.
+ */
+export async function discoverAgentsMdFiles(
+	root: string,
+	opts: DiscoverAgentsMdOptions = {},
+): Promise<{ files: string[]; dirsVisited: number }> {
+	const limit = opts.limit ?? AGENTS_MD_LIMIT;
+	const maxDepth = opts.maxDepth ?? AGENTS_MD_MAX_DEPTH;
+	const budget: WalkBudget = {
+		maxDirs: opts.maxDirs ?? AGENTS_MD_MAX_DIRS,
+		deadline: Date.now() + (opts.budgetMs ?? AGENTS_MD_WALK_BUDGET_MS),
+		dirsVisited: 0,
+	};
 	try {
 		const discovered = new Set<string>();
-		await collectAgentsMdFiles(root, root, 0, limit, discovered);
-		return Array.from(discovered).sort().slice(0, limit);
+		await collectAgentsMdFiles(root, root, 0, limit, maxDepth, discovered, budget);
+		return { files: Array.from(discovered).sort().slice(0, limit), dirsVisited: budget.dirsVisited };
 	} catch {
-		return [];
+		return { files: [], dirsVisited: budget.dirsVisited };
 	}
 }
 
-async function buildAgentsMdSearch(cwd: string): Promise<AgentsMdSearch> {
-	const files = await listAgentsMdFiles(cwd, AGENTS_MD_LIMIT);
+export async function buildAgentsMdSearch(cwd: string): Promise<AgentsMdSearch> {
+	const { files } = await discoverAgentsMdFiles(cwd);
 	return {
 		scopePath: ".",
 		limit: AGENTS_MD_LIMIT,
@@ -449,6 +500,9 @@ export interface BuildSystemPromptOptions {
 	cwd?: string;
 	/** Pre-loaded context files (skips discovery if provided). */
 	contextFiles?: Array<{ path: string; content: string; depth?: number }>;
+	/** Pre-computed nested-XCSH.md search (skips the CWD walk if provided). Hoisted
+	 *  once per session so tool-refresh rebuilds never re-walk the tree. */
+	agentsMdSearch?: AgentsMdSearch;
 	/**
 	 * Explicit disabled extension IDs applied to context-file discovery instead of the
 	 * global settings default. Pass `[]` to discover independent of process-wide settings.
@@ -519,6 +573,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		toolNames: providedToolNames,
 		cwd,
 		contextFiles: providedContextFiles,
+		agentsMdSearch: providedAgentsMdSearch,
 		skills: providedSkills,
 		rules,
 		alwaysApplyRules,
@@ -541,7 +596,9 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 					cwd: resolvedCwd,
 					disabledExtensions: options.disabledExtensions,
 				});
-		const agentsMdSearchPromise = logger.time("buildAgentsMdSearch", buildAgentsMdSearch, resolvedCwd);
+		const agentsMdSearchPromise = providedAgentsMdSearch
+			? Promise.resolve(providedAgentsMdSearch)
+			: logger.time("buildAgentsMdSearch", buildAgentsMdSearch, resolvedCwd);
 		const mergedSkillsSettings = {
 			...skillsSettings,
 			customDirectories: [...(skillsSettings?.customDirectories ?? []), ...(options.contextSkillDirs ?? [])],