@aexol/spectral 0.2.7 → 0.2.9

package/dist/mcp/tool-registrar.js

@@ -1,28 +1,67 @@
 // tool-registrar.ts - MCP content transformation
 // NOTE: Tools are NOT registered with Pi - only the unified `mcp` proxy tool is registered.
 // This keeps the LLM context small (1 tool instead of 100s).
+/**
+ * Maximum characters per text block from MCP tool results.
+ *
+ * MCP tools (especially Playwright's browser_snapshot, browser_evaluate,
+ * browser_network_requests) can return massive content — accessibility
+ * trees of 100-500KB, large JSON arrays, etc. When passed untruncated into
+ * pi's ToolResultMessage.content, they blow up the LLM context window,
+ * causing API errors (400/413) and dead sessions ("skipping empty
+ * intermediate message" loops).
+ *
+ * 20,000 characters ≈ 5,000-8,000 tokens depending on the model, which
+ * keeps individual tool results manageable even across multiple MCP calls
+ * in the same turn.
+ */
+const MAX_MCP_TEXT_LENGTH = 20_000;
+function truncateTextBlock(block) {
+    if (block.type !== "text")
+        return block;
+    if (block.text.length <= MAX_MCP_TEXT_LENGTH)
+        return block;
+    const omitted = block.text.length - MAX_MCP_TEXT_LENGTH;
+    return {
+        type: "text",
+        text: block.text.slice(0, MAX_MCP_TEXT_LENGTH) +
+            `\n\n[truncated — ${omitted.toLocaleString()} bytes omitted. ` +
+            `Use more specific tool calls or narrower queries to get complete results.]`,
+    };
+}
 /**
  * Transform MCP content types to Pi content blocks.
+ *
+ * Text blocks exceeding MAX_MCP_TEXT_LENGTH are truncated to prevent
+ * context-window overflow in downstream LLM calls.
  */
 export function transformMcpContent(content) {
     return content.map(c => {
         if (c.type === "text") {
-            return { type: "text", text: c.text ?? "" };
+            return truncateTextBlock({ type: "text", text: c.text ?? "" });
         }
         if (c.type === "image") {
+            // Most LLM APIs reject ImageContent blocks inside tool-result
+            // messages (even multimodal models often only accept images in
+            // user-turn content, not in tool results).  Passing through
+            // base64 images here causes 400 errors and dead sessions.
+            // Convert to a text placeholder that preserves metadata.
+            const sizeBytes = c.data?.length ?? 0;
             return {
-                type: "image",
-                data: c.data ?? "",
-                mimeType: c.mimeType ?? "image/png",
+                type: "text",
+                text: `[Image: ${c.mimeType ?? "image/png"}, ${sizeBytes.toLocaleString()} bytes base64]` +
+                    `\n(Image data is available in the raw MCP result — use direct tool\n` +
+                    `calls like browser_take_screenshot or browser_run_code to\n` +
+                    `save/process images to disk for further analysis.)`,
             };
         }
         if (c.type === "resource") {
             const resourceUri = c.resource?.uri ?? "(no URI)";
             const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
-            return {
+            return truncateTextBlock({
                 type: "text",
                 text: `[Resource: ${resourceUri}]\n${resourceContent}`,
-            };
+            });
         }
         if (c.type === "resource_link") {
             const linkName = c.name ?? c.uri ?? "unknown";
@@ -38,6 +77,6 @@ export function transformMcpContent(content) {
                 text: `[Audio content: ${c.mimeType ?? "audio/*"}]`,
             };
         }
-        return { type: "text", text: JSON.stringify(c) };
+        return truncateTextBlock({ type: "text", text: JSON.stringify(c) });
     });
 }

package/dist/relay/dispatcher.js

@@ -39,6 +39,7 @@
  *    transparent to this layer — we just respond when we can.
  */
 import { BadRequestError, NotFoundError } from "../server/handlers/errors.js";
+import { handlePathAutocomplete } from "../server/handlers/paths-autocomplete.js";
 import { handleCreateProject, handleDeleteProject, handleListProjects, handleListSessionsByProject, handleUpdateProject, } from "../server/handlers/projects.js";
 import { handleCreateSession, handleDeleteSession, handleGetSessionDetail, handleUpdateSession, } from "../server/handlers/sessions.js";
 import { shutdownState } from "../server/shutdown.js";
