berry-agent 0.1.0-alpha.1

package/dist/contracts/types.d.ts

@@ -0,0 +1,302 @@
+/**
+ * 会话事件信封与归因词汇类型（05 篇 §1.1 信封定稿 + §3.1 source 闭集定稿）。
+ *
+ * 本文件是 SessionEvent 形态的唯一权威——02 篇词汇表钉、05 篇 §1.1 重述，
+ * 此处逐字段转录；LLM 消息/流/角色与工具/插件/子代理/Job 类型随对应模块
+ * 落码批按 pi-ai 实形定义（contract-first：纵切批内先契约后实现）。
+ */
+import type { Usage } from './llm.js';
+/**
+ * 表面遮蔽指令（改历史的唯一合法形态——追加 replace 指令事件遮蔽旧区间，
+ * 原文保留可审计）。区间 [start, end] 为被遮蔽事件的 seq 闭区间。
+ */
+export interface SurfaceOp {
+    /** 指令形态——v1 唯一值 'replace'（词汇预留扩展） */
+    op: 'replace';
+    /** 被遮蔽区间起始 seq（含） */
+    start: number;
+    /** 被遮蔽区间结束 seq（含） */
+    end: number;
+}
+/**
+ * 会话事件信封：日志唯一条目形态（append-only，写入即冻结）。
+ */
+export interface SessionEvent<T = unknown> {
+    /** 事件类型词汇（核心清单 events.ts + 插件显式注册扩展） */
+    type: string;
+    /** = 写入时 log.length，强制连续、0 起（只在尾部追加结构保证，无独立分配器） */
+    seq: number;
+    /** 毫秒时间戳；合成事件复用最后真实事件的 time（确定性——金样回放友好） */
+    time: number;
+    /** 已冻结的 JSON 快照（写入时单遍校验 + deepFreeze——从冻结快照读 = 免拷贝投影） */
+    data: T;
+    /** true = 读侧可以不认识此类型（向前兼容）；缺省 = 必须认识 */
+    ignorable?: boolean;
+    /** 遮蔽指令——仅改历史事件携带（§2 surfaceOp 协议） */
+    surfaceOp?: SurfaceOp;
+    /** 遮蔽溯源：被遮蔽节点 + 依据事件的完整 seq 列表 */
+    sourceEventSeqs?: number[];
+}
+/**
+ * user/message 的 source 归因词汇闭集（05 §3.1 表全列）：
+ * 六字面量 ∪ 三前缀模板串。TS 模板字面量类型即闭集执法——已知前缀的
+ * 任意后缀（`plugin:未来插件`）类型合法，语义按前缀行展开。
+ */
+export type EventSource = 'user' | `channel:${string}` | 'schedule' | 'subagent-settled' | 'subagent-approval-pending' | 'budget-extended' | 'compaction' | `plugin:${string}` | `session:${string}`;
+/** source 归一化种类（前缀型归并到 kind；字面量一一对应） */
+export type EventSourceKind = 'user' | 'channel' | 'schedule' | 'subagent-settled' | 'subagent-approval-pending' | 'budget-extended' | 'compaction' | 'plugin' | 'session';
+/** parseEventSource 结果：归一化种类 + 原值 + 投影位判别 */
+export interface ParsedEventSource {
+    /** 归一化种类（未知字面量归 'user'——旧日志向前兼容按 user 同视） */
+    kind: EventSourceKind;
+    /** 原始字符串（审计保真） */
+    raw: string;
+    /**
+     * 投影是否以用户话语位展开（05 §3.1「投影同视 user」判据）：
+     * user/channel/schedule/subagent-settled = true（都是输入位，仅审计可辨入口）；
+     * compaction/plugin/session = false（摘要载体、受控注入与跨会话操控注入
+     * 不视为用户话语——渲染与记忆提取归因区分显示）。
+     */
+    treatedAsUser: boolean;
+}
+/**
+ * 解析 source 归因字符串（闭集执法的读侧判据，05 §3.1）：
+ *  - 已知前缀的未知后缀（如 'plugin:未来插件'）按前缀行语义展开；
+ *  - 未知字面量（旧日志向前兼容）按 user 同视；
+ *  - append 侧新值必须先扩闭集（类型 + 本函数）——写入纪律归 session 落码批。
+ */
+export declare function parseEventSource(source: string): ParsedEventSource;
+/**
+ * turn/end 的 reason 闭集（05 §1.1 表：completed / aborted / blocked / error /
+ * max-tokens / interrupted，可扩展）。`(string & {})` 保留字面量自动补全的
+ * 同时不拒扩展值——新增终态值属词汇演进，须先扩 05 篇表格。
+ */
+export type TurnEndReason = 'completed' | 'aborted' | 'blocked' | 'error' | 'max-tokens' | 'interrupted' | (string & {});
+/**
+ * 会话血缘 origin 闭集（05 §5.1）：'conversation'（普通对话）/ 'delegation'
+ * （委派子会话）/ 'import'（外部导入）/ 'fork'（显式 fork）/ 'trigger'（触发器
+ * starter 起的无头会话——首 turn 非人触，2026-09-07 触发器面 C 批落码扩词；
+ * 05 §9 sessions.origin 与 03 §2.4 session_start 载荷三处闭集同笔）。无插件
+ * 域——会话直归 agent（05 §0 会话归属模型）。
+ */
+export type SessionOrigin = 'conversation' | 'delegation' | 'import' | 'fork' | 'trigger';
+/** 血缘三元组（fork 动作的分层返回外层，05 §5.2；不返回幻影 id） */
+export interface SessionLineage {
+    /** 源会话 id（根会话 = undefined） */
+    readonly parentId: string | undefined;
+    /** 种子前缀长度（首条新 append 事件恰落此位，05 §5.2） */
+    readonly seedLength: number;
+    /** 血缘形态 */
+    readonly origin: SessionOrigin;
+}
+/**
+ * 重试进行态只读小面（04 §3.3 注记 seam——批 13a 落码位）：conversation 驱动
+ * 重试循环的只读探针，SDK 线协议心跳载荷是该 seam 的**唯一线面出口**
+ * （03 §10.6 线协议②：`retry <attempt>/<next>` 不可从事件流推导——活体层
+ * 「重试续入零新事件型」维持不破；非事件型、不进 durable）。
+ *
+ * 归位 contracts：producer（conversation）与 consumer（channels SDK 通道
+ * 后端）边表互不可达（02 §4.1），结构共享零 import 边——ApprovalAskRequest
+ * 归位同款先例（批 11b）。
+ */
+export interface RetryProbe {
+    /** 当前重试序（1 起——attempt 计数生命周期 = 单次 runTurns 调用） */
+    readonly attempt: number;
+    /** 名额上限（RetryPolicy.maxRetries 面——transient/overflow 各自分账） */
+    readonly maxAttempts: number;
+    /** 下次续入时间戳（epoch ms）；null = 不在退避等待（重试已续入/取消/耗尽） */
+    readonly nextAt: number | null;
+}
+/**
+ * 委派深度帽（04 §10 委派边界③）：根会话委派 = 深度 1；子代理再委派逐层 +1；
+ * 超帽 3 拒（SUBAGENT_DEPTH_EXCEEDED——防自嵌套爆栈）。
+ */
+export declare const SUBAGENT_DEPTH_MAX = 3;
+/**
+ * SubagentProvider 能力协商面（04 §10——五布尔）：注册方声明，消费方
+ * （委派机器/呈现面）据以决定可用形态（如 background=false 的 provider
+ * 不受理后台收场）。in-process 真工厂五项恒真（独立装配全套）。
+ */
+export interface SubagentCapabilities {
+    /** 子代理有自己的工具面（非纯文本模型） */
+    readonly tools: boolean;
+    /** 支持流式过程可见（父可观察中间输出） */
+    readonly streaming: boolean;
+    /** 支持协作取消（stop → stopping → killed） */
+    readonly cancel: boolean;
+    /** 支持后台收场（Job 注册表托管；one-shot-only provider 恒 false） */
+    readonly background: boolean;
+    /**
+     * 支持结构化输出（SubagentResult.structured 面）：语义 = 「结果携宿主铸造
+     * 结构账可依赖」——in-process 真 = 工厂结算位机器账（04 §10 定形段），
+     * 第三方 true = 自有形（契约位宽形不锁字段表）。
+     */
+    readonly structuredOutput: boolean;
+}
+/**
+ * 委派请求（04 §10：请求含 prompt、工具白名单、模型覆盖——其余为机器
+ * 注入位，模型侧工具 schema 不暴露）。
+ */
+export interface SubagentRequest {
+    /** 委派目标提示（子代理的唯一任务输入） */
+    readonly prompt: string;
+    /** 工具白名单（与 def 的 tools 交集执法——子代理可用面 ⊆ 交集） */
+    readonly tools?: readonly string[];
+    /** 模型覆盖（缺省回落宿主模型） */
+    readonly model?: string;
+    /** 子代理系统提示（声明式子代理正文直传；通用 agent 工具不设） */
+    readonly systemPrompt?: string;
+    /** 诊断名（Job 名与通知文案的显示位；缺省机器派生） */
+    readonly name?: string;
+    /** 机器注入位——父会话 id（background 结算通知路由） */
+    readonly parentSessionId?: string;
+    /** 机器注入位——收场形态（one-shot 缺省 / background 托管） */
+    readonly background?: boolean;
+    /** 机器注入位——委派深度（根 = 1；超帽拒——模型不可直设） */
+    readonly depth?: number;
+    /**
+     * 机器注入位——审批挂起通知闭包（in-process 子栈审批闸的父路由）：
+     * background 形注入（one-shot 不注入——挂着等待即知情）；实现方执法
+     * 恰一条幂等（driver dedupeKey 面）。
+     */
+    readonly notifyApproval?: (info: {
+        approvalId: string;
+        toolName: string;
+        reason?: string;
+    }) => Promise<unknown>;
+    /**
+     * 机器注入位——协作停止观察面（background 形注入）：JobHandle.stop()
+     * 置 stopping 后本闭包变真；in-process 工厂据此桥子栈中止（abort 子 run）。
+     * 只读观察非信号——轮询/桥接形态由工厂自选。
+     */
+    readonly stopRequested?: () => boolean;
+    /**
+     * 机器注入位——技能正文永久注入清单（06 §11.6 skills 键 spawn 永久注入模）：
+     * 技能名数组（形状三验在工厂 spawn 时统一复验——声明式 def 填充缺省/程序化
+     * def 镜像/直呼三方同点执法）；模型侧工具 schema 不暴露。
+     */
+    readonly skills?: readonly string[];
+}
+/**
+ * 委派结算（04 §10：子代理是黑盒——结果不重试，立即结算给父）。
+ */
+export interface SubagentResult {
+    /** 最终输出（黑盒面——父只见结果不见内部过程；机器账在位时降为参考面） */
+    readonly output: string;
+    /**
+     * 结构化输出（capabilities.structuredOutput 时有效）。契约位保持宽形
+     * （unknown——第三方 provider 可铸自有形）；in-process 工厂 v1 唯一形 =
+     * 宿主机器账 { childSessionId, jobName?, durationMs, turnCount,
+     * messageCount, usage {input,output}|null, stopReason }（04 §10 structured
+     * 定形段——subagent/types.ts SubagentMachineAccount 单源形）。
+     */
+    readonly structured?: unknown;
+    /** 降级上报（≤4096 截断——哪些工具被拒、以何降级路径完成；禁伪装执法位） */
+    readonly diagnostic?: string;
+    /**
+     * 用量（子栈计量上报；缺席 = 未计量）。in-process 工厂与 structured.usage
+     * 同值双填（同源一次铸造——顶层位 = 末条 assistant 完整 Usage、机器账位 =
+     * 同源两桶投影）；顶层位独立保留意义 = 第三方 provider 只报顶层计量不铸
+     * 机器账。
+     */
+    readonly usage?: Usage;
+    /** 收场原因（error 形 = 结果即错误数据——重试是父的策略不是子代理机制） */
+    readonly stopReason: SubagentStopReason;
+}
+/** 子代理收场原因闭集（StopReason 子集——委派语境三值；'killed' 承 Job 终态词） */
+export type SubagentStopReason = 'stop' | 'error' | 'aborted';
+/**
+ * SubagentProvider 契约（04 §10——subagent 件提供，core:）：能力协商 +
+ * 单一委派动词。in-process provider 是真工厂——每子代理独立装配全套
+ * （自己的 loop/scope/工具面/凭证），运行期无「我是谁派来的」识别。
+ */
+export interface SubagentProvider {
+    readonly capabilities: SubagentCapabilities;
+    run(request: SubagentRequest): Promise<SubagentResult>;
+}
+/**
+ * Job 种类闭集（04 §10——kind 现设四值；registerKind 显式登记后方可使用）。
+ * `'trigger'` = 触发器 starter 的缺省托管 kind（jobKind 缺省即隐式进此 kind；
+ * host 装配期自登 + 缺省并行帽 4——2026-09-07 触发器面 C 批落码定形）。
+ */
+export type JobKind = 'subagent' | 'process' | 'issue' | 'trigger';
+/** Job 状态机（04 §10：running →（可选 stopping）→ 唯一终态；first-wins） */
+export type JobStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed';
+/** Job 终态载荷（settle 时落——first-wins 封口后的不可变值） */
+export interface JobTerminal {
+    /** 终态（三值闭集——completed/killed/failed） */
+    readonly status: Extract<JobStatus, 'completed' | 'killed' | 'failed'>;
+    /** 终态落定时刻（epoch ms） */
+    readonly at: number;
+    /** 终态说明（人读——killed 的归因/failed 的错误摘要等） */
+    readonly detail?: string;
+}
+/** Job 注册表条目（进程内状态——04 §10 终态不镜像落库明文豁免） */
+export interface JobEntry {
+    /** 唯一 id（注册表自铸 `job-<n>` 序列） */
+    readonly id: string;
+    /** 显示名（子代理诊断名/进程命令行等） */
+    readonly name: string;
+    /** 种类（registerKind 登记词汇） */
+    readonly kind: JobKind;
+    /** 归属围栏（会话关闭按 owner 收口其在飞 Job 落 killed） */
+    readonly owner: string;
+    /** 当前状态（终态后不可变——first-wins） */
+    readonly status: JobStatus;
+    /** 起跑时刻（epoch ms） */
+    readonly startedAt: number;
+    /** 终态载荷（未终态 = undefined） */
+    readonly terminal?: JobTerminal;
+}
+/** job_settled 活体事件载荷（04 §10——总线词，内存直推不落库） */
+export interface JobSettledEvent {
+    /** 终态条目快照（含 id/kind/owner/terminal） */
+    readonly entry: JobEntry;
+}
+/**
+ * 声明式子代理解析产物（06 §11.6 agents/*.md 纯数据 def）。
+ * 归 contracts（02 §4.1 席 1 契约家）：解析层住 core:skills、机器住
+ * core:subagent——两侧共享形状只可经契约面（skills→subagent 无边，
+ * DAG 禁穿）；subagent 收纯数据 def 零 yaml（yaml 裸导入白名单不扩）。
+ */
+export interface SubagentDef {
+    /** 身份键（frontmatter name 缺省回落文件基名；提供时须与基名一致） */
+    readonly name: string;
+    /** 描述（必填——披露段清单行 = 模型选择依据） */
+    readonly description: string;
+    /** 工具白名单（可选 include 名单——与派生面交集执法） */
+    readonly tools?: readonly string[];
+    /** 前置要求（04 §10 预检闸声明位——与 tools 白名单正交不混读） */
+    readonly requires?: readonly string[];
+    /** 技能正文永久注入清单（06 §11.6 skills 键——spawn 时具名块拼入子 systemPrompt 尾） */
+    readonly skills?: readonly string[];
+    /** 模型覆盖（子代理启动参数直传工厂——不进能力协商面） */
+    readonly model?: string;
+    /** 正文即系统提示（frontmatter 闭合 --- 之后全文） */
+    readonly systemPrompt: string;
+    /** 来源文件绝对路径（诊断/溯源面） */
+    readonly filePath: string;
+}
+/**
+ * 程序化 named provider 注册 def（03 §2.2 第十二动词 ctx.agent.registerSubagentProvider
+ * 单参——04 §10 程序化注册槽段机制真源）。**镜像 frontmatter 形** = SubagentDef 减
+ * 来源文件位（程序化注册无文件载体——filePath 是声明式腿专属归因面）；注册即派生
+ * 静态工具 `agent_<name>`（物化机器住 core:subagent）。形状归 contracts 同 SubagentDef
+ * （消费方 = subagent 注册机器 + host ctx 面——经契约面共享，不私造双形）。
+ */
+export interface ProgrammaticSubagentDef {
+    /** 身份键（裸词——06 §11.6 声明式 name 同形：小写字母/数字/连字符，词法真源 06 §11.2） */
+    readonly name: string;
+    /** 描述（必填——披露段清单行 = 模型选择依据） */
+    readonly description: string;
+    /** 工具白名单（可选 include 名单——与派生面交集执法） */
+    readonly tools?: readonly string[];
+    /** 前置要求（04 §10 预检闸声明位——与 tools 白名单正交不混读） */
+    readonly requires?: readonly string[];
+    /** 技能正文永久注入清单（06 §11.6 skills 键——镜像 frontmatter 形；spawn 时统一复验） */
+    readonly skills?: readonly string[];
+    /** 模型覆盖（子代理启动参数直传工厂——不进能力协商面） */
+    readonly model?: string;
+    /** 子代理系统提示（程序化腿无文件载体——正文直传） */
+    readonly systemPrompt: string;
+}

