I Built a Full-Stack AI Agent with Laravel, Vue, MCP, and RAG — Here’s How It Works

┌─────────────────────────────────────────────────────────────┐
│                       Vue 3 Frontend                        │
│   (Pinia Store, SSE EventSource Reader, Reactive UI Tree)    │
└──────────────┬──────────────────────────────▲───────────────┘
               │ 1. POST /api/agent/chat       │ 7. SSE Event Stream
               ▼                               │    (Tokens, Tool Status)
┌──────────────────────────────────────────────┴──────────────┐
│                    Laravel Orchestrator                     │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ State Machine (ChatSession, Message, Context Budget)  │  │
│  └───────────┬───────────────────────────────▲───────────┘  │
│              │ 2. Build Prompt & Tools       │              │
│              ▼                               │              │
│  ┌────────────────────────┐    ┌─────────────┴───────────┐  │
│  │     Anthropic API      │    │  Hybrid RAG Pipeline    │  │
│  │  (Claude 3.5/3.7)      │    │  (Postgres + pgvector)  │  │
│  └───────────┬────────────┘    └─────────────▲───────────┘  │
│              │ 3. Tool Call Requested        │ 4. Vector/BM25│
│              ▼                               │    Search    │
│  ┌───────────────────────────────────────────┴───────────┐  │
│  │                  MCP Client Manager                   │  │
│  └───────────┬───────────────────────────────────────────┘  │
└──────────────┼──────────────────────────────────────────────┘
               │ 5. JSON-RPC (stdio / SSE)
               ▼
┌─────────────────────────────────────────────────────────────┐
│                 Decoupled MCP Servers                       │
│  ┌───────────────────────┐       ┌───────────────────────┐  │
│  │  Postgres DB Inspector│       │ GitHub / Jira Worker  │  │
│  └───────────────────────┘       └───────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

namespace App\Enums;

enum AgentStatus: string
{
    case Pending = 'pending';
    case Thinking = 'thinking';
    case ExecutingTool = 'executing_tool';
    case AwaitingInput = 'awaiting_input';
    case Streaming = 'streaming';
    case Completed = 'completed';
    case Failed = 'failed';
}

namespace App\Services\Agent;

use App\Enums\AgentStatus;
use App\Models\AgentRun;
use App\Models\Conversation;
use App\Services\Mcp\McpClientManager;
use App\Services\Rag\RagRetriever;
use Generator;
use Illuminate\Support\Facades\Log;

class AgentOrchestrator
{
    private const MAX_ITERATIONS = 8;

    public function __construct(
        protected McpClientManager $mcpManager,
        protected RagRetriever $ragRetriever,
        protected AnthropicClient $llmClient
    ) {}

