converse-mcp-server 2.27.0 → 2.28.0

package/src/providers/gemini-cli.js

@@ -1,81 +1,113 @@
 /**
- * Gemini CLI Provider
+ * Gemini CLI Provider (Antigravity CLI / agy subprocess)
  *
- * Provider implementation for Google's Gemini models using the ai-sdk-provider-gemini-cli package.
- * Implements the unified interface: async invoke(messages, options) => { content, stop_reason, rawResponse }
+ * Provider implementation for Google's Gemini models via the Antigravity CLI
+ * (`agy`, v1.0.7+) in print mode (`agy -p`), authenticated through the user's
+ * Antigravity Google OAuth login. Replaces the previous
+ * `ai-sdk-provider-gemini-cli` implementation, whose OAuth credentials Google
+ * sunsets on 2026-06-18.
  *
- * Key features:
- * - Uses OAuth authentication from Gemini CLI (no API keys needed)
- * - Supports gemini-3-pro-preview model via Google Cloud Code endpoints
- * - Uses AI SDK v6 standard interfaces (generateText/streamText)
- * - Compatible with both chat and consensus tools
+ * Architecture: one-shot subprocess wrapper. Each invoke() serializes the full
+ * messages array into a single prompt, spawns `agy` under a pseudo-terminal,
+ * collects the printed response, and returns it. A PTY is REQUIRED: agy print
+ * mode silently drops stdout in any non-TTY context (upstream bug
+ * google-antigravity/antigravity-cli#76, unfixed as of v1.0.7).
  *
  * Authentication:
- * - Requires global Gemini CLI installation: npm install -g @google/gemini-cli
- * - User must authenticate once via: gemini (interactive CLI)
- * - Credentials stored in ~/.gemini/oauth_creds.json
+ * - Requires the Antigravity CLI (`agy`) installed and authenticated once
+ *   interactively (`agy`) via Google OAuth. The first interactive login also
+ *   establishes workspace trust for the user's home directory.
+ *
+ * The provider registry key remains 'gemini-cli' and the user-facing alias
+ * remains 'gemini' for routing/normalization stability. Only three user-facing
+ * model names are exposed: gemini (= gemini:pro), gemini:pro, gemini:flash.
  */
 
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, delimiter } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
 
