agentweaver 0.1.8 → 0.1.10

package/README.md

@@ -1,41 +1,60 @@
 # AgentWeaver
 
-`AgentWeaver` is a TypeScript/Node.js CLI for engineering workflows around Jira, GitLab review artifacts, Codex, and Claude.
+`AgentWeaver` is a TypeScript/Node.js CLI for harness engineering around coding agents.
 
-It orchestrates a flow like:
+It brings Jira context, GitLab review artifacts, agent-driven steps via Codex and Claude, an interactive terminal UI, and fully automated workflows into one controlled execution harness.
+
+A typical flow looks like:
 
 `plan -> implement -> run-go-linter-loop -> run-go-tests-loop -> review -> review-fix`
 
-The package is designed to run as an npm CLI and includes an interactive terminal UI built on `neo-blessed`.
+The point is not the specific chain above, but that `AgentWeaver` lets you design, run, and reuse agent harnesses:
+
+- with declarative flows and isolated executors
+- with artifacts that survive restarts and let runs resume from the right point
+- with a TUI for semi-automatic operation and visibility
+- with an `auto` mode for fully automated flows without manual handoff
+
+The package runs as an npm CLI and includes a full-screen TUI built on `neo-blessed`.
 
 ## What It Does
 
-- Fetches a Jira issue by key or browse URL
-- Fetches GitLab merge request review comments into reusable markdown and JSON artifacts
-- Generates workflow artifacts such as design, implementation plan, QA plan, bug analysis, reviews, and summaries
-- Machine-readable JSON artifacts are stored under `.agentweaver/scopes/<scope-key>/.artifacts/` and act as the source of truth between workflow steps; Markdown artifacts remain for human inspection
-- Workflow artifacts are isolated by scope; for Jira-driven flows the scope key defaults to the Jira task key, otherwise it defaults to `<git-branch>--<worktree-hash>`
-- Runs workflow stages like `bug-analyze`, `bug-fix`, `mr-description`, `plan`, `task-describe`, `implement`, `review`, `review-fix`, `run-go-tests-loop`, `run-go-linter-loop`, and `auto`
-- Persists compact `auto` pipeline state on disk so runs can resume without storing large agent outputs
+- Fetches a Jira issue by key or browse URL and turns it into working context for agent steps
+- Fetches GitLab review comments and diffs into reusable Markdown and JSON artifacts
+- Runs agent stages such as `plan`, `implement`, `review`, and `review-fix`, plus verification loops such as `run-go-tests-loop` and `run-go-linter-loop`
+- Stores machine-readable JSON artifacts under `.agentweaver/scopes/<scope-key>/.artifacts/` and uses them as the source of truth between steps
+- Isolates workflows by scope: for Jira-backed runs this is usually the issue key, otherwise it defaults to `<git-branch>--<worktree-hash>`
+- Persists compact `auto` pipeline state on disk so runs can resume without keeping full agent transcripts
 - Uses Docker runtime services for isolated Codex execution and build verification
 
+In short, `AgentWeaver` is for cases where you do not want a one-off LLM script, but a durable engineering harness around agents.
+
+## Why AgentWeaver
+
+- Harness engineering instead of ad-hoc prompting. Flows, executors, prompts, and artifacts are separate layers rather than one mixed script.
+- Agent runtime instead of single-shot calls. You can build sequences where one agent plans, another implements, and the next verifies and fixes.
+- TUI instead of blind shell execution. The terminal UI gives you an operational view of flow state, activity, and artifacts.
+- Full automation instead of manual step switching. `auto` can run end-to-end flows that move through planning, implementation, verification, and review on their own.
+
 ## Architecture
 
-The CLI now uses an executor + node + declarative flow architecture.
+The CLI is built around an `executor + node + declarative flow` architecture that fits harness engineering well.
 
-- `src/index.ts` remains the CLI entrypoint and high-level orchestration layer
-- `src/executors/` contains first-class executors for external actions such as Jira fetch, GitLab review fetch, local Codex, Docker-based build verification, Claude, Claude summaries, and process execution
+- `src/index.ts` remains the CLI entrypoint and top-level orchestration layer
+- `src/executors/` contains first-class executors for external actions such as Jira, GitLab, local Codex, Docker-based build verification, Claude, and process execution
 - `src/pipeline/nodes/` contains reusable runtime nodes built on top of executors
