berry-agent 0.1.0-alpha.1

package/dist/conversation/backoff.js

@@ -0,0 +1,38 @@
+/**
+ * 指数退避 + 等比半幅抖动（04 §3.3 条 4 定式）。
+ * @param base 基值 ms（RetryPolicyConfig.baseDelayMs）
+ * @param attempt 第几次重试（1 起——指数位 n-1）
+ * @param random 随机源（缺省 Math.random；测试注确定性源）
+ * @returns 实延迟 ms——恒 ∈ [base·2^(n-1)·0.5, base·2^(n-1)），下界恒 > 0
+ */
+export function jitteredBackoff(base, attempt, random = Math.random) {
+    const scale = base * 2 ** (attempt - 1);
+    return scale * (0.5 + random() * 0.5);
+}
+/** 按策略计算某次重试的实延迟（抖动内联——runTurns 重试腿的取值口） */
+export function retryDelay(policy, attempt, random = Math.random) {
+    return jitteredBackoff(policy.baseDelayMs, attempt, random);
+}
+/**
+ * 可中止睡眠（退避挂 abort signal 的执法位）。
+ * @param ms 时长 @param signal 中止信号（已中止/中途触发都即时收场）
+ * @returns true = 睡满；false = 被中止（打断即取消重试）
+ */
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve(false);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolve(false);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve(true);
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/conversation/codes.js

