@sema-agent/sdk 0.1.8 → 1.0.0

package/openapi.yaml

@@ -9,7 +9,7 @@ openapi: 3.1.0
 # 回填这里——本文件开头曾自称"the SINGLE SOURCE OF TRUTH"、"drift fails in CI"两句均已不成立
 # (spec.test.ts 只覆盖 ~15 个类型的局部字段,`PendingCheckpoint`/`TaskStats`/`Capabilities`
 # 等核心类型的大面积字段级 drift 对 CI 完全不可见)。**现行权威 = `packages/sdk/src/types.ts`
-# (+ events.ts/errors.ts),逐类型带 `server.ts:行号` 实拆坐标,三批核查每一处改动都配红先行
+# (+ events.ts/errors.ts),逐类型带 server 实拆坐标,三批核查每一处改动都配红先行
 # 测试锚定,是目前唯一真正贴合 server 当前实现的文档**。本文件保留作 M0 时代的历史参照(早期
 # verb 清单/大致响应形状仍可读),但**任何具体字段名/是否顶层/是否为 optional 的判断,一律以
 # types.ts 为准,本文件不可信**——已实证撞获至少一处两者互斥的真矛盾(`PendingCheckpoint`,
@@ -37,6 +37,14 @@ openapi: 3.1.0
 #    bake 控制面(SDK 侧还用 `Record<string, unknown>`、没有具名类型 ⇒ 应先在 types.ts 具名);
 #    `SessionBundle` 目前是本文件里唯一的孤儿 schema(无人 $ref)。
 #
+# ── 📍 取证坐标的约定:**文件级,不是行级**(2026-07-29 F-f 批)────────────────────────────
+# 本文件与 `types.ts` 里的 server 取证坐标一律写成 **`src/http/routes/<域文件>.ts`** 这样的文件级
+# 指路,不再写 `server.ts:<行号>`。理由是实测的:server 已把 `src/http/server.ts` 拆成
+# `src/http/routes/*.ts`(主体只剩约 2800 行),此前散在两侧的 ~140 处行号坐标**绝大多数已经指到
+# 文件结尾之外** —— 而且就算今天逐个改对,下一次重排会再烂一遍。文件级坐标对重排免疫。
+# **要行级取证**:去 server 仓按符号名/路由字面量 grep,或查该文件的 git 历史 —— 那是唯一不会腐
+# 的行级真源。别把行号写回来。
+#
 # Consumed by @sema-agent/sdk (→ both doors: the CC/Codex MCP façade and the
 # portal BFF). Producer = the service.
 #
@@ -176,42 +184,6 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
 
