@sema-agent/server 7.20.0 → 7.21.0-rc.1

package/dist/tool-approval.d.ts

@@ -108,6 +108,41 @@ export interface ToolApprovalFrame {
         match: "exact" | "prefix";
         command: string;
     }>;
+    /**
+     * #253 件 G1(core 5.33.0 backlog #239,判据帖 [3930] G1;**ADDITIVE**,`"tool_approval"` only)——
+     * 这次 ask **为什么**被收紧的**结构化**因由(`AskRequest.probeCause`:工具的 `reversibilityProbe`
+     * 判不出可回滚时,引擎在 maybe 档收紧点铸并 `normalizeProbeCause` 校验过的那一只)。
+     *
+     * 🔴 **结构就是契约**:`{ code, roots:{shown,total}, further?:{shown,total} }` —— `code` 机器可读、
+     * 两个操作数族各带真实基数。引擎的原话是「ships a code and operand arrays, never a finished
+     * sentence」,句子归呈卡端渲。⇒ server **逐字透传结构**,不拍扁成文本、不重排、不合并两族。
+     * 值经 `approval-card.ts` 的 `readProbeCause` 窄读(与 `card_json` **同一个**函数 ⇒ 两面同值);
+     * 形不合按缺席处置,`code` 超限整只丢、`shown` 超限截条目而 `total` 保真(理由见那里的顶注)。
+     *
+     * 🔴 **与 `message` 刻意分列**(判据帖 G1 的负控):`message` 是分类器/模型的输入面,cause 永不进它;
+     * 本键是展示面的结构化数据。负控钉在 `test/approval-probe-cause-wire.test.ts` §3。
+     *
+     * 🔴 **缺席 ≠「没有原因」**:只有 maybe 档收紧且探针真给了 cause 的 ask 才有它。
+     *
+     * 耐久路的对偶 = `gate.riskDescriptor.probeCause`(同值,core `buildRiskDescriptor` 铸),走 checkpoint
+     * 行的**整体透传**到 `GET /v1/approvals` —— 键集零施工,钉在同一个文件的 §4。
+     *
+     * 姊妹键 `AskRequest.probeReason`(同一件事的**散文**兄弟)**今天不投影**:它与本键是同一个事实的两种
+     * 拼法,而 core 的边界哲学(交 code + 数组、不交句子)与「一张卡上不放两份同义解释」都指向只投结构化
+     * 那一份;散文那份还无法被消费端本地化。照 `preview` / `requiresRealApproval` 先例 = 候消费端(cli)
+     * 提渲染需求再翻(登记在 `trace/core-keyset-guard.ts` 的 EXCLUDED 栏)。
+     */
+    probeCause?: {
+        code: string;
+        roots: {
+            shown: string[];
+            total: number;
+        };
+        further?: {
+            shown: string[];
+            total: number;
+        };
+    };
     /** "tool_approval" only: the tool call's args, secret-redacted, UNTRUSTED-for-display. Absent (with
      *  `argsOmitted: true`) when over the byte cap or unserializable. */
     args?: unknown;

package/dist/tool-approval.js

