@sema-agent/server 7.137.0 → 7.139.0

package/README.md

@@ -133,6 +133,9 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   7.104.0 the execution-lane start refusals (`LEADER_ENABLED` on the host lane, a multi-tenant posture on a
   shared lane, the device lane without its durable stores) are judged there, not in `loadConfig()`;
   `assertExecutionLaneInvariants(config)` is the same judgment without the `config.d/remote-exec.json` override.
+  `createHttpServer` requires the `authorize` seat — the only resolver of a submission's root session (the server stamps
+  that root onto every spec it runs; `resolveSpec` returns no `sessionId` and reads `opts.execution.root` when it needs it).
+  A single-user embedding passes `createAuthorizer(config, runner.sessions)` (package root); omitting the seat refuses 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.
@@ -147,7 +150,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
     result and exits — no HTTP server, no submission auth gate.
   - **The deployment governance knobs apply here too** (since 7.5.0 — before that this leg assembled its
     task with the governance chain absent, so the knobs were silently inert): `AUTONOMY`,
-    `runtime.commandPolicy` (from `config.d/governance.json`) and `SENSITIVE_WRITE_PATTERNS` are compiled
+    `governance.commandPolicy` (from `config.d/governance.json`) and `SENSITIVE_WRITE_PATTERNS` are compiled
     onto the local task exactly as they are on the HTTP leg, tighten-only, anchored at the
     `--workspace` directory.
   - **Off switches**: `SENSITIVE_WRITE_PATTERNS=off` **or** an empty value (`SENSITIVE_WRITE_PATTERNS=`)
@@ -196,10 +199,11 @@ The server is configured entirely through environment variables. The most import
 | `SERVICE_AUTH_TOKEN` | — | Callers must send `Authorization: Bearer <token>` |
 | `DB_BACKEND` | `local`* | `mysql` (any MySQL-protocol DB: MySQL/TiDB/MariaDB) / `pg` (PostgreSQL) / `local` (file-backed, no DB) / `memory` (explicit in-memory: nothing survives a restart, durable-runs faces 501). *Bare boot (no DB env at all) defaults to `local` so a single-user machine keeps its runs across restarts; any SQL signal (`SESSION_BACKEND` or `MYSQL_/PG_HOST`) keeps the `mysql` engine default, and `REQUIRE_PRINCIPAL=true` bare boots stay `memory`. (`TIDB_HOST`/`_PORT`/`_USER`/`_PASSWORD`/`_DATABASE`/`_POOL_SIZE` are retired names, not an alias — since 5.0.0 setting any of them refuses to boot, pointing at the `MYSQL_*` replacement; TiDB itself connects fine through `MYSQL_*`, since it speaks the MySQL protocol.) (the local file store has no tenant isolation — a warning says so). A DEFAULT-derived `local` that cannot create its data root degrades to memory with a warning + the `store_backend_degraded` gauge; an EXPLICIT `DB_BACKEND=local` fails loud instead. Setting `mysql`/`pg` explicitly also switches sessions to durable |
 | `SESSION_BACKEND` | `memory`* | `memory` / `mysql` (durable session center) / `auto`. *Defaults to durable when `DB_BACKEND` is explicitly `mysql`/`pg`. (`tidb` is a RETIRED public name — setting it refuses to boot; since 7.57.0 `GET /v1/config/catalog` also echoes the public word `mysql` instead of the internal `tidb` label) |
