@sema-agent/server 1.322.0 → 2.0.0

package/dist/config.d.ts

@@ -1,7 +1,15 @@
 import { type Model } from "@sema-agent/core";
 import type { Autonomy } from "./runtime-governance.js";
 import type { ServiceConfig } 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";
+/** 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
+ *  config overlay (sema-registry.ts `applyRuntimeHot`) can re-derive the ENV BASELINE to revert to when center
+ *  stops managing `autonomy` (a stale center override must not stick — see applyRuntimeHot). */
 export declare function parseAutonomy(raw: string | undefined): Autonomy | undefined;
 export declare function drainConfigWarnings(): Array<{
     env: string;
@@ -11,25 +19,81 @@ export declare function drainConfigNotices(): Array<{
     event: string;
     fields: Record<string, string>;
 }>;
+/** F10 (codex audit): drain + log BOTH pre-logger diagnostic collectors (S20 soft-knob warnings + [792]④ boot
+ *  notices) in one place. EVERY entrypoint that calls loadConfig() then builds a logger must call this right
+ *  after (main.ts, run-local.ts) — a new entry that forgets it would silently drop operator-facing diagnostics
+ *  (run-local historically did exactly that), so the drain lives beside the collectors, not in one entrypoint. */
 export declare function logConfigDiagnostics(logger: {
     warn: (event: string, fields?: Record<string, unknown>) => void;
     debug?: (event: string, fields?: Record<string, unknown>) => void;
 }): void;
+/** design/158 N8/N9 — the BOOLEAN member of this module's env-parser family (`env`/`env2`/`numEnv`/
+ *  `numEnvBounded`/`optFinitePositiveEnv`/`enumEnv`/`headerNameEnv`/`firstSetEnv`). Until now booleans were the
+ *  one type parsed by a hand-written literal comparison at every single site, and that is exactly why the same
+ *  `*_ENABLED` suffix grew FOUR incompatible polarities (opt-in `=== "true"`, opt-out `!== "false"`, the posture
+ *  tri-state, and negative `*_DISABLED` names): with no shared helper there was nowhere for the default to be
+ *  stated, so it was re-invented per line and the suffix stopped predicting anything.
+ *
+ *  Semantics are the two dialects' semantics VERBATIM — an opt-in knob is `boolEnv(x, false)`, an opt-out knob is
+ *  `boolEnv(x, true)` — so this migration is value-preserving on every input. The one addition: a value that is
+ *  neither literal (`1`, `yes`, `TRUE`) still lands on the knob's default (as before) but now raises a config
+ *  warning instead of being swallowed, which is the whole failure mode operators kept hitting (`LSP_ENABLED=1`
+ *  reads as "on" to a human and as "off" to `=== "true"`).
+ *
+ *  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";
 export interface ConfigKnobRecord {
+    /** The CANONICAL env name (the positive one — a legacy alias appears in `legacyName`, never here). */
     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.
+ *
+ *  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):
+ *   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.
+ *   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
+ *  rather than lifted onto `ServiceConfig`, so this stays a pure env knob; `loadConfig` pre-registers it (below)
+ *  so its polarity row and any deprecation notice appear at boot with everything else. */
 export declare const configLkgEnabled: () => boolean;
+/** The `host` exec lane's background-shell capability kill switch (read per capability probe in remote-env-host.ts). */
 export declare const hostBackgroundShellEnabled: () => boolean;
+/** The `host` exec lane's spool-file stdio form; false ⇒ the pre-1.226 pipe fallback (read per exec). */
 export declare const hostExecSpoolEnabled: () => boolean;
+/** [818]① 1M dual-window derivation (core 1.289 `Model.autoCompactTokens`): an EXPLICIT positive value wins
+ *  (a center roster may declare its own); else contextWindow>=1e6 derives the CC-aligned 967000; else the field
+ *  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;
 export declare function loadConfig(): ServiceConfig;
+/** 有效监听绑址([1934])。**显式 `BIND_HOST`/`HOST` 恒生效**(operator 保留在任何形下明示暴露的
+ *  权利);未显式时:**无鉴权写面 ⇒ 127.0.0.1**,其余 ⇒ undefined(Node 默认全接口,既有部署零影响)。
+ *
+ *  为什么缺省要自己收窄、而不是只加旋钮:桌面形的安全结论原本写着「safe ONLY because HOST is
+ *  pinned to 127.0.0.1」,而那个前提在本仓从未成立(HOST 零消费)——把一个没人实现的假设当防线,
+ *  是「沉默陷阱」。零凭证 + 全接口 + host lane(用户真机非沙箱)= 同网段任意执行,缺省必须安全。
+ *  "无鉴权写面" 的判据与 http 层 503 fail-closed 门同源:allowUnauthedWrites 且**完全没有**凭证
+ *  (半配=凭证必须使用,不算无鉴权)。 */
 export declare function resolveBindHost(config: {
     bindHost?: string;
     allowUnauthedWrites?: boolean;