@threadbase-sh/streamer 1.52.2 → 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";
@@ -530,6 +576,7 @@ interface SessionCursor {
 }
 interface ServerConfig {
     port: number;
+    host?: string;
     apiKey?: string;
     /** 'cli' when --api-key was passed; rotation persists in-memory only and reverts on restart */
     apiKeySource?: "config" | "cli";
@@ -1694,7 +1741,8 @@ type ApiDeps = {
     };
     featureFlagsConfig: () => {
         registry: readonly FeatureFlagDefinition[];
-        values: FeatureFlagValues;
+        values: ResolvedFeatureFlags;
+        sources: Record<FeatureFlagId, FeatureFlagSource>;
     };
     publicUrl: string | null;
     browseRoot: string | null;
@@ -2014,6 +2062,7 @@ declare class StreamerServer {
     private dbPool;
     private dbInstanceId;
     private disableDb;
+    private host;
     private skipStartupWarmup;
     private autoResumeOnBoot;
     private browseRoot;
@@ -2026,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";
@@ -530,6 +576,7 @@ interface SessionCursor {
 }
 interface ServerConfig {
     port: number;
+    host?: string;
     apiKey?: string;
     /** 'cli' when --api-key was passed; rotation persists in-memory only and reverts on restart */
     apiKeySource?: "config" | "cli";
@@ -1694,7 +1741,8 @@ type ApiDeps = {
     };
     featureFlagsConfig: () => {
         registry: readonly FeatureFlagDefinition[];
-        values: FeatureFlagValues;
+        values: ResolvedFeatureFlags;
+        sources: Record<FeatureFlagId, FeatureFlagSource>;
     };
     publicUrl: string | null;
     browseRoot: string | null;
@@ -2014,6 +2062,7 @@ declare class StreamerServer {
     private dbPool;
     private dbInstanceId;
     private disableDb;
+    private host;
     private skipStartupWarmup;
     private autoResumeOnBoot;
     private browseRoot;
@@ -2026,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() {
@@ -14437,6 +14452,7 @@ var StreamerServer = class {
   dbPool = null;
   dbInstanceId = null;
   disableDb = false;
+  host;
   // Skip the startup warm-up scan (test hook; see ServerConfig.skipStartupWarmup).
   skipStartupWarmup;
   autoResumeOnBoot;
@@ -14452,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;
@@ -14558,16 +14578,20 @@ var StreamerServer = class {
     }
     this.verbose = config.verbose ?? false;
     this.disableDb = config.disableDb ?? false;
+    this.host = config.host;
     this.skipStartupWarmup = config.skipStartupWarmup ?? false;
     this.autoResumeOnBoot = config.autoResumeOnBoot ?? false;
     this.scanProfiles = config.scanProfiles;
     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";
@@ -14612,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) => {
@@ -15210,7 +15233,7 @@ var StreamerServer = class {
       await runMigrations(this.dbPool);
       this.log.info("Database migrations applied", { event: "db.migrations_applied" });
     }
-    await this.bindWithRetry(port);
+    await this.bindWithRetry(port, this.host);
     if (!this.ptyManager.isRemote()) {
       this.idleReaperTimer = setInterval(() => this.reapIdleSessions(), IDLE_REAP_SWEEP_MS);
       this.idleReaperTimer.unref?.();
@@ -15219,7 +15242,8 @@ var StreamerServer = class {
       {
         this.log.info(`Streamer server listening on port ${port}`, {
           port,
-          event: "server.listening"
+          event: "server.listening",
+          ...this.host !== void 0 && { host: this.host }
         });
         try {
           this.runtimeStore = RuntimeStore.open(this.runtimeDbPath);
@@ -15433,15 +15457,15 @@ var StreamerServer = class {
   // Bind the HTTP listener, retrying on a transient EADDRINUSE. See the call
   // site in listen() for why the race exists (kickstart -k relaunch). Total
   // worst case ≈ 6 × 500 ms = 3 s before the final attempt rethrows.
-  async bindWithRetry(port, attempts = 6, delayMs = 500) {
+  async bindWithRetry(port, host, attempts = 6, delayMs = 500) {
     this.binding = true;
     try {
-      await this.bindWithRetryLoop(port, attempts, delayMs);
+      await this.bindWithRetryLoop(port, host, attempts, delayMs);
     } finally {
       this.binding = false;
     }
   }
-  async bindWithRetryLoop(port, attempts, delayMs) {
+  async bindWithRetryLoop(port, host, attempts, delayMs) {
     for (let attempt = 1; attempt <= attempts; attempt++) {
       try {
         await new Promise((resolve2, reject) => {
@@ -15455,7 +15479,11 @@ var StreamerServer = class {
           };
           this.httpServer.once("error", onError);
           this.httpServer.once("listening", onListening);
-          this.httpServer.listen(port);
+          if (host === void 0) {
+            this.httpServer.listen(port);
+          } else {
+            this.httpServer.listen(port, host);
+          }
         });
         return;
       } catch (err) {
@@ -15463,13 +15491,18 @@ var StreamerServer = class {
         if (e.code === "EADDRINUSE" && attempt === attempts) {
           this.log.error(
             `port ${port} still busy (EADDRINUSE) after ${attempts} attempts; giving up`,
-            { port, attempts, event: "server.bind_failed" }
+            {
+              port,
+              attempts,
+              event: "server.bind_failed",
+              ...host !== void 0 && { host }
+            }
           );
         }
         if (e.code !== "EADDRINUSE" || attempt === attempts) throw err;
         this.log.debug?.(
           `port ${port} busy (EADDRINUSE), retry ${attempt}/${attempts - 1} in ${delayMs}ms`,
-          { port, attempt, event: "server.bind_retry" }
+          { port, attempt, event: "server.bind_retry", ...host !== void 0 && { host } }
         );
         await new Promise((r) => setTimeout(r, delayMs));
       }
@@ -15631,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 {