User Input
    |
    v
[ Planner / Reasoner ]  <---- working memory + observations
    |
    v
[ Action Selection ]  ----> tool call OR final answer
    |
    v
[ Tool Execution ]
    |
    v
[ Observation ]  ----> append to context, loop back

interface Tool {
  name: string
  description: string
  execute: (input: unknown) => Promise<unknown>
}

interface AgentStep {
  thought: string
  action: string
  actionInput: unknown
  observation: string
}

async function reactAgent(
  goal: string,
  tools: Tool[],
  llm: (prompt: string) => Promise<string>,
  maxIterations = 10,
): Promise<string> {
  const toolMap = Object.fromEntries(tools.map(t => [t.name, t]))
  const toolDescriptions = tools
    .map(t => `- ${t.name}: ${t.description}`)
    .join('\n')

  const history: AgentStep[] = []

  for (let i = 0; i < maxIterations; i++) {
    const context = history
      .map(s => `Thought: ${s.thought}\nAction: ${s.action}[${JSON.stringify(s.actionInput)}]\nObservation: ${s.observation}`)
      .join('\n')

    const prompt = `You are an agent. Available tools:\n${toolDescriptions}\n\nGoal: ${goal}\n\n${context}\n\nThought:`
    const response = await llm(prompt)

    if (response.includes('Final Answer:')) {
      return response.split('Final Answer:')[1].trim()
    }

    const actionMatch = response.match(/Action: (\w+)\[(.*)\]/s)
    if (!actionMatch) break

    const [, actionName, rawInput] = actionMatch
    const tool = toolMap[actionName]
    if (!tool) {
      history.push({ thought: response, action: actionName, actionInput: rawInput, observation: `Error: tool "${actionName}" not found` })
      continue
    }

    let input: unknown
    try { input = JSON.parse(rawInput) } catch { input = rawInput }

    const observation = await tool.execute(input)
    history.push({ thought: response, action: actionName, actionInput: input, observation: JSON.stringify(observation) })
  }

  return `Max iterations (${maxIterations}) reached. Last state: ${JSON.stringify(history.at(-1))}`
}

import { z } from 'zod'

// Input and output schemas are the contract between the LLM and your system.
// Keep descriptions action-oriented and specific.

const searchWebSchema = {
  name: 'search_web',
  description: 'Search the web for current information. Use for facts, news, or data not in training.',
  inputSchema: z.object({
    query: z.string().describe('Specific search query. Be precise - avoid vague terms.'),
    maxResults: z.number().int().min(1).max(10).default(5).describe('Number of results to return'),
  }),
  outputSchema: z.object({
    results: z.array(z.object({
      title: z.string(),
      url: z.string().url(),
      snippet: z.string(),
    })),
    totalFound: z.number(),
  }),
}

const writeFileSchema = {
  name: 'write_file',
  description: 'Write content to a file on disk. Overwrites if file exists.',
  inputSchema: z.object({
    path: z.string().describe('Absolute file path'),
    content: z.string().describe('Full file content to write'),
    encoding: z.enum(['utf-8', 'base64']).default('utf-8'),
  }),
  outputSchema: z.object({
    success: z.boolean(),
    bytesWritten: z.number(),
  }),
}

interface WorkingMemory {
  goal: string
  completedSteps: string[]
  currentPlan: string[]
  facts: Record<string, string>
}

interface EpisodicStore {
  save(sessionId: string, entry: { role: string; content: string }): Promise<void>
  load(sessionId: string, limit?: number): Promise<Array<{ role: string; content: string }>>
}

class AgentMemory {
  private working: WorkingMemory
  private episodic: EpisodicStore
  private sessionId: string

  constructor(goal: string, episodic: EpisodicStore, sessionId: string) {
    this.working = { goal, completedSteps: [], currentPlan: [], facts: {} }
    this.episodic = episodic
    this.sessionId = sessionId
  }

  updatePlan(steps: string[]): void {
    this.working.currentPlan = steps
  }

  markStepComplete(step: string): void {
    this.working.completedSteps.push(step)
    this.working.currentPlan = this.working.currentPlan.filter(s => s !== step)
  }

  storeFact(key: string, value: string): void {
    this.working.facts[key] = value
  }

  async persist(role: string, content: string): Promise<void> {
    await this.episodic.save(this.sessionId, { role, content })
  }

  async loadHistory(limit = 20) {
    return this.episodic.load(this.sessionId, limit)
  }

  serialize(): string {
    return JSON.stringify(this.working, null, 2)
  }
}

interface AgentResult {
  agentId: string
  output: string
  success: boolean
}

type AgentFn = (input: string, context: string) => Promise<AgentResult>

// Sequential pipeline - each agent feeds the next
async function sequentialPipeline(
  agents: Array<{ id: string; fn: AgentFn }>,
  initialInput: string,
): Promise<AgentResult[]> {
  const results: AgentResult[] = []
  let current = initialInput

  for (const { id, fn } of agents) {
    const context = results.map(r => `${r.agentId}: ${r.output}`).join('\n')
    const result = await fn(current, context)
    results.push(result)
    if (!result.success) break  // fail fast
    current = result.output
  }

  return results
}

// Parallel fan-out with synthesis
async function parallelFanOut(
  workers: Array<{ id: string; fn: AgentFn }>,
  synthesizer: AgentFn,
  input: string,
): Promise<AgentResult> {
  const workerResults = await Promise.allSettled(
    workers.map(({ id, fn }) => fn(input, ''))
  )

  const outputs = workerResults
    .filter((r): r is PromiseFulfilledResult<AgentResult> => r.status === 'fulfilled')
    .map(r => r.value)

  const synthesisInput = outputs.map(r => `[${r.agentId}]: ${r.output}`).join('\n\n')
  return synthesizer(synthesisInput, input)
}

