Multi-Agent Systems

import {
  LlmAgent,
  SequentialAgent,
  ParallelAgent,
  AgentBuilder,
} from "@iqai/adk";

// Specialist agents for content analysis
const sentimentAnalyzer = new LlmAgent({
  name: "sentiment_analyzer",
  model: "gemini-2.5-flash",
  description: "Analyzes emotional tone and sentiment",
  instruction:
    "Analyze the sentiment and emotional tone of the content. Classify as positive, negative, or neutral with confidence scores.",
  outputKey: "sentiment_analysis",
});

const topicExtractor = new LlmAgent({
  name: "topic_extractor",
  model: "gemini-2.5-flash",
  description: "Identifies key topics and themes",
  instruction:
    "Extract the main topics, themes, and key concepts from the content. Provide a hierarchical list.",
  outputKey: "topic_analysis",
});

// Parallel analysis phase
const analysisPhase = new ParallelAgent({
  name: "content_analysis",
  description: "Perform multiple types of content analysis simultaneously",
  subAgents: [sentimentAnalyzer, topicExtractor],
});

// Content processor and formatter
const contentSummarizer = new LlmAgent({
  name: "content_summarizer",
  model: "gemini-2.5-flash",
  description: "Creates comprehensive summaries",
  instruction:
    "Based on sentiment analysis: {sentiment_analysis} and topic analysis: {topic_analysis}, create a comprehensive summary highlighting key insights.",
  outputKey: "content_summary",
});

// Complete processing pipeline
const contentProcessor = new SequentialAgent({
  name: "content_processing_system",
  description: "Analyze and summarize content using multiple perspectives",
  subAgents: [
    analysisPhase, // Parallel: sentiment + topic analysis
    contentSummarizer, // Sequential: combine insights into summary
  ],
});

// Usage with AgentBuilder
const { runner } = await AgentBuilder.withAgent(contentProcessor).build();

const result = await runner.ask(
  "Analyze this customer feedback: 'I love the new features, but the interface is confusing and slow.'"
);

// Establishing agent hierarchy
const billingAgent = new LlmAgent({
  name: "billing_specialist",
  description: "Handles billing and payment issues",
});

const coordinator = new LlmAgent({
  name: "support_coordinator",
  description: "Routes customer inquiries to specialists",
  subAgents: [billingAgent], // Creates parent-child relationship
});

// ADK-TS automatically sets: billingAgent.parentAgent === coordinator
// Navigate: coordinator.findAgent("billing_specialist") returns billingAgent
// Access root: billingAgent.rootAgent === coordinator

// Sequential pipeline example
const dataFetcher = new LlmAgent({
  name: "data_fetcher",
  model: "gemini-2.5-flash",
  instruction: "Retrieve the latest market data for analysis",
  outputKey: "raw_data", // Saved to session state
});

const dataAnalyzer = new LlmAgent({
  name: "data_analyzer",
  model: "gemini-2.5-flash",
  instruction: "Analyze the market data: {raw_data} and identify key trends", // State injection
  outputKey: "analysis_results",
});

const reportGenerator = new LlmAgent({
  name: "report_generator",
  model: "gemini-2.5-flash",
  instruction:
    "Generate a comprehensive report from analysis: {analysis_results}",
  outputKey: "final_report",
});

const marketPipeline = new SequentialAgent({
  name: "market_analysis_pipeline",
  description: "Complete market analysis workflow",
  subAgents: [dataFetcher, dataAnalyzer, reportGenerator],
});

// Execution: dataFetcher → dataAnalyzer → reportGenerator
// State flows: raw_data → analysis_results → final_report

// Parallel processing example
const technicalAnalyzer = new LlmAgent({
  name: "technical_analyzer",
  model: "gemini-2.5-flash",
  instruction: "Perform technical analysis on the provided data",
  outputKey: "technical_analysis", // Unique key to avoid conflicts
});

const fundamentalAnalyzer = new LlmAgent({
  name: "fundamental_analyzer",
  model: "gemini-2.5-flash",
  instruction: "Perform fundamental analysis on the provided data",
  outputKey: "fundamental_analysis", // Different key
});

const sentimentAnalyzer = new LlmAgent({
  name: "sentiment_analyzer",
  model: "gemini-2.5-flash",
  instruction: "Analyze market sentiment from the provided data",
  outputKey: "sentiment_analysis", // Another unique key
});

