@sema-agent/server 7.95.0 → 7.96.0

package/USAGE.md

@@ -24,7 +24,7 @@ npm run dev                              # 或 bun run src/main.ts → http://<
 ```bash
 cd sema-server
 MODEL_GATEWAY_BASEURL=https://<your-gateway>/v1 MODEL_ID=<your-model-name> \
-SESSION_BACKEND=memory \
+SESSION_BACKEND=memory REMOTE_EXEC=host \
 docker compose up --build
 # 起来后 OA 只认 http://<host>:8090(LB)
 ```
@@ -40,10 +40,12 @@ docker compose up --build
 ```bash
 IMAGE_REGISTRY=<registry-namespace> \
 DB_BACKEND=mysql MYSQL_HOST=… MYSQL_USER=… MYSQL_PASSWORD=… MYSQL_DATABASE=sema_server \
-MODEL_GATEWAY_BASEURL=… MODEL_ID=<your-model-name> \
+MODEL_GATEWAY_BASEURL=… MODEL_ID=<your-model-name> REMOTE_EXEC=e2b E2B_API_KEY=… \
 docker compose up --build --scale service=4     # 4 个无状态 worker，nginx LB 扇发，TiDB 协调
 ```
 
+> 🔴 7.96.0 起根 `docker-compose.yml` 的 `REMOTE_EXEC`(执行车道)是**必填**:不设 ⇒ `docker compose config` 当场失败(此前静默起成一个没有手的 worker)。单人自用 `REMOTE_EXEC=host`(手落在 worker 容器里);多人 / 生产选隔离车道 `e2b`(配 `E2B_API_KEY`)或 `k8s`(配 `K8S_SANDBOX_IMAGE`)。
+
 > 拓扑:LB(入口)→ N 个一样的 worker → 共享 SQL 库(数据中心;MySQL 协议或 PG)+ 模型网关。无中央调度器,跨 worker 靠 DB 协调。
 
 **可选 — 多网关 failover + Anthropic 路由(消除单网关 SPOF)**
@@ -793,8 +795,8 @@ TASK_WRITE_FACE_ESCALATION=allow     # 词表 allow|refuse;坏词启动期响亮
 - **续跑腿**:一条在托管形机器上带着 `bypassPermissions` 的 parked 任务,赎回时被同一道门挡住,
   上层折成 `409 resume_blocked_by_policy`(`blockedBy: request.host_posture_refused`)。
   运维的解法是 `TASK_WRITE_FACE_ESCALATION=allow`。
-- **能力面披露位**:`GET /v1/capabilities` 的 `taskWriteFaceOpen`(`false` ⇒ 发那个键会拿 422)——
-  壳不必靠踩一次 422 才学会。
+- **能力面披露位**:`GET /v1/capabilities` 的 `taskWriteFaceOpen`(`false` ⇒ 发那个键会拿 422;或 —— 在
+  `AUTONOMY=read-only|plan` 的部署上(7.96.0 起)—— 受理但写面被钳回 roots)——壳不必靠踩一次才学会。
 - **`AUTONOMY=read-only|plan` 一行未动**。⚠️ 两者叠加时**本门先说话**:托管形 + `AUTONOMY=read-only`
   + `bypassPermissions` 的请求现在是 422,而 7.94 及以前它会跑起来(写被 autonomy 禁掉)。
   要保留旧结局就 `TASK_WRITE_FACE_ESCALATION=allow`(写面仍被 autonomy 压回 roots)。

package/deploy/sema-up/README.md

@@ -62,7 +62,7 @@ summary 会打印手动接法。
 | `--gateway=URL` | — | 模型网关 baseURL(OpenAI 兼容);带 agent 的档必需 |
 | `--model=ID` | `deepseek-v4-flash` | 模型 id |
 | `--model-key=K` | — | 模型 API key(也可 -f 里 MODEL_API_KEY) |
