@nghyane/arcane 0.1.0

package/src/tools/bash-interactive.ts

@@ -0,0 +1,419 @@
+import type { AgentToolContext } from "@nghyane/arcane-agent";
+import { type PtyRunResult, PtySession, sanitizeText } from "@nghyane/arcane-natives";
+import {
+	type Component,
+	matchesKey,
+	padding,
+	parseKey,
+	parseKittySequence,
+	truncateToWidth,
+	visibleWidth,
+} from "@nghyane/arcane-tui";
+import type { Terminal as XtermTerminalType } from "@xterm/headless";
+import xterm from "@xterm/headless";
+import type { Theme } from "../modes/theme/theme";
+import { OutputSink, type OutputSummary } from "../session/streaming-output";
+import { getStateIcon } from "../tui";
+import { replaceTabs } from "./render-utils";
+
+export interface BashInteractiveResult extends OutputSummary {
+	exitCode: number | undefined;
+	cancelled: boolean;
+	timedOut: boolean;
+}
+
+function normalizeCaptureChunk(chunk: string): string {
+	const normalized = chunk.replace(/\r\n/gu, "\n").replace(/\r/gu, "\n");
+	return sanitizeText(normalized);
+}
+
+const XtermTerminal = xterm.Terminal;
+
+function normalizeInputForPty(data: string, applicationCursorKeysMode: boolean): string {
+	const kitty = parseKittySequence(data);
+	if (!kitty) {
+		return data;
+	}
+	if (kitty.eventType === 3) {
+		return "";
+	}
+	const keyId = parseKey(data);
+	if (!keyId) {
+		return data;
+	}
+	const normalizedKey = keyId.toLowerCase();
+	if (normalizedKey === "up") return applicationCursorKeysMode ? "\x1bOA" : "\x1b[A";
+	if (normalizedKey === "down") return applicationCursorKeysMode ? "\x1bOB" : "\x1b[B";
+	if (normalizedKey === "right") return applicationCursorKeysMode ? "\x1bOC" : "\x1b[C";
+	if (normalizedKey === "left") return applicationCursorKeysMode ? "\x1bOD" : "\x1b[D";
+	if (normalizedKey === "home") return applicationCursorKeysMode ? "\x1bOH" : "\x1b[H";
+	if (normalizedKey === "end") return applicationCursorKeysMode ? "\x1bOF" : "\x1b[F";
+	if (normalizedKey === "pageup") return "\x1b[5~";
+	if (normalizedKey === "pagedown") return "\x1b[6~";
+	if (normalizedKey === "insert") return "\x1b[2~";
+	if (normalizedKey === "delete") return "\x1b[3~";
+	if (normalizedKey === "shift+tab") return "\x1b[Z";
+	if (normalizedKey === "enter") return "\r";
+	if (normalizedKey === "tab") return "\t";
+	if (normalizedKey === "space") return " ";
+	if (normalizedKey === "backspace") return "\x7f";
+	if (normalizedKey === "escape") return "\x1b";
+	const ctrlMatch = /^ctrl\+([a-z])$/u.exec(normalizedKey);
+	if (ctrlMatch) {
+		const letter = ctrlMatch[1]!;
+		return String.fromCharCode(letter.charCodeAt(0) - 96);
+	}
+	const altMatch = /^alt\+([a-z])$/u.exec(normalizedKey);
+	if (altMatch) {
+		return `\x1b${altMatch[1]!}`;
+	}
+	// For any other Kitty sequence with a printable codepoint, emit the character directly
+	if (kitty.codepoint >= 32 && kitty.codepoint < 127) {
+		let ch = String.fromCharCode(kitty.codepoint);
+		// Apply ctrl modifier if present (modifier bit 4 = ctrl)
+		if (kitty.modifier & 4) {
+			const code = kitty.codepoint;
+			if (code >= 97 && code <= 122) {
+				ch = String.fromCharCode(code - 96);
+			}
+		}
+		// Apply alt modifier if present (modifier bit 2 = alt)
+		if (kitty.modifier & 2) {
+			ch = `\x1b${ch}`;
+		}
+		return ch;
+	}
+	return data;
+}
+class BashInteractiveOverlayComponent implements Component {
+	#terminal: XtermTerminalType;
+	#state: "running" | "complete" | "timed_out" | "killed" = "running";
+	#exitCode: number | undefined;
+	#onInput: (data: string) => void = () => {};
+	#onDismiss: () => void = () => {};
+	#onDispose: () => void = () => {};
+	#session: PtySession | null = null;
+	#lastCols = 0;
+	#lastRows = 0;
+	#writeQueue: string[] = [];
+	#writeOffset = 0;
+	#flushResolvers: Array<() => void> = [];
+	#writing = false;
+
+	constructor(
+		private readonly command: string,
+		private readonly uiTheme: Theme,
+		private readonly getTerminalRows: () => number,
+	) {
+		this.#terminal = new XtermTerminal({
+			cols: 120,
+			rows: 40,
+			disableStdin: true,
+			allowProposedApi: true,
+			scrollback: 10_000,
+		});
+	}
+
+	setHandlers(onInput: (data: string) => void, onDismiss: () => void, onDispose: () => void): void {
+		this.#onInput = onInput;
+		this.#onDismiss = onDismiss;
+		this.#onDispose = onDispose;
+	}
+
+	appendOutput(chunk: string): void {
+		this.#writeQueue.push(chunk);
+		this.#drainQueue();
+	}
+
+	#drainQueue(): void {
+		if (this.#writing) return;
+		if (this.#writeOffset >= this.#writeQueue.length) {
+			this.#resolveFlushWaiters();
+			return;
+		}
+		this.#writing = true;
+		const data = this.#writeQueue[this.#writeOffset]!;
+		this.#terminal.write(data, () => {
+			this.#writing = false;
+			this.#writeOffset += 1;
+			if (this.#writeOffset >= this.#writeQueue.length) {
+				this.#writeQueue = [];
+				this.#writeOffset = 0;
+				this.#resolveFlushWaiters();
+			}
+			this.#drainQueue();
+		});
+	}
+
+	#resolveFlushWaiters(): void {
+		if (this.#writing || this.#writeOffset < this.#writeQueue.length) return;
+		if (this.#flushResolvers.length === 0) return;
+		const resolvers = this.#flushResolvers;
+		this.#flushResolvers = [];
+		for (const resolve of resolvers) {
+			resolve();
+		}
+	}
+
+	flushOutput(): Promise<void> {
+		if (!this.#writing && this.#writeOffset >= this.#writeQueue.length) {
+			return Promise.resolve();
+		}
+		const { promise, resolve } = Promise.withResolvers<void>();
+		this.#flushResolvers.push(resolve);
+		return promise;
+	}
+
+	setSession(session: PtySession): void {
+		this.#session = session;
+	}
+
+	setComplete(result: { exitCode: number | undefined; cancelled: boolean; timedOut: boolean }): void {
+		this.#exitCode = result.exitCode;
+		if (result.timedOut) {
+			this.#state = "timed_out";
+			return;
+		}
+		if (result.cancelled) {
+			this.#state = "killed";
+			return;
+		}
+		this.#state = "complete";
+	}
+
+	handleInput(data: string): void {
+		if (this.#state === "running" && (matchesKey(data, "escape") || matchesKey(data, "esc"))) {
+			this.#onDismiss();
+			return;
+		}
+		if (this.#state !== "running") {
+			return;
+		}
+		const normalizedInput = normalizeInputForPty(data, this.#terminal.modes.applicationCursorKeysMode);
+		if (!normalizedInput) {
+			return;
+		}
+		this.#onInput(normalizedInput);
+	}
+	#stateText(): string {
+		if (this.#state === "running") return this.uiTheme.fg("warning", "running");
+		if (this.#state === "timed_out") return this.uiTheme.fg("warning", "timed out");
+		if (this.#state === "killed") return this.uiTheme.fg("warning", "killed");
+		if (this.#exitCode === 0) return this.uiTheme.fg("success", "exit 0");
+		if (this.#exitCode === undefined) return this.uiTheme.fg("warning", "exited");
+		return this.uiTheme.fg("error", `exit ${this.#exitCode}`);
+	}
+
+	#readViewport(innerWidth: number, maxContentRows: number): string[] {
+		this.#terminal.resize(innerWidth, maxContentRows);
+		const buffer = this.#terminal.buffer.active;
+		const viewportY = buffer.viewportY;
+		const visibleLines: string[] = [];
+		for (let i = 0; i < maxContentRows; i++) {
+			const line = buffer.getLine(viewportY + i)?.translateToString(true) ?? "";
+			visibleLines.push(truncateToWidth(replaceTabs(sanitizeText(line)), innerWidth));
+		}
+		return visibleLines;
+	}
+	render(width: number): string[] {
+		const safeWidth = Math.max(20, width);
+		const innerWidth = Math.max(1, safeWidth - 2);
+		const maxOverlayRows = Math.max(5, Math.floor(this.getTerminalRows() * 0.8));
+		const chromeRows = 4;
+		const maxContentRows = Math.max(1, maxOverlayRows - chromeRows);
+		// Propagate terminal resize to PTY session
+		const currentCols = innerWidth;
+		const currentRows = maxContentRows;
+		if (this.#session && (currentCols !== this.#lastCols || currentRows !== this.#lastRows)) {
+			this.#lastCols = currentCols;
+			this.#lastRows = currentRows;
+			try {
+				this.#session.resize(currentCols, currentRows);
+			} catch {
+				// Session may have ended
+			}
+		}
+		const statusIcon =
+			this.#state === "running"
+				? getStateIcon("running", this.uiTheme)
+				: this.#state === "complete" && this.#exitCode === 0
+					? getStateIcon("success", this.uiTheme)
+					: getStateIcon("warning", this.uiTheme);
+		const title = this.uiTheme.fg("accent", "Console");
+		const statusBadge = `${this.uiTheme.fg("dim", this.uiTheme.format.bracketLeft)}${this.#stateText()}${this.uiTheme.fg("dim", this.uiTheme.format.bracketRight)}`;
+		const prefix = `${statusIcon} ${title} `;
+		const suffix = ` ${statusBadge}`;
+		const available = Math.max(1, innerWidth - visibleWidth(prefix) - visibleWidth(suffix));
+		const cmd = truncateToWidth(this.uiTheme.fg("muted", replaceTabs(this.command)), available);
+		const header = truncateToWidth(`${prefix}${cmd}${suffix}`, innerWidth);
+		const footer =
+			this.#state === "running"
+				? truncateToWidth(
+						`${this.uiTheme.fg("warning", "esc")} ${this.uiTheme.fg("dim", "force-kill")} ${this.uiTheme.fg("dim", "· input forwarded to PTY")}`,
+						innerWidth,
+					)
+				: truncateToWidth(this.uiTheme.fg("dim", "session finished"), innerWidth);
+		const visibleLines = this.#readViewport(innerWidth, maxContentRows);
+		const content = visibleLines.length > 0 ? visibleLines : [padding(innerWidth)];
+		const borderHorizontal = this.uiTheme.fg("border", this.uiTheme.boxSharp.horizontal.repeat(innerWidth));
+		const borderVertical = this.uiTheme.fg("border", this.uiTheme.boxSharp.vertical);
+		const boxLine = (line: string) =>
+			`${borderVertical}${line}${padding(Math.max(0, innerWidth - visibleWidth(line)))}${borderVertical}`;
+		return [
+			`${this.uiTheme.fg("border", this.uiTheme.boxSharp.topLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxSharp.topRight)}`,
+			boxLine(header),
+			...content.map(boxLine),
+			boxLine(footer),
+			`${this.uiTheme.fg("border", this.uiTheme.boxSharp.bottomLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxSharp.bottomRight)}`,
+		];
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {
+		this.#terminal.dispose();
+		this.#onDispose();
+	}
+}
+
+const NO_PAGER_ENV = {
+	// Disable pagers so commands don't block on interactive views.
+	PAGER: "cat",
+	GIT_PAGER: "cat",
+	MANPAGER: "cat",
+	SYSTEMD_PAGER: "cat",
+	BAT_PAGER: "cat",
+	DELTA_PAGER: "cat",
+	GH_PAGER: "cat",
+	GLAB_PAGER: "cat",
+	PSQL_PAGER: "cat",
+	MYSQL_PAGER: "cat",
+	AWS_PAGER: "",
+	HOMEBREW_PAGER: "cat",
+	LESS: "FRX",
+	// Disable editor and terminal credential prompts.
+	GIT_EDITOR: "true",
+	VISUAL: "true",
+	EDITOR: "true",
+	GIT_TERMINAL_PROMPT: "0",
+	SSH_ASKPASS: "/usr/bin/false",
+	CI: "1",
+	// Package manager defaults for unattended execution.
+	npm_config_yes: "true",
+	npm_config_update_notifier: "false",
+	npm_config_fund: "false",
+	npm_config_audit: "false",
+	npm_config_progress: "false",
+	PNPM_DISABLE_SELF_UPDATE_CHECK: "true",
+	PNPM_UPDATE_NOTIFIER: "false",
+	YARN_ENABLE_TELEMETRY: "0",
+	YARN_ENABLE_PROGRESS_BARS: "0",
+	// Cross-language/tooling non-interactive defaults.
+	CARGO_TERM_PROGRESS_WHEN: "never",
+	DEBIAN_FRONTEND: "noninteractive",
+	PIP_NO_INPUT: "1",
+	PIP_DISABLE_PIP_VERSION_CHECK: "1",
+	TF_INPUT: "0",
+	TF_IN_AUTOMATION: "1",
+	GH_PROMPT_DISABLED: "1",
+	COMPOSER_NO_INTERACTION: "1",
+	CLOUDSDK_CORE_DISABLE_PROMPTS: "1",
+};
+
+export async function runInteractiveBashPty(
+	ui: NonNullable<AgentToolContext["ui"]>,
+	options: {
+		command: string;
+		cwd: string;
+		timeoutMs: number;
+		signal?: AbortSignal;
+		env?: Record<string, string>;
+		artifactPath?: string;
+		artifactId?: string;
+	},
+): Promise<BashInteractiveResult> {
+	const sink = new OutputSink({ artifactPath: options.artifactPath, artifactId: options.artifactId });
+	let pendingChunks = Promise.resolve();
+	const result = await ui.custom<BashInteractiveResult>(
+		(tui, uiTheme, _keybindings, done) => {
+			const session = new PtySession();
+			const component = new BashInteractiveOverlayComponent(options.command, uiTheme, () => tui.terminal.rows);
+			component.setSession(session);
+			let finished = false;
+			const finalize = (run: PtyRunResult) => {
+				if (finished) return;
+				finished = true;
+				component.setComplete({ exitCode: run.exitCode, cancelled: run.cancelled, timedOut: run.timedOut });
+				tui.requestRender();
+				void (async () => {
+					await component.flushOutput();
+					await pendingChunks;
+					const summary = await sink.dump();
+					done({
+						exitCode: run.exitCode,
+						cancelled: run.cancelled,
+						timedOut: run.timedOut,
+						...summary,
+					});
+				})();
+			};
+			const cols = Math.max(20, tui.terminal.columns - 2);
+			const rows = Math.max(5, tui.terminal.rows - 4);
+			component.setHandlers(
+				data => {
+					try {
+						session.write(data);
+					} catch {
+						// ignore writes after command exits
+					}
+				},
+				() => {
+					try {
+						session.kill();
+					} catch {
+						// ignore
+					}
+				},
+				() => {
+					try {
+						session.kill();
+					} catch {
+						// ignore
+					}
+				},
+			);
+			void session
+				.start(
+					{
+						command: options.command,
+						cwd: options.cwd,
+						timeoutMs: options.timeoutMs,
+						env: {
+							...options.env,
+							...NO_PAGER_ENV,
+						},
+						signal: options.signal,
+						cols,
+						rows,
+					},
+					(err, chunk) => {
+						if (finished || err || !chunk) return;
+						component.appendOutput(chunk);
+						const normalizedChunk = normalizeCaptureChunk(chunk);
+						pendingChunks = pendingChunks.then(() => sink.push(normalizedChunk)).catch(() => {});
+						tui.requestRender();
+					},
+				)
+				.then(finalize)
+				.catch(error => {
+					pendingChunks = pendingChunks
+						.then(() => sink.push(`PTY error: ${error instanceof Error ? error.message : String(error)}\n`))
+						.catch(() => {});
+					finalize({ exitCode: undefined, cancelled: false, timedOut: false });
+				});
+			return component;
+		},
+		{ overlay: true },
+	);
+	return result;
+}

package/src/tools/bash-interceptor.ts

@@ -0,0 +1,105 @@
+/**
+ * Bash intent interceptor - redirects common shell patterns to proper tools.
+ *
+ * When an LLM calls bash with patterns like `grep`, `cat`, `find`, etc.,
+ * this interceptor provides helpful error messages directing them to use
+ * the specialized tools instead.
+ */
+import type { BashInterceptorRule } from "../config/settings-schema";
+
+export const DEFAULT_BASH_INTERCEPTOR_RULES: BashInterceptorRule[] = [
+	{
+		pattern: "^\\s*(cat|head|tail|less|more)\\s+",
+		tool: "read",
+		message: "Use the `read` tool instead of cat/head/tail. It provides better context and handles binary files.",
+	},
+	{
+		pattern: "^\\s*(grep|rg|ripgrep|ag|ack)\\s+",
+		tool: "grep",
+		message: "Use the `grep` tool instead of grep/rg. It respects .gitignore and provides structured output.",
+	},
+	{
+		pattern: "^\\s*(find|fd|locate)\\s+.*(-name|-iname|-type|--type|-glob)",
+		tool: "find",
+		message: "Use the `find` tool instead of find/fd. It respects .gitignore and is faster for glob patterns.",
+	},
+	{
+		pattern: "^\\s*sed\\s+(-i|--in-place)",
+		tool: "edit",
+		message: "Use the `edit` tool instead of sed -i. It provides diff preview and fuzzy matching.",
+	},
+	{
+		pattern: "^\\s*perl\\s+.*-[pn]?i",
+		tool: "edit",
+		message: "Use the `edit` tool instead of perl -i. It provides diff preview and fuzzy matching.",
+	},
+	{
+		pattern: "^\\s*awk\\s+.*-i\\s+inplace",
+		tool: "edit",
+		message: "Use the `edit` tool instead of awk -i inplace. It provides diff preview and fuzzy matching.",
+	},
+	{
+		pattern: "^\\s*(echo|printf|cat\\s*<<)\\s+.*[^|]>\\s*\\S",
+		tool: "write",
+		message: "Use the `write` tool instead of echo/cat redirection. It handles encoding and provides confirmation.",
+	},
+];
+
+export interface InterceptionResult {
+	/** If true, the bash command should be blocked */
+	block: boolean;
+	/** Error message to return instead of executing */
+	message?: string;
+	/** Suggested tool to use instead */
+	suggestedTool?: string;
+}
+
+/**
+ * Compile bash interceptor rules into regexes, skipping invalid patterns.
+ */
+function compileRules(rules: BashInterceptorRule[]): Array<{ rule: BashInterceptorRule; regex: RegExp }> {
+	const compiled: Array<{ rule: BashInterceptorRule; regex: RegExp }> = [];
+	for (const rule of rules) {
+		const flags = rule.flags ?? "";
+		try {
+			compiled.push({ rule, regex: new RegExp(rule.pattern, flags) });
+		} catch {
+			// Skip invalid regex patterns
+		}
+	}
+	return compiled;
+}
+
+/**
+ * Check if a bash command should be intercepted.
+ *
+ * @param command The bash command to check
+ * @param availableTools Set of tool names that are available
+ * @returns InterceptionResult indicating if the command should be blocked
+ */
+export function checkBashInterception(
+	command: string,
+	availableTools: string[],
+	rules: BashInterceptorRule[] = DEFAULT_BASH_INTERCEPTOR_RULES,
+): InterceptionResult {
+	// Normalize command for pattern matching
+	const normalizedCommand = command.trim();
+	const compiled = compileRules(rules);
+
+	for (const { rule, regex } of compiled) {
+		// Only block if the suggested tool is actually available
+		if (!availableTools.includes(rule.tool)) {
+			continue;
+		}
+
+		if (regex.test(normalizedCommand)) {
+			return {
+				block: true,
+				message: `Blocked: ${rule.message}\n\nOriginal command: ${command}`,
+				suggestedTool: rule.tool,
+			};
+		}
+	}
+
+	return { block: false };
+}

package/src/tools/bash-normalize.ts

@@ -0,0 +1,107 @@
+/**
+ * Bash command normalizer - extracts patterns that are better handled natively.
+ *
+ * Detects and extracts:
+ * - `| head -n N` / `| head -N` - extracted to headLines
+ * - `| tail -n N` / `| tail -N` - extracted to tailLines
+ */
+
+export interface NormalizedCommand {
+	/** Cleaned command with patterns stripped */
+	command: string;
+	/** Extracted head line count, if any */
+	headLines?: number;
+	/** Extracted tail line count, if any */
+	tailLines?: number;
+}
+
+/**
+ * Pattern to match trailing pipe to head/tail.
+ * Captures: full match, command (head/tail), line count
+ *
+ * Matches:
+ * - `| head -n 50`
+ * - `| head -50`
+ * - `| tail -n 100`
+ * - `| tail -100`
+ *
+ * Does NOT match head/tail with other flags or without line count.
+ */
+const TRAILING_HEAD_TAIL_PATTERN = /\|\s*(head|tail)\s+(?:-n\s*(\d+)|(-\d+))\s*$/;
+
+/**
+ * Normalize a bash command by stripping patterns better handled natively.
+ *
+ * Extracts `| head -n N` and `| tail -n N` suffixes into separate fields
+ * so they can be applied post-execution without breaking streaming.
+ *
+ * Strips `2>&1` since we already merge stdout/stderr.
+ */
+export function normalizeBashCommand(command: string): NormalizedCommand {
+	let normalized = command;
+	let headLines: number | undefined;
+	let tailLines: number | undefined;
+
+	// Extract trailing head/tail
+	const match = normalized.match(TRAILING_HEAD_TAIL_PATTERN);
+	if (match) {
+		const [fullMatch, cmd, nValue, dashValue] = match;
+		const lineCount = nValue ? Number.parseInt(nValue, 10) : Number.parseInt(dashValue.slice(1), 10);
+
+		if (cmd === "head") {
+			headLines = lineCount;
+		} else {
+			tailLines = lineCount;
+		}
+
+		normalized = normalized.slice(0, -fullMatch.length);
+	}
+
+	// Preserve internal whitespace (important for heredocs / indentation-sensitive scripts)
+	normalized = normalized.trim();
+
+	return {
+		command: normalized,
+		headLines,
+		tailLines,
+	};
+}
+
+/**
+ * Apply head/tail limits to output text.
+ *
+ * If both head and tail are specified, head is applied first (take first N lines),
+ * then tail is applied (take last M lines of that).
+ */
+export function applyHeadTail(
+	text: string,
+	headLines?: number,
+	tailLines?: number,
+): { text: string; applied: boolean; headApplied?: number; tailApplied?: number } {
+	if (!headLines && !tailLines) {
+		return { text, applied: false };
+	}
+
+	let lines = text.split("\n");
+	let headApplied: number | undefined;
+	let tailApplied: number | undefined;
+
+	// Apply head first (keep first N lines)
+	if (headLines !== undefined && headLines > 0 && lines.length > headLines) {
+		lines = lines.slice(0, headLines);
+		headApplied = headLines;
+	}
+
+	// Then apply tail (keep last N lines)
+	if (tailLines !== undefined && tailLines > 0 && lines.length > tailLines) {
+		lines = lines.slice(-tailLines);
+		tailApplied = tailLines;
+	}
+
+	return {
+		text: lines.join("\n"),
+		applied: headApplied !== undefined || tailApplied !== undefined,
+		headApplied,
+		tailApplied,
+	};
+}