Goals API Reference

The Goals Engine exposes functionality through two interfaces: the agent tool (used by agents in conversations) and JSON-RPC methods (used by the frontend and external clients via the gateway protocol).

Both interfaces map to the same underlying handlers in gateway/server-methods/goals.js.

Agent Tool Actions

The goals tool accepts an action parameter. All actions go through the gateway RPC layer.

`create`

Create a new goal with phases.

goals({
  action: "create",
  goal: {
    title: "Campaign optimization",           // required
    description: "Reduce CPA by 20%",         // optional
    agentId: "marketing-agent",                // optional (defaults to current agent)
    phases: [                                   // required, at least one
      { name: "Research", description: "...", type: "once" },
      { name: "Execute", type: "once" },
      { name: "Monitor", type: "loop" }
    ],
    budget: {                                   // optional
      maxTokens: 5000000,
      maxCost: 100,
      maxSessions: 50,
      approvalGate: 50
    },
    deadline: "2026-03-31T00:00:00Z",          // optional
    reportInterval: "2h",                       // optional
    reportChannel: "slack",                     // optional
    state: {},                                  // optional initial state
    metrics: []                                 // optional initial metrics
  }
})

Returns: { goal } — the created goal object with generated ID.

`get`

Get full goal details including recent checkpoints and logs.

goals({ action: "get", goalId: "g_abc123" })

Returns: { goal, checkpoints, logs } — goal object plus 5 most recent checkpoints and 10 most recent logs.

`list`

List goals with optional filters.

goals({
  action: "list",
  agentId: "marketing-agent",  // optional filter by agent
  status: "active",             // optional filter by status
  limit: 10                     // optional limit (default: all)
})

Returns: { goals } — array of goal objects.

`update`

Update goal fields directly.

goals({
  action: "update",
  goalId: "g_abc123",
  patch: {
    description: "Updated: reduce CPA by 25%",
    deadline: "2026-04-15T00:00:00Z"
  }
})

Returns: { goal } — updated goal object.

`checkpoint`

Save a state checkpoint for the current phase.

goals({
  action: "checkpoint",
  goalId: "g_abc123",
  summary: "Completed competitor analysis",    // required
  state: {                                      // optional
    competitors: ["Acme", "Beta"],
    keyFindings: "..."
  }
})

Returns: { checkpoint, goal } — the created checkpoint and updated goal.

`complete_phase`

Complete the current phase and advance to the next.

goals({
  action: "complete_phase",
  goalId: "g_abc123",
  result: "Research done. 5 competitors documented."  // optional
})

Returns: { goal, advanced, completed } — advanced is true if moved to next phase, completed is true if all phases are done.

Budget is checked before phase advancement. If the budget is exceeded, the call returns an error and the phase stays in running status.

`pause`

Pause a goal. Removes cron jobs for loop phases.

goals({ action: "pause", goalId: "g_abc123" })

`resume`

Resume a paused goal.

goals({ action: "resume", goalId: "g_abc123" })

`fail`

Mark a goal as failed with a reason.

goals({
  action: "fail",
  goalId: "g_abc123",
  reason: "API rate limits exceeded, unable to complete optimization"
})

`metric`

Update a tracked metric.

goals({
  action: "metric",
  goalId: "g_abc123",
  name: "signups",
  value: 342
})

Metrics accumulate history. The engine tracks trends (up/down/stable) across metric updates.

`log`

Add a log entry.

goals({
  action: "log",
  goalId: "g_abc123",
  message: "Started A/B test on landing page variant B",
  level: "action"   // "info" | "warn" | "error" | "action"
})

`budget_check`

Check if the goal's budget allows continued execution.

goals({ action: "budget_check", goalId: "g_abc123" })

Returns: { allow, reason?, remaining?, field?, budgetStatus, budget }

`record_spend`

Record spend against the goal's budget.

goals({
  action: "record_spend",
  goalId: "g_abc123",
  cost: {
    tokens: 150000,
    dollars: 2.50,
    sessions: 1
  }
})