@@ -0,0 +1,47 @@
+/**
+ * conversation 域操控面错误码注册（02 §5.3 SESSION_ 族操控四码——2026-09-08
+ * e-1 规范先行批明列；03 §2.2 第十一面三动词执法承载；本批 e-4 落码兑现
+ * 「词先锚定、落码随 e-4」）。
+ *
+ * 四码分层：SESSION_TARGET_NOT_FOUND 是三动词共同幽灵守卫（目标会话 id 无
+ * 对应行——GOAL_NOT_FOUND 同构；词面避撞批 13b SDK 面 SESSION_NOT_FOUND
+ * 〔module 段 session〕，e-1 冷读闸 blocker 处置案 a）；SESSION_INACTIVE 管
+ * interrupt 打断无对象（响亮拒不静默 no-op）；SESSION_TURN_STALE 管
+ * expectedTurnId 乐观并发位翻页拒（codex expected_turn_id 形）；SESSION_ROUND_LIMIT
+ * 管 a2a 回合护栏帽拒（缺省 5、人面输入重置链深）。第五码 SESSION_CONTROL_DENIED
+ * 管操控门检拒（sessions.control-cross 全域同门——操控轴无树内豁免；e-4
+ * 落码批 02 §5.3 同笔扩册，SESSION_OBSERVE_DENIED 同构先例）。
+ *
+ * module 段 conversation——SESSION_ 前缀系跨功能域共用前缀（session 模块
+ * 既有码族/批 13b SDK 面裸码〔module 段 session〕/obs 观测两码〔module 段
+ * obs〕与本族四码分域并存——02 §5.3 跨功能域共用前缀注）。
+ * 本文件由模块公开面 index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'SESSION_TARGET_NOT_FOUND',
+        module: 'conversation',
+        description: '操控动词目标会话 id 无对应行——幽灵守卫（GOAL_NOT_FOUND 同构；send/interrupt/withdraw 三动词共同前置，03 §2.2 第十一面。词面避撞：批 13b SDK 面 SESSION_NOT_FOUND 在册〔module 段 session——prompt 显式 sessionId 无对应会话〕，两码语义分立故带 TARGET 段）',
+    },
+    {
+        code: 'SESSION_INACTIVE',
+        module: 'conversation',
+        description: 'interrupt 作用目标无在飞 run 拒——打断无对象，响亮拒不静默 no-op（03 §2.2 第十一面 interrupt）',
+    },
+    {
+        code: 'SESSION_TURN_STALE',
+        module: 'conversation',
+        description: '乐观并发位 expectedTurnId 给定而目标 turn 已翻页拒（「说完话世界已变」显式化——静默错投比响亮拒更险；codex expected_turn_id 形，03 §2.2 第十一面 send）',
+    },
+    {
+        code: 'SESSION_ROUND_LIMIT',
+        module: 'conversation',
+        description: 'a2a 回合护栏帽拒——跨会话 send 链深超帽（缺省 5、人面输入重置链深，03 §2.2 第十一面回合护栏）',
+    },
+    {
+        code: 'SESSION_CONTROL_DENIED',
+        module: 'conversation',
+        description: '操控门未开门拒——高危面 sessions.control-cross（03 §4.6 v1 首批第六枚）门检执法位拒：操控轴无树内豁免、全域同门（03 §2.2 第十一面门制句），send/interrupt/withdraw 三动词共同前置（幽灵守卫之后）；SESSION_OBSERVE_DENIED 同构门检拒码先例（2026-09-08 e-4 落码批 02 §5.3 同笔扩册）',
+    },
+]);

package/dist/conversation/control-tools.js

@@ -0,0 +1,102 @@
+/**
+ * conversation — 跨会话操控工具族（03 §2.2 第十一面模型道——e-4 落码）：
+ * 宿主内建固定三件 `session_send` / `session_interrupt` / `session_withdraw`
+ * （`session_` 前缀保留字〔03 §2.7〕的宿主侧落位，与 obs 观测四件同段）。
+ *
+ * **双面同源**（题 7 拍板）：本族 = sessions-control 受理器（control.ts
+ * createSessionsControl——动词语义/执法序单源）的**薄包装**——工具 execute
+ * 只做 caller 归因闭包（{kind:'session', sessionId}——per-session 装配位
+ * 注入，模型无法伪造送话身份）+ 回执 JSON 呈报；幽灵守卫/门检/链深帽/
+ * TURN_STALE 全在受理器（拒码 BaseError 经 guard 折 `[CODE] message`
+ * isError——与 obs 工具族同形）。
+ *
+ * 恒挂载律（03 §2.2 第十一面同款）：模型可见清单恒在，不随门开合动态挂载
+ * ——门检在受理器内执法（拒 = SESSION_CONTROL_DENIED 自描述文案）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { Type } from 'typebox';
+/** execute 统一包装：受理器 BaseError 折 `[CODE] message` isError（obs guard 同形） */
+function guard(body) {
+    return body().catch((error) => {
+        if (error instanceof BaseError) {
+            return {
+                content: [{ type: 'text', text: `[${error.code}] ${error.message}` }],
+                isError: true,
+            };
+        }
+        throw error;
+    });
+}
+/** 回执 JSON 呈报（类型化回执词结构化转写——不虚构不改写） */
+function receiptText(receipt) {
+    return { content: [{ type: 'text', text: JSON.stringify(receipt) }] };
+}
+/** createControlTools 工厂（装载位/测试唯一入口）——三件定义数组 */
+export function createControlTools(deps) {
+    const { callerSessionId, control } = deps;
+    return [
+        {
+            name: 'session_send',
+            description: '向另一会话发送消息（跨会话 a2a 协作）。回执三态：delivered（已投递起跑/停摆落账）、' +
+                'queued（目标忙已入列——可经 session_withdraw 撤回）、dropped（拒收）。' +
+                '需高危面 sessions.control-cross 开门（全域同门——同树目标同样要开门）。' +
+                'a2a 链深帽缺省 5（连续代理互搏拒 SESSION_ROUND_LIMIT——目标会话收到人面输入即重置）；' +
+                'expectedTurnId 可选乐观并发位（= 目标最近 turn/start 事件 seq——不匹配拒 SESSION_TURN_STALE）；' +
+                'dedupeKey 可选幂等位（重试场景携稳定键——同键重复发送返原回执不重复注入）。',
+            parameters: Type.Object({
+                sessionId: Type.String({ description: '目标会话 id' }),
+                text: Type.String({ description: '注入文本（非空）' }),
+                expectedTurnId: Type.Optional(Type.Number({ description: '乐观并发位：目标 durable 日志最近 turn/start 事件 seq（可选）' })),
+                dedupeKey: Type.Optional(Type.String({ description: '幂等键（可选——同键重复 send 返原回执不重复注入；须调用方自铸唯一）' })),
+            }, { additionalProperties: false }),
+            effect: 'write',
+            execute: async (args) => guard(async () => {
+                const receipt = await control.send({
+                    caller: { kind: 'session', sessionId: callerSessionId },
+                    targetSessionId: args.sessionId,
+                    text: args.text,
+                    ...(args.expectedTurnId !== undefined ? { expectedTurnId: args.expectedTurnId } : {}),
+                    ...(args.dedupeKey !== undefined ? { dedupeKey: args.dedupeKey } : {}),
+                });
+                return receiptText(receipt);
+            }),
+        },
+        {
+            name: 'session_interrupt',
+            description: '打断目标会话的在飞 run（协作中止——目标 turn 以 interrupted 收口）。' +
+                '目标无在飞 run 拒 SESSION_INACTIVE（响亮拒不静默 no-op）。' +
+                '回执含 stillQueued（打断后在队操控件 id 清单——可逐件 session_withdraw 撤回）' +
+                '与 queuedCount（在队总数——在队件保留在队、下次续跑作种子，打断不清队）。' +
+                '需高危面 sessions.control-cross 开门（全域同门）。',
+            parameters: Type.Object({ sessionId: Type.String({ description: '目标会话 id' }) }, { additionalProperties: false }),
+            effect: 'write',
+            execute: async (args) => guard(async () => {
+                const receipt = await control.interrupt({
+                    caller: { kind: 'session', sessionId: callerSessionId },
+                    targetSessionId: args.sessionId,
+                });
+                return receiptText(receipt);
+            }),
+        },
+        {
+            name: 'session_withdraw',
+            description: '撤回本会话先前经 session_send 排入目标队列的消息（在队撤回对称闭环）。' +
+                'messageId 取 session_send 回执。回执两态：withdrawn（在队已移除）、' +
+                'delivered（已出队/从未在队——诚实呈报不虚构撤回成功）。' +
+                '需高危面 sessions.control-cross 开门（全域同门）。',
+            parameters: Type.Object({
+                sessionId: Type.String({ description: '目标会话 id' }),
+                messageId: Type.String({ description: 'send 回执所铸消息 id（msg-<n> 形）' }),
+            }, { additionalProperties: false }),
+            effect: 'write',
+            execute: async (args) => guard(async () => {
+                const receipt = await control.withdraw({
+                    caller: { kind: 'session', sessionId: callerSessionId },
+                    targetSessionId: args.sessionId,
+                    messageId: args.messageId,
+                });
+                return receiptText(receipt);
+            }),
+        },
+    ];
+}

