@aexol/spectral 0.7.8 → 0.8.2

package/dist/extensions/spectral-vision-fallback.js

@@ -1,55 +1,87 @@
 /**
  * Spectral Vision Extension
  *
- * Automatically describes images using a vision-capable model and replaces
- * raw image data with text descriptions. This saves context for the main agent
- * and allows non-vision models to "see" images.
+ * Automatically switches to a vision-capable model for image processing
+ * when images are attached. This allows non-vision models to "see" images
+ * and saves main agent context by using a potentially smaller/cheaper
+ * vision model for image understanding.
  *
  * Logic:
  *   - ALWAYS intercepts images (even when main model supports vision),
- *     replacing them with text descriptions to save main agent context.
- *   - Uses the main model for vision descriptions if it supports images.
- *   - Falls back to the admin-configured default vision model (isVisionDefault
- *     flag from backend via SettingsManager).
- *   - If no admin default is configured, falls back to the first available
+ *     replacing them with text descriptions.
+ *   - Prefers the admin-configured default vision model (isVisionDefault
+ *     flag from backend via SettingsManager) for image descriptions.
+ *   - Falls back to the main model for vision if no admin default is
+ *     configured and the main model supports images.
+ *   - If neither is available, falls back to the first available
  *     vision-capable model by provider priority.
  *
  * Hooks into the `context` event to intercept ALL images before they reach
  * the LLM (covers user-attached images and tool-result images alike).
  */
