Goals Engine

The Goals Engine lets agents pursue sustained, multi-phase objectives — not just respond to messages. A goal persists in the database, survives session resets and gateway restarts, and drives agent behavior between user interactions.

Why Goals?

Without goals, Reeve agents are reactive: they respond to messages, run heartbeats, and go idle. Goals make agents proactive — they can plan, execute, monitor, and optimize over hours or days.

You: "Run Freya's launch campaign. Budget: $200 ads, target 500 signups by Friday."

Agent: Goal created — "Freya Launch Campaign"
  Phase 1: Research & Plan (starting now)
  Phase 2: Build Creatives
  Phase 3: Deploy Campaign
  Phase 4: Monitor & Optimize (loop, every 30m, until Friday)
  Budget: $200 ad spend / ~$20 tokens

  I'll report progress every 2 hours. Say /goal pause to halt.

Core Concepts

A goal is a first-class primitive with:

• Phases — Ordered steps (research → build → deploy → monitor). Each phase can run once, loop on an interval, or wait for an event trigger.
• Budgets — Token, dollar, and session caps with automatic enforcement. Approval gates pause the goal and ask a human before continuing.
• Checkpoints — State snapshots that survive context compaction and session resets.
• Metrics — Tracked KPIs (signups, CTR, revenue) with history and trend analysis.
• Triggers — Webhooks, thresholds, and events that activate phases or advance the goal.
• Service Loops — Fast execution loops (min 10s interval) for intensive phases like monitoring.

Goal Lifecycle

created → active → [phase 1 running] → [phase 2 running] → ... → completed
                ↓                                                      ↑
              paused ──── resumed ─────────────────────────────────────┘
                ↓
              failed / cancelled

Goals move through statuses: active, paused, completed, failed, cancelled. Each phase within a goal has its own status: pending, running, completed, failed, skipped.

Quick Start

Create a goal via CLI

reeve goal create

The interactive wizard walks you through title, phases, budget, and deadline.

Create a goal programmatically (agent tool)

goals({
  action: "create",
  goal: {
    title: "Increase newsletter signups",
    description: "Get to 1000 signups by end of month",
    agentId: "marketing-agent",
    phases: [
      { name: "Audit current funnel", type: "once" },
      { name: "Optimize landing page", type: "once" },
      { name: "Monitor & iterate", type: "loop" }
    ],
    budget: { maxCost: 50, approvalGate: 25 }
  }
})

Monitor via CLI

reeve goal list              # All goals
reeve goal status <id>       # Detailed view with phases, budget, logs
reeve goal log <id>          # Recent activity log

Architecture

The Goals Engine consists of several gateway subsystems:

Data flows through two paths:

1. Agent tool → goals-tool.js → JSON-RPC → server-methods/goals.js → store
2. Heartbeat → heartbeat-hook.js → injects active goal context into agent's system prompt

What's Next