@theihtisham/ai-agent-starter-kit 1.0.0

package/src/lib/agents/orchestration/sequential.ts

@@ -0,0 +1,127 @@
+/**
+ * Sequential Orchestrator — Runs agents in a pipeline.
+ *
+ * Each agent receives the output of the previous agent as its input.
+ * Useful for multi-step processing: research -> analysis -> writing -> review.
+ *
+ * Example: Research Agent -> Summarizer Agent -> Polish Agent
+ */
+
+import type {
+  AgentConfig,
+  AgentMessage,
+  OrchestrationResult,
+  OrchestratorOptions,
+} from './types';
+
+export class SequentialOrchestrator {
+  private agents: AgentConfig[];
+  private options: OrchestratorOptions;
+
+  constructor(agents: AgentConfig[], options: OrchestratorOptions = {}) {
+    if (agents.length === 0) {
+      throw new Error('SequentialOrchestrator requires at least one agent');
+    }
+    this.agents = agents;
+    this.options = {
+      timeoutMs: 60_000,
+      maxRetries: 2,
+      ...options,
+    };
+  }
+
+  /**
+   * Run the sequential pipeline.
+   * The initial input is passed to the first agent, then each subsequent
+   * agent receives the output of the previous one.
+   */
+  async run(input: string): Promise<OrchestrationResult> {
+    const startTime = Date.now();
+    const trace: AgentMessage[] = [];
+    let currentContent = input;
+
+    const timeoutMs = this.options.timeoutMs ?? 60_000;
+
+    try {
+      for (let i = 0; i < this.agents.length; i++) {
+        const agent = this.agents[i]!;
+
+        // Check timeout
+        if (Date.now() - startTime > timeoutMs) {
+          return {
+            content: currentContent,
+            agentIds: this.agents.slice(0, i).map((a) => a.id),
+            trace,
+            durationMs: Date.now() - startTime,
+            success: false,
+            error: `Timeout after ${timeoutMs}ms during agent: ${agent.name}`,
+          };
+        }
+
+        // Build the input message
+        const inputMessage: AgentMessage = {
+          content: currentContent,
+          fromAgent: i === 0 ? 'user' : this.agents[i - 1]!.id,
+          toAgent: agent.id,
+          timestamp: Date.now(),
+        };
+
+        // Execute with retries
+        let result: AgentMessage | undefined;
+        let lastError: Error | undefined;
+        const maxRetries = this.options.maxRetries ?? 2;
+
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+          try {
+            result = await agent.execute(inputMessage, agent);
+            break;
+          } catch (err) {
+            lastError = err as Error;
+            if (attempt < maxRetries) {
+              // Brief backoff before retry
+              await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+            }
+          }
+        }
+
+        if (!result) {
+          return {
+            content: currentContent,
+            agentIds: this.agents.slice(0, i).map((a) => a.id),
+            trace,
+            durationMs: Date.now() - startTime,
+            success: false,
+            error: `Agent "${agent.name}" failed after ${maxRetries + 1} attempts: ${lastError?.message}`,
+          };
+        }
+
+        // Record the interaction
+        trace.push(inputMessage);
+        trace.push(result);
+
+        // Notify callback
+        this.options.onAgentMessage?.(result);
+
+        // Pass output to next agent
+        currentContent = result.content;
+      }
+
+      return {
+        content: currentContent,
+        agentIds: this.agents.map((a) => a.id),
+        trace,
+        durationMs: Date.now() - startTime,
+        success: true,
+      };
+    } catch (err) {
+      return {
+        content: currentContent,
+        agentIds: [],
+        trace,
+        durationMs: Date.now() - startTime,
+        success: false,
+        error: (err as Error).message,
+      };
+    }
+  }
+}

