@krotovm/gitlab-ai-review 1.0.25 → 1.0.27

package/README.md

@@ -30,6 +30,24 @@ ai_review:
     - npx -y @krotovm/gitlab-ai-review
 ```
 
+Save debug HTML as a CI artifact:
+
+```yaml
+stages: [review]
+
+ai_review:
+  stage: review
+  image: node:20
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  script:
+    - npx -y @krotovm/gitlab-ai-review --include-artifacts
+  artifacts:
+    expire_in: 7 days
+    paths:
+      - ai-review-report.html
+```
+
 ## Env variables
 
 Set these in your project/group CI settings:
@@ -39,6 +57,7 @@ Set these in your project/group CI settings:
 - `AI_MODEL` (optional, default: `gpt-4o-mini`; example: `gpt-4o`)
 - `PROJECT_ACCESS_TOKEN` (optional for public projects, but required for most private projects; token with `api` scope)
 - `GITLAB_TOKEN` (optional alias for `PROJECT_ACCESS_TOKEN`)
+- `AI_REVIEW_ARTIFACT_HTML_FILE` (optional, default: `ai-review-report.html`; used with `--include-artifacts`)
 
 `OPENAI_BASE_URL` is passed through to the `openai` SDK client, so you can use any OpenAI-compatible gateway/provider endpoint.
 
@@ -58,6 +77,7 @@ GitLab provides these automatically in Merge Request pipelines:
 - `--max-findings=5` - Max findings in the final review (CI multi-pass only).
 - `--max-review-concurrency=5` - Parallel per-file review API calls (CI multi-pass only).
 - `--debug` - Print full error details (stack and API error fields).
+- `--include-artifacts` - Generate a local HTML debug artifact with per-pass outputs/tokens.
 - `--help` - Show help output.
 
 ## Architecture

package/dist/cli/args.js

@@ -36,6 +36,10 @@ export function hasForceToolsFlag(argv) {
     const args = new Set(argv.slice(2));
     return args.has("--force-tools");
 }
+export function hasIncludeArtifactsFlag(argv) {
+    const args = new Set(argv.slice(2));
+    return args.has("--include-artifacts");
+}
 export function parseIgnoreExtensions(argv) {
     const parsed = [];
     const args = argv.slice(2);

package/dist/cli/ci-review.js

@@ -2,7 +2,53 @@
 import OpenAI from "openai";
 import { buildAnswer, buildConsolidatePrompt, buildFileReviewPrompt, buildPrompt, buildTriagePrompt, buildVerificationPrompt, extractCompletionText, parseTriageResponse, } from "../prompt/index.js";
 import { fetchFileAtRef, searchRepository, } from "../gitlab/services.js";
-import { logToolUsageMinimal, MAX_FILE_TOOL_ROUNDS, MAX_TOOL_ROUNDS, TOOL_NAME_GET_FILE, TOOL_NAME_GREP, } from "./tooling.js";
+import { logToolUsageMinimal, MAX_FILE_TOOL_ROUNDS, MAX_TOOL_ROUNDS, MAX_VERIFICATION_TOOL_ROUNDS, TOOL_NAME_GET_FILE, TOOL_NAME_GREP, } from "./tooling.js";
+async function appendDebugDump(_debugDumpFile, debugRecordWriter, record) {
+    const withTs = { ts: new Date().toISOString(), ...record };
+    if (debugRecordWriter != null) {
+        await debugRecordWriter(withTs);
+    }
+}
+async function createCompletionWithDebug(params) {
+    const { openaiInstance, requestLabel, request, debugDumpFile, debugRecordWriter } = params;
+    await appendDebugDump(debugDumpFile, debugRecordWriter, {
+        kind: "openai_request",
+        label: requestLabel,
+        request,
+    });
+    try {
+        const completion = await openaiInstance.chat.completions.create(request);
+        await appendDebugDump(debugDumpFile, debugRecordWriter, {
+            kind: "openai_response",
+            label: requestLabel,
+            response: {
+                id: completion.id,
+                model: completion.model,
+                usage: completion.usage,
+                choices: completion.choices.map((c) => ({
+                    index: c.index,
+                    finish_reason: c.finish_reason,
+                    message: c.message,
+                })),
+            },
+        });
+        return completion;
+    }
+    catch (error) {
+        await appendDebugDump(debugDumpFile, debugRecordWriter, {
+            kind: "openai_error",
+            label: requestLabel,
+            error: {
+                name: error?.name,
+                message: error?.message,
+                code: error?.code,
+                status: error?.status,
+                type: error?.type,
+            },
+        });
+        throw error;
+    }
+}
 function buildReviewMetadata(changes, refs) {
     const files = changes.map((change, index) => ({
         index: index + 1,
@@ -29,7 +75,10 @@ async function handleGetFileTool(argsRaw, gitLabProjectApiUrl, headers) {
         const path = parsed.path?.trim();
         const ref = parsed.ref?.trim();
         if (!path || !ref) {
-            return JSON.stringify({ ok: false, error: "Both path and ref are required." });
+            return JSON.stringify({
+                ok: false,
+                error: "Both path and ref are required.",
+            });
         }
         const fileText = await fetchFileAtRef({
             gitLabBaseUrl: gitLabProjectApiUrl,
@@ -113,7 +162,7 @@ async function mapWithConcurrency(items, concurrency, fn) {
     return results;
 }
 export async function reviewMergeRequestWithTools(params) {
-    const { openaiInstance, aiModel, promptLimits, changes, refs, gitLabProjectApiUrl, projectId, headers, forceTools, loggers, } = params;
+    const { openaiInstance, aiModel, promptLimits, changes, refs, gitLabProjectApiUrl, projectId, headers, forceTools, loggers, debugDumpFile, debugRecordWriter, } = params;
     const { logDebug, logStep } = loggers;
     const messages = buildPrompt({
         changes: changes.map((change) => ({ diff: change.diff })),
@@ -168,13 +217,19 @@ export async function reviewMergeRequestWithTools(params) {
         },
     ];
     for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
-        const completion = await openaiInstance.chat.completions.create({
-            model: aiModel,
-            temperature: 0.2,
-            stream: false,
-            messages,
-            tools,
-            tool_choice: forceTools && round === 0 ? "required" : "auto",
+        const completion = await createCompletionWithDebug({
+            openaiInstance,
+            requestLabel: `main_review_round_${round + 1}`,
+            debugDumpFile,
+            debugRecordWriter,
+            request: {
+                model: aiModel,
+                temperature: 0.2,
+                stream: false,
+                messages,
+                tools,
+                tool_choice: forceTools && round === 0 ? "required" : "auto",
+            },
         });
         const message = completion.choices[0]?.message;
         if (message == null)
@@ -189,19 +244,30 @@ export async function reviewMergeRequestWithTools(params) {
             tool_calls: toolCalls,
         });
         for (const toolCall of toolCalls) {
+            if (toolCall.type !== "function")
+                continue;
+            const toolName = toolCall.function.name;
             const argsRaw = toolCall.function.arguments ?? "{}";
-            logToolUsageMinimal(logStep, toolCall.function.name, argsRaw);
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_call",
+                phase: "main_review",
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                arguments: argsRaw,
+            });
+            logToolUsageMinimal(logStep, toolName, argsRaw);
             let toolContent;
-            if (toolCall.function.name === TOOL_NAME_GET_FILE) {
+            if (toolName === TOOL_NAME_GET_FILE) {
                 toolContent = await handleGetFileTool(argsRaw, gitLabProjectApiUrl, headers);
             }
-            else if (toolCall.function.name === TOOL_NAME_GREP) {
+            else if (toolName === TOOL_NAME_GREP) {
                 toolContent = await handleGrepTool(argsRaw, refs.head, gitLabProjectApiUrl, headers, projectId);
             }
             else {
                 toolContent = JSON.stringify({
                     ok: false,
-                    error: `Unknown tool "${toolCall.function.name}"`,
+                    error: `Unknown tool "${toolName}"`,
                 });
             }
             messages.push({
@@ -209,23 +275,37 @@ export async function reviewMergeRequestWithTools(params) {
                 tool_call_id: toolCall.id,
                 content: toolContent,
             });
-            logDebug(`tool response id=${toolCall.id} name=${toolCall.function.name} payload=${toolContent.slice(0, 300)}`);
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_response",
+                phase: "main_review",
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                content: toolContent,
+            });
+            logDebug(`tool response id=${toolCall.id} name=${toolName} payload=${toolContent.slice(0, 300)}`);
         }
     }
     messages.push({
         role: "user",
         content: `Tool-call limit reached (${MAX_TOOL_ROUNDS}). Do not call any tools. Provide your best-effort final review now, strictly following the required output format. If confidence is low, return the exact no-issues sentence.`,
     });
-    const finalCompletion = await openaiInstance.chat.completions.create({
-        model: aiModel,
-        temperature: 0.2,
-        stream: false,
-        messages,
+    const finalCompletion = await createCompletionWithDebug({
+        openaiInstance,
+        requestLabel: "main_review_final_after_tool_limit",
+        debugDumpFile,
+        debugRecordWriter,
+        request: {
+            model: aiModel,
+            temperature: 0.2,
+            stream: false,
+            messages,
+        },
     });
     return buildAnswer(finalCompletion);
 }
 async function runFileReviewWithTools(params) {
-    const { openaiInstance, aiModel, filePath, fileDiff, summary, otherChangedFiles, refs, gitLabProjectApiUrl, projectId, headers, forceTools, loggers, } = params;
+    const { openaiInstance, aiModel, filePath, fileDiff, summary, otherChangedFiles, refs, gitLabProjectApiUrl, projectId, headers, forceTools, loggers, debugDumpFile, debugRecordWriter, } = params;
     const { logDebug, logStep } = loggers;
     const messages = buildFileReviewPrompt({
         filePath,
@@ -278,13 +358,19 @@ async function runFileReviewWithTools(params) {
         },
     ];
     for (let round = 0; round < MAX_FILE_TOOL_ROUNDS; round += 1) {
-        const completion = await openaiInstance.chat.completions.create({
-            model: aiModel,
-            temperature: 0.2,
-            stream: false,
-            messages,
-            tools,
-            tool_choice: forceTools && round === 0 ? "required" : "auto",
+        const completion = await createCompletionWithDebug({
+            openaiInstance,
+            requestLabel: `file_review_${filePath}_round_${round + 1}`,
+            debugDumpFile,
+            debugRecordWriter,
+            request: {
+                model: aiModel,
+                temperature: 0.2,
+                stream: false,
+                messages,
+                tools,
+                tool_choice: forceTools && round === 0 ? "required" : "auto",
+            },
         });
         const msg = completion.choices[0]?.message;
         if (msg == null)
@@ -299,19 +385,31 @@ async function runFileReviewWithTools(params) {
             tool_calls: toolCalls,
         });
         for (const toolCall of toolCalls) {
+            if (toolCall.type !== "function")
+                continue;
+            const toolName = toolCall.function.name;
             const argsRaw = toolCall.function.arguments ?? "{}";
-            logToolUsageMinimal(logStep, toolCall.function.name, argsRaw, filePath);
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_call",
+                phase: "file_review",
+                filePath,
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                arguments: argsRaw,
+            });
+            logToolUsageMinimal(logStep, toolName, argsRaw, filePath);
             let toolContent;
-            if (toolCall.function.name === TOOL_NAME_GET_FILE) {
+            if (toolName === TOOL_NAME_GET_FILE) {
                 toolContent = await handleGetFileTool(argsRaw, gitLabProjectApiUrl, headers);
             }
-            else if (toolCall.function.name === TOOL_NAME_GREP) {
+            else if (toolName === TOOL_NAME_GREP) {
                 toolContent = await handleGrepTool(argsRaw, refs.head, gitLabProjectApiUrl, headers, projectId);
             }
             else {
                 toolContent = JSON.stringify({
                     ok: false,
-                    error: `Unknown tool "${toolCall.function.name}"`,
+                    error: `Unknown tool "${toolName}"`,
                 });
             }
             messages.push({
@@ -319,23 +417,176 @@ async function runFileReviewWithTools(params) {
                 tool_call_id: toolCall.id,
                 content: toolContent,
             });
-            logDebug(`tool response file=${filePath} id=${toolCall.id} name=${toolCall.function.name} payload=${toolContent.slice(0, 300)}`);
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_response",
+                phase: "file_review",
+                filePath,
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                content: toolContent,
+            });
+            logDebug(`tool response file=${filePath} id=${toolCall.id} name=${toolName} payload=${toolContent.slice(0, 300)}`);
         }
     }
     messages.push({
         role: "user",
         content: "Tool-call limit reached. Provide your final review now without any tool calls.",
     });
-    const final = await openaiInstance.chat.completions.create({
-        model: aiModel,
-        temperature: 0.2,
-        stream: false,
-        messages,
+    const final = await createCompletionWithDebug({
+        openaiInstance,
+        requestLabel: `file_review_${filePath}_final_after_tool_limit`,
+        debugDumpFile,
+        debugRecordWriter,
+        request: {
+            model: aiModel,
+            temperature: 0.2,
+            stream: false,
+            messages,
+        },
     });
     return extractCompletionText(final) ?? "No issues found.";
 }
+function draftHasStructuredFindings(consolidatedText) {
+    return /-\s*\[(?:high|medium)\]/i.test(consolidatedText);
+}
+async function runVerificationWithTools(params) {
+    const { openaiInstance, aiModel, baseMessages, refs, gitLabProjectApiUrl, projectId, headers, forceTools, consolidatedDraft, loggers, debugDumpFile, debugRecordWriter, } = params;
+    const { logDebug, logStep } = loggers;
+    const messages = [...baseMessages];
+    const tools = [
+        {
+            type: "function",
+            function: {
+                name: TOOL_NAME_GET_FILE,
+                description: "Fetch raw file content at a specific git ref for review context.",
+                parameters: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        path: { type: "string", description: "Repository file path." },
+                        ref: {
+                            type: "string",
+                            description: `Git ref or sha. Prefer "${refs.base}" (base) or "${refs.head}" (head).`,
+                        },
+                    },
+                    required: ["path", "ref"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: TOOL_NAME_GREP,
+                description: "Search the repository for a keyword or pattern. Returns up to 10 matching code fragments with file paths and line numbers.",
+                parameters: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search string (keyword, function name, variable, etc.).",
+                        },
+                        ref: {
+                            type: "string",
+                            description: `Git ref to search in. Prefer "${refs.head}" (head).`,
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+        },
+    ];
+    const verificationForceRound0 = forceTools && draftHasStructuredFindings(consolidatedDraft);
+    for (let round = 0; round < MAX_VERIFICATION_TOOL_ROUNDS; round += 1) {
+        const completion = await createCompletionWithDebug({
+            openaiInstance,
+            requestLabel: `verification_pass_round_${round + 1}`,
+            debugDumpFile,
+            debugRecordWriter,
+            request: {
+                model: aiModel,
+                temperature: 0,
+                stream: false,
+                messages,
+                tools,
+                tool_choice: verificationForceRound0 && round === 0 ? "required" : "auto",
+            },
+        });
+        const message = completion.choices[0]?.message;
+        if (message == null)
+            return completion;
+        const toolCalls = message.tool_calls ?? [];
+        logDebug(`verification round=${round + 1} tool_calls=${toolCalls.length} finish_reason=${completion.choices[0]?.finish_reason ?? "unknown"}`);
+        if (toolCalls.length === 0)
+            return completion;
+        messages.push({
+            role: "assistant",
+            content: message.content ?? "",
+            tool_calls: toolCalls,
+        });
+        for (const toolCall of toolCalls) {
+            if (toolCall.type !== "function")
+                continue;
+            const toolName = toolCall.function.name;
+            const argsRaw = toolCall.function.arguments ?? "{}";
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_call",
+                phase: "verification",
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                arguments: argsRaw,
+            });
+            logToolUsageMinimal(logStep, toolName, argsRaw, "(verify)");
+            let toolContent;
+            if (toolName === TOOL_NAME_GET_FILE) {
+                toolContent = await handleGetFileTool(argsRaw, gitLabProjectApiUrl, headers);
+            }
+            else if (toolName === TOOL_NAME_GREP) {
+                toolContent = await handleGrepTool(argsRaw, refs.head, gitLabProjectApiUrl, headers, projectId);
+            }
+            else {
+                toolContent = JSON.stringify({
+                    ok: false,
+                    error: `Unknown tool "${toolName}"`,
+                });
+            }
+            messages.push({
+                role: "tool",
+                tool_call_id: toolCall.id,
+                content: toolContent,
+            });
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_response",
+                phase: "verification",
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                content: toolContent,
+            });
+            logDebug(`verification tool id=${toolCall.id} name=${toolName} payload=${toolContent.slice(0, 300)}`);
+        }
+    }
+    messages.push({
+        role: "user",
+        content: `Tool-call limit reached (${MAX_VERIFICATION_TOOL_ROUNDS}). Do not call tools. Output only the verified findings in the required format.`,
+    });
+    return createCompletionWithDebug({
+        openaiInstance,
+        requestLabel: "verification_pass_final_after_tool_limit",
+        debugDumpFile,
+        debugRecordWriter,
+        request: {
+            model: aiModel,
+            temperature: 0,
+            stream: false,
+            messages,
+        },
+    });
+}
 export async function reviewMergeRequestMultiPass(params) {
-    const { openaiInstance, aiModel, promptLimits, changes, refs, gitLabProjectApiUrl, projectId, headers, maxFindings, reviewConcurrency, forceTools, loggers, } = params;
+    const { openaiInstance, aiModel, promptLimits, changes, refs, gitLabProjectApiUrl, projectId, headers, maxFindings, reviewConcurrency, forceTools, loggers, debugDumpFile, debugRecordWriter, } = params;
     const { logStep } = loggers;
     logStep(`Pass 1/4: triaging ${changes.length} file(s)`);
     const triageInputs = changes.map((c) => ({
@@ -348,12 +599,18 @@ export async function reviewMergeRequestMultiPass(params) {
     const triageMessages = buildTriagePrompt(triageInputs);
     let triageResult = null;
     try {
-        const triageCompletion = await openaiInstance.chat.completions.create({
-            model: aiModel,
-            temperature: 0.1,
-            stream: false,
-            messages: triageMessages,
-            response_format: { type: "json_object" },
+        const triageCompletion = await createCompletionWithDebug({
+            openaiInstance,
+            requestLabel: "triage_pass",
+            debugDumpFile,
+            debugRecordWriter,
+            request: {
+                model: aiModel,
+                temperature: 0.1,
+                stream: false,
+                messages: triageMessages,
+                response_format: { type: "json_object" },
+            },
         });
         const triageText = extractCompletionText(triageCompletion);
         if (triageText != null)
@@ -375,6 +632,8 @@ export async function reviewMergeRequestMultiPass(params) {
             headers,
             forceTools,
             loggers,
+            debugDumpFile,
+            debugRecordWriter,
         });
     }
     const triageMap = new Map(triageResult.files.map((f) => [f.path, f.verdict]));
@@ -402,6 +661,8 @@ export async function reviewMergeRequestMultiPass(params) {
             headers,
             forceTools,
             loggers,
+            debugDumpFile,
+            debugRecordWriter,
         });
         return { path: change.new_path, findings };
     });
@@ -416,29 +677,44 @@ export async function reviewMergeRequestMultiPass(params) {
         return `No confirmed bugs or high-value optimizations found.\n\n---\n_${DISCLAIMER}_`;
     }
     try {
-        const consolidateCompletion = await openaiInstance.chat.completions.create({
-            model: aiModel,
-            temperature: 0.1,
-            stream: false,
-            messages: consolidateMessages,
+        const consolidateCompletion = await createCompletionWithDebug({
+            openaiInstance,
+            requestLabel: "consolidate_pass",
+            debugDumpFile,
+            debugRecordWriter,
+            request: {
+                model: aiModel,
+                temperature: 0.1,
+                stream: false,
+                messages: consolidateMessages,
+            },
         });
         const consolidatedText = extractCompletionText(consolidateCompletion);
         if (consolidatedText == null || consolidatedText.trim() === "") {
             return buildAnswer(consolidateCompletion);
         }
-        logStep("Pass 4/4: verifying consolidated findings");
+        logStep("Pass 4/4: verifying consolidated findings (repo tools)");
         const verificationMessages = buildVerificationPrompt({
             perFileFindings,
             summary: triageResult.summary,
             consolidatedFindings: consolidatedText,
             maxFindings,
+            refs,
         });
         try {
-            const verificationCompletion = await openaiInstance.chat.completions.create({
-                model: aiModel,
-                temperature: 0.0,
-                stream: false,
-                messages: verificationMessages,
+            const verificationCompletion = await runVerificationWithTools({
+                openaiInstance,
+                aiModel,
+                baseMessages: verificationMessages,
+                refs,
+                gitLabProjectApiUrl,
+                projectId,
+                headers,
+                forceTools,
+                consolidatedDraft: consolidatedText,
+                loggers,
+                debugDumpFile,
+                debugRecordWriter,
             });
             return buildAnswer(verificationCompletion);
         }

package/dist/cli/debug-artifacts-html.js

@@ -0,0 +1,176 @@
+/** @format */
+import { writeFile } from "node:fs/promises";
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+export async function renderDebugArtifactsHtml(params) {
+    const { records, artifactHtmlFile, cliVersion, aiModel } = params;
+    const responses = records.filter((r) => r.kind === "openai_response");
+    const byLabel = new Map();
+    for (const response of responses) {
+        if (typeof response.label === "string")
+            byLabel.set(response.label, response);
+    }
+    const totalTokens = responses.reduce((sum, r) => sum + Number(r?.response?.usage?.total_tokens ?? 0), 0);
+    const tokenLine = responses
+        .map((r) => {
+        const label = String(r.label ?? "unknown");
+        const tokens = Number(r?.response?.usage?.total_tokens ?? 0);
+        return `${label}: ${tokens}`;
+    })
+        .join(" • ");
+    function getContent(label) {
+        const content = byLabel.get(label)?.response?.choices?.[0]?.message?.content;
+        return typeof content === "string" ? content : "";
+    }
+    function getTokenTriplet(label) {
+        const usage = byLabel.get(label)?.response?.usage;
+        if (usage == null)
+            return "prompt: 0 • completion: 0 • total: 0";
+        return `prompt: ${usage.prompt_tokens ?? 0} • completion: ${usage.completion_tokens ?? 0} • total: ${usage.total_tokens ?? 0}`;
+    }
+    function findTs(label) {
+        return String(byLabel.get(label)?.ts ?? "");
+    }
+    function formatAsPrettyJsonIfPossible(value) {
+        const trimmed = value.trim();
+        if (trimmed === "")
+            return value;
+        const fencedMatch = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+        const normalized = (fencedMatch?.[1] ?? trimmed).trim();
+        try {
+            return JSON.stringify(JSON.parse(normalized), null, 2);
+        }
+        catch {
+            return value;
+        }
+    }
+    function renderFindings(markdown) {
+        const trimmed = markdown.trim();
+        if (trimmed === "")
+            return "<pre>No data</pre>";
+        const blocks = trimmed.split(/\n\s*\n/);
+        const items = [];
+        for (const block of blocks) {
+            const lines = block.split("\n").map((l) => l.trimEnd());
+            const title = lines[0] ?? "";
+            const file = lines.find((l) => l.trimStart().startsWith("File:")) ?? "";
+            const line = lines.find((l) => l.trimStart().startsWith("Line:")) ?? "";
+            const why = lines.find((l) => l.trimStart().startsWith("Why:")) ?? "";
+            if (!title.startsWith("- ["))
+                continue;
+            const isHigh = title.toLowerCase().includes("[high]");
+            items.push(`<div class="finding${isHigh ? " high" : ""}"><div class="title">${escapeHtml(title)}</div><div class="meta">${escapeHtml(file)} • ${escapeHtml(line)}</div><div>${escapeHtml(why)}</div></div>`);
+        }
+        if (items.length === 0)
+            return `<pre>${escapeHtml(trimmed)}</pre>`;
+        return items.join("\n");
+    }
+    const triageContent = getContent("triage_pass");
+    const triageContentPretty = formatAsPrettyJsonIfPossible(triageContent);
+    const fileServerLabel = Array.from(byLabel.keys()).find((k) => k.startsWith("file_review_server.js_round_"));
+    const fileCiLabel = Array.from(byLabel.keys()).find((k) => k.startsWith("file_review_.gitlab-ci.yml_round_"));
+    const consolidateLabel = "consolidate_pass";
+    function pickVerificationSection() {
+        const afterLimit = getContent("verification_pass_final_after_tool_limit");
+        if (afterLimit.trim() !== "")
+            return {
+                label: "verification_pass_final_after_tool_limit",
+                content: afterLimit,
+            };
+        const roundLabels = Array.from(byLabel.keys())
+            .filter((k) => k.startsWith("verification_pass_round_"))
+            .sort((a, b) => {
+            const na = Number(a.replace("verification_pass_round_", ""));
+            const nb = Number(b.replace("verification_pass_round_", ""));
+            return na - nb;
+        });
+        for (let i = roundLabels.length - 1; i >= 0; i--) {
+            const lbl = roundLabels[i];
+            const c = getContent(lbl);
+            if (c.trim() !== "")
+                return { label: lbl, content: c };
+        }
+        const legacy = getContent("verification_pass");
+        if (legacy.trim() !== "")
+            return { label: "verification_pass", content: legacy };
+        return { label: "verification_pass_round_1", content: "" };
+    }
+    const verificationSection = pickVerificationSection();
+    const verificationLabel = verificationSection.label;
+    const finalStatus = verificationSection.content.trim() !== "" ? "Verified" : "Fallback";
+    const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>AI Review Debug Report</title>
+  <style>
+    :root { --bg:#0b1020; --panel:#121a2b; --muted:#8ea0c0; --text:#e8eefc; --ok:#2ecc71; --high:#ff6b6b; --med:#f4b942; --line:#24314f; --mono-bg:#0f1526; }
+    * { box-sizing:border-box; } body { margin:0; background:var(--bg); color:var(--text); font:14px/1.45 Inter,system-ui,sans-serif; padding:24px; }
+    .wrap{max-width:1100px;margin:0 auto;} h1,h2{margin:0 0 10px;} h1{font-size:24px;} h2{font-size:18px;margin-top:26px;} .sub{color:var(--muted);margin-bottom:18px;}
+    .grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin:14px 0 22px;} .card{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:12px;}
+    .k{color:var(--muted);font-size:12px;} .v{font-size:20px;font-weight:700;margin-top:4px;} .ok{color:var(--ok);}
+    .section{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:14px;margin-bottom:14px;}
+    .row{display:flex;align-items:center;justify-content:space-between;gap:10px;flex-wrap:wrap;margin-bottom:10px;}
+    .badge{border:1px solid var(--line);background:#16223a;border-radius:999px;padding:2px 10px;font-size:12px;color:var(--muted);}
+    .tokens{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;color:var(--muted);}
+    .finding{border-left:3px solid var(--med);background:#131f36;padding:10px 12px;border-radius:8px;margin:8px 0;} .finding.high{border-left-color:var(--high);}
+    .finding .title{font-weight:700;} .meta{color:var(--muted);font-size:12px;margin:4px 0;}
+    pre{margin:8px 0 0;white-space:pre-wrap;word-break:break-word;background:var(--mono-bg);border:1px solid var(--line);padding:10px;border-radius:8px;font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;color:#d7e3ff;}
+    @media (max-width:900px){.grid{grid-template-columns:1fr 1fr;}} @media (max-width:520px){.grid{grid-template-columns:1fr;}}
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>AI Review Debug Report</h1>
+    <div class="sub">cli v${escapeHtml(cliVersion)} • model ${escapeHtml(aiModel)} • records ${records.length}</div>
+
+    <div class="grid">
+      <div class="card"><div class="k">Model</div><div class="v">${escapeHtml(aiModel)}</div></div>
+      <div class="card"><div class="k">Requests</div><div class="v">${escapeHtml(String(records.filter((r) => r.kind === "openai_request").length))}</div></div>
+      <div class="card"><div class="k">Responses</div><div class="v">${escapeHtml(String(responses.length))}</div></div>
+      <div class="card"><div class="k">Final Status</div><div class="v ok">${escapeHtml(finalStatus)}</div></div>
+    </div>
+
+    <h2>Token Usage</h2>
+    <div class="section">
+      <div class="tokens">${escapeHtml(tokenLine)}</div>
+      <div class="tokens" style="margin-top:6px;"><strong>Total:</strong> ${escapeHtml(totalTokens.toLocaleString())} tokens</div>
+    </div>
+
+    <h2>Pass 1 — Triage</h2>
+    <div class="section">
+      <div class="row"><span class="badge">label: triage_pass</span><span class="tokens">${escapeHtml(findTs("triage_pass"))}</span></div>
+      <pre>${escapeHtml(triageContentPretty)}</pre>
+    </div>
+
+    <h2>Pass 2 — File Reviews</h2>
+    ${fileServerLabel == null
+        ? ""
+        : `<div class="section"><div class="row"><span class="badge">label: ${escapeHtml(fileServerLabel)}</span><span class="tokens">${escapeHtml(getTokenTriplet(fileServerLabel))}</span></div>${renderFindings(getContent(fileServerLabel))}</div>`}
+    ${fileCiLabel == null
+        ? ""
+        : `<div class="section"><div class="row"><span class="badge">label: ${escapeHtml(fileCiLabel)}</span><span class="tokens">${escapeHtml(getTokenTriplet(fileCiLabel))}</span></div>${renderFindings(getContent(fileCiLabel))}</div>`}
+
+    <h2>Pass 3 — Consolidation</h2>
+    <div class="section">
+      <div class="row"><span class="badge">label: ${escapeHtml(consolidateLabel)}</span><span class="tokens">${escapeHtml(getTokenTriplet(consolidateLabel))}</span></div>
+      ${renderFindings(getContent(consolidateLabel))}
+    </div>
+
+    <h2>Pass 4 — Verification</h2>
+    <div class="section">
+      <div class="row"><span class="badge">label: ${escapeHtml(verificationLabel)}</span><span class="tokens">${escapeHtml(getTokenTriplet(verificationLabel))}</span></div>
+      ${renderFindings(verificationSection.content)}
+    </div>
+  </div>
+</body>
+</html>`;
+    await writeFile(artifactHtmlFile, html, "utf8");
+}

