@sema-agent/client-core 0.76.1 → 0.77.0

package/dist/hitl/sessionPolicyWire.d.ts

@@ -0,0 +1,275 @@
+/**
+ * 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;
+    }): Promise<{
+        rules: StoredSessionRules;
+    }>;
+    putPolicy(sessionId: string, body: {
+        rules: SessionPermissionRules;
+        expectedRev?: number;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        rules: StoredSessionRules;
+    }>;
+}
+/**
+ * 规则记录的桶名全集。**派生自上表**,不是另一份手抄件。
+ * 🔴 形制:`Object.freeze` 的数组,**不是**只在类型面只读的 `readonly T[]` —— 后者一行 `.splice()` 就能改,
+ *    而公面消费者拿到的正是这个实例。
+ */
+export declare const SESSION_POLICY_RULE_FIELDS: readonly (keyof SessionPermissionRules)[];
+/**
+ * 本面失败的**处置分类**(不是成因分类)。结构读 `status` + `errorCode`,不 `instanceof`。
+ * 🔴 两个 409 是**两种相反的处置**:乐观并发不符(重读重写有意义)与「这条会话没有属主」
+ * (重试多少次都一样,记录键根本立不住)。只按状态分会把后者喂进重试腿。
+ */
+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;
+    rules: SessionPermissionRules;
+} | {
+    kind: 'malformed';
+    why: SessionPolicyMalformedWhy;
+    detail: string;
+} | {
+    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 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;
+} | {
+    kind: 'conflict';
+    rev: number;
+} | {
+    kind: 'loosen_forbidden';
+    message: string;
+} | {
+    kind: 'capability_absent';
+    why: 'not_reported' | 'absent';
+} | {
+    kind: 'unknown';
+    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;