berry-agent 0.1.0-alpha.1

package/dist/contracts/events.js

@@ -0,0 +1,329 @@
+import { BaseError } from './errors.js';
+/** 事件类别四分法闭集（类别列口径与 05 §3.1 投影执法对齐） */
+export const EVENT_CATEGORIES = ['surface', 'snapshot', 'log-only', 'structure'];
+/**
+ * 核心事件类型 32 词（05 §1.1 表格逐条转录；owner 归属按表注：
+ * gate/decision 归 tools、llm/usage 归 llm、llm/retry 注册走 session
+ * 核心词汇（llm 模块不知道驱动存在）、plugin/uninstalled 宿主写点 host、
+ * approval/* 与 sandbox/mode 归 safety 域、todo/write 与
+ * session/thinking-level 归 conversation〔05 行 66：写入者 = conversation
+ * 件档位切换面——agent 件零存储感知、不写本词〕）。
+ * tier 全 stable（核心词汇 = 已收口契约面，03 §8.3 零隐式载体）。
+ * 核心词计数 16→19：compaction/start|surface|end 随 compaction 纵切批入表；
+ * 19→20：session/thinking-level 随遗漏审计批回填（05 §1.1 行 66 agent 纵切
+ * 批已定名，注册表漏登——批 11 conversation 写入将撞词汇闸，先回填止血）；
+ * 20→22：plugin/opens·capability/used 随 U3 落码批入册（05 §1.1 行 70-71
+ * 开门制两审计词——载体 = 进程级 audit_events 审计流〔05 §9〕非会话流，
+ * 入册值 = 核心词身份双闸 + 目录单一真源；写入面随 U3-2 persist 笔落码）；
+ * 22→23：compaction/fallback 随 U4 落码批入册（05 §1.1 行 77 回落三律第 3
+ * 律审计词——2026-09-07 双轴二轮评估批已定词形、随 U4 落码批注册兑现）；
+ * 23→28：plugin/installed·mounted·unmounted·toggled·updated 随生命周期
+ * 五词 audit 落账批入册（05 §1.1 生命周期归因面行——uninstall 词已随装机
+ * 面落码批先行落 audit_events 载体〔CLI 人面无会话场景唯一可达 durable
+ * 载体〕，本五词与之同载体并列成族——六词同面；词形单源本表：
+ * installed {id,source,version} / mounted·unmounted {id} /
+ * toggled {id,disabled 双态} / updated {id,from?,to}）；
+ * 28→29：doors/updated 随开门制扩展批入册（05 §1.1 行 72——进程级开门位
+ * 授予面切换事实：doors 段〔模型道高危面授予载体，03 §4.6 双源并集律第二
+ * 源〕的审计腿，boot diff 幂等同 plugin/opens 律；载体 = audit_events）；
+ * 29→31：hook/registered·kv/written 随 T9 案一批入册（05 §1.1 常规行为
+ * 归因两词——钩子监听者受理账与键值写历史；载体 = audit_events。前者
+ * 载荷 {pluginId, hook} 无 rank 位〔03 §2.4 ctx.on 两参签名恒定、注册序由
+ * 受理时序承载〕；后者载荷 {pluginId, key, action} 值与元数据恒不入、
+ * 发射位随 ctx.sessions 受理制写面批兑现〔规范已裁代码未落——词先锚定，
+ * compaction/fallback 同律〕）。
+ * 31→32：preset/applied 随审批分档批 ap-3 入册（05 §1.1 权限预设切换审计词
+ * ——载体 = audit_events；写点 = TUI /approval preset 执行尾恰一笔，CLI
+ * --preset 逐次形零审计——04 §9 ⑥ ap-3 定形补充）。
+ * 32→33：session/paused 随无人值守深化批 u-3 入册（05 §1.1 会话停靠词
+ * ——04 §5 停靠升格定形注②；载体 = 会话流；写入者 = 编排层停靠登记位
+ * 〔issue 悬置/goal 停靠——run 在飞时先 driver.abort() 协作中止、收口后
+ * 落词〕；fold 语义 = 尾条即停靠〔SessionLiveState 推导判据〕；恢复不设
+ * 对称词——唤醒消息落账尾条翻位即恢复，resumed 词不立）。
+ * 34→35：compaction/skip 随 obs-b 压缩判据观测批入册（05 §1.1 五门
+ * skip 词 + §2.1 判序定形注——fire 而被门挡才落：判序 = 阈值评估先行
+ * 〔below 不落——判据素材可后算，不为 below 防 durable 膨胀落账〕→
+ * no-channel〔首触一条后静默，与 warn-once 同锚〕→ pending → cooldown
+ * 〔+remainMs 窗余〕，锁内复评已不 fire = retracted〔幻影触发可查〕、
+ * 区间规划无合法段 = no-segment；basis 五件同 compaction/start〔fire
+ * 判据快照〕；写入者 = 宿主 compaction 件；载体 = 会话流）。
+ */
+const CORE_EVENT_TYPES = [
+    {
+        type: 'turn/start',
+        category: 'structure',
+        owner: 'session',
+        tier: 'stable',
+        description: '一轮（用户输入 → 停止）开始',
+    },
+    {
+        type: 'turn/end',
+        category: 'structure',
+        owner: 'session',
+        tier: 'stable',
+        description: '一轮结束；reason = completed/aborted/blocked/error/max-tokens/interrupted（可扩展）',
+    },
+    {
+        type: 'user/message',
+        category: 'surface',
+        owner: 'session',
+        tier: 'stable',
+        description: '用户输入（string 或 text/image 块）；source 归因词汇闭集见 types.ts',
+    },
+    {
+        type: 'assistant/message',
+        category: 'surface',
+        owner: 'session',
+        tier: 'stable',
+        description: '组装完成后的消息级事件；toolCall 块不内联 content（由 tool/call 唯一承载）；errorMessage 腿独立 2KiB 小帽',
+    },
+    {
+        type: 'tool/call',
+        category: 'surface',
+        owner: 'session',
+        tier: 'stable',
+        description: '工具调用（arguments 存原始未解析字符串——审计保真）',
+    },
+    { type: 'tool/result', category: 'surface', owner: 'session', tier: 'stable', description: '一调用一结果' },
+    {
+        type: 'todo/write',
+        category: 'surface',
+        owner: 'conversation',
+        tier: 'stable',
+        description: '轮内清单全量快照（last-write-wins）；fold = 日志倒扫最后一条 user/message 之后的最后一条本事件',
+    },
+    {
+        type: 'request/header',
+        category: 'snapshot',
+        owner: 'session',
+        tier: 'stable',
+        description: '完整请求信封快照；reason = initial/resume/change，重建请求取最后一条为基准',
+    },
+    {
+        type: 'session/end-seed',
+        category: 'structure',
+        owner: 'session',
+        tier: 'stable',
+        description: 'fork 种子边界标记（data 为空对象，边界即事件自身 seq）',
+    },
+    {
+        type: 'approval/asked',
+        category: 'log-only',
+        owner: 'safety',
+        tier: 'stable',
+        description: '审批提问（决策对完整内容；turn 内闭合可回放）',
+    },
+    {
+        type: 'approval/decided',
+        category: 'log-only',
+        owner: 'safety',
+        tier: 'stable',
+        description: '审批决策（决策对完整内容；turn 内闭合可回放）',
+    },
+    {
+        type: 'gate/decision',
+        category: 'log-only',
+        owner: 'tools',
+        tier: 'stable',
+        description: '守门段决策（toolCallId/decision(allow|block|mutate)/reason）——「守门不可绕」不变式的断言对象',
+    },
+    {
+        type: 'sandbox/mode',
+        category: 'log-only',
+        owner: 'safety',
+        tier: 'stable',
+        description: '会话级沙箱状态 = fold(events)，append 即切换、重放即恢复（无独立配置存储）',
+    },
+    {
+        type: 'session/thinking-level',
+        category: 'log-only',
+        owner: 'conversation',
+        tier: 'stable',
+        description: '会话级思考档位 = fold(events)，append 即切换、重放即恢复（与 sandbox/mode 同形态；04 §5「thinkingLevel 是会话态不是 run 态」的 durable 落账词；写入者 = conversation 件档位切换面）',
+    },
+    {
+        type: 'llm/usage',
+        category: 'log-only',
+        owner: 'llm',
+        tier: 'stable',
+        description: 'complete 单发补全通道的计量事实（token 原始值入账，货币折算在投影查询做）',
+    },
+    {
+        type: 'llm/retry',
+        category: 'log-only',
+        owner: 'session',
+        tier: 'stable',
+        description: 'turn 级 auto-retry 的 durable 事实（attempt/phase scheduled|aborted|exhausted；成功不落）',
+    },
+    {
+        type: 'plugin/uninstalled',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '卸载四段成功尾落账（id/source/dataAction/affected?；核心词身份拒装载面注册）',
+    },
+    {
+        type: 'plugin/opens',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '高危面开门授予面切换事实（boot 装载序对每插件 grantedOpens 与审计流尾最近一条本词 diff——有变才落幂等记账；撤位落 opens:[] 空数组形收口；载体 = 进程级 durable 审计流 audit_events〔05 §9〕非会话流，fold = 审计流尾条 = 该插件当前有效授予面）',
+    },
+    {
+        type: 'doors/updated',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '进程级开门位授予面切换事实（开门制扩展批 2026-09-09——doors 段〔模型道高危面授予载体，03 §4.6 双源并集律第二源〕的审计腿，与 plugin/opens 分立成对：行 opens 授予跟插件 id 走、doors 段授予跟进程走）：boot 装载序以 doors 段现值与审计流尾最近一条本词 diff——有变才落幂等记账（空面首记不落），撤位落 doors:[] 空数组形收口；载荷 {doors 全量清单快照, origin（boot-diff|tui-cmd）}；载体 = audit_events',
+    },
+    {
+        type: 'capability/used',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '高危面开门后的每次换装/注册使用事实（宿主门检接线位在门检通过、注册动词受理成功后落；载体 = 进程级 durable 审计流 audit_events〔05 §9〕；v1 射程 = channels.ui-backend + triggers.start-run 逐次 fire（triggerName 归因腿）+ credentials.read-cross 逐次越域读（core: 直开豁免照记——豁免免的是门不是账，c-3），sdk.register-route 随 U5）',
+    },
+    {
+        type: 'plugin/installed',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '生命周期归因面——装机成功事实（id/source/version；写点 = CLI 人面 install 成功尾；载体 = 进程级 durable 审计流 audit_events〔05 §9〕非会话流，05 §1.1 生命周期归因面行）',
+    },
+    {
+        type: 'plugin/mounted',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '生命周期归因面——挂载事实（id；写点两路 = CLI 人面 mount 成功尾 + boot 装载序手编 enabled.yaml 漂移 diff 补播；载体 = audit_events；core: 内置基线态不造首记噪声——diff 基线 core: 前缀按启用算）',
+    },
+    {
+        type: 'plugin/unmounted',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '生命周期归因面——卸下事实（id；装机保留行移除；写点两路同 mounted；载体 = audit_events——与 plugin/uninstalled 同面（装机面落码批已先行，CLI 人面无会话恒此载体）；卸下/卸载两动词分立——卸下保留装机、卸载清算资产）',
+    },
+    {
+        type: 'plugin/toggled',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '生命周期归因面——禁用态翻转事实（id/disabled 双态 true|false——审计词形独立于 enabled.yaml 行形〔行内 absent 即启用、无 false 键〕，翻回启用需 false 位表达；写点两路 = CLI toggle 成功尾 + boot diff 补播；载体 = audit_events）',
+    },
+    {
+        type: 'plugin/updated',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '生命周期归因面——换装成功事实（id/from?/to——from 缺席 = 旧账本无版本位；local 源 no-op 不落〔无变更不造账〕；写点 = CLI 人面 update 成功尾；载体 = audit_events）',
+    },
+    {
+        type: 'compaction/start',
+        category: 'log-only',
+        owner: 'compaction',
+        tier: 'stable',
+        description: '压缩意图与判据快照（reason=threshold/overflow + willRetry + basis?；05 §2.1 五步之一）',
+    },
+    {
+        type: 'compaction/surface',
+        category: 'log-only',
+        owner: 'compaction',
+        tier: 'stable',
+        description: '遮蔽指令事件（信封 surfaceOp 载体本尊；data=summarySeq/规模审计；经 appendWithSurfaceOp 正门）',
+    },
+    {
+        type: 'compaction/end',
+        category: 'log-only',
+        owner: 'compaction',
+        tier: 'stable',
+        description: '压缩收尾标记（reason=completed/failed/vetoed/aborted；failed=摘要通道失败即时闭段防孤 start 悬挂；vetoed=钩子否决收形〔U4——start 后即 end 无摘要无遮蔽〕；aborted=§4 恢复协议合成形非 live 写入位）',
+    },
+    {
+        type: 'compaction/fallback',
+        category: 'log-only',
+        owner: 'compaction',
+        tier: 'stable',
+        description: '接管/算法槽失败回落事实（05 §2.1 回落三律第 3 律——回落非静默换算法；source=plugin:<id>、stage=throw|timeout|rejected〔抛错/超预算/产物被拒——空文本同宿主通道失败律〕、error? 截断、circuit?=true 末次记三振停用〔进程级，复位走重启〕；U4 调整途非法调整同 stage=rejected 记账）',
+    },
+    {
+        type: 'compaction/skip',
+        category: 'log-only',
+        owner: 'compaction',
+        tier: 'stable',
+        description: '压缩判据观测五门 skip（obs-b 2026-09-13——05 §1.1 行 82 + §2.1 判序定形注：fire 而被门挡才落，below 恒不落）：gate=pending〔防重入挡〕|cooldown〔冷却窗挡，+remainMs 窗余〕|no-segment〔fire 但区间规划无合法段〕|retracted〔排队锁内复评已不 fire——幻影触发可查〕|no-channel〔摘要通道缺席——首触落一条后静默，与 warn-once 同锚〕；basis 五件同 compaction/start（fire 判据快照——触发时刻判据素材，非门检时刻）；五门均不动冷却锚（skip 非 completed）；写入者 = 宿主 compaction 件 handleRunSettled',
+    },
+    {
+        type: 'hook/registered',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '钩子监听者受理账（T9 案一批 2026-09-09——context_transform 瀑布等钩子注册全隐身的 durable 归因：「谁在改我的上下文」有账）：载荷 {pluginId, hook}（无 rank——03 §2.4 ctx.on 两参签名恒定、注册序由受理时序承载）；写点 = ctx.on 受理壳成功尾逐笔（waterfall/notify 两腿返回位；含 §2.1 回调窗延伸内的受理；拒路径零审计〔PLUGIN_HOOK_UNKNOWN/PLUGIN_WINDOW_CLOSED——被拒的注册不是行为〕）；/reload 换代新受理新账（受理制非 boot diff——钩子注册无 fold 语义系行为流，每代如实记）；载体 = audit_events',
+    },
+    {
+        type: 'kv/written',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '键值写历史（T9 案一批 2026-09-09——store_state LRU+ttl 只有终态、写无历史的 durable 归因）：载荷 {pluginId, key 裸键名, action: set|delete}（值与 ttl/kind 元数据恒不入载荷——credentials/changed 同律；读腿零落账；persist 层 LRU/ttl 治理写零落账〔治理/受理分层〕）；写点 = ctx.sessions store_state 受理面 set/delete 成功尾逐笔——**规范已裁、代码未落**（词先锚定，发射位随受理制写面落码批兑现，compaction/fallback 同律）；载体 = audit_events',
+    },
+    {
+        type: 'preset/applied',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '权限预设切换审计（审批分档批 ap-3 2026-09-11——04 §9 定形块⑥「预设切换落审计」兑现：用户主权动作留痕，/danger approve 同形）：载荷 {preset: conservative|balanced|open, sandboxMode, approvalPolicy, appended}（appended = 建议集去重后真追加数——balanced/conservative 恒 0）；写点 = TUI /approval preset 执行尾恰一笔（写盘成功后；CLI --preset 逐次形零审计、失败路径零落账）；载体 = audit_events',
+    },
+    {
+        type: 'credentials/changed',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '凭证治理记账（凭证代管批 c-1 立词 2026-09-08——05 §1.1 词条单源；ix-4 补注册：规范立词而核心词表漏行的 c 批真遗漏，audit 词汇闸 fail-loud 抓出）：载荷 {namespace, name, action: add|remove|rotate, origin: human|oauth-flow}（值恒不入载荷——模型可见性铁律 03 §10.9）；写点 = 宿主受理位（人面 /credentials add/rm + oauth 流写/轮换 + /plugins config 表单 secret 入盒——装配根单写者律）；载体 = audit_events',
+    },
+    {
+        type: 'session/paused',
+        category: 'log-only',
+        owner: 'host',
+        tier: 'stable',
+        description: '会话停靠（无人值守深化批 u-3 2026-09-11——04 §5 停靠升格定形注②；05 §1.1 词行）：载荷 {reason}（v1 单值 budget——预算语境停靠；触发形态非穷举：记账刹停/budgetExceeded 复验/起跑前池检拒/issue 悬置同词承载）；写入者 = 编排层停靠登记位（run 在飞时先 driver.abort() 协作中止、收口后落词）；fold 语义 = 尾条即停靠（SessionLiveState paused 档推导判据）；恢复不设对称词——唤醒消息（user/message source=budget-extended）落账尾条翻位即恢复 running，resumed 词不立；载体 = 会话流',
+    },
+];
+/** 核心词类型名清单（核心词保护判据——registerEventType 拒收） */
+export const CORE_EVENT_TYPE_NAMES = CORE_EVENT_TYPES.map((m) => m.type);
+/** 注册表本体（type → 目录条目）；模块加载时灌入核心词 */
+const registry = new Map();
+for (const meta of CORE_EVENT_TYPES)
+    registry.set(meta.type, meta);
+/**
+ * 注册事件类型（插件扩展唯一入口；宿主件自管类型已列核心表）。
+ *
+ * 两类拒收（均 fail-loud）：
+ *  - 核心词身份：SESSION_CORE_TYPE_FORBIDDEN（防装载面伪造宿主词汇——
+ *    与 session append 侧词汇检查同判据双闸）；
+ *  - 注册冲突：PLUGIN_EVENT_TYPE_CONFLICT（03 §2.7 指派——装载面统一
+ *    插件域码：core 件与用户插件同走 registerSessionEventType 动词，
+ *    撞名按动词域拒收不分调用方身份）。
+ */
+export function registerEventType(meta) {
+    if (CORE_EVENT_TYPE_NAMES.includes(meta.type)) {
+        throw new BaseError('SESSION_CORE_TYPE_FORBIDDEN', `事件类型 ${meta.type} 是核心词汇——拒绝装载面注册/伪造（宿主身份词）`);
+    }
+    const existing = registry.get(meta.type);
+    if (existing) {
+        throw new BaseError('PLUGIN_EVENT_TYPE_CONFLICT', `事件类型 ${meta.type} 重复注册：${existing.owner}（彼） vs ${meta.owner}（此）`);
+    }
+    registry.set(meta.type, meta);
+}
+/** 判别事件类型是否已注册（session append 词汇检查的判据源） */
+export function isKnownEventType(type) {
+    return registry.has(type);
+}
+/** 事件类型目录条目查询（未注册返回 undefined；类别/归属消费面用） */
+export function getEventTypeMeta(type) {
+    return registry.get(type);
+}
+/** 全量目录枚举（生成目录 / CI 校验用） */
+export function listEventTypes() {
+    return [...registry.values()];
+}

