berry-agent 0.1.0-alpha.1

package/dist/host/webui-bridge.js

@@ -0,0 +1,165 @@
+/**
+ * host/webui-bridge — `--port` webui 统一 HTTP 面装配桥（批 12f-2c 落、
+ * 18a-3' 三入口咬合归一定形；03 §10.4 host 接线义务：`--port <n>` 开面 +
+ * token 一次性披露 + 生命周期收口）。18a-2' 起件零自持监听——路由经 sdk
+ * HTTP 面承載（mountWebui 注册 face.register——面注册器直注）。
+ *
+ * **三入口两段形（18a-3' 兑现——12f-2c 期「过渡期桥自持面」挂账注销）**：
+ * - mountWebuiOnFace：**共用挂载段**——桥真身映射 + 路由注册进任意 sdk 面 +
+ *   channels backend 挂接（信封扇出与审批腿接线——12f-2c 期注记「addBackend
+ *   归调用方」而调用方缺席 = TUI 形真缺陷〔SSE 死流〕，本段收编修前必红
+ *   例锁死）+ detach 摘挂（幂等——closer 归调用方接线）；
+ * - openWebuiFace：**前台自持面开面**（TUI / serve 前台 `--port` 形）——
+ *   自起统一 HTTP 面 TCP 人面（恒回环；SPA + /api/* + /v1/* 三族同面；
+ *   bridge 走 createServeBridge 零第二套映射）+ 披露两行 + closer 整体
+ *   收口；daemon 常驻面 `--port` 侧不起本面——serve-daemon 件内组态人面
+ *   监听后走共用挂载段（面归 daemon 单源）。
+ *
+ * 批 19e 件在场分档：openWebuiFace 挂载改经 mountKit（core:webui 件
+ * provide 'webui-face-mount' 的 kit——入口装配根 tryGet 后注入）；kit
+ * 缺席 = 件禁用/零装载——面仍开（/v1/* 程序调用族在场）而 /api/* 与
+ * SPA 404，披露分档诚实不虚报（sdk/webui 两件禁用语义族——03 §10.4）。
+ *
+ * 职责（装配桥五面）：conversation 栈五动词 → WebuiDeps 三窄面映射（词面
+ * 独立律的装配侧互证——compat 互证 18a-3' 两方向例锁死，见测试件）+
+ * staticDir 探测（dist/webui 共生形；缺席诚实 API-only 不虚报）+ token
+ * 一次性披露（stderr 缺省——「监听 ⇒ 鉴权」面本体保证恒在场，令牌只此
+ * 一次显示；token 生成归面）+ backend 通道挂接（UiBackend 第四实装 claim
+ * 桥——共用挂载段接线）+ stop 进运行时退出序 closer（注册序在
+ * plugin-unload 之后、tui-backend 之前——网络面先关再出屏）。
+ *
+ * 桥映射注记：createSession 走 manager.create 零 I/O（行随首事件落库——
+ * 浏览器会话无 cwd 锚，workspaceRoot 缺省全局态）；sessionStateOf 三档
+ * 判据 = isOpen 内存册（open）∪ 持久 list（closed）∪ 余（missing）；
+ * submitPrompt 受理门前置（服务端已判 open——isOpen 真则驱动在册，
+ * submitText 必达）；todoOf 无驱动回 undefined（服务端 `items ?? null`
+ * 诚实空）。completion 面 v1 不接（诚实缺席——补全族接线挂账后续批）。
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { foldTodoTable } from '../conversation/index.js';
+import { createSdkHttpFace } from '../sdk/index.js';
+import { WEBUI_DEFAULT_HOST, WEBUI_DEFAULT_PORT, mountWebui } from '../webui/index.js';
+import { createServeBridge } from './serve-entry.js';
+/**
+ * 前台自持面开面（async——监听绑定；TUI / serve 前台 `--port` 形）。
+ * 开面即披露（token 只此一次）+ stop 挂退出序；开面失败（如端口占用
+ * EADDRINUSE）时先摘挂载再抛——不留半挂 backend。
+ */
+export async function openWebuiFace(options) {
+    const face = createSdkHttpFace({
+        config: { tcp: { host: WEBUI_DEFAULT_HOST, port: options.port ?? WEBUI_DEFAULT_PORT } },
+        bridge: createServeBridge(options.stack, options.runtime, { cwd: process.cwd() }),
+        // U5-2 构造期 replay：装载序已受理的插件道路由快照注入 routes 位
+        // （受理与挂载两时点解耦——03 §10.6 时序缝定形）
+        ...(options.pluginRoutes !== undefined ? { routes: options.pluginRoutes.snapshot() } : {}),
+    });
+    // 件在场分档（批 19e）：kit 在场 → 挂载走件 kit（真身 = 共用挂载段）；
+    // 缺席 → 面开而无 webui 路由（/api/* 404——件禁用语义族，诚实披露）
+    const mount = options.mountKit !== undefined
+        ? options.mountKit.mountOnFace(face, options.staticDir !== undefined ? { staticDir: options.staticDir } : undefined)
+        : undefined;
+    let info;
+    try {
+        info = await face.start();
+    }
+    catch (err) {
+        mount?.detach(); // 监听未成——backend 与路由不留半挂
+        throw err;
+    }
+    const { host, port } = info.tcp[0];
+    // U5-2 晚注册路挂接：此后受理（/reload 换代重注册）走 face.register——
+    // 构造期已注入 snapshot，此处不重放（双注册 throw 防线）
+    options.pluginRoutes?.attachFace(face);
+    const stop = async () => {
+        mount?.detach(); // 幂等（backend 摘除 + 全路由摘除 + 全流收口 + 审批清槽丢弃性）
+        options.pluginRoutes?.detachFace(); // 受理账回 pending 态（活面解挂——收口对称）
+        await face.stop(); // 幂等（全流收口 + 关监听）
+    };
+    const disclose = options.disclose ?? ((line) => process.stderr.write(`${line}\n`));
+    if (mount !== undefined) {
+        disclose(`Web 界面已开面：http://${host}:${port}/`);
+    }
+    else {
+        disclose(`HTTP 面已开面（webui 件未装载——Web 界面与 /api/* 缺席，/v1/* 程序调用面仍在场）：http://${host}:${port}/`);
+    }
+    disclose(`访问令牌（仅此一次显示）：${face.token}`);
+    options.onOpen?.({ host, port, token: face.token });
+    options.runtime.registerCloser({ label: 'webui-server', fn: () => stop() });
+    return { webui: mount?.webui, face, deps: mount?.deps, stop };
+}
+/**
+ * 共用挂载段（18a-3' 三入口咬合真源）：桥真身映射 + webui 路由族注册进
+ * 承载面 + channels backend 挂接。TUI/serve 前台经 openWebuiFace 间接受益；
+ * daemon 常驻面直调本段（面归 daemon 单源，零第二套映射）。挂载即活——
+ * 信封扇出（SSE display/session 族）与审批腿（claim 桥）由 backend 挂接
+ * 接线；closer 注册与 token 披露归调用方按入口形各自编排。
+ */
+export function mountWebuiOnFace(options) {
+    const deps = bridgeDeps(options.stack, options.staticDir);
+    // 面注册器直注（WebuiRouteDescriptor → SdkRouteDescriptor 方向性结构兼容）
+    const webui = mountWebui({ ...deps, register: options.face.register });
+    // 通道挂接（UiBackend 第四实装 claim 桥）——12f-2c 期注记「addBackend 归
+    // 调用方」而 TUI 调用方缺席 = SSE 死流真缺陷，本段收编（修前必红例锁死）
+    options.stack.channels.addBackend(webui.backend);
+    let detached = false;
+    return {
+        webui,
+        deps,
+        detach: () => {
+            if (detached)
+                return;
+            detached = true;
+            options.stack.channels.removeBackend(webui.backend.id); // 未注册位 no-op（件内幂等）
+            webui.detach();
+        },
+    };
+}
+/**
+ * 桥真身：conversation 栈五动词 → WebuiDeps 三窄面（词面独立律——本侧
+ * 只做映射不造新词；结构兼容由 face.register 直注与 e2e 双向互证）。
+ */
+function bridgeDeps(stack, staticDirOverride) {
+    return {
+        sessions: {
+            createSession: () => stack.manager.create().sessionId,
+            listSessions: () => stack.manager.list().map((row) => ({
+                id: row.id,
+                title: row.title ?? null, // 无标题会话 null（不造占位串）
+                lastActivityAt: row.updatedAt,
+            })),
+            sessionStateOf: (sessionId) => {
+                if (stack.manager.isOpen(sessionId))
+                    return 'open';
+                // 持久册可见 = 已闭（open 态由内存册先判——零 I/O 承诺下新建未落库行
+                // 也在内存册，不漏判）
+                return stack.manager.list().some((row) => row.id === sessionId) ? 'closed' : 'missing';
+            },
+            submitPrompt: (input) => {
+                void stack.submitText(input.sessionId, input.content); // fire-and-forget——回执经信封回流
+                return { sessionId: input.sessionId };
+            },
+            interruptSession: (sessionId) => stack.interrupt(sessionId), // 未知 id 静默幂等（栈内建）
+        },
+        read: {
+            fetchMessages: (sessionId) => stack.projectionOf(sessionId),
+            // 无驱动（closed 会话）回 undefined——服务端 null 诚实空；fold 空事件得 []
+            todoOf: (sessionId) => {
+                const driver = stack.driverOf(sessionId);
+                return driver === undefined ? undefined : foldTodoTable(driver.session.events());
+            },
+        },
+        // completion 面 v1 不接（可选面缺席合法——服务端诚实回空）
+        ...(staticDirOverride !== undefined ? { staticDir: staticDirOverride } : { staticDir: resolveStaticDir() }),
+    };
+}
+/**
+ * 静态面目录探测：构建共生形 dist/host → dist/webui（SPA index.html 在场
+ * 才启用；缺席 = API-only 形——/ 与未知路径 404，诚实不虚报）。测试态
+ * （tsx 直跑 src）src/webui 无 index.html 自动落 API-only。
+ */
+function resolveStaticDir() {
+    const candidate = join(dirname(fileURLToPath(import.meta.url)), '..', 'webui');
+    return existsSync(join(candidate, 'index.html')) ? candidate : undefined;
+}

