@f5-sales-demo/xcsh 20.17.0 → 20.18.1

package/package.json

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

package/src/browser/chat-handler.ts

@@ -334,7 +334,7 @@ export class ChatHandler {
 			return;
 		}
 		if (event.type === "tool_execution_end" && "toolName" in event) {
-			if (event.toolName === "display_media" || event.toolName === "display_image") {
+			if (event.toolName === "display_media") {
 				const descriptor = extractMediaDescriptorFromToolResult(event.result);
 				if (descriptor) {
 					this.#server.send({

package/src/cli.ts

@@ -63,6 +63,7 @@ const commands: CommandEntry[] = [
 	{ name: "chrome", load: () => import("./commands/chrome").then(m => m.default) },
 	{ name: "chrome-host", load: () => import("./commands/native-host").then(m => m.default) },
 	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
+	{ name: "herdr", load: () => import("./commands/herdr").then(m => m.default) },
 	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
 	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
 	{

package/src/commands/herdr.ts

@@ -0,0 +1,122 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Args, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
+import type { HerdrBindingV1 } from "../herdr/controller";
+
+interface CommandResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+}
+
+async function execute(command: string[], inherit = false): Promise<CommandResult> {
+	const child = Bun.spawn({
+		cmd: command,
+		stdin: inherit ? "inherit" : "ignore",
+		stdout: inherit ? "inherit" : "pipe",
+		stderr: inherit ? "inherit" : "pipe",
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		inherit ? Promise.resolve("") : new Response(child.stdout).text(),
+		inherit ? Promise.resolve("") : new Response(child.stderr).text(),
+		child.exited,
+	]);
+	if (exitCode !== 0) throw new Error(stderr.trim() || `${command[0]} exited with ${exitCode}`);
+	return { stdout, stderr, exitCode };
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function buildXcshCommand(executable: string, args: string[]): string {
+	return [executable, ...args].map(shellQuote).join(" ");
+}
+
+export default class Herdr extends Command {
+	static description = "Launch xcsh in a conversation-owned Herdr workspace";
+	static strict = false;
+	static flags = {
+		session: Flags.string({ required: true, description: "Herdr named session" }),
+		label: Flags.string({ description: "Workspace label" }),
+	};
+	static args = {
+		xcshArgs: Args.string({ required: false, multiple: true, description: "Arguments passed to xcsh after --" }),
+	};
+
+	async run(): Promise<void> {
+		if (process.env.HERDR_ENV === "1") throw new Error("xcsh herdr must be launched outside an existing Herdr pane");
+		const { flags, args } = await this.parse(Herdr);
+		const session = flags.session;
+		if (!session) throw new Error("--session is required");
+		const ownerToken = randomUUID();
+		const stateRoot = process.env.XDG_STATE_HOME ?? path.join(os.homedir(), ".local", "state");
+		const bindingDir = path.join(stateRoot, "xcsh", "herdr");
+		await fs.mkdir(bindingDir, { recursive: true, mode: 0o700 });
+		const bindingPath = path.join(bindingDir, `${session}-${ownerToken}.json`);
+		const label = flags.label ?? `xcsh-${new Date().toISOString().replace(/[-:.]/g, "").slice(0, 15).toLowerCase()}`;
+		const created = await execute([
+			"herdr",
+			"--session",
+			session,
+			"workspace",
+			"create",
+			"--cwd",
+			process.cwd(),
+			"--label",
+			label,
+			"--env",
+			`XCSH_HERDR_OWNER=${ownerToken}`,
+			"--env",
+			`XCSH_HERDR_BINDING_PATH=${bindingPath}`,
+			"--focus",
+		]);
+		const response = JSON.parse(created.stdout) as {
+			result?: { workspace?: { workspace_id?: string }; root_pane?: { pane_id?: string } };
+		};
+		const workspaceId = response.result?.workspace?.workspace_id;
+		const rootPaneId = response.result?.root_pane?.pane_id;
+		if (!workspaceId || !rootPaneId) throw new Error("Herdr returned an invalid workspace creation response");
+		const binding: HerdrBindingV1 = {
+			version: 1,
+			sessionName: session,
+			workspaceId,
+			rootPaneId,
+			ownerToken,
+			terminals: [],
+		};
+		await fs.writeFile(bindingPath, `${JSON.stringify(binding, null, 2)}\n`, { mode: 0o600 });
+		await execute([
+			"herdr",
+			"--session",
+			session,
+			"workspace",
+			"report-metadata",
+			workspaceId,
+			"--source",
+			"xcsh:terminal",
+			"--token",
+			`xcsh_owner=${ownerToken}`,
+		]);
+		await execute([
+			"herdr",
+			"--session",
+			session,
+			"pane",
+			"report-metadata",
+			rootPaneId,
+			"--source",
+			"xcsh:terminal",
+			"--token",
+			`xcsh_owner=${ownerToken}`,
+		]);
+		const forwarded = Array.isArray(args.xcshArgs) ? args.xcshArgs : [];
+		const xcshCommand = buildXcshCommand(process.env.XCSH_BIN ?? "xcsh", forwarded);
+		await execute(["herdr", "--session", session, "pane", "run", rootPaneId, xcshCommand]);
+		await execute(["herdr", "session", "attach", session], true);
+	}
+}
+
+export { buildXcshCommand, shellQuote };

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

@@ -0,0 +1,135 @@
+import type { ExtensionAPI, ExtensionContext } from "@f5-sales-demo/xcsh";
+import { HerdrController } from "../../../herdr/controller";
+
+type Action = "list" | "create" | "run" | "send" | "read" | "wait" | "status" | "focus" | "close";
+interface TerminalParams {
+	action: Action;
+	target?: string;
+	name?: string;
+	cwd?: string;
+	command?: string;
+	text?: string;
+	match?: string;
+	lines?: number;
+	timeoutMs?: number;
+	enter?: boolean;
+	force?: boolean;
+}
+
+export function createRetryingLazy<T>(factory: () => Promise<T>): () => Promise<T> {
+	let pending: Promise<T> | undefined;
+	return () => {
+		pending ??= factory().catch(error => {
+			pending = undefined;
+			throw error;
+		});
+		return pending;
+	};
+}
+
+function sessionRef(ctx: ExtensionContext): string | undefined {
+	return ctx.sessionManager.getSessionFile?.() ?? ctx.sessionManager.getSessionId?.();
+}
+
+async function dispatch(controller: HerdrController, params: TerminalParams): Promise<unknown> {
+	switch (params.action) {
+		case "list":
+			return controller.list();
+		case "create":
+			return controller.create(params.name ?? "", params.cwd);
+		case "run":
+			await controller.run(params.target ?? "", params.command ?? "");
+			return { ok: true };
+		case "send":
+			await controller.send(params.target ?? "", params.text ?? "", params.enter);
+			return { ok: true };
+		case "read":
+			return controller.read(params.target ?? "", params.lines);
+		case "wait":
+			return controller.wait(params.target ?? "", params.match ?? "", params.timeoutMs);
+		case "status":
+			return controller.status(params.target ?? "");
+		case "focus":
+			await controller.focus(params.target ?? "");
+			return { ok: true };
+		case "close":
+			await controller.close(params.target ?? "", params.force);
+			return { ok: true };
+	}
+}
+
+export default function herdrTerminal(pi: ExtensionAPI): void {
+	const { Type } = pi.typebox;
+	const controller = createRetryingLazy(() => HerdrController.connect());
+
+	pi.registerTool({
+		name: "herdr_terminal",
+		label: "Herdr Terminal",
+		description:
+			"Manage support terminals owned by the current xcsh conversation. Actions: list, create, run, send, read, wait, status, focus, close. Focus and forced close must be explicit.",
+		parameters: Type.Object({
+			action: Type.Union(
+				["list", "create", "run", "send", "read", "wait", "status", "focus", "close"].map(value =>
+					Type.Literal(value),
+				),
+			),
+			target: Type.Optional(Type.String({ description: "Terminal name or owned pane ID" })),
+			name: Type.Optional(Type.String({ description: "Name for a newly created terminal" })),
+			cwd: Type.Optional(Type.String({ description: "Working directory for a newly created terminal" })),
+			command: Type.Optional(Type.String({ description: "Command for run" })),
+			text: Type.Optional(Type.String({ description: "Text for send" })),
+			match: Type.Optional(Type.String({ description: "Literal output awaited by wait" })),
+			lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 1000 })),
+			timeoutMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 300000 })),
+			enter: Type.Optional(Type.Boolean()),
+			force: Type.Optional(Type.Boolean({ description: "Required on the second close call for a busy pane" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const active = await controller();
+				await active.updateSessionRef(sessionRef(ctx));
+				const result = await dispatch(active, params as TerminalParams);
+				return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: message }], details: { error: message }, isError: true };
+			}
+		},
+	});
+
+	pi.registerCommand("terminal", {
+		description: "Manage Herdr terminals: /terminal <list|create|run|send|read|wait|status|focus|close>",
+		handler: async (args, ctx) => {
+			const [action = "list", target, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+			const params: TerminalParams = { action: action as Action, target };
+			if (action === "create") params.name = target;
+			if (action === "run") params.command = rest.join(" ");
+			if (action === "send") params.text = rest.join(" ");
+			if (action === "wait") params.match = rest.join(" ");
+			if (action === "read" && rest[0]) params.lines = Number(rest[0]);
+			if (action === "close") params.force = rest.includes("--force");
+			try {
+				const active = await controller();
+				await active.updateSessionRef(sessionRef(ctx));
+				ctx.ui.notify(JSON.stringify(await dispatch(active, params), null, 2), "info");
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
+	const update = async (_event: unknown, ctx: ExtensionContext): Promise<void> => {
+		if (!process.env.HERDR_SOCKET_PATH) return;
+		try {
+			await (await controller()).updateSessionRef(sessionRef(ctx));
+		} catch (error) {
+			pi.logger.debug("Herdr terminal binding update failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	};
+	pi.on("session_start", update);
+	pi.on("session_switch", update);
+	pi.on("session_branch", update);
+	pi.on("session_tree", update);
+}

package/src/extensibility/extensions/loader.ts

@@ -20,6 +20,7 @@ import { EventBus } from "../../utils/event-bus";
 import { getAllPluginExtensionPaths } from "../plugins/loader";
 import { resolvePath } from "../utils";
 import herdrReporter from "./bundled/herdr-reporter";
+import herdrTerminal from "./bundled/herdr-terminal";
 import sandboxGuard from "./bundled/sandbox-guard";
 import type {
 	Extension,
@@ -501,6 +502,7 @@ async function discoverExtensionsInDir(dir: string): Promise<string[]> {
 /** Extensions bundled with xcsh and loaded by default (before user extensions). */
 const BUNDLED_EXTENSIONS: ReadonlyArray<{ name: string; factory: ExtensionFactory }> = [
 	{ name: "herdr-reporter", factory: herdrReporter },
+	{ name: "herdr-terminal", factory: herdrTerminal },
 	{ name: "sandbox-guard", factory: sandboxGuard },
 ];
 

package/src/herdr/client.ts

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { connect } from "node:net";
+
+export const HERDR_PROTOCOL_VERSION = 18;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+export class HerdrProtocolError extends Error {
+	constructor(
+		message: string,
+		readonly code = "protocol_error",
+	) {
+		super(message);
+		this.name = "HerdrProtocolError";
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Typed, one-request-per-connection client for Herdr's protocol-18 JSONL socket. */
+export class HerdrClient {
+	private protocolChecked = false;
+
+	constructor(
+		readonly socketPath: string,
+		readonly timeoutMs = DEFAULT_TIMEOUT_MS,
+	) {
+		if (!socketPath) throw new HerdrProtocolError("HERDR_SOCKET_PATH is unavailable", "unavailable");
+	}
+
+	async ensureProtocol(): Promise<void> {
+		if (this.protocolChecked) return;
+		const pong = await this.requestRaw<{ type: string; protocol: number; version: string }>("ping", {});
+		if (pong.type !== "pong" || pong.protocol !== HERDR_PROTOCOL_VERSION) {
+			throw new HerdrProtocolError(
+				`Herdr protocol mismatch: expected ${HERDR_PROTOCOL_VERSION}, received ${String(pong.protocol)}`,
+				"protocol_mismatch",
+			);
+		}
+		this.protocolChecked = true;
+	}
+
+	async request<T extends Record<string, unknown>>(method: string, params: Record<string, unknown>): Promise<T> {
+		await this.ensureProtocol();
+		return this.requestRaw<T>(method, params);
+	}
+
+	private requestRaw<T>(method: string, params: Record<string, unknown>): Promise<T> {
+		const id = `xcsh:${randomUUID()}`;
+		return new Promise<T>((resolve, reject) => {
+			let buffer = "";
+			let settled = false;
+			const socket = connect({ path: this.socketPath });
+			const finish = (error?: unknown, value?: T): void => {
+				if (settled) return;
+				settled = true;
+				socket.destroy();
+				if (error !== undefined) reject(error);
+				else resolve(value as T);
+			};
+			socket.setEncoding("utf8");
+			socket.setTimeout(this.timeoutMs, () => finish(new HerdrProtocolError("Herdr request timed out", "timeout")));
+			socket.once("error", error => finish(new HerdrProtocolError(error.message, "transport_error")));
+			socket.once("connect", () => socket.write(`${JSON.stringify({ id, method, params })}\n`));
+			socket.on("data", chunk => {
+				buffer += chunk;
+				if (Buffer.byteLength(buffer) > MAX_RESPONSE_BYTES) {
+					finish(new HerdrProtocolError("Herdr response exceeded 4 MiB", "response_too_large"));
+					return;
+				}
+				for (;;) {
+					const newline = buffer.indexOf("\n");
+					if (newline < 0) break;
+					const line = buffer.slice(0, newline);
+					buffer = buffer.slice(newline + 1);
+					if (!line.trim()) continue;
+					let decoded: unknown;
+					try {
+						decoded = JSON.parse(line);
+					} catch {
+						finish(new HerdrProtocolError("Herdr returned invalid JSON", "invalid_json"));
+						return;
+					}
+					if (!isRecord(decoded) || decoded.id !== id) continue;
+					if (isRecord(decoded.error)) {
+						finish(
+							new HerdrProtocolError(
+								typeof decoded.error.message === "string" ? decoded.error.message : "Herdr request failed",
+								typeof decoded.error.code === "string" ? decoded.error.code : "remote_error",
+							),
+						);
+						return;
+					}
+					if (!("result" in decoded) || !isRecord(decoded.result)) {
+						finish(new HerdrProtocolError("Herdr response is missing a typed result"));
+						return;
+					}
+					finish(undefined, decoded.result as T);
+					return;
+				}
+			});
+			socket.once("end", () => {
+				if (settled) return;
+				// Protocol 18 permits the final response to be terminated by EOF. The
+				// server normally emits JSONL, but older/current transports may omit the
+				// trailing newline when they close a one-shot connection.
+				try {
+					const decoded = JSON.parse(buffer) as Record<string, unknown>;
+					if (decoded.id !== id) throw new Error("response id mismatch");
+					if (isRecord(decoded.error)) {
+						finish(
+							new HerdrProtocolError(
+								typeof decoded.error.message === "string" ? decoded.error.message : "Herdr request failed",
+								typeof decoded.error.code === "string" ? decoded.error.code : "remote_error",
+							),
+						);
+					} else if (isRecord(decoded.result)) finish(undefined, decoded.result as T);
+					else finish(new HerdrProtocolError("Herdr response is missing a typed result"));
+				} catch {
+					finish(new HerdrProtocolError("Herdr closed the socket before responding", "eof"));
+				}
+			});
+		});
+	}
+}