package/dist/contracts/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * contracts 模块公开面（L0 公共契约——模块间唯一共边；02 篇 §4.1）。
+ *
+ * 再导出面 = 错误码注册表 + 事件词汇注册表 + 会话事件信封类型 + LLM 边界
+ * 消息基础件（第五批）。工具/插件/子代理/Job 类型随对应模块落码批进本面。
+ */
+export * from './errors.js';
+export * from './agent-events.js';
+export * from './ui.js';
+/**
+ * api.ts 分桶收面（03 篇 §8.3 internal 行 + §8.4 公开根分桶——API 治理批 2）：
+ * api.ts 顶层导出分两桶，本处只转出**可见桶**六名（四型 + 两纯函数——插件作者
+ * 可消费面）；internal 机制桶八符号（VIRTUAL_API_KEYS / SERVICE_CATALOG /
+ * CAPABILITIES / API_ENFORCEMENT_IGNITED / adjudicateApiGate / ApiGateResult /
+ * assertExperimentalDeclared / materializeHostFace）不进公开根——它们是宿主
+ * 治理机制非插件 API，内核消费全深导 contracts/api.js。
+ * 本桶面即插件虚拟模块 `berry-agent` 的运行时面（loader 注入物），分桶 =
+ * 真实运行时收面（星出时代机制符号实测进面——内部重构将判伪 MAJOR）。
+ * 分桶不变式由抽取器 assertApiBucketPartition fail-loud 执法：api.ts 新顶层
+ * 导出未分桶即炸（白名单单点 tools/extract-api-surface.mjs INTERNAL_API_EXPORTS）。
+ * 类型四名走 export type（verbatimModuleSyntax 纪律——值面只含两纯函数）。
+ */
+export type { ApiTier, ApiBlock, HostFace, HostFaceInput } from './api.js';
+export { compareApiVersions, isValidApiVersion } from './api.js';
+export * from './events.js';
+export * from './types.js';
+export * from './env-ref.js';
+export * from './redact.js';
+export * from './llm.js';
+export * from './messages.js';
+export * from './approval.js';
+export * from './tools.js';

