berry-agent-sdk 0.1.0-alpha.2

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

@@ -0,0 +1,304 @@
+/**
+ * 会话事件信封与归因词汇类型（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 批落码定形）。
+ * 'process' 幽灵词已除（六役勘正笔：exec 子进程治理不走 Job 表登记——
+ * 联合零登记源词即除名，防随手字符串当 kind 用）。
+ */
+export type JobKind = 'subagent' | '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/src/contracts/types.js

@@ -0,0 +1,51 @@
+/** 字面量六值 → 归一化种类映射（前缀型经 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;
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/contracts/types.ts"],"names":[],"mappings":"AAqFA,0CAA0C;AAC1C,MAAM,oBAAoB,GAA8C;IACtE,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,kBAAkB,EAAE,kBAAkB;IACtC,2BAA2B,EAAE,2BAA2B;IACxD,iBAAiB,EAAE,iBAAiB;IACpC,UAAU,EAAE,YAAY;CACzB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,0CAA0C;QAC1C,iDAAiD;QACjD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;IAChE,CAAC;IACD,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,OAAO,EAAE,CAAC;QACZ,gDAAgD;QAChD,4DAA4D;QAC5D,wDAAwD;QACxD,yCAAyC;QACzC,MAAM,aAAa,GACjB,OAAO,KAAK,MAAM;YAClB,OAAO,KAAK,UAAU;YACtB,OAAO,KAAK,kBAAkB;YAC9B,OAAO,KAAK,2BAA2B;YACvC,OAAO,KAAK,iBAAiB,CAAC;QAChC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACvD,CAAC;IACD,4CAA4C;IAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC;AAgDD,wEAAwE;AAExE;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AA0NpC,KAAM,IAAiD,CAAC"}

package/dist/src/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/src/contracts/ui.js

@@ -0,0 +1,16 @@
+/**
+ * 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 {};
+//# sourceMappingURL=ui.js.map

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

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

package/dist/src/sdk/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * sdk/types — core:sdk HTTP 面契约（批 13e-1 契约先行）。
+ *
+ * 词面单源：端点路由与协议头（03 §10.6 批 13e 落码定形注①）/ 开面配置形
+ * （07 §5 serve 旗标族落码定名注——sock 缺省接入点、TCP 可选位、凭证 env
+ * 双载体三名）均在本件定形，传输实装（13e-2）与 daemon 装配（13e-3）只
+ * 消费不复制。
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { SdkWireDeps } from '../channels/index.js';
+/** HTTP 端点路由词面（03 §10.6 差异面①/批 13e 定形：程序调用面五 POST/GET + SSE 建立位） */
+export declare const SDK_HTTP_ENDPOINTS: {
+    /** POST——prompt 新发（sessionId 缺席即新建） */
+    readonly prompt: "/v1/prompt";
+    /** POST——interrupt（无应答档 HTTP 形 = 204 空体） */
+    readonly interrupt: "/v1/interrupt";
+    /** POST——审批应答（跨入口竞速回执） */
+    readonly decide: "/v1/decide";
+    /** POST——断线对账读面（since 窗口 (since, 高水位]） */
+    readonly entries: "/v1/entries";
+    /** GET——会话清单 */
+    readonly sessions: "/v1/sessions";
+    /** GET SSE——事件流建立位（即 hello 动词的 HTTP 承载：sessionId/after/noDelta 入查询参） */
+    readonly events: "/v1/events";
+};
+/** 协议版本头名（HTTP 无连接级 hello 位——每请求携版本，不符即 400 SDK_PROTOCOL_MISMATCH） */
+export declare const SDK_PROTOCOL_HEADER = "x-sdk-protocol";
+/** 鉴权头（10.4「监听 ⇒ 鉴权」恒在场——Bearer 形携 token） */
+export declare const SDK_AUTH_HEADER = "authorization";
+/** TCP 监听位形（单监听 spec——config.tcp 收单形或数组，内部归一数组执法） */
+export interface SdkTcpListenSpec {
+    readonly host: string;
+    readonly port: number;
+}
+/**
+ * sdk HTTP 面开面配置（07 §5 落码定名批 13e；18a-1' 多监听扩形——03 §10.6
+ * 路由扩展位段「sock 可缺席 + TCP×N」）。
+ *
+ * 监听器族多监听并存：sock 可选（缺席 = 不开——webui 人面 --port 独占 TCP 形
+ * 时 daemon 可无 sock）；TCP 侧收单形或数组（归一执法）。非回环 host 必配
+ * 凭证 fail-closed 拒启（03 §10.6 差异面③「非回环 ⇒ 必配鉴权凭证」不豁免）。
+ */
+export interface SdkHttpListenConfig {
+    /** Unix-domain socket 监听路径（daemon 形缺省接入点——02 数据域表 serve/ 行；可选化：缺席不开 sock） */
+    readonly socketPath?: string;
+    /** TCP 可选位（--sdk-port/--sdk-host 或 env 双载体；单形或数组形——缺席 = 不开 TCP） */
+    readonly tcp?: SdkTcpListenSpec | readonly SdkTcpListenSpec[];
+    /**
+     * 预置共享密钥（BERRY_AGENT_SDK_TOKEN——差异面⑤ env 载体）。缺席 = 监听面
+     * 自足生成进程内一次性 token（只存内存不落盘），经披露面出（daemon 形 =
+     * daemon 日志文件 / 前台形 = stderr）。
+     */
+    readonly token?: string;
+}
+/** 13e-2 传输实装的装配注入面（宿主装配桥同形——decideApproval/onSubscribed 后端自持、sink 传输自持；件不 import 宿主） */
+export type SdkHttpBridge = Omit<SdkWireDeps, 'decideApproval' | 'onSubscribed' | 'sink'>;
+/** 心跳看门狗节拍（10.4 同律：SSE 注释行 ping 每 30s + 写侧 90s 判死） */
+export declare const SDK_SSE_PING_INTERVAL_MS = 30000;
+/** SSE 写侧看门狗判死窗（ping 写失败或写超时即 reap 连接——读侧判死不可实施） */
+export declare const SDK_SSE_WRITE_TIMEOUT_MS = 90000;
+/**
+ * open 档合法语义位闭集（射界枚举钉死——注册期白名单校验、越界即拒 fail-loud，
+ * 代码可执法非仅冷读审读）：
+ * - `liveness`——探活（GET /api/health 形：零敏感面应答）；
+ * - `auth-exchange`——鉴权换证（POST /api/auth 形：token 换 cookie 桥）；
+ * - `static-shell`——静态壳（SPA 静态面 + fallback：壳先于鉴权必须可载）。
+ */
+export declare const SDK_ROUTE_OPEN_PURPOSES: readonly ["liveness", "auth-exchange", "static-shell"];
+/** open 档语义位（闭集成员——SDK_ROUTE_OPEN_PURPOSES 单源） */
+export type SdkRouteOpenPurpose = (typeof SDK_ROUTE_OPEN_PURPOSES)[number];
+/**
+ * 扩展路由鉴权档（四值——03 §10.6）：
+ * - `'token'`——Bearer 判（面 token 验换位 verifyToken 常时比对）；
+ * - `{mode:'token-or-cookie', cookie}`——Bearer ∪ HttpOnly cookie 双通道（EventSource
+ *   结构性无 Authorization 头——浏览器侧唯一凭证通道；恒时比对）；
+ * - `{mode:'open', purpose}`——跳 token 闸（射界枚举钉死三类语义位——注册期校验）；
+ * - `'self'`——跳面 token 闸、件侧自验（issue webhook HMAC 位——Host/Origin 防线
+ *   仍面级先行，self 只跳 token 闸）。
+ */
+export type SdkRouteAuth = 'token' | {
+    readonly mode: 'token-or-cookie';
+    readonly cookie: string;
+} | {
+    readonly mode: 'open';
+    readonly purpose: SdkRouteOpenPurpose;
+} | 'self';
+/** 面级 SSE 流（openSse 产物——write 即 `data: <单行 JSON>` 帧合成钉死；close 幂等） */
+export interface SdkRouteSseStream {
+    /** 帧写入（载荷整体单次 JSON.stringify 单行——禁手工拼帧）；背压期 droppable 载荷 shedding */
+    write(data: unknown): void;
+    /** 终结（幂等——连接 close / 看门狗 / 宿主 stop 三路共用） */
+    close(): void;
+}
+/** openSse 选项（背压 shedding 谓词注入——各消费面自定可丢档） */
+export interface SdkRouteSseOptions {
+    /** 背压期可丢判据（缺席 = 不 shedding——线控/关键帧永不丢档） */
+    readonly droppable?: (data: unknown) => boolean;
+}
+/** ctx.readBody 结果（排空纪律内含——超帽 ok:false 在体收完后才返回） */
+export type SdkRouteBodyResult = {
+    readonly ok: true;
+    readonly body: string;
+} | {
+    readonly ok: false;
+    readonly status: 413;
+    readonly message: string;
+};
+/** 扩展路由 handler 上下文（面级 helper 单源——03 §10.6「面级 helper ctx 单源」） */
+export interface SdkRouteContext {
+    /** `:param` 段提取（匹配期注入——非参数路由恒空对象） */
+    readonly params: Readonly<Record<string, string>>;
+    /** catch-all 尾吞的原始路径形（非 catch-all 路由恒 undefined；SPA fallback 承载位） */
+    readonly wildcard: string | undefined;
+    /** 面级 SSE 开流（帧形单行 JSON/ping 30s/写侧看门狗 90s/shedding 谓词注入/幂等 close——面 stop 全流收口） */
+    openSse(res: ServerResponse, opts?: SdkRouteSseOptions): SdkRouteSseStream;
+    /** 读请求体（排空纪律——超帽 413 永不早于请求体收完防连接池 RST 连坐；帽 = descriptor.bodyLimitBytes ?? 面缺省） */
+    readBody(req: IncomingMessage): Promise<SdkRouteBodyResult>;
+    /** 面 token 验换（sha256 摘要恒长 + timingSafeEqual——面 token 唯一验换位；cookie 桥/Bearer 共用） */
+    verifyToken(value: string): boolean;
+}
+/** 扩展路由 handler（三参定形——03 §10.6 路由描述符条款） */
+export type SdkRouteHandler = (req: IncomingMessage, res: ServerResponse, ctx: SdkRouteContext) => void | Promise<void>;
+/**
+ * 扩展路由 HTTP 方法词面（七值闭集——method+path 双键匹配的 method 侧；
+ * U5-1 起独立立名：插件道描述符子集形（plugin-routes.ts）同词面复用，
+ * 七值单源不再内联两处）。
+ */
+export type SdkRouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+/** 路由描述符（03 §10.6——path 段式 `:param` + 至多一枚 catch-all 通配尾 `*`） */
+export interface SdkRouteDescriptor {
+    /** HTTP 方法（method+path 双键匹配） */
+    readonly method: SdkRouteMethod;
+    /** 段式路径：`/api/sessions/:id/submit` 形；`*` 单独成 path = 吞一切（SPA fallback）；`/*` 尾 = 吞余段 */
+    readonly path: string;
+    /** 鉴权档（四值——SdkRouteAuth） */
+    readonly auth: SdkRouteAuth;
+    /** 恒回环可达标记（非回环 TCP 监听器不挂载——404 同未注册 + start warn；sock/回环 TCP 挂全路由） */
+    readonly loopbackOnly?: boolean;
+    /** per-route 请求体帽（缺席 = 面缺省 10 MiB；webui 族 256KiB 位） */
+    readonly bodyLimitBytes?: number;
+    readonly handler: SdkRouteHandler;
+}
+/** 路由注册器（两注册入口共享：SdkHttpFaceOptions.routes 构造期 + handle.register 晚注册——claim 桥同款晚绑）；返摘除 fn */
+export type SdkRouteRegistrar = (descriptor: SdkRouteDescriptor) => () => void;