@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/server.d.ts

@@ -33,65 +33,195 @@ import { coarseStatusForState, errorCodeForExit } from "./routes/images.js";
 export { coarseStatusForState, errorCodeForExit };
 import { explicitOperatorOk, isOperator, explicitOperator } from "./principal-gate.js";
 export { explicitOperatorOk, isOperator, explicitOperator };
+/** Per-request authorization context resolved before building the spec (identity, owned session). */
 export interface RequestAuth {
     principal?: string;
     sessionId: string;
     memoryScope?: string;
+    /** 142-S4:the SHAPE-VALIDATED `body.projectId`(authorizer 的 PROJECT_ID_REGEX 门通过后回传)。
+     *  main.ts 拿它查 config.projects 的 defaultScopes(memory.scopes 种子)。resume 腿(checkpoint 重建
+     *  auth)缺席 — main.ts 回落持久化 body.projectId(原始提交已验形)。 */
     resolvedProjectId?: string;
 }
+/**
+ * design/158 A8 —— ServiceDeps 的**分组窄接口**。
+ *
+ * 病:69 个平铺可选字段里 29 个只被单一路由域读、跨 ≥9 域的只有 4 个(config/logger/runStore/metrics)。
+ * 平铺形的直接后果 = main.ts 一个上千行的装配字面量,键与键之间没有任何「属于同一件事」的编译期表达,
+ * 键落错家/从未接线只能靠源码钉逐个盯(1.300/1.301/1.304/1.307/1.310 五起真缺陷都是这个病族)。
+ *
+ * 药:七个**窄**接口 + 顶层必填三件。装配点按组构造(每组一个带类型标注的中间 const ⇒ 受 TS 多余
+ * 属性检查保护),键放错组当场编译红。
+ *
+ * 兼容形(本批**不动消费点**):`ServiceDeps` = 平铺视图 ∩ 组槽。旧的平铺构造(96 个测试文件 +
+ * index.ts 的嵌入方)逐字不变仍编译通过;新的分组构造由 `flattenServiceDeps` 在 createHttpServer
+ * 入口摊平回平铺视图,server.ts 内的 ~700 处 `deps.x` 消费点原样保留。消费点迁移是后批的事——
+ * 一步到位需要同批改 ~700 处 src + ~800 处 test 键位,与「先立形、后搬家」相比没有额外收益。
+ */
+/** createHttpServer 的**必填三件**——引擎、部署配置、请求→TaskSpec 的映射。三者恒在场,
+ *  故留在顶层(不进任何可选组):没有它们 server 根本起不来,包一层可选组只会把编译期错误推迟到运行期。 */
 export interface ServiceCoreDeps {
     runner: Runner;
     config: ServiceConfig;
+    /**
+     * Map an inbound request body + resolved auth to a full TaskSpec. The SERVICE/deployment owns model
+     * + tools + mcp here (callers only supply content). `auth` carries the ownership-checked sessionId
+     * and the principal-derived memory scope — prefer them over anything in the body.
+     */
+    /** `opts.leg` (codex R4, appendSystemPrompt 案): "fresh" ⇒ a NEW submit — resolveSpec may fail-loud 400 on
+     *  combos that would silently discard caller payload (append rider / outputStyle on an append-less pack).
+     *  Absent/"resume" ⇒ a stored-body replay — the same combos drop+warn instead (a 4xx would brick the stored
+     *  task). The disposition lives INSIDE resolveSpec because only it derives the effective scenario (principal
+     *  ruling + defaultScenario) and holds the center-pack snapshot the provider pick uses — an HTTP-side probe
+     *  could disagree with the actual assembly (scenario mismatch / centerPrompts refresh TOCTOU). */
     resolveSpec: (body: TaskRequestBody, req: IncomingMessage | undefined, auth?: RequestAuth, opts?: {
         leg?: "fresh" | "resume";
     }) => TaskSpec | Promise<TaskSpec>;
 }
