@ai.ntellect/core 0.8.3 → 1.1.0

package/agent/tools/tool-resolver.ts

@@ -0,0 +1,104 @@
+import * as fs from "fs";
+import * as path from "path";
+
+export type ResolvedEntity = {
+  type: "file" | "dir";
+  path: string;
+};
+
+export function resolvePath(userPath: string, cwd: string): ResolvedEntity[] {
+  const candidates: ResolvedEntity[] = [];
+  const absolutePath = path.isAbsolute(userPath) ? userPath : path.join(cwd, userPath);
+
+  if (fs.existsSync(absolutePath)) {
+    const stat = fs.statSync(absolutePath);
+    candidates.push({ type: stat.isDirectory() ? "dir" : "file", path: absolutePath });
+    return candidates;
+  }
+
+  if (path.isAbsolute(userPath)) {
+    return candidates;
+  }
+
+  const parentDir = path.dirname(absolutePath);
+  const baseName = path.basename(absolutePath);
+
+  if (fs.existsSync(parentDir)) {
+    const entries = fs.readdirSync(parentDir);
+    const lowerTarget = baseName.toLowerCase();
+
+    for (const entry of entries) {
+      if (entry.toLowerCase() === lowerTarget) {
+        const fullPath = path.join(parentDir, entry);
+        const stat = fs.statSync(fullPath);
+        candidates.push({ type: stat.isDirectory() ? "dir" : "file", path: fullPath });
+      }
+    }
+
+    const noExt = baseName.includes(".") ? null : baseName;
+    if (noExt) {
+      for (const entry of entries) {
+        const entryNoExt = entry.includes(".") ? entry.substring(0, entry.lastIndexOf(".")) : entry;
+        if (entryNoExt.toLowerCase() === noExt.toLowerCase()) {
+          const fullPath = path.join(parentDir, entry);
+          const stat = fs.statSync(fullPath);
+          candidates.push({ type: stat.isDirectory() ? "dir" : "file", path: fullPath });
+        }
+      }
+    }
+  }
+
+  if (candidates.length === 0) {
+    const root = cwd;
+    const rootEntries = fs.readdirSync(root);
+    const lowerBase = baseName.toLowerCase();
+
+    for (const entry of rootEntries) {
+      if (entry.toLowerCase() === lowerBase) {
+        const fullPath = path.join(root, entry);
+        const stat = fs.statSync(fullPath);
+        candidates.push({ type: stat.isDirectory() ? "dir" : "file", path: fullPath });
+        break;
+      }
+    }
+
+    if (candidates.length === 0) {
+      const noExt2 = baseName.includes(".") ? null : baseName;
+      if (noExt2) {
+        for (const entry of rootEntries) {
+          const entryNoExt = entry.includes(".") ? entry.substring(0, entry.lastIndexOf(".")) : entry;
+          if (entryNoExt.toLowerCase() === noExt2.toLowerCase()) {
+            const fullPath = path.join(root, entry);
+            const stat = fs.statSync(fullPath);
+            candidates.push({ type: stat.isDirectory() ? "dir" : "file", path: fullPath });
+          }
+        }
+      }
+    }
+  }
+
+  return candidates;
+}
+
+export function findInCwd(filename: string, cwd: string): string | null {
+  const entries = fs.readdirSync(cwd);
+  const lowerName = filename.toLowerCase();
+
+  for (const entry of entries) {
+    if (entry.toLowerCase() === lowerName) {
+      return path.join(cwd, entry);
+    }
+  }
+
+  const noExt = filename.includes(".") ? null : filename;
+  if (noExt) {
+    for (const entry of entries) {
+      const entryNoExt = entry.includes(".") ? entry.substring(0, entry.lastIndexOf(".")) : entry;
+      if (entryNoExt.toLowerCase() === noExt.toLowerCase()) {
+        return path.join(cwd, entry);
+      }
+    }
+  }
+
+  return null;
+}

package/benchmark/cortexflow-workflow.ts