-| `REMOTE_EXEC` | unset | Sandbox execution lane: `host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`; unset = in-process stub (with `CONFIG_PROVIDER=local` the default becomes `host`). Naming a lane without its required env (e.g. `e2b` without `E2B_API_KEY`) or an unrecognized value **refuses to start** — no silent downgrade to the host/in-process lane (fail-closed). Under `CONFIG_PROVIDER=local` a `config.d/remote-exec.json` **wins over** this env (deliberate: the file is the single-machine source of truth). Since 7.57.0 that preemption is **loud** — `remote_exec_lane_preempted_by_file` names the preempted lane, the effective one, and whether it is an **isolation downgrade** (an isolated lane replaced by a non-isolated one); a file naming a not-yet-wired isolated lane (`e2b`/`k8s`/`ssh`/`adb`) leaves the env lane in force and says so |
+| `REMOTE_EXEC` | unset | Sandbox execution lane: `host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`; unset = in-process stub (with `CONFIG_PROVIDER=local` the default becomes `host`). Naming a lane without its required env (e.g. `e2b` without `E2B_API_KEY`; an unset, empty or whitespace-only value counts as absent, for every lane and every required key) or an unrecognized value **refuses to start** — no silent downgrade to the host/in-process lane (fail-closed). `k8s` needs `K8S_SANDBOX_IMAGE` **and** `K8S_NAMESPACE` — the sandbox pods' namespace has no built-in default (the deployment declares it; unset, empty or blank refuses to start; the bundled chart sets it from `sandbox.namespace`). Under `CONFIG_PROVIDER=local` a `config.d/remote-exec.json` **wins over** this env (deliberate: the file is the single-machine source of truth). Since 7.57.0 that preemption is **loud** — `remote_exec_lane_preempted_by_file` names the preempted lane, the effective one, and whether it is an **isolation downgrade** (an isolated lane replaced by a non-isolated one); a file naming a not-yet-wired isolated lane (`e2b`/`k8s`/`ssh`/`adb`) leaves the env lane in force and says so |
 | `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | unset | **SSH lane host-key verification** (`REMOTE_EXEC=ssh` only). `SSH_HOST_FINGERPRINT` = the host key's SHA256 base64 fingerprint (`SHA256:` prefix and `=` padding both optional); `SSH_KNOWN_HOSTS` = a path to a `known_hosts` file, matched literally on `host` / `[host]:port`. **Either one present ⇒ strict verification, a mismatch REFUSES the connection** (the error carries both fingerprints plus an `ssh-keyscan` line); both set ⇒ both must pass. **Both unset ⇒ a loud per-connection warning (`ssh_host_key_unverified`, man-in-the-middle risk) and the connection proceeds** — the deliberate posture for the batch-deploy lane, registered as a P-DEBT fail-open (`docs/FAIL-OPEN-CENSUS.md`). A malformed fingerprint or an unreadable `known_hosts` path **refuses to start**. Not supported in `known_hosts`, on purpose: hashed (`\|1\|…`) lines, wildcard patterns, `@cert-authority` — all skipped, so a host whose only entries are those is REFUSED (`@revoked` is honored and wins over any plain line, whatever the order) |
 | `HOOKS_TIMEOUT_MS` | unset (600000) | Time budget of each handler of the request `settings.hooks` registration (one event's run of the request's hook entries). Unset = 600000 ms — this is the engine's `budgetMs` for the registration (each handler's own time, one event's run of the request's hook entries); when the budget is spent, or the task is cancelled, the command hooks still running in that handler are stopped (SIGTERM, a short grace, then SIGKILL) — they no longer run on to their own `timeout`; the engine's default for an extension (10 s) is not used. `0` is honored as written (a zero budget). The server's own two observer registrations (deny meter, tool trace) do not read it. A non-integer, negative, or above-`setTimeout`-ceiling (2147483647) value **refuses to start** |
-| `CONFIG_PROVIDER` | unset | Config source: `local` (file-backed `config.d/`, single machine) / `remote` (registry control plane). Closed set, matched exactly (7.104.0+): any other value (wrong case, surrounding spaces) refuses to boot; empty = unset |
+| `MODS_ROOT` / `MODS_PACKAGES` | unset | **Deployment mod packages** loaded into the deployment seat. `MODS_PACKAGES` = a JSON array of `{ "name", "dir", "tier", "options"? }`: `name` is the package's own name (its `.claude-plugin/plugin.json` `name`, spelled exactly); `dir` an absolute path whose real path must sit strictly under the real path of `MODS_ROOT` (an absolute path; compared by path components — a symlink out of the root, a look-alike sibling such as `/mods-evil`, a `..` traversal, or the root itself all refuse to start); `tier` is required (`prepend` / `user` / `append` — the host declares it, a package never does); `options` is handed to the package's `register` as is. The engine's package reader is the only reader of the package files; this server never reads them. Every declared package is loaded once at boot and the whole list goes through the engine's admission: any failure (bad declaration, outside the root, the reader refuses the package, a name mismatch, the admission refuses) **refuses to start** with one single-line sentence naming the slot or the package — the server's own sentence never echoes declared values (paths, `options`); the reader's / admission's own words are passed through (credential shapes redacted, control characters stripped) and may name the package directory. Loaded ⇒ one `mods_package_loaded` log line per package (carrying the engine reader's `digest` — a digest of the bytes of the three package files it read, which tells you which bytes were loaded and is not a code-integrity credential: code the module loads on its own is not in it), `/health.mods.deploymentPackages` and the capability `modsDeploymentPackages: true`; unset (or `[]`) ⇒ both faces stay exactly as without these knobs. A package is **trusted deployment code** — it runs in this process with access to every tenant and the process credentials, the admission is not a sandbox — so install it only from a read-only artifact tree you control. If a package answers `allow` on `PreToolUse` (optionally with `updatedInput`), the engine still adjudicates the final arguments, and what an operator knob asks or refuses (`APPROVAL_REQUIRE`, `APPROVAL_NEVER_AUTO`, `MANUAL_MODE_SHELL_GATE=always`, the ask and deny tiers of `governance.commandPolicy`, …) or the engine mandates does not change because of it — but it can clear an **unmandated** default approval question, so installing a package hands that class of questions to the package author; to have a call asked whatever a package answers, declare it with those knobs. Changing the declaration or a package needs a restart (no automatic restart signal). The config catalog shows `MODS_PACKAGES` as present / length only. `options` is not a credential channel: this server does not withhold package credentials — `MODS_PACKAGES` itself and any variable a package reads are inherited by the model's child processes on the host lane under `inheritEnv: "all"` (only this server's declared own credentials are withheld), so deliver package credentials through a channel the host-lane model shell cannot read |
+| `CONFIG_PROVIDER` | unset | Config source: `local` (file-backed `config.d/`, single machine) / `remote` (registry control plane at `SEMA_WEB_ADMIN_URL` — `remote` without that URL refuses to boot). Unset = the center if `SEMA_WEB_ADMIN_URL` is set, else env only. Closed set, matched exactly (7.104.0+): any other value (wrong case, surrounding spaces) refuses to boot; empty = unset |
 | `DEFAULT_SCENARIO` | `code` | Default scenario when the request body names none; must be a scenario this deployment has (boot refuses otherwise) |
 | `SANDBOX_PKG_SOURCE` | `global` | Package sources inside sandboxes: `global` (official upstreams) / `cn` (China mirrors) / `custom` / `none` |
 | `SENSITIVE_WRITE_PATTERNS` | core's recommended set | Sensitive-path write deny list; comma-separated value replaces the set, `off` **or an empty value** disables. Applied unconditionally at the governance layer (independent of client permission mode, lane or settings presence) — including on the `run-local` leg. A value that cannot compile into a guard set (e.g. `/`, a pattern with no path segment) refuses to start |

package/README.zh-CN.md

@@ -115,6 +115,8 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   `composeExecutionLane(config, ctx)` —— HTTP 服务与 `run-local` 都这么做。7.104.0 起执行车道的几条拒启(host 车道上开
   `LEADER_ENABLED`、多租户姿态落在共享车道、device 车道缺耐久店)判在这一步,不在 `loadConfig()` 里;
   `assertExecutionLaneInvariants(config)` 是同一份判据,不做 `config.d/remote-exec.json` 覆写。
+  `createHttpServer` 的 `authorize` 席是必填:它是一次提交的根会话唯一的来源(server 把这只根盖进它执行的每一只 spec;`resolveSpec`
+  不返回 `sessionId`,要用根时读 `opts.execution.root`)。单用户嵌入传 `createAuthorizer(config, runner.sessions)`(包根导出);省掉即构造期拒。
   构建期工具(如目录编辑页)从包根取两张表、不手抄:`RETIRED_ENVS`(退役 env 墓碑)与 7.110.0 起的 `CATALOG_ENTRY_HEADER_LANES` /
   `CATALOG_ENTRY_HEADER_NAMES`(+ 型 `CatalogEntryHeaderName`)—— 模型目录条目 `headers` 的闭集白名单及读每个名字的线路。两者都冻结,就是服务端自己判据用的那一只。
   壳要知道一台在跑的引擎服务的是哪张模型表、目录采纳了没有、起服路由判官怎么说,读 `GET /v1/models` 的 `modelPlane`
@@ -126,7 +128,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   - `run-local` 在进程内启同一套引擎,把命令行给的目标跑完一次、打印结果、退出——没有 HTTP 服务,
     也没有提交鉴权门。
   - **部署治理旋钮在这条腿上同样生效**(7.5.0 起;此前这条腿自建任务时整条治理链缺席,旋钮静默失效):
-    `AUTONOMY`、`runtime.commandPolicy`(来自 `config.d/governance.json`)与 `SENSITIVE_WRITE_PATTERNS`
+    `AUTONOMY`、`governance.commandPolicy`(来自 `config.d/governance.json`)与 `SENSITIVE_WRITE_PATTERNS`
     与 HTTP 腿同样地 tighten-only 编译进本地任务,裁决锚在 `--workspace` 目录。
   - **关闸通道**:`SENSITIVE_WRITE_PATTERNS=off` **或**留空(`SENSITIVE_WRITE_PATTERNS=`)都关掉守卫集;
     `AUTONOMY` 不设(或设 `auto`)= 不额外收紧。守卫集若给了**编译不出来**的值(例如 `/` 这种不含任何
@@ -166,10 +168,11 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | `SERVICE_AUTH_TOKEN` | — | 调用方需带 `Authorization: Bearer <token>` |
 | `DB_BACKEND` | `local`* | SQL 引擎:`mysql`(任何 MySQL 协议库:MySQL/TiDB/MariaDB —— TiDB 走这个值,**没有** `tidb` 别名,写它启动即拒)/ `pg`(PostgreSQL)/ `local`(免 DB 文件持久化)/ `memory`(显式纯内存)。显式设置 `mysql`/`pg` 时 session 自动转 durable。*单租户裸 boot 缺省 `local`;`REQUIRE_PRINCIPAL=true` 的多租户裸 boot 缺省 `memory`(local 与多租户互斥) |
 | `SESSION_BACKEND` | `memory`* | `memory` / `mysql`(durable 会话中心)/ `auto`。*显式 `DB_BACKEND=mysql/pg` 时默认转 durable。(`tidb` 是**退役公名**,设了拒启;7.57.0 起 `GET /v1/config/catalog` 的回显也归一成公名 `mysql`,不再吐内部标签 `tidb`) |
-| `REMOTE_EXEC` | 未设 | 沙箱执行通道:`host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`;未设 = 进程内 stub(`CONFIG_PROVIDER=local` 时缺省转 `host`)。点名了通道但必需 env 不全(如 `e2b` 缺 `E2B_API_KEY`)或值不在闭集内 ⇒ **启动即拒**——不再静默降级到 host/进程内通道(fail-closed)。`CONFIG_PROVIDER=local` 下 `config.d/remote-exec.json` **压过**本 env(刻意:单机形的真源是那份文件);7.57.0 起这次抢占**响亮**——`remote_exec_lane_preempted_by_file` 点名被抢占的 lane、最终生效的 lane,以及它是不是一次**隔离降级**(隔离 lane 被换成不隔离的);文件点了尚未接线的隔离 lane(`e2b`/`k8s`/`ssh`/`adb`)时 env 腿照旧生效并说明 |
+| `REMOTE_EXEC` | 未设 | 沙箱执行通道:`host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`;未设 = 进程内 stub(`CONFIG_PROVIDER=local` 时缺省转 `host`)。点名了通道但必需 env 不全(如 `e2b` 缺 `E2B_API_KEY`;未设、空串或只含空白一律按缺,所有通道、所有必需键同判)或值不在闭集内 ⇒ **启动即拒**——不再静默降级到 host/进程内通道(fail-closed)。`k8s` 必需 `K8S_SANDBOX_IMAGE` **和** `K8S_NAMESPACE` —— 沙箱 pod 所在的命名空间没有内置缺省(部署自己声明;缺席、空串或只含空白 ⇒ 启动即拒;随包 chart 取 `sandbox.namespace` 显式设)。`CONFIG_PROVIDER=local` 下 `config.d/remote-exec.json` **压过**本 env(刻意:单机形的真源是那份文件);7.57.0 起这次抢占**响亮**——`remote_exec_lane_preempted_by_file` 点名被抢占的 lane、最终生效的 lane,以及它是不是一次**隔离降级**(隔离 lane 被换成不隔离的);文件点了尚未接线的隔离 lane(`e2b`/`k8s`/`ssh`/`adb`)时 env 腿照旧生效并说明 |
 | `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | 未设 | **SSH 通道主机密钥校验**(仅 `REMOTE_EXEC=ssh`)。前者 = 主机公钥的 SHA256 base64 指纹(`SHA256:` 前缀与 `=` 填充都可选);后者 = `known_hosts` 文件路径,按 `host` / `[host]:port` **逐字**匹配行。**任一在场 ⇒ 严格校验,不符即拒连**(拒因带两半指纹 + `ssh-keyscan` 取指纹指路一行);两只同时在场 ⇒ 合取(都要过)。**两只全缺席 ⇒ 每连接一条响亮 warn(`ssh_host_key_unverified`,中间人风险)后照常连** —— 批量部署通道的既定姿态,已登记为 P-DEBT fail-open(`docs/FAIL-OPEN-CENSUS.md`)。指纹拼错 / `known_hosts` 路径读不到 ⇒ **启动即拒**。`known_hosts` 里**刻意不支持**:hashed(`\|1\|…`)行、通配符 pattern、`@cert-authority` —— 一律跳过,于是只有这些条目的主机会被**拒连**(`@revoked` 照常生效,且无论写在哪一行都优先于普通匹配行) |
 | `HOOKS_TIMEOUT_MS` | 未设(600000) | 请求 `settings.hooks` 那张扩展注册**每个 handler** 的时间预算(一个事件跑一遍本请求的钩子条目)。未设 = 600000 ms —— 这是引擎对这张注册的 `budgetMs`(每个 handler 自己的时间:一个事件跑一遍本请求的钩子条目);预算到、或任务被取消,这个 handler 里还在跑的命令钩子会被叫停(SIGTERM → 短宽限 → SIGKILL),不再跑到自己的 `timeout`;不用引擎给扩展的缺省(10 s)。`0` **按字面生效**(零预算)。本服务自己的两张观察注册(拒绝计量 / 工具追踪)不读它。非整数 / 负数 / 超 `setTimeout` 上限(2147483647)⇒ **启动即拒** |
