@f5-sales-demo/xcsh 19.51.2

package/src/modes/types.ts

@@ -0,0 +1,273 @@
+import type { AgentMessage } from "@f5xc-salesdemos/pi-agent-core";
+import type { AssistantMessage, ImageContent, Message, UsageReport } from "@f5xc-salesdemos/pi-ai";
+import type { Component, Container, Loader, Spacer, Text, TUI } from "@f5xc-salesdemos/pi-tui";
+import type { KeybindingsManager } from "../config/keybindings";
+import type { Settings } from "../config/settings";
+import type {
+	ExtensionUIContext,
+	ExtensionUIDialogOptions,
+	ExtensionWidgetContent,
+	ExtensionWidgetOptions,
+} from "../extensibility/extensions";
+import type { CompactOptions } from "../extensibility/extensions/types";
+import type { MCPManager } from "../mcp";
+import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import type { HistoryStorage } from "../session/history-storage";
+import type { SessionContext, SessionManager } from "../session/session-manager";
+import type { ExitPlanModeDetails, LspStartupServerInfo } from "../tools";
+import type { AssistantMessageComponent } from "./components/assistant-message";
+import type { BashExecutionComponent } from "./components/bash-execution";
+import type { CustomEditor } from "./components/custom-editor";
+import type { GutterBlock } from "./components/gutter-block";
+import type { HookEditorComponent } from "./components/hook-editor";
+import type { HookInputComponent } from "./components/hook-input";
+import type { HookSelectorComponent } from "./components/hook-selector";
+import type { PythonExecutionComponent } from "./components/python-execution";
+import type { StatusLineComponent } from "./components/status-line";
+import type { ToolExecutionHandle } from "./components/tool-execution";
+import type { OAuthManualInputManager } from "./oauth-manual-input";
+import type { Theme } from "./theme/theme";
+
+export type CompactionQueuedMessage = {
+	text: string;
+	mode: "steer" | "followUp";
+};
+
+export type SubmittedUserInput = {
+	text: string;
+	images?: ImageContent[];
+	cancelled: boolean;
+	started: boolean;
+};
+
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+
+export type TodoItem = {
+	id: string;
+	content: string;
+	status: TodoStatus;
+	details?: string;
+};
+
+export type TodoPhase = {
+	id: string;
+	name: string;
+	tasks: TodoItem[];
+};
+
+export interface InteractiveModeContext {
+	// UI access
+	ui: TUI;
+	chatContainer: Container;
+	pendingMessagesContainer: Container;
+	statusContainer: Container;
+	todoContainer: Container;
+	btwContainer: Container;
+	editor: CustomEditor;
+	editorContainer: Container;
+	hookWidgetContainerAbove: Container;
+	hookWidgetContainerBelow: Container;
+	statusLine: StatusLineComponent;
+
+	// Session access
+	session: AgentSession;
+	sessionManager: SessionManager;
+	settings: Settings;
+	keybindings: KeybindingsManager;
+	agent: AgentSession["agent"];
+	historyStorage?: HistoryStorage;
+	mcpManager?: MCPManager;
+	lspServers?: LspStartupServerInfo[];
+
+	// State
+	isInitialized: boolean;
+	isBackgrounded: boolean;
+	isBashMode: boolean;
+	toolOutputExpanded: boolean;
+	todoExpanded: boolean;
+	planModeEnabled: boolean;
+	planModePlanFilePath?: string;
+	hideThinkingBlock: boolean;
+	pendingImages: ImageContent[];
+	compactionQueuedMessages: CompactionQueuedMessage[];
+	pendingTools: Map<string, ToolExecutionHandle>;
+	pendingBashComponents: BashExecutionComponent[];
+	bashComponent: BashExecutionComponent | undefined;
+	pendingPythonComponents: PythonExecutionComponent[];
+	pythonComponent: PythonExecutionComponent | undefined;
+	isPythonMode: boolean;
+	streamingComponent: AssistantMessageComponent | undefined;
+	streamingAssistantGutter: GutterBlock<AssistantMessageComponent> | undefined;
+	streamingMessage: AssistantMessage | undefined;
+	loadingAnimation: Loader | undefined;
+	autoCompactionLoader: Loader | undefined;
+	retryLoader: Loader | undefined;
+	autoCompactionEscapeHandler?: () => void;
+	retryEscapeHandler?: () => void;
+	unsubscribe?: () => void;
+	onInputCallback?: (input: SubmittedUserInput) => void;
+	optimisticUserMessageSignature: string | undefined;
+	lastSigintTime: number;
+	lastEscapeTime: number;
+	shutdownRequested: boolean;
+	hookSelector: HookSelectorComponent | undefined;
+	hookInput: HookInputComponent | undefined;
+	hookEditor: HookEditorComponent | undefined;
+	lastStatusSpacer: Spacer | undefined;
+	lastStatusText: Text | undefined;
+	fileSlashCommands: Set<string>;
+	skillCommands: Map<string, string>;
+	oauthManualInput: OAuthManualInputManager;
+	todoPhases: TodoPhase[];
+
+	// Lifecycle
+	init(): Promise<void>;
+	shutdown(): Promise<void>;
+	checkShutdownRequested(): Promise<void>;
+
+	// Extension UI integration
+	setToolUIContext(uiContext: ExtensionUIContext, hasUI: boolean): void;
+	initializeHookRunner(uiContext: ExtensionUIContext, hasUI: boolean): void;
+	createBackgroundUiContext(): ExtensionUIContext;
+
+	// Event handling
+	handleBackgroundEvent(event: AgentSessionEvent): Promise<void>;
+
+	// UI helpers
+	showStatus(message: string, options?: { dim?: boolean }): void;
+	showError(message: string): void;
+	showWarning(message: string): void;
+	clearEditor(): void;
+	updatePendingMessagesDisplay(): void;
+	queueCompactionMessage(text: string, mode: "steer" | "followUp"): void;
+	flushCompactionQueue(options?: { willRetry?: boolean }): Promise<void>;
+	flushPendingBashComponents(): void;
+	flushPendingModelSwitch(): Promise<void>;
+	setWorkingMessage(message?: string): void;
+	applyPendingWorkingMessage(): void;
+	ensureLoadingAnimation(): void;
+	startPendingSubmission(input: { text: string; images?: ImageContent[] }): SubmittedUserInput;
+	cancelPendingSubmission(): boolean;
+	markPendingSubmissionStarted(input: SubmittedUserInput): boolean;
+	finishPendingSubmission(input: SubmittedUserInput): void;
+	isKnownSlashCommand(text: string): boolean;
+	addMessageToChat(message: AgentMessage, options?: { populateHistory?: boolean }): void;
+	renderSessionContext(
+		sessionContext: SessionContext,
+		options?: { updateFooter?: boolean; populateHistory?: boolean },
+	): void;
+	renderInitialMessages(): void;
+	getUserMessageText(message: Message): string;
+	findLastAssistantMessage(): AssistantMessage | undefined;
+	extractAssistantText(message: AssistantMessage): string;
+	updateEditorTopBorder(): void;
+	updateEditorBorderColor(): void;
+	rebuildChatFromMessages(): void;
+	setTodos(todos: TodoItem[] | TodoPhase[]): void;
+	reloadTodos(): Promise<void>;
+	toggleTodoExpansion(): void;
+
+	// Command handling
+	handleExportCommand(text: string): Promise<void>;
+	handleShareCommand(): Promise<void>;
+	handleCopyCommand(sub?: string): void;
+	handleSessionCommand(): Promise<void>;
+	handleJobsCommand(): Promise<void>;
+	handleUsageCommand(reports?: UsageReport[] | null): Promise<void>;
+	handleChangelogCommand(showFull?: boolean): Promise<void>;
+	handleHotkeysCommand(): void;
+	handleToolsCommand(): void;
+	handleDumpCommand(): void;
+	handleDebugTranscriptCommand(): Promise<void>;
+	handleClearCommand(): Promise<void>;
+	handleForkCommand(): Promise<void>;
+	handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
+	handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
+	handleMCPCommand(text: string): Promise<void>;
+	handleSSHCommand(text: string): Promise<void>;
+	handleCompactCommand(customInstructions?: string): Promise<void>;
+	handleHandoffCommand(customInstructions?: string): Promise<void>;
+	handleMoveCommand(targetPath: string): Promise<void>;
+	handleRenameCommand(title: string): Promise<void>;
+	handleMemoryCommand(text: string): Promise<void>;
+	handleSTTToggle(): Promise<void>;
+	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void>;
+	openInBrowser(urlOrPath: string): void;
+	refreshSlashCommandState(cwd?: string): Promise<void>;
+
+	// Selector handling
+	showSettingsSelector(): void;
+	showHistorySearch(): void;
+	showExtensionsDashboard(): void;
+	showAgentsDashboard(): void;
+	showModelSelector(options?: { temporaryOnly?: boolean }): void;
+	showPluginSelector(mode?: "install" | "uninstall"): void;
+	showPluginDashboard(): void;
+	showUserMessageSelector(): void;
+	showTreeSelector(): void;
+	showSessionSelector(): void;
+	handleResumeSession(sessionPath: string): Promise<void>;
+	handleSessionDeleteCommand(): Promise<void>;
+	showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
+	showHookConfirm(title: string, message: string): Promise<boolean>;
+	showDebugSelector(): void;
+	showSessionObserver(): void;
+	resetObserverRegistry(): void;
+	refreshWelcomeAfterLogin(): Promise<void>;
+
+	// Input handling
+	handleCtrlC(): void;
+	handleCtrlD(): void;
+	handleCtrlZ(): void;
+	handleDequeue(): void;
+	handleBackgroundCommand(): void;
+	handleImagePaste(): Promise<boolean>;
+	handleBtwCommand(question: string): Promise<void>;
+	hasActiveBtw(): boolean;
+	handleBtwEscape(): boolean;
+	cycleThinkingLevel(): void;
+	cycleRoleModel(options?: { temporary?: boolean }): Promise<void>;
+	toggleToolOutputExpansion(): void;
+	setToolsExpanded(expanded: boolean): void;
+	toggleThinkingBlockVisibility(): void;
+	openExternalEditor(): void;
+	registerExtensionShortcuts(): void;
+	handlePlanModeCommand(initialPrompt?: string): Promise<void>;
+	handleExitPlanModeTool(details: ExitPlanModeDetails): Promise<void>;
+
+	// Hook UI methods
+	initHooksAndCustomTools(): Promise<void>;
+	emitCustomToolSessionEvent(
+		reason: "start" | "switch" | "branch" | "tree" | "shutdown",
+		previousSessionFile?: string,
+	): Promise<void>;
+	setHookWidget(key: string, content: ExtensionWidgetContent, options?: ExtensionWidgetOptions): void;
+	setHookStatus(key: string, text: string | undefined): void;
+	showHookSelector(
+		title: string,
+		options: string[],
+		dialogOptions?: ExtensionUIDialogOptions,
+	): Promise<string | undefined>;
+	hideHookSelector(): void;
+	showHookInput(title: string, placeholder?: string): Promise<string | undefined>;
+	hideHookInput(): void;
+	showHookEditor(
+		title: string,
+		prefill?: string,
+		dialogOptions?: ExtensionUIDialogOptions,
+		editorOptions?: { promptStyle?: boolean },
+	): Promise<string | undefined>;
+	hideHookEditor(): void;
+	showHookNotify(message: string, type?: "info" | "warning" | "error"): void;
+	showHookCustom<T>(
+		factory: (
+			tui: TUI,
+			theme: Theme,
+			keybindings: KeybindingsManager,
+			done: (result: T) => void,
+		) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,
+		options?: { overlay?: boolean },
+	): Promise<T>;
+	showExtensionError(extensionPath: string, error: string): void;
+	showToolError(toolName: string, error: string): void;
+}