    /**
     * Executes the agent loop, yielding SSE-formatted events along the way.
     *
     * @return Generator<string, mixed>
     */
    public function run(Conversation $conversation, string $userPrompt): Generator
    {
        $run = AgentRun::create([
            'conversation_id' => $conversation->id,
            'status' => AgentStatus::Pending,
            'iteration_count' => 0,
        ]);

        // 1. Fetch relevant RAG context documents
        yield ['event' => 'status', 'data' => ['message' => 'Searching knowledge base...']];
        $retrievedContext = $this->ragRetriever->retrieve($userPrompt, limit: 5);

        // 2. Build initial message history
        $conversation->messages()->create([
            'role' => 'user',
            'content' => $userPrompt,
        ]);

        $availableTools = $this->mcpManager->getAllToolDefinitions();
        $systemPrompt = $this->buildSystemPrompt($retrievedContext);

        $iteration = 0;
        $run->update(['status' => AgentStatus::Thinking]);

        while ($iteration < self::MAX_ITERATIONS) {
            $iteration++;
            $run->increment('iteration_count');

            $messages = $conversation->getSanitizedMessageHistory();
            $responseStream = $this->llmClient->streamConversation(
                system: $systemPrompt,
                messages: $messages,
                tools: $availableTools
            );

            $currentToolCall = null;
            $accumulatedContent = '';

            foreach ($responseStream as $chunk) {
                if ($chunk['type'] === 'text_delta') {
                    $accumulatedContent .= $chunk['text'];
                    yield ['event' => 'token', 'data' => ['delta' => $chunk['text']]];
                } elseif ($chunk['type'] === 'tool_use_start') {
                    $run->update(['status' => AgentStatus::ExecutingTool]);
                    $currentToolCall = [
                        'id' => $chunk['id'],
                        'name' => $chunk['name'],
                        'input' => '',
                    ];
                    yield ['event' => 'tool_start', 'data' => ['name' => $chunk['name'], 'id' => $chunk['id']]];
                } elseif ($chunk['type'] === 'tool_use_delta') {
                    $currentToolCall['input'] .= $chunk['input_json_delta'];
                } elseif ($chunk['type'] === 'tool_use_stop') {
                    yield ['event' => 'tool_executing', 'data' => ['id' => $currentToolCall['id']]];

                    // Parse inputs and execute via MCP
                    $parsedArgs = json_decode($currentToolCall['input'], true) ?? [];

                    $toolResult = $this->executeToolWithCircuitBreaker(
                        $currentToolCall['name'],
                        $parsedArgs
                    );

                    // Persist model tool request and the tool execution result
                    $conversation->messages()->create([
                        'role' => 'assistant',
                        'content' => [
                            ['type' => 'tool_use', 'id' => $currentToolCall['id'], 'name' => $currentToolCall['name'], 'input' => $parsedArgs]
                        ]
                    ]);

                    $conversation->messages()->create([
                        'role' => 'user',
                        'content' => [
                            ['type' => 'tool_result', 'tool_use_id' => $currentToolCall['id'], 'content' => json_encode($toolResult)]
                        ]
                    ]);

                    yield ['event' => 'tool_complete', 'data' => [
                        'id' => $currentToolCall['id'],
                        'result' => $toolResult
                    ]];

                    // Loop back to give the tool result to the LLM
                    continue 2;
                }
            }

            // If we reached here without a tool call, the model produced its final response
            if (!empty($accumulatedContent)) {
                $conversation->messages()->create([
                    'role' => 'assistant',
                    'content' => $accumulatedContent,
                ]);
            }

            $run->update(['status' => AgentStatus::Completed]);
            yield ['event' => 'done', 'data' => ['run_id' => $run->id]];
            return;
        }

        $run->update(['status' => AgentStatus::Failed, 'error' => 'Max iterations exceeded']);
        yield ['event' => 'error', 'data' => ['message' => 'Agent execution reached cycle limit without resolving.']];
    }

    private function executeToolWithCircuitBreaker(string $toolName, array $arguments): array
    {
        try {
            return $this->mcpManager->executeTool($toolName, $arguments);
        } catch (\Throwable $e) {
            Log::error("Tool execution failed: {$toolName}", ['error' => $e->getMessage()]);
            return [
                'is_error' => true,
                'content' => "Error executing tool '{$toolName}': " . $e->getMessage(),
            ];
        }
    }

    private function buildSystemPrompt(array $contextDocs): string
    {
        $contextSection = collect($contextDocs)->map(function ($doc, $idx) {
            return "<document index=\"{$idx}\">\n<title>{$doc['title']}</title>\n<content>{$doc['content']}</content>\n</document>";
        })->implode("\n\n");

        return <<<PROMPT
You are an advanced enterprise intelligence agent with direct access to internal databases, APIs, and analytical tools.
Always prioritize using verified context documents before making assumptions.

CRITICAL INSTRUCTIONS:
1. Always ground your answers in the provided knowledge base context when possible.
2. If you need data you do not have, check your available tools and execute them.
3. If a tool returns an error, evaluate whether you can retry with altered parameters or explain the limitation to the user.
4. Output your reasoning concisely before making tool calls.

CONTEXT DOCUMENTS:
{$contextSection}
PROMPT;
    }
}

