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 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 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 }
}