package/src/modes/utils/hotkeys-markdown.ts

@@ -0,0 +1,60 @@
+import { t } from "@f5xc-salesdemos/pi-utils";
+import type { AppKeybinding, KeybindingsManager } from "../../config/keybindings";
+
+export interface HotkeysMarkdownBindings {
+	keybindings: Pick<KeybindingsManager, "getDisplayString">;
+}
+
+function appKey(bindings: HotkeysMarkdownBindings, action: AppKeybinding): string {
+	return bindings.keybindings.getDisplayString(action) || "Disabled";
+}
+
+export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string {
+	return [
+		`**${t("hotkeys.navigation.title")}**`,
+		"| Key | Action |",
+		"|-----|--------|",
+		`| \`Arrow keys\` | ${t("hotkeys.navigation.moveCursor")} |`,
+		`| \`Option+Left/Right\` | ${t("hotkeys.navigation.moveByWord")} |`,
+		`| \`Ctrl+A\` / \`Home\` / \`Cmd+Left\` | ${t("hotkeys.navigation.startOfLine")} |`,
+		`| \`Ctrl+E\` / \`End\` / \`Cmd+Right\` | ${t("hotkeys.navigation.endOfLine")} |`,
+		"",
+		`**${t("hotkeys.editing.title")}**`,
+		"| Key | Action |",
+		"|-----|--------|",
+		`| \`Enter\` | ${t("hotkeys.editing.sendMessage")} |`,
+		`| \`Shift+Enter\` / \`Alt+Enter\` | ${t("hotkeys.editing.newLine")} |`,
+		`| \`Ctrl+W\` / \`Option+Backspace\` | ${t("hotkeys.editing.deleteWordBackwards")} |`,
+		`| \`Ctrl+U\` | ${t("hotkeys.editing.deleteToStart")} |`,
+		`| \`Ctrl+K\` | ${t("hotkeys.editing.deleteToEnd")} |`,
+		`| \`${appKey(bindings, "app.clipboard.copyLine")}\` | ${t("hotkeys.editing.copyLine")} |`,
+		`| \`${appKey(bindings, "app.clipboard.copyPrompt")}\` | ${t("hotkeys.editing.copyPrompt")} |`,
+		"",
+		`**${t("hotkeys.other.title")}**`,
+		"| Key | Action |",
+		"|-----|--------|",
+		`| \`Tab\` | ${t("hotkeys.other.pathCompletion")} |`,
+		`| \`${appKey(bindings, "app.interrupt")}\` | ${t("hotkeys.other.cancelInterrupt")} |`,
+		`| \`${appKey(bindings, "app.clear")}\` | ${t("hotkeys.other.clearExit")} |`,
+		`| \`${appKey(bindings, "app.exit")}\` | ${t("hotkeys.other.exit")} |`,
+		`| \`${appKey(bindings, "app.suspend")}\` | ${t("hotkeys.other.suspend")} |`,
+		`| \`${appKey(bindings, "app.thinking.cycle")}\` | ${t("hotkeys.other.cycleThinking")} |`,
+		`| \`${appKey(bindings, "app.model.cycleForward")}\` | ${t("hotkeys.other.cycleModelsForward")} |`,
+		`| \`${appKey(bindings, "app.model.cycleBackward")}\` | ${t("hotkeys.other.cycleModelsBackward")} |`,
+		`| \`${appKey(bindings, "app.model.selectTemporary")}\` | ${t("hotkeys.other.selectModelTemp")} |`,
+		`| \`${appKey(bindings, "app.model.select")}\` | ${t("hotkeys.other.selectModel")} |`,
+		`| \`${appKey(bindings, "app.plan.toggle")}\` | ${t("hotkeys.other.togglePlan")} |`,
+		`| \`${appKey(bindings, "app.history.search")}\` | ${t("hotkeys.other.searchHistory")} |`,
+		`| \`${appKey(bindings, "app.tools.expand")}\` | ${t("hotkeys.other.toggleToolExpand")} |`,
+		`| \`${appKey(bindings, "app.thinking.toggle")}\` | ${t("hotkeys.other.toggleThinking")} |`,
+		`| \`${appKey(bindings, "app.editor.external")}\` | ${t("hotkeys.other.externalEditor")} |`,
+		`| \`${appKey(bindings, "app.clipboard.pasteImage")}\` | ${t("hotkeys.other.pasteImage")} |`,
+		`| \`${appKey(bindings, "app.stt.toggle")}\` | ${t("hotkeys.other.toggleStt")} |`,
+		`| \`#\` | ${t("hotkeys.other.promptActions")} |`,
+		`| \`/\` | ${t("hotkeys.other.slashCommands")} |`,
+		`| \`!\` | ${t("hotkeys.other.runBash")} |`,
+		`| \`!!\` | ${t("hotkeys.other.runBashExcluded")} |`,
+		`| \`$\` | ${t("hotkeys.other.runPython")} |`,
+		`| \`$$\` | ${t("hotkeys.other.runPythonExcluded")} |`,
+	].join("\n");
+}

