@sema-agent/sdk 0.0.75 → 0.0.77

package/dist/types.d.ts

@@ -1,7 +1,25 @@
+/**
+ * Wire types — authoritative shapes from the service maintainer (see ../../../docs/SERVICE-CORE-CONTEXT.md).
+ * These are NOT guesses; they mirror the live service. They MUST be kept in sync with spec/openapi.yaml (M0):
+ * the contract test (producer side = service, consumer side = here) anchors both to the spec.
+ *
+ * 🔴 The SHARED WORK-VIEW MODEL (Task/Run/Artifact) is the anti-fragmentation substrate (DIRECTION.md §2):
+ * ALL doors — CC/Codex via the MCP façade, and web-native — produce the SAME Task/Run/Artifact. A dev's
+ * run and an ordinary user's run look identical in the workspace. Do NOT fork this per door.
+ */
 import type { SemaSettings } from "./settings.js";
+/** Authenticated end-user identity. Opaque to the service (used as memory scope + session owner). The SDK
+ *  normalizes; the service does NOT validate the format. Convention: `user:` / `org:` / `ai:` / `anon:`. */
 export type Principal = string;
+/** Service scenario = the primary routing axis (one image serves many). Open string (unknown → "default"). */
 export type Scenario = "default" | "oa" | "code-review" | "team" | (string & {});
+/** Terminal + in-flight run states. `suspended` = HITL: a policy gate (F4) or AskUserQuestion is waiting on a
+ *  human — NOT an error (see resources/approvals.ts). */
+/** design/80 D-0: `needs_review` is a durable TERMINAL (dry-run/shadow review) distinct from `suspended`
+ *  (mid-run HITL pause). Closed set on purpose — a new status is minted only with a proven need (D-0 r2:
+ *  don't pre-mint `plan_review`); core→wire contract test guards parity. */
 export type RunStatus = "running" | "completed" | "failed" | "suspended" | "needs_review";