const multiPerspectiveAnalysis = new ParallelAgent({
  name: "multi_perspective_analysis",
  description: "Analyze data from multiple perspectives simultaneously",
  subAgents: [technicalAnalyzer, fundamentalAnalyzer, sentimentAnalyzer],
});

// Execution: All three analyzers run concurrently
// Branch contexts: multi_perspective_analysis.technical_analyzer, etc.
// State populated with: technical_analysis, fundamental_analysis, sentiment_analysis
// Subsequent agents can access all results: "Combine insights from {technical_analysis}, {fundamental_analysis}, and {sentiment_analysis}"

import { LoopAgent, LlmAgent, BaseAgent, Event, EventActions } from "@iqai/adk";
import { InvocationContext } from "@iqai/adk/types";

// Custom agent to control loop termination
class QualityChecker extends BaseAgent {
  constructor() {
    super({
      name: "quality_checker",
      description:
        "Evaluates quality and decides whether to continue iterating",
    });
  }

  protected async *runAsyncImpl(ctx: InvocationContext) {
    const qualityScore = ctx.session.state.get("quality_score", 0);
    const iteration = ctx.session.state.get("iteration_count", 0) + 1;

    // Update iteration counter
    ctx.session.state.set("iteration_count", iteration);

    // Stop if quality is sufficient (score >= 8) or too many attempts
    const shouldStop = qualityScore >= 8 || iteration >= 5;

    yield new Event({
      author: this.name,
      content: {
        parts: [
          {
            text: `Iteration ${iteration}: Quality score ${qualityScore}. ${
              shouldStop ? "Quality sufficient!" : "Needs improvement."
            }`,
          },
        ],
      },
      actions: new EventActions({ escalate: shouldStop }),
    });
  }
}

const contentImprover = new LlmAgent({
  name: "content_improver",
  model: "gemini-2.5-flash",
  instruction:
    "Improve the content quality. Rate the current quality from 1-10 and provide an improved version.",
  outputKey: "quality_score", // Will be used by QualityChecker
});

const iterativeImprovement = new LoopAgent({
  name: "iterative_improvement",
  description: "Iteratively improve content until quality standards are met",
  maxIterations: 10, // Safety limit
  subAgents: [contentImprover, new QualityChecker()],
});

// Execution: contentImprover → QualityChecker → repeat until escalation
// Loop continues until quality_score >= 8 or maxIterations reached

// Producer agent - writes to state
const dataCollector = new LlmAgent({
  name: "data_collector",
  model: "gemini-2.5-flash",
  instruction:
    "Collect user preferences and demographic information from the input",
  outputKey: "user_profile", // Saves response to state["user_profile"]
});

// Consumer agent - reads from state
const recommendationEngine = new LlmAgent({
  name: "recommendation_engine",
  model: "gemini-2.5-flash",
  instruction:
    "Based on the user profile: {user_profile}, generate personalized recommendations", // {user_profile} gets replaced with actual data
});

const pipeline = new SequentialAgent({
  name: "personalization_pipeline",
  description: "Collect preferences and generate recommendations",
  subAgents: [dataCollector, recommendationEngine],
});

// Flow: dataCollector saves to state → recommendationEngine reads from state

// Specialist agents with clear descriptions
const billingAgent = new LlmAgent({
  name: "billing_specialist",
  model: "gemini-2.5-flash",
  description:
    "Handles billing issues, payment problems, refunds, and subscription management",
});

const technicalAgent = new LlmAgent({
  name: "technical_specialist",
  model: "gemini-2.5-flash",
  description:
    "Resolves technical issues, bugs, system problems, and integration questions",
});

// Coordinator with clear transfer instructions
const supportCoordinator = new LlmAgent({
  name: "support_coordinator",
  model: "gemini-2.5-flash",
  description: "Routes customer support requests to appropriate specialists",
  instruction: `You coordinate customer support. Analyze the user's issue and transfer to the appropriate specialist:

- For billing, payment, subscription, or refund issues → transfer to 'billing_specialist'
- For technical problems, bugs, or system issues → transfer to 'technical_specialist'  
- For general questions, handle them yourself

Use the transfer_to_agent function when you identify a specialist who can better help.`,
  subAgents: [billingAgent, technicalAgent], // Enables AutoFlow
});

