@sema-agent/server 1.315.0 → 1.317.0

package/README.md

@@ -147,6 +147,15 @@ The server is configured entirely through environment variables. The most import
 | `MODEL_IDLE_TIMEOUT_MS` | `300000` | Mid-stream idle timeout (`0` = off) |
 | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` (structured JSON logs) |
 
+**Boolean knobs** take exactly `true` or `false`. Any other value (`1`, `yes`, `TRUE`) is rejected with a
+`config_env_invalid_using_default` warning at boot and the knob keeps its default — so a mistyped switch is
+visible instead of silent. The default is not guessable from the name, so the server prints one
+`config_knob_polarity` line per knob at `LOG_LEVEL=debug`: name → polarity (`opt-in` = default OFF,
+`opt-out` = default ON, `posture` = derived from `REQUIRE_PRINCIPAL`) → effective value → where it came from.
+The table describes the knobs live in *this* configuration — a knob gated on an inactive lane (e.g.
+`K8S_INSECURE_TLS` outside the k8s provider, `E2B_ALLOW_NET` when unset) has no row, which means
+"not live here", not "off".
+
 The full surface — cost/quota ceilings, circuit breaker and failover, multi-model roles, approval
 gates, observability (Prometheus `/metrics` + optional OTLP), registry control plane, per-lane
 sandbox settings — is documented in [`USAGE.md`](USAGE.md).

package/README.zh-CN.md

@@ -140,6 +140,13 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | `MODEL_IDLE_TIMEOUT_MS` | `300000` | 流中 idle 超时(`0` 关) |
 | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error`(结构化 JSON 日志) |
 
+**布尔旋钮只认 `true` / `false` 两个字面量**。写成 `1`/`yes`/`TRUE` 会在启动时报一条
+`config_env_invalid_using_default` 警告并退回该旋钮的缺省值 —— 打错的开关会被看见,而不是静默失效。
+缺省值无法从名字推出,所以服务在 `LOG_LEVEL=debug` 下每个旋钮打一行 `config_knob_polarity`:
+名字 → 极性(`opt-in`=缺省关、`opt-out`=缺省开、`posture`=由 `REQUIRE_PRINCIPAL` 推导)→ 生效值 → 来源。
+该表描述**本配置下活着的旋钮**——挂在未激活通道上的旋钮(如非 k8s 通道下的 `K8S_INSECURE_TLS`、
+未设时的 `E2B_ALLOW_NET`)没有行,含义是「在这里不生效」,不是「关」。
+
 完整配置面 —— 成本/配额上限、断路器与 failover、多模型角色、审批门、可观测
 (Prometheus `/metrics` + 可选 OTLP)、registry 控制面、各沙箱通道细项 ——
 见 [`USAGE.md`](USAGE.md)。

package/dist/config-types.d.ts

