berry-agent 0.1.0-alpha.1

package/dist/issue/service.js

@@ -0,0 +1,341 @@
+/**
+ * issue 服务面（03 §10.7 全条款的编排核心——无人值守 issue→PR 件）。
+ *
+ * 入队纪律（enqueue 同步裁决、running 判定到 register 零 await——双触发
+ * 源竞速安全）：
+ * capabilities 预检（goal/exec/checkpoint 三名缺席任一拒）→ closed 弃 →
+ * dedupeKey 在飞互斥（running() 扫）→ 全局日池判（canAffordIssue）→
+ * jobs.register（kind 'issue'、name=dedupeKey、owner=合成键——会话未起，
+ * 见 types.ts owner 注记）→ fire runOne（不 await）。
+ *
+ * runOne 编舞（单 issue 全程）：
+ * worktree 名候选让位（issue-N → -r2..-r9，分支留史撞名域）→ create →
+ * startHeadless（cwd=worktree、prompt=buildIssuePrompt、预算帽、issue_get）→
+ * grant（拿到 sessionId 才能授予——create 时会话不存在的补授位）→ await
+ * outcome → 交付映射（04 §10 issue 消费注）：
+ * - draft+completed → 评论贴分支+补丁（60k 帽）→ settle completed；
+ * - auto+completed → 危险闸交付腿（04 §13——deliver = 闸包裹的 push/PR
+ *   执行）：push 分支 → 开 PR → 回执贴 PR 链接 → settle completed；闸拒
+ *   （DANGER_ 族）= 评论转人审 + 指路修复动作 + settle failed 需人审；
+ *   闸缺席（装配未注入 face）= 03 §10.7 原语义保持——阻塞转人审；
+ * - failed → 评论贴原因 → settle failed；
+ * - needs-human → 评论转人审 → settle failed（需人审）；
+ * - paused → **不 settle 不 clean 不释授予**——worktree/授予/在飞记账全
+ *   保留（budget_extended 唤醒 watcher 已接线——issue-session 起跑时登记
+ *   全部停靠 run，预算恢复自动唤醒续跑）。
+ * 收尾（非 paused）：worktree clean（dirty 保留不强拆——变更可能正是交付
+ * 物）、releaseSession。评论投递失败不阻塞 settle 的反面——settle 恒在评论
+ * 后落（人可见面优先；网络挂死场景 fetch 层兜底）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { createIssueTools } from './tools.js';
+import { createIssuePoller } from './poll.js';
+import { handleWebhookRequest } from './webhook.js';
+import { ISSUE_POLL_JOB_NAME, ISSUE_RECEIPT_PATCH_CHARS, ISSUE_WORKTREE_NAME_RE, issueDedupeKey } from './types.js';
+/** capabilities 预检名单（03 §10.7 ③入队定值——三名缺席任一拒） */
+const REQUIRED_CAPABILITIES = ['goal', 'exec', 'checkpoint'];
+/**
+ * 危险闸拒码 → 回执指路（04 §13 消费面按码分流呈现——approve / 重签 /
+ * 删 HALT / 次日或提帽重签四路）。未知码兜底呈现状态命令。
+ */
+const DANGER_REMEDIES = {
+    DANGER_CONSENT_ABSENT: 'consent 缺席——TUI 运行 /danger approve 签发授权后重跑',
+    DANGER_CONSENT_INVALID: 'consent 过期或配置漂移——重跑 /danger approve 重签',
+    DANGER_HALTED: 'HALT 哨兵在场——删除数据目录下 HALT 文件即恢复',
+    DANGER_TARGET_DENIED: '目标不在危险闸值域——检查件配置 repos 后重签 consent',
+    DANGER_CAP_EXCEEDED: '当日交付帽已达——UTC 次日自动恢复，或提帽后重签 consent',
+    DANGER_LEDGER_CORRUPT: '危险闸审计账本链损坏——人工检修（截断/重建是人工决策）',
+};
+/** 拒码指路取值（未知码兜底——不静默） */
+function dangerRemedy(code) {
+    return DANGER_REMEDIES[code] ?? '运行 /danger status 检查危险闸状态';
+}
+/** builtin 轮询行的 prompt 占位（RunnerFactory 对该行名程序化分派 pollOnce 零 token——行 prompt 不入模型面） */
+const POLL_PROMPT_PLACEHOLDER = '(builtin) issue 轮询占位——挂钟行由 issue 件程序化分派（pollOnce），本 prompt 不发往任何模型';
+/** 组 issue 服务 */
+export function createIssueService(deps) {
+    const warn = deps.warn ?? (() => undefined);
+    // 在飞记账（dedupeKey → worktree 名——orphanScan 的在飞减集；paused 停靠保留）
+    const inflight = new Map();
+    /** worktree 名候选序列（issue-N 首选；分支留史撞名让位 -r2..-r9——九连撞即弃转人审） */
+    function* worktreeNameCandidates(number) {
+        yield `issue-${number}`;
+        for (let r = 2; r <= 9; r++)
+            yield `issue-${number}-r${r}`;
+    }
+    /** 组单 issue 的 headless 首跑 prompt（交付纪律内嵌：禁 push/PR/评论、预算可见、issue_get 指引） */
+    function buildIssuePrompt(issue, branch) {
+        return [
+            `处理 GitHub issue ${issue.repo}#${issue.number}：「${issue.title}」。`,
+            '',
+            '- 先用 issue_get 工具读 issue 正文与全部评论（本会话已绑定该 issue，无需参数）。',
+            `- 当前目录是为本次任务建的独立 git worktree（分支 ${branch}）——所有改动在此分支上做并本地提交。`,
+            '- 严禁 push、严禁创建 PR、严禁对 issue 发评论（交付由编排层收口——越界动作将被拒）。',
+            `- 消息预算上限 ${deps.config.perIssueBudgetMessages} 条——聚焦最小可用改动，相关测试跑绿即算达成。`,
+            '- 目标：完成 issue 所述改动（含测试）并在本地提交。',
+        ].join('\n');
+    }
+    /** 评论投递（失败不抛——回执后补语义，warn 记；终态必落优先于投递成功） */
+    async function postReceipt(issue, body) {
+        try {
+            await deps.backend.postComment({ repo: issue.repo, number: issue.number, body });
+        }
+        catch (err) {
+            warn(`issue 回执评论投递失败（${issue.repo}#${issue.number}）：${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * runOne：单 issue 全程编舞（enqueue fire——不 await 调用方）。自身异常
+     * 兜底 settle failed（终态必落——编舞崩溃不悬挂注册表）。
+     */
+    async function runOne(issue, key) {
+        const handle = deps.jobs.register({ kind: 'issue', name: key, owner: `issue-job:${key}` });
+        let created;
+        let sessionId;
+        let retain = false; // paused 停靠：授予/worktree/在飞记账全保留（唤醒接线随装配批）
+        try {
+            // ── 隔离：worktree 名候选让位（撞名 = 前次重跑残留——分支留史的代价面） ──
+            let lastExists;
+            for (const name of worktreeNameCandidates(issue.number)) {
+                try {
+                    created = await deps.worktree.create({ name });
+                    break;
+                }
+                catch (err) {
+                    if (err instanceof BaseError && err.code === 'FS_WORKTREE_EXISTS') {
+                        lastExists = err;
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            if (created === undefined) {
+                throw lastExists instanceof Error
+                    ? lastExists
+                    : new Error(`worktree 名候选 9 连撞（issue-${issue.number}——需人清残留分支）`);
+            }
+            inflight.set(key, created.name);
+            // ── 起跑：headless 会话（cwd=worktree、预算帽、issue_get 绑定面） ──
+            const started = await deps.session.startHeadless({
+                cwd: created.path,
+                prompt: buildIssuePrompt(issue, created.branch),
+                budgetMessages: deps.config.perIssueBudgetMessages,
+                tools: createIssueTools({ backend: deps.backend, repo: issue.repo, number: issue.number }),
+            });
+            sessionId = started.sessionId;
+            // 拿到 sessionId 才能授予（create 时会话不存在的补授位——04 §7 补钉①编排路径）
+            await deps.worktree.grant({ sessionId: started.sessionId, path: created.path });
+            const outcome = await started.outcome;
+            // ── 交付映射（04 §10 issue 消费注·终态三因） ──
+            if (outcome.status === 'paused') {
+                retain = true;
+                warn(`issue run 停靠（${key}）：全局预算日池尽——worktree ${created.name} 与授予保留，预算恢复后经 budget_extended 唤醒自动续跑`);
+                return;
+            }
+            if (outcome.status === 'completed') {
+                if (deps.config.mode === 'draft') {
+                    // draft 档：评论贴分支 + 补丁（60k 字符帽——GitHub 评论体上限内留余量）
+                    let patch = '';
+                    try {
+                        patch = await deps.worktree.diffPatch({ name: created.name, baseRef: deps.config.baseBranch });
+                    }
+                    catch (err) {
+                        warn(`补丁取数失败（${key}）：${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    if (patch.length > ISSUE_RECEIPT_PATCH_CHARS) {
+                        patch = `${patch.slice(0, ISSUE_RECEIPT_PATCH_CHARS)}\n…（补丁超 ${ISSUE_RECEIPT_PATCH_CHARS} 字符帽截断）`;
+                    }
+                    await postReceipt(issue, [
+                        `🤖 issue run 完成（draft 档）：分支 \`${created.branch}\`（本地——未 push）`,
+                        outcome.summary,
+                        '',
+                        '```diff',
+                        patch || '（无补丁——无改动或取数失败）',
+                        '```',
+                    ].join('\n'));
+                    handle.settle({
+                        status: 'completed',
+                        detail: `draft：分支 ${created.branch}（${outcome.messagesUsed} 条消息）`,
+                    });
+                }
+                else {
+                    // auto 档：危险闸交付腿（04 §13——deliver = 闸包裹的 push/PR 执行闭包）。
+                    // 闸缺席（装配未注入 face）= 03 §10.7 原语义保持：阻塞转人审。
+                    if (deps.danger === undefined) {
+                        await postReceipt(issue, [
+                            `🤖 issue run 完成（auto 档）但不可逆外部写闸缺席——阻塞转人审：分支 \`${created.branch}\` 已就绪（本地未 push），请人工确认后交付。`,
+                            outcome.summary,
+                        ].join('\n'));
+                        handle.settle({
+                            status: 'failed',
+                            detail: '需人审：不可逆外部写闸缺席（auto 档成果已备，push/PR 需人工）',
+                        });
+                        return;
+                    }
+                    // 交付序：先 push 分支（PR 依赖远端分支在场）→ 再开 PR → 回执贴链接。
+                    // pushed 位供拒/败回执如实陈述分支状态（已推远端 vs 本地未推）。
+                    let pushed = false;
+                    try {
+                        await deps.danger.deliver({
+                            kind: 'push',
+                            repo: issue.repo,
+                            branch: created.branch,
+                            worktreePath: created.path,
+                        });
+                        pushed = true;
+                        const pr = await deps.danger.deliver({
+                            kind: 'create-pr',
+                            repo: issue.repo,
+                            branch: created.branch,
+                            base: deps.config.baseBranch,
+                            title: issue.title,
+                            body: [outcome.summary, '', `Closes #${issue.number}`, '', `Source issue: ${issue.htmlUrl}`].join('\n'),
+                            worktreePath: created.path,
+                        });
+                        const prRef = pr.prUrl !== undefined && pr.prUrl !== '' ? pr.prUrl : `#${pr.prNumber ?? '?'}`;
+                        await postReceipt(issue, [
+                            `🤖 issue run 完成（auto 档——危险闸放行交付）：PR ${prRef} 已开（分支 \`${created.branch}\`）。`,
+                            outcome.summary,
+                        ].join('\n'));
+                        handle.settle({
+                            status: 'completed',
+                            detail: `auto：PR ${prRef}（分支 ${created.branch}，${outcome.messagesUsed} 条消息）`,
+                        });
+                    }
+                    catch (err) {
+                        // 两路分账：DANGER_ 族 = 闸拒（零外联——execute 未被调用）转人审 +
+                        // 指路修复；其余 = 过闸外部写失败（allow-failed 已记账）留分支重试。
+                        const branchState = pushed
+                            ? `分支 \`${created.branch}\` 已推远端（PR 未开成——可人工补开）`
+                            : `分支 \`${created.branch}\` 已就绪（本地未推）`;
+                        if (err instanceof BaseError && err.code.startsWith('DANGER_')) {
+                            const remedy = dangerRemedy(err.code);
+                            await postReceipt(issue, [
+                                `🤖 issue run 需人审（危险闸拒 ${err.code}）——${branchState}。`,
+                                `修复指路：${remedy}`,
+                                `原始判据：${err.message}`,
+                                outcome.summary,
+                            ].join('\n'));
+                            handle.settle({ status: 'failed', detail: `需人审：危险闸拒（${err.code}）——${remedy}` });
+                        }
+                        else {
+                            const detail = err instanceof Error ? err.message : String(err);
+                            await postReceipt(issue, [`🤖 issue run 交付失败（外部写未成）：${detail}——${branchState}，可重试。`, outcome.summary].join('\n'));
+                            handle.settle({ status: 'failed', detail: `交付失败：${detail}` });
+                        }
+                    }
+                }
+            }
+            else if (outcome.status === 'failed') {
+                await postReceipt(issue, `🤖 issue run 失败：${outcome.reason}（分支 \`${created.branch}\` 留存供排查）`);
+                handle.settle({ status: 'failed', detail: outcome.reason });
+            }
+            else {
+                // needs-human：无应答者审批拒/写动作无策略表覆盖（04 §9 fail-closed）——转人审
+                await postReceipt(issue, `🤖 issue run 需人审：${outcome.reason}（分支 \`${created.branch}\` 留存——处理后可重开）`);
+                handle.settle({ status: 'failed', detail: `需人审：${outcome.reason}` });
+            }
+            // ── 收尾：拆 worktree（dirty 保留——未提交变更可能是交付物残余） ──
+            try {
+                await deps.worktree.clean({ name: created.name });
+            }
+            catch (err) {
+                if (err instanceof BaseError && err.code === 'FS_WORKTREE_DIRTY') {
+                    warn(`issue worktree 未提交变更保留不拆（${created.name}）——分支 ${created.branch} 留存`);
+                }
+                else {
+                    warn(`issue worktree 清理失败（${created.name}）：${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        catch (err) {
+            // 兜底：编舞自身异常——终态必落（注册表不悬挂）
+            const detail = err instanceof Error ? err.message : String(err);
+            handle.settle({ status: 'failed', detail });
+            warn(`issue run 编舞异常（${key}）：${detail}`);
+            if (created !== undefined) {
+                try {
+                    await deps.worktree.clean({ name: created.name });
+                }
+                catch {
+                    // 兜底清理失败——残留归 orphanScan 标注
+                }
+            }
+        }
+        finally {
+            if (!retain) {
+                inflight.delete(key);
+                if (sessionId !== undefined)
+                    deps.worktree.releaseSession(sessionId);
+            }
+        }
+    }
+    /**
+     * 入队裁决（同步、零 await 到 register——竞速窗口不存在）。预检序：
+     * capabilities → closed → dedupe → budget → register → fire。
+     */
+    function enqueue(issue) {
+        for (const cap of REQUIRED_CAPABILITIES) {
+            if (!deps.capabilities.includes(cap)) {
+                return { status: 'rejected', reason: `能力缺席：${cap}（issue 件依赖 goal/exec/checkpoint 三件在场）` };
+            }
+        }
+        if (issue.state !== 'open') {
+            return { status: 'rejected', reason: `issue 已 ${issue.state}（终态不再入队）` };
+        }
+        const key = issueDedupeKey(issue.repo, issue.number);
+        if (deps.jobs.running().some((j) => j.name === key)) {
+            warn(`[ISSUE_JOB_DUPLICATE] 在飞互斥撞锁：${key}（进程内——不重入）`);
+            return { status: 'duplicate', key };
+        }
+        const afford = deps.budget.canAffordIssue();
+        if (!afford.ok) {
+            return { status: 'rejected', reason: afford.reason ?? '全局预算日池尽（停靠）' };
+        }
+        // fire（runOne 首语句 register 同步执行——enqueue 返回前已入册，紧随的
+        // 二次 enqueue 在 running() 扫描即见：互斥成立）
+        void runOne(issue, key);
+        return { status: 'started', key };
+    }
+    const poller = createIssuePoller({ backend: deps.backend, state: deps.state, config: deps.config, enqueue });
+    const service = {
+        start() {
+            deps.jobs.registerKind('issue');
+            try {
+                deps.scheduler.registerPollJob({
+                    name: ISSUE_POLL_JOB_NAME,
+                    schedule: deps.config.schedule,
+                    prompt: POLL_PROMPT_PLACEHOLDER,
+                });
+            }
+            catch (err) {
+                // 幂等：行已在（重启再启）——warn 不炸装配；其余守卫拒（schedule 坏串）同样响亮可见
+                warn(`issue 轮询行登记失败：${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+        stop() {
+            deps.scheduler.removePollJob(ISSUE_POLL_JOB_NAME);
+        },
+        pollOnce() {
+            return poller.pollOnce();
+        },
+        enqueue(issue) {
+            return enqueue(issue);
+        },
+        async handleWebhook(req) {
+            if (deps.webhookSecret === undefined || deps.webhookSecret === '') {
+                throw new BaseError('ISSUE_WEBHOOK_INVALID', '[ISSUE_WEBHOOK_INVALID] webhook 面未开启（缺 secret 配置）');
+            }
+            return handleWebhookRequest({ secret: deps.webhookSecret, config: deps.config, enqueue }, req);
+        },
+        async orphanScan() {
+            // 名形匹配减在飞——只标注不自动清（销账#3：残留 worktree = 标注孤儿）
+            const entries = await deps.worktree.list();
+            const inflightNames = new Set(inflight.values());
+            return entries
+                .filter((e) => ISSUE_WORKTREE_NAME_RE.test(e.name) && !inflightNames.has(e.name))
+                .map((e) => ({ name: e.name, path: e.path }));
+        },
+    };
+    return service;
+}

package/dist/issue/tools.js

@@ -0,0 +1,70 @@
+/**
+ * issue 工具面（03 §10.7——件注册的只读工具）。
+ *
+ * 单工具 `issue_get`：取本 issue 正文 + 评论清单（升序）。绑定面设计——
+ * repo/number 由件侧闭包注入（模型不可指定他仓他号：外部输入最小暴露面），
+ * 参数面零自由度（无参数——headless 会话生来只服务这一个 issue）。
+ *
+ * 上下文帽：正文 + 评论合计 ISSUE_CONTEXT_CAP_BYTES（64KiB）——外部不可信
+ * 文本进模型上下文的总闸（出口治理④字段瘦身同律）；超帽截断尾部并注记
+ * （截断标记让模型自知信息不全，不静默丢）。
+ */
+import { Type } from 'typebox';
+import { ISSUE_CONTEXT_CAP_BYTES } from './types.js';
+/** 组 issue_get 工具（单件数组——effect read 恒免审批） */
+export function createIssueTools(deps) {
+    return [
+        {
+            name: 'issue_get',
+            effect: 'read',
+            description: '取当前 issue 的正文与全部评论（时间升序）。无参数——本会话已绑定该 issue。输出超 64KiB 时尾部截断并注记。',
+            parameters: Type.Object({}),
+            execute: async () => {
+                const [issues, comments] = await Promise.all([
+                    deps.backend.listIssues({ repo: deps.repo }),
+                    deps.backend.listComments({ repo: deps.repo, number: deps.number }),
+                ]);
+                const mine = issues.find((i) => i.number === deps.number);
+                if (mine === undefined) {
+                    return {
+                        content: [
+                            { type: 'text', text: `issue ${deps.repo}#${deps.number} 不在源返回集内（可能已关闭或删除）` },
+                        ],
+                        isError: true,
+                    };
+                }
+                // 正文段（不可信外部文本——原样引用不转义解释，帽前标注来源）
+                const sections = [
+                    `# ${mine.title}（${mine.repo}#${mine.number}）`,
+                    `状态：${mine.state}｜标签：${mine.labels.join(', ') || '（无）'}｜指派：${mine.assignees.join(', ') || '（无）'}`,
+                    `链接：${mine.htmlUrl}`,
+                    '',
+                    mine.body || '（正文为空）',
+                ];
+                if (comments.length > 0) {
+                    sections.push('', '## 评论');
+                    for (const c of comments) {
+                        sections.push(`— ${c.author}（${c.createdAt}）：`, c.body || '（空）');
+                    }
+                }
+                let text = sections.join('\n');
+                // 总闸帽：超限截断尾部 + 截断注记（模型自知信息不全）
+                const bytes = Buffer.byteLength(text, 'utf8');
+                if (bytes > ISSUE_CONTEXT_CAP_BYTES) {
+                    // 逐段回退到帽内（段级截断——不产生半个多字节字符）
+                    const kept = [];
+                    let used = 0;
+                    for (const section of sections) {
+                        const b = Buffer.byteLength(section, 'utf8') + 1;
+                        if (used + b > ISSUE_CONTEXT_CAP_BYTES - 200)
+                            break; // 尾注记余量
+                        kept.push(section);
+                        used += b;
+                    }
+                    text = `${kept.join('\n')}\n\n…（内容超 ${ISSUE_CONTEXT_CAP_BYTES} 字节帽已截断——评论可能不全）`;
+                }
+                return { content: [{ type: 'text', text }], details: { comments: comments.length } };
+            },
+        },
+    ];
+}

package/dist/issue/types.js

@@ -0,0 +1,34 @@
+/* ---------------- 常量（缺省值单源——03 §10.7 落码定形注） ---------------- */
+/** 轮询挂钟行名（builtin 行——装配 RunnerFactory 对该名程序化分派 pollOnce） */
+export const ISSUE_POLL_JOB_NAME = 'issue-poll';
+/** 轮询缺省周期（120s——schedule 串形态承 scheduler 词法） */
+export const ISSUE_DEFAULT_SCHEDULE = 'every:120s';
+/** Job kind issue 并行帽缺省（04 §10 定值注——装配 createJobRegistry parallelLimits 槽用） */
+export const ISSUE_PARALLEL_LIMIT_DEFAULT = 2;
+/** 每 issue 预算帽缺省（消息条数——实测定值校准挂账） */
+export const ISSUE_PER_ISSUE_MESSAGES_DEFAULT = 400;
+/** 回执评论补丁字符帽（GitHub 评论体 64KiB 上限内留余量——超限截断注记） */
+export const ISSUE_RECEIPT_PATCH_CHARS = 60_000;
+/** issue_get 工具上下文帽字节（外部文本进上下文的总闸——出口治理④字段瘦身同律） */
+export const ISSUE_CONTEXT_CAP_BYTES = 64 * 1024;
+/** webhook 端点路径（POST——`/webhooks/*` 入站外部投递路由族首径；03 §10.7 批 18a-4' 落码定形） */
+export const ISSUE_WEBHOOK_ENDPOINT = '/webhooks/issue';
+/** webhook 请求体帽（per-route bodyLimitBytes 位——GitHub issue 载荷 64KiB 级 + 元数据余量） */
+export const ISSUE_WEBHOOK_BODY_LIMIT_BYTES = 256 * 1024;
+/** GitHub token 凭证名（host 域——03 §10.9「env 与库优先级」c-5 迁移：凭证库
+ * 优先、env `BERRY_AGENT_GITHUB_TOKEN` 过渡载体回落——/credentials add
+ * github-token <token> 录入即生效） */
+export const ISSUE_GITHUB_TOKEN_NAME = 'github-token';
+/** webhook HMAC secret 凭证名（host 域——同上律：库优先、env
+ * `BERRY_AGENT_ISSUE_WEBHOOK_SECRET` 过渡载体回落） */
+export const ISSUE_WEBHOOK_SECRET_NAME = 'issue-webhook-secret';
+/** 交付日成功帽缺省（04 §13——mandate maxPerDay 原料；正整数律在
+ * normalizeIssueConfig 执法：0/负数/坏形 = 空帽即坏形拒，彻底关停走 HALT
+ * 哨兵或撤 consent 不走空帽） */
+export const ISSUE_MAX_DELIVERIES_PER_DAY_DEFAULT = 10;
+/** dedupeKey（03 §10.7 入队条：`repo#issue`——进程内在飞互斥键非 durable 幂等键） */
+export function issueDedupeKey(repo, number) {
+    return `${repo}#${number}`;
+}
+/** worktree 名形（`issue-<n>` 首选、重跑递进 `-r<k>`——分支留史撞名让位） */
+export const ISSUE_WORKTREE_NAME_RE = /^issue-\d+(-r\d+)?$/;

package/dist/issue/webhook.js

@@ -0,0 +1,126 @@
+/**
+ * issue webhook 腿（03 §10.7 触发面——可开启面）。
+ *
+ * 验签：X-Signature-256 头 = `sha256=` + HMAC-SHA256(secret, 原始 body)——
+ * timingSafeEqual 常时比对（防时序侧信道）；缺头/坏头/签名不符一律
+ * ISSUE_WEBHOOK_INVALID 响亮拒（不静默吞——运维可见）。
+ *
+ * 载荷路由（GitHub webhook 事件面子集）：
+ * - `issues`（opened/labeled/assigned/reopened）→ 归一 IssueRef → 域匹配
+ *   （issueMatchesFilter）→ enqueue；域外静默记 ignored（他仓事件正常流）；
+ * - `issue_comment` → v1 留位（03 §10.7 裁决⑧：评论不触发——防评论风暴
+ *   自激；receipt 'comment-ignored' 可见）；
+ * - `pull_request` → ignore（PR 域不属本件触发面）;
+ * - 其余事件 → ignored。
+ *
+ * 不可信外部文本纪律同 github.ts：载荷字段进上下文前经调用方帽。
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { BaseError } from '../contracts/index.js';
+import { issueMatchesFilter } from './filter.js';
+/** 计算 X-Signature-256 期望值（`sha256=` + hex——与 GitHub 官方算法一致） */
+export function computeSignature(secret, rawBody) {
+    return `sha256=${createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex')}`;
+}
+/** 常时签名比对（等长前提 + timingSafeEqual；长度不等直接 false） */
+export function signatureMatches(secret, rawBody, header) {
+    const expected = computeSignature(secret, rawBody);
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(header, 'utf8');
+    if (a.length !== b.length || a.length === 0)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * 解析载荷（事件名 + JSON 体 → 判别联合）。坏形（JSON 坏/域字段缺/类型错）
+ * 折 ISSUE_WEBHOOK_INVALID——外部输入不信任、但拒绝可观测。
+ */
+export function parseWebhookPayload(event, rawBody) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        throw new BaseError('ISSUE_WEBHOOK_INVALID', '[ISSUE_WEBHOOK_INVALID] webhook 载荷非合法 JSON');
+    }
+    const obj = parsed;
+    if (obj === null || typeof obj !== 'object') {
+        throw new BaseError('ISSUE_WEBHOOK_INVALID', '[ISSUE_WEBHOOK_INVALID] webhook 载荷须 JSON 对象形');
+    }
+    if (event === 'issues') {
+        const p = obj;
+        const repo = p.repository?.full_name;
+        const i = p.issue;
+        if (typeof repo !== 'string' || i === null || typeof i !== 'object') {
+            throw new BaseError('ISSUE_WEBHOOK_INVALID', '[ISSUE_WEBHOOK_INVALID] issues 事件缺 repository/issue 域');
+        }
+        if (typeof i.number !== 'number' || typeof i.title !== 'string' || typeof i.updated_at !== 'string') {
+            throw new BaseError('ISSUE_WEBHOOK_INVALID', '[ISSUE_WEBHOOK_INVALID] issue 域字段坏形（number/title/updated_at）');
+        }
+        const asString = (v) => (typeof v === 'string' ? v : '');
+        return {
+            kind: 'issues',
+            action: asString(p.action),
+            issue: {
+                repo,
+                number: i.number,
+                title: i.title,
+                body: typeof i.body === 'string' ? i.body : '',
+                labels: (i.labels ?? []).map((l) => asString(l?.name)).filter((n) => n !== ''),
+                assignees: (i.assignees ?? []).map((a) => asString(a?.login)).filter((n) => n !== ''),
+                state: i.state === 'closed' ? 'closed' : 'open',
+                updatedAt: i.updated_at,
+                htmlUrl: asString(i.html_url),
+            },
+        };
+    }
+    if (event === 'issue_comment') {
+        const p = obj;
+        const repo = p.repository?.full_name;
+        const number = p.issue?.number;
+        if (typeof repo !== 'string' || typeof number !== 'number') {
+            throw new BaseError('ISSUE_WEBHOOK_INVALID', '[ISSUE_WEBHOOK_INVALID] issue_comment 事件缺 repository/issue 域');
+        }
+        return { kind: 'issue_comment', action: typeof p.action === 'string' ? p.action : '', repo, number };
+    }
+    if (event === 'pull_request') {
+        return {
+            kind: 'pull_request',
+            action: typeof obj.action === 'string' ? obj.action : '',
+        };
+    }
+    return { kind: 'ignored', event };
+}
+/** issues 事件触发动词集（opened/labeled/assigned/reopened——edited/closed/deleted 等不触发） */
+const TRIGGERING_ACTIONS = new Set(['opened', 'labeled', 'assigned', 'reopened']);
+/**
+ * 处理单次 webhook 请求（验签 → 解析 → 路由 → enqueue 裁决）。
+ * 验签失败/载荷坏形抛 BaseError（ISSUE_WEBHOOK_INVALID——装配层折 400）；
+ * 域外/非触发动作 receipt 可见不抛（他仓事件是正常流非错误）。
+ */
+export async function handleWebhookRequest(deps, req) {
+    // 验签先行（未过验不解析——坏载荷信息不外泄）
+    if (!req.signatureHeader || !signatureMatches(deps.secret, req.rawBody, req.signatureHeader)) {
+        throw new BaseError('ISSUE_WEBHOOK_INVALID', '[ISSUE_WEBHOOK_INVALID] webhook 签名不符（X-Signature-256 缺失或错值——检查 secret 配置）');
+    }
+    const payload = parseWebhookPayload(req.event, req.rawBody);
+    if (payload.kind === 'issues') {
+        if (!TRIGGERING_ACTIONS.has(payload.action))
+            return { receipt: 'out-of-scope' };
+        if (!issueMatchesFilter(payload.issue, deps.config))
+            return { receipt: 'out-of-scope' };
+        const result = await deps.enqueue(payload.issue);
+        if (result.status === 'started')
+            return { receipt: 'enqueued', key: `${payload.issue.repo}#${payload.issue.number}` };
+        if (result.status === 'duplicate')
+            return { receipt: 'duplicate', key: result.key };
+        return { receipt: 'rejected', reason: result.reason };
+    }
+    if (payload.kind === 'issue_comment') {
+        // v1 留位（裁决⑧）：评论不触发——receipt 可见便于日志判读
+        return { receipt: 'comment-ignored', repo: payload.repo, number: payload.number };
+    }
+    if (payload.kind === 'pull_request')
+        return { receipt: 'ignored', event: 'pull_request' };
+    return { receipt: 'ignored', event: payload.event };
+}

package/dist/llm/codes.js

@@ -0,0 +1,77 @@
+/**
+ * llm 域错误码注册（04 篇 §3.5 四桶码族 + §3.7 + §5——LLM_ 前缀族首批）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1）。本文件
+ * 由模块公开面 index.ts 引入（注册纪律：写入点文件必须实际 import 本文件，
+ * 注册才发生——与 session/persist 的 codes.ts 同款）。
+ *
+ * 两类载体：抛出面（BaseError——MODEL_* / COMPLETE_FAILED / BUDGET_EXCEEDED）
+ * 与数据面（AssistantMessage.errorCode 携带——桶码族，供 classifyError 在场
+ * 码优先判定）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    // 04 §5 模型标识解析细则：语法层 fail-loud
+    {
+        code: 'LLM_MODEL_SPEC_INVALID',
+        module: 'llm',
+        description: '模型标识语法非法（缺斜杠/空段——必须是 "provider/model-id" 形式，首斜杠分割）',
+    },
+    // 04 §5：目录层 fail-loud（provider 未注册或模型不在目录）
+    {
+        code: 'LLM_MODEL_NOT_FOUND',
+        module: 'llm',
+        description: '模型解析失败：provider 未注册或该 provider 目录中无此模型 id',
+    },
+    // 04 §3.5 transient 桶码（429 限流——errorCode 归一位，provider 钩子纵切前无 provider 写点）
+    {
+        code: 'LLM_RATE_LIMITED',
+        module: 'llm',
+        description: '供应商限流（429）——transient 桶，turn 级 auto-retry 退避后重试',
+    },
+    // 04 §3.6 在飞帽拒绝（宿主合成码——transient 桶）
+    {
+        code: 'LLM_INFLIGHT_LIMIT',
+        module: 'llm',
+        description: 'per-provider 在飞请求达帽（缺省 4）——显式拒绝不排队，退避后槽已释放可重试',
+    },
+    // 04 §3.5 non-retryable 桶码（鉴权败——即 failed 用户面修复）
+    {
+        code: 'LLM_AUTH_INVALID',
+        module: 'llm',
+        description: '鉴权被拒（凭证无效/过期/权限不足）——non-retryable 桶，不重试',
+    },
+    // 04 §3.5 quota 桶码（配额尽——即 failed 换 key/等窗）
+    {
+        code: 'LLM_QUOTA_EXCEEDED',
+        module: 'llm',
+        description: '配额/余额耗尽——quota 桶，重试治不了（换 key 或等窗口）',
+    },
+    // 04 §3.5 overflow 桶码（上下文溢出——3.4 兜底 1/1）
+    {
+        code: 'LLM_CONTEXT_OVERFLOW',
+        module: 'llm',
+        description: '上下文溢出——overflow 桶，compact-and-retry-once 单次压缩重试',
+    },
+    // 04 §5 预算执法码（llm 层自产拒发错——不入四桶，调用方捕获即跳过本轮）
+    {
+        code: 'LLM_BUDGET_EXCEEDED',
+        module: 'llm',
+        description: '当日后台预算耗尽拒发（拒在请求发出前）——下个周期再试，不进 run 终态',
+    },
+    // 04 §3.7：complete 错误终态上抛（Promise 面错误回到异常形态）
+    {
+        code: 'LLM_COMPLETE_FAILED',
+        module: 'llm',
+        description: 'complete 单发补全失败（stopReason=error/aborted 终态或达帽拒绝上抛）',
+    },
+    // 03 §3.4 钩子段禁模型调用执法码（guard 前置查命中——双入口同码：stream 路
+    // errorStream 携带、complete 路 BaseError 抛；词面 02 §5.3 LLM_ 前缀族早已
+    // 在册，码册条目随 ca 批执法接线补齐）。non-retryable：钩子段内重试无意义
+    // ——违例是结构性的，换时刻（派发收口后）再调即合法
+    {
+        code: 'LLM_CALL_IN_HOOK',
+        module: 'llm',
+        description: '钩子派发段内禁模型调用（03 §3.4——起异步任务不等结果合法、await 耦合违法；non-retryable）',
+    },
+]);