@gajae-code/coding-agent 0.15.5 → 0.15.6

package/src/telemetry/events.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getTrustedAgentFile } from "@gajae-code/utils";
+
+export const TELEMETRY_SCHEMA_VERSION = 1 as const;
+export const TELEMETRY_INSTALL_ID_FILE = "telemetry-install-id" as const;
+
+export const TELEMETRY_EVENT_NAMES = [
+	"update_check_started",
+	"update_check_completed",
+	"update_install_started",
+	"update_install_completed",
+	"update_install_failed",
+] as const;
+
+export type TelemetryEventName = (typeof TELEMETRY_EVENT_NAMES)[number];
+
+export interface TelemetryEvent {
+	schemaVersion: typeof TELEMETRY_SCHEMA_VERSION;
+	event: TelemetryEventName;
+	installId: string;
+	occurredAt: string;
+	channel?: "stable" | "nightly";
+	result?: "available" | "up_to_date" | "installed" | "failed" | "skipped";
+	installMethod?: "bun" | "npm" | "binary" | "migrate";
+}
+
+type EventInput = {
+	event?: unknown;
+	installId?: unknown;
+	occurredAt?: unknown;
+	channel?: unknown;
+	result?: unknown;
+	installMethod?: unknown;
+	[key: string]: unknown;
+};
+
+const EVENT_NAMES = new Set<string>(TELEMETRY_EVENT_NAMES);
+const CHANNELS = new Set(["stable", "nightly"]);
+const RESULTS = new Set(["available", "up_to_date", "installed", "failed", "skipped"]);
+const INSTALL_METHODS = new Set(["bun", "npm", "binary", "migrate"]);
+const FORBIDDEN_KEY = /(?:prompt|argv|path|env|secret|account|model|provider|repo|error|hostname|username|machine|ip)/i;
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function hasForbiddenKey(value: unknown, seen = new Set<object>()): boolean {
+	if (value === null || typeof value !== "object") return false;
+	if (seen.has(value)) return false;
+	seen.add(value);
+	for (const [key, child] of Object.entries(value)) {
+		if (FORBIDDEN_KEY.test(key) || hasForbiddenKey(child, seen)) return true;
+	}
+	return false;
+}
+
+function requireString(value: unknown, field: string): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > 128) {
+		throw new Error(`invalid telemetry ${field}`);
+	}
+	return value;
+}
+
+/**
+ * Serialize only the versioned telemetry allowlist. Unknown fields are never
+ * emitted; forbidden fields anywhere in the input fail closed.
+ */
+export function serializeTelemetryEvent(input: unknown): string {
+	if (input === null || typeof input !== "object" || Array.isArray(input)) {
+		throw new Error("telemetry event must be an object");
+	}
+	if (hasForbiddenKey(input)) throw new Error("telemetry event contains forbidden data");
+	const value = input as EventInput;
+	const event = requireString(value.event, "event");
+	if (!EVENT_NAMES.has(event)) throw new Error("invalid telemetry event");
+	const installId = requireString(value.installId, "installId");
+	if (!UUID_V4.test(installId)) throw new Error("invalid telemetry installId");
+	const occurredAt = requireString(value.occurredAt, "occurredAt");
+	if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(occurredAt) || Number.isNaN(Date.parse(occurredAt))) {
+		throw new Error("invalid telemetry occurredAt");
+	}
+
+	const output: TelemetryEvent = {
+		schemaVersion: TELEMETRY_SCHEMA_VERSION,
+		event: event as TelemetryEventName,
+		installId,
+		occurredAt,
+	};
+	if (value.channel !== undefined) {
+		if (typeof value.channel !== "string" || !CHANNELS.has(value.channel))
+			throw new Error("invalid telemetry channel");
+		output.channel = value.channel as TelemetryEvent["channel"];
+	}
+	if (value.result !== undefined) {
+		if (typeof value.result !== "string" || !RESULTS.has(value.result)) throw new Error("invalid telemetry result");
+		output.result = value.result as TelemetryEvent["result"];
+	}
+	if (value.installMethod !== undefined) {
+		if (typeof value.installMethod !== "string" || !INSTALL_METHODS.has(value.installMethod)) {
+			throw new Error("invalid telemetry installMethod");
+		}
+		output.installMethod = value.installMethod as TelemetryEvent["installMethod"];
+	}
+	return `${JSON.stringify(output)}\n`;
+}
+
+async function writeNewInstallId(filePath: string, installId: string): Promise<void> {
+	const handle = await fs.open(filePath, "wx", 0o600);
+	try {
+		await handle.writeFile(`${installId}\n`, "utf8");
+	} finally {
+		await handle.close();
+	}
+}
+
+/** Load or create a random UUIDv4 that is not derived from machine data. */
+export async function getTelemetryInstallId(
+	filePath = getTrustedAgentFile(TELEMETRY_INSTALL_ID_FILE),
+): Promise<string> {
+	try {
+		const existing = (await Bun.file(filePath).text()).trim();
+		if (UUID_V4.test(existing)) {
+			await fs.chmod(filePath, 0o600);
+			return existing;
+		}
+		throw new Error("telemetry install ID is malformed");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+
+	await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+	const generated = randomUUID();
+	try {
+		await writeNewInstallId(filePath, generated);
+		return generated;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		const existing = (await Bun.file(filePath).text()).trim();
+		if (!UUID_V4.test(existing)) throw new Error("telemetry install ID is malformed");
+		await fs.chmod(filePath, 0o600);
+		return existing;
+	}
+}

package/src/telemetry/index.ts

@@ -0,0 +1,3 @@
+export * from "./control";
+export * from "./events";
+export * from "./transport";

package/src/telemetry/transport.ts

@@ -0,0 +1,87 @@
+import { Settings } from "../config/settings";
+import { getTelemetryStatus } from "./control";
+import { getTelemetryInstallId, serializeTelemetryEvent, type TelemetryEvent, type TelemetryEventName } from "./events";
+
+export const TELEMETRY_ENDPOINT = "https://telemetry.gajae.dev/v1/events" as const;
+export const TELEMETRY_MAX_IN_FLIGHT = 2 as const;
+export const TELEMETRY_TIMEOUT_MS = 1500 as const;
+export const TELEMETRY_FLUSH_TIMEOUT_MS = 2000 as const;
+
+interface TelemetryTransportDependencies {
+	fetchImpl?: (input: string | URL, init?: RequestInit) => Promise<Response>;
+	endpoint?: string;
+}
+
+export type TelemetryDetails = Pick<TelemetryEvent, "channel" | "result" | "installMethod">;
+
+let inFlight = 0;
+const pendingTelemetry = new Set<Promise<void>>();
+
+/**
+ * Best-effort transport. The caller only schedules work; disabled telemetry,
+ * queue saturation, network errors, and non-2xx responses are all ignored.
+ */
+export function sendTelemetryEvent(
+	settings: Parameters<typeof getTelemetryStatus>[0],
+	event: TelemetryEvent,
+	deps: TelemetryTransportDependencies = {},
+): Promise<void> {
+	if (!getTelemetryStatus(settings).enabled || inFlight >= TELEMETRY_MAX_IN_FLIGHT) return Promise.resolve();
+	let body: string;
+	try {
+		body = serializeTelemetryEvent(event);
+	} catch {
+		return Promise.resolve();
+	}
+	inFlight++;
+	const fetchImpl = deps.fetchImpl ?? fetch;
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+	timeout.unref?.();
+	const delivery = fetchImpl(deps.endpoint ?? TELEMETRY_ENDPOINT, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body,
+		signal: controller.signal,
+		redirect: "error",
+	})
+		.catch(() => undefined)
+		.then(() => undefined)
+		.finally(() => {
+			clearTimeout(timeout);
+			inFlight--;
+		});
+	pendingTelemetry.add(delivery);
+	void delivery.finally(() => pendingTelemetry.delete(delivery));
+	return delivery;
+}
+
+export async function resetTelemetryTransportForTest(): Promise<void> {
+	await Promise.allSettled([...pendingTelemetry]);
+}
+
+/** Schedule an event without making telemetry part of the caller's lifecycle. */
+export function recordTelemetryEvent(event: TelemetryEventName, details: TelemetryDetails): Promise<void> {
+	const pending = (async () => {
+		const settings = await Settings.init();
+		if (!getTelemetryStatus(settings).enabled) return;
+		const installId = await getTelemetryInstallId();
+		await sendTelemetryEvent(settings, {
+			schemaVersion: 1,
+			event,
+			installId,
+			occurredAt: new Date().toISOString(),
+			...details,
+		});
+	})().catch(() => undefined);
+	pendingTelemetry.add(pending);
+	void pending.finally(() => pendingTelemetry.delete(pending));
+	return pending;
+}
+
+/** Wait briefly for accepted events so explicit process exits do not drop them. */
+export async function flushTelemetryEvents(timeoutMs = TELEMETRY_FLUSH_TIMEOUT_MS): Promise<void> {
+	const pending = [...pendingTelemetry];
+	if (pending.length === 0) return;
+	await Promise.race([Promise.allSettled(pending), Bun.sleep(timeoutMs)]);
+}

