@runuai/host 0.9.14 → 0.9.42

package/lib/host-config.ts

@@ -0,0 +1,279 @@
+/**
+ * Strict host-local configuration manager for ADR-100.
+ *
+ * Only the three protocol-owned booleans are accepted. Agent CLI and
+ * telemetry switches are persisted in `.env.local`, where they take effect
+ * before the next process starts; terminal-history retention is a typed
+ * singleton row in host.sqlite. The cloud remains the only authority for the
+ * host display name, so it is deliberately absent here.
+ */
+
+import { join } from "node:path";
+
+import { eq } from "drizzle-orm";
+
+import { getDb, schema, type Db } from "./db";
+import {
+  readEnvFileSnapshot,
+  restoreEnvFileSnapshotAtomic,
+  serializeEnvFileMutation,
+  writeEnvValuesAtomic,
+} from "./env-file";
+import { env } from "./env";
+import { applyTerminalHistoryRetentionInTransaction } from "./runtime-state";
+import type {
+  HostConfigErrorCode,
+  HostConfigPatch,
+  HostConfigState,
+} from "../src/protocol";
+
+export type {
+  HostConfigErrorCode,
+  HostConfigPatch,
+  HostConfigState,
+} from "../src/protocol";
+
+export type HostConfigResult =
+  | {
+      readonly ok: true;
+      readonly config: HostConfigState;
+      readonly restartRequired: boolean;
+    }
+  | {
+      readonly ok: false;
+      readonly errorCode: HostConfigErrorCode;
+      readonly message: string;
+    };
+
+const CONFIG_KEYS = [
+  "agentCliAutoupdate",
+  "telemetryEnabled",
+  "retainTerminalHistory",
+] as const satisfies readonly (keyof HostConfigState)[];
+const CONFIG_KEY_SET = new Set<string>(CONFIG_KEYS);
+const SETTINGS_ID = "host";
+
+export interface HostConfigSeams {
+  readonly getDb: () => Db;
+  readonly envFilePath: () => string;
+  readonly procEnv: NodeJS.ProcessEnv;
+  readonly now: () => number;
+  readonly readEnvFileSnapshot: typeof readEnvFileSnapshot;
+  readonly restoreEnvFileSnapshotAtomic: typeof restoreEnvFileSnapshotAtomic;
+  readonly writeEnvValuesAtomic: typeof writeEnvValuesAtomic;
+  readonly serializeEnvFileMutation: typeof serializeEnvFileMutation;
+  readonly applyTerminalHistoryRetentionInTransaction: typeof applyTerminalHistoryRetentionInTransaction;
+}
+
+function defaultSeams(): HostConfigSeams {
+  return {
+    getDb,
+    envFilePath: () => join(env.uaiHome, ".env.local"),
+    procEnv: process.env,
+    now: Date.now,
+    readEnvFileSnapshot,
+    restoreEnvFileSnapshotAtomic,
+    writeEnvValuesAtomic,
+    serializeEnvFileMutation,
+    applyTerminalHistoryRetentionInTransaction,
+  };
+}
+
+/**
+ * The class form makes durability failures testable without weakening the
+ * production singleton API below.
+ */
+export class HostConfigManager {
+  private readonly bootTelemetryEnabled: boolean;
+
+  constructor(private readonly seams: HostConfigSeams = defaultSeams()) {
+    // The telemetry SDK is initialized before remote config is served. Keep
+    // that boot-applied value immutable for this process so GET and repeated
+    // PATCH acknowledgements continue to report a pending restart until the
+    // service actually restarts (or the durable setting is toggled back).
+    this.bootTelemetryEnabled =
+      this.seams.procEnv.UAI_TELEMETRY_DISABLED !== "1";
+  }
+
+  getConfig(): HostConfigResult {
+    try {
+      const config = this.readEffectiveConfig();
+      return {
+        ok: true,
+        config,
+        restartRequired:
+          config.telemetryEnabled !== this.bootTelemetryEnabled,
+      };
+    } catch {
+      return persistenceFailure();
+    }
+  }
+
+  patchConfig(patch: unknown): Promise<HostConfigResult> {
+    const parsed = parseHostConfigPatch(patch);
+    if (!parsed) return Promise.resolve(invalidPatch());
+
+    const envFile = this.seams.envFilePath();
+    return this.seams
+      .serializeEnvFileMutation(envFile, () => this.applyPatch(envFile, parsed))
+      .catch(() => persistenceFailure());
+  }
+
+  private readEffectiveConfig(db: Db = this.seams.getDb()): HostConfigState {
+    const settings = db
+      .select({
+        retainTerminalHistory: schema.hostSettings.retainTerminalHistory,
+      })
+      .from(schema.hostSettings)
+      .where(eq(schema.hostSettings.id, SETTINGS_ID))
+      .get();
+    return {
+      // Keep these predicates identical to their current runtime consumers.
+      agentCliAutoupdate:
+        this.seams.procEnv.UAI_AGENT_CLI_AUTOUPDATE !== "0",
+      telemetryEnabled: this.seams.procEnv.UAI_TELEMETRY_DISABLED !== "1",
+      retainTerminalHistory: settings?.retainTerminalHistory ?? true,
+    };
+  }
+
+  private applyPatch(
+    envFile: string,
+    patch: HostConfigPatch,
+  ): HostConfigResult {
+    try {
+      const db = this.seams.getDb();
+      const current = this.readEffectiveConfig(db);
+      const desired: HostConfigState = { ...current, ...patch };
+      const envUpdates: Record<string, string> = {};
+      if (patch.agentCliAutoupdate !== undefined) {
+        envUpdates.UAI_AGENT_CLI_AUTOUPDATE = desired.agentCliAutoupdate
+          ? "1"
+          : "0";
+      }
+      if (patch.telemetryEnabled !== undefined) {
+        // The durable kill switch is inverse by design.
+        envUpdates.UAI_TELEMETRY_DISABLED = desired.telemetryEnabled ? "0" : "1";
+      }
+
+      const snapshot =
+        Object.keys(envUpdates).length > 0
+          ? this.seams.readEnvFileSnapshot(envFile)
+          : null;
+
+      try {
+        db.transaction((tx) => {
+          if (patch.retainTerminalHistory !== undefined) {
+            const now = this.seams.now();
+            tx.insert(schema.hostSettings)
+              .values({
+                id: SETTINGS_ID,
+                retainTerminalHistory: desired.retainTerminalHistory,
+                updatedAt: now,
+              })
+              .onConflictDoUpdate({
+                target: schema.hostSettings.id,
+                set: {
+                  retainTerminalHistory: desired.retainTerminalHistory,
+                  updatedAt: now,
+                },
+              })
+              .run();
+          }
+          if (patch.retainTerminalHistory === false) {
+            // The setting row and every owner-facing terminal-history scrub
+            // share one SQLite commit. A crash can leave neither a durable
+            // opt-out with stale history nor a scrub with the old setting.
+            this.seams.applyTerminalHistoryRetentionInTransaction(tx);
+          }
+          // better-sqlite3 transactions are synchronous. A failed durable env
+          // replacement throws through this callback and rolls the row back.
+          this.seams.writeEnvValuesAtomic(envFile, envUpdates);
+        });
+      } catch {
+        // The writer can fail after rename (for example directory fsync). The
+        // SQLite transaction has rolled back; restore the exact prior env
+        // bytes before returning a negative acknowledgement.
+        if (snapshot) {
+          try {
+            this.seams.restoreEnvFileSnapshotAtomic(envFile, snapshot);
+          } catch {
+            // Still fail closed. A retry reads effective state and converges;
+            // an error response can never claim the patch was committed.
+          }
+        }
+        return persistenceFailure();
+      }
+
+      // Runtime consumers read process.env, so reflect only values that are
+      // durable. Telemetry still needs a restart to fully (de)initialize the
+      // already-created SDK; the acknowledgement makes that explicit.
+      if (patch.agentCliAutoupdate !== undefined) {
+        this.seams.procEnv.UAI_AGENT_CLI_AUTOUPDATE =
+          envUpdates.UAI_AGENT_CLI_AUTOUPDATE;
+      }
+      if (patch.telemetryEnabled !== undefined) {
+        this.seams.procEnv.UAI_TELEMETRY_DISABLED =
+          envUpdates.UAI_TELEMETRY_DISABLED;
+      }
+
+      const effective = this.readEffectiveConfig(db);
+      return {
+        ok: true,
+        config: effective,
+        restartRequired:
+          effective.telemetryEnabled !== this.bootTelemetryEnabled,
+      };
+    } catch {
+      return persistenceFailure();
+    }
+  }
+}
+
+/** Strict runtime validation: exact keys, booleans, and a non-empty patch. */
+export function parseHostConfigPatch(value: unknown): HostConfigPatch | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  try {
+    const keys = Object.keys(value);
+    if (
+      keys.length === 0 ||
+      keys.some(
+        (key) =>
+          !CONFIG_KEY_SET.has(key) ||
+          typeof (value as Record<string, unknown>)[key] !== "boolean",
+      )
+    ) {
+      return null;
+    }
+    return Object.fromEntries(
+      keys.map((key) => [key, (value as Record<string, boolean>)[key]]),
+    ) as HostConfigPatch;
+  } catch {
+    return null;
+  }
+}
+
+function invalidPatch(): HostConfigResult {
+  return {
+    ok: false,
+    errorCode: "invalid_patch",
+    message: "config patch must contain only supported boolean keys",
+  };
+}
+
+function persistenceFailure(): HostConfigResult {
+  return {
+    ok: false,
+    errorCode: "persistence_failed",
+    message: "host config could not be persisted",
+  };
+}
+
+const manager = new HostConfigManager();
+
+export function getHostConfig(): HostConfigResult {
+  return manager.getConfig();
+}
+
+export function patchHostConfig(patch: unknown): Promise<HostConfigResult> {
+  return manager.patchConfig(patch);
+}