package/dist/issue/codes.js

@@ -0,0 +1,38 @@
+/**
+ * issue 域错误码注册（03 §10.7——ISSUE_ 前缀族首批）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1）；码名清
+ * 单与语义真源 = 03 篇 §10.7 入队/触发/交付条 ISSUE_ 四码。本文件由模块公开
+ * 面 index.ts 引入（注册纪律：写入点文件必须实际 import 本文件注册才发
+ * 生——与 llm/session/persist/tools 的 codes.ts 同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'ISSUE_SOURCE_UNREACHABLE',
+        module: 'issue',
+        description: 'issue 源不可达（轮询/webhook 取数网络折——DNS/连接/5xx 等非限额类失败）',
+    },
+    {
+        code: 'ISSUE_SOURCE_RATE_LIMITED',
+        module: 'issue',
+        description: 'issue 源限额（GitHub 403/429——detail 携 retryAfter 秒；轮询下轮自退避，入队不重试风暴）',
+    },
+    {
+        code: 'ISSUE_WEBHOOK_INVALID',
+        module: 'issue',
+        description: 'webhook 请求坏形（签名不符/JSON 坏/载荷非 issue 域形——响亮拒不静默吞）',
+    },
+    {
+        code: 'ISSUE_JOB_DUPLICATE',
+        module: 'issue',
+        description: '同 dedupeKey（repo#issue）在飞互斥撞锁（03 §10.7 入队条——进程内语义，双触发源竞速护栏）',
+    },
+    {
+        // 批 19e 装载批补（03 §10.7 错误码族同笔 + 02 §5.3 随册）——装载期
+        // mount config 坏形响亮拒（行级装载失败 /reload 可修，MCP_CONFIG_INVALID 同律）
+        code: 'ISSUE_CONFIG_INVALID',
+        module: 'issue',
+        description: 'mount config 坏形（repos 缺席/非数组/glob 坏形等 normalizeIssueConfig 拒形——装载期响亮拒行级失败）',
+    },
+]);

package/dist/issue/filter.js

@@ -0,0 +1,146 @@
+import { ISSUE_DEFAULT_SCHEDULE, ISSUE_MAX_DELIVERIES_PER_DAY_DEFAULT, ISSUE_PER_ISSUE_MESSAGES_DEFAULT, } from './types.js';
+/** repo 串词法（精确形 `owner/name`——与 github.ts REPO_RE 同形，此处独立持有：filter 不依赖取数层） */
+const EXACT_REPO_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** schedule 串词法（前缀形粗校验——精校归 scheduler parseSchedule 守卫） */
+const SCHEDULE_PREFIX_RE = /^(every:|daily:|weekly:|once:)/;
+/** glob → 正则：`*` 通配段内任意（不含 `/`——段级通配）；锚定全配 */
+export function repoMatchesGlob(pattern, repo) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+    return new RegExp(`^${escaped}$`).test(repo);
+}
+/**
+ * 归一配置（坏形 {ok:false, message} 响亮拒）。输入来自 mount config——
+ * 用户可配域，一切缺省在此落定（缺省值单源 = types.ts 常量）。
+ */
+export function normalizeIssueConfig(raw) {
+    if (raw === null || typeof raw !== 'object') {
+        return { ok: false, message: `issue 配置须对象形（得 ${typeof raw}）` };
+    }
+    const obj = raw;
+    // repos：必填非空数组；元素 owner/name 精确形或含 * 的 glob 形
+    if (!Array.isArray(obj.repos) || obj.repos.length === 0) {
+        return { ok: false, message: 'issue 配置 repos 须非空数组（监听仓库域）' };
+    }
+    const repos = [];
+    for (const r of obj.repos) {
+        if (typeof r !== 'string' || r === '') {
+            return { ok: false, message: `issue 配置 repos 元素须非空串（得 ${JSON.stringify(r)}）` };
+        }
+        if (r.includes('*')) {
+            // glob 形：`*` 不越段（段级通配）——形如 owner/* 或 */name 或 */* 皆合法
+            const globOk = r.split('/').length === 2 && r.split('/').every((seg) => seg.length > 0);
+            if (!globOk)
+                return { ok: false, message: `issue 配置 repos glob 坏形：${r}（须 owner/name 两段、* 为段级通配）` };
+        }
+        else if (!EXACT_REPO_RE.test(r)) {
+            return { ok: false, message: `issue 配置 repos 元素坏形：${r}（须 owner/name 或含 * 的 glob）` };
+        }
+        repos.push(r);
+    }
+    // labels/assignees：可选数组；元素非空串；空数组 = 该维不约束
+    const normalizeList = (key) => {
+        const v = obj[key];
+        if (v === undefined)
+            return { ok: true };
+        if (!Array.isArray(v))
+            return { ok: false, message: `issue 配置 ${key} 须数组（得 ${typeof v}）` };
+        for (const item of v) {
+            if (typeof item !== 'string' || item === '') {
+                return { ok: false, message: `issue 配置 ${key} 元素须非空串（得 ${JSON.stringify(item)}）` };
+            }
+        }
+        return { ok: true, value: v };
+    };
+    const labels = normalizeList('labels');
+    if (!labels.ok)
+        return labels;
+    const assignees = normalizeList('assignees');
+    if (!assignees.ok)
+        return assignees;
+    // mode：缺省 'draft'（fail-closed 缺省律——全自动显式 opt-in）
+    let mode = 'draft';
+    if (obj.mode !== undefined) {
+        if (obj.mode !== 'draft' && obj.mode !== 'auto') {
+            return { ok: false, message: `issue 配置 mode 须 'draft'|'auto'（得 ${JSON.stringify(obj.mode)}）` };
+        }
+        mode = obj.mode;
+    }
+    // schedule：缺省 every:120s；前缀粗校验（精校归 scheduler 守卫）
+    let schedule = ISSUE_DEFAULT_SCHEDULE;
+    if (obj.schedule !== undefined) {
+        if (typeof obj.schedule !== 'string' || !SCHEDULE_PREFIX_RE.test(obj.schedule)) {
+            return {
+                ok: false,
+                message: `issue 配置 schedule 坏形：${JSON.stringify(obj.schedule)}（every:/daily:/weekly:/once: 前缀四形）`,
+            };
+        }
+        schedule = obj.schedule;
+    }
+    // perIssueBudgetMessages：缺省 400；正整数帽
+    let perIssueBudgetMessages = ISSUE_PER_ISSUE_MESSAGES_DEFAULT;
+    if (obj.perIssueBudgetMessages !== undefined) {
+        const n = obj.perIssueBudgetMessages;
+        if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > 100_000) {
+            return { ok: false, message: `issue 配置 perIssueBudgetMessages 须 1..100000 整数（得 ${JSON.stringify(n)}）` };
+        }
+        perIssueBudgetMessages = n;
+    }
+    // baseBranch：缺省 'main'；非空串
+    let baseBranch = 'main';
+    if (obj.baseBranch !== undefined) {
+        if (typeof obj.baseBranch !== 'string' || obj.baseBranch === '') {
+            return { ok: false, message: `issue 配置 baseBranch 须非空串（得 ${JSON.stringify(obj.baseBranch)}）` };
+        }
+        baseBranch = obj.baseBranch;
+    }
+    // maxDeliveriesPerDay：缺省 10（04 §13 mandate maxPerDay 原料）；正整数律
+    // ——空帽即坏形（0/负数/坏形拒；彻底关停走 HALT 哨兵或撤 consent，不走空帽）
+    let maxDeliveriesPerDay = ISSUE_MAX_DELIVERIES_PER_DAY_DEFAULT;
+    if (obj.maxDeliveriesPerDay !== undefined) {
+        const n = obj.maxDeliveriesPerDay;
+        if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > 100_000) {
+            return {
+                ok: false,
+                message: `issue 配置 maxDeliveriesPerDay 须 1..100000 正整数（得 ${JSON.stringify(n)}）——彻底关停走 HALT 哨兵或撤 consent，不走空帽`,
+            };
+        }
+        maxDeliveriesPerDay = n;
+    }
+    return {
+        ok: true,
+        config: {
+            mode,
+            schedule,
+            repos,
+            labels: labels.value,
+            assignees: assignees.value,
+            perIssueBudgetMessages,
+            baseBranch,
+            maxDeliveriesPerDay,
+        },
+    };
+}
+/**
+ * issue 是否命中过滤（白名单语义：命中任一 repo 即过；labels/assignees 维
+ * 缺席不约束、在场须至少一命中）。closed 一律不匹配（终态 issue 不再入队）。
+ */
+export function issueMatchesFilter(issue, config) {
+    if (issue.state !== 'open')
+        return false;
+    const repoHit = config.repos.some((p) => (p.includes('*') ? repoMatchesGlob(p, issue.repo) : p === issue.repo));
+    if (!repoHit)
+        return false;
+    if (config.labels !== undefined && config.labels.length > 0) {
+        if (!config.labels.some((l) => issue.labels.includes(l)))
+            return false;
+    }
+    if (config.assignees !== undefined && config.assignees.length > 0) {
+        if (!config.assignees.some((a) => issue.assignees.includes(a)))
+            return false;
+    }
+    return true;
+}
+/** 精确 repo 集（轮询面消费——glob 形不入轮询域，调用方计数 globSkipped） */
+export function exactRepos(config) {
+    return config.repos.filter((r) => !r.includes('*'));
+}