-| `--sandbox=LANE` | kvm 有→`kata` | `kata`/`e2b-cloud`/`runc`(full-single) |
+| `--sandbox=LANE` | single→`host`;multi→`e2b-cloud` | `host`/`e2b-cloud`(full-single / local-plus)。**执行车道**=agent 的手落在哪里,不点名就是没有手;词表与必需键的单一属主=`lib/lanes.json`。`kata`/`runc`/`e2b-self` 已退役(compose 路径对它们零接线),收到即非零退出并指路。kube 路径(full-cluster)**不选词**:runtime 按 runtimeClass `kata-qemu` 在不在自动定,车道恒 `REMOTE_EXEC=k8s` |
 | `--registry=BOOL` | `true`(local-plus `false`) | 配置中心网站开关 |
 | `--registry-image=REF` | — | sema-registry 镜像(registry=true 必需) |
 | `--git=MODE` | `none` | `none`/`provision`/`connect` |
@@ -105,6 +105,13 @@ data-center:2c/2G/20G)以下 BLOCK——确实无法稳定部署,提前警告不
 全部凭据生成一次、落 `~/.sema-up/<project>/.env`(0600),重跑**绝不轮换**;
 summary 里管理员密码只显示一次(新生成那次),不进日志不进 git。
 
+重跑时租户形与车道同一条规则:**决策 = 显式旗 ∨ 部署事实 ∨ 表缺省**。部署事实 = `.env`(与 shell / `-f` 环境)里
+上一次落下的 `REQUIRE_PRINCIPAL` / `REMOTE_EXEC` —— **不带旗重跑即沿用它**(多租部署、e2b 部署都不必再带旗);显式
+`--users` / `--sandbox` 与事实不一致 ⇒ 非零退出并点名两处(不静默覆盖;要换就先清掉旧值)。`.env` 与 shell / `-f`
+两处都给了且不同 ⇒ 同样拒。读 `.env` 的这几个键(连同所选车道的必需键,如 `E2B_API_KEY`)只认 sema-up 自己写出的
+**规范形**:一行、行首顶格 `K=<值>`,值是一个词或一对同型引号包住的一个词;`export ` 前缀、键旁空格、`K: v`、
+行内注释、重复行 ⇒ 非零退出并点名行号(不去猜 compose 会怎么读那一行)。`REQUIRE_PRINCIPAL` 只认 `true` / `false`。
+
 ## 验收
 
 ```bash

package/deploy/sema-up/chart/templates/server-v4pro.yaml

@@ -57,6 +57,9 @@ spec:
             - { name: MODEL_VISION, value: {{ .Values.server.modelVision | quote }} }
             - { name: SANDBOX_PKG_SOURCE, value: {{ .Values.server.sandboxPkgSource | quote }} }
             - { name: REMOTE_EXEC, value: k8s }
+            {{/* S-599:车道点名了就显式表态「这台有手」——REQUIRE_EXECUTION_LANE 让「车道被谁改没了」
+                 变成拒启而不是安静的无手 worker。server 侧默认仍 off,sema-up 产物一律写 true。 */}}
+            - { name: REQUIRE_EXECUTION_LANE, value: "true" }
             - { name: K8S_API_URL, value: "https://kubernetes.default.svc" }
 {{- if .Values.server.k8sInsecureTls }}
             - { name: K8S_INSECURE_TLS, value: "true" }

package/deploy/sema-up/chart/templates/server.yaml

@@ -70,6 +70,9 @@ spec:
             - { name: REQUIRE_PRINCIPAL, value: {{ .Values.server.requirePrincipal | default "false" | quote }} }
             - { name: SANDBOX_PKG_SOURCE, value: {{ .Values.server.sandboxPkgSource | quote }} }
             - { name: REMOTE_EXEC, value: k8s }
+            {{/* S-599:车道点名了就显式表态「这台有手」——REQUIRE_EXECUTION_LANE 让「车道被谁改没了」
+                 变成拒启而不是安静的无手 worker。server 侧默认仍 off,sema-up 产物一律写 true。 */}}
+            - { name: REQUIRE_EXECUTION_LANE, value: "true" }
             - { name: K8S_API_URL, value: "https://kubernetes.default.svc" }
 {{- if .Values.server.k8sInsecureTls }}
             - { name: K8S_INSECURE_TLS, value: "true" }

package/deploy/sema-up/lib/lanes.json

@@ -0,0 +1,56 @@
+{
+  "lanes": [
+    {
+      "path": "compose",
+      "choice": "host",
+      "users": ["single"],
+      "env": {
+        "REMOTE_EXEC": "host",
+        "REQUIRE_EXECUTION_LANE": "true"
+      },
+      "isolation": "unsupported",
+      "note": "server 容器本身就是沙箱:agent 的手落在这只容器里(worktree 隔离在、OS 级隔离不在)。只给单用户 —— 多租户下一个租户的输入会把手指向另一个租户的文件与进程。"
+    },
+    {
+      "path": "compose",
+      "choice": "e2b-cloud",
+      "users": ["single", "multi"],
+      "env": {
+        "REMOTE_EXEC": "e2b",
+        "REQUIRE_EXECUTION_LANE": "true",
+        "E2B_API_KEY": null
+      },
+      "isolation": "supported",
+      "note": "E2B 云沙箱:每任务一只 microVM。E2B_API_KEY 由运维自备(sema-up 只登记键名,绝不写值)。"
+    },
+    {
+      "path": "kube",
+      "choice": null,
+      "users": ["single", "multi"],
+      "env": {
+        "REMOTE_EXEC": "k8s",
+        "REQUIRE_EXECUTION_LANE": "true",
+        "K8S_SANDBOX_IMAGE": null
+      },
+      "isolation": "supported",
+      "note": "kube 路径**不选词**:runtime 由 kube-up.sh 按 runtimeClass `kata-qemu` 在不在自动定(在 ⇒ kata VM,不在 ⇒ runc 容器),沙箱镜像由 chart/清单给。本行只为对表(能力表 / 必需键 / REQUIRE_EXECUTION_LANE 三面),不进 --sandbox 词表。"
+    }
+  ],
+  "retired": [
+    {
+      "choice": "kata",
+      "why": "compose 路径对 kata 零接线:选了它 .env 里不会出现任何 REMOTE_EXEC,core 落 StubExecutionEnv ⇒ 起来的 worker 一只手都没有。有 KVM 的机器上它还曾是默认值,所以这是最贵的一个死词。",
+      "goto": "要 VM 级隔离走 kube 路径:sema-up.sh --profile=full-cluster(runtimeClass kata-qemu 在场即自动用 kata,不在场退 runc);留在单机 compose 上就选 host 或 e2b-cloud。"
+    },
+    {
+      "choice": "runc",
+      "why": "同 kata:compose 路径对它零接线,选了等于没选车道(无手)。",
+      "goto": "单机 compose 上「容器隔离」的真形就是 host(server 容器自己);要独立沙箱容器走 kube 路径 --profile=full-cluster。"
+    },
+    {
+      "choice": "e2b-self",
+      "why": "自托管 E2B 端点从未接线:它只在 preflight 文案与 machines.yaml 模板里出现过,没有任何一处把它翻成 REMOTE_EXEC。",
+      "goto": "先用 e2b-cloud(填 E2B_API_KEY);自托管端点的接线尚未排期。"
+    }
+  ]
+}

package/deploy/sema-up/lib/lanes.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""lanes.py — `lanes.json`(执行车道表)的唯一读者。
+
+## 为什么是一个文件而不是 sema-up.sh 里的几行 bash
+
+车道这件事此前被五份产物各写一遍(`sema-up.sh` 一行 `setk REMOTE_EXEC e2b`、三份 kube 清单的
+硬编码 `k8s`、根/review compose 的零车道白名单),于是「有 KVM 的机器默认选 kata ⇒ 零接线 ⇒
+起来的 worker 没有手」这件事没有任何一处会红。收成一张表之后,**表是唯一属主**:脚本里不许再
+出现任何一个车道词字面量,选项串、默认值、退役词指路、落 .env 的键值**全部**从这里渲。
+
+## 子命令(全部以非零退出表示「拒」,理由写 stderr)
+
+  choices                      打印 compose 路径的在役词(每行一个;--help / README 的词表渲它)
+  default <users>              打印该租户形下的缺省 choice
+  options <users>              每行一个 `ask` 选项串 `value:label[:infeasible=原因|建议]`
+  resolve <users> <choice>     校验并打印该车道要落 .env 的 `KEY=VALUE` 行(仅有值的键);
+                               必需但由运维自备的键名打印成 `#REQUIRED <NAME>` 注释行(「选了却没给」的早拒读它)
+  choice-of <REMOTE_EXEC 值>   部署事实 → `--sandbox` 词的反查(决策 = 显式旗 ∨ 部署事实 ∨ 表缺省):上一次落下的 `REMOTE_EXEC=<值>`
+                               是哪条 compose 车道;表里没有这个落盘值 / 反查不唯一 ⇒ 拒
+
+## 拒的三种形(全部 fail-closed,没有一条静默降级)
+
+ ① 退役词(`retired`):非零 + why + 指路;
+ ② 不在表里的词:非零 + 列出在役词表;
+ ③ 该租户形不许选的词(`users` 不含它):非零 + 列出该租户形可选的词。
+"""
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TABLE_PATH = os.path.join(HERE, "lanes.json")
+
+
+def die(msg):
+    sys.stderr.write("[sema-up] ⛔ %s\n" % msg)
+    raise SystemExit(1)
+
+
+def table():
+    with open(TABLE_PATH, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def compose_rows(t):
+    return [r for r in t["lanes"] if r["path"] == "compose"]
+
+
+def offered(t, users):
+    """该租户形下**可选**的 compose 行(顺序 = 表的声明序)。"""
+    return [r for r in compose_rows(t) if users in r["users"]]
+
+
+def find(t, choice):
+    for r in compose_rows(t):
+        if r["choice"] == choice:
+            return r
+    return None
+
+
+def retired_of(t, choice):
+    for r in t["retired"]:
+        if r["choice"] == choice:
+            return r
+    return None
+
+
+def cmd_choices():
+    return "\n".join(r["choice"] for r in compose_rows(table()))
+
+
+def cmd_default(users):
+    t = table()
+    rows = offered(t, users)
+    if not rows:
+        die("users=%s 在车道表里没有任何可选车道 —— 表坏了" % users)
+    return rows[0]["choice"]
+
+
+def cmd_options(users):
+    """`ask` 的选项串。该租户形不许选的车道**仍然列出**,但标 infeasible ——
+    运维要看见「这条路存在、但对你这个形不行、该怎么办」,而不是一个凭空少了一项的菜单
+    (`ask` 自己会在选中 infeasible 项时 fail-loud 退出,见 sema-up.sh 的 ask())。"""
+    t = table()
+    lines = []
+    for r in compose_rows(t):
+        label = r["note"].split("。")[0]
+        if users in r["users"]:
+            lines.append("%s:%s" % (r["choice"], label))
+        else:
+            lines.append(
+                "%s:%s:infeasible=users=%s 不许选它(隔离性 %s)|%s"
+                % (
+                    r["choice"],
+                    label,
+                    users,
+                    r["isolation"],
+                    "改选 %s,或走 kube 路径 --profile=full-cluster"
+                    % " / ".join(x["choice"] for x in offered(t, users)),
+                )
+            )
+    return "\n".join(lines)
+
+
+def cmd_choice_of(remote_exec):
+    """部署事实 → `--sandbox` 词的**反查**(sema-up 的决策规则:决策 = 显式旗 ∨ 部署事实 ∨ 表缺省)。
+
+    `.env` / shell 里已有的 `REMOTE_EXEC=<值>` 是上一次落下的哪条 compose 车道 —— 表是唯一属主,脚本不抄词。
+    表里没有这个落盘值 ⇒ 拒并列在役词(不猜、不把它讲成「冲突」);两行落同一个值 ⇒ 反查不唯一,表坏了
+    (`test/deploy-lanes-contract.test.ts` ⑥ 同时咬住「compose 行的 REMOTE_EXEC 两两不同」)。"""
+    t = table()
+    rows = [r for r in compose_rows(t) if r["env"].get("REMOTE_EXEC") == remote_exec]
+    if len(rows) == 1:
+        return rows[0]["choice"]
+    if len(rows) > 1:
+        die("车道表里有 %d 条 compose 车道都落 REMOTE_EXEC=%s —— 反查不唯一,表坏了" % (len(rows), remote_exec))
+    die(
+        "部署事实 REMOTE_EXEC=%s 不是这条部署路径上任何一条车道的落盘值 —— 在役:%s\n"
+        "   ↳ 下一步:清掉 .env / shell 里的 REMOTE_EXEC 后重跑(不带 --sandbox 即取表缺省),或带 --sandbox 选一条在役车道;"
+        "k8s 车道走 kube 路径 --profile=full-cluster"
+        % (
+            remote_exec,
+            " / ".join("%s(REMOTE_EXEC=%s)" % (r["choice"], r["env"]["REMOTE_EXEC"]) for r in compose_rows(t)),
+        )
+    )
+
+
+def cmd_resolve(users, choice):
+    t = table()
+    gone = retired_of(t, choice)
+    if gone is not None:
+        die(
+            "--sandbox=%s 已退役:%s\n   ↳ 下一步:%s"
+            % (choice, gone["why"], gone["goto"])
+        )
+    row = find(t, choice)
+    if row is None:
+        die(
+            "--sandbox=%s 不是这条部署路径上的车道 —— 可选:%s\n"
+            "   ↳ kube 路径(--profile=full-cluster)**不选词**:runtime 按 runtimeClass 自动定"
+            % (choice, " / ".join(r["choice"] for r in compose_rows(t)))
+        )
+    if users not in row["users"]:
+        die(
+            "--sandbox=%s 不能用在 --users=%s 上(该车道隔离性 %s)—— 改选:%s,或走 kube 路径 "
+            "--profile=full-cluster(k8s 车道,每任务一只 pod)"
+            % (
+                choice,
+                users,
+                row["isolation"],
+                " / ".join(r["choice"] for r in offered(t, users)),
+            )
+        )
+    out = []
+    for k, v in row["env"].items():
+        out.append("%s=%s" % (k, v) if v is not None else "#REQUIRED %s" % k)
+    return "\n".join(out)
+
+
+def main(argv):
+    if len(argv) < 2:
+        die("用法: lanes.py choices|default|options|resolve|choice-of …")
+    verb = argv[1]
+    if verb == "choices" and len(argv) == 2:
+        print(cmd_choices())
+    elif verb == "default" and len(argv) == 3:
+        print(cmd_default(argv[2]))
+    elif verb == "options" and len(argv) == 3:
+        print(cmd_options(argv[2]))
+    elif verb == "choice-of" and len(argv) == 3:
+        print(cmd_choice_of(argv[2]))
+    elif verb == "resolve" and len(argv) == 4:
+        print(cmd_resolve(argv[2], argv[3]))
+    else:
+        die("用法: lanes.py choices | default <users> | options <users> | resolve <users> <choice> | choice-of <REMOTE_EXEC 值>")
+
+
+if __name__ == "__main__":
+    main(sys.argv)

package/deploy/sema-up/lib/parse-machines.py

@@ -101,7 +101,13 @@ def main(path):
     emit("DP_S3", dp.get("s3", "deploy"))
     emit("DP_BACKUP", dp.get("backup", "true"))
     sb = sections.get("sandbox", {})
-    emit("SANDBOX_LANE", sb.get("lane"))
+    # S-599:`sandbox.lane` 是**死词**,已删。machines.yaml 只走 kube 路径,而 kube-up.sh 的 runtime
+    # 是按 runtimeClass `kata-qemu` 在不在自动定的(kube-up.sh:94-96),从来不读 SANDBOX_LANE ——
+    # 发射它只会让运维以为自己选到了什么。**响亮拒**而不是静默忽略:一个设了却没有任何效果的旋钮,
+    # 正是本批要消灭的那类病(留着它,下一个人还会照模板填)。
+    if sb.get("lane") is not None:
+        die("machines.yaml 的 sandbox.lane 已退役(kube 路径的 runtime 按 runtimeClass kata-qemu "
+            "在不在自动定,不读该键)——删掉那一行即可;compose 路径的车道见 sema-up.sh --help 的 --sandbox")
     emit("E2B_ENDPOINT", sb.get("e2b_endpoint"))
     emit("E2B_API_KEY", sb.get("e2b_api_key"))
     rg = sections.get("registry", {})

package/deploy/sema-up/machines.example.yaml

@@ -34,8 +34,11 @@ data_plane:
   backup: true          # PG 定时备份到 S3(data-center/full 默认 true)
 
 sandbox:
-  lane: kata            # kata(默认,需 KVM,预检不过不给)| e2b-cloud | e2b-self | runc
-  # e2b_endpoint: …     # lane=e2b-self 时必填(校验连通+模板可用)
+  # ⚠️ 这里**不选沙箱词**:machines.yaml 走的是 kube 路径,runtime 由 kube-up.sh 按 runtimeClass
+  #   `kata-qemu` 在不在自动定(在 ⇒ kata VM,不在 ⇒ runc 容器),执行车道恒 REMOTE_EXEC=k8s。
+  #   旧模板里的 `lane:` 是死词(从来没有任何一处读它),已退役——还写着它的 yaml 会被 fail-loud 拒。
+  #   单机 compose 路径的车道选择见 sema-up.sh --help 的 --sandbox。
+  # e2b_endpoint: …     # 自托管 E2B 端点(尚未接线,登记为 v2 候选)
   # e2b_api_key: …
 
 registry:

package/deploy/sema-up/preflight.sh

@@ -97,12 +97,15 @@ if [ -n "$BEST_MNT" ] && [ "$BEST_MNT" != "/" ] && [ "$BEST_GB" -gt "${DISK_GB:-
   add WARN disk-alt "$BEST_MNT ${BEST_GB}G avail" "存在比 / 更大的数据盘(多盘机)" "--data-root=$BEST_MNT/sema-data(sema-up 未显式指定时会自动选它)"
 fi
 
-# ── KVM(kata lane 前提;无=不给选 kata,建议替代,不算 BLOCK——lane 可换) ───────────────────
+# ── KVM(**kube 路径**的 kata runtimeClass 前提;compose 路径已无需要 KVM 的车道,S-599)────────
+# 有 KVM ⇒ 走 full-cluster 时 kata-deploy 能装上,沙箱得 VM 级隔离;没有 ⇒ kube 路径退 runc 容器
+# 隔离(仍是真隔离,只是弱于 VM)。两种都不是 BLOCK:单机 compose 路径的车道(host / e2b-cloud)
+# 与 KVM 无关。
 if [ -e /dev/kvm ] && grep -qE 'vmx|svm' /proc/cpuinfo 2>/dev/null; then
-  add OK kvm "available" "kata lane 可用(默认建议)" ""
+  add OK kvm "available" "kube 路径可用 kata runtimeClass(VM 级沙箱隔离)" ""
 else
-  add WARN kvm "unavailable" "无虚拟化支持,kata lane 不可部署" \
-    "①云上开嵌套虚拟化/换 bare metal ②e2b-cloud(填 key 即用)或 e2b-self ③runc(容器隔离,弱于 VM,不建议生产)"
+  add WARN kvm "unavailable" "无虚拟化支持:走 kube 路径时沙箱退 runc 容器隔离(弱于 VM)" \
+    "①云上开嵌套虚拟化/换 bare metal ②单机 compose 路径选 --sandbox=e2b-cloud(E2B 云沙箱,每任务一只 microVM)"
 fi
 
 # ── 端口(按 --ports/profile 决定检查面) ──────────────────────────────────────────────────────