berry-agent-sdk 0.1.0-alpha.2

package/dist/src/contracts/api.js

@@ -0,0 +1,334 @@
+/**
+ * L0 contracts — API 治理元数据单源 + 协商层纯函数（03 篇 §8，2026-09-05
+ * API 治理批 2 落码）。
+ *
+ * 本文件 = API 面身份层的机器可读真相源（§8.2 六真相源中的三处）：
+ * - `VIRTUAL_API_KEYS`：虚拟模块键表（键 + tier + since——§8.3 键级 tier 载体；
+ *   loader 注入表、抽取器、check-api 三面共取此单源）
+ * - `SERVICE_CATALOG`：ctx 服务面目录（随各服务面落码批增条——本目录即声明面）
+ * - `CAPABILITIES`：能力面目录（surface.json 顶层 capabilities[] 的声明位，
+ *   §8.5 ctx.host.capabilities 派生源；起算集 = core: 可卸件能力面——批 U2
+ *   首登 v1 高危面两枚并携 `userGrantable` 开门制标注）
+ *
+ * 加协商层纯函数（§8.4 装载门四出口 + 版本比较语义）与 ctx.host 自省面类型
+ * （§8.5——HostFace 插件侧形态 / HostFaceInput 装配侧纯数据输入）。
+ * 全部纯数据/纯函数：零副作用、jiti 可载（工具面 check-api/抽取器直接 import）。
+ *
+ * 分桶纪律（§8.3 internal 行 + §8.4 公开根分桶）：本文件顶层导出分两桶——
+ * 可见桶六名经 contracts/index.ts 显式 re-export 进公开根（插件作者可消费面）；
+ * internal 机制桶八名不进公开根（宿主治理机制非插件 API，内核消费深导
+ * contracts/api.js）。分桶不变式由抽取器 assertApiBucketPartition fail-loud
+ * 执法：新顶层导出未分桶即炸（白名单单点 tools/extract-api-surface.mjs
+ * INTERNAL_API_EXPORTS）。
+ */
+import { BaseError } from './errors.js';
+/** apiVersion 格式：MAJOR.MINOR 两段（API 面无 patch——§8.1） */
+const API_VERSION_FORMAT = /^\d+\.\d+$/;
+/**
+ * 虚拟模块键表——现役五键全 `stable`（§8.3：berry-agent/llm 是已落码正路非预览；
+ * typebox 三键纯转发）。loader 的注入表由本表派生（注入表不另持键单源）；
+ * 实验件未来以新键 + tier 'experimental' 进。
+ *
+ * `berry-agent/sqlite` 键（规范目标态六键之一）**推迟至 persist SqliteFace
+ * 落码批进表**：查 1 要求每键至少一条导出、无真身即红——表收现役真源，
+ * 键进表 = 真身在场（§8.3 批 2 落码注记）。首条 ctx 服务（SERVICE_CATALOG）
+ * 与首个 core: 能力（CAPABILITIES）同律随各自落码批进表。
+ */
+export const VIRTUAL_API_KEYS = [
+    { key: 'berry-agent', tier: 'stable', since: '1.0' },
+    { key: 'typebox', tier: 'stable', since: '1.0' },
+    { key: 'typebox/value', tier: 'stable', since: '1.0' },
+    { key: 'typebox/compile', tier: 'stable', since: '1.0' },
+    { key: 'berry-agent/llm', tier: 'stable', since: '1.0' },
+];
+/**
+ * ctx 服务面目录：首条真实 ctx 具名服务随 c-3 落码批入册（drift 闸守快照，
+ * 目录本身是声明面——声明即 API）。抽取器 services 块循环本表，接口切片
+ * 机制已就位、每条目落码即活。
+ */
+export const SERVICE_CATALOG = [
+    {
+        name: 'secrets',
+        module: 'credentials',
+        faceInterface: 'SecretsService',
+        note: '插件凭证受理制读写面（ctx.get("secrets") 消费——get 缺省自域、越域读走高危面开门 credentials.read-cross；set 恒自域且只在宿主回调窗内可达）',
+        tier: 'stable',
+    },
+    {
+        name: 'compaction',
+        module: 'compaction',
+        faceInterface: 'CompactionPluginFace',
+        note: '压缩策略面（ctx.get("compaction") 消费——setConfig 数值槽/registerSummarizer 摘要 provider 槽两动词装载窗 only 严于通律、单席位先到占；provider 只作用阈值路，溢出兜底恒宿主缺省算法）',
+        tier: 'stable',
+    },
+    {
+        name: 'sdk-routes',
+        module: 'sdk',
+        faceInterface: 'SdkRoutesPluginFace',
+        note: '路由受理面（ctx.get("sdk-routes") 消费——register 受理制注册 sdk HTTP 面插件道路由：前缀 /plugins/<id>/ 恒受理面施加 + 收窄四件〔鉴权子集/loopbackOnly 恒 true/体帽 1MiB 缺席即帽值/数帽 16〕+ 门检 sdk.register-route 前置 + 装载窗 only；裁决纯函数 sdk/plugin-routes.ts）',
+        tier: 'stable',
+    },
+    {
+        // fork 绑定真源 = plugin-boot 装载序 fork.provide(JOBS_SERVICE_NAME,
+        // options.jobs.bindForPlugin(pluginId))——绑定面委托共享根真身，改
+        // 归属注入两改写位（registerKind kind 归属 + register owner 闭包
+        // 固化——六役 CL-C ②）；方法面 = subagent/registry.ts JobRegistry
+        // 契约接口（七动词）
+        name: 'jobs',
+        module: 'subagent',
+        faceInterface: 'JobRegistry',
+        note: 'Job 注册表面（ctx.get("jobs") 消费——fork 绑定面委托共享根真身：registerKind 登记种类（fork 绑定携本插件 id 入 kind 归属记录——starter 谱系闸判籍面）、register 注册在飞 Job 得句柄、hasKind/running/list/get 只读对账、closeOwner 按 owner 围栏收口在飞；未登记 kind 拒 JOB_KIND_UNKNOWN）',
+        tier: 'stable',
+    },
+    {
+        // fork 绑定真源 = plugin-boot fork.provide('sessions',
+        // bindSessionsForPlugin(...))——归因闸 caller 宿主闭包铸造 + 行籍闸
+        // 两拍执法；方法面 = host/sessions-face.ts SessionsFace 契约接口
+        // （appendEventFor 单动词）
+        name: 'sessions',
+        module: 'host',
+        faceInterface: 'SessionsFace',
+        note: '会话事件受理面（ctx.get("sessions") 消费——appendEventFor 单动词按会话取 appendEvent 活引用：核心事件词/未注册词汇二道闸拒写、surfaceOp 信封改道 appendWithSurfaceOp 正门、无活体驱动返 undefined 诚实降级；插件道恒经绑定面——归因键 source: plugin:<id> 由宿主闭包铸造（传入面无 caller 位防冒名），行不在活装载代即残句柄拒写）',
+        tier: 'stable',
+    },
+    {
+        // fork 绑定真源 = plugin-boot fork.provide(SESSIONS_CONTROL_SERVICE,
+        // bindControlForPlugin(...))——caller 归因闭包铸造防冒名；方法面 =
+        // conversation/control.ts PluginControlFace 契约接口（send/interrupt/
+        // withdraw 三动词窄形——无 caller 位）
+        name: 'sessions-control',
+        module: 'conversation',
+        faceInterface: 'PluginControlFace',
+        note: '会话操控面（ctx.get("sessions-control") 消费——send/interrupt/withdraw 三动词窄形；caller 归因 {kind:"plugin", pluginId} 由宿主闭包铸造（传入面无 caller 位，传入即被覆写——伪造结构性不存在）；withdraw 目标未排队恒报 delivered 不虚构撤回成功；面缺席 = ctx.get 响亮 CONTEXT_SERVICE_MISSING 诚实缺席律）',
+        tier: 'stable',
+    },
+];
+/**
+ * 能力面目录：core: 可卸件能力起算集（§8.5——ctx.host.capabilities 读此层）。
+ * 语义 = **本构建面**（编译进包即有——启用清单是否挂载属运行时态，两问不混）。
+ * 批 U2 首登 v1 首批高危面两枚（§4.6——`userGrantable` 开门制标注单源）：
+ * - `channels.ui-backend`：替换界面后端（UiBackend 实装换装——02 §2 表 #6
+ *   重述所指高权面；承载方 = channels 宿主固定件〔自研 TUI 引擎席位〕）；
+ * - `sdk.register-route`：注册网页路由（sdk HTTP 面路由扩展位——03 §10.6；
+ *   承载方 = core:sdk 件）。
+ * 触发器面 C 批补第三枚（2026-09-07——P1 拍板批 v1 名单两枚→三枚的落码兑现）：
+ * - `triggers.start-run`：触发器起会（非人触发起无头会话——03 §2.2
+ *   ctx.triggers.register；承载方 = host 装配根〔注册表/starter 编舞住
+ *   host 侧触发器件，零新席——03 §8.2 providedBy 第三形〕）。
+ * 凭证代管件 c-1 规范先行批入册第四枚（2026-09-08——§4.6 v1 首批名单
+ * 三枚→四枚；c-3 读腿落码批代码侧兑现）：
+ * - `credentials.read-cross`：跨域读凭证（ctx.secrets.get 越自域
+ *   namespace 读——03 §2.2 第十面/§10.9 读腿；承载方 = core:credentials
+ *   件〔judged 面——默认关、开门后逐次 capability/used 审计〕）。
+ * 环境感知件 e-2 观测腿批入册第五枚（2026-09-08——§4.6 v1 首批名单
+ * 四枚→五枚；立题档题 6 拍板「动词族一枚高危面统摄」——拉取与订阅两
+ * 形态一枚统摄）：
+ * - `sessions.observe-cross`：跨树观测（obs 会话维工具族跨树目标读/
+ *   全会话维枚举——03 §10.8 可见性分轴观测轴；树内 self/tree 两档零
+ *   开门。承载方 = host 装配根〔per-session 工具族闭包装配位 +
+ *   订阅作用域执法住宿主侧——03 §8.2 providedBy 第三形同 triggers.
+ *   start-run；obs 件提供 SessionView 纯派生读面非承载方〕）。
+ * 后续高危面经三路准入扩枚举同律入册（§4.6）；构建差能力随真实构建分叉日
+ * 启用 `API_CAPABILITY_MISSING`（预留码，本批无 thrower）。
+ */
+export const CAPABILITIES = [
+    {
+        name: 'channels.ui-backend',
+        providedBy: 'channels',
+        userGrantable: true,
+    },
+    {
+        name: 'sdk.register-route',
+        providedBy: 'core:sdk',
+        userGrantable: true,
+    },
+    {
+        name: 'triggers.start-run',
+        providedBy: 'host',
+        userGrantable: true,
+    },
+    {
+        name: 'credentials.read-cross',
+        providedBy: 'core:credentials',
+        userGrantable: true,
+    },
+    {
+        name: 'sessions.observe-cross',
+        providedBy: 'host',
+        userGrantable: true,
+    },
+    {
+        // 操控轴高危面（03 §4.6 v1 首批第六枚——e-4 落码批入册）：跨会话
+        // send/interrupt/withdraw 全域同门无树内豁免（03 §2.2 第十一面门制句）
+        name: 'sessions.control-cross',
+        providedBy: 'host',
+        userGrantable: true,
+    },
+];
+/**
+ * 高危面开门名单单源（§4.6 登记单源的派生面）：CAPABILITIES 中 `userGrantable`
+ * 标注位的能力名清单。启用清单 `opens` 授予位的**值域即此名单**（行校验拒绝
+ * 式消费——host/manifest）；门检裁决（adjudicateCapabilityDoor）同源判「是否
+ * 高危面」。派生不另持单源——目录增删高危面，本面与校验/门检三面共变。
+ */
+export const USER_GRANTABLE_CAPABILITIES = CAPABILITIES.filter((c) => c.userGrantable === true).map((c) => c.name);
+/**
+ * 启用清单顶层 `doors:` 段值域 v1 单源（开门制扩展批 2026-09-09——03 §4.6
+ * 双源并集律第二源的值域面）：观测/操控两门枚举。**射程即值域**——六枚全宽
+ * 将致「清单呈现开、门检实效关」的三读分叉与审计说谎背离（冷读闸 major #1
+ * 收窄）；USER_GRANTABLE_CAPABILITIES 名单系其上界，扩枚随后续模型道高危面
+ * 立题放宽。行校验拒绝式消费（host/manifest——段坏形/值域外 fail-loud 拒）。
+ */
+export const DOORS_SEGMENT_V1_DOMAIN = ['sessions.observe-cross', 'sessions.control-cross'];
+/**
+ * 高危面门检裁决（§4.6——用户主权开门制的执法判定核；纯函数零副作用）。
+ *
+ * 判定两序：①能力名 ∈ USER_GRANTABLE_CAPABILITIES（不是高危面即 not-a-door
+ * ——常规能力位不走开门制，宿主侧把非门面接进门检系装配缺陷）；②该插件的
+ * 开门授予集是否含此名（缺席 = 默认关 door-closed）。开门授予集 = 启用清单
+ * 行 `opens` 位（读侧行校验已保证值域合法——本函数对集外值不再复验，信任
+ * 前置校验）。**调用方 = 宿主注入位**（界面后端换装缝/路由受理面随批 U3/U5
+ * 落地接线）；插件代码结构性不可达本函数（开门是宿主裁决面非插件 API）。
+ */
+export function adjudicateCapabilityDoor(opened, capability) {
+    if (!USER_GRANTABLE_CAPABILITIES.includes(capability)) {
+        return {
+            ok: false,
+            kind: 'not-a-door',
+            message: `能力位 ${capability} 不在高危面名单（现役：${USER_GRANTABLE_CAPABILITIES.join('、')}）——常规能力位不走开门制，宿主注入位接错面或能力名拼错`,
+        };
+    }
+    if (!opened.has(capability)) {
+        return {
+            ok: false,
+            kind: 'door-closed',
+            message: `高危面 ${capability} 默认关（用户主权开门制 03 §4.6）——本插件未获开门授予；开法：启用清单 enabled.yaml 该插件行加 opens: ["${capability}"] 后重装载，撤位即收回`,
+        };
+    }
+    return { ok: true };
+}
+/* ---------------- 版本比较与装载门（§8.4） ---------------- */
+/**
+ * apiVersion 比较（§8.4 版本比较语义）：MAJOR.MINOR 逐段数值比较——禁字符串
+ * 比较（"1.10" > "1.9"）。格式非法抛 API_VERSION_MALFORMED（调用方 = 清单
+ * 校验后的执法面，正常路径格式已验）。
+ * @returns 负数 = a < b；0 = 相等；正数 = a > b
+ */
+export function compareApiVersions(a, b) {
+    const pa = parseApiVersion(a);
+    const pb = parseApiVersion(b);
+    return pa[0] !== pb[0] ? pa[0] - pb[0] : pa[1] - pb[1];
+}
+/**
+ * API 族错误消息公共指路尾注（公开锚——运行时字符串不指路知识域）。
+ *
+ * 指路目标 = 仓库公开文档面（COMPATIBILITY.md 与 docs/API参考.md——批 4
+ * 收剑点火件落地后在场；本批先占位词面，两件生成后即真）。第三方插件作者
+ * 顺错误消息可达；知识域篇名/章节号（gitignored）禁入运行时字符串。
+ * 本模块三条拒载消息统一缀此尾注：拒载消息自带「下一步去哪读」。
+ * 模块私有（不入公开桶——INTERNAL_API_EXPORTS 白名单无需扩）。
+ */
+const API_DOC_ANCHOR_NOTE = 'API 治理语义见仓库 COMPATIBILITY.md 与 docs/API参考.md。';
+/** 解析 apiVersion 为 [MAJOR, MINOR] 数值对；格式非法即抛（单点执法） */
+function parseApiVersion(v) {
+    if (!API_VERSION_FORMAT.test(v)) {
+        throw new BaseError('API_VERSION_MALFORMED', `apiVersion 格式非法：${v}（应为 MAJOR.MINOR，如 "1.0"）${API_DOC_ANCHOR_NOTE}`);
+    }
+    const [major, minor] = v.split('.');
+    return [Number(major), Number(minor)];
+}
+/**
+ * 断言 apiVersion 格式合法（清单校验面用——错误归 PLUGIN_INVALID 语境由调用方
+ * 包，本函数只做纯格式判定的复用体）。
+ */
+export function isValidApiVersion(v) {
+    return API_VERSION_FORMAT.test(v);
+}
+/**
+ * API 兼容执法收剑点火位（§8.4「批 4 翻必填」+ §8.10 批表——机器在窗口内、
+ * 兼容执法单点收剑）。
+ *
+ * - `false`（现役）= pre-release 窗口容忍态：api 块缺席走 legacy 出口聚合 warn；
+ * - `true`（首个 dist-tag=latest 当笔翻转）= 点火：api 块缺席从 warn 变拒载
+ *   （`API_VERSION_MISMATCH`），min fail-loud 对全体插件生效。
+ *
+ * **散拷禁令**（§8.4）：常量消费面恰两处——adjudicateApiGate 出口 4（行为面：
+ * 缺块 warn/拒载）与抽取器 enforcement 纪元章（tools/extract-api-surface.mjs
+ * ——只读单源盖章进面快照，不改不散播，§8.10 点火可见性）；测试经纯函数
+ * `ignited` 参数注入两态，不改常量。点火日翻转 = 改此单点 + 同笔测试 + 快照
+ * 再生成（enforcement 纪元章随翻转变色——查 1 自然拦）。
+ */
+export const API_ENFORCEMENT_IGNITED = false;
+/**
+ * 装载门序（§8.4 四出口全定义）。纯函数：清单 api 块 × 宿主 apiVersion → 裁决。
+ * 全入口同律——凡构造装载计划的进路必经同一根公式（装机腿 / boot 合成腿 /
+ * 试件腿 / 收割腿 / core: 装载）。出口：
+ * 1. 宿主 < min → 抛 `API_VERSION_MISMATCH`（拒载——message 载 expected/actual/
+ *    升级指引三段）；
+ * 2. min ≤ 宿主 < target → 钳制不警示（生效 target = min(宿主, target)）；
+ * 3. 宿主 > target → 正常兼容态不警示（editions 设计目的）；
+ * 4. api 块缺席 → 点火前 status 'legacy'（调用方聚合 per-boot warn）；点火后
+ *    （`API_ENFORCEMENT_IGNITED` 翻 true）抛 `API_VERSION_MISMATCH` 拒载——
+ *    「批 4 翻必填」的唯一机器翻转点。
+ * 格式/不变式（min ≤ target）由清单校验先执法——本函数防御式复验格式，
+ * 不变式信任前置校验。
+ *
+ * @param ignited 点火位注入（缺省 = `API_ENFORCEMENT_IGNITED` 常量单源——测试
+ *   两态注入专用参数，产码调用点不传）。
+ */
+export function adjudicateApiGate(api, hostApiVersion, pluginId, ignited = API_ENFORCEMENT_IGNITED) {
+    // 出口 4：api 块缺席——点火前 legacy 容忍态（面/行为按宿主当前——不进任何兼容
+    // 模式）；点火后拒载（min fail-loud 全体生效的机器形态）
+    if (api === undefined) {
+        if (ignited) {
+            throw new BaseError('API_VERSION_MISMATCH', `插件 ${pluginId} 清单（package.json）缺 api 块——兼容执法已点火（api 块必填），` +
+                `须在 package.json 的 berryAgent 块补 "api": { "minApiVersion": "<宿主当前 apiVersion 或更旧>" }` +
+                `（批 4 翻必填——min fail-loud 与兼容模式对全体插件生效）。${API_DOC_ANCHOR_NOTE}`);
+        }
+        return { status: 'legacy', effectiveTarget: hostApiVersion, experimentalKeys: new Set() };
+    }
+    const min = api.minApiVersion;
+    const target = api.targetApiVersion ?? min; // 粘性锚：缺省 = min 的值
+    parseApiVersion(min); // 防御式格式复验（前置校验已红过一次）
+    parseApiVersion(hostApiVersion);
+    // 出口 1：硬地板拒载（fail-loud 三段消息）
+    if (compareApiVersions(hostApiVersion, min) < 0) {
+        throw new BaseError('API_VERSION_MISMATCH', `插件 ${pluginId} 声明 minApiVersion ${min}，宿主 API 面版本 ${hostApiVersion} 低于地板——拒载。` +
+            `升级指引：升级 berry-agent 宿主包（npm i -g berry-agent@latest）或联系插件作者放宽 minApiVersion。${API_DOC_ANCHOR_NOTE}`);
+    }
+    // 出口 2/3：钳制与兼容统称 admit——生效 target = min(宿主, target)（钳制出口
+    // 的值在兼容出口自然等于 target，两出口同式不分支——「钳制不警示」的机器形态）
+    const effectiveTarget = compareApiVersions(hostApiVersion, target) < 0 ? hostApiVersion : target;
+    return { status: 'admit', effectiveTarget, experimentalKeys: new Set(api.experimental ?? []) };
+}
+/**
+ * experimental import 门禁（§8.4 执法点——与说明符白名单门禁同执法位的纯裁决核）：
+ * import 实验键而清单未声明 → 抛 `API_EXPERIMENTAL_UNDECLARED`。契约即知情：
+ * 能用可破面 = 你签了字。键表之外的说明符不属本门禁（白名单三道另辖）。
+ */
+export function assertExperimentalDeclared(specifier, declared, pluginId) {
+    const entry = VIRTUAL_API_KEYS.find((k) => k.key === specifier);
+    if (entry === undefined || entry.tier !== 'experimental')
+        return;
+    if (declared.has(specifier))
+        return;
+    throw new BaseError('API_EXPERIMENTAL_UNDECLARED', `import 实验键 ${specifier} 未在清单声明——插件 ${pluginId ?? '(未知插件)'} 须在 package.json ` +
+        `的 berryAgent 块 api 段 experimental 数组显式点名该键方能启用（契约即知情：实验键任意 minor 可破可删）${API_DOC_ANCHOR_NOTE}`);
+}
+/** 由纯数据输入物化 HostFace（装配根唯一构造点——ctx.host 只读面由此而来） */
+export function materializeHostFace(data) {
+    const capabilitySet = new Set(data.capabilities);
+    const experimentalSet = new Set(data.experimentalKeys);
+    return {
+        version: data.version,
+        apiVersion: data.apiVersion,
+        capabilities: {
+            has: (name) => capabilitySet.has(name),
+            list: () => [...capabilitySet],
+        },
+        experimental: {
+            enabled: (name) => experimentalSet.has(name),
+        },
+    };
+}
+//# sourceMappingURL=api.js.map

