@threadbase-sh/streamer 1.52.3 → 1.52.4

package/dist/index.d.cts

@@ -114,7 +114,53 @@ interface FeatureFlagDefinition {
     /** Full env var name. */
     env: string;
 }
-type FeatureFlagValues = Record<string, boolean>;
+/**
+ * Values arriving from a config source. PARTIAL on purpose: server.yaml, the
+ * CLI and ServerConfig each speak about the flags they mention and stay silent
+ * on the rest, which is what lets the precedence chain fall through.
+ */
+type FeatureFlagValues = Partial<Record<FeatureFlagId, boolean>>;
+/** Every flag, resolved. Total — see resolveFeatureFlags(). */
+type ResolvedFeatureFlags = Record<FeatureFlagId, boolean>;
+/**
+ * Which rung of the precedence chain decided a flag.
+ *
+ * Kept because the resolved boolean alone cannot answer "why is this on?", and
+ * that is the first question asked of a flag that is on when nobody expected it.
+ * `override` is the legacy ServerConfig field (see resolveFeatureFlags).
+ */
+type FeatureFlagSource = "override" | "env" | "cli" | "yaml" | "default";
+declare const FEATURE_FLAGS: readonly [{
+    readonly id: "codexSystemPrompt";
+    readonly description: string;
+    readonly default: false;
+    readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
+}, {
+    readonly id: "sessionRehydration";
+    readonly description: string;
+    readonly default: true;
+    readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
+}, {
+    readonly id: "liveActivityPush";
+    readonly description: string;
+    readonly default: false;
+    readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
+}, {
+    readonly id: "ptyHost";
+    readonly description: string;
+    readonly default: false;
+    readonly env: "THREADBASE_FEATURE_PTY_HOST";
+}];
+/**
+ * The registry's ids as a union, derived rather than declared.
+ *
+ * This is what makes `flags.ptyHsot` a compile error instead of `undefined`.
+ * Under the old `Record<string, boolean>` an index signature accepted any key,
+ * so a typo in a consumer read as falsy and silently disabled the feature it
+ * was meant to gate — the exact failure the "total map" contract exists to
+ * prevent, reachable through the one door that contract left open.
+ */
+type FeatureFlagId = (typeof FEATURE_FLAGS)[number]["id"];
 
 declare const CLAUDE_CODE_PROVIDER: "claude-code";
 declare const CODEX_CLI_PROVIDER: "codex-cli";
@@ -1695,7 +1741,8 @@ type ApiDeps = {
     };
     featureFlagsConfig: () => {
         registry: readonly FeatureFlagDefinition[];
-        values: FeatureFlagValues;
+        values: ResolvedFeatureFlags;
+        sources: Record<FeatureFlagId, FeatureFlagSource>;
     };
     publicUrl: string | null;
     browseRoot: string | null;
