@sema-agent/sdk 6.17.2 → 7.0.0-rc.1

package/openapi.yaml

@@ -480,10 +480,29 @@ paths:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
       - $ref: '#/components/parameters/TaskIdPath'
+      # 🔴 #193 车8 P1-11(codex 交叉复审 R1 high,验真后采纳):此前**没声明**这个头,而 server 的 steer 段
+      # 真读它并 scoped+sha256 收成 core 的 `inputId`。它是 core 5.14.0 把 pendingSteer 队列化之后唯一能防
+      # 「202 丢在路上 → 无键重试 → 同一条操作员指令被再追加一条」的东西(队列只有 3 个位子,三次重试就满,
+      # 之后合法转向一律 409 `steering.queue_full`)。最刺眼的自证:本 op 的 409 臂里承诺的
+      # `steering.duplicate_input_id` 语义**完全依赖这个头** —— 不声明它,就是声明了一条谁也走不到的臂。
+      # ⚠️ 与 submit-class(`/v1/tasks`、`/v1/runs`)不同,这里的键**不是重试许可证**:steer 是
+      # AT-MOST-ONCE,SDK 不自动铸键也不因为有键就重试;它纯粹是服务端的去重令牌。
+      # ⚠️⚠️ **作用域只到 parked 两腿**(codex R2 复审报出,亲读 server 证实):只有
+      # `setPendingSteer(token, scope, steerInput())` 那两条腿把派生的 `inputId` 交给 core;live 腿走的是
+      # `live.steer(text, { trusted })`,**没传 inputId**,core 的 `TaskStream.steer()` 今天也不收 ——
+      # 所以 200 `applied` 腿**不去重**。这条限定写进下面 409 的描述里,别在别处把它说成整个 verb 的幂等。
+      - $ref: '#/components/parameters/IdempotencyKey'
     post:
       tags: [runs]
       operationId: runsSteer
-      x-status: draft            # design/80 D-A; core landing the slice (pendingSteer freeze/close-tag). Skeleton per the pinned wire contract.
+      x-status: live             # #193 车8 P1-11(2026-08-15):draft 标签过期作废。它当初的理由是「core 正在落
+                                 # pendingSteer freeze/close-tag 这一刀」——那把守卫**早已在 server 侧落地**
+                                 # (`src/http/routes/runs.ts` 的 steer 段:200 applied / 202 queued+parked_for_wake /
+                                 # 409 三码 / 422 steering.invalid_content / Idempotency-Key→core inputId),SDK 自己的
+                                 # `resources/runs.ts` JSDoc 从 [2400] 起就写着「🔴 ONE narrow caveat (NOT "steer is a
+                                 # draft")」。唯一仍是 forward-draft 的是**per-call `mode` 参数**(core 的 steer 今天是
+                                 # harness 级),那条窄注记挂在下面 `mode` 字段自己的 description 上,而不是整个 verb ——
+                                 # 一个字段没接线不构成「整条面未定形」,而 draft 的语义是把它整条排除在契约断言集外。
       summary: Steer a RUNNING durable run — inject mid-flight direction (supervision).
       description: >
         design/80 D-A. The core of *supervision* (vs mere approve/deny): inject direction into a running run.