package/dist/issue/github.js

@@ -0,0 +1,116 @@
+/**
+ * GitHub 源后端（03 §10.7 触发面——轮询/webhook 两源共用的取数腿）。
+ *
+ * 只走 REST v3（议题/评论面够用——GraphQL 引入零必要）；fetch 注入式
+ * （`fetchImpl` 缺省全局 fetch——测试注假件，零真网络纪律）；分页单页帽
+ * 100、不翻页（轮询 since 增量窗内单页 100 通常覆盖；溢出诚实注记于
+ * PollReport——不静默丢）。PR 混列：GitHub issues API 把 PR 计入 issues 列
+ * 表，`pull_request` 字段在场即过滤。
+ *
+ * 不可信外部文本：title/body/comments 进上下文一律经调用方帽（issue_get 面
+ * ISSUE_CONTEXT_CAP_BYTES）；本层只取数不渲染。
+ */
+import { BaseError } from '../contracts/index.js';
+/** repo 串词法（`owner/name`——防注入：两段、字符域限字母数字连字符下划线点） */
+const REPO_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** repo 串守卫（坏形 = 参数面问题——TOOL_INVALID_ARGS 语义域） */
+export function assertRepoValid(repo) {
+    if (!REPO_RE.test(repo)) {
+        throw new BaseError('TOOL_INVALID_ARGS', `[TOOL_INVALID_ARGS] repo 串坏形：${repo}（须 owner/name 两段、字符域限字母数字与 ._-'）`);
+    }
+}
+/**
+ * 组 GitHub 后端。错误折码：
+ * - 403/429 → ISSUE_SOURCE_RATE_LIMITED（detail 携 retryAfter 秒——
+ *   x-ratelimit-reset 头优先，缺席 60s 缺省）；
+ * - 网络异常/其余非 2xx → ISSUE_SOURCE_UNREACHABLE。
+ */
+export function createGithubBackend(opts) {
+    const apiBase = (opts.apiBase ?? 'https://api.github.com').replace(/\/+$/, '');
+    const doFetch = opts.fetchImpl ?? fetch;
+    /** 单请求（通用头 + JSON 解析；非 2xx/网络错折码上抛；POST 形携 body） */
+    async function requestJson(path, init) {
+        const hasBody = init?.body !== undefined;
+        let response;
+        try {
+            response = await doFetch(`${apiBase}${path}`, {
+                method: init?.method ?? (hasBody ? 'POST' : 'GET'),
+                headers: {
+                    accept: 'application/vnd.github+json',
+                    authorization: `Bearer ${opts.token}`,
+                    'x-github-api-version': '2022-11-28',
+                    ...(hasBody ? { 'content-type': 'application/json' } : {}),
+                },
+                ...(hasBody ? { body: JSON.stringify(init?.body) } : {}),
+            });
+        }
+        catch (err) {
+            // fetch 抛 = 网络层折（DNS/连接/超时）——非 HTTP 状态域
+            throw new BaseError('ISSUE_SOURCE_UNREACHABLE', `[ISSUE_SOURCE_UNREACHABLE] GitHub 不可达（${path}）：${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (response.status === 403 || response.status === 429) {
+            const reset = Number(response.headers.get('x-ratelimit-reset'));
+            // reset 头是 epoch 秒；缺席/坏值回 60s 缺省退避
+            const retryAfter = Number.isFinite(reset) && reset > 0 ? Math.max(1, reset - Math.floor(Date.now() / 1000)) : 60;
+            throw new BaseError('ISSUE_SOURCE_RATE_LIMITED', `[ISSUE_SOURCE_RATE_LIMITED] GitHub 限额（${path}，HTTP ${response.status}）——${retryAfter}s 后退避`);
+        }
+        if (!response.ok) {
+            throw new BaseError('ISSUE_SOURCE_UNREACHABLE', `[ISSUE_SOURCE_UNREACHABLE] GitHub 非预期状态（${path}，HTTP ${response.status}）`);
+        }
+        return (await response.json());
+    }
+    return {
+        async listIssues(req) {
+            assertRepoValid(req.repo);
+            const params = new URLSearchParams({ state: 'open', per_page: '100' });
+            if (req.since !== undefined)
+                params.set('since', req.since);
+            const rows = await requestJson(`/repos/${req.repo}/issues?${params.toString()}`);
+            // PR 混列过滤（pull_request 字段在场即 PR——issues API 语义）
+            return rows
+                .filter((r) => r.pull_request === undefined)
+                .map((r) => ({
+                repo: req.repo,
+                number: r.number,
+                title: r.title ?? '',
+                body: r.body ?? '',
+                labels: (r.labels ?? []).map((l) => l.name ?? '').filter((n) => n !== ''),
+                assignees: (r.assignees ?? []).map((a) => a.login ?? '').filter((n) => n !== ''),
+                state: r.state === 'closed' ? 'closed' : 'open',
+                updatedAt: r.updated_at,
+                htmlUrl: r.html_url,
+            }));
+        },
+        async listComments(req) {
+            assertRepoValid(req.repo);
+            const rows = await requestJson(`/repos/${req.repo}/issues/${req.number}/comments?per_page=100&sort=created&direction=asc`);
+            return rows.map((r) => ({
+                id: r.id,
+                author: r.user?.login ?? '(unknown)',
+                body: r.body ?? '',
+                createdAt: r.created_at,
+            }));
+        },
+        async postComment(req) {
+            assertRepoValid(req.repo);
+            // POST 回执 201——非 2xx 已在 requestJson 折码；body 帽由调用方执（ISSUE_RECEIPT_PATCH_CHARS）
+            const created = await requestJson(`/repos/${req.repo}/issues/${req.number}/comments`, {
+                body: { body: req.body },
+            });
+            return { id: typeof created.id === 'number' ? created.id : 0 };
+        },
+        async createPullRequest(req) {
+            assertRepoValid(req.repo);
+            // POST 开 PR（201/200——非 2xx 已在 requestJson 折码；422「PR 已在/无
+            // 差异」折 ISSUE_SOURCE_UNREACHABLE 族携状态码——与 postComment 同形
+            // 不特判，调用方按错误面分流）
+            const row = await requestJson(`/repos/${req.repo}/pulls`, {
+                body: { title: req.title, body: req.body, head: req.head, base: req.base },
+            });
+            return {
+                number: typeof row.number === 'number' ? row.number : 0,
+                htmlUrl: typeof row.html_url === 'string' ? row.html_url : '',
+            };
+        },
+    };
+}

package/dist/issue/index.js

@@ -0,0 +1,17 @@
+/**
+ * issue 件公开面（03 §10.7——core:issue 无人值守编排件；批 16）。
+ *
+ * 单向 DAG：issue → contracts + context（02 §4.1 #27 席）。兄弟件
+ * （scheduler/subagent/goal/tools/exec/checkpoint/persist）零 import——
+ * 全部经窄面注入（types.ts 词面独立律注）。错误码注册（codes.ts）随本面
+ * 引入生效——与 llm/session/persist/tools 的 codes.ts 同款纪律。
+ */
+import './codes.js';
+export { ISSUE_POLL_JOB_NAME, ISSUE_DEFAULT_SCHEDULE, ISSUE_PARALLEL_LIMIT_DEFAULT, ISSUE_PER_ISSUE_MESSAGES_DEFAULT, ISSUE_RECEIPT_PATCH_CHARS, ISSUE_CONTEXT_CAP_BYTES, ISSUE_WEBHOOK_ENDPOINT, ISSUE_WEBHOOK_BODY_LIMIT_BYTES, ISSUE_GITHUB_TOKEN_NAME, ISSUE_WEBHOOK_SECRET_NAME, ISSUE_MAX_DELIVERIES_PER_DAY_DEFAULT, ISSUE_WORKTREE_NAME_RE, issueDedupeKey, } from './types.js';
+export { createGithubBackend, assertRepoValid } from './github.js';
+export { normalizeIssueConfig, issueMatchesFilter, repoMatchesGlob, exactRepos } from './filter.js';
+export { createIssuePoller, watermarkKey } from './poll.js';
+export { computeSignature, signatureMatches, parseWebhookPayload, handleWebhookRequest } from './webhook.js';
+export { mountIssueWebhook, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER } from './mount.js';
+export { createIssueTools } from './tools.js';
+export { createIssueService } from './service.js';

package/dist/issue/mount.js

@@ -0,0 +1,70 @@
+import { BaseError } from '../contracts/index.js';
+import { ISSUE_WEBHOOK_BODY_LIMIT_BYTES, ISSUE_WEBHOOK_ENDPOINT } from './types.js';
+import { handleWebhookRequest } from './webhook.js';
+/** webhook 事件名头（GitHub 官方词面 X-GitHub-Event——node 头表恒小写读位） */
+export const WEBHOOK_EVENT_HEADER = 'x-github-event';
+/** 验签头（GitHub 官方词面 X-Hub-Signature-256——03 §10.7 批 18a-4' 勘正后单源） */
+export const WEBHOOK_SIGNATURE_HEADER = 'x-hub-signature-256';
+/** JSON 应答速记（webhook 回执/拒收形——面级无共享 sendJson 故件内自持） */
+function sendJson(res, status, payload) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(payload));
+}
+/** 单值头读取（node 头表恒小写；数组形取首——GitHub 恒单值） */
+function headerOf(req, name) {
+    const raw = req.headers[name];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' ? value : '';
+}
+/**
+ * 注册 issue webhook 端点（03 §10.7 ②——路由扩展位第二消费方）。
+ *
+ * 验签与拒收语义件侧执法：receipt 族 200 / `ISSUE_WEBHOOK_INVALID` 400 /
+ * 未预期异常上抛面级 catch 500（GitHub 侧按 5xx 重试）。
+ */
+export function mountIssueWebhook(deps, face, options = {}) {
+    let detacher = face.register({
+        method: 'POST',
+        path: options.path ?? ISSUE_WEBHOOK_ENDPOINT,
+        auth: 'self',
+        // loopbackOnly 不设（有意）——入站投递面须挂非回环监听器
+        bodyLimitBytes: options.bodyLimitBytes ?? ISSUE_WEBHOOK_BODY_LIMIT_BYTES,
+        handler: async (req, res, ctx) => {
+            // 空 secret = 面未开启（空密钥 HMAC 确定性可伪造——禁值守卫先于读体）
+            if (deps.secret === '') {
+                sendJson(res, 400, {
+                    error: 'ISSUE_WEBHOOK_INVALID',
+                    message: '[ISSUE_WEBHOOK_INVALID] webhook 面未开启（缺 secret 配置）',
+                });
+                return;
+            }
+            const body = await ctx.readBody(req);
+            if (!body.ok) {
+                sendJson(res, body.status, { error: 'body_too_large', message: body.message });
+                return;
+            }
+            try {
+                const receipt = await handleWebhookRequest(deps, {
+                    event: headerOf(req, WEBHOOK_EVENT_HEADER),
+                    signatureHeader: headerOf(req, WEBHOOK_SIGNATURE_HEADER),
+                    rawBody: body.body,
+                });
+                sendJson(res, 200, receipt);
+            }
+            catch (err) {
+                // 响亮拒（运维可见）——坏签/坏载荷 400；未预期异常上抛（面级 catch → 500）
+                if (err instanceof BaseError && err.code === 'ISSUE_WEBHOOK_INVALID') {
+                    sendJson(res, 400, { error: err.code, message: err.message });
+                    return;
+                }
+                throw err;
+            }
+        },
+    });
+    return {
+        dispose() {
+            detacher?.();
+            detacher = undefined;
+        },
+    };
+}

package/dist/issue/poll.js

@@ -0,0 +1,58 @@
+import { exactRepos, issueMatchesFilter } from './filter.js';
+/** 水位键（store_state 承载——kind 'issue-poll'） */
+export function watermarkKey(repo) {
+    return `issue:poll:watermark:${repo}`;
+}
+/** 组轮询器（单轮 = pollOnce 一次调用；无自驱时钟——挂钟归 scheduler 行） */
+export function createIssuePoller(deps) {
+    const { backend, state, config } = deps;
+    return {
+        async pollOnce() {
+            const repos = exactRepos(config);
+            const globSkipped = config.repos.length - repos.length;
+            let seen = 0;
+            let candidates = 0;
+            let enqueued = 0;
+            let duplicates = 0;
+            let rejected = 0;
+            const errors = [];
+            for (const repo of repos) {
+                // 水位读取（缺席 = 首轮全量窗；值坏形视同缺席——防御旧数据）
+                const stored = state.getStoreState(watermarkKey(repo));
+                const since = typeof stored?.value === 'string' ? stored.value : undefined;
+                let issues;
+                try {
+                    issues = await backend.listIssues({ repo, since });
+                }
+                catch (err) {
+                    // 单仓失败不炸整轮——记录进报告继续下一仓
+                    errors.push({ repo, message: err instanceof Error ? err.message : String(err) });
+                    continue;
+                }
+                // 水位推进 = 本轮见过的 max(updatedAt)（含被弃的——见 types 头注纪律）
+                let maxUpdated = since ?? '';
+                for (const issue of issues) {
+                    if (issue.updatedAt > maxUpdated)
+                        maxUpdated = issue.updatedAt;
+                }
+                if (issues.length > 0 && maxUpdated !== since) {
+                    state.setStoreState(watermarkKey(repo), maxUpdated, { kind: 'issue-poll' });
+                }
+                seen += issues.length;
+                for (const issue of issues) {
+                    if (!issueMatchesFilter(issue, config))
+                        continue;
+                    candidates += 1;
+                    const result = await deps.enqueue(issue);
+                    if (result.status === 'started')
+                        enqueued += 1;
+                    else if (result.status === 'duplicate')
+                        duplicates += 1;
+                    else
+                        rejected += 1;
+                }
+            }
+            return { repos, seen, candidates, enqueued, duplicates, rejected, globSkipped, errors };
+        },
+    };
+}