-| `CONFIG_PROVIDER` | 未设 | 配置来源:`local`(单机文件 `config.d/`)/ `remote`(registry 控制面)。闭集、逐字比较(7.104.0 起):其余任何值(大小写不同、带首尾空白)拒启;空串 = 未设 |
+| `MODS_ROOT` / `MODS_PACKAGES` | 未设 | **部署座装载的 mod 包**。`MODS_PACKAGES` = JSON 数组,每项 `{ "name", "dir", "tier", "options"? }`:`name` = 包自己的名(`.claude-plugin/plugin.json` 的 `name`,逐字同);`dir` 绝对路径,真实路径须严格落在 `MODS_ROOT`(绝对路径)的真实路径之下(按路径分量判 —— 符号链接出根、`/mods-evil` 这类前缀相似的兄弟目录、`..` 遍历、根本身都拒启);`tier` 必填(`prepend` / `user` / `append`,宿主声明,包不自报);`options` 原样交包的 `register`。包里的文件只有引擎的读包者一只读者,本服务不读。每只声明的包起服装一次、整列交引擎准入:任一失败(声明坏、越根、读包者拒包、名不同、准入拒)⇒ **拒启**,一行拒句点名哪一席或哪只包 —— 本服务自己写的句子不回显声明的值(路径、`options`);读包者 / 准入交回的话原样透传(凭据形换记号、剥控制字符),其中可能点名包目录。装上了 ⇒ 每包一行 `mods_package_loaded` 日志(带引擎读包者交回的 `digest` —— 装载件三件字节摘要,认得出装的是哪几份字节,非完整性凭据:模块自己再加载的代码不在其内)、`/health.mods.deploymentPackages` 与能力位 `modsDeploymentPackages: true`;未设(或 `[]`)⇒ 两面与没有这两根旋钮时逐字节同。包是**受信的部署代码** —— 在本进程里跑、可触全部租户与进程凭据,准入不是沙箱 —— 只从你控制的只读物料树装。包若在 `PreToolUse` 上答 `allow`(可带 `updatedInput`),引擎仍按最终参数裁决,运维旋钮要问或要拒的(`APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` / `MANUAL_MODE_SHELL_GATE=always` / `governance.commandPolicy` 的问档与拒档等)与引擎强制的问句不因它改变,但**未被强制的**缺省审批问句它能清掉 —— 装包就是把这一类问句的决定权交给包作者;要某类调用无论包怎么答都问人,用这些旋钮声明。改声明或换包要重启(没有自动重启信号)。配置目录对 `MODS_PACKAGES` 只回在场位与长度。`options` 不是凭据通道:本服务不替包扣凭据 —— `MODS_PACKAGES` 本身与包自己读的任何变量,在宿主车道 `inheritEnv: "all"` 下都会被模型的子进程继承(只有本服务声明的自有凭据被扣),包要的凭据请经宿主车道模型 shell 读不到的渠道交付 |
+| `CONFIG_PROVIDER` | 未设 | 配置来源:`local`(单机文件 `config.d/`)/ `remote`(`SEMA_WEB_ADMIN_URL` 那只 registry 控制面 —— 写了 `remote` 而没设这个地址拒启)。未设 = 设了 `SEMA_WEB_ADMIN_URL` 即中心,否则纯 env。闭集、逐字比较(7.104.0 起):其余任何值(大小写不同、带首尾空白)拒启;空串 = 未设 |
 | `DEFAULT_SCENARIO` | `code` | 请求体未指定场景时的缺省场景;必须是本部署在册的场景名,否则拒启 |
 | `SANDBOX_PKG_SOURCE` | `global` | 沙箱内装包源:`global`(官方源)/ `cn`(国内镜像)/ `custom` / `none` |
 | `SENSITIVE_WRITE_PATTERNS` | core 推荐集 | 敏感路径写拒集;逗号分隔值为整体替换,`off` **或留空**关闭。在治理层无条件施加(与客户端权限模式/lane/settings 在场性无关),`run-local` 腿同样生效;编译不出守卫集的值(如 `/`)启动即拒 |