@a1hvdy/cc-openclaw 0.8.0 → 0.9.0

package/dist/src/index.d.ts

@@ -10,6 +10,7 @@
  * injection must run BEFORE any session start so the cwd is already
  * adjusted by the time engines spawn. All others are order-independent.
  */
+import { getConfigService } from './lib/config-service.js';
 export declare const PLUGIN_ID = "cc-openclaw";
 export declare const VERSION = "0.1.0";
 /**
@@ -36,6 +37,7 @@ export interface PluginApi {
         stop: () => Promise<void> | void;
     }): void;
 }
+export { getConfigService };
 /**
  * Top-level plugin entry. Idempotent — re-calls are no-op.
  * Guard centralized via defaultRegisterGuard (P2 cco-hardening).
@@ -43,6 +45,13 @@ export interface PluginApi {
 export declare function register(api: PluginApi): void;
 /** Test-only helper to reset top-level registration state. */
 export declare function _resetRegisteredForTests(): void;
+/**
+ * Test-only helper to reset the ConfigService singleton. Each test that
+ * mutates `process.env` and re-invokes `register()` should call this first
+ * so the config is re-parsed with the test's env, not the cached value
+ * from a prior test. Also exported from `lib/config-service.ts` directly.
+ */
+export declare function _resetConfigServiceForTests(): void;
 export type { ChannelAdapter, ChannelMessage, ChannelInbound, ChannelButton } from './channels/adapter.js';
 export { registerChannelAdapter } from './channels/adapter.js';
-export { selectEngine, captureSessionRoute, type Engine, type SessionRoute } from './lib/route-flag.js';
+export { selectEngine, captureSessionRoute, type Engine, type SessionRoute } from './lib/config-service.js';

package/dist/src/index.js

@@ -11,7 +11,8 @@
  * adjusted by the time engines spawn. All others are order-independent.
  */
 import { defaultRegisterGuard } from './lib/register-guard.js';
-import { selectEngine } from './lib/route-flag.js';
+import { ConfigService, setConfigService, getConfigService, selectEngine, _resetConfigServiceForTests as _resetConfigSingleton, } from './lib/config-service.js';
+import { ConfigError, RuntimeMode } from './types/runtime-config.js';
 import { wrapApiWithDebugTap } from './lib/debug-tap.js';
 import { register as registerCommandRouter } from './command-router/index.js';
 import { registerCwdPatch, registerSyspromptStrip, registerThinkConflictResolver, } from './session-bootstrap/index.js';
@@ -32,9 +33,11 @@ export const VERSION = '0.1.0';
  * To activate: set OPENCLAW_CC_OPENCLAW_LISTENERS=1 AND remove
  * savvy-claude-code from openclaw.json plugins.allow (mutual exclusion).
  *