package/dist/cli/tooling.js

@@ -3,6 +3,8 @@ export const TOOL_NAME_GET_FILE = "get_file_at_ref";
 export const TOOL_NAME_GREP = "grep_repository";
 export const MAX_TOOL_ROUNDS = 12;
 export const MAX_FILE_TOOL_ROUNDS = 5;
+/** Pass 4 (verification): confirm drafts against repo without duplicating main-review depth. */
+export const MAX_VERIFICATION_TOOL_ROUNDS = 10;
 export function logToolUsageMinimal(logStep, toolName, argsRaw, contextFile) {
     try {
         const parsed = JSON.parse(argsRaw);

package/dist/cli.js

@@ -3,9 +3,10 @@
 import OpenAI from "openai";
 import { readFile } from "node:fs/promises";
 import { DEFAULT_MAX_FINDINGS, DEFAULT_REVIEW_CONCURRENCY, } from "./prompt/index.js";
-import { envOrDefault, envOrUndefined, hasDebugFlag, hasForceToolsFlag, hasIgnoredExtension, parseIgnoreExtensions, parseNumberFlag, parsePromptLimits, requireEnvs, } from "./cli/args.js";
+import { envOrDefault, envOrUndefined, hasDebugFlag, hasForceToolsFlag, hasIncludeArtifactsFlag, hasIgnoredExtension, parseIgnoreExtensions, parseNumberFlag, parsePromptLimits, requireEnvs, } from "./cli/args.js";
 import { reviewMergeRequestMultiPass } from "./cli/ci-review.js";
 import { fetchMergeRequestChanges, postMergeRequestNote, } from "./gitlab/services.js";
+import { renderDebugArtifactsHtml } from "./cli/debug-artifacts-html.js";
 function printHelp() {
     process.stdout.write([
         "gitlab-ai-review",
@@ -18,6 +19,7 @@ function printHelp() {
         "",
         "Debug:",
         "  --debug        Print full error details (stack, API error fields).",
+        "  --include-artifacts  Generate local HTML artifact without printing payloads to console.",
         "  --force-tools  Force at least one tool-call round in tool-enabled review paths.",
         "  --ignore-ext   Ignore file extensions (comma-separated only). Example: --ignore-ext=md,lock",
         "  --max-diffs=50",
@@ -39,6 +41,7 @@ function printHelp() {
 }
 const DEBUG_MODE = hasDebugFlag(process.argv);
 const FORCE_TOOLS = hasForceToolsFlag(process.argv);
+const INCLUDE_ARTIFACTS = hasIncludeArtifactsFlag(process.argv);
 function logStep(message) {
     process.stdout.write(`${message}\n`);
 }
@@ -74,6 +77,15 @@ async function main() {
     const maxFindings = parseNumberFlag(process.argv, "max-findings", DEFAULT_MAX_FINDINGS, 1);
     const reviewConcurrency = parseNumberFlag(process.argv, "max-review-concurrency", DEFAULT_REVIEW_CONCURRENCY, 1);
     const aiModel = envOrDefault("AI_MODEL", "gpt-4o-mini");
+    const artifactHtmlFile = INCLUDE_ARTIFACTS
+        ? envOrDefault("AI_REVIEW_ARTIFACT_HTML_FILE", "ai-review-report.html")
+        : undefined;
+    const artifactRecords = [];
+    const debugRecordWriter = INCLUDE_ARTIFACTS
+        ? async (record) => {
+            artifactRecords.push(record);
+        }
+        : undefined;
     const loggers = { logStep, logDebug };
     const projectAccessToken = envOrUndefined("PROJECT_ACCESS_TOKEN") ?? envOrUndefined("GITLAB_TOKEN");
     const gitlabRequired = [
@@ -127,6 +139,7 @@ async function main() {
         reviewConcurrency,
         forceTools: FORCE_TOOLS,
         loggers,
+        debugRecordWriter,
     });
     logStep("Posting AI review note to merge request");
     const noteRes = await postMergeRequestNote({
@@ -136,6 +149,14 @@ async function main() {
     }, { body: answer });
     if (noteRes instanceof Error)
         throw noteRes;
+    if (INCLUDE_ARTIFACTS && artifactHtmlFile != null) {
+        await renderDebugArtifactsHtml({
+            records: artifactRecords,
+            artifactHtmlFile,
+            cliVersion,
+            aiModel,
+        });
+    }
     process.stdout.write("Posted AI review comment to merge request.\n");
 }
 main().catch((err) => {

package/dist/prompt/index.js

@@ -126,7 +126,7 @@ export function buildConsolidatePrompt(params) {
     ];
 }
 export function buildVerificationPrompt(params) {
-    const { perFileFindings, summary, consolidatedFindings, maxFindings } = params;
+    const { perFileFindings, summary, consolidatedFindings, maxFindings, refs, } = params;
     const findingsText = perFileFindings
         .map((f) => `### ${f.path}\n${f.findings}`)
         .join("\n\n");
@@ -141,6 +141,7 @@ export function buildVerificationPrompt(params) {
                 summary,
                 findingsText,
                 consolidatedFindings,
+                refs,
             }),
         },
     ];

package/dist/prompt/templates/postprocess-system.js

@@ -20,8 +20,10 @@ export function buildVerificationSystemLines(maxFindings) {
     return [
         "You are a skeptical verifier of a merge request review.",
         "Your job is to remove weak, speculative, or unsupported findings from the draft list.",
+        "Tools get_file_at_ref and grep_repository are available. Use them to check claims about current code against the repository at the MR head ref.",
+        "Drop a finding if file contents at refs.head contradict it, or if it cannot be verified after reasonable tool use.",
         "Do not add new findings. Keep, rewrite for clarity, or remove existing findings only.",
-        "A finding can stay only if it is directly supported by evidence from the per-file findings.",
+        "A finding can stay only if supported by the per-file evidence pool and not contradicted by tools when the claim is about code that exists at refs.head.",
         "If confidence is not high, drop the finding.",
         "Preserve this exact per-finding markdown block:",
         "`- [high|medium] <title>`",

package/dist/prompt/templates/user-prompts.js

@@ -57,10 +57,12 @@ export function buildConsolidateUserContent(params) {
     ].join("\n");
 }
 export function buildVerificationUserContent(params) {
-    const { summary, findingsText, consolidatedFindings } = params;
+    const { summary, findingsText, consolidatedFindings, refs } = params;
     return [
         `MR Summary: ${summary}`,
         "",
+        `Refs for tools: head (post-change)="${refs.head}", base="${refs.base}". Prefer head when checking whether the issue exists in the MR.`,
+        "",
         "Per-file findings (evidence pool):",
         findingsText,
         "",

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@krotovm/gitlab-ai-review",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "CLI tool to generate AI code reviews for GitLab merge requests.",
   "main": "dist/cli.js",
   "bin": {
@@ -37,11 +37,11 @@
   },
   "homepage": "https://github.com/KrotovM/gitlab-ai-mr-reviewer#readme",
   "dependencies": {
-    "openai": "^4.47.2"
+    "openai": "^6.33.0"
   },
   "devDependencies": {
-    "@types/node": "^20.4.4",
-    "typescript": "^5.2.2"
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
   },
   "packageManager": "pnpm@8.15.4+sha256.cea6d0bdf2de3a0549582da3983c70c92ffc577ff4410cbf190817ddc35137c2"
 }