package/dist/contracts/index.js

@@ -0,0 +1,26 @@
+/**
+ * contracts 模块公开面（L0 公共契约——模块间唯一共边；02 篇 §4.1）。
+ *
+ * 再导出面 = 错误码注册表 + 事件词汇注册表 + 会话事件信封类型 + LLM 边界
+ * 消息基础件（第五批）。工具/插件/子代理/Job 类型随对应模块落码批进本面。
+ */
+export * from './errors.js';
+// AgentEvent 活体事件族 + UI 通道后端契约族（2026-09-08 U3 落码批归位——
+// 插件侧类型可达路径定形：虚拟主键 `berry-agent` 面只达 contracts，registerUiBackend
+// 的 backend 形〔UiBackend<never>〕与 onEnvelope 活体流词汇经此两件可达；
+// agent/channels 两侧公开面 re-export 维持不变〔批 11b ApprovalAsk 同款先例〕）
+export * from './agent-events.js';
+export * from './ui.js';
+export { compareApiVersions, isValidApiVersion } from './api.js';
+export * from './events.js';
+export * from './types.js';
+// 凭证 env 引用形词面单源（03 §10.9 注入腿——c-4）：exec 执法位与 credentials
+// resolver 两方消费，放公开根使两方零新 DAG 边（三名律——跨模块走公开面）
+export * from './env-ref.js';
+// 出口治理③ 凭据消毒纯函数族（04 §7 执行段 2026-09-08 落码定形）：tools 管道
+// 链尾（模式+值基两腿）与 agent 错误包装位（纯模式腿）两方消费，同律零新边
+export * from './redact.js';
+export * from './llm.js';
+export * from './messages.js';
+export * from './approval.js';
+export * from './tools.js';