@@ -2028,6 +2075,7 @@ declare class StreamerServer {
     private ptyGracePeriodMs;
     private defaultSystemPrompt;
     private featureFlags;
+    private featureFlagSources;
     private codexSystemPromptEnabled;
     private defaultPermissionMode;
     private defaultModel;

package/dist/index.d.ts

@@ -114,7 +114,53 @@ interface FeatureFlagDefinition {
     /** Full env var name. */
     env: string;
 }
-type FeatureFlagValues = Record<string, boolean>;
+/**
+ * Values arriving from a config source. PARTIAL on purpose: server.yaml, the
+ * CLI and ServerConfig each speak about the flags they mention and stay silent
+ * on the rest, which is what lets the precedence chain fall through.
+ */
+type FeatureFlagValues = Partial<Record<FeatureFlagId, boolean>>;
+/** Every flag, resolved. Total — see resolveFeatureFlags(). */
+type ResolvedFeatureFlags = Record<FeatureFlagId, boolean>;
+/**
+ * Which rung of the precedence chain decided a flag.
+ *
+ * Kept because the resolved boolean alone cannot answer "why is this on?", and
+ * that is the first question asked of a flag that is on when nobody expected it.
+ * `override` is the legacy ServerConfig field (see resolveFeatureFlags).
+ */
+type FeatureFlagSource = "override" | "env" | "cli" | "yaml" | "default";
+declare const FEATURE_FLAGS: readonly [{
+    readonly id: "codexSystemPrompt";
+    readonly description: string;
+    readonly default: false;
+    readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
+}, {
+    readonly id: "sessionRehydration";
+    readonly description: string;
+    readonly default: true;
+    readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
+}, {
+    readonly id: "liveActivityPush";
+    readonly description: string;
+    readonly default: false;
+    readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
+}, {
+    readonly id: "ptyHost";
+    readonly description: string;
+    readonly default: false;
+    readonly env: "THREADBASE_FEATURE_PTY_HOST";
+}];
+/**
+ * The registry's ids as a union, derived rather than declared.
+ *
+ * This is what makes `flags.ptyHsot` a compile error instead of `undefined`.
+ * Under the old `Record<string, boolean>` an index signature accepted any key,
+ * so a typo in a consumer read as falsy and silently disabled the feature it
+ * was meant to gate — the exact failure the "total map" contract exists to
+ * prevent, reachable through the one door that contract left open.
+ */
+type FeatureFlagId = (typeof FEATURE_FLAGS)[number]["id"];
 
 declare const CLAUDE_CODE_PROVIDER: "claude-code";
 declare const CODEX_CLI_PROVIDER: "codex-cli";
@@ -1695,7 +1741,8 @@ type ApiDeps = {
     };
     featureFlagsConfig: () => {
         registry: readonly FeatureFlagDefinition[];
-        values: FeatureFlagValues;
+        values: ResolvedFeatureFlags;
+        sources: Record<FeatureFlagId, FeatureFlagSource>;
     };
     publicUrl: string | null;
     browseRoot: string | null;
@@ -2028,6 +2075,7 @@ declare class StreamerServer {
     private ptyGracePeriodMs;
     private defaultSystemPrompt;
     private featureFlags;
+    private featureFlagSources;
     private codexSystemPromptEnabled;
     private defaultPermissionMode;
     private defaultModel;

package/dist/index.js

@@ -485,11 +485,12 @@ function validateFeatureFlagValues(raw) {
   const out = {};
   const dropped = [];
   for (const [id, value] of Object.entries(raw)) {
-    if (!findFeatureFlag(id) || typeof value !== "boolean") {
+    const def = findFeatureFlag(id);
+    if (!def || typeof value !== "boolean") {
       dropped.push(id);
       continue;
     }
-    out[id] = value;
+    out[def.id] = value;
   }
   if (dropped.length > 0) {
     getLogger("feature-flags").warn(
@@ -504,15 +505,29 @@ function validateFeatureFlagValues(raw) {
 }
 function resolveFeatureFlags(opts) {
   const env = opts?.env ?? process.env;
-  const out = {};
+  const values = {};
+  const sources = {};
   for (const def of FEATURE_FLAGS) {
-    out[def.id] = parseBooleanEnv(env[def.env]) ?? opts?.cli?.[def.id] ?? opts?.yaml?.[def.id] ?? def.default;
+    const rungs = [
+      ["override", opts?.override?.[def.id]],
+      ["env", parseBooleanEnv(env[def.env])],
+      ["cli", opts?.cli?.[def.id]],
+      ["yaml", opts?.yaml?.[def.id]]
+    ];
+    const won = rungs.find(([, v]) => v !== void 0);
+    values[def.id] = won ? won[1] : def.default;
+    sources[def.id] = won ? won[0] : "default";
   }
-  return out;
+  return { values, sources };
 }
 function nonDefaultFeatureFlags(values) {
   return FEATURE_FLAGS.filter((f) => values[f.id] !== f.default).map((f) => f.id);
 }
+function describeFeatureFlags(resolution) {
+  return FEATURE_FLAGS.map(
+    (f) => `${f.id}=${resolution.values[f.id]}(${resolution.sources[f.id]})`
+  ).join(" ");
+}
 
 // src/auth.ts
 function configDir() {
@@ -14453,6 +14468,10 @@ var StreamerServer = class {
   // Resolved once at boot; see src/feature-flags.ts. Total map — every registry
   // id is present, so indexing it never yields undefined.
   featureFlags;
+  // Which rung of the precedence chain decided each flag. Reported at boot and
+  // over GET /api/config/feature-flags — the resolved boolean alone cannot say
+  // whether a value came from the environment, the CLI, server.yaml or nowhere.
+  featureFlagSources;
   // Derived from featureFlags.codexSystemPrompt. Kept as its own field so the
   // read site in startFresh() is unchanged.
   codexSystemPromptEnabled;
@@ -14566,10 +14585,13 @@ var StreamerServer = class {
     this.codexRoots = config.codexRoots ?? [join23(homedir12(), ".codex", "sessions")];
     this.ptyGracePeriodMs = config.ptyGracePeriodMs ?? DEFAULT_PTY_GRACE_PERIOD_MS;
     this.defaultSystemPrompt = config.defaultSystemPrompt ?? DEFAULT_SYSTEM_PROMPT;
-    this.featureFlags = resolveFeatureFlags({ cli: config.featureFlags, yaml: loadFeatureFlags() });
-    if (config.codexSystemPromptEnabled !== void 0) {
-      this.featureFlags.codexSystemPrompt = config.codexSystemPromptEnabled;
-    }
+    const flagResolution = resolveFeatureFlags({
+      override: config.codexSystemPromptEnabled === void 0 ? void 0 : { codexSystemPrompt: config.codexSystemPromptEnabled },
+      cli: config.featureFlags,
+      yaml: loadFeatureFlags()
+    });
+    this.featureFlags = flagResolution.values;
+    this.featureFlagSources = flagResolution.sources;
     this.codexSystemPromptEnabled = this.featureFlags.codexSystemPrompt;
     this.defaultPermissionMode = config.defaultPermissionMode ?? loadDefaultPermissionMode() ?? "acceptEdits";
     this.defaultModel = config.defaultModel ?? "sonnet";
@@ -14614,13 +14636,12 @@ var StreamerServer = class {
     });
     this.includeAgents = parseIncludeAgentsEnv(process.env.THREADBASE_INCLUDE_AGENTS);
     this.agentEntrypoints = parseAgentEntrypointsEnv(process.env.THREADBASE_AGENT_ENTRYPOINTS);
-    const enabledFlags = nonDefaultFeatureFlags(this.featureFlags);
-    if (enabledFlags.length > 0) {
-      this.log.info(`Feature flags active: ${enabledFlags.join(", ")}`, {
-        event: "config.feature_flags_active",
-        flags: enabledFlags
-      });
-    }
+    this.log.info(`Feature flags: ${describeFeatureFlags(flagResolution)}`, {
+      event: "config.feature_flags",
+      values: this.featureFlags,
+      sources: this.featureFlagSources,
+      nonDefault: nonDefaultFeatureFlags(this.featureFlags)
+    });
     const rawRoot = process.env.THREADBASE_BROWSE_ROOT ?? loadBrowseRoot() ?? config.browseRoot;
     if (rawRoot) {
       realpath2(rawRoot).then((resolved) => {
@@ -15643,7 +15664,11 @@ var StreamerServer = class {
    * the absence of that field is the signal that this endpoint is read-only.
    */
   getFeatureFlagsConfig() {
-    return { registry: FEATURE_FLAGS, values: this.featureFlags };
+    return {
+      registry: FEATURE_FLAGS,
+      values: this.featureFlags,
+      sources: this.featureFlagSources
+    };
   }
   getClaudeFlagsConfig() {
     return {