@aexol/spectral 0.8.5 → 0.8.7

package/dist/server/agent-bridge.js

@@ -1,18 +1,18 @@
 /**
- * Per-connection pi SDK lifecycle.
+ * Per-connection spectral SDK lifecycle.
  *
  * One `AgentBridge` instance per active WebSocket connection. Wraps:
  *  - `createAgentSession` (in-memory session manager — we own persistence in
- *    SQLite; pi doesn't need to write its own JSONL files).
- *  - `subscribe` listener that translates pi `AgentSessionEvent`s into our
+ *    SQLite; spectral doesn't need to write its own JSONL files).
+ *  - `subscribe` listener that translates spectral `AgentSessionEvent`s into our
  *    own `ServerEvent` wire format and pushes them through a caller-supplied
  *    sink.
  *  - `prompt(text)` to send user input.
  *  - `dispose()` for clean teardown on WS close.
  *
- * Event mapping (pi → wire):
+ * Event mapping (agent → wire):
  *  - `message_start` (assistant)        → emit our own `message_start` with a
- *    fresh UUID `messageId`. Pi's AssistantMessage has no stable id field, so
+ *    fresh UUID `messageId`. spectral's AssistantMessage has no stable id field, so
  *    we mint one per turn and use it for all subsequent deltas/tool events
  *    until `message_end`.
  *  - `message_update` w/ inner text_delta / thinking_delta → wire `text_delta`
@@ -29,7 +29,7 @@
  *
  * Persistence shape:
  *  `events_jsonl` is the newline-delimited JSON of the wire-format
- *  `ServerEvent`s we emitted for this message — NOT raw pi
+ *  `ServerEvent`s we emitted for this message — NOT raw spectral
  *  `AgentSessionEvent`s. This guarantees the client's `parseWireEvents`
  *  reducer can rehydrate the turn after a refresh using the exact same
  *  reducer it uses for the live broadcast.
@@ -45,7 +45,7 @@
  *  `createAgentSession` is called, each message is appended to the
  *  in-memory SessionManager so the LLM sees the full conversation
  *  context from the very first prompt. Multi-turn conversations within
- *  a single pi session also work normally (the same AgentSession
+ *  a single spectral session also work normally (the same AgentSession
  *  instance is reused across `prompt()` calls).
  */
 import { createJiti } from "@mariozechner/jiti";