-import { streamSimple } from "../pi/ai/index.js";
+import { streamSimple } from "../sdk/ai/index.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Find the best available vision-capable model from the registry */
-function findVisionModel(ctx) {
+/**
+ * Check if the SettingsManager has an admin-configured default vision model
+ * with working auth. Returns the model if found and auth-ready, or undefined.
+ */
+function getAdminVisionModel(ctx) {
+    const settings = ctx.settingsManager;
+    if (!settings)
+        return undefined;
+    const defaultVisionProvider = settings.getDefaultVisionProvider();
+    const defaultVisionModel = settings.getDefaultVisionModel();
+    if (!defaultVisionProvider || !defaultVisionModel)
+        return undefined;
     const allModels = ctx.modelRegistry.getAll();
-    const availableModels = allModels.filter((m) => ctx.modelRegistry.hasConfiguredAuth(m));
-    // Filter to models that support images
-    const visionModels = availableModels.filter((m) => m.input.includes("image"));
-    if (visionModels.length === 0)
+    const match = allModels.find((m) => m.provider === defaultVisionProvider && m.id === defaultVisionModel);
+    if (!match || !match.input.includes("image"))
         return undefined;
-    // 1. Try admin-configured default vision model from settings
-    const settings = ctx.settingsManager;
-    if (settings) {
-        const defaultVisionProvider = settings.getDefaultVisionProvider();
-        const defaultVisionModel = settings.getDefaultVisionModel();
-        if (defaultVisionProvider && defaultVisionModel) {
-            const match = visionModels.find((m) => m.provider === defaultVisionProvider && m.id === defaultVisionModel);
-            if (match) {
-                process.stderr.write(`[spectral-vision] Using admin-configured default: ${match.provider}/${match.id}\n`);
-                return match;
-            }
-        }
+    if (!ctx.modelRegistry.hasConfiguredAuth(match))
+        return undefined;
+    return match;
+}
+/**
+ * Resolve the best vision model to use for image descriptions.
+ *
+ * Priority:
+ *   1. Admin-configured default vision model (isVisionDefault from backend)
+ *   2. Current main model if it supports images
+ *   3. Best available vision model by provider priority
+ *   4. First available vision model
+ */
+function resolveVisionModel(ctx) {
+    // 1. Admin-configured default vision model (always preferred)
+    const adminModel = getAdminVisionModel(ctx);
+    if (adminModel) {
+        process.stderr.write(`[spectral-vision] Using admin-configured default: ${adminModel.provider}/${adminModel.id}\n`);
+        return adminModel;
     }
-    // 2. Fall back to provider priority
+    // 2. Current main model if it supports images
+    const currentModel = ctx.model;
+    if (currentModel?.input.includes("image") && ctx.modelRegistry.hasConfiguredAuth(currentModel)) {
+        process.stderr.write(`[spectral-vision] Using main model for vision: ${currentModel.provider}/${currentModel.id}\n`);
+        return currentModel;
+    }
+    // 3. Fall back to best available vision model by provider priority
+    const allModels = ctx.modelRegistry.getAll();
+    const visionModels = allModels.filter((m) => m.input.includes("image") && ctx.modelRegistry.hasConfiguredAuth(m));
+    if (visionModels.length === 0)
+        return undefined;
     const providerPriority = ["anthropic", "openai", "google", "openrouter"];
     for (const provider of providerPriority) {
         const match = visionModels.find((m) => m.provider === provider);
-        if (match)
+        if (match) {
+            process.stderr.write(`[spectral-vision] Using fallback vision model: ${match.provider}/${match.id}\n`);
             return match;
+        }
     }
-    return visionModels[0];
+    // 4. First available vision model
+    const fallback = visionModels[0];
+    process.stderr.write(`[spectral-vision] Using first available vision model: ${fallback.provider}/${fallback.id}\n`);
+    return fallback;
 }
 /** Check if any content block in an array is an image */
 function hasImageContent(content) {
@@ -111,6 +143,13 @@ async function describeImages(visionModel, content, contextText, ctx) {
         const textNote = description.trim()
             ? `[Image description from ${visionModel.provider}/${visionModel.id} (${imageCount} image(s)):\n${description}\n]`
             : `[${imageCount} image(s) — vision model returned empty description]`;
+        // Notify the frontend that the vision extension analyzed the image(s)
+        try {
+            ctx.ui.notify(`[spectral-vision] Analyzed ${imageCount} image(s) with ${visionModel.provider}/${visionModel.id}`, "info");
+        }
+        catch {
+            // UI context may not be available in headless modes
+        }
         return [
             ...textPrefixBlocks,
             { type: "text", text: textNote },
@@ -119,6 +158,13 @@ async function describeImages(visionModel, content, contextText, ctx) {
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[spectral-vision] Vision call failed: ${msg}\n`);
+        // Notify frontend about the failure
+        try {
+            ctx.ui.notify(`[spectral-vision] Failed to analyze ${imageCount} image(s): ${msg}`, "warning");
+        }
+        catch {
+            // UI context may not be available in headless modes
+        }
         return [
             ...textPrefixBlocks,
             {
@@ -134,7 +180,7 @@ async function describeImages(visionModel, content, contextText, ctx) {
 export default function spectralVisionExtension(pi) {
     let visionModel;
     pi.on("session_start", (_event, ctx) => {
-        visionModel = findVisionModel(ctx);
+        visionModel = resolveVisionModel(ctx);
         if (visionModel) {
             process.stderr.write(`[spectral-vision] Ready — using ${visionModel.provider}/${visionModel.id} for image descriptions.\n`);
         }
@@ -151,27 +197,19 @@ export default function spectralVisionExtension(pi) {
         }
         if (totalImages === 0)
             return;
-        // Resolve vision model
-        const currentModel = ctx.model;
-        // If main model supports images, use it for vision (saves auth setup)
-        if (currentModel?.input.includes("image")) {
-            visionModel = currentModel;
-        }
-        else {
-            // Refresh vision model
-            if (!visionModel ||
-                !ctx.modelRegistry.hasConfiguredAuth(visionModel)) {
-                visionModel = findVisionModel(ctx);
-            }
-        }
+        // Re-resolve vision model each time images are encountered.
+        // This ensures automatic switching to the admin-configured default
+        // vision model even when the main model supports vision.
+        visionModel = resolveVisionModel(ctx);
         if (!visionModel) {
             process.stderr.write("[spectral-vision] No vision model available, images will be omitted\n");
             return;
         }
         process.stderr.write(`[spectral-vision] Describing ${totalImages} image(s) with ${visionModel.provider}/${visionModel.id}...\n`);
-        // Process each message
+        // Process each message — intercept both user messages and tool results
+        // that contain images (e.g. read tool returning a screenshot).
         const processed = await Promise.all(messages.map(async (msg) => {
-            if (msg.role !== "user" || !Array.isArray(msg.content) || !hasImageContent(msg.content)) {
+            if ((msg.role !== "user" && msg.role !== "toolResult") || !Array.isArray(msg.content) || !hasImageContent(msg.content)) {
                 return msg;
             }
             // Extract context from preceding text blocks

package/dist/mcp/agent-dir.js

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 export function getAgentDir() {
     const configured = process.env.PI_CODING_AGENT_DIR?.trim();
     if (!configured) {
-        return join(homedir(), ".pi", "agent");
+        return join(homedir(), ".spectral", "agent");
     }
     if (configured === "~") {
         return homedir();

package/dist/mcp/config.js

@@ -5,7 +5,7 @@ import { dirname, join, resolve } from "node:path";
 import { getAgentPath } from "./agent-dir.js";
 const GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");
 const PROJECT_CONFIG_NAME = ".mcp.json";
-const PROJECT_PI_CONFIG_NAME = ".pi/mcp.json";
+const PROJECT_MCP_CONFIG_NAME = ".spectral/mcp.json";
 const REPOPROMPT_BINARY_CANDIDATES = [
     join(homedir(), "RepoPrompt", "repoprompt_cli"),
     "/Applications/Repo Prompt.app/Contents/MacOS/repoprompt-mcp",
@@ -32,7 +32,7 @@ export function getProjectConfigPath(cwd = process.cwd()) {
     return resolve(cwd, PROJECT_CONFIG_NAME);
 }
 export function getProjectPiConfigPath(cwd = process.cwd()) {
-    return resolve(cwd, PROJECT_PI_CONFIG_NAME);
+    return resolve(cwd, PROJECT_MCP_CONFIG_NAME);
 }
 export function getConfigDiscoveryPaths(overridePath) {
     return getConfigSources(overridePath).map((source) => ({
@@ -368,7 +368,7 @@ function findProjectRoot(cwd = process.cwd()) {
         if (existsSync(join(current, ".git"))
             || existsSync(join(current, "package.json"))
             || existsSync(join(current, PROJECT_CONFIG_NAME))
-            || existsSync(join(current, ".pi"))) {
+            || existsSync(join(current, ".spectral"))) {
             return current;
         }
         const parent = dirname(current);

package/dist/mcp/init.js

@@ -208,15 +208,7 @@ export function flushMetadataCache(state) {
         }
     }
 }
-function safeFg(ui, color, text) {
-    try {
-        const styled = ui?.theme?.fg?.(color, text);
-        if (styled)
-            return styled;
-    }
-    catch {
-        // fall through to plain text
-    }
+function safeFg(_ui, _color, text) {
     return text;
 }
 export function updateStatusBar(state) {

package/dist/mcp/sampling-handler.js

@@ -1,4 +1,4 @@
-import { complete } from "../pi/ai/index.js";
+import { complete } from "../sdk/ai/index.js";
 import { truncateAtWord } from "./utils.js";
 import { CreateMessageRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 export function registerSamplingHandler(client, options) {

package/dist/mcp/server-manager.js

@@ -96,6 +96,8 @@ export class McpServerManager {
             }
             // Check for UnauthorizedError — server requires OAuth.
             // This can fire from createHttpTransport probe or client.connect.
+            // transport may be undefined if createHttpTransport threw during the probe
+            // before returning a transport; close() handles this safely.
             if (error instanceof UnauthorizedError && supportsOAuth(definition)) {
                 return {
                     client,
@@ -239,7 +241,9 @@ export class McpServerManager {
         connection.status = "closed";
         this.connections.delete(name);
         await connection.client.close().catch(() => { });
-        await connection.transport.close().catch(() => { });
+        if (connection.transport) {
+            await connection.transport.close().catch(() => { });
+        }
     }
     async closeAll() {
         const names = [...this.connections.keys()];

package/dist/memory/commands/status.js

@@ -1,4 +1,4 @@
-import { SettingsManager } from "../../pi/coding-agent/index.js";
+import { SettingsManager } from "../../sdk/coding-agent/index.js";
 import { getMemoryState, rawTokensSinceLastBound, rawTokensSinceLastCompaction, } from "../branch.js";
 import { observationPoolTokens as estimateObservationPoolTokens } from "../compaction.js";
 import { countByRelevance, formatRelevanceHistogram } from "../relevance.js";

package/dist/memory/compaction.js

@@ -1,5 +1,5 @@
-import { agentLoop } from "../pi/agent-core/index.js";
-import { Type } from "../pi/ai/index.js";
+import { agentLoop } from "../sdk/agent-core/index.js";
+import { Type } from "../sdk/ai/index.js";
 import { debugLog, isDebugLogEnabled } from "./debug-log.js";
 import { hashId } from "./ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "./model-budget.js";

package/dist/memory/config.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "../pi/coding-agent/index.js";
+import { getAgentDir } from "../sdk/coding-agent/index.js";
 export const DEFAULTS = {
     observationThresholdTokens: 1_000,
     compactionThresholdTokens: 50_000,
-    reflectionThresholdTokens: 30_000,
+    reflectionThresholdTokens: 10_000,
     passive: false,
     debugLog: false,
     observerMaxChunkTokens: 30_000,
@@ -72,7 +72,7 @@ function readNamespacedConfig(path) {
 }
 export function loadConfig(cwd, env = process.env) {
     const globalPath = join(getAgentDir(), "settings.json");
-    const projectPath = join(cwd, ".pi", "settings.json");
+    const projectPath = join(cwd, ".spectral", "settings.json");
     return {
         ...DEFAULTS,
         ...readNamespacedConfig(globalPath),

package/dist/memory/debug-log.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "../pi/coding-agent/index.js";
+import { getAgentDir } from "../sdk/coding-agent/index.js";
 export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
 export const DEBUG_LOG_RELATIVE_PATH = join("observational-memory", "debug.ndjson");
 const storage = new AsyncLocalStorage();

package/dist/memory/index.js

@@ -6,6 +6,7 @@ import { registerObserverTrigger } from "./hooks/observer-trigger.js";
 import { Runtime } from "./runtime.js";
 import { registerRecallTool } from "./tools/recall-observation.js";
 import { registerReadProjectObservationsTool } from "./tools/read-project-observations.js";
+import { registerWriteProjectObservationTool } from "./tools/write-project-observation.js";
 export default function observationalMemory(pi) {
     const runtime = new Runtime();
     // Log extension load so we can confirm it's running in serve mode.
@@ -17,4 +18,5 @@ export default function observationalMemory(pi) {
     registerViewCommand(pi, runtime);
     registerRecallTool(pi);
     registerReadProjectObservationsTool(pi);
+    registerWriteProjectObservationTool(pi);
 }

package/dist/memory/observer.js

@@ -1,5 +1,5 @@
-import { agentLoop } from "../pi/agent-core/index.js";
-import { Type } from "../pi/ai/index.js";
+import { agentLoop } from "../sdk/agent-core/index.js";
+import { Type } from "../sdk/ai/index.js";
 import { hashId } from "./ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "./model-budget.js";
 import { OBSERVER_SYSTEM } from "./prompts.js";

package/dist/memory/tokens.js

@@ -1,4 +1,4 @@
-import { estimateTokens as estimateMessageTokens } from "../pi/coding-agent/index.js";
+import { estimateTokens as estimateMessageTokens } from "../sdk/coding-agent/index.js";
 export function estimateStringTokens(text) {
     return Math.ceil(text.length / 4);
 }

package/dist/memory/tools/read-project-observations.js

@@ -1,5 +1,5 @@
-import { Type } from "../../pi/ai/index.js";
-import { defineTool } from "../../pi/coding-agent/index.js";
+import { Type } from "../../sdk/ai/index.js";
+import { defineTool } from "../../sdk/coding-agent/index.js";
 import { getProjectObsStore } from "../project-observations-store.js";
 export const READ_PROJECT_OBSERVATIONS_TOOL_NAME = "read_project_observations";
 export const readProjectObservationsTool = defineTool({

package/dist/memory/tools/recall-observation.js

@@ -1,5 +1,5 @@
-import { Type } from "../../pi/ai/index.js";
-import { defineTool } from "../../pi/coding-agent/index.js";
+import { Type } from "../../sdk/ai/index.js";
+import { defineTool } from "../../sdk/coding-agent/index.js";
 import { recallMemorySources, } from "../branch.js";
 import { renderRecallSourceEntries, renderRecallSourceEntry } from "../serialize.js";
 import { estimateEntryTokens } from "../tokens.js";

package/dist/memory/tools/write-project-observation.js

@@ -0,0 +1,60 @@
+import { Type } from "../../sdk/ai/index.js";
+import { defineTool } from "../../sdk/coding-agent/index.js";
+import { getProjectObsStore } from "../project-observations-store.js";
+import { hashId } from "../ids.js";
+export const WRITE_PROJECT_OBSERVATION_TOOL_NAME = "write_project_observation";
+export const writeProjectObservationTool = defineTool({
+    name: WRITE_PROJECT_OBSERVATION_TOOL_NAME,
+    label: "Write project observation",
+    description: "Write a durable, cross-session observation about this project. " +
+        "Use this to persist discovered conventions, architectural rules, " +
+        "gotchas, and directory purposes. Observations are deduplicated by " +
+        "content hash — writing the same fact twice is harmless (idempotent). " +
+        "Future sessions can discover these via read_project_observations.",
+    promptSnippet: "Use write_project_observation(content, relevance) to persist project-level knowledge.",
+    promptGuidelines: [
+        "Use for STABLE facts: conventions, architecture decisions, gotchas, file roles.",
+        "Use relevance='critical' for NEVER-EDIT rules (auto-generated files, invariant constraints).",
+        "Use relevance='high' for important conventions the agent must follow.",
+        "Use relevance='medium' for useful patterns and directory purposes.",
+        "Content must be a single, self-contained sentence — no markdown, no lists.",
+        "Deduplication is automatic — same content = same ID → INSERT OR REPLACE.",
+    ],
+    parameters: Type.Object({
+        content: Type.String({
+            minLength: 1,
+            description: "A single self-contained sentence describing the fact. No markdown, no lists.",
+        }),
+        relevance: Type.Union([
+            Type.Literal("low"),
+            Type.Literal("medium"),
+            Type.Literal("high"),
+            Type.Literal("critical"),
+        ], { description: "Importance: critical > high > medium > low" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const store = getProjectObsStore();
+        if (!store) {
+            return {
+                content: [{ type: "text", text: "Project observations store is not available." }],
+                details: { status: "store_unavailable" },
+            };
+        }
+        const projectId = store.getProjectByCwd(ctx.cwd);
+        if (!projectId) {
+            return {
+                content: [{ type: "text", text: `No project found for current working directory: ${ctx.cwd}` }],
+                details: { status: "no_project" },
+            };
+        }
+        const id = hashId(params.content);
+        store.insertProjectObservations(projectId, "auto-research", [{ id, content: params.content, relevance: params.relevance }], Date.now());
+        return {
+            content: [{ type: "text", text: `Observation [${id}] recorded (relevance: ${params.relevance}).` }],
+            details: { id, status: "ok" },
+        };
+    },
+});
+export function registerWriteProjectObservationTool(pi) {
+    pi.registerTool(writeProjectObservationTool);
+}