package/dist/src/contracts/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../../src/contracts/api.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/approval.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 审批 ask 跨模块词汇（07 §4.3 提问队列条款 + 04 §9 审批链的呈现载荷）。
+ *
+ * 属地裁决（批 11b 契约先行）：原住 channels/types.ts（批 10e-2 通道核
+ * askApproval 面定稿时落）——conversation 件（fresh 作用域审批三件）消费
+ * 同形而依 02 §4.1 边表不可达 channels，闭集词汇归位 contracts 单源；
+ * channels 侧改 import + re-export，公开面零变化。
+ */
+/**
+ * 审批 ask 应答闭集（07 §4.3 提问队列条款——审批入队契约）：approve/reject/
+ * cancel/always/unavailable。收口语义两分立（对齐 04 §9 run 信号透传 ask 链）：
+ * 会话关闭 / run 打断收口 → `'cancel'`（用户主动终止语境）；降级到底（全部
+ * 后端无 approval capability——headless 单发形态的结构态）→ `'unavailable'`
+ * （呈现面结构性无人可答——ApprovalService 侧落 outcome unavailable +
+ * source timeout，04 §9 无应答者语义；2026-09-13 真模型实测批增，修前误答
+ * `'cancel'` 致 decided 错标 cancel/user 双失真）；`always` + 草案的策略表
+ * 回写经装配注入回调（onApprovalAlways）。
+ */
+export type ApprovalAskAnswer = 'approve' | 'reject' | 'cancel' | 'always' | 'unavailable';
+/**
+ * 审批 ask 呈现载荷（07 §4.3——通道侧形）：channels 与 safety 边表互无边
+ * （02 §4.1），safety 侧 ApprovalRequest 经装配根映射注入本形；`suggestedEntry`
+ * = 「始终允许」草案条目（04 §9 ③ 策略表 allow 条目回写目标；无草案 = always 选项
+ * 语义上不呈现、防御收口视同 approve）。
+ */
+export interface ApprovalAskRequest {
+    /** 目标动作摘要（人可读一行——面板标题） */
+    readonly summary: string;
+    /** 请求方/理由（有则呈现说明段） */
+    readonly reason?: string;
+    /** 发起审批的工具名（有则呈现） */
+    readonly toolName?: string;
+    /** 挂起身份短形（多驱动单输入框下防串答） */
+    readonly approvalId?: string;
+    /** 「始终允许」草案条目（策略表 allow 条目回写目标；缺席 = always 防御收口视同 approve） */
+    readonly suggestedEntry?: string;
+}