package/dist/contracts/types.js

@@ -0,0 +1,50 @@
+/** 字面量六值 → 归一化种类映射（前缀型经 startsWith 归并） */
+const LITERAL_SOURCE_KINDS = {
+    user: 'user',
+    schedule: 'schedule',
+    'subagent-settled': 'subagent-settled',
+    'subagent-approval-pending': 'subagent-approval-pending',
+    'budget-extended': 'budget-extended',
+    compaction: 'compaction',
+};
+/**
+ * 解析 source 归因字符串（闭集执法的读侧判据，05 §3.1）：
+ *  - 已知前缀的未知后缀（如 'plugin:未来插件'）按前缀行语义展开；
+ *  - 未知字面量（旧日志向前兼容）按 user 同视；
+ *  - append 侧新值必须先扩闭集（类型 + 本函数）——写入纪律归 session 落码批。
+ */
+export function parseEventSource(source) {
+    if (source.startsWith('channel:')) {
+        return { kind: 'channel', raw: source, treatedAsUser: true };
+    }
+    if (source.startsWith('plugin:')) {
+        return { kind: 'plugin', raw: source, treatedAsUser: false };
+    }
+    if (source.startsWith('session:')) {
+        // 跨会话操控注入（模型工具道——前缀自描述送话会话 id）：agent 互搏注入
+        // 非用户话语，投影位与 plugin 同判 false（05 §3.1 session: 行）
+        return { kind: 'session', raw: source, treatedAsUser: false };
+    }
+    const literal = LITERAL_SOURCE_KINDS[source];
+    if (literal) {
+        // compaction 是摘要载体：不是人说的——投影位与 plugin 同判 false；
+        // subagent-approval-pending 与 subagent-settled 同通道同型（04 §10
+        // UserMessage 注入位）——投影同视用户话语；budget-extended 与 schedule
+        // 同形（机器注入的起跑输入位，05 §3.1 第六字面量）——投影同视用户话语
+        const treatedAsUser = literal === 'user' ||
+            literal === 'schedule' ||
+            literal === 'subagent-settled' ||
+            literal === 'subagent-approval-pending' ||
+            literal === 'budget-extended';
+        return { kind: literal, raw: source, treatedAsUser };
+    }
+    // 未知字面量：旧日志向前兼容——按 user 同视（读侧宽容，append 侧严进）
+    return { kind: 'user', raw: source, treatedAsUser: true };
+}
+/* ---------------- 子代理与 Job 注册表（04 §10——批 15c 契约先行） ---------------- */
+/**
+ * 委派深度帽（04 §10 委派边界③）：根会话委派 = 深度 1；子代理再委派逐层 +1；
+ * 超帽 3 拒（SUBAGENT_DEPTH_EXCEEDED——防自嵌套爆栈）。
+ */
+export const SUBAGENT_DEPTH_MAX = 3;
+void true;

