@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/hitl/resumeRunningCard.d.ts

@@ -1,134 +1,29 @@
-/**
- * hitl/resumeRunningCard.ts — **resume 撞上「上一轮还在跑」**时那张三选卡的判定 / 选项集 / 文案
- * (#265 上收件,2026-08-14;源形 = cli `src/sema/resumeRunningArm.ts` 的纯判定半场,编排腿留在端上)。
- *
- * ── 病与改形 ────────────────────────────────────────────────────────────────────────────────
- * resume 时读到一条 `running` 的 run,旧形是**客户端自己**给它打一枪 cancel(动机 = 僵尸烧 token)。
- * 矛盾:resume 时的 running run **不可判**是「用户要的在飞工作」还是「僵尸」—— 而实况里自动 cancel
- * 恰好是错的方向(用户批准之后 run 该继续跑,resume 时 cancel = 把刚救活的 run 又杀了)。血统纪律:
- * **破坏性动作恒不自动**。改形 = 把三条路交回用户:
- *   ① `Attach and watch`  —— 接管为当前 turn 输出;
- *   ② `Cancel it`         —— 那个动作降级为**用户按下**的选项;
- *   ③ `Leave it running in the background`(**默认焦点**)—— 零动作。
- *
- * ── §3.2a 活性证据的缺席纪律(不可削)──────────────────────────────────────────────────────
- * 判活体的 `msSinceLastActivity`(相对毫秒)在场 ⇒ 卡上渲一行「last activity Ns ago」;
- * **缺席 = 无法证明**(跨副本命中 / 副本重启后),不是「不活」—— 那一行**整行不渲**,绝不折成 0、
- * 绝不写成「已死」。
- *
- * ── §3.2b 无 UI 臂:退役自动 cancel 之后不许留死墙 ──────────────────────────────────────────
- * 「不自动 cancel + 没有卡可选」= 又一堵死墙。所以没有卡的形必须**显式定义臂**:恒不 cancel;
- * 输出**机读三选指路**({@link resumeRunningNoUiGuidance},attach / cancel / 后台留着三条路各给
- * 真实命令或 API 路径);headless 车道走**专码**退出({@link RESUME_RUNNING_NO_UI_EXIT_CODE});
- * 绝不静默挂起、绝不谎报成功。
- *
- * ── 🔴 塌缩纪律 ─────────────────────────────────────────────────────────────────────────────
- * Esc / 空答 / 认不出的自由文本 / 作答看门狗到点 / 呈卡失败 —— 一律收口成 ③(零动作)。
- * 破坏性动作只认**逐字命中**的显式选择({@link resumeChoiceFromLabels})。
- *
- * ── 🔴 假 affordance 禁令(按供给渲)───────────────────────────────────────────────────────
- * 一个按了没用的选项比没有这个选项更坏:durable `runs.events` 动词缺席**或**没有接管消费口 ⇒
- * ① 整个不渲;`runs.cancel` 缺席 ⇒ ② 整个不渲;两条都缺 ⇒ 一张卡都不铸,走 §3.2b 臂。
- *
- * ── 归层 ────────────────────────────────────────────────────────────────────────────────────
- * 本文件 = 纯判定 + 选项集 + 文案,**零 import**。呈卡口/动词切片/判活口/指路 sink/退出码应用口
- * 全部由端在装配点注入;端只剩装配与呈现。
- */
-/** ① 接管观看。 */
 export declare const RESUME_CHOICE_ATTACH_LABEL = "Attach and watch";
-/** ② 用户显式取消(自动 cancel 那个动作的降级形)。 */
 export declare const RESUME_CHOICE_CANCEL_LABEL = "Cancel it";
-/** ③ 后台留着 —— 🔴 **默认焦点**,所以它必须排在 options[0](见 {@link resumeRunningOptions})。 */
 export declare const RESUME_CHOICE_BACKGROUND_LABEL = "Leave it running in the background";
-/** 卡的 header(答案按 header 归键;本卡只有一问)。与 409 三选卡的入口刻意不同词 —— 同一张卡的
- *  两个入口,题面说的不是一件事。 */
 export declare const RESUME_CHOICE_HEADER = "Earlier run still in flight";
-/** 用户在 resume 变体卡上的决定。 */
 export type ResumeRunningChoice = 'attach' | 'cancel' | 'background';
-/**
- * 呈卡口的回执。🔴 `'unavailable'` 与 `'background'` **绝不合并**:前者 =「问都没问成」
- * (§3.2b 臂的入口:用户还欠一次告知),后者 =「问过了,用户选了什么都不做」(已经告知过)。
- * 合并的代价 = 一次呈现失败被静默当成用户的决定 —— 那正是 §3.2b 要封的死墙。
- */
 export type ResumeChoiceOutcome = ResumeRunningChoice | 'unavailable';
-/** 铸卡所需的全部材料(纯数据 —— 呈现层按它铸自己的卡/帧)。 */
 export interface ResumeRunningCardInput {
-    /** 那条还在跑的 run。 */
     taskId: string;
-    /** 引擎报的状态(如实转述,不加工)。 */
     status: string;
-    /** ① 可渲吗(= durable events 动词在场 **且** 有接管消费口)。 */
     canAttach: boolean;
-    /** ② 可渲吗(= `runs.cancel` 在场)。 */
     canCancel: boolean;
-    /** §3.2a 活性证据(null = 引擎没给 ⇒ 无法证明 ⇒ 那一行整行不渲)。 */
     msSinceLastActivity: number | null;
 }
