@aexol/spectral 0.2.7 → 0.2.8

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/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.8",
   "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
   "type": "module",
   "private": false,