Recursive AI Tool Loop

┌──────────────────────────────────────────────────────────────────┐
│                        ORCHESTRATOR                              │
│                                                                  │
│  1. Pre-Enrichment ─────────────────────────────────────────┐   │
│     │  Lightweight AI call picks which tools to run         │   │
│     │  Selected tools execute in parallel                   │   │
│     │  Results injected into Pass 1 system prompt           │   │
│     ▼                                                       │   │
│  2. Pass 1: Main Analysis ──────────────────────────────────┤   │
│     │  Streaming LLM call with full prompt + enriched data  │   │
│     │  Response parsed into section map (living document)   │   │
│     ▼                                                       │   │
│  3. Decision Gate ──────────────────────────────────────────┤   │
│     │  Extract confidence + ai_actions from response        │   │
│     │  Check exit conditions (confident? budget? max pass?) │   │
│     │  Filter to new, non-duplicate actions                 │   │
│     ▼                                                       │   │
│  4. Tool Execution ─────────────────────────────────────────┤   │
│     │  Run required + recommended tools in parallel         │   │
│     │  Each tool returns { summary, markdown, data }        │   │
│     │  Markdown accumulated into enriched context           │   │
│     ▼                                                       │   │
│  5. Refinement Pass (2, 3, ... up to 5) ───────────────────┤   │
│     │  System prompt = base rules + ALL enriched data       │   │
│     │  User message = current document + tool summaries     │   │
│     │  AI outputs ONLY sections that need changes           │   │
│     │  Sections merged into existing document               │   │
│     → Back to Decision Gate (step 3)                        │   │
│     ▼                                                       │   │
│  6. Complete ───────────────────────────────────────────────┘   │
│     Auto-save analysis to backend                               │
│     Restore model if escalated during the loop                  │
└──────────────────────────────────────────────────────────────────┘

Work Item (ticket, order, case, etc.)
    │
    ▼
Pre-Enrichment AI ──selects──▶ Tool Registry ──dispatches──▶ Individual Tools
                                                                   │
                                               graphqlFetch() / REST / AI sub-call
                                                                   │
                                                           ToolResult {
                                                             summary,   ← for UI
                                                             markdown,  ← for prompt injection
                                                             data       ← for structured access
                                                           }
                                                                   │
                                       Injected into LLM system prompt as context

on_analysis_complete(response, usage):
    update living document (build or merge sections)
    record pass in history

    if pass >= MAX_PASSES → exit("max-passes")
    if total_cost >= budget → exit("budget-exceeded")

    actions = extract_ai_actions(response)
    new_actions = actions.filter(not already completed)

    if new_actions is empty:
        if confidence == "high" → exit("confident")
        else → exit("no-new-actions")

    if pass >= 3 and confidence == last_confidence → exit("stale-confidence")

    run_tools(new_actions)
    → on tools complete → build refinement prompt → start next pass

interface ToolResult {
  success: boolean;
  toolName: string;
  data: unknown;       // raw structured data (for UI or further processing)
  summary: string;     // short text for inline UI display
  markdown: string;    // full formatted output for prompt injection ← CRITICAL
  error?: string;
}

interface ToolContext {
  companyId: string;   // scoping — which customer/account
  deviceId?: string;   // scoping — which asset
  ticketId?: string;   // scoping — which work item
  contactEmail?: string;
  companyName: string;
  modelId?: string;    // optional — enables AI sub-calls inside tools
  ticketTitle?: string;
}

type ToolFunction = (
  params: ToolParams,
  context: ToolContext,
  token: string
) => Promise<ToolResult>;

import type { ToolFunction, ToolResult } from './types';

export const execute: ToolFunction = async (params, context, token) => {
  const fail = (msg: string): ToolResult => ({
    success: false,
    toolName: 'fetch_your_thing',
    data: null,
    summary: msg,
    markdown: `> **Your Thing:** ${msg}`,
    error: msg,
  });

  try {
    const rawData = await yourApiCall(context.companyId, params.target, token);

    if (!rawData || rawData.length === 0) {
      return fail('No data found');
    }

    const markdown = [
      `## Your Thing — ${context.companyName}`,
      `| Name | Status | Last Updated |`,
      `|------|--------|------------- |`,
      ...rawData.map(item => `| ${item.name} | ${item.status} | ${item.date} |`),
    ].join('\n');

    return {
      success: true,
      toolName: 'fetch_your_thing',
      data: rawData,
      summary: `Found ${rawData.length} items`,
      markdown,
    };
  } catch (err) {
    return fail(err instanceof Error ? err.message : 'Unknown error');
  }
};

import { chatComplete } from '@/lib/ai-call';
import type { ToolFunction } from './types';

const AI_FILTER_THRESHOLD = 5;
const FILTER_PROMPT = `You are filtering results for relevance to a work item.
Given the context and a list of results, select the 1-3 most relevant.
Respond with ONLY a JSON array: [{"index": 0, "reason": "why"}]`;

export const execute: ToolFunction = async (params, context, token) => {
  const rawResults = await fetchFromApi(params, context, token);

  // AI filtering when available and data is large enough
  if (context.modelId && rawResults.length >= AI_FILTER_THRESHOLD) {
    try {
      const aiResult = await chatComplete(context.modelId, [
        { role: 'system', content: FILTER_PROMPT },
        { role: 'user', content: formatForAI(rawResults, context) },
      ], { maxTokens: 512, timeoutMs: 10_000 });

      const selections = parseAiResponse(aiResult.content);
      if (selections.length > 0) {
        return buildFocusedResult(selections, rawResults);
      }
    } catch {
      // Fall through to code-based filtering — ALWAYS have a fallback
    }
  }

  return codeBasedResult(rawResults, params.target);
};