package/dist/src/contracts/approval.js

@@ -0,0 +1,10 @@
+/**
+ * 审批 ask 跨模块词汇（07 §4.3 提问队列条款 + 04 §9 审批链的呈现载荷）。
+ *
+ * 属地裁决（批 11b 契约先行）：原住 channels/types.ts（批 10e-2 通道核
+ * askApproval 面定稿时落）——conversation 件（fresh 作用域审批三件）消费
+ * 同形而依 02 §4.1 边表不可达 channels，闭集词汇归位 contracts 单源；
+ * channels 侧改 import + re-export，公开面零变化。
+ */
+export {};
+//# sourceMappingURL=approval.js.map

package/dist/src/contracts/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../../../../src/contracts/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/src/contracts/env-ref.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 凭证 env 引用形（03 §10.9 注入腿——c-4 落码批）。
+ *
+ * 词面：`@credentials:<name>`（值位整串精确匹配——sigil 前缀 + 凭证名）。
+ * 用户在 MCP/LSP server config 的 env 声明里以引用形代替明文：
+ * `{ "GITHUB_TOKEN": "@credentials:github-token" }`——配置与 durable 面恒
+ * 只见引用形原文，明文值只在 spawn 时刻经宿主展开进子进程环境（exec
+ * buildChildEnv 单点——模型面/插件码面/工具结果结构性不见值）。
+ *
+ * 本文件是词面**单源**（跨模块契约词汇：exec 执法消费 + credentials
+ * resolver 消费 + 用户 config 书写三方法源）：放 contracts 使两消费方均
+ * 零新 DAG 边（exec 与 credentials 均既有 contracts 边）。纯数据/纯函数、
+ * jiti 可载——与 api.ts 同族纪律。
+ *
+ * v1 无转义形：以 `@credentials:` 起头的 env 值一律视为引用形（该形在
+ * env 值位无正当字面用途——逃生口挂账不需要）。
+ */
+/** 引用形 sigil 前缀（含冒号——`@credentials:`；名 = 前缀后的非空余段） */
+export declare const CREDENTIALS_ENV_REF_PREFIX = "@credentials:";
+/** 引用形解析结果（三态：非引用形 / 引用形携名 / 前缀命中而坏形） */
+export type CredentialEnvRef = 
+/** 非引用形——字面值原样放行 */
+{
+    readonly kind: 'none';
+}
+/** 引用形——name 为凭证作用名（host 域 provider 名） */
+ | {
+    readonly kind: 'ref';
+    readonly name: string;
+}
+/** 坏形——前缀命中而名空（意图明确是引用形，fail-loud 拒字面注入） */
+ | {
+    readonly kind: 'invalid';
+};
+/**
+ * 解析 env 值是否为凭证引用形。
+ * @param value env 声明值（set 面单值）
+ * @returns 三态解析结果——'none' 字面放行 / 'ref' 交宿主展开 / 'invalid'
+ *          前缀命中而名空（调用方以 CREDENTIALS_ENV_REF_INVALID 响亮拒）
+ */
+export declare function parseCredentialEnvRef(value: string): CredentialEnvRef;