+/** **durable 持久面**:每个键 present ⇔ 对应路由/能力位在场,absent ⇒ 501(诚实缺席),
+ *  绝不静默降级。装配点 = main.ts 的 store backend 开箱段。 */
 export interface ServiceStoreDeps {
+    /** Durable async-run registry + event log (S1/S2). Enables /v1/runs when present. */
     runStore?: RunStore;
+    /** E18 resume-at: the eventId→entryId anchor map (tidb/pg/local). Present whenever a backend is — resolveSpec
+     *  resolves body.resumeAt(eventId)→entryId, the run lifecycle captures per-turn anchors, E21 purges them. */
     resumeAnchorStore?: ResumeAnchorStore;
+    /** Human-in-the-loop approval store (F4 poll gate). Enables /v1/approvals when present. */
     approvalStore?: ApprovalStore;
+    /** Per-session approval exemption store — enables decide body `remember:"session"` + the
+     *  exemptions list/revoke surfaces on /v1/approvals. The ask-gate probe is wired separately (main.ts). */
     approvalExemptionStore?: ApprovalExemptionStore;
+    /** Durable-checkpoint store (design/45, core 1.67): durable F4 suspend/resume. When present, the resume
+     *  endpoint + suspended-run surfacing are active. Set only when DURABLE_APPROVAL + a TiDB pool. */
     checkpointStore?: CheckpointStoreFull;
+    /** E6 durable SessionPolicyStore (operator-tightened per-session tool rules). Enables PUT/GET /v1/sessions/:id/policy
+     *  when present; core reads the rules at prepare-time (subtract-only) via RunnerDeps.sessionPolicyStore (wired separately). */
     sessionPolicyStore?: ServiceSessionPolicyStore;
+    /** E19 rewind-files snapshot store. Present ⇒ the `rewindFiles` capability is advertised; core uses it via
+     *  RunnerDeps.fileSnapshotStore (snapshot per turn + restore on resumeAt, ANY env since gate-split 1.134.0). Also the 2c artifact store. */
     fileSnapshotStore?: ServiceFileSnapshotStore;
+    /** D-1 通用文件上传(clay 拍 2026-07-27:独立附件 store,不骑 snapshot blob 面):enables
+     *  POST/GET/DELETE /v1/attachments*。缺席 ⇒ 501(与其他可选 store 面同姿)。绑定/物化半场在
+     *  main.ts(resolveSpec + env factory 包装);本面只管上传/取回/删除三动词 + server 权威上限。 */
     taskAttachmentStore?: TaskAttachmentStore;
+    /** design/153 件3d(/decide parked 赎回腿)——与 RunnerDeps/scenarioDeps **同实例**:durable bg
+     *  行店 + boot 期从生产装配(buildScenarios)取的裸 Agent ToolSpec。**这两件**与 checkpointStore
+     *  齐备时,POST /v1/approvals/:sessionId/decide 对 parked 后台子代的 pending checkpoint 走
+     *  claim→execute 赎回腿(src/parked-decide.ts);任一缺席=分支不存在(legacy 腿现状:getCtx
+     *  null → 409,诚实不误驱)。 */
     backgroundAgentStore?: import("@sema-agent/core").BackgroundAgentStore;
+    /** §0.5 session-ownership: the durable session abstraction (`SessionRepo`-style) the service OWNS — session
+     *  IDENTITY/enumeration (E16 list) + lifecycle (E17 fork, E21 history delete) come from HERE, not the
+     *  `task_run` runs ledger. When it carries `listSessions`, GET /v1/sessions sources sessions from the session
+     *  store (task_run only joins for run preview); `fork`/`deleteSession` enable the fork/delete routes. */
     sessionStorage?: OwnerAwareSessionStore;
+    /** S8 workflow-run store (design/97/98): enables GET /v1/workflows (list) + /v1/workflows/:id (detail).
+     *  Set when SELF_ORCHESTRATION_ENABLED. Live progress (/v1/workflows/:id/stream) is in-process
+     *  (subscribeWorkflow) and works whenever self-orchestration is on, store or not. Runs are owner-gated by
+     *  `scope` (= the creating principal). Also drives `capabilities.workflowsList` (= "can durably LIST runs"). */
     workflowRunStore?: WorkflowRunStore;
+    /** [1402] journal 读面(PAIR-REVIEW 修车批):GET /v1/workflows/:runId/journal 的数据源——与 runner 侧
+     *  workflowJournalStore 同一实例(main.ts backend.workflowJournal());缺席=501(与 workflowRunStore 同门)。 */
     workflowJournalStore?: import("@sema-agent/core").WorkflowJournalStore;
+    /** Sandbox-image-pool index (IMAGE-API-DESIGN.md §2, pool design §8): enables /v1/images* (query + select).
+     *  Set when a TiDB pool is present. The bake/publish job API (P2/P3) layers on top later. */
     imageIndex?: ImageIndex;
+    /** Sandbox-image-pool BAKE store (IMAGE-API-DESIGN.md §P2): enables /v1/images/bakes* (operator-gated async
+     *  bake + resumable SSE + runner claim/ingest + status-monotonic auto-register). Set when a TiDB pool is
+     *  present AND `IMAGE_BAKES_ENABLED`. The auto-register path writes into `imageIndex` (so both are wired
+     *  together). 🔴 main.ts boot-asserts `operatorPrincipals` is non-empty when this is on (never a
+     *  world-writable build-host-RCE door, §P2.4a). */
     imageBakes?: ImageBake;
+    /** P2 (design/73 §7.2): the outcome-fact sink, for the `GET /v1/outcomes` read aggregate. `summary` is
+     *  present on the SQL ledgers; a File sink (no query surface) → the endpoint 501s honestly. */
     outcomeSink?: import("../plugins/file-outcome-sink.js").OutcomeSink;
+    /** SendUserFile 账本(多租户治理面):scope↔object 映射的读面 GET /v1/sendfile-links。present ⇔ 签发面
+     *  已配 AND 有 store backend(main.ts 建;写点在两条 send lane 的 withLedgerRecording)。 */
     sendFileLedger?: import("../plugins/send-file-ledger.js").SendFileLedger;
+    /** 2c session-sync (P1d) — the WHOLE durable backend, so the `/v1/sessions/:id/sync/*` routes can call
+     *  exportSession/importSession (src/session-sync.ts), which fan out across ALL four session subsystems
+     *  (session entries + fileSnapshot blobs/manifests + sessionPolicy + resumeAnchor) in the §8 fail-closed atomic
+     *  order. The individual stores above are wired for the per-feature routes; the sync routes need the backend
+     *  itself because the orchestrator coordinates the four together (a route can't reassemble it from the parts —
+     *  `backend.session()`/`fileSnapshot()`/`sessionPolicy()`/`resumeAnchor()` must come from ONE backend). Present
+     *  whenever a durable backend (tidb/pg/local) is; absent on the env-only/no-backend worker (the routes 501). */
     backend?: StoreBackend;
 }