┌─────────────────────────────────────────────────────────────┐
│                   Laravel Host Process                      │
│                                                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │                 McpClientManager                    │   │
│   └──────────┬───────────────────────────────▲──────────┘   │
│              │ JSON-RPC 2.0 Request          │ JSON-RPC     │
│              │ (tools/call)                  │ Response     │
│              ▼                               │              │
│   ┌─────────────────────────────────────────────────────┐   │
│   │            ProcessTransport (proc_open)             │   │
│   └──────────┬───────────────────────────────▲──────────┘   │
└──────────────┼───────────────────────────────┼──────────────┘
               │ STDIN                         │ STDOUT
               ▼                               │
┌─────────────────────────────────────────────────────────────┐
│             External MCP Server (Node/Python)               │
│         e.g., @modelcontextprotocol/server-postgres         │
└─────────────────────────────────────────────────────────────┘

namespace App\Services\Mcp;

use RuntimeException;
use Symfony\Component\Process\Process;

class McpProcessClient
{
    /** @var resource|null */
    private $process = null;
    /** @var array<int, resource> */
    private array $pipes = [];
    private int $requestId = 0;

    public function __construct(
        protected string $command,
        protected array $environment = []
    ) {}

    public function start(): void
    {
        $descriptorSpec = [
            0 => ['pipe', 'r'], // STDIN
            1 => ['pipe', 'w'], // STDOUT
            2 => ['pipe', 'w'], // STDERR
        ];

        $this->process = proc_open(
            $this->command,
            $descriptorSpec,
            $this->pipes,
            base_path(),
            array_merge($_ENV, $this->environment)
        );

        if (!is_resource($this->process)) {
            throw new RuntimeException("Failed to spawn MCP Server process: {$this->command}");
        }

        // Initialize MCP connection handshake
        $this->sendNotification('notifications/initialized');
    }

    /**
     * Lists all tools advertised by this MCP server.
     */
    public function listTools(): array
    {
        $response = $this->sendRequest('tools/list', []);

        // Map the MCP tool format to Anthropic's expected tool format
        return array_map(function ($tool) {
            return [
                'name' => $tool['name'],
                'description' => $tool['description'] ?? '',
                'input_schema' => $tool['inputSchema'],
            ];
        }, $response['result']['tools'] ?? []);
    }

    /**
     * Executes a specific tool by name with arguments.
     */
    public function callTool(string $name, array $arguments): array
    {
        $response = $this->sendRequest('tools/call', [
            'name' => $name,
            'arguments' => $arguments,
        ]);

        if (isset($response['error'])) {
            throw new RuntimeException("MCP Error [{$response['error']['code']}]: {$response['error']['message']}");
        }

        return $response['result'] ?? [];
    }

    private function sendRequest(string $method, array $params): array
    {
        $this->requestId++;
        $payload = [
            'jsonrpc' => '2.0',
            'id' => $this->requestId,
            'method' => $method,
            'params' => (object) $params,
        ];

        $json = json_encode($payload) . "\n";
        fwrite($this->pipes[0], $json);
        fflush($this->pipes[0]);

        $rawResponse = fgets($this->pipes[1]);
        if ($rawResponse === false) {
            $err = stream_get_contents($this->pipes[2]);
            throw new RuntimeException("MCP Server closed pipe unexpectedly: {$err}");
        }

        return json_decode($rawResponse, true) ?? [];
    }

    private function sendNotification(string $method, array $params = []): void
    {
        $payload = [
            'jsonrpc' => '2.0',
            'method' => $method,
            'params' => (object) $params,
        ];

        fwrite($this->pipes[0], json_encode($payload) . "\n");
        fflush($this->pipes[0]);
    }

    public function __destruct()
    {
        if (is_resource($this->process)) {
            foreach ($this->pipes as $pipe) {
                if (is_resource($pipe)) {
                    fclose($pipe);
                }
            }
            proc_close($this->process);
        }
    }
}