// Hierarchical: orchestrator delegates to specialists
async function hierarchical(
  orchestrator: AgentFn,
  specialists: Record<string, AgentFn>,
  goal: string,
): Promise<string> {
  // Orchestrator plans which specialists to invoke
  const plan = await orchestrator(goal, JSON.stringify(Object.keys(specialists)))
  const lines = plan.output.split('\n').filter(l => l.startsWith('DELEGATE:'))

  const delegations = await Promise.all(
    lines.map(line => {
      const [, agentId, task] = line.match(/DELEGATE:(\w+):(.+)/) ?? []
      const specialist = specialists[agentId]
      return specialist ? specialist(task, goal) : Promise.resolve({ agentId, output: 'agent not found', success: false })
    })
  )

  return orchestrator(
    `Synthesize these specialist outputs into a final answer for: ${goal}`,
    delegations.map(d => `${d.agentId}: ${d.output}`).join('\n'),
  ).then(r => r.output)
}

interface GuardrailConfig {
  maxIterations: number
  maxTokensPerStep: number
  allowedToolNames: string[]
  forbiddenPatterns: RegExp[]
  timeoutMs: number
}

class GuardedAgentRunner {
  private config: GuardrailConfig
  private iterationCount = 0
  private startTime = Date.now()

  constructor(config: GuardrailConfig) {
    this.config = config
  }

  checkIterationLimit(): void {
    if (++this.iterationCount > this.config.maxIterations) {
      throw new Error(`Agent exceeded max iterations (${this.config.maxIterations})`)
    }
  }

  checkTimeout(): void {
    if (Date.now() - this.startTime > this.config.timeoutMs) {
      throw new Error(`Agent timed out after ${this.config.timeoutMs}ms`)
    }
  }

  validateToolCall(toolName: string, input: string): void {
    if (!this.config.allowedToolNames.includes(toolName)) {
      throw new Error(`Tool "${toolName}" is not in the allowed list`)
    }
    for (const pattern of this.config.forbiddenPatterns) {
      if (pattern.test(input)) {
        throw new Error(`Tool input matches forbidden pattern: ${pattern}`)
      }
    }
  }

  async runStep<T>(step: () => Promise<T>): Promise<T> {
    this.checkIterationLimit()
    this.checkTimeout()
    return step()
  }
}

interface Task {
  id: string
  description: string
  dependsOn: string[]
  status: 'pending' | 'running' | 'done' | 'failed'
  result?: string
}

async function planAndExecute(
  goal: string,
  planner: (goal: string) => Promise<Task[]>,
  executor: (task: Task, context: Record<string, string>) => Promise<string>,
): Promise<Record<string, string>> {
  const tasks = await planner(goal)
  const results: Record<string, string> = {}

  // Topological execution respecting dependencies
  while (tasks.some(t => t.status === 'pending')) {
    const ready = tasks.filter(
      t => t.status === 'pending' && t.dependsOn.every(dep => results[dep] !== undefined)
    )

    if (ready.length === 0) {
      const stuck = tasks.filter(t => t.status === 'pending')
      throw new Error(`Deadlock: tasks ${stuck.map(t => t.id).join(', ')} cannot proceed`)
    }

    // Run independent ready tasks in parallel
    await Promise.all(
      ready.map(async task => {
        task.status = 'running'
        try {
          results[task.id] = await executor(task, results)
          task.status = 'done'
        } catch (err) {
          task.status = 'failed'
          results[task.id] = `Error: ${String(err)}`
        }
      })
    )
  }

  return results
}

interface AgentTrace {
  steps: Array<{
    thought: string
    toolName?: string
    toolInput?: unknown
    observation?: string
  }>
  finalAnswer: string
  tokensUsed: number
  durationMs: number
}

interface EvalResult {
  passed: boolean
  score: number  // 0-1
  details: string[]
}

function evaluateTrace(trace: AgentTrace, expected: {
  answer: string
  requiredTools?: string[]
  maxSteps?: number
  answerValidator?: (answer: string) => boolean
}): EvalResult {
  const details: string[] = []
  const scores: number[] = []

  // Answer correctness
  const answerCorrect = expected.answerValidator
    ? expected.answerValidator(trace.finalAnswer)
    : trace.finalAnswer.toLowerCase().includes(expected.answer.toLowerCase())
  scores.push(answerCorrect ? 1 : 0)
  details.push(`Answer correct: ${answerCorrect}`)

  // Tool coverage
  if (expected.requiredTools) {
    const usedTools = new Set(trace.steps.map(s => s.toolName).filter(Boolean))
    const covered = expected.requiredTools.filter(t => usedTools.has(t))
    const toolScore = covered.length / expected.requiredTools.length
    scores.push(toolScore)
    details.push(`Tools covered: ${covered.length}/${expected.requiredTools.length}`)
  }

  // Efficiency (step count)
  if (expected.maxSteps) {
    const stepScore = Math.max(0, 1 - (trace.steps.length - 1) / expected.maxSteps)
    scores.push(stepScore)
    details.push(`Steps used: ${trace.steps.length} (max: ${expected.maxSteps})`)
  }

  const score = scores.reduce((a, b) => a + b, 0) / scores.length
  return { passed: score >= 0.7, score, details }
}