- * This is separate from OPENCLAW_USE_CC_OPENCLAW (the route-flag),
- * which decides per-session engine routing at session-create time.
- * LISTENERS controls whether cc-openclaw wires its handlers at all.
+ * This is separate from OPENCLAW_CC_OPENCLAW_ACTIVE (or its deprecated
+ * alias OPENCLAW_USE_CC_OPENCLAW), which decides per-session engine
+ * routing — see `selectEngine()` in `lib/config-service.ts`. LISTENERS
+ * controls whether cc-openclaw wires its handlers at all; the two are
+ * orthogonal contracts (ARCHITECTURE.md §3).
  */
 function listenersEnabled() {
     const v = process.env.OPENCLAW_CC_OPENCLAW_LISTENERS;
@@ -43,14 +46,41 @@ function listenersEnabled() {
     const norm = v.toLowerCase();
     return norm === '1' || norm === 'true' || norm === 'on';
 }
+// Re-export getConfigService from config-service.ts for callers that import
+// from the plugin entry point. The actual singleton lives in config-service.ts
+// to avoid a circular import with src/lib/config.ts (which now reads from it).
+export { getConfigService };
 /**
  * Top-level plugin entry. Idempotent — re-calls are no-op.
  * Guard centralized via defaultRegisterGuard (P2 cco-hardening).
  */
 export function register(api) {
     defaultRegisterGuard.guard('cc-openclaw/index', api, () => {
-        const initialEngine = selectEngine();
         const logger = api.logger || console;
+        // ── Cluster A step 3+7: ConfigService boot wiring ─────────────────────
+        // Parse env into typed RuntimeConfig + install as the module-level
+        // singleton consumed by src/lib/config.ts getters (compat shim).
+        // Soft-fail during v0.9.x compat window — existing env readers still
+        // work when ConfigService is undefined. Hard-fail deferred until v1.0.
+        try {
+            const svc = ConfigService.fromEnv(process.env);
+            setConfigService(svc);
+            const cfg = svc.config;
+            logger.info(`[cc-openclaw] config: mode=${cfg.mode} cacheParity={module:${cfg.cacheParityModuleEnabled},trackB:${cfg.cacheParityTrackB}} tokenTelemetry={routeGate:${cfg.tokenTelemetryRouteGate},writer:${cfg.tokenTelemetryWriter}} testMode=${cfg.testMode}`);
+            if (cfg.usedDeprecatedAlias) {
+                logger.warn('[cc-openclaw] DEPRECATION: OPENCLAW_USE_CC_OPENCLAW is the legacy activation flag. Set OPENCLAW_CC_OPENCLAW_ACTIVE=1 instead. The alias is retained through v0.9.x and removed at v1.0.0.');
+            }
+            if (cfg.mode === RuntimeMode.PASSIVE) {
+                // No-op — passive mode is the default and announced by the
+                // existing passive-load message below. Avoids double-logging.
+            }
+        }
+        catch (err) {
+            const e = err instanceof ConfigError ? err.message : String(err);
+            logger.warn(`[cc-openclaw] ConfigService.fromEnv() failed during boot — continuing with legacy env readers (compat shim window): ${e}`);
+            setConfigService(undefined);
+        }
+        const initialEngine = selectEngine();
         logger.info(`[cc-openclaw] plugin loaded; route flag selects: ${initialEngine}`);
         if (!listenersEnabled()) {
             logger.info('[cc-openclaw] passive load — listeners gated. To activate: set OPENCLAW_CC_OPENCLAW_LISTENERS=1 AND remove savvy-claude-code from openclaw.json plugins.allow (else handlers collide).');
@@ -82,7 +112,17 @@ export function register(api) {
 export function _resetRegisteredForTests() {
     defaultRegisterGuard._resetForTests();
 }
+/**
+ * Test-only helper to reset the ConfigService singleton. Each test that
+ * mutates `process.env` and re-invokes `register()` should call this first
+ * so the config is re-parsed with the test's env, not the cached value
+ * from a prior test. Also exported from `lib/config-service.ts` directly.
+ */
+export function _resetConfigServiceForTests() {
+    _resetConfigSingleton();
+}
 export { registerChannelAdapter } from './channels/adapter.js';
-// Re-export route-flag types so callers can compose engine routing without a circular import.
-export { selectEngine, captureSessionRoute } from './lib/route-flag.js';
+// Re-export engine routing primitives. Originally lived in lib/route-flag.ts;
+// collapsed into config-service.ts at Cluster A step 8 (route-flag.ts deleted).
+export { selectEngine, captureSessionRoute } from './lib/config-service.js';
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/config-service.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Cluster A — ConfigService.
+ *
+ * The single source of truth for runtime configuration. Parses
+ * `process.env` into a frozen `RuntimeConfig` at boot, exposes two
+ * narrow escape hatches that preserve the live-read vs frozen-snapshot
+ * asymmetry currently encoded in `src/lib/route-flag.ts:48,63`.
+ *
+ * Compat-shim window (v0.9.x): existing `src/lib/config.ts` getters
+ * delegate here once Cluster A migration step 6 lands. Direct `process.env`
+ * reads are removed in step 7 (the final Cluster A commit) when
+ * `src/lib/route-flag.ts` collapses into `selectEngine()` /
+ * `captureSessionRoute()` below.
+ *
+ * NOT yet wired into `src/index.ts` — that's Cluster A migration step 3.
+ */
+import { type RuntimeConfig, type ParseEnvResult } from '../types/runtime-config.js';
+/**
+ * Parse `process.env` into a `RuntimeConfig`. Total function — never
+ * throws. Use the discriminated `ParseEnvResult` to handle failure.
+ *
+ * Behavior preservation contract: every `process.env.X` read here MUST
+ * match the semantic of the corresponding getter in `src/lib/config.ts`.
+ * The two dual-default flags (`OPENCLAW_TOKEN_TELEMETRY`,
+ * `OPENCLAW_CACHE_PARITY`) are split into two fields each — see
+ * `src/types/runtime-config.ts` schema comments.
+ */
+export declare function parseEnv(env: NodeJS.ProcessEnv): ParseEnvResult;
+export type Engine = 'cc-openclaw' | 'claude-local';
+export interface SessionRoute {
+    readonly engine: Engine;
+    readonly capturedAt: string;
+}
+/** Primary activation env var (PRP_v3 §10). */
+export declare const ACTIVE_FLAG_ENV = "OPENCLAW_CC_OPENCLAW_ACTIVE";
+/**
+ * @deprecated Use `ACTIVE_FLAG_ENV`. Read for fallback when the new name
+ * is unset. Removed in v1.0.0.
+ */
+export declare const ROUTE_FLAG_ENV = "OPENCLAW_USE_CC_OPENCLAW";
+/**
+ * Read env at call time and report whether cc-openclaw engine routing is
+ * active. **Independent of `LISTENERS`** — per ARCHITECTURE.md §3, engine
+ * selection (per-session) and handler wiring (process-wide) are orthogonal:
+ * a session can pick the cc-openclaw engine even when LISTENERS is off.
+ *
+ * Honors deprecated `OPENCLAW_USE_CC_OPENCLAW` fallback when the new
+ * ACTIVE_FLAG_ENV is unset.
+ *
+ * Free-function variant — works without a ConfigService instance.
+ */
+export declare function isCcOpenclawEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Free-function variant of `ConfigService.prototype.selectEngine()`.
+ * Re-reads env at call time. Use when you don't have a ConfigService instance
+ * (i.e. early boot, or in tests) — semantics match the instance method exactly.
+ *
+ * **Only reads `ACTIVE_FLAG_ENV` / deprecated alias.** Does NOT consider
+ * `LISTENERS` — that flag controls handler wiring, not engine selection.
+ * The higher-level `RuntimeMode` enum (which classifies the whole-process
+ * activation state) is computed separately by `deriveMode`.
+ */
+export declare function selectEngine(env?: NodeJS.ProcessEnv): Engine;
+/**
+ * Free-function variant of `ConfigService.prototype.captureSessionRoute()`.
+ * Returns a frozen snapshot — subsequent env mutations do NOT affect the
+ * captured route. This is what makes "in-flight sessions stay on original
+ * engine" architecturally true at the routing layer.
+ */
+export declare function captureSessionRoute(env?: NodeJS.ProcessEnv): SessionRoute;
+/**
+ * ConfigService wraps the parsed config with the live-read escape hatches
+ * that preserve `route-flag.ts:48,63` semantics.
+ *
+ * - `config`: frozen at construction; reads return boot-time values.
+ * - `selectEngine()`: re-reads `process.env` on every call. Use when picking
+ *   an engine for a NEW session — lets a rollback flip take effect mid-process
+ *   without restart.
+ * - `captureSessionRoute()`: snapshots the current engine into a frozen
+ *   object. Use at session-start to lock the engine for that session's
+ *   lifetime — lets in-flight sessions ride out a rollback unaffected.
+ */
+export declare class ConfigService {
+    readonly config: Readonly<RuntimeConfig>;
+    constructor(config: Readonly<RuntimeConfig>);
+    /**
+     * Re-reads env at call time. Use for new-session engine selection.
+     * Asymmetric with `config.activeRouting` (frozen at boot) BY DESIGN —
+     * see PRP §5 Cluster A "Frozen + escape-hatch contract".
+     *
+     * Delegates to the module-level `selectEngine` free function so that
+     * the class API and free-function API share one implementation.
+     */
+    selectEngine(env?: NodeJS.ProcessEnv): Engine;
+    /**
+     * Snapshot the current engine for a new session. Frozen — subsequent
+     * env mutations do NOT affect the captured route. Delegates to the
+     * free function for the same single-source-of-truth reason.
+     */
+    captureSessionRoute(env?: NodeJS.ProcessEnv): Readonly<SessionRoute>;
+    /** Convenience constructor for boot path. */
+    static fromEnv(env?: NodeJS.ProcessEnv): ConfigService;
+}
+export declare function getConfigService(): ConfigService | undefined;
+export declare function setConfigService(svc: ConfigService | undefined): void;
+export declare function _resetConfigServiceForTests(): void;

package/dist/src/lib/config-service.js

@@ -0,0 +1,217 @@
+/**
+ * Cluster A — ConfigService.
+ *
+ * The single source of truth for runtime configuration. Parses
+ * `process.env` into a frozen `RuntimeConfig` at boot, exposes two
+ * narrow escape hatches that preserve the live-read vs frozen-snapshot
+ * asymmetry currently encoded in `src/lib/route-flag.ts:48,63`.
+ *
+ * Compat-shim window (v0.9.x): existing `src/lib/config.ts` getters
+ * delegate here once Cluster A migration step 6 lands. Direct `process.env`
+ * reads are removed in step 7 (the final Cluster A commit) when
+ * `src/lib/route-flag.ts` collapses into `selectEngine()` /
+ * `captureSessionRoute()` below.
+ *
+ * NOT yet wired into `src/index.ts` — that's Cluster A migration step 3.
+ */
+import { RuntimeConfigSchema, RuntimeMode, ConfigError, deriveMode, } from '../types/runtime-config.js';
+const TRUTHY = (v) => v === '1' || v?.toLowerCase() === 'true' || v?.toLowerCase() === 'on';
+const FALSEY = (v) => v === '0' || v?.toLowerCase() === 'false' || v?.toLowerCase() === 'off';
+/**
+ * Parse `process.env` into a `RuntimeConfig`. Total function — never
+ * throws. Use the discriminated `ParseEnvResult` to handle failure.
+ *
+ * Behavior preservation contract: every `process.env.X` read here MUST
+ * match the semantic of the corresponding getter in `src/lib/config.ts`.
+ * The two dual-default flags (`OPENCLAW_TOKEN_TELEMETRY`,
+ * `OPENCLAW_CACHE_PARITY`) are split into two fields each — see
+ * `src/types/runtime-config.ts` schema comments.
+ */
+export function parseEnv(env) {
+    const mode = deriveMode(env);
+    const usedDeprecatedAlias = env.OPENCLAW_CC_OPENCLAW_ACTIVE === undefined &&
+        env.OPENCLAW_USE_CC_OPENCLAW !== undefined;
+    const raw = {
+        mode,
+        listenersEnabled: TRUTHY(env.OPENCLAW_CC_OPENCLAW_LISTENERS),
+        activeRouting: mode === RuntimeMode.ACTIVE_ROUTING,
+        toolStream: TRUTHY(env.CC_OPENCLAW_TOOL_STREAM),
+        allowBuiltins: TRUTHY(env.CC_OPENCLAW_ALLOW_BUILTINS),
+        toolsPerMessage: TRUTHY(env.OPENAI_COMPAT_TOOLS_PER_MESSAGE),
+        // Dual-default split (see schema comments).
+        cacheParityModuleEnabled: !FALSEY(env.OPENCLAW_CACHE_PARITY),
+        cacheParityTrackB: env.OPENCLAW_CACHE_PARITY === '1',
+        newConvoHeuristic: env.OPENAI_COMPAT_NEW_CONVO_HEURISTIC === '1',
+        aggressiveStripEnabled: !FALSEY(env.OPENCLAW_AGGRESSIVE_STRIP),
+        debug: TRUTHY(env.CC_OPENCLAW_DEBUG),
+        registerDebug: env.OPENCLAW_REGISTER_DEBUG === '1',
+        // Dual-default split (see schema comments).
+        tokenTelemetryRouteGate: env.OPENCLAW_TOKEN_TELEMETRY === '1',
+        tokenTelemetryWriter: env.OPENCLAW_TOKEN_TELEMETRY !== '0',
+        syspromptDump: env.OPENCLAW_SYSPROMPT_DUMP === '1',
+        trajectoryEnabled: env.CC_OPENCLAW_TRAJECTORY === '1',
+        statusUrl: env.OPENAI_COMPAT_STATUS_URL && env.OPENAI_COMPAT_STATUS_URL !== ''
+            ? env.OPENAI_COMPAT_STATUS_URL
+            : undefined,
+        surfaceThinking: env.CC_OPENCLAW_SURFACE_THINKING === '1',
+        thinkingExcerpt: env.CC_OPENCLAW_THINKING_EXCERPT === '1',
+        maxConcurrentSessions: parseInt(env.CLAUDE_CODE_MAX_SESSIONS ?? '', 10) || 32,
+        sessionTtlMinutes: parseInt(env.CLAUDE_CODE_SESSION_TTL ?? '', 10) || 1440,
+        serverHost: env.OPENCLAW_SERVER_HOST || '127.0.0.1',
+        rateLimit: parseInt(env.OPENCLAW_RATE_LIMIT ?? '', 10) || 100,
+        serverToken: env.OPENCLAW_SERVER_TOKEN && env.OPENCLAW_SERVER_TOKEN !== '' ? env.OPENCLAW_SERVER_TOKEN : undefined,
+        corsAllowAll: env.OPENCLAW_CORS_ORIGINS === '*',
+        claudeBin: env.CLAUDE_BIN && env.CLAUDE_BIN !== '' ? env.CLAUDE_BIN : undefined,
+        geminiBin: env.GEMINI_BIN && env.GEMINI_BIN !== '' ? env.GEMINI_BIN : undefined,
+        codexBin: env.CODEX_BIN && env.CODEX_BIN !== '' ? env.CODEX_BIN : undefined,
+        cursorBin: env.CURSOR_BIN && env.CURSOR_BIN !== '' ? env.CURSOR_BIN : undefined,
+        driftAlertsEnabled: env.OPENCLAW_CC_OPENCLAW_DRIFT_ALERTS !== '0',
+        autoRecoveryEnabled: env.OPENCLAW_CC_OPENCLAW_AUTO_RECOVERY !== '0',
+        quotaPausePct: Number(env.OPENCLAW_QUOTA_PAUSE_PCT) || 95,
+        testMode: env.OPENCLAW_PLUGIN_TEST_MODE === '1',
+        heartbeatWorkaroundDisabled: env.CC_OPENCLAW_DISABLE_HEARTBEAT_WORKAROUND === '1',
+        savvyLiveCardEnabled: TRUTHY(env.SAVVY_LIVE_CARD),
+        usedDeprecatedAlias,
+    };
+    const result = RuntimeConfigSchema.safeParse(raw);
+    if (!result.success) {
+        return { ok: false, error: new ConfigError(result.error.issues) };
+    }
+    return { ok: true, config: Object.freeze(result.data) };
+}
+// ── Free-function compat shims (Cluster A step 8: collapses route-flag.ts) ──
+//
+// The old `src/lib/route-flag.ts` exported `selectEngine`,
+// `isCcOpenclawEnabled`, `captureSessionRoute`, `ACTIVE_FLAG_ENV`, and
+// `ROUTE_FLAG_ENV` as free top-level symbols. Step 8 collapsed that file
+// into ConfigService: the exports below re-implement the same API as
+// pure functions that read env at call time (no caching, no
+// ConfigService instance required) so existing call sites + tests work
+// unchanged after a one-line import-path swap.
+//
+// `ConfigService.prototype.selectEngine()` and `captureSessionRoute()`
+// delegate to these free functions, so the semantics are bit-identical
+// regardless of which API a caller uses.
+//
+// **Deprecation alias `ROUTE_FLAG_ENV`** is preserved through v0.9.x and
+// removed at v1.0.0. The activation derivation in `deriveMode` already
+// honors it as a fallback.
+/** Primary activation env var (PRP_v3 §10). */
+export const ACTIVE_FLAG_ENV = 'OPENCLAW_CC_OPENCLAW_ACTIVE';
+/**
+ * @deprecated Use `ACTIVE_FLAG_ENV`. Read for fallback when the new name
+ * is unset. Removed in v1.0.0.
+ */
+export const ROUTE_FLAG_ENV = 'OPENCLAW_USE_CC_OPENCLAW';
+/**
+ * Read env at call time and report whether cc-openclaw engine routing is
+ * active. **Independent of `LISTENERS`** — per ARCHITECTURE.md §3, engine
+ * selection (per-session) and handler wiring (process-wide) are orthogonal:
+ * a session can pick the cc-openclaw engine even when LISTENERS is off.
+ *
+ * Honors deprecated `OPENCLAW_USE_CC_OPENCLAW` fallback when the new
+ * ACTIVE_FLAG_ENV is unset.
+ *
+ * Free-function variant — works without a ConfigService instance.
+ */
+export function isCcOpenclawEnabled(env = process.env) {
+    const v = env[ACTIVE_FLAG_ENV] ?? env[ROUTE_FLAG_ENV];
+    if (!v)
+        return false;
+    const norm = v.toLowerCase();
+    return norm === '1' || norm === 'true' || norm === 'on';
+}
+/**
+ * Free-function variant of `ConfigService.prototype.selectEngine()`.
+ * Re-reads env at call time. Use when you don't have a ConfigService instance
+ * (i.e. early boot, or in tests) — semantics match the instance method exactly.
+ *
+ * **Only reads `ACTIVE_FLAG_ENV` / deprecated alias.** Does NOT consider
+ * `LISTENERS` — that flag controls handler wiring, not engine selection.
+ * The higher-level `RuntimeMode` enum (which classifies the whole-process
+ * activation state) is computed separately by `deriveMode`.
+ */
+export function selectEngine(env = process.env) {
+    return isCcOpenclawEnabled(env) ? 'cc-openclaw' : 'claude-local';
+}
+/**
+ * Free-function variant of `ConfigService.prototype.captureSessionRoute()`.
+ * Returns a frozen snapshot — subsequent env mutations do NOT affect the
+ * captured route. This is what makes "in-flight sessions stay on original
+ * engine" architecturally true at the routing layer.
+ */
+export function captureSessionRoute(env = process.env) {
+    return Object.freeze({
+        engine: selectEngine(env),
+        capturedAt: new Date().toISOString(),
+    });
+}
+/**
+ * ConfigService wraps the parsed config with the live-read escape hatches
+ * that preserve `route-flag.ts:48,63` semantics.
+ *
+ * - `config`: frozen at construction; reads return boot-time values.
+ * - `selectEngine()`: re-reads `process.env` on every call. Use when picking
+ *   an engine for a NEW session — lets a rollback flip take effect mid-process
+ *   without restart.
+ * - `captureSessionRoute()`: snapshots the current engine into a frozen
+ *   object. Use at session-start to lock the engine for that session's
+ *   lifetime — lets in-flight sessions ride out a rollback unaffected.
+ */
+export class ConfigService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Re-reads env at call time. Use for new-session engine selection.
+     * Asymmetric with `config.activeRouting` (frozen at boot) BY DESIGN —
+     * see PRP §5 Cluster A "Frozen + escape-hatch contract".
+     *
+     * Delegates to the module-level `selectEngine` free function so that
+     * the class API and free-function API share one implementation.
+     */
+    selectEngine(env = process.env) {
+        return selectEngine(env);
+    }
+    /**
+     * Snapshot the current engine for a new session. Frozen — subsequent
+     * env mutations do NOT affect the captured route. Delegates to the
+     * free function for the same single-source-of-truth reason.
+     */
+    captureSessionRoute(env = process.env) {
+        return captureSessionRoute(env);
+    }
+    /** Convenience constructor for boot path. */
+    static fromEnv(env = process.env) {
+        const result = parseEnv(env);
+        if (!result.ok)
+            throw result.error;
+        return new ConfigService(result.config);
+    }
+}
+// ── Module-level singleton (Cluster A step 7) ────────────────────────────────
+//
+// The singleton lives here (NOT in src/index.ts) so that src/lib/config.ts
+// can import it without creating a circular import (index.ts imports from
+// many lib modules; if config.ts imported from index.ts, the cycle would
+// surface at boot).
+//
+// `setConfigService` is called once by `register()` at boot. `getConfigService`
+// returns `undefined` before that call OR if parseEnv failed. Compat-shim
+// callers should pattern-match: `getConfigService()?.config.X ?? legacy`.
+//
+// Tests can clear via `_resetConfigServiceForTests()`. Tests that mutate env
+// and depend on getters reading the new value should not call `register()`
+// at all, OR should reset the singleton first.
+let _singleton;
+export function getConfigService() {
+    return _singleton;
+}
+export function setConfigService(svc) {
+    _singleton = svc;
+}
+export function _resetConfigServiceForTests() {
+    _singleton = undefined;
+}
+//# sourceMappingURL=config-service.js.map

package/dist/src/lib/config-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-service.js","sourceRoot":"","sources":["../../../src/lib/config-service.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/config.d.ts

@@ -1,19 +1,27 @@
 /**
- * config — single env-reader source of truth (PRP_v3 §5 hard rule).
+ * config — env-reader source of truth.
  *
- * v3 §5 mandates: `process.env` reads only in `src/index.ts`,
- * `src/lib/route-flag.ts`, and this module. Every other source file imports
- * its config from here via the typed getter functions.
+ * Originally PRP_v3 §5: `process.env` reads only in `src/index.ts`,
+ * `src/lib/route-flag.ts`, and this module. Cluster A step 7 layered a
+ * compat shim on top: getters now delegate to `ConfigService.config.X`
+ * (the typed Cluster A boot config) when available, falling back to
+ * the original `process.env.X` read otherwise.
  *
- * Why getters (not cached constants): tests flip env vars at runtime via
- * `process.env.X = 'y'` and expect immediate effect. Cached-at-import
- * constants would freeze the value at first load, breaking every existing
- * test that toggles env mid-run. Getters preserve test flippability while
- * still centralizing env-coupling to one module.
+ * Why the shim instead of pure delegation: tests flip env vars at
+ * runtime via `process.env.X = 'y'` and expect immediate effect. When
+ * `ConfigService` is unset (most tests), getters fall through to env
+ * — preserving test flippability bit-for-bit. When `ConfigService` is
+ * set (live gateway boot), the typed config wins, providing single-
+ * source-of-truth observability via `/health` and the boot log.
  *
- * Adding a new env var: add a getter here, import it from the consumer.
- * Do NOT add `process.env.X` reads in any other file under src/ except
- * the two pre-authorized exceptions noted above.
+ * Adding a new env var: add a getter here AND a field to
+ * `RuntimeConfigSchema` in `src/types/runtime-config.ts`. The shim line
+ * pattern is `getConfigService()?.config.X ?? legacyEnvRead`.
+ *
+ * Cluster A step 8 will collapse the activation getters (selectEngine,
+ * route-flag) into ConfigService escape hatches and delete
+ * `src/lib/route-flag.ts`. Cluster F (v1.0.0) will remove the legacy
+ * env-read fallback and hard-fail when ConfigService is missing.
  */
 export declare function getAggressiveStripEnabled(): boolean;
 export declare function getCacheParityEnabled(): boolean;
@@ -50,6 +58,9 @@ export declare function getClaudeBin(): string | undefined;
  * PATH passed to spawned engine subprocesses. Falls back to the standard
  * Unix path so binaries resolve even when the parent's PATH is unset
  * (preserved from persistent-session.ts:257 + persistent-custom-session.ts:240).
+ *
+ * NOT in RuntimeConfig — PATH is process-environment, not plugin
+ * configuration. Kept as a direct env reader.
  */
 export declare function getProcessPath(): string;
 export declare function isTokenTelemetryWriterEnabled(): boolean;
@@ -57,7 +68,11 @@ export declare function isTokenTelemetryWriterEnabled(): boolean;
 export declare function isRegisterDebugEnabled(): boolean;
 export declare function isHeartbeatWorkaroundDisabled(): boolean;
 export declare function getQuotaPausePct(): number;
-/** Raw value for `isToolsPerMessageModeEnabled()` parsing. */
+/**
+ * Raw value for `isToolsPerMessageModeEnabled()` parsing.
+ * NOT delegated — the consumer parses the raw string itself; the typed
+ * `toolsPerMessage` boolean field is for boot-time observability only.
+ */
 export declare function getOpenaiCompatToolsPerMessage(): string | undefined;
 /** Strict opt-in — legacy new-conversation heuristic via env=1. */
 export declare function isOpenaiCompatNewConvoHeuristic(): boolean;
@@ -68,7 +83,11 @@ export declare function isSavvyLiveCardEnabled(): boolean;
 export declare function getHomeOrTmp(): string;
 export declare function getHealthPortEnv(): string | undefined;
 export declare function isDriftAlertsEnabled(): boolean;
-/** Dedup window for repeated drift Telegram alerts. Default 1h. */
+/**
+ * Dedup window for repeated drift Telegram alerts. Default 1h.
+ * NOT in RuntimeConfig — niche tunable not surfaced through the activation
+ * matrix. Kept as a direct env reader.
+ */
 export declare function getDriftDedupeWindowMs(): number;
 export declare function isAutoRecoveryEnabled(): boolean;
 export declare function getSurfaceThinkingEnabled(): boolean;