// Usage examples:
// "I was charged twice this month" → transfers to billing_specialist
// "The app keeps crashing" → transfers to technical_specialist
// "What are your business hours?" → handles directly (no transfer)

import { AgentTool, LlmAgent } from "@iqai/adk";

// Specialized capability agents
const dataValidator = new LlmAgent({
  name: "data_validator",
  model: "gemini-2.5-flash",
  description: "Validates data quality and format",
  instruction:
    "Analyze the provided data for completeness, accuracy, and format issues. Return validation results.",
});

const insightExtractor = new LlmAgent({
  name: "insight_extractor",
  model: "gemini-2.5-flash",
  description: "Extracts key insights and patterns from data",
  instruction:
    "Analyze the data and extract the most important insights, trends, and patterns.",
});

// Orchestrating agent that uses other agents as tools
const dataAnalyst = new LlmAgent({
  name: "data_analyst",
  model: "gemini-2.5-flash",
  description:
    "Comprehensive data analysis using validation and insight extraction",
  instruction: `You are a data analyst. For any data analysis request:
    1. First use the validate_data tool to check data quality
    2. Then use the extract_insights tool to find patterns
    3. Combine the results into a comprehensive analysis report`,
  tools: [
    new AgentTool({
      name: "validate_data",
      agent: dataValidator,
      description: "Validate data quality and format",
    }),
    new AgentTool({
      name: "extract_insights",
      agent: insightExtractor,
      description: "Extract key insights from data",
    }),
  ],
});

// Usage: dataAnalyst can call validate_data and extract_insights as needed
// Each tool invocation runs the wrapped agent and returns results

// Specialist agents with clear, distinct descriptions
const billingSpecialist = new LlmAgent({
  name: "billing_specialist",
  model: "gemini-2.5-flash",
  description:
    "Handles billing issues, payment problems, refunds, and subscription management",
  instruction:
    "You are a billing specialist. Help customers with payment issues, billing questions, refunds, and subscription management.",
});

const technicalSpecialist = new LlmAgent({
  name: "technical_specialist",
  model: "gemini-2.5-flash",
  description:
    "Resolves technical problems, system issues, bugs, and integration questions",
  instruction:
    "You are a technical support specialist. Help customers resolve technical issues, system problems, and integration questions.",
});

const generalSupport = new LlmAgent({
  name: "general_support",
  model: "gemini-2.5-flash",
  description:
    "Provides general information, account questions, and product assistance",
  instruction:
    "You provide general customer support for account questions, product information, and general assistance.",
});

// Coordinator with clear routing logic
const customerServiceRouter = new LlmAgent({
  name: "customer_service_router",
  model: "gemini-2.5-flash",
  description: "Routes customer inquiries to appropriate specialists",
  instruction: `You are a customer service coordinator. Analyze customer requests and route them to the appropriate specialist:

- For billing, payments, refunds, or subscription issues → transfer_to_agent('billing_specialist')  
- For technical problems, bugs, system issues, or integrations → transfer_to_agent('technical_specialist')
- For general questions, account info, or product features → transfer_to_agent('general_support')

If the request doesn't clearly fit a category, handle it yourself or ask for clarification.`,
  subAgents: [billingSpecialist, technicalSpecialist, generalSupport],
});

// Usage examples:
// "I was double-charged this month" → routes to billing_specialist
// "The app keeps crashing" → routes to technical_specialist
// "How do I change my password?" → routes to general_support

// Content creation pipeline example
const contentResearcher = new LlmAgent({
  name: "content_researcher",
  model: "gemini-2.5-flash",
  instruction:
    "Research the given topic thoroughly. Gather key facts, statistics, and relevant information.",
  outputKey: "research_data", // Output saved to session state
});

const contentOutliner = new LlmAgent({
  name: "content_outliner",
  model: "gemini-2.5-flash",
  instruction:
    "Based on the research data: {research_data}, create a detailed content outline with main points and structure.", // References research_data from state
  outputKey: "content_outline",
});

const contentWriter = new LlmAgent({
  name: "content_writer",
  model: "gemini-2.5-flash",
  instruction:
    "Using the research: {research_data} and outline: {content_outline}, write a comprehensive, well-structured article.", // References both previous outputs
  outputKey: "draft_content",
});