+/** **进程内活体协调面**(本副本 only,重启即空):HITL 协调器、可 steer 句柄注册表、事件总线、
+ *  收件箱。跨副本一律不可见——每个消费点都按「不在本副本 ⇒ 409/降级」写,不假装全局。 */
 export interface ServiceCoordinatorDeps {
+    /** E23 (shell-host contract): inbound MCP elicitation coordinator (live-only HITL). Set when MCP_ELICITATION_ENABLED.
+     *  Wired onto the runner's onElicit seam AND consumed here by `POST /v1/elicitations/:id/respond` + the per-run
+     *  ALS context wraps (background/inline-stream/resume). Absent ⇒ the capability is false + no server can elicit. */
     elicitation?: ElicitationCoordinator;
+    /** §4④: AskUserQuestion LIVE coordinator. Set when ASK_QUESTION_ENABLED. Wired onto the runner's onQuestion
+     *  seam AND consumed here by `POST /v1/questions/:id/respond` + the per-run ALS wraps on the streaming legs. Absent ⇒
+     *  the capability is false + the AskUserQuestion tool headless-defaults (never a live human). */
     question?: QuestionCoordinator;
+    /** [816]/[820]②: live tool-approval coordinator (core onAsk → CC three-choice card). Set when
+     *  TOOL_APPROVAL_ENABLED. Wired onto the runner's onAsk seam AND consumed here by
+     *  `POST /v1/tool-approvals/:id/respond` + the per-run ALS wrap on the SYNC streaming leg (live-only by design —
+     *  every other leg keeps core's fail-closed headless auto-deny, [819]⑤/[820]④). */
     toolApproval?: ToolApprovalCoordinator;
+    /** SVC-5 (design/97 CORE-5 #6): the process-local registry of STEERABLE workflow-agent handles
+     *  (`ctx.agentStream`) live on THIS replica. Enables POST /v1/workflows/:id/agents/:label/steer. See
+     *  workflow-agent-steer.ts for the handle-visibility seam status (the registry is real + ready; core does not
+     *  yet hand the deployment a handle to register, so the route returns steering.not_running until it does). */
     workflowAgentRegistry?: WorkflowAgentRegistry;
+    /** C2 (core 1.219): the process-local registry of STEERABLE Task-subagent handles live on THIS
+     *  replica (populated by the per-run-leg `onSubagentSpawn` internals sink). Enables
+     *  POST /v1/runs/:runId/subagents/:target/steer (`target` = the child's parentToolCallId, or its agentName
+     *  when unambiguous). Sync delegations only (core F3 scope: background children have no steer handle). */
     subagentSteerRegistry?: SubagentSteerRegistry;
+    /** P1 ①②: the async-workflow COMPLETION INBOX. A finished background workflow's completion
+     *  is enqueued here (in main.ts's `deliverWorkflowCompletion`) keyed by the originating session; when that
+     *  session next opens a stream (`POST /v1/runs` or a resume), we `drain` it and emit a `workflow_complete`
+     *  out-of-band SSE frame the shell turns into a `<task-notification>` (deduped by runId). Present when
+     *  self-orchestration is on. */
     workflowCompletionInbox?: WorkflowCompletionInbox;
+    /** MF-Fleet (shell-host data contract) — the in-process fleet aggregation bus backing `GET /v1/fleet/stream`
+     *  (the live multi-row task/workflow fleet view: status/elapsed/tokens/doneCount transitions pushed over time).
+     *  Present when wired in main.ts; the run + workflow lifecycle publish their per-row deltas to it. */
     fleetBus?: FleetEventBus;
+    /** [1196] session-watch registry(SSE 订阅共享探针面)。present ⇔ sessionStorage 有 getLeafId/ownerOf
+     *  (main.ts 建);absent ⇒ /v1/sessions/:id/events 501(capabilities.sessionEvents 同谓词,永不漂)。 */
     sessionWatch?: import("../session-watch.js").SessionWatchRegistry;
+    /** asyncRewake wake 管道 holder(main.ts 建壳,server 启动装 deliver=session→本副本活流 steer)。 */
     hookWakeBus?: {
         deliver?: (sessionId: string, text: string) => Promise<boolean>;
     };
+    /** SendUserFile(切片2):per-run file_link 帧发射 ALS;undefined ⇒ 工具未建(非 host lane / 未配签发面)。 */
     sendUserFile?: import("../capabilities/send-user-file-tool.js").SendUserFileEmitter;
+    /** v2 leader endpoint (design/50): enables POST /v1/leader (async) + GET /v1/leader/:id. Set when
+     *  LEADER_ENABLED + the leader wiring (e2b workers + git push) is configured. */
     leaderEndpoint?: LeaderEndpoint;
+    /** Fire-and-forget session auto-titler (first-submit hook; absent = feature dark). */
     sessionTitler?: {
         maybeTitle(sessionId: string, objective: string): void;
     };
 }