-- `src/pipeline/flow-specs/` contains declarative JSON flow specs for `preflight`, `bug-analyze`, `bug-fix`, `gitlab-review`, `mr-description`, `plan`, `task-describe`, `implement`, `review`, `review-fix`, `run-go-tests-loop`, `run-go-linter-loop`, and `auto`
-- `src/runtime/` contains shared runtime services such as command resolution, Docker runtime environment setup, and subprocess execution
+- `src/pipeline/flow-specs/` contains declarative JSON flow specs for `preflight`, `bug-analyze`, `bug-fix`, `gitlab-diff-review`, `gitlab-review`, `mr-description`, `plan`, `task-describe`, `implement`, `review`, `review-fix`, `run-go-tests-loop`, `run-go-linter-loop`, and `auto`
+- project-local flows can be added under `.agentweaver/.flows/*.json`; they are discovered from the current workspace at runtime
+- `src/runtime/` contains shared runtime services such as command resolution, Docker runtime setup, and subprocess execution
 
-This keeps command handlers focused on choosing a flow and providing parameters instead of assembling prompts and subprocess wiring inline.
+This keeps command handlers focused on selecting flows and passing parameters instead of assembling prompts, subprocess wiring, and side effects inline.
 
 ## Repository Layout
 
 - `src/` — main TypeScript sources
 - `src/index.ts` — CLI entrypoint and workflow orchestration
 - `src/pipeline/flow-specs/` — declarative JSON specs for workflow stages
+- `.agentweaver/.flows/` — optional project-local declarative flow specs loaded from the current repository
 - `src/pipeline/nodes/` — reusable pipeline nodes executed by the declarative runner
 - `src/interactive-ui.ts` — interactive TUI built with `neo-blessed`
 - `src/markdown.ts` — markdown-to-terminal renderer for the TUI
@@ -89,7 +108,7 @@ Required:
 Common optional variables:
 
 - `JIRA_BASE_URL` — required when you pass only an issue key like `DEMO-123`
-- `GITLAB_TOKEN` — personal access token for `gitlab-review`
+- `GITLAB_TOKEN` — personal access token for `gitlab-review` and `gitlab-diff-review`
 - `AGENTWEAVER_HOME` — path to the AgentWeaver installation directory
 - `DOCKER_COMPOSE_BIN` — override compose command, for example `docker compose`
 - `CODEX_BIN` — override `codex` executable path
@@ -115,6 +134,12 @@ GIT_ALLOW_PROTOCOL=file:https:ssh
 
 ## Usage
 