`approve`

Approve a goal past its approval gate. Raises the gate by 50% and resumes if paused.

goals({ action: "approve", goalId: "g_abc123" })

`trigger`

Manually fire a trigger on a goal phase.

goals({
  action: "trigger",
  goalId: "g_abc123",
  phaseIndex: 2,
  event: "staging-approved"   // optional, defaults to "manual"
})

`start_loop`

Start a service loop for a goal phase.

goals({
  action: "start_loop",
  goalId: "g_abc123",
  phaseIndex: 1,            // default: 0
  intervalMs: 60000,        // default: 300000 (5m)
  maxRuntimeMs: 14400000    // default: 28800000 (8h)
})

`stop_loop`

Stop a service loop.

goals({ action: "stop_loop", goalId: "g_abc123" })

JSON-RPC Methods

These are the gateway server methods, callable via the Reeve protocol from any connected client.

Method	Description
`goals.create`	Create a goal
`goals.get`	Get goal with checkpoints + logs
`goals.list`	List goals with filters
`goals.update`	Patch goal fields
`goals.checkpoint`	Save a checkpoint
`goals.complete_phase`	Complete current phase
`goals.pause`	Pause a goal
`goals.resume`	Resume a paused goal
`goals.fail`	Mark goal as failed
`goals.cancel`	Cancel and delete a goal
`goals.approve`	Approve past budget gate
`goals.metric`	Update a metric
`goals.log`	Add a log entry
`goals.logs`	Retrieve log entries
`goals.budget_check`	Check budget status
`goals.record_spend`	Record spend
`goals.trigger`	Fire a trigger on a phase
`goals.start_loop`	Start a service loop
`goals.stop_loop`	Stop a service loop

CLI Commands

reeve goal list                    # List all goals
reeve goal status <id>             # Detailed goal status
reeve goal log <id>                # View goal log
reeve goal pause <id>              # Pause a goal
reeve goal resume <id>             # Resume a goal
reeve goal cancel <id>             # Cancel a goal
reeve goal approve <id>            # Approve past budget gate
reeve goal budget <id>             # View budget status
reeve goal create                  # Interactive create wizard

Database Schema

Goals are stored in SQLite at ~/.reeve/goals/goals.db with three tables:

`goals` table

Column	Type	Description
`id`	TEXT PRIMARY KEY	Goal UUID
`agent_id`	TEXT	Owning agent
`created_by`	TEXT	Creator (user or agent)
`title`	TEXT NOT NULL	Goal title
`description`	TEXT	Full description
`status`	TEXT	active/paused/completed/failed/cancelled
`phases`	TEXT (JSON)	Array of phase objects
`current_phase`	INTEGER	Current phase index
`budget`	TEXT (JSON)	Budget config + usage
`deadline`	TEXT	ISO 8601 deadline
`report_interval`	TEXT	Reporting frequency
`report_channel`	TEXT	Report destination
`state`	TEXT (JSON)	Arbitrary working state
`metrics`	TEXT (JSON)	Tracked KPIs
`created_at`	TEXT	Creation timestamp
`started_at`	TEXT	Start timestamp
`completed_at`	TEXT	Completion timestamp
`last_report_at`	TEXT	Last auto-report time

`goal_checkpoints` table

Column	Type	Description
`id`	TEXT PRIMARY KEY	Checkpoint UUID
`goal_id`	TEXT	Foreign key to goals
`phase_id`	TEXT	Phase ID at checkpoint time
`iteration`	INTEGER	Loop iteration number
`state`	TEXT (JSON)	State snapshot
`summary`	TEXT	Human-readable summary
`created_at`	TEXT	Checkpoint timestamp

`goal_logs` table

Column	Type	Description
`id`	TEXT PRIMARY KEY	Log UUID
`goal_id`	TEXT	Foreign key to goals
`level`	TEXT	info/warn/error/action
`message`	TEXT	Log message
`metadata`	TEXT (JSON)	Optional structured data
`created_at`	TEXT	Log timestamp

API Reference

On this page