const contentEditor = new LlmAgent({
  name: "content_editor",
  model: "gemini-2.5-flash",
  instruction:
    "Review and edit the draft content: {draft_content}. Improve clarity, flow, and accuracy.",
  outputKey: "final_content",
});

// Sequential pipeline orchestration
const contentCreationPipeline = new SequentialAgent({
  name: "content_creation_pipeline",
  description: "Complete content creation from research to final edited piece",
  subAgents: [contentResearcher, contentOutliner, contentWriter, contentEditor],
});

// Execution flow:
// 1. contentResearcher → state["research_data"]
// 2. contentOutliner → reads research_data → state["content_outline"]
// 3. contentWriter → reads research_data + content_outline → state["draft_content"]
// 4. contentEditor → reads draft_content → state["final_content"]

// Multi-perspective analysis example
const sentimentAnalyzer = new LlmAgent({
  name: "sentiment_analyzer",
  model: "gemini-2.5-flash",
  instruction:
    "Analyze the sentiment and emotional tone of the provided content. Classify sentiment and provide confidence scores.",
  outputKey: "sentiment_analysis", // Unique key for this perspective
});

const topicExtractor = new LlmAgent({
  name: "topic_extractor",
  model: "gemini-2.5-flash",
  instruction:
    "Extract and categorize the main topics, themes, and subjects discussed in the content.",
  outputKey: "topic_extraction", // Different key to avoid conflicts
});

const styleAnalyzer = new LlmAgent({
  name: "style_analyzer",
  model: "gemini-2.5-flash",
  instruction:
    "Analyze the writing style, tone, complexity, and target audience of the content.",
  outputKey: "style_analysis", // Another unique key
});

// Parallel execution of all analysis types
const multiPerspectiveAnalysis = new ParallelAgent({
  name: "multi_perspective_analysis",
  description: "Analyze content from multiple perspectives simultaneously",
  subAgents: [sentimentAnalyzer, topicExtractor, styleAnalyzer],
});

// Optional: Synthesis agent to combine results
const insightSynthesizer = new LlmAgent({
  name: "insight_synthesizer",
  model: "gemini-2.5-flash",
  instruction: `Synthesize insights from multiple analyses:
    - Sentiment: {sentiment_analysis}
    - Topics: {topic_extraction}  
    - Style: {style_analysis}
    
    Create a comprehensive analysis that identifies patterns, correlations, and key insights across all perspectives.`,
  outputKey: "comprehensive_analysis",
});

// Complete workflow: parallel analysis + synthesis
const comprehensiveContentAnalysis = new SequentialAgent({
  name: "comprehensive_content_analysis",
  description: "Multi-perspective analysis with synthesis",
  subAgents: [multiPerspectiveAnalysis, insightSynthesizer],
});

// Execution:
// Phase 1 (Parallel): All three analyzers run simultaneously
//   - sentiment_analyzer → state["sentiment_analysis"]
//   - topic_extractor → state["topic_extraction"]
//   - style_analyzer → state["style_analysis"]
// Phase 2 (Sequential): insightSynthesizer combines all results

import { AgentTool } from "@iqai/adk";

// Foundation layer: Basic capabilities
const textAnalyzer = new LlmAgent({
  name: "text_analyzer",
  model: "gemini-2.5-flash",
  description: "Analyzes text for sentiment, topics, and key information",
  instruction:
    "Analyze the provided text and extract key information, sentiment, and main topics.",
});

const dataSummarizer = new LlmAgent({
  name: "data_summarizer",
  model: "gemini-2.5-flash",
  description: "Summarizes complex information into concise insights",
  instruction:
    "Create a clear, concise summary of the provided information, highlighting the most important points.",
});

// Intermediate layer: Composed capabilities
const contentProcessor = new LlmAgent({
  name: "content_processor",
  model: "gemini-2.5-flash",
  description: "Processes content through analysis and summarization",
  instruction: `Process content through multiple stages:
    1. Use text_analysis to understand the content structure
    2. Use summarization to create key insights
    3. Combine results into a processed content report`,
  tools: [
    new AgentTool({
      name: "text_analysis",
      agent: textAnalyzer,
      description: "Analyze text for structure and content",
    }),
    new AgentTool({
      name: "summarization",
      agent: dataSummarizer,
      description: "Summarize information into key points",
    }),
  ],
});

