@sema-agent/sdk 1.1.0 → 2.1.0

package/openapi.yaml

@@ -3857,6 +3857,13 @@ components:
 
     TaskResult:
       type: object
+      # 🔴 **刻意不封闭**(census 轴一裁定,2026-07-30)。此前是「没写」= JSON Schema 默认开放,分不清
+      # 「决定了要开」还是「忘了」;现在显式写成 true,让这条决定可读、可复审。理由:server 对引擎
+      # `TaskResult` 是**整体透传**(runs.ts `withModelUsage` 只做 `{...result, stats:{...}}` 的加法),
+      # 而 SDK 的 `TaskResult`/`TaskStats` 两侧都带 `[key: string]: unknown` 开集(types.ts:119)——把
+      # 这里改成 false 会让 spec 与本仓自己的类型面互相打脸,并且把「引擎加字段」判成 wire 违约(它不是)。
+      # 收紧这一面的正解不是 additionalProperties,是把引擎真发的键**逐个登记**(字段级 drift 门的活)。
+      additionalProperties: true
       description: Synchronous task result (`POST /v1/tasks`).
       required: [taskId, sessionId, status, stats]
       properties:
@@ -3921,6 +3928,10 @@ components:
 
     RunReceipt:
       type: object
+      # 封闭(census 轴一,2026-07-30):producer 铸造点 routes/runs.ts:180 与 idem 重放臂各自逐字写死
+      # `{taskId, sessionId, status}` —— 三键全在场、无第四键 ⇒ required 已完整,additionalProperties 收紧到
+      # false 后「server 多发一个 spec 没登记的键」当场红(此前 ①档只校已声明键的类型,多键完全不可见)。
+      additionalProperties: false
       description: Async run receipt (`POST /v1/runs` → 202). The capability token is NEVER on the wire.
       required: [taskId, sessionId, status]
       properties:
@@ -3934,6 +3945,10 @@ components:
         Run state (`GET /v1/runs/:id`) — live shape per the pinned wire contract Drift 2: `result` is the NESTED TaskResult
         object (output text in result.result, stats in result.stats; NO top-level stats), and the error text
         field is `error` (not errorMessage; errorCode is floated up from result.errorCode).
+      # 封闭(census 轴一,2026-07-30):铸造点 routes/runs.ts:337-351 是一个逐键写死的字面量,恰好 10 键
+      # (taskId/sessionId/status/result/supervisorCost/suggestions/errorCode/error/jobId/source),与本
+      # properties 一一对上;只有前三键无条件在场(其余走 `?? undefined` ⇒ JSON 丢键)⇒ required 维持 3 键。
+      additionalProperties: false
       required: [taskId, sessionId, status]
       properties:
         taskId: { type: string }
@@ -3963,10 +3978,14 @@ components:
       description: >
         Per-axis cost rollup for a supervised run. `llm` is `null` on a run whose LLM spend was not attributed
         (e.g. no brain call). All amounts are integer micro-USD (no float drift).
+      # 封闭(census 轴一,2026-07-30):composeSupervisorCost(observability/cost-taxonomy.ts)返回的是
+      # 三段闭合结构,TS 侧 `SupervisorCostBreakdown` 也没有索引签名 ⇒ 三层一并收紧。
+      additionalProperties: false
       required: [llm, infra, totalMicroUsd]
       properties:
         llm:
           type: ['object', 'null']
+          additionalProperties: false
           required: [llmRootMicroUsd, nestedSubagentMicroUsd, memoryConsolidationMicroUsd, compactionMicroUsd]
           properties:
             llmRootMicroUsd: { type: integer }
@@ -3976,6 +3995,7 @@ components:
         infra:
           type: object
           description: Service-owned infra rates (the engine prices only LLM tokens); all default 0 when unpriced.
+          additionalProperties: false
           required: [toolCallMicroUsd, sandboxWalltimeMicroUsd, egressMicroUsd, totalMicroUsd]
           properties:
             toolCallMicroUsd: { type: integer }
@@ -3989,6 +4009,9 @@ components:
       description: >
         Synchronous ack for `POST /v1/runs/:id/cancel`. `status` is "cancelling" (accepted) or a terminal status
         (idempotent no-op). NOTE: "cancelling" is NOT a RunStatus enum member — it only appears here.
+      # 封闭(census 轴一,2026-07-30):cancel 面的 7 个 sendJson 铸造点(routes/runs.ts:417/436/480/483/
+      # 495/505/512)键集的并集恰好 = {taskId, status, note?, errorCode?};taskId/status 无条件在场。
+      additionalProperties: false
       required: [taskId, status]
       properties:
         taskId: { type: string }