@@ -50,9 +51,16 @@ import { shutdownState } from "../server/shutdown.js";
  * also marginally slower and harder to read for ~9 routes.
  */
 export function matchRoute(method, path) {
-    // Strip query string if any (we don't use any, but be defensive).
+    // Strip query string for path matching but keep it for the handler.
     const qIdx = path.indexOf("?");
     const cleanPath = qIdx === -1 ? path : path.slice(0, qIdx);
+    const query = qIdx >= 0 ? new URLSearchParams(path.slice(qIdx + 1)) : undefined;
+    // /api/paths/autocomplete
+    if (cleanPath === "/api/paths/autocomplete") {
+        if (method === "GET")
+            return { route: "list_path_autocomplete", query };
+        return null;
+    }
     // /api/projects
     if (cleanPath === "/api/projects") {
         if (method === "GET")
@@ -267,6 +275,10 @@ function dispatchRoute(match, body, deps) {
             }
             return { ok: true };
         }
+        case "list_path_autocomplete": {
+            const prefix = match.query?.get("prefix") ?? "";
+            return handlePathAutocomplete(prefix);
+        }
     }
 }
 /**

package/dist/server/handlers/paths-autocomplete.js

@@ -0,0 +1,67 @@
+/**
+ * Filesystem autocomplete for project path creation.
+ *
+ * When a user types a partial path in the New Project form, the browser
+ * sends `GET /api/paths/autocomplete?prefix=<partial>`. This handler
+ * expands the prefix (tilde → $HOME, relative → absolute), lists the
+ * containing directory, and returns up to 10 directory suggestions whose
+ * basenames start with the typed partial segment.
+ *
+ * Dotfiles are excluded — they are rarely intentional project roots.
+ * Symlinks to directories ARE included (readdirSync with withFileTypes
+ * returns true for both real dirs and symlink dirs).
+ *
+ * Thread-safety: synchronous, called from the relay-dispatcher hot path.
+ * fs ops block the event loop for microseconds on local SSDs; the form
+ * is typed by a single human, so this is perfectly fine.
+ */
+import { readdirSync } from "node:fs";
+import { join, sep } from "node:path";
+import { expandPath } from "../paths.js";
+/**
+ * List directories inside `expandedPrefix`'s parent that start with the
+ * trailing (post-separator) segment of the expanded prefix.
+ *
+ * Examples (assume $HOME=/Users/alice, dirs are `projects`, `proj-old`,
+ * `Documents`, `.config`):
+ *   prefix="~/pro"  → expanded="/Users/alice/pro", parent="/Users/alice/"
+ *                      → ["/Users/alice/projects", "/Users/alice/proj-old"]
+ *   prefix="~/proj" → expanded="/Users/alice/proj"
+ *                      → ["/Users/alice/projects"]
+ *   prefix="~"      → expanded="/Users/alice", parent="/Users/alice/"
+ *                      → all top-level dirs in $HOME (except dotfiles)
+ */
+export function handlePathAutocomplete(prefix) {
+    const expanded = expandPath(prefix);
+    // Split into parent directory and basename prefix.
+    // On POSIX, `expanded` is always absolute after expandPath, so we
+    // always hit the else branch below with a trailing sep.
+    const lastSep = expanded.lastIndexOf(sep);
+    let parentDir;
+    let basenamePrefix;
+    if (lastSep < 0) {
+        // Shouldn't happen after expandPath, but be defensive.
+        parentDir = expanded;
+        basenamePrefix = "";
+    }
+    else {
+        parentDir = expanded.slice(0, lastSep + 1);
+        basenamePrefix = expanded.slice(lastSep + 1);
+    }
+    let suggestions = [];
+    try {
+        const entries = readdirSync(parentDir, { withFileTypes: true });
+        suggestions = entries
+            .filter((e) => e.isDirectory() &&
+            e.name.startsWith(basenamePrefix) &&
+            !e.name.startsWith("."))
+            .map((e) => join(parentDir, e.name))
+            .slice(0, 10); // keep the list short for the UI
+    }
+    catch {
+        // Directory doesn't exist or is unreadable → return empty list.
+        // The caller (dispatcher) returns a 200 with an empty suggestions[]
+        // so the UI can show a "no matching directories" hint.
+    }
+    return { suggestions, expandedPrefix: expanded };
+}

package/dist/server/pi-bridge.js

@@ -158,6 +158,84 @@ function lookupPricing(modelId) {
     }
     return null;
 }
