@j0hanz/code-review-analyst-mcp 1.0.3 → 1.2.0

package/dist/lib/gemini-schema.js

@@ -1,9 +1,3 @@
-/**
- * JSON Schema property keys that represent value-range or count constraints.
- * These are stripped when generating relaxed schemas for Gemini structured
- * output so the model is not over-constrained by bounds that the
- * application-level result schema enforces after parsing.
- */
 const CONSTRAINT_KEYS = new Set([
     'minLength',
     'maxLength',
@@ -15,6 +9,24 @@ const CONSTRAINT_KEYS = new Set([
     'maxItems',
     'multipleOf',
 ]);
+const INTEGER_JSON_TYPE = 'integer';
+const NUMBER_JSON_TYPE = 'number';
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stripConstraintValue(value) {
+    if (Array.isArray(value)) {
+        const stripped = new Array(value.length);
+        for (let index = 0; index < value.length; index += 1) {
+            stripped[index] = stripConstraintValue(value[index]);
+        }
+        return stripped;
+    }
+    if (isJsonRecord(value)) {
+        return stripJsonSchemaConstraints(value);
+    }
+    return value;
+}
 /**
  * Recursively strips value-range constraints (`min*`, `max*`, `multipleOf`)
  * from a JSON Schema object and converts `"type": "integer"` to
@@ -31,21 +43,11 @@ export function stripJsonSchemaConstraints(schema) {
             continue;
         // Relax integer → number so Gemini is not forced into integer-only
         // output; the stricter result schema still validates integrality.
-        if (key === 'type' && value === 'integer') {
-            result[key] = 'number';
+        if (key === 'type' && value === INTEGER_JSON_TYPE) {
+            result[key] = NUMBER_JSON_TYPE;
             continue;
         }
-        if (Array.isArray(value)) {
-            result[key] = value.map((item) => typeof item === 'object' && item !== null && !Array.isArray(item)
-                ? stripJsonSchemaConstraints(item)
-                : item);
-        }
-        else if (typeof value === 'object' && value !== null) {
-            result[key] = stripJsonSchemaConstraints(value);
-        }
-        else {
-            result[key] = value;
-        }
+        result[key] = stripConstraintValue(value);
     }
     return result;
 }

package/dist/lib/gemini.d.ts

@@ -2,5 +2,6 @@ import { EventEmitter } from 'node:events';
 import { GoogleGenAI } from '@google/genai';
 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 generateStructuredJson(request: GeminiStructuredRequest): Promise<unknown>;

package/dist/lib/gemini.js

@@ -3,18 +3,45 @@ import { randomInt, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { performance } from 'node:perf_hooks';
 import { setTimeout as sleep } from 'node:timers/promises';
+import { debuglog } from 'node:util';
 import { GoogleGenAI, HarmBlockThreshold, HarmCategory } from '@google/genai';
-import { getErrorMessage } from './errors.js';
+import { createCachedEnvInt } from './env-config.js';
+import { getErrorMessage, RETRYABLE_UPSTREAM_ERROR_PATTERN } from './errors.js';
+// Lazy-cached: first call happens after parseCommandLineArgs() sets GEMINI_MODEL.
+let _defaultModel;
 function getDefaultModel() {
-    return process.env.GEMINI_MODEL ?? 'gemini-2.5-flash';
+    if (_defaultModel !== undefined)
+        return _defaultModel;
+    const value = process.env.GEMINI_MODEL ?? 'gemini-2.5-flash';
+    _defaultModel = value;
+    return value;
 }
 const DEFAULT_MAX_RETRIES = 1;
-const DEFAULT_TIMEOUT_MS = 45_000;
+const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_OUTPUT_TOKENS = 16_384;
 const RETRY_DELAY_BASE_MS = 300;
 const RETRY_DELAY_MAX_MS = 5_000;
 const RETRY_JITTER_RATIO = 0.2;
 const DEFAULT_SAFETY_THRESHOLD = HarmBlockThreshold.BLOCK_NONE;
+const UNKNOWN_REQUEST_CONTEXT_VALUE = 'unknown';
+const RETRYABLE_NUMERIC_CODES = new Set([429, 500, 502, 503, 504]);
+const maxConcurrentCallsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS', 10);
+const concurrencyWaitMsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS_WAIT_MS', 2_000);
+const concurrencyPollMsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS_POLL_MS', 25);
+let activeCalls = 0;
+const RETRYABLE_TRANSIENT_CODES = new Set([
+    'RESOURCE_EXHAUSTED',
+    'UNAVAILABLE',
+    'DEADLINE_EXCEEDED',
+    'INTERNAL',
+    'ABORTED',
+]);
+const SAFETY_CATEGORIES = [
+    HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+    HarmCategory.HARM_CATEGORY_HARASSMENT,
+    HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+];
 const numberFormatter = new Intl.NumberFormat('en-US');
 function formatNumber(value) {
     return numberFormatter.format(value);
@@ -25,14 +52,71 @@ const SAFETY_THRESHOLD_BY_NAME = {
     BLOCK_MEDIUM_AND_ABOVE: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
     BLOCK_LOW_AND_ABOVE: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
 };
+let cachedSafetyThresholdEnv;
+let cachedSafetyThreshold = DEFAULT_SAFETY_THRESHOLD;
+const safetySettingsCache = new Map();
+function getSafetyThreshold() {
+    const threshold = process.env.GEMINI_HARM_BLOCK_THRESHOLD;
+    if (threshold === cachedSafetyThresholdEnv) {
+        return cachedSafetyThreshold;
+    }
+    cachedSafetyThresholdEnv = threshold;
+    if (!threshold) {
+        cachedSafetyThreshold = DEFAULT_SAFETY_THRESHOLD;
+        return cachedSafetyThreshold;
+    }
+    const normalizedThreshold = threshold.trim().toUpperCase();
+    if (normalizedThreshold in SAFETY_THRESHOLD_BY_NAME) {
+        cachedSafetyThreshold =
+            SAFETY_THRESHOLD_BY_NAME[normalizedThreshold];
+        return cachedSafetyThreshold;
+    }
+    cachedSafetyThreshold = DEFAULT_SAFETY_THRESHOLD;
+    return cachedSafetyThreshold;
+}
+function getThinkingConfig(thinkingBudget) {
+    return thinkingBudget !== undefined
+        ? { includeThoughts: true, thinkingBudget }
+        : undefined;
+}
+function getSafetySettings(threshold) {
+    const cached = safetySettingsCache.get(threshold);
+    if (cached) {
+        return cached;
+    }
+    const settings = new Array(SAFETY_CATEGORIES.length);
+    let index = 0;
+    for (const category of SAFETY_CATEGORIES) {
+        settings[index] = { category, threshold };
+        index += 1;
+    }
+    safetySettingsCache.set(threshold, settings);
+    return settings;
+}
 let cachedClient;
 export const geminiEvents = new EventEmitter();
+const debug = debuglog('gemini');
 geminiEvents.on('log', (payload) => {
-    console.error(JSON.stringify(payload));
+    if (debug.enabled) {
+        debug('%j', payload);
+    }
 });
 const geminiContext = new AsyncLocalStorage({
     name: 'gemini_request',
+    defaultValue: {
+        requestId: UNKNOWN_REQUEST_CONTEXT_VALUE,
+        model: UNKNOWN_REQUEST_CONTEXT_VALUE,
+    },
 });
+// Shared fallback avoids a fresh object allocation per logEvent call when outside a run context.
+const UNKNOWN_CONTEXT = {
+    requestId: UNKNOWN_REQUEST_CONTEXT_VALUE,
+    model: UNKNOWN_REQUEST_CONTEXT_VALUE,
+};
+export function getCurrentRequestId() {
+    const context = geminiContext.getStore();
+    return context?.requestId ?? UNKNOWN_REQUEST_CONTEXT_VALUE;
+}
 function getApiKey() {
     const apiKey = process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY;
     if (!apiKey) {
@@ -51,38 +135,79 @@ function nextRequestId() {
     return randomUUID();
 }
 function logEvent(event, details) {
-    const context = geminiContext.getStore();
+    const context = geminiContext.getStore() ?? UNKNOWN_CONTEXT;
     geminiEvents.emit('log', {
         event,
-        requestId: context?.requestId ?? null,
-        model: context?.model ?? null,
+        requestId: context.requestId,
+        model: context.model,
         ...details,
     });
 }
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    return value;
+}
+async function safeCallOnLog(onLog, level, data) {
+    try {
+        await onLog?.(level, data);
+    }
+    catch {
+        // Log callbacks are best-effort; never fail the tool call.
+    }
+}
+async function emitGeminiLog(onLog, level, payload) {
+    logEvent(payload.event, payload.details);
+    await safeCallOnLog(onLog, level, {
+        event: payload.event,
+        ...payload.details,
+    });
+}
 function getNestedError(error) {
-    if (!error || typeof error !== 'object') {
+    const record = asRecord(error);
+    if (!record) {
         return undefined;
     }
-    const record = error;
     const nested = record.error;
-    if (!nested || typeof nested !== 'object') {
+    const nestedRecord = asRecord(nested);
+    if (!nestedRecord) {
         return record;
     }
-    return nested;
+    return nestedRecord;
+}
+function toNumericCode(candidate) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+        return candidate;
+    }
+    if (typeof candidate === 'string' && /^\d+$/.test(candidate)) {
+        return Number.parseInt(candidate, 10);
+    }
+    return undefined;
+}
+function toUpperStringCode(candidate) {
+    if (typeof candidate !== 'string') {
+        return undefined;
+    }
+    const normalized = candidate.trim().toUpperCase();
+    return normalized.length > 0 ? normalized : undefined;
 }
 function getNumericErrorCode(error) {
     const record = getNestedError(error);
     if (!record) {
         return undefined;
     }
-    const candidates = [record.status, record.statusCode, record.code];
-    for (const candidate of candidates) {
-        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
-            return candidate;
-        }
-        if (typeof candidate === 'string' && /^\d+$/.test(candidate)) {
-            return Number.parseInt(candidate, 10);
-        }
+    const fromStatus = toNumericCode(record.status);
+    if (fromStatus !== undefined) {
+        return fromStatus;
+    }
+    const fromStatusCode = toNumericCode(record.statusCode);
+    if (fromStatusCode !== undefined) {
+        return fromStatusCode;
+    }
+    const fromCode = toNumericCode(record.code);
+    if (fromCode !== undefined) {
+        return fromCode;
     }
     return undefined;
 }
@@ -91,33 +216,32 @@ function getTransientErrorCode(error) {
     if (!record) {
         return undefined;
     }
-    const candidates = [record.code, record.status, record.statusText];
-    for (const candidate of candidates) {
-        if (typeof candidate === 'string' && candidate.trim().length > 0) {
-            return candidate.trim().toUpperCase();
-        }
+    const fromCode = toUpperStringCode(record.code);
+    if (fromCode !== undefined) {
+        return fromCode;
+    }
+    const fromStatus = toUpperStringCode(record.status);
+    if (fromStatus !== undefined) {
+        return fromStatus;
+    }
+    const fromStatusText = toUpperStringCode(record.statusText);
+    if (fromStatusText !== undefined) {
+        return fromStatusText;
     }
     return undefined;
 }
 function shouldRetry(error) {
     const numericCode = getNumericErrorCode(error);
-    if (numericCode === 429 ||
-        numericCode === 500 ||
-        numericCode === 502 ||
-        numericCode === 503 ||
-        numericCode === 504) {
+    if (numericCode !== undefined && RETRYABLE_NUMERIC_CODES.has(numericCode)) {
         return true;
     }
     const transientCode = getTransientErrorCode(error);
-    if (transientCode === 'RESOURCE_EXHAUSTED' ||
-        transientCode === 'UNAVAILABLE' ||
-        transientCode === 'DEADLINE_EXCEEDED' ||
-        transientCode === 'INTERNAL' ||
-        transientCode === 'ABORTED') {
+    if (transientCode !== undefined &&
+        RETRYABLE_TRANSIENT_CODES.has(transientCode)) {
         return true;
     }
     const message = getErrorMessage(error);
-    return /(429|500|502|503|504|rate limit|unavailable|timeout|invalid json)/i.test(message);
+    return RETRYABLE_UPSTREAM_ERROR_PATTERN.test(message);
 }
 function getRetryDelayMs(attempt) {
     const exponentialDelay = RETRY_DELAY_BASE_MS * 2 ** attempt;
@@ -126,57 +250,44 @@ function getRetryDelayMs(attempt) {
     const jitter = randomInt(0, jitterWindow);
     return Math.min(RETRY_DELAY_MAX_MS, boundedDelay + jitter);
 }
-function getSafetyThreshold() {
-    const threshold = process.env.GEMINI_HARM_BLOCK_THRESHOLD;
-    if (!threshold) {
-        return DEFAULT_SAFETY_THRESHOLD;
-    }
-    const normalizedThreshold = threshold.trim().toUpperCase();
-    if (normalizedThreshold in SAFETY_THRESHOLD_BY_NAME) {
-        return SAFETY_THRESHOLD_BY_NAME[normalizedThreshold];
-    }
-    return DEFAULT_SAFETY_THRESHOLD;
-}
 function buildGenerationConfig(request, abortSignal) {
-    const safetyThreshold = getSafetyThreshold();
+    const systemInstruction = request.systemInstruction
+        ? { systemInstruction: request.systemInstruction }
+        : undefined;
+    const thinkingConfig = getThinkingConfig(request.thinkingBudget);
+    const safetySettings = getSafetySettings(getSafetyThreshold());
     return {
         temperature: request.temperature ?? 0.2,
         maxOutputTokens: request.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
         responseMimeType: 'application/json',
         responseSchema: request.responseSchema,
-        ...(request.systemInstruction
-            ? { systemInstruction: request.systemInstruction }
-            : {}),
-        safetySettings: [
-            {
-                category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
-                threshold: safetyThreshold,
-            },
-            {
-                category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
-                threshold: safetyThreshold,
-            },
-            {
-                category: HarmCategory.HARM_CATEGORY_HARASSMENT,
-                threshold: safetyThreshold,
-            },
-            {
-                category: HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
-                threshold: safetyThreshold,
-            },
-        ],
+        ...(systemInstruction ?? undefined),
+        ...(thinkingConfig ? { thinkingConfig } : undefined),
+        safetySettings,
         abortSignal,
     };
 }
+function combineSignals(signal, requestSignal) {
+    return requestSignal ? AbortSignal.any([signal, requestSignal]) : signal;
+}
+function parseStructuredResponse(responseText) {
+    if (!responseText) {
+        throw new Error('Gemini returned an empty response body.');
+    }
+    try {
+        return JSON.parse(responseText);
+    }
+    catch (error) {
+        throw new Error(`Model produced invalid JSON: ${getErrorMessage(error)}`);
+    }
+}
 async function generateContentWithTimeout(request, model, timeoutMs) {
     const controller = new AbortController();
     const timeout = setTimeout(() => {
         controller.abort();
     }, timeoutMs);
     timeout.unref();
-    const signal = request.signal
-        ? AbortSignal.any([controller.signal, request.signal])
-        : controller.signal;
+    const signal = combineSignals(controller.signal, request.signal);
     try {
         return await getClient().models.generateContent({
             model,
@@ -189,7 +300,7 @@ async function generateContentWithTimeout(request, model, timeoutMs) {
             throw new Error('Gemini request was cancelled.');
         }
         if (controller.signal.aborted) {
-            throw new Error(`Gemini request timed out after ${formatNumber(timeoutMs)}ms.`);
+            throw new Error(`Gemini request timed out after ${formatNumber(timeoutMs)}ms.`, { cause: error });
         }
         throw error;
     }
@@ -197,52 +308,90 @@ async function generateContentWithTimeout(request, model, timeoutMs) {
         clearTimeout(timeout);
     }
 }
+async function executeAttempt(request, model, timeoutMs, attempt, onLog) {
+    const startedAt = performance.now();
+    const response = await generateContentWithTimeout(request, model, timeoutMs);
+    const latencyMs = Math.round(performance.now() - startedAt);
+    await emitGeminiLog(onLog, 'info', {
+        event: 'gemini_call',
+        details: {
+            attempt,
+            latencyMs,
+            usageMetadata: response.usageMetadata ?? null,
+        },
+    });
+    return parseStructuredResponse(response.text);
+}
+async function waitBeforeRetry(attempt, error, onLog) {
+    const delayMs = getRetryDelayMs(attempt);
+    const reason = getErrorMessage(error);
+    await emitGeminiLog(onLog, 'warning', {
+        event: 'gemini_retry',
+        details: {
+            attempt,
+            delayMs,
+            reason,
+        },
+    });
+    await sleep(delayMs, undefined, { ref: false });
+}
+async function throwGeminiFailure(maxRetries, lastError, onLog) {
+    const attempts = maxRetries + 1;
+    const message = getErrorMessage(lastError);
+    await emitGeminiLog(onLog, 'error', {
+        event: 'gemini_failure',
+        details: {
+            error: message,
+            attempts,
+        },
+    });
+    throw new Error(`Gemini request failed after ${attempts} attempts: ${message}`, { cause: lastError });
+}
+async function runWithRetries(request, model, timeoutMs, maxRetries, onLog) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+        try {
+            return await executeAttempt(request, model, timeoutMs, attempt, onLog);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxRetries || !shouldRetry(error)) {
+                break;
+            }
+            await waitBeforeRetry(attempt, error, onLog);
+        }
+    }
+    return throwGeminiFailure(maxRetries, lastError, onLog);
+}
+async function waitForConcurrencySlot(limit, requestSignal) {
+    const waitLimitMs = concurrencyWaitMsConfig.get();
+    const pollMs = concurrencyPollMsConfig.get();
+    const startedAt = performance.now();
+    while (activeCalls >= limit) {
+        if (requestSignal?.aborted) {
+            throw new Error('Gemini request was cancelled.');
+        }
+        const elapsedMs = performance.now() - startedAt;
+        if (elapsedMs >= waitLimitMs) {
+            throw new Error(`Too many concurrent Gemini calls (limit: ${formatNumber(limit)}; waited ${formatNumber(waitLimitMs)}ms).`);
+        }
+        await sleep(pollMs, undefined, { ref: false });
+    }
+}
 export async function generateStructuredJson(request) {
     const model = request.model ?? getDefaultModel();
     const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const maxRetries = request.maxRetries ?? DEFAULT_MAX_RETRIES;
-    return geminiContext.run({ requestId: nextRequestId(), model }, async () => {
-        let lastError;
-        for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
-            const startedAt = performance.now();
-            try {
-                const response = await generateContentWithTimeout(request, model, timeoutMs);
-                logEvent('gemini_call', {
-                    attempt,
-                    latencyMs: Math.round(performance.now() - startedAt),
-                    usageMetadata: response.usageMetadata ?? null,
-                });
-                if (!response.text) {
-                    throw new Error('Gemini returned an empty response body.');
-                }
-                let parsed;
-                try {
-                    parsed = JSON.parse(response.text);
-                }
-                catch (error) {
-                    throw new Error(`Model produced invalid JSON: ${getErrorMessage(error)}`);
-                }
-                return parsed;
-            }
-            catch (error) {
-                lastError = error;
-                const retryable = shouldRetry(error);
-                if (attempt >= maxRetries || !retryable) {
-                    break;
-                }
-                const delayMs = getRetryDelayMs(attempt);
-                logEvent('gemini_retry', {
-                    attempt,
-                    delayMs,
-                    reason: getErrorMessage(error),
-                });
-                await sleep(delayMs, undefined, { ref: false });
-            }
-        }
-        logEvent('gemini_failure', {
-            error: getErrorMessage(lastError),
-            attempts: maxRetries + 1,
+    const { onLog } = request;
+    const limit = maxConcurrentCallsConfig.get();
+    await waitForConcurrencySlot(limit, request.signal);
+    activeCalls += 1;
+    try {
+        return await geminiContext.run({ requestId: nextRequestId(), model }, async () => {
+            return runWithRetries(request, model, timeoutMs, maxRetries, onLog);
         });
-        throw new Error(`Gemini request failed after ${maxRetries + 1} attempts: ${getErrorMessage(lastError)}`);
-    });
+    }
+    finally {
+        activeCalls -= 1;
+    }
 }

package/dist/lib/model-config.d.ts

@@ -0,0 +1,17 @@
+/** Fast, cost-effective model for summarization and light analysis. */
+export declare const FLASH_MODEL = "gemini-2.5-flash";
+/** High-capability model for deep reasoning, quality inspection, and reliable code generation. */
+export declare const PRO_MODEL = "gemini-2.5-pro";
+/** Thinking budget (tokens) for Flash model thinking tasks (test plans, search/replace). */
+export declare const FLASH_THINKING_BUDGET = 8192;
+/** Thinking budget (tokens) for Pro model deep-analysis tasks (code quality inspection). */
+export declare const PRO_THINKING_BUDGET = 16384;
+/** Extended timeout for Pro model calls (ms). Pro thinks longer than Flash. */
+export declare const DEFAULT_TIMEOUT_PRO_MS = 120000;
+export declare const MODEL_TIMEOUT_MS: {
+    readonly defaultPro: 120000;
+};
+/** Default language hint when not specified by the user. Tells the model to auto-detect. */
+export declare const DEFAULT_LANGUAGE = "detect";
+/** Default test-framework hint when not specified by the user. Tells the model to auto-detect. */
+export declare const DEFAULT_FRAMEWORK = "detect";

package/dist/lib/model-config.js

@@ -0,0 +1,19 @@
+/** Fast, cost-effective model for summarization and light analysis. */
+export const FLASH_MODEL = 'gemini-2.5-flash';
+/** High-capability model for deep reasoning, quality inspection, and reliable code generation. */
+export const PRO_MODEL = 'gemini-2.5-pro';
+const FLASH_THINKING_BUDGET_VALUE = 8_192;
+const PRO_THINKING_BUDGET_VALUE = 16_384;
+/** Thinking budget (tokens) for Flash model thinking tasks (test plans, search/replace). */
+export const FLASH_THINKING_BUDGET = FLASH_THINKING_BUDGET_VALUE;
+/** Thinking budget (tokens) for Pro model deep-analysis tasks (code quality inspection). */
+export const PRO_THINKING_BUDGET = PRO_THINKING_BUDGET_VALUE;
+/** Extended timeout for Pro model calls (ms). Pro thinks longer than Flash. */
+export const DEFAULT_TIMEOUT_PRO_MS = 120_000;
+export const MODEL_TIMEOUT_MS = {
+    defaultPro: DEFAULT_TIMEOUT_PRO_MS,
+};
+/** Default language hint when not specified by the user. Tells the model to auto-detect. */
+export const DEFAULT_LANGUAGE = 'detect';
+/** Default test-framework hint when not specified by the user. Tells the model to auto-detect. */
+export const DEFAULT_FRAMEWORK = 'detect';

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

@@ -6,26 +6,38 @@ export interface PromptParts {
     systemInstruction: string;
     prompt: string;
 }
-export interface StructuredToolTaskConfig<TInput extends object = Record<string, unknown>> {
-    /** Tool name registered with the MCP server (e.g. 'review_diff'). */
+export interface StructuredToolTaskConfig<TInput extends object = Record<string, unknown>, TResult extends object = Record<string, unknown>, TFinal extends TResult = TResult> {
+    /** Tool name registered with the MCP server (e.g. 'analyze_pr_impact'). */
     name: string;
     /** Human-readable title shown to clients. */
     title: string;
     /** Short description of the tool's purpose. */
     description: string;
-    /** Zod shape object (e.g. `MySchema.shape`) used as the MCP input schema. */
-    inputSchema: ZodRawShapeCompat;
-    /** Full Zod schema for runtime input re-validation (rejects unknown fields). */
-    fullInputSchema?: z.ZodType;
+    /** Zod schema or raw shape for MCP request validation at the transport boundary. */
+    inputSchema: z.ZodType<TInput> | ZodRawShapeCompat;
+    /** Zod schema for validating the complete tool input inside the handler. */
+    fullInputSchema: z.ZodType<TInput>;
     /** Zod schema for parsing and validating the Gemini structured response. */
-    resultSchema: z.ZodType;
+    resultSchema: z.ZodType<TResult>;
     /** Optional Zod schema used specifically for Gemini response validation. */
     geminiSchema?: z.ZodType;
-    /** Stable error code returned on failure (e.g. 'E_REVIEW_DIFF'). */
+    /** Stable error code returned on failure (e.g. 'E_INSPECT_QUALITY'). */
     errorCode: string;
+    /** Optional post-processing hook called after resultSchema.parse(). The return value replaces the parsed result. */
+    transformResult?: (input: TInput, result: TResult) => TFinal;
     /** Optional validation hook for input parameters. */
     validateInput?: (input: TInput) => Promise<ReturnType<typeof createErrorToolResponse> | undefined> | ReturnType<typeof createErrorToolResponse> | undefined;
+    /** Optional Gemini model to use (e.g. 'gemini-2.5-pro'). */
+    model?: string;
+    /** Optional thinking budget in tokens. */
+    thinkingBudget?: number;
+    /** Optional timeout in ms for the Gemini call. Defaults to 60,000 ms. Use DEFAULT_TIMEOUT_PRO_MS for Pro model calls. */
+    timeoutMs?: number;
+    /** Optional formatter for human-readable text output. */
+    formatOutput?: (result: TFinal) => string;
+    /** Optional context text used in progress messages. */
+    progressContext?: (input: TInput) => string;
     /** Builds the system instruction and user prompt from parsed tool input. */
     buildPrompt: (input: TInput) => PromptParts;
 }
-export declare function registerStructuredToolTask<TInput extends object>(server: McpServer, config: StructuredToolTaskConfig<TInput>): void;
+export declare function registerStructuredToolTask<TInput extends object, TResult extends object = Record<string, unknown>, TFinal extends TResult = TResult>(server: McpServer, config: StructuredToolTaskConfig<TInput, TResult, TFinal>): void;