@sema-agent/server 7.131.0 → 7.133.0

package/dist/approval-ask-retention.js

@@ -0,0 +1,102 @@
+import { RUN_STATUS_CLASS } from "./plugins/store-contracts.js";
+export const APPROVAL_ASK_RETENTION_DEFAULT_MS = 30 * 86_400_000;
+export const APPROVAL_ASK_RETENTION_FLOOR_MS = 86_400_000;
+export const APPROVAL_ASK_RETENTION_PASS_MS = 3_600_000;
+export const APPROVAL_ASK_REAP_BATCH = 500;
+export const MOVABLE_RUN_STATUSES = [
+    ...Object.entries(RUN_STATUS_CLASS).filter(([, cls]) => cls === "parked"),
+    ...Object.entries(RUN_STATUS_CLASS).filter(([, cls]) => cls === "live"),
+    ...Object.entries(RUN_STATUS_CLASS).filter(([, cls]) => cls === "parked"),
+].map(([status]) => status);
+const BACKGROUND_AGENT_MOVABLE = {
+    running: true,
+    parked: true,
+    completed: false,
+    failed: false,
+    killed: false,
+};
+export async function collectMovableAnchors(input) {
+    const anchors = new Set();
+    for (const status of MOVABLE_RUN_STATUSES) {
+        let cursor;
+        for (;;) {
+            const page = await input.runs.listRuns({ status, limit: APPROVAL_ASK_REAP_BATCH, ...(cursor !== undefined ? { cursor } : {}) });
+            for (const r of page) {
+                anchors.add(r.taskId);
+                anchors.add(r.sessionId);
+            }
+            const last = page[page.length - 1];
+            if (page.length < APPROVAL_ASK_REAP_BATCH || last === undefined)
+                break;
+            cursor = { createdAt: last.createdAt, taskId: last.taskId };
+        }
+    }
+    const agents = input.backgroundAgents;
+    if (agents !== undefined) {
+        if (agents.listScopes === undefined) {
+            throw new Error("approval ledger retention: the background-agent store cannot enumerate its scopes (no listScopes) — cannot prove which delegated children can no longer move, so nothing is aged out this pass");
+        }
+        for (const scope of await agents.listScopes()) {
+            for (const row of await agents.listByScope(scope)) {
+                if (!BACKGROUND_AGENT_MOVABLE[row.status])
+                    continue;
+                for (const anchor of [row.owner, row.sessionId, row.parentSessionId, row.rootSessionId])
+                    if (anchor !== undefined)
+                        anchors.add(anchor);
+            }
+        }
+    }
+    if (input.checkpoints !== undefined)
+        for (const sessionId of await input.checkpoints.listPendingSessionIds())
+            anchors.add(sessionId);
+    return anchors;
+}
+export async function runApprovalAskRetentionPass(input) {
+    const { askStore, audit, runs, backgroundAgents, checkpoints, cutoffMs, logger, metrics } = input;
+    const reading = { cutoffMs, asks: 0, batches: 0, auditAsks: 0, auditRecords: 0 };
+    const count = (ledger, n) => {
+        if (n > 0)
+            metrics.inc("approval_ask_retention_rows_deleted_total", { ledger }, n);
+    };
+    const report = (incomplete) => {
+        if (reading.asks === 0 && reading.batches === 0 && reading.auditRecords === 0)
+            return;
+        logger.info("approval_ask_retention_swept", {
+            ...reading,
+            ...(incomplete ? { incomplete: true } : {}),
+            note: "settled approval asks quiet for longer than APPROVAL_ASK_RETENTION_MS, with nothing they hang off (their run, host session or asking leg's session) still able to move, were deleted whole from the approval ledgers (ask rows, emptied batches, and their audit-ledger records); records that remain are byte-for-byte unchanged. Set APPROVAL_ASK_RETENTION_MS=0 to keep everything.",
+        });
+    };
+    try {
+        const movable = await collectMovableAnchors({ runs, backgroundAgents, checkpoints });
+        if (askStore !== undefined) {
+            for (;;) {
+                const n = await askStore.reapSettledAsks(cutoffMs, APPROVAL_ASK_REAP_BATCH, movable);
+                reading.asks += n;
+                count("asks", n);
+                if (n < APPROVAL_ASK_REAP_BATCH)
+                    break;
+            }
+            for (;;) {
+                const n = await askStore.reapEmptyBatches(cutoffMs, APPROVAL_ASK_REAP_BATCH);
+                reading.batches += n;
+                count("batches", n);
+                if (n < APPROVAL_ASK_REAP_BATCH)
+                    break;
+            }
+        }
+        if (audit !== undefined) {
+            const rotated = audit.rotateOlderThan(cutoffMs, movable);
+            reading.auditAsks += rotated.droppedAsks;
+            reading.auditRecords += rotated.droppedRecords;
+            count("audit", rotated.droppedRecords);
+        }
+    }
+    catch (err) {
+        report(true);
+        throw err;
+    }
+    report(false);
+    return reading;
+}
+//# sourceMappingURL=approval-ask-retention.js.map

package/dist/approval-card.d.ts