package/dist/contracts/ui.d.ts

@@ -0,0 +1,122 @@
+/**
+ * UI 通道后端契约（07 篇 §4.1/§4.3 机制真源；03 §2.2 registerUiBackend
+ * 插件注册面）。
+ *
+ * 归位注记（2026-09-08 U3 落码批）：本族类型原住 channels 件
+ * （src/channels/types.ts），为插件侧类型可达（虚拟主键 `berry-agent` 面只达
+ * contracts——03 §2.2 定形注记）随 U3-1 归位本件（批 11b ApprovalAsk 归位
+ * 同款先例）；channels 公开面 re-export 维持不变。
+ *
+ * 插件实装形 = `UiBackend<never>`：投影泛型 TProjection 由宿主装配钉入
+ * （session 域投影类型，插件结构性不可达），插件后端走信封驱动呈现
+ * （onEnvelope 活体流）、不参与投影重画（onRepaint/openHistory——
+ * SDK/webui 后端 `UiBackend<never>` 同形先例）。
+ */
+import type { AgentEvent } from './agent-events.js';
+import type { ApprovalAskAnswer, ApprovalAskRequest } from './approval.js';
+/**
+ * 多会话信封（07 §4.1 channels 纵切批定形三则②）：AgentEvent 不带会话归属
+ * 是刻意的——loop 是单 run 视角无多会话概念；归属信封的包装位 = host 装配
+ * 的 per-run sink 包装器（conversation 侧 sink 签名零 channels 感知、纯
+ * AgentEvent 回调注册面，host 汇入 channels 分发器时附加信封——装配根是
+ * 唯一允许 import 全部宿主模块的横切层，2026-09-06 冷读裁决 C-1），channels
+ * 消费分流。
+ */
+export interface SessionEnvelope {
+    readonly sessionId: string;
+    readonly event: AgentEvent;
+}
+/** notify 通知档（07 §4.3 签名定稿；'success' = 任务完成语义档） */
+export type NotifyLevel = 'info' | 'success' | 'warn' | 'error';
+/** 阻塞原语公共选项（07 §4.3 撤销面：abort 按取消收场取保守值） */
+export interface UiAskOptions {
+    /** 可选中止信号——abort 时 confirm→false / select·input→''（保守值收场） */
+    readonly signal?: AbortSignal;
+}
+/** select 单选项（07 §4.3 签名定稿形） */
+export interface UiSelectChoice {
+    readonly value: string;
+    readonly label: string;
+}
+/** input 原语选项 */
+export interface UiInputOptions extends UiAskOptions {
+    readonly placeholder?: string;
+}
+/**
+ * 通道能力声明（07 §4.3 通道降级规则的判定面）：不支持的原语按
+ * 「notify 化」降级（select→input→notify、setWidget→notify）——插件不感知
+ * 通道能力差异，降级判定与编舞在核。
+ */
+export interface UiCapabilities {
+    /** 一次性通知（一切通道的最后降级目标——接口上仍声明，装配健全性由核校验） */
+    readonly notify: boolean;
+    readonly confirm: boolean;
+    readonly select: boolean;
+    readonly input: boolean;
+    /** 审批 ask（07 §4.3 提问队列条款——阻塞原语与审批统一入队的第四原语位） */
+    readonly approval: boolean;
+    readonly setStatus: boolean;
+    readonly setWidget: boolean;
+}
+/**
+ * 通道后端接口（通道核的呈现消费面）。TUI 实装 = channels 件内自研 TuiBackend
+ * （批 10e 已落）、webui 件同面接入；核经此面驱动一切呈现——阻塞原语多后端并发竞速（04 §9 跨入口竞速
+ * 先答先得），败腿经 signal 撤销收场（07 §4.3 撤销面同链）。
+ */
+export interface UiBackend<TProjection> {
+    /** 后端身份（'tui' / 'webui'——日志与调试面，非能力位） */
+    readonly id: string;
+    readonly capabilities: UiCapabilities;
+    /** 观众探针：本后端自报有观众（TUI 恒真 / webui 报在线连接数 > 0——07 §4.3） */
+    hasAudience(): boolean;
+    /** 一次性通知（level 档通道不识别时向后端自身归一 info） */
+    notify(message: string, opts?: {
+        level?: NotifyLevel;
+    }): void;
+    /** 是/否确认（仅 capable 后端被调——缺席面降级判定在核） */
+    confirm?(message: string, opts?: UiAskOptions): Promise<boolean>;
+    /** 单选（Enter 选定 / Esc 取消收 ''——TUI 原生实装语义） */
+    select?(message: string, choices: readonly UiSelectChoice[], opts?: UiAskOptions): Promise<string>;
+    /** 自由文本输入 */
+    input?(message: string, opts?: UiInputOptions): Promise<string>;
+    /**
+     * 审批 ask（仅 capable 后端被调——呈现形态归后端：TUI 主屏浮层是队首呈现之一）。
+     * sessionId 首参 = 会话归属承载位（批 13b-3 随 SDK 通道后端定形——ask 帧信封
+     * 必携会话归属；核心面 07 §4.3 `askApproval(sessionId, request)` 本含会话位，
+     * 后端面同携）。
+     */
+    askApproval?(sessionId: string, request: ApprovalAskRequest, opts?: UiAskOptions): Promise<ApprovalAskAnswer>;
+    /** 状态行更新（last-writer-wins——多写者自然覆盖） */
+    setStatus?(sessionId: string, status: string): void;
+    /** 自定义渲染槽呈现（会话级单槽值由核维护——见 UiCore.setWidget） */
+    setWidget?(sessionId: string, node: unknown | null): void;
+    /** 活体信封呈现（focused 位由核路由——聚焦全渲染/非聚焦摘要行，形态归后端） */
+    onEnvelope?(env: SessionEnvelope, focused: boolean): void;
+    /** 重画呈现（焦点切换/初始——载荷 = 投影快照 + 该会话当前 widget 槽值） */
+    onRepaint?(sessionId: string, projection: readonly TProjection[], widget: {
+        node: unknown;
+    } | null): void;
+    /**
+     * 收起副屏（07 §4.1 件 8「ask 强制收起（注意力优先级 ask > 回看）：通道
+     * ask 入口先收副屏再入提问队列」条款的可选能力面——批 10f-4）。在场即
+     * 实现 = 后端自报有副屏可收（TUI = 1049 备屏退出 + 主屏复起）；核 ask
+     * 入口扇出本钩。缺席 = 无副屏可收零义务（非 TUI 后端不受影响）。
+     */
+    collapseAltScreen?(): void;
+    /**
+     * 开副屏回看器（07 §4.1 件 8 /history 命令的呈现面——命令注册在通道核按
+     * ChannelsOptions.history 注入在场判）。载荷 = 全量 durable 正文投影
+     * （history() 拉取）；呈现形态归后端（TUI = 1049 副屏整屏回看，同一渲染
+     * 管线零第二渲染器）。缺席 = 不支持整屏回看的后端。
+     */
+    openHistory?(sessionId: string, messages: readonly TProjection[]): void;
+    /**
+     * 开副屏记忆管理面（06 §7 `/memory` 命令的呈现面——命令注册在通道核按
+     * ChannelsOptions.memory 注入在场判；mm 批）。零参形——材料归后端装配
+     * 自持（数据不经通道核流转：TuiBackend 经后置 setMemoryScreen 注入位持
+     * 有 DAO 窄面/消毒函数/导出闭包，与 openHistory 的载荷经核流转分立）。
+     * 返 boolean：true = 已开（支持且有材料）；false = 不支持或缺材料——核
+     * 据此走 notify 降级提示（不静默）。缺席 = 不支持管理面的后端。
+     */
+    openMemory?(): boolean;
+}