package/src/tools/bash-interactive.ts

@@ -3,6 +3,7 @@ import type { PtySession as NativePtySession, PtyRunResult } from "@gajae-code/n
 import {
 	type Component,
 	extractPrintableText,
+	getKeybindings,
 	matchesKey,
 	padding,
 	parseKey,
@@ -10,7 +11,7 @@ import {
 	truncateToWidth,
 	visibleWidth,
 } from "@gajae-code/tui";
-import { sanitizeText } from "@gajae-code/utils";
+import { logger, sanitizeText } from "@gajae-code/utils";
 import type { Terminal as XtermTerminalType } from "@xterm/headless";
 import { Settings } from "../config/settings";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
@@ -115,6 +116,7 @@ class BashInteractiveOverlayComponent implements Component {
 	#writeOffset = 0;
 	#flushResolvers: Array<() => void> = [];
 	#writing = false;
+	#onFoldKey: () => boolean = () => false;
 
 	constructor(
 		private readonly command: string,
@@ -131,10 +133,16 @@ class BashInteractiveOverlayComponent implements Component {
 		});
 	}
 
-	setHandlers(onInput: (data: string) => void, onDismiss: () => void, onDispose: () => void): void {
+	setHandlers(
+		onInput: (data: string) => void,
+		onDismiss: () => void,
+		onDispose: () => void,
+		onFoldKey: () => boolean,
+	): void {
 		this.#onInput = onInput;
 		this.#onDismiss = onDismiss;
 		this.#onDispose = onDispose;
+		this.#onFoldKey = onFoldKey;
 	}
 
 	appendOutput(chunk: string): void {
@@ -199,6 +207,9 @@ class BashInteractiveOverlayComponent implements Component {
 	}
 
 	handleInput(data: string): void {
+		if (this.#state === "running" && getKeybindings().matches(data, "app.tool.backgroundFold")) {
+			if (this.#onFoldKey()) return;
+		}
 		if (this.#state === "running" && (matchesKey(data, "escape") || matchesKey(data, "esc"))) {
 			this.#onDismiss();
 			return;
@@ -293,6 +304,25 @@ class BashInteractiveOverlayComponent implements Component {
 	}
 }
 
+/** Live controls handed to the caller once the PTY run owns its session. */
+export interface InteractivePtyControls {
+	/**
+	 * Detach the overlay and settle the foreground call with `foldResult`, leaving
+	 * the process running and still writing into the sink. Idempotent.
+	 */
+	detachObserver: (foldResult: BashInteractiveResult) => "resolved" | "already-settled";
+	/**
+	 * Resolves with the run's real summary when the process actually ends,
+	 * regardless of whether the foreground was folded. A folded run is delivered
+	 * from this, so its result can never be silently dropped.
+	 */
+	terminalCompletion: Promise<BashInteractiveResult>;
+	/** Kill the owned process during owner teardown; the observer never calls this. */
+	kill: () => void;
+	/** Stop forwarding the foreground abort signal after ownership transfers on fold. */
+	detachForegroundCancellation: () => void;
+}
+
 export async function runInteractiveBashPty(
 	ui: NonNullable<AgentToolContext["ui"]>,
 	options: {
@@ -307,6 +337,11 @@ export async function runInteractiveBashPty(
 		spillThreshold?: number;
 		headBytes?: number;
 		settings?: Settings;
+		/** Receives live controls once the session is running; used to register a fold. */
+		onControls?: (controls: InteractivePtyControls) => void;
+		onFoldKey?: () => boolean;
+		onDismiss?: () => void;
+		onOutput?: (chunk: string) => void;
 	},
 ): Promise<BashInteractiveResult> {
 	const settings = options.settings ?? (await Settings.init());
@@ -322,89 +357,151 @@ export async function runInteractiveBashPty(
 	const { default: xterm } = await import("@xterm/headless");
 	const XtermTerminal = xterm.Terminal;
 	const PtySession = await ptySessionNative();
-	const result = await ui.custom<BashInteractiveResult>(
-		(tui, uiTheme, _keybindings, done) => {
-			const session = new PtySession();
-			const component = new BashInteractiveOverlayComponent(
-				options.command,
-				uiTheme,
-				() => tui.terminal.rows,
-				XtermTerminal,
-			);
-			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();
-					const summary = await sink.dump();
-					done({
-						exitCode: run.exitCode,
-						cancelled: run.cancelled,
-						timedOut: run.timedOut,
-						...summary,
-					});
-				})();
+
+	// Ownership inversion: this runner owns the session and the sink from t0,
+	// started OUTSIDE ui.custom. The overlay is only an observer view, so
+	// dismissing it — or never creating it — can never kill the process.
+	// Seed the real host geometry so the first frame renders at the user's size;
+	// the overlay keeps resizing the session as it lays out. Fallbacks apply only
+	// when the host exposes no terminal (tests, pipes).
+	const initialPtySize = {
+		cols: Math.max(20, (process.stdout.columns ?? 80) - 2),
+		rows: Math.max(5, (process.stdout.rows ?? 24) - 4),
+	};
+
+	const session = new PtySession();
+	const processAbortController = new AbortController();
+	const forwardForegroundAbort = () => processAbortController.abort();
+	if (options.signal?.aborted) processAbortController.abort();
+	else options.signal?.addEventListener("abort", forwardForegroundAbort, { once: true });
+	let observer: BashInteractiveOverlayComponent | undefined;
+	let settleForeground: ((result: BashInteractiveResult) => void) | undefined;
+	let settled = false;
+	const foreground = Promise.withResolvers<BashInteractiveResult>();
+	const terminal = Promise.withResolvers<BashInteractiveResult>();
+
+	const settle = (result: BashInteractiveResult): "resolved" | "already-settled" => {
+		if (settled) return "already-settled";
+		settled = true;
+		// Prefer ui.custom's own `done` so the overlay tears down through its normal
+		// path; fall back to the outer promise when no overlay was ever attached.
+		if (settleForeground) settleForeground(result);
+		else foreground.resolve(result);
+		return "resolved";
+	};
+
+	let finished = false;
+	const finalize = (run: PtyRunResult): void => {
+		if (finished) return;
+		finished = true;
+		observer?.setComplete({ exitCode: run.exitCode, cancelled: run.cancelled, timedOut: run.timedOut });
+		void (async () => {
+			await observer?.flushOutput();
+			const summary = await sink.dump();
+			const outcome: BashInteractiveResult = {
+				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: {
-							...NON_INTERACTIVE_ENV,
-							...options.env,
-						},
-						signal: options.signal,
-						cols,
-						rows,
-						shell: resolvedShell,
-					},
-					(err, chunk) => {
-						if (finished || err || !chunk) return;
-						component.appendOutput(chunk);
-						const normalizedChunk = normalizeCaptureChunk(chunk);
-						sink.push(normalizedChunk);
-						tui.requestRender();
-					},
-				)
-				.then(finalize)
-				.catch(error => {
-					sink.push(`PTY error: ${error instanceof Error ? error.message : String(error)}\n`);
-					finalize({ exitCode: undefined, cancelled: false, timedOut: false });
-				});
-			return component;
+			options.signal?.removeEventListener("abort", forwardForegroundAbort);
+			// Publish the real outcome BEFORE settling: a folded run's foreground is
+			// already gone, and this is the only path that can deliver its result.
+			terminal.resolve(outcome);
+			settle(outcome);
+		})();
+	};
+
+	// The original deadline rides on the run itself, so a folded command expires
+	// exactly when it would have in the foreground.
+	void session
+		.start(
+			{
+				command: options.command,
+				cwd: options.cwd,
+				timeoutMs: options.timeoutMs,
+				env: { ...NON_INTERACTIVE_ENV, ...options.env },
+				signal: processAbortController.signal,
+				cols: initialPtySize.cols,
+				rows: initialPtySize.rows,
+				shell: resolvedShell,
+			},
+			(err, chunk) => {
+				if (finished || err || !chunk) return;
+				// The sink is fed unconditionally: output stays continuous across a
+				// fold, when no overlay exists, and after the overlay is disposed.
+				const normalizedChunk = normalizeCaptureChunk(chunk);
+				sink.push(normalizedChunk);
+				options.onOutput?.(normalizedChunk);
+				observer?.appendOutput(chunk);
+			},
+		)
+		.then(finalize)
+		.catch(error => {
+			sink.push(`PTY error: ${error instanceof Error ? error.message : String(error)}\n`);
+			finalize({ exitCode: undefined, cancelled: false, timedOut: false });
+		});
+
+	options.onControls?.({
+		terminalCompletion: terminal.promise,
+		kill: () => session.kill(),
+		detachForegroundCancellation: () => {
+			options.signal?.removeEventListener("abort", forwardForegroundAbort);
 		},
-		{ overlay: true },
-	);
-	return result;
+		detachObserver: (foldResult: BashInteractiveResult) => {
+			const outcome = settle(foldResult);
+			if (outcome === "resolved") observer = undefined;
+			return outcome;
+		},
+	});
+
+	// Folded (or already finished) before any view existed: there is nothing to
+	// attach an observer to, so never await an overlay that will never be settled.
+	if (settled) return await foreground.promise;
+
+	try {
+		const overlayResult = await Promise.race([
+			foreground.promise,
+			ui.custom<BashInteractiveResult>(
+				(tui, uiTheme, _keybindings, done) => {
+					settleForeground = done;
+					const component = new BashInteractiveOverlayComponent(
+						options.command,
+						uiTheme,
+						() => tui.terminal.rows,
+						XtermTerminal,
+					);
+					component.setSession(session);
+					// Observer view only: stdin still reaches the process while attached,
+					// Escape explicitly force-kills, while disposal never kills the work.
+					component.setHandlers(
+						data => {
+							try {
+								session.write(data);
+							} catch {
+								// ignore writes after the command exits
+							}
+						},
+						options.onDismiss ?? (() => session.kill()),
+						() => {},
+						options.onFoldKey ?? (() => false),
+					);
+					observer = component;
+					return component;
+				},
+				{ overlay: true },
+			),
+		]);
+		return overlayResult;
+	} catch (error) {
+		// Overlay creation or view init failed. The process is already running and
+		// owned here, so surface the failure without orphaning it: the run keeps
+		// writing to the sink and settles the foreground on its own.
+		logger.warn("Interactive PTY overlay unavailable; continuing without the view", {
+			error: error instanceof Error ? error.message : String(error),
+		});
+		observer = undefined;
+		settleForeground = undefined;
+		return await foreground.promise;
+	}
 }