@sema-agent/server 7.148.0 → 7.149.0

package/docs/error-text-lexicon.json

@@ -0,0 +1,317 @@
+{
+  "description": [
+    "错误响应体 `{ error, errorCode, … }` 里 `error` 文案的用词约束。`error` 是给人读的一句话,`errorCode` 才是机器面(程序按码分支,不按文案);这份词表约束的是文案怎么写,不是协议。本服务自己的错误文案词域检查读的就是这一份文件,没有第二份。",
+    "射程:约束的是本服务自己写的那部分句子。句中插进来的值 —— 调用方送来的名字 / 路径 / id、上游或引擎的原话 —— 原样带出,不在这份词表的约束里;按词表判一句 `error` 时先把这些插入值剔掉(例:请求点名了一个叫 `council` 的模型而目录里没有,拒句里引着的这个名字不算命中)。",
+    "`words`:内部词闭集 —— 引擎 / 本服务内部机件的名字,判据是「调用方在 wire 上拿不到这个名字」。`error` 文案里不出现其中任何一个词:把 `words.match.pattern` 里的 `{word}` 换成词、按 `words.match.flags` 编译成正则来匹配。式子两头的 `\\b` 是承重的:wire 字段名的拼法(如 `checkpointToken`)不是整词,不命中;连字符是词边界(`workflow-agent` 里的 `workflow` 命中)。屈折形逐个列成成员,不做词干化(`park` 与 `parked` 是两件事)。",
+    "`idShapes`:内部编号形。`error` 文案里不出现任何一形:`shapes[].pattern` 按 `idShapes.flags` 编译成正则来匹配。",
+    "`pardons`:逐族放行 —— 唯一的例外来源。一条放行按族 `family` 生效(`<HTTP 状态码>:<errorCode>`);带 `where` 时只放行该族里含这个子串的那一句,不带时该族只有一句文案;`words` 是那一句上放行的词(都是 `words` 闭集的成员);`why` 说这个词在这一族上是调用方自己看得见、拿得到、写得出的哪一样东西(路径段 / wire 字段 / 错误码的拼写 / 旋钮名 / 状态词)。不在放行里的命中都不该出现在 `error` 文案里。"
+  ],
+  "words": {
+    "match": {
+      "pattern": "\\b{word}\\b",
+      "flags": "i"
+    },
+    "groups": [
+      {
+        "forms": [
+          "workflow",
+          "workflows"
+        ],
+        "why": "引擎内部的 workflow 执行通道;产品义(`/v1/workflows` 资源、`Workflow` 工具)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "child",
+          "children"
+        ],
+        "why": "引擎的父子代角色名;产品义(调用方自己在一条 run 下起的后台 agent)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "host",
+          "hosts"
+        ],
+        "why": "引擎的宿主会话角色(「宿主会话 / 宿主的下一跑」);产品义(worker 所在机器的文件系统路径)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "park",
+          "parks",
+          "parking"
+        ],
+        "why": "挂起对象的名词 / 动词形 —— wire 上只有形容词 `parked`,没有这三个形;错误码自己拼着它的族按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "parked"
+        ],
+        "why": "wire 状态词(`GET /v1/agents/roster` 的 `?status=` 闭集成员);在待决 / decide 面上是产品词,但仍逐族放行、不整词豁免,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "lane",
+          "lanes"
+        ],
+        "why": "本服务对「执行通道 / 部署形」的内部自称;错误码自己拼着它的族按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "leader",
+          "leaders"
+        ],
+        "why": "编排席的内部名;产品义(`POST /v1/leader` 端点)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "subagent",
+          "subagents"
+        ],
+        "why": "引擎内部的角色名;产品义(`/v1/runs/:id/subagents` 路径段)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "council",
+          "councils"
+        ],
+        "why": "复审席的内部名 —— wire 上没有这个拼写。"
+      },
+      {
+        "forms": [
+          "checkpoint",
+          "checkpoints"
+        ],
+        "why": "挂起点对象的内部名;产品义(错误码目录里在册的部署件名)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "leg",
+          "legs"
+        ],
+        "why": "本服务对「一段执行」的内部自称 —— wire 上没有这个拼写。"
+      },
+      {
+        "forms": [
+          "seam",
+          "seams"
+        ],
+        "why": "本服务对「可替换接缝」的内部自称 —— wire 上没有这个拼写。"
+      },
+      {
+        "forms": [
+          "twin",
+          "twins"
+        ],
+        "why": "本服务对「另一后端的孪生实现」的内部自称 —— wire 上没有这个拼写。"
+      }
+    ]
+  },
+  "idShapes": {
+    "flags": "",
+    "shapes": [
+      {
+        "pattern": "\\bS-\\d+",
+        "label": "内部工单号(S-nnn)"
+      },
+      {
+        "pattern": "\\bA-\\d+(?:\\.\\d+)*",
+        "label": "内部审计号(A-nnn.n)"
+      },
+      {
+        "pattern": "\\bB-\\d+",
+        "label": "内部缺陷号(B-nnn)"
+      },
+      {
+        "pattern": "\\bC-R\\d+",
+        "label": "内部裁定号(C-Rnn)"
+      },
+      {
+        "pattern": "\\bdesign/\\d+",
+        "label": "内部设计稿号(design/nnn)"
+      },
+      {
+        "pattern": "\\[\\d{3,4}\\]",
+        "label": "内部讨论帖号([nnnn])"
+      },
+      {
+        "pattern": "车[A-Z]{1,2}\\b",
+        "label": "内部作业名(车XX)"
+      },
+      {
+        "pattern": "\\bwf_[0-9a-f]{6,}",
+        "label": "内部扫描号(wf_xxxxxxxx)"
+      }
+    ]
+  },
+  "pardons": [
+    {
+      "family": "400:request.field_invalid",
+      "where": "host path",
+      "words": [
+        "host"
+      ],
+      "why": "「absolute host path」限定的是调用方自己在 `cwd` / `additionalDirectories` / `additionalReadDirectories` 里送的那些路径 —— `host` 在这里是「worker 跑在哪台机器上」的产品义,不是引擎里的 HOST 会话角色。"
+    },
+    {
+      "family": "404:not_found.workflow",
+      "words": [
+        "workflow"
+      ],
+      "why": "`/v1/workflows/:id` 面自己的 404 —— 调用方 URL 里写的就是这个资源名,错误码 `not_found.workflow` 也逐字拼着它。"
+    },
+    {
+      "family": "400:request.path_malformed",
+      "where": "malformed workflow path",
+      "words": [
+        "workflow"
+      ],
+      "why": "路径段名(`/v1/workflows/…`),调用方自己写进 URL 的那一段。"
+    },
+    {
+      "family": "501:capability.workflow_store_required",
+      "where": "workflow",
+      "words": [
+        "workflow"
+      ],
+      "why": "两句都点名调用方够得着的东西:`GET /v1/workflows/:id/journal` 这张脸,以及部署旋钮 `WORKFLOW_RUN_STORE`(它自己的拼写里就有 WORKFLOW)。"
+    },
+    {
+      "family": "501:capability.self_orchestration_required",
+      "where": "workflow",
+      "words": [
+        "workflow",
+        "workflows"
+      ],
+      "why": "`/v1/workflows` 提交面与 `GET /v1/capabilities` 的 `workflows` 能力位 —— 长的那句自己就把那个 JSON 键(`workflows:false`)拼了出来。"
+    },
+    {
+      "family": "404:not_found.task_handle",
+      "words": [
+        "workflow",
+        "workflows"
+      ],
+      "why": "这句自己点名 `GET /v1/workflows/:id/journal` —— 指的是调用方接下来该去读的那张脸,不是引擎车道。"
+    },
+    {
+      "family": "404:not_found.subagent",
+      "words": [
+        "workflow",
+        "child",
+        "children"
+      ],
+      "why": "`workflow` = 同上那张 journal 读面;`child`/`children` = 调用方自己在这条 run 下起的后台 agent —— 它们在 `/v1/runs/:id/subagents` 与 `GET /v1/agents/roster` 上都有行,亲缘关系是调用方自己造的。"
+    },
+    {
+      "family": "400:request.path_malformed",
+      "where": "malformed subagent path",
+      "words": [
+        "subagent"
+      ],
+      "why": "路径段名(`/v1/runs/:id/subagents/…`),调用方自己写进 URL 的那一段。"
+    },
+    {
+      "family": "501:capability.run_store_required",
+      "where": "subagent",
+      "words": [
+        "subagent"
+      ],
+      "why": "同一段路径名的两条能力拒(`/v1/runs/:id/subagents/…` 的读面与流面)—— 主语就是调用方刚才请求的那条路径。"
+    },
+    {
+      "family": "404:not_found.checkpoint",
+      "words": [
+        "checkpoint"
+      ],
+      "why": "错误码自身即 `not_found.checkpoint` —— 码与文案同词,调用方读码、读文案得到同一件事;不依赖任何它发不出去的字段。"
+    },
+    {
+      "family": "404:not_found.parked_checkpoint",
+      "words": [
+        "parked",
+        "checkpoint"
+      ],
+      "why": "两个词都在错误码自己的拼写里(`not_found.parked_checkpoint`);`parked` 另是 `GET /v1/agents/roster` 的 `?status=` 闭集成员。"
+    },
+    {
+      "family": "501:capability.checkpoint_store_required",
+      "where": "checkpoint store",
+      "words": [
+        "checkpoint"
+      ],
+      "why": "运维面 501,码自身就是 `capability.checkpoint_store_required` —— `checkpoint store` 是错误码目录里在册的那只部署件的名字。"
+    },
+    {
+      "family": "501:feature.preemption_disabled",
+      "where": "checkpoint store",
+      "words": [
+        "checkpoint"
+      ],
+      "why": "同一只部署件,名字来自同一份错误码目录(`capability.checkpoint_store_required`)—— 运维读这句时要装的就是目录里那一件;与同句的 `RESOURCE_SUSPEND` 是两样东西,理由不靠那个旋钮。"
+    },
+    {
+      "family": "400:decide.parked_remember_unsupported",
+      "words": [
+        "parked"
+      ],
+      "why": "错误码自身即 `decide.parked_remember_unsupported`;主语是调用方在 `GET /v1/agents/roster` 上看得到的那一行,`parked` 是那张脸 `?status=` 闭集里的词。"
+    },
+    {
+      "family": "409:decide.claim_lost",
+      "where": "parked agent is already claimed",
+      "words": [
+        "parked"
+      ],
+      "why": "同 decide 族:主语是 `GET /v1/agents/roster` 上状态值逐字为 `parked` 的那一行 —— 这句说的是「你挑的那一行被别人先认领了」。"
+    },
+    {
+      "family": "409:decide.gate_moved",
+      "words": [
+        "parked"
+      ],
+      "why": "同 decide 族:`re-parked` 说的是那一行又回到了 roster `?status=` 闭集里的同一个值 —— 调用方的动作(重读待决列表)正是由这个词决定的。"
+    },
+    {
+      "family": "409:decide.not_parked",
+      "where": "moved under this decide",
+      "words": [
+        "parked"
+      ],
+      "why": "错误码自身即 `decide.not_parked` —— 码与文案说的是同一个 roster 状态值离开了,两边同词。"
+    },
+    {
+      "family": "410:gone.ask_parked",
+      "words": [
+        "parked"
+      ],
+      "why": "错误码自身即 `gone.ask_parked`,且 `tool_approval` 帧上有一个同名 additive 键 `parked`(契约 §7b)—— 这个词调用方在两处都见得到。"
+    },
+    {
+      "family": "425:parking.ask_retry",
+      "words": [
+        "park"
+      ],
+      "why": "错误码自身即 `parking.ask_retry` —— 「mid-park」是这个码的自然语言拼法,重试就会告诉调用方它最终落在哪。"
+    },
+    {
+      "family": "500:internal.error",
+      "where": "the parked approval",
+      "words": [
+        "parked"
+      ],
+      "why": "这句说的是赎回一张后台审批卡失败:主语是那张卡,`parked` 是 `GET /v1/agents/roster` 的 `?status=` 闭集与 `tool_approval` 帧同名键上的同一个词。"
+    },
+    {
+      "family": "501:capability.device_lane_required",
+      "words": [
+        "lane"
+      ],
+      "why": "错误码自身即 `capability.device_lane_required` —— `device execution lane` 是这个码在错误码目录里的全称,旋钮 `REMOTE_EXEC=device` 在同句里给出兑现路径。"
+    },
+    {
+      "family": "404:not_found.leader_run",
+      "words": [
+        "leader"
+      ],
+      "why": "`POST /v1/leader` / `GET /v1/leader/:id` 端点名,也是错误码自身的拼写(`not_found.leader_run`)、能力位名(`capabilities.leader`)与旋钮名(`LEADER_ENABLED`)。"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.148.0",
+  "version": "7.149.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -45,9 +45,11 @@
     "scripts/drain-check-local.mjs",
     "scripts/drain-check.mysql.sql",
     "scripts/drain-check.pg.sql",
+    "scripts/embed-minimal.mjs",
     "deploy/sema-up",
     "deploy/facts",
     "docs/DEVICE-EXECUTOR-PROTOCOL.md",
+    "docs/error-text-lexicon.json",
     "wire-changes/",
     "USAGE.md",
     "MIGRATION.md"

package/scripts/embed-minimal.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// embed-minimal.mjs — the smallest HTTP service assembled the way a library embedder assembles it.
+//
+//   node scripts/embed-minimal.mjs                 build every seat, listen on 127.0.0.1:0, print `EMBED-MINIMAL ok port=<n>`, exit 0
+//   node scripts/embed-minimal.mjs --omit <seat>   build every seat but <seat>, then call `createHttpServer`:
+//                                                  refused at construction → `EMBED-MINIMAL refused seat=<seat> message=<first line>`, exit 2
+//                                                  accepted at construction → `EMBED-MINIMAL accepted seat=<seat>`, exit 3 (the seat is not judged at construction)
+//   any other failure                              `EMBED-MINIMAL failed step=<step> message=<first line>`, exit 1; a bad command line exits 64.
+//                                                  `--omit` reads the omission against the complete assembly: when that does not construct either, the line is `failed step=baseline`,
+//                                                  and a clean-up that did not happen is `failed step=cleanup` — neither is ever reported as a refusal of the omitted seat.
+//
+// The assembly order is the README "Library embedding" chain: `declareServerWithheldEnv()` → `loadConfig()` → `composeExecutionLane(config, ctx)` →
+// `judgeServedModelRoute(config, { envTableIsPlaceholder })` (the route judge, once after the config-source apply; `loadConfig()` does not judge routes) →
+// the nine required `createHttpServer` seats (the type `ServiceCoreDeps`) → `createHttpServer(deps)`. It imports the package root `@sema-agent/server` and the
+// engine package `@sema-agent/core` (the server's pinned dependency, owner of the `Runner` class), never a path inside `dist/`.
+// The service it assembles runs on the host lane against a throwaway local data root and listens on a kernel-assigned loopback port; it takes no task,
+// calls no model and leaves nothing behind (the data root is removed on the way out). It sets the ten environment variables in the `env` block below
+// itself; every other service knob is read from the caller's environment as usual, so run it from a shell that does not carry a production deployment's variables.
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Runner } from "@sema-agent/core";
+import {
+  HTTP_SERVICE_LANE_ENTRY,
+  buildScenarios,
+  composeExecutionLane,
+  createAuthorizer,
+  createBrain,
+  createHttpServer,
+  createKeyResolver,
+  createLogger,
+  createPeerDesk,
+  createScenarioGate,
+  createSideQueryLane,
+  declareServerWithheldEnv,
+  judgeServedModelRoute,
+  loadConfig,
+} from "@sema-agent/server";
+
+/** The nine seats `createHttpServer` requires (the type `ServiceCoreDeps`); `--omit` takes exactly these names. */
+const SEATS = ["runner", "runnerFor", "sideQuery", "scenarioGate", "peerDesk", "deploymentMods", "config", "authorize", "resolveSpec"];
+
+const TAG = "EMBED-MINIMAL";
+const oneLine = (e) => String(e instanceof Error ? e.message : e).split("\n")[0].replace(/\s+/g, " ").slice(0, 400);
+
+// ── command line ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+let omit;
+if (args.length === 0) {
+  omit = undefined;
+} else if (args.length === 2 && args[0] === "--omit" && SEATS.includes(args[1])) {
+  omit = args[1];
+} else {
+  console.error(`usage: embed-minimal.mjs [--omit <${SEATS.join("|")}>]`);
+  process.exit(64);
+}
+
+let step = "env";
+let dataRoot;
+let runner;
+let server;
+let line;
+let code = 1;
+try {
+  // ── the deployment's own env: what a deployer would put in the service's environment ─────────────────────────────────────────────────────────
+  dataRoot = await mkdtemp(join(tmpdir(), "embed-minimal-"));
+  Object.assign(process.env, {
+    DB_BACKEND: "local", // file-backed local mode: no database
+    LOCAL_DATA_ROOT: dataRoot, // the store root (highest-priority data-root knob)
+    AGENT_DATA_DIR: dataRoot, // the engine's own default root follows the same directory
+    REMOTE_EXEC: "host", // every deployment names its execution lane; `host` = tools run on this machine
+    BIND_HOST: "127.0.0.1",
+    PORT: "0", // the kernel assigns the port; the bound one is read back from the server
+    OPERATOR_SINGLE_USER: "true", // a single-user process says who the operator is
+    ALLOW_UNAUTHED_WRITES: "true", // no service token: loopback only
+    MODEL_ID: "embed-minimal-model", // the model table needs one entry; nothing here calls it
+    MODEL_GATEWAY_BASEURL: "http://127.0.0.1:9/v1",
+  });
+
+  // ── seat: config (package root: declareServerWithheldEnv → loadConfig → composeExecutionLane) ─────────────────────────────────────────────
+  step = "config";
+  declareServerWithheldEnv(); // first, before `loadConfig()` and before any execution environment or child process
+  const logger = createLogger("error");
+  const config = await composeExecutionLane(loadConfig(), { configSource: undefined, localRoot: dataRoot, logger, entry: HTTP_SERVICE_LANE_ENTRY });
+  // The route judge runs after the config-source apply, never inside `loadConfig()`: a model row with no endpoint would otherwise travel to the first model call.
+  // No center here ⇒ the env table is the served table, not a placeholder awaiting a catalog.
+  const routeGap = judgeServedModelRoute(config, { envTableIsPlaceholder: false });
+  if (routeGap !== undefined) throw new Error(routeGap.reason);
+
+  // ── seats: peerDesk, deploymentMods (package root: createPeerDesk; `[]` = no mods) ────────────────────────────────────────────────────────
+  step = "seats";
+  const peerDesk = createPeerDesk(); // zero IO; the same desk goes to the server and, as `peerSeat`, to every Runner
+  const deploymentMods = []; // the very array the Runners carry as `mods`
+
+  // ── seat: runner (engine package: `Runner`; the brain comes from the package root's createBrain) ───────────────────────────────────────────
+  const brain = createBrain(config);
+  runner = new Runner({ brain, models: config.models, roles: config.roles, mods: deploymentMods, peerSeat: peerDesk.seat });
+
+  // ── seat: sideQuery (package root: createSideQueryLane + createKeyResolver, the same brain as the Runner's) ────────────────────────────────
+  const keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
+  const sideQuery = createSideQueryLane({ brain, config, getKeyResolver: () => keyResolver });
+
+  // ── seat: scenarioGate (package root: buildScenarios → createScenarioGate, the read-face leg `peek`) ───────────────────────────────────────
+  const scenarios = buildScenarios({ runner, subRunner: runner, model: Object.keys(config.models)[0], skills: [], logger });
+  const scenarioGate = createScenarioGate({ config, scenarios, principalCaps: undefined, logger }, "peek");
+
+  // ── seats: authorize, runnerFor (package root: createAuthorizer; a single-Runner embedding says so with `() => runner`) ─────────────────────
+  const authorize = createAuthorizer(config, runner.sessions);
+  const runnerFor = () => runner;
+
+  // ── seat: resolveSpec (the embedder's own: request body + identity → the task spec; it returns no `sessionId`, the server stamps the root) ──
+  const resolveSpec = (body) => ({ objective: String(body?.objective ?? "") });
+
+  const deps = { runner, runnerFor, sideQuery, scenarioGate, peerDesk, deploymentMods, config, authorize, resolveSpec };
+
+  if (omit !== undefined) {
+    // An omission can only be read against a complete assembly that constructs: build that first, so a refusal that has nothing to do with the omitted seat
+    // (any other construction-time check of the deployment's configuration) is reported as `failed step=baseline`, never as `refused seat=…`.
+    step = "baseline";
+    createHttpServer(deps).close();
+    const partial = { ...deps };
+    delete partial[omit];
+    step = "createHttpServer";
+    createHttpServer(partial).close();
+    line = `${TAG} accepted seat=${omit}`;
+    code = 3;
+  } else {
+    step = "createHttpServer";
+    server = createHttpServer(deps);
+    step = "listen";
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const port = server.address().port;
+    step = "health";
+    const res = await fetch(`http://127.0.0.1:${port}/health`);
+    if (res.status !== 200) throw new Error(`GET /health answered ${res.status}`);
+    line = `${TAG} ok port=${port}`;
+    code = 0;
+  }
+} catch (e) {
+  if (omit !== undefined && step === "createHttpServer") {
+    line = `${TAG} refused seat=${omit} message=${oneLine(e)}`;
+    code = 2;
+  } else {
+    line = `${TAG} failed step=${step} message=${oneLine(e)}`;
+    code = 1;
+  }
+}
+
+// ── leave nothing behind, and say so before the result is printed: a clean-up that did not happen is a failure, not a footnote ───────────────────
+const leftovers = [];
+if (server?.listening) {
+  try {
+    await new Promise((resolve) => (server.closeAllConnections?.(), server.close(() => resolve())));
+  } catch (e) {
+    leftovers.push(e);
+  }
+}
+try {
+  runner?.sessions.dispose();
+} catch (e) {
+  leftovers.push(e);
+}
+if (dataRoot !== undefined) {
+  try {
+    await rm(dataRoot, { recursive: true, force: true });
+  } catch (e) {
+    leftovers.push(e);
+  }
+}
+if (leftovers.length > 0) {
+  if (code === 1) {
+    console.error(`${TAG} clean-up also failed: ${oneLine(leftovers[0])}`); // the run had already failed; its own line stays the result
+  } else {
+    line = `${TAG} failed step=cleanup message=${oneLine(leftovers[0])}`;
+    code = 1;
+  }
+}
+console.log(line);
+process.exit(code);