package/dist/src/contracts/env-ref.js

@@ -0,0 +1,33 @@
+/**
+ * 凭证 env 引用形（03 §10.9 注入腿——c-4 落码批）。
+ *
+ * 词面：`@credentials:<name>`（值位整串精确匹配——sigil 前缀 + 凭证名）。
+ * 用户在 MCP/LSP server config 的 env 声明里以引用形代替明文：
+ * `{ "GITHUB_TOKEN": "@credentials:github-token" }`——配置与 durable 面恒
+ * 只见引用形原文，明文值只在 spawn 时刻经宿主展开进子进程环境（exec
+ * buildChildEnv 单点——模型面/插件码面/工具结果结构性不见值）。
+ *
+ * 本文件是词面**单源**（跨模块契约词汇：exec 执法消费 + credentials
+ * resolver 消费 + 用户 config 书写三方法源）：放 contracts 使两消费方均
+ * 零新 DAG 边（exec 与 credentials 均既有 contracts 边）。纯数据/纯函数、
+ * jiti 可载——与 api.ts 同族纪律。
+ *
+ * v1 无转义形：以 `@credentials:` 起头的 env 值一律视为引用形（该形在
+ * env 值位无正当字面用途——逃生口挂账不需要）。
+ */
+/** 引用形 sigil 前缀（含冒号——`@credentials:`；名 = 前缀后的非空余段） */
+export const CREDENTIALS_ENV_REF_PREFIX = '@credentials:';
+/**
+ * 解析 env 值是否为凭证引用形。
+ * @param value env 声明值（set 面单值）
+ * @returns 三态解析结果——'none' 字面放行 / 'ref' 交宿主展开 / 'invalid'
+ *          前缀命中而名空（调用方以 CREDENTIALS_ENV_REF_INVALID 响亮拒）
+ */
+export function parseCredentialEnvRef(value) {
+    if (!value.startsWith(CREDENTIALS_ENV_REF_PREFIX)) {
+        return { kind: 'none' };
+    }
+    const name = value.slice(CREDENTIALS_ENV_REF_PREFIX.length);
+    return name === '' ? { kind: 'invalid' } : { kind: 'ref', name };
+}
+//# sourceMappingURL=env-ref.js.map

