@sema-agent/sdk 0.0.101 → 0.0.102

package/openapi.yaml

@@ -13,8 +13,29 @@ openapi: 3.1.0
 # 测试锚定,是目前唯一真正贴合 server 当前实现的文档**。本文件保留作 M0 时代的历史参照(早期
 # verb 清单/大致响应形状仍可读),但**任何具体字段名/是否顶层/是否为 optional 的判断,一律以
 # types.ts 为准,本文件不可信**——已实证撞获至少一处两者互斥的真矛盾(`PendingCheckpoint`,
-# 见下方该 schema 旁注)。回填 spec + 建反射式字段 diff 门是后续候办项,未完成前不要相信这里
-# 的字段级细节。
+# 见下方该 schema 旁注)。
+#
+# ── 状态更新(2026-07-25 回填批完成)────────────────────────────────────────────────────────
+# 上面那句「回填 spec + 建反射式字段 diff 门是后续候办项,未完成前不要相信这里的字段级细节」
+# **已经过时**。现状是:
+#   ✅ 反射式字段级 diff 门已建并**零容忍**:`packages/sdk/test/spec-field-drift-gate.test.ts`
+#      用 TS 编译器 API 解析 `types.ts`(跟 extends / 解 Omit / Pick)× 解析本文件(递归展开
+#      `allOf`/`$ref`)逐字段比对。存量两族基线**都已清零**:字段级 drift 0、整 schema 缺席 0。
+#      ⇒ types.ts 加了字段而这里不加,CI 就红。**字段级细节现在有机器看守了。**
+#   ✅ 本批同时补了 3 条此前整条缺失的路径(`/v1/images`、`/v1/images/select`、
+#      `/v1/capabilities/scenarios/{name}`)、`AgentEvent` 缺的 6 个臂、`/v1/sessions/{id}` 的
+#      5 个 query 参数,并修掉一处真错(`/v1/tasks/{id}/stream` 原先 $ref 到 `AgentEvent`,实际是
+#      `TraceStreamEvent` 词汇表 —— 本文件自己的两处声明互相矛盾)。
+#
+# 🔴 但**权威依然是 types.ts**,理由没变:本文件是手写的第二份声明,门只能保证"字段名集合一致",
+#    保不了语义/可空性/枚举值。已知门**看不见**的三类(判断时请回 types.ts 或 server 源码):
+#      ① 枚举值陈旧 —— 本批就抓到 `AssistantTask.status` 少了 `needs_review`(真的一等 triage 态)。
+#      ② 联合缺臂 —— `AgentEvent` 曾少 6 臂;门只按"命名 schema ↔ 同名 interface"配对,联合对它不可见。
+#      ③ 层差 —— 本文件描述 **wire**(如 gate 的数值字段是显式 `null`),types.ts 描述 **SDK 归一后**
+#         (null 已在资源层折成省略键)。两者都对,不要互相"修正"。见 `AssistantGate` 旁注。
+#    另仍有意留在覆盖外(**不是已覆盖**):`/v1/images` 前缀下的 register/:profile/digests 与整个
+#    bake 控制面(SDK 侧还用 `Record<string, unknown>`、没有具名类型 ⇒ 应先在 types.ts 具名);
+#    `SessionBundle` 目前是本文件里唯一的孤儿 schema(无人 $ref)。
 #
 # Consumed by @sema-agent/sdk (→ both doors: the CC/Codex MCP façade and the
 # portal BFF). Producer = the service.
@@ -124,6 +145,37 @@ paths:
               schema: { $ref: '#/components/schemas/Capabilities' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
+  # 补漏(2026-07-25):本路径此前完全不在本文件里,尽管 SDK 早有 `ScenarioDetail` 类型。形按 server 亲读取证。
+  /v1/capabilities/scenarios/{name}:
+    get:
+      tags: [metrics]
+      operationId: scenarioDetail
+      x-status: live
+      summary: One scenario's detail card.
+      description: >
+        The detail for a single scenario. The LIST of available names rides `capabilities().scenarios` — this
+        route only expands one. Auth = same as `/v1/capabilities` (config surface).
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema: { type: string }
+          description: 'the scenario name (as listed in `capabilities().scenarios`).'
+      responses:
+        '200':
+          description: The scenario detail card.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ScenarioDetail' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          # 🔴 这条曾是全站唯一的**对象形** error(`{error:{code}}`),SDK 的 toApiError 为它特判过一轮。
+          #    server 已统一为「字符串 error + 顶层 errorCode」的邻位形(同 cancel/decide),机器判据保留为 errorCode。
+          description: 'Unknown scenario — `{ error: "scenario not found", errorCode: "scenario_not_found" }`.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/memory:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -533,14 +585,71 @@ paths:
         CURRENT model context (older history already folded into a summary message) — can be LARGE, the portal
         should lazy-expand. Absent entirely on workers without the TiDB pool (capabilities.asyncRuns is the
         practical same-prereq signal).
+
+
+        🔴 The 5 query params below are ADDITIVE: a request with NONE of them returns the byte-identical legacy
+        payload. `?message=` SHORT-CIRCUITS to a different response schema (`SessionMessageEnvelope`) — see below.
+      # 补漏(2026-07-25):此前本操作**一个 query 参数都没声明**,所以整个分页/截断/单条展开面对生成式消费方
+      # 等于不存在。以下 5 个按 server 亲读取证(`http/server.ts:5692-5723`)。
+      parameters:
+        - name: message
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: >
+            The single-message EXPAND leg: returns `SessionMessageEnvelope` (ONE full message body) instead of a
+            `SessionRecord`, and IGNORES the other params. Index is stable within one `floorEntryId` generation —
+            a compaction changes `floorEntryId` and invalidates held indices. Out-of-range → 404 (body carries
+            `total`). This is the companion of a `blobCap`-truncated read: expand = refetch that ONE message.
+        - name: tail
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: 'return the LAST N messages (+ a `window` `{offset,total}`).'
+        - name: before
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: 'return the page ABOVE a prior window offset (pair with `limit`).'
+        - name: limit
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: 'page size for the `tail`/`before` window. Ignored unless one of those is present.'
+        - name: blobCap
+          in: query
+          required: false
+          schema: { type: integer, minimum: 1 }
+          description: >
+            Truncate oversized string bodies to a preview and mark that message `truncated: true`. Only values
+            > 0 take effect. Expand a truncated message via `?message=<index>` (full size).
       responses:
         '200':
-          description: Session record.
+          description: >
+            A `SessionRecord` — or a `SessionMessageEnvelope` when `?message=` was supplied.
+
+            ⚠️ Parameter parsing is LENIENT by construction: a non-numeric or NEGATIVE value is treated as
+            ABSENT, not as an error (so `?tail=-1` quietly returns the full record rather than a 400). A client
+            must not rely on a 400 to catch its own bad paging arithmetic.
           content:
             application/json:
-              schema: { $ref: '#/components/schemas/SessionRecord' }
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/SessionRecord'
+                  - $ref: '#/components/schemas/SessionMessageEnvelope'
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { $ref: '#/components/responses/NotFound' }
+        '404':
+          description: >
+            Non-owner / unknown session (no existence oracle) — or, with `?message=`, an out-of-range index, whose
+            body additionally carries `total`.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                properties:
+                  error: { type: string }
+                  total: { type: integer, description: 'present on the out-of-range `?message=` 404 — the message count available.' }
     delete:
       tags: [sessions]
       operationId: sessionsDelete
@@ -1278,15 +1387,14 @@ paths:
         Owner-gated (NOT D-G); non-owner → 404. SDK → GateNotResumableError on the 409.
       responses:
         '200':
-          description: Resumed; `{status}` (e.g. "completed").
+          # 2026-07-25:此前只声明 `{status}`。真体(`http/server.ts:7688-7696`,与 plan_review 共用
+          # `driveResumeIntoRunLog`)带 taskId/sessionId + 失败态的 errorCode/errorMessage/retriable。
+          description: >
+            Resumed. 🔴 A 200 does NOT mean success — `status` can be `failed`, in which case `errorCode`/
+            `errorMessage` say why and `retriable:true` means the park is STILL PENDING (decide again).
           content:
             application/json:
-              schema:
-                type: object
-                required: [status]
-                additionalProperties: true
-                properties:
-                  status: { type: string }
+              schema: { $ref: '#/components/schemas/AssistantTaskStatus' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -1321,15 +1429,13 @@ paths:
             schema: { $ref: '#/components/schemas/PlanReviewRequest' }
       responses:
         '200':
-          description: Resolved; `{status}` (e.g. "completed").
+          # 2026-07-25:同 resume —— 两条共用 `driveResumeIntoRunLog`,响应体逐字相同。
+          description: >
+            Resolved. 🔴 A 200 does NOT mean success — see `status`/`errorCode`/`retriable` (same body as §4b
+            resume; the two share one handler).
           content:
             application/json:
-              schema:
-                type: object
-                required: [status]
-                additionalProperties: true
-                properties:
-                  status: { type: string }
+              schema: { $ref: '#/components/schemas/AssistantTaskStatus' }
         '400':
           description: >
             Bad/missing `decision`; `edit` without a non-empty `editedPlan`; `editedPlan` present on
@@ -1364,15 +1470,14 @@ paths:
         `202` no-op; an already-`suspended` task → 409; `RESOURCE_SUSPEND` off → 501. Owner-gated; non-owner → 404.
       responses:
         '202':
-          description: Preempting (or 202 no-op on a terminal task); `{status}`.
+          # 2026-07-25:此前只声明 `{status}`。真体是 `{taskId, status, note}`(`http/server.ts` 三个 202 出口)。
+          description: >
+            Preempting — or an honest 202 NO-OP. ⚠️ `status` is NOT always `"preempting"`: the two no-op exits
+            echo the run's own status instead (a non-preempt-eligible leg, or a task that already stopped
+            running), and `note` says which case it was. Read `note`, do not assume the preempt took effect.
           content:
             application/json:
-              schema:
-                type: object
-                required: [status]
-                additionalProperties: true
-                properties:
-                  status: { type: string }
+              schema: { $ref: '#/components/schemas/AssistantTaskStatus' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -1472,10 +1577,20 @@ paths:
         - $ref: '#/components/parameters/LastEventId'
       responses:
         '200':
-          description: SSE stream of AgentEvents (resumable; same durable source as runs.events).
+          # 🔴 修正(2026-07-25):此处原先 $ref 到 `AgentEvent`,是真错 —— 而且本文件自己就矛盾:专门为这条路写的
+          #   `TraceStreamEvent` schema 的描述里明写「A DISTINCT vocabulary from AgentEvent」,却没有任何地方引用它
+          #   (它是本文件里的一个孤儿 schema)。按 server 真码两侧取证后确定 TraceStreamEvent 才是对的:
+          #   `streamTaskTrace` 每帧走 `mapTraceEvent`(`trace/project.ts:530`),发的是 SSE **event 名**
+          #   `block-thinking-delta` / `block-content-delta` / `tool-call` / `tool-result` / `turn` /
+          #   `prompt-assembled` / `done` / `error`,帧里**没有** `type` 字段;SDK 的 `trace.stream()` 注释逐字同款。
+          #   照旧声明生成的客户端会去 switch 一个不存在的 `type` ⇒ 这条流路对它完全不可用。
+          #   (AgentEvent 词汇表在 `GET /v1/runs/:id/events`,那条声明是对的 —— 两条是不同的面,别再混。)
+          description: >
+            Resumable SSE of the workspace LIVE timeline — the BLOCK-grained trace vocabulary
+            (`TraceStreamEvent`), NOT the `AgentEvent` vocabulary of `/v1/runs/:id/events`.
           content:
             text/event-stream:
-              schema: { $ref: '#/components/schemas/AgentEvent' }
+              schema: { $ref: '#/components/schemas/TraceStreamEvent' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
 
@@ -1793,6 +1908,101 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
 
+  # ── sandbox 镜像目录(补漏 2026-07-25)──────────────────────────────────────────────────────────────
+  # ⚠️ 诚实记下本次的**范围**:只补了带 SDK 具名类型的这两条读面(`ImageIndexEntry`/`ImageSelectResult`)。
+  #    server 的 `/v1/images` 前缀下还有 register / :profile / digests/:digest 以及整个 bake 控制面
+  #    (`/v1/images/bakes*`,operator 与 runner 两种主体),SDK 侧目前用 `Record<string, unknown>` 表达、
+  #    没有具名类型 ⇒ 本批不进 spec(补它们等于在这里新发明一份契约,应当先在 types.ts 具名)。**不是已覆盖**。
+  /v1/images:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [sandbox]
+      operationId: imagesList
+      x-status: live
+      summary: Paginated sandbox-image catalog (principal-scoped visibility).
+      description: >
+        The READ-ONLY data source for a "pick a sandbox template" UI. Visibility is scoped to the request
+        principal by the server. Gated on a configured image index — otherwise the route is not mounted.
+        Paginate with `nextCursor` and treat the cursor as OPAQUE (never parse or synthesize one).
+      parameters:
+        - { name: profile, in: query, required: false, schema: { type: string } }
+        - { name: status, in: query, required: false, schema: { type: string, enum: [building, published, deprecated, failed] } }
+        - { name: capability, in: query, required: false, schema: { type: string }, description: 'filter to images having this capability (e.g. `browser`).' }
+        - { name: latest, in: query, required: false, schema: { type: string, enum: ['true'] }, description: 'string `"true"` ⇒ latest-per-profile only.' }
+        - { name: limit, in: query, required: false, schema: { type: integer } }
+        - { name: cursor, in: query, required: false, schema: { type: string }, description: 'echo `nextCursor` from the previous page verbatim.' }
+      responses:
+        '200':
+          description: 'Catalog page — `{ images, nextCursor? }`.'
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [images]
+                additionalProperties: true
+                properties:
+                  images:
+                    type: array
+                    items: { $ref: '#/components/schemas/ImageIndexEntry' }
+                  nextCursor: { type: string, description: 'OPAQUE — pass back as `cursor`. Absent on the last page.' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/images/select:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [sandbox]
+      operationId: imagesSelect
+      x-status: live
+      summary: Resolve a profile to its newest published digest (UI PREVIEW only).
+      description: >
+        Pure resolution, no build. 🔴 The result is a PREVIEW, NOT a binding credential: to actually run on this
+        image, send `sandboxImageProfile` (a PROFILE) on the task request and let the server resolve + re-admit
+        under a trusted principal. A caller that sends/caches/recomputes a digest turns a fail-closed admission
+        into a fail-open one.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile]
+              additionalProperties: true
+              properties:
+                profile: { type: string, description: 'non-empty; missing/blank → 400.' }
+                capabilitiesNeeded:
+                  type: array
+                  items: { type: string }
+                  description: 'capability names that MUST be satisfied by the resolved image, else 409.'
+      responses:
+        '200':
+          description: The resolution preview.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ImageSelectResult' }
+        '400':
+          description: '`profile` missing/blank.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          description: 'No published image for that profile VISIBLE TO THIS PRINCIPAL (invisible and nonexistent are deliberately indistinguishable — no existence oracle).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '409':
+          description: 'The resolved image does not satisfy `capabilitiesNeeded` — body carries `missing[]`.'
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                properties:
+                  error: { type: string }
+                  missing: { type: array, items: { type: string } }
+
   /metrics/summary:
     get:
       tags: [metrics]
@@ -1939,6 +2149,27 @@ components:
         Primary routing axis (one image serves many; unknown → "default"). Selects model/tools/skills/prompt.
       examples: ['default', 'oa', 'code-review', 'team']
 
+    ScenarioDetail:
+      # 新增(2026-07-25 回填批):`GET /v1/capabilities/scenarios/{name}` 此前**整条路径**都不在本文件里
+      # (只有 `Capabilities.scenarios` 那个名字数组)。形按 server 亲读取证(`http/server.ts:1517-1527`)。
+      type: object
+      description: >
+        One scenario's detail card (`GET /v1/capabilities/scenarios/{name}`). The LIST of names rides
+        `Capabilities.scenarios` instead. `source`/`builtin` = builtin vs center-config overlay; `toolset` names
+        the tool bundle while `tools` are the resolved tool names; `promptSummary` is a human-readable prompt
+        DIGEST (never the full prompt); `enabled` = a center scenario can be declared-but-disabled.
+      required: [name, source, builtin, summary, toolset, tools, promptSummary, enabled]
+      additionalProperties: true
+      properties:
+        name: { type: string }
+        source: { type: string, enum: [builtin, center] }
+        builtin: { type: boolean }
+        summary: { type: string }
+        toolset: { type: string }
+        tools: { type: array, items: { type: string } }
+        promptSummary: { type: string, description: 'a human-readable prompt DIGEST — NOT the full prompt.' }
+        enabled: { type: boolean }
+
     RunStatus:
       type: string
       enum: [running, completed, failed, suspended, needs_review]
@@ -1997,6 +2228,58 @@ components:
       # passes them through rather than dropping, so consumers must not assume this list is exhaustive.
       additionalProperties: true
 
+    TaskAgentDefinition:
+      # 新增(2026-07-25 回填批)—— 取代 `TaskRequest.agents.items` 的 OPEN 对象(理由见那里的旁注)。
+      type: object
+      description: >
+        One per-task subagent definition (`TaskRequest.agents[]` item) — mirrors core `AgentDefinition` verbatim.
+        🔴 The server WHITELISTS exactly these keys: anything else is a 400 on the strict lane (so an
+        unrecognised key is a client bug, not a passthrough).
+      required: [name]
+      properties:
+        name: { type: string, description: 'the `subagent_type` the model passes to Task. Non-empty, ≤64 chars, UNIQUE per request.' }
+        whenToUse: { type: string, description: 'when the model should delegate to this agent (shown in the Task tool''s agent list). ≤4096 chars.' }
+        whenToUseLean: { type: string, description: 'compact variant of `whenToUse` for lean tool listings. ≤4096 chars.' }
+        allowTools: { type: array, items: { type: string }, description: 'allowlist of tool names. Omit ⇒ inherit ALL tools.' }
+        denyTools: { type: array, items: { type: string }, description: 'denylist (SUBTRACTIVE — applied after `allowTools`).' }
+        skills:
+          type: array
+          description: 'skills preloaded into the agent.'
+          items:
+            type: object
+            required: [name, description, content]
+            additionalProperties: true
+            properties:
+              name: { type: string }
+              description: { type: string }
+              content: { type: string }
+              manifest: { type: object, additionalProperties: true }
+              files:
+                type: array
+                items:
+                  type: object
+                  required: [path, content]
+                  additionalProperties: true
+                  properties: { path: { type: string }, content: { type: string } }
+        background: { type: boolean, description: 'run the agent in the background (the parent turn continues).' }
+        isolation: { type: string, enum: [worktree], description: '`worktree` = run the agent in an isolated git worktree.' }
+        model:
+          description: >
+            Shell-resolved REAL model name/id — or a Model object with a string `id`. 🔴 NOT an alias: the server
+            does no translation. Omit ⇒ inherit the parent model.
+          oneOf:
+            - type: string
+            - type: object
+              required: [id]
+              additionalProperties: true
+              properties: { id: { type: string } }
+        thinking: { type: string, enum: [off, minimal, low, medium, high, xhigh, max] }
+        systemPrompt: { type: string, description: 'the agent''s system prompt. ≤65536 chars.' }
+        maxTurns: { type: integer, minimum: 1, description: 'max agent turns before the subagent is stopped.' }
+        memory: { type: object, additionalProperties: true, description: 'memory spec (`{ scope?, scopes?, writeScope?, enabled?, scopeContract? }`).' }
+        observer: { type: string, description: 'observer prompt (agent-observes-agent lane). ≤4096 chars.' }
+        observerMessage: { type: string, description: 'message template the observer sends. ≤4096 chars.' }
+
     TaskRequest:
       type: object
       description: >
@@ -2156,14 +2439,15 @@ components:
         cwd: { type: string, description: Working directory for the execution env. }
         selfOrchestration: { type: boolean, description: Permit S8 self-orchestration (run_workflow) inside this task. }
         enableFork: { type: boolean, description: Permit session forking from inside this task. }
+        # 原注是「形状归 SDK 的 TaskAgentDefinition 所有,这里刻意保持 OPEN 而不重复一遍」。2026-07-25 推翻该选择,
+        # 理由是那条推理只对 TS 消费方成立:TS 消费方本来就 import 得到 `TaskAgentDefinition`,从本文件生成客户端的
+        # 消费方(本文件存在的全部意义)拿到的却是一个「任意键的对象」——而这是**请求体**,写错键会被 server 的严格
+        # 通道 400 掉,恰恰是最需要 schema 的地方。⚠️ 代价诚实记下:这确实成了第二处需要跟着 core `AgentDefinition`
+        # 走的声明。因此反射式 drift 门(`test/spec-field-drift-gate.test.ts`)把 `TaskAgentDefinition` 纳入了逐字段
+        # 比对 —— types.ts 加字段而这里不加,门就会红。这就是"重复"这次可以接受的原因:它被机器看住了。
         agents:
           type: array
-          items:
-            type: object
-            description: >
-              One per-task sub-agent definition. Shape owned by `TaskAgentDefinition` in the SDK types; kept OPEN
-              here rather than duplicated (same reasoning as `settings`).
-            additionalProperties: true
+          items: { $ref: '#/components/schemas/TaskAgentDefinition' }
           description: Per-task sub-agent definitions (roster additions scoped to this task only).
         interactiveTools: { type: boolean, description: Mount interactive (prompting) tools. }
         retainBackgroundProcesses: { type: boolean, description: Keep background processes alive past the turn. }
@@ -2371,6 +2655,93 @@ components:
         error: { type: string }
         retainedFrom: { type: integer, description: Lowest event seq still retained; resume events from here. }
 
+    ImageIndexEntry:
+      # 新增(2026-07-25 回填批):sandbox 镜像目录条目。此前 `/v1/images` 整条路径不在本文件里。
+      # 🔴 为什么 21 个字段**全部** required:server 侧 `plugins/tidb-image-index.ts` 的 `mapRow()` 对每一行
+      #    恒全量赋值 —— nullable 的字段也至少给 `null`,**从不省略键**;`GET /v1/images` 的 handler 把 entries
+      #    原样 sendJson、零裁剪。所以「可空」在这里表达为 `type: [..., 'null']`,而不是从 required 里拿掉。
+      type: object
+      description: >
+        One sandbox-image catalog entry (`GET /v1/images` → `images[]`). Visibility is principal-scoped by the
+        server. READ-ONLY data source for a "pick a sandbox template" UI.
+      required:
+        [id, profile, bands, repo, tag, digest, toolchainVersions, capabilities, podContract, sizeBytes, status,
+         visibility, tenantId, manifestSha, recipeGitSha, generatorVersion, buildDate, supersedes, signed,
+         createdAt, updatedAt]
+      additionalProperties: true
+      properties:
+        id: { type: string, description: 'deterministically derived from (repo, digest) — there is no explicit-id upsert path, so an id collision ⟺ a (repo, digest) collision.' }
+        profile: { type: string }
+        bands: { type: array, items: { type: string } }
+        repo: { type: string }
+        tag: { type: string }
+        digest:
+          type: string
+          description: >
+            The immutable digest a running sandbox is built from. 🔴 DISPLAY ONLY — a caller must NEVER send this
+            back to bind an image (bind by `profile`; the server re-resolves + re-admits under a trusted
+            principal, because trusting a caller-supplied digest would fail OPEN).
+        toolchainVersions: { type: object, additionalProperties: { type: string } }
+        capabilities:
+          type: object
+          additionalProperties: true
+          properties:
+            browser: { type: boolean }
+            db: { type: boolean }
+            nestedBuild: { type: boolean, description: 'can it build container images (back-compat boolean).' }
+            nestedBuildMode:
+              type: string
+              enum: [none, docker-cli-only, rootless-buildkit, privileged-dind]
+              description: 'HOW it nests (the posture). Refines `nestedBuild`; absent ⇒ fall back to the boolean.'
+        podContract:
+          type: object
+          additionalProperties: true
+          properties:
+            devShmMB: { type: integer }
+            minMemMB: { type: integer }
+            minCpu: { type: string }
+            readyTimeoutSec: { type: integer }
+            securityContext: { type: object, additionalProperties: true }
+        sizeBytes: { type: ['integer', 'null'] }
+        status: { type: string, enum: [building, published, deprecated, failed] }
+        visibility: { type: string, enum: [public, tenant] }
+        tenantId: { type: ['string', 'null'] }
+        manifestSha: { type: ['string', 'null'] }
+        recipeGitSha: { type: ['string', 'null'] }
+        generatorVersion: { type: ['string', 'null'] }
+        buildDate: { type: ['string', 'null'], description: 'ISO date-time string (the server projects Date/string uniformly to ISO).' }
+        supersedes: { type: ['string', 'null'], description: 'version-lineage anchor (optionally written by the server''s setStatus; semantics not further specified server-side — pass through).' }
+        signed: { type: boolean }
+        createdAt: { type: string, description: ISO date-time. }
+        updatedAt: { type: string, description: ISO date-time. }
+
+    ImageSelectResult:
+      # 新增(2026-07-25 回填批)。
+      type: object
+      description: >
+        `POST /v1/images/select` resolution result — a PREVIEW of "which digest/capabilities does this profile
+        resolve to" for the UI. 🔴 NOT a binding credential: to actually bind, send `sandboxImageProfile` on the
+        task request and let the server resolve under a trusted principal.
+      additionalProperties: true
+      properties:
+        profile: { type: string }
+        digest: { type: string }
+        repo: { type: string }
+        ref:
+          type: string
+          description: >
+            `${repo}@${digest}` — always present on a 200. This is the value a caller threads into the kata
+            adapter's per-sandbox image (the server handler says so itself), i.e. it is load-bearing, not decorative.
+        podContract: { type: object, additionalProperties: true }
+        capabilities:
+          type: object
+          additionalProperties: true
+          properties:
+            browser: { type: boolean }
+            db: { type: boolean }
+            nestedBuild: { type: boolean }
+        manifestSha: { type: string }
+
     QuotaError:
       type: object
       description: 429 per-principal cumulative-quota body (`quotaExceeded`).
@@ -2867,6 +3238,46 @@ components:
         endedAt: { type: integer, description: 'End epoch ms (absent while running).' }
         createdAt: { type: integer, description: 'Record-creation epoch ms (listByScope sort key).' }
 
+    WorkflowActivityBeat:
+      # 新增(2026-07-25 回填批)—— workflow 监视面 "Activity · last N of M tool calls" 的一拍。
+      type: object
+      description: >
+        One tool-call beat on a workflow agent's BOUNDED activity tail (source = core `ToolActivity`, projected
+        verbatim by the service detail handler).
+
+        🔴 `arg` is a SHORT primary-arg SUMMARY (command→name, path→basename, url→origin+path), secret-scrubbed
+        and truncated (~80 code points) by core. It exists for the monitor's `Read(path)` / `Bash(grep …)`
+        display — it is NOT the full args. RENDER it; NEVER re-feed it to a model.
+      additionalProperties: true
+      properties:
+        phase: { type: string, enum: [start, end] }
+        toolCallId: { type: string }
+        toolName: { type: string, description: 'the monitor renders `${toolName}(${arg})`.' }
+        arg: { type: string, description: 'SHORT, secret-scrubbed, ~80-code-point summary (set on `phase:"start"`). UNTRUSTED display text.' }
+        isError: { type: boolean, description: 'set on `phase:"end"` — whether the tool call errored.' }
+
+    WorkflowAgentRow:
+      # 新增(2026-07-25 回填批)—— 取代 `WorkflowRun.agents` 的 `items: {}`(零形状)。
+      type: object
+      description: >
+        One agent-run row in a workflow's detail. The shape is PERMISSIVE — read the known render fields below,
+        tolerate the rest as the projection evolves.
+      additionalProperties: true
+      properties:
+        label: { type: string, description: 'display label.' }
+        status: { type: string, description: 'lifecycle status (the input vocabulary the display derivation reads).' }
+        phase: { type: string, description: 'the phase title this agent ran under (groups it into a phase bucket).' }
+        model: { type: string, description: 'per-agent model DISPLAY label (e.g. "Opus 4.8 (1M context)"), not an id.' }
+        tokens: { type: integer }
+        turns: { type: integer }
+        toolCalls: { type: integer, description: 'total tool calls — the "M" in "last N of M tool calls".' }
+        activity:
+          type: array
+          description: 'the "Activity" tail — the LAST-N tool-call beats (bounded).'
+          items: { $ref: '#/components/schemas/WorkflowActivityBeat' }
+        prompt: { type: string, description: 'what the worker was ASKED (core-redacted + bounded). UNTRUSTED display text.' }
+        output: { type: string, description: 'the worker''s final OUTPUT (core-redacted + bounded). UNTRUSTED display text.' }
+
     WorkflowRun:
       type: object
       description: >
@@ -2881,7 +3292,13 @@ components:
         description: { type: string, description: "The workflow script's declared `meta.description` (one-liner)." }
         status: { $ref: '#/components/schemas/WorkflowRunStatus' }
         phases: { type: array, description: 'Phase records (permissive).', items: {} }
-        agents: { type: array, description: 'Agent-run records (permissive).', items: {} }
+        # `items: {}`(= 任意值,零形状)改为具名 $ref(2026-07-25 回填批):这是 workflow 监视面最吃重的数组,
+        # 空 schema 等于对非 TS 消费方完全没描述过它。`WorkflowAgentRow` 仍是 PERMISSIVE(additionalProperties)——
+        # 只钉住监视面真正 key 的那些字段,其余随投影演进。
+        agents:
+          type: array
+          description: 'Agent-run records (permissive — read the known render fields, tolerate the rest).'
+          items: { $ref: '#/components/schemas/WorkflowAgentRow' }
         stats:
           type: object
           description: 'Token stats — own at stats.tokens, nested at stats.nested.tokens (R-5 own/nested split).'
@@ -3198,27 +3615,79 @@ components:
           type: array
           items: { $ref: '#/components/schemas/InboxRow' }
 
-    AssistantTaskRow:
+    AssistantGate:
+      # 从 `AssistantTaskRow.gate` 的内联形提取为命名 schema(2026-07-25 回填批):内联的 schema 生成不出可复用
+      # 的具名类型,非 TS 消费方只能拿到匿名对象;且反射式 drift 门只按「命名 schema ↔ 同名 exported interface」
+      # 配对,内联形对它完全不可见 ⇒ 这里的字段漂移过去无人看守。
+      type: object
+      description: >
+        ASSISTANT-WIRE-CONTRACT §3 — the active gate inlined on an `AssistantTask` row.
+
+        🔴 LAYER NOTE (this schema and the SDK's `AssistantGate` type describe DIFFERENT layers, deliberately):
+        this file documents the WIRE, where `severity`/`spentMicroUsd`/`deadline` are sent as EXPLICIT `null`
+        when absent (server `http/server.ts` sends `severity: s.severity ?? null` — a present key holding null,
+        NOT an omitted key). The SDK's TS type declares them `?: number` because the SDK FOLDS null → omitted
+        key at its resource boundary (`resources/assistant.ts` `RawAssistantGate` + `normalizeGate()`), so a
+        TS consumer never observes the null. Both are correct for their layer — do NOT "fix" either to match
+        the other. A non-TS client generated from this file MUST tolerate the nulls itself.
+      required: [kind]
+      additionalProperties: true
+      properties:
+        kind:
+          type: string
+          description: >
+            Same open set as `CheckpointSummary.gateKind` — the FLATTENED projection of core's
+            `CheckpointGate`. (Nested-as-`gate` ⇒ the discriminator is named `kind`; flattened onto a row ⇒
+            `gateKind`. Same value domain, different position — a naming CONVENTION, not an inconsistency.)
+          enum: [human, irreversible_ask, resource_limit, needs_review, plan_review, task_done]
+          x-open-enum: true   # a future core kind must render generically, never crash — do not close this union
+        severity:
+          type: ['integer', 'null']
+          enum: [1, 2, 3, 4, 5, null]
+          description: >
+            Risk tier. `null` (or, post-SDK-normalization, absent) = this gate kind carries no RiskDescriptor
+            (resource_limit / needs_review / plan_review) — treat as "unknown", never as 0.
+        spentMicroUsd:
+          type: ['number', 'null']
+          description: >
+            Cumulative spend ALREADY INCURRED on the suspend chain (micro-USD). ⚠️ NOT the same concept as
+            `costMicroUsd` ("what this thing cost") — never treat the two as aliases.
+        deadline:
+          type: ['integer', 'null']
+          description: 'awaiting-human SLA deadline — epoch ms (the checkpoint family''s time convention; run-ledger rows use ISO strings instead).'
+
+    AssistantTask:
+      # 重命名自 `AssistantTaskRow`(2026-07-25):SDK 的 exported interface 叫 `AssistantTask`,而权威已在
+      # types.ts(见本文件顶注),spec 侧沿用另一个名字会让反射式 drift 门永远配不上对 ⇒ 以 TS 名为准对齐。
       type: object
       description: >
         ASSISTANT-WIRE-CONTRACT §3 — a scheduler-overview row = run-store `listRuns(owner)` joined with the core
         scheduler seam. ⚠️ `createdAt`/`updatedAt` are ISO date-time strings (unlike inbox/§1 epoch-ms).
-      required: [taskId, sessionId, status, needsAttention, createdAt, updatedAt]
+      required: [taskId, sessionId, status, needsAttention, gate, createdAt, updatedAt]
       additionalProperties: true
       properties:
         taskId: { type: string }
         sessionId: { type: string }
-        status: { type: string, enum: [running, suspended] }
-        needsAttention: { type: boolean, description: '= suspended on a HITL gate.' }
+        status:
+          type: string
+          # 🔴 `needs_review` 是 2026-07-25 补的:server 的行过滤器逐字是
+          #   `.filter(r => r.status === "running" || r.status === "suspended" || r.status === "needs_review")`
+          #   (`http/server.ts:4677`,已亲读取证)——本枚举此前只有前两个,是真陈旧,照它生成的客户端会把一个
+          #   合法的一等 triage 态判成非法值。字段级 drift 门只比字段名、比不到枚举值,所以它没抓到这条。
+          enum: [running, suspended, needs_review]
+          description: >
+            `running` — live. `suspended` — durably parked on a HITL gate (resolve via §4b resume / §4a decide).
+            `needs_review` — a FIRST-CLASS triage state: a plan_review / dry-run review park (NOT `suspended`);
+            carries `needsAttention:true` + `gate.kind` = `plan_review`/`needs_review` (severity absent) and
+            sorts FIRST. 🔴 Resolve it via §4c `POST /v1/assistant/tasks/:id/plan_review`, NOT §4b resume.
+            ⚠️ Distinct axis from `RunStatus.needs_review` (that one is a dry-run TERMINAL run status; this is a
+            park state on the overview row) — same name, different axis.
+        needsAttention: { type: boolean, description: '= parked on a HITL gate (`suspended` OR `needs_review`); server derives it as `!!gate`.' }
         gate:
-          type: ['object', 'null']
-          description: 'the active gate, or null. severity/spentMicroUsd/deadline may themselves be null on the wire.'
-          additionalProperties: true
-          properties:
-            kind: { type: string, description: 'same open set as gateKind.' }
-            severity: { type: ['integer', 'null'], enum: [1, 2, 3, 4, 5, null] }
-            spentMicroUsd: { type: ['number', 'null'] }
-            deadline: { type: ['integer', 'null'], description: epoch ms. }
+          description: 'the active gate, or null when the row is not parked.'
+          oneOf:
+            - $ref: '#/components/schemas/AssistantGate'
+            - type: 'null'
         createdAt: { type: string, description: ISO date-time. }
         updatedAt: { type: string, description: ISO date-time. }
 
@@ -3232,7 +3701,39 @@ components:
       properties:
         tasks:
           type: array
-          items: { $ref: '#/components/schemas/AssistantTaskRow' }
+          items: { $ref: '#/components/schemas/AssistantTask' }
+
+    AssistantTaskStatus:
+      # 新增(2026-07-25 回填批):§4b resume / §4c plan_review / §4d preempt 三条决策端点此前在本文件里都只声明
+      # 了 `{status}` 一个字段——与 SDK 三批核查前的旧类型同样陈旧。下面的形按 server 源码逐字取证:
+      #   • resume / plan_review 200(共用 `driveResumeIntoRunLog`,`http/server.ts:7688-7696`):
+      #       `{ taskId, sessionId, status, errorCode?, errorMessage?, retriable? }`(后三个条件 spread ⇒ 缺则省键)
+      #   • preempt 202(`http/server.ts:4726/4734/4737` 三个出口):`{ taskId, status, note }`
+      #     ⚠️ `status` 在 202 上**并非恒为 `"preempting"`**:两个 no-op 出口分别回 `run.status` 与
+      #        `now?.status ?? "failed"` —— 所以这里不能把它写成 const。
+      type: object
+      description: >
+        The response of the §4b/§4c/§4d decision endpoints (resume / plan_review / preempt). Union of the two
+        real body shapes — `sessionId` appears only on resume/plan_review, `note` only on preempt; everything
+        else is shared (absent keys are OMITTED, never null).
+      required: [taskId, status]
+      additionalProperties: true
+      properties:
+        taskId: { type: string, description: 'always present (all three response bodies carry it).' }
+        status:
+          type: string
+          description: >
+            OPEN string — do NOT narrow. Observed values include `completed` / `failed` / `suspended` /
+            `needs_review` / `preempting`, plus whatever run status a no-op preempt echoes back.
+        sessionId: { type: string, description: 'resume/plan_review ONLY — the session the decided checkpoint belongs to. Absent from the preempt body.' }
+        errorCode: { type: string, description: 'present on a failed resume/plan_review (e.g. `checkpoint.reopen_failed`).' }
+        errorMessage: { type: string, description: 'human-readable failure detail (server-side secret-redacted).' }
+        retriable:
+          type: boolean
+          description: >
+            `true` = the park is STILL PENDING (the server re-parked it), so re-fetching and deciding again is
+            meaningful. Emitted only when the store CONFIRMED the reopen — never inferred.
+        note: { type: string, description: 'preempt ONLY — human-readable explanation (incl. the honest "preempt is a no-op" cases). Absent from the resume/plan_review body.' }
 
     PlanReviewRequest:
       type: object
@@ -3309,6 +3810,23 @@ components:
         offset: { type: integer, description: Index of the first returned message within the full context. }
         total: { type: integer, description: Total messages available (so a client can page). }
 
+    SessionMessageEnvelope:
+      # 新增(2026-07-25 回填批):`GET /v1/sessions/{id}?message=<index>` 的单条消息展开支路。本文件此前连
+      # `/v1/sessions/{id}` 的 query 参数都一个没声明,所以这条支路对生成式消费方等于不存在。
+      type: object
+      description: >
+        The single-message expand leg — `GET /v1/sessions/{sessionId}?message=<index>` returns THIS instead of a
+        `SessionRecord`. An out-of-range index → 404 (the error body carries `total`).
+      required: [sessionId, index, message]
+      additionalProperties: true
+      properties:
+        sessionId: { type: string }
+        floorEntryId:
+          type: ['string', 'null']
+          description: 'the compaction floor this index is relative to, when one applies.'
+        index: { type: integer, description: 'the requested message index (echoed).' }
+        message: { description: 'OPEN — the message payload as stored; shape belongs to the transcript format, not to this envelope.' }
+
     PromptEpoch:
       type: object
       description: >
@@ -3578,6 +4096,16 @@ components:
         - $ref: '#/components/schemas/Event_task_progress'
         - $ref: '#/components/schemas/Event_workspace_changed'
         - $ref: '#/components/schemas/Event_suspended'
+        # 🔴 以下 6 臂是 2026-07-25 补的:`events.ts` 的 `AgentEvent` 联合有 21 个 `type` 字面量,本文件此前只声明
+        #   15 个 —— 照本文件生成客户端的消费方会把 6 种合法帧当成非法值(事件面是最吃重的 wire 面,这个缺口比
+        #   字段级 drift 更伤)。字段级 drift 门只按「命名 schema ↔ 同名 exported interface」配对,联合缺臂对它
+        #   不可见,故这条只能靠人工核对 —— 补齐时是拿 `events.ts` 的 type 字面量集与本联合做机器 diff 得出的。
+        - $ref: '#/components/schemas/Event_file_link'
+        - $ref: '#/components/schemas/Event_prompt_assembled'
+        - $ref: '#/components/schemas/Event_model_usage'
+        - $ref: '#/components/schemas/Event_task_notification'
+        - $ref: '#/components/schemas/Event_diagnostics'
+        - $ref: '#/components/schemas/Event_steering_injected'
         - $ref: '#/components/schemas/Event_done'
         - $ref: '#/components/schemas/Event_failed'
       discriminator:
@@ -3596,6 +4124,12 @@ components:
           task_progress: '#/components/schemas/Event_task_progress'
           workspace_changed: '#/components/schemas/Event_workspace_changed'
           suspended: '#/components/schemas/Event_suspended'
+          file_link: '#/components/schemas/Event_file_link'
+          prompt_assembled: '#/components/schemas/Event_prompt_assembled'
+          model_usage: '#/components/schemas/Event_model_usage'
+          task_notification: '#/components/schemas/Event_task_notification'
+          diagnostics: '#/components/schemas/Event_diagnostics'
+          steering_injected: '#/components/schemas/Event_steering_injected'
           done: '#/components/schemas/Event_done'
           failed: '#/components/schemas/Event_failed'
 
@@ -3747,6 +4281,60 @@ components:
       properties:
         type: { const: workspace_changed }
         cwd: { type: string }
+    CheckpointGate:
+      # 从 `Event_suspended.gate` 的内联 oneOf 提取为命名 schema(2026-07-25 回填批)。两个理由:
+      #  ① 内联形生成不出可复用具名类型;② 反射式 drift 门只按「命名 schema ↔ 同名 exported interface」配对,
+      #     内联形对它不可见 —— 这块 wire 契约过去没有任何机器看守。
+      # 🔴 为什么同时写顶层 `properties` 和 `oneOf`:门解析有效属性集时只展开 `$ref`/`allOf`,**不认 `oneOf`**
+      #    (`test/spec-field-drift-gate.test.ts` 的 `effectiveSpecProps`)。若只留 oneOf,门会认为本 schema
+      #    「没有属性」从而当作整个 schema 缺席 ⇒ 回填等于没做。两者是合取关系(JSON Schema 语义):顶层
+      #    properties 给出字段全集(=门的比对面),oneOf 继续施加逐 kind 的形状校验,互不削弱。
+      # nullability 现在挂在**引用点**(`gate: oneOf[$ref, null]`),不再是本 schema 的一个 union 臂 ——
+      # 命名类型自身是对象形,更贴 TS 的 `gate?: CheckpointGate | null`。
+      type: object
+      description: >
+        CheckpointGate — OPEN DISCRIMINATED SET (design/80 D-0), mirrors core src/core/checkpoint-store.ts.
+        5 known kinds; consumers MUST branch on `kind` and render an UNKNOWN kind generically (core can mint a
+        kind this contract predates — a core→wire contract test fails CI, not prod). Tool args / question text
+        are NOT here — join the task's trace tool-call block via approvals' toolCallId.
+      required: [kind]
+      properties:
+        kind:
+          type: string
+          description: >
+            `human` — plain HITL approval (budget-auto-approvable). `irreversible_ask` — design/37
+            irreversibility / design/70 egress tighten; NOT budgetable (load-bearing safety gate).
+            `resource_limit` — design/74 cost/token/time slice boundary; resolve `{decision:"continue"}`.
+            `needs_review` — design/76 dry-run/shadow → durable `needs_review` TERMINAL (post-prediction
+            review, disjoint from the approval family). `task_done` — design/38 Path A background sub-task
+            handle (door B never sees it).
+          enum: [human, irreversible_ask, resource_limit, needs_review, task_done]
+          x-open-enum: true   # do not close this union — an unknown future kind is VALID on the wire
+        reason: { type: string, description: 'present on human / irreversible_ask / resource_limit / needs_review (not task_done).' }
+        toolName: { type: string, description: 'present on human / irreversible_ask.' }
+      oneOf:
+        - type: object       # plain human approval (budget-auto-approvable)
+          required: [kind, reason, toolName]
+          properties: { kind: { const: human } }
+        - type: object       # design/37 irreversibility / design/70 egress safety-tighten — NOT budgetable (load-bearing safety gate)
+          required: [kind, reason, toolName]
+          properties: { kind: { const: irreversible_ask } }
+        - type: object       # design/74 resource (cost/token/time) slice boundary — resolve { decision: "continue" }
+          required: [kind, reason]
+          properties: { kind: { const: resource_limit } }
+        - type: object       # design/76 dry-run/shadow → durable needs_review TERMINAL (POST-prediction review, disjoint from approval family)
+          required: [kind, reason]
+          properties: { kind: { const: needs_review } }
+        - type: object       # design/38 Path A background sub-task handle (door B never sees it)
+          required: [kind]
+          properties: { kind: { const: task_done } }
+        - type: object       # OPEN SET — unknown future kind (e.g. design/80 D-B plan_review); render generically, never crash
+          required: [kind]
+          # 🔴 the pinned wire contract: exclude the 5 KNOWN kinds so a known kind matches ONLY its const member above
+          #   (not also this fallback) → keeps `oneOf` unambiguous AND preserves each kind's shape validation.
+          #   This fallback matches ONLY a future kind this contract predates. Add new known kinds to the enum.
+          properties: { kind: { type: string, not: { enum: [human, irreversible_ask, resource_limit, needs_review, task_done] } } }
+
     Event_suspended:
       type: object
       description: HITL — the run paused on an F4 gate or AskUserQuestion. Resolve via approvals.decide, then resume.
@@ -3754,34 +4342,225 @@ components:
       properties:
         type: { const: suspended }
         gate:
-          description: >
-            CheckpointGate — OPEN DISCRIMINATED SET (design/80 D-0), mirrors core src/core/checkpoint-store.ts.
-            5 known kinds below; consumers MUST branch on `kind` and render an UNKNOWN kind generically (core
-            can mint a kind this contract predates — a core→wire contract test fails CI, not prod). Tool
-            args/question text are NOT here — join the task's trace tool-call block via approvals' toolCallId.
+          description: 'the gate the run paused on, or null.'
           oneOf:
-            - type: object       # plain human approval (budget-auto-approvable)
-              required: [kind, reason, toolName]
-              properties: { kind: { const: human }, reason: { type: string }, toolName: { type: string } }
-            - type: object       # design/37 irreversibility / design/70 egress safety-tighten — NOT budgetable (load-bearing safety gate)
-              required: [kind, reason, toolName]
-              properties: { kind: { const: irreversible_ask }, reason: { type: string }, toolName: { type: string } }
-            - type: object       # design/74 resource (cost/token/time) slice boundary — resolve { decision: "continue" }
-              required: [kind, reason]
-              properties: { kind: { const: resource_limit }, reason: { type: string } }
-            - type: object       # design/76 dry-run/shadow → durable needs_review TERMINAL (POST-prediction review, disjoint from approval family)
-              required: [kind, reason]
-              properties: { kind: { const: needs_review }, reason: { type: string } }
-            - type: object       # design/38 Path A background sub-task handle (door B never sees it)
-              required: [kind]
-              properties: { kind: { const: task_done } }
-            - type: object       # OPEN SET — unknown future kind (e.g. design/80 D-B plan_review); render generically, never crash
-              required: [kind]
-              # 🔴 the pinned wire contract: exclude the 5 KNOWN kinds so a known kind matches ONLY its const member above
-              #   (not also this fallback) → keeps `oneOf` unambiguous AND preserves each kind's shape validation.
-              #   This fallback matches ONLY a future kind this contract predates. Add new known kinds to the enum.
-              properties: { kind: { type: string, not: { enum: [human, irreversible_ask, resource_limit, needs_review, task_done] } } }
+            - $ref: '#/components/schemas/CheckpointGate'
             - type: 'null'
+    ModelUsageDelta:
+      # 新增(2026-07-25 回填批)。SDK 的 facade 审计把这个形状命名了一次(此前是在两个使用点各写一遍的匿名内联形:
+      # `AgentEvent` 的 `model_usage` 臂 与 `done.result.stats.modelUsage` 的值类型,同源同形)。
+      type: object
+      description: >
+        Per-model token/cost delta, keyed by model name in a `Record<string, ModelUsageDelta>`. Fields mirror
+        `turn_end.usage`; ALL optional (open contract — tolerates future core fields).
+      additionalProperties: true
+      properties:
+        inputTokens: { type: integer }
+        outputTokens: { type: integer }
+        cacheReadTokens: { type: integer }
+        cacheWriteTokens: { type: integer }
+        costMicroUsd:
+          type: number
+          description: >
+            What THIS model's slice cost (micro-USD). ⚠️ Distinct concept from `spentMicroUsd`
+            ("cumulative already-incurred spend") — never treat the two as aliases.
+
+    PromptManifest:
+      # 新增(2026-07-25 回填批):server ≥1.219 的 prompt-assembly manifest。此前本文件完全没有它(全文 0 次提及),
+      # 尽管它同时是 `AgentEvent.prompt_assembled` 臂和 trace 流 `prompt-assembled` 帧的载荷。
+      type: object
+      description: >
+        The prompt-assembly manifest (core's `prompt.assembled` trace contract verbatim). Carries ONLY
+        ids/digests/counts — NEVER prompt bodies (privacy boundary). 🔴 Hashes are PROCESS-SALTED: they are NOT
+        comparable across worker restarts, so a UI must never diff them cross-process. `constitution`/`blocks`/
+        `totalChars` are the v1 face; `sections`/`tools` are the v2 ADDITIVE face (absent on a v1-only engine).
+        ⚠️ One task can carry MULTIPLE manifests — a cascade/verify run re-prepares under one taskId and every
+        rung's manifest is persisted in emission order.
+      required: [constitution, blocks, totalChars]
+      additionalProperties: true
+      properties:
+        constitution:
+          type: string
+          description: 'who owned the constitution layer — `core` is the steady state; anything else is worth eyes.'
+          enum: [core, replaced, provider-assembled, legacy]
+          x-open-enum: true
+        blocks:
+          type: array
+          items:
+            type: object
+            required: [id, chars, hash]
+            additionalProperties: true
+            properties:
+              id: { type: string }
+              chars: { type: integer }
+              hash: { type: string, description: 'process-salted digest — never compare across restarts.' }
+        sections:
+          type: array
+          description: 'v2 additive face — absent on a v1-only engine.'
+          items:
+            type: object
+            required: [id, slot, carrier, cadence, cacheClass, chars, hash]
+            additionalProperties: true
+            properties:
+              id: { type: string }
+              slot: { type: string }
+              carrier: { type: string }
+              cadence: { type: string }
+              cacheClass: { type: string }
+              chars: { type: integer }
+              hash: { type: string }
+        tools:
+          type: array
+          description: 'v2 additive face — the tool contract summary.'
+          items:
+            type: object
+            required: [wireName, aliases, contractId, implementationRevision, cardId, shapeDigest, wireSchemaDigest]
+            additionalProperties: true
+            properties:
+              wireName: { type: string }
+              aliases: { type: array, items: { type: string } }
+              contractId: { type: string }
+              implementationRevision: { type: string }
+              cardId: { type: string }
+              shapeDigest: { type: string }
+              wireSchemaDigest: { type: string }
+        totalChars: { type: integer }
+
+    Event_file_link:
+      type: object
+      description: >
+        The engine SENT THE USER A FILE via a presigned link (probe `capabilities().sendUserFile` before
+        rendering affordances). 🔴 `url` EXPIRES after `ttlSec` seconds — render a fetch-soon affordance, never
+        persist the URL as durable.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, url, filename, size, ttlSec, status]
+      properties:
+        type: { const: file_link }
+        url: { type: string, description: 'presigned download URL — EXPIRING, do not persist.' }
+        filename: { type: string }
+        size: { type: integer }
+        ttlSec: { type: integer }
+        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.' }
+
+    Event_prompt_assembled:
+      type: object
+      description: >
+        DURABLE only (server ≥1.219) — the prepare's prompt-assembly manifest, FLATTENED onto the frame (the
+        manifest's own keys sit at the top level next to `type`, they are NOT nested under a `manifest` key).
+        Lands AHEAD of the first event of the turn it prepared. ⚠️ MULTIPLE per task on cascade/verify runs.
+      allOf:
+        - $ref: '#/components/schemas/PromptManifest'
+      required: [type]
+      properties:
+        type: { const: prompt_assembled }
+
+    Event_model_usage:
+      type: object
+      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).
+      required: [type, usage]
+      properties:
+        type: { const: model_usage }
+        usage:
+          type: object
+          additionalProperties: { $ref: '#/components/schemas/ModelUsageDelta' }
+
+    Event_task_notification:
+      type: object
+      description: >
+        A BACKGROUND task (bg agent / bash / monitor / workflow / external) settled or emitted a batch while THIS
+        run was live. The engine ALREADY injected the `<task-notification>` into the model in-process — this frame
+        is the UI/display projection only. `partial:true` = a KILLED child's salvaged remnant (render as
+        incomplete). `seq` = stop-cycle/batch counter (dedup key together with task_id + status).
+        🔴 summary/result/lines/diagnostics are UNTRUSTED redacted free text — render, never re-feed to a model.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, task_id, task_type, status, summary]
+      additionalProperties: true
+      properties:
+        type: { const: task_notification }
+        task_id: { type: string }
+        task_type: { type: string }
+        status: { type: string }
+        summary: { type: string, description: 'UNTRUSTED display text.' }
+        sessionId: { type: string }
+        toolUseId: { type: string }
+        seq: { type: integer }
+        source: { type: string }
+        lines: { type: array, items: { type: string } }
+        stoppedBy: { type: string }
+        exitCode: { type: integer }
+        partial: { type: boolean, description: '`true` = a KILLED child''s salvaged remnant — render as incomplete.' }
+        diagnostics: { type: string }
+        recentSteps:
+          type: array
+          items:
+            type: object
+            required: [tool, target, outcome]
+            additionalProperties: true
+            properties: { tool: { type: string }, target: { type: string }, outcome: { type: string } }
+        editedFiles:
+          type: array
+          items:
+            type: object
+            required: [path, edits]
+            additionalProperties: true
+            properties: { path: { type: string }, edits: { type: integer } }
+        resumable: { type: boolean }
+        result: { type: string, description: 'UNTRUSTED display text.' }
+        output_file: { type: string }
+        usage: { description: 'open shape — usage rollup of the background task.' }
+
+    Event_diagnostics:
+      type: object
+      description: >
+        NEW LSP diagnostics drained at a turn boundary (server-side redacted). The model already got the context
+        message in-process; this frame is the RENDER source.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, files]
+      additionalProperties: true
+      properties:
+        type: { const: diagnostics }
+        files:
+          type: array
+          items:
+            type: object
+            required: [uri, diagnostics]
+            additionalProperties: true
+            properties:
+              uri: { type: string }
+              diagnostics:
+                type: array
+                items:
+                  type: object
+                  required: [message]
+                  additionalProperties: true
+                  properties:
+                    message: { type: string }
+                    severity: { type: integer }
+                    range: { description: 'open shape (LSP Range).' }
+                    code: { type: ['string', 'integer'] }
+                    source: { type: string }
+        isNew: { type: boolean }
+
+    Event_steering_injected:
+      type: object
+      description: >
+        A mid-run system-reminder core injected into the model's context (todo / file-change / date-roll /
+        skills-delta / …). The model already got the injected text in-process; this frame is the RENDER source
+        (`source` picks the icon/label, `preview` is the truncated display text — server-side redacted).
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, source, preview]
+      additionalProperties: true
+      properties:
+        type: { const: steering_injected }
+        source:
+          type: string
+          description: 'OPEN string — deliberately NOT the closed core enum, so a future core source value cannot runtime-crash a strict switch.'
+        preview: { type: string, description: 'truncated, redacted display text — UNTRUSTED.' }
+
     Event_done:
       type: object
       description: Carries the full TaskResult (output string at .result, stats at .stats) — service Drift 4.