@sema-agent/server 7.150.0 → 7.152.0

package/README.md

@@ -158,8 +158,8 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   up to the point where the model table is settled, never listens, and prints that same `modelPlane` JSON as one stdout line (byte-identical to the started engine's
   reading at the end of stage 2; when the boot pull overruns `CONFIG_BOOT_FETCH_BUDGET_MS` it is the fallback served before that pull lands); where the start-up would
   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`.
+  The start-up's own route judge runs **after** the catalog is applied, not in `loadConfig()`: a hand-built assembly calls `judgeServedModelRoute(config, { envTableIsPlaceholder, webAdminIsConfigSource })`
+  (package root) once after its own config-source apply, like `composeExecutionLane` (`webAdminIsConfigSource`: whether a web-admin is that assembly's config source — `false` for an assembly with none; it only decides whether the env-table refusal sentence names the web-admin as a way to get a default catalog).
   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).
@@ -211,7 +211,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` 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. |
+| `BIND_HOST` | see note | Listen address — the only source (`HOST` is not read: shells commonly set it to the machine name without the operator knowing). 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. 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 |
 | `MODEL_API_KEY` | — | Gateway API key (optional). Pairs only with `MODEL_GATEWAY_BASEURL`: with no gateway it is not loaded and sent nowhere |
@@ -265,6 +265,17 @@ are read from this process's own environment, never from the file. The file is e
 trusted directory (owner and mode are checked before every read; on Windows only the directory structure can be checked). Where the file lives, the entry keys, the credential boundary,
 the posture of an anonymous (no-principal) caller and how it relates to a request body's `mcpServers` are in `USAGE.md` §9.5i-ter.
 