package/src/lib/agents/orchestration/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Multi-Agent Orchestration Types
+ *
+ * Defines the types for different orchestration patterns:
+ * sequential, parallel, router, and debate.
+ */
+
+/** Configuration for a single agent in the orchestration */
+export interface AgentConfig {
+  id: string;
+  name: string;
+  description: string;
+  systemPrompt: string;
+  model?: string;
+  /** Called to execute the agent — can be a local function or API call */
+  execute: (input: AgentMessage, config: AgentConfig) => Promise<AgentMessage>;
+}
+
+/** A message passed between agents */
+export interface AgentMessage {
+  content: string;
+  fromAgent: string;
+  toAgent?: string;
+  metadata?: Record<string, unknown>;
+  timestamp?: number;
+}
+
+/** Result of an orchestration run */
+export interface OrchestrationResult {
+  content: string;
+  /** Which agents participated */
+  agentIds: string[];
+  /** Full trace of agent interactions */
+  trace: AgentMessage[];
+  /** Total execution time in ms */
+  durationMs: number;
+  /** Success status */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+}
+
+/** Available orchestration patterns */
+export type OrchestrationPattern = 'sequential' | 'parallel' | 'router' | 'debate';
+
+/** A handoff between two agents */
+export interface Handoff {
+  fromAgent: string;
+  toAgent: string;
+  content: string;
+  reason?: string;
+}
+
+/** Options for configuring an orchestrator */
+export interface OrchestratorOptions {
+  /** Maximum total time for the orchestration in ms (default: 60000) */
+  timeoutMs?: number;
+  /** Maximum retries for individual agent calls (default: 2) */
+  maxRetries?: number;
+  /** Callback for monitoring agent interactions */
+  onAgentMessage?: (message: AgentMessage) => void;
+}
+
+/** Function signature for a router classifier */
+export type RouterClassifier = (
+  input: string,
+  agents: AgentConfig[],
+) => Promise<AgentConfig | AgentConfig[]>;

package/src/lib/agents/tools/calculator.ts