+/** **函数/构件缝**:main.ts 把跨多个子系统的动作编译成一个可调用面交给路由(路由不该自己
+ *  重组零件——见 backend 的同款论证)。parked-revive 三件是同族的构件缝(boot 期从生产装配取的裸
+ *  ToolSpec + 成员集 + 父约束重建器),与 backgroundAgentStore 齐备才构成赎回腿。 */
 export interface ServiceSeamDeps {
+    /** Audit回溯: current context (+ summary) for a session, plus its owner. Enables GET /v1/sessions/:id. */
     sessionAudit?: (sessionId: string) => Promise<({
         owner: string | null;
     } & Record<string, unknown>) | undefined>;
+    /** E21 session delete coordinator: purge a session's history (sessionStorage) PLUS the service-owned
+     *  run-ledger/checkpoint/tool-result rows, owner-guarded, in one call. Returns `{ deleted }` (idempotent) — or
+     *  `{ active }` when the runs-ledger TX re-asserted a still-live run (a concurrent createRun raced the route's
+     *  pre-check), which the route maps to 409. Enables DELETE /v1/sessions/:id. Wired by main.ts (all the stores). */
     purgeSession?: (sessionId: string, owner: string | null) => Promise<{
         deleted: boolean;
     } | {
         active: string;
     }>;
+    /** [1488]③(b): read a BACKGROUND agent-handle child's final report / current status out of the core
+     *  TaskRegistry (the same face the TaskOutput tool reads — agent handles are NEVER in the run store).
+     *  Wired in main.ts to `defaultTaskRegistry.pollTask` (non-blocking). Access is the REGISTRATION tuple:
+     *  owner = the parent run's taskId (resume legs register children under the sessionId — the registry's
+     *  sessionScoped arm matches via `access.sessionId`), scope = the run's principal ?? "default". */
     subagentTaskOutput?: (handle: string, access: {
         owner: string;
         scope: string;
@@ -100,6 +230,10 @@ export interface ServiceSeamDeps {
         content: string;
         details: unknown;
     }>;
+    /** [1499] CC TaskOutput 人侧对位 — the GENERIC task-handle read (background_bash cursor-consuming stdout /
+     *  monitor batches / background_agent final report; `workflow` refused at the seam — journal face owns it).
+     *  Same registration-tuple access derivation as subagentTaskOutput. Wired in main.ts to the seam over
+     *  defaultTaskRegistry.pollTask. */
     taskHandleOutput?: (handle: string, access: {
         owner: string;
         scope: string;
@@ -108,6 +242,8 @@ export interface ServiceSeamDeps {
         content: string;
         details: unknown;
     }>;
+    /** [1499] CC TaskStop 人侧对位 — stop a background task handle (bash kill / monitor stop / agent abort),
+     *  attributed "user". Same kind gate + access derivation as taskHandleOutput. */
     taskHandleStop?: (handle: string, access: {
         owner: string;
         scope: string;
@@ -116,10 +252,30 @@ export interface ServiceSeamDeps {
         content: string;
         details: unknown;
     }>;
+    /** 142-S5 §1.4: per-scope memory export reader (main.ts wires `exportMemoryScope` over the DB memory
+     *  backend). Enables GET /v1/memory/export — present ONLY on a DB memory plane (MEMORY_ENGINE_BACKEND=
+     *  pg|tidb); absent / file posture ⇒ 501 (single-user file memory exports by copying the memory dir). */
     memoryExport?: (scope: string) => Promise<MemoryEntry[]>;
+    /** 142-S2.5(设计 §2.5;裁定 plan 随数据走,core 零运行时半场):one full sync round for one
+     *  (scope, peer) — main.ts wires `performMemorySync` over the DB memory backend + the sync-cursor
+     *  store. Enables POST /v1/memory/sync/:scope — present ONLY on a DB memory plane
+     *  (MEMORY_ENGINE_BACKEND=pg|tidb); absent / file posture ⇒ 501 honestly (a single-user file plane
+     *  IS the TOC side of a sync — it has no central-authority half to serve). */
     memorySync?: (scope: string, syncReq: MemorySyncRequest) => Promise<MemorySyncResponse>;
+    /** WEB-SETUP-RECON 附B — org sessionMirror 治理态的 SERVICE 半场 = **观测面(audit),非执法面**。
+     *  裁定 (c):「该镜像而未镜像」发生在数据产生端(壳)——本 server 是镜像**目标**,只看得见到达的 push;
+     *  没到达的会话对 server 不存在(无客户端会话清单、无心跳契约),required 锁的真执法只能在壳(CC
+     *  managed-settings 心智;registry-core 域头注同判)。server 能诚实观测的最小面 = 镜像 PUSH 到达时该
+     *  principal 的治理态(required + 指定 engineUrl)入 audit 日志/metrics,供运营关联「治理生效 vs 到达流」。
+     *  per-principal 查询走 caps client 的 executionRuling 同车(零额外 RTT);absent = 无 center(单用户/
+     *  dry-run)⇒ 观测面不接线,零行为差。fail-open:观测失败绝不影响 sync 面本身。 */
     sessionMirrorRuling?: (principal: string | undefined) => Promise<SessionMirrorRuling | undefined>;
+    /** Degenerate-output a/b instrument: on errorCode=output.degenerate, inspect the session's turns to
+     *  classify where the salvageable answer was (counter + log). Fire-and-forget; no-op otherwise. */
     instrumentDegenerate?: (result: TaskResult) => void;
+    /** [1469] side-query 记账 seam(budget.ts createSideQueryAccountant——与 createTracer 同一装配点、
+     *  同一组 sink 实例:costQuota/model_cost 指标/fleetUsage/fleetLease,四路同语义)。缺席=零记账
+     *  (手搭测试 deps;生产 main.ts 恒传)。 */
     sideQueryAccounting?: (principal: string | undefined, r: {
         model: string;
         family?: "input-includes-cached" | "input-excludes-cached";
@@ -134,55 +290,131 @@ export interface ServiceSeamDeps {
         };
     }) => void;
     parkedReviveTool?: import("@sema-agent/core").ToolSpec;
+    /** 可选第三件:revive args 的 `subagent_type` roster 成员集([1588] Q1 成员性规则)。当前生产装配
+     *  **恒缺席**(boot 内建 default 无自定义 agents roster,per-request 的 spec.agents 不进 boot 工具)
+     *  = 恒省略 subagent_type,typed 子代按 general-purpose 形复活(保真度 caveat 已报 core,[1588]
+     *  批复审 G-F1;center roster 接线是候件,字段先留给它与测试口)。 */
     parkedKnownAgentTypes?: ReadonlySet<string>;
+    /** [1596]/[1597] 跨进程父约束重供:decide 腿按部署配置重建 host 任务的同语义父策略链(exempt 锚=
+     *  row.rootSessionId),经 core 1.396 的 `parkedResume.inheritedGate` 席位透传——缺席时重启后带
+     *  requiresParentConstraint 的 parked checkpoint 恒被 core pre-CAS 门诚实拒(不可赎回)。 */
     parkedReviveInheritedGate?: (row: import("@sema-agent/core").BackgroundAgentRecord) => unknown;
 }
+/** **可观测面**:日志/指标/累加器。全体 fail-open——观测失败绝不改变业务面行为。 */
 export interface ServiceObservabilityDeps {
+    /** Structured logger (access log + errors). */
     logger?: Logger;
+    /** Metrics registry; when present, exposed at GET /metrics (token-gated). */
     metrics?: Metrics;
+    /** E8 (shell-host contract): per-task × per-model usage accumulator fed by the cost tracer. Shared with `createTracer`
+     *  so the durable run lifecycle drains it into `model_usage` events → the `TaskStats.modelUsage` echo. */
     modelUsage?: ModelUsageTracker;
+    /** [998]②: the shared prompt-manifest accumulator (tracer records at prepare; the durable legs drain it
+     *  into `prompt_assembled` events for turns/stream). Same register-fence lifecycle as modelUsage. */
     promptManifests?: PromptManifestTracker;
+    /** Plan-cache recurrence probe (core design/42): per-scope objective recurrence rate, dumped at
+     *  GET /metrics/plan-cache. Pure in-memory; recorded per finished task on both result paths. */
     planCacheProbe?: PlanCacheProbe;
 }
+/** **准入/治理面**:身份解析与配额/限流/租约。每一件都是**拒绝**的权力(400/403/429),
+ *  缺席 = 该道门不存在(不是「默认放行的门」——两者在事故复盘里语义完全不同)。 */
 export interface ServiceGovernanceDeps {
+    /**
+     * Resolve identity + the owned session BEFORE the spec is built (S6). Throw `HttpError` to reject.
+     * Optional: when omitted, no principal/ownership enforcement (the body's sessionId is used as-is).
+     */
     authorize?: (ctx: {
         req: IncomingMessage;
         body: TaskRequestBody;
     }) => Promise<RequestAuth>;
+    /** 鉴权桥(registry-core api/auth-bridge):registry 用户 JWT → principal。缺席=分支不存在
+     *  (bearer 只认 SERVICE_AUTH_TOKEN(S),现状不变)。 */
     registryJwtVerifier?: {
         verify: (bearer: string) => Promise<import("../auth-bridge.js").VerifyOutcome>;
     };
+    /** Per-principal rate limiter for task/run endpoints. In-memory (single replica) or TiDB-backed
+     *  (cross-replica soft limit) — both satisfy RateGate. */
     rateLimiter?: RateGate;
+    /** Per-principal cumulative cost quota (refuses a tenant's next task once over for the window).
+     *  In-memory (single replica) or TiDB-backed (cross-replica) — both satisfy QuotaTracker. */
     costQuota?: QuotaTracker;
+    /** D4 AP:worker 侧 quota-lease admission(协商式;center lane 未配 = 缺席 = 零行为)。 */
     fleetLease?: FleetLeaseManager;
 }
+/** **部署自述面**:只被 /health、/v1/capabilities 与提交前置门读的部署事实(多为 live getter,
+ *  不是快照——/health 必须回答「此刻」)。 */
 export interface ServiceDeploymentDeps {
+    /** Stable per-process id recorded on runs (audit / stale recovery). */
     instanceId?: string;
+    /** Deployment-level capability facts merged into GET /v1/capabilities: e.g.
+     *  scenarios list, version, pricingConfigured. The store-derived booleans (asyncRuns/artifacts/approvals/
+     *  leader) are computed here from the deps — this bag is for what only main.ts knows. Open set. */
     capabilities?: Record<string, unknown>;
+    /** 场景详情只读面(GET /v1/capabilities/scenarios/:name 数据源):main.ts 在 boot 组装
+     *  (内建 details+center 条目同判定源盖同名)。absent = 404(与 capabilities 缺席同姿势)。 */
     scenarioDetails?: Record<string, import("../capabilities/scenarios.js").ScenarioDetail>;
+    /** Honest /health `sessionBackend` label — the wiring coerces the config enum to "tidb"
+     *  (meaning "durable, generically"), which on a pg deployment reads as SQL-TiDB and misleads triage.
+     *  main.ts passes the effective store label (`durable(pg)` / `durable(mysql)` / `durable(local)` / "memory",
+     *  same derivation as the boot `listening` log). Absent → fall back to the raw config enum. */
     sessionStoreLabel?: string;
+    /** S5 (SILENT-FALLBACK P0-b): true when the boot auto-probe degraded the store backend to in-memory. */
     storeDegraded?: boolean;
+    /**
+     * Graceful drain — shared mutable state between main.ts (flips `draining` on SIGTERM) and this server:
+     *  • while `draining`, NEW model-running submissions (the billable submit paths) get 503 + Retry-After, so an
+     *    orchestrator/shell retries against the replacement instance; read paths + in-flight verbs (steer/cancel/
+     *    respond/subagent) stay open so the runs we are waiting on can still finish/interact.
+     *  • `inflight` is ASSIGNED BY createServer (a live union of this replica's in-flight legs: durable bg/resume
+     *    `inflightRuns` + live sync/resume streams `steerableRuns`) — main.ts polls it to know when drain is done.
+     *  • /health carries `draining:true` (k8s readiness 摘流信号) + `version` (build self-description).
+     */
     drainState?: {
         draining: boolean;
         since?: number;
         inflight?: () => number;
         lastActivityAt?: () => number;
     };
+    /** boot ready 门(b):false = registry 部署无显式 env 模型且首次 effective pull 尚未落 roster
+     *  (worker 只有占位模型)。计费提交 503 + /health 加性 `ready:false`。absent = 恒 ready(env 模型在/非
+     *  registry 部署),现有部署零影响。main.ts 在 applyEffective 落模型后翻 true(one-way latch)。 */
     modelReady?: () => boolean;
+    /** Sema-registry restart signal: the refresh loop sets this when a pull carries restart-to-apply
+     *  changes (skills/mcp/scenarios/runtime-gates baked at boot) that DIFFER from this process's boot config.
+     *  Surfaced at GET /health as `restartRequired` + `restart{reasons,version,since}` so the orchestrator can
+     *  auto rolling-restart the worker. Change-detected (not presence) — absent when nothing baked-at-boot
+     *  changed, so polling it never causes a restart loop. */
     restartState?: () => RestartSignal | undefined;
+    /** codex R18 (models-tiers deferral): the persistent "deferred WITHOUT a next-boot handoff" state — set when a
+     *  changed model plane could not hot-apply (tier-frozen Runner / tiered candidate) AND no restart-surviving LKG
+     *  exists to justify forcing a restart. Surfaced on /health (`modelPlaneDeferred`) so the stuck-degraded state
+     *  outlives the one-shot warn (the etag advances → later ticks 304 and never re-enter the defer branch). */
     planeDeferredState?: () => {
         version: number;
         since: number;
         blocked?: string[];
     } | undefined;
+    /** ① core ruling — SPLIT: `capabilities.workflows` = the ENGINE-CAN axis, boot-computed from core's own
+     *  `workflowsCapability(deps)` (hardened script runner ∧ governance), NOT the `Boolean(workflowRunStore)` store
+     *  proxy. Orthogonal to `workflowsList` (the durable-list axis = `workflowRunStore`). Falls back to the store
+     *  proxy when absent (older callers / tests that don't pass it). */
     workflowsCapable?: boolean;
 }
+/** **数值旋钮**:部署可调的上限/拍距。缺省值写在消费点(`?? 256` 之类),此处只承载覆写。 */
 export interface ServiceKnobDeps {
+    /** (a)(clay 拍 a+c,2026-07-27)当快照 blob 走 SQL 默认店时(逃生口形/覆写形),该店的 per-blob
+     *  承载帽——PUT /sync/blobs 面据此**前置 413**(typed `blob_too_large_for_sql`)。不设=不前置(MinIO
+     *  形无帽)。为什么在 HTTP 面重复店里的检查:店的 never-throw 结果形把一切写失败折成 502,而 502
+     *  语义=可重试,对端会对一个永远过不去的 blob 无限重试——413 才是「别再送了」的诚实形。 */
     snapshotBlobSqlCapBytes?: number;
+    /** [1196] SSE 连接帽(缺省 256/副本;超限 503+Retry-After=消费方回落 /head 轮询)。 */
     sessionEventsMaxConnections?: number;
+    /** [1196] SSE 心跳/owner 复核拍距 ms(缺省 25s;测试注入用)。 */
     sessionEventsHeartbeatMs?: number;
+    /** [1196] 背压阻塞断流阈 ms(缺省 60s;write 持续 false 超过即断——僵消费者不无界积压)。 */
     sessionEventsStallMs?: number;
 }
+/** 组槽本身。每组可选:一个只跑 env-only 的 worker 可以一组都不给。 */
 export interface ServiceDepGroups {
     stores?: ServiceStoreDeps;
     coordinators?: ServiceCoordinatorDeps;
@@ -192,16 +424,39 @@ export interface ServiceDepGroups {
     deployment?: ServiceDeploymentDeps;
     knobs?: ServiceKnobDeps;
 }
+/** 平铺视图 = 必填三件 + 其余七组的全可选并集。**派生**自组接口,故与分组形永不漂。 */
 export type FlatServiceDeps = ServiceCoreDeps & Partial<ServiceStoreDeps & ServiceCoordinatorDeps & ServiceSeamDeps & ServiceObservabilityDeps & ServiceGovernanceDeps & ServiceDeploymentDeps & ServiceKnobDeps>;
+/** createHttpServer 的入参:两形皆可(平铺=存量,分组=推荐)。同名键两形都给时,**顶层显式键赢**
+ *  (含显式 `undefined`)——一处装配点只该用一形,混用时以肉眼最近的那个为准。 */
 export type ServiceDeps = FlatServiceDeps & ServiceDepGroups;
+/** 分组入参 → 平铺视图(createHttpServer 的第一件事)。一组都没给 ⇒ 原样返回(存量调用零开销、零形变)。 */
 export declare function flattenServiceDeps(deps: ServiceDeps): FlatServiceDeps;
 export type { TaskRequestBody } from "./wire-types.js";
+/** Personalization caps: server-pinned hard limits — a UI may be stricter, never looser. */
 export declare const MAX_USER_SKILLS = 10;
+/** = core `SKILL_CONTENT_MAX_CHARS`(1MB 加载门,core 1.293 起 invoke 全文零截断、超 1MB 整拒;常量在
+ *  dist/core/runner/synthetic-tools.js:84,未从 core 包根导出,故钉本地孪生+本出处注记)。修7 曾对齐旧
+ *  20k 截断门([845] 飞轮考据:20k 是压缩保留区口径,invoke 时刻用错),core 1.293 撤门后本门跟随回收
+ *  ([853]① 收口)——HTTP 面与引擎加载门同值,超限 400 fail-loud 而非引擎侧整拒后难诊断。 */
 export declare const MAX_SKILL_CONTENT_CHARS = 1048576;
 export declare const MAX_SYSTEM_PROMPT_CHARS = 16384;
+/** Cap on a request's `outputSchema` (JSON-serialized) — an uncapped schema bloats the prompt + the per-turn
+ *  validation cost. 32KB comfortably holds a rich nested schema while bounding the abuse surface. */
 export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
+/** Validate `body.skills` (caps + shape). Returns an error string (→ 400) or null when acceptable. */
 export declare function validateUserSkills(skills: unknown): string | null;
+/** Verification rounds requested by a caller, clamped to a safe [1,5] (default 2). */
 export declare function clampVerifyRounds(v: unknown): number;
+/**
+ * Managed-Agents-style HTTP/SSE service surface.
+ *   GET  /health
+ *   POST /v1/tasks            → run to completion, TaskResult JSON (synchronous)
+ *   POST /v1/tasks/stream     → SSE of TaskEvent, live tokens (synchronous, same instance)
+ *   POST /v1/runs             → async: 202 {taskId, sessionId, status}, runs in background (S1)
+ *   GET  /v1/runs/:id         → run status + result (poll)
+ *   GET  /v1/runs/:id/events  → SSE replay from Last-Event-ID, then tail to terminal (S2)
+ *   POST /v1/sessions/:id/wake→ 501 (resume is implicit: re-issue a task with the same sessionId)
+ */
 export declare function createHttpServer(rawDeps: ServiceDeps): http.Server & {
     denyExpiredApprovals: (now: number) => Promise<void>;
 };