@j0hanz/code-review-analyst-mcp 1.5.0 → 1.5.1

package/README.md

@@ -371,17 +371,21 @@ Create a test plan covering the changes in the diff using the Flash model with t
 
 ### Environment Variables
 
-| Variable                       | Description                                          | Default      | Required |
-| ------------------------------ | ---------------------------------------------------- | ------------ | -------- |
-| `GEMINI_API_KEY`               | Gemini API key                                       | —            | Yes      |
-| `GOOGLE_API_KEY`               | Alternative API key (if `GEMINI_API_KEY` not set)    | —            | No       |
-| `GEMINI_MODEL`                 | Override default model selection                     | —            | No       |
-| `GEMINI_HARM_BLOCK_THRESHOLD`  | Safety threshold (BLOCK_NONE, BLOCK_ONLY_HIGH, etc.) | `BLOCK_NONE` | No       |
-| `MAX_DIFF_CHARS`               | Max chars for diff input                             | `120000`     | No       |
-| `MAX_CONTEXT_CHARS`            | Max combined context for inspection                  | `500000`     | No       |
-| `MAX_CONCURRENT_CALLS`         | Max concurrent Gemini requests                       | `10`         | No       |
-| `MAX_CONCURRENT_CALLS_WAIT_MS` | Max wait time for a free Gemini slot                 | `2000`       | No       |
-| `MAX_CONCURRENT_CALLS_POLL_MS` | Poll interval while waiting for a free slot          | `25`         | No       |
+| Variable                        | Description                                          | Default      | Required |
+| ------------------------------- | ---------------------------------------------------- | ------------ | -------- |
+| `GEMINI_API_KEY`                | Gemini API key                                       | —            | Yes      |
+| `GOOGLE_API_KEY`                | Alternative API key (if `GEMINI_API_KEY` not set)    | —            | No       |
+| `GEMINI_MODEL`                  | Override default model selection                     | —            | No       |
+| `GEMINI_HARM_BLOCK_THRESHOLD`   | Safety threshold (BLOCK_NONE, BLOCK_ONLY_HIGH, etc.) | `BLOCK_NONE` | No       |
+| `MAX_DIFF_CHARS`                | Max chars for diff input                             | `120000`     | No       |
+| `MAX_CONTEXT_CHARS`             | Max combined context for inspection                  | `500000`     | No       |
+| `MAX_CONCURRENT_CALLS`          | Max concurrent Gemini requests                       | `10`         | No       |
+| `MAX_CONCURRENT_BATCH_CALLS`    | Max concurrent inline batch requests                 | `2`          | No       |
+| `MAX_CONCURRENT_CALLS_WAIT_MS`  | Max wait time for a free Gemini slot                 | `2000`       | No       |
+| `MAX_SCHEMA_RETRY_ERROR_CHARS`  | Max chars from schema error injected into retry text | `1500`       | No       |
+| `GEMINI_BATCH_MODE`             | Request mode for Gemini calls (`off`, `inline`)      | `off`        | No       |
+| `GEMINI_BATCH_POLL_INTERVAL_MS` | Poll interval for batch job status                   | `2000`       | No       |
+| `GEMINI_BATCH_TIMEOUT_MS`       | Max wait for batch completion                        | `120000`     | No       |
 
 ### Models
 

package/dist/lib/diff-parser.js

@@ -32,24 +32,35 @@ function sortPaths(paths) {
     }
     return Array.from(paths).sort(PATH_SORTER);
 }
-function buildDiffComputation(files) {
+function buildDiffComputation(files, options) {
     let added = 0;
     let deleted = 0;
-    const paths = new Set();
-    const summaries = new Array(files.length);
+    const paths = options.needPaths ? new Set() : undefined;
+    const summaries = options.needSummaries
+        ? new Array(files.length)
+        : undefined;
     let index = 0;
     for (const file of files) {
         added += file.additions;
         deleted += file.deletions;
-        const path = resolveChangedPath(file);
-        if (path) {
-            paths.add(path);
+        if (options.needPaths || options.needSummaries) {
+            const path = resolveChangedPath(file);
+            if (paths && path) {
+                paths.add(path);
+            }
+            if (summaries) {
+                summaries[index] =
+                    `${path ?? UNKNOWN_PATH} (+${file.additions} -${file.deletions})`;
+            }
         }
-        summaries[index] =
-            `${path ?? UNKNOWN_PATH} (+${file.additions} -${file.deletions})`;
         index += 1;
     }
-    return { added, deleted, paths, summaries };
+    return {
+        added,
+        deleted,
+        paths: paths ?? new Set(),
+        summaries: summaries ?? [],
+    };
 }
 function buildStats(filesCount, added, deleted) {
     return { files: filesCount, added, deleted };
@@ -61,7 +72,10 @@ export function computeDiffStatsAndSummaryFromFiles(files) {
             summary: NO_FILES_CHANGED,
         };
     }
-    const computed = buildDiffComputation(files);
+    const computed = buildDiffComputation(files, {
+        needPaths: false,
+        needSummaries: true,
+    });
     const stats = buildStats(files.length, computed.added, computed.deleted);
     return {
         stats,
@@ -75,7 +89,10 @@ export function computeDiffStatsAndPathsFromFiles(files) {
             paths: EMPTY_PATHS,
         };
     }
-    const computed = buildDiffComputation(files);
+    const computed = buildDiffComputation(files, {
+        needPaths: true,
+        needSummaries: false,
+    });
     return {
         stats: buildStats(files.length, computed.added, computed.deleted),
         paths: sortPaths(computed.paths),
@@ -86,7 +103,7 @@ export function extractChangedPathsFromFiles(files) {
     if (files.length === 0) {
         return EMPTY_PATHS;
     }
-    return sortPaths(buildDiffComputation(files).paths);
+    return sortPaths(buildDiffComputation(files, { needPaths: true, needSummaries: false }).paths);
 }
 /** Extract all unique changed file paths (renamed: returns new path). */
 export function extractChangedPaths(diff) {
@@ -96,7 +113,10 @@ export function computeDiffStatsFromFiles(files) {
     if (files.length === 0) {
         return EMPTY_STATS;
     }
-    const computed = buildDiffComputation(files);
+    const computed = buildDiffComputation(files, {
+        needPaths: false,
+        needSummaries: false,
+    });
     return buildStats(files.length, computed.added, computed.deleted);
 }
 /** Count changed files, added lines, and deleted lines. */

package/dist/lib/diff-store.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ParsedFile } from './diff-parser.js';
 import { createErrorToolResponse } from './tool-response.js';
 export declare const DIFF_RESOURCE_URI = "diff://current";
 export interface DiffStats {
@@ -8,6 +9,7 @@ export interface DiffStats {
 }
 export interface DiffSlot {
     diff: string;
+    parsedFiles: readonly ParsedFile[];
     stats: DiffStats;
     generatedAt: string;
     mode: string;

package/dist/lib/gemini.d.ts

@@ -4,4 +4,8 @@ import type { GeminiStructuredRequest } from './types.js';
 export declare const geminiEvents: EventEmitter<[never]>;
 export declare function getCurrentRequestId(): string;
 export declare function setClientForTesting(client: GoogleGenAI): void;
+export declare function getGeminiQueueSnapshot(): {
+    activeCalls: number;
+    waitingCalls: number;
+};
 export declare function generateStructuredJson(request: GeminiStructuredRequest): Promise<unknown>;

package/dist/lib/gemini.js

@@ -13,6 +13,7 @@ const DEFAULT_MODEL = 'gemini-3-flash-preview';
 const GEMINI_MODEL_ENV_VAR = 'GEMINI_MODEL';
 const GEMINI_HARM_BLOCK_THRESHOLD_ENV_VAR = 'GEMINI_HARM_BLOCK_THRESHOLD';
 const GEMINI_INCLUDE_THOUGHTS_ENV_VAR = 'GEMINI_INCLUDE_THOUGHTS';
+const GEMINI_BATCH_MODE_ENV_VAR = 'GEMINI_BATCH_MODE';
 const GEMINI_API_KEY_ENV_VAR = 'GEMINI_API_KEY';
 const GOOGLE_API_KEY_ENV_VAR = 'GOOGLE_API_KEY';
 function getDefaultModel() {
@@ -30,14 +31,20 @@ const RETRY_DELAY_MAX_MS = 5_000;
 const RETRY_JITTER_RATIO = 0.2;
 const DEFAULT_SAFETY_THRESHOLD = HarmBlockThreshold.BLOCK_NONE;
 const DEFAULT_INCLUDE_THOUGHTS = false;
+const DEFAULT_BATCH_MODE = 'off';
 const UNKNOWN_REQUEST_CONTEXT_VALUE = 'unknown';
 const RETRYABLE_NUMERIC_CODES = new Set([429, 500, 502, 503, 504]);
 const DIGITS_ONLY_PATTERN = /^\d+$/;
 const SLEEP_UNREF_OPTIONS = { ref: false };
 const maxConcurrentCallsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS', 10);
+const maxConcurrentBatchCallsConfig = createCachedEnvInt('MAX_CONCURRENT_BATCH_CALLS', 2);
 const concurrencyWaitMsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS_WAIT_MS', 2_000);
+const batchPollIntervalMsConfig = createCachedEnvInt('GEMINI_BATCH_POLL_INTERVAL_MS', 2_000);
+const batchTimeoutMsConfig = createCachedEnvInt('GEMINI_BATCH_TIMEOUT_MS', 120_000);
 let activeCalls = 0;
+let activeBatchCalls = 0;
 const slotWaiters = [];
+const batchSlotWaiters = [];
 const RETRYABLE_TRANSIENT_CODES = new Set([
     'RESOURCE_EXHAUSTED',
     'UNAVAILABLE',
@@ -149,6 +156,25 @@ function getDefaultIncludeThoughts() {
     cachedIncludeThoughts = parseBooleanEnv(value) ?? DEFAULT_INCLUDE_THOUGHTS;
     return cachedIncludeThoughts;
 }
+function getDefaultBatchMode() {
+    const value = process.env[GEMINI_BATCH_MODE_ENV_VAR]?.trim().toLowerCase();
+    if (value === 'inline') {
+        return 'inline';
+    }
+    return DEFAULT_BATCH_MODE;
+}
+function applyResponseKeyOrdering(responseSchema, responseKeyOrdering) {
+    if (!responseKeyOrdering || responseKeyOrdering.length === 0) {
+        return responseSchema;
+    }
+    return {
+        ...responseSchema,
+        propertyOrdering: [...responseKeyOrdering],
+    };
+}
+function getPromptWithFunctionCallingContext(request) {
+    return request.prompt;
+}
 function getSafetySettings(threshold) {
     const cached = safetySettingsCache.get(threshold);
     if (cached) {
@@ -281,19 +307,21 @@ function findFirstStringCode(record, keys) {
     }
     return undefined;
 }
+const NUMERIC_ERROR_KEYS = ['status', 'statusCode', 'code'];
 function getNumericErrorCode(error) {
     const record = getNestedError(error);
     if (!record) {
         return undefined;
     }
-    return findFirstNumericCode(record, ['status', 'statusCode', 'code']);
+    return findFirstNumericCode(record, NUMERIC_ERROR_KEYS);
 }
+const TRANSIENT_ERROR_KEYS = ['code', 'status', 'statusText'];
 function getTransientErrorCode(error) {
     const record = getNestedError(error);
     if (!record) {
         return undefined;
     }
-    return findFirstStringCode(record, ['code', 'status', 'statusText']);
+    return findFirstStringCode(record, TRANSIENT_ERROR_KEYS);
 }
 function shouldRetry(error) {
     const numericCode = getNumericErrorCode(error);
@@ -322,7 +350,7 @@ function buildGenerationConfig(request, abortSignal) {
         temperature: request.temperature ?? 1.0,
         maxOutputTokens: request.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
         responseMimeType: 'application/json',
-        responseSchema: request.responseSchema,
+        responseSchema: applyResponseKeyOrdering(request.responseSchema, request.responseKeyOrdering),
         safetySettings: getSafetySettings(getSafetyThreshold()),
         topP: 0.95,
         topK: 40,
@@ -366,12 +394,12 @@ async function generateContentWithTimeout(request, model, timeoutMs) {
     try {
         return await getClient().models.generateContent({
             model,
-            contents: request.prompt,
+            contents: getPromptWithFunctionCallingContext(request),
             config: buildGenerationConfig(request, signal),
         });
     }
     catch (error) {
-        if (request.signal?.aborted) {
+        if (request.signal?.aborted === true) {
             throw new Error('Gemini request was cancelled.');
         }
         if (controller.signal.aborted) {
@@ -466,8 +494,9 @@ function tryWakeNextWaiter() {
         next();
     }
 }
-async function waitForConcurrencySlot(limit, requestSignal) {
-    if (activeCalls < limit) {
+async function waitForSlot(limit, getActiveCount, acquireSlot, waiters, requestSignal) {
+    if (waiters.length === 0 && getActiveCount() < limit) {
+        acquireSlot();
         return;
     }
     if (requestSignal?.aborted) {
@@ -484,16 +513,17 @@ async function waitForConcurrencySlot(limit, requestSignal) {
             if (requestSignal) {
                 requestSignal.removeEventListener('abort', onAbort);
             }
+            acquireSlot();
             resolve();
         };
-        slotWaiters.push(waiter);
+        waiters.push(waiter);
         const deadlineTimer = setTimeout(() => {
             if (settled)
                 return;
             settled = true;
-            const idx = slotWaiters.indexOf(waiter);
+            const idx = waiters.indexOf(waiter);
             if (idx !== -1) {
-                slotWaiters.splice(idx, 1);
+                waiters.splice(idx, 1);
             }
             if (requestSignal) {
                 requestSignal.removeEventListener('abort', onAbort);
@@ -505,9 +535,9 @@ async function waitForConcurrencySlot(limit, requestSignal) {
             if (settled)
                 return;
             settled = true;
-            const idx = slotWaiters.indexOf(waiter);
+            const idx = waiters.indexOf(waiter);
             if (idx !== -1) {
-                slotWaiters.splice(idx, 1);
+                waiters.splice(idx, 1);
             }
             clearTimeout(deadlineTimer);
             reject(new Error('Gemini request was cancelled.'));
@@ -517,19 +547,254 @@ async function waitForConcurrencySlot(limit, requestSignal) {
         }
     });
 }
+async function waitForConcurrencySlot(limit, requestSignal) {
+    return waitForSlot(limit, () => activeCalls, () => {
+        activeCalls += 1;
+    }, slotWaiters, requestSignal);
+}
+function tryWakeNextBatchWaiter() {
+    const next = batchSlotWaiters.shift();
+    if (next !== undefined) {
+        next();
+    }
+}
+async function waitForBatchConcurrencySlot(limit, requestSignal) {
+    return waitForSlot(limit, () => activeBatchCalls, () => {
+        activeBatchCalls += 1;
+    }, batchSlotWaiters, requestSignal);
+}
+function getBatchState(payload) {
+    const record = asRecord(payload);
+    if (!record) {
+        return undefined;
+    }
+    const directState = toUpperStringCode(record.state);
+    if (directState) {
+        return directState;
+    }
+    const metadata = asRecord(record.metadata);
+    if (!metadata) {
+        return undefined;
+    }
+    return toUpperStringCode(metadata.state);
+}
+function extractBatchResponseText(payload) {
+    const record = asRecord(payload);
+    if (!record) {
+        return undefined;
+    }
+    const inlineResponse = asRecord(record.inlineResponse);
+    const inlineText = typeof inlineResponse?.text === 'string' ? inlineResponse.text : undefined;
+    if (inlineText) {
+        return inlineText;
+    }
+    const response = asRecord(record.response);
+    if (!response) {
+        return undefined;
+    }
+    const responseText = typeof response.text === 'string' ? response.text : undefined;
+    if (responseText) {
+        return responseText;
+    }
+    const { inlineResponses } = response;
+    if (!Array.isArray(inlineResponses) || inlineResponses.length === 0) {
+        return undefined;
+    }
+    const firstInline = asRecord(inlineResponses[0]);
+    return typeof firstInline?.text === 'string' ? firstInline.text : undefined;
+}
+function extractBatchErrorDetail(payload) {
+    const record = asRecord(payload);
+    if (!record) {
+        return undefined;
+    }
+    const directError = asRecord(record.error);
+    const directMessage = typeof directError?.message === 'string' ? directError.message : undefined;
+    if (directMessage) {
+        return directMessage;
+    }
+    const metadata = asRecord(record.metadata);
+    const metadataError = asRecord(metadata?.error);
+    const metadataMessage = typeof metadataError?.message === 'string'
+        ? metadataError.message
+        : undefined;
+    if (metadataMessage) {
+        return metadataMessage;
+    }
+    const response = asRecord(record.response);
+    const responseError = asRecord(response?.error);
+    return typeof responseError?.message === 'string'
+        ? responseError.message
+        : undefined;
+}
+function getBatchSuccessResponseText(polled) {
+    const responseText = extractBatchResponseText(polled);
+    if (!responseText) {
+        const errorDetail = extractBatchErrorDetail(polled);
+        throw new Error(errorDetail
+            ? `Gemini batch request succeeded but returned no response text: ${errorDetail}`
+            : 'Gemini batch request succeeded but returned no response text.');
+    }
+    return responseText;
+}
+function handleBatchTerminalState(state, payload) {
+    if (state === 'JOB_STATE_FAILED' || state === 'JOB_STATE_CANCELLED') {
+        const errorDetail = extractBatchErrorDetail(payload);
+        throw new Error(errorDetail
+            ? `Gemini batch request ended with state ${state}: ${errorDetail}`
+            : `Gemini batch request ended with state ${state}.`);
+    }
+}
+async function pollBatchStatusWithRetries(batches, batchName, onLog, requestSignal) {
+    const maxPollRetries = 2;
+    for (let attempt = 0; attempt <= maxPollRetries; attempt += 1) {
+        try {
+            return await batches.get({ name: batchName });
+        }
+        catch (error) {
+            if (!canRetryAttempt(attempt, maxPollRetries, error)) {
+                throw error;
+            }
+            await waitBeforeRetry(attempt, error, onLog, requestSignal);
+        }
+    }
+    throw new Error('Batch polling retries exhausted unexpectedly.');
+}
+async function cancelBatchIfNeeded(request, batches, batchName, onLog, completed, timedOut) {
+    const aborted = request.signal?.aborted === true;
+    if (completed || (!aborted && !timedOut) || !batchName) {
+        return;
+    }
+    if (batches.cancel === undefined) {
+        return;
+    }
+    try {
+        await batches.cancel({ name: batchName });
+        await emitGeminiLog(onLog, 'info', {
+            event: 'gemini_batch_cancelled',
+            details: {
+                batchName,
+                reason: timedOut ? 'timeout' : 'aborted',
+            },
+        });
+    }
+    catch (error) {
+        await emitGeminiLog(onLog, 'warning', {
+            event: 'gemini_batch_cancel_failed',
+            details: {
+                batchName,
+                reason: timedOut ? 'timeout' : 'aborted',
+                error: getErrorMessage(error),
+            },
+        });
+    }
+}
+async function runInlineBatchWithPolling(request, model, onLog) {
+    const client = getClient();
+    const { batches } = client;
+    if (batches === undefined) {
+        throw new Error('Batch mode requires SDK batch support, but batches API is unavailable.');
+    }
+    let batchName;
+    let completed = false;
+    let timedOut = false;
+    try {
+        const createPayload = {
+            model,
+            src: [
+                {
+                    contents: [{ role: 'user', parts: [{ text: request.prompt }] }],
+                    config: buildGenerationConfig(request, new AbortController().signal),
+                },
+            ],
+        };
+        const createdJob = await batches.create(createPayload);
+        const createdRecord = asRecord(createdJob);
+        batchName =
+            typeof createdRecord?.name === 'string' ? createdRecord.name : undefined;
+        if (!batchName) {
+            throw new Error('Batch mode failed to return a job name.');
+        }
+        const pollStart = performance.now();
+        const timeoutMs = batchTimeoutMsConfig.get();
+        const pollIntervalMs = batchPollIntervalMsConfig.get();
+        await emitGeminiLog(onLog, 'info', {
+            event: 'gemini_batch_created',
+            details: { batchName },
+        });
+        for (;;) {
+            if (request.signal?.aborted === true) {
+                throw new Error('Gemini request was cancelled.');
+            }
+            const elapsedMs = Math.round(performance.now() - pollStart);
+            if (elapsedMs > timeoutMs) {
+                timedOut = true;
+                throw new Error(`Gemini batch request timed out after ${formatNumber(timeoutMs)}ms.`);
+            }
+            const polled = await pollBatchStatusWithRetries(batches, batchName, onLog, request.signal);
+            const state = getBatchState(polled);
+            if (state === 'JOB_STATE_SUCCEEDED') {
+                const responseText = getBatchSuccessResponseText(polled);
+                completed = true;
+                return parseStructuredResponse(responseText);
+            }
+            handleBatchTerminalState(state, polled);
+            await sleep(pollIntervalMs, undefined, request.signal
+                ? { ...SLEEP_UNREF_OPTIONS, signal: request.signal }
+                : SLEEP_UNREF_OPTIONS);
+        }
+    }
+    finally {
+        await cancelBatchIfNeeded(request, batches, batchName, onLog, completed, timedOut);
+    }
+}
+export function getGeminiQueueSnapshot() {
+    return {
+        activeCalls,
+        waitingCalls: slotWaiters.length,
+    };
+}
 export async function generateStructuredJson(request) {
     const model = request.model ?? getDefaultModel();
     const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const maxRetries = request.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const batchMode = request.batchMode ?? getDefaultBatchMode();
     const { onLog } = request;
-    const limit = maxConcurrentCallsConfig.get();
-    await waitForConcurrencySlot(limit, request.signal);
-    activeCalls += 1;
+    const limit = batchMode === 'inline'
+        ? maxConcurrentBatchCallsConfig.get()
+        : maxConcurrentCallsConfig.get();
+    const queueWaitStartedAt = performance.now();
+    if (batchMode === 'inline') {
+        await waitForBatchConcurrencySlot(limit, request.signal);
+    }
+    else {
+        await waitForConcurrencySlot(limit, request.signal);
+    }
+    const queueWaitMs = Math.round(performance.now() - queueWaitStartedAt);
+    await safeCallOnLog(onLog, 'info', {
+        event: 'gemini_queue_acquired',
+        queueWaitMs,
+        waitingCalls: batchMode === 'inline' ? batchSlotWaiters.length : slotWaiters.length,
+        activeCalls,
+        activeBatchCalls,
+        mode: batchMode,
+    });
     try {
-        return await geminiContext.run({ requestId: nextRequestId(), model }, () => runWithRetries(request, model, timeoutMs, maxRetries, onLog));
+        return await geminiContext.run({ requestId: nextRequestId(), model }, () => {
+            if (batchMode === 'inline') {
+                return runInlineBatchWithPolling(request, model, onLog);
+            }
+            return runWithRetries(request, model, timeoutMs, maxRetries, onLog);
+        });
     }
     finally {
-        activeCalls -= 1;
-        tryWakeNextWaiter();
+        if (batchMode === 'inline') {
+            activeBatchCalls -= 1;
+            tryWakeNextBatchWaiter();
+        }
+        else {
+            activeCalls -= 1;
+            tryWakeNextWaiter();
+        }
     }
 }

package/dist/lib/tool-contracts.d.ts

@@ -23,6 +23,8 @@ export interface ToolContract {
      * Omit to use the global default (0.2).
      */
     temperature?: number;
+    /** Enables deterministic JSON guidance and schema key ordering. */
+    deterministicJson?: boolean;
     params: readonly ToolParameterContract[];
     outputShape: string;
     gotchas: readonly string[];
@@ -53,6 +55,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly thinkingLevel: "minimal";
     readonly maxOutputTokens: 4096;
     readonly temperature: 1;
+    readonly deterministicJson: true;
     readonly params: readonly [{
         readonly name: "repository";
         readonly type: "string";
@@ -77,6 +80,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly thinkingLevel: "minimal";
     readonly maxOutputTokens: 4096;
     readonly temperature: 1;
+    readonly deterministicJson: true;
     readonly params: readonly [{
         readonly name: "repository";
         readonly type: "string";
@@ -101,6 +105,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly thinkingLevel: "high";
     readonly maxOutputTokens: 12288;
     readonly temperature: 1;
+    readonly deterministicJson: true;
     readonly params: readonly [{
         readonly name: "repository";
         readonly type: "string";
@@ -144,6 +149,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly thinkingLevel: "high";
     readonly maxOutputTokens: 8192;
     readonly temperature: 1;
+    readonly deterministicJson: true;
     readonly params: readonly [{
         readonly name: "findingTitle";
         readonly type: "string";
@@ -169,6 +175,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly thinkingLevel: "medium";
     readonly maxOutputTokens: 8192;
     readonly temperature: 1;
+    readonly deterministicJson: true;
     readonly params: readonly [{
         readonly name: "repository";
         readonly type: "string";
@@ -205,6 +212,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly thinkingLevel: "medium";
     readonly maxOutputTokens: 2048;
     readonly temperature: 1;
+    readonly deterministicJson: true;
     readonly params: readonly [{
         readonly name: "language";
         readonly type: "string";
@@ -223,6 +231,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly thinkingLevel: "minimal";
     readonly maxOutputTokens: 4096;
     readonly temperature: 1;
+    readonly deterministicJson: true;
     readonly params: readonly [{
         readonly name: "language";
         readonly type: "string";

package/dist/lib/tool-contracts.js

@@ -43,6 +43,7 @@ export const TOOL_CONTRACTS = [
         thinkingLevel: FLASH_TRIAGE_THINKING_LEVEL,
         maxOutputTokens: FLASH_TRIAGE_MAX_OUTPUT_TOKENS,
         temperature: TRIAGE_TEMPERATURE,
+        deterministicJson: true,
         params: [
             {
                 name: 'repository',
@@ -76,6 +77,7 @@ export const TOOL_CONTRACTS = [
         thinkingLevel: FLASH_TRIAGE_THINKING_LEVEL,
         maxOutputTokens: FLASH_TRIAGE_MAX_OUTPUT_TOKENS,
         temperature: TRIAGE_TEMPERATURE,
+        deterministicJson: true,
         params: [
             {
                 name: 'repository',
@@ -109,6 +111,7 @@ export const TOOL_CONTRACTS = [
         thinkingLevel: PRO_THINKING_LEVEL,
         maxOutputTokens: PRO_REVIEW_MAX_OUTPUT_TOKENS,
         temperature: ANALYSIS_TEMPERATURE,
+        deterministicJson: true,
         params: [
             {
                 name: 'repository',
@@ -166,6 +169,7 @@ export const TOOL_CONTRACTS = [
         thinkingLevel: PRO_THINKING_LEVEL,
         maxOutputTokens: PRO_PATCH_MAX_OUTPUT_TOKENS,
         temperature: PATCH_TEMPERATURE,
+        deterministicJson: true,
         params: [
             {
                 name: 'findingTitle',
@@ -201,6 +205,7 @@ export const TOOL_CONTRACTS = [
         thinkingLevel: FLASH_THINKING_LEVEL,
         maxOutputTokens: FLASH_TEST_PLAN_MAX_OUTPUT_TOKENS,
         temperature: CREATIVE_TEMPERATURE,
+        deterministicJson: true,
         params: [
             {
                 name: 'repository',
@@ -248,6 +253,7 @@ export const TOOL_CONTRACTS = [
         thinkingLevel: FLASH_THINKING_LEVEL,
         maxOutputTokens: FLASH_COMPLEXITY_MAX_OUTPUT_TOKENS,
         temperature: ANALYSIS_TEMPERATURE,
+        deterministicJson: true,
         params: [
             {
                 name: 'language',
@@ -272,6 +278,7 @@ export const TOOL_CONTRACTS = [
         thinkingLevel: FLASH_TRIAGE_THINKING_LEVEL,
         maxOutputTokens: FLASH_API_BREAKING_MAX_OUTPUT_TOKENS,
         temperature: TRIAGE_TEMPERATURE,
+        deterministicJson: true,
         params: [
             {
                 name: 'language',

package/dist/lib/tool-factory.d.ts

@@ -72,6 +72,10 @@ export interface StructuredToolTaskConfig<TInput extends object = Record<string,
     temperature?: number;
     /** Optional opt-in to Gemini thought output. Defaults to false. */
     includeThoughts?: boolean;
+    /** Optional deterministic JSON mode for stricter key ordering and repair prompting. */
+    deterministicJson?: boolean;
+    /** Optional batch execution mode. Defaults to runtime setting. */
+    batchMode?: 'off' | 'inline';
     /** Optional formatter for human-readable text output. */
     formatOutput?: (result: TFinal) => string;
     /** Optional context text used in progress messages. */
@@ -81,6 +85,7 @@ export interface StructuredToolTaskConfig<TInput extends object = Record<string,
     /** Builds the system instruction and user prompt from parsed tool input. */
     buildPrompt: (input: TInput, ctx: ToolExecutionContext) => PromptParts;
 }
+export declare function summarizeSchemaValidationErrorForRetry(errorMessage: string): string;
 export declare function wrapToolHandler<TInput, TResult extends CallToolResult>(options: {
     toolName: string;
     progressContext?: (input: TInput) => string;

package/dist/lib/tool-factory.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { DefaultOutputSchema } from '../schemas/outputs.js';
 import { getDiff } from './diff-store.js';
+import { createCachedEnvInt } from './env-config.js';
 import { getErrorMessage, RETRYABLE_UPSTREAM_ERROR_PATTERN } from './errors.js';
 import { stripJsonSchemaConstraints } from './gemini-schema.js';
 import { generateStructuredJson, getCurrentRequestId } from './gemini.js';
@@ -14,6 +15,9 @@ const TIMEOUT_ERROR_PATTERN = /timed out|timeout/i;
 const BUDGET_ERROR_PATTERN = /exceeds limit|max allowed size|input too large/i;
 const BUSY_ERROR_PATTERN = /too many concurrent/i;
 const MAX_SCHEMA_RETRIES = 1;
+const DEFAULT_SCHEMA_RETRY_ERROR_CHARS = 1_500;
+const schemaRetryErrorCharsConfig = createCachedEnvInt('MAX_SCHEMA_RETRY_ERROR_CHARS', DEFAULT_SCHEMA_RETRY_ERROR_CHARS);
+const DETERMINISTIC_JSON_RETRY_NOTE = 'Deterministic JSON mode: keep key names exactly as schema-defined and preserve stable field ordering.';
 function createGeminiResponseSchema(config) {
     const sourceSchema = config.geminiSchema ?? config.resultSchema;
     return stripJsonSchemaConstraints(z.toJSONSchema(sourceSchema));
@@ -21,6 +25,35 @@ function createGeminiResponseSchema(config) {
 function parseToolInput(input, fullInputSchema) {
     return fullInputSchema.parse(input);
 }
+function extractResponseKeyOrdering(responseSchema) {
+    const schemaType = responseSchema.type;
+    if (schemaType !== 'object') {
+        return undefined;
+    }
+    const { properties } = responseSchema;
+    if (typeof properties !== 'object' || properties === null) {
+        return undefined;
+    }
+    return Object.keys(properties);
+}
+export function summarizeSchemaValidationErrorForRetry(errorMessage) {
+    const maxChars = Math.max(200, schemaRetryErrorCharsConfig.get());
+    const compact = errorMessage.replace(/\s+/g, ' ').trim();
+    if (compact.length <= maxChars) {
+        return compact;
+    }
+    return `${compact.slice(0, maxChars - 3)}...`;
+}
+function createSchemaRetryPrompt(prompt, errorMessage, deterministicJson) {
+    const summarizedError = summarizeSchemaValidationErrorForRetry(errorMessage);
+    const deterministicNote = deterministicJson
+        ? `\n${DETERMINISTIC_JSON_RETRY_NOTE}`
+        : '';
+    return {
+        summarizedError,
+        prompt: `${prompt}\n\nCRITICAL: The previous response failed schema validation. Error: ${summarizedError}${deterministicNote}`,
+    };
+}
 function createGenerationRequest(config, promptParts, responseSchema, onLog, signal) {
     const request = {
         systemInstruction: promptParts.systemInstruction,
@@ -46,13 +79,23 @@ function createGenerationRequest(config, promptParts, responseSchema, onLog, sig
     if (config.includeThoughts !== undefined) {
         request.includeThoughts = config.includeThoughts;
     }
+    if (config.deterministicJson) {
+        const responseKeyOrdering = extractResponseKeyOrdering(responseSchema);
+        if (responseKeyOrdering !== undefined) {
+            request.responseKeyOrdering = responseKeyOrdering;
+        }
+    }
+    if (config.batchMode !== undefined) {
+        request.batchMode = config.batchMode;
+    }
     if (signal !== undefined) {
         request.signal = signal;
     }
     return request;
 }
+const VALIDATION_ERROR_PATTERN = /validation/i;
 function classifyErrorMeta(error, message) {
-    if (error instanceof z.ZodError || /validation/i.test(message)) {
+    if (error instanceof z.ZodError || VALIDATION_ERROR_PATTERN.test(message)) {
         return {
             kind: 'validation',
             retryable: false,
@@ -341,11 +384,16 @@ export function registerStructuredToolTask(server, config) {
                                 throw error;
                             }
                             const errorMessage = getErrorMessage(error);
+                            const schemaRetryPrompt = createSchemaRetryPrompt(prompt, errorMessage, config.deterministicJson === true);
                             await onLog('warning', {
                                 event: 'schema_validation_failed',
-                                details: { attempt, error: errorMessage },
+                                details: {
+                                    attempt,
+                                    error: schemaRetryPrompt.summarizedError,
+                                    originalChars: errorMessage.length,
+                                },
                             });
-                            retryPrompt = `${prompt}\n\nCRITICAL: The previous response failed schema validation. Error: ${errorMessage}`;
+                            retryPrompt = schemaRetryPrompt.prompt;
                         }
                     }
                     if (!parsed) {

package/dist/lib/types.d.ts

@@ -1,5 +1,8 @@
 export type JsonObject = Record<string, unknown>;
 export type GeminiLogHandler = (level: string, data: unknown) => Promise<void>;
+export interface GeminiFunctionCallingContext {
+    readonly modelParts: readonly unknown[];
+}
 export interface GeminiRequestExecutionOptions {
     maxRetries?: number;
     timeoutMs?: number;
@@ -9,6 +12,9 @@ export interface GeminiRequestExecutionOptions {
     includeThoughts?: boolean;
     signal?: AbortSignal;
     onLog?: GeminiLogHandler;
+    responseKeyOrdering?: readonly string[];
+    functionCallingContext?: GeminiFunctionCallingContext;
+    batchMode?: 'off' | 'inline';
 }
 export interface GeminiStructuredRequestOptions extends GeminiRequestExecutionOptions {
     model?: string;

package/dist/resources/server-config.js

@@ -8,13 +8,18 @@ const DEFAULT_CONCURRENT_WAIT_MS = 2_000;
 const DEFAULT_SAFETY_THRESHOLD = 'BLOCK_NONE';
 const GEMINI_HARM_BLOCK_THRESHOLD_ENV_VAR = 'GEMINI_HARM_BLOCK_THRESHOLD';
 const GEMINI_MODEL_ENV_VAR = 'GEMINI_MODEL';
+const GEMINI_BATCH_MODE_ENV_VAR = 'GEMINI_BATCH_MODE';
 const diffCharsConfig = createCachedEnvInt('MAX_DIFF_CHARS', DEFAULT_MAX_DIFF_CHARS);
 const contextCharsConfig = createCachedEnvInt('MAX_CONTEXT_CHARS', DEFAULT_MAX_CONTEXT_CHARS);
 const concurrentCallsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS', DEFAULT_MAX_CONCURRENT_CALLS);
+const concurrentBatchCallsConfig = createCachedEnvInt('MAX_CONCURRENT_BATCH_CALLS', 2);
 const concurrentWaitConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS_WAIT_MS', DEFAULT_CONCURRENT_WAIT_MS);
 function getModelOverride() {
     return process.env[GEMINI_MODEL_ENV_VAR] ?? FLASH_MODEL;
 }
+function getBatchMode() {
+    return process.env[GEMINI_BATCH_MODE_ENV_VAR] ?? 'off';
+}
 function getSafetyThreshold() {
     return (process.env[GEMINI_HARM_BLOCK_THRESHOLD_ENV_VAR] ?? DEFAULT_SAFETY_THRESHOLD);
 }
@@ -31,8 +36,10 @@ export function buildServerConfig() {
     const maxDiffChars = diffCharsConfig.get();
     const maxContextChars = contextCharsConfig.get();
     const maxConcurrent = concurrentCallsConfig.get();
+    const maxConcurrentBatch = concurrentBatchCallsConfig.get();
     const concurrentWaitMs = concurrentWaitConfig.get();
     const defaultModel = getModelOverride();
+    const batchMode = getBatchMode();
     const safetyThreshold = getSafetyThreshold();
     const toolRows = getToolContracts()
         .filter((contract) => contract.model !== 'none')
@@ -49,7 +56,9 @@ export function buildServerConfig() {
 | Diff limit | ${formatNumber(maxDiffChars)} chars | \`MAX_DIFF_CHARS\` |
 | Context limit (inspect) | ${formatNumber(maxContextChars)} chars | \`MAX_CONTEXT_CHARS\` |
 | Concurrency limit | ${maxConcurrent} | \`MAX_CONCURRENT_CALLS\` |
+| Batch concurrency limit | ${maxConcurrentBatch} | \`MAX_CONCURRENT_BATCH_CALLS\` |
 | Wait timeout | ${formatNumber(concurrentWaitMs)}ms | \`MAX_CONCURRENT_CALLS_WAIT_MS\` |
+| Batch mode | ${batchMode} | \`GEMINI_BATCH_MODE\` |
 
 ## Model Assignments
 
@@ -67,5 +76,11 @@ ${toolRows}
 ## API Keys
 
 - Set \`GEMINI_API_KEY\` or \`GOOGLE_API_KEY\` environment variable (required)
+
+## Batch Mode
+
+- \`GEMINI_BATCH_MODE\`: \`off\` (default) or \`inline\`
+- \`GEMINI_BATCH_POLL_INTERVAL_MS\`: poll cadence for batch status checks
+- \`GEMINI_BATCH_TIMEOUT_MS\`: max wait for batch completion
 `;
 }

package/dist/tools/analyze-complexity.js

@@ -29,6 +29,9 @@ export function registerAnalyzeComplexityTool(server) {
         ...(TOOL_CONTRACT.temperature !== undefined
             ? { temperature: TOOL_CONTRACT.temperature }
             : undefined),
+        ...(TOOL_CONTRACT.deterministicJson !== undefined
+            ? { deterministicJson: TOOL_CONTRACT.deterministicJson }
+            : undefined),
         validateInput: (_input, ctx) => {
             const slot = ctx.diffSlot;
             if (!slot)

package/dist/tools/analyze-pr-impact.js

@@ -1,5 +1,5 @@
 import { validateDiffBudget } from '../lib/diff-budget.js';
-import { computeDiffStatsAndSummaryFromFiles, parseDiffFiles, } from '../lib/diff-parser.js';
+import { computeDiffStatsAndSummaryFromFiles } from '../lib/diff-parser.js';
 import { createNoDiffError } from '../lib/diff-store.js';
 import { requireToolContract } from '../lib/tool-contracts.js';
 import { registerStructuredToolTask } from '../lib/tool-factory.js';
@@ -33,6 +33,9 @@ export function registerAnalyzePrImpactTool(server) {
         ...(TOOL_CONTRACT.temperature !== undefined
             ? { temperature: TOOL_CONTRACT.temperature }
             : undefined),
+        ...(TOOL_CONTRACT.deterministicJson !== undefined
+            ? { deterministicJson: TOOL_CONTRACT.deterministicJson }
+            : undefined),
         validateInput: (_input, ctx) => {
             const slot = ctx.diffSlot;
             if (!slot)
@@ -43,7 +46,7 @@ export function registerAnalyzePrImpactTool(server) {
         formatOutput: (result) => `Impact Analysis (${result.severity}): ${result.summary}`,
         buildPrompt: (input, ctx) => {
             const diff = ctx.diffSlot?.diff ?? '';
-            const files = parseDiffFiles(diff);
+            const files = ctx.diffSlot?.parsedFiles ?? [];
             const { stats, summary: fileSummary } = computeDiffStatsAndSummaryFromFiles(files);
             const languageSegment = formatLanguageSegment(input.language);
             return {

package/dist/tools/detect-api-breaking.js

@@ -29,6 +29,9 @@ export function registerDetectApiBreakingTool(server) {
         ...(TOOL_CONTRACT.temperature !== undefined
             ? { temperature: TOOL_CONTRACT.temperature }
             : undefined),
+        ...(TOOL_CONTRACT.deterministicJson !== undefined
+            ? { deterministicJson: TOOL_CONTRACT.deterministicJson }
+            : undefined),
         validateInput: (_input, ctx) => {
             const slot = ctx.diffSlot;
             if (!slot)

package/dist/tools/generate-diff.js

@@ -59,7 +59,7 @@ export function registerGenerateDiffTool(server) {
         const parsedFiles = parseDiffFiles(cleaned);
         const stats = computeDiffStatsFromFiles(parsedFiles);
         const generatedAt = new Date().toISOString();
-        storeDiff({ diff: cleaned, stats, generatedAt, mode });
+        storeDiff({ diff: cleaned, parsedFiles, stats, generatedAt, mode });
         const summary = `Diff cached at ${DIFF_RESOURCE_URI} — ${stats.files} file(s), +${stats.added} -${stats.deleted}. All review tools are now ready.`;
         return createToolResponse({
             ok: true,

package/dist/tools/generate-review-summary.js

@@ -1,5 +1,4 @@
 import { validateDiffBudget } from '../lib/diff-budget.js';
-import { computeDiffStatsFromFiles, parseDiffFiles, } from '../lib/diff-parser.js';
 import { createNoDiffError } from '../lib/diff-store.js';
 import { requireToolContract } from '../lib/tool-contracts.js';
 import { registerStructuredToolTask, } from '../lib/tool-factory.js';
@@ -18,9 +17,16 @@ function formatLanguageSegment(language) {
     return language ? `\nLanguage: ${language}` : '';
 }
 function getDiffStats(ctx) {
-    const diff = ctx.diffSlot?.diff ?? '';
-    const { files, added, deleted } = computeDiffStatsFromFiles(parseDiffFiles(diff));
-    return { diff, files, added, deleted };
+    const slot = ctx.diffSlot;
+    if (!slot) {
+        return { diff: '', files: 0, added: 0, deleted: 0 };
+    }
+    return {
+        diff: slot.diff,
+        files: slot.stats.files,
+        added: slot.stats.added,
+        deleted: slot.stats.deleted,
+    };
 }
 export function registerGenerateReviewSummaryTool(server) {
     registerStructuredToolTask(server, {
@@ -40,6 +46,9 @@ export function registerGenerateReviewSummaryTool(server) {
         ...(TOOL_CONTRACT.temperature !== undefined
             ? { temperature: TOOL_CONTRACT.temperature }
             : undefined),
+        ...(TOOL_CONTRACT.deterministicJson !== undefined
+            ? { deterministicJson: TOOL_CONTRACT.deterministicJson }
+            : undefined),
         validateInput: (_input, ctx) => {
             const slot = ctx.diffSlot;
             if (!slot)

package/dist/tools/generate-test-plan.js

@@ -1,5 +1,5 @@
 import { validateDiffBudget } from '../lib/diff-budget.js';
-import { computeDiffStatsAndPathsFromFiles, parseDiffFiles, } from '../lib/diff-parser.js';
+import { computeDiffStatsAndPathsFromFiles } from '../lib/diff-parser.js';
 import { createNoDiffError } from '../lib/diff-store.js';
 import { requireToolContract } from '../lib/tool-contracts.js';
 import { registerStructuredToolTask } from '../lib/tool-factory.js';
@@ -33,6 +33,9 @@ export function registerGenerateTestPlanTool(server) {
         ...(TOOL_CONTRACT.temperature !== undefined
             ? { temperature: TOOL_CONTRACT.temperature }
             : undefined),
+        ...(TOOL_CONTRACT.deterministicJson !== undefined
+            ? { deterministicJson: TOOL_CONTRACT.deterministicJson }
+            : undefined),
         validateInput: (_input, ctx) => {
             const slot = ctx.diffSlot;
             if (!slot)
@@ -47,7 +50,7 @@ export function registerGenerateTestPlanTool(server) {
         },
         buildPrompt: (input, ctx) => {
             const diff = ctx.diffSlot?.diff ?? '';
-            const parsedFiles = parseDiffFiles(diff);
+            const parsedFiles = ctx.diffSlot?.parsedFiles ?? [];
             const { stats, paths } = computeDiffStatsAndPathsFromFiles(parsedFiles);
             const languageLine = formatOptionalLine('Language', input.language);
             const frameworkLine = formatOptionalLine('Test Framework', input.testFramework);

package/dist/tools/inspect-code-quality.js

@@ -1,6 +1,6 @@
 import { validateContextBudget } from '../lib/context-budget.js';
 import { validateDiffBudget } from '../lib/diff-budget.js';
-import { computeDiffStatsAndSummaryFromFiles, parseDiffFiles, } from '../lib/diff-parser.js';
+import { computeDiffStatsAndSummaryFromFiles } from '../lib/diff-parser.js';
 import { createNoDiffError } from '../lib/diff-store.js';
 import { requireToolContract } from '../lib/tool-contracts.js';
 import { registerStructuredToolTask } from '../lib/tool-factory.js';
@@ -69,6 +69,9 @@ export function registerInspectCodeQualityTool(server) {
         ...(TOOL_CONTRACT.temperature !== undefined
             ? { temperature: TOOL_CONTRACT.temperature }
             : undefined),
+        ...(TOOL_CONTRACT.deterministicJson !== undefined
+            ? { deterministicJson: TOOL_CONTRACT.deterministicJson }
+            : undefined),
         progressContext: (input) => {
             const fileCount = input.files?.length;
             return fileCount ? `+${fileCount} files` : '';
@@ -98,7 +101,7 @@ export function registerInspectCodeQualityTool(server) {
         },
         buildPrompt: (input, ctx) => {
             const diff = ctx.diffSlot?.diff ?? '';
-            const parsedFiles = parseDiffFiles(diff);
+            const parsedFiles = ctx.diffSlot?.parsedFiles ?? [];
             const { summary: fileSummary } = computeDiffStatsAndSummaryFromFiles(parsedFiles);
             const fileContext = formatFileContext(input.files);
             const languageLine = formatOptionalLine('Language', input.language);

package/dist/tools/suggest-search-replace.js

@@ -1,5 +1,5 @@
 import { validateDiffBudget } from '../lib/diff-budget.js';
-import { extractChangedPathsFromFiles, parseDiffFiles, } from '../lib/diff-parser.js';
+import { extractChangedPathsFromFiles } from '../lib/diff-parser.js';
 import { createNoDiffError } from '../lib/diff-store.js';
 import { requireToolContract } from '../lib/tool-contracts.js';
 import { registerStructuredToolTask } from '../lib/tool-factory.js';
@@ -33,6 +33,9 @@ export function registerSuggestSearchReplaceTool(server) {
         ...(TOOL_CONTRACT.temperature !== undefined
             ? { temperature: TOOL_CONTRACT.temperature }
             : undefined),
+        ...(TOOL_CONTRACT.deterministicJson !== undefined
+            ? { deterministicJson: TOOL_CONTRACT.deterministicJson }
+            : undefined),
         validateInput: (_input, ctx) => {
             const slot = ctx.diffSlot;
             if (!slot)
@@ -47,7 +50,7 @@ export function registerSuggestSearchReplaceTool(server) {
         },
         buildPrompt: (input, ctx) => {
             const diff = ctx.diffSlot?.diff ?? '';
-            const files = parseDiffFiles(diff);
+            const files = ctx.diffSlot?.parsedFiles ?? [];
             const paths = extractChangedPathsFromFiles(files);
             return {
                 systemInstruction: SYSTEM_INSTRUCTION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/code-review-analyst-mcp",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "mcpName": "io.github.j0hanz/code-review-analyst",
   "description": "Gemini-powered MCP server for code review analysis.",
   "type": "module",