@a1hvdy/cc-openclaw 0.8.0 → 0.9.1

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;

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,wBAAgB,yBAAyB,IAAI,OAAO,CAInD;AAcD,wBAAgB,qBAAqB,IAAI,OAAO,CAI/C;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAMD,wBAAgB,WAAW,IAAI,MAAM,GAAG,SAAS,CAGhD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAKD,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAKD,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AASD,wBAAgB,gCAAgC,IAAI;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAOtF;AAID,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,iFAAiF;AACjF,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAGnD;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAID,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAGlD;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAGlD;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAGvD;AAED,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAGpD;AAED,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAGpD;AAMD,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAGjD;AAED,wBAAgB,WAAW,IAAI,MAAM,GAAG,SAAS,CAGhD;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAGjD;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAGjD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAQD,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAKD,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAKD,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC;AAID,8DAA8D;AAC9D,wBAAgB,8BAA8B,IAAI,MAAM,GAAG,SAAS,CAGnE;AAED,mEAAmE;AACnE,wBAAgB,+BAA+B,IAAI,OAAO,CAEzD;AAED,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,SAAS,CAG7D;AAMD,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAG3D;AAMD,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAG3D;AAID,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAMD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAMD,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAGrD;AAKD,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,IAAI,MAAM,CAI/C;AAKD,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}