-/** 一个选项(CC AskUserQuestionTool option 形)。 */
 export interface ResumeRunningCardOption {
     label: string;
     description: string;
 }
-/**
- * §3.2a 活性证据行。**缺席 ⇒ null(整行不渲)**;绝不渲 0、绝不渲「已死」。
- * 负数 / 非有限值同样按缺席处理(wire 位 UNTRUSTED,类型说是 number 也要真判)。
- */
 export declare function resumeRunningLivenessRow(msSinceLastActivity: number | null | undefined): string | null;
-/**
- * 卡的题面。第二行 = 活性证据(§3.2a 缺席时**整行消失**,不留占位、不留「unknown」字样 ——
- * 一行「last activity: unknown」和一行 0 一样是在替引擎回答一个它没回答的问题)。
- */
 export declare function resumeRunningQuestionText(i: ResumeRunningCardInput): string;
-/**
- * 选项集(同一张卡两个入口,选项集**按入口分形**)。
- *
- * 🔴 **顺序即默认焦点**:卡的渲染面 `focusedIndex` 初值恒 0,而 wire 的 `QuestionFrame` 里
- *    **没有**任何「默认焦点」位可传。所以「默认焦点 = ③ 后台留着」在结构上只有一个落法:把 ③ 排在
- *    options[0]。谁哪天为了「读起来顺」把 ①②③ 按序号排回去,默认焦点就漂到了 `Attach and watch`
- *    —— 一个手滑回车就把一条后台 run 接管到前台。常驻门逐位反钉这个顺序。
- */
 export declare function resumeRunningOptions(i: ResumeRunningCardInput): ResumeRunningCardOption[];
-/**
- * 答案 → 决定。🔴 只认**逐字命中**的标签;空答(overlay 的 Esc/dismiss 形)、多选、认不出的
- * 自由文本一律回落 ③ —— 破坏性动作只认显式选择(与 409 三选卡同律)。
- */
 export declare function resumeChoiceFromLabels(selected: readonly string[] | null | undefined): ResumeRunningChoice;
-/**
- * headless 车道撞 resume-running 的**专码**退出码。
- *
- * 为什么非 0:这一趟 resume **没有**把会话交到一个可用状态 —— 那条 run 还占着会话,脚本接下来
- * 提交什么都会撞 409。静默 0 = 谎报成功。
- * 为什么是 75:sysexits.h 的 `EX_TEMPFAIL`(「暂时性失败,请稍后重试」)语义正对 —— run 跑完
- * 或被取消之后同一条命令就能过;与 cli 既用的 0/1/2/129/143 零撞(脚本消费者据此可以把「会话被
- * 在飞 run 占住」与「真失败(1)」「用法错(2)」分臂)。
- */
 export declare const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
-/** 机读指路的行首标识 —— 脚本按它 grep;UI 改版不许动它。 */
 export declare const RESUME_RUNNING_GUIDANCE_TAG = "sema: resume-running:";
-/**
- * §3.2b 的**机读三选指路**。三条路各给真实命令或 API 路径,一条都不许省 ——
- * 少写一条 = 那条路在这个车道上被客户端单方面关掉了。
- *
- * 🔴 `attach=` 那一行只有在**真知道 session id** 时才给具体命令:不知道还硬拼一条
- * `sema --resume <sessionId>` 字面量,就是印一条按了没用的命令(假 affordance 的文本形)。
- */
 export declare function resumeRunningNoUiGuidance(i: {
     taskId: string;
     sessionId?: string | null;
 }): string;
-/**
- * ① 接管之前的**显式披露**。
- *
- * resume 入口没有 `lastEventId` 可用(端今天不持久化引擎事件锚),所以 durable 尾从这条 run 的
- * 第一帧读起 —— 崩溃前已落盘、已被 resume 还原到屏上的那一段会再渲一遍。续听腿那道「无锚 × 已上屏
- * ⇒ 不许从头续读」的门在这一格判不出来(它数的是**本条流**吐过几帧,resume 入口恒 0),所以不能
- * 拿它当安全证明。处置 = 说在前面:静默复读会让用户以为模型把同一段活干了两遍。
- *
- * 🔴 **账目面同源**:同一次重放也会把这条 run 已经执行过的每一个 `turn_end` 再喂一次成本累计器。
- *    客户端这一端证明不了哪一枚已经在恢复出来的总额里(那需要一本按 turn 落盘的账 —— 与缺席的
- *    事件锚是同一件移交残件),所以接管腿声明**不计账**。既然不计,就必须在**同一行**说清楚:
- *    只披露视觉复读、不披露账目缺口,用户拿成本面跟引擎账本对不上时只会怀疑客户端算错了。
- */
 export declare function resumeAttachReplayDisclosure(taskId: string): string;
-/** ② 打完 cancel 但引擎没确认落地时的如实一行(绝不谎报「已停止」)。 */
 export declare function resumeRunningCancelUnconfirmedRow(taskId: string): string;

package/dist/hitl/resumeRunningCard.js

