@sema-agent/server 7.148.0 → 7.149.0

package/README.md

@@ -129,7 +129,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   (both public; `:latest` rolling, `:<sha>` pinned).
 - **Image publishing discontinued**: Container images are no longer published since 7.128.0; the npm package is the only release artifact; self-build steps are in USAGE 9.13.
 - **Library embedding** (package root, e.g. `createHttpServer` + your own `StoreBackend`): first call
-  `declareServerWithheldEnv()` (package root) once, before `loadConfig()` and before any execution environment or child process —
+  `declareServerWithheldEnv()` (package root export since 7.148.0) once, before `loadConfig()` and before any execution environment or child process —
   it declares this process's own credential variables to the engine, so host child processes do not inherit them (under any `inheritEnv` word) and no name-list knob may hand them on;
   `loadConfig()` refuses (throws) in a process that has not declared, naming that step. The service's own entries do it as their first step. After
   `loadConfig()`, call `composeExecutionLane(config, ctx)` — the HTTP service and `run-local` both do. Since
@@ -142,6 +142,12 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   Since 7.145.0 it also requires `deploymentMods` — the very array the Runners carry as `mods` (`[]` for an embedding without mods): the server reads it to
   learn whether a prompt screen runs on a leg, and on such a leg stores objective text only once the engine delivered it unchanged (two paths sit outside that: a `verify`
   submission's resume input keeps the request text for its verifier, and that copy is never shown; and the leader lane's durable-worker sub-goal resume inputs, which do not go through that seat and are still stored as submitted — tracked separately); omitting it refuses at construction.
+  Since 7.147.0 `createHttpServer` also refuses to start a single-user deployment (`REQUIRE_PRINCIPAL` not `true`) that names no operator — the same sentence the service's own start-up gives:
+  set `OPERATOR_SINGLE_USER=true` (every caller is the operator) or a named `OPERATOR_PRINCIPALS` in the process environment before `loadConfig()`.
+  The seats `createHttpServer` requires (the type `ServiceCoreDeps`) are `runner`, `runnerFor`, `sideQuery`, `scenarioGate`, `peerDesk`, `deploymentMods`, `config`, `authorize` and `resolveSpec`
+  (`resolveSpec` is the embedder's own map from a request body and identity to a task spec; it returns no `sessionId`, the server stamps the root). Leaving out `runnerFor`, `authorize`,
+  `deploymentMods`, `peerDesk` or `scenarioGate` makes `createHttpServer` throw `createHttpServer: the <seat> seat is required` (followed by the way out) before it routes anything (leaving out `config` throws an unnamed
+  `TypeError`); for `runner`, `sideQuery` and `resolveSpec` the type is the only notice — a plain-JS embedding that leaves one out is accepted at construction.
   Build-time tools (e.g. a catalog editor) read two allowlists from the package root instead of hand-copying them: `RETIRED_ENVS` (the retired-env
   tombstones) and, since 7.110.0, `CATALOG_ENTRY_HEADER_LANES` / `CATALOG_ENTRY_HEADER_NAMES` (+ type `CatalogEntryHeaderName`) — the closed allowlist of
   model-catalog entry `headers` and the API line that reads each name. Both are frozen, the very objects the server judges with.
@@ -154,6 +160,9 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   refuse in those stages it exits non-zero with the start-up's own `fatal` line.
   The start-up's own route judge runs **after** the catalog is applied, not in `loadConfig()`: a hand-built assembly calls `judgeServedModelRoute(config, { envTableIsPlaceholder })`
   (package root) once after its own config-source apply, like `composeExecutionLane`.
+  A runnable reference of this whole chain ships in the package: `node scripts/embed-minimal.mjs` (from the package directory) assembles the nine seats `createHttpServer` requires
+  (package-root factories, the engine's `Runner`, and a one-line `resolveSpec` of its own), serves on the host lane from a throwaway data root on a kernel-assigned loopback port,
+  and prints `EMBED-MINIMAL ok port=<n>`; `--omit <seat>` leaves one seat out and says whether `createHttpServer` refused it at construction (`refused`, exit 2) or took it (`accepted`, exit 3).
 - **Bundled binaries**: the package ships two `bin` entries — `run-local` (single-machine local
   runner) and `sema-up` (deployment bootstrap script).
   - `run-local` boots the same engine in-process, runs one task from the CLI objective, prints the
@@ -225,6 +234,7 @@ The server is configured entirely through environment variables. The most import
 | `MODEL_FIRST_BYTE_TIMEOUT_MS` | unset (core's own default) | The wait from `fetch()` to the response headers, ms (7.103.0; replaces the retired `MODEL_CONNECT_TIMEOUT_MS`, which now **refuses to start** — the TCP + TLS connect is the transport's own clock since core 7.33.0). Unset = no key is passed, core's default applies (plus an upload allowance by request size, and one widened retry of its own). `0` = no engine clock on that segment and the transport's header / body clocks off too (the TCP + TLS connect keeps the transport's own clock). A whole number in `[0, 2147483647]`, anything else refuses to start. With `MODEL_GATEWAY_FALLBACK_URLS` set every gateway route likewise gets the first window plus one widened retry before failover (the server does not pass core's `firstByteRetries`: a caller can turn failover off per request, and that call has no backup behind it). A failover topology must set this knob explicitly: unset, a primary that accepts the connection but never answers is cut over only after core's first-byte lane (default window plus the widened retry) runs out, and a call with a shorter time budget (code-review council lenses, 180 s) is cancelled before the backup is tried; at boot such a deployment logs one `failover_first_byte_lane` warn |
 | `MODEL_FIRST_TOKEN_TIMEOUT_MS` | `600000` | First-token timeout (the only watchdog for a stream that opens and never emits; `0` = no engine clock on that segment, the transport's body clock off too. Raised from `120000` in 7.71.0 — a self-hosted backend's long prefill legitimately takes minutes to the first byte; set `120000` to restore the old posture) |
 | `MODEL_IDLE_TIMEOUT_MS` | `300000` | Mid-stream idle timeout (`0` = no engine clock on that segment, the transport's body clock off too) |
+| `REAP_RUN_STALE_SEC` | `120` | Run liveness window, seconds: the reaper (every `REAP_INTERVAL_SEC`, default `60`) fails a `running` run whose row has not been touched for this long, and the stop-then-start one-time migrations judge "is an earlier replica still serving" by the same window (a boot refuses while any run on the database heartbeated within it). **Must be greater than the 30 s liveness heartbeat** — a value at or below 30 refuses to boot (the reaper would race a run that is still heartbeating) |
 | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` (structured JSON logs) |
 
 **Boolean knobs** accept `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off` (case-insensitive; word table widened
@@ -287,6 +297,11 @@ One row per endpoint family (not exhaustive):
 | `/v1/workflows` (list · get · stream · agents/:label/steer) | Deterministic workflow orchestration runs with live streams and per-agent steering |
 | `GET /v1/usage` · `GET /v1/policy` | Cumulative spend (when quotas are configured) and effective policy read surface |
 
+Every 4xx/5xx body is `{ error, errorCode, … }`: branch on `errorCode` only — `error` is the sentence for a human. The wording rules for the
+server's own words in that sentence (a closed set of internal words and internal ID shapes, per-code exceptions with their reasons, and the scope —
+values quoted into the sentence, such as a name you sent, are outside it) ship in the package as `docs/error-text-lexicon.json`, the same file the
+server's own wording check reads (its notes are in Chinese).
+
 ## Ecosystem
 
 | Repository | What it is |

package/README.zh-CN.md

@@ -185,6 +185,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | `MODEL_FIRST_BYTE_TIMEOUT_MS` | 未设(core 缺省) | `fetch()` → 响应头的等待,毫秒(7.103.0 起;取代退役的 `MODEL_CONNECT_TIMEOUT_MS`,设了旧键**拒启** —— core 7.33.0 起建连(TCP + TLS)是传输层自己的钟)。未设 = 不传键,core 缺省当家(另加按请求体大小的上传宽限,到点 core 自有一次加宽重试)。`0` = 该段不设引擎钟、传输层的响应头 / 响应体钟也关(TCP + TLS 建连仍归传输层自己的钟)。须为 `[0, 2147483647]` 内整数,其余拒启。配了 `MODEL_GATEWAY_FALLBACK_URLS` 时每条网关路由同样是首窗 + 一次加宽重试之后才切备(server 不铸 core `firstByteRetries`:调用方可按请求关 failover,那一次身后没有备)。failover 拓扑须显式设:未设时接了连接却不回头的主网关要等 core 的首字节 lane(缺省窗 + 加宽重试)走完才切备,预算更短的调用(code-review council 镜头 180 s)在备网关被尝试之前就被取消;这类部署起服时打一条 `failover_first_byte_lane` warn |
 | `MODEL_FIRST_TOKEN_TIMEOUT_MS` | `600000` | 首 token 超时(开流不吐字的唯一看门狗;`0` = 该段不设引擎钟、传输层响应体钟也关。7.71.0 起由 `120000` 提高 —— 自托管后端长 prefill 下首字合理地就要等几分钟;要旧姿态显式设 `120000`) |
 | `MODEL_IDLE_TIMEOUT_MS` | `300000` | 流中 idle 超时(`0` = 该段不设引擎钟、传输层响应体钟也关) |
+| `REAP_RUN_STALE_SEC` | `120` | run 判活窗(秒):收割器(每 `REAP_INTERVAL_SEC`,缺省 `60`)把行 `REAP_RUN_STALE_SEC` 内没被碰过的 `running` run 判死;停-迁-起的一次性迁移也用这同一个窗判「更早版本的副本是否还在服务」(窗内库里还有 run 在心跳 ⇒ 起服拒)。**必须大于 30 s 的心跳周期** —— 设成 30 或更小起服拒(收割器会和仍在正常心跳的 run 抢) |
 | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error`(结构化 JSON 日志) |
 
 **布尔旋钮收 `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`**(大小写不敏感;词表自 7.16.0 起放宽)。
@@ -239,6 +240,9 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 | `/v1/workflows`(list · get · stream · agents/:label/steer) | 确定性 workflow 编排 run,带实时流与逐 agent 转向 |
 | `GET /v1/usage` · `GET /v1/policy` | 累计花费(配置配额时)与生效策略只读面 |
 
+每个 4xx/5xx 响应体都是 `{ error, errorCode, … }`:程序只按 `errorCode` 分支,`error` 是给人读的那句话。那句话里本服务自己写的部分有用词约束(内部词闭集与内部编号形、
+按错误码逐族的放行与理由,以及射程 —— 句中插进来的值,如你送来的名字,不在约束里),随包在 `docs/error-text-lexicon.json` —— 本服务自己的文案检查读的就是这一份。
+
 ## 生态导航
 
 | 仓库 | 是什么 |