-// Supported Gemini CLI models with their configurations
+// Prompts at or below this length pass directly as the -p argv value (fast
+// path). Larger prompts are written to a file and -p carries a bootstrap
+// instruction. Keeps argv well under the Windows 32,767-char CreateProcess
+// ceiling (error 206).
+const ARGV_PROMPT_LIMIT = 24000;
+
+// Default print timeout (ms) when the tool layer passes none.
+const DEFAULT_TIMEOUT_MS = 600000;
+
+// Extra wall-clock grace before the JS-side hard kill fires (ms).
+const HARD_KILL_GRACE_MS = 15000;
+
+// After pty.kill(), force-settle if onExit never fires (ms).
+const POST_KILL_GRACE_MS = 5000;
+
+// PTY width: wide enough that response lines rarely soft-wrap (soft-wrap inserts
+// \r\n indistinguishable from real newlines). rows are irrelevant in print mode.
+const PTY_COLS = 1000;
+
+/**
+ * Supported Gemini models. Only three user-facing names are exposed; each maps
+ * to an agy display-name base that gets a reasoning-effort suffix appended at
+ * spawn time. All are text-only (print mode has no image input channel).
+ */
 const SUPPORTED_MODELS = {
   gemini: {
     modelName: 'gemini',
-    friendlyName: 'Gemini 3.5 Flash (via CLI)',
-    contextWindow: 1048576, // 1M tokens
+    friendlyName: 'Gemini 3.1 Pro (via Antigravity CLI)',
+    contextWindow: 1048576,
+    maxOutputTokens: 65536,
+    supportsStreaming: true,
+    supportsImages: false,
+    supportsTemperature: false,
+    supportsWebSearch: false,
+    supportsThinking: true,
+    timeout: DEFAULT_TIMEOUT_MS,
+    description:
+      'Gemini 3.1 Pro via Antigravity CLI (agy) - requires Antigravity Google OAuth login',
+    aliases: ['gemini-cli'],
+    // agy display-name base; reasoning_effort selects the parenthesized variant
+    agyModelBase: 'Gemini 3.1 Pro',
+  },
+  'gemini:pro': {
+    modelName: 'gemini:pro',
+    friendlyName: 'Gemini 3.1 Pro (via Antigravity CLI)',
+    contextWindow: 1048576,
     maxOutputTokens: 65536,
     supportsStreaming: true,
-    supportsImages: true, // Base64 only (no URLs)
-    supportsTemperature: true,
+    supportsImages: false,
+    supportsTemperature: false,
+    supportsWebSearch: false,
     supportsThinking: true,
-    supportsWebSearch: true,
-    timeout: 600000, // 10 minutes
+    timeout: DEFAULT_TIMEOUT_MS,
     description:
-      'Gemini 3.5 Flash via OAuth - frontier agentic/coding at Flash speed (requires Gemini CLI authentication)',
-    aliases: [
-      'gemini-cli',
-      'gemini-3.5-flash',
-      'gemini-3.5',
-      'gemini3.5',
-      'flash',
-      'flash-3.5',
-      'gemini-flash',
-      'gemini-flash-3.5',
-    ],
-    // Internal SDK model name passed to the Google Cloud Code endpoint
-    sdkModelName: 'gemini-3.5-flash',
+      'Gemini 3.1 Pro via Antigravity CLI (agy) - explicit alias of `gemini`',
+    aliases: [],
+    agyModelBase: 'Gemini 3.1 Pro',
   },
-  'gemini-3.1-pro-preview': {
-    modelName: 'gemini-3.1-pro-preview',
-    friendlyName: 'Gemini 3.1 Pro Preview (via CLI)',
-    contextWindow: 1048576, // 1M tokens
-    maxOutputTokens: 64000,
+  'gemini:flash': {
+    modelName: 'gemini:flash',
+    friendlyName: 'Gemini 3.5 Flash (via Antigravity CLI)',
+    contextWindow: 1048576,
+    maxOutputTokens: 65536,
     supportsStreaming: true,
-    supportsImages: true, // Base64 only (no URLs)
-    supportsTemperature: true,
+    supportsImages: false,
+    supportsTemperature: false,
+    supportsWebSearch: false,
     supportsThinking: true,
-    supportsWebSearch: true,
-    timeout: 600000, // 10 minutes
+    timeout: DEFAULT_TIMEOUT_MS,
     description:
-      'Gemini 3.1 Pro Preview via OAuth - requires Gemini CLI authentication',
-    aliases: [
-      'gemini-3.1-pro',
-      'gemini-3.1',
-      'gemini-pro',
-      'gemini-3-pro',
-      'pro',
-    ],
-    sdkModelName: 'gemini-3.1-pro-preview',
+      'Gemini 3.5 Flash via Antigravity CLI (agy) - requires Antigravity Google OAuth login',
+    aliases: ['flash'],
+    agyModelBase: 'Gemini 3.5 Flash',
   },
 };
 
 /**
- * Custom error class for Gemini CLI provider errors
+ * Custom error class for Gemini CLI (agy) provider errors
  */
 class GeminiCliProviderError extends ProviderError {
   constructor(message, code, originalError = null) {
@@ -84,484 +116,679 @@ class GeminiCliProviderError extends ProviderError {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit testing)
+// ---------------------------------------------------------------------------
+
+let _cachedAgyPath; // undefined = not probed; null = probed, not found
+
 /**
- * Check if OAuth credentials file exists
- * @returns {boolean} True if credentials file exists
+ * Locate the agy binary: PATH first, then the platform install fallback.
+ * Result is cached at module level (null cached if not found).
+ * @returns {string|null} Absolute path to agy, or null if not found
  */
-function hasOAuthCredentials() {
-  try {
-    const credsPath = join(homedir(), '.gemini', 'oauth_creds.json');
-    return existsSync(credsPath);
-  } catch (error) {
-    debugError('[Gemini CLI] Error checking OAuth credentials', error);
-    return false;
+export function findAgyBinary() {
+  if (_cachedAgyPath !== undefined) {
+    return _cachedAgyPath;
   }
-}
 
-/**
- * Dynamically import Gemini CLI SDK (lazy loading)
- * This keeps the SDK as an optional dependency
- */
-async function getGeminiCliSDK() {
+  const isWindows = process.platform === 'win32';
+  const exe = isWindows ? 'agy.exe' : 'agy';
+
+  // 1. PATH lookup
+  const pathEnv = process.env.PATH || process.env.Path || '';
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir) continue;
+    try {
+      const candidate = join(dir, exe);
+      if (existsSync(candidate)) {
+        _cachedAgyPath = candidate;
+        return _cachedAgyPath;
+      }
+    } catch {
+      // ignore malformed PATH entries
+    }
+  }
+
+  // 2. Platform install fallback
   try {
-    // Use dynamic import to load SDK only when needed
-    const { createGeminiProvider } = await import('ai-sdk-provider-gemini-cli');
-    return createGeminiProvider;
-  } catch (error) {
-    throw new GeminiCliProviderError(
-      'Gemini CLI SDK not installed. Install with: npm install ai-sdk-provider-gemini-cli',
-      'GEMINI_CLI_NOT_INSTALLED',
-      error,
-    );
+    if (isWindows) {
+      const localAppData =
+        process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+      const candidate = join(localAppData, 'agy', 'bin', 'agy.exe');
+      if (existsSync(candidate)) {
+        _cachedAgyPath = candidate;
+        return _cachedAgyPath;
+      }
+    } else {
+      const candidate = join(homedir(), '.local', 'bin', 'agy');
+      if (existsSync(candidate)) {
+        _cachedAgyPath = candidate;
+        return _cachedAgyPath;
+      }
+    }
+  } catch {
+    // ignore
   }
+
+  _cachedAgyPath = null;
+  return _cachedAgyPath;
 }
 
 /**
- * Dynamically import AI SDK (lazy loading)
+ * Map a reasoning_effort value to the agy parenthesized variant suffix.
+ * Flash supports Low/Medium/High; Pro supports Low/High (no Medium).
+ * @param {string} base - agy model base ('Gemini 3.5 Flash' / 'Gemini 3.1 Pro')
+ * @param {string} [reasoningEffort]
+ * @returns {string} e.g. '(Low)', '(Medium)', '(High)'
  */
-async function getAISDK() {
-  try {
-    const { generateText, streamText } = await import('ai');
-    return { generateText, streamText };
-  } catch (error) {
-    throw new GeminiCliProviderError(
-      'AI SDK not installed. Install with: npm install ai',
-      'AI_SDK_NOT_INSTALLED',
-      error,
-    );
+function effortSuffix(base, reasoningEffort) {
+  const isPro = /pro/i.test(base);
+  const effort = (reasoningEffort || '').toLowerCase();
+
+  switch (effort) {
+  case 'none':
+  case 'minimal':
+  case 'low':
+    return '(Low)';
+  case 'medium':
+    // Pro has no Medium variant — fall back to High
+    return isPro ? '(High)' : '(Medium)';
+  case 'high':
+  case 'max':
+    return '(High)';
+  default:
+    // unset → High
+    return '(High)';
   }
 }
 
 /**
- * Create stream generator for Gemini CLI streaming responses
- * Yields normalized events compatible with ProviderStreamNormalizer
+ * Resolve a user-facing model name + reasoning_effort to the agy display name
+ * passed via --model. Strips the gemini: prefix (case-insensitive), maps the
+ * alias, and appends the effort suffix. Full agy display names pass through
+ * verbatim so power users aren't blocked.
+ * @param {string} model - e.g. 'gemini', 'gemini:flash', or a full agy name
+ * @param {string} [reasoningEffort]
+ * @returns {string} agy --model value, e.g. 'Gemini 3.1 Pro (High)'
  */
-async function* createStreamingGenerator(
-  modelInstance,
-  messages,
-  options,
-  signal,
-  userFacingModelName = 'gemini',
-) {
-  const { streamText } = await getAISDK();
+export function resolveAgyModel(model, reasoningEffort) {
+  const raw = typeof model === 'string' ? model.trim() : '';
 
-  try {
-    const streamOptions = {
-      model: modelInstance,
-      messages,
-      ...options,
-    };
+  // Full agy display-name passthrough (already contains a parenthesized variant)
+  if (/\(.*\)\s*$/.test(raw) && /gemini/i.test(raw)) {
+    return raw;
+  }
 
-    if (signal) {
-      streamOptions.abortSignal = signal;
-    }
+  let name = raw;
+  if (name.toLowerCase().startsWith('gemini:')) {
+    name = name.slice('gemini:'.length).trim();
+  }
 
-    const result = await streamText(streamOptions);
+  const nameLower = name.toLowerCase();
+
+  // Determine the agy base
+  let base;
+  if (
+    !nameLower ||
+    nameLower === 'gemini' ||
+    nameLower === 'gemini-cli' ||
+    nameLower === 'pro'
+  ) {
+    base = SUPPORTED_MODELS.gemini.agyModelBase;
+  } else if (nameLower === 'flash') {
+    base = SUPPORTED_MODELS['gemini:flash'].agyModelBase;
+  } else {
+    // Unknown suffix: pass through verbatim (power-user agy display name)
+    return raw;
+  }
 
-    // Yield start event
-    yield {
-      type: 'start',
-      provider: 'gemini-cli',
-      model: userFacingModelName,
-    };
+  return `${base} ${effortSuffix(base, reasoningEffort)}`;
+}
 
-    // Stream text chunks
-    for await (const chunk of result.textStream) {
-      // Check for cancellation
-      if (signal?.aborted) {
-        throw new GeminiCliProviderError('Request cancelled', 'CANCELLED');
-      }
+/**
+ * Serialize the full messages array into a single role-labeled prompt string.
+ * System message becomes a <system> preamble; prior turns render as
+ * User:/Assistant: blocks; ends with an instruction to answer the final user
+ * message directly without role labels. Throws on image content parts.
+ * @param {Array} messages - Converse-format messages
+ * @returns {string}
+ */
+export function buildPrompt(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new GeminiCliProviderError(
+      'Messages must be a non-empty array',
+      ErrorCodes.INVALID_MESSAGES,
+    );
+  }
 
-      // Yield delta event with content chunk (normalized format)
-      yield {
-        type: 'delta',
-        data: {
-          textDelta: chunk,
-        },
-      };
+  const renderContent = (content) => {
+    if (typeof content === 'string') {
+      return content;
     }
-
-    // Get final usage stats and metadata
-    const usage = await result.usage;
-    const finishReason = await result.finishReason;
-
-    // Yield usage event
-    if (usage) {
-      const tokens = extractUsageTokens(usage);
-      yield {
-        type: 'usage',
-        usage: {
-          input_tokens: tokens.input,
-          output_tokens: tokens.output,
-          total_tokens: tokens.total,
-          cached_input_tokens: 0,
-        },
-      };
+    if (Array.isArray(content)) {
+      const parts = [];
+      for (const part of content) {
+        if (part?.type === 'image') {
+          throw new GeminiCliProviderError(
+            'Images are not supported by the gemini provider (Antigravity CLI print mode has no image input channel)',
+            ErrorCodes.INVALID_REQUEST,
+          );
+        }
+        if (part?.type === 'text' && typeof part.text === 'string') {
+          parts.push(part.text);
+        }
+      }
+      return parts.join('\n');
     }
-
-    // Yield end event
-    yield {
-      type: 'end',
-      stop_reason: mapFinishReason(finishReason),
-      finish_reason: getRawFinishReason(finishReason),
-    };
-  } catch (error) {
-    if (signal?.aborted) {
-      throw new GeminiCliProviderError('Request cancelled', 'CANCELLED');
+    return '';
+  };
+
+  const systemParts = [];
+  const turns = [];
+
+  for (const message of messages) {
+    const role = message?.role;
+    const text = renderContent(message?.content);
+    if (role === 'system') {
+      if (text) systemParts.push(text);
+    } else if (role === 'assistant') {
+      turns.push(`Assistant: ${text}`);
+    } else {
+      // treat anything else (user/tool/unknown) as a user turn
+      turns.push(`User: ${text}`);
     }
-    throw error;
   }
+
+  const sections = [];
+  if (systemParts.length > 0) {
+    sections.push(`<system>\n${systemParts.join('\n\n')}\n</system>`);
+  }
+
+  if (turns.length > 1) {
+    sections.push(
+      'The following is a conversation transcript. Read the full transcript, then write the assistant\'s next reply to the final User message. Respond directly without any role label.',
+    );
+    sections.push(turns.join('\n\n'));
+  } else {
+    // Single user turn — strip the label, just ask directly.
+    const onlyTurn = turns[0] || '';
+    sections.push(onlyTurn.replace(/^User:\s*/, ''));
+  }
+
+  return sections.join('\n\n');
 }
 
 /**
- * Map AI SDK v6 finish reasons to our StopReasons enum
- * AI SDK v6 returns finishReason as { unified: 'stop', raw: 'STOP' }
- * @param {Object|string} finishReason - The finish reason (object in v6, string in v5)
+ * Clean agy PTY output: strip ANSI escape sequences (CSI, OSC, charset
+ * selection), resolve carriage-return overwrites, trim trailing whitespace.
+ * Pure function so it can be unit-tested against captured raw output.
+ * @param {string} raw
+ * @returns {string}
  */
-function mapFinishReason(finishReason) {
-  // AI SDK v6 returns an object with 'unified' property
-  const reason =
-    typeof finishReason === 'object' ? finishReason?.unified : finishReason;
-
-  switch (reason) {
-  case 'stop':
-    return StopReasons.STOP;
-  case 'length':
-  case 'max-tokens':
-    return StopReasons.LENGTH;
-  case 'content-filter':
-    return StopReasons.CONTENT_FILTER;
-  case 'tool-calls':
-    return StopReasons.TOOL_USE;
-  case 'error':
-    return StopReasons.ERROR;
-  default:
-    return StopReasons.OTHER;
+export function cleanAgyOutput(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return '';
   }
+
+  let s = raw;
+
+  // Strip OSC sequences: ESC ] ... terminated by BEL (\x07) or ST (ESC \).
+  s = s.replace(/\x1b\][\s\S]*?(?:\x07|\x1b\\)/g, '');
+
+  // Strip CSI sequences: ESC [ parameter-bytes (0x30-0x3F) intermediate-bytes
+  // (0x20-0x2F) final-byte (0x40-0x7E). Full grammar so truecolor / less common
+  // sequences don't leak their tail as text.
+  s = s.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+
+  // Strip charset selection (ESC ( X / ESC ) X) and other single-char escapes
+  // (ESC =, ESC >, and any remaining ESC + final byte).
+  s = s.replace(/\x1b[()][AB0-2]/g, '');
+  s = s.replace(/\x1b[=>]/g, '');
+  s = s.replace(/\x1b[@-Z\\-_]/g, '');
+
+  // Resolve carriage-return overwrites within each line: a lone \r (not part of
+  // a \r\n line break) means the cursor returned to column 0 and overwrote.
+  // Normalize CRLF first so we only handle bare CRs.
+  s = s.replace(/\r\n/g, '\n');
+  s = s
+    .split('\n')
+    .map((line) => {
+      if (!line.includes('\r')) return line;
+      // Last CR-delimited segment wins (spinner frames overwrite each other)
+      const segments = line.split('\r');
+      return segments[segments.length - 1];
+    })
+    .join('\n');
+
+  // Strip any remaining lone control chars (BEL, etc.) except tab and newline.
+  s = s.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+
+  // Trim trailing whitespace/newlines
+  return s.replace(/\s+$/, '');
 }
 
+// ---------------------------------------------------------------------------
+// Subprocess runner
+// ---------------------------------------------------------------------------
+
 /**
- * Extract raw finish reason string for metadata
- * AI SDK v6 returns finishReason as { unified: 'stop', raw: 'STOP' }
- * @param {Object|string} finishReason - The finish reason
- * @returns {string} The raw finish reason string
+ * Lazily import @lydell/node-pty. Kept lazy so the module loads even when the
+ * native binary is unavailable (e.g. unit tests that mock the layer).
  */
-function getRawFinishReason(finishReason) {
-  if (typeof finishReason === 'object') {
-    return finishReason?.unified || finishReason?.raw || 'stop';
+async function getPty() {
+  try {
+    const mod = await import('@lydell/node-pty');
+    return mod.default || mod;
+  } catch (error) {
+    throw new GeminiCliProviderError(
+      '@lydell/node-pty is not installed. Run: pnpm add @lydell/node-pty',
+      ErrorCodes.API_ERROR,
+      error,
+    );
   }
-  return finishReason || 'stop';
 }
 
 /**
- * Extract usage tokens from AI SDK v6 hierarchical structure
- * AI SDK v6 usage: { inputTokens: { total: N }, outputTokens: { total: N } }
- * AI SDK v5 usage: { promptTokens: N, completionTokens: N, totalTokens: N }
- * @param {Object} usage - The usage object from AI SDK
- * @returns {Object} Normalized token counts
+ * Spawn agy under a PTY, deliver the prompt, collect output, resolve on exit.
+ *
+ * @param {object} params
+ * @param {string} params.prompt - Fully serialized prompt
+ * @param {string} params.model - Resolved agy --model value
+ * @param {number} params.timeoutMs - Print timeout in ms
+ * @param {AbortSignal} [params.signal]
+ * @param {object} [params.ptyLib] - Injected pty module (tests)
+ * @param {string} [params.agyPath] - Override binary path (tests)
+ * @returns {Promise<{output: string, exitCode: number}>}
  */
-function extractUsageTokens(usage) {
-  if (!usage) {
-    return { input: 0, output: 0, total: 0 };
+export async function runAgy({
+  prompt,
+  model,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  signal,
+  ptyLib,
+  agyPath,
+}) {
+  const binary = agyPath || findAgyBinary();
+  if (!binary) {
+    throw new GeminiCliProviderError(
+      'Antigravity CLI (agy) not found. Install it and run `agy` once to log in (https://antigravity.google)',
+      ErrorCodes.MISSING_API_KEY,
+    );
   }
 
-  // AI SDK v6 hierarchical structure
-  if (usage.inputTokens && typeof usage.inputTokens === 'object') {
-    const input = usage.inputTokens.total || 0;
-    const output = usage.outputTokens?.total || 0;
-    return { input, output, total: input + output };
+  if (signal?.aborted) {
+    throw new GeminiCliProviderError('Request cancelled', 'CANCELLED');
   }
 
-  // AI SDK flat structure (backwards compatibility)
-  const input = usage.promptTokens || usage.inputTokens || 0;
-  const output = usage.completionTokens || usage.outputTokens || 0;
-  const total = usage.totalTokens || input + output;
-  return { input, output, total };
-}
+  const pty = ptyLib || (await getPty());
 
-/**
- * Convert messages from Converse internal format to AI SDK ModelMessage format
- *
- * Converse format (used by other providers like Anthropic):
- * - Images: { type: 'image', source: { type: 'base64', media_type: '...', data: '...' } }
- *
- * AI SDK ModelMessage format (required by generateText/streamText):
- * - Images: { type: 'image', image: '...' }  (base64 string, Buffer, or URL)
- * - Text: { type: 'text', text: '...' }
- *
- * Note: The AI SDK validates ModelMessage format before passing to providers.
- * We must use 'image' property (not 'data') for the AI SDK to accept the message.
- *
- * @param {Array} messages - Messages in Converse internal format
- * @returns {Array} Messages in AI SDK ModelMessage format
- */
-function convertToModelMessages(messages) {
-  return messages.map((message) => {
-    // If content is a string, no conversion needed
-    if (typeof message.content === 'string') {
-      return message;
+  // Per-call cwd under HOME (covered by agy workspace trust on first login).
+  // On POSIX, restrict the dir to the owner (0700) since it may hold prompt.md.
+  const runId = randomUUID();
+  let runDir = join(homedir(), '.converse', 'agy-runs', runId);
+  const mkOpts =
+    process.platform === 'win32'
+      ? { recursive: true }
+      : { recursive: true, mode: 0o700 };
+  try {
+    mkdirSync(runDir, mkOpts);
+  } catch (error) {
+    // Fall back to a per-call dir under tmpdir if HOME isn't writable. Still a
+    // unique dir (never a bare tmpdir) so concurrent calls don't collide and
+    // cleanup still applies.
+    debugError(
+      '[Gemini CLI] Failed to create run dir, falling back to tmp',
+      error,
+    );
+    runDir = join(tmpdir(), 'converse-agy-runs', runId);
+    try {
+      mkdirSync(runDir, mkOpts);
+    } catch (fallbackErr) {
+      throw new GeminiCliProviderError(
+        `Failed to create agy run directory: ${fallbackErr.message}`,
+        ErrorCodes.API_ERROR,
+        fallbackErr,
+      );
     }
+  }
+  // Decide prompt delivery: argv (fast) vs file (large-prompt bootstrap).
+  let promptArg;
+  if (prompt.length > ARGV_PROMPT_LIMIT) {
+    const promptFile = join(runDir, 'prompt.md');
+    // 0600 on POSIX — prompt may contain sensitive context.
+    const writeOpts =
+      process.platform === 'win32'
+        ? { encoding: 'utf8' }
+        : { encoding: 'utf8', mode: 0o600 };
+    writeFileSync(promptFile, prompt, writeOpts);
+    // Reference the absolute path to minimize the agent's file-search flailing.
+    promptArg = `Read the file located at ${promptFile} and respond to its contents directly. Do not summarize the file; answer it.`;
+  } else {
+    promptArg = prompt;
+  }
 
-    // If content is an array, convert each part
-    if (Array.isArray(message.content)) {
-      const convertedContent = message.content.map((part) => {
-        // Text parts are already in correct format
-        if (part.type === 'text') {
-          return part;
-        }
+  const timeoutSeconds = Math.ceil(timeoutMs / 1000);
+  // --sandbox is intentionally omitted: it blocks the large-prompt file read in
+  // print mode (verified 2026-06-10 — agy times out unable to read prompt.md).
+  const args = [
+    '-p',
+    promptArg,
+    '--model',
+    model,
+    '--print-timeout',
+    `${timeoutSeconds}s`,
+  ];
+
+  return new Promise((resolve, reject) => {
+    let child;
+    let output = '';
+    let settled = false;
+    // Set when abort/timeout has requested termination. Once set, a subsequent
+    // onExit (which kill() may fire synchronously) must NOT resolve as a normal
+    // exit — the termination error wins.
+    let terminationError = null;
+    let hardTimer = null;
+    let postKillTimer = null;
+    let onDataSub = null;
+    let onExitSub = null;
+
+    const cleanup = () => {
+      if (hardTimer) {
+        clearTimeout(hardTimer);
+        hardTimer = null;
+      }
+      if (postKillTimer) {
+        clearTimeout(postKillTimer);
+        postKillTimer = null;
+      }
+      if (signal) {
+        signal.removeEventListener('abort', onAbort);
+      }
+      try {
+        onDataSub?.dispose?.();
+      } catch {
+        /* ignore */
+      }
+      try {
+        onExitSub?.dispose?.();
+      } catch {
+        /* ignore */
+      }
+      // Best-effort run-dir cleanup; never throw. On abort the killed process
+      // may still hold a handle on prompt.md (EBUSY), so retry once detached.
+      try {
+        rmSync(runDir, { recursive: true, force: true });
+      } catch (err) {
+        debugLog('[Gemini CLI] Run dir cleanup failed, retrying: %s', err?.message);
+        setTimeout(() => {
+          try {
+            rmSync(runDir, { recursive: true, force: true });
+          } catch (retryErr) {
+            debugLog(
+              '[Gemini CLI] Run dir cleanup retry failed: %s',
+              retryErr?.message,
+            );
+          }
+        }, 2000).unref?.();
+      }
+    };
 
-        // Convert image from Converse format to AI SDK ModelMessage format
-        if (part.type === 'image' && part.source) {
-          return {
-            type: 'image',
-            image: part.source.data, // AI SDK expects 'image' property (not 'data')
-          };
-        }
+    const settleResolve = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
 
-        // If already in AI SDK v5 format, return as-is
-        if (part.type === 'image' && part.image) {
-          return part;
-        }
+    const settleReject = (err) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
 
-        // Handle file parts (already in correct format)
-        if (part.type === 'file' && part.data) {
-          return part;
-        }
+    // Terminate the child for a known reason (abort/timeout). Records the error
+    // first so a synchronous onExit from kill() rejects rather than resolves,
+    // then schedules a post-kill grace timer so we never hang if onExit never
+    // fires.
+    const terminate = (err) => {
+      if (settled) return;
+      terminationError = err;
+      try {
+        child?.kill();
+      } catch (killErr) {
+        debugLog('[Gemini CLI] pty.kill() failed: %s', killErr?.message);
+      }
+      if (!postKillTimer) {
+        postKillTimer = setTimeout(() => {
+          settleReject(terminationError);
+        }, POST_KILL_GRACE_MS);
+      }
+    };
+
+    function onAbort() {
+      terminate(new GeminiCliProviderError('Request cancelled', 'CANCELLED'));
+    }
 
-        // Unknown part type, return as-is and let SDK handle it
-        debugLog(`[Gemini CLI] Unknown content part type: ${part.type}`);
-        return part;
+    try {
+      child = pty.spawn(binary, args, {
+        name: 'xterm-256color',
+        cols: PTY_COLS,
+        rows: 30,
+        cwd: runDir,
+        env: process.env,
       });
+    } catch (error) {
+      cleanup();
+      reject(
+        new GeminiCliProviderError(
+          `Failed to spawn agy: ${error.message}`,
+          ErrorCodes.API_ERROR,
+          error,
+        ),
+      );
+      return;
+    }
+
+    onDataSub = child.onData((data) => {
+      output += data;
+    });
+
+    onExitSub = child.onExit(({ exitCode }) => {
+      // If termination was requested, the abort/timeout error wins over a
+      // (possibly kill()-induced) exit.
+      if (terminationError) {
+        settleReject(terminationError);
+      } else {
+        settleResolve({ output, exitCode });
+      }
+    });
+
+    hardTimer = setTimeout(() => {
+      terminate(
+        new GeminiCliProviderError(
+          `Antigravity CLI (agy) timed out after ${timeoutMs}ms`,
+          ErrorCodes.TIMEOUT_ERROR,
+        ),
+      );
+    }, timeoutMs + HARD_KILL_GRACE_MS);
 
-      return {
-        ...message,
-        content: convertedContent,
-      };
+    if (signal) {
+      signal.addEventListener('abort', onAbort, { once: true });
+      // Guard the window between the early aborted-check and listener
+      // registration: if it aborted in between, the listener won't fire.
+      if (signal.aborted) {
+        onAbort();
+      }
     }
+  });
+}
 
-    // Unknown content type, return as-is
-    return message;
+/**
+ * Yield the passthrough event sequence for stream mode:
+ * start -> delta(fullText) -> usage(zeroed) -> end
+ */
+async function* createStreamingGenerator(fullText, userFacingModel) {
+  yield {
+    type: 'start',
+    provider: 'gemini-cli',
+    model: userFacingModel,
+  };
+  yield {
+    type: 'delta',
+    data: { textDelta: fullText },
+  };
+  yield {
+    type: 'usage',
+    usage: {
+      input_tokens: 0,
+      output_tokens: 0,
+      total_tokens: 0,
+      cached_input_tokens: 0,
+    },
+  };
+  yield {
+    type: 'end',
+    stop_reason: 'stop',
+    finish_reason: 'stop',
+  };
+}
+
+/**
+ * Run agy and return the cleaned response text, mapping failure modes to
+ * provider errors.
+ */
+async function executeAgy(messages, options) {
+  const { model = 'gemini', reasoning_effort, signal, timeout } = options;
+
+  const prompt = buildPrompt(messages);
+  const agyModel = resolveAgyModel(model, reasoning_effort);
+  const timeoutMs =
+    typeof timeout === 'number' && timeout > 0 ? timeout : DEFAULT_TIMEOUT_MS;
+
+  const { output, exitCode } = await runAgy({
+    prompt,
+    model: agyModel,
+    timeoutMs,
+    signal,
   });
+
+  const cleaned = cleanAgyOutput(output);
+
+  if (exitCode !== 0) {
+    const tail = cleaned.slice(-500);
+    throw new GeminiCliProviderError(
+      `Antigravity CLI (agy) exited with code ${exitCode}. ${tail ? `Output tail: ${tail}` : 'No output.'} If this persists, run \`agy\` interactively once to authenticate (Antigravity Google OAuth).`,
+      ErrorCodes.API_ERROR,
+    );
+  }
+
+  if (!cleaned) {
+    throw new GeminiCliProviderError(
+      'Antigravity CLI (agy) returned empty output. This usually means the CLI is not authenticated — run `agy` interactively once to authenticate (Antigravity Google OAuth). (See upstream bug google-antigravity/antigravity-cli#76 for the non-TTY case.)',
+      ErrorCodes.API_ERROR,
+    );
+  }
+
+  return cleaned;
 }
 
 /**
- * Gemini CLI Provider Implementation
+ * Gemini CLI (Antigravity) Provider Implementation
  */
 export const geminiCliProvider = {
   /**
-   * Invoke Gemini CLI with messages and options
+   * Invoke agy with messages and options.
    * @param {Array} messages - Message array (Converse format)
    * @param {Object} options - Invocation options
    * @returns {Promise<Object>|AsyncGenerator} Response or stream generator
    */
   async invoke(messages, options = {}) {
-    const {
-      model = 'gemini',
-      config,
-      stream = false,
-      signal,
-      reasoning_effort,
-      temperature,
-      use_websearch,
-    } = options;
-
-    // Validate configuration
-    if (!config) {
-      throw new GeminiCliProviderError(
-        'Configuration is required',
-        ErrorCodes.MISSING_API_KEY,
-      );
-    }
+    const { model = 'gemini', stream = false, signal } = options;
 
-    // Check OAuth credentials
-    if (!hasOAuthCredentials()) {
-      throw new GeminiCliProviderError(
-        'Gemini CLI authentication required. Run: gemini (interactive CLI) to authenticate',
-        ErrorCodes.INVALID_API_KEY,
-      );
+    if (signal?.aborted) {
+      throw new GeminiCliProviderError('Request cancelled', 'CANCELLED');
     }
 
-    try {
-      // Get model configuration to map user-facing name to SDK model name
-      const modelConfig = this.getModelConfig(model);
-      if (!modelConfig) {
-        throw new GeminiCliProviderError(
-          `Model ${model} not supported by Gemini CLI provider`,
-          ErrorCodes.MODEL_NOT_FOUND,
-        );
-      }
-
-      // Get the SDK model name (e.g., "gemini" -> "gemini-3-pro-preview")
-      const sdkModelName = modelConfig.sdkModelName || model;
-
-      // Get SDKs
-      const createGeminiProvider = await getGeminiCliSDK();
-      const { generateText } = await getAISDK();
-
-      // Create provider instance with OAuth authentication
-      const gemini = createGeminiProvider({
-        authType: 'oauth-personal',
-      });
-
-      // Create model instance with SDK model name
-      const modelInstance = gemini(sdkModelName);
-
-      // Convert messages from Converse format to AI SDK ModelMessage format
-      const convertedMessages = convertToModelMessages(messages);
-
-      // Build AI SDK options
-      const aiOptions = {
-        messages: convertedMessages,
-      };
-
-      // Add optional parameters
-      if (temperature !== undefined) {
-        aiOptions.temperature = temperature;
-      }
-
-      // Note: reasoning_effort and use_websearch are not directly supported by AI SDK
-      // These would need to be handled at the API level if the provider supports them
-      if (reasoning_effort !== undefined) {
-        debugLog(
-          '[Gemini CLI] Parameter "reasoning_effort" not directly supported (ignored)',
-        );
-      }
-      if (use_websearch) {
-        debugLog(
-          '[Gemini CLI] Parameter "use_websearch" not directly supported (ignored)',
-        );
-      }
-
-      // Streaming mode
-      if (stream) {
-        return createStreamingGenerator(
-          modelInstance,
-          convertedMessages,
-          aiOptions,
-          signal,
-          model, // Pass user-facing model name for metadata
-        );
-      }
-
-      // Synchronous mode
-      const startTime = Date.now();
-
-      const result = await generateText({
-        model: modelInstance,
-        ...aiOptions,
-        ...(signal && { abortSignal: signal }),
-      });
-
-      const responseTime = Date.now() - startTime;
-
-      // Extract content from AI SDK v6 response format
-      const content = result.content?.[0]?.text || result.text || '';
-
-      // Extract usage tokens with AI SDK v6 compatibility
-      const tokens = extractUsageTokens(result.usage);
-
-      return {
-        content,
-        stop_reason: mapFinishReason(result.finishReason),
-        rawResponse: result,
-        metadata: {
-          provider: 'gemini-cli',
-          model,
-          usage: result.usage
-            ? {
-              input_tokens: tokens.input,
-              output_tokens: tokens.output,
-              total_tokens: tokens.total,
-              cached_input_tokens: 0,
-            }
-            : null,
-          response_time_ms: responseTime,
-          finish_reason: getRawFinishReason(result.finishReason),
-        },
-      };
-    } catch (error) {
-      debugError('[Gemini CLI] Execution error', error);
-
-      // Map common errors to standard error codes
-      if (
-        error.message?.includes('authentication') ||
-        error.message?.includes('oauth') ||
-        error.message?.includes('credentials')
-      ) {
-        throw new GeminiCliProviderError(
-          'Gemini CLI authentication failed. Run: gemini (interactive CLI) to authenticate',
-          ErrorCodes.INVALID_API_KEY,
-          error,
-        );
-      }
-
-      if (error.message?.includes('rate limit')) {
-        throw new GeminiCliProviderError(
-          'Rate limit exceeded',
-          ErrorCodes.RATE_LIMIT_EXCEEDED,
-          error,
-        );
-      }
-
-      if (error.message?.includes('timeout')) {
-        throw new GeminiCliProviderError(
-          'Request timeout',
-          ErrorCodes.TIMEOUT_ERROR,
-          error,
-        );
-      }
-
-      // Re-throw as Gemini CLI error
-      throw new GeminiCliProviderError(
-        error.message || 'Gemini CLI execution failed',
-        ErrorCodes.API_ERROR,
-        error,
-      );
+    if (stream) {
+      // Run agy first (one-shot), then replay as a passthrough stream.
+      const fullText = await executeAgy(messages, options);
+      return createStreamingGenerator(fullText, model);
     }
+
+    const startTime = Date.now();
+    const content = await executeAgy(messages, options);
+    const responseTime = Date.now() - startTime;
+
+    return {
+      content,
+      stop_reason: StopReasons.STOP,
+      rawResponse: { content },
+      metadata: {
+        provider: 'gemini-cli',
+        model,
+        usage: null,
+        response_time_ms: responseTime,
+        finish_reason: 'stop',
+      },
+    };
   },
 
   /**
-   * Validate Gemini CLI configuration
-   * Gemini CLI uses OAuth authentication (no API keys needed)
+   * Validate configuration. agy uses OAuth (no env keys); always true.
+   * Availability is determined by isAvailable (binary presence).
    */
   validateConfig(_config) {
-    // Check if OAuth credentials file exists
-    return hasOAuthCredentials();
+    return true;
   },
 
   /**
-   * Check if Gemini CLI provider is available
+   * Check if the provider is available (agy binary present).
    */
-  isAvailable(config) {
-    return this.validateConfig(config);
+  isAvailable(_config) {
+    return findAgyBinary() !== null;
   },
 
   /**
-   * Get supported Gemini CLI models
+   * Get supported Gemini models.
    */
   getSupportedModels() {
     return SUPPORTED_MODELS;
   },
 
   /**
-   * Get model configuration for specific model
+   * Get model configuration for a specific model (alias-aware, prefix-aware).
    */
   getModelConfig(modelName) {
-    const modelNameLower = modelName.toLowerCase();
+    if (typeof modelName !== 'string') return null;
+
+    const name = modelName.toLowerCase().trim();
 
-    // Check exact match
-    if (SUPPORTED_MODELS[modelNameLower]) {
-      return SUPPORTED_MODELS[modelNameLower];
+    // Full agy display-name passthrough → matching base config.
+    if (/gemini 3\.5 flash/i.test(modelName)) {
+      return SUPPORTED_MODELS['gemini:flash'];
+    }
+    if (/gemini 3\.1 pro/i.test(modelName)) {
+      return SUPPORTED_MODELS.gemini;
     }
 
-    // Check aliases
-    for (const [supportedModel, config] of Object.entries(SUPPORTED_MODELS)) {
-      if (config.aliases) {
-        for (const alias of config.aliases) {
-          if (alias.toLowerCase() === modelNameLower) {
-            return config;
-          }
-        }
+    if (name === 'pro') {
+      return SUPPORTED_MODELS['gemini:pro'];
+    }
+
+    // Exact key match (gemini, gemini:pro, gemini:flash)
+    if (SUPPORTED_MODELS[name]) {
+      return SUPPORTED_MODELS[name];
+    }
+
+    // Alias match
+    for (const config of Object.values(SUPPORTED_MODELS)) {
+      if (
+        config.aliases &&
+        config.aliases.some((alias) => alias.toLowerCase() === name)
+      ) {
+        return config;
       }
     }