@easynet/agent-runtime 1.0.1

package/src/malformed-tool-call-middleware.ts

@@ -0,0 +1,239 @@
+/**
+ * Middleware that recovers from malformed tool call errors produced by OSS LLMs.
+ *
+ * When models like Ollama-hosted open-source LLMs mix chain-of-thought reasoning
+ * into tool call JSON arguments, the server returns a 500 parsing error.
+ * This middleware catches those errors, extracts the valid JSON from the raw text,
+ * and constructs a proper AIMessage so the agent loop can continue.
+ */
+import { createMiddleware } from "langchain";
+import { AIMessage } from "@langchain/core/messages";
+
+export interface MalformedToolCallMiddlewareConfig {
+  /** Maximum retry attempts after JSON extraction fails. Default: 1 */
+  maxRetries?: number;
+  /** Log recovery attempts to stderr. Default: true */
+  verbose?: boolean;
+}
+
+interface OllamaToolCallError {
+  rawText: string;
+}
+
+interface ExtractedToolCall {
+  toolName: string;
+  args: Record<string, unknown>;
+  id?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect Ollama "500 error parsing tool call" errors and extract the raw text.
+ * Error format: `500 error parsing tool call: raw='<raw_text>', err=invalid character...`
+ */
+function parseOllamaToolCallError(err: Error): OllamaToolCallError | null {
+  const msg = err.message;
+  const rawMatch = msg.match(/error parsing tool call.*?raw='(.+?)',\s*err=/s);
+  if (!rawMatch) return null;
+  return { rawText: rawMatch[1] };
+}
+
+/**
+ * Extract valid JSON object from a string that may contain leading non-JSON text.
+ * Uses brace-depth counting to find matching `{...}` blocks.
+ */
+function extractJsonObject(text: string): Record<string, unknown> | null {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "{") continue;
+
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    let end = -1;
+
+    for (let j = i; j < text.length; j++) {
+      const ch = text[j];
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = !inString;
+        continue;
+      }
+      if (inString) continue;
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          end = j;
+          break;
+        }
+      }
+    }
+    if (end === -1) continue;
+
+    const candidate = text.slice(i, end + 1);
+    try {
+      const parsed = JSON.parse(candidate) as unknown;
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // not valid JSON from this position, try next '{'
+    }
+  }
+  return null;
+}
+
+/**
+ * Match extracted JSON keys against available tool schemas to infer the tool name.
+ */
+function matchToolByArgs(
+  args: Record<string, unknown>,
+  tools: ReadonlyArray<{ name: string; schema?: unknown }>,
+): string | null {
+  const argKeys = new Set(Object.keys(args));
+  let bestMatch: string | null = null;
+  let bestScore = 0;
+
+  for (const tool of tools) {
+    const schema = tool.schema as
+      | { properties?: Record<string, unknown> }
+      | { shape?: Record<string, unknown> }
+      | null
+      | undefined;
+    const propKeys =
+      (schema && "properties" in schema && schema.properties
+        ? Object.keys(schema.properties)
+        : schema && "shape" in schema && schema.shape
+          ? Object.keys(schema.shape)
+          : null);
+    if (!propKeys) continue;
+
+    let score = 0;
+    for (const key of argKeys) {
+      if (propKeys.includes(key)) score++;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = tool.name;
+    }
+  }
+  return bestMatch;
+}
+
+function generateToolCallId(): string {
+  return `call_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Middleware
+// ---------------------------------------------------------------------------
+
+export function malformedToolCallMiddleware(
+  config?: MalformedToolCallMiddlewareConfig,
+) {
+  const maxRetries = config?.maxRetries ?? 1;
+  const verbose = config?.verbose ?? true;
+
+  const log = verbose
+    ? (msg: string) => console.error(`[malformedToolCallRecovery] ${msg}`)
+    : () => {};
+
+  function tryExtract(
+    rawText: string,
+    tools: ReadonlyArray<{ name: string; schema?: unknown }>,
+  ): ExtractedToolCall | null {
+    const args = extractJsonObject(rawText);
+    if (!args) return null;
+
+    const toolName =
+      matchToolByArgs(args, tools) ?? tools[0]?.name ?? "unknown_tool";
+    return { toolName, args, id: generateToolCallId() };
+  }
+
+  function buildAIMessage(tc: ExtractedToolCall): AIMessage {
+    return new AIMessage({
+      content: "",
+      tool_calls: [{ name: tc.toolName, args: tc.args, id: tc.id }],
+    });
+  }
+
+  return createMiddleware({
+    name: "malformedToolCallRecovery",
+
+    wrapModelCall: async (request, handler) => {
+      // --- Normal call ---
+      try {
+        return await handler(request);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const parsed = parseOllamaToolCallError(err);
+        if (!parsed) throw err; // not our error type
+
+        log("Caught malformed tool call error. Attempting JSON extraction...");
+
+        // Cast tools to access name/schema for matching
+        const req = request as unknown as Record<string, unknown>;
+        const tools = (req.tools ?? []) as ReadonlyArray<{
+          name: string;
+          schema?: unknown;
+        }>;
+        const systemPrompt = req.systemPrompt as string | undefined;
+
+        // --- Strategy A: extract JSON directly from the error text ---
+        const extracted = tryExtract(parsed.rawText, tools);
+        if (extracted) {
+          log(`Extracted JSON for tool "${extracted.toolName}".`);
+          return buildAIMessage(extracted);
+        }
+
+        // --- Strategy B: retry with enhanced prompt ---
+        log(`JSON extraction failed. Retrying (${maxRetries} attempts)...`);
+
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+          try {
+            const retryRequest = {
+              ...request,
+              systemPrompt:
+                (systemPrompt ?? "") +
+                "\n\nCRITICAL: Tool call arguments MUST be a single valid JSON object. " +
+                "Do NOT include any reasoning text before or after the JSON.",
+            };
+            return await handler(retryRequest);
+          } catch (retryError) {
+            const retryErr =
+              retryError instanceof Error
+                ? retryError
+                : new Error(String(retryError));
+            const retryParsed = parseOllamaToolCallError(retryErr);
+            if (retryParsed) {
+              const retryExtracted = tryExtract(retryParsed.rawText, tools);
+              if (retryExtracted) {
+                log(`Extracted JSON on retry ${attempt + 1} for tool "${retryExtracted.toolName}".`);
+                return buildAIMessage(retryExtracted);
+              }
+            }
+            log(`Retry ${attempt + 1}/${maxRetries} failed.`);
+          }
+        }
+
+        // --- All strategies exhausted ---
+        log("All recovery attempts failed. Returning error to agent loop.");
+        return new AIMessage({
+          content:
+            "Tool call failed due to malformed output from the model. " +
+            "Please try a simpler command or rephrase your request.",
+        });
+      }
+    },
+  });
+}

package/src/markdown-it-terminal.d.ts

@@ -0,0 +1,4 @@
+declare module "markdown-it-terminal" {
+  const plugin: (...args: unknown[]) => void;
+  export default plugin;
+}

package/src/marked-terminal.d.ts

@@ -0,0 +1,16 @@
+declare module "marked-terminal" {
+  import type { MarkedExtension } from "marked";
+
+  export interface MarkedTerminalOptions {
+    [key: string]: unknown;
+  }
+
+  export interface HighlightOptions {
+    [key: string]: unknown;
+  }
+
+  export function markedTerminal(
+    options?: MarkedTerminalOptions,
+    highlightOptions?: HighlightOptions,
+  ): MarkedExtension;
+}