package/src/modes/utils/keybinding-matchers.ts

@@ -0,0 +1,30 @@
+import { getKeybindings, matchesKey } from "@f5xc-salesdemos/pi-tui";
+
+/**
+ * Match the coding-agent interrupt key.
+ *
+ * Interactive mode installs a keybinding manager that exposes `app.interrupt`
+ * globally, but some isolated component tests still run with only TUI
+ * keybindings registered. In that case, fall back to raw Escape matching.
+ */
+export function matchesAppInterrupt(data: string): boolean {
+	const keybindings = getKeybindings();
+	const interruptKeys = keybindings.getKeys("app.interrupt");
+	if (interruptKeys.length > 0) {
+		return keybindings.matches(data, "app.interrupt");
+	}
+	return matchesKey(data, "escape") || matchesKey(data, "esc");
+}
+
+export function matchesSelectCancel(data: string): boolean {
+	return getKeybindings().matches(data, "tui.select.cancel");
+}
+
+export function matchesAppExternalEditor(data: string): boolean {
+	const keybindings = getKeybindings();
+	const externalEditorKeys = keybindings.getKeys("app.editor.external");
+	if (externalEditorKeys.length > 0) {
+		return keybindings.matches(data, "app.editor.external");
+	}
+	return matchesKey(data, "ctrl+g");
+}