namespace App\Services\Mcp;

class McpClientManager
{
    /** @var array<string, McpProcessClient> */
    protected array $clients = [];

    public function __construct()
    {
        $this->bootServers();
    }

    protected function bootServers(): void
    {
        $servers = config('mcp.servers', []);

        foreach ($servers as $name => $cfg) {
            $client = new McpProcessClient($cfg['command'], $cfg['env'] ?? []);
            $client->start();
            $this->clients[$name] = $client;
        }
    }

    public function getAllToolDefinitions(): array
    {
        $allTools = [];
        foreach ($this->clients as $serverName => $client) {
            foreach ($client->listTools() as $tool) {
                // Namespace tool to prevent collisions: e.g. postgres__query
                $namespacedName = "{$serverName}__{$tool['name']}";
                $tool['name'] = $namespacedName;
                $allTools[] = $tool;
            }
        }
        return $allTools;
    }

    public function executeTool(string $namespacedToolName, array $arguments): array
    {
        [$serverName, $toolName] = explode('__', $namespacedToolName, 2);

        if (!isset($this->clients[$serverName])) {
            throw new \InvalidArgumentException("MCP Server '{$serverName}' not registered.");
        }

        return $this->clients[$serverName]->callTool($toolName, $arguments);
    }
}

User Query: "Severity 1 SLA contract version 2024.2"
                     │
         ┌───────────┴───────────┐
         ▼                       ▼
  Dense Embedding         Text Query String
  (OpenAI / Cohere)              │
         │                       │
         ▼                       ▼
Vector Search (Cosine)    Full-Text (BM25/tsvector)
   pgvector <=> index       websearch_to_tsquery
         │                       │
     Top 20 Docs             Top 20 Docs
         └───────────┬───────────┘
                     ▼
          Reciprocal Rank Fusion (RRF)
            Score = Σ [1 / (k + Rank)]
                     │
                     ▼
         Top 5 Re-Ranked Documents

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        DB::statement('CREATE EXTENSION IF NOT EXISTS vector;');

        Schema::create('knowledge_documents', function (Blueprint $table) {
            $table->id();
            $table->foreignId('team_id')->constrained()->cascadeOnDelete();
            $table->string('title');
            $table->text('content');
            $table->jsonb('metadata')->nullable();

            // Vector column (1536 dimensions for text-embedding-3-small)
            // Using raw SQL because Laravel Blueprint doesn't natively wrap vector types
            $table->timestamps();
        });

        DB::statement('ALTER TABLE knowledge_documents ADD COLUMN embedding vector(1536);');

        // Full-Text Search tsvector column
        DB::statement("ALTER TABLE knowledge_documents ADD COLUMN search_vector tsvector GENERATED ALWAYS AS (to_tsvector('english', title || ' ' || content)) STORED;");

        // Indexes: HNSW for vector search, GIN for full-text
        DB::statement('CREATE INDEX knowledge_docs_embedding_hnsw ON knowledge_documents USING hnsw (embedding vector_cosine_ops);');
        DB::statement('CREATE INDEX knowledge_docs_search_vector_gin ON knowledge_documents USING GIN (search_vector);');
    }

    public function down(): void
    {
        Schema::dropIfExists('knowledge_documents');
    }
};

namespace App\Services\Rag;

use Illuminate\Support\Facades\DB;
use OpenAI\Client as OpenAiClient;

class RagRetriever
{
    private const RRF_K = 60;

    public function __construct(
        protected OpenAiClient $openai
    ) {}