@@ -23,6 +23,8 @@
 import { z } from "zod";
 import { ALLOW_RULE_MEMBERS, READ_ROOT_CANDIDATE_DIR_MAX, type AskClass, type AskEvidenceAbsence, type PendingAction as CorePendingAction, type ReadRootGrantCandidate, type ResumeStartupCause, type RuleOffer, type RuleOffersAbsence as CoreRuleOffersAbsence, type SteerReplayFacet } from "@sema-agent/core";
 import type { AskRow } from "./plugins/approval-ask-store-sql.js";
+import type { SettleCause, SettleOutcome } from "./approval-deny-reasons.js";
+import type { ToolApprovalFrame } from "./tool-approval.js";
 /** 模型自由文本(`sourceAgentName` / `delegation.agentName`)的限长(设计稿 §6.2)。设计 §3.1 把
  *  「限长 + 脱敏」写成 **server 新增责任**(引擎无此层):spawning model 挑的名字是自由文本,
  *  不能指望壳去截——一条 100KB 的 agentName 在 server 侧就该被拒,而不是变成一张撑爆呈卡面的卡。 */
@@ -82,8 +84,8 @@ export declare const RuleOfferSchema: z.ZodUnion<readonly [z.ZodObject<{
     rule: z.ZodString;
     match: z.ZodEnum<{
         name: "name";
-        path: "path";
         host: "host";
+        path: "path";
         exact: "exact";
         prefix: "prefix";
         wildcard: "wildcard";
@@ -99,8 +101,8 @@ export declare const RuleOfferSchema: z.ZodUnion<readonly [z.ZodObject<{
         rule: z.ZodString;
         match: z.ZodEnum<{
             name: "name";
-            path: "path";
             host: "host";
+            path: "path";
             exact: "exact";
             prefix: "prefix";
             wildcard: "wildcard";
@@ -167,8 +169,8 @@ export declare const RuleOfferRawSchema: z.ZodUnion<readonly [z.ZodObject<{
     rule: z.ZodString;
     match: z.ZodEnum<{
         name: "name";
-        path: "path";
         host: "host";
+        path: "path";
         exact: "exact";
         prefix: "prefix";
         wildcard: "wildcard";
@@ -184,8 +186,8 @@ export declare const RuleOfferRawSchema: z.ZodUnion<readonly [z.ZodObject<{
         rule: z.ZodString;
         match: z.ZodEnum<{
             name: "name";
-            path: "path";
             host: "host";
+            path: "path";
             exact: "exact";
             prefix: "prefix";
             wildcard: "wildcard";
@@ -295,7 +297,9 @@ export declare function readProbeCause(req: unknown): ProbeCauseProjection | und
  *
  * 姿势逐条(与 {@link readProbeCause} / {@link readRuleEvidence} 同款分工):
  *  · `safeParse`,非串 ⇒ 按缺席处置(宪法 [ref]);空串 / 纯空白 ⇒ 缺席(core 自己也只在 `trim() !== ""` 时铸)。
- *  · 长度:超过 {@link MAX_PROBE_REASON_CODEPOINTS} ⇒ **整只丢,不截**(判据与 `probeCause.code` 超限同形);
+ *  · 长度(S-733 信封):core 铸不出的长度 ⇒ **整只丢,不截**(判据与 `probeCause.code` 超限同形;截出来的是**另一句话**)。判官是 core 包根导出的
+ *    `isMintableProbeReason`(core 7.53.0 #1883:上限 = core 的 cap + 它那一枚截断记号的宽度,「+1」只写在 core 一处;修前本仓手抄
+ *    `MAX_PROBE_REASON_CODEPOINTS = 201` —— 数字与「+1」两件事都是抄的)。超过它的值**不是 core 铸的**(第三方 producer / 世代差)。
  *    先判长度再脱敏 ⇒ 喂给脱敏器的永远是个短串(脱敏器的 RangeError 面是超大输入)。
  *  · 内容族(部署自写的探针散文,人眼信任边界上的文本)⇒ `redactSecrets`。脱敏后**不再截**:耐久面同样不截,
  *    两面逐字节同值比「帧上短一截」重要(allow 层披露那一格 R2-[medium] 的反面:那里有卡面要对齐,这里没有)。
@@ -629,8 +633,8 @@ export declare const ApprovalCardSchema: z.ZodObject<{
         rule: z.ZodString;
         match: z.ZodEnum<{
             name: "name";
-            path: "path";
             host: "host";
+            path: "path";
             exact: "exact";
             prefix: "prefix";
             wildcard: "wildcard";
@@ -646,8 +650,8 @@ export declare const ApprovalCardSchema: z.ZodObject<{
             rule: z.ZodString;
             match: z.ZodEnum<{
                 name: "name";
-                path: "path";
                 host: "host";
+                path: "path";
                 exact: "exact";
                 prefix: "prefix";
                 wildcard: "wildcard";
@@ -726,10 +730,13 @@ export declare const ApprovalCardSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ApprovalCard = z.infer<typeof ApprovalCardSchema>;
 /**
- * `approval_ask.card_json` 里真正存的东西(设计稿 §6.2)。存**信封**而不是裸卡的理由:重放帧要回填
- * 车2 铸的 `approvalId`(wire 面的回决通道桥 + 消费端与并行 `tool_approval` 帧的去重键),而它不属于
- * 「卡的内容」——放进卡里会让 schema 的语义边界糊掉。`schemaVersion` 是形的版本闩(与行上的
+ * `approval_ask.card_json` 里真正存的东西(设计稿 §6.2)。`schemaVersion` 是形的版本闩(与行上的
  * `schema_version` 列同值,列供 SQL 侧过滤,信封里这份供读面在解出内容**之前**判形)。
+ *
+ * `approvalId` = 这张卡**呈出时**的 wire 身份。7.133.0 起它恒等于行的键 `askId`(一只 ask 一只 wire 身份),本服务的活读者(重放帧 /
+ * 应答口 / 读口)一律读行的键、不读这一格;写它是给滚动升级窗里上一版的副本(它们的 strict 信封 schema 要求这一格并照它重放)。
+ * 唯一读这一格的是 local 车道的启动收敛 —— 拿它去审计账里查前世这只 ask 的成因:审计行记的就是当时呈出的那个 id
+ * (更早写下的行上是当年的登记本地 id)。
  */
 export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
@@ -764,8 +771,8 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
             rule: z.ZodString;
             match: z.ZodEnum<{
                 name: "name";
-                path: "path";
                 host: "host";
+                path: "path";
                 exact: "exact";
                 prefix: "prefix";
                 wildcard: "wildcard";
@@ -781,8 +788,8 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
                 rule: z.ZodString;
                 match: z.ZodEnum<{
                     name: "name";
-                    path: "path";
                     host: "host";
+                    path: "path";
                     exact: "exact";
                     prefix: "prefix";
                     wildcard: "wildcard";
@@ -956,16 +963,33 @@ export declare function buildApprovalRequestFrame(input: {
     card: ApprovalCard;
     expiresAtMs: number;
     nowMs: number;
+    live: ApprovalRequestLiveFacts;
 }): ApprovalRequestFrame;
 /**
- * [ref] §3.1 的呈卡帧(设计稿 §4.1 逐字)。
+ * 🔴 **呈卡帧的活面事实座**(呈卡腿上旧族退役之后,开卡帧的全部事实都由本族承载)。
+ *
+ * 这十个座是活卡帧 `tool_approval` 上有、而卡(`ApprovalCardSchema`,`card_json` 的耐久信封)上**没有**的那几位:
+ * 卡外的事实此前只骑活卡帧,呈卡腿的消费方靠「两帧按 approvalId 合读」拿到它们。呈卡腿自此只发本族帧 ⇒ 它们挪到**活铸**的
+ * 呈卡帧顶层,同名同型同值 —— 值取自同一只帧对象(活卡帧的那一次铸定,`tool-approval.ts` 的 `askBroadcast`),本仓不另算一遍。
  *
- * 与既有 `tool_approval` 帧是**并行加帧、不替换**(§4.2):存量壳只认旧帧,新帧是闭集加员;两帧同带
- * `approvalId`,消费端据它去重。
+ * 在场面与它们在活卡帧上的在场面**逐字相同**:只在活铸的帧上,断连重放帧({@link buildReplayFrame},从 `card_json` 回读)上恒缺席 ——
+ * 活卡帧从来不重放,卡外事实也从来不在重放面上;是否把其中某几位收进卡(耐久、随重放)是另一件事,各自要过 `.strict()` 信封的回滚窗判断
+ * (`readRootCandidate` 有不进卡的硬理由:耐久面兑现不了它,见活卡帧该座顶注)。
  *
- * 🔴 铸造/发射**不在刀 3c**(那是 3b 的域)。本文件只出「持久行 → 帧」的重放投影 `buildReplayFrame`。
+ * `requiresRealApproval` 不在表里:卡上 `risk.requiresRealApproval` 是同一个事实(铸卡第三参就是它),一个事实一个读法。
  */
-export interface ApprovalRequestFrame {
+export declare const APPROVAL_REQUEST_LIVE_FACT_KEYS: readonly ["mandated", "mandate", "origin", "boundGrantDigest", "boundGrants", "classifierNoRuling", "boundGrantAbsence", "approvalCard", "readRootCandidate", "probeReason"];
+/** 呈卡帧活面事实座的类型面 = 活卡帧同名座的 `Pick`(同型由构造保证,不手抄)。 */
+export type ApprovalRequestLiveFacts = Pick<ToolApprovalFrame, (typeof APPROVAL_REQUEST_LIVE_FACT_KEYS)[number]>;
+/**
+ * [ref] §3.1 的呈卡帧(设计稿 §4.1 逐字)。
+ *
+ * 🔴 **一条腿一个帧族**:呈卡协议在一条腿上场(腿的审批上下文接了 `emitCard`)⇒ 这条腿上一只 ask 的开卡 / 消卡 / 撤卡只走本族
+ * (`approval_request` / {@link ApprovalCompleteFrame} / {@link ApprovalRevokeFrame}),旧族 `tool_approval` / `tool_approval_complete`
+ * 一帧都不发;协议未上场的腿只发旧族。同一只 ask 在同一条腿上不再有两种开卡帧,消费方不再按 `approvalId` 去重。
+ * 开卡的全部事实因此在本帧上:卡(`card`,耐久信封)+ 活面事实座({@link ApprovalRequestLiveFacts},只在活铸的帧上)。
+ */
+export interface ApprovalRequestFrame extends ApprovalRequestLiveFacts {
     /** = SSE 具名事件名(与 `tool_approval` 同约定)。 */
     type: "approval_request";
     schemaVersion: 1;
@@ -982,12 +1006,50 @@ export interface ApprovalRequestFrame {
     expiresAtMs: number;
     serverNowMs: number;
     /**
-     * server 扩(不在设计字面):车4 落地前的**回决通道桥**——现行
-     * `POST /v1/tool-approvals/:id/respond` 的 id。也是消费端把本帧与并行的 `tool_approval` 帧去重的键。
-     * 车4 上线后仍保留(旧壳过渡窗)。
+     * server 扩(不在设计字面):`POST /v1/tool-approvals/:id/respond` / `GET /v1/tool-approvals/:id` 的 id —— **恒等于 `askId`**(行的键就是这只 ask
+     * 唯一的 wire 身份;本族的消卡帧({@link ApprovalCompleteFrame})同带它)。
      */
     approvalId: string;
 }
+/**
+ * 呈卡族的**单卡消卡帧**(`approval_complete`)—— 一只 ask 落定时发给每一条**收到过它的呈卡帧**的呈卡腿连接。
+ *
+ * 语义与旧族 `tool_approval_complete` 逐字同一件事(同一次 settle 的同一份判决:`outcome` 三词、非人结局的 `cause`、park 路由的
+ * `parked`),只是它属于本族:键与开卡帧对位(`askId` / `taskId` / `approvalId`,开卡帧上有的身份这里都有),消卡按开卡那一帧的键。
+ * 与 {@link ApprovalRevokeFrame} 的分工:撤卡帧是**批级**的(兄弟被赢家连坐成 `VOID` 的那一批,名单 = 那一次原子事务的行集,
+ * 不带逐卡终局);本帧是**单卡**的终局(人答 / 窗到期 / park 路由 / 取消 …)。同一只 ask 两帧都可能收到(被撤的兄弟自己的
+ * 登记也按 settle 收场)—— 按 `askId` 清卡即可,两帧不冲突。
+ *
+ * 投递口 = 开卡帧的同一只口(`ToolApprovalRunContext.emitCard`):卡帧在哪,消卡帧就在哪(sync 腿 live + detach 账本,bg / resume 腿账本)。
+ * 门 = 这条连接的**开卡帧真的送达过**(没见过开卡帧的连接收到消卡帧就是孤儿 close,与旧族同一条门)。
+ */
+export interface ApprovalCompleteFrame {
+    /** = SSE 具名事件名(同 `approval_request` 约定)。 */
+    type: "approval_complete";
+    schemaVersion: 1;
+    askId: string;
+    taskId: string;
+    approvalId: string;
+    /** 这只 ask 怎么落定 —— 与审计 settle 行 `outcome` 同三词(`allowed` / `denied` = 一次决议;`expired` = 非人结局)。 */
+    outcome: SettleOutcome;
+    /** 非人结局的成因(与审计 settle 行 `cause` 同一个词);人答缺席。缺席不是证据。 */
+    cause?: SettleCause;
+    /** 这只 ask 按 park 路由收尾(行已转 PARKING / PARKED、迟到回决可达)。缺席 = 无证据,禁读作真拒。 */
+    parked?: true;
+    serverNowMs: number;
+}
+/** 单卡消卡帧的纯构造(`build*`:纯数据)。可选座只在有值时写键。 */
+export declare function buildApprovalCompleteFrame(input: {
+    askId: string;
+    taskId: string;
+    approvalId: string;
+    outcome: SettleOutcome;
+    cause?: SettleCause;
+    parked: boolean;
+    nowMs: number;
+}): ApprovalCompleteFrame;
+/** 呈卡腿的单卡帧(开卡 / 消卡)—— `ToolApprovalRunContext.emitCard` 的入参形。 */
+export type ApprovalCardLegFrame = ApprovalRequestFrame | ApprovalCompleteFrame;
 /**
  * [ref] §3.3 的**批级撤卡帧**(车6;设计稿 §3 逐字)。
  *

package/dist/approval-card.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
-import { ALLOW_RULE_MEMBERS, ASK_EVIDENCE_ABSENCE_VALUES, BOUND_GRANT_ABSENCES, MAX_RULE_TEXT_CHARS, READ_ROOT_CANDIDATE_DIR_MAX, RESUME_STARTUP_CAUSES, RULE_OFFERS_ABSENCES, STEER_REPLAY_FACETS, isAskClass, isAskOrigin, isAutoModeFallbackCause, isPersistedRuleMandate, screenAskClassMembers } from "@sema-agent/core";
+import { ALLOW_RULE_MEMBERS, ASK_EVIDENCE_ABSENCE_VALUES, BOUND_GRANT_ABSENCES, MAX_RULE_TEXT_CHARS, READ_ROOT_CANDIDATE_DIR_MAX, RESUME_STARTUP_CAUSES, RULE_OFFERS_ABSENCES, STEER_REPLAY_FACETS, isAskClass, isAskOrigin, isAutoModeFallbackCause, isMintableProbeReason, isPersistedRuleMandate, screenAskClassMembers } from "@sema-agent/core";
 import { redactSecrets } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { capText } from "./caller-text-echo.js";
 import { retireParkArmWords, retireStoredCardWords } from "./retired-card-words.js";
 import { PERSISTED_RULE_MATCHES, UNCOVERED_SEGMENT_REASONS } from "./permission-rule-vocab.js";
 export const MAX_AGENT_NAME = 200;
@@ -161,14 +162,13 @@ export function readProbeCause(req) {
         ...(raw.further !== undefined ? { further: family(raw.further) } : {}),
     };
 }
-const MAX_PROBE_REASON_CODEPOINTS = 201;
 const ProbeReasonEnvelopeSchema = z.object({ probeReason: z.string().optional() });
 export function readProbeReason(req) {
     const parsed = ProbeReasonEnvelopeSchema.safeParse(req);
     const raw = parsed.success ? parsed.data.probeReason : undefined;
     if (raw === undefined || raw.trim() === "")
         return undefined;
-    if ([...raw].length > MAX_PROBE_REASON_CODEPOINTS)
+    if (!isMintableProbeReason(raw))
         return undefined;
     const redacted = redactSecrets(raw);
     return redacted === "" ? undefined : redacted;
@@ -451,11 +451,6 @@ const RiskAxesEnvelopeSchema = z.object({
     })
         .optional(),
 });
-function clip(s, max) {
-    if (s === undefined)
-        return undefined;
-    return s.length > max ? s.slice(0, max) : s;
-}
 export function buildApprovalCard(source, req, requiresRealApproval) {
     const axes = RiskAxesEnvelopeSchema.safeParse(req);
     const riskAxes = axes.success ? axes.data.riskAxes : undefined;
@@ -464,13 +459,13 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
     const ruleOffersAbsence = readRuleOffersAbsence(req);
     const denialLimitFallback = readDenialLimitFallback(req);
     const askClassPair = readAskClassPair(source);
-    const toolCallId = clip(source.toolCallId, MAX_IDENT);
-    const sourceTaskId = clip(source.sourceTaskId, MAX_IDENT);
-    const sourceAgentName = clip(source.sourceAgentName, MAX_AGENT_NAME);
+    const toolCallId = capText(source.toolCallId, MAX_IDENT);
+    const sourceTaskId = capText(source.sourceTaskId, MAX_IDENT);
+    const sourceAgentName = capText(source.sourceAgentName, MAX_AGENT_NAME);
     const allowRuleShadowed = readAllowRuleShadowed(req);
     return {
-        toolName: clip(source.toolName, MAX_IDENT) ?? "",
-        message: clip(source.message, MAX_MESSAGE) ?? "",
+        toolName: capText(source.toolName, MAX_IDENT) ?? "",
+        message: capText(source.message, MAX_MESSAGE) ?? "",
         ...(source.argsOmitted === true ? { argsOmitted: true } : source.args !== undefined ? { args: source.args } : {}),
         ...(toolCallId !== undefined ? { toolCallId } : {}),
         risk: {
@@ -494,9 +489,9 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
         ...(source.delegation
             ? {
                 delegation: {
-                    parentToolCallId: clip(source.delegation.parentToolCallId, MAX_IDENT) ?? "",
+                    parentToolCallId: capText(source.delegation.parentToolCallId, MAX_IDENT) ?? "",
                     depth: source.delegation.depth,
-                    ...(source.delegation.agentName !== undefined ? { agentName: clip(source.delegation.agentName, MAX_AGENT_NAME) ?? "" } : {}),
+                    ...(source.delegation.agentName !== undefined ? { agentName: capText(source.delegation.agentName, MAX_AGENT_NAME) ?? "" } : {}),
                 },
             }
             : {}),
@@ -533,6 +528,41 @@ export function buildApprovalRequestFrame(input) {
         expiresInMs: Math.max(0, input.expiresAtMs - input.nowMs),
         serverNowMs: input.nowMs,
         approvalId: input.approvalId,
+        ...pickApprovalRequestLiveFacts(input.live),
+    };
+}
+export const APPROVAL_REQUEST_LIVE_FACT_KEYS = [
+    "mandated",
+    "mandate",
+    "origin",
+    "boundGrantDigest",
+    "boundGrants",
+    "classifierNoRuling",
+    "boundGrantAbsence",
+    "approvalCard",
+    "readRootCandidate",
+    "probeReason",
+];
+function pickApprovalRequestLiveFacts(src) {
+    const out = {};
+    for (const key of APPROVAL_REQUEST_LIVE_FACT_KEYS) {
+        const v = src[key];
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+export function buildApprovalCompleteFrame(input) {
+    return {
+        type: "approval_complete",
+        schemaVersion: 1,
+        askId: input.askId,
+        taskId: input.taskId,
+        approvalId: input.approvalId,
+        outcome: input.outcome,
+        ...(input.cause !== undefined ? { cause: input.cause } : {}),
+        ...(input.parked ? { parked: true } : {}),
+        serverNowMs: input.nowMs,
     };
 }
 export function buildRevokeFrame(batchId, askIds, reason, serverNowMs, originTaskId) {
@@ -552,7 +582,7 @@ export function buildReplayFrame(row, nowMs) {
         expiresAtMs: row.expiresAtMs,
         expiresInMs: Math.max(0, row.expiresAtMs - nowMs),
         serverNowMs: nowMs,
-        approvalId: parsed.approvalId,
+        approvalId: row.askId,
     };
 }
 export function storedCardDemandsAPerson(cardJson) {

package/dist/approval-deny-reasons.d.ts

@@ -46,7 +46,7 @@ export declare const APPROVAL_ENDING_CAUSES: {
     /** 承载这张卡的流没了:断连强转 park(`parkOpenAsksForTask`,断连臂的事实 = 这个 wire run 的承载流断了;卡曾送达过,只是不会再有人从那条流上答它)。 */
     readonly STREAM_DISCONNECTED: "stream_disconnected";
     /**
-     * 这张卡呈不出去:兜底臂(行不可用 / 身份不定 / 悬挂无行,`unattendedOutcome` 的 `persisted_row_unusable` / `ensure_indeterminate` / `unreached_no_row`)—— 持久行证不出属主或读不成,
+     * 这张卡呈不出去:兜底臂(行不可用 / 身份不定 / 无行且无旧族腿可呈,`unattendedOutcome` 的 `persisted_row_unusable` / `ensure_indeterminate` / `no_row_no_presenter`)—— 持久行证不出属主或读不成,
      * 本次登记根本没把卡呈到任何投递面;同 askId 的其余本地登记按这个词随行收场。与 `broadcast_lost`(emit 零接收)是两个事实。
      */
     readonly UNDELIVERABLE: "undeliverable";

package/dist/approval.d.ts

@@ -184,5 +184,14 @@ export declare function createDeploymentListExemption(store: Pick<ApprovalExempt
     info(event: string, fields?: Record<string, unknown>): void;
     warn(event: string, fields?: Record<string, unknown>): void;
 }, leg?: "parked_revive"): DeploymentListExemption;
+/**
+ * **请求叶策略:`settings.permissions.neverAuto`**(S-1351)—— 命中名单的工具恒问真人;名单外「本层没有意见」(裸 allow)。叶只管请求自己写的那张表,部署的 `APPROVAL_NEVER_AUTO`
+ * 在基线里({@link createDurableAskPolicy}),两者经 `tightenGoverned` 的 deny-wins 折叠取并:请求叶只会**多**问,删不掉基线里的任何一行。
+ *
+ * 名字读法与部署名单是**同一只**({@link createApprovalListVerdict} → 精确 ∪ covering,收紧臂读调用答得上的全部名字):一条规则只有一种读法。问的铸点是
+ * {@link requestAlwaysHumanAsk}(要真人位 + 请求出处),不是部署的 {@link operatorAlwaysHumanAsk}(那一个盖部署出身,请求里的声明冒不得)。
+ * `source` = 这张表在请求体里的坐标(出处进 `matchedAskRule`,审计 / 卡面据它说清是哪张表问的)。
+ */
+export declare function createRequestNeverAutoPolicy(names: readonly string[], source: string): ToolPolicy;
 export declare function createDurableAskPolicy(opts: DurableAskOptions): ToolPolicy;
 //# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -1,5 +1,5 @@
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "@sema-agent/core";
-import { operatorAlwaysHumanAsk, operatorAsk } from "./operator-ask.js";
+import { operatorAlwaysHumanAsk, operatorAsk, requestAlwaysHumanAsk } from "./operator-ask.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./approval-content-kind.js";
 import { isExplicitPosture } from "./posture-source.js";
 import { handsOnWorkerFilePlane } from "./execution-lane-caps.js";
@@ -37,7 +37,7 @@ export function buildNoResponderBootWarns(input) {
         out.push({
             event: "fs_write_gate_no_responder",
             fields: {
-                hint: "host-semantics lane with no approval face: permissionMode default/auto Write/Edit asks will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
+                hint: "host-semantics lane with no approval face: the engine's write-gate asks (permissionMode default/auto, absent reads as default; acceptEdits outside the write roots) will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
             },
         });
     }
@@ -45,7 +45,7 @@ export function buildNoResponderBootWarns(input) {
         out.push({
             event: "workflow_gate_no_responder",
             fields: {
-                hint: "self-orchestration with no approval face: permissionMode default/auto/acceptEdits run_workflow asks will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
+                hint: "self-orchestration with no approval face: run_workflow asks (every permission mode but bypassPermissions, which releases them, and dontAsk, which refuses them; absent reads as default) will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
             },
         });
     }
@@ -122,6 +122,27 @@ function createNameSetMatcher(names) {
 function grantedByRule() {
     return { action: "allow", decisionReason: "rule" };
 }
+export function createRequestNeverAutoPolicy(names, source) {
+    const verdictOf = createApprovalListVerdict({ requireApproval: [], neverAuto: names });
+    return {
+        check: (req) => {
+            const verdict = verdictOf(req);
+            switch (verdict.list) {
+                case "never_auto":
+                    return requestAlwaysHumanAsk(`${source}(${verdict.hit})`, `human approval required to run "${req.toolName}"`);
+                case "none":
+                    return { action: "allow" };
+                case "deny":
+                case "require":
+                    throw new Error(`request never-auto leaf reached a "${verdict.list}" verdict with empty deny / require lists`);
+                default: {
+                    const unreachable = verdict;
+                    throw new Error(`unhandled approval-list verdict: ${JSON.stringify(unreachable)}`);
+                }
+            }
+        },
+    };
+}
 export function createDurableAskPolicy(opts) {
     const verdictOf = createApprovalListVerdict(opts);
     const budget = Math.max(0, Math.floor(opts.autoBudget ?? 0));

package/dist/audit.d.ts

@@ -1,3 +1,4 @@
+import { type SessionPlacementRecord, type StoredPromptEpoch } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 /**
@@ -21,23 +22,39 @@ export interface SessionAudit {
      *  再回给调用方;直接消费本视图的宿主(`buildSessionAudit` 是包根导出)自己负责同一道脱敏。
      *  唯一一处服务端添键:用户消息行的回退手柄 `taskId`(给了 {@link RewindHandles} 才投,见 {@link buildRewindHandles})。 */
     messages: unknown[];
-    /** [ref]① web 观测切片 B: the session's prompt-epoch pin, core contract verbatim (core 1.304
-     *  `session.getPromptEpoch()` — first-class `prompt_epoch` entry, compaction restatement, [ref] anchor
-     *  all inside core). Additive; a pre-epoch session omits the key entirely (undefined). */
-    promptEpoch?: {
-        epoch: number;
-        artifactDigest: string;
-        packId: string;
-        assemblyApi: number;
-        activatedBy: "session_start" | "compaction" | "legacy_migration";
-    };
+    /** [ref]① web 观测切片 B: the session's prompt-epoch record as the engine reads it, verbatim (`session.getPromptEpoch()` —
+     *  first-class `prompt_epoch` entry, compaction restatement, [ref] anchor, the reading itself all inside the engine):
+     *  `{ kind: "pin", descriptor }` for a current-shape record, `{ kind: "legacy", centerPinned }` for a record an engine
+     *  ≤ 7.51 wrote (recognized by its retired field names). This view adds no reading of its own. A pre-epoch session omits
+     *  the key entirely (undefined). */
+    promptEpoch?: StoredPromptEpoch;
+}
+/**
+ * 会话视图体顶层 additive 键 `agent` —— **这只会话是哪只委派子代的转录**(`GET /v1/sessions/:id`;读法:终端侧链投影方按 fleet 帧的 `transcriptId`
+ * 读同一只会话读面,从体上拿到子代身份,不必再回头翻 fleet 行 —— 行一离场就没有了)。
+ *
+ * 只投影**存下来的 placement 元组**(`session_meta` 的 `placement_*` 列,首写不可变;店的 `placementOf` 一行 PK 探针),**不另铸**:
+ *  · `id` = 元组里的 `handle` —— 耐久 agent 行的 `a…` 键,与 fleet 行的 `id`、`GET /v1/agents/roster` 的 `handle` 是同一个串(core 铸元组时 `handle: taskId`);
+ *  · `parentSessionId` / `rootSessionId` = 元组里的同名格(派它的会话 / 委派树的根会话);
+ *  · 元组缺哪一格这里就缺哪一格(present-iff;不铸空串);元组的 `scope`(租户键)/ `placedAt` / `kind` 不上 wire。
+ * 键在场 = 这是一只委派子代的转录(哪怕元组只存了 `kind`,那时 `agent` 是 `{}`);键缺席 = 普通会话,**或这台部署的店不存 placement 元组**
+ * (local 后端:子代转录停驻前住私有短 TTL 店、停驻时拷进来的那一份是普通会话行 —— 事实没存就不报,消费方在 fleet 行 / `GET /v1/agents/roster` 上本就有 `id`)。
+ * 元组由引擎在**后台**委派子代(带耐久 agent 行、店声明了 placements)建会话时铸;同步委派的子代转录不落宿主店,没有元组。
+ */
+export interface SessionAgent {
+    id?: string;
+    parentSessionId?: string;
+    rootSessionId?: string;
 }
+/** {@link SessionAgent} 的唯一投影:店答出的 placement 元组 → 体上的 `agent` 值;`undefined`(普通会话 / 店没有这一面)⇒ 调用方不铸键。 */
+export declare function sessionAgentOf(placement: SessionPlacementRecord | undefined): SessionAgent | undefined;
 /**
  * 用户消息行的**回退手柄**表:用户条目 id → 回退时交给 `resumeAt` 的那个 `event_id`(R8 用户消息锚按 run 的 taskId 键入)。
  * 真源 = `resume_anchor`(锚店 `listBySession` 的读数),本表只是它对**一位读者**的一次投影。
  */
 export type RewindHandles = ReadonlyMap<string, string>;
-/** 会话视图读口(`ServiceDeps.sessionAudit`)的读者参数:`reader` = 读这张视图的**已验身份**(无身份 = `null`)。给了 ⇒ 用户消息行投回退手柄。 */
+/** 会话视图读口(`ServiceDeps.sessionAudit`)的读者参数:`reader` = 读这张视图的**已验身份**(无身份 = `null`)。给了 ⇒ 这是一次**视图读**:用户消息行投回退手柄、体顶层投 `agent`({@link sessionAgentOf});
+ *  不给(只要归属的调用方:memory-status / 自助抹除)⇒ 两样投影的读都不付。 */
 export interface SessionAuditReadOpts {
     readonly reader: string | null;
 }
@@ -56,15 +73,12 @@ export declare function buildRewindHandles(anchors: ReadonlyArray<{
  *  rewind-handle projection ({@link buildRewindHandles}); absent ⇒ no `taskId` keys. */
 export declare function buildSessionAudit(pool: Pool, sessionId: string, handles?: RewindHandles): Promise<SessionAudit | undefined>;
 /** The PG twin — same view over PgSessionStorage.wake. Until this, the
- *  audit face was TiDB-only and a PG/local deployment 404'd the whole web session area. local = follow-on
- *  (its storage seam has no wake-equivalent yet — may turn out to be a core gap). */
+ *  audit face was TiDB-only and a PG/local deployment 404'd the whole web session area. */
 export declare function buildSessionAuditPg(pool: PgPool, sessionId: string, handles?: RewindHandles): Promise<SessionAudit | undefined>;
-/** The LOCAL (File) leg — web session area on DB_BACKEND=local.
- *  repo 取自 `createLocalSessionRepo`(与 `LocalSessionStore` 同一只工厂):坏记录的披露座(F 类 `server.session-repo.corrupt-record-skipped`)
- *  因此在视图口同样在场 —— 视图照常返回、跳过的记录有计数 + 探针行(修前自建一只不带座的 repo,零披露)。
- *  实现姿势:`FileSessionRepo.exportEntries`(纯读、torn-tail 恢复、missing→not_found)→
- *  `boundedTail`(纯函数切 floor)→ InMemorySessionStorage → 同一 auditFromStorage 内核。零写面、
- *  零新 seam;createdAt 从 repo.list() 的 metadata 取(File 形态 meta 与 entries 分储)。 */
+/** The LOCAL (File) leg — web session area on DB_BACKEND=local: the same view over `LocalSessionWindow.wake`
+ *  (`plugins/local-session-window.ts`). All three legs read one way — a bounded window that carries the epoch anchor below its
+ *  floor — and on every backend that is what the run reads: the SQL twins' run wakes the same window; the local run wakes the whole
+ *  tree, and the local window is cut from that tree's branch, with the anchor walking the branch below the floor. */
 export declare function buildSessionAuditLocal(root: string, sessionId: string, handles?: RewindHandles): Promise<SessionAudit | undefined>;
 /**
  * 🔴 **会话视图的读面口 —— `GET /v1/sessions/:id` 的全部取法(整读 / `?tail` / `?before` / `?blobCap` / `?message=N`)共用这一只**。

package/dist/audit.js

@@ -1,11 +1,20 @@
-import { StoredSession, InMemorySessionStorage, boundedTail } from "@sema-agent/core";
+import { StoredSession } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./plugins/tidb-session-storage.js";
 import { PgSessionStorage } from "./plugins/pg-session-storage.js";
-import { createLocalSessionRepo } from "./plugins/local-session-store.js";
+import { LocalSessionWindow } from "./plugins/local-session-window.js";
 import { redactModelText } from "./observability/run-terminal.js";
 import { redactDeepWith } from "./trace/redact.js";
 import { projectToolStructured } from "./trace/tool-output-media.js";
 import { INJECTED_BLOCK_RE, isAttachmentFrame } from "./user-authored-text.js";
+export function sessionAgentOf(placement) {
+    if (placement === undefined)
+        return undefined;
+    return {
+        ...(placement.handle !== undefined ? { id: placement.handle } : {}),
+        ...(placement.parentSessionId !== undefined ? { parentSessionId: placement.parentSessionId } : {}),
+        ...(placement.rootSessionId !== undefined ? { rootSessionId: placement.rootSessionId } : {}),
+    };
+}
 export function buildRewindHandles(anchors, reader) {
     const byEntry = new Map();
     for (const a of anchors) {
@@ -26,20 +35,7 @@ export async function buildSessionAuditPg(pool, sessionId, handles) {
     return auditFromStorage(await PgSessionStorage.wake(pool, sessionId), sessionId, handles);
 }
 export async function buildSessionAuditLocal(root, sessionId, handles) {
-    const repo = createLocalSessionRepo(root);
-    let entries;
-    try {
-        entries = await repo.exportEntries(sessionId);
-    }
-    catch (e) {
-        if (e.code === "not_found")
-            return undefined;
-        throw e;
-    }
-    const meta = (await repo.list()).find((m) => m.id === sessionId);
-    const { tail, floorEntryId } = boundedTail(entries);
-    const storage = new InMemorySessionStorage({ entries: tail, floorEntryId, ...(meta ? { metadata: meta } : {}) });
-    return auditFromStorage(storage, sessionId, handles);
+    return auditFromStorage(await LocalSessionWindow.wake(root, sessionId), sessionId, handles);
 }
 async function auditFromStorage(storage, sessionId, handles) {
     if (!storage)

package/dist/auth-bridge.d.ts

@@ -45,6 +45,10 @@ export type VerifyOutcome = {
 export interface WebAdminJwtVerifier {
     verify: (bearer: string) => Promise<VerifyOutcome>;
 }
+/** 缓存键的常规刷新周期缺省(秒):过期后下一发在后台重拉,当前请求不等。 */
+export declare const DEFAULT_JWKS_TTL_SEC: number;
+/** 一次 JWKS 拉取的时限(毫秒):kid 未知、超离线宽限、后台刷新三条路用同一只拉取,同一个时限。 */
+export declare const JWKS_FETCH_TIMEOUT_MS = 10000;
 /**
  * registry-JWT verifier(单例,进程级 JWKS 缓存)。`verify(bearer)` 全程不 throw——一切异常折为
  * AUTH_BRIDGE_ERROR_CODES(HTTP 面由调用方恒答 generic 401,码只进日志/metrics,R9)。