package/src/modes/utils/read-group-outcome-aggregator.ts

@@ -0,0 +1,55 @@
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import type { GutterBlock } from "../components/gutter-block";
+
+type Outcome = "success" | "error";
+
+/**
+ * Aggregates per-read outcomes across a shared read-group gutter so the
+ * final rendered dot reflects the worst-case outcome of the group.
+ *
+ * Called by two paths:
+ *   • live event-controller — reads arrive one at a time during streaming;
+ *     the gutter's spinner must stay active until the last read in the
+ *     group completes, so finalize is called only when `stillActive` is
+ *     false.
+ *   • replay ui-helpers — transcript rebuild walks completed tool results
+ *     in order; finalize is called at each group boundary.
+ *
+ * Semantics:
+ *   • `record` merges an incoming outcome into the running worst-case for
+ *     the gutter. "error" beats "success" regardless of ordering.
+ *   • `finalize` flushes the aggregated outcome to `gutter.setDone()`,
+ *     clears the entry, and returns. Calling `finalize` on a gutter that
+ *     was never `record`ed calls `setDone()` with no argument so the
+ *     gutter renders in its neutral done state.
+ *   • `peek` is read-only — useful for assertions and instrumentation.
+ */
+// Gutter generic parameter is not relevant to aggregation; constrain to
+// `Component` (the superclass required by GutterBlock) so callers with
+// concrete child types still flow in cleanly.
+type AnyGutter = GutterBlock<Component>;
+
+export class ReadGroupOutcomeAggregator {
+	#outcomes = new WeakMap<AnyGutter, Outcome>();
+
+	record(gutter: AnyGutter, outcome: Outcome): void {
+		const current = this.#outcomes.get(gutter);
+		// "error" is strictly worse than "success" — once any read in the
+		// group fails, the whole group is marked failed.
+		if (current === "error") return;
+		this.#outcomes.set(gutter, outcome);
+	}
+
+	peek(gutter: AnyGutter): Outcome | undefined {
+		return this.#outcomes.get(gutter);
+	}
+
+	finalize(gutter: AnyGutter): void {
+		const outcome = this.#outcomes.get(gutter);
+		this.#outcomes.delete(gutter);
+		gutter.setDone(outcome);
+	}
+}
+
+// Re-export for callers that need the generic gutter type alias.
+export type { AnyGutter as ReadGroupGutter, Outcome as ReadGroupOutcome };