    /**
     * Executes hybrid retrieval combining pgvector Cosine distance and Postgres tsvector GIN.
     */
    public function retrieve(string $query, int $limit = 5): array
    {
        // 1. Generate dense embedding
        $embeddingResponse = $this->openai->embeddings()->create([
            'model' => 'text-embedding-3-small',
            'input' => $query,
        ]);
        $vector = json_encode($embeddingResponse->embeddings[0]->embedding);

        // 2. Dense Semantic Retrieval (Top 25)
        $vectorResults = DB::select("
            SELECT id, title, content, 
                   ROW_NUMBER() OVER (ORDER BY embedding <=> ?::vector) as rank
            FROM knowledge_documents
            ORDER BY embedding <=> ?::vector
            LIMIT 25
        ", [$vector, $vector]);

        // 3. Sparse Keyword Retrieval via Full-Text Search (Top 25)
        $keywordResults = DB::select("
            SELECT id, title, content,
                   ROW_NUMBER() OVER (ORDER BY ts_rank_cd(search_vector, websearch_to_tsquery('english', ?)) DESC) as rank
            FROM knowledge_documents
            WHERE search_vector @@ websearch_to_tsquery('english', ?)
            ORDER BY ts_rank_cd(search_vector, websearch_to_tsquery('english', ?)) DESC
            LIMIT 25
        ", [$query, $query, $query]);

        // 4. Compute Reciprocal Rank Fusion
        $scores = [];
        $documents = [];

        foreach ($vectorResults as $doc) {
            $id = $doc->id;
            $documents[$id] = ['id' => $doc->id, 'title' => $doc->title, 'content' => $doc->content];
            $scores[$id] = ($scores[$id] ?? 0.0) + (1.0 / (self::RRF_K + $doc->rank));
        }

        foreach ($keywordResults as $doc) {
            $id = $doc->id;
            if (!isset($documents[$id])) {
                $documents[$id] = ['id' => $doc->id, 'title' => $doc->title, 'content' => $doc->content];
            }
            $scores[$id] = ($scores[$id] ?? 0.0) + (1.0 / (self::RRF_K + $doc->rank));
        }

        // Sort documents by RRF score descending
        arsort($scores);

        $finalResults = [];
        foreach (array_slice(array_keys($scores), 0, $limit) as $docId) {
            $finalResults[] = array_merge($documents[$docId], ['score' => $scores[$docId]]);
        }

        return $finalResults;
    }
}

Unbounded Conversation History (Degrades Accuracy & Blows Budget)
┌──────────────┬───────────────────────────────┬──────────────┬──────────────┐
│ System Prompt│ Turn 1 Context + Massive Dump │ Turn 2 Tool  │ Turn 3 Query │
│ (Crucial)    │ (Obsolete DB Result - 40k tok)│ Result       │ (Current)    │
└──────────────┴───────────────────────────────┴──────────────┴──────────────┘

Sanitized Sliding-Window Context (Production Pattern)
┌──────────────┬───────────────────────────────┬──────────────┬──────────────┐
│ System Prompt│ Trimmed Tool Outputs          │ Turn 2 Tool  │ Turn 3 Query │
│ + Cached RAG │ (Summarized/Truncated)        │ Result       │ (Current)    │
└──────────────┴───────────────────────────────┴──────────────┴──────────────┘

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Conversation extends Model
{
    public function messages(): HasMany
    {
        return $this->hasMany(Message::class)->oldest();
    }

    /**
     * Prepares message history for LLM submission while honoring a strict token budget.
     */
    public function getSanitizedMessageHistory(int $maxTurns = 10): array
    {
        $allMessages = $this->messages()->get();

        if ($allMessages->count() <= $maxTurns) {
            return $allMessages->map(fn($m) => $this->formatMessageForApi($m))->toArray();
        }

        $initialMessage = $allMessages->first();
        $recentMessages = $allMessages->slice(-($maxTurns - 1));

        $sanitized = [];
        $sanitized[] = $this->formatMessageForApi($initialMessage);

        // Add a structural divider so the model understands data was pruned
        $sanitized[] = [
            'role' => 'user',
            'content' => '[System Note: Older conversation turns have been pruned to preserve context budget.]'
        ];

        foreach ($recentMessages as $message) {
            $formatted = $this->formatMessageForApi($message);

            // If it's an older tool_result, truncate massive outputs
            if (is_array($formatted['content'])) {
                foreach ($formatted['content'] as &$block) {
                    if (($block['type'] ?? '') === 'tool_result' && strlen($block['content']) > 1500) {
                        $block['content'] = substr($block['content'], 0, 1500) . "\n...[Truncated Historic Output]";
                    }
                }
            }

            $sanitized[] = $formatted;
        }

        return $sanitized;
    }

    protected function formatMessageForApi(Message $message): array
    {
        return [
            'role' => $message->role,
            'content' => is_string($message->content) 
                ? $message->content 
                : $message->content, // Handled as array of blocks (Anthropic spec)
        ];
    }
}

namespace App\Http\Controllers;

use App\Models\Conversation;
use App\Services\Agent\AgentOrchestrator;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\StreamedResponse;

class AgentChatController extends Controller
{
    public function __invoke(
        Request $request, 
        Conversation $conversation, 
        AgentOrchestrator $orchestrator
    ): StreamedResponse {
        $validated = $request->validate([
            'prompt' => 'required|string|max:4000',
        ]);

        $response = new StreamedResponse(function () use ($conversation, $validated, $orchestrator) {
            // Disable output buffering completely
            while (ob_get_level() > 0) {
                ob_end_flush();
            }

            // Implicit flush tells PHP to output data immediately
            ob_implicit_flush(true);

            $generator = $orchestrator->run($conversation, $validated['prompt']);

            foreach ($generator as $payload) {
                $event = $payload['event'];
                $data = json_encode($payload['data']);

                echo "event: {$event}\n";
                echo "data: {$data}\n\n";

                flush();
            }
        });

        $response->headers->set('Content-Type', 'text/event-stream');
        $response->headers->set('Cache-Control', 'no-cache, no-transform');
        $response->headers->set('Connection', 'keep-alive');
        // Crucial header: instructs Nginx to immediately flush packets to client
        $response->headers->set('X-Accel-Buffering', 'no');

        return $response;
    }
}

location /api/agent/ {
    proxy_pass http://php_fpm_upstream;
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # Disable buffering for real-time SSE streams
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 600s;
    chunked_transfer_encoding on;
}

import { ref } from 'vue';

export interface ToolInvocation {
  id: string;
  name: string;
  status: 'pending' | 'running' | 'completed' | 'error';
  args?: Record<string, any>;
  result?: any;
}

export interface ChatMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  tools: ToolInvocation[];
}

export function useAgentStream() {
  const isStreaming = ref(false);
  const activeStatus = ref<string | null>(null);

  async function streamPrompt(
    conversationId: number, 
    prompt: string, 
    messagesList: Ref<ChatMessage[]>
  ) {
    isStreaming.value = true;
    activeStatus.value = 'Connecting...';

    // Optimistically push user prompt
    messagesList.value.push({
      id: crypto.randomUUID(),
      role: 'user',
      content: prompt,
      tools: [],
    });

    // Create placeholder for assistant response
    const assistantMessage: ChatMessage = {
      id: crypto.randomUUID(),
      role: 'assistant',
      content: '',
      tools: [],
    };
    messagesList.value.push(assistantMessage);

    try {
      const response = await fetch(`/api/agent/conversations/${conversationId}/chat`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'text/event-stream',
          'X-CSRF-TOKEN': (document.querySelector('meta[name="csrf-token"]') as HTMLMetaElement)?.content,
        },
        body: JSON.stringify({ prompt }),
      });

      if (!response.ok || !response.body) {
        throw new Error(`HTTP Error: ${response.status}`);
      }

      const reader = response.body.getReader();
      const decoder = new TextDecoder('utf-8');
      let buffer = '';

      while (true) {
        const { value, done } = await reader.read();
        if (done) break;

        buffer += decoder.decode(value, { stream: true });
        const lines = buffer.split('\n\n');
        buffer = lines.pop() ?? ''; // Keep partial chunk in buffer

        for (const line of lines) {
          if (!line.trim()) continue;

          const match = line.match(/^event: (.+)\ndata: (.+)$/s);
          if (!match) continue;

          const [, event, rawData] = match;
          const payload = JSON.parse(rawData);

          handleSseEvent(event, payload, assistantMessage);
        }
      }
    } catch (err: any) {
      assistantMessage.content += `\n\n**Error during execution:** ${err.message}`;
    } finally {
      isStreaming.value = false;
      activeStatus.value = null;
    }
  }

  function handleSseEvent(event: string, data: any, message: ChatMessage) {
    switch (event) {
      case 'status':
        activeStatus.value = data.message;
        break;

      case 'token':
        activeStatus.value = null;
        message.content += data.delta;
        break;

      case 'tool_start':
        message.tools.push({
          id: data.id,
          name: data.name,
          status: 'running',
        });
        break;

      case 'tool_complete':
        const tool = message.tools.find((t) => t.id === data.id);
        if (tool) {
          tool.status = 'completed';
          tool.result = data.result;
        }
        break;

      case 'error':
        message.content += `\n> ⚠️ **Error:** ${data.message}`;
        break;
    }
  }

  return {
    isStreaming,
    activeStatus,
    streamPrompt,
  };
}