package/dist/contracts/ui.js

@@ -0,0 +1,15 @@
+/**
+ * UI 通道后端契约（07 篇 §4.1/§4.3 机制真源；03 §2.2 registerUiBackend
+ * 插件注册面）。
+ *
+ * 归位注记（2026-09-08 U3 落码批）：本族类型原住 channels 件
+ * （src/channels/types.ts），为插件侧类型可达（虚拟主键 `berry-agent` 面只达
+ * contracts——03 §2.2 定形注记）随 U3-1 归位本件（批 11b ApprovalAsk 归位
+ * 同款先例）；channels 公开面 re-export 维持不变。
+ *
+ * 插件实装形 = `UiBackend<never>`：投影泛型 TProjection 由宿主装配钉入
+ * （session 域投影类型，插件结构性不可达），插件后端走信封驱动呈现
+ * （onEnvelope 活体流）、不参与投影重画（onRepaint/openHistory——
+ * SDK/webui 后端 `UiBackend<never>` 同形先例）。
+ */
+export {};

package/dist/conversation/agent-service.js

@@ -0,0 +1,61 @@
+/**
+ * ctx.agent 服务面（02 §2.3「ctx.agent provide」/ 03 §2.2 能力面表）——
+ * conversation 件经 scope.provide('agent', …) 供给的服务词汇。
+ *
+ * 两动词（03 篇能力面表在册——本面只登记不重复语义）：
+ *  - registerMessageRole：自定义消息角色注册（contracts 注册表的单入口委托
+ *    ——域名前缀两段式强制/撞名拒绝式执法全在 contracts 单源）；
+ *  - onRunSettled：run 终态订阅（**非总线词汇**——触发契约锚 = run 终态
+ *    三值 04 §2；compaction 触发〔05 §2〕消费）。会话内每次 runTurns
+ *    结算由 ConversationDriver 在终态边界回调（04 §3——与审批收口同界）。
+ *
+ * 服务面是进程级单例：多会话共用一枚，订阅回调携 {sessionId} 信封区分
+ * 来源会话（多会话并存下活体载荷携带 sessionId 的同律）。
+ */
+import { registerMessageRole } from '../contracts/index.js';
+/** scope 服务名（02 §2.3 ctx.agent provide——服务词汇单源定值） */
+export const AGENT_SERVICE_NAME = 'agent';
+/** 订阅表登记（服务实例 → 终态回调集——驱动回调面的受控读口，WeakMap 随服务回收） */
+const settleTables = new WeakMap();
+/**
+ * 组装 ctx.agent 服务并 provide 到装载运行时 scope（host 装配根调用一次，
+ * 先于一切驱动起跑——驱动在 runTurns 终态经 scope.tryGet 回调订阅面）。
+ */
+export function provideAgentService(scope) {
+    /** run 终态订阅表（注册序回调；dispose 即摘） */
+    const settleHandlers = new Set();
+    const service = {
+        // 委托 contracts 注册表：域名纪律/撞名执法单源在彼，此处零再立法
+        registerMessageRole: (role, definition) => registerMessageRole(role, definition),
+        onRunSettled: (handler) => {
+            settleHandlers.add(handler);
+            return () => {
+                settleHandlers.delete(handler);
+            };
+        },
+    };
+    settleTables.set(service, settleHandlers);
+    scope.provide(AGENT_SERVICE_NAME, service);
+    return service;
+}
+/**
+ * 驱动侧终态回调（runTurns finally 消费点——04 §3 终态=结算边界，与审批
+ * 收口同界）。scope 未 provide（纯对话测试形态/装配序缺口）= 零回调静默
+ * 跳过；订阅者异常隔离（emit 族同律——单订阅者故障不反噬 run 结算路径）。
+ */
+export function notifyRunSettled(scope, event) {
+    const service = scope.tryGet(AGENT_SERVICE_NAME);
+    if (service === undefined)
+        return;
+    const handlers = settleTables.get(service);
+    if (handlers === undefined)
+        return;
+    for (const handler of [...handlers]) {
+        try {
+            handler(event);
+        }
+        catch {
+            // 观察者异常隔离——继续其余订阅者，结算路径不受影响
+        }
+    }
+}

