@geminixiang/mikan 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/adapters/github/bot.js

@@ -0,0 +1,581 @@
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { Type } from "@sinclair/typebox";
+import * as log from "../../log.js";
+import { ensureDirExists, readJsonSchemaFileIfExists } from "../../utils/file-guards.js";
+import { atomicWritePrivateFile } from "../../utils/fs-atomic.js";
+import { resolveChatSessionKey } from "../../sessions/policy.js";
+import { formatNothingRunning } from "../../platform-messages.js";
+import { appendBotResponseLog, appendChannelLog, MessagingEventQueue, resolveStopTarget, splitText, withRetry, } from "../shared.js";
+import { processMessageIntake } from "../intake.js";
+import { GithubClient, githubIsRateLimited } from "./client.js";
+import { createGithubAdapters } from "./context.js";
+import { cloneRepo, GITHUB_PUSH_BRANCH_PATTERN, pushBranch } from "./repo.js";
+import { buildGithubConversationId, GITHUB_ISSUE_BODY_TS, parseGithubConversationId, } 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()),
+    })),
+});
+/**
+ * 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;
+/** 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;
+/** Permission lookups are cached this long per repo+user. */
+const PERMISSION_CACHE_TTL_MS = 5 * 60 * 1000;
+const githubRetry = (fn) => withRetry(fn, { isRateLimited: githubIsRateLimited });
+/** GitHub comment bodies cap at 65536 chars; leave headroom for markup. */
+export const GITHUB_MAX_COMMENT_LENGTH = 60000;
+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]);
+}
+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.pollInFlight = false;
+        this.handler = handler;
+        this.config = config;
+        this.client =
+            client ??
+                new GithubClient({
+                    appId: config.appId,
+                    privateKey: config.privateKey,
+                    installationId: config.installationId,
+                });
+    }
+    // ==========================================================================
+    // Public API (implements MessagingBot)
+    // ==========================================================================
+    async start() {
+        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),
+                }
+                : { baseline: now, cursor: now, seenComments: new Set(), seenIssues: new Set() });
+        }
+        this.persistSyncState();
+        setInterval(() => {
+            void this.poll();
+        }, this.config.pollIntervalMs).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 postMessage(channel, text) {
+        const ref = parseGithubConversationId(channel);
+        const parts = splitText(text, GITHUB_MAX_COMMENT_LENGTH, formatGithubContinuation);
+        const firstId = await this.postComment(ref, parts[0]);
+        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(", ")})`);
+        }
+        await githubRetry(() => messageTs === GITHUB_ISSUE_BODY_TS
+            ? this.client.createIssueReaction(ref.owner, ref.repo, ref.number, content)
+            : this.client.createCommentReaction(ref.owner, ref.repo, Number(messageTs), content));
+    }
+    enqueueEvent(event) {
+        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)}`);
+        queue.enqueue(() => {
+            const context = createGithubAdapters(event, this);
+            return this.handler.handleEvent(event, this, context);
+        });
+        return true;
+    }
+    getMessagingInfo() {
+        return {
+            name: "github",
+            formattingGuide: "## GitHub Formatting (GitHub Flavored Markdown)\n" +
+                "Standard Markdown plus tables, task lists, and ```suggestion blocks.\n" +
+                "Reference issues/PRs as #123 and users as @login.",
+            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.config.workingDir, conversationId, entry);
+    }
+    logBotResponse(conversationId, text, ts) {
+        appendBotResponseLog(this.config.workingDir, 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;
+    }
+    /** One poll tick over every watched repo. Public for tests. */
+    async poll() {
+        if (this.pollInFlight)
+            return;
+        this.pollInFlight = true;
+        try {
+            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();
+            }
+        }
+        finally {
+            this.pollInFlight = false;
+        }
+    }
+    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)) ?? [];
+        for (const issue of issues) {
+            if (issue.updated_at > state.cursor) {
+                state.cursor = issue.updated_at;
+                changed = true;
+            }
+            // Edits re-surface old items with a fresh updated_at; the id watermark
+            // plus the creation baseline decide what actually triggers.
+            if (issue.created_at < state.baseline || state.seenIssues.has(issue.id))
+                continue;
+            state.seenIssues.add(issue.id);
+            changed = true;
+            if (issue.user.type === "Bot")
+                continue;
+            await this.handleIncoming({
+                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),
+            });
+        }
+        const comments = (await this.client.listIssueCommentsSince(repo.owner, repo.repo, since)) ?? [];
+        for (const comment of comments) {
+            if (comment.updated_at > state.cursor) {
+                state.cursor = comment.updated_at;
+                changed = true;
+            }
+            if (comment.created_at < state.baseline || state.seenComments.has(comment.id))
+                continue;
+            state.seenComments.add(comment.id);
+            changed = true;
+            if (comment.user.type === "Bot")
+                continue;
+            await this.handleIncoming({
+                ref: { ...repo, number: issueNumberFromUrl(comment.issue_url) },
+                ts: String(comment.id),
+                user: comment.user.login,
+                text: comment.body,
+                createdAt: comment.created_at,
+            });
+        }
+        pruneSeen(state.seenComments);
+        pruneSeen(state.seenIssues);
+        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;
+        }
+    }
+    persistSyncState() {
+        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],
+            };
+        }
+        ensureDirExists(dirname(this.config.syncStatePath));
+        atomicWritePrivateFile(this.config.syncStatePath, JSON.stringify(state));
+    }
+    // ==========================================================================
+    // 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();
+    }
+    isParticipating(conversationId) {
+        return existsSync(join(this.config.workingDir, conversationId, "log.jsonl"));
+    }
+    /**
+     * 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(PERMISSION_RANK[role.role_name ?? ""] ?? 0, PERMISSION_RANK[role.permission] ?? 0);
+        }
+        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,
+        });
+        if (/^stop$/i.test(cleanedText)) {
+            this.logToFile(conversationId, {
+                date: item.createdAt,
+                ts: item.ts,
+                user: item.user,
+                userName: item.user,
+                text: cleanedText,
+                attachments: [],
+                isMessagingBot: false,
+            });
+            const stopTarget = resolveStopTarget({ handler: this.handler, conversationId, sessionKey });
+            if (stopTarget) {
+                await this.handler.handleStop(stopTarget, conversationId, this);
+            }
+            else if (mentioned) {
+                await this.postMessage(conversationId, formatNothingRunning("github"));
+            }
+            return;
+        }
+        // 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.
+        let isPrHint = item.isPr;
+        if (!participating && item.ts !== GITHUB_ISSUE_BODY_TS) {
+            const issue = await this.logIssueContext(item.ref, conversationId, item.createdAt);
+            if (issue)
+                isPrHint = Boolean(issue.pull_request);
+        }
+        if (!existsSync(this.repoDir(conversationId))) {
+            const isPr = isPrHint ?? (await this.fetchIsPr(item.ref));
+            await this.ensureRepoClone(item.ref, conversationId, isPr);
+        }
+        const eventBase = {
+            type: item.ts === GITHUB_ISSUE_BODY_TS ? "issue" : "message",
+            conversationId,
+            conversationKind: "shared",
+            ts: item.ts,
+            sessionKey,
+            user: item.user,
+            userName: item.user,
+            text: cleanedText,
+        };
+        await processMessageIntake({
+            eventBase,
+            workingDir: this.config.workingDir,
+            isAutoReplyCandidate: false,
+            logEntryBase: {
+                date: item.createdAt,
+                ts: item.ts,
+                user: item.user,
+                userName: item.user,
+                text: cleanedText,
+                isMessagingBot: false,
+            },
+            log: (entry) => this.logToFile(conversationId, entry),
+            processAttachments: async () => [],
+            queueKey: conversationId,
+            enqueue: (queueKey, work) => this.getQueue(queueKey).enqueue(work),
+            handler: this.handler,
+            bot: this,
+            createContext: (event) => createGithubAdapters(event, this),
+        });
+    }
+    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 + pull requests
+    // ==========================================================================
+    repoDir(conversationId) {
+        return join(this.config.workingDir, conversationId, "repo");
+    }
+    /** Whether the conversation's issue is a PR, for clone retries where the
+     *  triggering item didn't carry that knowledge. Errs toward plain issue. */
+    async fetchIsPr(ref) {
+        try {
+            const issue = await githubRetry(() => this.client.getIssue(ref.owner, ref.repo, ref.number));
+            return Boolean(issue.pull_request);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 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 dir = this.repoDir(conversationId);
+        if (existsSync(dir))
+            return;
+        try {
+            const token = await this.client.createScopedInstallationToken(ref.repo, {
+                contents: "read",
+            });
+            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,
+            });
+            log.logInfo(`[${conversationId}] Cloned ${ref.owner}/${ref.repo}${isPr ? ` and checked out PR #${ref.number} head` : ""}`);
+        }
+        catch (err) {
+            log.logWarning(`GitHub: repo clone failed for ${conversationId}`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    /**
+     * Backs the `github_pr` tool: push a `pi/*` branch the agent prepared in
+     * the conversation's clone, then open a pull request as the App. The write
+     * token is minted per call, scoped to this one repo, and never enters the
+     * sandbox.
+     */
+    async pushAndCreatePr(conversationId, request) {
+        const ref = parseGithubConversationId(conversationId);
+        const dir = this.repoDir(conversationId);
+        if (!existsSync(dir)) {
+            throw new Error("This conversation has no ./repo clone to push from.");
+        }
+        if (!GITHUB_PUSH_BRANCH_PATTERN.test(request.branch)) {
+            throw new Error(`Branch '${request.branch}' is not pushable: name it pi/<something> (e.g. pi/fix-${ref.number}).`);
+        }
+        const repository = await githubRetry(() => this.client.getRepository(ref.owner, ref.repo));
+        const base = request.base ?? repository.default_branch;
+        const token = await this.client.createScopedInstallationToken(ref.repo, {
+            contents: "write",
+            pull_requests: "write",
+        });
+        await pushBranch({ dir, branch: request.branch, token });
+        const pr = await githubRetry(() => this.client.createPullRequest(ref.owner, ref.repo, {
+            title: request.title,
+            head: request.branch,
+            base,
+            body: request.body,
+            draft: request.draft,
+        }));
+        log.logInfo(`[${conversationId}] Opened PR #${pr.number}: ${pr.html_url}`);
+        return { number: pr.number, url: pr.html_url };
+    }
+}
+//# sourceMappingURL=bot.js.map