package/dist/contracts/llm.d.ts

@@ -0,0 +1,275 @@
+/**
+ * L0 contracts — LLM 边界消息基础件（04 篇 §3 StreamFn 契约 + §5 模型层）。
+ *
+ * 承 berry 同款关键决策：agent loop 不 import llm（02 篇 §4.2 关键不依赖第
+ * 一条），StreamFn 签名与消息形状收进 contracts——pi-ai 产生的消息值可原样
+ * 赋给这里的类型（标准三角色零转换直通）。
+ *
+ * 兼容策略：字段取 pi-ai 0.84.4 对应接口的**超集兼容子集**——本文件要求的
+ * 必填字段在 pi-ai 中全部存在且同名同型；pi-ai 独有的字段（api/responseModel/
+ * deferred 等）不在此收口，多出的字段对结构化赋值透明。
+ */
+/** 文本块（user/assistant/toolResult 通用） */
+export interface TextContent {
+    type: 'text';
+    text: string;
+    /** 供应商侧文本签名（回放用；透传） */
+    textSignature?: string;
+}
+/** 思考块（仅 assistant；供应商推理内容回放） */
+export interface ThinkingContent {
+    type: 'thinking';
+    thinking: string;
+    /** 供应商不透明签名（推理上下文复用；透传） */
+    thinkingSignature?: string;
+    /** 安全过滤已遮蔽的思考（加密载荷存 thinkingSignature 透传回 API） */
+    redacted?: boolean;
+}
+/** 图片块（多模态附件；base64 数据） */
+export interface ImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+/** 工具调用块（仅 assistant 内联；arguments 已是解析后的对象） */
+export interface ToolCallBlock {
+    type: 'toolCall';
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * 一次 LLM 调用的 token 用量（pi-ai 同构）：cacheRead/cacheWrite 独立拆桶，
+ * cacheWrite1h（仅 Anthropic 上报拆分）与 reasoning（已含于 output，供应商
+ * 不报则缺省）为可选子集。
+ */
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** cacheWrite 中 1h 保留的子集（仅 Anthropic 上报拆分） */
+    cacheWrite1h?: number;
+    /** 推理 token 子集（已含于 output；供应商不报则缺省） */
+    reasoning?: number;
+    totalTokens: number;
+    /** 费用（供应商可解析时填充） */
+    cost?: {
+        total: number;
+        input?: number;
+        output?: number;
+        currency?: string;
+    };
+}
+/**
+ * 计量四桶形（05 篇 §1.1 llm/usage 事件载荷 usage 字段形）：input/output/
+ * cacheRead/cacheWrite 四桶必落（供应商恒报），cacheWrite1h/reasoning 上报才落；
+ * totalTokens（派生）与 cost（折算）**不入账**——token 原始值入账、货币折算
+ * 在投影查询做（价格表更新不回改历史）。
+ */
+export interface UsageBuckets {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** cacheWrite 中 1h 保留的子集（仅 Anthropic 上报拆分；上报才落） */
+    cacheWrite1h?: number;
+    /** 推理 token 子集（已含于 output；上报才落） */
+    reasoning?: number;
+}
+/**
+ * LLM 调用终态（pi-ai 同构七值）。
+ * loop 只消费 error/aborted（终态短路）与 length（截断防御）；
+ * deferred 是 pi-ai 原生延迟工具装载透传值，v1 不产生但词汇保留。
+ */
+export type StopReason = 'pending' | 'stop' | 'length' | 'toolUse' | 'error' | 'aborted' | 'deferred';
+/**
+ * 错误四桶（04 §3.5 表）。词汇归 contracts 单源（批 11b 契约先行）：唯一实现
+ * 在 llm（classifyError 纯函数表），conversation（runTurns 重试循环与溢出
+ * 兜底）经装配注入消费同形——两侧零词汇漂移（04 §3.5 消费通路条款）。
+ * transient/non-retryable/quota 是消费动作桶（每桶一个动作无歧义态），
+ * overflow 只分类不消费（动作挂溢出兜底纵切 04 §3.4）。
+ */
+export type ErrorBucket = 'transient' | 'non-retryable' | 'quota' | 'overflow';
+/**
+ * 用户消息（content 允许纯文本或图文块数组）。
+ * source 归因复用会话事件词汇闭集 EventSource（05 §3.1 单源——durable 落账
+ * 与 LLM 边界同一名；pi-ai UserMessage 不带此字段，多出字段对直通透明）。
+ */
+export interface UserMessage {
+    role: 'user';
+    content: string | (TextContent | ImageContent)[];
+    /** Unix 毫秒时间戳 */
+    timestamp: number;
+    /** 输入归因（缺省视为 'user'；投影带出、durable 原样落账） */
+    source?: import('./types.js').EventSource;
+    /**
+     * 幂等去重键（05 §1.1 user/message 行：调用方自选、可选字段——serve 面
+     * 幂等 admit 语义真源 05 §3.5；UI 侧不带零影响）。子代理审批挂起通知等
+     * 「恰一条」机器注入以本键承载去重判据（04 §10）。
+     */
+    dedupeKey?: string;
+}
+/** 助手消息（流式组装终值；stopReason=error/aborted 时错误即数据，见 AssistantStream） */
+export interface AssistantMessage {
+    role: 'assistant';
+    content: (TextContent | ThinkingContent | ToolCallBlock)[];
+    usage: Usage;
+    stopReason: StopReason;
+    /** Unix 毫秒时间戳 */
+    timestamp: number;
+    /** 模型标识（provider 内模型 id；llm 模块解析） */
+    model?: string;
+    /** 供应商标识 */
+    provider?: string;
+    /** stopReason=error/aborted 时的错误说明（错误是数据契约之一） */
+    errorMessage?: string;
+    /**
+     * 错误码（04 §3.5 判定序的机器判定位）：宿主合成错误携带 LLM_ 码（如
+     * LLM_INFLIGHT_LIMIT 帽拒绝）；provider 真错误码归一挂 provider 钩子纵切。
+     * classifyError 判定时在场码优先、文案正则兜底。
+     */
+    errorCode?: string;
+    /** 脱敏诊断（恢复与审计用） */
+    diagnostics?: unknown[];
+}
+/** 工具结果消息（与 assistant 内 toolCall 按 toolCallId 配对） */
+export interface ToolResultMessage {
+    role: 'toolResult';
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent)[];
+    isError: boolean;
+    /** Unix 毫秒时间戳 */
+    timestamp: number;
+    /** 供日志/UI 的结构化明细（不进主上下文计费） */
+    details?: unknown;
+    /** 工具执行自身的用量（若可得上报；不进主上下文计费） */
+    usage?: Usage;
+    /** 本次结果后新可用的工具名（延迟装载透传） */
+    addedToolNames?: string[];
+}
+/** LLM 边界标准三角色（convertToLlm 透传的标准半边） */
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+/** LLM 工具描述（parameters 为 JSON Schema——typebox 产物即此形状） */
+export interface LlmTool {
+    name: string;
+    description: string;
+    /** JSON Schema 参数描述（typebox 产物或等价 JSON Schema 对象；宽收 object 兼容构建器类型） */
+    parameters: object;
+}
+/** 单次 LLM 请求上下文（StreamFn 第一参数；04 §3.1） */
+export interface LlmContext {
+    systemPrompt?: string;
+    messages: Message[];
+    tools?: LlmTool[];
+}
+/**
+ * 模型目录只读投影（listModels()/getModel() 返回形）：pi-ai Model 的应用友好
+ * 子集——枚举/展示/能力判别所需字段直通，传输与 provider 配置面（baseUrl/
+ * headers/samplingParams/compat）不披露（宿主数据只经服务面，03 篇 §3.2
+ * 「防双实例」纪律的读侧配套）。
+ */
+export interface ModelInfo {
+    /** 模型标识（"provider/model-id" 全形——resolveModel 可解析的同一名） */
+    readonly id: string;
+    /** 展示名（人类可读） */
+    readonly name: string;
+    /** 所属 provider id（目录分组用） */
+    readonly provider: string;
+    /** 是否推理模型（思考档位面可用性判据） */
+    readonly reasoning: boolean;
+    /** 输入模态清单 */
+    readonly input: readonly ('text' | 'image')[];
+    /** 上下文窗口（tokens） */
+    readonly contextWindow: number;
+    /** 单请求输出上限（tokens） */
+    readonly maxTokens: number;
+}
+/** 思考档位（pi-ai 同构七值；xhigh/max 仅部分模型家族支持——会话态非 run 态，04 §5） */
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** StreamFn 每次调用的选项（model 为模型 id 字符串——解析归 llm 模块，loop 不持模型对象） */
+export interface StreamFnOptions {
+    /** 模型 id（llm 模块解析为具体 provider/model；可逐轮替换） */
+    model: string;
+    thinkingLevel?: ThinkingLevel;
+    /** 凭证（缺省 undefined 由 llm 层走持久化凭证链） */
+    apiKey?: string;
+}
+/**
+ * 模型层注入签名（llm 模块整体替换位——agent 与 llm 两模块的唯一会合点，故落在
+ * contracts）。契约：**永不抛错**（04 §3）——一切失败编码为返回流的 error 终止
+ * 事件 + 最终消息 stopReason='error'|'aborted' + errorMessage（AssistantStream
+ * 契约注释）。这是 loop 零 try/catch 的契约根基：错误是数据不是异常。
+ */
+export type StreamFn = (context: LlmContext, options: StreamFnOptions, signal?: AbortSignal) => AssistantStream | Promise<AssistantStream>;
+/**
+ * 流式事件（pi-ai AssistantMessageEvent 同构 12 型）。
+ * 协议：`start` 先行 → 各内容块 start/delta/end 交错（partial 携带累计快照）→
+ * 以 `done`（成功）或 `error`（stopReason=error/aborted）收尾。
+ */
+export type AssistantStreamEvent = {
+    type: 'start';
+    partial: AssistantMessage;
+} | {
+    type: 'text_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'text_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'text_end';
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_end';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_end';
+    contentIndex: number;
+    toolCall: ToolCallBlock;
+    partial: AssistantMessage;
+} | {
+    type: 'done';
+    reason: Extract<StopReason, 'stop' | 'length' | 'toolUse' | 'deferred'>;
+    message: AssistantMessage;
+} | {
+    type: 'error';
+    reason: Extract<StopReason, 'aborted' | 'error'>;
+    error: AssistantMessage;
+};
+/**
+ * 流式响应：异步迭代事件 + 最终消息取值口。
+ * 契约（04 §3「永不抛」，loop 零 try/catch 的根基）：**永不抛错**——一切失败
+ * 编码为流内 `error` 终止事件 + 最终 AssistantMessage 的 stopReason='error'|
+ * 'aborted' + errorMessage。错误是数据不是异常（金样回放轨的替换点 seam）。
+ */
+export interface AssistantStream {
+    /** 迭代流事件（以 done/error 收尾后结束） */
+    [Symbol.asyncIterator](): AsyncIterator<AssistantStreamEvent>;
+    /** 取最终 AssistantMessage（流耗尽后 resolve；失败编码在 stopReason/errorMessage 上） */
+    result(): Promise<AssistantMessage>;
+}