@aexol/spectral 0.9.20 → 0.9.24

package/dist/server/agent-bridge.d.ts

@@ -49,6 +49,7 @@
  *  instance is reused across `prompt()` calls).
  */
 import { type AgentSessionEvent } from "../sdk/coding-agent/index.js";
+import { type AgentSettings } from "./handlers/agent-settings.js";
 import { fetchAllowedModels as defaultFetchAllowedModels } from "../relay/models-fetch.js";
 import type { SessionMemorySnapshot } from "./storage.js";
 import type { ImageAttachment, ServerEvent, WireMessage } from "./wire.js";
@@ -116,6 +117,13 @@ export interface AgentBridgeOptions {
      * can run without a live backend.
      */
     fetchAllowedModels?: FetchAllowedModelsFn;
+    /**
+     * Agent-behavior toggles (primary-agent injection, subagent tool).
+     * When omitted, settings are loaded from `settings.json` at `start()`
+     * time. Changes take effect on the next session/bridge — a running
+     * session is not hot-reloaded.
+     */
+    agentSettings?: AgentSettings;
 }
 export declare class AgentBridge {
     private session?;

package/dist/server/agent-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}

package/dist/server/agent-bridge.js

@@ -55,6 +55,8 @@ import { existsSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import aexolMcpExtension from "../extensions/aexol-mcp.js";
+import { discoverPrimaryAgent, injectPrimaryAgentPrompt } from "../agent/agents.js";
+import { loadAgentSettings } from "./handlers/agent-settings.js";
 import kanbanBridgeExtension from "../extensions/kanban-bridge.js";
 import spectralVisionExtension from "../extensions/spectral-vision-fallback.js";
 import subagentExt from "../agent/index.js";
@@ -417,7 +419,30 @@ export class AgentBridge {
     async start() {
         if (this.disposed)
             throw new Error("AgentBridge already disposed");
-        const extensionFactories = [aexolMcpExtension, kanbanBridgeExtension, async (ext) => { spectralVisionExtension(ext); }, async (ext) => { subagentExt(ext); }, async (ext) => { designerExtension(ext); }, async (ext) => { observationalMemory(ext); }];
+        const extensionFactories = [
+            // Primary-agent prompt is injected per-turn via before_agent_start so the
+            // primaryAgentEnabled toggle takes effect mid-session (next user message).
+            async (ext) => {
+                ext.on("before_agent_start", (event) => {
+                    const settings = loadAgentSettings(this.opts.cwd, this.opts.agentDir);
+                    if (!settings.primaryAgentEnabled)
+                        return;
+                    const primaryAgent = discoverPrimaryAgent(this.opts.cwd, "both", this.opts.agentDir);
+                    const injected = injectPrimaryAgentPrompt(event.systemPrompt, primaryAgent);
+                    if (injected === event.systemPrompt)
+                        return;
+                    return { systemPrompt: injected };
+                });
+            },
+            aexolMcpExtension, kanbanBridgeExtension, async (ext) => { spectralVisionExtension(ext); }, async (ext) => { designerExtension(ext); }, async (ext) => { observationalMemory(ext); }
+        ];
+        // Agent-behavior toggles. Loaded once at bridge construction so changes
+        // take effect on the next session (not mid-turn).
+        const agentSettings = this.opts.agentSettings ?? loadAgentSettings(this.opts.cwd, this.opts.agentDir);
+        // Only register the subagent tool when the toggle is enabled.
+        if (agentSettings.subagentsEnabled) {
+            extensionFactories.splice(4, 0, async (ext) => { subagentExt(ext, { disabledAgents: agentSettings.disabledSubagents }); });
+        }
         // Load spectral-mcp-adapter via jiti so tsc never crawls its .ts files in
         // node_modules. The static `import` was causing tsc to type-check
         // spectral-mcp-adapter's source and fail the build on its type errors.
@@ -448,6 +473,9 @@ export class AgentBridge {
         // .opencode/skills and .aexol/skills so OpenCode/Codex/Aexol skills
         // work out of the box.
         const extraSkillPaths = collectAncestorSkillDirs(this.opts.cwd, [".opencode/skills", ".aexol/skills"]);
+        // Primary-agent prompt injection happens per-turn via the before_agent_start
+        // extension registered above, so the primaryAgentEnabled toggle takes effect
+        // mid-session (on the next user message) rather than only at session start.
         const resourceLoader = new DefaultResourceLoader({
             cwd: this.opts.cwd,
             agentDir: this.opts.agentDir ?? `${process.env.HOME ?? ""}/.spectral/agent`,

package/dist/server/handlers/agent-settings.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent-behavior toggles stored under the `agent` namespace in
+ * `settings.json`. These control whether the primary-agent system prompt
+ * is injected and whether the `subagent` tool is registered.
+ *
+ * Both default to `true` so existing behaviour is preserved when the
+ * namespace is absent.
+ */
+export interface AgentSettings {
+    primaryAgentEnabled: boolean;
+    subagentsEnabled: boolean;
+    /** Names of individual subagents that have been explicitly disabled. */
+    disabledSubagents: string[];
+}
+export declare const AGENT_SETTINGS_DEFAULTS: AgentSettings;
+export interface PutAgentSettingsInput {
+    primaryAgentEnabled?: unknown;
+    subagentsEnabled?: unknown;
+    disabledSubagents?: unknown;
+}
+export interface PutAgentSettingsOutput extends AgentSettings {
+    ok: true;
+}
+/**
+ * Load agent settings by merging defaults ← global ← project overrides.
+ * Mirrors the precedence pattern used by `loadConfig` for observational
+ * memory config.
+ */
+export declare function loadAgentSettings(cwd: string, agentDir?: string): AgentSettings;
+export declare function handleGetAgentSettings(cwd: string, agentDir?: string): AgentSettings;
+/**
+ * Persist a partial update to the `agent` namespace in the **global**
+ * `settings.json` (per-machine, matching the existing memory-settings
+ * behaviour). Project-level overrides are read-only from the REST API.
+ *
+ * Only boolean values are accepted for the two known keys; anything else
+ * is a `400 BadRequestError`.
+ */
+export declare function handlePutAgentSettings(cwd: string, body: PutAgentSettingsInput, agentDir?: string): PutAgentSettingsOutput;
+export interface AgentInfo {
+    name: string;
+    description: string;
+    mode: string;
+    source: string;
+}
+export declare function handleListAgents(cwd: string, agentDir?: string): {
+    agents: AgentInfo[];
+};
+//# sourceMappingURL=agent-settings.d.ts.map

package/dist/server/handlers/agent-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-settings.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/agent-settings.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,eAAO,MAAM,uBAAuB,EAAE,aAIrC,CAAC;AAKF,MAAM,WAAW,qBAAqB;IACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,EAAE,EAAE,IAAI,CAAC;CACV;AA+BD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,CAQf;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,CAEf;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,qBAAqB,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,sBAAsB,CAuCxB;AAMD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAUzB"}

package/dist/server/handlers/agent-settings.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "../../sdk/coding-agent/index.js";
+import { discoverAgents } from "../../agent/agents.js";
+import { BadRequestError } from "./errors.js";
+import { withSettingsLock } from "./settings-lock.js";
+export const AGENT_SETTINGS_DEFAULTS = {
+    primaryAgentEnabled: true,
+    subagentsEnabled: true,
+    disabledSubagents: [],
+};
+const AGENT_NAMESPACE = "agent";
+const ALLOWED_KEYS = new Set(["primaryAgentEnabled", "subagentsEnabled", "disabledSubagents"]);
+/**
+ * Read the `agent` namespace from a single `settings.json` file.
+ * Returns `{}` when the file or namespace is absent or unparseable.
+ */
+function readAgentNamespace(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        const ns = raw[AGENT_NAMESPACE];
+        if (!ns || typeof ns !== "object")
+            return {};
+        const obj = ns;
+        const result = {};
+        if (typeof obj.primaryAgentEnabled === "boolean") {
+            result.primaryAgentEnabled = obj.primaryAgentEnabled;
+        }
+        if (typeof obj.subagentsEnabled === "boolean") {
+            result.subagentsEnabled = obj.subagentsEnabled;
+        }
+        if (Array.isArray(obj.disabledSubagents)) {
+            result.disabledSubagents = obj.disabledSubagents.filter((s) => typeof s === "string");
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Load agent settings by merging defaults ← global ← project overrides.
+ * Mirrors the precedence pattern used by `loadConfig` for observational
+ * memory config.
+ */
+export function loadAgentSettings(cwd, agentDir) {
+    const globalPath = join(agentDir ?? getAgentDir(), "settings.json");
+    const projectPath = join(cwd, ".spectral", "settings.json");
+    return {
+        ...AGENT_SETTINGS_DEFAULTS,
+        ...readAgentNamespace(globalPath),
+        ...readAgentNamespace(projectPath),
+    };
+}
+export function handleGetAgentSettings(cwd, agentDir) {
+    return loadAgentSettings(cwd, agentDir);
+}
+/**
+ * Persist a partial update to the `agent` namespace in the **global**
+ * `settings.json` (per-machine, matching the existing memory-settings
+ * behaviour). Project-level overrides are read-only from the REST API.
+ *
+ * Only boolean values are accepted for the two known keys; anything else
+ * is a `400 BadRequestError`.
+ */
+export function handlePutAgentSettings(cwd, body, agentDir) {
+    const patch = {};
+    for (const key of ["primaryAgentEnabled", "subagentsEnabled"]) {
+        if (body[key] !== undefined) {
+            if (typeof body[key] !== "boolean") {
+                throw new BadRequestError(`agent setting "${key}" must be a boolean, got ${typeof body[key]}`);
+            }
+            patch[key] = body[key];
+        }
+    }
+    // disabledSubagents is a full-replacement string array
+    if (body.disabledSubagents !== undefined) {
+        if (!Array.isArray(body.disabledSubagents) ||
+            !body.disabledSubagents.every((s) => typeof s === "string")) {
+            throw new BadRequestError(`agent setting "disabledSubagents" must be a string array`);
+        }
+        patch.disabledSubagents = body.disabledSubagents;
+    }
+    if (Object.keys(patch).length === 0) {
+        throw new BadRequestError(`agent settings body must include at least one of: ${[...ALLOWED_KEYS].join(", ")}`);
+    }
+    // Persist to the global file only. The lock is shared with the
+    // observational-memory handler so concurrent writes cannot corrupt
+    // each other's namespace.
+    withSettingsLock({ agentDir, namespace: AGENT_NAMESPACE }, (current) => {
+        return { ...current, ...patch };
+    });
+    // Return the fully resolved settings (global + project merge) so the
+    // caller sees the effective state, not just what we wrote.
+    return { ok: true, ...loadAgentSettings(cwd, agentDir) };
+}
+export function handleListAgents(cwd, agentDir) {
+    const { agents } = discoverAgents(cwd, "both", agentDir);
+    return {
+        agents: agents.map((a) => ({
+            name: a.name,
+            description: a.description,
+            mode: a.mode,
+            source: a.source,
+        })),
+    };
+}

package/dist/server/handlers/settings-lock.d.ts

@@ -0,0 +1,36 @@
+import { BadRequestError } from "./errors.js";
+/**
+ * Acquire a synchronous file lock with bounded retries on `ELOCKED`.
+ *
+ * Shared by all settings handlers that persist to `settings.json` so
+ * concurrent writes from different namespaces (observational-memory,
+ * agent) cannot interleave and corrupt the file.
+ */
+export declare function acquireLockSyncWithRetry(path: string): () => void;
+/**
+ * Resolve the `settings.json` path for a given agent directory.
+ * Falls back to the default agent dir (`~/.spectral/agent`) when
+ * `agentDir` is omitted.
+ */
+export declare function settingsFilePath(agentDir?: string): string;
+/**
+ * Read-persist cycle for a single namespace inside `settings.json`,
+ * guarded by a file-level lock so concurrent writes across namespaces
+ * are serialized.
+ *
+ * - Reads the **entire** file (preserving all top-level keys).
+ * - Extracts `parsed[namespace]` (or `{}` if absent).
+ * - Passes the current namespace object to `fn`. If `fn` returns
+ *   `undefined`, no write occurs. Otherwise the returned object
+ *   replaces the namespace and the full file is written back.
+ *
+ * The lock is acquired **before** writing (and also before reading if
+ * the file already exists) so we never observe a half-written file.
+ */
+export declare function withSettingsLock(opts: {
+    agentDir?: string;
+    namespace: string;
+}, fn: (current: Record<string, unknown>) => Record<string, unknown> | undefined): void;
+/** Re-exported for handler convenience. */
+export { BadRequestError };
+//# sourceMappingURL=settings-lock.d.ts.map

package/dist/server/handlers/settings-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-lock.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/settings-lock.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAsBjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC9C,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5E,IAAI,CA4BN;AAED,2CAA2C;AAC3C,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/server/handlers/settings-lock.js

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import lockfile from "proper-lockfile";
+import { getAgentDir } from "../../sdk/coding-agent/index.js";
+import { BadRequestError } from "./errors.js";
+/**
+ * Acquire a synchronous file lock with bounded retries on `ELOCKED`.
+ *
+ * Shared by all settings handlers that persist to `settings.json` so
+ * concurrent writes from different namespaces (observational-memory,
+ * agent) cannot interleave and corrupt the file.
+ */
+export function acquireLockSyncWithRetry(path) {
+    const maxAttempts = 10;
+    const delayMs = 20;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return lockfile.lockSync(path, { realpath: false });
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null && "code" in error
+                ? String(error.code)
+                : undefined;
+            if (code !== "ELOCKED" || attempt === maxAttempts) {
+                throw error;
+            }
+            lastError = error;
+            const start = Date.now();
+            while (Date.now() - start < delayMs) {
+            }
+        }
+    }
+    throw lastError ?? new Error("Failed to acquire settings lock");
+}
+/**
+ * Resolve the `settings.json` path for a given agent directory.
+ * Falls back to the default agent dir (`~/.spectral/agent`) when
+ * `agentDir` is omitted.
+ */
+export function settingsFilePath(agentDir) {
+    return join(agentDir ?? getAgentDir(), "settings.json");
+}
+/**
+ * Read-persist cycle for a single namespace inside `settings.json`,
+ * guarded by a file-level lock so concurrent writes across namespaces
+ * are serialized.
+ *
+ * - Reads the **entire** file (preserving all top-level keys).
+ * - Extracts `parsed[namespace]` (or `{}` if absent).
+ * - Passes the current namespace object to `fn`. If `fn` returns
+ *   `undefined`, no write occurs. Otherwise the returned object
+ *   replaces the namespace and the full file is written back.
+ *
+ * The lock is acquired **before** writing (and also before reading if
+ * the file already exists) so we never observe a half-written file.
+ */
+export function withSettingsLock(opts, fn) {
+    const path = settingsFilePath(opts.agentDir);
+    const dir = dirname(path);
+    let release;
+    try {
+        const fileExists = existsSync(path);
+        if (fileExists) {
+            release = acquireLockSyncWithRetry(path);
+        }
+        const raw = fileExists ? readFileSync(path, "utf-8") : "{}";
+        const parsed = JSON.parse(raw);
+        const ns = (parsed[opts.namespace] ?? {});
+        const next = fn(ns);
+        if (next !== undefined) {
+            parsed[opts.namespace] = { ...ns, ...next };
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            if (!release) {
+                release = acquireLockSyncWithRetry(path);
+            }
+            writeFileSync(path, JSON.stringify(parsed, null, 2), "utf-8");
+        }
+    }
+    finally {
+        if (release) {
+            release();
+        }
+    }
+}
+/** Re-exported for handler convenience. */
+export { BadRequestError };

package/dist/server/handlers/settings.d.ts

@@ -1,14 +1,3 @@
-/**
- * Pure REST handler for `GET /api/settings` and `PUT /api/settings`.
- *
- * Settings are stored in the machine's global `settings.json` under the
- * `"observational-memory"` namespace (see `src/memory/config.ts`).
- *
- * GET  /api/settings                        → returns full observational-memory config
- * PUT  /api/settings                        → updates a single key via `{ key, value }` body
- *
- * All paths are machine-level — no session context needed.
- */
 export interface PutSettingsInput {
     key?: unknown;
     value?: unknown;

package/dist/server/handlers/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;IAClC,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsFD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAShE;AAMD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,iBAAiB,CA0BnB"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/settings.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AACD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,iBAAiB;IAChC,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;IAClC,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAgBD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAShE;AACD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,iBAAiB,CAoBnB"}

package/dist/server/handlers/settings.js

@@ -1,93 +1,19 @@
-/**
- * Pure REST handler for `GET /api/settings` and `PUT /api/settings`.
- *
- * Settings are stored in the machine's global `settings.json` under the
- * `"observational-memory"` namespace (see `src/memory/config.ts`).
- *
- * GET  /api/settings                        → returns full observational-memory config
- * PUT  /api/settings                        → updates a single key via `{ key, value }` body
- *
- * All paths are machine-level — no session context needed.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import lockfile from "proper-lockfile";
-import { getAgentDir } from "../../sdk/coding-agent/index.js";
 import { loadConfig } from "../../memory/config.js";
 import { BadRequestError } from "./errors.js";
-/** Recognised setting keys (dot-separated path within the config object). */
+import { withSettingsLock } from "./settings-lock.js";
 const ALLOWED_KEYS = new Set([
     "observationThresholdTokens",
     "compactionThresholdTokens",
     "reflectionThresholdTokens",
 ]);
-/** Sane bounds for token thresholds. */
 const MIN_TOKENS = 1_000;
 const MAX_TOKENS = 1_000_000;
-// ---------------------------------------------------------------------------
-// File helpers (inlined to avoid pulling in the full SettingsManager)
-// ---------------------------------------------------------------------------
-function acquireLockSyncWithRetry(path) {
-    const maxAttempts = 10;
-    const delayMs = 20;
-    let lastError;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        try {
-            return lockfile.lockSync(path, { realpath: false });
-        }
-        catch (error) {
-            const code = typeof error === "object" && error !== null && "code" in error
-                ? String(error.code)
-                : undefined;
-            if (code !== "ELOCKED" || attempt === maxAttempts) {
-                throw error;
-            }
-            lastError = error;
-            const start = Date.now();
-            while (Date.now() - start < delayMs) {
-                // busy-wait; synchronous by design
-            }
-        }
-    }
-    throw lastError ?? new Error("Failed to acquire settings lock");
-}
-/**
- * Atomically read-modify-write the global `settings.json` under the
- * `"observational-memory"` namespace.
- */
 function withObservationalMemoryLock(fn) {
-    const path = join(getAgentDir(), "settings.json");
-    const dir = dirname(path);
-    let release;
-    try {
-        const fileExists = existsSync(path);
-        if (fileExists) {
-            release = acquireLockSyncWithRetry(path);
-        }
-        const raw = fileExists ? readFileSync(path, "utf-8") : "{}";
-        const parsed = JSON.parse(raw);
-        const ns = (parsed["observational-memory"] ?? {});
-        const next = fn(ns);
-        if (next !== undefined) {
-            parsed["observational-memory"] = { ...ns, ...next };
-            if (!existsSync(dir)) {
-                mkdirSync(dir, { recursive: true });
-            }
-            if (!release) {
-                release = acquireLockSyncWithRetry(path);
-            }
-            writeFileSync(path, JSON.stringify(parsed, null, 2), "utf-8");
-        }
-    }
-    finally {
-        if (release) {
-            release();
-        }
-    }
+    withSettingsLock({ namespace: "observational-memory" }, (current) => {
+        const next = fn(current);
+        return next;
+    });
 }
-// ---------------------------------------------------------------------------
-// GET handler
-// ---------------------------------------------------------------------------
 export function handleGetSettings(cwd) {
     const config = loadConfig(cwd);
     return {
@@ -98,16 +24,11 @@ export function handleGetSettings(cwd) {
         debugLog: config.debugLog,
     };
 }
-// ---------------------------------------------------------------------------
-// PUT handler
-// ---------------------------------------------------------------------------
 export function handlePutSettings(cwd, body) {
-    // Validate key
     if (typeof body.key !== "string" || !ALLOWED_KEYS.has(body.key)) {
         throw new BadRequestError(`settings key must be one of: ${[...ALLOWED_KEYS].join(", ")}`);
     }
     const key = body.key;
-    // Validate value
     if (typeof body.value !== "number" || !Number.isInteger(body.value)) {
         throw new BadRequestError("settings value must be an integer");
     }
@@ -115,7 +36,6 @@ export function handlePutSettings(cwd, body) {
         throw new BadRequestError(`token threshold must be between ${MIN_TOKENS.toLocaleString()} and ${MAX_TOKENS.toLocaleString()}`);
     }
     const value = body.value;
-    // Persist
     withObservationalMemoryLock((current) => {
         return { ...current, [key]: value };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.20",
+  "version": "0.9.24",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,