@@ -64,12 +64,12 @@ import { Runtime } from "../memory/runtime.js";
 import { OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE, OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE, } from "../memory/types.js";
 import { fetchAllowedModels as defaultFetchAllowedModels, } from "../relay/models-fetch.js";
 /**
- * Synthetic provider names registered with pi's `ModelRegistry`. They route
+ * Synthetic provider names registered with spectral's `ModelRegistry`. They route
  * 100% of inference traffic through the backend (`${backendUrl}/v1`), which
  * authenticates with the machine JWT and forwards to the upstream provider
  * with centrally-managed API keys.
  *
- * Two providers (rather than one) because pi's `ProviderConfigInput.api`
+ * Two providers (rather than one) because spectral's `ProviderConfigInput.api`
  * picks the request shape per registration. Backend supports both, but a
  * single bag would force all models onto one shape; instead we group by
  * upstream provider type.
@@ -84,7 +84,7 @@ const SPECTRAL_PROXY_USER_MODEL = "spectral-proxy-user-model";
  *
  * Directories are returned in order from the deepest ancestor to `cwd` so
  * project-local skills override ancestor-level ones when there are name
- * collisions (pi's skill loader keeps the first found).
+ * collisions (spectral's skill loader keeps the first found).
  */
 function collectAncestorSkillDirs(cwd, relativePaths) {
     const found = [];
@@ -111,8 +111,8 @@ function collectAncestorSkillDirs(cwd, relativePaths) {
 /**
  * Concatenate text from an `AssistantMessage.content` array. Returns the
  * empty string when no text blocks are present (tool-only turns) or when
- * the input is missing/non-array (defensive — pi's `message_end` always
- * carries an array, but we don't want to crash on a future SDK change).
+ * the input is missing/non-array (defensive — spectral's `message_end` always
+ * carries an array, but we don't want to crash on a future sdk change).
  */
 function extractTextFromContent(content) {
     if (!Array.isArray(content))
@@ -129,7 +129,7 @@ function extractTextFromContent(content) {
     return out;
 }
 /**
- * Resolve the entry point of the pi-mcp-adapter extension.
+ * Resolve the entry point of the spectral-mcp-adapter extension.
  * Uses the bundled copy in dist/mcp/index.js (same directory as this file).
  * Returns the absolute path, or null if the bundled file is missing.
  */
@@ -145,8 +145,8 @@ function resolveMcpAdapterEntry() {
 /**
  * Token pricing per model (USD per 1M tokens). Matches provider list
  * prices as of May 2026. Used to compute token cost server-side when
- * pi's own cost field is unavailable (synthetic proxy models are
- * registered with zero cost to avoid pi-side billing).
+ * spectral's own cost field is unavailable (synthetic proxy models are
+ * registered with zero cost to avoid agent-side billing).
  *
  * Keys are matched as prefix substrings against modelId, so
  * `"claude-sonnet-4"` covers both `claude-sonnet-4-20250514` and any
@@ -386,7 +386,7 @@ export class AgentBridge {
     disposed = false;
     opts;
     /**
-     * Pi's model registry. Built lazily in `start()` so we can resolve a
+     * spectral's model registry. Built lazily in `start()` so we can resolve a
      * `modelId` (envelope-supplied or SQLite-persisted) to a concrete `Model`
      * via `registry.getAll().find(m => m.id === modelId)` before invoking
      * `session.setModel()`. Phase 3 (Available Models whitelist).
@@ -400,12 +400,12 @@ export class AgentBridge {
     allowedModels;
     /**
      * Last `modelId` we successfully applied via `session.setModel()`, or
-     * `undefined` if we never applied one (pi falls back to its own settings
+     * `undefined` if we never applied one (spectral falls back to its own settings
      * file in that case, matching pre-Phase-3 behaviour). Tracked so repeated
-     * envelopes carrying the same modelId don't churn pi's internal state.
+     * envelopes carrying the same modelId don't churn spectral's internal state.
      */
     lastAppliedModelId;
-    /** Current model's credit rates (from availableBaseModels), used for token_usage. */
+    /** Current model's credit rates (from availableAgentModels), used for token_usage. */
     activeCreditRates = null;
     memoryRuntime = new Runtime();
     memoryPhase = "idle";
@@ -413,38 +413,38 @@ export class AgentBridge {
         this.opts = opts;
     }
     /**
-     * Create the pi session, wire up subscription, and return.
+     * Create the spectral session, wire up subscription, and return.
      * Throws on creation failure (caller should surface to client).
      */
     async start() {
         if (this.disposed)
             throw new Error("AgentBridge already disposed");
-        const extensionFactories = [aexolMcpExtension, kanbanBridgeExtension, async (pi) => { spectralVisionExtension(pi); }, async (pi) => { subagentExt(pi); }, async (pi) => { designerExtension(pi); }, async (pi) => { observationalMemory(pi); }];
-        // Load pi-mcp-adapter via jiti so tsc never crawls its .ts files in
+        const extensionFactories = [aexolMcpExtension, kanbanBridgeExtension, async (ext) => { spectralVisionExtension(ext); }, async (ext) => { subagentExt(ext); }, async (ext) => { designerExtension(ext); }, async (ext) => { observationalMemory(ext); }];
+        // 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
-        // pi-mcp-adapter's source and fail the build on its type errors.
-        // jiti is the same loader pi uses internally for all extensions.
+        // spectral-mcp-adapter's source and fail the build on its type errors.
+        // jiti is the same loader spectral uses internally for all extensions.
         const mcpAdapterPath = resolveMcpAdapterEntry();
         if (mcpAdapterPath) {
             try {
                 const jiti = createJiti(import.meta.url, { moduleCache: false });
                 const mcpAdapterFactory = await jiti.import(mcpAdapterPath, { default: true });
                 if (typeof mcpAdapterFactory === "function") {
-                    extensionFactories.push(async (pi) => mcpAdapterFactory(pi));
+                    extensionFactories.push(async (ext) => mcpAdapterFactory(ext));
                 }
             }
             catch {
-                console.info("[AgentBridge] pi-mcp-adapter not found; standard MCP servers disabled.");
+                console.info("[AgentBridge] spectral-mcp-adapter not found; standard MCP servers disabled.");
             }
         }
         else {
-            console.info("[AgentBridge] pi-mcp-adapter not found; standard MCP servers disabled.");
+            console.info("[AgentBridge] spectral-mcp-adapter not found; standard MCP servers disabled.");
         }
         // ResourceLoader with extensions wired in via factories.
-        // Each factory's signature `(pi: ExtensionAPI) => Promise<void>` matches
+        // Each factory's signature `(ext: ExtensionAPI) => Promise<void>` matches
         // the ExtensionFactory type exactly, so we can pass them directly.
         //
-        // Skill discovery: pi's defaults scan ~/.spectral/agent/skills/ (user),
+        // Skill discovery: spectral's defaults scan ~/.spectral/agent/skills/ (user),
         // .spectral/skills/ (project via CONFIG_DIR_NAME), and .agents/skills/
         // (ancestor-walked). We additionally walk ancestors for
         // .opencode/skills and .aexol/skills so OpenCode/Codex/Aexol skills
@@ -581,7 +581,7 @@ export class AgentBridge {
         // provider credentials and the only allowed inference target. We then
         // register synthetic providers (`spectral-proxy-anthropic` /
         // `spectral-proxy-openai`) whose `baseUrl` points at the backend's
-        // `/v1` proxy and whose `apiKey` is the machine JWT. Pi will then
+        // `/v1` proxy and whose `apiKey` is the machine JWT. spectral will then
         // POST `${baseUrl}/messages` (or `/chat/completions`) with
         // `Authorization: Bearer <machineJwt>` for every turn — the backend
         // verifies the JWT, looks up the requested `model` in the BaseModel
@@ -639,7 +639,7 @@ export class AgentBridge {
             }
             catch { /* best-effort */ }
         });
-        // Emit session_start so extensions can initialize (e.g. pi-mcp-adapter
+        // Emit session_start so extensions can initialize (e.g. spectral-mcp-adapter
         // connects to MCP servers, loads configs from ~/.config/mcp/mcp.json etc.).
         // bindExtensions also fires resources_discover for dynamic skill/prompt
         // registration.
@@ -684,7 +684,7 @@ export class AgentBridge {
      * (OpenAI-compatible API). The backend supports both endpoints natively
      * (verified in F1).
      *
-     * Pi will send `Authorization: Bearer ${apiKey}` (because `authHeader: true`)
+     * spectral will send `Authorization: Bearer ${apiKey}` (because `authHeader: true`)
      * which carries the machine JWT — the only credential the backend trusts.
      *
      * The `id` we register is the raw `modelId` (e.g. `claude-3-5-haiku-latest`),
@@ -707,7 +707,7 @@ export class AgentBridge {
                         id: m.modelId,
                         name: m.displayName,
                         api: "anthropic-messages",
-                        // Pin provider/baseUrl explicitly so pi's ModelRegistry doesn't
+                        // Pin provider/baseUrl explicitly so spectral's ModelRegistry doesn't
                         // auto-derive `provider` from a slash-prefixed id (e.g. treating
                         // `deepseek/deepseek-v4-pro` as provider `"deepseek"`), which would
                         // make `hasConfiguredAuth(model)` look up the wrong provider key
@@ -735,7 +735,7 @@ export class AgentBridge {
                         id: m.modelId,
                         name: m.displayName,
                         api: "openai-completions",
-                        // See anthropic batch above for rationale — without these, pi
+                        // See anthropic batch above for rationale — without these, spectral
                         // auto-derives `provider` from slash-prefixed ids like
                         // `deepseek/deepseek-v4-pro` or `meta-llama/llama-3.3-70b-instruct`,
                         // breaking auth lookup against our synthetic proxy provider.
@@ -781,7 +781,7 @@ export class AgentBridge {
         }
     }
     /**
-     * Apply a sticky model selection to the underlying pi session, if it
+     * Apply a sticky model selection to the underlying spectral session, if it
      * differs from what was last applied. No-ops when:
      *  - `modelId` is null/undefined (caller passed nothing to apply)
      *  - the same modelId was already applied to this session
@@ -792,7 +792,7 @@ export class AgentBridge {
      * Returns true when the requested model is now in effect (either because
      * we just applied it or because it was already applied). Returns false
      * on resolution failure so the caller can skip `prompt()` and avoid
-     * driving pi against the wrong model.
+     * driving spectral against the wrong model.
      *
      * Phase 3 (Available Models whitelist).
      */
@@ -809,7 +809,7 @@ export class AgentBridge {
         return this.allowedModels?.[0]?.modelId;
     }
     /**
-     * Return current session context usage from pi's built-in estimator.
+     * Return current session context usage from spectral's built-in estimator.
      * Used after compaction and session start to push updated context-window
      * stats to the frontend without waiting for the next assistant turn.
      */
@@ -850,7 +850,7 @@ export class AgentBridge {
     }
     async setModel(modelId) {
         if (!modelId)
-            return true; // nothing to apply — pi keeps its current model
+            return true; // nothing to apply — spectral keeps its current model
         if (!this.session)
             throw new Error("AgentBridge.start() not called");
         if (this.lastAppliedModelId === modelId)
@@ -858,7 +858,7 @@ export class AgentBridge {
         if (!this.modelRegistry) {
             // Defensive: start() always populates this; if it didn't we can't
             // resolve and must surface to the client rather than silently using
-            // pi's default.
+            // spectral's default.
             this.opts.emit({
                 type: "error",
                 message: `Cannot apply modelId "${modelId}": model registry unavailable`,
@@ -884,7 +884,7 @@ export class AgentBridge {
         if (!model) {
             this.opts.emit({
                 type: "error",
-                message: `Unknown modelId "${modelId}" — not found in pi model registry${refreshError ? ` after refresh: ${refreshError.message}` : ""}`,
+                message: `Unknown modelId "${modelId}" — not found in spectral model registry${refreshError ? ` after refresh: ${refreshError.message}` : ""}`,
             });
             return false;
         }
@@ -914,18 +914,18 @@ export class AgentBridge {
         }
     }
     /**
-     * Map a frontend reasoning-effort string to pi's ThinkingLevel.
+     * Map a frontend reasoning-effort string to spectral's ThinkingLevel.
      * Frontend sends: xhigh | high | medium | low | minimal | none | undefined
-     * Pi expects:   "high" | "medium" | "low" | "minimal" | "off"
+     * spectral expects:   "high" | "medium" | "low" | "minimal" | "off"
      *
      * Mapping:
-     *   xhigh   → high    (pi doesn't have xhigh, default to max)
+     *   xhigh   → high    (spectral doesn't have xhigh, default to max)
      *   high    → high
      *   medium  → medium
      *   low     → low
      *   minimal → minimal
      *   none    → off
-     *   undefined → no-op (pi keeps whatever it has currently)
+     *   undefined → no-op (spectral keeps whatever it has currently)
      */
     mapReasoningEffortToThinkingLevel(effort) {
         if (effort === undefined)
@@ -946,10 +946,10 @@ export class AgentBridge {
     }
     /**
      * Set the reasoning/thinking effort level for the next prompt.
-     * Pass `undefined` to leave pi's current level unchanged.
+     * Pass `undefined` to leave spectral's current level unchanged.
      *
      * The caller (SessionStreamManager) is responsible for persisting the
-     * value to SQLite; this method only applies it to pi's in-memory session.
+     * value to SQLite; this method only applies it to spectral's in-memory session.
      */
     setReasoningEffort(effort) {
         const level = this.mapReasoningEffortToThinkingLevel(effort);
@@ -973,13 +973,13 @@ export class AgentBridge {
         }
     }
     /**
-     * Forward a user message to pi. Resolves when the full turn ends.
+     * Forward a user message to ext. Resolves when the full turn ends.
      * The caller is responsible for persisting the user message to SQLite
-     * BEFORE invoking this — we don't do it here because pi's `prompt` may
+     * BEFORE invoking this — we don't do it here because spectral's `prompt` may
      * fail and we still want the user message recorded.
      *
      * When `images` is non-empty, each base64-encoded attachment is converted
-     * to a pi `ImageContent` block and passed as `options.images` to
+     * to a spectral `ImageContent` block and passed as `options.images` to
      * `session.prompt()`. If the current model does not support image inputs,
      * images are instead converted to text placeholders so the conversation
      * can continue without errors.
@@ -1012,7 +1012,7 @@ export class AgentBridge {
         }
     }
     /**
-     * Manually compact the session context via pi's built-in compaction.
+     * Manually compact the session context via spectral's built-in compaction.
      * Pi generates a summary of older conversation history, preserving the
      * most recent ~20K tokens verbatim. Compaction events are forwarded to
      * the wire through `handleEvent()`.
@@ -1136,8 +1136,8 @@ export class AgentBridge {
     }
     /**
      * Subscriber callback. Public so tests can drive event flow without
-     * spinning up a real pi session — production code never calls this
-     * directly; pi's `subscribe()` does, via the closure registered in
+     * spinning up a real spectral session — production code never calls this
+     * directly; spectral's `subscribe()` does, via the closure registered in
      * `start()`.
      */
     handleEvent(ev) {
@@ -1152,7 +1152,7 @@ export class AgentBridge {
                 // Finalize the previous pending message (if any) before starting a
                 // new one. This captures tool events that arrived after the previous
                 // `message_end` but before this `message_start`. Deferred persistence
-                // is necessary because pi fires tool_execution_* events BETWEEN
+                // is necessary because spectral fires tool_execution_* events BETWEEN
                 // messages — after the previous `message_end` nulled the pending in
                 // the old code, those tool events were lost from history.
                 this.finalizePendingMessage();
@@ -1327,7 +1327,7 @@ export class AgentBridge {
                 if (ev.message.role !== "assistant" || !this.pending)
                     return;
                 const { messageId, text } = this.pending;
-                // Prefer the assembled text from pi's final AssistantMessage
+                // Prefer the assembled text from spectral's final AssistantMessage
                 // (authoritative — providers like deepseek only populate this and
                 // skip per-token `text_delta`s entirely). Fall back to the
                 // accumulator for providers that stream deltas without re-asserting
@@ -1338,7 +1338,7 @@ export class AgentBridge {
                 const endEvent = { type: "message_end", messageId };
                 this.pending.wireEvents.push(endEvent);
                 this.opts.emit(endEvent);
-                // Emit token usage for this assistant message. pi provides token
+                // Emit token usage for this assistant message. spectral provides token
                 // counts via ev.message.usage; credits are computed from the active
                 // model's configured credit rates.
                 //
@@ -1355,7 +1355,7 @@ export class AgentBridge {
                     (usage?.cacheRead ?? 0) +
                     (usage?.cacheWrite ?? 0);
                 if (usage && totalTokens > 0) {
-                    // Resolve current context window usage from pi's built-in
+                    // Resolve current context window usage from spectral's built-in
                     // `getContextUsage()`, which handles post-compaction ambiguity
                     // and estimates total tokens from the full session tree.
                     const ctxUsage = this.session?.getContextUsage();
@@ -1378,7 +1378,7 @@ export class AgentBridge {
                     this.opts.emit(usageEvent);
                 }
                 // Defer persistence: keep `this.pending` alive so tool events that
-                // arrive after `message_end` (pi fires tool_execution_* events
+                // arrive after `message_end` (spectral fires tool_execution_* events
                 // BETWEEN messages) are buffered into `pending.wireEvents`. We store
                 // the final content and persist later — when the next `message_start`
                 // signals a new step, or when `agent_end` closes the turn.
@@ -1415,7 +1415,7 @@ export class AgentBridge {
                 return;
             }
             default:
-                // Other pi-internal events (turn_start, queue_update,
+                // Other spectral-internal events (turn_start, queue_update,
                 // auto_retry_*, tool_execution_update) are intentionally not on
                 // the wire surface for MVP and are NOT persisted — the wire format
                 // is the source of truth for replay.
@@ -1457,7 +1457,7 @@ function detectNotifSystem(message) {
 /**
  * Create a minimal ExtensionUIContext that forwards `notify()` calls as
  * `agent_notification` wire events. All other UI methods are no-ops —
- * only extensions (not pi's TUI) call into the UI context in headless mode,
+ * only extensions (not spectral's TUI) call into the UI context in headless mode,
  * and extensions that call methods other than `notify()` are expected to
  * guard with `ctx.hasUI` first.
  */

package/dist/server/handlers/mcp-status.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Handler for `GET /api/mcp-status`.
+ *
+ * Returns a snapshot of the locally connected MCP servers managed by
+ * `spectral serve`. Pure handler pattern — no framework, no side effects.
+ * The caller (the relay dispatcher) injects `McpExtensionState`.
+ *
+ * This module intentionally imports ONLY `McpExtensionState` (a pure-type
+ * import from `state.ts`). It avoids `init.ts` / `config.ts` / etc. so the
+ * dispatcher never pulls in heavy transitive deps.
+ */
+import type { McpExtensionState } from "../../mcp/state.js";
+export interface McpServerStatus {
+    name: string;
+    status: "connected" | "disconnected" | "needs-auth" | "failed" | "cached";
+    toolCount: number;
+    /** Epoch-ms of the most recent connection failure, if the server is in a failed state. */
+    failedAt?: number;
+}
+export declare function handleListMcpStatus(state: McpExtensionState): McpServerStatus[];
+//# sourceMappingURL=mcp-status.d.ts.map

package/dist/server/handlers/mcp-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-status.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/mcp-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,iBAAiB,GACvB,eAAe,EAAE,CA0BnB"}

package/dist/server/handlers/mcp-status.js

@@ -0,0 +1,52 @@
+/**
+ * Handler for `GET /api/mcp-status`.
+ *
+ * Returns a snapshot of the locally connected MCP servers managed by
+ * `spectral serve`. Pure handler pattern — no framework, no side effects.
+ * The caller (the relay dispatcher) injects `McpExtensionState`.
+ *
+ * This module intentionally imports ONLY `McpExtensionState` (a pure-type
+ * import from `state.ts`). It avoids `init.ts` / `config.ts` / etc. so the
+ * dispatcher never pulls in heavy transitive deps.
+ */
+/** Maximum age (ms) of a failure entry before we treat it as stale. */
+const FAILURE_BACKOFF_MS = 60_000;
+export function handleListMcpStatus(state) {
+    const result = [];
+    for (const name of Object.keys(state.config.mcpServers)) {
+        const connection = state.manager.getConnection(name);
+        const metadata = state.toolMetadata.get(name);
+        const toolCount = metadata?.length ?? 0;
+        const failedAgo = getFailureAgeSeconds(state, name);
+        let status = "disconnected";
+        let failedAt;
+        if (connection?.status === "connected") {
+            status = "connected";
+        }
+        else if (connection?.status === "needs-auth") {
+            status = "needs-auth";
+        }
+        else if (failedAgo !== null) {
+            status = "failed";
+            failedAt = state.failureTracker.get(name) ?? undefined;
+        }
+        else if (metadata !== undefined) {
+            status = "cached";
+        }
+        result.push({ name, status, toolCount, failedAt });
+    }
+    return result;
+}
+/**
+ * Mirrors `init.ts#getFailureAgeSeconds` without pulling in init.ts's
+ * heavy runtime deps (config, consent manager, UI resource handler, etc.).
+ */
+function getFailureAgeSeconds(state, serverName) {
+    const failedAt = state.failureTracker.get(serverName);
+    if (!failedAt)
+        return null;
+    const ageMs = Date.now() - failedAt;
+    if (ageMs > FAILURE_BACKOFF_MS)
+        return null;
+    return Math.round(ageMs / 1000);
+}

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

@@ -3,7 +3,7 @@
  *
  * Same shape as projects handlers — see that file's header for the contract.
  *
- * Note: session deletion does not tear down the in-flight pi stream itself.
+ * Note: session deletion does not tear down the in-flight spectral stream itself.
  * The Batch 3 dispatcher must call `manager.disposeSessionStream(id)` BEFORE
  * invoking `handleDeleteSession` so the FK cascade doesn't leave a zombie
  * bridge driving events at a row that no longer exists. This matches the

package/dist/server/handlers/sessions.js

@@ -3,7 +3,7 @@
  *
  * Same shape as projects handlers — see that file's header for the contract.
  *
- * Note: session deletion does not tear down the in-flight pi stream itself.
+ * Note: session deletion does not tear down the in-flight spectral stream itself.
  * The Batch 3 dispatcher must call `manager.disposeSessionStream(id)` BEFORE
  * invoking `handleDeleteSession` so the FK cascade doesn't leave a zombie
  * bridge driving events at a row that no longer exists. This matches the

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

@@ -0,0 +1,30 @@
+/**
+ * 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;
+}
+export interface PutSettingsOutput {
+    ok: true;
+    key: string;
+    value: number;
+}
+export interface GetSettingsOutput {
+    observationThresholdTokens: number;
+    compactionThresholdTokens: number;
+    reflectionThresholdTokens: number;
+    passive: boolean;
+    debugLog: boolean;
+}
+export declare function handleGetSettings(cwd: string): GetSettingsOutput;
+export declare function handlePutSettings(cwd: string, body: PutSettingsInput): PutSettingsOutput;
+//# sourceMappingURL=settings.d.ts.map

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

@@ -0,0 +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"}

package/dist/server/handlers/settings.js

@@ -0,0 +1,123 @@
+/**
+ * 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). */
+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();
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// GET handler
+// ---------------------------------------------------------------------------
+export function handleGetSettings(cwd) {
+    const config = loadConfig(cwd);
+    return {
+        observationThresholdTokens: config.observationThresholdTokens,
+        compactionThresholdTokens: config.compactionThresholdTokens,
+        reflectionThresholdTokens: config.reflectionThresholdTokens,
+        passive: config.passive,
+        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");
+    }
+    if (body.value < MIN_TOKENS || body.value > MAX_TOKENS) {
+        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 };
+    });
+    return { ok: true, key, value };
+}