@geminixiang/mikan 1.0.0-beta.7 → 1.0.0-beta.71

package/dist/adapters/github/bot.js

@@ -0,0 +1,720 @@
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { Type } from "@sinclair/typebox";
+import { createConversationEvent } from "../index.js";
+import * as log from "../../log.js";
+import { ensureDirExists, readJsonSchemaFileIfExists } from "../../file-guards.js";
+import { atomicWritePrivateFile } from "../../file-guards.js";
+import { resolveChatSessionKey } from "../../sessions/session-key.js";
+import { appendBotResponseLog, appendChannelLog, MessagingEventQueue, splitText, } from "../shared.js";
+import { matchMagicWord, processMessageIntake } from "../intake.js";
+import { GithubClient, GITHUB_MAX_COMMENT_LENGTH, githubRetry } from "./client.js";
+import { createGithubAdapters } from "./context.js";
+import { fetchIsPr, fetchPrHeadBranch, GithubOps } from "./github-ops.js";
+import { cloneRepo, conversationRepoDir } from "./repo.js";
+import { createOfficeAddress } from "../../office/index.js";
+import { buildGithubConversationId, GITHUB_ISSUE_BODY_TS, githubReviewCommentTs, parseGithubConversationId, parseReviewCommentTs, } from "./ids.js";
+const SyncStateSchema = Type.Object({
+    repos: Type.Record(Type.String(), Type.Object({
+        baseline: Type.String(),
+        cursor: Type.String(),
+        seenComments: Type.Array(Type.Number()),
+        seenIssues: Type.Array(Type.Number()),
+        // Optional: state files written before review-comment polling must keep
+        // loading — a schema failure re-baselines and silently drops dedup state.
+        seenReviewComments: Type.Optional(Type.Array(Type.Number())),
+    })),
+});
+/**
+ * Re-fetch this far behind the cursor each poll. Dedup is by id (the
+ * watermark), so the overlap only costs bandwidth and closes the boundary
+ * races of a bare `since` timestamp (DESIGN.md § Event source).
+ */
+const POLL_OVERLAP_MS = 5 * 60 * 1000;
+const MAX_SEEN_IDS = 5000;
+/** Webhook pokes within this window collapse into one poll tick. */
+const REQUEST_POLL_DEBOUNCE_MS = 1500;
+/** Effective role → rank, for the trigger-permission gate. */
+const PERMISSION_RANK = {
+    none: 0,
+    read: 1,
+    triage: 2,
+    write: 3,
+    maintain: 4,
+    admin: 5,
+};
+/**
+ * Commenters need write or better to trigger the agent. Fixed, not a config
+ * knob: it guards public repos (anyone can comment there), and the people who
+ * ask an agent to change code are exactly the people with push access.
+ */
+const REQUIRED_TRIGGER_RANK = PERMISSION_RANK.write;
+/** Rank for an arbitrary API-reported permission name; unknown names rank 0. */
+function rankOfPermission(name) {
+    return PERMISSION_RANK[name] ?? 0;
+}
+/** Permission lookups are cached this long per repo+user. */
+const PERMISSION_CACHE_TTL_MS = 5 * 60 * 1000;
+export const formatGithubContinuation = (partNum) => `*(continued ${partNum})*`;
+/** Slack-style emoji short names → GitHub reaction content values. */
+const GITHUB_REACTIONS = {
+    "+1": "+1",
+    thumbsup: "+1",
+    "-1": "-1",
+    thumbsdown: "-1",
+    laugh: "laugh",
+    smile: "laugh",
+    confused: "confused",
+    heart: "heart",
+    hooray: "hooray",
+    tada: "hooray",
+    rocket: "rocket",
+    eyes: "eyes",
+};
+// Repo refs are lowercased at every entry point (env config here, the
+// installation API in start()) so conversation ids and sync-state keys never
+// depend on how a repo's name was spelled — GitHub is case-insensitive.
+function parseRepoList(repos) {
+    return repos.map((entry) => {
+        const [owner, repo, ...rest] = entry.split("/");
+        if (!owner || !repo || rest.length > 0) {
+            throw new Error(`Invalid GITHUB_REPOS entry (expected owner/repo): ${entry}`);
+        }
+        return { owner: owner.toLowerCase(), repo: repo.toLowerCase() };
+    });
+}
+/** Sets iterate in insertion order; drop the oldest ids once over the cap. */
+function pruneSeen(seen) {
+    if (seen.size <= MAX_SEEN_IDS)
+        return;
+    let toDrop = seen.size - MAX_SEEN_IDS / 2;
+    for (const id of seen) {
+        if (toDrop-- <= 0)
+            break;
+        seen.delete(id);
+    }
+}
+/** Issue number from a comment's `issue_url` (…/repos/o/r/issues/42). */
+function issueNumberFromUrl(issueUrl) {
+    const match = /\/issues\/(\d+)$/.exec(issueUrl);
+    if (!match) {
+        throw new Error(`Cannot parse issue number from ${issueUrl}`);
+    }
+    return Number(match[1]);
+}
+/** PR number from a review comment's `pull_request_url` (…/repos/o/r/pulls/42). */
+function prNumberFromUrl(pullRequestUrl) {
+    const match = /\/pulls\/(\d+)$/.exec(pullRequestUrl);
+    if (!match) {
+        throw new Error(`Cannot parse PR number from ${pullRequestUrl}`);
+    }
+    return Number(match[1]);
+}
+/** Keep the tail: a review comment anchors to the hunk's final lines. */
+const MAX_DIFF_HUNK_CHARS = 1500;
+const MAX_THREAD_TURNS = 10;
+const MAX_THREAD_TURN_CHARS = 500;
+export class GithubMessagingBot {
+    constructor(handler, config, client) {
+        this.appSlug = null;
+        this.botEmail = null;
+        this.watchedRepos = [];
+        this.queues = new Map();
+        this.repoState = new Map();
+        this.permissionCache = new Map();
+        this.stopped = true;
+        this.stopping = false;
+        this.activePoll = null;
+        this.pollPending = false;
+        this.pollIntervalTimer = null;
+        this.requestPollTimer = null;
+        this.handler = handler;
+        this.config = config;
+        this.client =
+            client ??
+                new GithubClient({
+                    appId: config.appId,
+                    privateKey: config.privateKey,
+                    installationId: config.installationId,
+                });
+        this.ops = new GithubOps(this.client, { workspace: config.workspace });
+    }
+    // ==========================================================================
+    // Public API (implements MessagingBot)
+    // ==========================================================================
+    async start() {
+        this.stopped = false;
+        this.stopping = false;
+        this.appSlug = await this.client.getAppSlug();
+        // Canonical noreply author email (<user-id>+<login>@users.noreply.github.com)
+        // so the bot's commits link to its avatar/profile; degrade to a plain
+        // noreply spelling when the lookup fails.
+        try {
+            const botUserId = await this.client.getUserId(`${this.appSlug}[bot]`);
+            this.botEmail = `${botUserId}+${this.appSlug}[bot]@users.noreply.github.com`;
+        }
+        catch {
+            this.botEmail = `${this.appSlug}[bot]@users.noreply.github.com`;
+        }
+        this.watchedRepos =
+            this.config.repos.length > 0
+                ? parseRepoList(this.config.repos)
+                : (await this.client.listInstallationRepositories()).map((repository) => ({
+                    owner: repository.owner.login.toLowerCase(),
+                    repo: repository.name.toLowerCase(),
+                }));
+        if (this.watchedRepos.length === 0) {
+            log.logWarning("GitHub: installation has no repositories; nothing to poll");
+        }
+        // Restore persisted watermarks; a repo watched for the first time gets a
+        // baseline of "now" so history never triggers (DESIGN.md § Event source).
+        const persisted = this.loadSyncState();
+        const now = new Date().toISOString();
+        for (const repo of this.watchedRepos) {
+            const repoKey = `${repo.owner}/${repo.repo}`;
+            const saved = persisted?.repos[repoKey];
+            this.repoState.set(repoKey, saved
+                ? {
+                    baseline: saved.baseline,
+                    cursor: saved.cursor,
+                    seenComments: new Set(saved.seenComments),
+                    seenIssues: new Set(saved.seenIssues),
+                    seenReviewComments: new Set(saved.seenReviewComments ?? []),
+                }
+                : {
+                    baseline: now,
+                    cursor: now,
+                    seenComments: new Set(),
+                    seenIssues: new Set(),
+                    seenReviewComments: new Set(),
+                });
+        }
+        this.persistSyncState();
+        if (this.stopping)
+            return;
+        this.stopped = false;
+        this.pollIntervalTimer = setInterval(() => {
+            void this.poll();
+        }, this.config.pollIntervalMs);
+        this.pollIntervalTimer.unref();
+        log.logConnected("GitHub");
+        log.logInfo(`GitHub bot started as @${this.appSlug}[bot], polling ${this.watchedRepos.length} repo(s) every ${Math.round(this.config.pollIntervalMs / 1000)}s`);
+    }
+    async stop() {
+        this.stopping = true;
+        this.pollPending = false;
+        if (this.pollIntervalTimer)
+            clearInterval(this.pollIntervalTimer);
+        if (this.requestPollTimer)
+            clearTimeout(this.requestPollTimer);
+        this.pollIntervalTimer = null;
+        this.requestPollTimer = null;
+        try {
+            if (this.activePoll)
+                await this.activePoll;
+        }
+        finally {
+            this.stopped = true;
+            await Promise.all([...this.queues.values()].map((queue) => queue.close()));
+        }
+    }
+    async postMessage(channel, text) {
+        const ref = parseGithubConversationId(channel);
+        const parts = splitText(text, GITHUB_MAX_COMMENT_LENGTH, formatGithubContinuation);
+        const firstId = await this.postComment(ref, parts[0] ?? text);
+        for (const part of parts.slice(1)) {
+            await this.postComment(ref, part);
+        }
+        return String(firstId);
+    }
+    async updateMessage(channel, ts, text) {
+        const ref = parseGithubConversationId(channel);
+        await githubRetry(() => this.client.updateIssueComment(ref.owner, ref.repo, Number(ts), text));
+    }
+    async addReaction(channel, messageTs, emoji) {
+        const ref = parseGithubConversationId(channel);
+        const content = GITHUB_REACTIONS[emoji.replace(/^:|:$/g, "")];
+        if (!content) {
+            throw new Error(`GitHub does not support reaction '${emoji}' (supported: ${Object.keys(GITHUB_REACTIONS).join(", ")})`);
+        }
+        const reviewCommentId = parseReviewCommentTs(messageTs);
+        await githubRetry(() => {
+            if (messageTs === GITHUB_ISSUE_BODY_TS) {
+                return this.client.createIssueReaction(ref.owner, ref.repo, ref.number, content);
+            }
+            if (reviewCommentId !== null) {
+                return this.client.createReviewCommentReaction(ref.owner, ref.repo, reviewCommentId, content);
+            }
+            return this.client.createCommentReaction(ref.owner, ref.repo, Number(messageTs), content);
+        });
+    }
+    enqueueEvent(event) {
+        if (this.stopped)
+            return false;
+        const conversationId = event.conversationId;
+        const queue = this.getQueue(conversationId);
+        if (queue.size() >= 5) {
+            log.logWarning(`Event queue full for ${conversationId}, discarding: ${event.text.substring(0, 50)}`);
+            return false;
+        }
+        log.logInfo(`Enqueueing event for ${conversationId}: ${event.text.substring(0, 50)}`);
+        return queue.enqueue(() => {
+            const context = createGithubAdapters(event, this);
+            return this.handler.handleEvent(event, this, context);
+        });
+    }
+    getMessagingInfo() {
+        return {
+            name: "github",
+            trustModel: "open-trigger",
+            formattingGuide: "## GitHub Formatting (GitHub Flavored Markdown)\n" +
+                "Standard Markdown plus tables, task lists, fenced code blocks, and ```suggestion blocks.\n" +
+                "Reference issues/PRs as #123 and users as @login (mentions notify people — use sparingly).",
+            channels: [],
+            users: [],
+        };
+    }
+    // ==========================================================================
+    // Internal helpers (used by context.ts)
+    // ==========================================================================
+    async postComment(ref, text) {
+        const comment = await githubRetry(() => this.client.createIssueComment(ref.owner, ref.repo, ref.number, text));
+        return comment.id;
+    }
+    async deleteComment(ref, commentId) {
+        await githubRetry(() => this.client.deleteIssueComment(ref.owner, ref.repo, commentId));
+    }
+    logToFile(conversationId, entry) {
+        appendChannelLog(this.office(conversationId), entry);
+    }
+    logBotResponse(conversationId, text, ts) {
+        appendBotResponseLog(this.office(conversationId), text, ts);
+    }
+    // ==========================================================================
+    // Private - polling
+    // ==========================================================================
+    getQueue(conversationId) {
+        let queue = this.queues.get(conversationId);
+        if (!queue) {
+            queue = new MessagingEventQueue("GitHub");
+            this.queues.set(conversationId, queue);
+        }
+        return queue;
+    }
+    /**
+     * Webhook poke: run a poll soon. Debounced so a burst of deliveries costs
+     * one tick; a poke landing mid-poll marks it pending and the tick re-runs,
+     * because the in-flight pass may already be past the poked repo's feeds.
+     */
+    requestPoll(debounceMs = REQUEST_POLL_DEBOUNCE_MS) {
+        if (this.stopped || this.stopping)
+            return;
+        if (this.activePoll) {
+            this.pollPending = true;
+            return;
+        }
+        if (this.requestPollTimer)
+            return;
+        this.requestPollTimer = setTimeout(() => {
+            this.requestPollTimer = null;
+            void this.poll();
+        }, debounceMs);
+        this.requestPollTimer.unref();
+    }
+    /** One poll tick over every watched repo. Public for tests. */
+    async poll() {
+        if (this.stopped || this.stopping)
+            return;
+        if (this.activePoll) {
+            this.pollPending = true;
+            return;
+        }
+        const activePoll = this.pollWatchedRepos();
+        this.activePoll = activePoll;
+        try {
+            await activePoll;
+        }
+        finally {
+            this.activePoll = null;
+            if (this.pollPending) {
+                this.pollPending = false;
+                this.requestPoll();
+            }
+        }
+    }
+    async pollWatchedRepos() {
+        let changed = false;
+        for (const repo of this.watchedRepos) {
+            try {
+                changed = (await this.pollRepo(repo)) || changed;
+            }
+            catch (err) {
+                log.logWarning(`GitHub poll failed for ${repo.owner}/${repo.repo}`, err instanceof Error ? err.message : String(err));
+            }
+        }
+        if (changed)
+            this.persistSyncState();
+    }
+    async pollRepo(repo) {
+        const repoKey = `${repo.owner}/${repo.repo}`;
+        const state = this.repoState.get(repoKey);
+        if (!state)
+            return false;
+        const since = new Date(Date.parse(state.cursor) - POLL_OVERLAP_MS).toISOString();
+        let changed = false;
+        // Comment activity also bumps the parent issue's updated_at, so the issues
+        // list mostly echoes the comments list; only issues *created* since the
+        // baseline are new conversations (their body is the first message).
+        const issues = (await this.client.listIssuesSince(repo.owner, repo.repo, since)) ?? [];
+        changed =
+            (await this.advanceFeed(state, state.seenIssues, issues, (issue) => ({
+                ref: { ...repo, number: issue.number },
+                ts: GITHUB_ISSUE_BODY_TS,
+                user: issue.user.login,
+                text: `# ${issue.title}\n\n${issue.body ?? ""}`.trim(),
+                createdAt: issue.created_at,
+                isPr: Boolean(issue.pull_request),
+            }))) || changed;
+        const comments = (await this.client.listIssueCommentsSince(repo.owner, repo.repo, since)) ?? [];
+        changed =
+            (await this.advanceFeed(state, state.seenComments, comments, (comment) => ({
+                ref: { ...repo, number: issueNumberFromUrl(comment.issue_url) },
+                ts: String(comment.id),
+                user: comment.user.login,
+                text: comment.body,
+                createdAt: comment.created_at,
+            }))) || changed;
+        // Inline PR review comments live in their own endpoint and id space; the
+        // same watermark discipline applies. The bot's own thread replies (the
+        // github_review_reply tool) re-surface here and are dropped as Bot-authored.
+        const reviewComments = (await this.client.listPullReviewCommentsSince(repo.owner, repo.repo, since)) ?? [];
+        changed =
+            (await this.advanceFeed(state, state.seenReviewComments, reviewComments, (comment) => ({
+                ref: { ...repo, number: prNumberFromUrl(comment.pull_request_url) },
+                ts: githubReviewCommentTs(comment.id),
+                user: comment.user.login,
+                text: comment.body,
+                createdAt: comment.created_at,
+                isPr: true,
+                review: {
+                    commentId: comment.id,
+                    path: comment.path,
+                    line: comment.line,
+                    diffHunk: comment.diff_hunk,
+                    inReplyToId: comment.in_reply_to_id,
+                },
+            }))) || changed;
+        pruneSeen(state.seenComments);
+        pruneSeen(state.seenIssues);
+        pruneSeen(state.seenReviewComments);
+        return changed;
+    }
+    /**
+     * One feed's watermark advance — the same discipline for all three feeds:
+     * bump the cursor on any fresher updated_at, then let the id watermark plus
+     * the creation baseline decide what actually triggers (edits re-surface old
+     * items with a fresh updated_at). Bot-authored items advance the watermark
+     * without triggering.
+     */
+    async advanceFeed(state, seen, items, toIncoming) {
+        let changed = false;
+        for (const item of items) {
+            if (item.updated_at > state.cursor) {
+                state.cursor = item.updated_at;
+                changed = true;
+            }
+            if (item.created_at < state.baseline || seen.has(item.id))
+                continue;
+            seen.add(item.id);
+            changed = true;
+            if (item.user.type === "Bot")
+                continue;
+            await this.handleIncoming(toIncoming(item));
+        }
+        return changed;
+    }
+    // ==========================================================================
+    // Private - watermark persistence
+    // ==========================================================================
+    loadSyncState() {
+        try {
+            return readJsonSchemaFileIfExists(this.config.syncStatePath, SyncStateSchema, (detail) => `Malformed GitHub sync state at ${this.config.syncStatePath}: ${detail}`);
+        }
+        catch (err) {
+            // A bad state file re-baselines (history won't trigger) rather than
+            // blocking startup; the next persist overwrites it.
+            log.logWarning("GitHub: ignoring unreadable sync state", err instanceof Error ? err.message : String(err));
+            return undefined;
+        }
+    }
+    /** The persisted form of the current watermarks; the test/inspection surface. */
+    syncStateSnapshot() {
+        const state = { repos: {} };
+        for (const [repoKey, watermark] of this.repoState) {
+            state.repos[repoKey] = {
+                baseline: watermark.baseline,
+                cursor: watermark.cursor,
+                seenComments: [...watermark.seenComments],
+                seenIssues: [...watermark.seenIssues],
+                seenReviewComments: [...watermark.seenReviewComments],
+            };
+        }
+        return state;
+    }
+    persistSyncState() {
+        ensureDirExists(dirname(this.config.syncStatePath));
+        atomicWritePrivateFile(this.config.syncStatePath, JSON.stringify(this.syncStateSnapshot()));
+    }
+    // ==========================================================================
+    // Private - triggering
+    // ==========================================================================
+    /** Fresh regex per call: the `g` flag makes `test`/`replace` stateful. */
+    mentionPattern() {
+        return this.appSlug ? new RegExp(`@${this.appSlug}(?![\\w-])`, "gi") : null;
+    }
+    isMentioned(text) {
+        const pattern = this.mentionPattern();
+        return pattern ? pattern.test(text) : false;
+    }
+    stripMention(text) {
+        const pattern = this.mentionPattern();
+        return (pattern ? text.replace(pattern, "") : text).trim();
+    }
+    /** The Conversation office for a GitHub conversation id (one PR/issue). */
+    office(conversationId) {
+        return this.config.workspace.office(createOfficeAddress("github", conversationId));
+    }
+    isParticipating(conversationId) {
+        return existsSync(this.office(conversationId).logPath);
+    }
+    /**
+     * True when `user` holds at least write permission on the repo. Fails
+     * closed: a failed lookup denies the trigger (and logs) rather than
+     * letting an unverified commenter drive the agent.
+     */
+    async hasTriggerPermission(ref, user) {
+        const cacheKey = `${ref.owner}/${ref.repo}#${user}`;
+        const cached = this.permissionCache.get(cacheKey);
+        if (cached && Date.now() < cached.expiresAt) {
+            return cached.rank >= REQUIRED_TRIGGER_RANK;
+        }
+        let rank;
+        try {
+            const role = await githubRetry(() => this.client.getCollaboratorPermission(ref.owner, ref.repo, user));
+            // Custom role_name values are unrankable; the legacy permission field
+            // still carries their closest standard mapping, so take the stronger.
+            rank = Math.max(rankOfPermission(role.role_name ?? ""), rankOfPermission(role.permission));
+        }
+        catch (err) {
+            log.logWarning(`GitHub: permission lookup failed for ${user} on ${ref.owner}/${ref.repo}; denying trigger`, err instanceof Error ? err.message : String(err));
+            return false;
+        }
+        this.permissionCache.set(cacheKey, {
+            rank,
+            expiresAt: Date.now() + PERMISSION_CACHE_TTL_MS,
+        });
+        return rank >= REQUIRED_TRIGGER_RANK;
+    }
+    async handleIncoming(item) {
+        const conversationId = buildGithubConversationId(item.ref);
+        const mentioned = this.isMentioned(item.text);
+        const participating = this.isParticipating(conversationId);
+        // Narrow trigger (DESIGN.md): only threads the bot is mentioned in or
+        // already participates in. Everything else is ignored without logging so
+        // busy repos don't grow conversation dirs for untouched issues.
+        if (!mentioned && !participating)
+            return;
+        // Permission gate: on public repos anyone can comment, so a mention from
+        // anyone below write permission is ignored entirely (no log, no state).
+        if (!(await this.hasTriggerPermission(item.ref, item.user))) {
+            log.logInfo(`GitHub: ignoring ${conversationId} comment from ${item.user} (below write permission)`);
+            return;
+        }
+        const cleanedText = this.stripMention(item.text);
+        const sessionKey = resolveChatSessionKey({
+            conversationId,
+            conversationKind: "shared",
+            messageId: item.ts,
+            persistentTopLevel: true,
+        });
+        const messageText = item.review
+            ? await this.formatReviewMessage(item, cleanedText)
+            : cleanedText;
+        const eventBase = createConversationEvent({
+            platform: "github",
+            type: item.ts === GITHUB_ISSUE_BODY_TS ? "issue" : "message",
+            conversationId,
+            conversationKind: "shared",
+            ts: item.ts,
+            sessionKey,
+            user: item.user,
+            userName: item.user,
+            text: messageText,
+        });
+        await processMessageIntake({
+            eventBase,
+            addressed: true,
+            // Match on the user-typed text, not the review-decorated messageText.
+            magicWord: { text: cleanedText, addressed: mentioned, scopeFallback: "never" },
+            busyPolicy: "queue",
+            logEntryBase: {
+                date: item.createdAt,
+                ts: item.ts,
+                user: item.user,
+                userName: item.user,
+                text: messageText,
+                isMessagingBot: false,
+            },
+            // log.jsonl existence is the participation authority for this adapter:
+            // a first-contact magic word ("@bot stop" on an untouched issue) must
+            // not materialize the log, or every later comment from any writer
+            // would be treated as addressed to a conversation the bot never joined.
+            log: (entry) => {
+                if (!participating && matchMagicWord(cleanedText) === "stop")
+                    return;
+                this.logToFile(conversationId, entry);
+            },
+            // GitHub has no attachments; the prep hook is used to lay down the
+            // issue context and repo clone only for messages that will dispatch,
+            // and before the comment itself is logged.
+            processAttachments: async () => {
+                await this.prepareConversation(item, conversationId, participating);
+                return [];
+            },
+            queueKey: conversationId,
+            enqueue: (queueKey, work) => this.getQueue(queueKey).enqueue(work),
+            handler: this.handler,
+            bot: this,
+            createContext: (event) => createGithubAdapters(event, this),
+        });
+    }
+    /**
+     * First contact: log the issue title/body ahead of the comment so the
+     * session history starts with what the thread is about. The clone is
+     * (re)attempted on every trigger while ./repo is missing — a no-op once
+     * it exists — so a failed first clone (e.g. App permissions granted
+     * later) heals on the next mention instead of wedging the conversation.
+     */
+    async prepareConversation(item, conversationId, participating) {
+        let isPrHint = item.isPr;
+        if (!participating && item.ts !== GITHUB_ISSUE_BODY_TS) {
+            const issue = await this.logIssueContext(item.ref, conversationId, item.createdAt);
+            // Only comments arrive without the PR-ness hint; review comments carry
+            // isPr: true (they only exist on PRs) and that knowledge is authoritative.
+            if (issue && isPrHint === undefined)
+                isPrHint = Boolean(issue.pull_request);
+        }
+        if (!existsSync(conversationRepoDir(this.office(conversationId)))) {
+            const isPr = isPrHint ?? (await fetchIsPr(this.client, item.ref));
+            await this.ensureRepoClone(item.ref, conversationId, isPr);
+        }
+    }
+    /**
+     * Decorates an inline review comment with its diff anchor and (for replies)
+     * the thread's earlier turns, so the agent knows which code the feedback is
+     * about without hunting through the PR. The rc-<id> in the header is what
+     * github_review_reply takes to answer in-thread.
+     */
+    async formatReviewMessage(item, cleanedText) {
+        const review = item.review;
+        const location = review.line !== null ? `${review.path}:${review.line}` : review.path;
+        const parts = [`[PR review comment ${githubReviewCommentTs(review.commentId)} on ${location}]`];
+        if (review.diffHunk) {
+            const hunk = review.diffHunk.length > MAX_DIFF_HUNK_CHARS
+                ? `…${review.diffHunk.slice(-MAX_DIFF_HUNK_CHARS)}`
+                : review.diffHunk;
+            parts.push(`\`\`\`diff\n${hunk}\n\`\`\``);
+        }
+        if (review.inReplyToId !== undefined) {
+            const turns = await this.reviewThreadContext(item.ref, review.inReplyToId, review.commentId);
+            if (turns.length > 0) {
+                parts.push(`Thread so far:\n${turns.join("\n")}`);
+            }
+        }
+        parts.push(cleanedText);
+        return parts.join("\n");
+    }
+    /**
+     * Earlier turns of one review thread (root + replies before the trigger),
+     * newest-truncated. Fail-soft: context is a nicety, the trigger is not.
+     */
+    async reviewThreadContext(ref, rootId, beforeId) {
+        try {
+            const all = await githubRetry(() => this.client.listPullReviewComments(ref.owner, ref.repo, ref.number));
+            return all
+                .filter((comment) => (comment.id === rootId || comment.in_reply_to_id === rootId) && comment.id < beforeId)
+                .slice(-MAX_THREAD_TURNS)
+                .map((comment) => {
+                const body = comment.body.length > MAX_THREAD_TURN_CHARS
+                    ? `${comment.body.slice(0, MAX_THREAD_TURN_CHARS)}…`
+                    : comment.body;
+                return `@${comment.user.login}: ${body}`;
+            });
+        }
+        catch (err) {
+            log.logWarning(`GitHub: could not fetch review thread context for ${ref.owner}/${ref.repo}#${ref.number}`, err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    async logIssueContext(ref, conversationId, triggerCreatedAt) {
+        let issue;
+        try {
+            issue = await githubRetry(() => this.client.getIssue(ref.owner, ref.repo, ref.number));
+        }
+        catch (err) {
+            log.logWarning(`GitHub: could not fetch issue context for ${conversationId}`, err instanceof Error ? err.message : String(err));
+            return null;
+        }
+        // Dated just before the triggering comment, NOT issue.created_at: history
+        // sync date-sorts entries and drops anything older than its recency
+        // window, so an old issue's real creation date would silently evict the
+        // one message that says what the thread is about.
+        const triggerMs = Date.parse(triggerCreatedAt);
+        const contextDate = new Date((Number.isFinite(triggerMs) ? triggerMs : Date.now()) - 1000);
+        this.logToFile(conversationId, {
+            date: contextDate.toISOString(),
+            ts: GITHUB_ISSUE_BODY_TS,
+            user: issue.user.login,
+            userName: issue.user.login,
+            text: `# ${issue.title}\n\n${issue.body ?? ""}`.trim(),
+            attachments: [],
+            isMessagingBot: false,
+        });
+        return issue;
+    }
+    // ==========================================================================
+    // Repo clone
+    // ==========================================================================
+    /**
+     * Clone the conversation's repo into its dir (bind-mounted into the
+     * sandbox) using an ephemeral contents:read token that never leaves the
+     * host. Non-fatal: a failed clone degrades to the pre-clone experience.
+     */
+    async ensureRepoClone(ref, conversationId, isPr) {
+        const office = this.office(conversationId);
+        const dir = conversationRepoDir(office);
+        if (existsSync(dir))
+            return;
+        try {
+            office.ensure();
+            const token = await this.client.createScopedInstallationToken(ref.repo, {
+                contents: "read",
+            });
+            const prHeadBranch = isPr ? await fetchPrHeadBranch(this.client, ref) : undefined;
+            await cloneRepo({
+                url: `https://github.com/${ref.owner}/${ref.repo}.git`,
+                dir,
+                token,
+                botLogin: `${this.appSlug}[bot]`,
+                botEmail: this.botEmail ?? `${this.appSlug}[bot]@users.noreply.github.com`,
+                prNumber: isPr ? ref.number : undefined,
+                prHeadBranch,
+            });
+            log.logInfo(`[${conversationId}] Cloned ${ref.owner}/${ref.repo}${isPr ? ` and checked out PR #${ref.number} head as ${prHeadBranch ?? `pr-${ref.number}`}` : ""}`);
+        }
+        catch (err) {
+            log.logWarning(`GitHub: repo clone failed for ${conversationId}`, err instanceof Error ? err.message : String(err));
+        }
+    }
+}
+//# sourceMappingURL=bot.js.map