const qualityAssessor = new LlmAgent({
  name: "quality_assessor",
  model: "gemini-2.5-flash",
  description: "Assesses content quality and provides improvement suggestions",
  instruction:
    "Evaluate content quality on clarity, accuracy, completeness, and provide specific improvement suggestions.",
});

// Top layer: High-level orchestration
const contentManager = new LlmAgent({
  name: "content_manager",
  model: "gemini-2.5-flash",
  description: "Manages end-to-end content processing and quality assurance",
  instruction: `Manage complete content workflow:
    1. Use process_content to analyze and summarize
    2. Use assess_quality to evaluate results
    3. Provide final recommendations and processed content`,
  tools: [
    new AgentTool({
      name: "process_content",
      agent: contentProcessor,
      description: "Process content through analysis and summarization",
    }),
    new AgentTool({
      name: "assess_quality",
      agent: qualityAssessor,
      description: "Assess content quality and suggest improvements",
    }),
  ],
});

// Usage: contentManager orchestrates the entire hierarchy
// contentManager → contentProcessor → textAnalyzer + dataSummarizer
// contentManager → qualityAssessor
// Results flow back up through the tool calls

// Generator-Critic workflow for content creation
const contentGenerator = new LlmAgent({
  name: "content_generator",
  model: "gemini-2.5-flash",
  instruction:
    "Create comprehensive content based on the provided requirements. Focus on accuracy, clarity, and completeness.",
  outputKey: "initial_content", // Saves generated content
});

const contentCritic = new LlmAgent({
  name: "content_critic",
  model: "gemini-2.5-flash",
  instruction: `Review the content: {initial_content}
    
    Evaluate on these criteria:
    - Accuracy: Are facts and information correct?
    - Clarity: Is the content easy to understand?
    - Completeness: Does it cover all necessary points?
    - Structure: Is it well-organized and logical?
    
    Provide specific, actionable feedback with examples of what needs improvement.`,
  outputKey: "review_feedback", // Saves critic's feedback
});

const contentRefiner = new LlmAgent({
  name: "content_refiner",
  model: "gemini-2.5-flash",
  instruction: `Improve the original content: {initial_content} based on this feedback: {review_feedback}
    
    Make specific improvements while maintaining the original intent and style. Address each point of feedback systematically.`,
  outputKey: "refined_content", // Saves improved version
});

// Sequential workflow: Generate → Critique → Refine
const qualityContentWorkflow = new SequentialAgent({
  name: "quality_content_workflow",
  description: "Generate high-quality content through review and refinement",
  subAgents: [contentGenerator, contentCritic, contentRefiner],
});

// Optional: Iterative version using LoopAgent
const iterativeQualityWorkflow = new LoopAgent({
  name: "iterative_quality_workflow",
  description: "Repeatedly refine content until quality standards are met",
  maxIterations: 3,
  subAgents: [contentGenerator, contentCritic, contentRefiner],
});

// Execution flow:
// 1. contentGenerator → state["initial_content"]
// 2. contentCritic → reads initial_content → state["review_feedback"]
// 3. contentRefiner → reads both → state["refined_content"]

import { LoopAgent, LlmAgent, BaseAgent, Event, EventActions } from "@iqai/adk";

// Agent that performs improvements
const solutionImprover = new LlmAgent({
  name: "solution_improver",
  model: "gemini-2.5-flash",
  instruction: `Analyze the current solution: {current_solution} and the original problem: {problem_statement}
    
    Identify specific areas for improvement:
    - Completeness: Does it fully address the problem?
    - Efficiency: Can it be optimized?
    - Clarity: Is it well-explained?
    - Accuracy: Are there any errors?
    
    Provide an improved version that addresses these issues.`,
  outputKey: "current_solution", // Updates solution each iteration
});

// Agent that evaluates quality
const qualityEvaluator = new LlmAgent({
  name: "quality_evaluator",
  model: "gemini-2.5-flash",
  instruction: `Evaluate the solution: {current_solution} against the problem: {problem_statement}
    
    Rate on a scale of 1-10 considering:
    - Completeness (fully addresses problem)
    - Accuracy (correct and reliable)
    - Clarity (well-explained)
    - Efficiency (optimal approach)
    
    Provide only the numeric score (1-10).`,
  outputKey: "quality_score", // Saves evaluation score
});

