foliko 1.0.53 → 1.0.55

package/plugins/ambient-agent-plugin.js

@@ -0,0 +1,1134 @@
+/**
+ * Ambient Agent Plugin
+ * Continuous background agent that monitors events and takes proactive actions
+ */
+
+const { Plugin } = require('../src/core/plugin-base')
+const { z } = require('zod')
+const fs = require('fs')
+const path = require('path')
+
+// Goal lifecycle states
+const GoalState = {
+  PENDING: 'pending',
+  ACTIVE: 'active',
+  COMPLETED: 'completed',
+  FAILED: 'failed'
+}
+
+// Generate unique IDs
+function generateId() {
+  if (require('crypto').randomUUID) {
+    return require('crypto').randomUUID()
+  }
+  return `goal_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+}
+
+// ============================================================================
+// StateStore - Persists goals and memories to .agent/data/ambient/*.json
+// ============================================================================
+class StateStore {
+  constructor(persistencePath) {
+    this._persistencePath = persistencePath
+    this._ensureDir()
+  }
+
+  _ensureDir() {
+    if (!fs.existsSync(this._persistencePath)) {
+      fs.mkdirSync(this._persistencePath, { recursive: true })
+    }
+  }
+
+  _getGoalsPath() {
+    return path.join(this._persistencePath, 'goals.json')
+  }
+
+  _getMemoriesPath() {
+    return path.join(this._persistencePath, 'memories.json')
+  }
+
+  saveGoals(goals) {
+    try {
+      fs.writeFileSync(this._getGoalsPath(), JSON.stringify(goals, null, 2))
+    } catch (err) {
+      console.error('[Ambient] Failed to save goals:', err.message)
+    }
+  }
+
+  loadGoals() {
+    try {
+      const filePath = this._getGoalsPath()
+      if (fs.existsSync(filePath)) {
+        const data = fs.readFileSync(filePath, 'utf-8')
+        return JSON.parse(data)
+      }
+    } catch (err) {
+      console.error('[Ambient] Failed to load goals:', err.message)
+    }
+    return []
+  }
+
+  saveMemories(memories) {
+    try {
+      fs.writeFileSync(this._getMemoriesPath(), JSON.stringify(memories, null, 2))
+    } catch (err) {
+      console.error('[Ambient] Failed to save memories:', err.message)
+    }
+  }
+
+  loadMemories() {
+    try {
+      const filePath = this._getMemoriesPath()
+      if (fs.existsSync(filePath)) {
+        const data = fs.readFileSync(filePath, 'utf-8')
+        return JSON.parse(data)
+      }
+    } catch (err) {
+      console.error('[Ambient] Failed to load memories:', err.message)
+    }
+    return []
+  }
+}
+
+// ============================================================================
+// GoalManager - Manages goals with lifecycle states
+// ============================================================================
+class GoalManager {
+  constructor(stateStore) {
+    this._goals = new Map()
+    this._stateStore = stateStore
+    this._loadGoals()
+  }
+
+  _loadGoals() {
+    const savedGoals = this._stateStore.loadGoals()
+    for (const goal of savedGoals) {
+      this._goals.set(goal.id, goal)
+    }
+  }
+
+  _persist() {
+    const goalsArray = Array.from(this._goals.values())
+    this._stateStore.saveGoals(goalsArray)
+  }
+
+  createGoal(goalData) {
+    const goal = {
+      id: generateId(),
+      title: goalData.title || 'Untitled Goal',
+      description: goalData.description || '',
+      priority: goalData.priority || 5,
+      state: GoalState.PENDING,
+      actions: goalData.actions || [],
+      conditions: goalData.conditions || {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      activatedAt: null,
+      completedAt: null,
+      failedAt: null,
+      attempts: 0,
+      maxAttempts: goalData.maxAttempts || 10,
+      consecutiveSameActions: 0,
+      lastActionId: null,
+      eventsReceived: []
+    }
+    this._goals.set(goal.id, goal)
+    this._persist()
+    return goal
+  }
+
+  getGoal(id) {
+    return this._goals.get(id)
+  }
+
+  getAllGoals() {
+    return Array.from(this._goals.values())
+  }
+
+  getActiveGoals() {
+    return Array.from(this._goals.values()).filter(g => g.state === GoalState.ACTIVE)
+  }
+
+  getPendingGoals() {
+    return Array.from(this._goals.values()).filter(g => g.state === GoalState.PENDING)
+  }
+
+  updateGoal(id, updates) {
+    const goal = this._goals.get(id)
+    if (!goal) return null
+    Object.assign(goal, updates, { updatedAt: new Date() })
+    this._persist()
+    return goal
+  }
+
+  activateGoal(id) {
+    const goal = this._goals.get(id)
+    if (!goal || goal.state !== GoalState.PENDING) return null
+    goal.state = GoalState.ACTIVE
+    goal.activatedAt = new Date()
+    goal.updatedAt = new Date()
+    this._persist()
+    return goal
+  }
+
+  completeGoal(id) {
+    const goal = this._goals.get(id)
+    if (!goal) return null
+    goal.state = GoalState.COMPLETED
+    goal.completedAt = new Date()
+    goal.updatedAt = new Date()
+    this._persist()
+    return goal
+  }
+
+  failGoal(id, reason) {
+    const goal = this._goals.get(id)
+    if (!goal) return null
+    goal.state = GoalState.FAILED
+    goal.failedAt = new Date()
+    goal.failureReason = reason
+    goal.updatedAt = new Date()
+    this._persist()
+    return goal
+  }
+
+  deleteGoal(id) {
+    const deleted = this._goals.delete(id)
+    if (deleted) this._persist()
+    return deleted
+  }
+
+  addEventToGoal(goalId, event) {
+    const goal = this._goals.get(goalId)
+    if (!goal) return
+    goal.eventsReceived.push({
+      event: event.type,  // "email:received"
+      data: event.data,   // the actual event data (contains email object)
+      timestamp: new Date()
+    })
+    this._persist()
+  }
+}
+
+// ============================================================================
+// EventWatcher - Subscribes to framework events, filters relevant ones
+// ============================================================================
+class EventWatcher {
+  constructor(goalManager, framework) {
+    this._goalManager = goalManager
+    this._framework = framework
+    this._handlers = []
+    this._relevantEvents = new Set([
+      'tool:result',
+      'scheduler:reminder',
+      'agent:message',
+      'think:thought_completed',
+      'scheduler:task_completed',
+      'scheduler:task_failed',
+      'email:received',
+      'webhook:received'
+    ])
+  }
+
+  start() {
+    this._handlers.push(
+      this._framework.on('tool:result', (data) => this._handleEvent('tool:result', data)),
+      this._framework.on('scheduler:reminder', (data) => this._handleEvent('scheduler:reminder', data)),
+      this._framework.on('agent:message', (data) => this._handleEvent('agent:message', data)),
+      this._framework.on('think:thought_completed', (data) => this._handleEvent('think:thought_completed', data)),
+      this._framework.on('scheduler:task_completed', (data) => this._handleEvent('scheduler:task_completed', data)),
+      this._framework.on('scheduler:task_failed', (data) => this._handleEvent('scheduler:task_failed', data)),
+      this._framework.on('email:received', (data) => this._handleEvent('email:received', data)),
+      this._framework.on('webhook:received', (data) => this._handleEvent('webhook:received', data))
+    )
+  }
+
+  stop() {
+    for (const handler of this._handlers) {
+      handler()
+    }
+    this._handlers = []
+  }
+
+  _handleEvent(type, data) {
+    // Check active goals
+    const activeGoals = this._goalManager.getActiveGoals()
+    for (const goal of activeGoals) {
+      if (this._isRelevantToGoal(goal, type, data)) {
+        this._goalManager.addEventToGoal(goal.id, { type, data })
+      }
+    }
+
+    // Also check pending goals - activate if conditions match
+    const pendingGoals = this._goalManager.getPendingGoals()
+    for (const goal of pendingGoals) {
+      if (this._isRelevantToGoal(goal, type, data)) {
+        this._goalManager.activateGoal(goal.id)
+        this._goalManager.addEventToGoal(goal.id, { type, data })
+      }
+    }
+  }
+
+  _isRelevantToGoal(goal, eventType, data) {
+    // Check explicit event types in conditions
+    if (goal.conditions && goal.conditions.events) {
+      const allowedEvents = Array.isArray(goal.conditions.events)
+        ? goal.conditions.events
+        : [goal.conditions.events]
+      if (!allowedEvents.includes(eventType)) {
+        return false
+      }
+    }
+    // Check tool name filters
+    if (goal.conditions && goal.conditions.toolNames) {
+      const toolNames = Array.isArray(goal.conditions.toolNames)
+        ? goal.conditions.toolNames
+        : [goal.conditions.toolNames]
+      if (data && data.toolName && !toolNames.includes(data.toolName)) {
+        return false
+      }
+    }
+    return true
+  }
+}
+
+// ============================================================================
+// Reflector - Evaluates action outcomes, updates goal states
+// ============================================================================
+class Reflector {
+  constructor(goalManager) {
+    this._goalManager = goalManager
+  }
+
+  evaluateOutcome(goal, actionResult) {
+    if (!goal) return null
+
+    // Check for errors
+    if (actionResult && actionResult.error) {
+      // Increment attempts but don't immediately fail
+      goal.attempts++
+      return {
+        shouldContinue: goal.attempts < goal.maxAttempts,
+        actionTaken: false
+      }
+    }
+
+    // Check for successful completion
+    if (actionResult && actionResult.success === true) {
+      goal.attempts++
+
+      // Check if goal is complete
+      if (goal.actions.length === 0 || goal.attempts >= goal.maxAttempts) {
+        return { shouldContinue: false, goalComplete: true }
+      }
+
+      return { shouldContinue: true, actionTaken: true }
+    }
+
+    // Tool executed without error - consider it successful
+    goal.attempts++
+
+    // Check if goal is complete (no more actions)
+    if (goal.actions.length === 0 || goal.attempts >= goal.maxAttempts) {
+      return { shouldContinue: false, goalComplete: true }
+    }
+
+    return { shouldContinue: true, actionTaken: true }
+  }
+
+  checkLoopDetection(goal, actionId) {
+    // If same action repeats 3x consecutively, fail goal
+    if (goal.lastActionId === actionId) {
+      goal.consecutiveSameActions++
+      if (goal.consecutiveSameActions >= 3) {
+        this._goalManager.failGoal(goal.id, 'Loop detected: same action repeated 3 times')
+        return true
+      }
+    } else {
+      goal.consecutiveSameActions = 1
+      goal.lastActionId = actionId
+    }
+    return false
+  }
+}
+
+// ============================================================================
+// ExplorerLoop - Main autonomous loop that decides and executes actions
+// ============================================================================
+class ExplorerLoop {
+  constructor(goalManager, reflector, framework, config) {
+    this._goalManager = goalManager
+    this._reflector = reflector
+    this._framework = framework
+    this._config = config
+    this._running = false
+    this._timer = null
+    this._lastActionTime = 0
+    this._tickCount = 0
+    this._recentActivities = []
+  }
+
+  start() {
+    if (this._running) return
+    this._running = true
+    this._scheduleNext()
+  }
+
+  stop() {
+    this._running = false
+    if (this._timer) {
+      clearTimeout(this._timer)
+      this._timer = null
+    }
+  }
+
+  pause() {
+    this._running = false
+    if (this._timer) {
+      clearTimeout(this._timer)
+      this._timer = null
+    }
+  }
+
+  resume() {
+    if (!this._running) {
+      this._running = true
+      this._scheduleNext()
+    }
+  }
+
+  isRunning() {
+    return this._running
+  }
+
+  getStatus() {
+    return {
+      running: this._running,
+      tickCount: this._tickCount,
+      lastTick: this._lastActionTime ? new Date(this._lastActionTime) : null,
+      recentActivities: this._recentActivities.slice(-10),
+      activeGoals: this._goalManager.getActiveGoals().length,
+      pendingGoals: this._goalManager.getPendingGoals().length
+    }
+  }
+
+  _scheduleNext() {
+    if (!this._running) return
+    this._timer = setTimeout(() => this._tick(), this._config.tickInterval)
+  }
+
+  async _tick() {
+    if (!this._running) return
+
+    // Skip tick if in nested execution context
+    try {
+      if (this._framework.getExecutionContext) {
+        const ctx = this._framework.getExecutionContext()
+        if (ctx && ctx.id) {
+          // Skip this tick, reschedule
+          this._scheduleNext()
+          return
+        }
+      }
+    } catch (e) {
+      // getExecutionContext might not exist, continue
+    }
+
+    this._tickCount++
+
+    try {
+      await this._processGoals()
+    } catch (err) {
+      console.error('[Ambient] Tick error:', err.message)
+      this._addActivity('error', { message: err.message })
+    }
+
+    // Schedule next tick
+    this._scheduleNext()
+  }
+
+  async _processGoals() {
+    const activeGoals = this._goalManager.getActiveGoals()
+
+    for (const goal of activeGoals) {
+      // Check cooldown
+      if (Date.now() - this._lastActionTime < this._config.cooldownPeriod) {
+        continue
+      }
+
+      // Check if goal has unprocessed events
+      const hasNewEvents = goal.eventsReceived && goal.eventsReceived.length > 0
+
+      // Check if goal is event-driven
+      const isEventDriven = goal.conditions && goal.conditions.events && goal.conditions.events.length > 0
+
+      // Get next action
+      if (goal.actions && goal.actions.length > 0) {
+        const action = goal.actions[0] // Simple: take first action
+
+        // For event-driven goals, only execute if there are new events
+        if (isEventDriven && !hasNewEvents) {
+          // Skip execution but don't fail - just wait for events
+          continue
+        }
+
+        // Loop detection (only for non-event-driven actions)
+        if (!hasNewEvents && this._reflector.checkLoopDetection(goal, action.id)) {
+          this._addActivity('goal_failed', { goalId: goal.id, reason: 'Loop detected' })
+          continue
+        }
+
+        // Execute action
+        const result = await this._executeAction(action, hasNewEvents ? goal.eventsReceived[0] : null)
+
+        // Evaluate outcome
+        const outcome = this._reflector.evaluateOutcome(goal, result)
+
+        if (outcome.goalComplete) {
+          // For event-driven goals, don't complete - reset and wait for more events
+          if (isEventDriven) {
+            goal.eventsReceived = []
+            goal.attempts = 0
+            this._goalManager.updateGoal(goal.id, { eventsReceived: [], attempts: 0 })
+            this._addActivity('goal_reset', { goalId: goal.id, reason: 'Event-driven, waiting for more events' })
+          } else {
+            this._goalManager.completeGoal(goal.id)
+            this._addActivity('goal_completed', { goalId: goal.id, attempts: goal.attempts })
+          }
+        } else if (!outcome.shouldContinue) {
+          this._goalManager.failGoal(goal.id, 'Max attempts reached')
+          this._addActivity('goal_failed', { goalId: goal.id, reason: 'Max attempts' })
+        } else if (outcome.actionTaken) {
+          // For event-driven goals, keep actions in queue for continuous processing
+          // Only shift if this is a one-time goal (no pending events)
+          if (!isEventDriven) {
+            goal.actions.shift()
+          }
+          this._addActivity('action_executed', { goalId: goal.id, action: action.id, hasEvents: hasNewEvents })
+          // Update last action time for cooldown
+          this._lastActionTime = Date.now()
+        }
+
+        // Clear processed events after action is taken
+        if (hasNewEvents) {
+          goal.eventsReceived = []
+          this._goalManager.updateGoal(goal.id, { eventsReceived: [] })
+        }
+      }
+    }
+
+    // Activate pending goals that have matching events
+    const pendingGoals = this._goalManager.getPendingGoals()
+    for (const goal of pendingGoals) {
+      // Auto-activate goals without conditions, or with satisfied conditions
+      if (!goal.conditions || Object.keys(goal.conditions).length === 0) {
+        this._goalManager.activateGoal(goal.id)
+        this._addActivity('goal_activated', { goalId: goal.id })
+      }
+    }
+  }
+
+  async _executeAction(action, eventData = null) {
+    if (!this._framework) {
+      return { success: false, error: 'Framework not available' }
+    }
+
+    try {
+      if (action.type === 'tool') {
+        // Use getTools() which returns array, find by name
+        const tools = this._framework.getTools()
+        const tool = tools.find(t => t.name === action.name)
+        if (!tool) {
+          return { success: false, error: `Tool not found: ${action.name}` }
+        }
+        // Merge event data into args if available
+        const args = { ...action.args }
+        if (eventData) {
+          args._event = eventData
+        }
+        const result = await tool.execute(args, this._framework)
+        return result
+      } else if (action.type === 'message') {
+        const agent = this._getActiveAgent()
+        if (!agent) {
+          return { success: false, error: 'No active agent' }
+        }
+        // Include event context in message if available
+        let content = action.content
+        if (eventData) {
+          content = `${action.content}\n\n[Event Context: ${JSON.stringify(eventData)}]`
+        }
+        const result = await agent.pushMessage(content)
+        return { success: true, result }
+      } else if (action.type === 'think') {
+        // Trigger thinking
+        const thinkPlugin = this._framework.pluginManager.get('think')
+        if (thinkPlugin) {
+          // Include event context in topic if available
+          let topic = action.topic || 'Ambient agent reflection'
+          if (eventData) {
+            topic = `${topic}\n\n[Event Context: ${JSON.stringify(eventData)}]`
+          }
+          const result = await thinkPlugin._triggerThinking({
+            topic,
+            mode: action.mode || 'reflect',
+            depth: action.depth || 2
+          })
+          return result
+        }
+        return { success: false, error: 'Think plugin not available' }
+      }
+
+      return { success: false, error: `Unknown action type: ${action.type}` }
+    } catch (err) {
+      return { success: false, error: err.message }
+    }
+  }
+
+  _getActiveAgent() {
+    if (this._framework._mainAgent) {
+      return this._framework._mainAgent
+    }
+    const agents = this._framework._agents || []
+    return agents.length > 0 ? agents[agents.length - 1] : null
+  }
+
+  _addActivity(type, data) {
+    this._recentActivities.push({
+      type,
+      data,
+      timestamp: new Date()
+    })
+    // Keep only last 50 activities
+    if (this._recentActivities.length > 50) {
+      this._recentActivities = this._recentActivities.slice(-50)
+    }
+  }
+}
+
+// ============================================================================
+// Main Plugin Class
+// ============================================================================
+class AmbientAgentPlugin extends Plugin {
+  constructor(config = {}) {
+    super()
+    this.name = 'ambient'
+    this.version = '1.0.0'
+    this.description = `Ambient Agent - 持续运行的后台 Agent，用于主动监控和自动操作
+支持监听的事件：
+- email:received - 收到新邮件（需配合 email_watch 启动监控）
+- webhook:received - 收到 webhook 请求
+- scheduler:reminder - 定时提醒触发
+- scheduler:task_completed - 定时任务完成
+- scheduler:task_failed - 定时任务失败
+- think:thought_completed - 思考完成
+- tool:result - 工具执行结果
+- agent:message - Agent 消息`
+    this.priority = 18
+    this.system = true
+
+    this.config = {
+      enabled: config.enabled !== false,
+      tickInterval: config.tickInterval || 5000,
+      cooldownPeriod: config.cooldownPeriod || 3000,
+      persistencePath: config.persistencePath || '.agent/data/ambient',
+      defaultGoals: config.defaultGoals || []
+    }
+
+    this._framework = null
+    this._stateStore = null
+    this._goalManager = null
+    this._eventWatcher = null
+    this._reflector = null
+    this._explorerLoop = null
+    this._memories = []
+  }
+
+  install(framework) {
+    this._framework = framework
+    this._stateStore = new StateStore(this.config.persistencePath)
+    this._goalManager = new GoalManager(this._stateStore)
+    this._reflector = new Reflector(this._goalManager)
+
+    // Load persisted memories
+    this._memories = this._stateStore.loadMemories()
+
+    return this
+  }
+
+  start(framework) {
+    if (!this.config.enabled) {
+      return this
+    }
+
+    // Create default goals if none exist
+    if (this._goalManager.getAllGoals().length === 0 && this.config.defaultGoals.length > 0) {
+      for (const goalDef of this.config.defaultGoals) {
+        this._goalManager.createGoal(goalDef)
+      }
+    }
+
+    // Start event watcher
+    this._eventWatcher = new EventWatcher(this._goalManager, this._framework)
+    this._eventWatcher.start()
+
+    // Start explorer loop
+    this._explorerLoop = new ExplorerLoop(this._goalManager, this._reflector, this._framework, {
+      tickInterval: this.config.tickInterval,
+      cooldownPeriod: this.config.cooldownPeriod
+    })
+    this._explorerLoop.start()
+
+    // Register tools
+    this._registerTools(framework)
+
+    return this
+  }
+
+  _registerTools(framework) {
+    // ambient_goals - List/create/update/delete goals
+    framework.registerTool({
+      name: 'ambient_goals',
+      description: 'Manage ambient agent goals - list, create, update, delete goals',
+      inputSchema: z.object({
+        action: z.enum(['list', 'create', 'update', 'delete', 'activate']).describe('Operation to perform'),
+        goalId: z.string().optional().describe('Goal ID (required for update/delete/activate)'),
+        title: z.string().optional().describe('Goal title (for create/update)'),
+        description: z.string().optional().describe('Goal description (for create/update)'),
+        priority: z.number().optional().describe('Priority 1-10, higher = more important (for create/update)'),
+        actions: z.array(z.object({
+          id: z.string().optional().describe('Action identifier'),
+          type: z.enum(['tool', 'message', 'think']).describe('Action type'),
+          name: z.string().optional().describe('Tool name (for tool type)'),
+          args: z.record(z.any()).optional().describe('Tool arguments (for tool type)'),
+          content: z.string().optional().describe('Message content (for message type)'),
+          topic: z.string().optional().describe('Think topic (for think type)'),
+          mode: z.enum(['reflect', 'brainstorm', 'analyze', 'plan']).optional().describe('Think mode (for think type)')
+        })).optional().describe('Actions to execute (for create/update)'),
+        conditions: z.object({
+          events: z.union([z.string(), z.array(z.string())]).optional().describe('Event types to listen for'),
+          toolNames: z.union([z.string(), z.array(z.string())]).optional().describe('Filter by tool names')
+        }).optional().describe('Activation conditions (for create/update)')
+      }),
+      execute: async (args) => {
+        return this._handleGoalsTool(args)
+      }
+    })
+
+    // ambient_status - Get current loop state
+    framework.registerTool({
+      name: 'ambient_status',
+      description: 'Get current ambient agent status - loop state, active goals, recent activity',
+      inputSchema: z.object({}),
+      execute: async () => {
+        return this._handleStatusTool()
+      }
+    })
+
+    // ambient_think - Trigger proactive LLM thinking
+    framework.registerTool({
+      name: 'ambient_think',
+      description: 'Trigger proactive LLM thinking for a goal - modes: reflect, brainstorm, plan, analyze',
+      inputSchema: z.object({
+        goalId: z.string().optional().describe('Goal ID to think about'),
+        mode: z.enum(['reflect', 'brainstorm', 'plan', 'analyze']).describe('Thinking mode'),
+        topic: z.string().optional().describe('Topic to think about'),
+        depth: z.number().optional().describe('Thinking depth 1-5')
+      }),
+      execute: async (args) => {
+        return this._handleThinkTool(args)
+      }
+    })
+
+    // ambient_remember - Store/retrieve/search persistent memories
+    framework.registerTool({
+      name: 'ambient_remember',
+      description: 'Store or retrieve persistent memories for the ambient agent',
+      inputSchema: z.object({
+        action: z.enum(['store', 'retrieve', 'search']).describe('Action: store a memory, retrieve recent, or search'),
+        content: z.string().optional().describe('Memory content (for store)'),
+        key: z.string().optional().describe('Memory key (for store/retrieve)'),
+        query: z.string().optional().describe('Search query (for search)'),
+        limit: z.number().optional().describe('Max results (for retrieve/search)')
+      }),
+      execute: async (args) => {
+        return this._handleRememberTool(args)
+      }
+    })
+
+    // ambient_control - Pause/resume/adjust the explorer loop
+    framework.registerTool({
+      name: 'ambient_control',
+      description: 'Control the ambient agent explorer loop - pause, resume, or adjust settings',
+      inputSchema: z.object({
+        action: z.enum(['pause', 'resume', 'status', 'adjust']).describe('Control action'),
+        tickInterval: z.number().optional().describe('New tick interval in ms (for adjust)'),
+        cooldownPeriod: z.number().optional().describe('New cooldown period in ms (for adjust)')
+      }),
+      execute: async (args) => {
+        return this._handleControlTool(args)
+      }
+    })
+  }
+
+  _handleGoalsTool(args) {
+    const { action, goalId, title, description, priority, actions, conditions } = args
+
+    switch (action) {
+      case 'list': {
+        const allGoals = this._goalManager.getAllGoals()
+        return {
+          success: true,
+          goals: allGoals.map(g => ({
+            id: g.id,
+            title: g.title,
+            state: g.state,
+            priority: g.priority,
+            actionsCount: g.actions ? g.actions.length : 0,
+            attempts: g.attempts,
+            createdAt: g.createdAt,
+            activatedAt: g.activatedAt,
+            completedAt: g.completedAt,
+            failedAt: g.failedAt
+          })),
+          total: allGoals.length,
+          active: this._goalManager.getActiveGoals().length,
+          pending: this._goalManager.getPendingGoals().length
+        }
+      }
+
+      case 'create': {
+        if (!title) {
+          return { success: false, error: 'Title is required for creating a goal' }
+        }
+        const goal = this._goalManager.createGoal({ title, description, priority, actions, conditions })
+        return { success: true, goal }
+      }
+
+      case 'update': {
+        if (!goalId) {
+          return { success: false, error: 'Goal ID is required for update' }
+        }
+        const updates = {}
+        if (title !== undefined) updates.title = title
+        if (description !== undefined) updates.description = description
+        if (priority !== undefined) updates.priority = priority
+        if (actions !== undefined) updates.actions = actions
+        if (conditions !== undefined) updates.conditions = conditions
+        const goal = this._goalManager.updateGoal(goalId, updates)
+        return goal ? { success: true, goal } : { success: false, error: 'Goal not found' }
+      }
+
+      case 'delete': {
+        if (!goalId) {
+          return { success: false, error: 'Goal ID is required for delete' }
+        }
+        const deleted = this._goalManager.deleteGoal(goalId)
+        return { success: deleted }
+      }
+
+      case 'activate': {
+        if (!goalId) {
+          return { success: false, error: 'Goal ID is required for activate' }
+        }
+        const goal = this._goalManager.activateGoal(goalId)
+        return goal ? { success: true, goal } : { success: false, error: 'Goal not found or not pending' }
+      }
+
+      default:
+        return { success: false, error: `Unknown action: ${action}` }
+    }
+  }
+
+  _handleStatusTool() {
+    if (!this._explorerLoop) {
+      return { success: false, error: 'Explorer loop not initialized' }
+    }
+
+    const loopStatus = this._explorerLoop.getStatus()
+    const activeGoals = this._goalManager.getActiveGoals().map(g => ({
+      id: g.id,
+      title: g.title,
+      priority: g.priority,
+      attempts: g.attempts,
+      lastActionId: g.lastActionId
+    }))
+    const pendingGoals = this._goalManager.getPendingGoals().map(g => ({
+      id: g.id,
+      title: g.title,
+      priority: g.priority
+    }))
+
+    return {
+      success: true,
+      loop: {
+        running: loopStatus.running,
+        tickCount: loopStatus.tickCount,
+        lastTick: loopStatus.lastTick,
+        tickInterval: this.config.tickInterval,
+        cooldownPeriod: this.config.cooldownPeriod
+      },
+      activeGoals,
+      pendingGoals,
+      recentActivities: loopStatus.recentActivities
+    }
+  }
+
+  async _handleThinkTool(args) {
+    const { goalId, mode, topic, depth } = args
+
+    // Get active agent
+    const agent = this._getActiveAgent()
+    if (!agent) {
+      return { success: false, error: 'No active agent available' }
+    }
+
+    // Build thinking prompt
+    let prompt = ''
+    if (goalId) {
+      const goal = this._goalManager.getGoal(goalId)
+      if (goal) {
+        prompt = this._buildGoalThinkPrompt(goal, mode, topic)
+      } else {
+        return { success: false, error: 'Goal not found' }
+      }
+    } else {
+      prompt = this._buildFreeThinkPrompt(mode, topic)
+    }
+
+    // Wait for agent to be available if busy
+    let attempts = 0
+    const maxWaitAttempts = 10
+    const waitInterval = 500
+
+    while (agent._status === 'busy' && attempts < maxWaitAttempts) {
+      await new Promise(resolve => setTimeout(resolve, waitInterval))
+      attempts++
+    }
+
+    if (agent._status === 'busy') {
+      return {
+        success: false,
+        error: 'Agent is busy and could not become available in time. Please try again later.',
+        queued: true
+      }
+    }
+
+    // Execute thinking via agent
+    const thinkPlugin = this._framework.pluginManager.get('think')
+    if (thinkPlugin) {
+      const result = await thinkPlugin._triggerThinking({ topic: prompt, mode, depth: depth || 2 })
+      // If the result indicates busy, return a more helpful message
+      if (result && result.message && result.message.includes && result.message.includes('busy')) {
+        return {
+          success: true,
+          queued: true,
+          message: 'Thinking request was queued and will be processed when the agent is free.'
+        }
+      }
+      return result
+    }
+
+    // Fallback: push message directly
+    return agent.pushMessage(prompt).then(result => ({
+      success: true,
+      result: typeof result === 'string' ? result : JSON.stringify(result)
+    })).catch(err => ({
+      success: false,
+      error: err.message
+    }))
+  }
+
+  _buildGoalThinkPrompt(goal, mode, topic) {
+    const modePrompts = {
+      reflect: `As the Ambient Agent, reflect on the current goal:
+Title: ${goal.title}
+Description: ${goal.description || 'None'}
+Priority: ${goal.priority}
+State: ${goal.state}
+Attempts: ${goal.attempts}
+
+${topic ? `Additional focus: ${topic}` : ''}
+
+Reflect on:
+1. Is this goal still relevant and achievable?
+2. Are the actions appropriate for the goal?
+3. What could be improved?`,
+      brainstorm: `Brainstorm new approaches for the ambient agent goal:
+Title: ${goal.title}
+${goal.description ? `Description: ${goal.description}` : ''}
+Actions planned: ${goal.actions ? goal.actions.length : 0}
+
+${topic ? `Focus: ${topic}` : 'Generate new ideas for how this goal could be pursued more effectively.'}`,
+      plan: `Create a refined plan for the ambient agent goal:
+Title: ${goal.title}
+${goal.description ? `Description: ${goal.description}` : ''}
+${topic ? `Additional context: ${topic}` : ''}
+
+Develop a clear, actionable plan.`,
+      analyze: `Analyze the ambient agent goal:
+Title: ${goal.title}
+State: ${goal.state}
+Priority: ${goal.priority}
+Actions: ${goal.actions ? JSON.stringify(goal.actions) : 'None'}
+
+${topic ? `Analysis focus: ${topic}` : 'What are the strengths, weaknesses, and potential issues with this goal?'}`
+    }
+    return modePrompts[mode] || modePrompts.reflect
+  }
+
+  _buildFreeThinkPrompt(mode, topic) {
+    const modePrompts = {
+      reflect: `Ambient Agent reflection: ${topic || 'Consider the current state of the system and goals. What could be improved?'}`,
+      brainstorm: `Ambient Agent brainstorming: ${topic || 'Generate creative ideas for new goals or approaches.'}`,
+      plan: `Ambient Agent planning: ${topic || 'Develop plans for pending objectives.'}`,
+      analyze: `Ambient Agent analysis: ${topic || 'Analyze current goals and their progress.'}`
+    }
+    return modePrompts[mode] || modePrompts.reflect
+  }
+
+  _handleRememberTool(args) {
+    const { action, content, key, query, limit } = args
+    const maxResults = limit || 10
+
+    switch (action) {
+      case 'store': {
+        if (!content) {
+          return { success: false, error: 'Content is required for store' }
+        }
+        const memoryKey = key || `memory_${Date.now()}`
+        const memory = {
+          key: memoryKey,
+          content,
+          timestamp: new Date()
+        }
+        this._memories.push(memory)
+        this._stateStore.saveMemories(this._memories)
+        return { success: true, memory }
+      }
+
+      case 'retrieve': {
+        const memories = this._memories.slice(-maxResults).reverse()
+        return {
+          success: true,
+          memories,
+          total: this._memories.length
+        }
+      }
+
+      case 'search': {
+        if (!query) {
+          return { success: false, error: 'Query is required for search' }
+        }
+        const queryLower = query.toLowerCase()
+        const results = this._memories
+          .filter(m => m.content.toLowerCase().includes(queryLower))
+          .slice(-maxResults)
+          .reverse()
+        return {
+          success: true,
+          results,
+          total: results.length
+        }
+      }
+
+      default:
+        return { success: false, error: `Unknown action: ${action}` }
+    }
+  }
+
+  _handleControlTool(args) {
+    const { action, tickInterval, cooldownPeriod } = args
+
+    switch (action) {
+      case 'pause': {
+        if (!this._explorerLoop) {
+          return { success: false, error: 'Explorer loop not initialized' }
+        }
+        this._explorerLoop.pause()
+        return { success: true, message: 'Explorer loop paused' }
+      }
+
+      case 'resume': {
+        if (!this._explorerLoop) {
+          return { success: false, error: 'Explorer loop not initialized' }
+        }
+        this._explorerLoop.resume()
+        return { success: true, message: 'Explorer loop resumed' }
+      }
+
+      case 'status': {
+        if (!this._explorerLoop) {
+          return { success: false, error: 'Explorer loop not initialized' }
+        }
+        const status = this._explorerLoop.getStatus()
+        return {
+          success: true,
+          running: status.running,
+          tickCount: status.tickCount,
+          lastTick: status.lastTick,
+          tickInterval: this.config.tickInterval,
+          cooldownPeriod: this.config.cooldownPeriod
+        }
+      }
+
+      case 'adjust': {
+        if (tickInterval) {
+          this.config.tickInterval = tickInterval
+        }
+        if (cooldownPeriod) {
+          this.config.cooldownPeriod = cooldownPeriod
+        }
+        return {
+          success: true,
+          message: 'Settings adjusted',
+          tickInterval: this.config.tickInterval,
+          cooldownPeriod: this.config.cooldownPeriod
+        }
+      }
+
+      default:
+        return { success: false, error: `Unknown action: ${action}` }
+    }
+  }
+
+  _getActiveAgent() {
+    if (this._framework._mainAgent) {
+      return this._framework._mainAgent
+    }
+    const agents = this._framework._agents || []
+    return agents.length > 0 ? agents[agents.length - 1] : null
+  }
+
+  reload(framework) {
+    this._framework = framework
+    if (this._explorerLoop && this._explorerLoop.isRunning()) {
+      // Restart with new framework reference
+      this._eventWatcher = new EventWatcher(this._goalManager, this._framework)
+      this._eventWatcher.start()
+    }
+  }
+
+  uninstall(framework) {
+    // Stop explorer loop
+    if (this._explorerLoop) {
+      this._explorerLoop.stop()
+      this._explorerLoop = null
+    }
+
+    // Stop event watcher
+    if (this._eventWatcher) {
+      this._eventWatcher.stop()
+      this._eventWatcher = null
+    }
+
+    // Clear references
+    this._framework = null
+    this._goalManager = null
+    this._reflector = null
+    this._stateStore = null
+    this._memories = []
+  }
+}
+
+module.exports = { AmbientAgentPlugin, GoalState }