Phases

Goals are broken into phases — ordered steps that advance sequentially. Each phase has a type that determines how it executes.

Phase Types

Type	Behavior	Example
`once`	Runs once, then advances to the next phase	"Research competitors"
`loop`	Repeats on an interval until a condition is met	"Monitor metrics every 30m"
`event-driven`	Waits for an external trigger (webhook, threshold)	"Deploy when staging tests pass"

`once` Phases

The simplest type. The agent works on the phase, then calls complete_phase to advance:

// Agent completes research phase
goals({ action: "complete_phase", goalId: "g_abc123", result: "Identified 5 competitors, documented in state" })

`loop` Phases

Loop phases repeat on an interval. They're managed by the Service Loop system or cron scheduler:

goals({
  action: "create",
  goal: {
    title: "Monitor ad performance",
    phases: [
      { name: "Initial setup", type: "once" },
      {
        name: "Monitor & optimize",
        type: "loop",
        // Loop config is managed by service-loops or cron
      }
    ]
  }
})

When a loop phase becomes active, start a service loop:

goals({
  action: "start_loop",
  goalId: "g_abc123",
  phaseIndex: 1,
  intervalMs: 300000,      // Every 5 minutes
  maxRuntimeMs: 28800000   // Stop after 8 hours
})

`event-driven` Phases

Event-driven phases wait for external triggers — webhooks, threshold crossings, or manual activation:

goals({
  action: "create",
  goal: {
    title: "Deploy pipeline",
    phases: [
      { name: "Build & test", type: "once" },
      { name: "Await staging approval", type: "event-driven" },
      { name: "Production deploy", type: "once" }
    ]
  }
})

Trigger the event-driven phase via the Triggers system or manually:

goals({ action: "trigger", goalId: "g_abc123", phaseIndex: 1, event: "staging-approved" })

Phase Advancement

Phases advance sequentially. When complete_phase is called:

The current phase status changes to "completed" with a timestamp and optional result
A log entry is created: "Phase completed: Research audience"
The next phase status changes to "running"
If no more phases remain, the goal itself is marked "completed"

Phase 1: Research    [completed ✓]
Phase 2: Build       [running →]     ← current
Phase 3: Monitor     [pending ○]
Phase 4: Report      [pending ○]

Budget checks on advancement

Before advancing, the engine checks the budget. If the budget is exceeded, phase advancement is blocked:

Budget exceeded: cost $51.20 exceeds limit $50.00. Remaining: -$1.20

The agent must either get the budget increased or the goal approved before continuing.

Phase Statuses

Status	Meaning
`pending`	Waiting for earlier phases to complete
`running`	Currently active — agent is working on this
`completed`	Finished with optional result text
`failed`	Phase failed (agent or system reported failure)
`skipped`	Manually skipped

Checkpoints

Agents save checkpoints to preserve state across context compactions:

goals({
  action: "checkpoint",
  goalId: "g_abc123",
  summary: "Completed competitor analysis. Top 5 documented.",
  state: {
    competitors: ["Acme", "Beta", "Gamma", "Delta", "Echo"],
    keyFindings: "Acme leads in pricing, Beta in features..."
  }
})

Checkpoints are stored in the goal_checkpoints table and included when the goal context is injected into the agent's system prompt. The 5 most recent checkpoints are shown.

Context Injection

Active goals are automatically injected into agent heartbeats via goals/heartbeat-hook.js. The agent sees:

## Active Goals

### Goal: Increase newsletter signups (active)
Phase 2 of 3: "Optimize landing page" (running)
Budget: $12.50 / $50.00 (25%)
Last checkpoint: "Completed audit, found 3 conversion issues"
Metrics: signups=245, conversion_rate=2.1%

This keeps the agent focused on its objectives even after session resets.

The complete_phase action is the primary way to advance goals. Agents can also update the goal directly with goals({ action: "update" }) for edge cases, but phase advancement through complete_phase is preferred because it handles logging, cron management, and status transitions automatically.

Phases

On this page