package/dist/conversation/control.js

@@ -0,0 +1,210 @@
+/**
+ * conversation — 跨会话操控面（03 §2.2 第十一面 `sessions-control`——e-1
+ * 规范先行批立面、2026-09-08 e-4 落码批兑现、2026-09-09 e-5 收口批定形）。
+ *
+ * **双面同源**（题 7 拍板）：模型走宿主内建固定工具族（`session_send` /
+ * `session_interrupt` / `session_withdraw`——恒挂载不随门开合动态挂载），
+ * 插件代码走 `ctx.get("sessions-control")` 服务面；**两面同一实现源**——
+ * 工具 = 服务面薄包装，动词语义单源本文件（受理器 + 契约）。
+ *
+ * 三动词（共同前置：幽灵守卫 `SESSION_TARGET_NOT_FOUND` → 门检
+ * `SESSION_CONTROL_DENIED`〔操控轴无树内豁免、全域同门〕→ …动词各自位）：
+ *  - `send`：跨会话输入注入——发送方不选通道（04 §4 三通道路由驱动侧
+ *    单源：idle→followUp 起跑 / busy→steer 合批 / 停摆→inject 带入），
+ *    回执 = 入列回执（被丢/被拒项呈报不静默）；`expectedTurnId?` 乐观
+ *    并发位（翻页拒 `SESSION_TURN_STALE`）；a2a 链深超帽拒
+ *    `SESSION_ROUND_LIMIT`；`dedupeKey?` 幂等位（e-5 定案——同键重复
+ *    send 返原回执不重复注入，键域按调用方身份分域）。
+ *  - `interrupt`：打断目标在飞 run（turn 终态 interrupted）；无在飞拒
+ *    `SESSION_INACTIVE`（响亮拒不静默 no-op）。回执含 still_queued 后果
+ *    清单（e-5 定形：在队操控件 id 清单 + 在队总数计数——打断只打断当前
+ *    run，在队 steer 件保留在队、下次 followUp 作种子续跑）。
+ *  - `withdraw`：在队撤回对称闭环（题 9 缺省案 e-5 呈拍确认维持：已出队
+ *    'delivered' no-op 诚实回执，不虚构撤回成功）。
+ *
+ * **provenance 盖章单源**（05 §3.1）：注入的 user/message `source` 由本
+ * 受理面按调用方身份（ControlCaller）铸——模型工具道 `session:<送话会话id>`、
+ * 插件服务道 `plugin:<插件id>`（既有前缀复用）；**调用方传入面无 source
+ * 参数位**——伪造结构性不存在。
+ */
+import { BaseError } from '../contracts/index.js';
+import { adjudicateCapabilityDoor } from '../contracts/api.js';
+/** 操控轴高危面名（03 §4.6 v1 首批第六枚——操控全域无树内豁免，两轴分立） */
+export const CONTROL_CROSS_CAPABILITY = 'sessions.control-cross';
+/** 服务面名（scope.provide 键——插件经 `ctx.get("sessions-control")` 消费） */
+export const SESSIONS_CONTROL_SERVICE = 'sessions-control';
+/** a2a 回合护栏帽缺省（03 §2.2 第十一面题 8 呈拍定案：缺省 5 对齐 openclaw；装配可覆盖） */
+export const A2A_ROUND_LIMIT_DEFAULT = 5;
+/**
+ * send 幂等近期窗帽（e-5 定案——与队列帽同数 100：同键重复 send 返原回执
+ * 的查重窗容量；超帽逐最旧〔Map 插入序〕。内存位不承诺跨进程——与队列/
+ * a2a 深度位同语义）。
+ */
+export const SEND_DEDUPE_WINDOW_CAPACITY = 100;
+/**
+ * 受理面铸 source（provenance 盖章——05 §3.1；唯一合法铸位：driver.submit
+ * 对 `session:` 前缀 fail-loud 拒，结构性杜绝绕受理面伪造）。
+ */
+export function controlSourceOf(caller) {
+    return caller.kind === 'session' ? `session:${caller.sessionId}` : `plugin:${caller.pluginId}`;
+}
+/**
+ * 操控受理器工厂（双面同源的单源实现位——03 §2.2 第十一面 e-4 落码）：
+ * 宿主内建工具族（模型道）与 `ctx.get("sessions-control")`（插件道）都调
+ * 本件返回的 SessionsControlFace，动词语义/执法序单源在此。
+ *
+ * 受理序（send）：幽灵守卫 → 操控门检（全域）→ a2a 链深帽 →
+ * expectedTurnId 对拍 → 投递（auto-open：目标未 open 即 resume 打开——
+ * 发送方不应被要求先手动打开目标）→ capability/used 审计；
+ * interrupt/withdraw：幽灵守卫 → 门检 → 动词位（interrupt 不 auto-open——
+ * 打断休眠会话无在飞可打；withdraw 不 auto-open——队列是内存态，休眠无队）。
+ */
+export function createSessionsControl(deps) {
+    const roundLimit = deps.roundLimit ?? A2A_ROUND_LIMIT_DEFAULT;
+    /** 撤回关联键铸造位（栈级自增——受理器栈内唯一，跨会话可对账） */
+    let messageSeq = 0;
+    /**
+     * send 幂等近期窗（e-5 定案）：分域键 = `<caller 前缀>|<dedupeKey>` →
+     * 原回执。仅成功回执入窗（拒路径不入——重试须重新走受理序）；命中前置
+     * 返原回执（零新注入零新审计——回执重放非新受理）。超帽逐最旧（Map
+     * 插入序）。内存位：崩溃重启即丢（与队列/a2a 深度位同语义——幂等承诺
+     * 不跨进程）。
+     */
+    const dedupeWindow = new Map();
+    /** 幽灵守卫（三动词共同前置①——目标 id 无对应行，进程内 ∪ durable） */
+    const guardTarget = (verb, targetSessionId) => {
+        if (!deps.manager.exists(targetSessionId)) {
+            throw new BaseError('SESSION_TARGET_NOT_FOUND', `操控动词 ${verb} 的目标会话 ${targetSessionId} 不存在（进程内与 durable 均无对应行）`);
+        }
+    };
+    /**
+     * 操控门检（三动词共同前置②——全域同门无树内豁免，03 §2.2 第十一面门制句）。
+     * 门检输入 = caller 感知合成（开门制扩展批——deps.getOpensFor(caller)：
+     * 插件道 doors 段 ∪ 该插件行 opens、模型道 doors 段单独）。
+     */
+    const enforceDoor = (verb, targetSessionId, caller) => {
+        const verdict = adjudicateCapabilityDoor(deps.getOpensFor(caller), CONTROL_CROSS_CAPABILITY);
+        if (!verdict.ok) {
+            throw new BaseError('SESSION_CONTROL_DENIED', `${verdict.message}（动词 ${verb}，目标会话 ${targetSessionId}——操控轴无树内豁免）`);
+        }
+    };
+    /** capability/used 逐次审计（门开后行使即记——拒路径未获许可不记） */
+    const audit = (verb, input, caller) => {
+        deps.onCapabilityUsed?.({
+            capability: CONTROL_CROSS_CAPABILITY,
+            verb,
+            targetSessionId: input.targetSessionId,
+            ...(caller.kind === 'session' ? { callerSessionId: caller.sessionId } : { pluginId: caller.pluginId }),
+        });
+    };
+    /**
+     * send 幂等窗入位（仅成功回执——e-5 定案）：分域键铸造 + 超帽逐最旧。
+     * 命中查询在 send 入口前置（见 send 体）。
+     */
+    const rememberSend = (dedupeKey, caller, receipt) => {
+        const key = `${controlSourceOf(caller)}|${dedupeKey}`;
+        if (dedupeWindow.size >= SEND_DEDUPE_WINDOW_CAPACITY) {
+            // 逐最旧（Map 迭代序 = 插入序——首个键即最旧）
+            dedupeWindow.delete(dedupeWindow.keys().next().value);
+        }
+        dedupeWindow.set(key, receipt);
+    };
+    return {
+        async send(input) {
+            // 空文本拒收（契约位——空文本是调用方 bug，非业务拒不造码）
+            if (input.text.trim() === '') {
+                throw new Error('send 拒收空文本（调用方 bug——注入文本非空是调用方契约）');
+            }
+            // —— 幂等命中前置（e-5 定案）：同键重复 send 返原回执不重复注入。
+            // 前置于幽灵/门检——首次受理已成功，重试就该幂等返原果（重试时世界
+            // 变化不该让已成功的逻辑发送吃新拒码）；命中 = 回执重放非新受理，
+            // 零新注入零新审计
+            if (input.dedupeKey !== undefined) {
+                const prior = dedupeWindow.get(`${controlSourceOf(input.caller)}|${input.dedupeKey}`);
+                if (prior !== undefined)
+                    return prior;
+            }
+            guardTarget('send', input.targetSessionId);
+            enforceDoor('send', input.targetSessionId, input.caller);
+            // —— a2a 链深帽（03 §2.2 第十一面回合护栏）：送话方深度+1 超帽拒。
+            // 插件服务道起跳链深 1（插件直唤即第一跳）；送话会话未 open 按 0——
+            // 与「崩溃重启归零」同语义（内存位不承诺跨进程精确保留，护栏目的已达）
+            const callerDepth = input.caller.kind === 'session' ? (deps.manager.driverOf(input.caller.sessionId)?.a2aDepth ?? 0) : 0;
+            const newDepth = callerDepth + 1;
+            if (newDepth > roundLimit) {
+                throw new BaseError('SESSION_ROUND_LIMIT', `跨会话 send 链深 ${newDepth} 超回合护栏帽 ${roundLimit}（a2a 互搏环——人面输入重置链深）`);
+            }
+            // —— auto-open 投递腿：目标未 open 即 resume 打开（幂等 open——单焦点
+            // 不造第二附着）；expectedTurnId 对拍用活体 durable 日志尾扫（单源）
+            const driver = deps.manager.driverOf(input.targetSessionId) ?? deps.manager.open(input.targetSessionId).driver;
+            if (input.expectedTurnId !== undefined && input.expectedTurnId !== lastTurnStartSeq(driver)) {
+                throw new BaseError('SESSION_TURN_STALE', `目标会话 ${input.targetSessionId} 的 turn 已翻页（期望最近 turn/start seq=${input.expectedTurnId}，实际 ${String(lastTurnStartSeq(driver))}——说完话世界已变）`);
+            }
+            const messageId = `msg-${(messageSeq += 1)}`;
+            const message = {
+                role: 'user',
+                content: input.text,
+                timestamp: Date.now(),
+                source: controlSourceOf(input.caller),
+            };
+            const receipt = driver.deliverControl(message, messageId, newDepth);
+            // 幂等窗入位（仅成功回执——三态都是「受理完成」面；拒路径已在上方 throw 不至此）
+            if (input.dedupeKey !== undefined)
+                rememberSend(input.dedupeKey, input.caller, receipt);
+            audit('send', input, input.caller);
+            return receipt;
+        },
+        async interrupt(input) {
+            guardTarget('interrupt', input.targetSessionId);
+            enforceDoor('interrupt', input.targetSessionId, input.caller);
+            // 打断无对象响亮拒不静默 no-op（03 §2.2 第十一面 interrupt）——目标未
+            // open 必无在飞 run（休眠会话无 run），缺席 driver 同判
+            const driver = deps.manager.driverOf(input.targetSessionId);
+            if (driver === undefined || !driver.running) {
+                throw new BaseError('SESSION_INACTIVE', `目标会话 ${input.targetSessionId} 无在飞 run 可打断（休眠或已停摆）`);
+            }
+            driver.abort();
+            // —— still_queued 后果清单（e-5 定形）：打断只打断当前 run，在队件
+            // 保留在队（aborted 不续跑——下次 followUp 作种子续跑）。打断后取快照
+            // 呈报去向：操控件 id 清单（可 withdraw）+ 在队总数（含普通件计数）
+            const queued = driver.queuedItems();
+            audit('interrupt', input, input.caller);
+            return {
+                status: 'interrupted',
+                targetSessionId: input.targetSessionId,
+                stillQueued: queued.flatMap((item) => (item.id !== undefined ? [item.id] : [])),
+                queuedCount: queued.length,
+            };
+        },
+        async withdraw(input) {
+            guardTarget('withdraw', input.targetSessionId);
+            enforceDoor('withdraw', input.targetSessionId, input.caller);
+            // 队列是内存态：目标未 open / 已停摆清队 → 不在队恒真（'delivered'
+            // 诚实呈报——不虚构撤回成功）
+            const driver = deps.manager.driverOf(input.targetSessionId);
+            const withdrawn = driver?.withdrawQueued(input.messageId) ?? false;
+            audit('withdraw', input, input.caller);
+            return { status: withdrawn ? 'withdrawn' : 'delivered', messageId: input.messageId };
+        },
+    };
+}
+/**
+ * 逐插件绑定（plugin-boot fork 落位调用）：caller = {kind:'plugin', pluginId}
+ * 闭包铸造——插件传入面无 caller 位（传入即被覆写，伪造结构性不存在）。
+ */
+export function bindControlForPlugin(pluginId, face) {
+    return {
+        send: (input) => face.send({ ...input, caller: { kind: 'plugin', pluginId } }),
+        interrupt: (input) => face.interrupt({ ...input, caller: { kind: 'plugin', pluginId } }),
+        withdraw: (input) => face.withdraw({ ...input, caller: { kind: 'plugin', pluginId } }),
+    };
+}
+/** 目标 durable 日志最近 turn/start 事件 seq（expectedTurnId 对拍单源——尾扫；无 turn 返 undefined） */
+function lastTurnStartSeq(driver) {
+    const events = driver.session.events();
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        if (events[i].type === 'turn/start')
+            return events[i].seq;
+    }
+    return undefined;
+}