+/**
+ * Parse the newline-delimited JSON of wire events persisted alongside an
+ * assistant message and extract all tool_call / tool_result events.
+ *
+ * These are used during session rehydration to reconstruct the full tool
+ * interaction history (call → result) so the LLM context is complete —
+ * without this, reconnected sessions would see only the assistant text
+ * and never the tool results, causing the model to get confused about
+ * the conversation state.
+ */
+function parseWireToolEvents(eventsJsonl) {
+    const toolCalls = [];
+    const toolResults = [];
+    if (!eventsJsonl)
+        return { toolCalls, toolResults };
+    for (const line of eventsJsonl.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const ev = JSON.parse(trimmed);
+            if (ev.type === "tool_call") {
+                toolCalls.push({
+                    id: ev.id,
+                    name: ev.name,
+                    arguments: ev.args ?? {},
+                });
+            }
+            else if (ev.type === "tool_result") {
+                toolResults.push({
+                    id: ev.id,
+                    result: ev.result,
+                    isError: ev.isError ?? false,
+                });
+            }
+        }
+        catch {
+            // Skip malformed JSON lines — they won't be meaningful for
+            // rehydration and we'd rather keep the session alive than fail.
+        }
+    }
+    return { toolCalls, toolResults };
+}
+/**
+ * Safety clean-up for content blocks rehydrated from persisted wire events.
+ *
+ * Sessions created before the fixes in tool-registrar.ts may carry raw
+ * ImageContent (base64 blobs) and untruncated large text blocks in their
+ * events_jsonl. When replayed into a fresh session manager without cleanup
+ * they can trigger 400 API errors (unsupported image content in tool results)
+ * or context-window overflow — both surface as "skipping empty intermediate
+ * message" / hung sessions after reconnect.
+ */
+const MAX_REHYDRATED_TEXT = 20_000;
+function sanitizeRehydratedBlock(block) {
+    // Convert images to text placeholders — most LLM APIs reject
+    // ImageContent inside tool-result messages (even multimodal
+    // models often only accept images in user-turn content).
+    if (block.type === "image") {
+        const sizeBytes = typeof block.data === "string" ? block.data.length : 0;
+        return {
+            type: "text",
+            text: `[Image: ${block.mimeType ?? "image/png"}, ${sizeBytes.toLocaleString()} bytes base64]` +
+                `\n(Image data is available in the raw MCP result.)`,
+        };
+    }
+    // Truncate oversized text blocks to prevent context overflow.
+    if (block.type !== "text")
+        return block;
+    if (block.text.length <= MAX_REHYDRATED_TEXT)
+        return block;
+    const omitted = block.text.length - MAX_REHYDRATED_TEXT;
+    return {
+        ...block,
+        text: block.text.slice(0, MAX_REHYDRATED_TEXT) +
+            `\n\n[truncated — ${omitted.toLocaleString()} bytes omitted]`,
+    };
+}
 export class PiBridge {
     session;
     unsubscribe;
@@ -227,8 +305,11 @@ export class PiBridge {
         const sessionManager = SessionManager.inMemory(this.opts.cwd);
         // Rehydrate session history so the LLM sees the full conversation
         // transcript from the beginning (not just the current prompt).
-        // Previously this was documented as a "History rehydration
-        // limitation" — the UI saw the transcript but pi did not.
+        // Tool calls and their results are reconstructed from the persisted
+        // wire-event JSONL so the LLM context is complete — without them
+        // reconnected sessions would see assistant messages that reference
+        // tool invocations whose results never appear, causing hung/confused
+        // responses.
         if (this.opts.history && this.opts.history.length > 0) {
             for (const msg of this.opts.history) {
                 if (msg.role === "user") {
@@ -249,10 +330,31 @@ export class PiBridge {
                     });
                 }
                 else if (msg.role === "assistant") {
-                    const textBlocks = msg.content ? [{ type: "text", text: msg.content }] : [];
+                    // Parse wire events to reconstruct tool calls & results from the
+                    // original turn. Without this, reconnected sessions lose all tool
+                    // interaction context.
+                    const { toolCalls, toolResults } = parseWireToolEvents(msg.events);
+                    // Build a toolCallId → toolName lookup for tool result messages.
+                    const toolNameById = new Map();
+                    for (const tc of toolCalls) {
+                        toolNameById.set(tc.id, tc.name);
+                    }
+                    // Build assistant message content: text + reconstructed ToolCall blocks.
+                    const content = [];
+                    if (msg.content) {
+                        content.push({ type: "text", text: msg.content });
+                    }
+                    for (const tc of toolCalls) {
+                        content.push({
+                            type: "toolCall",
+                            id: tc.id,
+                            name: tc.name,
+                            arguments: tc.arguments,
+                        });
+                    }
                     sessionManager.appendMessage({
                         role: "assistant",
-                        content: textBlocks,
+                        content,
                         api: "anthropic-messages",
                         provider: "spectral-proxy-anthropic",
                         model: "unknown",
@@ -264,9 +366,34 @@ export class PiBridge {
                             totalTokens: 0,
                             cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
                         },
-                        stopReason: "stop",
+                        stopReason: toolCalls.length > 0
+                            ? "toolUse"
+                            : "stop",
                         timestamp: msg.createdAt,
                     });
+                    // Append tool result messages so the LLM sees the full tool
+                    // interaction (call → result → next assistant response).
+                    //
+                    // Safety: truncate text blocks here too — sessions created before
+                    // the truncation fix (in tool-registrar.ts) may have untruncated
+                    // large MCP results in their wire events, which would overflow the
+                    // context window when replayed into the fresh session manager.
+                    for (const tr of toolResults) {
+                        const toolName = toolNameById.get(tr.id) ?? "unknown";
+                        const rawResult = tr.result;
+                        const rawContent = Array.isArray(rawResult?.content)
+                            ? rawResult.content
+                            : [];
+                        sessionManager.appendMessage({
+                            role: "toolResult",
+                            toolCallId: tr.id,
+                            toolName,
+                            content: rawContent.map(sanitizeRehydratedBlock),
+                            details: rawResult?.details,
+                            isError: tr.isError,
+                            timestamp: msg.createdAt,
+                        });
+                    }
                 }
                 // system messages are informational only; skip for LLM context
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
   "type": "module",
   "private": false,