apex-code 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/core/settings-manager.js

@@ -1,10 +1,36 @@
-import { randomUUID } from "crypto";
+import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
-import lockfile from "proper-lockfile";
 import { CONFIG_DIR_NAME, getAgentDir } from "../config.js";
 import { normalizePath, resolvePath } from "../utils/paths.js";
+import { stripBom } from "../utils/text.js";
+import { getApexEnvironment } from "./environment.js";
 import { DEFAULT_HTTP_IDLE_TIMEOUT_MS, parseHttpIdleTimeoutMs } from "./http-dispatcher.js";
+/**
+ * `proper-lockfile` is required lazily, not imported: the supervisor loads this module
+ * on every launch just to read settings, and a static import puts the lock library
+ * (measured: the single largest share of the settings-manager import cost) on the
+ * pre-child critical path where it is never used -- the supervisor only reads. The
+ * sync `require` keeps `withLock`'s synchronous interface; the write path pays the
+ * load once, on first write.
+ */
+const requireFromHere = createRequire(import.meta.url);
+let lockfileModule;
+function lockfile() {
+    if (!lockfileModule) {
+        lockfileModule = requireFromHere("proper-lockfile");
+    }
+    return lockfileModule;
+}
+/**
+ * Hard ceiling on `delegationMaxDepth`, independent of what a user configures. A
+ * placeholder pending real measurement (the open question `docs/plans/2026-08-14-
+ * delegation-and-multi-agent.md` carries into this task): each level multiplies
+ * both token cost and the distance between the human and the work, and this
+ * repository has not yet measured that cost per level. 5 is conservative headroom
+ * above the default of 2, not a derived number.
+ */
+export const DELEGATION_MAX_DEPTH_HARD_CAP = 5;
 function isMergeableObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -37,6 +63,13 @@ function parseTimeoutSetting(value, settingName) {
     }
     return undefined;
 }