// Custom termination agent
class QualityGate extends BaseAgent {
  constructor() {
    super({
      name: "quality_gate",
      description: "Determines when quality standards are met",
    });
  }

  protected async *runAsyncImpl(ctx: InvocationContext) {
    const score = parseInt(ctx.session.state.get("quality_score", "0"), 10);
    const iteration = ctx.session.state.get("iteration_count", 0) + 1;

    // Track iterations
    ctx.session.state.set("iteration_count", iteration);

    // Stop if quality is high enough (score >= 8)
    const qualityMet = score >= 8;

    yield new Event({
      author: this.name,
      content: {
        parts: [
          {
            text: `Iteration ${iteration}: Quality score ${score}/10. ${
              qualityMet
                ? "Quality target achieved!"
                : "Continuing refinement..."
            }`,
          },
        ],
      },
      actions: new EventActions({ escalate: qualityMet }),
    });
  }
}

// Iterative refinement workflow
const iterativeImprovement = new LoopAgent({
  name: "iterative_improvement",
  description: "Iteratively improve solution until quality standards are met",
  maxIterations: 5, // Prevent infinite loops
  subAgents: [solutionImprover, qualityEvaluator, new QualityGate()],
});

// Usage with AgentBuilder
const { runner } = await AgentBuilder.withAgent(iterativeImprovement).build();

// Execution pattern:
// Iteration 1: solutionImprover → qualityEvaluator → qualityGate (continue if score < 8)
// Iteration 2: solutionImprover → qualityEvaluator → qualityGate (continue if score < 8)
// ... continues until quality_score >= 8 or maxIterations reached

import { createTool, LlmAgent, SequentialAgent } from "@iqai/adk";
import { z } from "zod";

// Custom tool for human approval integration
const humanApprovalTool = createTool({
  name: "request_human_approval",
  description: "Request human approval for important decisions",
  schema: z.object({
    decision: z.string().describe("The decision requiring approval"),
    reasoning: z.string().describe("Why this decision is being made"),
    urgency: z.enum(["low", "medium", "high"]).describe("Priority level"),
  }),
  fn: async ({ decision, reasoning, urgency }) => {
    // This would integrate with your approval system
    // Examples: Slack bot, email notification, web dashboard

    console.log(`🔔 Human approval requested:`);
    console.log(`Decision: ${decision}`);
    console.log(`Reasoning: ${reasoning}`);
    console.log(`Urgency: ${urgency}`);

    // Simulate human approval (in production, this would wait for real input)
    const approved = Math.random() > 0.3; // 70% approval rate for demo

    return {
      approved,
      approver: "human.reviewer@company.com",
      feedback: approved ? "Looks good to proceed" : "Needs more analysis",
      timestamp: new Date().toISOString(),
    };
  },
});

// Workflow with human approval checkpoint
const proposalAnalyzer = new LlmAgent({
  name: "proposal_analyzer",
  model: "gemini-2.5-flash",
  instruction:
    "Analyze the proposal for risks, benefits, and feasibility. Provide a comprehensive assessment.",
  outputKey: "analysis_report",
});

const approvalGate = new LlmAgent({
  name: "approval_gate",
  model: "gemini-2.5-flash",
  instruction: `Based on the analysis: {analysis_report}, request human approval for proceeding.
    
    Use the request_human_approval tool with:
    - Clear description of what needs approval
    - Summary of key findings and reasoning
    - Appropriate urgency level`,
  tools: [humanApprovalTool],
  outputKey: "approval_decision",
});

const actionExecutor = new LlmAgent({
  name: "action_executor",
  model: "gemini-2.5-flash",
  instruction: `Check the approval decision: {approval_decision}
    
    If approved: Proceed with implementation and log the action
    If rejected: Document the rejection and suggest next steps`,
  outputKey: "execution_result",
});

// Complete human-in-the-loop workflow
const approvalWorkflow = new SequentialAgent({
  name: "approval_workflow",
  description: "Automated workflow with human approval checkpoints",
  subAgents: [proposalAnalyzer, approvalGate, actionExecutor],
});

// Execution flow:
// 1. proposalAnalyzer → creates analysis_report
// 2. approvalGate → requests human approval (workflow pauses)
// 3. Human reviews and responds via external system
// 4. actionExecutor → proceeds based on approval decision