+Primary usage modes:
+
+- direct execution of individual stages for controlled agent work
+- interactive TUI mode for selecting flows and observing progress
+- fully automated `auto` mode for end-to-end pipelines
+
 Direct CLI usage:
 
 ```bash
@@ -122,7 +147,8 @@ agentweaver plan DEMO-3288
 agentweaver plan
 agentweaver bug-analyze DEMO-3288
 agentweaver bug-fix DEMO-3288
-agentweaver gitlab-review DEMO-3288
+agentweaver gitlab-diff-review
+agentweaver gitlab-review
 agentweaver mr-description DEMO-3288
 agentweaver task-describe DEMO-3288
 agentweaver implement DEMO-3288
@@ -142,7 +168,8 @@ node dist/index.js plan DEMO-3288
 node dist/index.js plan
 node dist/index.js bug-analyze DEMO-3288
 node dist/index.js bug-fix DEMO-3288
-node dist/index.js gitlab-review DEMO-3288
+node dist/index.js gitlab-diff-review
+node dist/index.js gitlab-review
 node dist/index.js mr-description DEMO-3288
 node dist/index.js task-describe DEMO-3288
 node dist/index.js review
@@ -174,17 +201,28 @@ agentweaver auto-reset DEMO-3288
 Notes:
 
 - `--verbose` streams child process `stdout/stderr` in direct CLI mode
-- task-only commands such as `plan` and `auto` ask for Jira task via interactive `user-input` when it is omitted
-- scope-flexible commands such as `review`, `review-fix`, `run-go-tests-loop`, and `run-go-linter-loop` use the current git branch by default when Jira task is omitted
-- `--scope <name>` lets you override the default project scope name
-- the interactive `Activity` pane is intentionally structured: it shows launch separators, prompts, summaries, and short status messages instead of raw Codex/Claude logs by default
+- task-only commands such as `plan` and `auto` ask for a Jira task via interactive `user-input` when it is omitted
+- scope-flexible commands such as `gitlab-diff-review`, `gitlab-review`, `review`, `review-fix`, `run-go-tests-loop`, and `run-go-linter-loop` use the current git branch by default when a Jira task is omitted
+- `gitlab-review` and `gitlab-diff-review` ask for a GitLab merge request URL via interactive `user-input`
+- `--scope <name>` lets you override the default workflow scope name
+- the interactive `Activity` pane intentionally shows structured events, prompts, summaries, and short statuses instead of raw Codex/Claude logs by default
+
+For fully automated flows, the main entrypoint looks like:
+
+```bash
+agentweaver auto DEMO-3288
+agentweaver auto-status DEMO-3288
+agentweaver auto-reset DEMO-3288
+```
+
+This lets you run an agent pipeline as a reproducible process rather than a loose set of manual steps.
 
 ## Interactive TUI
 
-Interactive mode opens a full-screen terminal UI with:
+Interactive mode opens a full-screen TUI that works as an operator console for the agent harness:
 
 - flow list
-- current flow progress
+- current progress for the selected flow
 - activity log
 - task summary pane
 - keyboard navigation between panes
@@ -197,6 +235,14 @@ Current navigation:
 - `h` — help overlay
 - `q` or `Ctrl+C` — exit
 
+Flow discovery and highlighting:
+
+- built-in flows are loaded from `src/pipeline/flow-specs/`
+- project-local flows are loaded from `.agentweaver/.flows/*.json`
+- project-local flows are shown in a different color in the `Flows` pane
+- when a project-local flow is selected, the description pane also shows its source file path
+- if a local flow conflicts with a built-in flow id or uses unknown `node` / `executor` / `prompt` / `schema` types, interactive startup fails fast with a validation error
+
 Activity pane behavior:
 
 - each external launch is separated with a framed block that shows the current `node`, `executor`, and `model` when available

package/dist/artifacts.js

@@ -59,6 +59,12 @@ export function planFile(taskKey) {
 export function planJsonFile(taskKey) {
     return artifactJsonFile("plan", taskKey, 1);
 }
+export function planningQuestionsJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `planning-questions-${taskKey}.json`);
+}
+export function planningAnswersJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `planning-answers-${taskKey}.json`);
+}
 export function bugAnalyzeFile(taskKey) {
     return taskWorkspaceFile(taskKey, `bug-analyze-${taskKey}.md`);
 }
@@ -95,6 +101,15 @@ export function readyToMergeFile(taskKey) {
 export function jiraTaskFile(taskKey) {
     return taskArtifactsFile(taskKey, `${taskKey}.json`);
 }
+export function jiraAttachmentsDir(taskKey) {
+    return path.join(taskArtifactsDir(taskKey), "jira-attachments");
+}
+export function jiraAttachmentsManifestFile(taskKey) {
+    return taskArtifactsFile(taskKey, `jira-attachments-${taskKey}.json`);
+}
+export function jiraAttachmentsContextFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `jira-attachments-context-${taskKey}.txt`);
+}
 export function jiraDescriptionFile(taskKey) {
     return taskWorkspaceFile(taskKey, `jira-${taskKey}-description.md`);
 }
@@ -116,11 +131,20 @@ export function gitlabReviewJsonFile(taskKey) {
 export function gitlabReviewInputJsonFile(taskKey) {
     return taskArtifactsFile(taskKey, `gitlab-review-input-${taskKey}.json`);
 }
+export function gitlabDiffFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `gitlab-diff-${taskKey}.md`);
+}
+export function gitlabDiffJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `gitlab-diff-${taskKey}.json`);
+}
+export function gitlabDiffReviewInputJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `gitlab-diff-review-input-${taskKey}.json`);
+}
 export function autoStateFile(taskKey) {
     return taskArtifactsFile(taskKey, `.agentweaver-state-${taskKey}.json`);
 }
 export function flowStateFile(scopeKey, flowId) {
-    return scopeArtifactsFile(scopeKey, `.agentweaver-flow-state-${flowId}.json`);
+    return scopeArtifactsFile(scopeKey, `.agentweaver-flow-state-${encodeURIComponent(flowId)}.json`);
 }
 export function planArtifacts(taskKey) {
     return [designFile(taskKey), designJsonFile(taskKey), planFile(taskKey), planJsonFile(taskKey), qaFile(taskKey), qaJsonFile(taskKey)];

package/dist/errors.js

@@ -4,3 +4,10 @@ export class TaskRunnerError extends Error {
         this.name = "TaskRunnerError";
     }
 }
+export class FlowInterruptedError extends TaskRunnerError {
+    returnCode = 130;
+    constructor(message = "Flow interrupted by user.") {
+        super(message);
+        this.name = "FlowInterruptedError";
+    }
+}

package/dist/executors/configs/fetch-gitlab-diff-config.js

@@ -0,0 +1,3 @@
+export const fetchGitLabDiffExecutorDefaultConfig = {
+    authEnvVar: "GITLAB_TOKEN",
+};

package/dist/executors/configs/opencode-config.js

@@ -0,0 +1,6 @@
+export const opencodeExecutorDefaultConfig = {
+    commandEnvVar: "OPENCODE_BIN",
+    defaultCommand: "opencode",
+    modelEnvVar: "OPENCODE_MODEL",
+    subcommand: "run",
+};

package/dist/executors/fetch-gitlab-diff-executor.js

@@ -0,0 +1,26 @@
+import { fetchGitLabDiffExecutorDefaultConfig } from "./configs/fetch-gitlab-diff-config.js";
+import { buildGitLabMergeRequestDiffFetchTarget, fetchGitLabMergeRequestDiff } from "../gitlab.js";
+export const fetchGitLabDiffExecutor = {
+    kind: "fetch-gitlab-diff",
+    version: 1,
+    defaultConfig: fetchGitLabDiffExecutorDefaultConfig,
+    async execute(context, input) {
+        const target = buildGitLabMergeRequestDiffFetchTarget(input.mergeRequestUrl);
+        if (context.verbose) {
+            context.ui.writeStdout(`GitLab MR URL: ${target.mergeRequestUrl}\n`);
+            context.ui.writeStdout(`GitLab project path: ${target.projectPath}\n`);
+            context.ui.writeStdout(`GitLab merge request IID: ${target.mergeRequestIid}\n`);
+            context.ui.writeStdout(`GitLab merge request API URL: ${target.mergeRequestApiUrl}\n`);
+            context.ui.writeStdout(`GitLab diffs API URL: ${target.diffsApiUrl}\n`);
+            context.ui.writeStdout(`Saving GitLab diff markdown to: ${input.outputFile}\n`);
+            context.ui.writeStdout(`Saving GitLab diff JSON to: ${input.outputJsonFile}\n`);
+        }
+        const artifact = await fetchGitLabMergeRequestDiff(input.mergeRequestUrl, input.outputFile, input.outputJsonFile);
+        return {
+            outputFile: input.outputFile,
+            outputJsonFile: input.outputJsonFile,
+            mergeRequestUrl: artifact.merge_request_url,
+            filesCount: artifact.files.length,
+        };
+    },
+};

package/dist/executors/jira-fetch-executor.js

@@ -5,7 +5,13 @@ export const jiraFetchExecutor = {
     version: 1,
     defaultConfig: jiraFetchExecutorDefaultConfig,
     async execute(_context, input) {
-        await fetchJiraIssue(input.jiraApiUrl, input.outputFile);
-        return { outputFile: input.outputFile };
+        const artifacts = await fetchJiraIssue(input.jiraApiUrl, input.outputFile, input.attachmentsManifestFile, input.attachmentsContextFile);
+        return {
+            outputFile: artifacts.issueFile,
+            downloadedAttachments: artifacts.downloadedAttachments,
+            planningContextAttachments: artifacts.planningContextAttachments,
+            ...(artifacts.attachmentsManifestFile ? { attachmentsManifestFile: artifacts.attachmentsManifestFile } : {}),
+            ...(artifacts.attachmentsContextFile ? { attachmentsContextFile: artifacts.attachmentsContextFile } : {}),
+        };
     },
 };

package/dist/executors/opencode-executor.js

@@ -0,0 +1,35 @@
+import { opencodeExecutorDefaultConfig } from "./configs/opencode-config.js";
+import { processExecutor } from "./process-executor.js";
+function resolveModel(config, inputModel, env) {
+    const explicitModel = inputModel?.trim();
+    if (explicitModel) {
+        return explicitModel;
+    }
+    const envModel = env[config.modelEnvVar]?.trim();
+    return envModel || undefined;
+}
+export const opencodeExecutor = {
+    kind: "opencode",
+    version: 1,
+    defaultConfig: opencodeExecutorDefaultConfig,
+    async execute(context, input, config) {
+        const env = input.env ?? context.env;
+        const command = input.command ?? context.runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
+        const model = resolveModel(config, input.model, env);
+        const argv = [command, config.subcommand];
+        if (model) {
+            argv.push("--model", model);
+        }
+        argv.push(input.prompt);
+        const result = await processExecutor.execute(context, {
+            argv,
+            env,
+            label: model ? `opencode:${model}` : "opencode",
+        }, processExecutor.defaultConfig);
+        return {
+            output: result.output,
+            command,
+            ...(model ? { model } : {}),
+        };
+    },
+};

package/dist/gitlab.js

@@ -37,8 +37,17 @@ export function buildGitLabReviewFetchTarget(mergeRequestUrl) {
         discussionsApiUrl: `${mergeRequestRef.apiBaseUrl}/projects/${encodeURIComponent(mergeRequestRef.projectPath)}/merge_requests/${mergeRequestRef.mergeRequestIid}/discussions`,
     };
 }
-async function fetchDiscussionPage(target, page, token) {
-    const apiUrl = `${target.discussionsApiUrl}?per_page=100&page=${page}`;
+export function buildGitLabMergeRequestDiffFetchTarget(mergeRequestUrl) {
+    const mergeRequestRef = parseGitLabMergeRequestUrl(mergeRequestUrl);
+    const mergeRequestApiUrl = `${mergeRequestRef.apiBaseUrl}/projects/${encodeURIComponent(mergeRequestRef.projectPath)}` +
+        `/merge_requests/${mergeRequestRef.mergeRequestIid}`;
+    return {
+        ...mergeRequestRef,
+        mergeRequestApiUrl,
+        diffsApiUrl: `${mergeRequestApiUrl}/diffs`,
+    };
+}
+async function fetchGitLabJson(apiUrl, token) {
     const response = await fetch(apiUrl, {
         headers: {
             "PRIVATE-TOKEN": token,
@@ -46,17 +55,31 @@ async function fetchDiscussionPage(target, page, token) {
         },
     });
     if (!response.ok) {
+        throw new TaskRunnerError(`GitLab API request failed: HTTP ${response.status}\nURL: ${apiUrl}`);
+    }
+    return {
+        body: (await response.json()),
+        headers: response.headers,
+    };
+}
+async function fetchDiscussionPage(target, page, token) {
+    const apiUrl = `${target.discussionsApiUrl}?per_page=100&page=${page}`;
+    let payload;
+    try {
+        payload = await fetchGitLabJson(apiUrl, token);
+    }
+    catch (error) {
         throw new TaskRunnerError([
-            `Failed to fetch GitLab merge request discussions: HTTP ${response.status}`,
+            `Failed to fetch GitLab merge request discussions: ${error.message}`,
             `MR URL: ${target.mergeRequestUrl}`,
             `GitLab project path: ${target.projectPath}`,
             `GitLab merge request IID: ${target.mergeRequestIid}`,
             `GitLab discussions API URL: ${apiUrl}`,
         ].join("\n"));
     }
-    const nextPageHeader = response.headers.get("x-next-page");
+    const nextPageHeader = payload.headers.get("x-next-page");
     const nextPage = nextPageHeader && nextPageHeader.trim().length > 0 ? Number.parseInt(nextPageHeader, 10) : null;
-    const discussions = (await response.json());
+    const discussions = payload.body;
     return { discussions, nextPage: Number.isNaN(nextPage ?? Number.NaN) ? null : nextPage };
 }
 async function fetchMergeRequestDiscussions(target, token) {
@@ -128,6 +151,142 @@ function buildGitLabReviewMarkdown(artifact) {
     });
     return lines.join("\n");
 }
+function normalizeMergeRequestAuthor(details) {
+    return details.author?.username?.trim() || details.author?.name?.trim() || "unknown";
+}
+function normalizeDiffContent(diff, response) {
+    const trimmed = diff?.trimEnd() ?? "";
+    if (trimmed.length > 0) {
+        return trimmed;
+    }
+    if (response.too_large) {
+        return "[Diff omitted by GitLab because it is too large.]";
+    }
+    if (response.collapsed) {
+        return "[Diff omitted by GitLab because it is collapsed.]";
+    }
+    return "[Diff content is empty.]";
+}
+function normalizeDiffFiles(diffs) {
+    return diffs.map((file, index) => {
+        const newPath = file.new_path?.trim() || file.old_path?.trim() || `unknown-file-${index + 1}`;
+        const oldPath = file.old_path?.trim() || newPath;
+        let changeType = "modified";
+        if (file.new_file) {
+            changeType = "added";
+        }
+        else if (file.deleted_file) {
+            changeType = "deleted";
+        }
+        else if (file.renamed_file) {
+            changeType = "renamed";
+        }
+        return {
+            old_path: oldPath,
+            new_path: newPath,
+            change_type: changeType,
+            new_file: Boolean(file.new_file),
+            renamed_file: Boolean(file.renamed_file),
+            deleted_file: Boolean(file.deleted_file),
+            generated_file: Boolean(file.generated_file),
+            too_large: Boolean(file.too_large),
+            collapsed: Boolean(file.collapsed),
+            diff: normalizeDiffContent(file.diff, file),
+        };
+    });
+}
+async function fetchMergeRequestDetails(target, token) {
+    try {
+        return (await fetchGitLabJson(target.mergeRequestApiUrl, token)).body;
+    }
+    catch (error) {
+        throw new TaskRunnerError([
+            `Failed to fetch GitLab merge request details: ${error.message}`,
+            `MR URL: ${target.mergeRequestUrl}`,
+            `GitLab project path: ${target.projectPath}`,
+            `GitLab merge request IID: ${target.mergeRequestIid}`,
+            `GitLab merge request API URL: ${target.mergeRequestApiUrl}`,
+        ].join("\n"));
+    }
+}
+async function fetchMergeRequestDiffsPage(target, page, token) {
+    const apiUrl = `${target.diffsApiUrl}?per_page=100&page=${page}`;
+    let payload;
+    try {
+        payload = await fetchGitLabJson(apiUrl, token);
+    }
+    catch (error) {
+        throw new TaskRunnerError([
+            `Failed to fetch GitLab merge request diffs: ${error.message}`,
+            `MR URL: ${target.mergeRequestUrl}`,
+            `GitLab project path: ${target.projectPath}`,
+            `GitLab merge request IID: ${target.mergeRequestIid}`,
+            `GitLab diffs API URL: ${apiUrl}`,
+        ].join("\n"));
+    }
+    const nextPageHeader = payload.headers.get("x-next-page");
+    const nextPage = nextPageHeader && nextPageHeader.trim().length > 0 ? Number.parseInt(nextPageHeader, 10) : null;
+    return {
+        diffs: payload.body,
+        nextPage: Number.isNaN(nextPage ?? Number.NaN) ? null : nextPage,
+    };
+}
+async function fetchMergeRequestDiffs(target, token) {
+    const diffs = [];
+    let page = 1;
+    while (true) {
+        const chunk = await fetchMergeRequestDiffsPage(target, page, token);
+        diffs.push(...chunk.diffs);
+        if (!chunk.nextPage) {
+            return diffs;
+        }
+        page = chunk.nextPage;
+    }
+}
+function buildGitLabMergeRequestDiffMarkdown(artifact) {
+    const lines = [
+        "# GitLab MR Diff",
+        "",
+        `- MR: ${artifact.merge_request_url}`,
+        `- Title: ${artifact.merge_request.title}`,
+        `- Project: ${artifact.project_path}`,
+        `- IID: ${artifact.merge_request_iid}`,
+        `- State: ${artifact.merge_request.state}`,
+        `- Draft: ${artifact.merge_request.draft ? "yes" : "no"}`,
+        `- Author: ${artifact.merge_request.author}`,
+        `- Branches: ${artifact.merge_request.source_branch} -> ${artifact.merge_request.target_branch}`,
+        `- SHA: ${artifact.merge_request.sha}`,
+        `- Fetched at: ${artifact.fetched_at}`,
+        `- Files changed: ${artifact.files.length}`,
+        "",
+    ];
+    const description = artifact.merge_request.description.trim();
+    if (description) {
+        lines.push("## Description", "", description, "");
+    }
+    if (artifact.files.length === 0) {
+        lines.push("Изменений в diff не найдено.");
+        return lines.join("\n");
+    }
+    artifact.files.forEach((file, index) => {
+        lines.push(`## File ${index + 1}: ${file.new_path}`);
+        lines.push(`- Change type: ${file.change_type}`);
+        if (file.old_path !== file.new_path) {
+            lines.push(`- Old path: ${file.old_path}`);
+        }
+        if (file.generated_file) {
+            lines.push("- Generated: yes");
+        }
+        if (file.too_large) {
+            lines.push("- Too large: yes");
+        }
+        if (file.collapsed) {
+            lines.push("- Collapsed: yes");
+        }
+        lines.push("", "```diff", file.diff, "```", "");
+    });
+    return lines.join("\n");
+}
 export async function fetchGitLabReview(mergeRequestUrl, outputFile, outputJsonFile) {
     const token = process.env.GITLAB_TOKEN?.trim();
     if (!token) {
@@ -151,3 +310,38 @@ export async function fetchGitLabReview(mergeRequestUrl, outputFile, outputJsonF
     await writeFile(outputFile, `${buildGitLabReviewMarkdown(artifact)}\n`, "utf8");
     return artifact;
 }
+export async function fetchGitLabMergeRequestDiff(mergeRequestUrl, outputFile, outputJsonFile) {
+    const token = process.env.GITLAB_TOKEN?.trim();
+    if (!token) {
+        throw new TaskRunnerError("GITLAB_TOKEN is required for gitlab-diff-review flow.");
+    }
+    const target = buildGitLabMergeRequestDiffFetchTarget(mergeRequestUrl);
+    const [details, diffs] = await Promise.all([fetchMergeRequestDetails(target, token), fetchMergeRequestDiffs(target, token)]);
+    const files = normalizeDiffFiles(diffs);
+    const fetchedAt = new Date().toISOString();
+    const artifact = {
+        summary: files.length > 0 ? `Fetched GitLab MR diff with ${files.length} changed files.` : "GitLab MR diff is empty.",
+        merge_request_url: target.mergeRequestUrl,
+        project_path: target.projectPath,
+        merge_request_iid: target.mergeRequestIid,
+        fetched_at: fetchedAt,
+        merge_request: {
+            title: details.title?.trim() || `MR !${target.mergeRequestIid}`,
+            description: details.description?.trim() || "",
+            state: details.state?.trim() || "unknown",
+            draft: Boolean(details.draft),
+            source_branch: details.source_branch?.trim() || "unknown",
+            target_branch: details.target_branch?.trim() || "unknown",
+            sha: details.sha?.trim() || "unknown",
+            author: normalizeMergeRequestAuthor(details),
+            created_at: details.created_at ?? new Date(0).toISOString(),
+            updated_at: details.updated_at ?? new Date(0).toISOString(),
+        },
+        files,
+    };
+    mkdirSync(path.dirname(outputFile), { recursive: true });
+    mkdirSync(path.dirname(outputJsonFile), { recursive: true });
+    await writeFile(outputJsonFile, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+    await writeFile(outputFile, `${buildGitLabMergeRequestDiffMarkdown(artifact)}\n`, "utf8");
+    return artifact;
+}