+/** Per-task budget/usage the service reports back. */
 export interface TaskStats {
     turns: number;
     tokens: number;
@@ -10,16 +28,28 @@ export interface TaskStats {
     outputTokens?: number;
     costUsd?: number;
     cacheHitRate?: number;
+    /** 🔴 Live-verified(@sema-agent/server@1.3.0 `done.result.stats` 真回传;原 TaskStats 漏声明 → 严格消费方读不到,
+     *  尤其 `costMicroUsd`/`totalInputTokens` 是成本/总览面板要的。live full-scenario 测逮到,round-6 补)。 */
     toolCalls?: number;
     cacheWriteTokens?: number;
     cacheWriteTokensLong?: number;
     totalInputTokens?: number;
     costMicroUsd?: number;
+    /** ASSISTANT-WIRE-CONTRACT §5（service main 6cd0164 / core 1.110.0）— cost + 人工耗时透传, 运行时已经过
+     *  `GET /v1/runs/:id → result.stats` 原样回传, 这里只补类型层让 N4 总览/成本 UI 能类型安全读取（不另起 wire）。
+     *  这些字段是封闭 TaskStats 之外的可选投影, 缺则 OMIT。 */
+    /** core LLM 成本明细（开放结构, 透传不解析）。 */
     costBreakdown?: unknown;
+    /** 便利字段: LLM + service infra 轴的合计, 仅在 infra 定价已配置且 run 终态时出现。 */
     supervisorCost?: number;
+    /** design/89 §2.4 C2 人工复核负担轴（core 1.110.0）—— budget-EXCLUDED（永不折进成本/预算门, 同 stats.memory）。 */
     humanReview?: {
         count: number;
         totalWaitMs: number;
+        /** MF-24 denial ledger。🔴 **LIVE 钉死(canary 1.6.1 在线验形 2026-06-27,deny 后 result.stats.humanReview)**:
+         *  gate **恰好 4 键** `{kind, decision, toolName, waitMs}`,逐键命中、零未声明字段。**`tool_input`/`toolInput` 不在
+         *  1.6.1 gate ledger 上**(此前推测 core 1.148 会经开集带被拒入参 —— 本部署证伪;留开集 `[k]` 待更新部署再验,不加为
+         *  typed 字段)。`toolName` 实采为被拒工具名(Q6/core 1.161 起 = CC 名,如 "Bash")。 */
         gates: Array<{
             kind: string;
             waitMs: number;
@@ -28,23 +58,67 @@ export interface TaskStats {
             [k: string]: unknown;
         }>;
     };
+    /** 🔴 开集:引擎 `result.stats` 可携带本类型未命名的字段(如 `costBreakdown.*` 明细;live 实测),原样透传不丢。 */
     [key: string]: unknown;
 }
+/** Common request body. `objective` is required; everything else is optional and server-capped where noted.
+ *  `[k: string]: unknown` mirrors the service's passthrough (scenario-specific fields like code-review's
+ *  `repo`/`council`/`debate`/`rounds` ride here). 🔴 `jobId` is the work-view correlation key (DIRECTION §2):
+ *  set it so the workspace groups the runs of one logical job into one Task — across BOTH doors. */
 export interface TaskRequest {
+    /** 🔴 secret discipline: NEVER put tokens/secrets in `objective` or `systemPrompt` — commands/prompts land
+     *  in the durable event stream (tool_start.args) and the L1 session history. Secrets reach the sandbox
+     *  OUT-OF-BAND via the worker's `E2B_SANDBOX_ENV` (see service CONSUMER-SANDBOX-SKILLS.md). */
     objective: string;
     scenario?: Scenario;
+    /** Continue a conversation: pass the same sessionId across turns. Omit on first turn → service mints one. */
     sessionId?: string;
+    /** 🔴 Per-turn MODEL (CC /model picker parity). A model alias ('sonnet'/'opus') or full id. The service
+     *  resolveTaskModel (main.ts:1217) CATALOG-GATES it (body.model wins over @mention wins over the deployment
+     *  default; an out-of-roster pick falls back). Maps to core TaskSpec.model. Omit ⇒ deployment/role default. */
     model?: string;
+    /** Cheap-model gear for within-task compaction/summarize (server ≥1.243, core design/145). A catalog intent
+     *  like `model` (name/tier word/id), gated against the SAME allow-list — an unknown value is a 400 on fresh
+     *  submit. core clamps window-unsafe picks back to the main model (`modelFallback` on the `compacted` event).
+     *  Probe `capabilities.compactionModel`; older servers drop the field. Omit ⇒ summarize role / main model. */
     compactionModel?: string;
+    /** Work-view correlation (the anti-fragmentation substrate). A CC dispatch loop or a web job sets one
+     *  jobId across its sub-runs so they group into one Task. SDK auto-generates if absent. */
     jobId?: string;
+    /** Business/UX system prompt the CLIENT owns (decoupling seam) — STABLE per integrator version (cacheable
+     *  prefix); put per-request context in `objective`. Server cap: >16384 chars → 400. */
     systemPrompt?: string;
+    /** Append-only system prompt rider (server ≥1.243, ≈ CC `--append-system-prompt`): a STABLE block composed
+     *  after the scenario base + `systemPrompt`, before the volatile tail. First-class lane for the shell's
+     *  product-knowledge block — `settings.outputStyle` composes AFTER it (byte-stable order), so a style block
+     *  and this rider coexist. Probe `capabilities.appendSystemPrompt`; on false/absent fall back to the
+     *  `settings.outputStyle` ride-along. Same cap as `systemPrompt`: >16384 chars → 400. */
     appendSystemPrompt?: string;
+    /** Per-request user skills (live, service 170c384): progressive disclosure, same mechanism
+     *  as scenario skills. Server caps: ≤10 items, name ≤64, description ≤1024, content ≤32768 — violations 400.
+     *  Merge: scenario WINS on name collision (user's dropped + warn-logged) — the safety baseline can't be
+     *  overridden. Injected by the trusted BFF, never raw user input. */
     skills?: SkillSpec[];
+    /** Per-turn reasoning strength (CC `/effort` parity). One of the core ThinkingLevel tiers:
+     *  `off`|`minimal`|`low`|`medium`|`high`|`xhigh`|`max`. Service maps it → `TaskSpec.thinking`
+     *  (server.ts reasoningEffort → main.ts:1270); an UNKNOWN value is a 400 (fail-loud). Omit ⇒ engine
+     *  default (the model/role default). The shell stamps the user's `/effort` pick here per turn. */
     reasoningEffort?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    /** User context for env-block localization (core 1.181, design/112). The shell/client knows the user's TZ +
+     *  identity; the worker container runs UTC and knows neither. Threaded → service `body.clientContext` →
+     *  `TaskSpec.clientContext` → core localizes the `# Environment` block's "today" to the user's zone (+ names
+     *  who the agent acts for); absent ⇒ UTC date, no user line. Auto-inherited by subagent/Fork children. Shape =
+     *  core `TaskSpec.clientContext`. The shell stamps `timeZone` from `Intl.DateTimeFormat().resolvedOptions()`. */
     clientContext?: {
         timeZone?: string;
         userEmail?: string;
     };
+    /** Per-request MCP servers (CC `.mcp.json` / `claude mcp add` parity). The trusted BFF/shell projects the
+     *  user's local `.mcp.json` here so the engine mounts those servers' tools. Field shape = core `McpServerSpec`.
+     *  HONORED only on a SINGLE-USER deployment (service `task-mcp.ts mcpInjectionHonored = requirePrincipal!==true`):
+     *  there the caller is their own worker's superadmin (= CC). Multi-tenant: ignored (fail-closed, no RCE/SSRF);
+     *  the fleet gets MCP via center config refs. Merge: deployment/center baseline wins on name collision (caller
+     *  can ADD, never SHADOW), like `skills`. Gate whether to project via `capabilities.mcpInjection`. */
     mcpServers?: McpServerSpec[];
     images?: Array<{
         data: string;
@@ -52,32 +126,137 @@ export interface TaskRequest {
     } | {
         url: string;
     }>;
+    /** Caller-requested ceilings; server caps to the operator max (a caller may ask for less, never more). */
     maxCostUsd?: number;
     maxTokens?: number;
+    /** Developer-mode adversarial verify gate (impl → independent read-only verify → fix loop). Not on `stream`. */
     verify?: boolean;
     verifyRounds?: number;
+    /** Quality-gate cascade (cheap→strong). Mutually exclusive with verify. Not on `stream`. */
     cascade?: boolean;
+    /** §sandbox-image-select（P0.5）：送**镜像 profile 意图**（≤128 chars），service 内部按 trusted
+     *  principal 用 `latestPublished(profile, viewer)` **fail-closed** 解析 digest + 再准入 → per-pod 起像（复用 select 同 visibility）。
+     *  🔴 caller **永远只送 profile,绝不送 digest/ref**（信 caller digest = fail-OPEN，对抗审逮 4 越权）；解析/准入 100% 在 service 信任边界。
+     *  v1 约束（违反 → 400）：仅 k8s 后端；**不与 `verify`/`cascade` 同用**（镜像绑定按 sessionId，子运行换 session 会静默回退默认像，宁可 fail-loud）。 */
     sandboxImageProfile?: string;
+    /** 约束选中像须具备的 bool 能力（`browser`/`db`/`nestedBuild`）；**单独给（无 `sandboxImageProfile`）→ 400**。 */
     capabilitiesNeeded?: string[];
+    /** E12（shell-host;service `normalizeSuggestNextPrompts` spec-fields.ts:9 / runs.ts:392 + server.ts:3276,SHIPPED）
+     *  —— opt-in：run 跑完(`status:"completed"`)后 core 跑一次 LLM pass 生成「下一步可问什么」建议,service 持久成一个
+     *  `suggestions` event（见 {@link AgentEvent} 的 suggestions arm）on the durable run-events tail。`true` = 用 core
+     *  默认；`{count?, role?}` = 调条数 / 指定生成用的 model role。🔴 与 `verify`/`cascade` **互斥**（那两个返 result 非
+     *  streamed run → 400）。只在 `/v1/runs` durable leg 有意义（`POST /v1/tasks` 同步返 result,无 events tail）。
+     *  UNTRUSTED 模型文本（service 已 redact）→ 仅 UI 展示,**绝不回喂模型**。 */
     suggestNextPrompts?: boolean | {
         count?: number;
         role?: string;
     };
+    /** MF-30 PAUSE toggle(per-request,@sema-agent/server 1.4.0 `84ff944` option B,2026-06-27 拍板)——
+     *  `memoryWrite:false` → 本 run 对 memory **只读**(`writeScope:null`:无 remember 工具、无 consolidation 写;recall 仍可)。
+     *  缺省 = 写开启。引擎 main.ts:1183 / security.ts:194 读它。pause 是 per-RUN(非 per-session stored-flag)。 */
     memoryWrite?: boolean;
+    /** 🔴 TOB-fleet 透传(core/search AI 2026-06-27,research/toc-settings-adapter/01-design.md §5②)—— fleet/远端模式
+     *  把用户 `settings.json`(CC-parity {@link SemaSettings})带给 service;**service** 把它 wire 进引擎同款 seam
+     *  (SessionPolicyStore / NodeExecutionEnv / RunnerDeps.hooks),同它做 MF-* 数据契约那层。TOC-local 模式**不走这**
+     *  (shell 适配器直接 wire 本地 `new Runner(deps)`)。⚠️ **service-side wire pending** —— 契约先立、service 接后即 live。
+     *  SDK 只搬契约、不解释、不跑 shell-hook(那是 shell/profile 层的活)。 */
     settings?: SemaSettings;
+    /** 🔴 LOCAL workspace 目录(FATAL 修,service root-cause A)—— 持久 HTTP 引擎(常驻 8788)的 agent
+     *  bash/file 工具默认跑在**引擎启动时的固定 workspaceDir**,而非每次 `sema` 启动的目录;持久进程无从知 client 的
+     *  cwd → client 在 launch 时传 `process.cwd()`,service 在 **LOCAL host-adapter 模式** honor 它(executionEnv
+     *  workspaceDir = cwd)。🔒 安全:cwd 是宿主路径,**只在 local 单用户(REQUIRE_PRINCIPAL=false / host adapter)
+     *  honor;云/多租户 MUST ignore**(否则租户可把共享 worker 指到任意宿主路径 = 路径穿越,同 env-defer 信任边界)。 */
     cwd?: string;
+    /** 🔴 E18 resume-at / REWIND(core 答 §J=方案A "fork-from-entry";core prepare-task.ts:529 `spec.resumeAt`,
+     *  service main.ts:1150-1166)—— 从会话历史里**某条已发生的消息**分叉一条新支线(不是 mutate 旧 run)。值 = 该消息的
+     *  **E2 message eventId**(`AgentEvent.eventId`,client 在流里见过的那个),**非** core 内部 entryId —— service 持有
+     *  eventId→entryId 映射、`resumeAnchorStore.resolve` 折算。**必须配 `sessionId`**(要分叉的会话;session 由 auth 派生,
+     *  body 不带);**不能与 durable resume 同用**(resume 路径会先剥掉 resumeAt 再 re-resolve)。anchor 未知 → 4xx;已知但
+     *  被 compact 掉 → 同步 4xx / 异步 run-result `resume_at.not_found`。worker 无 anchor store(`resumeAnchorStore`+
+     *  `getLeafId`)→ 501,与 `capabilities.resumeAt` 同对一对(能力说 yes ⟺ 路由 resolve)。 */
     resumeAt?: string;
+    /** 🔴 与 {@link resumeAt} 配套(core runtask.ts:1834 `spec.rewindFiles`,service main.ts:1198 `body.rewindFiles===true`)
+     *  —— 分叉时**同时把工作树恢复**到 resumeAt 那一回合完成时的快照(否则只回退对话、文件留在最新态)。core 自动按
+     *  completed-turn 快照 capture/restore(任何 ExecutionEnv,当 fileSnapshotStore wired);worker 缺快照存储则 `rewindFiles`
+     *  能力位 false。缺省 = 不动文件。 */
     rewindFiles?: boolean;
+    /** 🔴 E18 code-only rewind(core 1.166.0 `TaskSpec.rewindFilesTo`,commit 0bf1aeb)—— 把工作树还原到该 message
+     *  entryId 的快照、**不** fork 对话(无 setLeafId）。= CC Rewind "code"-only 模式(`resumeAt`+`rewindFiles`=both、
+     *  `resumeAt` 单独=conversation、本字段=code）。收的是 user-message 的 `SessionTreeEntry.id`（server anchor user
+     *  message 边界后即可端到端）。与 `resumeAt` 互斥使用（code-only 不 fork 对话）。 */
     rewindFilesTo?: string;
+    /** 🔴 PERMISSION MODE INTENT (CC permission mode: `default` | `plan` | `acceptEdits` | `bypassPermissions`).
+     *  The shell/web frontend carries the RAW mode; the SERVICE INTERPRETS it (axis-aware, tighten-only): `plan` ⇒
+     *  mount the first-party `present_plan` tool (core `TaskSpec.enablePlanMode`, CC ExitPlanMode parity) + read-only
+     *  hands (`handsReadOnly`) = CC EnterPlanMode read-only research; `acceptEdits`/`bypassPermissions` are LOOSENING
+     *  → not honorable remotely (tighten-only), coerced to `default` engine-side + enforced client-side. Carrying the
+     *  INTENT (not the client's pre-interpreted core fields) keeps one interpretation across TUI+web frontends and
+     *  lets the service govern per deployment axis (single-user vs multi-tenant). Omit/`default` ⇒ no stamp. */
     permissionMode?: "default" | "plan" | "acceptEdits" | "bypassPermissions" | "auto";
+    /** 🔴 Workflow super-set (sema-cc-parity) — per-task activation of the LLM-authored workflow engine (core
+     *  `run_workflow`: the agent/parallel/pipeline/phase/nested orchestrator). The SERVICE reads `body.selfOrchestration`
+     *  STRICTLY (`=== true`) → `TaskSpec.selfOrchestration`, the gate that MOUNTS run_workflow (the service
+     *  task-workflow.ts `selfOrchestrationFromBody` / main.ts:1343; server.ts:282 SubmitTaskRequest `selfOrchestration?`).
+     *  Gated downstream: (1) DEPLOYMENT — the worker's `SELF_ORCHESTRATION_ENABLED` must be on (else a harmless no-op,
+     *  dropped); (2) MULTI-TENANT — honored only when a per-principal entitlement RESOLVER is wired (fail-closed:
+     *  no resolver ⇒ dropped); single-user honors directly. Absent/false ⇒ no workflow tool this run (default behaviour
+     *  unchanged). Three-gate: engine-can ∧ center-may(allowWorkflows) ∧ shell-show. */
     selfOrchestration?: boolean;
+    /** 🔴 Fork super-set (sema-cc-parity, CC `subagent_type:fork`) — per-task activation of core's first-party Fork
+     *  tool: the model can fork itself into a subagent that INHERITS the parent context + shares the prompt cache
+     *  (vs Task's clean-context subagent). The SERVICE reads `body.enableFork` STRICTLY (`=== true`) → `TaskSpec.enableFork`,
+     *  the gate that MOUNTS the Fork tool (core prepare-task.ts: `enableFork===true` AND a durable session store with
+     *  `hasSessionFork` — TOC's file backend qualifies). OPT-IN (default OFF): fork can recurse / burn tokens, so unlike
+     *  `selfOrchestration` it is NOT default-on — the USER enables it (shell `SEMA_ENABLE_FORK`), the model never gets it
+     *  by default (2026-07-01 拍板: 用户来开,默认对 LLM 不开). Absent/false ⇒ no fork tool this run (default unchanged).
+     *  ⚠️ SERVICE must add the `body.enableFork → spec.enableFork` mapping (awaiting per CHANGELOG 1.38; client path
+     *  now chosen = opt-in model tool). */
     enableFork?: boolean;
+    /** 🔴 [876]③ Per-task custom SUBAGENTS — the shell/client projects the user's subagent definitions
+     *  (`.sema/agents/*.md` or programmatic) here so the ENGINE can mount them as Task-tool agent types for THIS
+     *  run. 0.0.50 BREAKING vs 0.0.49: the 0.0.49 shape (Record keyed by name, description/prompt/tools keys —
+     *  a CC-SDK-style guess) never matched the live wire and was rejected 400 by every deployment; this array
+     *  shape mirrors the server contract verbatim (server 1.205 `spec-fields.js` `validateTaskAgents` /
+     *  `TASK_AGENT_FIELD_SHAPES` = core 1.295 `AgentDefinition`), so no consumer can have depended on the old
+     *  type at runtime. Rules enforced server-side: non-empty array, ≤32 items, unique `name`s, unknown keys
+     *  fail-loud 400 on the strict lane (`permissionMode` is DELIBERATELY excluded from this contract — send it
+     *  and the request is rejected), body→spec lane drops invalid items with a `task_agent_dropped` warn.
+     *  `model` = the SHELL-RESOLVED real model name/id (壳侧已解析,引擎零词表负担 — the server does no alias
+     *  translation; resolve 'sonnet'→id before sending). Multi-tenant deployments ignore this field entirely
+     *  (fail-closed, `task_agents_ignored`). Probe `capabilities.taskAgents` before sending to older servers. */
     agents?: TaskAgentDefinition[];
+    /** 🔴 INTERACTIVE-TOOLS toggle (server 1.214 server.js:4021 — STRICT boolean, anything else 400s).
+     *  `false` = the CC `-p`/headless UNATTENDED semantic: the engine does NOT mount the interactive HITL tool
+     *  family (AskUserQuestion etc.) so the run never parks on a live human — it takes the headless default and
+     *  keeps moving (CI / cron / fire-and-forget). `true`/omit = attended (interactive tools mount where the
+     *  deployment supports them). Probe `capabilities.interactiveTools` (server hardcodes true at server.js:600)
+     *  before sending to OLDER servers — an unknown-field deployment on the strict lane would 400. */
     interactiveTools?: boolean;
+    /** 🔴 Retain background processes past the turn (server 1.214 server.js:4025 — STRICT boolean, else 400).
+     *  `true` = backgrounded Bash tasks (b*) survive the run's turn end instead of being reaped (long dev servers,
+     *  watch builds). HONORED only on a single-user deployment (`capabilities.retainBackgroundProcesses` =
+     *  `requirePrincipal !== true`, server.js:599) — multi-tenant ignores it (a tenant must not pin processes on
+     *  a shared worker). */
     retainBackgroundProcesses?: boolean;
+    /** server ≥1.221 (core 1.314 工具面控制批,[1052]②): roster TRUE-UNMOUNT list — the named wire tools'
+     *  schemas never reach the model (the deny gate saves no tokens; this does), and the assembly manifest
+     *  narrows honestly. Tighten-only: core's inheritance invariant unions it into EVERY child spawn path.
+     *  Malformed (non-array / empty-string items) → 400 fail-loud at submit. */
     excludeTools?: string[];
+    /** server ≥1.221 (core 1.314): DEFERRED DISCLOSURE list — the named MOUNTED tools (built-ins included)
+     *  ride the wire as a placeholder (schema bytes out of the cache prefix) and materialize via ToolSearch
+     *  on demand. The carrier for the shell's "Workflow on by default but not exposed" posture. Same
+     *  validation/inheritance posture as {@link excludeTools}. */
     deferTools?: string[];
+    /** server ≥1.227 (core 1.328 R2, [1144]/[1146]): prompt PRESENTATION profile — `"simple"` (CC 212
+     *  short form; the engine default when omitted) or `"classic"` (the long pre-R2 form; switchable per
+     *  task/model for A/B). Pure presentation axis (no policy change); inherits through the whole
+     *  delegation tree. Any other value → 400 fail-loud at submit; omit to stay on the engine default. */
     promptProfile?: "simple" | "classic";
+    /** server ≥1.254 — context attachments family (core design/133):literal-true opt-ins
+     *  (todoReminder/planModeReminder/budgetUsd/backgroundTasks/toolsDelta/mcpInstructions;false=省键),
+     *  `changedFiles` 可带 {maxFiles};`agentListing`/`skillsListing` 是 core DEFAULT-ON——**explicit false
+     *  才关**(1.254 起 false 真透传;更老 server 静默丢);`todoReminderMode` "baseline"|"off"。 */
     attachments?: {
         todoReminder?: true;
         todoReminderMode?: "baseline" | "off";
@@ -92,6 +271,8 @@ export interface TaskRequest {
         skillsListing?: boolean;
         mcpInstructions?: true;
     };
+    /** server ≥1.254 — per-task limits(数值三键早有;deadline 族三 **opt-out** 只认 literal false:
+     *  timeoutSec 在场即默认 ON 的 nudge/call-cap/graceful-finalize 可关)。 */
     limits?: {
         timeoutSec?: number;
         maxOutputTokens?: number;
@@ -100,18 +281,29 @@ export interface TaskRequest {
         callCapByDeadline?: false;
         gracefulFinalize?: false;
     };
+    /** server ≥1.254 — retry-on-invalid rounds for `outputSchema`(成对旋钮;1..10,无 schema 时 core 忽略)。 */
     outputRetries?: number;
+    /** server ≥1.254 — within-task compaction 的容差旋钮(design/145,与 compactionModel 配套;0..1)。
+     *  其余 compaction 键是操作方轴,wire 不开。 */
     compaction?: {
         clampTolerance?: number;
     };
     [k: string]: unknown;
 }
+/** 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). */
 export interface TaskAgentDefinition {
+    /** Agent name = the `subagent_type` the model passes to Task. Non-empty, ≤64 chars, unique per request. */
     name: string;
+    /** When the model should delegate to this agent (shown in the Task tool's agent list). ≤4096 chars. */
     whenToUse?: string;
+    /** Compact variant of `whenToUse` for lean tool listings. ≤4096 chars. */
     whenToUseLean?: string;
+    /** Allowlist of tool names the agent may use. Omit ⇒ inherit all tools. */
     allowTools?: string[];
+    /** Denylist of tool names (subtractive; applied after `allowTools`). */
     denyTools?: string[];
+    /** Skills preloaded into the agent: `{ name, description, content }` (+ optional manifest/files). */
     skills?: Array<{
         name: string;
         description: string;
@@ -122,19 +314,30 @@ export interface TaskAgentDefinition {
             content: string;
         }>;
     }>;
+    /** Run the agent in the background (parent turn continues). */
     background?: boolean;
+    /** `"worktree"` = run the agent in an isolated git worktree. */
     isolation?: 'worktree';
+    /** 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. */
     model?: string | {
         id: string;
         [k: string]: unknown;
     };
+    /** Thinking level: off | minimal | low | medium | high | xhigh | max. */
     thinking?: string;
+    /** The agent's system prompt. ≤65536 chars. */
     systemPrompt?: string;
+    /** Max agent turns before the subagent is stopped. Positive integer. */
     maxTurns?: number;
+    /** Memory spec (`{ scope?, scopes?, writeScope?, enabled?, scopeContract? }`). */
     memory?: Record<string, unknown>;
+    /** Observer prompt (agent-observes-agent lane). ≤4096 chars. */
     observer?: string;
+    /** Message template the observer sends. ≤4096 chars. */
     observerMessage?: string;
 }
+/** Synchronous task result (`POST /v1/tasks`). */
 export interface TaskResult {
     taskId: string;
     sessionId: string;
@@ -143,51 +346,109 @@ export interface TaskResult {
     errorCode?: string;
     errorMessage?: string;
     stats: TaskStats;
+    /** MF-25 — effective model id that ran the task(`done.result.model`,engine main.ts:1339 `model: config.model.id`)。
+     *  成本/总览面板据此知"哪个模型跑的"。live 实测引擎真回传(@sema-agent/server 1.3.0+)。 */
     model?: string;
+    /** Present when the task was run behind the verify gate. */
     verification?: {
         verdict: "PASS" | "FAIL" | "PARTIAL" | "unverified";
         rounds: number;
         findings: string[];
     };
+    /** [1543] SDK-M 补键(core 真域逐字,engine 一直在发、此前封闭接口读不到):
+     *  salvagedOutput = degenerate/timeout 终态抢救出的最后模型文本(render as partial);
+     *  blockedReason = 任务被策略/门挡下的人类可读因;
+     *  checkpointGate = suspended 时挂起的门(与 events 的 `suspended.gate` 同源——poller 面读这里);
+     *  degraded = 模型降级链实录(from/to/reason/atTurn);
+     *  structuredOutput = outputSchema 任务的结构化产出(0.0.74 的 outputRetries 旋钮所服务的产物)。 */
+    salvagedOutput?: string;
+    blockedReason?: string;
+    checkpointGate?: unknown;
+    degraded?: {
+        from: string;
+        to: string;
+        reason: "breaker_open" | "rate_limit" | "budget" | "server_error" | "last_resort" | (string & {});
+        chain?: string[];
+        atTurn: number;
+    };
+    structuredOutput?: unknown;
+    [k: string]: unknown;
 }
+/** Async run receipt (`POST /v1/runs` → 202). The capability token is NEVER on the wire (server-internal). */
 export interface RunReceipt {
     taskId: string;
     sessionId: string;
     status: RunStatus;
 }
+/** §sandbox-image catalog（service IMAGE-API §7）— `GET /v1/images` 的目录行（visibility 按 principal scoped）。
+ *  门B「选沙箱模板」UI 据此渲染（profile 卡 + 能力徽章 + toolchain）。开集容多余字段；字段源自 worker → 渲染前 sanitize。 */
+/** `GET /v1/models` 的非密钥模型目录条目（core 1.116 `@model` mention 线;service server.ts:535）。
+ *  `name` = `@handle`（用户在正文打 `@<name>` per-task 选它）。🔴 **只名/能力,无 baseUrl/apiKey/headers**（service 已剥）。 */
 export interface ModelInfo {
+    /** `@mention` 句柄 = 用户可选的模型名。 */
     name: string;
+    /** 底层 model id（展示用,如 deepseek-v4-pro）。 */
     id?: string;
     provider?: string;
+    /** 该模型是否 reasoning 档（picker 可标徽章）。 */
     reasoning?: boolean;
+    /** 是否支持图片输入。 */
     vision?: boolean;
+    /** E4（shell-host；service server.ts:868-874，SHIPPED）— 上下文窗口 token 总额 = 「% 上下文已用 / 距 compact N
+     *  token / 低上下文告警」仪表的**分母**。soft-degrade：未知（0）则 service 省略 → 壳渲染裸 token 数无 %。
+     *  （分子 `turn_end.usage.contextTokens` 仍 core-blocked；分母此处已可独立用。） */
     contextWindow?: number;
+    /** E4（service server.ts:874，SHIPPED）— 该模型单次输出的 max token（`maxTokens`）。未知则省略。 */
     maxOutputTokens?: number;
+    /** E7（shell-host；service server.ts:875-879，SHIPPED）— `/effort` picker 的选项 = core 权威默认档集
+     *  （minimal/low/medium/high）。**仅 reasoning 模型**有（非 reasoning 省略，effort 不适用）。这是 picker 默认展示集，
+     *  非硬白名单（请求侧 accept-set 更宽 = 任意 core ThinkingLevel）。 */
     supportedEffortLevels?: string[];
     [k: string]: unknown;
 }
+/** §cost/usage 面板（service `GET /v1/usage`,实测形态已按源审计）—— per-principal 成本配额 + 单任务上限。
+ *  CLI `/cost` `/usage` 面板 + 门B 用量条据此渲染真数据（取代静态占位）。🔴 owner-scoped:worker 据 request principal 自算。
+ *  无配额时 `enabled:false` + 仅 `windowSec`/`maxTask*`（金额/limit 字段缺）→ 渲染须容缺。permissive 开集容未来字段。 */
 export interface UsageInfo {
+    /** 是否配置了成本配额窗口（false ⇒ 仅有单任务上限,无窗口用量账本）。 */
     enabled: boolean;
+    /** 配额滚动窗口秒数（如 86400=日窗）。 */
     windowSec?: number;
+    /** 当前窗口已用（micro-USD,1e-6 美元）。 */
     usedMicroUsd?: number;
+    /** 当前窗口已用（USD,便利投影）。 */
     usedUsd?: number;
+    /** 窗口配额上限（micro-USD）。 */
     limitMicroUsd?: number;
+    /** 窗口配额上限（USD）。 */
     limitUsd?: number;
+    /** 窗口剩余额度（micro-USD;limit - used）。 */
     remainingMicroUsd?: number;
+    /** 是否已超出窗口配额（超则新任务被拦,等 retryAfterSec）。 */
     overLimit?: boolean;
+    /** 超限时建议的重试等待秒数。 */
     retryAfterSec?: number;
+    /** 单任务成本硬上限（USD;与窗口配额独立,总在）。 */
     maxTaskCostUsd?: number;
+    /** 单任务 token 硬上限（与窗口配额独立,总在）。 */
     maxTaskTokens?: number;
     [k: string]: unknown;
 }
+/** §permissions 面板（service `GET /v1/policy`,实测形态已按源审计）—— 当前生效的自治档 + 命令策略 + 上限。
+ *  CLI `/permissions` 面板渲它显「现在能自动做什么、哪些要审批、上限多少」（取代静态占位,真实反映 worker 侧策略）。
+ *  🔴 只读快照:client 不重算/不据此放行（放行 100% 在 worker;面板仅 inspect）。permissive 开集 + 内部嵌套形态容演进。 */
 export interface PolicyInfo {
+    /** 自治档（如 "auto"/"supervised"/...;null = 未设/默认）。开放串,渲染读已知值、容未知。 */
     autonomy?: string | null;
+    /** 命令 → 决策（allow/deny/ask 等）的策略表。内部形态 permissive,渲染读 command/decision。 */
     commandPolicy?: Array<{
         command?: string;
         decision?: string;
         [k: string]: unknown;
     }>;
+    /** 触发人工审批的条件列表（开放结构,透传不解析）。 */
     approvalRequire?: unknown[];
+    /** 生效上限（单任务 + principal 级 + 配额窗口）。缺字段容缺。 */
     limits?: {
         maxTaskCostUsd?: number;
         maxTaskTokens?: number;
@@ -197,51 +458,98 @@ export interface PolicyInfo {
     };
     [k: string]: unknown;
 }
+/** §workflows 可观测（core 1.116 design/97;service `GET /v1/workflows*`）。
+ *  生命周期状态;开放联合容未来新态。源=core `WorkflowRunStatus`(running/completed/failed,workflow-run-store.ts)。 */
 export type WorkflowRunStatus = "queued" | "running" | "completed" | "failed" | (string & {});
+/** `GET /v1/workflows` 列表行 = core `summarizeWorkflowRun` 投影（workflow-run-store.ts:34,跨 InMem/File/PG byte-identical）。
+ *  owner-scoped（service 只返调用方 principal 自己的 run,scope=创建者 principal）。时间均 epoch ms。 */
 export interface WorkflowRunSummary {
+    /** run id（= `WorkflowRun.id`）。 */
     id: string;
+    /** 租户/分组 scope（= 创建 run 的 principal）。 */
     scope: string;
+    /** 🔴 K-2(core SHIPPED 1.155.0)—— `/workflows` 列表渲染:工作流名/描述/当前 phase 标题。core
+     *  `summarizeWorkflowRun` 投影发(additive/tolerate-absent)。 */
     name?: string;
     description?: string;
     currentPhase?: string;
     status: WorkflowRunStatus;
+    /** 已记录的 phase 数。 */
     phaseCount: number;
+    /** 已记录的 agent-run 数。 */
     agentCount: number;
+    /** 总 token = own + nested（summary 已折叠;triage 排序键）。 */
     tokens: number;
+    /** 起始 epoch ms。🔴 MF-W:**queued 态还没起跑 → optional**（1.6.0 / core 1.150,startedAt now optional）。 */
     startedAt?: number;
+    /** 结束 epoch ms（running 时缺）。 */
     endedAt?: number;
+    /** 记录创建 epoch ms（listByScope 排序键）。 */
     createdAt: number;
     [k: string]: unknown;
 }
+/** MF-W (workflow monitor "Activity · last N of M tool calls") — one tool-call beat on a workflow agent's bounded
+ *  activity tail. Source = core `ToolActivity` (types.ts:1023-1035), projected verbatim by the service detail
+ *  handler (`summarizeWorkflowDetail` → `activity: a.activity`, server.ts). Maps to the shell `WorkflowToolCall
+ *  { name, arg? }` (MF-W-workflow-monitor.md): `toolName`→`name`, `arg`→`arg`.
+ *  🔴 `arg` is a SHORT primary-arg summary (command→name, path→basename, url→origin+path), SECRET-SCRUBBED +
+ *  truncated (~80 code points) by core — it is for the monitor's `Read(path)` / `Bash(grep …)` display, NOT the
+ *  full args; render it, NEVER re-feed it to a model. Open shape (index sig) — tolerate future fields. */
 export interface WorkflowActivityBeat {
     phase?: "start" | "end";
     toolCallId?: string;
+    /** The tool name (shell renders `${toolName}(${arg})`). */
     toolName?: string;
+    /** SHORT, secret-scrubbed, ~80-code-point primary-arg summary (set on `phase:"start"`). UNTRUSTED display text. */
     arg?: string;
+    /** Set on `phase:"end"` — whether the tool call errored. */
     isError?: boolean;
     [k: string]: unknown;
 }
+/** MF-W — one agent-run row in a workflow's detail (`summarizeWorkflowDetail` agents projection, server.ts). The
+ *  shape is PERMISSIVE (index sig) — read the known render fields, tolerate the rest as the projection evolves.
+ *  The typed fields are the ones the monitor keys on; `activity[].arg` is the load-bearing addition (round-3 ③). */
 export interface WorkflowAgentRow {
+    /** Display label ("port:/mcp"). */
     label?: string;
+    /** Lifecycle status (the input vocab the display derivation reads). */
     status?: string;
+    /** The phase title this agent ran under (groups it into a phase bucket). */
     phase?: string;
+    /** Per-agent model display label ("Opus 4.8 (1M context)") — SVC-4 / CORE-8 ①. */
     model?: string;
     tokens?: number;
     turns?: number;
+    /** Total tool calls ("M" in "last N of M tool calls") — CORE-8 ②. */
     toolCalls?: number;
+    /** MF-W "Activity" tail — the LAST-N tool-call beats (bounded; `arg` is the per-beat display summary). CORE-8 ③. */
     activity?: WorkflowActivityBeat[];
+    /** What the worker was ASKED (core-redacted + bounded). UNTRUSTED display text. */
     prompt?: string;
+    /** The worker's final OUTPUT (core-redacted + bounded). UNTRUSTED display text. */
     output?: string;
     [k: string]: unknown;
 }
+/** `GET /v1/workflows/:id` 完整 run（core `WorkflowRun`,orchestration/workflow.ts;service `summarizeWorkflowDetail`
+ *  投影）。非 owner → 404（无 existence oracle）。
+ *  🔴 phases/groups/stats 内部嵌套形态可能演进 → 标 permissive（unknown[]/index sig);消费方按需读、容缺。
+ *  🔴 round-3 ③: `agents[]` 收紧为 {@link WorkflowAgentRow}（暴露 `activity[].arg`,MF-W 监视器渲染键),仍 index-sig 容缺。
+ *  🔴 工作流级 `name`/`description`(core `WorkflowRun.name?/description?` 确有,MF-W 头部要)截至 service `1bf7a5c`
+ *     **未被 `summarizeWorkflowDetail`/`summarizeWorkflowRun` 投到 wire** → SDK 暂不声明（不造没发的形;service 补投后再加）。 */
 export interface WorkflowRun {
     id: string;
     scope: string;
     status: WorkflowRunStatus;
+    /** 🔴 K-2c detail 侧(service `summarizeWorkflowDetail` server.ts:5171-5172,redacted/omit-when-absent)—— 工作流头部
+     *  名/副标题(来自脚本 `export const meta={name,description}`)。detail **不带 `currentPhase`**(那是 summary 行字段;
+     *  detail 有完整 `phases[]` 含 per-phase `title`,当前 phase 自这里取)。老 run 二者皆缺。 */
     name?: string;
     description?: string;
+    /** 阶段记录（内部形态 permissive;渲染读 length/已知字段即可。detail 投结构化 `{title,status,startedAt,endedAt,durationMs,done,total}`）。 */
     phases: unknown[];
+    /** agent-run 记录（收紧为 {@link WorkflowAgentRow}:暴露 MF-W `activity[].arg`;仍容缺/容演进）。 */
     agents: WorkflowAgentRow[];
+    /** 统计（`stats.tokens` own + `stats.nested.tokens`,R-5 own/nested 分开存）。 */
     stats: {
         tokens?: number;
         nested?: {
@@ -250,6 +558,7 @@ export interface WorkflowRun {
         };
         [k: string]: unknown;
     };
+    /** 起始 epoch ms。🔴 MF-W:queued 态还没起跑 → optional（1.6.0 / core 1.150）。 */
     startedAt?: number;
     endedAt?: number;
     createdAt: number;
@@ -267,9 +576,11 @@ export interface ImageIndexEntry {
     podContract?: Record<string, unknown>;
     status?: string;
     visibility?: string;
+    /** 不可变 digest（一个 running sandbox 由它 build）。🔴 UI **仅展示**，caller **绝不送它回去绑定**（绑定送 profile）。 */
     digest?: string;
     [k: string]: unknown;
 }
+/** `POST /v1/images/select` 的 §7 resolution 结果（**仅 UI 预览"这 profile 解析到哪个 digest/能力",非绑定凭证**）。 */
 export interface ImageSelectResult {
     profile?: string;
     digest?: string;
@@ -283,6 +594,8 @@ export interface ImageSelectResult {
     manifestSha?: string;
     [k: string]: unknown;
 }
+/** Run state (`GET /v1/runs/:id`) — LIVE shape (service Drift 2): `result` is the NESTED TaskResult
+ *  (output text = result.result, stats = result.stats; no top-level stats); error text field is `error`. */
 export interface RunRecord {
     taskId: string;
     sessionId: string;
@@ -290,17 +603,30 @@ export interface RunRecord {
     result?: TaskResult;
     errorCode?: string;
     error?: string;
+    /** Work-view correlation. Present when the run has a jobId (omitted when null). LIVE server-side
+     *  (service 63b8696): persisted + groupable via `GET /v1/tasks?jobId=`. */
     jobId?: string;
+    /** System-level attribution, DERIVED FROM the authenticating credential (unforgeable; body injection is
+     *  ignored). e.g. "oa" | "cc-mcp" | "portal". LIVE (service cf1be73). */
     source?: string;
+    /** E12 prompt-suggestions(`suggestNextPrompts:true` 提交后)—— **完成后**才产(settle 前 undefined,轮询到出现);
+     *  UNTRUSTED 模型文本、仅 UI、绝不回喂模型。🔴 **LIVE 验证(tidb 引擎 2026-06-27)**:`runs.get`
+     *  把 events tail 上最后一个 `suggestions` 事件读进此字段(server.ts:1371)—— 不流式消费 events 的轮询方从这读。
+     *  仅 durable run(async,需 TiDB run store);流式消费方读 {@link AgentEvent} 的 `suggestions` arm(两路同源)。 */
     suggestions?: string[];
 }
+/** Run list item (`GET /v1/tasks` items) — the live cheap `runSummary` shape (service Drift 1).
+ *  NOTE wire names: `id` (not taskId), `startedAt` (not createdAt), `costMicroUsd` (micro-USD); no sessionId. */
 export interface TaskSummary {
     id: string;
     status: RunStatus;
     scenario?: string;
     jobId?: string;
+    /** Credential-derived system attribution. */
     source?: string;
+    /** Objective, secret-redacted then truncated to 120 chars (the pinned wire contract; older rows null/absent). */
     objectivePreview?: string;
+    /** Run owner principal (boss/operator view; the pinned wire contract). */
     owner?: string;
     startedAt: string;
     endedAt?: string;
@@ -313,25 +639,59 @@ export interface TaskSummary {
     };
     [k: string]: unknown;
 }
+/** A workspace artifact — deterministic projection of persisted tool events (co-signed with the service).
+ *  `kind` is an OPEN set: render unknown kinds as a generic row, never crash. v1 emits "file" | "git-push"
+ *  ("diff" reserved, not emitted). */
 export interface Artifact {
+    /** "<taskId>:<n>" — stable within the task (UI key). */
     id: string;
     taskId: string;
+    /** Present when the run has a job (job-level aggregation key). */
     jobId?: string;
     kind: "file" | "git-push" | "diff" | (string & {});
+    /** file: workspace-relative path; git-push: refspec tail or command. */
     ref: string;
     summary?: string;
+    /** ts of the last successful contributing call. */
     createdAt: string;
+    /** file kind only — HUNK-LEVEL line stats derived from logged call args (NOT a git diff; upgrades to the
+     *  reserved `diff` kind when a real patch store lands). the pinned wire contract. */
     additions?: number;
     deletions?: number;
     [k: string]: unknown;
 }
+/** The `suspended` event's gate payload (core checkpoint-store). Tool args / question text
+ *  are NOT here — join the same task's trace tool-call block via approvals' toolCallId.
+ *
+ *  OPEN DISCRIMINATED SET (design/80 D-0) — mirrors core `src/core/checkpoint-store.ts` CheckpointGate.
+ *  Consumers MUST branch on `kind` and render an unknown `kind` generically (never crash): core can mint a
+ *  kind this wire predates, and a contract test pins core→wire parity so a new core arm fails CI, not prod. */
 export interface CheckpointGate {
+    /** OPEN SET — branch on this, render an UNKNOWN kind generically (interface, not a closed union, so a new
+     *  core kind doesn't break narrowing — same idiom as `Artifact.kind`). Known kinds:
+     *  - `human`          — plain HITL approval (budget-auto-approvable). has `reason`, `toolName`.
+     *  - `irreversible_ask` — design/37 irreversibility / design/70 egress safety-tighten; NOT budgetable
+     *                         (load-bearing safety gate). has `reason`, `toolName`.
+     *  - `resource_limit` — design/74 cost/token/time slice boundary; resolve `{decision:"continue"}`. has `reason`.
+     *  - `needs_review`   — design/76 dry-run/shadow → durable `needs_review` TERMINAL (POST-prediction review,
+     *                       disjoint from the approval family). has `reason`.
+     *  - `task_done`      — design/38 Path A background sub-task handle (door B never sees it). */
     kind: "human" | "irreversible_ask" | "resource_limit" | "needs_review" | "task_done" | (string & {});
+    /** Present on human / irreversible_ask / resource_limit / needs_review (not task_done). */
     reason?: string;
+    /** Present on human / irreversible_ask. */
     toolName?: string;
     [k: string]: unknown;
 }
+/** The prompt-assembly manifest (server ≥1.219 — core `prompt.assembled` trace contract verbatim,
+ *  service budget.ts `promptManifestRecordOf` 实拆): constitution ownership + per-section digests +
+ *  the tool contract summary. Carries ONLY ids/digests/counts — NEVER prompt bodies (privacy boundary);
+ *  hashes are process-salted (NOT comparable across worker restarts — UI must not diff them cross-process).
+ *  v1 face = constitution/blocks/totalChars; `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 (server runs.ts flushPromptManifest). */
 export interface PromptManifest {
+    /** Who owned the constitution layer: "core" is the steady state; anything else is worth eyes. */
     constitution: "core" | "replaced" | "provider-assembled" | "legacy" | (string & {});
     blocks: Array<{
         id: string;
@@ -362,14 +722,21 @@ export interface PromptManifest {
     totalChars: number;
     [k: string]: unknown;
 }
+/** A session's prompt-epoch pin (server ≥1.220 `GET /v1/sessions/:id` additive `promptEpoch`; core
+ *  `session.getPromptEpoch()` contract verbatim, service audit.ts 实拆). Absent key = a pre-epoch
+ *  session (never null). `activatedBy: "legacy_migration"` = the one-time re-pin after an engine
+ *  upgrade (normal, not an anomaly). */
 export interface PromptEpoch {
     epoch: number;
+    /** `sha256:<64 hex>` — core's normalize gate rejects anything else (a bad pin reads as absent). */
     artifactDigest: string;
     packId: string;
     assemblyApi: number;
     activatedBy: "session_start" | "compaction" | "legacy_migration" | (string & {});
     [k: string]: unknown;
 }
+/** A trace turn (GET /v1/tasks/:id/turns items — true shape). role currently only
+ *  "assistant" (user/system/tool reserved). */
 export interface TraceTurn {
     seq: number;
     ts: string;
@@ -383,6 +750,14 @@ export interface TraceTurn {
     };
     [k: string]: unknown;
 }
+/** Open set — render unknown types generically, never crash.
+ *
+ *  design/99 §E1/§E2 (SHIPPED, service `TraceBlock`/`projectEvents` project.ts:69-73,160-165): the action-card
+ *  BODY now rides the trace. `tool-result.output` (+ `truncated`) is the model-facing result content — UNTRUSTED
+ *  RAW, but the service has already `redactDeep`'d + SIZE-bounded it at append (the old "ALWAYS absent" gap is
+ *  CLOSED). NON-UNIFORM (string | (TextContent|ImageContent)[]; truncated ⇒ a single string); absent ⇒ no body.
+ *  Both `tool-call` and `tool-result` also carry the §E2 identity (`eventId` = dedup/resume handle;
+ *  `parentToolCallId` = sub-agent attribution), additive / tolerate-absent. */
 export type TraceBlock = {
     type: "thinking";
     text: string;
@@ -404,27 +779,66 @@ export type TraceBlock = {
     truncated?: boolean;
     eventId?: string;
     parentToolCallId?: string;
-} | ({
+}
+/** server ≥1.219 ([998]②/[1005]①b): the assembly manifest rendered at the TOP of the turn it prepared
+ *  (web's "Prompt 组成" card source; service project.ts projectEvents `prompt_assembled` 实拆). */
+ | ({
     type: "prompt-assembled";
 } & PromptManifest) | {
     type: string;
     [k: string]: unknown;
 };
+/** A trace-relay SSE event (`GET /v1/tasks/:id/stream` — the workspace LIVE timeline, `streamTaskTrace` +
+ *  `mapTraceEvent`, server.ts). This is a DISTINCT vocabulary from `AgentEvent` (do NOT confuse with
+ *  `runs.events`): the durable log is BLOCK-grained, so each frame is a "delta" the client appends. Resumable
+ *  (each `id:` = the durable `task_event.seq`); on a window eviction the server returns 416 → resync via
+ *  `trace.turns` then resume from `retainedFrom`.
+ *
+ *  OPEN set — branch on `event`, render an unknown one generically (never crash). Known frames (mapTraceEvent):
+ *   - `meta`                  — FIRST frame: `{ version, mode, resumeFrom }` (stream contract, NOT id-stamped).
+ *   - `block-thinking-delta`  — `{ seq, text }` collapsible thinking append.
+ *   - `block-content-delta`   — `{ seq, text }` answer text append.
+ *   - `tool-call`             — `{ seq, id, name, input, eventId?, parentToolCallId? }` an action started (§E2 identity additive).
+ *   - `tool-result`           — `{ seq, callId, isError, output?, truncated?, eventId?, parentToolCallId? }` an action closed.
+ *                               §E1 (SHIPPED, mapTraceEvent project.ts:248-250): `output`/`truncated` = the model-facing
+ *                               BODY (redacted+bounded at append; absent ⇒ no body). The old "output absent" gap is CLOSED.
+ *   - `prompt-assembled`      — `{ seq, ...PromptManifest }` (server ≥1.219): the prepare's assembly manifest
+ *                               (constitution/blocks/sections?/tools?/totalChars — mapTraceEvent passthrough,
+ *                               whitelisted at append). MULTIPLE per task on cascade/verify runs.
+ *   - `turn`                  — `{ seq, tokens? }` a turn boundary (+ usage if present).
+ *   - `done`                  — `{ seq, suspended? }` terminal (suspended:true = paused on HITL, NOT completed).
+ *   - `error`                 — `{ code, message }` terminal failure / `WORKER_DOWN` (stalled) / `STREAM_MAX_DURATION`.
+ *   - `heartbeat`             — `{}` keep-alive (the SDK reader swallows these; not yielded). */
 export interface TraceStreamEvent {
+    /** SSE event name (open set; dispatch on this). */
     event: "meta" | "block-thinking-delta" | "block-content-delta" | "tool-call" | "tool-result" | "prompt-assembled" | "turn" | "done" | "error" | (string & {});
+    /** The durable seq (`id:` line) when the frame carries one — feed it back as Last-Event-ID to resume. `meta`
+     *  and `heartbeat` carry none. */
     id?: string;
+    /** The frame's JSON `data:` payload (shape varies by `event`; permissive — read known fields, tolerate the rest). */
     data: Record<string, unknown>;
 }
+/** A workflow-run SSE event (`GET /v1/workflows/:id/stream` — S8 self-orchestration LIVE progress,
+ *  `streamWorkflowRun` + core `subscribeWorkflow`, server.ts). NOT resumable (replica-local, in-process;
+ *  no `id:`/Last-Event-ID — a drop is a full restart, NOT a resume). FIRST frame is `meta` `{ version, runId }`;
+ *  subsequent frames carry the core `WorkflowEvent` (its `type` becomes the SSE event name). OPEN set — branch on
+ *  `event`, the `data` shape is core-internal and may evolve (read known fields, tolerate the rest). */
 export interface WorkflowStreamEvent {
+    /** SSE event name = `meta` for the opener, else the core WorkflowEvent `type` (open set). */
     event: "meta" | "error" | (string & {});
+    /** The frame's JSON `data:` payload (core `WorkflowEvent` shape; permissive). */
     data: Record<string, unknown>;
 }
+/** A per-request skill (passed as an object, not loaded from disk) — core-native TaskSpec.skills shape. */
 export interface SkillSpec {
     name: string;
     description: string;
     content: string;
 }
+/** A per-request MCP server (CC `.mcp.json` parity) — core-native `McpServerSpec` shape (core types.ts:277).
+ *  `stdio` = a local command the worker spawns (single-user only); `http` = a remote streamable-HTTP server. */
 export interface McpServerSpec {
+    /** Stable name; the server's tools are namespaced `<name>__<tool>`. */
     name: string;
     transport: {
         kind: "stdio";
@@ -434,59 +848,123 @@ export interface McpServerSpec {
     } | {
         kind: "http";
         url: string;
+        /** Static headers sent on every request (e.g. an auth bearer for the MCP server itself). */
         headers?: Record<string, string>;
+        /** Header name into which the Runner-held principal is injected (model/worker can't read/set it). */
         principalHeader?: string;
     };
+    /** Optional allowlist of tool names to expose (others dropped). */
     allowTools?: string[];
+    /** Opt in to INBOUND elicitation for this server (server may ask the END USER mid-tool-call). Default OFF. */
     elicitation?: boolean;
+    /** Caller-side per-tool safety-axis overrides, keyed by the server's remote (un-namespaced) tool name. */
     toolAxes?: Record<string, {
         effect?: "read" | "write";
         egress?: boolean;
         irreversibility?: "always" | "never";
     }>;
 }
+/** The user's `<user_memory>` (GET /v1/memory) — owner-scoped by construction (scope derived from the
+ *  request principal; cannot address others' memory). content null = empty. the pinned wire contract. */
 export interface MemoryRecord {
     scope: string;
     content: string | null;
 }
+/** MF-30 memory WRITE ack —— append/edit/remove **统一形** `{ ok, id, scope }`(service `@sema-agent/server@1.3.0`,
+ *  实际 handler append=2917 / patch=2926 / delete=2933 全返此形;locked 测试断言 append 含 `ok`)。
+ *  🔴 service 订正:旧源**摘要注释** server.ts:2880 误写 append 漏 `ok`,**实际代码一直含 `ok`** —— 代码为准,三 verb 统一。
+ *  🔴 **memory 是 per-PRINCIPAL,不是 per-session** —— path 的 `:id`(session)只是 shell 的**寻址上下文**(`/memory`
+ *  命令在某 session 里跑),**非 per-session 分区**;为某 principal append 的 note,该 principal **所有 session 都读得到**。
+ *  note **VERBATIM 存(≤8 KiB,用户授权内容、不 redact)**;空/超长/缺字段 → 400 fail-loud。edit/remove 需 store 的
+ *  id-addressable update/delete,后端缺 → **501**(honest degrade,绝非假 200);append 永远可用(memoryWrite=true 时)。 */
 export interface MemoryWriteAck {
     ok: boolean;
     id: string;
     scope: string;
 }
+/** Worker capability map (`GET /v1/capabilities`). Open set — ignore unknown keys. Booleans
+ *  share deps with the route gates ("says yes but 501s" is structurally impossible, producer-tested). */
 export interface Capabilities {
     asyncRuns?: boolean;
     artifacts?: boolean;
     approvals?: boolean;
     leader?: boolean;
+    /** 🔴 K-2(core SHIPPED 1.155.0;service `/v1/capabilities` 暴 `workflows: Boolean(deps.workflowRunStore)`,
+     *  server.ts:930)—— worker 支持工作流编排(`/workflows` 可观测 + workflow 提交)。false/缺 ⇒ shell 隐藏 `/workflows`
+     *  面板,别 trial-by-501。注:per-principal `allowWorkflows`(center runtimeCaps,core 1.157.0)是更细的**授权**轴,
+     *  与本 worker 能力位正交。 */
     workflows?: boolean;
+    /** 🔴 E18 rewind gate(service server.ts:911 `Boolean(resumeAnchorStore && sessionStorage.getLeafId)`)—— `TaskRequest.resumeAt`
+     *  能否 resolve。false/缺 ⇒ shell 隐藏「rewind 到某条消息」入口,别 trial-by-4xx。本/云均可(anchor store 各后端都在),
+     *  仅 env-only/无后端 worker false。 */
     resumeAt?: boolean;
+    /** 🔴 E19 rewind-files gate(service server.ts:921 `Boolean(fileSnapshotStore)`)—— `TaskRequest.rewindFiles` 能否生效
+     *  (分叉时同步回退工作树)。false/缺 ⇒ rewind 仅回退对话、文件留最新态(shell 该把「连同文件回退」选项灰掉)。 */
     rewindFiles?: boolean;
+    /** 🔴 K-1c 手动 compact gate(service server.ts:~932 `Boolean(runStore)`,POST /v1/runs/:id/compact → core 1.156
+     *  `TaskStream.compact()`)—— 手动 `/compact` 命令是否可发。配 `compacted` 事件的 `trigger:"manual"`。false/缺 ⇒ 灰掉
+     *  `/compact`(非 live run 409、无 store 501)。 */
     manualCompact?: boolean;
     version: string;
     scenarios?: string[];
+    /** false ⇒ stats.costMicroUsd=0 may mean "no MODEL_COST_* configured", not "free". Worker-level. */
     pricingConfigured?: boolean;
+    /** Memory transparency endpoints available (GET/DELETE /v1/memory). the pinned wire contract. */
     memory?: boolean;
+    /** MF-30 — memory WRITE available (`deps.memory?.append`;server.ts:828)。true ⇒ `memory.append/edit/remove` 可用,
+     *  UI 显写入入口。append 永远可用(memoryWrite=true 时);edit/remove 后端缺 id-addressable 时各自 501。 */
     memoryWrite?: boolean;
+    /** 2c session-sync (P1d) — the `/v1/sessions/:id/sync/*` peer routes resolve (durable backend + entry-export seam
+     *  + a file-snapshot store all wired; server.ts:850). Gate the whole `client.sessions.sync.*` surface off this —
+     *  DON'T trial-by-501. False ⇒ the routes 501 (no durable session store). */
     sessionSync?: boolean;
+    /** 🔴 K-5 session-resume gates(service server.ts:894/836/+,§0.5 session 抽象)—— shell 的 `/resume` picker 据此诚实
+     *  gate,别 trial-by-501:`sessionList` = list 可用(`Boolean(sessionStorage.listSessions ?? runStore.listSessions)`,
+     *  喂 picker 行);`sessions` = transcript preview 可用(`Boolean(sessionAudit)`,`GET /v1/sessions/:id`→SessionAudit)。
+     *  `sessionFork`(E17,`sessionStorage.fork`)/`sessionDelete`(E21,`purgeSession`)是 fork/删的 producing-path gate。
+     *  各 false ⇒ 对应路由 501(「says yes ⟺ route works」)。 */
     sessions?: boolean;
     sessionList?: boolean;
+    /** K-5 session-search — same producing gate as `sessionList` (server.js:610 — the picker's search leg). */
     sessionSearch?: boolean;
     sessionFork?: boolean;
     sessionDelete?: boolean;
+    /** /v1/usage 成本面可用(server.js:588 `Boolean(costQuota)`)。 */
     usage?: boolean;
+    /** /v1/policy 面(server.js:587 硬编码 true)。 */
     policy?: boolean;
+    /** 会话内改 permission mode 的写面 —— server 1.214 恒 false(server.js:589,未上线;mode 走 TaskRequest.permissionMode)。 */
     permissionModeWrite?: boolean;
+    /** per-turn `model` 字段可用(server.js:590 硬编码 true;TaskRequest.model → CC /model parity)。 */
     modelSelection?: boolean;
+    /** per-turn `reasoningEffort` 可用(server.js:591 硬编码 true;CC /effort parity)。 */
     effortSelection?: boolean;
+    /** tool_end 带完整 toolOutput(server.js:592 硬编码 true)。 */
     toolOutput?: boolean;
+    /** 事件带 message identity(eventId/messageId 族;server.js:593 硬编码 true)。 */
     messageIdentity?: boolean;
+    /** 子代理内容事件前向转发(parentToolCallId stamped;server.js:594 硬编码 true)。 */
     forwardSubagentEvents?: boolean;
+    /** C2 子代理 steer 面(server.js:595 `Boolean(subagentSteerRegistry && runStore)`;POST /v1/runs/:id/subagents/:t/steer)。 */
     subagentSteer?: boolean;
+    /** 子代理 resume/复活面(server.js:596 同 subagentSteer 双 dep;POST …/subagents/:t/resume,还需 run 侧 retainSubagentSessions)。 */
     subagentResume?: boolean;
+    /** server 1.244 [1488]③(b):后台子代(a… 句柄,background_agent ONLY;wa… 观测行走 workflow journal)终报读面
+     *  —— GET /v1/runs/:id/subagents/:handle/output(引擎 TaskRegistry 的 TaskOutput 工具投影过 HTTP;
+     *  bg 子代永不在 run store)。副本本地,同 steer。 */
     subagentOutput?: boolean;
+    /** server 1.251(S2,core 1.370 bgAgentId):per-agent live tail —— GET /v1/runs/:id/subagents/:handle/stream
+     *  (SSE:meta/forward/heartbeat;replay+tail 的 tail 半场,replay=subagentOutput 面)。live 帧
+     *  replica-local(帧只在宿主 run 所在副本产生;meta 帧如实声明)。同门同寻址同 404 形,session-enforced。 */
     subagentStream?: boolean;
+    /** server 1.246 [1499]:泛后台任务句柄双 verb(CC TaskOutput/TaskStop 人侧对位)——
+     *  GET/POST /v1/runs/:id/tasks/:handle/{output,stop}:background_bash(stdout;是否消费游标取决于句柄形态,
+     *  spooled 全量可重读/cursor-only 增量,投影 flags 权威)/monitor(批)/background_agent(终报);workflow
+     *  句柄 404(读走 journal 面;wire 上无 workflow 停止面)。出生即 session-enforced(session-bound run 必带
+     *  匹配 ?session=)。副本本地,同 subagentOutput。 */
     taskHandles?: boolean;
+    /** TaskRequest.settings 各分片是否 honored(server.js:597 —— 唯一对象形能力位;`env` 恒 false,
+     *  `hooks` 单用户部署(requirePrincipal!==true)才 true)。 */
     taskSettings?: {
         permissions?: boolean;
         permissionMode?: boolean;
@@ -496,31 +974,69 @@ export interface Capabilities {
         hooks?: boolean;
         [k: string]: unknown;
     };
+    /** server ≥1.243 ([1478] R2): TaskRequest.appendSystemPrompt accepted top-level → core TaskSpec.appendSystemPrompt.
+     *  false/absent ⇒ fall back to the `settings.outputStyle` ride-along (older servers fold it into the same field). */
     appendSystemPrompt?: boolean;
+    /** server ≥1.243 ([1479]①): TaskRequest.compactionModel accepted (catalog-gated cheap compaction gear).
+     *  false/absent ⇒ older server drops the field — don't offer the picker. */
     compactionModel?: boolean;
+    /** [876]③ TaskRequest.agents per-task 子代理定义 honored(server.js:598 `requirePrincipal !== true` —— 单用户部署才收)。 */
     taskAgents?: boolean;
+    /** TaskRequest.retainBackgroundProcesses honored(server.js:599 单用户部署才收)。 */
     retainBackgroundProcesses?: boolean;
+    /** server ≥1.221 (core 1.314 工具面控制批,[1052]②): roster TRUE-UNMOUNT list — the named wire tools'
+     *  schemas never reach the model (the deny gate saves no tokens; this does), and the assembly manifest
+     *  narrows honestly. Tighten-only: core's inheritance invariant unions it into EVERY child spawn path.
+     *  Malformed (non-array / empty-string items) → 400 fail-loud at submit. */
     excludeTools?: string[];
+    /** server ≥1.221 (core 1.314): DEFERRED DISCLOSURE list — the named MOUNTED tools (built-ins included)
+     *  ride the wire as a placeholder (schema bytes out of the cache prefix) and materialize via ToolSearch
+     *  on demand. The carrier for the shell's "Workflow on by default but not exposed" posture. Same
+     *  validation/inheritance posture as {@link excludeTools}. */
     deferTools?: string[];
+    /** TaskRequest.interactiveTools 认词(server.js:600 硬编码 true;-p 无人值守语义探测位 —— 见 TaskRequest 注)。 */
     interactiveTools?: boolean;
+    /** TaskRequest.cwd honored(server.js:601 `cwdHonored`:local 单用户 host-adapter 才 true;多租户 fail-closed)。 */
     projectContext?: boolean;
+    /** TaskRequest.mcpServers honored(server.js:602 `mcpInjectionHonored`:单用户才 true,多租户 ignore)。 */
     mcpInjection?: boolean;
+    /** GET /v1/runs/:id/model-usage 面(server.js:603 `Boolean(runStore && modelUsage)`)。 */
     modelUsage?: boolean;
+    /** session_init 首帧(CC parity;server.js:604 硬编码 true)。 */
     sessionInit?: boolean;
+    /** MCP 面总位(/v1/mcp status 等;server.js:605 硬编码 true)。 */
     mcp?: boolean;
+    /** §E23 inbound-MCP elicitation HITL(server.js:606 `Boolean(elicitation)` = MCP_ELICITATION_ENABLED)。 */
     mcpElicitation?: boolean;
+    /** §4④ live AskUserQuestion HITL(server.js:607 `Boolean(question)` = ASK_QUESTION_ENABLED)。 */
     askUserQuestion?: boolean;
+    /** [830]① live tool-approval HITL(server.js:608 `Boolean(toolApproval)` = TOOL_APPROVAL_ENABLED;
+     *  gate `client.toolApprovals` 整面,别 trial-by-501)。 */
     toolApproval?: boolean;
+    /** E12 suggestNextPrompts 认词(server.js:614 硬编码 true)。 */
     promptSuggestions?: boolean;
+    /** PUT /v1/sessions/:id/policy 面(server.js:615 `Boolean(sessionPolicyStore)`)。 */
     sessionPolicy?: boolean;
+    /** E18 code-only rewind(TaskRequest.rewindFilesTo;server.js:617 `Boolean(fileSnapshotStore && resumeAnchorStore && getLeafId)`)。 */
     rewindFilesTo?: boolean;
+    /** assistant-scheduler 面(server.js:618 `schedulerEnabled && requirePrincipal!==true && remoteExec==="host"` 三与)。 */
     scheduler?: boolean;
+    /** SendUserFile 工具面(server.js:620 `Boolean(sendUserFile && publicEndpoint)`)。 */
     sendUserFile?: boolean;
+    /** SendUserFile 的 S3 公网端点(server.js:621 —— 唯一 string|null 位;null = 未配)。 */
     s3PublicEndpoint?: string | null;
+    /** GET /v1/files/sent 台账面(server.js:622 `Boolean(sendFileLedger)`)。 */
     sendUserFileLedger?: boolean;
+    /** GET /v1/workflows 列表面(server.js:624 `Boolean(workflowRunStore)`;`workflows` 总位见上)。 */
     workflowsList?: boolean;
     [k: string]: unknown;
 }
+/** One scenario's detail card (`GET /v1/capabilities/scenarios/:name` — server 1.214 server.js:567-576 handler,
+ *  shape = capabilities/scenarios.d.ts `ScenarioDetail` verbatim; the LIST of names rides `capabilities.scenarios`).
+ *  `source`/`builtin` = builtin vs center-config overlay; `toolset` names the tool bundle, `tools` the resolved
+ *  tool names; `promptSummary` is a human-readable prompt digest (NOT the full prompt); `enabled` = a center
+ *  scenario can be declared-but-disabled. UNKNOWN name → 404 `{error:{code:"scenario_not_found"}}` (note the
+ *  OBJECT-shaped error body — unique to this route). */
 export interface ScenarioDetail {
     name: string;
     source: "builtin" | "center";
@@ -532,17 +1048,49 @@ export interface ScenarioDetail {
     enabled: boolean;
     [k: string]: unknown;
 }
+/** A pending HITL checkpoint — the RICH `/v1/approvals` operator-queue row (true shape;
+ *  ASSISTANT-WIRE-CONTRACT §7(b), service main 1fafeec / core 1.110.0). ⚠️ createdAt/deadline are EPOCH MS.
+ *
+ *  🔴 §7 钉死两形状不可混 —— 本类型是 **(b) 富 /v1/approvals 行**（`GET /v1/approvals` + `/stream` 用,
+ *  decide-ready operator queue）,**不是** (a) inbox/tasks 的标量 `CheckpointSummary`（见下文 CheckpointSummary）。
+ *  与标量形状的精确差（§7b/§4a):
+ *    - severity 嵌在 **`riskDescriptor.severity`** 内 —— 富行**无顶层 severity 标量**;
+ *    - 富行**无 `gateKind`**（消费方要类别时回退 `toolName`/`riskDescriptor.toolName`）;
+ *    - 富行**无 `token`**（§1:resume capability token 是永不上线的 secret,server 自按 sessionId 解析）;
+ *    - **无 `checkpointToken`**（§4a:server-INTERNAL,NOT surfaced 在 /v1/approvals 记录上;合规 client 只回传
+ *      boundCallId+boundInputHash 两件套,可选 checkpointToken→409 approval_stale 是 deprecated legacy 路径）。
+ *  这是 boundCallId/boundInputHash decide 绑定的唯一 surface 处。契约说"可选字段缺则 OMIT 不是 null"。 */
 export interface PendingCheckpoint {
+    /** The decide handle: POST /v1/approvals/:sessionId/decide. */
     sessionId: string;
+    /** Principal / 多租户 owner scope; "_" = submitted without one. */
     scope: string;
+    /** The suspended run holding the session claim — the JOIN KEY to the task's trace
+     *  tool-call block (block.id == toolCallId → input = full args/question payload) and the context link. */
     taskId?: string | null;
+    /** Tool awaiting approval (AskUserQuestion = the question gate)。富行无 gateKind → 类别从 toolName 推。 */
     toolName?: string | null;
     toolCallId?: string | null;
+    /** design/80 D-1 — the TWO binding values the human implicitly approves; the consumer reads them here and
+     *  echoes them VERBATIM into `decide` (TOCTOU guard: "I'm approving THIS pending action, not one swapped in").
+     *  Absent on checkpoints minted before D-1 → omit from decide (server falls back to the legacy resolve).
+     *  = `toolCallId` of the action the human saw (the bound call). */
     boundCallId?: string;
+    /** SERVER-MINTED OPAQUE sha256 over the pending action's args at mint time. Echo VERBATIM; NEVER recompute
+     *  (no canonical-JSON on the client — a false mismatch would fail-close a legitimate approval). It binds the
+     *  input the human SAW, NOT any `updatedInput` (which is applied AFTER binding, design/37 last-wins). */
     boundInputHash?: string;
+    /** The pending tool call's args (post-hook), REDACTED + size-bounded by the producer:
+     *  for a tool gate the write payload, for an AskUserQuestion the question itself. Lets an approval card
+     *  render WITHOUT an N+1 `trace.turns` fetch per item. Oversized → `{ truncated, bytes }`. NEVER a
+     *  capability token. `null`/absent = checkpoint suspended before this field existed → fall back to the
+     *  trace join (block.id == toolCallId). */
     input?: unknown;
     createdAt: number;
+    /** epoch ms; expired checkpoints are reaped. */
     deadline?: number | null;
+    /** §7(b) — 富行的**完整 RiskDescriptor 对象**;**severity 在此处**（无顶层 severity 标量）。
+     *  axes/toolName/summary/touchedPaths 是引擎内部投影出的风险画像。缺则 OMIT(早期 checkpoint 可能无)。 */
     riskDescriptor?: {
         severity?: 1 | 2 | 3 | 4 | 5;
         axes?: Record<string, unknown>;
@@ -552,10 +1100,17 @@ export interface PendingCheckpoint {
     };
     [k: string]: unknown;
 }
+/** Session audit (`GET /v1/sessions/:id`) — true shape. `messages` = CURRENT model context
+ *  (older history folded into a summary message); can be LARGE — lazy-expand in UIs.
+ *  With window params (server ≥1.162 four-face, board [611]) the response additionally carries
+ *  `window` — ABSENT on an old engine (<1.162 strips the query before routing and returns the
+ *  full record): probe "no `window` in the response" to degrade honestly, never error. */
 export interface SessionRecord {
     sessionId: string;
     owner?: string | null;
+    /** ISO timestamp (unlike approvals' epoch-ms). */
     createdAt: string;
+    /** Compaction window floor; null = never compacted. */
     floorEntryId?: string | null;
     thinkingLevel?: string;
     model?: {
@@ -563,15 +1118,24 @@ export interface SessionRecord {
         modelId: string;
     } | null;
     messages: unknown[];
+    /** Present ONLY on a windowed read (`tail`/`before`) against server ≥1.162. */
     window?: SessionWindow;
+    /** server ≥1.220 ([1023]①): the session's prompt-epoch pin (additive; absent = pre-epoch session
+     *  OR an older engine — never null). The typed entry is NOT an LLM message, so it never appears
+     *  in `messages`. */
     promptEpoch?: PromptEpoch;
     [k: string]: unknown;
 }
+/** The `window` companion of a windowed session read: `messages` is the slice
+ *  `[offset, offset+messages.length)` of `total`. `offset` is stable within one `floorEntryId`
+ *  generation — compaction swaps the generation (floorEntryId changes) ⇒ re-pull from scratch. */
 export interface SessionWindow {
     offset: number;
     total: number;
     [k: string]: unknown;
 }
+/** `GET /v1/sessions/:id?message=<index>` — the single-message expand leg (server ≥1.162).
+ *  Out-of-range index → 404 (typed NotFoundError; wire body carries `total`). */
 export interface SessionMessageEnvelope {
     sessionId: string;
     floorEntryId?: string | null;
@@ -579,31 +1143,63 @@ export interface SessionMessageEnvelope {
     message: unknown;
     [k: string]: unknown;
 }
+/** E16（shell-host sessionPicker;service `SessionSummary` plugins/tidb-run-store.ts:42,SHIPPED `6cbf61e`）—
+ *  `GET /v1/sessions` 列表行 = keyset 聚合一个 session 的 run 账本（**不是** TaskSummary 的单 run 行）。owner-scoped
+ *  （service 据 principal 自算；non-owner 不出现）。门B/CLI 的「会话/对话历史」picker 据此渲染（last activity + 最近
+ *  objective 预览 + 最近状态）。`objectivePreview` 已 service 侧脱敏 + 截断,真回 `null`（无 run 时）故保 `| null`。
+ *  所有时间 ISO 串。permissive 开集容未来字段。 */
 export interface SessionSummary {
     sessionId: string;
+    /** 租户/owner（ownerless session = null）。 */
     owner: string | null;
+    /** 最近一个 run 的创建时间（keyset 排序键）。 */
     lastActivityAt: string;
+    /** 该 session 第一个 run 的创建时间。 */
     firstActivityAt: string;
+    /** 该 session 下的 run 数。 */
     runCount: number;
+    /** 最近 run 的 objective 预览（service 脱敏 + 截断；无 run → null）。 */
     objectivePreview: string | null;
+    /** 最近 run 的状态（"completed"/"running"/... 开放串）。 */
     lastStatus: string;
+    /** 🔴 K-5c(service SHIPPED 全后端:security.ts:19 + tidb/pg/file/memory/local-session-store)—— 最近 run 的 taskId,
+     *  = **一跳 live-tail re-attach 锚**:picker 选中会话 → 直接 `GET /v1/runs/:lastRunId/events?from=seq` 续 live 尾,
+     *  免二次查。无 run → null(空会话)。running/suspended run 也会冒出来(noteTaskRun seam),故选中即可续在跑的尾。 */
     lastRunId: string | null;
     [k: string]: unknown;
 }
+/** `GET /v1/sessions` 的分页信封（service handleSessionList,keyset）。`nextCursor` 缺 = 末页。 */
 export interface SessionListPage {
     sessions: SessionSummary[];
+    /** 不透明 keyset 游标;原样回送 `?cursor=` 取下一页（绝不 parse）。缺 = 没有更多。 */
     nextCursor?: string;
 }
+/** E6（shell-host permissionMode;core `SessionPermissionRules` session-policy-store.ts:23,service `GET/PUT
+ *  /v1/sessions/:id/policy`,SHIPPED）—— operator 收紧的 per-session 工具权限规则（core 在 prepare-time SUBTRACT-only
+ *  读它）。5 个开放可选 string[] 字段;读写均经 {@link StoredSessionRules}（带 `rev` OCC 键）。🔴 **tighten-only 不变式**
+ *  core 强制：普通（非 operator）写只能收紧（删 deny / 不能放宽 allowlist/allowDirs）→ 放宽 403 `loosen_forbidden`;
+ *  CAS `expectedRev` 不符 → 409 `conflict`;ownerless session → 409;non-owner → 404（无 existence oracle）。 */
 export interface SessionPermissionRules {
+    /** 设了 = 仅这些工具名放行（白名单收紧）。 */
     toolAllow?: string[];
+    /** 总禁的工具名（deny wins）。 */
     toolDeny?: string[];
+    /** 设了 = 写工具（Q6/core 1.161 起 CC 名 `Write`/`Edit`）仅可写这些目录内;不能路径约束的写工具（如 `Bash`）在它设了时被禁。RAW 存,run 时解析。 */
     allowDirs?: string[];
+    /** 设了 = 仅这些 bash 命令名（argv[0]）放行。 */
     commandAllow?: string[];
+    /** 总禁的 bash 命令名（argv[0]）。 */
     commandDeny?: string[];
 }
+/** {@link SessionPermissionRules} + store 盖的单调 `rev`（OCC 键）。GET/PUT 的 `{rules}` 信封里就是这个。
+ *  PUT 回送 `rev` 作下次 `expectedRev`（CAS）。 */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
 }
+/** E9（shell-host mcpStatus;core `McpServerStatus` core/mcp.ts:76,service `GET /v1/sessions/:id/mcp`,SHIPPED
+ *  core 1.124）—— 单 MCP server 的状态。🔴 core 不持久化 MCP 连接（task-scoped）→ 无「存的 session MCP 健康」；service
+ *  **按需 materialize**（fresh connect→list→dispose,fail-open）→ 这是 **materialization-time** 状态,非 live session
+ *  健康（壳渲「as of <asOf>」）。`status` 仅 connected/failed（core 不发 disabled）。`error` service 已脱敏 + 限 200 字符。 */
 export interface McpServerStatus {
     name: string;
     status: "connected" | "failed" | (string & {});
@@ -612,50 +1208,87 @@ export interface McpServerStatus {
         version: string;
     };
     toolNames?: string[];
+    /** 仅 failed 时;service redact + slice(200)。 */
     error?: string;
     [k: string]: unknown;
 }
+/** `GET /v1/sessions/:id/mcp` 的信封（service server.ts:2640-2672）。`asOf` = THIS materialize 时刻（ISO）；
+ *  `degraded:true` = materialize 超时/失败 → `servers` 空但非「无 MCP」（壳显「状态暂不可得」）。无 MCP 配置 → `servers:[]`。 */
 export interface McpStatusPanel {
     asOf: string;
     servers: McpServerStatus[];
+    /** materialize 超时/失败的降级标记（servers 空且 degraded 时 = 取不到,非「没有」）。 */
     degraded?: boolean;
     [k: string]: unknown;
 }
+/** ONE session-tree entry as it crosses the sync wire — the SDK treats it as an OPAQUE payload (verbatim,
+ *  cross-backend stable ids/parents). It is core's `SessionTreeEntry`; the SDK only ever reads `.id` (for the
+ *  §7 id-set classify) and otherwise pipes it through untouched (the cloud re-validates the whole tree). */
 export interface SyncEntry {
+    /** Stable entry id, unique within a session (verbatim across backends — the §7 divergence key). */
     id: string;
+    /** Parent entry id, or null for a root. */
     parentId?: string | null;
+    /** Entry discriminator (message / leaf / compaction / …) — opaque to the SDK. */
     type?: string;
     [k: string]: unknown;
 }
+/** A (principal, rules) record — one row of a session's policy across ALL principals (E6 `listBySession`).
+ *  Replayed verbatim on import (the cloud applies the E6 tighten-only gate). `principal` absent = the
+ *  session-default rules. */
 export interface SessionRulesRecord {
     principal?: string;
     rules: StoredSessionRules;
 }
+/** One E19 file snapshot keyed by a `SessionTreeEntry.id` — `manifest` = `[relPath, blobHash]` tuples. The blob
+ *  BYTES are NOT inlined (a turn's working tree can be tens of MiB → OOM/413); they ride the content-addressed
+ *  blob routes (GET …/snapshots/:key/blobs/:hash to pull, PUT …/blobs/:hash to push). */
 export interface SyncSnapshot {
     key: string;
     manifest: Array<[string, string]>;
 }
+/** One E18 resume-at anchor (eventId→entryId + its source owner). `owner` is RE-KEYED to the importing principal
+ *  on a PUSH (§9) — the local peer sends what it has; the cloud overwrites it. */
 export interface SyncAnchor {
     eventId: string;
     entryId: string;
     owner: string | null;
 }
+/** `GET …/sync/manifest` → `{ manifest: SessionManifest }`. The THIN cross-backend snapshot: entry IDS (oldest-first,
+ *  NOT payloads — those stream via `/sync/entries`) + per-snapshot relPath→blobHash + policy + anchors + leaf. The
+ *  local peer feeds `entryIds` to {@link classifySyncRelationshipByIds} to decide fast-forward/fork BEFORE pulling
+ *  the entry stream + only the blob hashes it lacks. Mirrors session-sync.ts SessionManifest:213. */
 export interface SessionManifest {
     sessionId: string;
+    /** The full durable log's entry IDS, oldest-first (verbatim, cross-backend stable). NOT the payloads. */
     entryIds: string[];
+    /** `entryIds.length` — the count the paired `/sync/entries` NDJSON trailer must report. */
     entryCount: number;
+    /** The session's current leaf entry id, or null. */
     leafId: string | null;
     snapshots: SyncSnapshot[];
     policy: SessionRulesRecord[];
     anchors: SyncAnchor[];
 }
+/** The portable state of ONE session, ready to replay into another backend (mirrors session-sync.ts SessionBundle:193).
+ *  Blobs are deliberately NOT inlined — each snapshot carries only its `manifest`; the bytes stream through the
+ *  content-addressed blob routes. The SDK assembles this from a manifest + the streamed entries for a PUSH. */
 export interface SessionBundle {
     sessionId: string;
+    /** The FULL durable conversation log, verbatim ids/parents/payload (oldest-first). */
     entries: SyncEntry[];
     snapshots: SyncSnapshot[];
     policy: SessionRulesRecord[];
     anchors: SyncAnchor[];
 }
+/** §7 — how a SOURCE log relates to a DESTINATION log, decided over the entry-ID SETS (mirrors session-sync.ts
+ *  SyncRelation:95). A discriminated union the local peer reads to decide what a PUSH/PULL would do:
+ *   - `fresh`        — dst has no such session → an unconditional fresh import.
+ *   - `identical`    — the id sets are equal → a no-op.
+ *   - `fast_forward` — dst ⊊ src (src strictly ahead = clean append) → SAFE to apply; `newEntryIds` = the tail.
+ *   - `stale`        — src ⊊ dst (src strictly behind) → applying LOSES dst entries → a conflict (`dstAheadBy`).
+ *   - `fork`         — each side has ≥1 exclusive entry (true divergence) → a conflict; `commonAncestor` = the
+ *                      deepest shared id (null if none), `srcExclusive`/`dstExclusive` = each side's extra ids. */
 export type SyncRelation = {
     relation: "fresh";
 } | {
@@ -672,21 +1305,40 @@ export type SyncRelation = {
     srcExclusive: string[];
     dstExclusive: string[];
 };
+/** The two conflicting relations (`fork`/`stale`) the cloud refuses on a PUSH without `{resolution:"overwrite-dst"}`
+ *  — the payload of the 409 typed {@link import("./errors.js").SyncConflictError}. */
 export type SyncConflictRelation = Extract<SyncRelation, {
     relation: "fork" | "stale";
 }>;
+/** `POST …/sync/import` Phase-A result. A `fork`/`stale` without `overwrite-dst` → 409 (typed SyncConflictError),
+ *  never this. `identical` → `{ relation:"identical" }` with NO `stagingId` (the dst already holds the log; Phase B
+ *  is skipped). Anything that needs entries → `{ stagingId, relation }` (drive Phase B with the `stagingId`).
+ *  `relation` is the BARE classifier tag (server sends `relA.relation`, not the full object — server.ts:3037/2986). */
 export interface ImportStaged {
+    /** Present iff Phase B is needed (absent on `identical`). Feed it to `importEntries(...)`. */
     stagingId?: string;
+    /** The §7 relation tag classified at Phase A (`fresh` | `fast_forward` | `identical`). */
     relation: SyncRelation["relation"];
 }
+/** `POST …/sync/import/:stagingId/entries` (Phase B) commit result — `{ relation }` (the AUTHORITATIVE in-txn
+ *  re-classify tag; server.ts:3138). */
 export interface ImportCommitted {
     relation: SyncRelation["relation"];
 }
+/** Synchronous ack for `POST /v1/runs/:id/cancel` (LIVE, service ced3d88). `status` is
+ *  "cancelling" (accepted) or a terminal status (idempotent no-op). NOT a RunStatus member. The run then
+ *  settles to `failed` + `errorCode:"cancelled"`. */
 export interface CancelAck {
     taskId: string;
     status: string;
     note?: string;
 }
+/** Leader run (`POST /v1/leader`) — the **v2 leader pipeline** (E2B workers + git push), gated server-side
+ *  (`LEADER_ENABLED` + `REMOTE_EXEC=e2b`, both default OFF). Mode is a SERVER deploy flag, NOT a client choice:
+ *  `LEADER_FANOUT_ENABLED=true` (default) = router decides single-vs-decompose and CAN fan out to N workers
+ *  (= the value-HOLD correctness path); `=false` pins it to a deterministic single worker. ⚠️ This is NOT the
+ *  default door-B brain — **door B uses `/v1/tasks`+`/v1/runs`+`scenario`** (strong single, live today, no
+ *  E2B-leader machinery). Keep this resource as a clearly-labeled v2/optional path. See DIRECTION §1. */
 export interface LeaderReceipt {
     leaderRunId: string;
     status: "running" | "completed" | "failed";
@@ -697,52 +1349,108 @@ export interface LeaderRecord {
     result?: unknown;
     error?: string;
 }
+/** §1 CheckpointSummary —— core 对每个 PENDING checkpoint 的轻量投影（summarizeCheckpoint, 全 store 后端一致）。
+ *  inbox/总览 的共享行形状。可选字段缺则 OMIT 不是 null。🔴 只投影 severity 标量, **不带 riskDescriptor 对象**。 */
 export interface CheckpointSummary {
+    /** resume capability token（opaque; echo, 绝不 parse）。 */
     token: string;
+    /** 被暂停的 task/session id。 */
     sessionId: string;
+    /** 多租户 owner scope。 */
     scope: string;
+    /** 哪种暂停（6-arm 开集）。开放联合留 `(string & {})` 容未来新 arm。 */
     gateKind: "human" | "irreversible_ask" | "resource_limit" | "needs_review" | "plan_review" | "task_done" | (string & {});
+    /** MF-14 contentKind passthrough（@sema-agent/server 1.6.0 / core 1.150 checkpoint-store.d.ts:765）—— `needs_review`/
+     *  `suspended` gate 上 core 透传的内容类型;`"content_ask"` = 被 gate 的工具是 AskUserQuestion(让 shell 渲染问答式 UI
+     *  而非普通审批)。开放联合容未来新 kind。缺省 = 普通 gate。 */
     contentKind?: "content_ask" | (string & {});
+    /** 确定性风险层 = inbox 排序键。**仅 human/irreversible_ask 有**; 其余无 → 排序须容 undefined。 */
     severity?: 1 | 2 | 3 | 4 | 5;
+    /** suspend 链上累计花费（资源账本附着时出现）。 */
     spentMicroUsd?: number;
+    /** awaiting-human SLA deadline（epoch ms）。 */
     deadline?: number;
+    /** §assistant-scheduler 归因（core 1.114.0 source-tag 持久化 + summarizeCheckpoint 投影自动带；the pinned wire contract）。
+     *  echo-only triage 显示 —— **core 门控不读、跨副本持久化带着、跨后端 byte-identical**。单收件箱跨任务聚合时,
+     *  消费方据此显「这条 ask 属哪个任务/用户」。缺则 OMIT（旧 worker / 未持久化场景）。 */
+    /** 发起此 ask 的任务身份（= 发起 ask 的 worker session id；delegated worker-unforgeable）。 */
     sourceTaskId?: string;
+    /** 发起此 ask 的 end-user principal（per-ask 用户归因；与多租户 `scope` 不同层 —— scope=租户命名空间, principal=具体用户）。 */
     principal?: string;
+    /** §assistant-scheduler 下批（service b96b76b）：ask 创建时间（epoch ms）→ 面板显「挂了多久」。
+     *  非轻量 summary 字段,inbox 端点并行 get 完整 Checkpoint best-effort 取;缺/过期 cp → OMIT（容缺降级）。 */
     createdAt?: number;
 }
+/** §2 GET /v1/assistant/inbox 的行 = CheckpointSummary + objective（从 task ctx 富化）。
+ *  objective 契约明确"`null` if unavailable"故保留 `| null`（不与"缺则 OMIT"冲突, 这是真的回 null 的字段）。
+ *  已由 core listPending 按 severity 排序 —— 消费方**不要再排**。 */
 export interface InboxRow extends CheckpointSummary {
     objective?: string | null;
+    /** 🔴 LIVE 契约偏差(实测,已 flag service):部署的 worker(42c7a65,≥6cd0164)
+     *  的 `/v1/assistant/inbox` 实返**富 pending**(server.ts:1414 直接 spread `listPending()`,**没走 summarizeCheckpoint**),
+     *  即 `severity` 藏在 **`riskDescriptor.severity`** 里、无顶层 `severity` 标量、无 `gateKind`、无 `token`,且带 decide 三绑定。
+     *  这与契约文档「只 severity 标量、不上 riskDescriptor、有 gateKind/token」矛盾(文档自述"code wins")。
+     *  `assistant.inbox()` 防御性归一:severity 优先顶层标量(文档/未来态),缺则回退 `riskDescriptor.severity`(当前 live 态)——
+     *  service 修 handler 后顶层标量自动接管,前向兼容。下列字段标 optional 容当前富形状。 */
     riskDescriptor?: {
         severity?: 1 | 2 | 3 | 4 | 5;
         axes?: Record<string, unknown>;
         toolName?: string;
     } | null;
     toolName?: string | null;
+    /** decide 三绑定(富 inbox 行直接带 → 可不回拉 /api/approvals 决策;opaque echo)。 */
     boundCallId?: string;
     boundInputHash?: string;
+    /** §assistant-scheduler（core 1.114.0；the pinned wire contract）approval-suspend 时的 per-call 身份 = S3 D-1 精确锚。
+     *  🔴 聚合单收件箱**必保** toolCallId —— 否则 decide 仅按 taskId+sessionId 在 boundCallId 缺时退化 first-match（D-1 锚定回归）。 */
     toolCallId?: string;
+    /** §assistant-scheduler 下批（service b96b76b）：挂起工具调用的 args **脱敏预览**（"这条 ask 关于什么"）。
+     *  🔴 server 侧已 `redactDeep` scrub 密钥族 + 限长 2KB（inbox owner-scoped,仅 ask 自己 principal/operator 见）;
+     *  仅 `tool_approval` gate 带 args,`resource_limit`/`plan_review` 无 args → `null`（容缺渲染）。client 只展示、不重算。 */
     input?: unknown;
 }
+/** §3 GET /v1/assistant/tasks 行内联的 gate。wire 上 severity/spentMicroUsd/deadline 形如 `4 | null` —
+ *  SDK 侧规约为 `?:number`（缺/null 都容忍, OMIT 优先）。整个 gate 在 wire 上可为 null → AssistantTask.gate 是 `AssistantGate | null`。 */
 export interface AssistantGate {
+    /** 同 gateKind 开集。 */
     kind: string;
+    /** wire 可能回 null, 容忍。 */
     severity?: number;
     spentMicroUsd?: number;
+    /** epoch ms; wire 可能回 null, 容忍。 */
     deadline?: number;
 }
+/** §3 N-task 调度总览行 = run-store listRuns(owner) join 核心 scheduler seam listByScope。
+ *  Triage 序: needs-attention 优先, 再 severity DESC, 再 spend DESC（**core 已排, 不要再排**）。
+ *  需 TiDB run store 否则 `{tasks:[]}`。⚠️ createdAt/updatedAt 是 **ISO 串**（与 inbox/§1 的 epoch-ms 不同）。 */
 export interface AssistantTask {
     taskId: string;
     sessionId: string;
+    /** §3 状态三态（service 源审计 fix）:
+     *  - `running`  — 在跑。
+     *  - `suspended` — 在 HITL 门上 durable 挂起（resource_limit / 人审 tool gate 等）→ 走 §4b resume / §4a decide。
+     *  - `needs_review` — **first-class triage 态**:plan_review / dry-run review park 持久化成此态（**非 suspended**;
+     *    旧 handler filter 漏了它）。带 needsAttention:true + gate.kind=`plan_review`/`needs_review`（severity 缺）、
+     *    排最前。🔴 解析走 §4c plan_review（POST /v1/assistant/tasks/:id/plan_review），**非 §4b resume**。
+     *  注:与 L23 RunStatus 的 `needs_review`（design/80 D-0 dry-run TERMINAL 终态)语义不同 —— 那是 run 终态,
+     *  这是调度总览行上的 park 态;同名不同轴。 */
     status: "running" | "suspended" | "needs_review";
+    /** = 在 HITL 门上 park(suspended 或 needs_review)。 */
     needsAttention: boolean;
     gate: AssistantGate | null;
+    /** ISO 时间串。 */
     createdAt: string;
     updatedAt: string;
 }
+/** §4c plan_review 请求体（3-state）。editedPlan 仅 decision==="edit" 时必带, 其余禁带（→ 400, BFF 也会守）。 */
 export interface PlanReviewRequest {
     decision: "approve" | "edit" | "reject";
+    /** operator 改写后的 plan; REQUIRED iff decision==="edit", 否则禁带。 */
     editedPlan?: string;
     reason?: string;
 }
+/** §4b/§4c/§4d 决策端点的轻量返回（resume/plan_review→200 {status}, preempt→202 {status}）。
+ *  status 形如 "completed"|"preempting"|… —— 开放串, 不窄化。 */
 export interface AssistantTaskStatus {
     status: string;
 }