@@ -538,6 +557,23 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/SteerReceipt' }
+        '400':
+          # 🔴 #193 车8 P1-11(2026-08-15):**整条 400 臂此前缺席** —— draft 把这条 op 排除在契约断言集外,
+          # 于是它攒下了三个从未进 spec 的真码。server 的 steer 段在 run 查找**之前**就跑完这三道校验
+          # (`src/http/routes/runs.ts`),所以 400 与运行态无关,live/suspended 上一模一样。
+          description: >-
+            THREE distinct machine codes share this status (`routes/runs.ts`, all validated BEFORE the run
+            lookup — so a 400 is your request's fault regardless of run state):
+            errorCode "request.invalid_json" — the body did not parse as JSON;
+            errorCode "request.body_shape" — `text` is missing, not a string, or empty (the message is the
+            literal accepted shape: `{ text: string (non-empty), mode?: 'all' | 'one-at-a-time',
+            priority?: 'now' | 'next' | 'later' }`);
+            errorCode "request.field_invalid" — `mode` or `priority` carried an off-enum value. FAIL-LOUD by
+            design: the server never coerces an unknown word to a default (a silently-defaulted `priority`
+            would look accepted and behave differently).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -554,14 +590,31 @@ paths:
             sent is already parked with DIFFERENT steering content (same key + same content is an idempotent
             no-op and 202s). The engine refuses rather than silently picking a side. Reissue with a fresh
             key — this is a new instruction, not a retry.
+            🔴 SCOPE (#193 车8, codex R2 — read this before treating the key as verb-wide idempotency): this
+            code, and idempotency in general, exist ONLY on the PARKED legs (202 `queued` / `parked_for_wake`),
+            because only those thread the derived `inputId` into core via `setPendingSteer`. The 200 `applied`
+            leg calls core's `TaskStream.steer(text, {trusted})`, which takes NO inputId today — so it does
+            NOT dedupe: a lost 200 retried with the SAME key injects the instruction a SECOND time. Worse, the
+            receipt's `messageId` is derived from that key, so both receipts are byte-identical and the
+            duplicate looks like an idempotent hit. Treat a lost 200 as "outcome unknown", not "safe to retry".
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '413':
+          # 🔴 #193 车8 P1-11(2026-08-15)**改判**,依据=亲读 server 两处铸造点。原文写的是
+          # `steer.content_too_large` @ 256 KiB —— 那是**另一条腿**的事实:该码只在 subagent steer
+          # (`routes/runs.ts` 的子代 verb 区,判 `body.content.length > STEER_IN_MAX_REQUEST_CHARS` = 256 KiB)
+          # 与 workflow-agent steer(`routes/workflows.ts`)两处发出。**本条主 run steer 从不发它**:它的
+          # 413 来自 `readJson` 抛的 `HttpError(413, "request body too large")`(**不带 code**),经
+          # `httpErrorCode(413, undefined)`(`src/http/send.ts`)落成 `request.payload_too_large`,阈值是
+          # `MAX_BODY` = 8 MiB。按旧文案写 `errorCode === "steer.content_too_large"` 的消费方在这条腿上永不命中。
           description: >-
-            errorCode "steer.content_too_large" — the steer body exceeded the server's request cap (256 KiB,
-            server 1.279.2). REJECTED, never truncated: server-side truncation would make the engine's
-            "[+N chars]" disclosure under-report. Shorten and resend; retrying the same bytes is pointless.
+            errorCode "request.payload_too_large" — the request body exceeded the worker's global body cap
+            (`MAX_BODY`, 8 MiB), raised by the shared JSON reader before this handler sees a `text` at all.
+            REJECTED, never truncated. Shorten and resend; retrying the same bytes is pointless.
+            ⚠️ NOT `steer.content_too_large` — that code (and its 256 KiB threshold) belongs to the SUBAGENT
+            steer `POST /v1/runs/{taskId}/subagents/{target}/steer` and the workflow-agent steer, which cap
+            the steer TEXT itself. This verb has no separate text cap.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -571,6 +624,21 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '429': { $ref: '#/components/responses/RateLimited' } # (declared 2026-07-31) rateLimited||quotaExceeded||leaseDenied all gate this verb (routes/runs.ts)
+        '501':
+          # 🔴 #193 车8 P1-11(2026-08-15):**臂缺席,而这条 op 自己的 description 早就在说 501**
+          #(「A worker with no checkpoint store answers 501 instead」)—— 散文说有、机器面没有,正是
+          # 生成式消费方结构性看不见的那一格。两个码来自两处不同的谓词,处置也不同(见描述)。
+          description: >-
+            TWO distinct capability codes share this status (`routes/runs.ts`):
+            errorCode "capability.run_store_required" — the worker wires no durable run store
+            (DB_BACKEND=mysql|pg), so the whole async-run family is off. Nothing about THIS request can fix it;
+            read the `capabilities` bit instead of probing.
+            errorCode "capability.checkpoint_store_required" — the run store IS wired and the run is durably
+            PARKED, but there is no checkpoint store to park the steer on. The live-run path (200 `applied`)
+            still works on such a worker — only the parked leg 501s.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/runs/{taskId}/subagents/{target}/steer:
     parameters:
@@ -2619,10 +2687,29 @@ paths:
     get:
       tags: [trace]
       operationId: traceStream
-      x-status: draft            # trace relay (same source/semantics as runs.events); kept for the workspace live view.
+      x-status: live             # #193 车8 P2-15②(2026-08-15):trace relay,2026-06 起成熟在产(cli `-p` 腿消费,
+                                 # live SSE 的 `id:` 游标行早已在发)。draft 标签过期作废——它的语义是「响应形还没定
+                                 # 形、别过度断言」,而这条流的形自 `TraceStreamEvent` 那次修正(2026-07-25)起就已按
+                                 # server 真码钉死(`routes/trace-usage.ts` 的 `streamTaskTrace` + `trace/project.ts`
+                                 # 的 `mapTraceEvent`)。属主裁定翻 live,一并补齐 draft 免检期里漏掉的 416 臂与
+                                 # `from` 续传参数(两者都真在 server 上,只是从没进机器可读面)。
       summary: Trace relay SSE (same source/semantics as runs.events).
       parameters:
         - $ref: '#/components/parameters/LastEventId'
+        # 🔴 #193 车8 P2-15②(2026-08-15):server 的 resume 点是
+        # `req.headers["last-event-id"] ?? searchParams.get("from")`(`routes/trace-usage.ts` 的
+        # `streamTaskTrace`)—— **两个入口同源**,spec 此前只声明了 header 那一个。后果不是文档不全:一个
+        # 不能自定义 SSE 请求头的消费方(浏览器原生 `EventSource` 就是这一类)照 spec 生成客户端时,
+        # 结构上拿不到任何可用的续传入口,只能每次从头重放整条流。
+        - name: from
+          in: query
+          required: false
+          schema: { type: integer }
+          description: >
+            Resume cursor — the durable `task_event.seq` to replay AFTER (the same value an `id:` line
+            carries). Equivalent to `Last-Event-ID`, which WINS when both are sent. For callers that cannot
+            set request headers (native `EventSource`) this is the only resume entry. A non-numeric or
+            negative value replays from the beginning (no error).
       responses:
         '200':
           # 🔴 修正(2026-07-25):此处原先 $ref 到 `AgentEvent`,是真错 —— 而且本文件自己就矛盾:专门为这条路写的
@@ -2641,6 +2728,20 @@ paths:
               schema: { $ref: '#/components/schemas/TraceStreamEvent' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
+        '416':
+          # 🔴 #193 车8 P2-15②(2026-08-15):**整条 416 臂此前缺席**,而这是 resumable 流的**正常**降级路径:
+          # `streamTaskTrace` 在写 SSE 头**之前**判 `retainedFrom > from + 1` ⇒
+          # `sendError(res, 416, "limit.retention_evicted", …, { retainedFrom })`。三处早就知道它
+          #(server 真码 / `TraceStreamEvent` 的 description / SDK 的 `trace.stream()` 实现),唯独机器可读的
+          # responses 里没有。姊妹面 `GET /v1/runs/{taskId}/events` 是正确形对照组,复用它的同一具名信封。
+          description: >-
+            errorCode "limit.retention_evicted" — the resume point (`Last-Event-ID` / `from`) was evicted past
+            retention, so the gap cannot be replayed. Sent BEFORE any SSE header, so this is an ordinary JSON
+            error response, not a stream frame. Read `retainedFrom`, full-sync the gap via
+            `GET /v1/tasks/{taskId}/turns`, then resume the stream from `retainedFrom`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ResumeEvicted' }
         '501': { $ref: '#/components/responses/NotImplemented' } # (declared 2026-07-31) `routes/trace-usage.ts`'s `!deps.runStore` guard fires before the /turns|/stream|/artifacts sub-dispatch — capability.run_store_required
 
   /v1/usage:
@@ -3392,7 +3493,9 @@ paths:
       operationId: imagesRegister
       x-status: live             # operator face; entry shape = the image-index row (open, server-validated).
       summary: 'OPERATOR: register one image-index entry → { id }.'
-      requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+      # 🔴 #193 车8 P1-12(2026-08-15):此前是裸开集 object(= 生成式消费方拿到 `any`),现挂具名
+      # `ImageRegisterRequest`(字段集对 `routes/images.ts` 亲读,含每个键的 server 侧默认值)。
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ImageRegisterRequest' } } } }
       responses:
         '200': { description: '{ id }.', content: { application/json: { schema: { type: object, required: [id], properties: { id: { type: string } }, additionalProperties: false } } } }
         '400': { $ref: '#/components/responses/BadRequest' }
@@ -3446,7 +3549,10 @@ paths:
       description: >
         Whitelisted-args validation (400/501); an identical-argv in-flight bake is idempotently reused (202);
         busy ⇒ 409 {activeBakeId?, eventsUrl?}; submission rate-limit ⇒ 429 + retryAfterSec.
-      requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+      # 🔴 #193 车8 P1-12(2026-08-15):挂具名 `BakeCreateRequest`(字段集对 `images/bake-validate.ts` 的
+      # `validateBake` 亲读)。一条 build-host-RCE-capable 的门用裸开集 object 描述请求体,与它自己的
+      # 「每个字段都过冻结闭集」纪律直接矛盾。
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/BakeCreateRequest' } } } }
       responses:
         '202': { description: '{ bakeId, eventsUrl, status, state }.', content: { application/json: { schema: { $ref: '#/components/schemas/BakeSubmitAck' } } } }
         '400': { $ref: '#/components/responses/BadRequest' }
@@ -3558,7 +3664,9 @@ paths:
       x-status: live
       summary: 'RUNNER: push one build.sh event line + lease heartbeat (x-bake-ingest-secret header from the claim).'
       description: 'line = {event, …}; event=heartbeat renews the lease only. 409 = lease lost/stolen; cancelRequested=true ⇒ the runner should kill the build.'
-      requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+      # 🔴 #193 车8 P1-12(2026-08-15):挂具名 `BakeIngestLine`(字段集对 `routes/images.ts` 的
+      # `ingestBakeLine` 亲读)。刻意保持**开集** —— 非终态帧的其余键是 build.sh 帧的逐字透传。
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/BakeIngestLine' } } } }
       responses:
         '200': { description: 'One of four shapes (heartbeat / non-terminal append / terminal done-success / terminal done-needs-flip) — see BakeIngestAck.', content: { application/json: { schema: { $ref: '#/components/schemas/BakeIngestAck' } } } }
         '403':
@@ -5325,11 +5433,15 @@ components:
     ResumeEvicted:
       type: object
       description: >
-        416 body for an evicted SSE resume point (`GET /v1/runs/:id/events`). Carries the machine code
-        `errorCode: "limit.retention_evicted"`; matching the 416 STATUS alone is equally valid. Read
-        `retainedFrom`, then full-sync via `/v1/tasks/:id/turns` (pinned SSE contract).
+        416 body for an evicted SSE resume point. Shared by BOTH resumable streams — `GET /v1/runs/:id/events`
+        (AgentEvent vocabulary) and `GET /v1/tasks/{taskId}/stream` (the block-grained trace vocabulary): the
+        two handlers mint it through the SAME `sendError(…, 416, "limit.retention_evicted", …, {retainedFrom})`
+        site shape, so one envelope serves both. Carries the machine code `errorCode:
+        "limit.retention_evicted"`; matching the 416 STATUS alone is equally valid. Read `retainedFrom`, then
+        full-sync via `/v1/tasks/:id/turns` (pinned SSE contract).
         (Corrected 2026-07-31 — see the 416 response note on that path: the "no machine code" claim predates
-        the site's move onto the shared `sendError`.)
+        the site's move onto the shared `sendError`. Widened to both paths by #193 车8 P2-15②, 2026-08-15 —
+        the trace stream had the same 416 arm in code all along, just never declared.)
       required: [error, errorCode, retainedFrom]
       properties:
         error: { type: string }
@@ -5432,6 +5544,52 @@ components:
         capabilities: { $ref: '#/components/schemas/ImageCapabilities' }
         manifestSha: { type: ['string', 'null'], description: 'the source entry''s manifestSha — nullable (ImageIndexEntry.manifestSha is string|null; was wrongly non-nullable here).' }
 
+    ImageRegisterRequest:
+      # 🔴 新(#193 车8 P1-12,2026-08-15)—— `POST /v1/images/register` 的请求体。此前这条 op 的 requestBody
+      # 是裸 `{type: object, additionalProperties: true}`(SDK 侧对应 `Record<string, unknown>`):operator
+      # 面上一个**打错的键名**既不会被 server 拒(白名单是「读已知键」,不是「拒未知键」),也不会被类型
+      # 或校验器拦下 —— 它安静地落成该字段的默认值。字段集逐条对 `src/http/routes/images.ts` 的 register
+      # 分支亲读:三个必填由 handler 显式 400(`request.field_invalid`),其余每一个都有 handler 里写死的默认值。
+      #
+      # ⚠️ `additionalProperties: false` 在这里是**客户端护栏**,不是 server 行为的镜像:server 并不拒收
+      # 未知键,它只是**读不到就用默认值**。封闭声明的价值恰在于把那个静默 no-op 变成一个当场可见的错误。
+      # ⚠️ `id` / `createdAt` / `updatedAt` 刻意不在场:handler 一个都不读(id 由 `idFor(repo,digest)` 确定性
+      # 派生,两个时间戳由 store 写)。送它们是纯粹的误解,所以封闭形要让它们编译不过。
+      type: object
+      description: >
+        `POST /v1/images/register` body — the operator-only image-index upsert (P1 seeding; the P3
+        atomic-publish pipeline drives it for real). STATUS-MONOTONIC: `registerBuilding` never downgrades an
+        already-`published` row, so this door cannot de-publish a live image (take-down is the explicit
+        deprecate path). Everything except profile/repo/digest is optional with a server-side default.
+      required: [profile, repo, digest]
+      additionalProperties: false
+      properties:
+        profile: { type: string, description: 'REQUIRED — missing/non-string ⇒ 400 request.field_invalid.' }
+        repo: { type: string, description: 'REQUIRED — same 400.' }
+        digest: { type: string, description: 'REQUIRED — same 400. The immutable "sha256:<64hex>" this entry is keyed on.' }
+        # ⚠️ 下面每一条 enum 都是**契约**,不是 server 的运行期校验:除 profile/repo/digest 三个必填外,
+        #    handler 对取值**不做集合校验** —— 一个打错的 `status: "publish"` 会原样落库,而
+        #    `latestPublished` 只认 `"published"` ⇒ 这张镜像从此对选择面隐形,且没有任何错误。
+        #    这正是把这条体从裸开集 object 收成具名封闭形的理由。
+        bands: { type: array, items: { type: string }, description: 'Absent / not-an-array ⇒ `[]`.' }
+        tag: { type: string, description: 'Absent / non-string ⇒ `""`.' }
+        toolchainVersions: { type: object, additionalProperties: { type: string }, description: 'Absent ⇒ `{}`.' }
+        capabilities: { $ref: '#/components/schemas/ImageCapabilities' }
+        podContract: { $ref: '#/components/schemas/ImagePodContract' }
+        sizeBytes: { type: ['integer', 'null'], description: 'Anything that is not a number ⇒ `null` (no coercion).' }
+        status: { type: string, enum: [building, published, deprecated, failed], description: 'Absent / non-string ⇒ `"building"`.' }
+        visibility:
+          type: string
+          enum: [public, tenant]
+          description: 'STRICT equality to `"tenant"` selects tenant; EVERY other value (including a typo) ⇒ `"public"`.'
+        tenantId: { type: ['string', 'null'], description: 'Non-string ⇒ `null`.' }
+        manifestSha: { type: ['string', 'null'], description: 'Non-string ⇒ `null`.' }
+        recipeGitSha: { type: ['string', 'null'], description: 'Non-string ⇒ `null`.' }
+        generatorVersion: { type: ['string', 'null'], description: 'Non-string ⇒ `null`.' }
+        buildDate: { type: ['string', 'null'], description: 'ISO date-time string; non-string ⇒ `null`.' }
+        supersedes: { type: ['string', 'null'], description: 'Version-lineage anchor; non-string ⇒ `null`.' }
+        signed: { type: boolean, description: 'STRICT `=== true`; anything else (including the string "true") ⇒ `false`.' }
+
     QuotaError:
       type: object
       description: >
@@ -6211,6 +6369,7 @@ components:
           type: array
           items: { type: string }
           description: 'E7 (SHIPPED) — the /effort picker default set (minimal/low/medium/high); present ONLY for a reasoning model.'
+        atMentionable: { type: boolean, description: '#233/A-002.8 (SHIPPED) — @model mention allowlist verdict; present ONLY when the deployment configured an at-mention allowlist. Absent = no allowlist verdict, NOT "not mentionable" — do not narrow absence to false.' }
 
     ElicitResponse:
       type: object
@@ -10008,6 +10167,153 @@ components:
       type: [string, 'null']
       enum: [band-conflict, duplicate, disk, timeout, cancelled, null]
 
+    BakeCreateRequest:
+      # 🔴 新(#193 车8 P1-12,2026-08-15)—— `POST /v1/images/bakes` 的请求体。此前是裸
+      # `{type: object, additionalProperties: true}`。这条门是 §P2.4 的**反 RCE 核心**:bands/profile/
+      # baseRef/bump 组合出一个 Dockerfile + 一个 FROM + 一次 docker build = build host 上的任意代码,所以
+      # 每个字段在**任何 argv 被拼出来之前**就按冻结闭集校验(`src/images/bake-validate.ts` 的 `validateBake`)。
+      # 一个连字段名都不具名的请求体和这条纪律是矛盾的:调用方连「哪些键会被看」都无从知道。
+      # 字段集逐条对 `validateBake` 的 `BakeSubmit` 亲读,外加 `routes/images.ts` 自己读的 `idempotencyKey`。
+      #
+      # ⚠️ profile 与 bands 是 **XOR**(恰好给一个):两个都给 ⇒ 400「provide profile OR bands, not both」,
+      # 一个都不给 ⇒ 400「one of profile | bands is required」。JSON Schema 表达不出「恰好一个」而不牺牲
+      # 可读性,所以两者都标 optional 并在这里说清 —— 判据的属主是 server 的校验器,不是本文件。
+      type: object
+      description: >
+        `POST /v1/images/bakes` body — the operator-only bake submit. Give EXACTLY ONE of `profile` | `bands`.
+        Every value is checked against a FROZEN closed set server-side before any argv exists; an off-list
+        value is a 400 (or a 501 for the reserved `custom` band = the P4 tenant affordance), NEVER coerced.
+        The output repo/tag and the `FROM` base are server-fixed — a caller cannot set them.
+        ⚠️ `additionalProperties: false` here is a CLIENT-SIDE guardrail, not a mirror of server behaviour:
+        `validateBake` reads NAMED fields, so an unknown key is silently ignored rather than rejected — a
+        typo'd knob is a wire no-op. Declaring the body closed is what turns that no-op into a visible error.
+      additionalProperties: false
+      properties:
+        profile:
+          type: string
+          description: >
+            One of the FROZEN profile catalog (`code-python` … `code-full-db`, mirrored from the recipe
+            `gen-dockerfile.sh`). Unknown profile ⇒ 400. XOR with `bands`.
+        bands:
+          type: array
+          items: { type: string }
+          description: >
+            Non-empty, duplicate-free list from the FROZEN band set (one dir per band under the recipe's
+            `bands/`). XOR with `profile`; a `bands` bake records profile="custom". An off-list id ⇒ 400
+            (with `conflictBands` for the composer UI); the reserved id `custom` ⇒ 501 "custom/tenant bake is P4".
+        baseRef:
+          type: string
+          description: >
+            An immutable `sha256:<64hex>` — and it must additionally be a KNOWN PUBLISHED `sandbox-base`
+            digest the index has seen (400 `request.unknown_reference` otherwise). Absent ⇒ the server picks
+            the base itself (`SANDBOX_BASE_REF` pin, else the index's latest published sandbox-base), which is
+            why a caller can never inject an arbitrary FROM.
+        bump:
+          type: object
+          additionalProperties: { type: string }
+          description: >
+            `{ tool: version }` — tool ∈ the FROZEN bump-tool set, version ∈ `^[A-Za-z0-9._-]{1,40}$`.
+            Off-list tool or off-range version ⇒ 400.
+        push: { type: boolean, description: 'STRICT `=== true`; anything else ⇒ false (node-local build, no registry push).' }
+        dryRun: { type: boolean, description: 'STRICT `=== true`. Resolve-only: bypasses the single-flight busy guard and never takes the lease.' }
+        logs: { type: boolean, description: 'STRICT `=== true`. Opt-in raw build-log tail rows on the event stream.' }
+        pkgSource:
+          type: string
+          enum: [cn, global]
+          description: 'Bake-time package-source profile (RFC B4). Closed set, never coerced; absent ⇒ build.sh default (cn).'
+        idempotencyKey:
+          type: string
+          description: >
+            Durable submit-idempotency, read ONLY when the `Idempotency-Key` HEADER is absent (the header
+            wins). Scoped to the submitting principal server-side, so a replay dedupes for the SAME caller only.
+
+    BakeIngestLine:
+      # 🔴 新(#193 车8 P1-12,2026-08-15)—— `POST /v1/images/bakes/{bakeId}/ingest` 的请求体(一行 build.sh
+      # 事件)。此前是裸 `{type: object, additionalProperties: true}`;SDK 侧同样是 `Record<string, unknown>`,
+      # 于是 runner 侧写错一个键名(`manifestSha` 打成 `manifest_sha`)在两侧都是静默的。
+      # 字段集对 `routes/images.ts` 的 `ingestBakeLine` + ingest handler 亲读:handler 只在 `event` 上分派,
+      # 终态 `done` 那一支另读 8 个键,非终态支把**剩余全部键**原样(经 redactDeep)存进事件 data。
+      #
+      # ⚠️ 这条**刻意保持开集**(`additionalProperties: true`,与上面两条请求体相反):非终态帧的 `...data`
+      # 是 build.sh 帧字段的逐字透传,封闭它等于在这里发明一份 build.sh 没有承诺过的帧契约。
+      type: object
+      description: >
+        One runner-forwarded build.sh event line. The handler dispatches on `event` alone; a
+        `heartbeat` renews the lease and appends NO event, every other value appends one durable event whose
+        data is the line MINUS `event`/`lineOrd`/`line_ord` (redacted). OPEN by design — build.sh frame fields
+        ride through verbatim.
+      required: [event]
+      additionalProperties: true
+      properties:
+        event:
+          type: string
+          description: >
+            build.sh's frame name — `resolved | state | step | image | manifest | log | done`, plus the
+            runner-synthesized `heartbeat`. Open set: an unknown name is stored under that name as the SSE
+            kind. A non-string ⇒ treated as `""` (still a non-terminal append), never an error.
+        lineOrd: { type: integer, description: 'Per-line ordinal — the at-least-once dedupe key (uq_line). `line_ord` is accepted as a snake_case alias.' }
+        line_ord: { type: integer, description: 'snake_case alias of `lineOrd` (the handler reads either).' }
+        state:
+          # 🔴 codex R2 复审后统一口径:**开集**,与 `BakeRecordView.state` 的闭集刻意不对称。请求侧镜像
+          #    **产者**的 wire —— server 自己的 `bake-runner/protocol.ts` 把它声明为 `state: string`,且
+          #    `setState` 落库只做 `as BakeState` 强转、不做集合校验;响应侧才镜像闭集域类型。
+          type: string
+          description: >-
+            `event:"state"` only — denormalizes the UI progress bar. NEVER the coarse terminality (§P2.3).
+            Today's values: PENDING | BUILDING | PUSHING | VERIFYING | REGISTERING | COMPLETE | FAILED |
+            CANCELLED. OPEN on purpose: build.sh owns this vocabulary and the server stores it unvalidated,
+            so a future ninth state must not make a legal frame fail validation.
+        level: { type: string, description: '`event:"log"` only — the literal `"raw"` marks an opt-in build-log tail row (evicted first).' }
+        status:
+          # 🔴 自审修(#193 车8,提交后本车自查):这个键**跨帧种复用**,所以它绝不能是闭集 enum。
+          #    `done` 帧上是 COMPLETE|FAILED|CANCELLED(handler 唯一读它的地方);而 **`step` 帧上同名键**
+          #    带的是 build.sh 的步骤状态(runner 的 `dockerBuildTickFrame` 就恒发 `status:"running"`,
+          #    server 自铸的 register step 发 running|ok|fail|skipped)。写死三值 enum ⇒ 每一条合法的
+          #    step 帧都被严格校验器判违约 —— 与本文件里 `Event_tool_end.errorCode` 那条「开集写 enum 比
+          #    漏声明更糟」的裁定同族,方向一致。
+          type: string
+          description: >
+            OVERLOADED across frame kinds — do NOT treat as a closed set. On `event:"done"` (the only place the
+            handler reads it) it is the build outcome `COMPLETE` | `FAILED` | `CANCELLED`, and a non-string is
+            treated as FAILED. On `event:"step"` frames the SAME key carries build.sh's step status
+            (`running` / `ok` / `fail`), which the handler does not read — it rides through into the event data.
+        exitCode:
+          type: [integer, 'null']
+          description: >-
+            `event:"done"` only. Absent ⇒ 0 on COMPLETE, else null. 🔴 EXPLICITLY nullable: the runner's
+            cancel arm (`bake-runner/protocol.ts`) sends `{status:"CANCELLED", exitCode: null}` verbatim.
+        error:
+          type: [string, 'null']
+          description: >-
+            `event:"done"` only — free text; secret-redacted server-side before storage. 🔴 EXPLICITLY
+            nullable: the runner's push-recovery leg (`bake-runner/runner.ts`, exitCode===13) sends
+            `{status:"COMPLETE", exitCode: 0, error: null}` verbatim.
+        tag: { type: string, description: '`event:"done"` only; absent ⇒ the bake row''s existing tag.' }
+        digest: { type: string, description: '`event:"done"` only — the built image digest (a no-push build sends build.sh''s node-local LOCAL_ID).' }
+        manifestBody: { type: object, additionalProperties: true, description: '`event:"done"` only — the build manifest BODY the runner read off the build host (`manifest`/`done` carry only a host FS path). Required for auto-register.' }
+        manifest:
+          # 🔴 codex R2 复审报出、验真属实:build.sh 的 done 行带的是 manifest **路径字符串**
+          #    (`bake-runner/protocol.ts` 的 `manifestPathFromLine` 首条分支就是 typeof === "string"),
+          #    runner 逐字转发。声明成纯 object ⇒ 严格校验器拒收每一条真实 terminal ingest。
+          oneOf:
+            - { type: string }
+            - { type: object, additionalProperties: true }
+          description: >-
+            EITHER build.sh's manifest PATH (a build-host filesystem string, what the real `done` line
+            carries) OR the manifest body object. When it is an object it is the fallback source for the
+            manifest body and its `sha256` is the fallback for `manifestSha`; when it is a string those two
+            fallbacks simply do not fire (the server gates on `typeof manifestBody === "object"`).
+        manifestSha: { type: string, description: '`event:"done"` only; falls back to `manifest.sha256`, then the bake row''s stored value.' }
+        errorCode:
+          type: string
+          enum: [band-conflict, duplicate, disk, timeout, cancelled]
+          description: >
+            `event:"done"` only — a runner-supplied structured terminal code, PREFERRED over the exit-code
+            recompute (the runner knows codes the exit code cannot reconstruct, e.g. the disk guard). Validated
+            by set membership: an off-list value is DROPPED (never trusted as free text), not an error.
+        conflictBands: { type: array, items: { type: string }, description: '`event:"done"` only — honored ONLY when the FINAL code is `band-conflict`; the composer UI red-highlights these chips.' }
+        sizeBytes: { type: integer, description: '`event:"done"` only — rides the terminal done event; non-number ⇒ null.' }
+
     BakeClaim:
       type: object
       description: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "6.17.2",
+  "version": "7.0.0-rc.1",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",