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

package/dist/lib/gemini.js

@@ -9,22 +9,31 @@ 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;
+const DEFAULT_MODEL = 'gemini-2.5-flash';
+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_API_KEY_ENV_VAR = 'GEMINI_API_KEY';
+const GOOGLE_API_KEY_ENV_VAR = 'GOOGLE_API_KEY';
 function getDefaultModel() {
     if (_defaultModel !== undefined)
         return _defaultModel;
-    const value = process.env.GEMINI_MODEL ?? 'gemini-2.5-flash';
+    const value = process.env[GEMINI_MODEL_ENV_VAR] ?? DEFAULT_MODEL;
     _defaultModel = value;
     return value;
 }
-const DEFAULT_MAX_RETRIES = 1;
-const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_TIMEOUT_MS = 90_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 DEFAULT_INCLUDE_THOUGHTS = false;
 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 concurrencyWaitMsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS_WAIT_MS', 2_000);
 const concurrencyPollMsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS_POLL_MS', 25);
@@ -54,9 +63,11 @@ const SAFETY_THRESHOLD_BY_NAME = {
 };
 let cachedSafetyThresholdEnv;
 let cachedSafetyThreshold = DEFAULT_SAFETY_THRESHOLD;
+let cachedIncludeThoughtsEnv;
+let cachedIncludeThoughts = DEFAULT_INCLUDE_THOUGHTS;
 const safetySettingsCache = new Map();
 function getSafetyThreshold() {
-    const threshold = process.env.GEMINI_HARM_BLOCK_THRESHOLD;
+    const threshold = process.env[GEMINI_HARM_BLOCK_THRESHOLD_ENV_VAR];
     if (threshold === cachedSafetyThresholdEnv) {
         return cachedSafetyThreshold;
     }
@@ -65,30 +76,70 @@ function getSafetyThreshold() {
         cachedSafetyThreshold = DEFAULT_SAFETY_THRESHOLD;
         return cachedSafetyThreshold;
     }
-    const normalizedThreshold = threshold.trim().toUpperCase();
-    if (normalizedThreshold in SAFETY_THRESHOLD_BY_NAME) {
-        cachedSafetyThreshold =
-            SAFETY_THRESHOLD_BY_NAME[normalizedThreshold];
+    const parsedThreshold = parseSafetyThreshold(threshold);
+    if (parsedThreshold) {
+        cachedSafetyThreshold = parsedThreshold;
         return cachedSafetyThreshold;
     }
     cachedSafetyThreshold = DEFAULT_SAFETY_THRESHOLD;
     return cachedSafetyThreshold;
 }
-function getThinkingConfig(thinkingBudget) {
-    return thinkingBudget !== undefined
-        ? { includeThoughts: true, thinkingBudget }
-        : undefined;
+function parseSafetyThreshold(threshold) {
+    const normalizedThreshold = threshold.trim().toUpperCase();
+    if (!(normalizedThreshold in SAFETY_THRESHOLD_BY_NAME)) {
+        return undefined;
+    }
+    return SAFETY_THRESHOLD_BY_NAME[normalizedThreshold];
+}
+function getThinkingConfig(thinkingBudget, includeThoughts) {
+    if (thinkingBudget === undefined) {
+        return undefined;
+    }
+    if (includeThoughts) {
+        return { includeThoughts: true, thinkingBudget };
+    }
+    return { thinkingBudget };
+}
+function parseBooleanEnv(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return undefined;
+    }
+    if (normalized === '1' ||
+        normalized === 'true' ||
+        normalized === 'yes' ||
+        normalized === 'on') {
+        return true;
+    }
+    if (normalized === '0' ||
+        normalized === 'false' ||
+        normalized === 'no' ||
+        normalized === 'off') {
+        return false;
+    }
+    return undefined;
+}
+function getDefaultIncludeThoughts() {
+    const value = process.env[GEMINI_INCLUDE_THOUGHTS_ENV_VAR];
+    if (value === cachedIncludeThoughtsEnv) {
+        return cachedIncludeThoughts;
+    }
+    cachedIncludeThoughtsEnv = value;
+    if (!value) {
+        cachedIncludeThoughts = DEFAULT_INCLUDE_THOUGHTS;
+        return cachedIncludeThoughts;
+    }
+    cachedIncludeThoughts = parseBooleanEnv(value) ?? DEFAULT_INCLUDE_THOUGHTS;
+    return cachedIncludeThoughts;
 }
 function getSafetySettings(threshold) {
     const cached = safetySettingsCache.get(threshold);
     if (cached) {
         return cached;
     }
-    const settings = new Array(SAFETY_CATEGORIES.length);
-    let index = 0;
+    const settings = new Array();
     for (const category of SAFETY_CATEGORIES) {
-        settings[index] = { category, threshold };
-        index += 1;
+        settings.push({ category, threshold });
     }
     safetySettingsCache.set(threshold, settings);
     return settings;
@@ -118,14 +169,17 @@ export function getCurrentRequestId() {
     return context?.requestId ?? UNKNOWN_REQUEST_CONTEXT_VALUE;
 }
 function getApiKey() {
-    const apiKey = process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY;
+    const apiKey = process.env[GEMINI_API_KEY_ENV_VAR] ?? process.env[GOOGLE_API_KEY_ENV_VAR];
     if (!apiKey) {
-        throw new Error('Missing GEMINI_API_KEY or GOOGLE_API_KEY.');
+        throw new Error(`Missing ${GEMINI_API_KEY_ENV_VAR} or ${GOOGLE_API_KEY_ENV_VAR}.`);
     }
     return apiKey;
 }
 function getClient() {
-    cachedClient ??= new GoogleGenAI({ apiKey: getApiKey() });
+    cachedClient ??= new GoogleGenAI({
+        apiKey: getApiKey(),
+        apiVersion: 'v1beta',
+    });
     return cachedClient;
 }
 export function setClientForTesting(client) {
@@ -180,7 +234,7 @@ function toNumericCode(candidate) {
     if (typeof candidate === 'number' && Number.isFinite(candidate)) {
         return candidate;
     }
-    if (typeof candidate === 'string' && /^\d+$/.test(candidate)) {
+    if (typeof candidate === 'string' && DIGITS_ONLY_PATTERN.test(candidate)) {
         return Number.parseInt(candidate, 10);
     }
     return undefined;
@@ -192,43 +246,37 @@ function toUpperStringCode(candidate) {
     const normalized = candidate.trim().toUpperCase();
     return normalized.length > 0 ? normalized : undefined;
 }
+function findFirstNumericCode(record, keys) {
+    for (const key of keys) {
+        const numericCode = toNumericCode(record[key]);
+        if (numericCode !== undefined) {
+            return numericCode;
+        }
+    }
+    return undefined;
+}
+function findFirstStringCode(record, keys) {
+    for (const key of keys) {
+        const stringCode = toUpperStringCode(record[key]);
+        if (stringCode !== undefined) {
+            return stringCode;
+        }
+    }
+    return undefined;
+}
 function getNumericErrorCode(error) {
     const record = getNestedError(error);
     if (!record) {
         return undefined;
     }
-    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;
+    return findFirstNumericCode(record, ['status', 'statusCode', 'code']);
 }
 function getTransientErrorCode(error) {
     const record = getNestedError(error);
     if (!record) {
         return undefined;
     }
-    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;
+    return findFirstStringCode(record, ['code', 'status', 'statusText']);
 }
 function shouldRetry(error) {
     const numericCode = getNumericErrorCode(error);
@@ -251,21 +299,25 @@ function getRetryDelayMs(attempt) {
     return Math.min(RETRY_DELAY_MAX_MS, boundedDelay + jitter);
 }
 function buildGenerationConfig(request, abortSignal) {
-    const systemInstruction = request.systemInstruction
-        ? { systemInstruction: request.systemInstruction }
-        : undefined;
-    const thinkingConfig = getThinkingConfig(request.thinkingBudget);
-    const safetySettings = getSafetySettings(getSafetyThreshold());
-    return {
+    const includeThoughts = request.includeThoughts ?? getDefaultIncludeThoughts();
+    const thinkingConfig = getThinkingConfig(request.thinkingBudget, includeThoughts);
+    const config = {
         temperature: request.temperature ?? 0.2,
         maxOutputTokens: request.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
         responseMimeType: 'application/json',
         responseSchema: request.responseSchema,
-        ...(systemInstruction ?? undefined),
-        ...(thinkingConfig ? { thinkingConfig } : undefined),
-        safetySettings,
+        safetySettings: getSafetySettings(getSafetyThreshold()),
+        topP: 0.95,
+        topK: 40,
         abortSignal,
     };
+    if (request.systemInstruction) {
+        config.systemInstruction = request.systemInstruction;
+    }
+    if (thinkingConfig) {
+        config.thinkingConfig = thinkingConfig;
+    }
+    return config;
 }
 function combineSignals(signal, requestSignal) {
     return requestSignal ? AbortSignal.any([signal, requestSignal]) : signal;
@@ -281,6 +333,12 @@ function parseStructuredResponse(responseText) {
         throw new Error(`Model produced invalid JSON: ${getErrorMessage(error)}`);
     }
 }
+function formatTimeoutErrorMessage(timeoutMs) {
+    return `Gemini request timed out after ${formatNumber(timeoutMs)}ms.`;
+}
+function formatConcurrencyLimitErrorMessage(limit, waitLimitMs) {
+    return `Too many concurrent Gemini calls (limit: ${formatNumber(limit)}; waited ${formatNumber(waitLimitMs)}ms).`;
+}
 async function generateContentWithTimeout(request, model, timeoutMs) {
     const controller = new AbortController();
     const timeout = setTimeout(() => {
@@ -300,7 +358,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.`, { cause: error });
+            throw new Error(formatTimeoutErrorMessage(timeoutMs), { cause: error });
         }
         throw error;
     }
@@ -322,7 +380,7 @@ async function executeAttempt(request, model, timeoutMs, attempt, onLog) {
     });
     return parseStructuredResponse(response.text);
 }
-async function waitBeforeRetry(attempt, error, onLog) {
+async function waitBeforeRetry(attempt, error, onLog, requestSignal) {
     const delayMs = getRetryDelayMs(attempt);
     const reason = getErrorMessage(error);
     await emitGeminiLog(onLog, 'warning', {
@@ -333,7 +391,20 @@ async function waitBeforeRetry(attempt, error, onLog) {
             reason,
         },
     });
-    await sleep(delayMs, undefined, { ref: false });
+    if (requestSignal?.aborted) {
+        throw new Error('Gemini request was cancelled.');
+    }
+    try {
+        await sleep(delayMs, undefined, requestSignal
+            ? { ...SLEEP_UNREF_OPTIONS, signal: requestSignal }
+            : SLEEP_UNREF_OPTIONS);
+    }
+    catch (sleepError) {
+        if (requestSignal?.aborted) {
+            throw new Error('Gemini request was cancelled.');
+        }
+        throw sleepError;
+    }
 }
 async function throwGeminiFailure(maxRetries, lastError, onLog) {
     const attempts = maxRetries + 1;
@@ -355,27 +426,29 @@ async function runWithRetries(request, model, timeoutMs, maxRetries, onLog) {
         }
         catch (error) {
             lastError = error;
-            if (attempt >= maxRetries || !shouldRetry(error)) {
+            if (!canRetryAttempt(attempt, maxRetries, error)) {
                 break;
             }
-            await waitBeforeRetry(attempt, error, onLog);
+            await waitBeforeRetry(attempt, error, onLog, request.signal);
         }
     }
     return throwGeminiFailure(maxRetries, lastError, onLog);
 }
+function canRetryAttempt(attempt, maxRetries, error) {
+    return attempt < maxRetries && shouldRetry(error);
+}
 async function waitForConcurrencySlot(limit, requestSignal) {
     const waitLimitMs = concurrencyWaitMsConfig.get();
     const pollMs = concurrencyPollMsConfig.get();
-    const startedAt = performance.now();
+    const deadline = performance.now() + waitLimitMs;
     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).`);
+        if (performance.now() >= deadline) {
+            throw new Error(formatConcurrencyLimitErrorMessage(limit, waitLimitMs));
         }
-        await sleep(pollMs, undefined, { ref: false });
+        await sleep(pollMs, undefined, SLEEP_UNREF_OPTIONS);
     }
 }
 export async function generateStructuredJson(request) {
@@ -387,9 +460,7 @@ export async function generateStructuredJson(request) {
     await waitForConcurrencySlot(limit, request.signal);
     activeCalls += 1;
     try {
-        return await geminiContext.run({ requestId: nextRequestId(), model }, async () => {
-            return runWithRetries(request, model, timeoutMs, maxRetries, onLog);
-        });
+        return await geminiContext.run({ requestId: nextRequestId(), model }, () => runWithRetries(request, model, timeoutMs, maxRetries, onLog));
     }
     finally {
         activeCalls -= 1;

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

@@ -3,9 +3,21 @@ 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;
+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;
+export declare const PRO_THINKING_BUDGET: 16384;
+/** Output cap for Flash triage tools (impact, summary). */
+export declare const FLASH_TRIAGE_MAX_OUTPUT_TOKENS: 2048;
+/** Output cap for API breaking-change detection (migration guidance needs room). */
+export declare const FLASH_API_BREAKING_MAX_OUTPUT_TOKENS: 4096;
+/** Output cap for test-plan generation (includes pseudocode snippets). */
+export declare const FLASH_TEST_PLAN_MAX_OUTPUT_TOKENS: 4096;
+/** Output cap for Pro deep review findings. */
+export declare const PRO_REVIEW_MAX_OUTPUT_TOKENS: 8192;
+/** Output cap for Pro search/replace remediation blocks. */
+export declare const PRO_PATCH_MAX_OUTPUT_TOKENS: 4096;
+/** Output cap for Flash complexity analysis reports. */
+export declare const FLASH_COMPLEXITY_MAX_OUTPUT_TOKENS: 2048;
 /** 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: {

package/dist/lib/model-config.js

@@ -2,18 +2,42 @@
 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;
+const THINKING_BUDGET_TOKENS = {
+    flash: 8_192,
+    pro: 16_384,
+};
+const OUTPUT_TOKEN_BUDGET = {
+    flashTriage: 2_048,
+    flashTestPlan: 4_096,
+    flashApiBreaking: 4_096,
+    flashComplexity: 2_048,
+    proReview: 8_192,
+    proPatch: 4_096,
+};
+const DEFAULT_DETECT_HINT = 'detect';
 /** Thinking budget (tokens) for Flash model thinking tasks (test plans, search/replace). */
-export const FLASH_THINKING_BUDGET = FLASH_THINKING_BUDGET_VALUE;
+export const FLASH_THINKING_BUDGET = THINKING_BUDGET_TOKENS.flash;
 /** Thinking budget (tokens) for Pro model deep-analysis tasks (code quality inspection). */
-export const PRO_THINKING_BUDGET = PRO_THINKING_BUDGET_VALUE;
+export const PRO_THINKING_BUDGET = THINKING_BUDGET_TOKENS.pro;
+/** Output cap for Flash triage tools (impact, summary). */
+export const FLASH_TRIAGE_MAX_OUTPUT_TOKENS = OUTPUT_TOKEN_BUDGET.flashTriage;
+/** Output cap for API breaking-change detection (migration guidance needs room). */
+export const FLASH_API_BREAKING_MAX_OUTPUT_TOKENS = OUTPUT_TOKEN_BUDGET.flashApiBreaking;
+/** Output cap for test-plan generation (includes pseudocode snippets). */
+export const FLASH_TEST_PLAN_MAX_OUTPUT_TOKENS = OUTPUT_TOKEN_BUDGET.flashTestPlan;
+/** Output cap for Pro deep review findings. */
+export const PRO_REVIEW_MAX_OUTPUT_TOKENS = OUTPUT_TOKEN_BUDGET.proReview;
+/** Output cap for Pro search/replace remediation blocks. */
+export const PRO_PATCH_MAX_OUTPUT_TOKENS = OUTPUT_TOKEN_BUDGET.proPatch;
+/** Output cap for Flash complexity analysis reports. */
+export const FLASH_COMPLEXITY_MAX_OUTPUT_TOKENS = OUTPUT_TOKEN_BUDGET.flashComplexity;
 /** 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,
 };
+Object.freeze(MODEL_TIMEOUT_MS);
 /** Default language hint when not specified by the user. Tells the model to auto-detect. */
-export const DEFAULT_LANGUAGE = 'detect';
+export const DEFAULT_LANGUAGE = DEFAULT_DETECT_HINT;
 /** Default test-framework hint when not specified by the user. Tells the model to auto-detect. */
-export const DEFAULT_FRAMEWORK = 'detect';
+export const DEFAULT_FRAMEWORK = DEFAULT_DETECT_HINT;

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

@@ -0,0 +1,245 @@
+export interface ToolParameterContract {
+    name: string;
+    type: string;
+    required: boolean;
+    constraints: string;
+    description: string;
+}
+export interface ToolContract {
+    name: string;
+    purpose: string;
+    model: string;
+    timeoutMs: number;
+    thinkingBudget?: number;
+    maxOutputTokens: number;
+    params: readonly ToolParameterContract[];
+    outputShape: string;
+    gotchas: readonly string[];
+    crossToolFlow: readonly string[];
+    constraints?: readonly string[];
+}
+export declare const TOOL_CONTRACTS: readonly [{
+    readonly name: "analyze_pr_impact";
+    readonly purpose: "Assess severity, categories, breaking changes, and rollback complexity.";
+    readonly model: "gemini-2.5-flash";
+    readonly timeoutMs: 90000;
+    readonly maxOutputTokens: 2048;
+    readonly params: readonly [{
+        readonly name: "diff";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-120K chars";
+        readonly description: "Unified diff text.";
+    }, {
+        readonly name: "repository";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "1-200 chars";
+        readonly description: "Repository identifier (org/repo).";
+    }, {
+        readonly name: "language";
+        readonly type: "string";
+        readonly required: false;
+        readonly constraints: "2-32 chars";
+        readonly description: "Primary language hint.";
+    }];
+    readonly outputShape: "{severity, categories[], summary, breakingChanges[], affectedAreas[], rollbackComplexity}";
+    readonly gotchas: readonly ["Flash triage tool optimized for speed.", "Diff-only analysis (no full-file context)."];
+    readonly crossToolFlow: readonly ["severity/categories feed triage and merge-gate decisions."];
+}, {
+    readonly name: "generate_review_summary";
+    readonly purpose: "Produce PR summary, risk rating, and merge recommendation.";
+    readonly model: "gemini-2.5-flash";
+    readonly timeoutMs: 90000;
+    readonly maxOutputTokens: 2048;
+    readonly params: readonly [{
+        readonly name: "diff";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-120K chars";
+        readonly description: "Unified diff text.";
+    }, {
+        readonly name: "repository";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "1-200 chars";
+        readonly description: "Repository identifier (org/repo).";
+    }, {
+        readonly name: "language";
+        readonly type: "string";
+        readonly required: false;
+        readonly constraints: "2-32 chars";
+        readonly description: "Primary language hint.";
+    }];
+    readonly outputShape: "{summary, overallRisk, keyChanges[], recommendation, stats{filesChanged, linesAdded, linesRemoved}}";
+    readonly gotchas: readonly ["stats are computed locally from the diff.", "Flash triage tool optimized for speed."];
+    readonly crossToolFlow: readonly ["Use before deep review to decide whether Pro analysis is needed."];
+}, {
+    readonly name: "inspect_code_quality";
+    readonly purpose: "Deep code review with optional full-file context.";
+    readonly model: "gemini-2.5-pro";
+    readonly timeoutMs: 120000;
+    readonly thinkingBudget: 16384;
+    readonly maxOutputTokens: 8192;
+    readonly params: readonly [{
+        readonly name: "diff";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-120K chars";
+        readonly description: "Unified diff text.";
+    }, {
+        readonly name: "repository";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "1-200 chars";
+        readonly description: "Repository identifier (org/repo).";
+    }, {
+        readonly name: "language";
+        readonly type: "string";
+        readonly required: false;
+        readonly constraints: "2-32 chars";
+        readonly description: "Primary language hint.";
+    }, {
+        readonly name: "focusAreas";
+        readonly type: "string[]";
+        readonly required: false;
+        readonly constraints: "1-12 items, 2-80 chars each";
+        readonly description: "Focused inspection categories.";
+    }, {
+        readonly name: "maxFindings";
+        readonly type: "number";
+        readonly required: false;
+        readonly constraints: "1-25";
+        readonly description: "Post-generation cap applied to findings.";
+    }, {
+        readonly name: "files";
+        readonly type: "object[]";
+        readonly required: false;
+        readonly constraints: "1-20 files, 100K chars/file";
+        readonly description: "Optional full file content context.";
+    }];
+    readonly outputShape: "{summary, overallRisk, findings[], testsNeeded[], contextualInsights[], totalFindings}";
+    readonly gotchas: readonly ["Combined diff + file context is bounded by MAX_CONTEXT_CHARS.", "maxFindings caps output after generation."];
+    readonly crossToolFlow: readonly ["findings[].title -> suggest_search_replace.findingTitle", "findings[].explanation -> suggest_search_replace.findingDetails"];
+    readonly constraints: readonly ["Context budget (diff + files) < 500K chars."];
+}, {
+    readonly name: "suggest_search_replace";
+    readonly purpose: "Generate verbatim search/replace fix blocks for one finding.";
+    readonly model: "gemini-2.5-pro";
+    readonly timeoutMs: 120000;
+    readonly thinkingBudget: 16384;
+    readonly maxOutputTokens: 4096;
+    readonly params: readonly [{
+        readonly name: "diff";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-120K chars";
+        readonly description: "Unified diff containing the target issue.";
+    }, {
+        readonly name: "findingTitle";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "3-160 chars";
+        readonly description: "Short finding title.";
+    }, {
+        readonly name: "findingDetails";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-3000 chars";
+        readonly description: "Detailed finding context.";
+    }];
+    readonly outputShape: "{summary, blocks[], validationChecklist[]}";
+    readonly gotchas: readonly ["One finding per call to avoid mixed patch intent.", "search must be exact whitespace-preserving match."];
+    readonly crossToolFlow: readonly ["Consumes findings from inspect_code_quality for targeted fixes."];
+    readonly constraints: readonly ["One finding per call; verbatim search match required."];
+}, {
+    readonly name: "generate_test_plan";
+    readonly purpose: "Generate prioritized test cases and coverage guidance.";
+    readonly model: "gemini-2.5-flash";
+    readonly timeoutMs: 90000;
+    readonly thinkingBudget: 8192;
+    readonly maxOutputTokens: 4096;
+    readonly params: readonly [{
+        readonly name: "diff";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-120K chars";
+        readonly description: "Unified diff text.";
+    }, {
+        readonly name: "repository";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "1-200 chars";
+        readonly description: "Repository identifier (org/repo).";
+    }, {
+        readonly name: "language";
+        readonly type: "string";
+        readonly required: false;
+        readonly constraints: "2-32 chars";
+        readonly description: "Primary language hint.";
+    }, {
+        readonly name: "testFramework";
+        readonly type: "string";
+        readonly required: false;
+        readonly constraints: "1-50 chars";
+        readonly description: "Framework hint (jest, vitest, pytest, node:test).";
+    }, {
+        readonly name: "maxTestCases";
+        readonly type: "number";
+        readonly required: false;
+        readonly constraints: "1-30";
+        readonly description: "Post-generation cap applied to test cases.";
+    }];
+    readonly outputShape: "{summary, testCases[], coverageSummary}";
+    readonly gotchas: readonly ["maxTestCases caps output after generation."];
+    readonly crossToolFlow: readonly ["Pair with inspect_code_quality to validate high-risk paths."];
+}, {
+    readonly name: "analyze_time_space_complexity";
+    readonly purpose: "Analyze Big-O complexity and detect degradations in changed code.";
+    readonly model: "gemini-2.5-flash";
+    readonly timeoutMs: 90000;
+    readonly thinkingBudget: 8192;
+    readonly maxOutputTokens: 2048;
+    readonly params: readonly [{
+        readonly name: "diff";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-120K chars";
+        readonly description: "Unified diff text.";
+    }, {
+        readonly name: "language";
+        readonly type: "string";
+        readonly required: false;
+        readonly constraints: "2-32 chars";
+        readonly description: "Primary language hint.";
+    }];
+    readonly outputShape: "{timeComplexity, spaceComplexity, explanation, potentialBottlenecks[], isDegradation}";
+    readonly gotchas: readonly ["Analyzes only changed code visible in the diff."];
+    readonly crossToolFlow: readonly ["Use for algorithmic/performance-sensitive changes."];
+}, {
+    readonly name: "detect_api_breaking_changes";
+    readonly purpose: "Detect breaking API/interface changes in a diff.";
+    readonly model: "gemini-2.5-flash";
+    readonly timeoutMs: 90000;
+    readonly maxOutputTokens: 4096;
+    readonly params: readonly [{
+        readonly name: "diff";
+        readonly type: "string";
+        readonly required: true;
+        readonly constraints: "10-120K chars";
+        readonly description: "Unified diff text.";
+    }, {
+        readonly name: "language";
+        readonly type: "string";
+        readonly required: false;
+        readonly constraints: "2-32 chars";
+        readonly description: "Primary language hint.";
+    }];
+    readonly outputShape: "{hasBreakingChanges, breakingChanges[]}";
+    readonly gotchas: readonly ["Targets public API contracts over internal refactors."];
+    readonly crossToolFlow: readonly ["Run before merge for API-surface-sensitive changes."];
+}];
+export declare function getToolContracts(): readonly ToolContract[];
+export declare function getToolContract(toolName: string): ToolContract | undefined;
+export declare function requireToolContract(toolName: string): ToolContract;
+export declare function getToolContractNames(): string[];