<script setup lang="ts">
import { ref } from 'vue';
import { useAgentStream, ChatMessage } from '@/composables/useAgentStream';
import MarkdownRenderer from '@/Components/MarkdownRenderer.vue';

const props = defineProps<{ conversationId: number }>();

const messages = ref<ChatMessage[]>([]);
const inputPrompt = ref('');
const { isStreaming, activeStatus, streamPrompt } = useAgentStream();

function submit() {
  if (!inputPrompt.value.trim() || isStreaming.value) return;
  const p = inputPrompt.value;
  inputPrompt.value = '';
  streamPrompt(props.conversationId, p, messages);
}
</script>

<template>
  <div class="flex flex-col h-[85vh] max-w-4xl mx-auto bg-gray-900 text-gray-100 rounded-xl shadow-2xl border border-gray-800">
    <!-- Messages Scrollable Body -->
    <div class="flex-1 overflow-y-auto p-6 space-y-6">
      <div 
        v-for="msg in messages" 
        :key="msg.id" 
        :class="msg.role === 'user' ? 'justify-end' : 'justify-start'" 
        class="flex"
      >
        <div 
          :class="msg.role === 'user' ? 'bg-blue-600 text-white' : 'bg-gray-800 border border-gray-700'"
          class="rounded-lg p-5 max-w-[85%] space-y-3"
        >
          <!-- Tool Invocations Telemetry Cards -->
          <div v-if="msg.tools.length > 0" class="space-y-2">
            <div 
              v-for="tool in msg.tools" 
              :key="tool.id" 
              class="text-xs bg-gray-950/60 rounded border border-gray-700 p-2 font-mono"
            >
              <div class="flex items-center justify-between">
                <span class="flex items-center gap-1.5 text-blue-400">
                  <span class="h-2 w-2 rounded-full animate-pulse" :class="tool.status === 'completed' ? 'bg-green-500' : 'bg-amber-400'" />
                  Tool: {{ tool.name }}
                </span>
                <span class="text-gray-400 uppercase">{{ tool.status }}</span>
              </div>
              <div v-if="tool.result" class="mt-2 text-gray-300 max-h-32 overflow-y-auto border-t border-gray-800 pt-1">
                <pre>{{ JSON.stringify(tool.result, null, 2) }}</pre>
              </div>
            </div>
          </div>

          <!-- Message Text Markdown Body -->
          <MarkdownRenderer :source="msg.content" class="prose prose-invert max-w-none text-sm" />
        </div>
      </div>

      <!-- Live Spinner / Processing State Indicator -->
      <div v-if="activeStatus" class="flex items-center space-x-2 text-sm text-gray-400 italic">
        <svg class="animate-spin h-4 w-4 text-blue-500" viewBox="0 0 24 24" fill="none">
          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8v8H4z"></path>
        </svg>
        <span>{{ activeStatus }}</span>
      </div>
    </div>

    <!-- Input Form Area -->
    <div class="border-t border-gray-800 p-4 bg-gray-950/50">
      <form @submit.prevent="submit" class="flex gap-2">
        <input
          v-model="inputPrompt"
          :disabled="isStreaming"
          placeholder="Ask your agent to analyze data, search documents, or invoke tools..."
          class="flex-1 bg-gray-800 border border-gray-700 rounded-lg px-4 py-2.5 text-sm text-gray-100 focus:outline-none focus:border-blue-500"
        />
        <button
          type="submit"
          :disabled="isStreaming || !inputPrompt.trim()"
          class="bg-blue-600 hover:bg-blue-500 disabled:opacity-50 text-white font-medium px-5 py-2.5 rounded-lg text-sm transition"
        >
          Send
        </button>
      </form>
    </div>
  </div>