-  /v1/memory:
-    parameters:
-      - $ref: '#/components/parameters/PrincipalHeader'
-    get:
-      tags: [sessions]
-      operationId: memoryGet
-      x-status: live             # service 170c384. Owner-scoped by construction.
-      summary: Read your own <user_memory> (transparency surface).
-      description: >
-        Scope derives from the request principal (same rule as task execution) — a caller CANNOT address
-        anyone else's memory. No principal header → 401. Discover via capabilities().memory.
-      responses:
-        '200':
-          description: The memory record (content null = empty).
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/MemoryRecord' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-    delete:
-      tags: [sessions]
-      operationId: memoryClear
-      x-status: live
-      summary: Clear your WHOLE memory scope (per-entry deletion is a future additive).
-      responses:
-        '200':
-          description: Cleared.
-          content:
-            application/json:
-              schema:
-                type: object
-                required: [ok, scope]
-                properties:
-                  ok: { type: boolean }
-                  scope: { type: string }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-
   /v1/tasks:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -900,7 +872,7 @@ paths:
         🔴 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`)。
+      # 等于不存在。以下 5 个按 server 亲读取证(`src/http/routes/sessions.ts`)。
       parameters:
         - name: message
           in: query
@@ -1400,7 +1372,7 @@ paths:
         deliberately serve as octet-stream — agent output is untrusted; `x-content-type-options: nosniff`
         always set) + the `x-sema-content-binary` discriminator header (first-8KiB NUL sniff, [1894]③).
         Capped at `capabilities.workspace.maxFileBytes` (default 8MiB, WORKSPACE_FILE_MAX_BYTES) — over-cap ⇒
-        413 STRUCTURED envelope `{code: "workspace_file_too_large", sizeBytes, limit}` ([1894]①; the archive
+        413 STRUCTURED envelope `{errorCode: "workspace_file_too_large", sizeBytes, limit}` ([1894]①; the archive
         endpoint is the escape hatch). When the SQL size index knows the size, the 413 fires BEFORE fetching
         the bytes.
       parameters:
@@ -1419,15 +1391,15 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '413':
-          description: 'Structured over-cap envelope: {error, code: "workspace_file_too_large", sizeBytes, limit}.'
+          description: 'Structured over-cap envelope: {error, errorCode: "workspace_file_too_large", sizeBytes, limit}.'
           content:
             application/json:
               schema:
                 type: object
-                required: [error, code, sizeBytes, limit]
+                required: [error, errorCode, sizeBytes, limit]
                 properties:
                   error: { type: string }
-                  code: { type: string, enum: [workspace_file_too_large] }
+                  errorCode: { type: string, enum: [workspace_file_too_large] }
                   sizeBytes: { type: integer }
                   limit: { type: integer }
         '501': { $ref: '#/components/responses/NotImplemented' }
@@ -1565,90 +1537,6 @@ paths:
               schema: { $ref: '#/components/schemas/McpStatusPanel' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
-  /v1/sessions/{sessionId}/memory:
-    parameters:
-      - $ref: '#/components/parameters/PrincipalHeader'
-      - in: path
-        name: sessionId
-        required: true
-        schema: { type: string }
-    post:
-      tags: [sessions]
-      operationId: memoryAppend
-      x-status: live             # MF-30, service @sema-agent/server 1.3.0 (server.ts:2880).
-      summary: Append a memory note (MF-30 — the /memory write verb).
-      description: >
-        🔴 Memory is PER-PRINCIPAL, not per-session — {sessionId} is only the shell's addressing context (the
-        /memory command runs inside some session); a note appended for a principal is visible from ALL that
-        principal's sessions. Note stored VERBATIM (≤8 KiB, user-authored = intentional, NOT redacted).
-        Empty/oversized → 400. Always available when capabilities().memoryWrite.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [content]
-              properties: { content: { type: string } }
-      responses:
-        '200':
-          description: Append ack — unified { ok, id, scope } (service; handler always returns ok).
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/MemoryWriteAck' }
-        '400': { description: "Empty / oversized / missing content." }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-
-  /v1/sessions/{sessionId}/memory/{noteId}:
-    parameters:
-      - $ref: '#/components/parameters/PrincipalHeader'
-      - in: path
-        name: sessionId
-        required: true
-        schema: { type: string }
-      - in: path
-        name: noteId
-        required: true
-        schema: { type: string }
-    patch:
-      tags: [sessions]
-      operationId: memoryEdit
-      x-status: live             # MF-30 (server.ts:2881).
-      summary: Edit one memory note by id (id unchanged).
-      description: >
-        🔴 501 when the backend lacks id-addressable update (honest degrade, never a fake 200). Per-PRINCIPAL.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [content]
-              properties: { content: { type: string } }
-      responses:
-        '200':
-          description: Edited note ack.
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/MemoryWriteAck' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: "Backend lacks id-addressable update." }
-    delete:
-      tags: [sessions]
-      operationId: memoryForget
-      x-status: live             # MF-30 (server.ts:2882).
-      summary: Forget one memory note by id.
-      description: >
-        🔴 501 when the backend lacks id-addressable delete (honest degrade). Per-PRINCIPAL.
-      responses:
-        '200':
-          description: Forgotten note ack.
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/MemoryWriteAck' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: "Backend lacks id-addressable delete." }
-
   # ── 2c session-sync (P1d) — the cloud as a SYNC PEER ──────────────────────────────────────────────────────────
   # The local shell's local backend ⇄ this cloud service. PULL a session's whole state out, or PUSH the local
   # peer's in. Gate the whole surface off `capabilities.sessionSync` (= durable backend + entry export + a
@@ -1997,9 +1885,8 @@ paths:
       description: >
         Resolves a `suspended` run: an F4 approve/deny, or an answer to an AskUserQuestion. The resumed run
         continues its durable stream (`/v1/runs/:id/events`). design/80 D-1: the decision SHOULD carry the
-        action binding (checkpointToken/boundCallId/boundInputHash read off the PendingCheckpoint) — the server
-        resolves THAT exact checkpoint, fail-closed on mismatch. (Path param stays `sessionId` until service
-        finalizes a checkpointToken-keyed route; the binding travels in the body regardless.)
+        action binding (boundCallId + boundInputHash, read off the PendingCheckpoint) — the server resolves THAT
+        exact checkpoint, fail-closed on mismatch. (Path param stays `sessionId`; the binding travels in the body.)
       requestBody:
         required: true
         content:
@@ -2179,7 +2066,7 @@ paths:
         Owner-gated (NOT D-G); non-owner → 404. SDK → GateNotResumableError on the 409.
       responses:
         '200':
-          # 2026-07-25:此前只声明 `{status}`。真体(`http/server.ts:7688-7696`,与 plan_review 共用
+          # 2026-07-25:此前只声明 `{status}`。真体(`src/http/routes/approvals-assistant.ts`,与 plan_review 共用
           # `driveResumeIntoRunLog`)带 taskId/sessionId + 失败态的 errorCode/errorMessage/retriable。
           description: >
             Resumed. 🔴 A 200 does NOT mean success — `status` can be `failed`, in which case `errorCode`/
@@ -2491,7 +2378,7 @@ paths:
     get:
       tags: [models]
       operationId: modelsList
-      x-status: live             # service GET /v1/models (server.ts:859-882). SDK models.list().
+      x-status: live             # service GET /v1/models (src/http/routes/capabilities.ts). SDK models.list().
       summary: Non-secret model catalog (the `@model` picker / autocomplete data source).
       description: >
         READ-ONLY catalog of `@mention`-pickable models. The user selects a model PER-TASK by typing `@<name>` in
@@ -2787,7 +2674,7 @@ paths:
     get:
       tags: [fleet]
       operationId: fleetStream
-      x-status: live             # service 1bf7a5c — streamFleet (http/server.ts:4874) + fleet/fleet-bus.ts. Owner-gated; in-process bus; NOT resumable.
+      x-status: live             # service 1bf7a5c — streamFleet (src/http/routes/fleet.ts) + fleet/fleet-bus.ts. Owner-gated; in-process bus; NOT resumable.
       summary: Live multi-row fleet view SSE (NON-resumable).
       description: >
         MF-Fleet (shell-host data contract). The LIVE fleet as an SSE PUSH stream: a SNAPSHOT on connect, then a
@@ -3474,9 +3361,12 @@ components:
           schema: { $ref: '#/components/schemas/ErrorResponse' }
     RateLimited:
       description: >
-        429 — per-principal CUMULATIVE quota exceeded (`quotaExceeded`). `Retry-After` (seconds) honored by the
-        SDK on retry. This is the ONLY budget/limit signal at the HTTP layer; per-task budget gates are
-        result-level (200 + errorCode), NOT here (pinned wire contract).
+        429 — a limit was hit. Three real `errorCode`s ride this status: `limit.cost_quota_exceeded`
+        (per-principal CUMULATIVE cost quota — the QuotaError body below), `limit.rate_exceeded`
+        (request-rate limit; also the status-derived fallback code), and `quota_exhausted` (the E4 fleet
+        quota-LEASE budget). `Retry-After` (seconds) honored by the SDK on retry. These are the ONLY
+        budget/limit signals at the HTTP layer; per-task budget gates are result-level (200 + errorCode),
+        NOT here (pinned wire contract).
       headers:
         Retry-After:
           schema: { type: integer }
@@ -3521,7 +3411,7 @@ components:
 
     ScenarioDetail:
       # 新增(2026-07-25 回填批):`GET /v1/capabilities/scenarios/{name}` 此前**整条路径**都不在本文件里
-      # (只有 `Capabilities.scenarios` 那个名字数组)。形按 server 亲读取证(`http/server.ts:1517-1527`)。
+      # (只有 `Capabilities.scenarios` 那个名字数组)。形按 server 亲读取证(`src/http/routes/capabilities.ts`)。
       type: object
       description: >
         One scenario's detail card (`GET /v1/capabilities/scenarios/{name}`). The LIST of names rides
@@ -3557,7 +3447,6 @@ components:
         promptTokens: { type: integer }
         cachedTokens: { type: integer }
         outputTokens: { type: integer }
-        costUsd: { type: number, deprecated: true, description: "Legacy float track — prefer integer costMicroUsd for accounting (no FP drift); canonical read = the SDK's taskCostMicroUsd() normalizer. Kept on the wire (older engines still emit it)." }
         cacheHitRate: { type: number }
         toolCalls: { type: integer }
         cacheWriteTokens: { type: integer, description: Short-TTL cache-write tokens. }
@@ -3568,8 +3457,15 @@ components:
         costMicroUsd:
           type: integer
           description: >
-            Integer micro-USD cost. Prefer this over the float `costUsd` for accounting (no FP drift). Both are
-            emitted; they describe the same spend.
+            Integer micro-USD cost — the ONLY cost track on this object (core 2.0.0 removed the legacy float
+            `costUsd` at the source, server 1.319.0 adopted it, and SDK 1.0.0 removed the mirroring field plus its
+            ×1e6 fallback). Canonical read = the SDK's `taskCostMicroUsd()` normalizer (integer pass-through + a
+            non-finite guard).
+            ⚠️ SCOPE: this removal covers `TaskStats` (and its nested/checkpoint variants) ONLY. The float
+            `costUsd` on the SERVER's own accounting surfaces is alive and untouched — `GET /metrics/summary`
+            (`costUsd`/`costUsdByModel`) and the usage-analytics face (`UsageTotals.costUsd`, `?metric=costUsd`)
+            are server-side aggregates computed as Σ costMicroUsd / 1e6. Seeing those is NOT evidence of an
+            un-upgraded peer.
         costBreakdown:
           description: >
             Per-axis cost detail (LLM root / nested subagents / compaction / infra). Deliberately untyped — it is an
@@ -3665,6 +3561,25 @@ components:
         sessionId:
           type: string
           description: Continue a conversation (same sessionId across turns). Omit on first turn → service mints one.
+        requireExistingSession:
+          type: boolean
+          description: >
+            design/114 Phase3 warm-resume assertion: require `sessionId` to ALREADY exist. `true` + a genuinely
+            missing session (expired / purged / never created) ⇒ the run FAILS LOUD (`resume.session_not_found`)
+            instead of silently starting a fresh empty session ("looks warm, actually fresh"). Sending `true`
+            with NO sessionId also fails loud (nothing to resume). Absent/`false` ⇒ the historical create-on-miss.
+            Rides the persisted body onto resume legs.
+        projectId:
+          type: string
+          description: >
+            design/142-S4: which PROJECT this run belongs to (a center registry key — generic lowercase UUID).
+            A SELECTOR, not an identity or a capability: the tenant segment of any scope always comes from the
+            verified principal, and the client only passes this through (zero minting authority). Shape-gated in
+            the server authorizer — a malformed value is a 422 with `errorCode: "invalid_project_id"`. On the
+            multi-tenant DB memory face it moves the derived scope from the user shelf to the project shelf
+            (`proj:<tenant>/<projectId>`) and seeds `memory.scopes` from that project's `defaultScopes`;
+            single-user deployments ignore the derivation and only apply the seed. Rides the persisted body
+            onto resume legs.
         jobId:
           type: string
           minLength: 1
@@ -3717,6 +3632,18 @@ components:
             branch via setLeafId). With rewindFiles=true ⇒ "both" (also restore the working tree). Alone ⇒
             "conversation". HONORED only where the deployment wired a resume-anchor store + getLeafId (capabilities.resumeAt);
             unknown anchor ⇒ 4xx, capability-off ⇒ 501. Cannot combine with a durable resume.
+        resumeAtMode:
+          type: string
+          enum: [at, before]
+          description: >
+            [833] EXCLUSIVE rewind (core 1.292 TaskSpec.resumeAtMode) — qualifies `resumeAt`'s landing point.
+            `at` (the default when absent — zero regression) KEEPS the target message in the branched context;
+            `before` branches at the target's PARENT, EXCLUDING the target itself ("remove this prompt and
+            everything after it"). core enforces the edges and the service passes its rejection codes through
+            UNCHANGED for the shell to render: `resume_at.before_target_not_user` (plain user-message targets
+            only), `resume_at.before_root_unsupported` (cannot rewind past the session root — start a new
+            session), `rewind_snapshot.unresolvable` (with rewindFiles: no snapshot at/above the branch point).
+            Only meaningful WITH `resumeAt` — sent alone it is a 400 (fail-loud, not a silent no-op).
         rewindFiles:
           type: boolean
           description: >
@@ -3890,7 +3817,28 @@ components:
             deadlineNudge: { type: boolean, enum: [false] }
             callCapByDeadline: { type: boolean, enum: [false] }
             gracefulFinalize: { type: boolean, enum: [false] }
+        outputSchema:
+          type: object
+          additionalProperties: true
+          description: >
+            Structured-output constraint (CC `--json-schema`): a JSON Schema the model's FINAL answer must match.
+            Threaded into core's TaskSpec.outputSchema, which injects a built-in `submit_output` tool and surfaces
+            the validated object as `TaskResult.structuredOutput`. An invalid submit retries (see `outputRetries`),
+            then fails the task with `output.invalid`. A plain JSON-Schema OBJECT — the server validates shape and
+            size; deep validity is core's. (Paired knob: `outputRetries` was already declared without this one.)
         outputRetries: { type: integer, description: How many times to retry a malformed structured output. }
+        resilience:
+          type: object
+          description: >
+            design/131 (core 1.246) per-task resilience INTENT flags. `allowDegrade` / `allowFailover` are
+            caller-facing (permit model degradation / provider failover for this run). `bypassBreaker` is
+            OPERATOR-ONLY: for a non-operator caller resolveSpec DROPS the key — a permission downgrade, not a
+            400, so a 2xx does NOT mean the breaker was actually bypassed. All opt-in; absent ⇒ the deployment's
+            default resilience posture.
+          properties:
+            allowDegrade: { type: boolean }
+            allowFailover: { type: boolean }
+            bypassBreaker: { type: boolean, description: 'Operator-only; silently dropped for non-operator callers.' }
         compaction:
           type: object
           description: Compaction tuning for this task.
@@ -4143,7 +4091,10 @@ components:
 
     QuotaError:
       type: object
-      description: 429 per-principal cumulative-quota body (`quotaExceeded`).
+      description: >
+        429 per-principal cumulative COST-quota body (`errorCode: "limit.cost_quota_exceeded"`). The other two
+        429 codes carry different bodies: `limit.rate_exceeded` sends only `retryAfterSec`, and
+        `quota_exhausted` (E4 lease) passes the center's structured deny fields through verbatim.
       additionalProperties: true
       properties:
         error: { type: string }
@@ -4304,10 +4255,11 @@ components:
                   selected: { type: array, items: { type: string } }
                   note: { type: string }
         reason: { type: string }
-        # design/80 D-1 — action binding (TOCTOU guard). Read the three off the PendingCheckpoint the human saw
+        # design/80 D-1 — action binding (TOCTOU guard). Read the TWO off the PendingCheckpoint the human saw
         # and echo VERBATIM; server resolves THAT exact checkpoint, fail-closed on mismatch (approval_binding_mismatch).
         # Omit only against a pre-D-1 worker. boundInputHash is OPAQUE — never hashed/recomputed client-side.
-        checkpointToken: { type: string, description: 'Single-use token of the exact checkpoint the human saw.' }
+        # 🔴 `checkpointToken` REMOVED (SDK 1.0.0): §4a makes it server-INTERNAL and it is NEVER surfaced on a
+        # /v1/approvals row, so a compliant client has no way to obtain a correct value for it.
         boundCallId: { type: string, description: '= PendingCheckpoint.boundCallId (the bound pendingAction.toolCallId).' }
         boundInputHash: { type: string, description: 'Echo PendingCheckpoint.boundInputHash byte-for-byte; server-minted opaque, NEVER recompute.' }
         updatedInput:
@@ -4337,7 +4289,14 @@ components:
           description: false ⇒ stats.costMicroUsd=0 may mean "no MODEL_COST_* configured", not "free".
         memory:
           type: boolean
-          description: Memory transparency endpoints (GET/DELETE /v1/memory) available. the pinned wire contract.
+          description: >
+            🔴 HARD-CODED `false` on every current server (design/138 S1, clay 2026-07-08): it advertised the
+            legacy MemoryStore surface (`GET`/`DELETE /v1/memory`), which was retired together with the store
+            itself. The memory ENGINE that replaced it is model-facing skills over an injected memory dir and
+            has NO service HTTP verbs, so this flag is not its availability signal. The SDK removed the five
+            legacy verbs in 1.0.0; the live face is `client.memory.exportScope` / `.sync`
+            (`GET /v1/memory/export`, `POST /v1/memory/sync/{scope}`), which this flag does NOT gate.
+            Kept on the wire so an older shell that still reads it honestly hides the dead affordances.
         workflows: { type: boolean, description: "S8 self-orchestration workflow routes are mounted." }
         workflowsList: { type: boolean, description: "`GET /v1/workflows` list face (separate from the per-run reads)." }
         resumeAt: { type: boolean, description: "E18 resume-at-message anchors are resolvable." }
@@ -4444,12 +4403,16 @@ components:
             hooks: { type: boolean }
         memoryWrite:
           type: boolean
-          description: MF-30 — memory WRITE (append/edit/forget) available (deps.memory.append; server.ts:828).
+          description: >
+            🔴 HARD-CODED `false` on every current server, for the same reason as `memory` above: it advertised
+            the MF-30 session memory WRITE verbs, retired with the legacy MemoryStore (SDK 1.0.0 removed them).
+            NOT related to `TaskRequest.memoryWrite` (the per-run memory-engine write PAUSE toggle), which is
+            live and ungated by this flag.
         sessionSync:
           type: boolean
           description: >
             2c session-sync (P1d) — the `/v1/sessions/{sessionId}/sync/*` peer routes resolve (durable backend +
-            entry-export seam + a file-snapshot store wired; server.ts:850). Gate the whole sync surface off this.
+            entry-export seam + a file-snapshot store wired; src/http/routes/capabilities.ts). Gate the whole sync surface off this.
 
     SkillSpec:
       type: object
@@ -4495,28 +4458,10 @@ components:
               egress: { type: boolean }
               irreversibility: { type: string, enum: [always, never] }
 
-    MemoryRecord:
-      type: object
-      description: The caller's own <user_memory> (owner-scoped by construction). content null = empty.
-      required: [scope, content]
-      properties:
-        scope: { type: string }
-        content: { type: ['string', 'null'] }
-
-    MemoryWriteAck:
-      type: object
-      description: MF-30 write ack — unified { ok, id, scope } for append/edit/forget (service; the handler
-        always returns ok — the old src:2880 summary comment that dropped it was a doc-bug). id = the note (unchanged on edit).
-      required: [ok, id, scope]
-      properties:
-        ok: { type: boolean }
-        id: { type: string }
-        scope: { type: string }
-
     ModelInfo:
       type: object
       description: >
-        A non-secret `@model` catalog entry (GET /v1/models; service server.ts:860-880). `name` = the `@handle` the
+        A non-secret `@model` catalog entry (GET /v1/models; service src/http/routes/capabilities.ts). `name` = the `@handle` the
         user types in the objective body to pick this model per-task. 🔴 NON-SECRET — name/capabilities only, never
         baseUrl/apiKey/headers (the service strips them). Open set (additive future fields).
       required: [name]
@@ -4867,7 +4812,7 @@ components:
         tokens: { type: integer }
     FleetFrame:
       description: >
-        One decoded frame off GET /v1/fleet/stream (service streamFleet emit set, http/server.ts:4877-4908). On the
+        One decoded frame off GET /v1/fleet/stream (service streamFleet emit set, src/http/routes/fleet.ts). On the
         wire this is SSE framing (the `type` here = the SSE `event` name; the object = the decoded `data:` JSON).
         Emit order: `meta` (FIRST) → `snapshot` (connect-time full set) → per-row `task`/`workflow` upserts +
         `task_remove`/`workflow_remove` departures. The SDK PRODUCES these frames; the consumer maintains the
@@ -5070,7 +5015,7 @@ components:
       description: >
         The `GET /v1/approvals` operator queue row (true shape). NEVER includes a capability token.
         ⚠️ `createdAt`/`deadline` are EPOCH MILLISECONDS (numbers), not ISO strings.
-        🔴 真矛盾撞获+纠正(2026-07-25,core [1640] 审计撞获 + server 复核确认 server.ts:4536→
+        🔴 真矛盾撞获+纠正(2026-07-25,core [1640] 审计撞获 + server 复核确认 src/http/routes/approvals-assistant.ts→
         listPending() 真实实现 `src/plugins/tidb-checkpoint-store.ts:54-79`):这份 schema 此前声称
         "MIRRORS core CheckpointSummary,顶层 gateKind/severity,NEVER a riskDescriptor object"——
         与真实实现完全相反。真实的 `PendingCheckpoint`(service 自定义类型,不是 core 的
@@ -5243,7 +5188,7 @@ components:
           type: string
           # 🔴 `needs_review` 是 2026-07-25 补的:server 的行过滤器逐字是
           #   `.filter(r => r.status === "running" || r.status === "suspended" || r.status === "needs_review")`
-          #   (`http/server.ts:4677`,已亲读取证)——本枚举此前只有前两个,是真陈旧,照它生成的客户端会把一个
+          #   (`src/http/routes/approvals-assistant.ts`,已亲读取证)——本枚举此前只有前两个,是真陈旧,照它生成的客户端会把一个
           #   合法的一等 triage 态判成非法值。字段级 drift 门只比字段名、比不到枚举值,所以它没抓到这条。
           enum: [running, suspended, needs_review]
           description: >
@@ -5277,9 +5222,9 @@ components:
     AssistantTaskStatus:
       # 新增(2026-07-25 回填批):§4b resume / §4c plan_review / §4d preempt 三条决策端点此前在本文件里都只声明
       # 了 `{status}` 一个字段——与 SDK 三批核查前的旧类型同样陈旧。下面的形按 server 源码逐字取证:
-      #   • resume / plan_review 200(共用 `driveResumeIntoRunLog`,`http/server.ts:7688-7696`):
+      #   • resume / plan_review 200(共用 `driveResumeIntoRunLog`,`src/http/routes/approvals-assistant.ts`):
       #       `{ taskId, sessionId, status, errorCode?, errorMessage?, retriable? }`(后三个条件 spread ⇒ 缺则省键)
-      #   • preempt 202(`http/server.ts:4726/4734/4737` 三个出口):`{ taskId, status, note }`
+      #   • preempt 202(`src/http/routes/approvals-assistant.ts` 三个出口):`{ taskId, status, note }`
       #     ⚠️ `status` 在 202 上**并非恒为 `"preempting"`**:两个 no-op 出口分别回 `run.status` 与
       #        `now?.status ?? "failed"` —— 所以这里不能把它写成 const。
       type: object
@@ -5649,15 +5594,19 @@ components:
       description: >
         Typed-error source. The SDK maps (status, errorCode) → a semantic error class so callers branch on the
         error, not a string. Messages are secret-scrubbed before surfacing.
-        🔴 CANONICAL KEY (server >=1.302, 2026-07-28 归一): `errorCode` is ALWAYS present on typed error
-        bodies — the historical `code`-only track is retired (a source-level gate enforces it server-side).
-        `code` may still ride alongside as the historical/original-core-code slot; consumers read `errorCode`.
+        🔴 SINGLE KEY (server >=3.0.0): `errorCode` is the ONLY machine key on a typed error body. The
+        historical `code` slot is GONE at the source (`http/send.ts` emits `{error, errorCode, ...extra}`;
+        a source-level gate enforces it server-side) and the SDK no longer reads it — a body that still
+        sends `code` yields `errorCode: undefined` and no typed subclass.
       additionalProperties: true
       properties:
         errorCode:
           type: string
           description: >
-            HTTP-error typed code. Known: `conflict` (409 session active / CAS), `quotaExceeded` (429).
+            HTTP-error typed code. Real examples: `conflict` (409 session active / CAS);
+            `limit.cost_quota_exceeded` (429 — the principal's CUMULATIVE cost quota; body = QuotaError);
+            `limit.rate_exceeded` (429 — request-rate limit, also the status-derived fallback code);
+            `quota_exhausted` (429 — the E4 fleet quota-LEASE budget, distinct from the cost quota).
             NOTE: budget (`budget.precall`/`budget.exceeded`) and `cancelled` are RESULT-level codes on
             TaskResult/RunRecord, NOT HTTP errors (pinned wire contract).
         error: { type: string }
@@ -5828,7 +5777,7 @@ components:
     Event_suggestions:
       type: object
       description: >
-        E12 (shell-host; service runs.ts:392 + server.ts:3633, opt-in via `TaskRequest.suggestNextPrompts`) —
+        E12 (shell-host; service runs.ts:392 + src/http/routes/runs.ts, opt-in via `TaskRequest.suggestNextPrompts`) —
         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.
@@ -5839,10 +5788,16 @@ components:
     Event_status:
       type: object
       description: >
-        design/99 §E3/§E10 (SHIPPED, LIVE-only) — a brain-layer liveness status the brain would otherwise absorb
-        silently (429 rate-limit / 5xx-or-network retry / reconnect / open circuit breaker). EPHEMERAL — never
-        persisted/replayed on resume; provider-neutral (NO HTTP status / stop_reason). `phase` is core's closed
-        BrainStatusPhase but render open (a deployment may add a phase on its own channel).
+        design/99 §E3/§E10 (SHIPPED) — a brain-layer liveness status the brain would otherwise absorb silently
+        (429 rate-limit / 5xx-or-network retry / reconnect / open circuit breaker). Provider-neutral (NO HTTP
+        status / stop_reason). `phase` is core's closed BrainStatusPhase but render open (a deployment may add a
+        phase on its own channel). 🔴 WIRE NOTE (design/158 B2, corrects the prior "EPHEMERAL — never
+        persisted/replayed on resume" claim): the durable/replay leg (GET /v1/runs/:id/events) DOES persist this
+        as its own liveness observation row. Server >=1.317 uses this SAME arm name on both legs AND normalizes
+        pre-upgrade rows (stored under the historical literal `brain_status`) to `status` at the read boundary —
+        stored bytes untouched, but a >=1.317 server never delivers the old literal. 🔴 The deprecated
+        `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' }]
       required: [type, phase]
       properties:
@@ -6303,7 +6258,7 @@ components:
     ApprovalStreamEvent:
       type: object
       description: >
-        One delta event off GET /v1/approvals/stream (SSE; server streamApprovals, http/server.ts:8924).
+        One delta event off GET /v1/approvals/stream (SSE; server streamApprovals, src/http/routes/approvals-assistant.ts).
         Every data payload echoes a `type` field mirroring the SSE event name (so a client can dispatch
         without the `event:` line). OPEN set — a consumer that does not parse the delta can treat any
         non-heartbeat event as a "changed" signal and refetch the authoritative GET /v1/approvals list.
@@ -6340,7 +6295,7 @@ components:
     FleetMeta:
       type: object
       description: >
-        The connect-time `meta` frame payload of GET /v1/fleet/stream (server http/server.ts:9675 —
+        The connect-time `meta` frame payload of GET /v1/fleet/stream (server src/http/routes/fleet.ts —
         the payload view of FleetFrame_meta, without the SSE frame envelope).
       required: [version, scoped]
       additionalProperties: true
@@ -6429,7 +6384,7 @@ components:
       type: object
       description: >
         The RUNNER claim response of POST /v1/images/bakes/claim and POST /v1/images/bakes/{bakeId}/claim
-        (server claimResponse, http/server.ts:9164 — exact key set): the VETTED argv + the per-bake ingest
+        (server claimResponse, src/http/routes/images.ts — exact key set): the VETTED argv + the per-bake ingest
         secret (minted at claim, echoed on every ingest via the x-bake-ingest-secret header) + the
         profile/bands the runner needs for its profile-aware hard deadline. The runner executes `argv`
         VERBATIM — it never assembles its own command line. 204 (no body) = queue empty.
@@ -6471,7 +6426,7 @@ components:
       type: object
       description: >
         One SendUserFile distribution-link ledger row of GET /v1/sendfile-links (envelope `{links,
-        nextBefore?}`; server http/server.ts:5504 — exact projection). A principal caller is PINNED to its
+        nextBefore?}`; server src/http/routes/sessions-list.ts — exact projection). A principal caller is PINNED to its
         own scope (?scope= ignored); a fleet credential may pass ?scope= (default = the single-user
         sentinel "_"). Page with `before` = a previous page's `nextBefore` (uuidv7; malformed → 400).
       required: [id, filename, size, ttlSec, track, bucket, key, createdAt]
@@ -6492,7 +6447,7 @@ components:
       type: object
       description: >
         The 200 receipt of POST /v1/runs/{runId}/subagents/{target}/steer and …/resume (server
-        http/server.ts:4143/4148 — exact literal: `status:"running"`, `delivery:"applied"`, `marker` =
+        src/http/routes/runs.ts — exact literal: `status:"running"`, `delivery:"applied"`, `marker` =
         the engine-minted delivery marker, `note` = the CC-verbatim "Message queued for delivery…" copy).
       required: [taskId, target]
       additionalProperties: true
@@ -6508,7 +6463,7 @@ components:
       type: object
       description: >
         The 200 body of GET /v1/runs/{runId}/subagents/{target}/output and the generic
-        …/tasks/{target}/output|/stop faces (server http/server.ts:3852/4070). `content` = the engine
+        …/tasks/{target}/output|/stop faces (server src/http/routes/runs.ts). `content` = the engine
         TaskOutput-tool text (the child's final assistant body once terminal) — UNTRUSTED model output,
         same posture as a run `result`. `output` = the engine registry's UnifiedTaskOutput projection
         passed through VERBATIM.
@@ -6545,7 +6500,7 @@ components:
     CompactAck:
       type: object
       description: >
-        The 202 ack of POST /v1/runs/{runId}/compact (K-1c manual compaction; server http/server.ts:3595 —
+        The 202 ack of POST /v1/runs/{runId}/compact (K-1c manual compaction; server src/http/routes/runs.ts —
         exact literal: `status:"running"`, `delivery:"accepted"`). ACCEPTANCE, not an outcome: compaction
         runs at the next turn boundary and a `compacted{trigger:"manual"}` event rides the run stream ONLY
         if anything was summarized (mooted/failed → no event).
@@ -6560,7 +6515,7 @@ components:
     DetachAck:
       type: object
       description: >
-        The 202 ack of POST /v1/runs/{runId}/detach (server http/server.ts:3650 — exact literal:
+        The 202 ack of POST /v1/runs/{runId}/detach (server src/http/routes/runs.ts — exact literal:
         `toolCallId` echoed, `delivery:"requested"`). Fire-and-forget: acceptance only — the
         authoritative outcome is the tool call's own `tool_end.structured {detached:true, task_id}`;
         a non-detachable env makes the request a fail-safe no-op.
@@ -6575,7 +6530,7 @@ components:
     SideQueryRequest:
       type: object
       description: >
-        The POST /v1/side-query body ([1469], server 1.242; http/server.ts:1853 — whitelist passthrough of
+        The POST /v1/side-query body ([1469], server 1.242; src/http/routes/side-query.ts — whitelist passthrough of
         core SideQuerySpec). One-shot brain routing Q&A: no session side effects, no tool EXECUTION, no
         engine-side policy gate, no streaming (v1). `signal` is server territory — client disconnect
         abandons the call; sending it in the body is discarded. Rides every billable-submit gate
@@ -6607,7 +6562,7 @@ components:
       type: object
       description: >
         The 200 body of POST /v1/side-query (core SideQueryResult passed through verbatim, server
-        http/server.ts:1917). `model` = routing identity; `servedModel` = who actually served (degrading
+        src/http/routes/side-query.ts). `model` = routing identity; `servedModel` = who actually served (degrading
         fallback attributes honestly). A post-stream error lands in `errorMessage`, NOT an HTTP error
         (400 is reserved for validation/model-resolution; 5xx = a server defect).
       required: [text, toolCalls, model, servedModel, usage, stopReason]
@@ -6711,7 +6666,7 @@ components:
       type: object
       description: >
         The common window envelope of the /v1/usage/{summary,series,breakdown} responses (server
-        http/server.ts:1284). `from`/`to` are the RESOLVED window (ISO-8601; defaults now-7d..now).
+        src/http/routes/trace-usage.ts). `from`/`to` are the RESOLVED window (ISO-8601; defaults now-7d..now).
       required: [from, to]
       additionalProperties: true
       properties:
@@ -6723,14 +6678,14 @@ components:
           description: 'Present (true) ⇔ the store scan hit its row limit (USAGE_SCAN_LIMIT) — the window was truncated, never silently.'
 
     UsageSummary:
-      description: 'The 200 body of GET /v1/usage/summary — window envelope + totals (server http/server.ts:1286).'
+      description: 'The 200 body of GET /v1/usage/summary — window envelope + totals (server src/http/routes/trace-usage.ts).'
       allOf:
         - $ref: '#/components/schemas/UsageWindowBase'
         - $ref: '#/components/schemas/UsageTotals'
 
     UsageSeries:
       description: >
-        The 200 body of GET /v1/usage/series (server http/server.ts:1294). UTC buckets; EMPTY BUCKETS ARE
+        The 200 body of GET /v1/usage/series (server src/http/routes/trace-usage.ts). UTC buckets; EMPTY BUCKETS ARE
         NOT EMITTED — consumers zero-fill as needed.
       allOf:
         - $ref: '#/components/schemas/UsageWindowBase'
@@ -6750,7 +6705,7 @@ components:
 
     UsageBreakdown:
       description: >
-        The 200 body of GET /v1/usage/breakdown (server http/server.ts:1302). dimension=model expands the
+        The 200 body of GET /v1/usage/breakdown (server src/http/routes/trace-usage.ts). dimension=model expands the
         per-model echo (one run may contribute to several model buckets; fallback rows land in
         "(unattributed)"); dimension=principal maps a NULL owner to "(anonymous)".
       allOf:
@@ -6772,7 +6727,7 @@ components:
     WorkflowAgentSteerReceipt:
       type: object
       description: >
-        The 200 receipt of POST /v1/workflows/{runId}/agents/{label}/steer (server http/server.ts:3752 —
+        The 200 receipt of POST /v1/workflows/{runId}/agents/{label}/steer (server src/http/routes/workflows.ts —
         exact literal: `status:"running"`, `delivery:"applied"`, `marker` = the engine-minted delivery
         marker; NO `note`, unlike the run-subagent verb).
       required: [runId, label]
@@ -6788,7 +6743,7 @@ components:
       type: object
       description: >
         One snapshot row of GET /v1/sessions/{sessionId}/workspace (envelope `{sessionId, snapshots,
-        latest?, total}`; server http/server.ts:6109 — newest first, uuidv7 keys). E19 snapshot store's
+        latest?, total}`; server src/http/routes/sessions.ts — newest first, uuidv7 keys). E19 snapshot store's
         read-only projection: each row is the freeze at a turn boundary, NOT a live workspace.
       required: [key, files]
       additionalProperties: true
@@ -6801,7 +6756,7 @@ components:
       type: object
       description: >
         One file entry of GET /v1/sessions/{sessionId}/workspace/{key}/tree (envelope `{sessionId, key,
-        entries, total, nextOffset?}`; server http/server.ts:6144 — stable path order, offset paging).
+        entries, total, nextOffset?}`; server src/http/routes/sessions.ts — stable path order, offset paging).
       required: [path, hash]
       additionalProperties: true
       properties: