@sema-agent/server 7.148.0 → 7.150.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
@@ -201,7 +210,7 @@ The server is configured entirely through environment variables. The most import
 
 | Variable | Default | What it does |
 |----------|---------|--------------|
-| `PORT` | `8090` | HTTP listen port. `0` = let the OS pick one: the `listening` log line (stdout, info level) and `/health.port` report the port actually bound |
+| `PORT` | `8090` | HTTP listen port. `0` = let the OS pick one: the `listening` startup line (stdout, one JSON line at info level; a startup protocol line, not filtered by `LOG_LEVEL`) and `/health.port` report the port actually bound; the same line's `boundAddress` is the address the kernel actually bound |
 | `BIND_HOST` (alias `HOST`) | see note | Listen address. An explicit `BIND_HOST` **always wins**. Default: `127.0.0.1` when the write face is unauthenticated (`ALLOW_UNAUTHED_WRITES=true` **and** no service token configured), otherwise all interfaces — deployments with a token are unaffected. Since 3.15.0 the `HOST` alias is **not** fully equivalent: shells commonly set `HOST` to the machine name without the operator knowing, so when the narrowing condition above holds it wins over an inherited `HOST` (logged as `bind_host_from_HOST_env_overridden`). To expose the write face, configure a service token — on a single-user deployment (`REQUIRE_PRINCIPAL` off) an explicit non-loopback `BIND_HOST` with an unauthenticated write face refuses to boot (invariant `single-user-anonymous-boundary`); on a multi-tenant deployment an explicit `BIND_HOST` still exposes it. |
 | `MODEL_GATEWAY_BASEURL` | **no default** | OpenAI-compatible gateway base URL (without `/chat/completions`). **No factory default**: every route that rides the openai-compatible lane must resolve to an explicit endpoint — the model's own catalog `baseUrl`, or this knob — else the server refuses to boot, naming the models and printing the explicit local spelling (`MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1`). An Anthropic-only deployment may leave it unset. Setting `MODEL_GATEWAY_FALLBACK_URLS` without it is refused too |
 | `MODEL_ID` | **required unless a catalog supplies the default** | Default model id — **no factory default since 3.0.0**. Since 7.101.0 the check runs **after** the catalog is applied: `MODEL_ID` **or** a usable catalog default (`config.d/models.json` / the web-admin) is enough; with neither the server refuses to boot (`config.default_model_missing`, naming both ways out). A catalog that is adopted replaces the env model table, so `MODEL_ID` is then not served: the boot is not refused (even with no gateway, when the catalog entries carry their own `baseUrl`) and logs one `config_env_set_but_ineffective` line naming the catalog default that serves (exactly once, at the moment the catalog is first adopted — at boot, or later when it arrives after the boot fetch budget / on a refresh). The old baked-in default was an internal-only model name, so every external deployment failed later and further from the cause: a gateway `400` plus a cascade of title-hook warnings |
@@ -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

@@ -164,7 +164,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 
 | 变量 | 默认 | 说明 |
 |------|------|------|
-| `PORT` | `8090` | HTTP 监听端口。`0` = 让 OS 分一个:`listening` 日志行(stdout,info 级)与 `/health.port` 报实际绑到的口 |
+| `PORT` | `8090` | HTTP 监听端口。`0` = 让 OS 分一个:`listening` 启动行(stdout 一行 JSON,info 级;启动协议行,不随 `LOG_LEVEL` 滤掉)与 `/health.port` 报实际绑到的口;同一行的 `boundAddress` 是内核实际绑上的地址 |
 | `BIND_HOST`(别名 `HOST`) | 见说明 | 监听地址。显式 `BIND_HOST` **恒生效**。缺省:写面无鉴权时(`ALLOW_UNAUTHED_WRITES=true` **且**未配任何 service token)= `127.0.0.1`,否则全接口——配了 token 的部署不受影响。自 3.15.0 起 `HOST` 别名**不再完全等效**:shell 常把 `HOST` 设成机器名而 operator 并不知情,于是上述收窄条件成立时,收窄压过继承来的 `HOST`(告警事件 `bind_host_from_HOST_env_overridden`)。要暴露写面,配一个 service token —— 单用户部署(`REQUIRE_PRINCIPAL` 未开)上写面无鉴权时显式非回环 `BIND_HOST` 起服拒(不变量 `single-user-anonymous-boundary`);多租部署上显式 `BIND_HOST` 照旧暴露。 |
 | `MODEL_GATEWAY_BASEURL` | **无缺省** | OpenAI 兼容网关地址(不带 `/chat/completions`)。**无出厂缺省**:每一条落 openai 兼容腿的路由都必须解析到显式端点 —— 目录条目自己的 `baseUrl`,或本键 —— 否则拒启,拒因点名模型并给出本机写法(`MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1`)。anthropic 单路由部署可不设。只设 `MODEL_GATEWAY_FALLBACK_URLS` 不设本键同拒 |
 | `MODEL_ID` | **必填(目录给出缺省时可省)** | 缺省模型 id ——**3.0.0 起无出厂缺省**。7.101.0 起判据挪到目录应用**之后**:`MODEL_ID` **或**目录里一条可用的缺省(`config.d/models.json` / 配置控制面)任一在场即可;两者皆无 = 拒启(码 `config.default_model_missing`,指路二选一)。目录一旦被采纳就整张换掉 env 表,`MODEL_ID` 此时不服务:起服不拒(目录条目自带 `baseUrl` 时没有网关也能起),并说一行 `config_env_set_but_ineffective` 点名在服务的目录缺省(目录第一次被采纳的那一拍恰好说一次 —— 启动时,或目录晚到 / 刷新时才第一次采纳)。旧的烤死缺省是内网模型名,外部部署必炸且炸在离根因最远处:网关 `400` + 标题 hook 连环告警 |
@@ -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` —— 本服务自己的文案检查读的就是这一份。
+
 ## 生态导航
 
 | 仓库 | 是什么 |