</template>

Incoming Untrusted Context (Vector Search / External Webhook)
                            │
                            ▼
         ┌──────────────────────────────────────┐
         │ XML Tag Delimiting & Sanitization    │
         │ Strip `<script>`, enforce bounds    │
         └──────────────────┬───────────────────┘
                            │
                            ▼
         ┌──────────────────────────────────────┐
         │ LLM Core Reasoning (Decides to Call) │
         └──────────────────┬───────────────────┘
                            │
                     Tool Call Payload
                            │
                            ▼
    ┌────────────────────────────────────────────────┐
    │  Deterministic Application-Layer Enforcement   │
    │  1. Check Laravel Gate / RBAC Policy           │
    │  2. Validate Arguments Schema (Laravel Rules)  │
    │  3. Read-Only Transaction Context              │
    └───────────────────────┬────────────────────────┘
                            │
                     Passes Inspection?
                   ┌────────┴────────┐
                   │                 │
                  Yes                No
                   ▼                 ▼
          Execute via MCP      Throw SecurityException
                               & Return Error Block to LLM

namespace App\Services\Agent;

use App\Models\User;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\ValidationException;
use RuntimeException;

class SecureToolDispatcher
{
    /**
     * White-listed capabilities mapped to authorization abilities.
     */
    private const TOOL_PERMISSIONS = [
        'postgres__execute_query' => 'run-analytical-queries',
        'jira__create_ticket'     => 'create-support-tickets',
        'fs__read_file'           => 'read-internal-docs',
    ];