package/src/modes/utils/sanitize-error-message.ts

@@ -0,0 +1,60 @@
+import { Ellipsis, truncateToWidth } from "@f5xc-salesdemos/pi-tui";
+
+/**
+ * Single-line-safe sanitizer for error messages rendered inside TUI status
+ * footers (e.g. `(error: <message>)`). Protects the layout from payloads that
+ * contain ANSI escape sequences, embedded newlines, tabs, other control
+ * characters, wide glyphs (CJK / emoji), or are simply too long to fit on
+ * one terminal row.
+ *
+ * Contract (applied in order):
+ *   1. Full ANSI escape sequences (CSI like `\x1b[31m`, OSC like
+ *      `\x1b]8;;...\x1b\\`, and single-byte ESC introducers) are removed
+ *      WHOLE — not just the lone ESC byte — so no `[31mboom[0m` garbage
+ *      survives.
+ *   2. Embedded newlines and tabs are collapsed to a single space.
+ *   3. Any remaining ASCII control characters (\x00–\x1F and \x7F) are
+ *      stripped.
+ *   4. Runs of whitespace are collapsed to a single space; leading/trailing
+ *      whitespace is trimmed.
+ *   5. Output is truncated to {@link MAX_ERROR_MESSAGE_WIDTH} **terminal
+ *      cells** (not UTF-16 code units) via `truncateToWidth` from pi-tui;
+ *      wide glyphs therefore count as 2 cells each. Truncation is marked
+ *      with a single horizontal ellipsis (`…`). The limit is chosen so
+ *      that `(error: <msg>)` (9-cell wrapper) fits on a single row of an
+ *      80-column terminal.
+ */
+
+// Sanitized-message budget for the `(error: <msg>)` footer.
+//
+// The footer is rendered inside GutterBlock (2-cell prefix) + the bash/
+// python execution box (which reserves a 1-cell Text indent on each side
+// plus a further gap on the right before wrapping occurs in practice).
+// Arithmetic gives ~68 cells on an 80-column terminal, but empirical
+// rendering with `createToolGutter(new BashExecutionComponent(...)).render(80)`
+// still wraps the trailing `)` onto the next row at that ceiling.
+// Pin the budget well inside the algebraic limit so the guarantee holds
+// under the real layered layout.
+//
+// Net budget for the message: 60 cells → full footer ≤ ~73 cells →
+// safe on any terminal ≥ 80 columns even after the gutter + box overhead.
+export const MAX_ERROR_MESSAGE_WIDTH = 60;
+
+// Matches CSI (Control Sequence Introducer) / SGR sequences: \x1b[ … final byte.
+const ANSI_CSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+// Matches OSC (Operating System Command) sequences: \x1b] … terminator (BEL or ESC\).
+const ANSI_OSC_RE = /\x1b\][\s\S]*?(?:\x07|\x1b\\)/g;
+// Fallback for any stray single-byte ESC sequences (e.g. "\x1bM" reverse index).
+const ANSI_ESC_RE = /\x1b[@-_]?/g;
+
+export function sanitizeErrorMessage(raw: string): string {
+	const withoutAnsi = raw.replace(ANSI_OSC_RE, "").replace(ANSI_CSI_RE, "").replace(ANSI_ESC_RE, "");
+	// Collapse whitespace-like control chars (tab, newline, CR, form feed)
+	// to a single space, then strip every remaining control character.
+	const flattened = withoutAnsi.replace(/[\t\n\r\f\v]+/g, " ").replace(/[\x00-\x1F\x7F]/g, "");
+	const collapsed = flattened.replace(/\s+/g, " ").trim();
+	// truncateToWidth measures in terminal cells (wide glyphs count as 2)
+	// and appends an ellipsis when it clips. Returns the input unchanged if
+	// already within budget.
+	return truncateToWidth(collapsed, MAX_ERROR_MESSAGE_WIDTH, Ellipsis.Unicode);
+}

package/src/modes/utils/tools-markdown.ts

@@ -0,0 +1,28 @@
+import { t } from "@f5xc-salesdemos/pi-utils";
+import type { Tool } from "../../tools";
+
+export interface ToolsMarkdownBindings {
+	tools: ReadonlyArray<Pick<Tool, "description" | "name">>;
+}
+
+function escapeTableCell(value: string): string {
+	return value
+		.replace(/\|/g, "\\|")
+		.replace(/\r?\n+/g, " ")
+		.trim();
+}
+
+export function buildToolsMarkdown(bindings: ToolsMarkdownBindings): string {
+	if (bindings.tools.length === 0) {
+		return t("tools.emptyState");
+	}
+
+	return [
+		`| ${t("tools.tableHeaderTool")} | ${t("tools.tableHeaderDescription")} |`,
+		"|------|-------------|",
+		...bindings.tools.map(tool => {
+			const description = escapeTableCell(tool.description) || t("tools.noDescription");
+			return `| \`${tool.name}\` | ${description} |`;
+		}),
+	].join("\n");
+}