matimo-examples 0.1.0-alpha.11

package/agents/langchain-agent.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Matimo + LangChain Agent - Proper ReAct Agent Pattern
+ *
+ * This demonstrates a complete agent loop:
+ * 1. LLM decides which tool to use based on goal
+ * 2. Tool is executed via Matimo
+ * 3. Result is fed back to LLM
+ * 4. Process repeats until agent reaches conclusion
+ *
+ * Key advantages:
+ * - Shows real agent reasoning loop
+ * - Single source of truth (Matimo YAML definitions)
+ * - How to integrate Matimo with any LangChain setup
+ * - Demonstrates tool selection and execution
+ *
+ * Run: npm run agent:langchain
+ */
+
+import 'dotenv/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { ChatOpenAI } from '@langchain/openai';
+import { BaseMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import { MatimoInstance, convertToolsToLangChain, ToolDefinition } from 'matimo';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Run LangChain ReAct Agent with Matimo Tools
+ */
+async function runLangChainAgent() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║   Matimo + LangChain Agent (ReAct Pattern)              ║');
+  console.info('║   Demonstrates real agent reasoning loop                ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  try {
+    // Initialize Matimo
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    const matimoTools = matimo.listTools();
+    console.info(`📦 Loaded ${matimoTools.length} tools:\n`);
+    matimoTools.forEach((t) => {
+      console.info(`  • ${t.name}`);
+      console.info(`    ${t.description}\n`);
+    });
+
+    // ✅ Convert Matimo tools to LangChain tools
+    console.info('🔧 Converting Matimo tools to LangChain format...\n');
+    const langchainTools = await convertToolsToLangChain(matimoTools as ToolDefinition[], matimo);
+
+    console.info(`✅ Successfully converted ${langchainTools.length} tools!\n`);
+
+    // 🤖 Create GPT-4o-mini LLM with tool binding
+    console.info('🧠 Creating GPT-4o-mini LLM with tool binding...\n');
+    const llm = new ChatOpenAI({
+      model: 'gpt-4o-mini',
+      temperature: 0,
+    });
+
+    const llmWithTools = llm.bindTools(langchainTools as any);
+
+    // 🎯 Agent Loop - ReAct Pattern
+    console.info('🧪 Starting Agent Loop (ReAct Pattern)\n');
+    console.info('═'.repeat(60));
+
+    const userQuery = 'What is 42 plus 58?';
+    console.info(`\n❓ User Query: "${userQuery}"\n`);
+
+    const messages: BaseMessage[] = [new HumanMessage(userQuery)];
+
+    let iterationCount = 0;
+    const maxIterations = 10;
+    let continueLoop = true;
+
+    while (continueLoop && iterationCount < maxIterations) {
+      iterationCount++;
+      console.info(`\n[Iteration ${iterationCount}]`);
+      console.info('─'.repeat(60));
+
+      // Step 1: Call LLM with tools
+      console.info('🤔 LLM Thinking...');
+      const response = await llmWithTools.invoke(messages);
+      console.info(`LLM Response Content: ${response.content || '(no text content)'}`);
+
+      // Step 2: Check if LLM wants to use tools
+      if (response.tool_calls && response.tool_calls.length > 0) {
+        // Add assistant message to conversation
+        messages.push(response);
+
+        // Step 3: Execute each tool call
+        for (const toolCall of response.tool_calls) {
+          console.info(`\n🔧 Executing Tool: ${toolCall.name}`);
+          console.info(`   Input: ${JSON.stringify(toolCall.args)}`);
+
+          try {
+            // Execute via Matimo
+            const result = await matimo.execute(toolCall.name, toolCall.args);
+            console.info(`   ✅ Result: ${JSON.stringify(result)}`);
+
+            // Add tool result to conversation
+            messages.push(
+              new ToolMessage({
+                tool_call_id: toolCall.id || '',
+                content: JSON.stringify(result),
+                name: toolCall.name,
+              })
+            );
+          } catch (toolError) {
+            const msg = toolError instanceof Error ? toolError.message : String(toolError);
+            console.info(`   ❌ Error: ${msg}`);
+
+            // Add error to conversation
+            messages.push(
+              new ToolMessage({
+                tool_call_id: toolCall.id || '',
+                content: `Error: ${msg}`,
+                name: toolCall.name,
+              })
+            );
+          }
+        }
+      } else {
+        // Step 4: No more tools - agent reached conclusion
+        console.info('\n✅ Agent Reached Conclusion');
+        console.info(`\n📝 Final Response:\n${response.content || '(no response)'}`);
+        continueLoop = false;
+      }
+    }
+
+    if (iterationCount >= maxIterations) {
+      console.info('\n⚠️  Max iterations reached');
+    }
+
+    console.info('\n' + '═'.repeat(60));
+    console.info(`\n✨ Agent Loop Complete (${iterationCount} iterations)\n`);
+  } catch (error) {
+    console.error('❌ Agent failed:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run the agent
+runLangChainAgent().catch(console.error);

package/edit/edit-decorator.ts

@@ -0,0 +1,178 @@
+import {
+  MatimoInstance,
+  setGlobalMatimoInstance,
+  tool,
+  getGlobalApprovalHandler,
+  type ApprovalRequest,
+} from '@matimo/core';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import * as readline from 'readline';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Create an interactive approval callback
+ */
+function createApprovalCallback() {
+  return async (request: ApprovalRequest): Promise<boolean> => {
+    const isInteractive = process.stdin.isTTY;
+
+    console.info('\n' + '='.repeat(70));
+    console.info('🔒 APPROVAL REQUIRED FOR FILE OPERATION');
+    console.info('='.repeat(70));
+    console.info(`\n📋 Tool: ${request.toolName}`);
+    console.info(`📝 Description: ${request.description || '(no description provided)'}`);
+    console.info(`\n📄 File Operation:`);
+    console.info(`   Path: ${request.params.filePath}`);
+    console.info(`   Operation: ${request.params.operation}`);
+    if (request.params.content) {
+      console.info(`   Content: ${String(request.params.content).substring(0, 50)}...`);
+    }
+
+    if (!isInteractive) {
+      console.info('\n❌ REJECTED - Non-interactive environment (no terminal)');
+      console.info('\n💡 To enable auto-approval in CI/scripts:');
+      console.info('   export MATIMO_AUTO_APPROVE=true');
+      console.info('\n💡 Or approve specific patterns:');
+      console.info('   export MATIMO_APPROVED_PATTERNS="edit"');
+      console.info('\n' + '='.repeat(70) + '\n');
+      return false;
+    }
+
+    // Interactive mode: prompt user
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+      console.info('\n❓ User Action Required');
+      const question = '   Type "yes" to approve or "no" to reject: ';
+
+      rl.question(question, (answer) => {
+        const approved = answer.toLowerCase() === 'yes' || answer.toLowerCase() === 'y';
+
+        if (approved) {
+          console.info('   ✅ Operation APPROVED by user');
+        } else {
+          console.info('   ❌ Operation REJECTED by user');
+        }
+        console.info('='.repeat(70) + '\n');
+
+        rl.close();
+        resolve(approved);
+      });
+    });
+  };
+}
+
+/**
+ * Example: Edit tool using @tool decorator pattern
+ * Demonstrates class-based file editing with automatic decoration
+ */
+class FileEditor {
+  @tool('edit')
+  async replaceContent(
+    filePath: string,
+    operation: string,
+    content: string,
+    startLine: number,
+    endLine: number
+  ): Promise<unknown> {
+    // Decorator automatically intercepts and executes via Matimo
+    return undefined;
+  }
+
+  @tool('edit')
+  async insertContent(
+    filePath: string,
+    operation: string,
+    content: string,
+    startLine: number,
+    endLine: number
+  ): Promise<unknown> {
+    // Decorator automatically intercepts and executes via Matimo
+    return undefined;
+  }
+}
+
+async function decoratorExample() {
+  // Set up decorator support with autoDiscover
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+  setGlobalMatimoInstance(matimo);
+
+  // Configure centralized approval handler
+  const approvalHandler = getGlobalApprovalHandler();
+  approvalHandler.setApprovalCallback(createApprovalCallback());
+
+  console.info('\n' + '='.repeat(70));
+  console.info('🚀 Edit Tool - Decorator Pattern Example');
+  console.info('='.repeat(70));
+
+  // Show current approval mode
+  const autoApproveEnabled = process.env.MATIMO_AUTO_APPROVE === 'true';
+  const approvedPatterns = process.env.MATIMO_APPROVED_PATTERNS;
+
+  console.info('\n🔐 APPROVAL CONFIGURATION:');
+  if (autoApproveEnabled) {
+    console.info('   ✅ MATIMO_AUTO_APPROVE=true');
+    console.info('   → All destructive operations will be AUTO-APPROVED');
+  } else if (approvedPatterns) {
+    console.info(`   ✅ MATIMO_APPROVED_PATTERNS="${approvedPatterns}"`);
+    console.info('   → Matching operations will be auto-approved');
+  } else {
+    console.info('   ⚠️  INTERACTIVE MODE ENABLED');
+    console.info('   → You will be prompted to approve file operations');
+  }
+
+  const editor = new FileEditor();
+
+  // Create a temp file for demonstration
+  const tempFile = path.join(__dirname, 'temp-demo-decorator.txt');
+  fs.writeFileSync(tempFile, 'Original line\nAnother line\nThird line\n');
+
+  try {
+    // Example 1: Replace through decorated method
+    console.info('\n1️⃣  REPLACING CONTENT');
+    console.info('-'.repeat(70));
+    console.info('Replacing line 1 with: "Updated line"');
+    console.info('(This is a write operation - may require approval)\n');
+    const result1 = await editor.replaceContent(tempFile, 'replace', 'Updated line', 1, 1);
+    if (result1) {
+      console.info('✅ Edit Result:', (result1 as any).success);
+      console.info('📊 Lines Affected:', (result1 as any).linesAffected);
+      console.info('📝 File content:');
+      console.info(fs.readFileSync(tempFile, 'utf-8'));
+    }
+    console.info('---\n');
+
+    // Example 2: Insert through decorated method
+    console.info('2️⃣  INSERTING CONTENT');
+    console.info('-'.repeat(70));
+    console.info('Inserting "Inserted line" at line 1');
+    console.info('(This is a write operation - may require approval)\n');
+    const result2 = await editor.insertContent(tempFile, 'insert', 'Inserted line', 1, 0);
+    if (result2) {
+      console.info('✅ Insert Result:', (result2 as any).success);
+      console.info('📊 Lines Affected:', (result2 as any).linesAffected);
+      console.info('📝 File content:');
+      console.info(fs.readFileSync(tempFile, 'utf-8'));
+    }
+    console.info('---\n');
+
+    console.info('✅ Decorator example completed successfully');
+  } catch (error: any) {
+    console.error('❌ Error:', error.message);
+  } finally {
+    // Clean up temp file
+    if (fs.existsSync(tempFile)) {
+      fs.unlinkSync(tempFile);
+      console.info('\n🧹 Cleaned up temporary file');
+    }
+    console.info('');
+  }
+}
+
+decoratorExample();

package/edit/edit-factory.ts

@@ -0,0 +1,138 @@
+import { MatimoInstance, getGlobalApprovalHandler, type ApprovalRequest } from '@matimo/core';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import * as readline from 'readline';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Create an interactive approval callback for file operations
+ */
+function createApprovalCallback() {
+  return async (request: ApprovalRequest): Promise<boolean> => {
+    const isInteractive = process.stdin.isTTY;
+
+    console.info('\n' + '='.repeat(70));
+    console.info('🔒 APPROVAL REQUIRED FOR FILE OPERATION');
+    console.info('='.repeat(70));
+    console.info(`\n📋 Tool: ${request.toolName}`);
+    console.info(`📝 Description: ${request.description || '(no description provided)'}`);
+    console.info(`\n📄 File Operation:`);
+    console.info(`   Path: ${request.params.filePath}`);
+    if (request.params.startLine) {
+      console.info(`   Start Line: ${request.params.startLine}`);
+    }
+    if (request.params.endLine) {
+      console.info(`   End Line: ${request.params.endLine}`);
+    }
+
+    if (!isInteractive) {
+      console.info('\n❌ REJECTED - Non-interactive environment (no terminal)');
+      console.info('\n💡 To enable auto-approval in CI/scripts:');
+      console.info('   export MATIMO_AUTO_APPROVE=true');
+      console.info('\n💡 Or approve specific patterns:');
+      console.info('   export MATIMO_APPROVED_PATTERNS="edit"');
+      console.info('\n' + '='.repeat(70) + '\n');
+      return false;
+    }
+
+    // Interactive mode: prompt user
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+      console.info('\n❓ User Action Required');
+      const question = '   Type "yes" to approve or "no" to reject: ';
+
+      rl.question(question, (answer) => {
+        const approved = answer.toLowerCase() === 'yes' || answer.toLowerCase() === 'y';
+
+        if (approved) {
+          console.info('   ✅ Operation APPROVED by user');
+        } else {
+          console.info('   ❌ Operation REJECTED by user');
+        }
+        console.info('='.repeat(70) + '\n');
+
+        rl.close();
+        resolve(approved);
+      });
+    });
+  };
+}
+
+/**
+ * Example: Edit tool using factory pattern
+ * Demonstrates editing and modifying file contents with interactive approval
+ */
+async function editExample() {
+  // Initialize Matimo with autoDiscover to find all tools (core + providers)
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  // Configure centralized approval handler
+  const approvalHandler = getGlobalApprovalHandler();
+  approvalHandler.setApprovalCallback(createApprovalCallback());
+
+  console.info('=== Edit Tool - Factory Pattern (Interactive Approval) ===\n');
+
+  // Create a temp file for demonstration
+  const tempFile = path.join(__dirname, 'temp-demo.txt');
+  fs.writeFileSync(tempFile, 'Line 1\nLine 2\nLine 3\n');
+
+  try {
+    // Example 1: Replace text in file (replace line 2)
+    console.info('1. Replacing content in file\n');
+    console.info('Original content:');
+    console.info(fs.readFileSync(tempFile, 'utf-8'));
+    console.info('---\n');
+
+    const result = await matimo.execute('edit', {
+      filePath: tempFile,
+      operation: 'replace',
+      content: 'Line 2 (Modified)',
+      startLine: 2,
+      endLine: 2,
+    });
+
+    if ((result as any).success) {
+      console.info('Edit Result:', (result as any).success);
+      console.info('Lines Affected:', (result as any).linesAffected);
+      console.info('\nModified content:');
+      console.info(fs.readFileSync(tempFile, 'utf-8'));
+    } else {
+      console.info('Edit denied:', (result as any).error);
+    }
+    console.info('---\n');
+
+    // Example 2: Insert new content
+    console.info('2. Inserting new line\n');
+    const insertResult = await matimo.execute('edit', {
+      filePath: tempFile,
+      operation: 'insert',
+      content: 'New inserted line',
+      startLine: 2,
+    });
+
+    if ((insertResult as any).success) {
+      console.info('Insert Result:', (insertResult as any).success);
+      console.info('Lines Affected:', (insertResult as any).linesAffected);
+      console.info('\nFinal content:');
+      console.info(fs.readFileSync(tempFile, 'utf-8'));
+    } else {
+      console.info('Insert denied:', (insertResult as any).error);
+    }
+    console.info('---\n');
+  } catch (error: any) {
+    console.error('Error editing file:', error.message);
+  } finally {
+    // Clean up temp file
+    if (fs.existsSync(tempFile)) {
+      fs.unlinkSync(tempFile);
+    }
+  }
+}
+
+editExample();