@@ -1,86 +1,22 @@
-/**
- * hitl/resumeRunningCard.ts — **resume 撞上「上一轮还在跑」**时那张三选卡的判定 / 选项集 / 文案
- * (#265 上收件,2026-08-14;源形 = cli `src/sema/resumeRunningArm.ts` 的纯判定半场,编排腿留在端上)。
- *
- * ── 病与改形 ────────────────────────────────────────────────────────────────────────────────
- * resume 时读到一条 `running` 的 run,旧形是**客户端自己**给它打一枪 cancel(动机 = 僵尸烧 token)。
- * 矛盾:resume 时的 running run **不可判**是「用户要的在飞工作」还是「僵尸」—— 而实况里自动 cancel
- * 恰好是错的方向(用户批准之后 run 该继续跑,resume 时 cancel = 把刚救活的 run 又杀了)。血统纪律:
- * **破坏性动作恒不自动**。改形 = 把三条路交回用户:
- *   ① `Attach and watch`  —— 接管为当前 turn 输出;
- *   ② `Cancel it`         —— 那个动作降级为**用户按下**的选项;
- *   ③ `Leave it running in the background`(**默认焦点**)—— 零动作。
- *
- * ── §3.2a 活性证据的缺席纪律(不可削)──────────────────────────────────────────────────────
- * 判活体的 `msSinceLastActivity`(相对毫秒)在场 ⇒ 卡上渲一行「last activity Ns ago」;
- * **缺席 = 无法证明**(跨副本命中 / 副本重启后),不是「不活」—— 那一行**整行不渲**,绝不折成 0、
- * 绝不写成「已死」。
- *
- * ── §3.2b 无 UI 臂:退役自动 cancel 之后不许留死墙 ──────────────────────────────────────────
- * 「不自动 cancel + 没有卡可选」= 又一堵死墙。所以没有卡的形必须**显式定义臂**:恒不 cancel;
- * 输出**机读三选指路**({@link resumeRunningNoUiGuidance},attach / cancel / 后台留着三条路各给
- * 真实命令或 API 路径);headless 车道走**专码**退出({@link RESUME_RUNNING_NO_UI_EXIT_CODE});
- * 绝不静默挂起、绝不谎报成功。
- *
- * ── 🔴 塌缩纪律 ─────────────────────────────────────────────────────────────────────────────
- * Esc / 空答 / 认不出的自由文本 / 作答看门狗到点 / 呈卡失败 —— 一律收口成 ③(零动作)。
- * 破坏性动作只认**逐字命中**的显式选择({@link resumeChoiceFromLabels})。
- *
- * ── 🔴 假 affordance 禁令(按供给渲)───────────────────────────────────────────────────────
- * 一个按了没用的选项比没有这个选项更坏:durable `runs.events` 动词缺席**或**没有接管消费口 ⇒
- * ① 整个不渲;`runs.cancel` 缺席 ⇒ ② 整个不渲;两条都缺 ⇒ 一张卡都不铸,走 §3.2b 臂。
- *
- * ── 归层 ────────────────────────────────────────────────────────────────────────────────────
- * 本文件 = 纯判定 + 选项集 + 文案,**零 import**。呈卡口/动词切片/判活口/指路 sink/退出码应用口
- * 全部由端在装配点注入;端只剩装配与呈现。
- */
-// ── 逐字契约面(答案按 label 原样回声 —— 引擎的 `selected ⊆ options` 围栏,漂一个字节即失灵)──
-/** ① 接管观看。 */
 export const RESUME_CHOICE_ATTACH_LABEL = 'Attach and watch';
-/** ② 用户显式取消(自动 cancel 那个动作的降级形)。 */
 export const RESUME_CHOICE_CANCEL_LABEL = 'Cancel it';
-/** ③ 后台留着 —— 🔴 **默认焦点**,所以它必须排在 options[0](见 {@link resumeRunningOptions})。 */
 export const RESUME_CHOICE_BACKGROUND_LABEL = 'Leave it running in the background';
-/** 卡的 header(答案按 header 归键;本卡只有一问)。与 409 三选卡的入口刻意不同词 —— 同一张卡的
- *  两个入口,题面说的不是一件事。 */
 export const RESUME_CHOICE_HEADER = 'Earlier run still in flight';
-/**
- * §3.2a 活性证据行。**缺席 ⇒ null(整行不渲)**;绝不渲 0、绝不渲「已死」。
- * 负数 / 非有限值同样按缺席处理(wire 位 UNTRUSTED,类型说是 number 也要真判)。
- */
 export function resumeRunningLivenessRow(msSinceLastActivity) {
     const ms = msSinceLastActivity;
     if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0)
         return null;
     return `The engine last recorded activity on it ${String(Math.round(ms / 1000))}s ago.`;
 }
-/**
- * 卡的题面。第二行 = 活性证据(§3.2a 缺席时**整行消失**,不留占位、不留「unknown」字样 ——
- * 一行「last activity: unknown」和一行 0 一样是在替引擎回答一个它没回答的问题)。
- */
 export function resumeRunningQuestionText(i) {
     const head = `This conversation was resumed while an earlier turn is still executing on the engine ` +
         `(run ${i.taskId}, status ${i.status}). sema did not touch it. What should it do?`;
     const liveness = resumeRunningLivenessRow(i.msSinceLastActivity);
     return liveness === null ? head : `${head}\n${liveness}`;
 }