+function toSettingsError(scope, error, path) {
+    return {
+        scope,
+        ...(path ? { path } : {}),
+        error: error instanceof Error ? error : new Error(String(error)),
+    };
+}
 export class FileSettingsStorage {
     globalSettingsPath;
     projectSettingsPath;
@@ -52,7 +85,7 @@ export class FileSettingsStorage {
         let lastError;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             try {
-                return lockfile.lockSync(path, { realpath: false });
+                return lockfile().lockSync(path, { realpath: false });
             }
             catch (error) {
                 const code = typeof error === "object" && error !== null && "code" in error
@@ -130,7 +163,8 @@ export class SettingsManager {
     projectSettingsLoadError = null; // Track if project settings file had parse errors
     writeQueue = Promise.resolve();
     errors;
-    constructor(storage, initialGlobal, initialProject, globalLoadError = null, projectLoadError = null, initialErrors = [], projectTrusted = true) {
+    settingsPaths;
+    constructor(storage, initialGlobal, initialProject, globalLoadError = null, projectLoadError = null, initialErrors = [], projectTrusted = true, settingsPaths = {}) {
         this.storage = storage;
         this.globalSettings = initialGlobal;
         this.projectSettings = initialProject;
@@ -138,26 +172,36 @@ export class SettingsManager {
         this.globalSettingsLoadError = globalLoadError;
         this.projectSettingsLoadError = projectLoadError;
         this.errors = [...initialErrors];
+        this.settingsPaths = settingsPaths;
         this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
     }
     /** Create a SettingsManager that loads from files */
     static create(cwd, agentDir = getAgentDir(), options = {}) {
-        const storage = new FileSettingsStorage(cwd, agentDir);
-        return SettingsManager.fromStorage(storage, options);
+        const resolvedCwd = resolvePath(cwd);
+        const resolvedAgentDir = resolvePath(agentDir);
+        const storage = new FileSettingsStorage(resolvedCwd, resolvedAgentDir);
+        return SettingsManager.fromStorageWithPaths(storage, options, {
+            global: join(resolvedAgentDir, "settings.json"),
+            project: join(resolvedCwd, CONFIG_DIR_NAME, "settings.json"),
+        });
     }
     /** Create a SettingsManager from an arbitrary storage backend */
     static fromStorage(storage, options = {}) {
+        return SettingsManager.fromStorageWithPaths(storage, options);
+    }
+    /** Create a manager while retaining optional file paths for reported storage errors. */
+    static fromStorageWithPaths(storage, options, settingsPaths = {}) {
         const projectTrusted = options.projectTrusted ?? true;
         const globalLoad = SettingsManager.tryLoadFromStorage(storage, "global");
         const projectLoad = SettingsManager.tryLoadFromStorage(storage, "project", projectTrusted);
         const initialErrors = [];
         if (globalLoad.error) {
-            initialErrors.push({ scope: "global", error: globalLoad.error });
+            initialErrors.push(toSettingsError("global", globalLoad.error, settingsPaths.global));
         }
         if (projectLoad.error) {
-            initialErrors.push({ scope: "project", error: projectLoad.error });
+            initialErrors.push(toSettingsError("project", projectLoad.error, settingsPaths.project));
         }
-        return new SettingsManager(storage, globalLoad.settings, projectLoad.settings, globalLoad.error, projectLoad.error, initialErrors, projectTrusted);
+        return new SettingsManager(storage, globalLoad.settings, projectLoad.settings, globalLoad.error, projectLoad.error, initialErrors, projectTrusted, settingsPaths);
     }
     /** Create an in-memory SettingsManager (no file I/O) */
     static inMemory(settings = {}, options = {}) {
@@ -178,7 +222,7 @@ export class SettingsManager {
         if (!content) {
             return {};
         }
-        const settings = JSON.parse(content);
+        const settings = JSON.parse(stripBom(content));
         return SettingsManager.migrateSettings(settings);
     }
     static tryLoadFromStorage(storage, scope, projectTrusted = true) {
@@ -323,8 +367,7 @@ export class SettingsManager {
         }
     }
     recordError(scope, error) {
-        const normalizedError = error instanceof Error ? error : new Error(String(error));
-        this.errors.push({ scope, error: normalizedError });
+        this.errors.push(toSettingsError(scope, error, this.settingsPaths[scope]));
     }
     clearModifiedScope(scope) {
         if (scope === "global") {
@@ -358,7 +401,7 @@ export class SettingsManager {
     persistScopedSettings(scope, snapshotSettings, modifiedFields, modifiedNestedFields) {
         this.storage.withLock(scope, (current) => {
             const currentFileSettings = current
-                ? SettingsManager.migrateSettings(JSON.parse(current))
+                ? SettingsManager.migrateSettings(JSON.parse(stripBom(current)))
                 : {};
             const mergedSettings = { ...currentFileSettings };
             for (const field of modifiedFields) {
@@ -429,6 +472,14 @@ export class SettingsManager {
         this.markModified("lastChangelogVersion");
         this.save();
     }
+    getFirstUseHints() {
+        return [...(this.settings.firstUseHints ?? [])];
+    }
+    setFirstUseHints(hints) {
+        this.globalSettings.firstUseHints = [...new Set(hints)];
+        this.markModified("firstUseHints");
+        this.save();
+    }
     getSessionDir() {
         const sessionDir = this.settings.sessionDir;
         return sessionDir ? normalizePath(sessionDir) : sessionDir;
@@ -495,6 +546,30 @@ export class SettingsManager {
         this.markModified("defaultThinkingLevel");
         this.save();
     }
+    getModelThinkingLevel(provider, modelId) {
+        return this.settings.modelThinkingLevels?.[`${provider}/${modelId}`];
+    }
+    getAllModelThinkingLevels() {
+        return { ...(this.settings.modelThinkingLevels ?? {}) };
+    }
+    setModelThinkingLevel(provider, modelId, level) {
+        if (!this.globalSettings.modelThinkingLevels) {
+            this.globalSettings.modelThinkingLevels = {};
+        }
+        this.globalSettings.modelThinkingLevels[`${provider}/${modelId}`] = level;
+        this.markModified("modelThinkingLevels");
+        this.save();
+    }
+    removeModelThinkingLevel(provider, modelId) {
+        if (!this.globalSettings.modelThinkingLevels)
+            return;
+        delete this.globalSettings.modelThinkingLevels[`${provider}/${modelId}`];
+        if (Object.keys(this.globalSettings.modelThinkingLevels).length === 0) {
+            delete this.globalSettings.modelThinkingLevels;
+        }
+        this.markModified("modelThinkingLevels");
+        this.save();
+    }
     getTransport() {
         return this.settings.transport ?? "auto";
     }
@@ -533,6 +608,21 @@ export class SettingsManager {
             skipPrompt: this.settings.branchSummary?.skipPrompt ?? false,
         };
     }
+    getNetworkSettings() {
+        return this.settings.network;
+    }
+    getSandboxProfiles() {
+        return this.settings.sandboxProfiles === undefined ? undefined : structuredClone(this.settings.sandboxProfiles);
+    }
+    getLspSettings() {
+        return this.settings.lsp === undefined ? undefined : structuredClone(this.settings.lsp);
+    }
+    getWebSearchSettings() {
+        return this.settings.webSearch === undefined ? undefined : structuredClone(this.settings.webSearch);
+    }
+    getCheckpointSettings() {
+        return this.settings.checkpoints === undefined ? undefined : structuredClone(this.settings.checkpoints);
+    }
     getBranchSummarySkipPrompt() {
         return this.settings.branchSummary?.skipPrompt ?? false;
     }
@@ -554,6 +644,9 @@ export class SettingsManager {
             baseDelayMs: this.settings.retry?.baseDelayMs ?? 2000,
         };
     }
+    getObservabilitySettings() {
+        return this.settings.observability ?? {};
+    }
     getHttpIdleTimeoutMs() {
         return parseTimeoutSetting(this.settings.httpIdleTimeoutMs, "httpIdleTimeoutMs") ?? DEFAULT_HTTP_IDLE_TIMEOUT_MS;
     }
@@ -575,6 +668,13 @@ export class SettingsManager {
     getWebSocketConnectTimeoutMs() {
         return parseTimeoutSetting(this.settings.websocketConnectTimeoutMs, "websocketConnectTimeoutMs");
     }
+    /** Max delegation recursion depth (roadmap Phase 5, task 5.3). A non-positive or missing configured value falls back to the default rather than being rejected outright -- this bound is a safety ceiling, not a value where a malformed setting should block startup. Always clamped to DELEGATION_MAX_DEPTH_HARD_CAP, regardless of configuration. */
+    getDelegationMaxDepth() {
+        const DEFAULT = 2;
+        const configured = this.settings.delegationMaxDepth;
+        const value = Number.isFinite(configured) && configured > 0 ? configured : DEFAULT;
+        return Math.min(Math.floor(value), DELEGATION_MAX_DEPTH_HARD_CAP);
+    }
     getHideThinkingBlock() {
         return this.settings.hideThinkingBlock ?? false;
     }
@@ -652,28 +752,12 @@ export class SettingsManager {
         this.markModified("collapseChangelog");
         this.save();
     }
-    getEnableInstallTelemetry() {
-        return this.settings.enableInstallTelemetry ?? true;
+    getSendProviderAttribution() {
+        return this.settings.sendProviderAttribution ?? true;
     }
-    setEnableInstallTelemetry(enabled) {
-        this.globalSettings.enableInstallTelemetry = enabled;
-        this.markModified("enableInstallTelemetry");
-        this.save();
-    }
-    getEnableAnalytics() {
-        return this.settings.enableAnalytics ?? false;
-    }
-    getTrackingId() {
-        return this.settings.trackingId;
-    }
-    /** Set the analytics opt-in preference; generates a tracking identifier on first opt-in */
-    setEnableAnalytics(enabled) {
-        this.globalSettings.enableAnalytics = enabled;
-        this.markModified("enableAnalytics");
-        if (enabled && !this.globalSettings.trackingId) {
-            this.globalSettings.trackingId = randomUUID();
-            this.markModified("trackingId");
-        }
+    setSendProviderAttribution(enabled) {
+        this.globalSettings.sendProviderAttribution = enabled;
+        this.markModified("sendProviderAttribution");
         this.save();
     }
     getPackages() {
@@ -778,12 +862,21 @@ export class SettingsManager {
         this.markModified("terminal", "imageWidthCells");
         this.save();
     }
+    getSymbolPreset() {
+        return this.settings.terminal?.symbolPreset ?? "unicode";
+    }
+    getColorBlindMode() {
+        return this.settings.terminal?.colorBlindMode ?? false;
+    }
+    getTokenUsageDisplay() {
+        return this.settings.terminal?.tokenUsageDisplay ?? "compact";
+    }
     getClearOnShrink() {
         // Settings takes precedence, then env var, then default false
         if (this.settings.terminal?.clearOnShrink !== undefined) {
             return this.settings.terminal.clearOnShrink;
         }
-        return process.env.PI_CLEAR_ON_SHRINK === "1";
+        return getApexEnvironment("APEX_CODE_CLEAR_ON_SHRINK") === "1";
     }
     setClearOnShrink(enabled) {
         if (!this.globalSettings.terminal) {
@@ -812,6 +905,14 @@ export class SettingsManager {
         this.markModified("tuiMode");
         this.save();
     }
+    getFullscreenExitOutput() {
+        return this.settings.fullscreenExitOutput === "resume-hint" ? "resume-hint" : "transcript";
+    }
+    setFullscreenExitOutput(output) {
+        this.globalSettings.fullscreenExitOutput = output;
+        this.markModified("fullscreenExitOutput");
+        this.save();
+    }
     getFullscreenScrollbar() {
         const mode = this.settings.fullscreenScrollbar;
         return mode === "always" || mode === "hidden" ? mode : "auto";
@@ -846,6 +947,10 @@ export class SettingsManager {
     getEnabledModels() {
         return this.settings.enabledModels;
     }
+    getDefaultTools() {
+        const tools = this.settings.defaultTools;
+        return tools ? [...tools] : undefined;
+    }
     setEnabledModels(patterns) {
         this.globalSettings.enabledModels = patterns;
         this.markModified("enabledModels");
@@ -870,7 +975,7 @@ export class SettingsManager {
         this.save();
     }
     getShowHardwareCursor() {
-        return this.settings.showHardwareCursor ?? process.env.PI_HARDWARE_CURSOR === "1";
+        return this.settings.showHardwareCursor ?? getApexEnvironment("APEX_CODE_HARDWARE_CURSOR") === "1";
     }
     setShowHardwareCursor(enabled) {
         this.globalSettings.showHardwareCursor = enabled;