@@ -48,7 +48,7 @@ import { uuidv7, MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "./trace/redact.js";
 import { createLogger } from "./observability/logger.js";
 import { deriveAskId, deriveBatchId, MAX_DECISION_NOTE_CHARS } from "./approval-ask-machine.js";
-import { ApprovalCardEnvelopeSchema, MAX_RULE_SUGGESTIONS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, } from "./approval-card.js";
+import { ApprovalCardEnvelopeSchema, MAX_RULE_SUGGESTIONS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, readProbeCause, } from "./approval-card.js";
 import { governanceAskMarksFor, runWithGovernanceAskScope } from "./governance-ask-marks.js";
 /** #151 车2:本模块自有的日志出口——同 config-provider.ts/runtime-caps-resolver.ts 先例(协调器不走
  *  DI logger,构造签名是设计定稿钉死的三键 options bag,加第四个 logger 键属于重议已裁事项）。仅用于
@@ -900,6 +900,9 @@ export class ToolApprovalCoordinator {
                 : {}),
             // #154 车二:候选逐字透传(条件见 `ruleLaneMaterial` 上方注)。
             ...(ruleLaneMaterial !== undefined ? { ruleSuggestions: ruleLaneMaterial.suggestions } : {}),
+            // #253 件 G1:结构化探针因由。窄读走 `approval-card.ts` 的 `readProbeCause` —— **卡也用它**,
+            // 所以活卡帧与 `card_json` 是同一份值(而不是两处各挑一次键)。缺席/形不合 ⇒ 不铸键。
+            ...((c) => (c !== undefined ? { probeCause: c } : {}))(readProbeCause(req)),
             ...(bounded.omitted ? { argsOmitted: true } : { args: bounded.args }),
         };
         // #151 车2(design/172 §3.3 D3 窗长三元):有效窗——legDeadlineMonotonic 缺席时退化成 ttlMs(D1 零

package/dist/trace/core-keyset-guard.d.ts

@@ -26,8 +26,8 @@ type BgNotifExcluded = "kind" | "sessionScoped" | "owner" | "scope" | "descripti
 type _GuardBgNotif = AssertAllKeysHandled<Exclude<keyof BackgroundChildEvent, BgNotifProjected | BgNotifExcluded>>;
 type RosterProjected = "name" | "agentId" | "sessionId" | "toolUseId" | "owner" | "scope" | "sessionScoped" | "rootSessionId" | "model" | "modelFallback" | "createdAt";
 type _GuardRoster = AssertAllKeysHandled<Exclude<keyof RosterEntry, RosterProjected>>;
-type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation" | "ruleSuggestions" | "persistedRuleShadowed";
-type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash" | "isDelegatedChild";
+type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation" | "ruleSuggestions" | "persistedRuleShadowed" | "probeCause";
+type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash" | "isDelegatedChild" | "probeReason";
 type _GuardAsk = AssertAllKeysHandled<Exclude<keyof AskRequest, AskProjected | AskExcluded>>;
 type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome" | "human_input" | "wiring_manifest";
 type _GuardTaskEvent = AssertAllKeysHandled<Exclude<TaskEvent["type"], TaskEventHandled>>;

package/dist/trace/ledger-events.d.ts

@@ -0,0 +1,43 @@
+/**
+ * runs 账本(`task_run_event`)的**事件型闭集**——A-032 P1-③ / codex 对抗复审 F2。
+ *
+ * ## 为什么需要这个联合
+ * 账本行的 `type` 是消费端分流的键:`GET /v1/runs/:id/events` 裸回放照发,而 `trace/project.ts` 的
+ * `mapTraceEventInner` 要把其中一部分投影成 registry 契约 2.3 的 SSE 帧,剩下的**刻意**落 null。
+ * 「新加了一个账本事件型却没人给它归类」这件事此前只能靠源码扫描发现,而扫描对**别名门**是盲的
+ * (真例:`http/server.ts` 的 `const ap = (type, data) => rs2.appendEvent(...)`,以及
+ * `ap(reSuspended ? reParkStatus : "suspended", …)` 这种**动态**首参 —— 任何词法门都抓不到)。
+ * 把词表收成一个**类型**,新型就必须先在这里登记(否则调用点编译红),投影闭合门再从这里枚举 ⇒
+ * 「加型 ⇒ 必须归类」变成编译期 + 门的两道执法,不再依赖扫描器的视力。
+ *
+ * ## 执法面(收到哪一层)
+ * 联合被**三层**写口共同引用,所以"绕开 typed 门直写"这条路已经堵死(codex R2-F2:此前只收了
+ * `LedgerSink.append`,底层 `appendEvent` 仍吃 `string`,`const t = "x"; runStore.appendEvent(id, seq, t, d)`
+ * 既过编译又躲过逐行字面量扫描):
+ *  1. `LedgerSink.append` / `trace/project.ts` 的 `AppendFn` / 各腿的 `append`·`ap`·`approvalEmit` 闭包;
+ *  2. `createLedgerSink({ appendEvent })` 的回调签名;
+ *  3. **三个 RunStore 实现**的 `appendEvent(taskId, seq, type, data)`(SQL / file / memory)—— 账本行的
+ *     最终落点,类型收在这里才与"能不能写进去"同源。
+ *
+ * ## 射程上限(如实,别夸大)
+ * 仍有**一条动态门**:`http/server.ts` 的通知 drain 回调把 core 帧的 `type` 逐字落账(那里有一处
+ * 显式窄化 + 自陈注释)。它今天产出的是 `task_notification`(已在册),但 core 换帧名时本联合**不会**
+ * 自动红 —— 那条腿的对齐由 core 帧集的消费门(`trace/core-keyset-guard.ts` 一族)负责,不是这里。
+ * 另有若干测试用显式窄化写入**历史行名**(`brain_status`)或合成桩型:那是在模拟"库里躺着的旧行/
+ * 失败路径",不是本版本的写口 —— 本联合的语义是「**这个版本会写出来的型**」,故不收它们。
+ *
+ * ## 成员的两类
+ *  · **流事件投影**:两条 durable 腿(bg = `runs.ts` + `trace/ledger-sink.ts`,resume = `http/server.ts`)
+ *    的 `switch (ev.type)` 白名单臂(差集门 `test/durable-append-arm-parity.test.ts` 看守两腿一致);
+ *  · **腿自己的带外行**:park/终局/失败/建议/用量/装配自证(不来自流事件)。
+ */
+export type LedgerEventType = "reasoning" | "text" | "tool_start" | "tool_end" | "status" | "context_usage" | "compacted" | "diagnostics" | "steering_injected" | "compaction_outcome" | "workspace_changed" | "wiring_manifest" | "human_input" | "task_progress" | "task_notification" | "turn_end"
+/** park 行名**两个**(`appendParked(kind)` 逐字取自 `result.status`)。 */
+ | "suspended" | "needs_review" | "done" | "failed" | "suggestions" | "model_usage" | "prompt_assembled" | "config_assembled" | "file_link"
+/** 人在环三族的 open/close 帧对(投递面 = 本腿的 durable events tail)。 */
+ | "elicitation" | "elicitation_complete" | "question" | "question_complete" | "tool_approval" | "tool_approval_complete"
+/** design/172 §4.3 新协议的呈卡帧(与上面两只 tool_approval 帧同一条投递面)。 */
+ | "approval_request"
+/** 异步 workflow 完成的入箱 drain(`emitPendingWorkflowCompletions` 两个字面型之一)。 */
+ | "workflow_complete";
+//# sourceMappingURL=ledger-events.d.ts.map

package/dist/trace/ledger-events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ledger-events.js.map

package/dist/trace/ledger-sink.d.ts

@@ -1,4 +1,5 @@
 import { NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
+import type { LedgerEventType } from "./ledger-events.js";
 /**
  * LedgerSink — the SINGLE "stream event → durable runs-ledger" projection, shared by the background leg
  * (runs.ts `runInBackground`) and the sync `/v1/tasks/stream` detach lane (server.ts, `x-detach-on-disconnect`).
@@ -21,7 +22,7 @@ export interface LedgerSink {
     /** Seq-stamped raw append — for a leg's out-of-band rows (elicitation/question frames, model_usage deltas,
      *  suggestions, `failed`) that must share this run's single seq counter. Redaction is the CALLER's duty on
      *  this raw door (every existing site already redacts); the typed doors below redact internally. */
-    append(type: string, data: unknown): Promise<void>;
+    append(type: LedgerEventType, data: unknown): Promise<void>;
     /** Flush the buffered turn text/reasoning. Thinking precedes content within a turn → a buffered reasoning
      *  block flushes FIRST (redacted; core [R57]: CoT may carry reasoned-about secrets — TRACE_THINKING gates
      *  capture). The `text` row is stamped with the turn's first text eventId (E18 per-message resume handle,
@@ -53,7 +54,7 @@ export interface LedgerSink {
 }
 export declare function createLedgerSink(opts: {
     /** The seq-stamped durable append — typically `(seq, type, data) => runStore.appendEvent(taskId, seq, type, data)`. */
-    appendEvent: (seq: number, type: string, data: unknown) => Promise<void>;
+    appendEvent: (seq: number, type: LedgerEventType, data: unknown) => Promise<void>;
     /** TRACE_THINKING gate: reasoning deltas are buffered (later redacted+persisted) only when true (core [R57] —
      *  persisting CoT is a deployment decision). Both legs pass the SAME config source (`config.traceThinking`). */
     persistThinking: boolean;

package/dist/trace/project.d.ts

@@ -15,7 +15,10 @@
 import type { ApprovalSettledBy, TaskResult } from "@sema-agent/core";
 import type { RunEvent, RunRecord } from "../plugins/store-contracts.js";
 import type { ModelUsageDelta, ModelUsageTracker, PromptManifestRecord } from "../budget.js";
-type AppendFn = (type: string, data: unknown) => Promise<void>;
+import type { LedgerEventType } from "./ledger-events.js";
+/** 账本写口的统一签名 —— `type` 是**闭集**(`ledger-events.ts`):新型必须先登记,否则调用点编译红
+ *  (codex 对抗复审 F2:别名门 `ap("x")` 与动态首参让纯词法门结构性抓不全)。 */
+type AppendFn = (type: LedgerEventType, data: unknown) => Promise<void>;
 type GetEventsFn = (taskId: string, afterSeq: number) => Promise<RunEvent[]>;
 /** E8 (shell-host): drain the per-task model-usage accumulator into an append-only `model_usage` DELTA event.
  *  Shared by BOTH durable-write legs (runInBackground + the resume leg) so the persisted shape never drifts; the

package/dist/trace/project.js

@@ -903,6 +903,21 @@ function mapTraceEventInner(type, seq, data) {
             // approvals 的帧同形。这一处是 3.0.0 摘 legacy `code` 键时的漏网:帧在 src/trace/ 铸,而当时的门只扫
             // src/http/,于是"SSE error 帧机器键统一为 errorCode"的公开声明与 wire 上跑的东西不一致(门是绿的)。
             return { event: "error", data: { type: "error", errorCode: "WORKER_DOWN", message: redactSecrets(String(data.errorMessage ?? "run failed")) } };
+        // 🔴 **显式不投影**(A-032 P1-③ 裁定,2026-08-14)。这四型是账本写口(`trace/ledger-sink.ts` 与
+        // resume 腿都 append 它们)却从来不在任何 case 臂上,于是走的是下面那个 `default` —— 而「刻意不发帧」
+        // 与「忘了接线」在码面上**同形**,两者的下一步动作却相反(前者什么都不做,后者是缺陷)。写成显式臂
+        // 就是把裁定钉在源码上。裁的是「不投影」,理由不是懒:契约 2.3 的帧集是**闭集**(thinking/content/
+        // tool/turn/prompt/done/error 七类),给它加一个新帧名会让穷举式 closed-oneOf 消费端收到公开联合之外
+        // 的帧 —— design/158 B2 那次(durable 腿发 `brain_status`、公开联合只有 `status`)真咬过的同形。
+        // 这四型的消费面是 `GET /v1/runs/:id/events` 裸回放,不是这条流。特别地 `human_input` **不能**折成
+        // content/thinking:它是「谁经哪条载体喂了这条 run」的归属事实,映射成 agent 内容就是编造。
+        // 要改成投影 ⇒ 那是一次 wire 帧集扩张(能力发布件,须点名消费方表态),不是顺手加一行。
+        // 闭合门:test/probe-wire-1.test.ts「A-032 P1-③ 账本写口 ↔ mapTraceEvent 投影的三方闭合门」。
+        case "context_usage":
+        case "compaction_outcome":
+        case "wiring_manifest":
+        case "human_input":
+            return null;
         default:
             return null; // compacted etc. — not a client trace event
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.20.0",
+  "version": "7.21.0-rc.1",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.32.0",
+    "@sema-agent/core": "^5.33.0",
     "@sema-agent/registry-core": "^0.16.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",