@@ -4151,7 +4174,12 @@ components:
       description: >
         Turn trace envelope (`GET /v1/tasks/:id/turns`). Key is `turns` (resource-named). `retainedFrom` marks
         the lowest retained seq. Turn ITEM shape is draft (co-design with artifacts, Q7).
-      required: [turns]
+      # 封闭 + required 补全(census 轴一,2026-07-30):铸造点 routes/trace-usage.ts:233
+      # `{ turns, ...(nextCursor?{nextCursor}:{}) , retainedFrom }` —— `retainedFrom` 是**无条件**键
+      # (`RunStore.retainedFrom(): Promise<number>`,四个实现都返回数字),此前只 required 了 `turns`,
+      # 于是「server 少发 retainedFrom」这种断页判据丢失对本门不可见。
+      additionalProperties: false
+      required: [turns, retainedFrom]
       properties:
         turns:
           type: array
@@ -4162,6 +4190,9 @@ components:
     TaskList:
       type: object
       description: Paginated run summaries (`GET /v1/tasks`). Envelope key is `tasks` (resource-named, NOT `items`).
+      # 封闭(census 轴一,2026-07-30):信封铸造点 routes/trace-usage.ts:201 只有 tasks + 条件 nextCursor。
+      # 行本身(`TaskSummary`)保持开集 —— 它的 TS 侧有索引签名(引擎透传),那份「开」是真的。
+      additionalProperties: false
       required: [tasks]
       properties:
         tasks:
@@ -4220,6 +4251,9 @@ components:
 
     ArtifactList:
       type: object
+      # 封闭(census 轴一,2026-07-30):铸造点 routes/trace-usage.ts:214 只有 artifacts 一键(无分页)。
+      # 行本身(`Artifact`)保持开集(TS 侧索引签名)。
+      additionalProperties: false
       required: [artifacts]
       properties:
         artifacts:
@@ -4282,6 +4316,10 @@ components:
       description: >
         Worker capability map (`GET /v1/capabilities`). Open set — ignore unknown keys.
         Booleans share deps with the route gates (can't say yes and then 501).
+      # 🔴 **刻意不封闭**(census 轴一裁定,2026-07-30):能力面按定义就是「新部署先长出一位、老客户端忽略它」
+      # 的探测面(TS 侧同样带索引签名),封闭它等于把「加一位能力」判成 wire 违约。`required` 也停在
+      # `version` 一键 —— 其余每一位都由部署侧的 deps 决定在不在场,没有第二个恒在键可钉。
+      # 本 schema 的真正收紧手段是别的两条:字段级 drift 门(键必须登记)+ capabilities-http 的整体 toEqual 门。
       required: [version]
       additionalProperties: true
       properties:
@@ -4992,6 +5030,9 @@ components:
     PendingList:
       type: object
       description: Envelope for pending HITL checkpoints (key `pending`, NOT a bare array — the pinned wire contract).
+      # 封闭(census 轴一,2026-07-30):三个铸造点(routes/approvals-assistant.ts:89/620/624)都只发
+      # `{ pending }`。行本身(`PendingCheckpoint`)保持开集(TS 侧索引签名)。
+      additionalProperties: false
       required: [pending]
       properties:
         pending:
@@ -5123,27 +5164,33 @@ components:
 
     InboxRow:
       description: >
-        ASSISTANT-WIRE-CONTRACT §2 — an inbox row = a CheckpointSummary + an `objective` (enriched from the
-        task ctx; `null` if unavailable).
-      allOf:
-        - $ref: '#/components/schemas/CheckpointSummary'
-        - type: object
-          properties:
-            objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
-            toolName:
-              type: ['string', 'null']
-              description: 'The gated tool, when the pause came from a tool call (null for non-tool gates).'
-            toolCallId: { type: string, description: 'The gated tool-call id.' }
-            boundCallId: { type: string, description: 'D-1 decision binding — echo it back on /decide.' }
-            boundInputHash:
-              type: string
-              description: >
-                D-1 decision binding — hash of the bound tool input. Echo on /decide so an approval cannot land on
-                a DIFFERENT call that was swapped in after the operator looked.
-            input:
-              description: >
-                REDACTED tool input for display. Untyped by design (per-tool shape) — and note the raw `toolInput`
-                is deliberately NOT on this row: the handler always strips it (along with `token`) before returning.
+        ASSISTANT-WIRE-CONTRACT §2 — an inbox row (server >=3.4.0 EXPLICIT-projection form): the §1 mirror keys
+        of a CheckpointSummary (token stripped; no rich per-tool fields) + two nullable enrichments.
+        NARROWING RECORD (2026-07-30, board [2027]->[2029]): rows used to also carry
+        toolName/toolCallId/preview/principal/sourceTaskId/contentKind (handler spread the whole projection) and
+        this spec over-declared decide bindings that never appeared on inbox wire at all. Four client repos were
+        structurally zero-consumers, so server 3.4.0 narrowed the wire and this schema follows. For the tool face
+        and decide bindings use /v1/approvals (PendingCheckpoint); for task attribution use /v1/assistant/tasks.
+      type: object
+      required: [sessionId, scope, objective, input]
+      additionalProperties: false
+      properties:
+        sessionId: { type: string, description: 'The suspended task/session id.' }
+        scope: { type: string, description: 'Multi-tenant owner scope.' }
+        createdAt: { type: number, description: 'Ask creation time (epoch ms).' }
+        gateKind:
+          type: string
+          description: 'Same open set as CheckpointSummary.gateKind.'
+          enum: [human, irreversible_ask, resource_limit, needs_review, plan_review, task_done]
+          x-open-enum: true
+        severity: { type: integer, minimum: 1, maximum: 5, description: 'Sort key; only human/irreversible_ask carry it.' }
+        spentMicroUsd: { type: number, description: 'Accumulated spend on the suspend chain (micro-USD).' }
+        deadline: { type: number, description: 'Awaiting-human SLA deadline (epoch ms).' }
+        objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
+        input:
+          description: >
+            REDACTED tool-args preview for display (null on gates without one, e.g. plan_review). Untyped by
+            design (per-tool shape). The raw `toolInput` is deliberately NOT on this row.
 
     InboxList:
       type: object
@@ -5292,6 +5339,10 @@ components:
       description: >
         Session audit (`GET /v1/sessions/:id`) — true shape. `messages` = current model context
         (older history folded into a summary message); can be large.
+      # 🔴 **暂不封闭**(census 轴一裁定,2026-07-30):本体是 core `StoredSession.buildContext()` 的投影
+      # (server `audit.ts` auditFromStorage),再叠 server 自己的两条 additive 后处理(windowMessages /
+      # truncateMessageBlobs)与路由层追加的 owner —— 键集由「core 投影 × 查询参数」共同决定,不是一个
+      # 写死的字面量。封闭它要先把这三层的键集逐一钉死,属于下一段的活,不在本批。
       required: [sessionId, createdAt, messages]
       additionalProperties: true
       properties:
@@ -5685,6 +5736,11 @@ components:
         - $ref: '#/components/schemas/Event_steering_injected'
         - $ref: '#/components/schemas/Event_done'
         - $ref: '#/components/schemas/Event_failed'
+        # 🔴 census 轴一(2026-07-30)补的 4 臂:server 今天就真发,spec/SDK 两侧此前同缺(详见各 schema 处的注)。
+        - $ref: '#/components/schemas/Event_context_usage'
+        - $ref: '#/components/schemas/Event_config_assembled'
+        - $ref: '#/components/schemas/Event_needs_review'
+        - $ref: '#/components/schemas/Event_message_committed'
       discriminator:
         propertyName: type
         mapping:
@@ -5710,15 +5766,26 @@ components:
           steering_injected: '#/components/schemas/Event_steering_injected'
           done: '#/components/schemas/Event_done'
           failed: '#/components/schemas/Event_failed'
+          context_usage: '#/components/schemas/Event_context_usage'
+          config_assembled: '#/components/schemas/Event_config_assembled'
+          needs_review: '#/components/schemas/Event_needs_review'
+          message_committed: '#/components/schemas/Event_message_committed'
 
     # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
     # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
     # `text` re-stamps the turn's first text_delta eventId, runs.ts:250); parentToolCallId = sub-agent attribution.
     EventIdentity:
       type: object
+      # 🔴 census 轴一(2026-07-30)亲读铸造点补的两键:LIVE 腿的白名单化 catch-all
+      # (server `routes/tasks.ts:640-648`,text_delta / turn_end / message_committed / context_usage 四臂)
+      # 传的是**四个** identity 键,而 durable 腿的 `identityFields`(trace/project.ts:101)只传前两个
+      # ——「两腿两策」是那段代码自己写下的口径。此前 spec 只声明两键 ⇒ 在封闭这些臂时会把真键判成违约。
+      # 声明面取两腿并集(逐臂再收窄不值当),缺席即缺席。
       properties:
         eventId: { type: string }
         parentToolCallId: { type: string }
+        sourceTaskId: { type: string, description: 'LIVE 腿四臂专属(durable 腿不发):core 的来源任务归因键。' }
+        bgAgentId: { type: string, description: 'LIVE 腿四臂专属(durable 腿不发):core 1.370 后台子代 agent 标识。' }
     Event_meta:
       type: object
       description: >-
@@ -5727,6 +5794,8 @@ components:
         condition: durable-ledger leg only (no ledger => neither header nor frame). sessionId rides along
         (needed to bind subsequent turns when the server minted a fresh session). Always precedes any content
         frame. NOT an engine event — server-minted, no EventIdentity.
+      # 封闭:铸造点 routes/tasks.ts:122 是逐字写死的三键字面量(sessionId 条件在场)。
+      additionalProperties: false
       required: [type, taskId]
       properties:
         type: { const: meta }
@@ -5736,43 +5805,77 @@ components:
       type: object
       description: durable stream only — turn-aggregated thinking.
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      # 🔴 封闭 + identity 本地镜像(census 轴一,2026-07-30)。为什么要镜像:JSON Schema 里
+      # `additionalProperties` 只认**同一个 subschema** 的 `properties`,`allOf` 分支($ref EventIdentity)
+      # 声明的键不在它的作用域内 —— 只写 `additionalProperties: false` 会把合法的 eventId 判成违约
+      # (draft-07 的 ajv 也不支持能跨 allOf 结算的 `unevaluatedProperties`,写了会被静默忽略 = 假绿)。
+      # 镜像取两腿并集(超集,宁可漏抓不可假红);`$ref` 保留(spec.test.ts:92 的 §E2 门要它)。
+      # 镜像与 EventIdentity 的一致性由 spec.test.ts 的「封闭臂必须镜像全部 identity 键」门看守。
+      additionalProperties: false
       required: [type, text]
       properties:
         type: { const: reasoning }
         text: { type: string }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_text:
       type: object
       description: durable stream only — turn-aggregated answer text (carries the E18 resume-handle eventId).
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
       required: [type, text]
       properties:
         type: { const: text }
         text: { type: string }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_reasoning_delta:
       type: object
       description: live stream only — per-token thinking fragment (`delta` is the string fragment).
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
       required: [type, delta]
       properties:
         type: { const: reasoning_delta }
         delta: { type: string }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_text_delta:
       type: object
       description: live stream only — per-token answer fragment.
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
       required: [type, delta]
       properties:
         type: { const: text_delta }
         delta: { type: string }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_tool_start:
       type: object
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
       required: [type, toolCallId, toolName]
       properties:
         type: { const: tool_start }
         toolCallId: { type: string }
         toolName: { type: string }
+        # 🔴 census 轴一(2026-07-30)回填:server 白名单 builder `toolStartEventData`(trace/project.ts:112)
+        # 真发 `label`(core 展示名,与 tool_end 同待遇),spec 此前漏声明 —— 封闭前必须先补,否则真帧变假红。
+        label: { type: string, description: 'core 展示名(缺席 ⇒ 用 toolName 渲染)。' }
         args: {}
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_tool_end:
       type: object
       description: >
@@ -5781,35 +5884,96 @@ components:
         (`truncated: true`). Absent ⇒ the tool produced no body. 🔴 UNTRUSTED RAW + observability-only: the service
         has redactDeep'd + size-bounded it; a consumer MAY further bound, MUST never re-feed it to a model.
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
       required: [type, toolCallId, toolName, isError]
       properties:
         type: { const: tool_end }
         toolCallId: { type: string }
         toolName: { type: string }
+        # 🔴 census 轴一(2026-07-30)回填:`toolEndEventData`(trace/project.ts:125)真发 `label` 与
+        # `structured`,spec 此前两者都漏 —— SDK 的 events.ts 早已声明,漂移只在 spec 这一侧。
+        label: { type: string, description: 'core 展示名(同 tool_start.label)。' }
+        structured: {}   # core 1.203 CC 卡片明细;与 output 同一 UNTRUSTED RAW 待遇(已 redactDeep),形状开放
         isError: { type: boolean }
         output: {}   # NON-UNIFORM: string | (TextContent|ImageContent)[] | (truncated) string. Absent ⇒ no body.
         truncated: { type: boolean }
         totalChars: { type: integer, description: 'core >=1.442 (RB-210): honest ORIGINAL size when truncated — sum of each block''s true size (text=chars, image/document=base64 bytes), no JSON-wrapping overhead. Absent on older cores / untruncated results.' }  # true ⇒ output was size-bounded to a truncated string.
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_turn_end:
       type: object
+      # 🔴 census 轴一(2026-07-30):`turn_end` 走 LIVE 腿的白名单 catch-all(routes/tasks.ts:646),该分支
+      # 对四个 identity 键做条件 spread —— 即「core 若真在 turn_end 上盖了 identity,它会上 wire」。
+      # 处置:**不** allOf EventIdentity(契约面继续不承诺生命周期臂带 identity,spec.test.ts §E2 那条钉
+      # 保持有效),但把四键作为本地可选属性声明出来,好让下面的封闭对那条真实代码路径不产生假红。
+      additionalProperties: false
       required: [type]
       properties:
         type: { const: turn_end }
         usage:
           type: object
           description: Full live shape — the portal cost bar's data source.
+          # 本子对象是 core 的 usage 结构原样透传(builder 不重建),留开集。
+          additionalProperties: true
           properties:
             inputTokens: { type: integer }
             outputTokens: { type: integer }
             cacheReadTokens: { type: integer }
             cacheWriteTokens: { type: integer }
             costMicroUsd: { type: integer }
+        # 🔴 census 轴一(2026-07-30)回填:`turnEndEventData`(trace/project.ts:449)是 2026-07-25 才补的
+        # builder,它带上来的这两键 spec 从未声明过 —— 而它们恰恰是**诚实缺席**语义的载体:
+        # `usageMissing` 缺了,「没有 usage」会被读成「用量是 0」而不是「未知」。
+        usageMissing: { const: true, description: '本轮用量不可信/缺失的诚实标记。缺席 ⇒ usage 可信。' }
+        stopReason: { type: string, description: '这一轮为什么停(max_tokens / stop_sequence / …),core 原词。' }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_compacted:
       type: object
+      # 🔴 **刻意不封闭**(SDK events.ts 的 compacted 臂带 `[k: string]: unknown`),但 census 轴一
+      # (2026-07-30)把 `compactedEventData`(trace/project.ts:340-407)真发的键**全部登记**了一遍 ——
+      # 此前 spec 只有 tokensBefore 一键,连 fixture 天天在喂的 `trigger` 都不在声明面上。
+      additionalProperties: true
       required: [type]
       properties:
         type: { const: compacted }
         tokensBefore: { type: integer }
+        trigger: { type: string, description: 'auto(逼近窗口上限)| manual(/compact)。缺席按 auto 渲染。' }
+        preserved_segment:
+          type: object
+          required: [firstKeptEntryId]
+          properties:
+            firstKeptEntryId: { type: string }
+        attachedFiles:
+          type: array
+          description: '压缩时随行附回的工作文件清单(path 已 redact;畸形元素由 builder 丢弃,全丢则整键缺席)。'
+          items:
+            type: object
+            required: [path, chars, truncated]
+            properties:
+              path: { type: string }
+              chars: { type: integer }
+              truncated: { type: boolean }
+        modelFallback: { const: true, description: 'core 1.286:压缩摘要器回退到更大窗模型。' }
+        fallbackReason: { type: string, description: "回退原因(今天只有 'window')。" }
+        clampedRatio: { type: number, description: 'core 1.286:keep 比例被夹紧后的值。' }
+        clampReason: { type: string, description: 'budget | walltime | tolerance。' }
+        tokensAfter: { type: integer }
+        triggerTokensBefore: { type: integer }
+        durationMs: { type: integer }
+        phaseDurations:
+          type: object
+          description: 'core 1.289 CompactionPhaseDurations —— builder 逐字段重建的闭合数值结构。'
+          additionalProperties: false
+          properties:
+            prepareMs: { type: integer }
+            summaryMs: { type: integer }
+            persistMs: { type: integer }
+            ptlRetries: { type: integer }
     Event_suggestions:
       type: object
       description: >
@@ -5817,6 +5981,8 @@ components:
         post-completion "what to ask next" prompt suggestions. Appended to the DURABLE run-events tail AFTER a
         `done` with `status:"completed"` (core's fire-and-forget LLM pass). 🔴 UNTRUSTED model text, service-
         redacted, UI-ONLY — render as clickable next-prompt chips; NEVER re-feed to a model. Empty/absent ⇒ none.
+      # 封闭:铸造点 runs.ts `append("suggestions", { suggestions })` 只有这一键。
+      additionalProperties: false
       required: [type, suggestions]
       properties:
         type: { const: suggestions }
@@ -5835,27 +6001,37 @@ components:
         `brain_status` alias arm was REMOVED from this union in SDK 1.0.0 (supported floor = server >=1.317, at
         which point the literal is never emitted on either leg).
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注(builder=brainStatusEventData)
       required: [type, phase]
       properties:
         type: { const: status }
         phase: { type: string, description: "rate_limited | retrying | reconnecting | circuit_open (open set)" }
         detail: { type: string, description: "neutral human hint (NO provider/HTTP detail)" }
         retryInSec: { type: number }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_task_progress:
       type: object
       description: >
         design/99 MF-10 (core 1.147+, `task_progress` arm) — a SUBAGENT PROGRESS TICK: a delegated sub-run's usage
         ACCRUING at each turn boundary WHILE it runs (tokens/tool-uses climbing), so a parent UI animates the Task
         card rollup. Emitted ONLY for a subagent (a task carrying a `parentToolCallId`, via EventIdentity); a
-        top-level run's own usage is the consumer's own (turn_end). `status` is the literal "running" (the terminal
-        usage is the `done` result). LIVE/EPHEMERAL — NOT persisted, NOT replayed on resume.
-        🔴 WIRE NOTE: core mints this arm, but as of service 1bf7a5c NO service projection forwards it onto a CLIENT
-        wire (/v1/tasks/stream or /v1/runs/:id/events) — the service consumes it INTERNALLY (fleetRunPublisher) and
-        re-expresses it as a fleet CHILD row on /v1/fleet/stream. So today MF-10 is observable via the fleet stream
-        subagent child rows; this arm is the core-arm MIRROR and surfaces on the task/run streams ONLY IF a future
-        service projection passes it through. Additive / tolerate-absent.
+        top-level run's own usage is the consumer's own (turn_end).
+        🔴 WIRE NOTE(2026-07-30 更正 — 旧注「as of service 1bf7a5c NO service projection forwards it onto a
+        CLIENT wire」已是 doc-rot,SDK events.ts 早已改口):server **确实**在三条腿上转发本臂
+        (`taskProgressEventData`,bg runs.ts append / resume append / 同步 live SSE),此外才是 fleet 子行。
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
-      required: [type, taskId, usage, status]
+      # 🔴 census 轴一(2026-07-30)三处纠正,依据=亲读 `taskProgressEventData`(trace/project.ts:146-166):
+      #  ① required 过严 —— builder 里 `usage`/`status` 都是**条件 spread**,只有 `taskId` 无条件在场;
+      #     spec 却把它们列进 required ⇒ 一个没带 usage 的真 tick 会被判违约(方向反了的假红)。
+      #  ② `status` 写成 `const: running` 太窄 —— core [1414]#3 的 settle 终态 tick("completed"/"failed")
+      #     server ≥1.258 原样转发,SDK 的臂也是开集字符串。
+      #  ③ 漏 5 个 builder 真发的键(name / parentTaskId / currentAction / workflowRunId / workflowAgentLabel),
+      #     全都在 SDK events.ts 上声明着 —— 漂移只在 spec 这一侧。
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
+      required: [type, taskId]
       properties:
         type: { const: task_progress }
         taskId: { type: string, description: 'The subagent task id (the delegated sub-run).' }
@@ -5867,7 +6043,16 @@ components:
             totalTokens: { type: integer }
             toolUses: { type: integer }
             durationMs: { type: integer }
-        status: { const: running, description: 'Always "running" mid-run (the terminal usage is the done result).' }
+        status: { type: string, description: 'running 为主;core [1414]#3 的 settle 终态 tick 亦可为 completed/failed(开集,按未知值兜底渲染)。' }
+        name: { type: string, description: '子代的人类展示名(UNTRUSTED,已 redactSecrets)。缺席 ⇒ 无名,别回退到 objective。' }
+        parentTaskId: { type: string, description: '嵌套子代的上级 taskId;缺席 ⇒ 一级子代。' }
+        currentAction: { type: string, description: '子代最近一次 tool_start 的一行人话("Bash npm test");UNTRUSTED,已 redactSecrets。' }
+        workflowRunId: { type: string, description: 'core 1.401:后台 workflow 子代的不透明 run id(下游据此跳过与 fleet 行的重复渲染)。' }
+        workflowAgentLabel: { type: string, description: '脚本作者可控的展示字符串;UNTRUSTED,已 redactSecrets。' }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_workspace_changed:
       type: object
       description: >
@@ -5875,10 +6060,15 @@ components:
         new RAW logical cwd so a shell UI updates its prompt/path. Only fires with a real shell mounted; the initial
         cwd is NOT announced (only subsequent changes). EPHEMERAL — not persisted; resets across suspend/resume.
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
       required: [type, cwd]
       properties:
         type: { const: workspace_changed }
         cwd: { type: string }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     CheckpointGate:
       # 从 `Event_suspended.gate` 的内联 oneOf 提取为命名 schema(2026-07-25 回填批)。两个理由:
       #  ① 内联形生成不出可复用具名类型;② 反射式 drift 门只按「命名 schema ↔ 同名 exported interface」配对,
@@ -5936,6 +6126,9 @@ components:
     Event_suspended:
       type: object
       description: HITL — the run paused on an F4 gate or AskUserQuestion. Resolve via approvals.decide, then resume.
+      # 封闭(census 轴一,2026-07-30)。两个铸造点都是写死的字面量:server.ts:2147 `{gate}`、
+      # server.ts:2161 `{gate:null, reopened}` —— 后者的 `reopened` 此前 spec 完全没有,是本次亲读补上的。
+      additionalProperties: false
       required: [type]
       properties:
         type: { const: suspended }
@@ -5944,6 +6137,11 @@ components:
           oneOf:
             - $ref: '#/components/schemas/CheckpointGate'
             - type: 'null'
+        reopened:
+          type: ['string', 'null']
+          description: >
+            server.ts:2161 —— 一条 resume 腿把 run 重新挂回 suspended 时,带上「为什么重开」的 errorCode
+            (无则显式 null)。只出现在这条重开臂上;普通挂起帧不带此键。
     ModelUsageDelta:
       # 新增(2026-07-25 回填批)。SDK 的 facade 审计把这个形状命名了一次(此前是在两个使用点各写一遍的匿名内联形:
       # `AgentEvent` 的 `model_usage` 臂 与 `done.result.stats.modelUsage` 的值类型,同源同形)。
@@ -6031,6 +6229,7 @@ components:
         rendering affordances). 🔴 `url` EXPIRES after `ttlSec` seconds — render a fetch-soon affordance, never
         persist the URL as durable.
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注(server 校验入参,闭集上 wire)
       required: [type, url, filename, size, ttlSec, status]
       properties:
         type: { const: file_link }
@@ -6041,6 +6240,10 @@ components:
         status: { type: string, enum: [normal, proactive], description: '`normal` = a turn deliverable; `proactive` = a mid-run push.' }
         caption: { type: string }
         display: { type: string, enum: [render, attach], description: 'absent = the consumer''s default.' }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
 
     Event_prompt_assembled:
       type: object
@@ -6059,6 +6262,9 @@ components:
       description: >
         Per-model usage delta (live-verified on canary). `usage` is keyed BY MODEL NAME — same source as
         `done.result.stats.modelUsage` (lets a multi-model / role-routed run attribute spend per model).
+      # 封闭:铸造点 trace/project.ts:27 `append("model_usage", { usage: delta })` 只有这一键
+      #(map 的**值**仍是开集 ModelUsageDelta —— 那层的「开」是真的,不动)。
+      additionalProperties: false
       required: [type, usage]
       properties:
         type: { const: model_usage }
@@ -6275,17 +6481,106 @@ components:
     Event_done:
       type: object
       description: Carries the full TaskResult (output string at .result, stats at .stats) — service Drift 4.
+      additionalProperties: false   # 封闭:帧本身只有 {type,result};`result` 内部保持开集(见 TaskResult 处的裁定注)
       required: [type, result]
       properties:
         type: { const: done }
         result: { $ref: '#/components/schemas/TaskResult' }
     Event_failed:
       type: object
+      # 封闭 + 回填 `activeTaskId`(census 轴一,2026-07-30):[1833] G10 —— session 已有活跃 run 的冲突
+      # 失败形会带上占用者 taskId(SDK events.ts 早已声明,spec 侧漏)。
+      additionalProperties: false
       required: [type]
       properties:
         type: { const: failed }
         errorCode: { type: string }
         errorMessage: { type: string }
+        activeTaskId: { type: string, description: '冲突失败形:当前占着该 session 的 run —— 消费方可直接引导 cancel/attach。' }
+
+    # ══════════════════════════════════════════════════════════════════════════════════════════════
+    # 🔴 census 轴一(2026-07-30)补的**四个未登记臂**。它们不是「将来会有」——**今天就在 wire 上**:
+    #   · `context_usage`     LIVE(routes/tasks.ts:653)+ DURABLE(trace/ledger-sink.ts:144 / server.ts:2115)
+    #   · `config_assembled`  DURABLE(trace/project.ts:43)
+    #   · `needs_review`      DURABLE(http/server.ts:2148)
+    #   · `message_committed` LIVE(routes/tasks.ts:650)
+    # durable 腿的读边界(routes/runs.ts:99 `formatEvent`)对**每一条**落库事件原样下发 `{type, ...data}`
+    # (唯一归一是 brain_status→status),所以「本仓 append 了什么」= 「wire 上会出现什么」。而本文件的
+    # `AgentEvent` 是闭集 oneOf ⇒ 一个真实的 context_usage 帧对着 spec 校验**当场零臂命中**。
+    # ⚠️ 元教训:`spec-union-arm-gate` 比的是 spec ↔ SDK 两侧的臂集,这四个臂**两侧同缺**,所以那道门
+    #    对它们结构性失明 —— 抓到它们靠的是拿 server 的 `append("…")` / live SSE 铸造点做第三方对账。
+    # ══════════════════════════════════════════════════════════════════════════════════════════════
+    Event_context_usage:
+      type: object
+      description: >
+        core 1.414 first-class arm, whitelisted by `contextUsageEventData` (server trace/project.ts:431).
+        🔴 Two engine-stated conventions, pass them through, never re-derive: (a) `usedTokens > compactAtTokens`
+        IS the predicate the engine itself feeds `shouldCompact`; (b) `windowTokens` is the AUTOCOMPACT window,
+        NOT the model's context size (rendering it as "model context" gives the user a wrong denominator).
+        ⚠️ Reported at EVERY compaction boundary (not only when compaction happens) — many per task; take the
+        last one as current. It is NOT folded into `turn_end.usage` (the boundary check runs after turn_end).
+        All three scalars go through a finite-number guard; non-finite ⇒ key absent (never `null`).
+      additionalProperties: false
+      required: [type]
+      properties:
+        type: { const: context_usage }
+        usedTokens: { type: integer }
+        windowTokens: { type: integer, description: 'autocompact 窗,不是模型上下文大小。' }
+        compactAtTokens: { type: integer }
+        # LIVE 腿(routes/tasks.ts:653)在这条臂上挂 identity;durable 腿不挂。同 turn_end 的处置:
+        # 本地可选声明,不 allOf(不把 identity 承诺进契约面)。
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
+    Event_config_assembled:
+      type: object
+      description: >
+        DURABLE only ([1301]③, server trace/project.ts:43) — the per-turn companion record of `prompt_assembled`:
+        which config catalog version produced this turn's effective fields, and why anything was overridden.
+        Bounded frame: the builder DROPS the whole record over 32 KiB rather than shipping a truncated half-shape.
+        `fields` / `overrideReasons` are engine/registry-shaped passthrough — treat as opaque display data.
+      additionalProperties: false
+      required: [type]
+      properties:
+        type: { const: config_assembled }
+        catalogVersion: {}
+        fields: {}
+        overrideReasons: {}
+        ts: {}
+    Event_needs_review:
+      type: object
+      description: >
+        DURABLE only (design/80 D-B, server http/server.ts:2148) — a RESUMED plan_review leg got re-gated into
+        another review pause. Same payload shape as `suspended`: the gate verbatim, or an explicit `null`.
+        NOTE `needs_review` is BOTH a `RunStatus` terminal and a `CheckpointGate.kind`; this arm is the third
+        use of the name — the stream frame announcing that pause.
+      additionalProperties: false
+      required: [type, gate]
+      properties:
+        type: { const: needs_review }
+        gate:
+          description: 'the review gate, or an explicit null (the key is always present — `?? null` at the mint point).'
+          oneOf:
+            - $ref: '#/components/schemas/CheckpointGate'
+            - type: 'null'
+    Event_message_committed:
+      type: object
+      description: >
+        LIVE only (server routes/tasks.ts:650, whitelisted in the same catch-all as text_delta/turn_end/
+        context_usage) — a session-history entry was committed. `entryId` is the durable entry handle the
+        R8 rewind anchor is keyed on ("rewind to the prompt" targets a `role:"user"` entry).
+      additionalProperties: false
+      required: [type, entryId, role]
+      properties:
+        type: { const: message_committed }
+        entryId: { type: string }
+        role: { type: string, description: 'user | assistant | … (open on read).' }
+        toolCallId: { type: string }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
 
     # ── resources/*.ts schema backfill, batch 2 (2026-07-28) — the 28-item WIRE_PENDING ratchet zeroed.
     #    Each schema below is cross-checked against the server source (file:line cited in its description