llm-cli-gateway 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [1.10.0] - 2026-05-27 — Phase 4 slice ε (Gemini `-o stream-json` enum widening)
+
+Ships the fifth Phase 4 slice: Gemini's NDJSON event-stream output format
+(`-o stream-json`) is now reachable from `gemini_request` and
+`gemini_request_async`. Four commits land together: the feature wiring, a
+contract-table widening, a test-veracity regression suite, and a follow-up
+test fix driven by the multi-LLM round-1 audit.
+
+### Added — `outputFormat: "stream-json"` for Gemini
+
+- `gemini_request` and `gemini_request_async` `outputFormat` enums widened
+  from `text | json` to `text | json | stream-json`.
+- `prepareGeminiRequest` emits `-o stream-json` when the new value is set.
+  No `--include-partial-messages` analogue is required: Gemini already
+  streams stdout in real time across all output modes (covered by
+  `CLI_IDLE_TIMEOUTS.gemini = 600_000`).
+- New `parseGeminiStreamJson` parser consumes the NDJSON event stream
+  (`init` / `message` / `result` lines), concatenates assistant `delta`
+  messages into the response, and extracts
+  `input_tokens` / `output_tokens` / `cached` → `cache_read_tokens` from
+  the terminal `result.stats` event.
+- `extractUsageAndCost("gemini", _, "stream-json")` routes to the new
+  parser so usage tokens reach the flight recorder on the stream-json
+  path, matching the existing `-o json` behaviour.
+- `UPSTREAM_CLI_CONTRACTS.gemini.flags["-o"].values` widened to
+  `["json", "stream-json"]`; two new conformance fixtures
+  (`gemini-stream-json` passing, `gemini-output-format-invalid` failing
+  for `-o ndjson`) pin the enum bound.
+
+### Test-veracity audit
+
+Per the standing protocol established with v1.9.0
+(`feedback_test_veracity_audit_protocol`), this slice's tests were
+audited by Codex + Gemini + Grok + Mistral in async parallel with
+mandatory mutation-probe execution. Round 1 found one real gap
+(`Eε-4` only checked fixture presence/shape — P-Eε-1 left it green);
+closed in commit `4a78f9c` by running the fixture's args through
+`validateUpstreamCliArgs` inside the same `it()` block. Round 2
+delivered unanimous UNCONDITIONAL APPROVE across all four reviewers,
+with site-by-site probe evidence for the contested `Eα` registered-schema
+helper. Spec at `docs/plans/test-veracity-audit-slice-epsilon.spec.md`.
+
+Test count: 771 → 795 → 796 (24 + 1 new across two files).
+
+### Known caveats
+
+- The `npm run check` script still does not include `format:check` (a
+  gap first flagged in the v1.8.0 release notes). Run both locally
+  before pushing; CI runs format:check separately.
+
 ## [1.9.0] - 2026-05-27 — Phase 4 slice δ (budget/max-turns parity) + retroactive α/γ contract closure
 
 Ships the fourth Phase 4 slice (budget/max-turns parity for Grok and Mistral),

package/dist/gemini-json-parser.d.ts

@@ -1,13 +1,22 @@
 /**
- * Parser for Gemini CLI `-o json` output.
+ * Parsers for Gemini CLI `-o json` (single object) and `-o stream-json`
+ * (NDJSON event stream) output.
  *
- * Gemini emits a single JSON object with:
+ * `-o json` emits a single JSON object with:
  *   - `response`: string final model output
  *   - `usageMetadata`: { promptTokenCount, candidatesTokenCount,
  *                        cachedContentTokenCount?, totalTokenCount }
  *
- * Returns null when stdout is not parseable as JSON. Returns an object with
- * only `response` when usageMetadata is missing.
+ * `-o stream-json` emits one JSON object per line:
+ *   - `{ "type": "init", "session_id": "...", "model": "..." }`
+ *   - `{ "type": "message", "role": "user", "content": "..." }`
+ *   - `{ "type": "message", "role": "assistant", "content": "...", "delta": true }` (repeated)
+ *   - `{ "type": "result", "status": "success", "stats": { "input_tokens": N,
+ *        "output_tokens": N, "cached": N, ... } }`
+ *
+ * Both parsers return null when stdout is unparseable. Both populate the same
+ * `GeminiJsonParseResult` shape so `extractUsageAndCost` can branch on
+ * outputFormat without further dispatch.
  */
 export interface GeminiUsage {
     input_tokens: number;
@@ -19,3 +28,9 @@ export interface GeminiJsonParseResult {
     response?: string;
 }
 export declare function parseGeminiJson(stdout: string): GeminiJsonParseResult | null;
+/**
+ * Parse Gemini `-o stream-json` NDJSON output. Concatenates assistant `delta`
+ * message content into `response`, extracts the terminal `result.stats` payload
+ * into `usage`. Returns null when stdout contains no parseable JSON line.
+ */
+export declare function parseGeminiStreamJson(stdout: string): GeminiJsonParseResult | null;

package/dist/gemini-json-parser.js

@@ -1,13 +1,22 @@
 /**
- * Parser for Gemini CLI `-o json` output.
+ * Parsers for Gemini CLI `-o json` (single object) and `-o stream-json`
+ * (NDJSON event stream) output.
  *
- * Gemini emits a single JSON object with:
+ * `-o json` emits a single JSON object with:
  *   - `response`: string final model output
  *   - `usageMetadata`: { promptTokenCount, candidatesTokenCount,
  *                        cachedContentTokenCount?, totalTokenCount }
  *
- * Returns null when stdout is not parseable as JSON. Returns an object with
- * only `response` when usageMetadata is missing.
+ * `-o stream-json` emits one JSON object per line:
+ *   - `{ "type": "init", "session_id": "...", "model": "..." }`
+ *   - `{ "type": "message", "role": "user", "content": "..." }`
+ *   - `{ "type": "message", "role": "assistant", "content": "...", "delta": true }` (repeated)
+ *   - `{ "type": "result", "status": "success", "stats": { "input_tokens": N,
+ *        "output_tokens": N, "cached": N, ... } }`
+ *
+ * Both parsers return null when stdout is unparseable. Both populate the same
+ * `GeminiJsonParseResult` shape so `extractUsageAndCost` can branch on
+ * outputFormat without further dispatch.
  */
 export function parseGeminiJson(stdout) {
     const trimmed = stdout.trim();
@@ -45,3 +54,63 @@ export function parseGeminiJson(stdout) {
     }
     return result;
 }
+/**
+ * Parse Gemini `-o stream-json` NDJSON output. Concatenates assistant `delta`
+ * message content into `response`, extracts the terminal `result.stats` payload
+ * into `usage`. Returns null when stdout contains no parseable JSON line.
+ */
+export function parseGeminiStreamJson(stdout) {
+    if (!stdout) {
+        return null;
+    }
+    const lines = stdout.split(/\r?\n/);
+    const result = {};
+    const assistantChunks = [];
+    let sawAnyLine = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Gemini stream-json lines are individual JSON objects; non-JSON
+        // chatter (warnings, "Ripgrep not available", etc.) is silently
+        // ignored so a stray banner line doesn't poison usage extraction.
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (!event || typeof event !== "object")
+            continue;
+        sawAnyLine = true;
+        if (event.type === "message" &&
+            event.role === "assistant" &&
+            typeof event.content === "string") {
+            assistantChunks.push(event.content);
+            continue;
+        }
+        if (event.type === "result" && event.stats && typeof event.stats === "object") {
+            const stats = event.stats;
+            const input = typeof stats.input_tokens === "number" ? stats.input_tokens : undefined;
+            const output = typeof stats.output_tokens === "number" ? stats.output_tokens : undefined;
+            if (input !== undefined || output !== undefined) {
+                const usage = {
+                    input_tokens: input ?? 0,
+                    output_tokens: output ?? 0,
+                };
+                if (typeof stats.cached === "number") {
+                    usage.cache_read_tokens = stats.cached;
+                }
+                result.usage = usage;
+            }
+        }
+    }
+    if (!sawAnyLine) {
+        return null;
+    }
+    if (assistantChunks.length > 0) {
+        result.response = assistantChunks.join("");
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -212,11 +212,13 @@ export declare function prepareGeminiRequest(params: {
     optimizePrompt: boolean;
     operation: string;
     /**
-     * U23: output format. When set to "json", emits `-o json` so Gemini emits
-     * the JSON object containing usageMetadata that `parseGeminiJson` (and
-     * downstream `extractUsageAndCost`) can consume. Defaults to "text".
+     * U23 + Phase 4 slice ε: output format. `json` emits `-o json` (single
+     * JSON object with usageMetadata). `stream-json` emits `-o stream-json`
+     * (NDJSON event stream — `init` / `message` / `result` lines). Both
+     * route through `extractUsageAndCost` so usage tokens reach the flight
+     * recorder. Defaults to "text".
      */
-    outputFormat?: "text" | "json";
+    outputFormat?: "text" | "json" | "stream-json";
     sandbox?: boolean;
     policyFiles?: string[];
     adminPolicyFiles?: string[];
@@ -313,8 +315,11 @@ export interface GeminiRequestParams {
     optimizeResponse?: boolean;
     idleTimeoutMs?: number;
     forceRefresh?: boolean;
-    /** U23: "json" emits `-o json` so token usage is parsed and reported. */
-    outputFormat?: "text" | "json";
+    /**
+     * U23 + Phase 4 slice ε: "json" emits `-o json`; "stream-json" emits
+     * `-o stream-json` (NDJSON event stream). Both are usage-extracted.
+     */
+    outputFormat?: "text" | "json" | "stream-json";
     sandbox?: boolean;
     policyFiles?: string[];
     adminPolicyFiles?: string[];

package/dist/index.js

@@ -9,7 +9,7 @@ import { z } from "zod";
 import { executeCli, killAllProcessGroups } from "./executor.js";
 import { parseStreamJson } from "./stream-json-parser.js";
 import { parseCodexJsonStream } from "./codex-json-parser.js";
-import { parseGeminiJson } from "./gemini-json-parser.js";
+import { parseGeminiJson, parseGeminiStreamJson } from "./gemini-json-parser.js";
 import { parseVibeMetaJson } from "./mistral-meta-json-parser.js";
 import { homedir } from "os";
 import { createSessionManager } from "./session-manager.js";
@@ -530,8 +530,8 @@ ctx) {
             costUsd: parsed.usage.cost_usd,
         };
     }
-    if (cli === "gemini" && outputFormat === "json") {
-        const parsed = parseGeminiJson(output);
+    if (cli === "gemini" && (outputFormat === "json" || outputFormat === "stream-json")) {
+        const parsed = outputFormat === "stream-json" ? parseGeminiStreamJson(output) : parseGeminiJson(output);
         if (!parsed || !parsed.usage) {
             return {};
         }
@@ -1271,9 +1271,19 @@ export function prepareGeminiRequest(params, runtime = resolveGatewayServerRunti
     // U23 fix: emit `-o json` when the caller asked for JSON output. The Gemini
     // JSON parser is otherwise unreachable from the tool surface and the
     // structured usageMetadata is silently dropped.
+    //
+    // Phase 4 slice ε: same wiring for `-o stream-json` (NDJSON event stream).
+    // Gemini already streams stdout in real-time so the existing 10-minute
+    // idle timeout (CLI_IDLE_TIMEOUTS.gemini) covers both modes without
+    // adjustment — unlike Claude, no `--include-partial-messages` companion
+    // flag is required because Gemini emits assistant `delta` events as part
+    // of the default stream-json shape.
     if (params.outputFormat === "json") {
         args.push("-o", "json");
     }
+    else if (params.outputFormat === "stream-json") {
+        args.push("-o", "stream-json");
+    }
     // Phase 4 slice γ: opt-in trust-prompt bypass for fresh workspaces.
     if (params.skipTrust) {
         args.push("--skip-trust");
@@ -3069,11 +3079,14 @@ export function createGatewayServer(deps = {}) {
             .default(false)
             .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
         // U23: emit `-o json` to extract token usage via parseGeminiJson. Default
-        // remains text so existing callers see no behavior change.
+        // remains text so existing callers see no behavior change. Phase 4 slice
+        // ε adds `stream-json` (NDJSON event stream parsed by
+        // parseGeminiStreamJson — `init`/`message`/`result` lines, idle-timeout
+        // semantics covered by Gemini's existing real-time stdout streaming).
         outputFormat: z
-            .enum(["text", "json"])
+            .enum(["text", "json", "stream-json"])
             .default("text")
-            .describe("Gemini output format. `json` emits `-o json` so usageMetadata is parsed and reported."),
+            .describe("Gemini output format. `json` emits `-o json` (single JSON with usageMetadata). `stream-json` emits `-o stream-json` (NDJSON event stream — `init`/`message`/`result` lines, usage extracted from the terminal `result.stats` event). Both report usage to the flight recorder."),
         sandbox: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.sandbox.describe("Run Gemini in sandbox mode (-s)"),
         policyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.policyFiles.describe("Policy file paths (--policy <path>, one per file). Paths must exist."),
         adminPolicyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.adminPolicyFiles.describe("Admin policy file paths (--admin-policy <path>, one per file). Paths must exist."),
@@ -3691,11 +3704,14 @@ export function createGatewayServer(deps = {}) {
                 .default(false)
                 .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
             // U23: emit `-o json` to extract token usage via parseGeminiJson. Default
-            // remains text so existing callers see no behavior change.
+            // remains text so existing callers see no behavior change. Phase 4 slice
+            // ε adds `stream-json` (NDJSON event stream parsed by
+            // parseGeminiStreamJson — `init`/`message`/`result` lines, idle-timeout
+            // semantics covered by Gemini's existing real-time stdout streaming).
             outputFormat: z
-                .enum(["text", "json"])
+                .enum(["text", "json", "stream-json"])
                 .default("text")
-                .describe("Gemini output format. `json` emits `-o json` so usageMetadata is parsed and reported."),
+                .describe("Gemini output format. `json` emits `-o json` (single JSON with usageMetadata). `stream-json` emits `-o stream-json` (NDJSON event stream — `init`/`message`/`result` lines, usage extracted from the terminal `result.stats` event). Both report usage to the flight recorder."),
             sandbox: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.sandbox.describe("Run Gemini in sandbox mode (-s)"),
             policyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.policyFiles.describe("Policy file paths (--policy <path>, one per file). Paths must exist."),
             adminPolicyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.adminPolicyFiles.describe("Admin policy file paths (--admin-policy <path>, one per file). Paths must exist."),

package/dist/upstream-contracts.js

@@ -248,7 +248,11 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "-s": { arity: "none", description: "Sandbox mode" },
             "--policy": { arity: "one", description: "Policy file path" },
             "--admin-policy": { arity: "one", description: "Admin policy file path" },
-            "-o": { arity: "one", values: ["json"], description: "Output format" },
+            "-o": {
+                arity: "one",
+                values: ["json", "stream-json"],
+                description: "Output format (Phase 4 slice ε adds stream-json)",
+            },
             "--resume": { arity: "one", description: "Resume session" },
             "--skip-trust": {
                 arity: "none",
@@ -275,6 +279,18 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 args: ["-p", "hello", "--skip-trust"],
                 expect: "pass",
             },
+            {
+                id: "gemini-stream-json",
+                description: "Phase 4 slice ε: -o stream-json is accepted",
+                args: ["-p", "hello", "-o", "stream-json"],
+                expect: "pass",
+            },
+            {
+                id: "gemini-output-format-invalid",
+                description: "Phase 4 slice ε: -o ndjson is rejected (not in contract enum)",
+                args: ["-p", "hello", "-o", "ndjson"],
+                expect: "fail",
+            },
         ],
     },
     grok: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, and Mistral Vibe CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",