package/dist/conversation/approval-wiring.js

@@ -0,0 +1,82 @@
+import { APPROVAL_ANSWER_EVENT, bridgeApprovalSignal, createApprovalService } from '../safety/index.js';
+/**
+ * 组装会话审批三件的前两件。@returns 装配产物（settlePending 归驱动 run 终态
+ * 调用——04 §3 终态=结算边界；dispose 归会话拆除）。
+ */
+export function wireSessionApproval(opts) {
+    /** 挂起 ask 簿记（本会话 answerer 在身的问询——settlePending 收口对象） */
+    const pending = new Set();
+    const service = createApprovalService(opts.dispatch, {
+        ownership: { sessionId: opts.sessionId },
+        ...(opts.policy !== undefined ? { policy: opts.policy } : {}),
+        ...(opts.persistToolPolicy !== undefined ? { persistToolPolicy: opts.persistToolPolicy } : {}),
+        // 审批对 durable 落账（05 §1.1 词行 data 形与 sink 载荷一一对应）
+        sink: {
+            asked: (payload) => opts.session.append('approval/asked', payload),
+            decided: (payload) => opts.session.append('approval/decided', payload),
+        },
+    });
+    const off = opts.dispatch.onWaterfall(APPROVAL_ANSWER_EVENT, async (input, next) => {
+        // 归属路由（恰一键条款）：他会话的 ask 不接——交棒下游（他会的 answerer
+        // 或全链无答 unavailable），不越权代答
+        if (input.req.ownership?.sessionId !== opts.sessionId)
+            return next(input);
+        // 呈现面缺席：本行不答（交棒；全链无答 = fail-closed unavailable）
+        if (opts.askApproval === undefined)
+            return next(input);
+        // run 信号桥（04 §9 run 信号透传）：已 abort 的 signal 同步触发
+        const controller = new AbortController();
+        const unbridge = bridgeApprovalSignal(input.req, controller);
+        // 挂起簿记 + 收口竞速：settlePending 先胜 = 无答案（迟到答案被弃）
+        let settleAsk;
+        const settled = new Promise((resolve) => {
+            settleAsk = resolve;
+        });
+        const entry = { settle: settleAsk };
+        pending.add(entry);
+        let answer;
+        try {
+            answer = await Promise.race([
+                // 呈现面异常 = 无答案（不答交棒——fail-closed 由 service 全链无答承担）
+                opts.askApproval(toAskRequest(input.req), { signal: controller.signal }).catch(() => undefined),
+                settled,
+            ]);
+        }
+        finally {
+            pending.delete(entry);
+            unbridge();
+        }
+        if (answer !== undefined) {
+            input.answer = answer; // 能答短路（不调 next——本链应答位；可变载荷就地写）
+            return input;
+        }
+        return next(input);
+    });
+    return {
+        approval: service,
+        settlePending() {
+            // turn 界闭合：统一无答案（service 落 unavailable）——通道没了问也无从答
+            for (const entry of [...pending])
+                entry.settle(undefined);
+        },
+        dispose() {
+            off();
+        },
+    };
+}
+/**
+ * safety ApprovalRequest → 呈现载荷（contracts/approval 单源形）：
+ * suggestedEntry 草案对象折人可读一行（`<tool> <pattern>`——面板展示面，
+ * 回写走 persistToolPolicy 的结构形草案，不经本串）。
+ */
+function toAskRequest(req) {
+    return {
+        summary: req.summary,
+        ...(req.reason !== undefined ? { reason: req.reason } : {}),
+        ...(req.toolName !== undefined ? { toolName: req.toolName } : {}),
+        ...(req.approvalId !== undefined ? { approvalId: req.approvalId } : {}),
+        ...(req.suggestedEntry !== undefined
+            ? { suggestedEntry: `${req.suggestedEntry.tool} ${req.suggestedEntry.pattern}` }
+            : {}),
+    };
+}