llm-cli-gateway 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.6.0] - 2026-06-12: Gemini provider on Google Antigravity CLI
+
+### Changed
+
+- **Gemini provider now runs through Google Antigravity CLI (`agy`)** instead of
+  the Google Gemini CLI. `gemini_request` / `gemini_request_async` spawn `agy`;
+  install via `curl -fsSL https://antigravity.google/cli/install.sh | bash`;
+  upgrade via `agy update` (explicit version targets unsupported); session resume
+  via `--conversation <id>` (`sessionId`) or `--continue` (`resumeLatest`). Models
+  pass to `agy --model` (e.g. `gemini-3-pro-preview`, `gemini-2.5-flash`, `pro`,
+  `flash`, `latest`).
+- `gemini_request` parameter surface tightened to Antigravity's capabilities:
+  `approvalMode` accepts only `default` and `yolo` (`auto_edit`/`plan` are
+  rejected); `allowedTools`, `mcpServers`, non-`text` `outputFormat`,
+  `policyFiles`, `adminPolicyFiles`, `attachments`, and `skipTrust` are rejected
+  with an explanatory error (retained in the schema for caller parity).
+  `includeDirs` (`--add-dir`) and `sandbox` (`--sandbox`) remain supported.
+- Customer-facing documentation (README, the llm-cli-gateway.dev site, install
+  guide, dev.to tutorial) and the MCP server instructions string updated to match
+  the Antigravity-backed behavior. Verified by a four-reviewer cross-LLM evidence
+  gate (Codex/Gemini/Grok/Mistral); see
+  `docs/reviews/2026-06-12-customer-docs-antigravity.*`.
+
+### Added
+
+- Reply text is mirrored into MCP `structuredContent.response` on provider tool
+  responses (Issue #1), alongside the unchanged `content[0].text`.
+- Contract-driven code generation for the Grok provider's argv and tool schema
+  (`src/provider-codegen.ts`), proven byte-identical to the prior hand-written
+  surface by golden/parity tests.
+- Async-job stall telemetry (Issue #21).
+
+### Upstream provider maintenance
+
+- Grok Build v0.2.38: local binary upgraded from 0.2.33; full `--probe-installed` contract + subcommand drift scan executed (live source fetch performed in the run that produced the referenced report). 40 top-level flags + 23 subcommand paths all clean (`extraVsContract: []`, `missingFromBinary: []` across the board per the snapshot). Refreshed `docs/upstream/snapshots/grok.json` (new help surface hash capturing 0.2.38 agent subcommand surface) and `docs/upstream/reports/2026-06-09-grok.md`. `UPSTREAM_CLI_CONTRACTS.grok` now has 18 conformance fixtures (added `grok-0.2.38-agent-surface` as a dated top-level example); no flag, enum, arity, permission-mode, sandbox, output-format, or resume-behaviour changes to encode in the primary contract. `npm run upstream:contracts` and targeted grok/upstream tests pass. (Cross-LLM reviews from Claude and Codex independently reproduced the diff, commands, and fixture behaviour via their own tool inspections of the sources.)
+
 ## [2.5.0] - 2026-06-08: Remote connector OAuth and workspaces
 
 - Added remote connector OAuth discovery and authorization-code support with

package/README.md

@@ -235,11 +235,13 @@ npm install -g @openai/codex
 codex login
 ```
 
-### Gemini CLI
+### Gemini (Google Antigravity CLI)
+
+The Gemini provider runs through Google Antigravity CLI (`agy`).
 
 ```bash
-npm install -g @google/gemini-cli
-# Or: https://github.com/google-gemini/gemini-cli
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+# Docs: https://antigravity.google/docs/cli-overview
 ```
 
 ### Grok Build CLI (xAI)
@@ -477,7 +479,7 @@ Fork an existing Codex session into a new branch (`codex fork <SESSION_ID|--last
 
 ##### `gemini_request`
 
-Execute a Gemini CLI request with session support.
+Execute a Google Antigravity CLI (`agy`) request with session support.
 
 **Parameters:**
 
@@ -486,18 +488,14 @@ Execute a Gemini CLI request with session support.
 - `sessionId` (string, optional): Session ID to resume
 - `resumeLatest` (boolean, optional): Resume the latest session automatically
 - `createNewSession` (boolean, optional): Always create a new session
-- `approvalMode` (string, optional): Gemini approval mode (`default|auto_edit|yolo|plan`) in legacy mode
+- `approvalMode` (string, optional): Antigravity approval mode in legacy mode. Only `default` (prompted execution) and `yolo` (emits `--dangerously-skip-permissions`) are accepted; `auto_edit` and `plan` are rejected with an error.
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
-- `mcpServers` (string[], optional): Allowed Gemini MCP server names
-- `allowedTools` (string[], optional): Restrict Gemini tools to this allow-list
-- `includeDirs` (string[], optional): Additional workspace directories for Gemini
-- `outputFormat` (string, optional): `text` (default), `json` (`-o json`), or `stream-json` (`-o stream-json`, NDJSON with usage extraction)
-- `sandbox` (boolean, optional): Run Gemini in sandbox mode (`-s`)
-- `policyFiles` / `adminPolicyFiles` (string[], optional): Policy / admin-policy file paths (one `--policy`/`--admin-policy` per file; paths must exist)
-- `attachments` (string[], optional): Absolute file paths prepended as `@<path>` tokens to the prompt
-- `skipTrust` (boolean, optional): Emit `--skip-trust` to trust the workspace for this session (required for headless runs in fresh workspaces)
-- `yolo` (boolean, optional): Auto-approve all; equivalent to `approvalMode: "yolo"`. Emits `--yolo` only when `--approval-mode yolo` is not already being emitted (never both)
+- `includeDirs` (string[], optional): Additional workspace directories (passed as `--add-dir`)
+- `sandbox` (boolean, optional): Run Antigravity in sandbox mode (`--sandbox`)
+- `outputFormat` (string, optional): `text` only. Antigravity print mode emits text; `json` and `stream-json` are rejected.
+- `mcpServers`, `allowedTools`, `policyFiles`, `adminPolicyFiles`, `attachments` (string[], optional) and `skipTrust` (boolean, optional): **Unsupported by Antigravity CLI** — non-empty values (or `skipTrust: true`) are rejected with an explanatory error. Retained in the schema for caller parity.
+- `yolo` (boolean, optional): Auto-approve all; equivalent to `approvalMode: "yolo"`. Emits `--dangerously-skip-permissions`
 - `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
 - `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency, default: false
@@ -1046,7 +1044,7 @@ Plan or run an upgrade for one CLI.
 - Claude explicit target: `claude install <target>`
 - Codex latest: `codex update`
 - Codex explicit target: `npm install -g @openai/codex@<target>`
-- Gemini: `npm install -g @google/gemini-cli@<target>`
+- Gemini latest: `agy update` (Antigravity self-update; explicit version targets are unsupported)
 - Grok latest: `grok update`
 - Grok explicit target: `grok update --version <target>`
 - Mistral (Vibe): dispatches to the detected installer (`pip`/`uv`/`brew`); errors with guidance when none is detected (Vibe ships no self-update command)
@@ -1236,7 +1234,7 @@ Make sure the CLIs are installed and in your PATH:
 ```bash
 which claude
 which codex
-which gemini
+which agy
 ```
 
 The gateway extends PATH to include common locations:
@@ -1253,7 +1251,7 @@ If you encounter permission errors, ensure the CLI tools have proper permissions
 ```bash
 chmod +x $(which claude)
 chmod +x $(which codex)
-chmod +x $(which gemini)
+chmod +x $(which agy)
 ```
 
 ### Session Storage Issues
@@ -1306,7 +1304,7 @@ If you're vetting `llm-cli-gateway` through [Socket](https://socket.dev/npm/pack
 | Alert                            | Where                                                                                                                                                                                            | Why it's bounded                                                                                                                                                                                                                                                                                                                                             |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Network access**               | `src/http-transport.ts` opens an HTTP MCP transport when started via `npm run start:http`. `src/endpoint-exposure.ts` issues a HEAD probe to verify configured public/tunnel URLs. Socket also flagged `dist/upstream-contracts.js` in v1.17.2 from descriptive text, not a network call. | The transport binds to `127.0.0.1` by default and requires `LLM_GATEWAY_AUTH_TOKEN` to be set. The default stdio MCP entry point (`npm start`) opens no sockets. `src/upstream-contracts.ts` stores provider CLI metadata and imports no HTTP client APIs.                                                                                                  |
-| **Shell access**                 | `src/executor.ts` uses `child_process.spawn(cmd, args, …)` to invoke the underlying LLM CLIs.                                                                                                    | `spawn` is called with an argument array and **never** `shell: true`, so there is no shell interpolation path for caller input. The command name is restricted to an allow-list of known CLI binaries (`claude`, `codex`, `gemini`, `grok`, `vibe`).                                                                                                         |
+| **Shell access**                 | `src/executor.ts` uses `child_process.spawn(cmd, args, …)` to invoke the underlying LLM CLIs.                                                                                                    | `spawn` is called with an argument array and **never** `shell: true`, so there is no shell interpolation path for caller input. The command name is restricted to an allow-list of known CLI binaries (`claude`, `codex`, `agy`, `grok`, `vibe`).                                                                                                         |
 | **Uses eval**                    | None in our source. Transitive: `@modelcontextprotocol/sdk` → `ajv@8` uses `new Function(...)` in `ajv/dist/compile/index.js` to compile JSON Schema validators.                                 | This is ajv's standard codegen path. Only known schemas (defined in our source and the MCP SDK) flow into it; no caller-supplied data ever reaches the compiled function body.                                                                                                                                                                               |
 | **SQLite adapter isolation**     | Persistence uses Node's built-in `node:sqlite` module (no native binding, no install scripts) through a single adapter, `src/sqlite-driver.ts`.                                                  | `node:sqlite` is touched by exactly one production module (the adapter); every other module talks to SQLite through its typed surface. We never call any `db.pragma()` helper (it does not exist on `node:sqlite`); SQLite setup uses fixed literal `db.exec("PRAGMA ...")` statements. `npm run security:audit` fails the release if production code references `node:sqlite` outside the adapter or reintroduces a `.pragma()` call.                                                            |
 | **Dependency ownership**         | A handful of small transitive packages (e.g. `media-typer` via `@modelcontextprotocol/sdk`) trip Socket's "unstable ownership" or "obfuscated code" heuristics.                                  | These are pinned, well-known micro-deps in the Node ecosystem with no known issues. We pin direct override versions of `content-type` and `type-is` in `package.json#overrides`. As of 2.0.0 the prod graph carries no native module (`better-sqlite3` moved to devDependencies; `node:sqlite` is built into Node), eliminating the entire `prebuild-install`/`tar-fs`/`tar-stream` install-time chain. Our earlier direct dependency on `toml@3.0.0` was replaced with `smol-toml`.        |

package/dist/async-job-manager.d.ts

@@ -61,10 +61,12 @@ export declare class AsyncJobManager {
     private onJobComplete?;
     private jobs;
     private evictionTimer;
+    private stallTimer;
     private processMonitor;
     private store;
     private flightRecorder;
     constructor(logger?: Logger, onJobComplete?: ((cli: LlmCli, durationMs: number, success: boolean) => void) | undefined, store?: JobStore | null, flightRecorder?: FlightRecorderLike);
+    checkStalledJobs(now?: number): void;
     hasStore(): boolean;
     private emitMetrics;
     private evictCompletedJobs;

package/dist/async-job-manager.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "crypto";
-import { envWithExtendedPath, getExtendedPath, killProcessGroup, spawnCliProcess, unregisterProcessGroup, } from "./executor.js";
-import { noopLogger } from "./logger.js";
+import { envWithExtendedPath, getExtendedPath, killProcessGroup, providerCommandName, spawnCliProcess, unregisterProcessGroup, } from "./executor.js";
+import { noopLogger, logWarn } from "./logger.js";
 import { ProcessMonitor } from "./process-monitor.js";
 import { computeRequestKey } from "./job-store.js";
 import { NoopFlightRecorder } from "./flight-recorder.js";
@@ -8,6 +8,8 @@ const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
 const JOB_TTL_MS = 60 * 60 * 1000;
 const EVICTION_INTERVAL_MS = 5 * 60 * 1000;
 const OUTPUT_FLUSH_INTERVAL_MS = 1000;
+const STALL_CHECK_INTERVAL_MS = 60 * 1000;
+const STALL_WARNING_MARKS_MS = [5, 10, 15].map(min => min * 60 * 1000);
 function describeProcessLaunchError(cli, error) {
     const code = error.code;
     if (code === "ENOENT") {
@@ -55,6 +57,7 @@ export class AsyncJobManager {
     onJobComplete;
     jobs = new Map();
     evictionTimer = null;
+    stallTimer = null;
     processMonitor;
     store;
     flightRecorder;
@@ -97,6 +100,43 @@ export class AsyncJobManager {
         if (this.evictionTimer.unref) {
             this.evictionTimer.unref();
         }
+        this.stallTimer = setInterval(() => this.checkStalledJobs(), STALL_CHECK_INTERVAL_MS);
+        if (this.stallTimer.unref) {
+            this.stallTimer.unref();
+        }
+    }
+    checkStalledJobs(now = Date.now()) {
+        for (const job of this.jobs.values()) {
+            if (job.status !== "running")
+                continue;
+            if (Buffer.byteLength(job.stdout) > 0) {
+                job.stallWarnIndex = STALL_WARNING_MARKS_MS.length;
+                continue;
+            }
+            const idx = job.stallWarnIndex ?? 0;
+            if (idx >= STALL_WARNING_MARKS_MS.length)
+                continue;
+            const elapsedMs = now - new Date(job.startedAt).getTime();
+            if (elapsedMs < STALL_WARNING_MARKS_MS[idx])
+                continue;
+            let newIdx = idx;
+            while (newIdx < STALL_WARNING_MARKS_MS.length &&
+                elapsedMs >= STALL_WARNING_MARKS_MS[newIdx]) {
+                newIdx++;
+            }
+            job.stallWarnIndex = newIdx;
+            const crossedMarkMin = Math.round(STALL_WARNING_MARKS_MS[newIdx - 1] / 60000);
+            logWarn(this.logger, `Async job ${job.id} (${job.cli}) has produced no stdout after ~${crossedMarkMin}min — possible silent stall (issue #21)`, {
+                jobId: job.id,
+                cli: job.cli,
+                correlationId: job.correlationId,
+                elapsedMs,
+                stdoutBytes: 0,
+                stderrBytes: Buffer.byteLength(job.stderr),
+                model: job.flightRecorderEntry?.model,
+                promptLength: job.flightRecorderEntry?.prompt?.length,
+            });
+        }
     }
     hasStore() {
         return this.store !== null;
@@ -399,7 +439,7 @@ export class AsyncJobManager {
         }
         const id = randomUUID();
         const startedAt = new Date().toISOString();
-        const command = cli === "mistral" ? "vibe" : cli;
+        const command = providerCommandName(cli);
         const baseEnv = envWithExtendedPath(process.env, getExtendedPath());
         const child = spawnCliProcess(command, args, {
             cwd,

package/dist/cli-updater.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { executeCli } from "./executor.js";
+import { executeCli, providerCommandName } from "./executor.js";
 import { getProviderRuntimeStatus } from "./provider-status.js";
 const MISTRAL_VIBE_PACKAGE = "mistral-vibe";
 const LEGACY_VIBE_PACKAGE = "vibe-cli";
@@ -35,10 +35,7 @@ const VERSION_ARGS = {
     grok: ["--version"],
     mistral: ["--version"],
 };
-const NPM_PACKAGES = {
-    codex: "@openai/codex",
-    gemini: "@google/gemini-cli",
-};
+const CODEX_NPM_PACKAGE = "@openai/codex";
 export function buildCliUpgradePlan(cli, target = "latest", detectMistral = detectMistralInstallMethod) {
     const normalizedTarget = normalizeTarget(target);
     if (cli === "mistral") {
@@ -96,17 +93,28 @@ export function buildCliUpgradePlan(cli, target = "latest", detectMistral = dete
             requiresNetwork: true,
         };
     }
-    const packageName = cli === "codex" ? NPM_PACKAGES.codex : NPM_PACKAGES.gemini;
+    if (cli === "gemini") {
+        if (normalizedTarget !== "latest") {
+            throw new Error("Antigravity CLI upgrades support only the 'latest' target via 'agy update'.");
+        }
+        return {
+            cli,
+            target: normalizedTarget,
+            command: "agy",
+            args: ["update"],
+            strategy: "self-update",
+            requiresNetwork: true,
+            note: "Gemini provider requests now run through Google Antigravity CLI (`agy`).",
+        };
+    }
     return {
         cli,
         target: normalizedTarget,
         command: "npm",
-        args: ["install", "-g", `${packageName}@${normalizedTarget}`],
+        args: ["install", "-g", `${CODEX_NPM_PACKAGE}@${normalizedTarget}`],
         strategy: "npm-global-install",
         requiresNetwork: true,
-        note: cli === "codex"
-            ? "Explicit Codex targets use the documented npm package path; latest can use 'codex update'."
-            : "Gemini CLI does not expose a self-update command in the gateway-supported CLI surface, so upgrades use npm.",
+        note: "Explicit Codex targets use the documented npm package path; latest can use 'codex update'.",
     };
 }
 export async function getCliVersion(cli) {
@@ -115,7 +123,7 @@ export async function getCliVersion(cli) {
         const status = getProviderRuntimeStatus(cli);
         return {
             cli,
-            command: cli,
+            command: status.command,
             args,
             installed: status.installed,
             version: status.version || undefined,
@@ -191,10 +199,11 @@ function buildMistralUpgradePlan(normalizedTarget, detectMistral) {
 }
 async function fallbackCliVersion(cli, args) {
     try {
-        const result = await executeCli(cli, args, { timeout: 15_000 });
+        const command = providerCommandName(cli);
+        const result = await executeCli(command, args, { timeout: 15_000 });
         return {
             cli,
-            command: cli,
+            command,
             args,
             installed: true,
             version: extractVersion(result.stdout, result.stderr),

package/dist/executor.d.ts

@@ -13,6 +13,7 @@ export interface ExecuteResult {
     stderr: string;
     code: number;
 }
+export declare function providerCommandName(command: string): string;
 export declare function buildExtendedPath(env?: NodeJS.ProcessEnv, home?: string, nodePath?: string, platform?: NodeJS.Platform): string;
 export declare function getExtendedPath(): string;
 export declare function envWithExtendedPath(baseEnv?: NodeJS.ProcessEnv, extendedPath?: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;

package/dist/executor.js

@@ -3,6 +3,13 @@ import { homedir } from "os";
 import { delimiter, join, dirname, extname, win32 } from "path";
 import { readdirSync, existsSync } from "fs";
 import { createCircuitBreaker, withRetry } from "./retry.js";
+export function providerCommandName(command) {
+    if (command === "gemini")
+        return "agy";
+    if (command === "mistral")
+        return "vibe";
+    return command;
+}
 const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
 const circuitBreakers = new Map();
 let cachedNvmPath;