@ipul-labs/forge 1.16.8 → 1.17.1

package/lib/server/forge/core/ForgeAgent.js

@@ -0,0 +1,995 @@
+/**
+ * server/forge/core/ForgeAgent.ts
+ *
+ * Orchestrates the full Forge pipeline across one or more repositories.
+ *
+ *   analyzeIssue  → identify files across all repos → fetch contents → propose fix
+ *   applyFix      → group changes by repo → per repo: branch + commit + MR
+ *   refineIssue   → re-run pass 2 with feedback; reuses prior file paths per-repo
+ *   ciFixIssue    → target fix at CI failure logs
+ *
+ * Progress is reported via an optional onProgress callback so that
+ * the calling route can stream SSE events to the client.
+ *
+ * Multi-repo model
+ * ────────────────
+ * - `primaryProject` is the repo where the issue lives.
+ * - `secondaryProjects` are additional repos the fix can span (full-stack).
+ * - The AI sees every repo's file tree in pass 1 and tags files with repo id.
+ * - In pass 2 it proposes changes tagged with the repo they target.
+ * - `applyFix` groups by repo and creates one branch + MR per repo.
+ */
+import { randomUUID } from "node:crypto";
+import { checkResolution, identifyRelevantFiles, proposeFix, refineOrAsk } from "./agentClient.js";
+import { branchNameFor } from "./branchName.js";
+import * as configStore from "./configStore.js";
+import { ensureWorkingTree, overlayChanges } from "./localRepo.js";
+import { classifyIssue } from "./prompts.js";
+import { createProvider } from "./providers/index.js";
+import { reattributeChanges } from "./validator/attribute.js";
+/**
+ * Whether Refine should give the model real Read/Glob/Grep access to a local
+ * checkout of the primary repo. Primary control is the Settings UI flag
+ * (configStore.defaults.refineRepoAccess, default true). The
+ * FORGE_REFINE_REPO_ACCESS env var, when set, overrides the config — useful
+ * for forcing it on/off in CI or dev without touching the persisted config.
+ * Only honours GitLab primaries at runtime (matches validator/localRepo).
+ */
+function refineRepoAccessEnabled() {
+    const raw = process.env.FORGE_REFINE_REPO_ACCESS;
+    if (raw != null) {
+        const v = raw.trim().toLowerCase();
+        return !(v === "0" || v === "false" || v === "off" || v === "no");
+    }
+    return configStore.get().defaults?.refineRepoAccess ?? true;
+}
+function supportsLocalClone(repo) {
+    const colon = repo.indexOf(":");
+    if (colon <= 0)
+        return true;
+    return repo.slice(0, colon).toLowerCase() === "gitlab";
+}
+/**
+ * Heuristic: does this CLI error look like a missing/corrupt Claude session?
+ * We can't pattern-match on an exact string because the CLI wording drifts
+ * between versions — as of today it emits "No conversation found with session
+ * ID: <uuid>" for a missing resume, but older/newer builds have said "session
+ * not found" / "Unable to resume" / "expired". Match on session-specific
+ * vocabulary only so we don't fall back on unrelated failures like "Unknown
+ * model".
+ */
+function isLikelyResumeFailure(err) {
+    const msg = String((err instanceof Error ? err.message : err) ?? "").toLowerCase();
+    return /session|resume|conversation|expired/.test(msg);
+}
+// ─── Types (JSDoc) ────────────────────────────────────────────────────────────
+/**
+ * @typedef {{ type: 'progress', step: string, message: string }} ProgressEvent
+ * @typedef {{ type: 'log', message: string }} LogEvent
+ * @typedef {{ type: 'result', data: AnalysisResult }} ResultEvent
+ * @typedef {{ type: 'error', message: string }} ErrorEvent
+ *
+ * @typedef {{
+ *   repo: string,
+ *   file: string,
+ *   action: 'create'|'modify'|'delete',
+ *   proposed: string,
+ *   original: string|null,
+ *   summary: string
+ * }} ForgeChange
+ *
+ * @typedef {{
+ *   issue: object,
+ *   mrTitle?: string,
+ *   explanation: string,
+ *   reasoning: string,
+ *   changes: ForgeChange[],
+ *   repos: string[]
+ * }} AnalysisResult
+ *
+ * @typedef {{
+ *   repo: string,
+ *   branchName: string,
+ *   mr: object|null,
+ *   pipelineUrl: string|null
+ * }} ApplicationResult
+ */
+const MAX_FILE_BYTES = 40_000; // ~40 KB per file to keep the context window healthy
+const CONV_PREFIX = /^(?:feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)(?:\([^)]+\))?!?:\s*/i;
+const FILE_CAPS = {
+    feature: { total: 18, perRepo: 15 },
+    refactor: { total: 18, perRepo: 15 },
+    fix: { total: 12, perRepo: 8 },
+    chore: { total: 12, perRepo: 8 },
+};
+/**
+ * Builds a conventional-commit subject line from the analysis. Prefers
+ * `analysis.mrTitle` (the model's own commit-style summary), falling back to
+ * the issue title with a prefix derived from the issue kind.
+ */
+function buildCommitSubject(analysis) {
+    const mrTitle = analysis.mrTitle?.trim();
+    if (mrTitle)
+        return mrTitle;
+    const kind = classifyIssue(analysis.issue);
+    const prefix = kind === "feature" ? "feat" : kind === "refactor" ? "refactor" : "fix";
+    return `${prefix}: ${analysis.issue.title.replace(CONV_PREFIX, "")}`;
+}
+/**
+ * Assembles the full commit message: subject + per-file change list + trailers.
+ * Trailers let external tooling (and humans) identify Forge commits without
+ * parsing the subject line.
+ */
+function buildCommitMessage(subject, changes, analysis, mode) {
+    const body = changes.map((c) => `- ${c.file}: ${c.summary}`).join("\n");
+    const trailers = [
+        `Forge-Issue: #${analysis.issue.iid}`,
+        `Forge-Mode: ${mode}`,
+    ].join("\n");
+    return `${subject}\n\n${body}\n\n${trailers}`;
+}
+/**
+ * Returns the progress-step copy for a given analysis kind.
+ *
+ *   "fresh"   — first analysis for an issue
+ *   "new"     — rerunning analysis after discarding a stored result
+ *   "update"  — re-analyzing because an MR already exists
+ *   "retry"   — retrying because a merged MR didn't actually resolve the issue
+ *
+ * Keeping the messaging here (not inlined) means each phase gets its own
+ * voice without the analyze function turning into a switch statement.
+ *
+ * @param {"fresh"|"new"|"update"|"retry"} kind
+ * @param {number} iid
+ * @param {string} agentLabel
+ * @param {string} [repoLine]  Extra " (repos: …)" suffix appended to the intro line.
+ */
+function buildStepMessages(kind, iid, agentLabel, repoLine = "") {
+    const files = (n) => `${n} file${n !== 1 ? "s" : ""}`;
+    switch (kind) {
+        case "new":
+            return {
+                intro: `Discarding stored analysis — starting fresh for issue #${iid}${repoLine}`,
+                fetch_issue: `Reloading issue #${iid} for a clean slate...`,
+                scan_repo: "Rescanning repository from scratch...",
+                identify_files: "Re-evaluating which files matter this time...",
+                fetch_files: (n) => `Re-pulling ${files(n)} at current main...`,
+                generate_fix: `Drafting a new fix with ${agentLabel}...`,
+            };
+        case "update":
+            return {
+                intro: `Updating existing MR for issue #${iid}${repoLine}`,
+                fetch_issue: `Loading issue #${iid} to update the open MR...`,
+                scan_repo: "Checking repository for drift since the last analysis...",
+                identify_files: "Selecting files that still need changes...",
+                fetch_files: (n) => `Loading ${files(n)} for the revised proposal...`,
+                generate_fix: `Revising the fix with ${agentLabel}...`,
+            };
+        case "retry":
+            return {
+                intro: `Retrying analysis for issue #${iid} — prior fix left it unresolved${repoLine}`,
+                fetch_issue: `Reloading issue #${iid} for a follow-up attempt...`,
+                scan_repo: "Rescanning repository with what we learned...",
+                identify_files: "Looking for files the first attempt missed...",
+                fetch_files: (n) => `Loading ${files(n)} for the retry...`,
+                generate_fix: `Attempting a different fix with ${agentLabel}...`,
+            };
+        case "fresh":
+        default:
+            return {
+                intro: `Analysis started for issue #${iid}${repoLine}`,
+                fetch_issue: `Fetching issue #${iid}...`,
+                scan_repo: "Scanning repository...",
+                identify_files: "Identifying relevant files...",
+                fetch_files: (n) => `Loading ${files(n)}...`,
+                generate_fix: `Generating fix with ${agentLabel}...`,
+            };
+    }
+}
+export class ForgeAgent {
+    primaryProject;
+    secondaryProjects;
+    allRepos;
+    agent;
+    providers;
+    provider;
+    constructor(opts = {}) {
+        const primary = opts.project ?? configStore.getPrimaryProject();
+        if (!primary)
+            throw new Error("ForgeAgent requires a primary project.");
+        const secondaries = (opts.secondaryProjects ?? [])
+            .filter((p) => !!p && p !== primary);
+        this.primaryProject = primary;
+        this.secondaryProjects = [...new Set(secondaries)];
+        this.allRepos = [this.primaryProject, ...this.secondaryProjects];
+        this.agent = opts.agent ?? "claude";
+        this.providers = new Map();
+        for (const repo of this.allRepos) {
+            this.providers.set(repo, createProvider(repo));
+        }
+        // Back-compat: `this.provider` is the primary repo's provider.
+        this.provider = this.providers.get(this.primaryProject);
+    }
+    _provider(repo) {
+        const p = this.providers.get(repo);
+        if (!p)
+            throw new Error(`ForgeAgent: no provider configured for repo "${repo}"`);
+        return p;
+    }
+    get _agentLabel() {
+        return this.agent === "openclaw" ? "OpenClaw" : "Claude";
+    }
+    get _isMultiRepo() {
+        return this.allRepos.length > 1;
+    }
+    // ─── Shared helpers ────────────────────────────────────────────────────────
+    async _fetchAllTrees(emit) {
+        const results = await Promise.all(this.allRepos.map(async (repo) => {
+            try {
+                const files = await this._provider(repo).getFileTree("", "main");
+                return { repo, files };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                emit({ type: "log", message: `Could not scan ${repo}: ${message}` });
+                return { repo, files: [] };
+            }
+        }));
+        return results;
+    }
+    async _fetchFiles(entries, emit) {
+        const byRepo = new Map();
+        for (const entry of entries) {
+            const list = byRepo.get(entry.repo) ?? [];
+            list.push(entry.path);
+            byRepo.set(entry.repo, list);
+        }
+        const all = await Promise.all([...byRepo.entries()].map(async ([repo, paths]) => {
+            const provider = this._provider(repo);
+            return Promise.all(paths.map(async (filePath) => {
+                try {
+                    const content = await provider.getFileContent(filePath, "main");
+                    const truncated = content.length > MAX_FILE_BYTES;
+                    const body = truncated
+                        ? content.slice(0, MAX_FILE_BYTES) + "\n// [truncated — file exceeds size limit]"
+                        : content;
+                    const sizeKB = (content.length / 1024).toFixed(1);
+                    emit({ type: "log", message: `Loaded ${repo}:${filePath} (${sizeKB} KB${truncated ? ", truncated" : ""})` });
+                    return { repo, path: filePath, content: body };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    emit({ type: "log", message: `Skipped ${repo}:${filePath}: ${message}` });
+                    return null;
+                }
+            }));
+        }));
+        return all.flat().filter((f) => f != null);
+    }
+    /**
+     * Normalises raw file entries coming back from the model.
+     * The schema now asks for `{ repo, path }` objects, but older prompts /
+     * smaller models occasionally return plain strings — default those to the
+     * primary repo.
+     */
+    _normalizeFileSelections(rawEntries) {
+        return (rawEntries ?? [])
+            .map((entry) => {
+            if (!entry)
+                return null;
+            if (typeof entry === "string")
+                return { repo: this.primaryProject, path: entry };
+            const obj = entry;
+            if (obj.path && obj.repo)
+                return { repo: String(obj.repo), path: String(obj.path) };
+            if (obj.path)
+                return { repo: this.primaryProject, path: String(obj.path) };
+            return null;
+        })
+            .filter((e) => e != null);
+    }
+    _validateSelections(entries, repoTrees) {
+        const treeSet = new Map(repoTrees.map((t) => [t.repo, new Set(t.files)]));
+        const valid = [];
+        const skipped = [];
+        const seen = new Set();
+        for (const { repo, path } of entries) {
+            const key = `${repo}::${path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const set = treeSet.get(repo);
+            if (!set) {
+                skipped.push(`${repo}:${path} (unknown repo)`);
+                continue;
+            }
+            if (!set.has(path)) {
+                skipped.push(`${repo}:${path} (not in tree)`);
+                continue;
+            }
+            valid.push({ repo, path });
+        }
+        return { valid, skipped };
+    }
+    /** Enforces the per-repo and total caps, preserving model order. */
+    _capSelections(entries, issueKind) {
+        const caps = FILE_CAPS[issueKind] ?? FILE_CAPS.fix;
+        const capped = [];
+        const perRepo = new Map();
+        for (const entry of entries) {
+            if (capped.length >= caps.total)
+                break;
+            const count = perRepo.get(entry.repo) ?? 0;
+            if (count >= caps.perRepo)
+                continue;
+            capped.push(entry);
+            perRepo.set(entry.repo, count + 1);
+        }
+        return capped;
+    }
+    _normalizeChanges(rawChanges, fileContents) {
+        return (rawChanges ?? []).map((change) => {
+            const repo = change.repo && this.allRepos.includes(change.repo)
+                ? change.repo
+                : this.primaryProject;
+            const original = fileContents.find((f) => f.repo === repo && f.path === change.file)?.content ?? null;
+            return { ...change, repo, original };
+        });
+    }
+    // ─── Analyze ───────────────────────────────────────────────────────────────
+    /**
+     * Runs the full analysis pipeline for an issue across all configured repos.
+     *
+     * @param {number} issueIid
+     * @param {(event: ProgressEvent|LogEvent|ResultEvent|ErrorEvent) => void} [onProgress]
+     * @param {string} [model]
+     * @param {string} [ciContext]
+     * @param {string} [userPrompt]
+     * @returns {Promise<AnalysisResult>}
+     */
+    async analyzeIssue(issueIid, onProgress, model, ciContext, userPrompt, kind = "fresh", opts = {}, previousChanges = null) {
+        const emit = onProgress ?? (() => { });
+        const { signal } = opts;
+        const repoLine = this._isMultiRepo
+            ? ` (repos: ${this.allRepos.join(", ")})`
+            : "";
+        const msgs = buildStepMessages(kind, issueIid, this._agentLabel, repoLine);
+        emit({ type: "log", message: msgs.intro });
+        // Step 1 — fetch the issue from the primary repo
+        emit({ type: "progress", step: "fetch_issue", message: msgs.fetch_issue });
+        const issue = await this.provider.getIssue(issueIid);
+        // Step 2 — scan all repos in parallel
+        emit({
+            type: "progress",
+            step: "scan_repo",
+            message: this._isMultiRepo
+                ? `Scanning ${this.allRepos.length} repositories...`
+                : msgs.scan_repo,
+        });
+        const repoTrees = await this._fetchAllTrees(emit);
+        for (const { repo, files } of repoTrees) {
+            emit({ type: "log", message: `${repo}: ${files.length} file${files.length !== 1 ? "s" : ""} in tree` });
+        }
+        // Step 3 — identify relevant files (Claude pass 1)
+        emit({ type: "progress", step: "identify_files", message: msgs.identify_files });
+        const ident = await identifyRelevantFiles(issue, repoTrees, model, this.agent, { signal });
+        const { files: rawFiles, reasoning = "", cost: cost1 = 0, serviceTier, inputTokens: it1 = 0, outputTokens: ot1 = 0, cacheCreationTokens: cc1 = 0, cacheReadTokens: cr1 = 0, } = ident;
+        const issueKind = classifyIssue(issue);
+        emit({ type: "log", message: `Issue classified as: ${issueKind}` });
+        const normalized = this._normalizeFileSelections(rawFiles);
+        const { valid, skipped } = this._validateSelections(normalized, repoTrees);
+        const capped = this._capSelections(valid, issueKind);
+        if (capped.length) {
+            emit({ type: "log", message: `Identified ${capped.length} file(s): ${capped.map((f) => `${f.repo}:${f.path}`).join(", ")}` });
+        }
+        else {
+            emit({ type: "log", message: "No files identified — the model returned no valid selections." });
+        }
+        if (skipped.length)
+            emit({ type: "log", message: `Skipped: ${skipped.join(", ")}` });
+        if (reasoning)
+            emit({ type: "log", message: `Reasoning: ${reasoning}` });
+        // Step 4 — fetch file contents across repos
+        emit({
+            type: "progress",
+            step: "fetch_files",
+            message: msgs.fetch_files(capped.length),
+        });
+        const fileContents = await this._fetchFiles(capped, emit);
+        // Step 5 — propose fix (pass 2)
+        emit({ type: "progress", step: "generate_fix", message: msgs.generate_fix });
+        const promptRules = configStore.get().defaults?.promptRules || "";
+        const propose = await proposeFix(issue, fileContents, { ciContext, userPrompt, previousChanges, repos: this.allRepos, promptRules }, model, this.agent, { signal });
+        const { title: mrTitle, explanation, changes, removals = [], cost: cost2 = 0, inputTokens: it2 = 0, outputTokens: ot2 = 0, cacheCreationTokens: cc2 = 0, cacheReadTokens: cr2 = 0, rateLimit: rl2 = null, } = propose;
+        const enrichedChanges = this._normalizeChanges(changes ?? [], fileContents);
+        emit({
+            type: "log",
+            message: `Proposed ${enrichedChanges.length} change(s): ${enrichedChanges.map((c) => `${c.repo}:${c.file} (${c.action})`).join(", ")}`,
+        });
+        if (removals.length > 0) {
+            emit({
+                type: "log",
+                message: `⚠ ${removals.length} removal(s) declared: ${removals.map((r) => `${r.file}: ${r.what}`).join("; ")}`,
+            });
+        }
+        const result = {
+            issue,
+            mrTitle,
+            explanation,
+            reasoning,
+            changes: enrichedChanges,
+            removals,
+            repos: this.allRepos,
+        };
+        emit({ type: "result", data: result });
+        emit({
+            type: "usage",
+            cost: cost1 + cost2,
+            serviceTier: serviceTier ?? "unknown",
+            inputTokens: it1 + it2,
+            outputTokens: ot1 + ot2,
+            cacheCreationTokens: cc1 + cc2,
+            cacheReadTokens: cr1 + cr2,
+            // Most recent rate-limit snapshot wins (pass 2 is last).
+            rateLimit: rl2 ?? ident.rateLimit ?? null,
+        });
+        return result;
+    }
+    // ─── Refine ────────────────────────────────────────────────────────────────
+    /**
+     * Re-runs pass 2 with reviewer feedback and the prior proposed changes as
+     * additional context. Reuses the previous files (per-repo) — no new file
+     * discovery.
+     */
+    async refineIssue(issueIid, previousChanges, feedback, onProgress, model, ciContext, validationState, claudeSessionId, opts = {}) {
+        const emit = onProgress ?? (() => { });
+        const { signal } = opts;
+        // Session continuity: only the user-feedback refine path on Claude carries
+        // a multi-turn session. CI-fix refines route through proposeFix (stateless)
+        // and OpenClaw has no session API. Generate a fresh UUID for turn 1 so we
+        // own the id from the start and can --resume it on turn 2+.
+        const useSession = this.agent === "claude" && !ciContext;
+        const resumeSession = Boolean(useSession && claudeSessionId);
+        const sessionId = useSession ? (claudeSessionId || randomUUID()) : null;
+        emit({ type: "progress", step: "fetch_issue", message: `Fetching issue #${issueIid}...` });
+        const issue = await this.provider.getIssue(issueIid);
+        // Pull the unique (repo, path) pairs from the previous changes.
+        const uniq = new Map();
+        for (const c of previousChanges ?? []) {
+            const repo = c.repo && this.allRepos.includes(c.repo) ? c.repo : this.primaryProject;
+            const key = `${repo}::${c.file}`;
+            if (!uniq.has(key))
+                uniq.set(key, { repo, path: c.file });
+        }
+        const selections = [...uniq.values()];
+        emit({
+            type: "progress",
+            step: "fetch_files",
+            message: `Loading ${selections.length} file${selections.length !== 1 ? "s" : ""}...`,
+        });
+        const fileContents = await this._fetchFiles(selections, emit);
+        // CI-context refines are always directive (the failure logs describe what
+        // broke), so skip classification and go straight through proposeFix. This
+        // keeps the CI-fix loop tight and avoids an "answer" being emitted when
+        // the caller expects fresh changes.
+        if (ciContext) {
+            emit({ type: "progress", step: "generate_fix", message: `Fixing CI failure with ${this._agentLabel}...` });
+            const ciRefineRules = configStore.get().defaults?.promptRules || "";
+            const propose = await proposeFix(issue, fileContents, { feedback, previousChanges, ciContext, repos: this.allRepos, promptRules: ciRefineRules }, model, this.agent, { signal });
+            return this._emitRefineResult(propose, fileContents, issue, emit, "ci-fix");
+        }
+        // Give the refine model access to the full primary repo: prepare a local
+        // clone with previousChanges overlaid and hand Claude Read/Glob/Grep via
+        // cwd. Falls back to the lighter "file tree only" path when disabled,
+        // when using a non-Claude agent, or when the primary repo isn't GitLab
+        // (validator/localRepo are GitLab-only for now).
+        let repoCwd = null;
+        let repoTrees = null;
+        const canUseLocalClone = refineRepoAccessEnabled()
+            && this.agent !== "openclaw"
+            && supportsLocalClone(this.primaryProject);
+        if (canUseLocalClone) {
+            try {
+                emit({ type: "progress", step: "prepare_repo", message: `Preparing local checkout of ${this.primaryProject}...` });
+                const branchName = branchNameFor(issue.iid, { issue });
+                const dir = await ensureWorkingTree(this.primaryProject, branchName, (msg) => emit({ type: "log", message: msg }));
+                const primaryChanges = (previousChanges ?? []).filter((c) => (c.repo ?? this.primaryProject) === this.primaryProject);
+                if (primaryChanges.length) {
+                    await overlayChanges(dir, primaryChanges, (msg) => emit({ type: "log", message: msg }));
+                }
+                repoCwd = dir;
+                emit({ type: "log", message: `Refine session has Read/Glob/Grep access at ${dir}` });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                emit({ type: "log", message: `Could not prepare local checkout (${message}); falling back to file-tree mode.` });
+                repoCwd = null;
+            }
+        }
+        if (!repoCwd) {
+            try {
+                repoTrees = await this._fetchAllTrees(emit);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                emit({ type: "log", message: `Could not scan repo trees: ${message}` });
+            }
+        }
+        emit({ type: "progress", step: "generate_fix", message: `Refining fix with ${this._agentLabel}...` });
+        if (sessionId)
+            emit({ type: "session", sessionId, resumed: resumeSession });
+        const refinePromptRules = configStore.get().defaults?.promptRules || "";
+        const callRefine = (sid, resume) => refineOrAsk(issue, fileContents, {
+            feedback,
+            previousChanges,
+            validationState,
+            repos: this.allRepos,
+            repoCwd,
+            repoTrees,
+            repoAccessMode: repoCwd ? "tools" : "tree",
+            promptRules: refinePromptRules,
+            ...(sid ? { sessionId: sid, resumeSession: resume } : {}),
+        }, model, this.agent, (evt) => emit(evt), { signal });
+        let activeSessionId = sessionId;
+        let response;
+        try {
+            response = await callRefine(activeSessionId, resumeSession);
+        }
+        catch (err) {
+            // Resume failures (session pruned by the CLI, format drift after an
+            // upgrade, crashed half-turn leaving the session unreadable) should
+            // not kill the user's refine. Regenerate the session, tell the
+            // frontend to adopt the new id, and retry once with the full prompt.
+            if (resumeSession && isLikelyResumeFailure(err)) {
+                const fresh = randomUUID();
+                const errMsg = err instanceof Error ? err.message : String(err);
+                emit({ type: "log", message: `Could not resume Claude session ${activeSessionId} (${errMsg}). Starting fresh session ${fresh}.` });
+                activeSessionId = fresh;
+                emit({ type: "session", sessionId: fresh, resumed: false });
+                response = await callRefine(fresh, false);
+            }
+            else {
+                throw err;
+            }
+        }
+        // CLI sometimes forks on resume and returns a different session id than
+        // the one we passed. Re-emit so the frontend persists the authoritative
+        // id — otherwise next refine would --resume a stale handle.
+        if (response?.sessionId && response.sessionId !== activeSessionId) {
+            emit({ type: "log", message: `Claude session forked: ${activeSessionId} → ${response.sessionId}` });
+            activeSessionId = response.sessionId;
+            emit({ type: "session", sessionId: activeSessionId, resumed: false });
+        }
+        const { kind, answer, cost = 0, serviceTier, inputTokens = 0, outputTokens = 0, cacheCreationTokens = 0, cacheReadTokens = 0, rateLimit = null, } = response;
+        const usageEvent = {
+            type: "usage",
+            cost,
+            serviceTier: serviceTier ?? "unknown",
+            inputTokens,
+            outputTokens,
+            cacheCreationTokens,
+            cacheReadTokens,
+            rateLimit,
+        };
+        if (kind === "answer") {
+            const text = answer?.trim() || "(no answer produced)";
+            emit({ type: "log", message: "Refine classified as question — responding without changing code." });
+            emit({ type: "answer", text });
+            emit(usageEvent);
+            return { kind: "answer", answer: text };
+        }
+        // kind === "refine" (default to this if the model omitted kind but gave changes)
+        return this._emitRefineResult({ ...response, title: response.title, explanation: answer }, fileContents, issue, emit, "refine");
+    }
+    /**
+     * Shared tail for both ciFix-style proposeFix results and directive refine
+     * results: normalises changes, emits the result + usage events, and returns
+     * the AnalysisResult so callers can still await it.
+     */
+    _emitRefineResult(propose, fileContents, issue, emit, label) {
+        const { title: mrTitle, explanation, changes, cost = 0, serviceTier, inputTokens = 0, outputTokens = 0, cacheCreationTokens = 0, cacheReadTokens = 0, rateLimit = null, } = propose;
+        const enrichedChanges = this._normalizeChanges(changes ?? [], fileContents);
+        emit({
+            type: "log",
+            message: `${label === "ci-fix" ? "CI fix" : "Refined"} to ${enrichedChanges.length} change(s): ${enrichedChanges.map((c) => `${c.repo}:${c.file} (${c.action})`).join(", ")}`,
+        });
+        const result = {
+            issue,
+            mrTitle,
+            explanation: explanation ?? "",
+            reasoning: "",
+            changes: enrichedChanges,
+            repos: this.allRepos,
+        };
+        emit({ type: "result", data: result });
+        emit({
+            type: "usage",
+            cost,
+            serviceTier: serviceTier ?? "unknown",
+            inputTokens,
+            outputTokens,
+            cacheCreationTokens,
+            cacheReadTokens,
+            rateLimit,
+        });
+        return result;
+    }
+    // ─── CI Fix ────────────────────────────────────────────────────────────────
+    /**
+     * Targeted fix for a CI pipeline failure. Uses the CI logs as the primary
+     * signal for file selection instead of the issue description.
+     */
+    async ciFixIssue(issueIid, ciContext, onProgress, model, opts = {}) {
+        const emit = onProgress ?? (() => { });
+        const { signal } = opts;
+        emit({ type: "log", message: `CI fix started for issue #${issueIid}` });
+        emit({ type: "progress", step: "fetch_issue", message: `Fetching issue #${issueIid}...` });
+        const issue = await this.provider.getIssue(issueIid);
+        emit({ type: "progress", step: "scan_repo", message: "Scanning repositories..." });
+        const repoTrees = await this._fetchAllTrees(emit);
+        emit({ type: "progress", step: "identify_files", message: "Identifying files from CI failure..." });
+        const ciIssue = { ...issue, description: `CI pipeline failure:\n\n${ciContext}` };
+        const ident = await identifyRelevantFiles(ciIssue, repoTrees, model, this.agent, { signal });
+        const { files: rawFiles, cost: cost1 = 0, serviceTier, inputTokens: it1 = 0, outputTokens: ot1 = 0, cacheCreationTokens: cc1 = 0, cacheReadTokens: cr1 = 0, } = ident;
+        const { valid } = this._validateSelections(this._normalizeFileSelections(rawFiles), repoTrees);
+        const capped = this._capSelections(valid, "fix");
+        emit({
+            type: "progress",
+            step: "fetch_files",
+            message: `Loading ${capped.length} file${capped.length !== 1 ? "s" : ""}...`,
+        });
+        const fileContents = await this._fetchFiles(capped, emit);
+        emit({ type: "progress", step: "generate_fix", message: `Fixing CI failure with ${this._agentLabel}...` });
+        const ciPromptRules = configStore.get().defaults?.promptRules || "";
+        const propose = await proposeFix(issue, fileContents, { ciContext, repos: this.allRepos, promptRules: ciPromptRules }, model, this.agent, { signal });
+        const { title: mrTitle, explanation, changes, cost: cost2 = 0, inputTokens: it2 = 0, outputTokens: ot2 = 0, cacheCreationTokens: cc2 = 0, cacheReadTokens: cr2 = 0, rateLimit: rl2 = null, } = propose;
+        const enrichedChanges = this._normalizeChanges(changes ?? [], fileContents);
+        emit({
+            type: "log",
+            message: `Proposed ${enrichedChanges.length} change(s): ${enrichedChanges.map((c) => `${c.repo}:${c.file} (${c.action})`).join(", ")}`,
+        });
+        const result = {
+            issue,
+            mrTitle,
+            explanation,
+            reasoning: "",
+            changes: enrichedChanges,
+            repos: this.allRepos,
+        };
+        emit({ type: "result", data: result });
+        emit({
+            type: "usage",
+            cost: cost1 + cost2,
+            serviceTier: serviceTier ?? "unknown",
+            inputTokens: it1 + it2,
+            outputTokens: ot1 + ot2,
+            cacheCreationTokens: cc1 + cc2,
+            cacheReadTokens: cr1 + cr2,
+            rateLimit: rl2 ?? ident.rateLimit ?? null,
+        });
+        return result;
+    }
+    // ─── Resolution check ──────────────────────────────────────────────────────
+    /**
+     * Asks the model whether the diffs in a merged MR actually fix the issue.
+     * The issue lives in the primary repo; the MR is fetched from whichever
+     * provider created it.
+     */
+    async checkResolution(issueIid, mrIid, repo = this.primaryProject) {
+        const provider = this._provider(repo);
+        const [issue, diffs] = await Promise.all([
+            this.provider.getIssue(issueIid),
+            provider.getMRDiffs(mrIid),
+        ]);
+        return checkResolution(issue, diffs, undefined, this.agent, {});
+    }
+    // ─── Apply ─────────────────────────────────────────────────────────────────
+    /**
+     * Applies an approved analysis: creates one branch + commit + MR per repo
+     * that has changes. Primary repo is always processed first so its MR exists
+     * before any secondary MRs that cross-reference it.
+     *
+     * @param {AnalysisResult} analysis
+     * @returns {Promise<{ applications: ApplicationResult[] }>}
+     */
+    async applyFix(analysis) {
+        // The model's `c.repo` is occasionally wrong (a `.go` file routed to a
+        // Node primary by the normalize fallback). Reattribute against the SCM
+        // API before grouping so we never try to commit a file to a repo that
+        // doesn't have it.
+        const corrected = await this._correctAttribution(analysis.changes);
+        const grouped = this._groupChangesByRepo(corrected);
+        if (grouped.size === 0) {
+            throw new Error("No changes to apply.");
+        }
+        const ordered = this._orderedRepos(grouped);
+        const applications = [];
+        for (const repo of ordered) {
+            const changes = grouped.get(repo);
+            const app = await this._applyToRepo(repo, changes, analysis, applications);
+            applications.push(app);
+        }
+        return { applications };
+    }
+    /**
+     * Pushes a new commit to an existing branch in a specific repo (e.g. to fix
+     * a failing pipeline without creating a new MR). Only affects the one repo.
+     *
+     * @param {string} branchName
+     * @param {AnalysisResult} analysis
+     * @param {string} [repo]  Defaults to primary.
+     */
+    async commitToBranch(branchName, analysis, repo = this.primaryProject) {
+        const corrected = await this._correctAttribution(analysis.changes);
+        const grouped = this._groupChangesByRepo(corrected);
+        const changes = grouped.get(repo);
+        if (!changes?.length) {
+            throw new Error(`No changes for repo "${repo}" to commit.`);
+        }
+        const provider = this._provider(repo);
+        // Rebase onto latest main before pushing so CI runs against current code.
+        try {
+            const mrs = await provider.listAllForgeMRs();
+            const mr = mrs.find((m) => m.source_branch === branchName);
+            if (mr && provider.supportsRebase) {
+                await provider.rebaseMR(mr.iid);
+            }
+        }
+        catch { /* rebase failure is non-fatal — push will still work */ }
+        const actions = changes.map((c) => ({ action: c.action, file_path: c.file, content: c.proposed ?? "" }));
+        const subject = buildCommitSubject(analysis);
+        const commitMessage = buildCommitMessage(subject, changes, analysis, "ci-fix");
+        await provider.commitFiles(branchName, commitMessage, actions);
+        return { repo, branchName };
+    }
+    /**
+     * Opens an MR for a branch that was previously pushed via deployBranch.
+     * Used when a test-deploy pipeline goes green and the user wants to promote
+     * the change to a real MR.
+     *
+     * @param {string} branchName
+     * @param {string} repo
+     * @param {number} issueIid
+     * @returns {Promise<ApplicationResult>}
+     */
+    async promoteBranchToMR(branchName, repo, issueIid) {
+        const targetRepo = repo && this.allRepos.includes(repo) ? repo : this.primaryProject;
+        const provider = this._provider(targetRepo);
+        const isPrimary = targetRepo === this.primaryProject;
+        // Refuse to open an MR that has nothing to merge. `compareRefs` returns
+        // `null` on providers that can't answer, which we treat as "allowed" so
+        // we don't block GitHub/Azure until they implement it.
+        const cmp = await provider.compareRefs("main", branchName);
+        if (cmp && cmp.aheadCount === 0) {
+            throw new Error(`Branch \`${branchName}\` has no commits ahead of main — nothing to promote.`);
+        }
+        const issue = await this._provider(this.primaryProject).getIssue(issueIid);
+        const rawTitle = issue.title.replace(CONV_PREFIX, "");
+        const subject = `fix: ${rawTitle}`;
+        const mrTitle = this._isMultiRepo
+            ? `${subject} [${this._repoShortLabel(targetRepo)}]`
+            : subject;
+        const linkedIssue = isPrimary
+            ? `Closes #${issueIid}`
+            : `Relates to ${this.primaryProject}#${issueIid}`;
+        const description = `## 🎯 Summary
+
+Promoted to MR from test-deploy branch \`${branchName}\` after the branch pipeline went green.
+
+${linkedIssue}
+
+---
+
+_Opened by Forge._`;
+        const mr = await this._ensureMR(provider, {
+            sourceBranch: branchName,
+            targetBranch: "main",
+            title: mrTitle,
+            description,
+            labels: ["forge", `forge:issue-${issueIid}`],
+        });
+        let pipelineUrl = null;
+        try {
+            const pipelines = await provider.getMRPipelines(mr.iid);
+            pipelineUrl = pipelines[0]?.web_url ?? null;
+        }
+        catch {
+            // Pipeline lookup is best-effort.
+        }
+        return { repo: targetRepo, branchName, mr, pipelineUrl };
+    }
+    /**
+     * Pushes a fix as a new branch per repo without opening MRs. Used for the
+     * "Deploy to Test" flow where a branch pipeline deploys to a test namespace.
+     *
+     * @param {AnalysisResult} analysis
+     * @returns {Promise<{ applications: ApplicationResult[] }>}
+     */
+    async deployBranch(analysis) {
+        const corrected = await this._correctAttribution(analysis.changes);
+        const grouped = this._groupChangesByRepo(corrected);
+        if (grouped.size === 0)
+            throw new Error("No changes to deploy.");
+        const ordered = this._orderedRepos(grouped);
+        const applications = [];
+        const branchName = branchNameFor(analysis.issue.iid, analysis);
+        for (const repo of ordered) {
+            const changes = grouped.get(repo);
+            const provider = this._provider(repo);
+            await this._ensureBranch(provider, branchName, "main");
+            const actions = changes.map((c) => ({ action: c.action, file_path: c.file, content: c.proposed ?? "" }));
+            const subject = buildCommitSubject(analysis);
+            const commitMessage = buildCommitMessage(subject, changes, analysis, "deploy-to-test");
+            await provider.commitFiles(branchName, commitMessage, actions);
+            let pipelineUrl = null;
+            try {
+                const pipelines = await provider.getPipelinesByRef(branchName);
+                pipelineUrl = pipelines[0]?.web_url ?? null;
+            }
+            catch {
+                // Pipeline may not have kicked off yet — non-fatal.
+            }
+            applications.push({ repo, branchName, mr: null, pipelineUrl });
+        }
+        return { applications };
+    }
+    // ─── Private apply helpers ─────────────────────────────────────────────────
+    /**
+     * Resolves each change's `repo` against the SCM (does the file actually
+     * exist there?) so we don't try to commit to the wrong repo when the
+     * model omitted or guessed `c.repo` wrong. Mirror of the validator's
+     * auto-attribution; returns a flat changes array with corrected repo.
+     * Falls back to the input on attribution failure so we never block apply
+     * on a flaky API call.
+     */
+    async _correctAttribution(changes) {
+        try {
+            const { changes: corrected, unattributed } = await reattributeChanges(changes ?? [], this.allRepos);
+            if (unattributed.length) {
+                console.warn(`[forge] Dropping ${unattributed.length} unattributable change(s):`, unattributed.map((c) => c.file).join(", "));
+            }
+            return corrected;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn("[forge] Attribution lookup failed, using model-supplied repo:", message);
+            return changes ?? [];
+        }
+    }
+    _groupChangesByRepo(changes) {
+        const grouped = new Map();
+        for (const change of changes ?? []) {
+            const repo = change.repo && this.allRepos.includes(change.repo)
+                ? change.repo
+                : this.primaryProject;
+            const list = grouped.get(repo) ?? [];
+            list.push(change);
+            grouped.set(repo, list);
+        }
+        return grouped;
+    }
+    /** Primary always first, secondaries after in allRepos order. */
+    _orderedRepos(grouped) {
+        const present = new Set(grouped.keys());
+        return this.allRepos.filter((r) => present.has(r));
+    }
+    async _applyToRepo(repo, changes, analysis, priorApplications) {
+        const provider = this._provider(repo);
+        const { issue, explanation } = analysis;
+        const branchName = branchNameFor(issue.iid, analysis);
+        await this._ensureBranch(provider, branchName, "main");
+        const actions = changes.map((c) => ({ action: c.action, file_path: c.file, content: c.proposed ?? "" }));
+        const subject = buildCommitSubject(analysis);
+        const commitMessage = buildCommitMessage(subject, changes, analysis, "mr");
+        await provider.commitFiles(branchName, commitMessage, actions);
+        const isPrimary = repo === this.primaryProject;
+        const mrTitle = this._isMultiRepo
+            ? `${subject} [${this._repoShortLabel(repo)}]`
+            : subject;
+        const mrDescription = this._buildMRDescription(issue, explanation, changes, {
+            isPrimary,
+            repo,
+            priorApplications,
+        });
+        const mr = await this._ensureMR(provider, {
+            sourceBranch: branchName,
+            targetBranch: "main",
+            title: mrTitle,
+            description: mrDescription,
+            labels: ["forge", `forge:issue-${issue.iid}`],
+        });
+        let pipelineUrl = null;
+        try {
+            const pipelines = await provider.getMRPipelines(mr.iid);
+            pipelineUrl = pipelines[0]?.web_url ?? null;
+        }
+        catch {
+            // Pipeline may not have kicked off yet — non-fatal.
+        }
+        return { repo, branchName, mr, pipelineUrl };
+    }
+    /**
+     * Creates a branch, tolerating the case where it already exists — the whole
+     * point of intent-based names is that multiple applies/refines reuse the
+     * same branch. GitLab returns 400 "Branch already exists"; other providers
+     * may use different strings, so we match loosely.
+     */
+    async _ensureBranch(provider, branchName, ref) {
+        try {
+            return await provider.createBranch(branchName, ref);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/already exists/i.test(message))
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Opens an MR for the given branch, or returns the existing open one if
+     * the user is re-applying to a branch that already has an MR attached.
+     * Source-branch match is exact; label updates are intentionally skipped on
+     * the reuse path to keep this idempotent.
+     */
+    async _ensureMR(provider, mrSpec) {
+        try {
+            return await provider.createMR(mrSpec);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!/already|exist/i.test(message))
+                throw err;
+            const open = await provider.listAllForgeMRs();
+            const match = open.find((mr) => mr.source_branch === mrSpec.sourceBranch);
+            if (match)
+                return match;
+            throw err;
+        }
+    }
+    _repoShortLabel(repo) {
+        return repo.split("/").pop() || repo;
+    }
+    _buildMRDescription(issue, explanation, changes, opts = {}) {
+        const { isPrimary = true, repo = this.primaryProject, priorApplications = [] } = opts;
+        const changeList = changes
+            .map((c) => `- **${c.file}** (${c.action}): ${c.summary}`)
+            .join("\n");
+        const linkedIssue = isPrimary
+            ? `Closes #${issue.iid}`
+            : `Relates to ${this.primaryProject}#${issue.iid}`;
+        let companionBlock = "";
+        if (this._isMultiRepo) {
+            const companions = priorApplications
+                .filter((a) => a.mr && a.repo !== repo)
+                .map((a) => `- [${a.repo}!${a.mr.iid}](${a.mr.web_url}) — ${this._repoShortLabel(a.repo)}`);
+            const heading = "## 🔗 Companion MRs";
+            if (companions.length) {
+                companionBlock = `\n\n${heading}\n\nThis is part of a full-stack change spanning multiple repositories.\n\n${companions.join("\n")}`;
+            }
+            else {
+                companionBlock = `\n\n${heading}\n\nThis is part of a full-stack change — companion MRs will be posted in other repos.`;
+            }
+        }
+        return `## 🎯 Summary
+
+Automated fix for ${this.primaryProject}#${issue.iid} generated by Forge.
+
+${explanation}
+
+${linkedIssue}${companionBlock}
+
+## ✨ Changes (${this._repoShortLabel(repo)})
+
+${changeList}
+
+## 🧪 Testing
+
+- ⏳ Automated CI pipeline
+- ⏳ Manual review of diff before merge
+
+---
+
+_Generated by [Forge](https://iplayulisten.com/admin/forge)_`;
+    }
+}
+//# sourceMappingURL=ForgeAgent.js.map