@@ -0,0 +1,182 @@
+/**
+ * CortexFlow benchmark workflow — multi-step mail triage.
+ *
+ * LLM call budget (fixed regardless of inbox size):
+ *   #1  Intent classification  (CortexFlowOrchestrator)
+ *   #2  Batch urgency check    (one call for all N mails)
+ *   #3  Batch response draft   (one call for all urgent mails; skipped if none)
+ */
+import { TransitionAction } from '../routing/index';
+import { CortexFlowOrchestrator } from '../routing/orchestrator';
+import { ToolRegistry } from '../execution/registry';
+import { GraphFlow } from '../execution/index';
+import { z } from 'zod';
+import { HybridIntentClassifier } from '../routing/intent-classifier';
+import { google } from 'googleapis';
+import * as fs from 'fs';
+import * as path from 'path';
+import { LLMCall, safeParse } from './llm-client';
+
+// ---------------------------------------------------------------------------
+// Gmail helper
+// ---------------------------------------------------------------------------
+
+function createGmailClient() {
+  const credentials = JSON.parse(fs.readFileSync(path.join(__dirname, '../client_secret.json'), 'utf8'));
+  const token       = JSON.parse(fs.readFileSync(path.join(__dirname, '../gmail_token.json'), 'utf8'));
+  const oauth2Client = new google.auth.OAuth2(
+    credentials.web.client_id,
+    credentials.web.client_secret,
+    'http://localhost:3000/oauth2callback'
+  );
+  oauth2Client.setCredentials(token);
+  return google.gmail({ version: 'v1', auth: oauth2Client });
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export async function runCortexFlowBenchmark(llm: LLMCall) {
+  console.log('\n🚀 CortexFlow benchmark...\n');
+  llm.resetCount();
+
+  const startTime   = Date.now();
+  const startMemory = process.memoryUsage().heapUsed;
+
+  const gmail       = createGmailClient();
+  const toolRegistry = new ToolRegistry();
+  const orchestrator = new CortexFlowOrchestrator('mail_triage', toolRegistry);
+
+  // Intent classification — keyword rules first, LLM fallback for ambiguous messages.
+  // The benchmark input contains "fetch", "mail", "urgent", "archive" → keyword match,
+  // confidence 0.95, no LLM call needed for classification.
+  const classifier = new HybridIntentClassifier(
+    [
+      { intent: 'TRIAGE_MAILS', keywords: ['fetch', 'mail', 'urgent', 'archive'], confidence: 0.95 },
+      { intent: 'TRIAGE_MAILS', keywords: ['triage', 'mail'],                     confidence: 0.95 },
+      { intent: 'FETCH_MAILS',  keywords: ['fetch', 'email'],                     confidence: 0.90 },
+      { intent: 'FETCH_MAILS',  keywords: ['fetch', 'mail'],                      confidence: 0.90 },
+    ],
+    { intents: ['TRIAGE_MAILS', 'FETCH_MAILS', 'UNKNOWN'], confidenceThreshold: 0.6 },
+    llm.call.bind(llm), // LLM fallback for messages that don't match any rule
+  );
+  orchestrator.setIntentClassifier(HybridIntentClassifier.toFn(classifier), classifier);
+  orchestrator.setLLMCall(llm.call.bind(llm));
+
+  // ---------------------------------------------------------------------------
+  // Petri Net: idle ──[process_mails]──► processing ──[complete]──► done
+  // ---------------------------------------------------------------------------
+
+  const net = orchestrator.petri;
+  net.addPlace({ id: 'idle',       type: 'initial', tokens: [{ id: 'start', data: {}, createdAt: 0 }] });
+  net.addPlace({ id: 'processing', type: 'normal',  tokens: [] });
+  net.addPlace({ id: 'done',       type: 'final',   tokens: [] });
+
+  // ---------------------------------------------------------------------------
+  // GraphFlow — 4 nodes, 2 LLM calls
+  // ---------------------------------------------------------------------------
+
+  const mailGraph = new GraphFlow<any>({
+    name: 'process_mails',
+    context: { maxMails: 5 },
+    schema: z.object({ maxMails: z.number() }).passthrough(),
+    nodes: [
+      {
+        name: 'fetch_mails',
+        execute: async (ctx: any) => {
+          console.log('  [CortexFlow] Fetching mails...');
+          const res      = await gmail.users.messages.list({ userId: 'me', maxResults: ctx.maxMails || 5, q: '' });
+          const messages = res.data.messages || [];
+          ctx.mails = [];
+          for (const msg of messages) {
+            const detail  = await gmail.users.messages.get({ userId: 'me', id: msg.id!, format: 'metadata', metadataHeaders: ['Subject', 'From'] });
+            const headers = detail.data.payload?.headers || [];
+            ctx.mails.push({
+              id:      msg.id!,
+              subject: headers.find((h: any) => h.name === 'Subject')?.value || '(no subject)',
+              from:    headers.find((h: any) => h.name === 'From')?.value    || '(unknown)',
+            });
+          }
+          console.log(`  [CortexFlow] Fetched ${ctx.mails.length} mails`);
+        },
+        next: 'classify_urgency',
+      },
+      {
+        name: 'classify_urgency',
+        execute: async (ctx: any) => {
+          console.log('  [CortexFlow] Batch urgency (LLM call #2)...');
+          const mailList = ctx.mails.map((m: any, i: number) => `[${i}] From: ${m.from} | Subject: ${m.subject}`).join('\n');
+          const raw = await llm.call(
+            `For each email, is it urgent (needs reply today)? Urgent = deadline/ASAP/security alert/action required.\n\nEmails:\n${mailList}\n\nJSON: {"urgency":[{"index":0,"urgent":true},...]}`
+          );
+          const parsed  = safeParse<any>(raw, { urgency: [] });
+          const results: any[] = Array.isArray(parsed.urgency) ? parsed.urgency : [];
+          ctx.urgentMails    = ctx.mails.filter((_: any, i: number) => results.find((r: any) => r.index === i)?.urgent === true);
+          ctx.nonUrgentMails = ctx.mails.filter((_: any, i: number) => !results.find((r: any) => r.index === i)?.urgent);
+          console.log(`  [CortexFlow] Urgent: ${ctx.urgentMails.length}, Non-urgent: ${ctx.nonUrgentMails.length}`);
+        },
+        next: 'respond_urgent',
+      },
+      {
+        name: 'respond_urgent',
+        execute: async (ctx: any) => {
+          if (!ctx.urgentMails?.length) {
+            ctx.responses = [];
+            console.log('  [CortexFlow] No urgent mails — response generation skipped');
+            return;
+          }
+          console.log(`  [CortexFlow] Batch response draft for ${ctx.urgentMails.length} mail(s) (LLM call #3)...`);
+          const mailList = ctx.urgentMails.map((m: any, i: number) => `[${i}] From: ${m.from} | Subject: ${m.subject}`).join('\n');
+          const raw = await llm.call(
+            `Draft a brief professional reply (<40 words) for each urgent email.\n\nEmails:\n${mailList}\n\nJSON: {"responses":[{"index":0,"response":"..."},...]}`
+          );
+          const parsed = safeParse<any>(raw, { responses: [] });
+          ctx.responses = Array.isArray(parsed.responses) ? parsed.responses : [];
+          console.log(`  [CortexFlow] Drafted ${ctx.responses.length} response(s)`);
+        },
+        next: 'archive_others',
+      },
+      {
+        name: 'archive_others',
+        execute: async (ctx: any) => {
+          ctx.archivedCount = ctx.nonUrgentMails?.length || 0;
+          console.log(`  [CortexFlow] Archive: ${ctx.archivedCount} mail(s) (no LLM)`);
+        },
+      },
+    ],
+    entryNode: 'fetch_mails',
+  });
+
+  toolRegistry.register({
+    name: 'process_mails',
+    description: 'Fetch, triage, respond to urgent mails and archive the rest',
+    graph: mailGraph,
+    startNode: 'fetch_mails',
+  });
+
+  net.addTransition({
+    id: 'process_mails', from: ['idle'], to: 'processing',
+    action: { type: 'graphflow', name: 'process_mails', contextMapper: (ctx) => ({ maxMails: ctx.maxMails || 5 }) } as TransitionAction,
+  });
+  net.addTransition({ id: 'complete', from: ['processing'], to: 'done' });
+
+  const sessionId = orchestrator.startSession();
+  const result    = await orchestrator.orchestrate(
+    'Fetch my 5 latest mails, flag the urgent ones, draft replies for urgent mails, and archive the rest.',
+    sessionId
+  );
+
+  const ar = (result as any).transitionResult?.actionResult ?? {};
+  return {
+    framework:     'CortexFlow',
+    totalTime:     Date.now() - startTime,
+    llmCalls:      llm.callCount,
+    memoryUsed:    process.memoryUsage().heapUsed - startMemory,
+    mailsCount:    ar.mails?.length        ?? 0,
+    urgentCount:   ar.urgentMails?.length  ?? 0,
+    responsesCount: ar.responses?.length   ?? 0,
+    archivedCount: ar.archivedCount        ?? 0,
+    intentConfidence: result.intent.confidence,
+  };
+}

package/benchmark/langgraph-workflow.ts

@@ -0,0 +1,201 @@
+/**
+ * LangGraph benchmark workflows — multi-step mail triage.
+ *
+ * Two variants:
+ *
+ *   runLangGraphNaiveBenchmark     — one LLM call per urgency decision (N mails = N calls).
+ *                                    Mirrors the standard LangGraph supervisor/router pattern.
+ *                                    LLM calls: 1 intent + 5 urgency + 0–1 response = 6–7
+ *
+ *   runLangGraphOptimisedBenchmark — urgency batched manually by the developer.
+ *                                    LLM calls: 1 intent + 1 urgency batch + 0–1 response = 2–3
+ */
+import { StateGraph, Annotation } from '@langchain/langgraph';
+import { google } from 'googleapis';
+import * as fs from 'fs';
+import * as path from 'path';
+import { LLMCall, safeParse } from './llm-client';
+
+// ---------------------------------------------------------------------------
+// State definition
+// ---------------------------------------------------------------------------
+
+const MailState = Annotation.Root({
+  messages:      Annotation<Array<{ role: 'user' | 'assistant'; content: string }>>({
+    reducer: (curr, update) => curr.concat(update),
+  }),
+  intent:        Annotation<string>(),
+  mails:         Annotation<any[]>(),
+  urgentMails:   Annotation<any[]>(),
+  responses:     Annotation<any[]>(),
+  archivedCount: Annotation<number>(),
+  maxMails:      Annotation<number>(),
+});
+
+// ---------------------------------------------------------------------------
+// Gmail helper
+// ---------------------------------------------------------------------------
+
+async function fetchMails(maxResults = 5) {
+  console.log('  [LangGraph] Fetching mails...');
+  const credentials = JSON.parse(fs.readFileSync(path.join(__dirname, '../client_secret.json'), 'utf8'));
+  const token       = JSON.parse(fs.readFileSync(path.join(__dirname, '../gmail_token.json'), 'utf8'));
+  const oauth2Client = new google.auth.OAuth2(
+    credentials.web.client_id,
+    credentials.web.client_secret,
+    'http://localhost:3000/oauth2callback'
+  );
+  oauth2Client.setCredentials(token);
+  const gmail = google.gmail({ version: 'v1', auth: oauth2Client });
+
+  const res      = await gmail.users.messages.list({ userId: 'me', maxResults, q: '' });
+  const messages = res.data.messages || [];
+  const mails: any[] = [];
+  for (const msg of messages) {
+    const detail  = await gmail.users.messages.get({ userId: 'me', id: msg.id!, format: 'metadata', metadataHeaders: ['Subject', 'From'] });
+    const headers = detail.data.payload?.headers || [];
+    mails.push({
+      id:      msg.id,
+      subject: headers.find((h: any) => h.name === 'Subject')?.value || '(no subject)',
+      from:    headers.find((h: any) => h.name === 'From')?.value    || '(unknown)',
+    });
+  }
+  return mails;
+}
+
+// ---------------------------------------------------------------------------
+// Node factories (capture llm via closure)
+// ---------------------------------------------------------------------------
+
+function makeNodes(llm: LLMCall, variant: 'naive' | 'optimised') {
+  async function classifyIntent(state: typeof MailState.State) {
+    console.log(`  [LangGraph/${variant}] Classifying intent...`);
+    const last   = state.messages[state.messages.length - 1]?.content || '';
+    const raw    = await llm.call(
+      `Intent classifier. Intents: TRIAGE_MAILS, FETCH_MAILS, UNKNOWN.\nMessage: "${last}"\nJSON: {"intent":"INTENT","params":{"count":5}}`
+    );
+    const parsed = safeParse<any>(raw, { intent: 'TRIAGE_MAILS', params: { count: 5 } });
+    return { intent: parsed.intent, maxMails: parsed.params?.count || 5 };
+  }
+
+  async function fetchMailsNode(state: typeof MailState.State) {
+    const mails = await fetchMails(state.maxMails || 5);
+    console.log(`  [LangGraph/${variant}] Fetched ${mails.length} mails`);
+    return { mails };
+  }
+
+  /** Naive: one LLM call per mail. */
+  async function decideUrgencyNaive(state: typeof MailState.State) {
+    console.log(`  [LangGraph/naive] Urgency check per mail (${state.mails.length} LLM calls)...`);
+    const urgentMails: any[] = [];
+    for (const mail of state.mails) {
+      const raw    = await llm.call(
+        `Is this email urgent (needs reply today)? Urgent = security alert/deadline/ASAP/action required.\nFrom: ${mail.from}\nSubject: ${mail.subject}\nJSON: {"urgent":true}`
+      );
+      const parsed = safeParse<any>(raw, { urgent: false });
+      if (parsed.urgent === true) urgentMails.push(mail);
+    }
+    console.log(`  [LangGraph/naive] Urgent: ${urgentMails.length}`);
+    return { urgentMails };
+  }
+
+  /** Optimised: one batch LLM call for all mails. */
+  async function decideUrgencyBatch(state: typeof MailState.State) {
+    console.log('  [LangGraph/optimised] Batch urgency (1 LLM call)...');
+    const mailList = state.mails.map((m: any, i: number) => `[${i}] From: ${m.from} | Subject: ${m.subject}`).join('\n');
+    const raw      = await llm.call(
+      `For each email, is it urgent (needs reply today)?\n\nEmails:\n${mailList}\n\nJSON: {"urgency":[{"index":0,"urgent":true},...]}`
+    );
+    const parsed   = safeParse<any>(raw, { urgency: [] });
+    const results  = Array.isArray(parsed.urgency) ? parsed.urgency : [];
+    const urgentMails = state.mails.filter((_: any, i: number) => results.find((r: any) => r.index === i)?.urgent === true);
+    console.log(`  [LangGraph/optimised] Urgent: ${urgentMails.length}`);
+    return { urgentMails };
+  }
+
+  async function generateResponsesNode(state: typeof MailState.State) {
+    if (!state.urgentMails?.length) {
+      console.log(`  [LangGraph/${variant}] No urgent mails — skipping`);
+      return { responses: [] };
+    }
+    console.log(`  [LangGraph/${variant}] Batch response draft (1 LLM call)...`);
+    const mailList = state.urgentMails.map((m: any, i: number) => `[${i}] From: ${m.from} | Subject: ${m.subject}`).join('\n');
+    const raw      = await llm.call(
+      `Draft a brief professional reply (<40 words) for each urgent email.\n\nEmails:\n${mailList}\n\nJSON: {"responses":[{"index":0,"response":"..."},...]}`
+    );
+    const parsed   = safeParse<any>(raw, { responses: [] });
+    const responses = Array.isArray(parsed.responses) ? parsed.responses : [];
+    console.log(`  [LangGraph/${variant}] Drafted ${responses.length} response(s)`);
+    return { responses };
+  }
+
+  async function archiveNode(state: typeof MailState.State) {
+    const urgentIds = new Set((state.urgentMails || []).map((m: any) => m.id));
+    const count     = (state.mails || []).filter((m: any) => !urgentIds.has(m.id)).length;
+    console.log(`  [LangGraph/${variant}] Archive ${count} mail(s) (no LLM)`);
+    return { archivedCount: count };
+  }
+
+  return { classifyIntent, fetchMailsNode, decideUrgencyNaive, decideUrgencyBatch, generateResponsesNode, archiveNode };
+}
+
+// ---------------------------------------------------------------------------
+// Graph builder
+// ---------------------------------------------------------------------------
+
+function buildGraph(llm: LLMCall, variant: 'naive' | 'optimised') {
+  const nodes = makeNodes(llm, variant);
+  const urgencyNode = variant === 'naive' ? nodes.decideUrgencyNaive : nodes.decideUrgencyBatch;
+
+  return new StateGraph(MailState)
+    .addNode('classify',           nodes.classifyIntent)
+    .addNode('fetch_mails',        nodes.fetchMailsNode)
+    .addNode('decide_urgency',     urgencyNode)
+    .addNode('generate_responses', nodes.generateResponsesNode)
+    .addNode('archive',            nodes.archiveNode)
+    .addEdge('__start__',          'classify')
+    .addEdge('classify',           'fetch_mails')
+    .addEdge('fetch_mails',        'decide_urgency')
+    .addEdge('decide_urgency',     'generate_responses')
+    .addEdge('generate_responses', 'archive')
+    .addEdge('archive',            '__end__')
+    .compile();
+}
+
+// ---------------------------------------------------------------------------
+// Runner helper
+// ---------------------------------------------------------------------------
+
+const INPUT = {
+  messages: [{ role: 'user' as const, content: 'Fetch my 5 latest mails, flag the urgent ones, draft replies for urgent mails, and archive the rest.' }],
+  maxMails: 5,
+};
+
+async function run(label: string, llm: LLMCall, variant: 'naive' | 'optimised') {
+  console.log(`\n🚀 LangGraph (${variant}) benchmark...\n`);
+  llm.resetCount();
+  const t0 = Date.now();
+  const m0 = process.memoryUsage().heapUsed;
+
+  const graph  = buildGraph(llm, variant);
+  const result = await graph.invoke(INPUT);
+
+  return {
+    framework:      label,
+    totalTime:      Date.now() - t0,
+    llmCalls:       llm.callCount,
+    memoryUsed:     process.memoryUsage().heapUsed - m0,
+    mailsCount:     result.mails?.length        ?? 0,
+    urgentCount:    result.urgentMails?.length   ?? 0,
+    responsesCount: result.responses?.length     ?? 0,
+    archivedCount:  result.archivedCount         ?? 0,
+  };
+}
+
+export async function runLangGraphNaiveBenchmark(llm: LLMCall) {
+  return run('LangGraph (naive)', llm, 'naive');
+}
+
+export async function runLangGraphOptimisedBenchmark(llm: LLMCall) {
+  return run('LangGraph (optimised)', llm, 'optimised');
+}

package/benchmark/llm-client.ts

@@ -0,0 +1,76 @@
+/**
+ * @file llm-client.ts
+ * @description Thin OpenAI-compatible LLM client shared by all benchmark variants.
+ *
+ * Works with any OpenAI-compatible endpoint:
+ *   - Ollama local  : http://localhost:11434/v1  (no key required)
+ *   - Groq          : https://api.groq.com/openai/v1
+ *   - OpenRouter    : https://openrouter.ai/api/v1
+ */
+
+export interface LLMConfig {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  /** Request timeout in ms. Default: 60 000 */
+  timeout?: number;
+}
+
+export interface LLMCall {
+  /** Number of LLM calls made since creation (for benchmark accounting). */
+  callCount: number;
+  /** Send a prompt and return the text content of the first choice. */
+  call(prompt: string): Promise<string>;
+  /** Reset the call counter (used between benchmark variants). */
+  resetCount(): void;
+}
+
+/**
+ * Creates an LLMCall instance backed by an OpenAI-compatible chat endpoint.
+ * The `format: json` instruction is embedded in the system prompt so that
+ * both providers that support the `response_format` field and those that do
+ * not (e.g. some Ollama models) behave consistently.
+ */
+export function createLLMClient(config: LLMConfig): LLMCall {
+  let callCount = 0;
+
+  async function call(prompt: string): Promise<string> {
+    callCount++;
+    const res = await fetch(`${config.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: config.model,
+        messages: [
+          { role: 'system', content: 'You are a helpful assistant. Always respond with valid JSON.' },
+          { role: 'user',   content: prompt },
+        ],
+        temperature: 0,
+      }),
+      signal: AbortSignal.timeout(config.timeout ?? 60_000),
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`LLM API error ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const data = await res.json();
+    return data.choices?.[0]?.message?.content ?? '';
+  }
+
+  return {
+    get callCount() { return callCount; },
+    call,
+    resetCount() { callCount = 0; },
+  };
+}
+
+/** Safely parse LLM JSON output; returns `fallback` on failure. */
+export function safeParse<T>(raw: string, fallback: T): T {
+  // Strip markdown code fences if present
+  const cleaned = raw.replace(/^```(?:json)?\s*/i, '').replace(/\s*```\s*$/i, '').trim();
+  try { return JSON.parse(cleaned) as T; }
+  catch { return fallback; }
+}