brownian-code 2026.2.10

package/src/agent/agent.ts

@@ -0,0 +1,385 @@
+import { AIMessage } from '@langchain/core/messages';
+import { StructuredToolInterface } from '@langchain/core/tools';
+import { callLlm } from '../model/llm.js';
+import { Scratchpad, type ToolContext } from './scratchpad.js';
+import { getTools } from '../tools/registry.js';
+import { buildSystemPrompt, buildIterationPrompt, buildFinalAnswerPrompt } from '../agent/prompts.js';
+import { extractTextContent, hasToolCalls } from '../utils/ai-message.js';
+import { InMemoryChatHistory } from '../utils/in-memory-chat-history.js';
+import { getToolDescription } from '../utils/tool-description.js';
+import { estimateTokens, getContextThreshold, KEEP_TOOL_USES } from '../utils/tokens.js';
+import { createProgressChannel } from '../utils/progress-channel.js';
+import type { AgentConfig, AgentEvent, ToolStartEvent, ToolProgressEvent, ToolEndEvent, ToolErrorEvent, ToolLimitEvent, ContextClearedEvent, TokenUsage } from '../agent/types.js';
+import { TokenCounter } from './token-counter.js';
+
+
+const DEFAULT_MAX_ITERATIONS = 10;
+
+/**
+ * The core agent class that handles the agent loop and tool execution.
+ */
+export class Agent {
+  private readonly model: string;
+  private readonly modelProvider: string;
+  private readonly maxIterations: number;
+  private readonly tools: StructuredToolInterface[];
+  private readonly toolMap: Map<string, StructuredToolInterface>;
+  private readonly systemPrompt: string;
+  private readonly signal?: AbortSignal;
+
+  private constructor(
+    config: AgentConfig,
+    tools: StructuredToolInterface[],
+    systemPrompt: string
+  ) {
+    this.model = config.model ?? 'claude-sonnet-4-5';
+    this.modelProvider = config.modelProvider ?? 'anthropic';
+    this.maxIterations = config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    this.tools = tools;
+    this.toolMap = new Map(tools.map(t => [t.name, t]));
+    this.systemPrompt = systemPrompt;
+    this.signal = config.signal;
+  }
+
+  /**
+   * Create a new Agent instance with tools.
+   */
+  static create(config: AgentConfig = {}): Agent {
+    const model = config.model ?? 'claude-sonnet-4-5';
+    const tools = getTools(model);
+    const systemPrompt = buildSystemPrompt(model);
+    return new Agent(config, tools, systemPrompt);
+  }
+
+  /**
+   * Run the agent and yield events for real-time UI updates.
+   * Anthropic-style context management: full tool results during iteration,
+   * with threshold-based clearing of oldest results when context exceeds limit.
+   */
+  async *run(query: string, inMemoryHistory?: InMemoryChatHistory): AsyncGenerator<AgentEvent> {
+    const startTime = Date.now();
+    const tokenCounter = new TokenCounter();
+    
+    if (this.tools.length === 0) {
+      yield { type: 'done', answer: 'No tools available. Please check your API key configuration.', toolCalls: [], iterations: 0, totalTime: Date.now() - startTime };
+      return;
+    }
+
+    // Create scratchpad for this query - single source of truth for all work done
+    const scratchpad = new Scratchpad(query);
+    
+    // Build initial prompt with conversation history context
+    let currentPrompt = await this.buildInitialPrompt(query, inMemoryHistory);
+    
+    let iteration = 0;
+
+    const contextThreshold = getContextThreshold(this.model);
+
+    // Main agent loop
+    while (iteration < this.maxIterations) {
+      iteration++;
+
+      // Pre-flight context check: trim before sending to model
+      const estimatedPreFlight = estimateTokens(this.systemPrompt + currentPrompt);
+      if (estimatedPreFlight > contextThreshold) {
+        const clearedCount = scratchpad.clearOldestToolResults(KEEP_TOOL_USES);
+        if (clearedCount > 0) {
+          yield { type: 'context_cleared', clearedCount, keptCount: KEEP_TOOL_USES } as ContextClearedEvent;
+          const trimmedResults = scratchpad.getToolResults();
+          currentPrompt = buildIterationPrompt(
+            query,
+            trimmedResults,
+            scratchpad.formatToolUsageForPrompt()
+          );
+        }
+      }
+
+      const { response, usage } = await this.callModel(currentPrompt);
+      tokenCounter.add(usage);
+      const responseText = typeof response === 'string' ? response : extractTextContent(response);
+
+      // Emit thinking if there are also tool calls (skip whitespace-only responses)
+      if (responseText?.trim() && typeof response !== 'string' && hasToolCalls(response)) {
+        const trimmedText = responseText.trim();
+        scratchpad.addThinking(trimmedText);
+        yield { type: 'thinking', message: trimmedText };
+      }
+
+      // No tool calls = ready to generate final answer
+      if (typeof response === 'string' || !hasToolCalls(response)) {
+        // If no tools were called at all, just use the direct response
+        // This handles greetings, clarifying questions, etc.
+        if (!scratchpad.hasToolResults() && responseText) {
+          yield { type: 'answer_start' };
+          const totalTime = Date.now() - startTime;
+          yield { type: 'done', answer: responseText, toolCalls: [], iterations: iteration, totalTime, tokenUsage: tokenCounter.getUsage(), tokensPerSecond: tokenCounter.getTokensPerSecond(totalTime) };
+          return;
+        }
+
+        // Generate final answer with full context from scratchpad
+        const fullContext = this.buildFullContextForAnswer(query, scratchpad);
+        const finalPrompt = buildFinalAnswerPrompt(query, fullContext);
+        
+        yield { type: 'answer_start' };
+        const { response: finalResponse, usage: finalUsage } = await this.callModel(finalPrompt, false);
+        tokenCounter.add(finalUsage);
+        const answer = typeof finalResponse === 'string' 
+          ? finalResponse 
+          : extractTextContent(finalResponse);
+
+        const totalTime = Date.now() - startTime;
+        yield { type: 'done', answer, toolCalls: scratchpad.getToolCallRecords(), iterations: iteration, totalTime, tokenUsage: tokenCounter.getUsage(), tokensPerSecond: tokenCounter.getTokensPerSecond(totalTime) };
+        return;
+      }
+
+      // Execute tools and add results to scratchpad (response is AIMessage here)
+      const generator = this.executeToolCalls(response, query, scratchpad);
+      let result = await generator.next();
+
+      // Yield tool events
+      while (!result.done) {
+        yield result.value;
+        result = await generator.next();
+      }
+      
+      // Anthropic-style context management: get full tool results
+      let fullToolResults = scratchpad.getToolResults();
+      
+      // Check context threshold and clear oldest tool results if needed
+      const estimatedContextTokens = estimateTokens(this.systemPrompt + query + fullToolResults);
+      if (estimatedContextTokens > contextThreshold) {
+        const clearedCount = scratchpad.clearOldestToolResults(KEEP_TOOL_USES);
+        if (clearedCount > 0) {
+          yield { type: 'context_cleared', clearedCount, keptCount: KEEP_TOOL_USES } as ContextClearedEvent;
+          // Re-fetch after clearing
+          fullToolResults = scratchpad.getToolResults();
+        }
+      }
+      
+      // Build iteration prompt with full tool results (Anthropic-style)
+      currentPrompt = buildIterationPrompt(
+        query, 
+        fullToolResults,
+        scratchpad.formatToolUsageForPrompt()
+      );
+    }
+
+    // Max iterations reached - still generate proper final answer
+    const fullContext = this.buildFullContextForAnswer(query, scratchpad);
+    const finalPrompt = buildFinalAnswerPrompt(query, fullContext);
+    
+    yield { type: 'answer_start' };
+    const { response: finalResponse, usage: finalUsage } = await this.callModel(finalPrompt, false);
+    tokenCounter.add(finalUsage);
+    const answer = typeof finalResponse === 'string' 
+      ? finalResponse 
+      : extractTextContent(finalResponse);
+
+    const totalTime = Date.now() - startTime;
+    yield {
+      type: 'done',
+      answer: answer || `Reached maximum iterations (${this.maxIterations}).`,
+      toolCalls: scratchpad.getToolCallRecords(),
+      iterations: iteration,
+      totalTime,
+      tokenUsage: tokenCounter.getUsage(),
+      tokensPerSecond: tokenCounter.getTokensPerSecond(totalTime)
+    };
+  }
+
+  /**
+   * Call the LLM with the current prompt.
+   * @param prompt - The prompt to send to the LLM
+   * @param useTools - Whether to bind tools (default: true). When false, returns string directly.
+   */
+  private async callModel(prompt: string, useTools: boolean = true): Promise<{ response: AIMessage | string; usage?: TokenUsage }> {
+    const result = await callLlm(prompt, {
+      model: this.model,
+      systemPrompt: this.systemPrompt,
+      tools: useTools ? this.tools : undefined,
+      signal: this.signal,
+    });
+    return { response: result.response, usage: result.usage };
+  }
+
+  /**
+   * Execute all tool calls from an LLM response and add results to scratchpad.
+   * Deduplicates skill calls - each skill can only be executed once per query.
+   * Includes graceful exit mechanism - checks tool limits before executing.
+   */
+  private async *executeToolCalls(
+    response: AIMessage,
+    query: string,
+    scratchpad: Scratchpad
+  ): AsyncGenerator<ToolStartEvent | ToolProgressEvent | ToolEndEvent | ToolErrorEvent | ToolLimitEvent, void> {
+    for (const toolCall of response.tool_calls!) {
+      const toolName = toolCall.name;
+      const toolArgs = toolCall.args as Record<string, unknown>;
+
+      // Deduplicate skill calls - each skill can only run once per query
+      if (toolName === 'skill') {
+        const skillName = toolArgs.skill as string;
+        if (scratchpad.hasExecutedSkill(skillName)) continue;
+      }
+
+      const generator = this.executeToolCall(toolName, toolArgs, query, scratchpad);
+      let result = await generator.next();
+
+      while (!result.done) {
+        yield result.value;
+        result = await generator.next();
+      }
+    }
+  }
+
+  /**
+   * Execute a single tool call and add result to scratchpad.
+   * Yields start/end/error events for UI updates.
+   * Includes soft limit warnings to guide the LLM.
+   */
+  private async *executeToolCall(
+    toolName: string,
+    toolArgs: Record<string, unknown>,
+    query: string,
+    scratchpad: Scratchpad
+  ): AsyncGenerator<ToolStartEvent | ToolProgressEvent | ToolEndEvent | ToolErrorEvent | ToolLimitEvent, void> {
+    // Extract query string from tool args for similarity detection
+    const toolQuery = this.extractQueryFromArgs(toolArgs);
+
+    // Check tool limits - yields warning if approaching/over limits
+    const limitCheck = scratchpad.canCallTool(toolName, toolQuery);
+    
+    if (limitCheck.warning) {
+      yield { 
+        type: 'tool_limit', 
+        tool: toolName, 
+        warning: limitCheck.warning, 
+        blocked: false 
+      };
+    }
+
+    yield { type: 'tool_start', tool: toolName, args: toolArgs };
+
+    const toolStartTime = Date.now();
+
+    try {
+      const tool = this.toolMap.get(toolName);
+      if (!tool) {
+        throw new Error(`Tool '${toolName}' not found`);
+      }
+
+      // Create a progress channel so subagent tools can stream status updates
+      const channel = createProgressChannel();
+      const config = {
+        metadata: { onProgress: channel.emit },
+        ...(this.signal ? { signal: this.signal } : {}),
+      };
+
+      // Launch tool invocation -- closes the channel when it settles
+      const toolPromise = tool.invoke(toolArgs, config).then(
+        (raw) => { channel.close(); return raw; },
+        (err) => { channel.close(); throw err; },
+      );
+
+      // Drain progress events in real-time as the tool executes
+      for await (const message of channel) {
+        yield { type: 'tool_progress', tool: toolName, message } as ToolProgressEvent;
+      }
+
+      // Tool has finished -- collect the result
+      const rawResult = await toolPromise;
+      const result = typeof rawResult === 'string' ? rawResult : JSON.stringify(rawResult);
+      const duration = Date.now() - toolStartTime;
+
+      yield { type: 'tool_end', tool: toolName, args: toolArgs, result, duration };
+
+      // Record the tool call for limit tracking
+      scratchpad.recordToolCall(toolName, toolQuery);
+
+      // Add full tool result to scratchpad (Anthropic-style: no inline summarization)
+      scratchpad.addToolResult(toolName, toolArgs, result);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      yield { type: 'tool_error', tool: toolName, error: errorMessage };
+
+      // Still record the call even on error (counts toward limit)
+      scratchpad.recordToolCall(toolName, toolQuery);
+
+      // Add error to scratchpad
+      scratchpad.addToolResult(toolName, toolArgs, `Error: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Extract query string from tool arguments for similarity detection.
+   * Looks for common query-like argument names.
+   */
+  private extractQueryFromArgs(args: Record<string, unknown>): string | undefined {
+    const queryKeys = ['query', 'search', 'question', 'q', 'text', 'input'];
+    
+    for (const key of queryKeys) {
+      if (typeof args[key] === 'string') {
+        return args[key] as string;
+      }
+    }
+    
+    return undefined;
+  }
+
+  /**
+   * Build initial prompt with conversation history context if available.
+   * Uses LLM-based relevance selection to include only pertinent history.
+   */
+  private async buildInitialPrompt(
+    query: string,
+    inMemoryChatHistory?: InMemoryChatHistory
+  ): Promise<string> {
+    if (!inMemoryChatHistory?.hasMessages()) {
+      return query;
+    }
+
+    const relevantMessages = await inMemoryChatHistory.selectRelevantMessages(query);
+    if (relevantMessages.length === 0) {
+      return query;
+    }
+
+    const historyContext = inMemoryChatHistory.formatForPlanning(relevantMessages);
+    return `Current query to answer: ${query}\n\nRelevant conversation history:\n${historyContext}`;
+  }
+
+  /**
+   * Build full context data for final answer generation from scratchpad.
+   * Uses only active (non-cleared) tool results — cleared entries were removed
+   * because context was too large, so re-including them would cause the same overflow.
+   */
+  private buildFullContextForAnswer(_query: string, scratchpad: Scratchpad): string {
+    const contexts = scratchpad.getActiveToolResults();
+
+    if (contexts.length === 0) {
+      return 'No data was gathered.';
+    }
+
+    // Filter out error results
+    const validContexts = contexts.filter(ctx => !ctx.result.startsWith('Error:'));
+
+    if (validContexts.length === 0) {
+      return 'No data was successfully gathered.';
+    }
+
+    // Format all contexts with full data
+    return validContexts.map(ctx => this.formatToolContext(ctx)).join('\n\n');
+  }
+
+  /**
+   * Format a single tool context entry for the final answer.
+   */
+  private formatToolContext(ctx: ToolContext): string {
+    const description = getToolDescription(ctx.toolName, ctx.args);
+    try {
+      return `### ${description}\n\`\`\`json\n${JSON.stringify(JSON.parse(ctx.result), null, 2)}\n\`\`\``;
+    } catch {
+      // If result is not valid JSON, return as-is
+      return `### ${description}\n${ctx.result}`;
+    }
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,27 @@
+export { Agent } from './agent.js';
+
+export { Scratchpad } from './scratchpad.js';
+
+export { getCurrentDate, buildSystemPrompt, buildIterationPrompt, DEFAULT_SYSTEM_PROMPT } from './prompts.js';
+
+export type { 
+  AgentConfig, 
+  Message,
+  AgentEvent,
+  ThinkingEvent,
+  ToolStartEvent,
+  ToolProgressEvent,
+  ToolEndEvent,
+  ToolErrorEvent,
+  ToolLimitEvent,
+  AnswerStartEvent,
+  DoneEvent,
+} from './types.js';
+
+export type { 
+  ToolCallRecord, 
+  ToolContext, 
+  ScratchpadEntry,
+  ToolLimitConfig,
+  ToolUsageStatus,
+} from './scratchpad.js';

package/src/agent/prompts.ts

@@ -0,0 +1,271 @@
+import { buildToolDescriptions } from '../tools/registry.js';
+import { buildSkillMetadataSection, discoverSkills } from '../skills/index.js';
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Returns the current date formatted for prompts.
+ */
+export function getCurrentDate(): string {
+  const options: Intl.DateTimeFormatOptions = {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  };
+  return new Date().toLocaleDateString('en-US', options);
+}
+
+/**
+ * Build the skills section for the system prompt.
+ * Only includes skill metadata if skills are available.
+ */
+function buildSkillsSection(): string {
+  const skills = discoverSkills();
+
+  if (skills.length === 0) {
+    return '';
+  }
+
+  const skillList = buildSkillMetadataSection();
+
+  return `## Available Skills
+
+${skillList}
+
+## Skill Usage Policy
+
+- Check if available skills can help complete the task more effectively
+- When a skill is relevant, invoke it IMMEDIATELY as your first action
+- Skills provide specialized workflows for complex tasks
+- Do not invoke a skill that has already been invoked for the current query`;
+}
+
+// ============================================================================
+// Default System Prompt (for backward compatibility)
+// ============================================================================
+
+/**
+ * Default system prompt used when no specific prompt is provided.
+ */
+export const DEFAULT_SYSTEM_PROMPT = `You are Brownian Code, an AI agent for crypto research.
+
+Current date: ${getCurrentDate()}
+
+Your output is displayed on a command line interface. Keep responses short and concise.
+
+## Behavior
+
+- Prioritize accuracy over validation
+- Use professional, data-driven tone
+- Never hype or shill tokens
+
+## Response Format
+
+- Keep responses brief and direct
+- For non-comparative information, prefer plain text or simple lists over tables
+- Do not use markdown headers or *italics* - use **bold** sparingly for emphasis
+
+## Tables (for comparative/tabular data)
+
+Use markdown tables. They will be rendered as formatted box tables.
+
+STRICT FORMAT - each row must:
+- Start with | and end with |
+- Have no trailing spaces after the final |
+- Use |---| separator (with optional : for alignment)
+
+| Token | Price    | 24h    | MCap  |
+|-------|----------|--------|-------|
+| BTC   | $67,420  | +2.3%  | 1.3T  |
+
+Keep tables compact:
+- Max 3-4 columns; prefer multiple small tables over one wide table
+- Use symbols/tickers not full names: "BTC" not "Bitcoin"
+- Numbers compact: 1.3T not $1,300,000,000,000
+- Omit units in cells if header has them`;
+
+// ============================================================================
+// System Prompt
+// ============================================================================
+
+/**
+ * Build the system prompt for the agent.
+ * @param model - The model name (used to get appropriate tool descriptions)
+ */
+export function buildSystemPrompt(model: string): string {
+  const toolDescriptions = buildToolDescriptions(model);
+
+  return `You are Brownian Code, a CLI agent for crypto research. You have access to 227+ crypto data tools via Hive Intelligence, covering market data, DeFi, wallets, security, NFTs, and more.
+
+Current date: ${getCurrentDate()}
+
+Your output is displayed on a command line interface. Keep responses short and concise.
+
+## Available Tools
+
+${toolDescriptions}
+
+## Tool Usage Policy
+
+- **Category-first routing**: classify intent → call category endpoint → get schema → invoke endpoint
+- **Common shortcuts**: skip schema for well-known endpoints (get_protocol_tvl, get_defi_protocol, get_token_security, check_malicious_address)
+- **Tool budget**: aim for 3-5 tool calls per query (1 category + 1 schema + 1-3 invokes)
+- **Prefer aggregate endpoints**: use coins_market_data_browser for multi-coin comparisons instead of multiple simple_price calls
+- Only use tools when the query actually requires external data
+- Use web_fetch for reading web pages, articles, and documentation
+- Only use browser when you need JavaScript rendering or interactive navigation
+- For general knowledge questions, respond directly without tools
+
+## CRITICAL Tool Rules
+
+- **NEVER** call the same tool twice with the same or similar arguments
+- **NEVER** call a category tool (get_*_endpoints) more than once per query
+- invoke_api_endpoint takes \`endpoint_name\` and \`arguments\` — e.g. \`{ "endpoint_name": "get_protocol_tvl", "arguments": { "protocol": "lido" } }\`
+- get_api_endpoint_schema takes \`endpoint_name\` — e.g. \`{ "endpoint_name": "get_token_security" }\`
+- If a tool call returns an error, do NOT retry with the same arguments — adjust or try a different endpoint
+
+## Correct Call Pattern Examples
+
+**TVL lookup** (1 call — well-known shortcut):
+→ invoke_api_endpoint({ endpoint_name: "get_protocol_tvl", arguments: { protocol: "lido" } })
+
+**DeFi protocol detail** (3 calls):
+→ get_defi_protocol_endpoints() → get_api_endpoint_schema({ endpoint_name: "get_defi_protocol" }) → invoke_api_endpoint({ endpoint_name: "get_defi_protocol", arguments: { protocol: "aave" } })
+
+**Security audit** (3 calls):
+→ get_security_risk_endpoints() → get_api_endpoint_schema({ endpoint_name: "get_token_security" }) → invoke_api_endpoint({ endpoint_name: "get_token_security", arguments: { chainId: "1", contract_addresses: "0x..." } })
+
+## Entity Resolution
+
+When users mention crypto assets, resolve to standard IDs:
+- BTC/btc/Bitcoin → id: "bitcoin"
+- ETH/eth/Ethereum → id: "ethereum"
+- SOL/sol/Solana → id: "solana"
+- BNB/bnb → id: "binancecoin"
+- XRP/xrp → id: "ripple"
+- ADA/ada/Cardano → id: "cardano"
+- AVAX/avax → id: "avalanche-2"
+- DOT/dot → id: "polkadot"
+- MATIC/matic → id: "matic-network"
+- LINK/link → id: "chainlink"
+- UNI/uni → id: "uniswap"
+- AAVE/aave → id: "aave"
+- Default currency: USD | Default timeframe: 24h
+- For contract addresses (0x...), use contract lookup endpoints
+
+## Security-First Routing
+
+- **Top 20 tokens** (BTC, ETH, SOL, BNB, XRP, ADA, AVAX, DOT, MATIC, LINK, UNI, AAVE, etc.): direct price lookup OK
+- **Any other token**: ALWAYS check security first via get_security_risk_endpoints before presenting data
+- **Always warn about**: honeypots, concentrated holders (>50% held by top 10), unverified contracts, low liquidity
+
+## Query Classification
+
+- **LOOKUP** (2-3 calls): single asset price, basic token info → category + schema + invoke
+- **ANALYSIS** (3-5 calls): multi-asset comparison, wallet analysis, DeFi research → category + schema + 2-3 invokes
+- **EXPLORATION** (4-6 calls): discovery, trending, complex research → multiple categories + invokes
+
+${buildSkillsSection()}
+
+## Behavior
+
+- Prioritize accuracy — never fabricate data or make up numbers
+- Use professional, data-driven tone without hype or shilling
+- For research tasks, be thorough but efficient
+- Always note data freshness (Hive data is near real-time but may have slight delays)
+- Acknowledge limitations of on-chain data (e.g., CEX balances not visible)
+- Never ask users to provide raw data or reference JSON/API internals
+- If data is incomplete, answer with what you have without exposing implementation details
+
+## Response Format
+
+- Keep casual responses brief and direct
+- For research: lead with the key finding and include specific data points
+- For price lookups: include price, 24h change, and market cap when available
+- For comparisons: use tables with key metrics
+- Don't narrate your actions or ask leading questions
+- Do not use markdown headers or *italics* - use **bold** sparingly for emphasis
+- Include data source attribution when relevant (e.g., "via CoinGecko", "via DefiLlama")
+
+## Tables (for comparative/tabular data)
+
+Use markdown tables. They will be rendered as formatted box tables.
+
+STRICT FORMAT - each row must:
+- Start with | and end with |
+- Have no trailing spaces after the final |
+- Use |---| separator (with optional : for alignment)
+
+| Token | Price    | 24h    | MCap  |
+|-------|----------|--------|-------|
+| BTC   | $67,420  | +2.3%  | 1.3T  |
+
+Keep tables compact:
+- Max 3-4 columns; prefer multiple small tables over one wide table
+- Use symbols/tickers not full names: "BTC" not "Bitcoin"
+- Numbers compact: 1.3T not $1,300,000,000,000
+- Omit units in cells if header has them
+- Use color hints: prefix positive changes with +, negative with -`;
+}
+
+// ============================================================================
+// User Prompts
+// ============================================================================
+
+/**
+ * Build user prompt for agent iteration with full tool results.
+ * Anthropic-style: full results in context for accurate decision-making.
+ * Context clearing happens at threshold, not inline summarization.
+ *
+ * @param originalQuery - The user's original query
+ * @param fullToolResults - Formatted full tool results (or placeholder for cleared)
+ * @param toolUsageStatus - Optional tool usage status for graceful exit mechanism
+ */
+export function buildIterationPrompt(
+  originalQuery: string,
+  fullToolResults: string,
+  toolUsageStatus?: string | null
+): string {
+  let prompt = `Query: ${originalQuery}`;
+
+  if (fullToolResults.trim()) {
+    prompt += `
+
+Data retrieved from tool calls:
+${fullToolResults}`;
+  }
+
+  // Add tool usage status if available (graceful exit mechanism)
+  if (toolUsageStatus) {
+    prompt += `\n\n${toolUsageStatus}`;
+  }
+
+  prompt += `
+
+Continue working toward answering the query. If you have gathered actual content (not just links or titles), you may respond. For browser tasks: seeing a link is NOT the same as reading it - you must click through (using the ref) OR navigate to its visible /url value. NEVER guess at URLs - use ONLY URLs visible in snapshots.`;
+
+  return prompt;
+}
+
+// ============================================================================
+// Final Answer Generation
+// ============================================================================
+
+/**
+ * Build the prompt for final answer generation with full context data.
+ * This is used after context compaction - full data is loaded from disk for the final answer.
+ */
+export function buildFinalAnswerPrompt(
+  originalQuery: string,
+  fullContextData: string
+): string {
+  return `Query: ${originalQuery}
+
+Data retrieved from your tool calls:
+${fullContextData}
+
+Answer the user's query using this data. Do not ask the user to provide additional data, paste values, or reference JSON/API internals. If data is incomplete, answer with what you have.`;
+}