@@ -0,0 +1,131 @@
+/**
+ * Calculator Tool — Safely evaluate mathematical expressions.
+ *
+ * Uses a restricted Function constructor with only Math functions available.
+ * No filesystem, network, or DOM access. Timeout protection included.
+ */
+
+import type { ToolDefinition } from './registry';
+
+export const calculatorTool: ToolDefinition = {
+  name: 'calculator',
+  description:
+    'Evaluate mathematical expressions. Supports basic arithmetic, trigonometry, logarithms, and Math functions. Examples: "2 + 2", "Math.sqrt(16)", "Math.PI * 5^2"',
+  parameters: {
+    expression: {
+      type: 'string',
+      description: 'Math expression to evaluate (e.g., "2 + 2", "Math.sqrt(16)", "sin(PI/4)")',
+      required: true,
+    },
+    precision: {
+      type: 'number',
+      description: 'Number of decimal places in the result (default: 6)',
+      required: false,
+      default: 6,
+    },
+  },
+  handler: async (params): Promise<string> => {
+    const expression = (params.expression as string).trim();
+    const precision = (params.precision as number) ?? 6;
+
+    if (!expression) {
+      return 'Error: Empty expression';
+    }
+
+    // Validate expression — reject dangerous patterns
+    const forbidden = [
+      /\brequire\s*\(/,
+      /\bimport\s+/,
+      /\beval\s*\(/,
+      /\bFunction\s*\(/,
+      /\bprocess\b/,
+      /\bglobal\b/,
+      /\bwindow\b/,
+      /\bdocument\b/,
+      /\bfetch\s*\(/,
+      /\b__proto__\b/,
+      /\bconstructor\b/,
+      /\bprototype\b/,
+    ];
+
+    for (const pattern of forbidden) {
+      if (pattern.test(expression)) {
+        return `Error: Expression contains forbidden pattern: ${pattern.source}`;
+      }
+    }
+
+    try {
+      // Create a sandboxed math environment
+      const mathEnv: Record<string, unknown> = {
+        abs: Math.abs,
+        ceil: Math.ceil,
+        floor: Math.floor,
+        round: Math.round,
+        trunc: Math.trunc,
+        sqrt: Math.sqrt,
+        cbrt: Math.cbrt,
+        pow: Math.pow,
+        exp: Math.exp,
+        log: Math.log,
+        log2: Math.log2,
+        log10: Math.log10,
+        ln: Math.log,
+        sin: Math.sin,
+        cos: Math.cos,
+        tan: Math.tan,
+        asin: Math.asin,
+        acos: Math.acos,
+        atan: Math.atan,
+        atan2: Math.atan2,
+        sinh: Math.sinh,
+        cosh: Math.cosh,
+        tanh: Math.tanh,
+        min: Math.min,
+        max: Math.max,
+        random: Math.random,
+        sign: Math.sign,
+        PI: Math.PI,
+        E: Math.E,
+        LN2: Math.LN2,
+        LN10: Math.LN10,
+        SQRT2: Math.SQRT2,
+        // Aliases
+        pi: Math.PI,
+        e: Math.E,
+        // Convenience functions
+        avg: (...args: number[]) => args.reduce((a, b) => a + b, 0) / args.length,
+        sum: (...args: number[]) => args.reduce((a, b) => a + b, 0),
+        factorial: (n: number) => {
+          if (n < 0 || !Number.isInteger(n)) return NaN;
+          if (n <= 1) return 1;
+          let result = 1;
+          for (let i = 2; i <= n; i++) result *= i;
+          return result;
+        },
+      };
+
+      const keys = Object.keys(mathEnv);
+      const values = Object.values(mathEnv);
+
+      // Replace ^ with ** for exponentiation
+      const processedExpr = expression.replace(/\^/g, '**');
+
+      const fn = new Function(...keys, `"use strict"; return (${processedExpr});`);
+      const result = fn(...values);
+
+      if (typeof result !== 'number' || isNaN(result)) {
+        return `Result: ${result}`;
+      }
+
+      if (!isFinite(result)) {
+        return `Result: ${result === Infinity ? 'Infinity' : '-Infinity'}`;
+      }
+
+      // Format with specified precision
+      const formatted = Number(result.toFixed(precision));
+      return `Result: ${formatted}`;
+    } catch (err) {
+      return `Error evaluating "${expression}": ${(err as Error).message}`;
+    }
+  },
+};

package/src/lib/agents/tools/code-executor.ts

@@ -0,0 +1,191 @@
+/**
+ * Code Executor Tool — Safe sandboxed JavaScript execution.
+ *
+ * Runs user code in a restricted Function sandbox with:
+ * - No filesystem, network, or DOM access
+ * - Configurable timeout
+ * - Console output capture
+ * - Return value serialization
+ */
+
+import type { ToolDefinition } from './registry';
+
+export interface CodeExecutionResult {
+  success: boolean;
+  output: string;
+  returnValue: unknown;
+  consoleOutput: string[];
+  durationMs: number;
+  error?: string;
+}
+
+export const codeExecutorTool: ToolDefinition = {
+  name: 'code_executor',
+  description:
+    'Execute JavaScript code in a safe sandbox. Supports console.log output capture and return values. No filesystem or network access.',
+  parameters: {
+    code: {
+      type: 'string',
+      description: 'JavaScript code to execute. Use return statements to return a value.',
+      required: true,
+    },
+    timeout: {
+      type: 'number',
+      description: 'Execution timeout in milliseconds (default: 5000, max: 10000)',
+      required: false,
+      default: 5000,
+    },
+  },
+  handler: async (params): Promise<string> => {
+    const code = (params.code as string).trim();
+    const timeout = Math.min((params.timeout as number) ?? 5000, 10000);
+
+    if (!code) {
+      return 'Error: No code provided';
+    }
+
+    // Validate code — reject dangerous patterns
+    const forbidden = [
+      /\brequire\s*\(/,
+      /\bimport\s+/,
+      /\beval\s*\(/,
+      /\bFunction\s*\(/,
+      /\bprocess\b/,
+      /\bglobal\b/,
+      /\bglobalThis\b/,
+      /\bwindow\b/,
+      /\bdocument\b/,
+      /\bfetch\s*\(/,
+      /\bXMLHttpRequest\b/,
+      /\bWebSocket\b/,
+      /\bWorker\b/,
+      /\bSharedArrayBuffer\b/,
+      /\bAtomics\b/,
+      /\b__proto__\b/,
+      /\bconstructor\s*\[/,
+      /\[\s*\'constructor\'\s*\]/,
+      /\.constructor\b/,
+    ];
+
+    for (const pattern of forbidden) {
+      if (pattern.test(code)) {
+        return `Error: Code contains forbidden pattern for security: ${pattern.source}`;
+      }
+    }
+
+    try {
+      const consoleOutput: string[] = [];
+
+      // Create a mock console
+      const mockConsole = {
+        log: (...args: unknown[]) => {
+          consoleOutput.push(args.map(stringify).join(' '));
+        },
+        error: (...args: unknown[]) => {
+          consoleOutput.push(`[ERROR] ${args.map(stringify).join(' ')}`);
+        },
+        warn: (...args: unknown[]) => {
+          consoleOutput.push(`[WARN] ${args.map(stringify).join(' ')}`);
+        },
+        info: (...args: unknown[]) => {
+          consoleOutput.push(`[INFO] ${args.map(stringify).join(' ')}`);
+        },
+        table: (data: unknown) => {
+          consoleOutput.push(stringify(data));
+        },
+      };
+
+      // Wrap the code to capture the return value
+      const wrappedCode = `
+        "use strict";
+        const console = arguments[0];
+        ${code}
+      `;
+
+      const startTime = Date.now();
+
+      // Execute with timeout using Promise.race
+      const executionPromise = new Promise<unknown>((resolve, reject) => {
+        try {
+          const fn = new Function(wrappedCode);
+          const result = fn(mockConsole);
+          resolve(result);
+        } catch (err) {
+          reject(err);
+        }
+      });
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error(`Execution timed out after ${timeout}ms`)), timeout);
+      });
+
+      let returnValue: unknown;
+      try {
+        returnValue = await Promise.race([executionPromise, timeoutPromise]);
+      } catch (err) {
+        const durationMs = Date.now() - startTime;
+        const result: CodeExecutionResult = {
+          success: false,
+          output: '',
+          returnValue: undefined,
+          consoleOutput,
+          durationMs,
+          error: (err as Error).message,
+        };
+        return formatResult(result);
+      }
+
+      const durationMs = Date.now() - startTime;
+      const result: CodeExecutionResult = {
+        success: true,
+        output: consoleOutput.join('\n'),
+        returnValue,
+        consoleOutput,
+        durationMs,
+      };
+
+      return formatResult(result);
+    } catch (err) {
+      return `Error: ${(err as Error).message}`;
+    }
+  },
+};
+
+function formatResult(result: CodeExecutionResult): string {
+  const lines: string[] = [];
+
+  lines.push(`Execution ${result.success ? 'completed' : 'failed'} in ${result.durationMs}ms`);
+
+  if (result.consoleOutput.length > 0) {
+    lines.push('');
+    lines.push('Console output:');
+    for (const line of result.consoleOutput) {
+      lines.push(`  ${line}`);
+    }
+  }
+
+  if (result.returnValue !== undefined) {
+    lines.push('');
+    lines.push(`Return value: ${stringify(result.returnValue)}`);
+  }
+
+  if (result.error) {
+    lines.push('');
+    lines.push(`Error: ${result.error}`);
+  }
+
+  return lines.join('\n');
+}
+
+function stringify(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  if (value === null) return 'null';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'function') return '[Function]';
+  if (typeof value === 'symbol') return value.toString();
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}

package/src/lib/agents/tools/file-reader.ts

@@ -0,0 +1,129 @@
+/**
+ * File Reader Tool — Read and analyze file contents.
+ *
+ * Supports text files with line counting, character analysis,
+ * and content previewing. Designed for agent use — does not
+ * directly access the filesystem for security.
+ */
+
+import type { ToolDefinition } from './registry';
+
+export const fileReaderTool: ToolDefinition = {
+  name: 'file_reader',
+  description:
+    'Analyze file contents provided as text. Returns statistics (lines, characters, words) and a preview. Does NOT access the filesystem directly — content must be passed in.',
+  parameters: {
+    content: {
+      type: 'string',
+      description: 'The file content to analyze',
+      required: true,
+    },
+    filename: {
+      type: 'string',
+      description: 'Name of the file (for display purposes)',
+      required: true,
+    },
+    analysis: {
+      type: 'string',
+      description:
+        'Type of analysis: "stats" (line/word/char counts), "preview" (first N lines), "full" (everything), or "summary" (stats + preview)',
+      required: false,
+      default: 'summary',
+      enum: ['stats', 'preview', 'full', 'summary'],
+    },
+    max_preview_lines: {
+      type: 'number',
+      description: 'Maximum number of lines to include in preview (default: 50)',
+      required: false,
+      default: 50,
+    },
+  },
+  handler: async (params): Promise<string> => {
+    const content = params.content as string;
+    const filename = params.filename as string;
+    const analysis = (params.analysis as string) ?? 'summary';
+    const maxPreviewLines = (params.max_preview_lines as number) ?? 50;
+
+    if (!content) {
+      return `File "${filename}": Empty or no content provided.`;
+    }
+
+    const lines = content.split('\n');
+    const totalLines = lines.length;
+    const totalChars = content.length;
+    const totalWords = content.split(/\s+/).filter(Boolean).length;
+
+    // Detect file type
+    const extension = filename.split('.').pop()?.toLowerCase() ?? '';
+    const fileType = getFileType(extension);
+
+    // Non-empty lines
+    const nonEmptyLines = lines.filter((line) => line.trim().length > 0).length;
+
+    const linesResult: string[] = [];
+
+    linesResult.push(`=== File Analysis: ${filename} ===`);
+    linesResult.push('');
+
+    if (analysis === 'stats' || analysis === 'summary') {
+      linesResult.push('Statistics:');
+      linesResult.push(`  Lines: ${totalLines} (${nonEmptyLines} non-empty)`);
+      linesResult.push(`  Characters: ${totalChars.toLocaleString()}`);
+      linesResult.push(`  Words: ${totalWords.toLocaleString()}`);
+      linesResult.push(`  Type: ${fileType}`);
+      linesResult.push(`  Average line length: ${totalChars > 0 ? Math.round(totalChars / totalLines) : 0} chars`);
+      linesResult.push('');
+    }
+
+    if (analysis === 'preview' || analysis === 'summary') {
+      const previewLines = lines.slice(0, maxPreviewLines);
+      linesResult.push(`Content preview (first ${Math.min(maxPreviewLines, totalLines)} of ${totalLines} lines):`);
+      linesResult.push('---');
+
+      for (let i = 0; i < previewLines.length; i++) {
+        const lineNum = String(i + 1).padStart(4, ' ');
+        const line = previewLines[i]!;
+        linesResult.push(`${lineNum} | ${line}`);
+      }
+
+      if (totalLines > maxPreviewLines) {
+        linesResult.push(`\n... ${totalLines - maxPreviewLines} more lines not shown`);
+      }
+
+      linesResult.push('---');
+    }
+
+    if (analysis === 'full') {
+      linesResult.push('Full content:');
+      linesResult.push(content);
+    }
+
+    return linesResult.join('\n');
+  },
+};
+
+function getFileType(extension: string): string {
+  const types: Record<string, string> = {
+    ts: 'TypeScript',
+    tsx: 'TypeScript (React)',
+    js: 'JavaScript',
+    jsx: 'JavaScript (React)',
+    json: 'JSON',
+    md: 'Markdown',
+    css: 'CSS',
+    html: 'HTML',
+    py: 'Python',
+    rs: 'Rust',
+    go: 'Go',
+    java: 'Java',
+    yaml: 'YAML',
+    yml: 'YAML',
+    xml: 'XML',
+    csv: 'CSV',
+    sql: 'SQL',
+    sh: 'Shell',
+    bash: 'Bash',
+    txt: 'Plain Text',
+  };
+  return types[extension] ?? `Unknown (.${extension || 'text'})`;
+}

package/src/lib/agents/tools/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Agent Tools — Default tool set and registry setup.
+ *
+ * Re-exports the ToolRegistry, built-in tools, and provides
+ * a convenience function to create a registry with all default tools.
+ */
+
+export { ToolRegistry, getGlobalRegistry } from './registry';
+export type { ToolDefinition, ToolExecutionResult } from './registry';
+
+export { webSearchTool } from './web-search';
+export { calculatorTool } from './calculator';
+export { codeExecutorTool } from './code-executor';
+export { fileReaderTool } from './file-reader';
+
+import { ToolRegistry } from './registry';
+import { webSearchTool } from './web-search';
+import { calculatorTool } from './calculator';
+import { codeExecutorTool } from './code-executor';
+import { fileReaderTool } from './file-reader';
+
+/** All built-in tools as an array */
+export const builtInTools = [webSearchTool, calculatorTool, codeExecutorTool, fileReaderTool];
+
+/**
+ * Create a ToolRegistry pre-loaded with all built-in tools.
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry();
+ *
+ * // Execute a calculation
+ * const result = await registry.execute('calculator', { expression: '2 + 2' });
+ * console.log(result.result); // "Result: 4"
+ *
+ * // List available tools
+ * console.log(registry.listNames()); // ["web_search", "calculator", "code_executor", "file_reader"]
+ * ```
+ */
+export function createDefaultRegistry(): ToolRegistry {
+  const registry = new ToolRegistry();
+
+  for (const tool of builtInTools) {
+    registry.register(tool);
+  }
+
+  return registry;
+}