@sema-agent/server 2.0.0 → 3.0.0

package/dist/config-lkg.d.ts

@@ -11,7 +11,8 @@ export interface PersistedLkg {
  *  `<dir>/<sha-hex>` 落盘,读侧**必验 hash**(content-addressed 的全部意义;坏文件=忽略重拉)。 */
 export declare function defaultSkillCacheDir(): string;
 /** 默认路径(scheduler store 同门:SEMA_CONFIG_DIR → ~/.sema)。`CONFIG_LKG_PATH` 覆写;
- *  `CONFIG_LKG_ENABLED=false` 关闭(读写双关;design/158 B4 正名前叫 `CONFIG_LKG_DISABLED=true`,兼容期内仍认)。 */
+ *  `CONFIG_LKG_ENABLED=false` 关闭(读写双关)。🪦 正名前的 `CONFIG_LKG_DISABLED` 自 server 3.0.0 起是
+ *  **fail-loud 墓碑**——设了(任何值)即拒启并指路新名,不再被读取。 */
 export declare function defaultLkgPath(worker: string | undefined): string;
 /** 原子落盘一个干净候选(tmp+rename,0600)。BEST-EFFORT:失败=一条 warn 的素材(调用方发),绝不
  *  影响在飞的应用链——LKG 缓存丢失的代价只是下次冷启动回到 env 兜底。 */

package/dist/config-lkg.js

@@ -30,7 +30,8 @@ export function defaultSkillCacheDir() {
     return join(process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema"), "skill-cache");
 }
 /** 默认路径(scheduler store 同门:SEMA_CONFIG_DIR → ~/.sema)。`CONFIG_LKG_PATH` 覆写;
- *  `CONFIG_LKG_ENABLED=false` 关闭(读写双关;design/158 B4 正名前叫 `CONFIG_LKG_DISABLED=true`,兼容期内仍认)。 */
+ *  `CONFIG_LKG_ENABLED=false` 关闭(读写双关)。🪦 正名前的 `CONFIG_LKG_DISABLED` 自 server 3.0.0 起是
+ *  **fail-loud 墓碑**——设了(任何值)即拒启并指路新名,不再被读取。 */
 export function defaultLkgPath(worker) {
     const dir = process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema");
     const key = (worker ?? "global").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64);

package/dist/config-types.d.ts

@@ -34,7 +34,7 @@ export interface ImageBakeConfig {
      *  2026-07-13, SWR 弃用): `docker.io/claybobby`(海外主源;CN 兜底=内网 Gitea registry)。 */
     registry: string | null;
     /** The build-host promoted fetch-once cache base injected as `--cache-base` (NEVER caller-settable — a foreign
-     *  origin would defeat the domestic-only iron rule). `BAKE_CACHE_BASE` (e.g. http://172.17.0.1:8099). */
+     *  origin would defeat the domestic-only iron rule). `BAKE_CACHE_BASE` (e.g. `http://<build-host>:<port>`). */
     cacheBase: string | null;
     /** The pinned current sandbox-base ref injected as `--base-ref` when the caller omits `baseRef` (§P2.4c default).
      *  When NULL the server falls back to the index's latest published `sandbox-base` digest (design §P2.4c
@@ -53,8 +53,10 @@ export interface ImageBakeConfig {
     submitRateMax: number;
     submitRateWindowSec: number;
 }
-/** Service configuration, read from environment. */
-export interface ServiceConfig {
+/** Service configuration, read from environment — the **平铺面**(the ONE storage location for every
+ *  field). `ServiceConfig` (bottom of this file) = this flat face **plus** nine read-only group views;
+ *  fixtures that CONSTRUCT a config literal build this type and hand it to `attachConfigGroups`. */
+export interface ServiceConfigFlat {
     port: number;
     /** OpenAI-compatible model gateway base URL (without /chat/completions). */
     gatewayBaseUrl: string;
@@ -573,8 +575,9 @@ export interface ServiceConfig {
     /** design/113 C4: host-lane project-memory injection (CLAUDE.md + git narrative). Default **ON** (subject to the
      *  host-lane + single-user gate), so "open like CC" works without config. `PROJECT_MEMORY_ENABLED=false` opts out.
      *  design/158 B4 (lens4 N8): this was `projectMemoryDisabled` — the ONE negative boolean on a ServiceConfig whose
-     *  other 16 flags are positive `*Enabled`/`*Allowed`, so every read site had to invert twice. The retired env name
-     *  `PROJECT_MEMORY_DISABLED` still works for one deprecation window (inverted, with a boot notice). */
+     *  other 16 flags are positive `*Enabled`/`*Allowed`, so every read site had to invert twice. 🪦 server 3.0.0:
+     *  the retired env name `PROJECT_MEMORY_DISABLED` is a **fail-loud tombstone** — setting it (any value) refuses
+     *  boot with a message naming this knob; it is no longer read. */
     projectMemoryEnabled: boolean;
     /** R7: override the shared scheduler store path. Default `SEMA_CONFIG_DIR`→`~/.sema/scheduled_tasks.json` (the
      *  server writer + the shell daemon reader MUST agree). `SCHEDULER_STORE_PATH`. */
@@ -687,8 +690,9 @@ export interface ServiceConfig {
      *  ON for the host lane (CC-parity); set `LSP_HOST_ENABLED=false` to opt out. (`REMOTE_EXEC=host` only — ssh/adb/
      *  local-docker can't reach a local child process to the right filesystem.)
      *  design/158 B4 (lens4 N7): this lane used to share `LSP_ENABLED` with `lspEnabled` above — one env name driving
-     *  two OPPOSITE defaults. It now has its own knob; `LSP_ENABLED=false` remains a back-compat host opt-out (with a
-     *  boot notice naming the replacement) and `LSP_HOST_ENABLED` wins whenever it is set. */
+     *  two OPPOSITE defaults. It now has its own knob. 🪦 server 3.0.0: `LSP_ENABLED=false` (the pre-split host
+     *  opt-out) is a **fail-loud tombstone** — it refuses boot naming `LSP_HOST_ENABLED`; `LSP_ENABLED=true` keeps
+     *  its own meaning (the sandbox lane's opt-in above) and is unaffected. */
     lspHostEnabled: boolean;
     /** Graceful drain: how long SIGTERM waits for in-flight turns (live streams + bg/resume legs on this
      *  instance) to finish before the hard shutdown. During drain, new billable submissions get 503+Retry-After and
@@ -849,4 +853,40 @@ export interface ServiceConfig {
     /** Root dir holding `config.d/<domain>.json` for the local config source. Env: CONFIG_LOCAL_DIR. */
     configLocalDir?: string;
 }
+/** 组:store(持久化)—— DB 引擎三态、session 后端、SQL coords、快照 BLOB / SendUserFile 对象存储。 */
+export type ServiceStoreConfig = Pick<ServiceConfigFlat, "sessionBackend" | "sessionCacheTtlSec" | "rewindSnapshotMaxMb" | "dbBackend" | "dbBackendExplicit" | "localDataRoot" | "tidb" | "pg" | "dbQueryTimeoutMs" | "snapshotBlobStore" | "snapshotBlobSqlMaxBytes" | "snapshotBlobAllowSql" | "sendUserFile">;
+/** 组:modelPlane(模型面)—— 网关坐标、Anthropic 路线、韧性旋钮、主/廉价 model entry、role 表、降级梯。 */
+export type ServiceModelPlaneConfig = Pick<ServiceConfigFlat, "gatewayBaseUrl" | "gatewayApiKey" | "gatewayFallbackUrls" | "anthropic" | "resilience" | "model" | "models" | "modelApiKeyEnv" | "modelApiKeys" | "modelQuotaWeights" | "tiers" | "projects" | "roles" | "cascadeLadder" | "degrade">;
+/** 组:approval(审批 / HITL 门)。`directDoorActive` 无 env 解析腿(装配层三域合取的产物),但语义上
+ *  就是本组的门状态,故进组;`parseApprovalDomain` 的返回类型相应是 `Omit<…, "directDoorActive">`。 */
+export type ServiceApprovalConfig = Pick<ServiceConfigFlat, "approvalRequire" | "approvalDeny" | "approvalPollMs" | "approvalTimeoutSec" | "approvalAutoBudget" | "approvalNeverAuto" | "approvalHmacKeys" | "durableApproval" | "directApprovalDoor" | "directDoorActive" | "resourceSuspend" | "resourceSuspendTtlSec" | "askQuestionEnabled" | "toolApprovalEnabled" | "mcpElicitation" | "sensitiveWritePatterns" | "manualModeShellGate">;
+/** 组:memory(记忆面 + TOC 同步腿)。 */
+export type ServiceMemoryConfig = Pick<ServiceConfigFlat, "memoryEngineEnabled" | "memoryEngineDir" | "memoryEngineRemoteLaneAllowed" | "memoryEngineBackend" | "memoryScope" | "memorySync" | "projectMemoryEnabled" | "syncImportLeaseStaleSec">;
+/** 组:auth(鉴权 / 身份 / 治理棒)。`commandPolicy` 只有 sema-registry 腿(无 env 标量形),故 env 解析
+ *  函数不产出它,但它与 `autonomy` 是同一根治理棒的两半,归本组。 */
+export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "operatorPrincipals" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "principalJwtMaxTtlSec" | "bindHost">;
+/** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
+export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerStorePath" | "planModeEnabled" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "rosterRetentionMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "imageBakes">;
+/** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */
+export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "sighupIdleGraceMs" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
+/** 组:observability(可观测)。 */
+export type ServiceObservabilityConfig = Pick<ServiceConfigFlat, "metricsToken" | "traceToken" | "toolTrace" | "traceThinking" | "logLevel" | "otel">;
+/** 组:integrations(外部集成)。`mcpServers` 由 sema-registry 适配器填(无 env 腿),归本组。 */
+export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "defaultScenario" | "skillsDir" | "oaApiBaseUrl" | "oaServiceToken" | "oaIssue" | "configCenter" | "configProvider" | "configLocalDir">;
+/** 九个组槽。每组恒在场(`loadConfig` / `attachConfigGroups` 装好才交出配置),故不可选——新代码写
+ *  `config.modelPlane.model` 不需要 `?.`(可选组会把 `Model` 污染成 `Model | undefined`)。 */
+export interface ServiceConfigGroups {
+    store: ServiceStoreConfig;
+    modelPlane: ServiceModelPlaneConfig;
+    approval: ServiceApprovalConfig;
+    memory: ServiceMemoryConfig;
+    auth: ServiceAuthConfig;
+    orchestration: ServiceOrchestrationConfig;
+    limitsHttp: ServiceLimitsHttpConfig;
+    observability: ServiceObservabilityConfig;
+    integrations: ServiceIntegrationsConfig;
+}
+/** Service configuration = 平铺面(唯一存储处,消费点原样) ∩ 九个组视图(additive,不可枚举)。 */
+export interface ServiceConfig extends ServiceConfigFlat, ServiceConfigGroups {
+}
 //# sourceMappingURL=config-types.d.ts.map

package/dist/config.d.ts

@@ -1,10 +1,10 @@
 import { type Model } from "@sema-agent/core";
 import type { Autonomy } from "./runtime-governance.js";
-import type { ServiceConfig } from "./config-types.js";
+import type { ServiceConfig, ServiceConfigFlat, ServiceConfigGroups } from "./config-types.js";
 /** design/158 A1: the config TYPE face lives in the leaf module config-types.ts; re-exported here so
  *  every existing `from "./config.js"` importer compiles unchanged (pure-type consumers should prefer
  *  importing config-types.js directly — a type-only leaf, no loader baggage). */
-export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig } from "./config-types.js";
+export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig, ServiceConfigFlat, ServiceConfigGroups, ServiceStoreConfig, ServiceModelPlaneConfig, ServiceApprovalConfig, ServiceMemoryConfig, ServiceAuthConfig, ServiceOrchestrationConfig, ServiceLimitsHttpConfig, ServiceObservabilityConfig, ServiceIntegrationsConfig, } from "./config-types.js";
 /** Parse the AUTONOMY env into a validated autonomy mode. Unset/empty → undefined (unmanaged → no extra
  *  tightening). An UNKNOWN value FAILS at startup rather than silently becoming a no-op (a typo'd `AUTONOMY=readonly`
  *  must not silently leave a deployment ungoverned — fail-loud, same discipline as numEnv). Exported so the HOT
@@ -43,33 +43,38 @@ export declare function logConfigDiagnostics(logger: {
  *  Note the deliberate non-migrations: the posture family (`postureOn`) keeps its tri-state — its unset case is
  *  neither `true` nor `false` but "single-user ∧ infra-ready" — and the sentinel-valued knobs (`MEMORY_ENGINE`,
  *  `SANDBOX_PKG_SOURCE`, `MANUAL_MODE_SHELL_GATE`) are enums wearing a boolean's clothes, not booleans. */
-type ConfigKnobSource = "env" | "legacy-env" | "posture" | "default";
+/** 复审 2026-07-29 B4:3.0.0 把负名 env 改成 fail-loud 墓碑之后,legacy-env 这个 source 取值**永不可达**——
+ *  留着它等于在类型上书面承诺"还有一条 legacy 取值路径"。同批摘掉的还有 `ConfigKnobRecord.legacyName`
+ *  与它在 boot 诊断行里的输出:运维在日志里看到 `legacyName: HOST_BG_DISABLED` 的合理结论是"旧名还能
+ *  用",而实际设了就拒启——诊断面撒的谎比没有诊断更贵(它会让人先去试那个必然拒启的开关)。 */
+type ConfigKnobSource = "env" | "posture" | "default";
 export interface ConfigKnobRecord {
-    /** The CANONICAL env name (the positive one — a legacy alias appears in `legacyName`, never here). */
+    /** The env name. 3.0.0 起只有这一个名字 —— 负名别名已是墓碑(见 `boolEnvWithLegacyNegated`)。 */
     name: string;
     /** `opt-in` = default OFF, `opt-out` = default ON, `posture` = default derived from REQUIRE_PRINCIPAL ∧ infra. */
     polarity: "opt-in" | "opt-out" | "posture";
     value: boolean;
     source: ConfigKnobSource;
-    /** Set when the value came from (or the knob still accepts) a deprecated negative-form alias. */
-    legacyName?: string;
 }
 /** The registered boolean knobs, sorted by name — the data behind `logConfigDiagnostics`'s polarity table. */
 export declare function configKnobTable(): ConfigKnobRecord[];
-/** design/158 N8 (D-family) — a knob whose CANONICAL name is positive (`X_ENABLED`, default ON) but which keeps
- *  its retired negative name (`X_DISABLED`) working for one deprecation window.
+/** design/158 N8 (D-family) + server 3.0.0 墓碑 —— a knob whose CANONICAL name is positive (`X_ENABLED`,
+ *  default ON) and whose retired negative name (`X_DISABLED`) is now a **fail-loud tombstone**.
  *
  *  Why the flip at all: `X_DISABLED !== "true"` is a double negative at the read site, so the four knobs that
  *  used it (`PROJECT_MEMORY`, `CONFIG_LKG`, `HOST_BG`, `HOST_EXEC_SPOOL`) could not be read for their default
  *  without inverting twice in your head, and `projectMemoryDisabled` was the ONE negative boolean on a
  *  `ServiceConfig` that otherwise carries 16 positive `*Enabled`/`*Allowed` fields.
  *
- *  Resolution order (new name wins, so there is never an ambiguous both-set state):
+ *  🔴 3.0.0([1989],clay 令「不做兼容」):旧名不再有兼容窗——**设了就拒启**。这个函数保留 legacy 形参
+ *  不是为了继续读它,而正是为了**认出它在场并拒绝启动**(把墓碑放在唯一知道这对名字关系的地方)。
+ *
+ *  Resolution order:
  *   1. `X_ENABLED` set to a literal ⇒ that.
- *   2. `X_ENABLED` set to a non-literal ⇒ default + warning (the legacy name is NOT consulted — a typo in the
- *      new name must not silently hand control back to the deprecated one).
- *   3. `X_ENABLED` unset ∧ `X_DISABLED` set ⇒ the legacy site's exact contract, `X_DISABLED !== "true"`, plus a
- *      one-shot deprecation notice naming the replacement.
+ *   2. `X_ENABLED` set to a non-literal ⇒ default + warning (the tombstone is NOT consulted — a typo in the
+ *      new name must not turn into a boot refusal about an env the operator never set).
+ *   3. `X_ENABLED` unset ∧ `X_DISABLED` set(**任何值**,含 `"false"`)⇒ throw,文案指路新名。选拒启不选
+ *      静默忽略:静默会让升级部署的旧开关名义在、实际归默认——比拒启危险,且下游冒烟测试测不出来。
  *   4. neither ⇒ default. */
 export declare function boolEnvWithLegacyNegated(name: string, legacyNegatedName: string, def: boolean): boolean;
 /** LKG (last-known-good) persistence of the remote effective-config fetch. Read LAZILY at both main.ts sites
@@ -85,6 +90,18 @@ export declare const hostExecSpoolEnabled: () => boolean;
  *  is REMOVED (a spread-inherited value from a bigger-window base model would mis-trigger a small window).
  *  Shared by the env lane (main + cheap models) and the center lane (sema-registry toModel). */
 export declare function applyAutoCompactWindow(m: Model, explicit?: number): void;
+/** 组名 → 该组取景的平铺键(introspection 面:测试用它钉「每个平铺键恰好被一组取景」)。 */
+export declare const CONFIG_GROUP_KEYS: {
+    readonly [G in keyof ServiceConfigGroups]: readonly (keyof ServiceConfigFlat)[];
+};
+/** 把九个组视图挂到平铺配置上(**就地**,返回的就是同一个对象——视图必须看着这一个存储处)。
+ *
+ *  组键是**不可枚举**的:`Object.keys(config)` / `JSON.stringify(config)` / `{...config}` 的平铺面因此
+ *  逐字节不变(既有消费点、既有 dump/审计面零影响),代价是 spread 克隆不带组视图——克隆后要用组形,
+ *  再过一次本函数(读一个缺席的组是当场 TypeError,不会静默给旧值)。
+ *
+ *  `loadConfig` 是主调用点;测试夹具(test/helpers/make-config.ts)构造 `ServiceConfigFlat` 后同样过它。 */
+export declare function attachConfigGroups(flat: ServiceConfigFlat): ServiceConfig;
 export declare function loadConfig(): ServiceConfig;
 /** 有效监听绑址([1934])。**显式 `BIND_HOST`/`HOST` 恒生效**(operator 保留在任何形下明示暴露的
  *  权利);未显式时:**无鉴权写面 ⇒ 127.0.0.1**,其余 ⇒ undefined(Node 默认全接口,既有部署零影响)。