-/**
- * 选项集(同一张卡两个入口,选项集**按入口分形**)。
- *
- * 🔴 **顺序即默认焦点**:卡的渲染面 `focusedIndex` 初值恒 0,而 wire 的 `QuestionFrame` 里
- *    **没有**任何「默认焦点」位可传。所以「默认焦点 = ③ 后台留着」在结构上只有一个落法:把 ③ 排在
- *    options[0]。谁哪天为了「读起来顺」把 ①②③ 按序号排回去,默认焦点就漂到了 `Attach and watch`
- *    —— 一个手滑回车就把一条后台 run 接管到前台。常驻门逐位反钉这个顺序。
- */
 export function resumeRunningOptions(i) {
     const options = [
         {
-            // 🔴 默认焦点 —— 三条路里唯一零副作用的一条,所以它是手滑回车的落点。
-            // 🔴 措辞:这一项**不许**承诺「它会留在某个任务面板里」—— 这张卡的前提恰恰是「那条 run 活得
-            //    比上一个客户端进程久」,新进程里没有任何腿会为它建行(③ 的处置本身也是显式零动作)。
-            //    默认焦点上的一句假 affordance 是最坏的一格:手滑回车的人拿到一条既看不见、也停不掉、
-            //    还占着会话锁的 run。换成两句**可证的**真话:本屏不会列出它;它还占着会话,所以下一条
-            //    消息会再撞上它(那时 409 三选卡会带着 steer/cancel 两条真出路出现)。
             label: RESUME_CHOICE_BACKGROUND_LABEL,
             description: 'Leaves the run alone. It keeps executing on the engine, but this screen will not show it and it will not be listed here — your next message runs into it again, and sema asks you then.',
         },
@@ -88,10 +24,6 @@ export function resumeRunningOptions(i) {
     if (i.canAttach) {
         options.push({
             label: RESUME_CHOICE_ATTACH_LABEL,
-            // 🔴 第二句是**知情同意**那一半(见 {@link resumeAttachReplayDisclosure}):resume 入口没有
-            //    事件锚可用,durable 尾只能从这条 run 的第一帧读起,所以崩溃前已经落盘并被 resume 还原到
-            //    屏上的那一段会再出现一次。用户按下之前就得看见这句 —— 一个会做出用户没预料到的事的
-            //    选项,和一个按了没用的选项同样是假 affordance。
             description: 'Follows that run from here: sema replays it from the engine ledger and keeps streaming it into this conversation. ' +
                 'Anything from that turn already shown above will appear a second time — sema has no resume marker for it.',
         });
@@ -104,10 +36,6 @@ export function resumeRunningOptions(i) {
     }
     return options;
 }
-/**
- * 答案 → 决定。🔴 只认**逐字命中**的标签;空答(overlay 的 Esc/dismiss 形)、多选、认不出的
- * 自由文本一律回落 ③ —— 破坏性动作只认显式选择(与 409 三选卡同律)。
- */
 export function resumeChoiceFromLabels(selected) {
     if (!Array.isArray(selected) || selected.length !== 1)
         return 'background';
@@ -118,26 +46,8 @@ export function resumeChoiceFromLabels(selected) {
         return 'cancel';
     return 'background';
 }
-// ── §3.2b 无 UI 臂 ───────────────────────────────────────────────────────────────────────────
-/**
- * headless 车道撞 resume-running 的**专码**退出码。
- *
- * 为什么非 0:这一趟 resume **没有**把会话交到一个可用状态 —— 那条 run 还占着会话,脚本接下来
- * 提交什么都会撞 409。静默 0 = 谎报成功。
- * 为什么是 75:sysexits.h 的 `EX_TEMPFAIL`(「暂时性失败,请稍后重试」)语义正对 —— run 跑完
- * 或被取消之后同一条命令就能过;与 cli 既用的 0/1/2/129/143 零撞(脚本消费者据此可以把「会话被
- * 在飞 run 占住」与「真失败(1)」「用法错(2)」分臂)。
- */
 export const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
-/** 机读指路的行首标识 —— 脚本按它 grep;UI 改版不许动它。 */
 export const RESUME_RUNNING_GUIDANCE_TAG = 'sema: resume-running:';
-/**
- * §3.2b 的**机读三选指路**。三条路各给真实命令或 API 路径,一条都不许省 ——
- * 少写一条 = 那条路在这个车道上被客户端单方面关掉了。
- *
- * 🔴 `attach=` 那一行只有在**真知道 session id** 时才给具体命令:不知道还硬拼一条
- * `sema --resume <sessionId>` 字面量,就是印一条按了没用的命令(假 affordance 的文本形)。
- */
 export function resumeRunningNoUiGuidance(i) {
     const sid = typeof i.sessionId === 'string' && i.sessionId.length > 0 ? i.sessionId : null;
     const attach = sid === null ? 'sema --resume (pick this session from the list)' : `sema --resume ${sid}`;
@@ -146,30 +56,15 @@ export function resumeRunningNoUiGuidance(i) {
         `${T} run ${i.taskId} from an earlier turn is still executing on the engine, and this lane has no card to ask you on. sema did NOT cancel it and did NOT attach to it.`,
         `${T} attach=${attach}`,
         `${T} cancel=POST /v1/runs/${i.taskId}/cancel`,
-        // 🔴 这条车道连 REPL 都不挂载,更没有任何本地面板可看。给的是引擎侧真读面。
         `${T} background=do nothing — run ${i.taskId} keeps executing on the engine; this client does not list it (read it with GET /v1/runs/${i.taskId})`,
     ].join('\n');
 }
-/**
- * ① 接管之前的**显式披露**。
- *
- * resume 入口没有 `lastEventId` 可用(端今天不持久化引擎事件锚),所以 durable 尾从这条 run 的
- * 第一帧读起 —— 崩溃前已落盘、已被 resume 还原到屏上的那一段会再渲一遍。续听腿那道「无锚 × 已上屏
- * ⇒ 不许从头续读」的门在这一格判不出来(它数的是**本条流**吐过几帧,resume 入口恒 0),所以不能
- * 拿它当安全证明。处置 = 说在前面:静默复读会让用户以为模型把同一段活干了两遍。
- *
- * 🔴 **账目面同源**:同一次重放也会把这条 run 已经执行过的每一个 `turn_end` 再喂一次成本累计器。
- *    客户端这一端证明不了哪一枚已经在恢复出来的总额里(那需要一本按 turn 落盘的账 —— 与缺席的
- *    事件锚是同一件移交残件),所以接管腿声明**不计账**。既然不计,就必须在**同一行**说清楚:
- *    只披露视觉复读、不披露账目缺口,用户拿成本面跟引擎账本对不上时只会怀疑客户端算错了。
- */
 export function resumeAttachReplayDisclosure(taskId) {
     return (`sema: attaching to run ${taskId} — sema is replaying it from the engine's ledger, so anything from that ` +
         `turn already shown above will appear again below. There is no resume marker for a run that outlived its shell. ` +
         `The replayed turns are not billed into this session's cost again either — the engine's own record ` +
         `(GET /v1/runs/${taskId}) is the authority on what that run really spent.`);
 }
-/** ② 打完 cancel 但引擎没确认落地时的如实一行(绝不谎报「已停止」)。 */
 export function resumeRunningCancelUnconfirmedRow(taskId) {
     return (`sema: the cancel for run ${taskId} did not come back confirmed, so that run may still be executing. ` +
         `This screen does not list it — read its real state on the engine (GET /v1/runs/${taskId}) before ` +

package/dist/hitl/sessionPolicyWire.d.ts

@@ -1,62 +1,5 @@
-/**
- * hitl/sessionPolicyWire.ts — **会话策略写端口**:per-session 工具规则(`GET` / `PUT /v1/sessions/:id/policy`)
- * 的三端共用窄读 + 收紧编排(0.77.0 CC-105)。
- *
- * ── 它与常驻规则那一面是**两个面**,不是一个面的两半 ────────────────────────────────────────────
- * 常驻规则面是**跨会话**的治理清单(按内容寻址、可列举、可撤销);本面是**一条会话**上的一份记录:
- *   · 作用域 = 这条会话(键还是这条会话的属主,不是调用者;非属主读到的是「没有这条会话」);
- *   · 方向 = **只许收紧**,放宽方向由引擎拒(本包不复述那条判据,见下);
- *   · 并发 = 记录上盖着一枚单调版本号,写入带上它做乐观并发(不带 = 不做并发校验,本包从不这么发)。
- * 所以它**不住进**常驻规则那只门面;但失败分类与回执读口的**姿势**照它:错误按状态 + 机器码结构读
- * (不 `instanceof`:注入面可能是假件,打包后 `instanceof` 也不该是承重判据),回执只认已过窄化的形。
- *
- * ── 🔴 整份替换,所以「追加一条限制」必须把旧的一起发 ───────────────────────────────────────────
- * 写入口的语义是**整份记录替换**,不是逐字段合并:提交体里省掉的字段等于把那个字段的限制**清空**。
- * 于是「只发新增的那条」在引擎眼里是一次**放宽**,当场被拒。本编排因此是「读 → 已有 ∪ 新增 → 整份回写」:
- *   · 并集的**键**就是规则记录自己的那几只桶,键集由引擎型面**派生**(下面的 `RULE_FIELD_PRESENCE`
- *     `satisfies` 表)——引擎加一只桶 ⇒ 本文件**编译红**,而不是「静默丢一桶 + 回执说已生效」;
- *   · 每只桶内按**逐字去重**并集(旧的在前、新的在后,原样字节,不做规范化)。路径一类的规范拼写归引擎,
- *     壳替它改写会让两端对「同一条限制」各有一份判据;
- *   · 🔴 旧记录里**在场的空桶照样保留成空桶**:一只「设了但是空」的白名单与「没设」在语义上是相反的两件事
- *     (前者= 什么都不放行,后者 = 不设这类限制),把它丢掉就是一次放宽。
- *
- * ── 🔴 收紧到底怎么判,判官只有一个 ─────────────────────────────────────────────────────────────
- * 「哪些差异算放宽」的判据在引擎侧(逐桶方向各不相同:禁止名单删条目算放宽;白名单加条目、整只白名单
- * 消失算放宽;目录限制解除或多出一个不在原限制之内的目录算放宽)。本包**不铸第二份**:按「已有 ∪ 新增」
- * 写,判定留给引擎,收到放宽拒绝**原样上报、不吞不重试**。
- * ⚠️ 并集写在结构上消不掉**删除方向**的放宽(旧条目一条不少),但消不掉**加宽方向**的:
- * 端把一条放宽方向的条目(例如往白名单或目录限制里加一项)放进 `add`,并集里就真多一项,引擎会判放宽并拒。
- * **本包不预判这件事** —— 出现放宽拒绝时,事实就是「端喂了放宽方向的条目」,措辞据此指路。
- * 🔴 **但那条拒绝只对普通调用方成立**:上游的方向门是**身份门**,不是字段门 —— 被部署判为运维身份的调用方
- * 写入时方向判据**根本不跑**,于是同一份「已有 ∪ 新增」在运维身份上会**被接受**,而其中往白名单 / 目录限制里
- * 加的那一项就是一次真的放宽。所以本编排的 `written` 只承诺一件事:**记录现在等于原有的加上送来的**;
- * 它**不**承诺「这条会话变严了」,措辞也一个字都不这么说(方向的判官只有引擎一个,而它对运维身份不设门)。
- * 端要的若是「无论谁调用都只会更严」,那需要一个不受身份豁免的写模式,而这条 wire 上今天没有。
- *
- * ── 🔴 生效时机 ────────────────────────────────────────────────────────────────────────────────
- * 够新的引擎在**每一道工具门**重读这份记录 ⇒ 一条 run 跑着的时候写下的收紧,**同一条 run 的下一道工具门**
- * 就拒;更早的引擎只在起手读一次,收紧要等下一条 run。本包**不据此做任何判据**(它是引擎版本的函数,
- * 而这条 wire 上没有位回答它),只在措辞里如实说「下一道工具门」并且不承诺「立刻打断正在跑的那一步」。
- *
- * ── 🔴 三种「没读到」不许互折 ──────────────────────────────────────────────────────────────────
- * 窄读三向:**真空**(记录在、一条限制都没有 —— 这台引擎对一条还没写过策略的会话就这么答,版本号为 0)/
- * **读不懂**(信封、版本号、任一只桶的形不对)/ **调用失败**(带 typed 分类)。读不懂**绝不**折成「空策略」——
- * 折了之后并集写会把一份读不懂的旧记录当成空的整份覆盖上去,那是一次**静默的整面放宽**。
- * 同样,写回执读不懂**绝不**答「已写」:那一次很可能真的落了盘,答案是「不知道」,不是「成功」也不是「失败」。
- *
- * ── UNTRUSTED ─────────────────────────────────────────────────────────────────────────────────
- * 规则文本是部署侧/用户侧的内容,只当字节搬运与渲染,绝不当代码用;桶内逐条只判「是不是字符串」,
- * 内容文法归引擎。
- */
 import type { SessionPermissionRules, StoredSessionRules } from '@sema-agent/sdk';
 import type { SessionPolicyReading } from '../sessionPolicyCapability.js';
-/**
- * 本面消费的客户端切片(注入缝:宿主给真 facade,测试给假件)。
- * 🔴 两只动词的入参与回体型**逐字取自引擎的 wire 型面**(`SessionPermissionRules` / `StoredSessionRules`),
- *    本包不自铸同名形 —— 这同时是一条编译期见证:真客户端上那一对动词若改了签名,这里当场编译红。
- * 🔴 **声明形不是运行期保证**:传输层只把回体解出来,不做运行期校验。所以拿到 200 之后照样走
- *    结构窄读(承重键是版本号与五只桶),与列举腿对页体的处置同律。
- */
 export interface SessionPolicyFacade {
     getPolicy(sessionId: string, opts?: {
         signal?: AbortSignal;
@@ -72,89 +15,40 @@ export interface SessionPolicyFacade {
         rules: StoredSessionRules;
     }>;
 }
-/**
- * 规则记录的桶名全集。**派生自上表**,不是另一份手抄件。
- * 🔴 形制:`Object.freeze` 的数组,**不是**只在类型面只读的 `readonly T[]` —— 后者一行 `.splice()` 就能改,
- *    而公面消费者拿到的正是这个实例。
- */
 export declare const SESSION_POLICY_RULE_FIELDS: readonly (keyof SessionPermissionRules)[];
-/**
- * 本面失败的**处置分类**(不是成因分类)。结构读 `status` + `errorCode`,不 `instanceof`。
- * 🔴 两个 409 是**两种相反的处置**:乐观并发不符(重读重写有意义)与「这条会话没有属主」
- * (重试多少次都一样,记录键根本立不住)。只按状态分会把后者喂进重试腿。
- */
-export type SessionPolicyFailure = 
-/** 这台部署没有会话规则店(整面藏起来)。 */
-{
+export type SessionPolicyFailure = {
     kind: 'face-unavailable';
     message: string;
-}
-/** 放宽方向被拒。**原样上报**,不吞不重试 —— 判据在引擎,本包不复述。 */
- | {
+} | {
     kind: 'loosen-forbidden';
     message: string;
-}
-/**
- * 规则店读不出这条记录的存活标记,于是**拒绝**盖一个证明不了的版本号。
- * 🔴 它与放宽被拒**同一个状态码**、不同的机器码 —— 折进放宽那一臂会让人去改自己送的条目,而条目一个字都没错。
- */
- | {
+} | {
     kind: 'store-corrupt';
     message: string;
-}
-/** 乐观并发键不符:记录在本次读与本次写之间被别人推进过。 */
- | {
+} | {
     kind: 'cas-conflict';
     message: string;
-}
-/** 这条会话没有属主 ⇒ 记录键立不住,引擎拒绝存一条永远读不回来的规则。**不是**可重试的并发冲突。 */
- | {
+} | {
     kind: 'session-ownerless';
     message: string;
-}
-/** 没有这条会话 —— **禁按成因分支**:不存在与不是你的在这条面上同码同串(设计如此,不给存在性预言机)。 */
- | {
+} | {
     kind: 'session-not-found';
     message: string;
-}
-/** 请求体被判形不合法(重发同一份没有意义,改了再发)。 */
- | {
+} | {
     kind: 'request-rejected';
     message: string;
-}
-/** 这次调用带不到可验明的身份。 */
- | {
+} | {
     kind: 'unauthorized';
     message: string;
-}
-/**
- * 引擎**答了**(带着它的机器码),答的是一个本面没有具名臂的客户端侧拒绝(4xx)。这条口上引擎发出的 4xx
- * 都在落盘**之前**(方向门与并发键都是「拒而不写」),所以这一臂可以说「什么都没写」。
- */
- | {
+} | {
     kind: 'error';
     message: string;
-}
-/**
- * 🔴 **引擎的裁决没到手**:裸抛 / 断连 / 超时 / 回体解不开 / 5xx / **没带机器码的 4xx**。
- * 最后一种是出处问题:引擎的错误信封**恒带机器码**(服务端只有一只错误信封写法,兜底站点也按状态补一枚粗码),
- * 所以一个没有码的 405 / 409 / 404 证明不了是引擎在答 —— 反代 / 网关拦下这次写回一页 HTML 就是这个形,
- * 而那时引擎**可能已经落盘**。这一臂**不许**说成「没送到」:传输层在读回体时抛出的那一下可能发生在服务端
- * 已经落盘之后,5xx 同理(提交成功而回程失败)。唯一诚实的话是「不知道,先重读」。
- */
- | {
+} | {
     kind: 'no-verdict';
     message: string;
 };
-/**
- * 抛出来的东西 → 处置分类。
- * 🔴 **并发冲突按机器码逐字认,不按 409 状态认**:同一个 409 上骑着两个码(并发不符 / 会话无属主),
- * 而后者重试多少次都是同一个答案。没带码的 409 一律落通用臂 —— 猜一个码去重试,代价是无穷重试。
- */
 export declare function classifySessionPolicyFailure(e: unknown): SessionPolicyFailure;
-/** 读不懂的三种位置。🔴 三者都是「读不懂」,**不是**「空策略」。 */
 export type SessionPolicyMalformedWhy = 'envelope' | 'rev' | 'rule_field';
-/** 一次读的结局。`present` 的 `rules` 恒是**已窄化的副本**(调用方改它不串味到别处)。 */
 export type SessionPolicyReadOutcome = {
     kind: 'present';
     rev: number;
@@ -167,73 +61,17 @@ export type SessionPolicyReadOutcome = {
     kind: 'failed';
     failure: SessionPolicyFailure;
 };
-/**
- * 读这条会话当前的规则记录。
- * 🔴 记录**真的空**(一只桶都没有、版本号 0)是这台引擎对「还没写过策略的会话」的诚实答案,
- *    它与「读不懂」是两个结局;调用方据此知道下一次写该带哪一个版本号。
- */
 export declare function readSessionPolicy(facade: SessionPolicyFacade, sessionId: string, opts?: {
     signal?: AbortSignal;
 }): Promise<SessionPolicyReadOutcome>;
-/**
- * 「已有 ∪ 新增」。**只加不减**:旧记录的每一只桶、每一条条目都原样留在结果里(在场的空桶保留成空桶),
- * 新增的条目逐字去重后接在后面。两边都没有的桶**不铸**(凭空铸一只空桶 = 凭空加一条限制)。
- * 🔴 条目字节原样搬运:不 trim、不规范化路径、不排序 —— 那些都是引擎的判据,壳再做一遍就是第二份。
- */
 export declare function tightenedSessionRules(prior: SessionPermissionRules, add: SessionPermissionRules): SessionPermissionRules;
-/** {@link tightenSessionPolicy} 的入参。 */
 export interface SessionPolicyTightenRequest {
     sessionId: string;
-    /** 要追加的限制(本编排把它并进已有记录后整份回写)。 */
     add: SessionPermissionRules;
-    /**
-     * 本次编排对能力位的读数。**必填** —— 缺省读锚在多引擎宿主上会静默换成「随便哪台已装引擎」的答案,
-     * 而这一步要决定的是**动不动网络**。由调用方显式给,判官只有这一个。
-     */
     capability: SessionPolicyReading;
 }
-/** `unknown` 那一臂的成因闭集。**每一个都意味着「没有拿到一句『已写』」**,而不是「已确认没写」。 */
-export type SessionPolicyTightenUnknownWhy = 
-/** 这台部署没有会话规则店(读腿就这么答了)。 */
-'face_unavailable'
-/** 没有这条会话(不存在与不是你的同码同串)。 */
- | 'session_not_found'
-/** 这条会话没有属主 ⇒ 记录键立不住。 */
- | 'session_ownerless'
-/** 这次调用带不到可验明的身份。 */
- | 'unauthorized'
-/** 提交体被判形不合法(改了再发)。 */
- | 'request_rejected'
-/** 规则店拒绝盖一个证明不了的版本号(与放宽被拒同状态码不同机器码);送出去的条目没有问题。 */
- | 'store_corrupt'
-/** 当前记录读不懂 ⇒ **不许**当成空记录整份覆盖。 */
- | 'read_unreadable'
-/** 读腿以别的方式失败(读没有副作用,所以这一臂照样意味着什么都没写)。 */
- | 'read_failed'
-/** 写腿被引擎**带码答复**拒绝(引擎的客户端侧 4xx 都在落盘之前发出)⇒ 什么都没写。 */
- | 'write_refused'
-/** 🔴 写腿**没拿到引擎的裁决**(裸抛 / 断连 / 超时 / 回体解不开 / 5xx / 没带机器码的 4xx)⇒ 可能已经生效,绝不说成「没送到」。 */
- | 'write_indeterminate'
-/** 🔴 写回执读不懂:那一次**可能真的落了盘**,所以既不是 `written` 也不是「没写」。 */
- | 'write_receipt_unreadable'
-/**
- * 🔴 写回执读得懂,但它**证明不了这一次提交落了盘**:版本号没有推进、或送出去的桶 / 条目不在回执里。
- * 与上一臂同一处置(可能已生效,先重读);分开一格是因为「回执说的不是这次」与「回执读不懂」要不同的排查方向。
- */
- | 'write_receipt_mismatch';
-/** 成因闭集的运行期镜像(冻结)。 */
+export type SessionPolicyTightenUnknownWhy = 'face_unavailable' | 'session_not_found' | 'session_ownerless' | 'unauthorized' | 'request_rejected' | 'store_corrupt' | 'read_unreadable' | 'read_failed' | 'write_refused' | 'write_indeterminate' | 'write_receipt_unreadable' | 'write_receipt_mismatch';
 export declare const SESSION_POLICY_TIGHTEN_UNKNOWN_WHY: readonly SessionPolicyTightenUnknownWhy[];
-/**
- * 一次收紧的结局。**判别联合**,五臂互斥:
- *  · `written` —— 引擎回了一份读得懂的回执,`rev` 是记录的新版本号(下一次写的并发键)。
- *    🔴 它说的是「记录现在等于原有的加上送来的」,**不是**「这条会话变严了」——方向的判官只有引擎,
- *    而引擎对运维身份不设方向门(见头注);措辞一个字都不承诺方向;
- *  · `conflict` —— 重读重写过**一次**之后仍被并发键挡住;`rev` = 本次写所依据的那个版本号
- *    (按定义它在被拒的那一刻就已经过期,调用方要么重新走一遍,要么把这件事交给人);
- *  · `loosen_forbidden` —— 放宽方向被拒。**不吞不重试**(重试同一份永远同一个答案);
- *  · `capability_absent` —— 引擎明说没有这一面、或这份二进制比这一位还老 ⇒ **一个请求都没发**;
- *  · `unknown` —— 其余一切。🔴 `unknown` 绝不带 `rev`,也绝不被读成「已写」。
- */
 export type SessionPolicyTightenOutcome = {
     kind: 'written';
     rev: number;
@@ -251,25 +89,7 @@ export type SessionPolicyTightenOutcome = {
     why: SessionPolicyTightenUnknownWhy;
     message?: string;
 };
-/**
- * 给这条会话**追加**一组限制:读当前记录 → 「已有 ∪ 新增」→ 带当前版本号整份回写。
- *
- * 🔴 **只重读重写一次**(结构上,不靠计数器:本函数里没有循环)。撞上并发键说明有别的写者在同一条
- * 会话上推进了记录;重来一趟是为了把对方刚写进去的限制也一并带上(并集只加不减,所以重来是**收敛**的)。
- * 第二趟仍撞 ⇒ 如实上报 `conflict`:第三趟不比第二趟更有理由成功,而一个自己会无限重试的写腿在争用下
- * 会把一条会话的规则记录变成两个写者的角力场。
- * 🔴 能力位明说没有这一面(或这份二进制比这一位还老)⇒ **一个请求都不发**;从没观测过 ⇒ **照发** ——
- * 「本进程没探过能力面」是本进程的缺陷,不是引擎的否定,把它当否定会让一次用户已经点过的动作凭空落空。
- * 那两条的分家写在 `sessionPolicyFaceAvailable` 的头注里(渲不渲入口 vs 动不动网络是两个问题)。
- */
 export declare function tightenSessionPolicy(facade: SessionPolicyFacade, req: SessionPolicyTightenRequest, opts?: {
     signal?: AbortSignal;
 }): Promise<SessionPolicyTightenOutcome>;
-/**
- * 一次收紧结局的人话,**唯一措辞真源**。
- * 🔴 三条不许说反:① 放宽被拒那一句要指向「送出去的那组条目里有放宽方向的」,不许说成引擎坏了或没权限;
- *    ② 并发那一句要说「记录又被别人动了」并把下一步交出去,不许说成已写;③ 回执读不懂那一句**必须**
- *    说「可能已经生效」——把它说成失败,人会再写一遍,而那一遍会把已经生效的那条当成新增重发。
- * 生效时机只说「下一道工具门」,不承诺打断正在跑的那一步。
- */
 export declare function sessionPolicyTightenNotice(outcome: SessionPolicyTightenOutcome): string;