@@ -221,7 +221,7 @@ export interface ServiceConfig {
     workflowRunStoreBackend: "auto" | "file" | "memory";
     workflowOrphanGraceMs: number;
     schedulerEnabled: boolean;
-    projectMemoryDisabled: boolean;
+    projectMemoryEnabled: boolean;
     schedulerStorePath?: string;
     configBootFetchBudgetMs: number;
     schedulerSessionWakeup: boolean;

package/dist/config.d.ts

@@ -13,7 +13,21 @@ export declare function drainConfigNotices(): Array<{
 }>;
 export declare function logConfigDiagnostics(logger: {
     warn: (event: string, fields?: Record<string, unknown>) => void;
+    debug?: (event: string, fields?: Record<string, unknown>) => void;
 }): void;
+type ConfigKnobSource = "env" | "legacy-env" | "posture" | "default";
+export interface ConfigKnobRecord {
+    name: string;
+    polarity: "opt-in" | "opt-out" | "posture";
+    value: boolean;
+    source: ConfigKnobSource;
+    legacyName?: string;
+}
+export declare function configKnobTable(): ConfigKnobRecord[];
+export declare function boolEnvWithLegacyNegated(name: string, legacyNegatedName: string, def: boolean): boolean;
+export declare const configLkgEnabled: () => boolean;
+export declare const hostBackgroundShellEnabled: () => boolean;
+export declare const hostExecSpoolEnabled: () => boolean;
 export declare function applyAutoCompactWindow(m: Model, explicit?: number): void;
 export declare function loadConfig(): ServiceConfig;
 export declare function resolveBindHost(config: {

package/dist/config.js

@@ -82,6 +82,17 @@ export function logConfigDiagnostics(logger) {
         logger.warn("config_env_invalid_using_default", { env: w.env, raw: w.raw });
     for (const n of drainConfigNotices())
         logger.warn(n.event, n.fields);
+    if (logger.debug) {
+        for (const k of configKnobTable()) {
+            logger.debug("config_knob_polarity", {
+                knob: k.name,
+                polarity: k.polarity,
+                value: k.value,
+                source: k.source,
+                ...(k.legacyName ? { legacyName: k.legacyName } : {}),
+            });
+        }
+    }
 }
 function firstSetEnv(...names) {
     for (const n of names) {
@@ -102,6 +113,71 @@ function optFinitePositiveEnv(name) {
     }
     return n;
 }
+const CONFIG_KNOBS = new Map();
+const KNOB_DEPRECATIONS_SEEN = new Set();
+export function configKnobTable() {
+    return [...CONFIG_KNOBS.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function registerKnob(rec) {
+    CONFIG_KNOBS.set(rec.name, rec);
+}
+function boolEnv(name, def) {
+    const raw = process.env[name];
+    let value = def;
+    let source = "default";
+    if (raw !== undefined && raw !== "") {
+        if (raw === "true") {
+            value = true;
+            source = "env";
+        }
+        else if (raw === "false") {
+            value = false;
+            source = "env";
+        }
+        else if (!CONFIG_KNOBS.has(name)) {
+            CONFIG_WARNINGS.push({ env: name, raw });
+        }
+    }
+    registerKnob({ name, polarity: def ? "opt-out" : "opt-in", value, source });
+    return value;
+}
+export function boolEnvWithLegacyNegated(name, legacyNegatedName, def) {
+    const raw = process.env[name];
+    const legacy = process.env[legacyNegatedName];
+    let value;
+    let source;
+    if (raw === "true" || raw === "false") {
+        value = raw === "true";
+        source = "env";
+    }
+    else if (raw !== undefined && raw !== "") {
+        if (!CONFIG_KNOBS.has(name)) {
+            CONFIG_WARNINGS.push({ env: name, raw });
+        }
+        value = def;
+        source = "default";
+    }
+    else if (legacy !== undefined && legacy !== "") {
+        value = legacy !== "true";
+        source = "legacy-env";
+        if (!KNOB_DEPRECATIONS_SEEN.has(legacyNegatedName)) {
+            KNOB_DEPRECATIONS_SEEN.add(legacyNegatedName);
+            CONFIG_NOTICES.push({
+                event: "config_env_deprecated_negated_name",
+                fields: { deprecated: legacyNegatedName, replacement: name, effective: String(value) },
+            });
+        }
+    }
+    else {
+        value = def;
+        source = "default";
+    }
+    registerKnob({ name, polarity: def ? "opt-out" : "opt-in", value, source, legacyName: legacyNegatedName });
+    return value;
+}
+export const configLkgEnabled = () => boolEnvWithLegacyNegated("CONFIG_LKG_ENABLED", "CONFIG_LKG_DISABLED", true);
+export const hostBackgroundShellEnabled = () => boolEnvWithLegacyNegated("HOST_BG_ENABLED", "HOST_BG_DISABLED", true);
+export const hostExecSpoolEnabled = () => boolEnvWithLegacyNegated("HOST_EXEC_SPOOL_ENABLED", "HOST_EXEC_SPOOL_DISABLED", true);
 function enumEnv(name, fallback, allowed) {
     const v = (process.env[name] ?? fallback);
     if (!allowed.includes(v))
@@ -164,15 +240,24 @@ export function applyAutoCompactWindow(m, explicit) {
 export function loadConfig() {
     CONFIG_WARNINGS.length = 0;
     CONFIG_NOTICES.length = 0;
+    CONFIG_KNOBS.clear();
+    KNOB_DEPRECATIONS_SEEN.clear();
     const gatewayBaseUrl = env("MODEL_GATEWAY_BASEURL", "http://127.0.0.1:8000/v1");
     const modelId = env("MODEL_ID", "Qwen3.5-35B");
-    const singleUserTurnkey = process.env.REQUIRE_PRINCIPAL !== "true";
-    const postureOn = (envVal, infraReady = true) => envVal === "true" ? true : envVal === "false" ? false : singleUserTurnkey && infraReady;
+    const requirePrincipal = boolEnv("REQUIRE_PRINCIPAL", false);
+    const singleUserTurnkey = !requirePrincipal;
+    const postureOn = (name, infraReady = true) => {
+        const envVal = process.env[name];
+        const explicit = envVal === "true" ? true : envVal === "false" ? false : undefined;
+        const value = explicit ?? (singleUserTurnkey && infraReady);
+        registerKnob({ name, polarity: "posture", value, source: explicit === undefined ? "posture" : "env" });
+        return value;
+    };
     const dbBackendSet = !!process.env.DB_BACKEND;
     const sqlSignal = (!!process.env.SESSION_BACKEND && process.env.SESSION_BACKEND !== "memory") ||
         !!(process.env.TIDB_HOST || process.env.MYSQL_HOST || process.env.PG_HOST);
     const bareBoot = !dbBackendSet && !sqlSignal;
-    const multiTenantBareBoot = bareBoot && process.env.REQUIRE_PRINCIPAL === "true";
+    const multiTenantBareBoot = bareBoot && requirePrincipal;
     const dbBackendRaw = enumEnv("DB_BACKEND", bareBoot ? (multiTenantBareBoot ? "memory" : "local") : "mysql", ["mysql", "tidb", "pg", "local", "memory"]);
     const dbBackend = dbBackendRaw === "tidb" ? "mysql" : dbBackendRaw;
     if (multiTenantBareBoot) {
@@ -197,7 +282,7 @@ export function loadConfig() {
         throw new Error(`WORKFLOW_SIZE_GUIDELINE must be small|medium|large|unrestricted, got "${workflowSizeGuidelineRaw}"`);
     }
     const workflowSizeGuideline = workflowSizeGuidelineRaw;
-    const memoryScope = process.env.MEMORY_SCOPE ?? (memoryEngineEnabled && process.env.REQUIRE_PRINCIPAL !== "true" ? "local" : undefined);
+    const memoryScope = process.env.MEMORY_SCOPE ?? (memoryEngineEnabled && !requirePrincipal ? "local" : undefined);
     const memorySyncUrl = process.env.MEMORY_SYNC_URL || undefined;
     const memorySyncToken = process.env.MEMORY_SYNC_TOKEN || undefined;
     const memorySyncScopeRaw = process.env.MEMORY_SYNC_SCOPE || undefined;
@@ -320,14 +405,14 @@ export function loadConfig() {
                 ? { model: cur, systemPrompt: CODE_AGENT_PROMPT }
                 : { ...cur, systemPrompt: CODE_AGENT_PROMPT };
     }
-    const directApprovalDoor = process.env.DIRECT_APPROVAL_DOOR === "true";
+    const directApprovalDoor = boolEnv("DIRECT_APPROVAL_DOOR", false);
     const principalJwtPubkeys = parsePrincipalJwks(process.env.PRINCIPAL_JWT_PUBKEYS);
     const principalJwtIss = process.env.PRINCIPAL_JWT_ISS || undefined;
     const principalJwtAud = process.env.PRINCIPAL_JWT_AUD || undefined;
     const principalJwtMaxTtlSec = Math.max(0, numEnv("PRINCIPAL_JWT_MAX_TTL_SEC", "120"));
     const dgHmacKeys = parseApprovalHmacKeys(process.env.APPROVAL_HMAC_KEYS);
     const dgOperators = csv("OPERATOR_PRINCIPALS");
-    const dgDurable = process.env.DURABLE_APPROVAL === "true";
+    const dgDurable = boolEnv("DURABLE_APPROVAL", false);
     const directDoorActive = directApprovalDoor && dgDurable && dgHmacKeys.length > 0 && principalJwtPubkeys.length > 0 && !!principalJwtIss && !!principalJwtAud;
     if (directApprovalDoor) {
         const missing = [];
@@ -343,7 +428,7 @@ export function loadConfig() {
             missing.push("PRINCIPAL_JWT_AUD");
         if (dgOperators.length === 0)
             missing.push("OPERATOR_PRINCIPALS (else isOperator is true-for-all)");
-        if (process.env.REQUIRE_PRINCIPAL !== "true")
+        if (!requirePrincipal)
             missing.push("REQUIRE_PRINCIPAL=true (a direct door is multi-tenant; without it an absent principal is anonymous and the spoofable header governs owner/quota checks)");
         if (missing.length) {
             throw new Error(`DIRECT_APPROVAL_DOOR=true but D-G anchors are missing: ${missing.join(", ")} — refusing to start a half-open direct door (design/80 D-G boot invariant)`);
@@ -356,12 +441,30 @@ export function loadConfig() {
         .map((s) => [s.slice(0, s.indexOf("=")).trim(), s.slice(s.indexOf("=") + 1).trim()])
         .filter(([tok, sys]) => tok.length > 0 && sys.length > 0));
     const bakeRunnerPrincipal = env("BAKE_RUNNER_PRINCIPAL", "system:bake-runner");
-    if (process.env.IMAGE_BAKES_ENABLED === "true" && dgOperators.length === 0) {
+    if (boolEnv("IMAGE_BAKES_ENABLED", false) && dgOperators.length === 0) {
         throw new Error("IMAGE_BAKES_ENABLED=true but OPERATOR_PRINCIPALS is empty — the bake door runs build.sh on the privileged build host; an empty operator set makes isOperator() true-for-all (world-writable RCE). Set OPERATOR_PRINCIPALS or disable bakes (IMAGE-API-DESIGN.md §P2.4a boot invariant)");
     }
-    if (process.env.IMAGE_BAKES_ENABLED === "true" && !Object.values(authTokens).includes(bakeRunnerPrincipal)) {
+    if (boolEnv("IMAGE_BAKES_ENABLED", false) && !Object.values(authTokens).includes(bakeRunnerPrincipal)) {
         throw new Error(`IMAGE_BAKES_ENABLED=true but no SERVICE_AUTH_TOKENS entry maps to the runner principal '${bakeRunnerPrincipal}' — the bake-runner authenticates by its credential (token-derived source), so a '<BAKE_RUNNER_TOKEN>=${bakeRunnerPrincipal}' SERVICE_AUTH_TOKENS entry is required or claim/ingest/heartbeat all 403 (IMAGE-API-DESIGN.md §P2.12 boot invariant)`);
     }
+    const projectMemoryEnabled = boolEnvWithLegacyNegated("PROJECT_MEMORY_ENABLED", "PROJECT_MEMORY_DISABLED", true);
+    configLkgEnabled();
+    hostBackgroundShellEnabled();
+    hostExecSpoolEnabled();
+    const lspHostEnabled = (() => {
+        const explicitHost = process.env.LSP_HOST_ENABLED;
+        if (explicitHost === undefined || explicitHost === "") {
+            if (process.env.LSP_ENABLED === "false") {
+                CONFIG_NOTICES.push({
+                    event: "config_env_deprecated_lane_alias",
+                    fields: { deprecated: "LSP_ENABLED=false", replacement: "LSP_HOST_ENABLED=false", lane: "host", effective: "false" },
+                });
+                registerKnob({ name: "LSP_HOST_ENABLED", polarity: "opt-out", value: false, source: "legacy-env", legacyName: "LSP_ENABLED" });
+                return false;
+            }
+        }
+        return boolEnv("LSP_HOST_ENABLED", true);
+    })();
     return {
         port: Number(env("PORT", "8090")),
         gatewayBaseUrl,
@@ -381,7 +484,7 @@ export function loadConfig() {
             connectTimeoutMs: Number(env("MODEL_CONNECT_TIMEOUT_MS", "30000")),
             firstTokenTimeoutMs: Number(env("MODEL_FIRST_TOKEN_TIMEOUT_MS", "120000")),
             idleTimeoutMs: Number(env("MODEL_IDLE_TIMEOUT_MS", "300000")),
-            circuitBreaker: process.env.MODEL_CIRCUIT_BREAKER === "true",
+            circuitBreaker: boolEnv("MODEL_CIRCUIT_BREAKER", false),
             failureThreshold: Number(env("MODEL_CB_FAILURE_THRESHOLD", "5")),
             cooldownMs: Number(env("MODEL_CB_COOLDOWN_MS", "30000")),
         },
@@ -410,7 +513,7 @@ export function loadConfig() {
                 ...(process.env.E2B_TEMPLATE ? { template: process.env.E2B_TEMPLATE } : {}),
                 ...(process.env.E2B_TIMEOUT_MS ? { timeoutMs: Number(process.env.E2B_TIMEOUT_MS) } : {}),
                 ...(process.env.E2B_LIVENESS_MS ? { livenessMs: Number(process.env.E2B_LIVENESS_MS) } : {}),
-                ...(process.env.E2B_ALLOW_NET ? { allowInternetAccess: process.env.E2B_ALLOW_NET !== "false" } : {}),
+                ...(process.env.E2B_ALLOW_NET ? { allowInternetAccess: boolEnv("E2B_ALLOW_NET", true) } : {}),
                 ...(process.env.E2B_SANDBOX_ENV ? { sandboxEnv: resolveEnvForward(process.env.E2B_SANDBOX_ENV) } : {}),
                 ...(process.env.E2B_MOUNT_PATH ? { mountPath: process.env.E2B_MOUNT_PATH } : {}),
             }
@@ -422,7 +525,7 @@ export function loadConfig() {
                         ...(process.env.K8S_API_URL ? { apiUrl: process.env.K8S_API_URL } : {}),
                         ...(process.env.K8S_TOKEN ? { token: process.env.K8S_TOKEN } : {}),
                         ...(process.env.K8S_CA_CERT_B64 ? { caCert: Buffer.from(process.env.K8S_CA_CERT_B64, "base64").toString("utf8") } : {}),
-                        ...(process.env.K8S_INSECURE_TLS === "true" ? { insecureTls: true } : {}),
+                        ...(boolEnv("K8S_INSECURE_TLS", false) ? { insecureTls: true } : {}),
                         ...(process.env.K8S_NAMESPACE ? { namespace: process.env.K8S_NAMESPACE } : {}),
                         ...(process.env.K8S_RUNTIME_CLASS != null ? { runtimeClass: process.env.K8S_RUNTIME_CLASS } : {}),
                         ...(process.env.K8S_MOUNT_PATH ? { mountPath: process.env.K8S_MOUNT_PATH } : {}),
@@ -479,7 +582,7 @@ export function loadConfig() {
                                                         ...(process.env.DOCKER_MEMORY ? { memory: process.env.DOCKER_MEMORY } : {}),
                                                         ...(process.env.DOCKER_CPUS ? { cpus: Number(process.env.DOCKER_CPUS) } : {}),
                                                         ...(process.env.DOCKER_PIDS_LIMIT ? { pidsLimit: Number(process.env.DOCKER_PIDS_LIMIT) } : {}),
-                                                        ...(process.env.DOCKER_DROP_CAPS === "true" ? { dropAllCaps: true } : {}),
+                                                        ...(boolEnv("DOCKER_DROP_CAPS", false) ? { dropAllCaps: true } : {}),
                                                         ...(process.env.DOCKER_NETWORK
                                                             ? { network: enumEnv("DOCKER_NETWORK", "bridge", ["none", "bridge", "host"]) }
                                                             : {}),
@@ -490,7 +593,7 @@ export function loadConfig() {
                                                         process.env.CONFIG_PROVIDER === "local"
                                                             ? { provider: "host" }
                                                             : undefined,
-        worktreeIsolation: process.env.WORKTREE_ISOLATION_ENABLED === "true" && process.env.WORKTREE_REPO_ROOT
+        worktreeIsolation: boolEnv("WORKTREE_ISOLATION_ENABLED", false) && process.env.WORKTREE_REPO_ROOT
             ? {
                 repoRoot: process.env.WORKTREE_REPO_ROOT,
                 ...(process.env.WORKTREE_ALLOWED_ROOTS
@@ -537,7 +640,7 @@ export function loadConfig() {
             }
             : undefined,
         snapshotBlobSqlMaxBytes: optFinitePositiveEnv("SNAPSHOT_BLOB_SQL_MAX_BYTES"),
-        snapshotBlobAllowSql: process.env.SNAPSHOT_BLOB_ALLOW_SQL_BYTES === "true",
+        snapshotBlobAllowSql: boolEnv("SNAPSHOT_BLOB_ALLOW_SQL_BYTES", false),
         pluginsAllowHosts: (process.env.PLUGINS_ALLOW_HOSTS ?? "github.com").split(",").map((h) => h.trim()).filter(Boolean),
         bindHost: process.env.BIND_HOST || process.env.HOST || undefined,
         attachmentOrphanGraceMs: ((v) => (v !== undefined && Number.isFinite(v) && v >= 0 ? v : 3_600_000))(process.env.ATTACHMENT_ORPHAN_GRACE_MS !== undefined ? Number(process.env.ATTACHMENT_ORPHAN_GRACE_MS) : undefined),
@@ -560,7 +663,7 @@ export function loadConfig() {
             : undefined,
         authToken: process.env.SERVICE_AUTH_TOKEN,
         authTokens,
-        allowUnauthedWrites: process.env.ALLOW_UNAUTHED_WRITES === "true",
+        allowUnauthedWrites: boolEnv("ALLOW_UNAUTHED_WRITES", false),
         metricsToken: process.env.METRICS_TOKEN || undefined,
         traceToken: process.env.TRACE_TOKEN || undefined,
         corsOrigins: (process.env.CORS_ORIGIN ?? "").split(",").map((s) => s.trim()).filter(Boolean),
@@ -570,15 +673,15 @@ export function loadConfig() {
             : {}),
         attachmentUnboundTtlMs: Math.max(60_000, numEnv("ATTACHMENT_UNBOUND_TTL_MS", String(24 * 3600 * 1000))),
         principalHeader: headerNameEnv("PRINCIPAL_HEADER", "x-agent-principal"),
-        requirePrincipal: process.env.REQUIRE_PRINCIPAL === "true",
+        requirePrincipal,
         autonomy: parseAutonomy(process.env.AUTONOMY),
         approvalRequire: csv("APPROVAL_REQUIRE"),
         operatorPrincipals: csv("OPERATOR_PRINCIPALS"),
         cascadeLadder: csv("MODEL_CASCADE_LADDER"),
         approvalDeny: csv("APPROVAL_DENY"),
         approvalPollMs: Number(env("APPROVAL_POLL_MS", "1500")),
-        durableApproval: process.env.DURABLE_APPROVAL === "true",
-        resourceSuspend: process.env.RESOURCE_SUSPEND === "true",
+        durableApproval: boolEnv("DURABLE_APPROVAL", false),
+        resourceSuspend: boolEnv("RESOURCE_SUSPEND", false),
         resourceSuspendTtlSec: Math.max(0, numEnv("RESOURCE_SUSPEND_TTL_SEC", "0")),
         approvalAutoBudget: Math.min(10000, Math.max(0, numEnv("APPROVAL_AUTO_BUDGET", "0"))),
         approvalNeverAuto: csv("APPROVAL_NEVER_AUTO"),
@@ -594,20 +697,20 @@ export function loadConfig() {
             sandboxSecMicroUsd: Math.max(0, numEnv("INFRA_COST_SANDBOX_SEC", "0")),
             egressGbMicroUsd: Math.max(0, numEnv("INFRA_COST_EGRESS_GB", "0")),
         },
-        leaderEnabled: process.env.LEADER_ENABLED === "true",
-        leaderFanoutEnabled: process.env.LEADER_FANOUT_ENABLED !== "false",
-        routerEnabled: process.env.ROUTER_ENABLED === "true",
-        selfOrchestrationEnabled: postureOn(process.env.SELF_ORCHESTRATION_ENABLED),
-        forkEnabled: postureOn(process.env.FORK_ENABLED),
-        experimentalObserverAgents: process.env.EXPERIMENTAL_OBSERVER_AGENTS === "true",
-        schedulerEnabled: postureOn(process.env.SCHEDULER_ENABLED),
-        projectMemoryDisabled: process.env.PROJECT_MEMORY_DISABLED === "true",
-        planModeEnabled: process.env.PLAN_MODE_ENABLED !== "false",
+        leaderEnabled: boolEnv("LEADER_ENABLED", false),
+        leaderFanoutEnabled: boolEnv("LEADER_FANOUT_ENABLED", true),
+        routerEnabled: boolEnv("ROUTER_ENABLED", false),
+        selfOrchestrationEnabled: postureOn("SELF_ORCHESTRATION_ENABLED"),
+        forkEnabled: postureOn("FORK_ENABLED"),
+        experimentalObserverAgents: boolEnv("EXPERIMENTAL_OBSERVER_AGENTS", false),
+        schedulerEnabled: postureOn("SCHEDULER_ENABLED"),
+        projectMemoryEnabled,
+        planModeEnabled: boolEnv("PLAN_MODE_ENABLED", true),
         ...(process.env.SCHEDULER_STORE_PATH ? { schedulerStorePath: process.env.SCHEDULER_STORE_PATH } : {}),
         configBootFetchBudgetMs: Math.max(0, numEnv("CONFIG_BOOT_FETCH_BUDGET_MS", "1500")),
-        schedulerSessionWakeup: process.env.SCHEDULER_SESSION_WAKEUP !== "false",
+        schedulerSessionWakeup: boolEnv("SCHEDULER_SESSION_WAKEUP", true),
         selfOrchestrationModels: csv("SELF_ORCHESTRATION_MODELS"),
-        selfOrchestrationWorkerIsolation: process.env.SELF_ORCHESTRATION_WORKER_ISOLATION === "true",
+        selfOrchestrationWorkerIsolation: boolEnv("SELF_ORCHESTRATION_WORKER_ISOLATION", false),
         workflowRunStoreBackend: enumEnv("WORKFLOW_RUN_STORE", "auto", ["auto", "file", "memory"]),
         workflowOrphanGraceMs: Math.max(60_000, numEnv("WORKFLOW_ORPHAN_GRACE_MS", String(24 * 60 * 60 * 1000))),
         workflowJournalRetentionMs: Math.max(60_000, numEnv("WORKFLOW_JOURNAL_RETENTION_MS", String(7 * 24 * 60 * 60 * 1000))),
@@ -620,9 +723,9 @@ export function loadConfig() {
         ...(process.env.SANDBOX_PKG_SOURCE !== "none"
             ? { sandboxPkgSource: process.env.SANDBOX_PKG_SOURCE || "global" }
             : {}),
-        sessionAutoTitle: process.env.SESSION_AUTO_TITLE !== "false",
-        selectEnvironmentTool: process.env.SELECT_ENVIRONMENT_TOOL !== "false",
-        envFactsEnabled: process.env.SANDBOX_ENV_FACTS !== "false",
+        sessionAutoTitle: boolEnv("SESSION_AUTO_TITLE", true),
+        selectEnvironmentTool: boolEnv("SELECT_ENVIRONMENT_TOOL", true),
+        envFactsEnabled: boolEnv("SANDBOX_ENV_FACTS", true),
         sensitiveWritePatterns: ((raw) => {
             if (raw === undefined)
                 return [...RECOMMENDED_SENSITIVE_PATTERNS];
@@ -634,13 +737,13 @@ export function loadConfig() {
         ...(process.env.MANUAL_MODE_SHELL_GATE === "always" || process.env.MANUAL_MODE_SHELL_GATE === "classify"
             ? { manualModeShellGate: process.env.MANUAL_MODE_SHELL_GATE }
             : {}),
-        toolDeferLongtail: process.env.TOOL_DEFER_LONGTAIL === "true",
-        lspEnabled: process.env.LSP_ENABLED === "true",
-        lspHostEnabled: process.env.LSP_ENABLED !== "false",
+        toolDeferLongtail: boolEnv("TOOL_DEFER_LONGTAIL", false),
+        lspEnabled: boolEnv("LSP_ENABLED", false),
+        lspHostEnabled,
         drainGraceMs: Math.max(10_000, numEnv("DRAIN_GRACE_MS", String(10 * 60 * 1000))),
         sighupIdleGraceMs: Math.max(5_000, numEnv("SIGHUP_IDLE_GRACE_MS", String(120_000))),
         mcpElicitation: {
-            enabled: process.env.MCP_ELICITATION_ENABLED === "true",
+            enabled: boolEnv("MCP_ELICITATION_ENABLED", false),
             throttle: {
                 maxConcurrentPerRun: numEnvBounded("MCP_ELICITATION_MAX_CONCURRENT", String(DEFAULT_ELICITATION_THROTTLE.maxConcurrentPerRun), 1, 64),
                 maxTotalPerRun: numEnvBounded("MCP_ELICITATION_MAX_TOTAL", String(DEFAULT_ELICITATION_THROTTLE.maxTotalPerRun), 1, 10_000),
@@ -648,11 +751,11 @@ export function loadConfig() {
                 ttlMs: numEnvBounded("MCP_ELICITATION_TTL_MS", String(DEFAULT_ELICITATION_THROTTLE.ttlMs), 1_000, 3_600_000),
             },
         },
-        askQuestionEnabled: postureOn(process.env.ASK_QUESTION_ENABLED),
-        toolApprovalEnabled: postureOn(process.env.TOOL_APPROVAL_ENABLED),
-        workflowAgentsReadOnly: process.env.WORKFLOW_AGENTS_READONLY === "true",
+        askQuestionEnabled: postureOn("ASK_QUESTION_ENABLED"),
+        toolApprovalEnabled: postureOn("TOOL_APPROVAL_ENABLED"),
+        workflowAgentsReadOnly: boolEnv("WORKFLOW_AGENTS_READONLY", false),
         imageBakes: {
-            enabled: process.env.IMAGE_BAKES_ENABLED === "true",
+            enabled: boolEnv("IMAGE_BAKES_ENABLED", false),
             runnerPrincipal: bakeRunnerPrincipal,
             registry: process.env.BAKE_IMAGE_REGISTRY || null,
             cacheBase: process.env.BAKE_CACHE_BASE || null,
@@ -662,8 +765,8 @@ export function loadConfig() {
             submitRateMax: Math.max(0, numEnv("BAKE_SUBMIT_RATE_MAX", "10")),
             submitRateWindowSec: Math.max(1, numEnv("BAKE_SUBMIT_RATE_WINDOW_SEC", "60")),
         },
-        toolTrace: process.env.TOOL_TRACE === "true",
-        traceThinking: process.env.TRACE_THINKING !== "false",
+        toolTrace: boolEnv("TOOL_TRACE", false),
+        traceThinking: boolEnv("TRACE_THINKING", true),
         logLevel: env("LOG_LEVEL", "info"),
         rateLimitPerMin: numEnv("RATE_LIMIT_RPM", "0"),
         maxTaskCostUsd: numEnv("MAX_TASK_COST_USD", "0"),
@@ -674,11 +777,11 @@ export function loadConfig() {
             ? {
                 to: env("MODEL_DEGRADE_TO"),
                 atCostFraction: Number(env("MODEL_DEGRADE_AT_COST_FRACTION", "0.7")),
-                reactive: process.env.MODEL_DEGRADE_REACTIVE === "true",
+                reactive: boolEnv("MODEL_DEGRADE_REACTIVE", false),
                 downgradeOn: csv("MODEL_DEGRADE_ON").length
                     ? csv("MODEL_DEGRADE_ON")
                     : undefined,
-                toSupportsImages: process.env.MODEL_DEGRADE_TO_VISION === "true",
+                toSupportsImages: boolEnv("MODEL_DEGRADE_TO_VISION", false),
             }
             : undefined,
         otel: process.env.OTEL_EXPORTER_OTLP_ENDPOINT

package/dist/elicitation.js

@@ -129,10 +129,10 @@ export class ElicitationCoordinator {
     respond(id, principal, body) {
         const parsed = parseElicitationResponse(body);
         if (!parsed.ok)
-            return { status: 400, body: { error: parsed.error } };
+            return { status: 400, body: { error: parsed.error, errorCode: "request.body_shape" } };
         const entry = this.pending.get(id);
         if (!entry || (entry.owner !== null && entry.owner !== principal)) {
-            return { status: 404, body: { error: "no pending elicitation for this id (answered, expired, or not on this replica)" } };
+            return { status: 404, body: { error: "no pending elicitation for this id (answered, expired, or not on this replica)", errorCode: "elicitation.not_pending" } };
         }
         entry.settle(parsed.value);
         return { status: 200, body: { elicitationId: id, delivery: "applied", action: parsed.value.action } };

package/dist/http/idempotency.d.ts

@@ -9,4 +9,5 @@ export declare class IdempotencyCache<T> {
     private live;
     private maybeSweep;
 }
+export declare function scopedIdempotencyKey(raw: string | undefined, source: string | null, principal: string | undefined): string | undefined;
 //# sourceMappingURL=idempotency.d.ts.map

package/dist/http/idempotency.js

@@ -46,4 +46,7 @@ export class IdempotencyCache {
                 this.entries.delete(k);
     }
 }
+export function scopedIdempotencyKey(raw, source, principal) {
+    return raw ? `${source ?? ""}\x1f${principal ?? ""}\x1f${raw}` : undefined;
+}
 //# sourceMappingURL=idempotency.js.map

package/dist/http/principal-gate.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage } from "node:http";
+import type { ServiceConfig } from "../config-types.js";
+export declare function headerStr(v: string | string[] | undefined): string | undefined;
+export declare function safeEqual(a: string, b: string): boolean;
+export declare function authorized(req: IncomingMessage, token: string): boolean;
+export declare function systemFor(req: IncomingMessage, config: ServiceConfig): string | null | undefined;
+export declare function bearerPresentedButUnverified(req: IncomingMessage, config: ServiceConfig): boolean;
+export declare function gatedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
+export declare function explicitOperatorOk(principal: string | undefined, operatorPrincipals: readonly string[]): boolean;
+export declare function isOperator(principal: string | undefined, operatorPrincipals: readonly string[]): boolean;
+export declare function explicitOperator(principal: string | undefined, operatorPrincipals: readonly string[]): boolean;
+//# sourceMappingURL=principal-gate.d.ts.map

package/dist/http/principal-gate.js

@@ -0,0 +1,52 @@
+import { timingSafeEqual } from "node:crypto";
+import { verifiedPrincipal, ssoVerifiedPrincipal } from "../security.js";
+export function headerStr(v) {
+    return Array.isArray(v) ? v[0] : v;
+}
+export function safeEqual(a, b) {
+    const ab = Buffer.from(a, "utf8");
+    const bb = Buffer.from(b, "utf8");
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+export function authorized(req, token) {
+    const h = req.headers.authorization ?? "";
+    return safeEqual(h, `Bearer ${token}`) || safeEqual(h, `token ${token}`);
+}
+export function systemFor(req, config) {
+    for (const [tok, system] of Object.entries(config.authTokens ?? {})) {
+        if (authorized(req, tok))
+            return system;
+    }
+    if (config.authToken && authorized(req, config.authToken))
+        return null;
+    return undefined;
+}
+export function bearerPresentedButUnverified(req, config) {
+    const h = req.headers.authorization;
+    if (typeof h !== "string" || !/^(Bearer|token) /i.test(h))
+        return false;
+    if (ssoVerifiedPrincipal(req))
+        return false;
+    if (systemFor(req, config) !== undefined)
+        return false;
+    if (config.traceToken && authorized(req, config.traceToken))
+        return false;
+    return true;
+}
+export function gatedPrincipal(req, config) {
+    if (bearerPresentedButUnverified(req, config))
+        return undefined;
+    return verifiedPrincipal(req, config);
+}
+export function explicitOperatorOk(principal, operatorPrincipals) {
+    return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
+}
+export function isOperator(principal, operatorPrincipals) {
+    if (operatorPrincipals.length === 0)
+        return true;
+    return principal !== undefined && operatorPrincipals.includes(principal);
+}
+export function explicitOperator(principal, operatorPrincipals) {
+    return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
+}
+//# sourceMappingURL=principal-gate.js.map

package/dist/http/route-ctx.d.ts

@@ -0,0 +1,116 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { TaskStream, TaskSpec, TaskResult, QuestionAnswer, CheckpointToken, ResumeOutcome } from "@sema-agent/core";
+import type { FlatServiceDeps, RequestAuth } from "./server.js";
+import type { TaskRequestBody, DecideBinding } from "./wire-types.js";
+import type { IdempotencyCache } from "./idempotency.js";
+import type { ImagesLocal } from "./routes/images.js";
+import type { SessionsLocal } from "./routes/sessions.js";
+import type { SessionSyncLocal } from "./routes/session-sync.js";
+export interface RunRegistry {
+    idemCache: IdempotencyCache<{
+        status: number;
+        body: unknown;
+    }>;
+    inflightRuns: Map<string, AbortController>;
+    preemptableRuns: Map<string, AbortController>;
+    cancelledViaVerb: Set<string>;
+    steerableRuns: Map<string, TaskStream>;
+    wakeParkMints: Map<string, Promise<void>>;
+    counters: {
+        uncountedBillableInflight: number;
+        admittedInflight: number;
+    };
+}
+export interface RouteHelpers {
+    readJson(req: IncomingMessage): Promise<unknown>;
+    readRawBody(req: IncomingMessage, max: number): Promise<Buffer>;
+    rateLimited(req: IncomingMessage, res: ServerResponse): boolean;
+    quotaExceeded(req: IncomingMessage, res: ServerResponse): boolean;
+    leaseDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+    safeDecode(seg: string): string | null;
+    isFleetWide(req: IncomingMessage): boolean;
+    runOwnerOk(req: IncomingMessage, res: ServerResponse, owner: string | null): boolean;
+    sessionOwnerScope(req: IncomingMessage): {
+        fleetWide: boolean;
+        gateOwner: string | null;
+    };
+    sessionOwnerScopeForWrite(req: IncomingMessage): {
+        fleetWide: boolean;
+        gateOwner: string | null;
+    };
+    runSessionAcceptOk(req: IncomingMessage, res: ServerResponse, run: {
+        sessionId: string | null;
+    }, face: string, notFoundError?: string): boolean;
+}
+export interface RouteLocals {
+    images: ImagesLocal;
+    sessions: SessionsLocal;
+    sessionSync: SessionSyncLocal;
+}
+export interface RouteRequestState {
+    streamTaskId: string | undefined;
+    streamDetached: boolean;
+    source: string | null;
+}
+export interface RouteLegs {
+    prepareSpec(req: IncomingMessage, res: ServerResponse): Promise<{
+        spec: TaskSpec;
+        auth?: RequestAuth;
+        verify?: {
+            maxRounds: number;
+            costCeilingMicroUsd?: number;
+        };
+        cascade?: boolean;
+        jobId?: string;
+        body: TaskRequestBody;
+    } | null>;
+    finalizeTaskResult(result: TaskResult, principal: string | undefined, objective: string, sessionId: string | undefined): void;
+    resumeCheckpoint(sessionId: string, decision: "approve" | "deny", reason: string | undefined, req?: IncomingMessage, answer?: QuestionAnswer, binding?: DecideBinding, onResumeCommitted?: (overrideSessionId?: string) => Promise<void>): Promise<{
+        status: number;
+        body: object;
+    }>;
+    driveResumeIntoRunLog(args: {
+        token: CheckpointToken;
+        sessionId: string;
+        principal: string | undefined;
+        fleetScope: string;
+        taskConfig: Omit<TaskSpec, "objective" | "sessionId">;
+        resumeObjective: string;
+        outcome: ResumeOutcome;
+        verifyRounds: {
+            maxRounds: number;
+            costCeilingMicroUsd?: number;
+        } | undefined;
+        onResumeCommitted?: () => Promise<void>;
+    }): Promise<{
+        status: number;
+        body: object;
+    }>;
+    resumePreempted(sessionId: string, req: IncomingMessage | undefined): Promise<{
+        status: number;
+        body: object;
+    }>;
+    resumeWake(sessionId: string, message: string | undefined, caller: string | undefined, req: IncomingMessage | undefined): Promise<{
+        status: number;
+        body: object;
+    }>;
+    resumePlanReview(sessionId: string, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, req: IncomingMessage | undefined): Promise<{
+        status: number;
+        body: object;
+    }>;
+}
+export interface RouteCtxBase {
+    deps: FlatServiceDeps;
+    registry: RunRegistry;
+    helpers: RouteHelpers;
+    local: RouteLocals;
+    legs: RouteLegs;
+}
+export interface RouteCtx extends RouteCtxBase {
+    req: RouteRequestState;
+}
+export type RouteHandler = (req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx) => Promise<boolean>;
+export interface RouteMiss {
+    fell: boolean;
+}
+//# sourceMappingURL=route-ctx.d.ts.map