@agnishc/edb-gemini-proxy 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- Initial release: `gemini_proxy` tool with stream-json event parsing
+- `approvalMode` parameter: yolo / auto_edit / plan
+- File context injection and `includeDirectories` workspace expansion
+- Collapsed and expanded TUI rendering with per-tool-call status icons

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agnish Chakraborty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @agnishc/edb-gemini-proxy
+
+A Pi CLI extension that registers a `gemini_proxy` tool — lets the pi agent delegate tasks to **Google's Gemini CLI** running in headless mode.
+
+## Use cases
+
+- Cross-model second opinion (different perspective from Gemini vs the primary agent)
+- Tasks that benefit from Gemini's large context window
+- Google Search grounding
+- Code review, security audit, diff analysis
+
+## Install
+
+```bash
+pi install npm:@agnishc/edb-gemini-proxy
+```
+
+## Requirements
+
+- `gemini` CLI on PATH (`npm install -g @google/gemini-cli`)
+- Auth: `GEMINI_API_KEY` env var, or run `gemini auth` for OAuth
+- Set `GEMINI_PATH` env var to override the binary location
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prompt` | string | The task for Gemini — be specific |
+| `systemPrompt` | string? | Role / instructions prepended to context |
+| `model` | string? | e.g. `gemini-2.5-pro`, `gemini-2.5-flash` |
+| `approvalMode` | string? | `yolo` (default), `auto_edit`, `plan` (read-only) |
+| `files` | string[]? | File paths to inject into Gemini's context |
+| `includeDirectories` | string[]? | Additional directories for Gemini's workspace |
+| `cwd` | string? | Working directory for the Gemini process |
+
+## TUI
+
+- Collapsed: tool call list + response preview with streaming status
+- Expanded (`Ctrl+O`): full markdown response with all tool calls and status icons
+
+## License
+
+[MIT](LICENSE) © Agnish Chakraborty

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@agnishc/edb-gemini-proxy",
+	"version": "0.1.0",
+	"description": "Pi extension: gemini_proxy tool — delegate tasks to Google Gemini CLI from within pi",
+	"keywords": ["pi-package", "pi-extension", "edb", "gemini"],
+	"type": "module",
+	"license": "MIT",
+	"author": "Agnish Chakraborty",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agnishcc/pi-extention-monorepo.git",
+		"directory": "packages/edb-gemini-proxy"
+	},
+	"homepage": "https://github.com/agnishcc/pi-extention-monorepo/tree/main/packages/edb-gemini-proxy#readme",
+	"bugs": { "url": "https://github.com/agnishcc/pi-extention-monorepo/issues" },
+	"publishConfig": { "access": "public" },
+	"scripts": { "test": "vitest run" },
+	"files": ["src", "README.md", "LICENSE", "CHANGELOG.md"],
+	"pi": {
+		"extensions": ["./src/index.ts"]
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-coding-agent": "*",
+		"@mariozechner/pi-tui": "*",
+		"typebox": "*"
+	}
+}

package/src/cli.ts

@@ -0,0 +1,53 @@
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// ── CLI discovery ──────────────────────────────────────────────────────────────
+
+export function findGeminiCli(): string {
+	if (process.env.GEMINI_PATH) {
+		try {
+			fs.accessSync(process.env.GEMINI_PATH, fs.constants.X_OK);
+			return process.env.GEMINI_PATH;
+		} catch {
+			/* fall through */
+		}
+	}
+
+	try {
+		const resolved = execSync("which gemini", {
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+		if (resolved) return resolved;
+	} catch {
+		/* fall through */
+	}
+
+	for (const c of [
+		"/opt/homebrew/bin/gemini",
+		path.join(os.homedir(), ".local/bin/gemini"),
+		"/usr/local/bin/gemini",
+	]) {
+		try {
+			fs.accessSync(c, fs.constants.X_OK);
+			return c;
+		} catch {
+			/* continue */
+		}
+	}
+
+	return "gemini";
+}
+
+// ── File context ───────────────────────────────────────────────────────────────
+
+export async function readFileForContext(absPath: string): Promise<string> {
+	try {
+		const content = await fs.promises.readFile(absPath, "utf-8");
+		return `<file path="${absPath}">\n${content}\n</file>`;
+	} catch (err) {
+		return `<file path="${absPath}" error="${(err as Error).message}" />`;
+	}
+}

package/src/execute.ts

@@ -0,0 +1,202 @@
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import { readFileForContext } from "./cli";
+import type { GeminiProxyDetails, GeminiStreamEvent, ToolCallRecord } from "./types";
+
+// ── Execute ────────────────────────────────────────────────────────────────────
+
+export async function execute(
+	geminiPath: string,
+	params: any,
+	signal: AbortSignal | undefined,
+	onUpdate: ((update: { content: Array<{ type: "text"; text: string }>; details?: any }) => void) | undefined,
+	ctx: any,
+): Promise<{ content: Array<{ type: string; text: string }>; details: GeminiProxyDetails; isError: boolean }> {
+	const workDir = params.cwd ?? ctx.cwd;
+	const approvalMode = params.approvalMode ?? "yolo";
+
+	// ----- 1. Build stdin payload -----
+	const stdinParts: string[] = [];
+	if (params.systemPrompt) {
+		stdinParts.push(`<instructions>\n${params.systemPrompt}\n</instructions>`);
+	}
+
+	const filesInjected: string[] = [];
+	if (params.files && params.files.length > 0) {
+		for (const filePath of params.files) {
+			const absPath = path.isAbsolute(filePath) ? filePath : path.join(workDir, filePath);
+			filesInjected.push(absPath);
+			stdinParts.push(await readFileForContext(absPath));
+		}
+	}
+	stdinParts.push(params.prompt);
+	const stdinPayload = stdinParts.join("\n\n");
+
+	// ----- 2. Build CLI arguments -----
+	const args: string[] = ["--output-format", "stream-json"];
+	if (params.model) args.push("--model", params.model);
+	if (approvalMode === "yolo") {
+		args.push("--yolo");
+	} else {
+		args.push("--approval-mode", approvalMode);
+	}
+	if (params.includeDirectories && params.includeDirectories.length > 0) {
+		for (const dir of params.includeDirectories) {
+			const absDir = path.isAbsolute(dir) ? dir : path.join(workDir, dir);
+			args.push("--include-directories", absDir);
+		}
+	}
+
+	// ----- 3. Spawn Gemini -----
+	const details: GeminiProxyDetails = {
+		streaming: true,
+		toolCalls: [],
+		filesInjected: filesInjected.length > 0 ? filesInjected : undefined,
+	};
+
+	const pendingToolCalls = new Map<string, ToolCallRecord>();
+	let assistantText = "";
+	let spawnError = "";
+	let _finalStatus: "success" | "error" = "success";
+	// eslint-disable-next-line prefer-const
+	let hadError = false;
+
+	const emitUpdate = () => {
+		onUpdate?.({
+			content: [{ type: "text" as const, text: assistantText || "(waiting for Gemini…)" }],
+			details: { ...details },
+		});
+	};
+
+	const exitCode = await new Promise<number>((resolve) => {
+		const proc = spawn(geminiPath, args, {
+			cwd: workDir,
+			shell: false,
+			stdio: ["pipe", "pipe", "pipe"],
+			env: { ...process.env },
+		});
+
+		proc.stdin.write(stdinPayload, "utf-8");
+		proc.stdin.end();
+
+		let buffer = "";
+
+		const processLine = (line: string) => {
+			if (!line.trim()) return;
+			let event: GeminiStreamEvent;
+			try {
+				event = JSON.parse(line) as GeminiStreamEvent;
+			} catch {
+				return;
+			}
+
+			switch (event.type) {
+				case "init": {
+					details.sessionId = event.session_id;
+					details.model = event.model;
+					break;
+				}
+				case "message": {
+					if (event.role !== "assistant") break;
+					if (event.delta) {
+						assistantText += event.content;
+					} else {
+						assistantText = event.content;
+					}
+					emitUpdate();
+					break;
+				}
+				case "tool_use": {
+					const record: ToolCallRecord = {
+						id: event.tool_id,
+						name: event.tool_name,
+						parameters: event.parameters,
+					};
+					pendingToolCalls.set(record.id, record);
+					details.toolCalls = [...details.toolCalls, record];
+					emitUpdate();
+					break;
+				}
+				case "tool_result": {
+					const record = pendingToolCalls.get(event.tool_id);
+					if (record) {
+						record.status = event.status;
+						record.output = event.output ?? event.error?.message;
+						details.toolCalls = details.toolCalls.map((t) => (t.id === event.tool_id ? { ...record } : t));
+						emitUpdate();
+					}
+					break;
+				}
+				case "error": {
+					if (event.severity === "error") spawnError += (spawnError ? "\n" : "") + event.message;
+					break;
+				}
+				case "result": {
+					details.streaming = false;
+					_finalStatus = event.status;
+					if (event.status === "error") hadError = true;
+					if (event.stats) {
+						details.totalTokens = event.stats.total_tokens;
+						details.durationMs = event.stats.duration_ms;
+					}
+					if (event.status === "error" && event.error) {
+						spawnError = event.error.message || "Gemini reported an error";
+					}
+					break;
+				}
+			}
+		};
+
+		proc.stdout.on("data", (chunk) => {
+			buffer += chunk.toString("utf-8");
+			const lines = buffer.split("\n");
+			buffer = lines.pop() ?? "";
+			for (const line of lines) processLine(line);
+		});
+
+		proc.stderr.on("data", (chunk) => {
+			const IGNORED = [
+				"Loaded cached credentials",
+				"YOLO mode is enabled",
+				"All tool calls will be automatically",
+				"Skill ",
+				"overriding the built-in",
+				"gemini-cli",
+			];
+			const errorLines = chunk
+				.toString("utf-8")
+				.split("\n")
+				.filter((l: string) => l.trim() && !IGNORED.some((prefix) => l.includes(prefix)));
+			if (errorLines.length > 0) spawnError += (spawnError ? "\n" : "") + errorLines.join("\n");
+		});
+
+		proc.on("close", (code) => {
+			if (buffer.trim()) processLine(buffer);
+			details.exitCode = code ?? 0;
+			resolve(code ?? 0);
+		});
+
+		proc.on("error", (err) => {
+			spawnError = `Failed to spawn gemini CLI: ${err.message}\n\nMake sure 'gemini' is on your PATH (npm install -g @google/gemini-cli) or set GEMINI_PATH.`;
+			details.exitCode = 1;
+			resolve(1);
+		});
+
+		if (signal) {
+			const kill = () => {
+				proc.kill("SIGTERM");
+				setTimeout(() => {
+					if (!proc.killed) proc.kill("SIGKILL");
+				}, 5000);
+			};
+			if (signal.aborted) kill();
+			else signal.addEventListener("abort", kill, { once: true });
+		}
+	});
+
+	// ----- 4. Return result -----
+	const isError = exitCode !== 0 || hadError || (Boolean(spawnError) && !assistantText);
+	const responseText = isError ? spawnError || "(gemini exited with no output)" : assistantText || "(no output)";
+
+	return { content: [{ type: "text" as const, text: responseText }], details, isError };
+}

package/src/format.ts

@@ -0,0 +1,47 @@
+import * as os from "node:os";
+
+// ── Format helpers ─────────────────────────────────────────────────────────────
+
+/** Format a Gemini tool call for single-line display in the TUI. */
+export function formatToolCall(name: string, params: Record<string, unknown>): string {
+	const shortenPath = (p: string) => {
+		const home = os.homedir();
+		return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+	};
+
+	// Gemini tool names follow snake_case conventions
+	switch (name) {
+		case "read_file": {
+			const p = shortenPath(String(params.path ?? params.absolute_path ?? "..."));
+			return `read ${p}`;
+		}
+		case "write_file":
+		case "edit_file":
+		case "replace_in_file": {
+			const p = shortenPath(String(params.path ?? params.absolute_path ?? "..."));
+			return `${name.replace(/_/g, " ")} ${p}`;
+		}
+		case "run_shell_command": {
+			const cmd = String(params.command ?? "...");
+			return `$ ${cmd.length > 60 ? `${cmd.slice(0, 60)}…` : cmd}`;
+		}
+		case "list_directory": {
+			const p = shortenPath(String(params.path ?? "."));
+			return `ls ${p}`;
+		}
+		case "search_file_content":
+		case "grep_search": {
+			const pattern = String(params.pattern ?? params.query ?? "...");
+			return `grep ${pattern.length > 30 ? `${pattern.slice(0, 30)}…` : pattern}`;
+		}
+		case "web_search":
+		case "google_web_search": {
+			const q = String(params.query ?? "...");
+			return `search: ${q.length > 50 ? `${q.slice(0, 50)}…` : q}`;
+		}
+		default: {
+			const s = JSON.stringify(params);
+			return `${name} ${s.length > 50 ? `${s.slice(0, 50)}…` : s}`;
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * pi-gemini-proxy
+ *
+ * Registers a `gemini_proxy` tool that lets the pi agent delegate tasks
+ * to Google's Gemini CLI running in non-interactive (headless) mode.
+ *
+ * Typical uses: code review, security audit, diff analysis, second-opinion
+ * reasoning — from a model with a different perspective than the primary agent.
+ *
+ * Requires: `gemini` CLI on PATH (npm install -g @google/gemini-cli)
+ * Optional:  set GEMINI_PATH env var to point to a specific binary.
+ * Auth:      GEMINI_API_KEY env var, or run `gemini auth` to login via OAuth.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { findGeminiCli } from "./cli";
+import { execute } from "./execute";
+import { renderCall, renderResult } from "./render";
+
+// ── Extension ──────────────────────────────────────────────────────────────────
+
+export default function geminiProxyExtension(pi: ExtensionAPI): void {
+	const geminiPath = findGeminiCli();
+
+	pi.registerTool({
+		name: "gemini_proxy",
+		label: "Gemini Proxy",
+		description: [
+			"Delegate a task to Google's Gemini CLI running in non-interactive (headless) mode.",
+			"Best for: code review, security audit, diff analysis, cross-model second opinion,",
+			"tasks that benefit from Gemini's large context window or Google Search grounding.",
+			"Supply files[] to inject specific files into context.",
+			"Default approval mode is 'yolo' (auto-approve all tool actions).",
+		].join(" "),
+		promptSnippet:
+			"Delegate a task to Gemini — triggers on 'ask gemini', 'check with gemini', 'have gemini look at', 'get gemini to', or requests for cross-model second opinion, large-context analysis, or Google Search grounding",
+		promptGuidelines: [
+			"Use gemini_proxy when the user says 'ask gemini', 'check with gemini', 'have gemini look at this', 'get gemini to', or any similar phrase that directs a task explicitly to Gemini.",
+			"Use gemini_proxy when the user wants a second opinion from Gemini on code, architecture, or security.",
+			"Use gemini_proxy with a tailored systemPrompt to give Gemini a specific expert persona.",
+			"Use gemini_proxy with approvalMode 'plan' for read-only analysis without any file modifications.",
+			"Pass relevant file paths in the files[] parameter so Gemini has precise context without needing to hunt for them.",
+		],
+
+		parameters: Type.Object({
+			prompt: Type.String({
+				description:
+					"The task or question for Gemini. Be specific: include file names, what to look for, expected output format.",
+			}),
+			systemPrompt: Type.Optional(
+				Type.String({
+					description:
+						"Role / instructions prepended to the context. E.g. 'You are a senior security engineer. Identify vulnerabilities and rate their severity.'",
+				}),
+			),
+			model: Type.Optional(
+				Type.String({
+					description:
+						"Gemini model to use. E.g. 'gemini-2.5-pro', 'gemini-2.5-flash'. Defaults to the CLI's configured default.",
+				}),
+			),
+			approvalMode: Type.Optional(
+				Type.Union([Type.Literal("yolo"), Type.Literal("auto_edit"), Type.Literal("plan")], {
+					description:
+						"Tool approval mode. 'yolo' = auto-approve all (default), 'auto_edit' = auto-approve file edits only, 'plan' = read-only (no writes or shell).",
+				}),
+			),
+			files: Type.Optional(
+				Type.Array(Type.String(), {
+					description:
+						"File paths (relative to cwd) whose full contents are injected into Gemini's context before the prompt.",
+				}),
+			),
+			includeDirectories: Type.Optional(
+				Type.Array(Type.String(), {
+					description:
+						"Additional directory paths to include in Gemini's workspace (Gemini can read files from these dirs using its own Read tool).",
+				}),
+			),
+			cwd: Type.Optional(
+				Type.String({
+					description: "Working directory for the Gemini process. Defaults to pi's current working directory.",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			return execute(geminiPath, params, signal, onUpdate as any, ctx) as any;
+		},
+
+		renderCall,
+		renderResult,
+	});
+}

package/src/render.ts

@@ -0,0 +1,105 @@
+import { getMarkdownTheme } from "@mariozechner/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
+import { formatToolCall } from "./format";
+import type { GeminiProxyDetails } from "./types";
+
+// ── TUI rendering ──────────────────────────────────────────────────────────────
+
+export function renderCall(args: any, theme: any): any {
+	const prompt = String(args.prompt ?? "");
+	const preview = prompt.length > 80 ? `${prompt.slice(0, 80)}…` : prompt;
+	const model = args.model ? String(args.model) : "default";
+	const mode = args.approvalMode ? String(args.approvalMode) : "yolo";
+
+	let text =
+		theme.fg("toolTitle", theme.bold("gemini_proxy ")) +
+		theme.fg("accent", `[${model}]`) +
+		theme.fg("muted", ` mode: ${mode}`);
+
+	if (args.systemPrompt) {
+		const rolePreview = String(args.systemPrompt).slice(0, 50);
+		text += `\n  ${theme.fg("muted", "role: ")}${theme.fg("dim", rolePreview)}`;
+	}
+
+	text += `\n  ${theme.fg("dim", preview)}`;
+
+	if (args.files && (args.files as string[]).length > 0) {
+		text += `\n  ${theme.fg("muted", "files: ")}${theme.fg("dim", (args.files as string[]).join(", "))}`;
+	}
+
+	if (args.includeDirectories && (args.includeDirectories as string[]).length > 0) {
+		text += `\n  ${theme.fg("muted", "dirs: ")}${theme.fg("dim", (args.includeDirectories as string[]).join(", "))}`;
+	}
+
+	return new Text(text, 0, 0);
+}
+
+export function renderResult(result: any, { expanded }: any, theme: any): any {
+	const details = result.details as GeminiProxyDetails | undefined;
+	const text = result.content[0]?.type === "text" ? result.content[0].text : "(no output)";
+
+	const metaParts: string[] = [];
+	if (details?.model) metaParts.push(details.model);
+	if (details?.totalTokens) metaParts.push(`${details.totalTokens.toLocaleString()} tok`);
+	if (details?.durationMs) metaParts.push(`${(details.durationMs / 1000).toFixed(1)}s`);
+	const meta = metaParts.map((p) => theme.fg("dim", p)).join("  ");
+
+	if (result.isError) {
+		const errText = details?.streaming ? "(aborted)" : text;
+		return new Text(
+			theme.fg("error", "✗ ") +
+				theme.fg("toolTitle", theme.bold("Gemini")) +
+				(meta ? `  ${meta}` : "") +
+				`\n${theme.fg("error", errText)}`,
+			0,
+			0,
+		);
+	}
+
+	const icon = details?.streaming ? theme.fg("warning", "⏳") : theme.fg("success", "✓");
+	const headerLine = `${icon} ${theme.fg("toolTitle", theme.bold("Gemini"))}${meta ? `  ${meta}` : ""}`;
+
+	const toolCallLines = (details?.toolCalls ?? []).map((tc) => {
+		const statusIcon =
+			tc.status === "success"
+				? theme.fg("success", "✓")
+				: tc.status === "error"
+					? theme.fg("error", "✗")
+					: theme.fg("warning", "⏳");
+		return (
+			`  ${theme.fg("muted", "→ ")}${theme.fg("accent", tc.name)}` +
+			`${theme.fg("dim", ` ${formatToolCall(tc.name, tc.parameters)}`)} ${statusIcon}`
+		);
+	});
+
+	if (expanded) {
+		const mdTheme = getMarkdownTheme();
+		const container = new Container();
+		container.addChild(new Text(headerLine, 0, 0));
+		if (toolCallLines.length > 0) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(theme.fg("muted", "─── Tool calls ───"), 0, 0));
+			for (const tl of toolCallLines) container.addChild(new Text(tl, 0, 0));
+		}
+		if (text) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(theme.fg("muted", "─── Response ───"), 0, 0));
+			container.addChild(new Markdown(text.trim(), 0, 0, mdTheme));
+		}
+		return container;
+	}
+
+	// Collapsed view
+	const previewLines = text.split("\n").slice(0, 6);
+	const previewText = previewLines.join("\n") + (text.split("\n").length > 6 ? "\n…" : "");
+
+	let out = headerLine;
+	if (toolCallLines.length > 0) {
+		out += `\n${toolCallLines.slice(0, 3).join("\n")}`;
+		if (toolCallLines.length > 3) out += `\n  ${theme.fg("muted", `… +${toolCallLines.length - 3} more`)}`;
+	}
+	if (text) out += `\n${theme.fg("toolOutput", previewText)}`;
+	out += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+
+	return new Text(out, 0, 0);
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+// ── Gemini stream-json event types ─────────────────────────────────────────────
+
+export interface GeminiInitEvent {
+	type: "init";
+	timestamp: string;
+	session_id: string;
+	model: string;
+}
+
+export interface GeminiMessageEvent {
+	type: "message";
+	timestamp: string;
+	role: "user" | "assistant";
+	content: string;
+	/** true = streaming chunk; accumulate content. absent/false = full message */
+	delta?: boolean;
+}
+
+export interface GeminiToolUseEvent {
+	type: "tool_use";
+	timestamp: string;
+	tool_name: string;
+	tool_id: string;
+	parameters: Record<string, unknown>;
+}
+
+export interface GeminiToolResultEvent {
+	type: "tool_result";
+	timestamp: string;
+	tool_id: string;
+	status: "success" | "error";
+	output?: string;
+	error?: { type: string; message: string };
+}
+
+export interface GeminiErrorEvent {
+	type: "error";
+	timestamp: string;
+	severity: "warning" | "error";
+	message: string;
+}
+
+export interface GeminiResultEvent {
+	type: "result";
+	timestamp: string;
+	status: "success" | "error";
+	error?: { type: string; message: string };
+	stats?: {
+		total_tokens: number;
+		input_tokens: number;
+		output_tokens: number;
+		tool_calls: number;
+		duration_ms: number;
+		models: Record<string, { total_tokens: number; input_tokens: number; output_tokens: number }>;
+	};
+}
+
+export type GeminiStreamEvent =
+	| GeminiInitEvent
+	| GeminiMessageEvent
+	| GeminiToolUseEvent
+	| GeminiToolResultEvent
+	| GeminiErrorEvent
+	| GeminiResultEvent;
+
+// ── Internal types ─────────────────────────────────────────────────────────────
+
+export interface ToolCallRecord {
+	id: string;
+	name: string;
+	parameters: Record<string, unknown>;
+	status?: "success" | "error";
+	output?: string;
+}
+
+export interface GeminiProxyDetails {
+	sessionId?: string;
+	model?: string;
+	totalTokens?: number;
+	toolCalls: ToolCallRecord[];
+	streaming: boolean;
+	exitCode?: number;
+	filesInjected?: string[];
+	durationMs?: number;
+}