+Object storage (MinIO / S3): the server never creates buckets and uses no S3 SDK — every request is a SigV4 presigned URL signed with the
+engine's one key (`MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`). What it does to which bucket is one machine-readable table, importable without
+the server's dependency graph: `import { OBJECT_STORE_ACTIONS, OBJECT_STORE_ACTION_PERMISSIONS, objectKeyGlob } from "@sema-agent/server/object-store-buckets"`
+— one row per request (bucket knob, key form, S3 action, who sends it: the server, the execution sandbox holding only the presigned URL, or the
+end user's client; URL lifetime). A tool that issues least-privilege object-store credentials per engine can generate the policy from it; the
+same table rendered as the per-bucket permission list is the deployment prerequisites list's 「对象存储桶」 section (internal record) — generate it from `OBJECT_STORE_ACTION_PERMISSIONS` × `objectKeyGlob`.
+A per-engine policy only separates the rows whose key starts with a per-engine prefix (`objectStoreRowEngineSlot(row)` names that slot; 圈不住 = it returns nothing):
+the SendUserFile tracks (`sendfile/…`, the public bucket's root) and the leader's patches (`leader-diff/…`) are the same objects for every engine on the bucket, so engines that
+share a bucket share those rows whatever their policy says — and engines that share the session snapshot bucket must each set their own `SESSION_SNAPSHOT_PREFIX` (a second
+database on the same bucket × prefix is refused at boot). Every signed URL lives at most `SIGV4_PRESIGN_MAX_SEC` (604800 s).
+
 ## Security & privacy note
 
 > 🔴 **Trace redaction ≠ egress control** (anchor: 脱敏 ≠ 出站控制). Trace redaction (the `«redacted»` markers you see in the
@@ -287,6 +298,7 @@ One row per endpoint family (not exhaustive):
 | `GET /health` · `GET /readyz` · `GET /metrics` | Liveness, readiness (`/readyz`: 200 / 503 for status-code-only probes such as a k8s `readinessProbe`) + Prometheus metrics (`/metrics/summary`, `/metrics/plan-cache`) |
 | `GET /v1/capabilities` | Deployment capability discovery — what this deployment can actually do, so clients never probe 501s |
 | `GET /v1/capabilities/mcp` · `POST /v1/capabilities/mcp/probe` | Per-server MCP status with **no run required**: dial each declared server, list its tools, close it again — the first for this deployment's own declarations, the second for a caller's `.mcp.json`. Rows are the engine's own wiring-manifest rows, so a one-shot command and an interactive session read the same verdict. Rate-capped per caller and cached briefly (it really dials) |
+| `GET /v1/capabilities/scenario` | Which scenario this request takes effect under and where it came from — `{ scenario, source }` (`request` / `ruling` / `deployment`), the same answer a submission with the same request shape gets; optional `?scenario=` (or the `x-agent-scenario` header) names one, refusals are the submission's own (capability bit `effectiveScenario`) |
 | `GET /v1/models` | Model catalog (names only; no gateway URLs or keys) |
 | `POST /v1/tasks` · `/v1/tasks/stream` | Synchronous task execution; SSE variant streams typed `TaskEvent`s token by token |
 | `POST /v1/runs` · `GET /v1/runs/:id` | Asynchronous runs: immediate `202`, background execution, poll for status/result |

package/README.zh-CN.md

@@ -126,7 +126,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   (`{ servedTable: "env" | "catalog", catalog: "absent" | "adopted" | "refused", refusalCode?, gap? }`)—— 问 server,不猜:判官的输入是服务进程的事实。
   引擎起来之前要同一个答案:跑包里的 `dist/model-plane-probe.js`(子路径 `@sema-agent/server/model-plane-probe`;env / 工作目录 = 将要起的那只引擎的),
   它跑起服的前两段到模型表定形即停、不监听,stdout 一行就是同一格 JSON(与起服第 2 段末的读数字节同;起服拉取超窗时是拉取落地之前的回落读数);起服会在这两段拒时退非 0,拒句与起服同一行。
-  起服自己的路由判官在**目录应用之后**判,不在 `loadConfig()` 里:自建装配在自己的配置源应用之后调一次包根的 `judgeServedModelRoute(config, { envTableIsPlaceholder })`(与 `composeExecutionLane` 同形)。
+  起服自己的路由判官在**目录应用之后**判,不在 `loadConfig()` 里:自建装配在自己的配置源应用之后调一次包根的 `judgeServedModelRoute(config, { envTableIsPlaceholder, webAdminIsConfigSource })`(与 `composeExecutionLane` 同形;`webAdminIsConfigSource` = web-admin 是不是这个装配的配置源,没有配置源的装配传 `false`,只决定 env 表拒因句是否把 web-admin 说成让目录缺省来服务的出路)。
 - **随包二进制**:包内带两个 `bin` —— `run-local`(单机本地 runner)与
   `sema-up`(部署引导脚本)。
   - `run-local` 在进程内启同一套引擎,把命令行给的目标跑完一次、打印结果、退出——没有 HTTP 服务,
@@ -165,7 +165,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | 变量 | 默认 | 说明 |
 |------|------|------|
 | `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` 照旧暴露。 |
+| `BIND_HOST` | 见说明 | 监听地址 —— 唯一来源(不读 `HOST`:shell 常把 `HOST` 设成机器名而 operator 并不知情)。显式 `BIND_HOST` **恒生效**。缺省:写面无鉴权时(`ALLOW_UNAUTHED_WRITES=true` **且**未配任何 service token)= `127.0.0.1`,否则全接口——配了 token 的部署不受影响。要暴露写面,配一个 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 连环告警 |
 | `MODEL_API_KEY` | — | 网关 key(可选)。只与 `MODEL_GATEWAY_BASEURL` 配对:没设网关时不装载、不发往任何路由 |
@@ -210,6 +210,13 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 (`envRefs` / `headerRefs`),值从本进程自己的环境里读、从不来自文件。这份文件是可执行配置,所以只从受信目录读(每次读之前判属主与模式;Windows 上只判得了目录结构)。
 文件放哪、条目有哪些键、凭据的边界、匿名(不带 principal)调用方的姿态、以及它与请求体 `mcpServers` 的关系,见 `USAGE.md` §9.5i-ter。
 
+对象存储(MinIO / S3):本服务不建桶、不用 S3 SDK —— 每个请求都是用引擎的那一对钥(`MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`)签的 SigV4 预签名 URL。
+它对哪只桶做什么是一张机读表,不带本服务的依赖图即可 import:`import { OBJECT_STORE_ACTIONS, OBJECT_STORE_ACTION_PERMISSIONS, objectKeyGlob } from "@sema-agent/server/object-store-buckets"`
+—— 一个请求一行(桶旋钮、key 形、S3 动作、谁发:server 进程 / 只持预签名 URL 的执行沙箱 / 拿链接的用户端、URL 有效期)。按引擎发最小权限对象存储凭据的工具据它生成策略;
+同一张表按桶渲染成的权限清单是部署前置清单「对象存储桶」一节(内部记录),由 `OBJECT_STORE_ACTION_PERMISSIONS` × `objectKeyGlob` 生成。
+按引擎的策略只圈得住 key 以每引擎前缀开头的行(`objectStoreRowEngineSlot(row)` 给出那只槽;没有 = 圈不住):SendUserFile 三轨(`sendfile/…`、公桶根)与 leader 补丁(`leader-diff/…`)对共桶的每台引擎是同一批对象,
+共桶的引擎不论策略怎么写都共用这些行;共用会话快照桶的引擎必须各设各的 `SESSION_SNAPSHOT_PREFIX`(同桶同前缀的第二只库起服即拒)。每只签名 URL 至多活 `SIGV4_PRESIGN_MAX_SEC`(604800 s)。
+
 ## 安全与隐私提示
 
 > 🔴 **trace 脱敏 ≠ 出站控制。** trace 脱敏(你在账本 / SSE / turns / 审批预览里看到的 `«redacted»`
@@ -230,6 +237,7 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 | `GET /health` · `GET /readyz` · `GET /metrics` | 存活探针 + 就绪探针(`/readyz`:200 / 503,给只认状态码的探针,如 k8s `readinessProbe`)+ Prometheus 指标(`/metrics/summary`、`/metrics/plan-cache`) |
 | `GET /v1/capabilities` | 部署能力发现 —— 本部署真正能做什么,客户端免 501 探测 |
 | `GET /v1/capabilities/mcp` · `POST /v1/capabilities/mcp/probe` | **无需先跑一条 run** 的逐台 MCP 状态:现连、列工具、关掉 —— 前者答本部署自己申报的服务器,后者答调用方自带的 `.mcp.json`。行就是引擎装配名册里的那一行,所以一次性命令与交互会话读到同一个判定。它会真拨号,所以按调用方限速 + 短窗复用 |
+| `GET /v1/capabilities/scenario` | 这次请求会生效哪只场景、它从哪一层来 —— `{ scenario, source }`(`request` / `ruling` / `deployment`),与同一请求形的提交拿到的是同一只答;可选 `?scenario=`(或场景头 `x-agent-scenario`)点名,拒与提交腿同码同句(能力位 `effectiveScenario`) |
 | `GET /v1/models` | 模型目录(仅名字,不含网关 URL/key) |
 | `POST /v1/tasks` · `/v1/tasks/stream` | 同步任务执行;SSE 变体逐 token 流式输出类型化 `TaskEvent` |
 | `POST /v1/runs` · `GET /v1/runs/:id` | 异步 run:立即 `202`,后台续跑,轮询状态/结果 |