    /**
     * Enforces deterministic security policies on tool invocation.
     */
    public function authorizeAndValidate(User $user, string $toolName, array $arguments): void
    {
        // 1. Role-Based Access Control on Tools
        if (isset(self::TOOL_PERMISSIONS[$toolName])) {
            $requiredAbility = self::TOOL_PERMISSIONS[$toolName];

            if (!Gate::forUser($user)->allows($requiredAbility)) {
                throw new RuntimeException("Security Exception: User is not authorized to execute [{$toolName}].");
            }
        }

        // 2. Strict Input Validation Rules per Tool
        $this->validateArguments($toolName, $arguments);
    }

    private function validateArguments(string $toolName, array $arguments): void
    {
        $rules = match ($toolName) {
            'postgres__execute_query' => [
                'sql' => ['required', 'string', function ($attribute, $value, $fail) {
                    // Block destructive queries deterministically at the regex level
                    if (preg_match('/\b(DROP|TRUNCATE|DELETE|UPDATE|ALTER|INSERT)\b/i', $value)) {
                        $fail("Destructive SQL commands are blocked on this agent connection.");
                    }
                }],
            ],
            'jira__create_ticket' => [
                'project_key' => 'required|string|size:3',
                'summary'     => 'required|string|max:255',
                'description' => 'required|string',
            ],
            default => [],
        };

        if (empty($rules)) {
            return;
        }

        $validator = Validator::make($arguments, $rules);

        if ($validator->fails()) {
            throw new ValidationException($validator);
        }
    }
}