package/dist/src/contracts/env-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-ref.js","sourceRoot":"","sources":["../../../../../src/contracts/env-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,sDAAsD;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAAG,eAAe,CAAC;AAW1D;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC;IAC5D,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACnE,CAAC"}

package/dist/src/contracts/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 错误码注册表与单一错误基类（02 篇 §5.3 错误码族规范；07 篇 §8 表 #9 定名）。
+ *
+ * 四条族规范（02 §5.3）：
+ *  1. 形态：字符串错误码（SCREAMING_SNAKE + 模块前缀族），不搞兼容、定死一条路线；
+ *  2. 注册目录：错误码与事件类型同一纪律——contracts 显式注册、运行时可枚举、
+ *     CI 校验抛出/写入点一致；插件扩展错误码同样显式注册，禁止字符串字面量散落；
+ *  3. 进程内载体：全仓单基类 BaseError（Error 子类，{ code, message, cause? }）——
+ *     类不是词汇、码才是身份；禁止每码一类，catch 一律按 code 分派；
+ *  4. durable 事件内一律写码：错误信息 = code + 人读 message（日志自描述）。
+ */
+/**
+ * 全仓单一错误基类（07 篇 §8 表 #9 定名，2026-09-05 冷读闸补定）。
+ *
+ * 用法约定：catch 一律按 `err instanceof BaseError && err.code === 'XXX'` 分派
+ * （或直接读 code 字段判别——码才是身份，类只作载体）；禁止为单个错误码派生子类。
+ */
+export declare class BaseError extends Error {
+    /** 错误码身份（SCREAMING_SNAKE + 模块前缀，注册表成员） */
+    readonly code: string;
+    /**
+     * @param code 错误码（须已在注册表——本构造器不拦截，注册纪律由写入点与 CI 执法）
+     * @param message 人读错误信息（与 code 一道进 durable 事件的错误腿）
+     * @param options.cause 底层异常（可选；Error 原生 cause 语义）
+     */
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 错误码目录条目（可枚举目录 = 注册表值形态） */
+export interface ErrorCodeInfo {
+    /** 错误码（SCREAMING_SNAKE + 模块前缀） */
+    code: string;
+    /** 归属模块（宿主件名或插件 id）——CI 对账「抛出/写入点一致」的依据 */
+    module: string;
+    /** 中文语义描述（生成目录用） */
+    description: string;
+}
+/**
+ * 错误码前缀族明列（02 篇 §5.3 #1）——文档性常量，供注册面校验与 CI 目录生成；
+ * 'HOST_' 系装配根码族（单活跃机 HOST_DATA_DIR_BUSY 等，07 篇 §1 定名位）。
+ */
+export declare const ERROR_CODE_PREFIXES: readonly ["TOOL_", "FS_", "SESSION_", "SANDBOX_", "LLM_", "EXEC_", "PROVIDER_", "APPROVAL_", "CHANNEL_", "WEB_", "CONTEXT_", "SKILLS_", "PLUGIN_", "HOST_", "PERSIST_", "API_", "AGENT_", "SDK_", "SCHEDULER_", "GOAL_", "SUBAGENT_", "JOB_", "TRIGGER_", "CREDENTIALS_", "DANGER_", "UI_"];
+/**
+ * 注册错误码（宿主件落码批与插件装载面的统一入口）。
+ *
+ * 同码重复注册即抛（fail-loud——防两模块抢码/插件伪造宿主码；冲突属装配期
+ * 执法，归 host 码族 HOST_ERROR_CODE_CONFLICT）。
+ */
+export declare function registerErrorCodes(infos: readonly ErrorCodeInfo[]): void;
+/** 判别错误码是否已注册（catch 面 code 分派前的目录查询） */
+export declare function isKnownErrorCode(code: string): boolean;
+/** 错误码目录条目查询（未注册返回 undefined） */
+export declare function getErrorCodeInfo(code: string): ErrorCodeInfo | undefined;
+/** 全量目录枚举（生成目录 / CI 校验用） */
+export declare function listErrorCodes(): ErrorCodeInfo[];