agent-step-sequencer

# Agent Step Sequencer

Multi-step scheduler for in-depth requests. Enables step-based actions with heartbeat integration—survives gateway reset mid-step.

## Core Pattern

1. **Interpret** when user request requires multiple steps
2. **Suggest** step plan, wait for confirmation
3. **Persist** state.json (with plan format)
4. **Agent invokes** `scripts/step-sequencer-check.py` immediately (no wait for heartbeat)
5. **Heartbeat** (e.g. every 5 min) also invokes the script—keeps sequencer aligned with email jobs and other heartbeat tasks

**Critical:** If gateway resets mid-step, next heartbeat reads state and resumes correctly.

---

## Plan Format

Agent builds a plan when user approves. During approval, agent asks: **Use 2-minute delay between steps?** Recommended for rate-limit–sensitive API calls. User chooses; agent sets `stepDelayMinutes` (0 or 2) in state. Each step has `title`, `instruction`, and optionally `requiredOutputs` (paths relative to workspace that must exist before the step is marked DONE):

```json
{
  "plan": {
    "steps": {
      "step-1": { "title": "Research topic X", "instruction": "Research topic X and produce a concise summary", "requiredOutputs": ["study/summary.md"] },
      "step-2": { "title": "Write paper", "instruction": "Using the summary from step 1, write a research paper..." }
    }
  },
  "stepQueue": ["step-1", "step-2"],
  "currentStep": 0,
  "stepRuns": {},
  "stepDelayMinutes": 0,
  "status": "IN_PROGRESS"
}
```

- **title**: Human-readable label
- **instruction**: Full instruction for the agent (research, summarize, pull X from Y, etc.)
- **requiredOutputs** (optional): List of paths (relative to workspace). Runner marks step DONE only if agent exits 0 and all these paths exist; otherwise step is FAILED with "Missing required outputs: …".

---

## Roles

- **Agent**: Builds plan, persists state; does not touch state during step execution. Takes prompts.
- **Runner** (`step-sequencer-runner.py`): Invokes agent with step inst...

# Agent Step Sequencer

Multi-step scheduler for in-depth agent requests. Detects when a task needs multiple steps, suggests a plan, waits for confirmation, persists state, and runs a heartbeat-aware flow.

**Core pattern:** Agent proposes plan → user approves → persist state.json → check script invokes runner → runner invokes agent per step → heartbeat keeps it aligned.

---

## Why Agent Step Sequencer?

Tasks like "research X, summarize it, then write a paper" or "pull data from 5 sources and merge" need sequential execution. A single agent run stops when it finishes one step. 

Agent Step Sequencer:

- **Persists state** — survives gateway resets mid-step
- **Schedules steps** — check script invokes runner; runner invokes agent with each step instruction
- **Retries on failure** — troubleshoot prompt, immediate retry (no heartbeat wait)
- **Heartbeat-aware** — runs alongside email jobs and other heartbeat tasks

---

## Critical Rules

- **No cron** — Check script invokes runner directly; heartbeat drives the schedule
- **Delay as approval** — Agent asks during approval: "2-min delay between steps?" (for rate-limit–sensitive calls); user choice sets `stepDelayMinutes`
- **Agent suggests before executing** — When MULTI_STEP, propose plan and wait for confirmation
- **Check script invokes runner** — Check script never runs work; it invokes the runner
- **Runner invokes agent** — Runner passes step instruction to agent; agent executes
- **State is source of truth** — On heartbeat reset, check script reads state and resumes

---

## Flow

### Check script → Runner

```mermaid
flowchart TD
    A[Heartbeat or Agent] --> B[step-sequencer-check.py]
    B --> C{Work to do?}
    C -->|No| D[Do nothing]
    C -->|Yes| E[Invoke runner]
    E --> F[step-sequencer-runner.py]
    F --> G[Invoke agent with instruction]
    G --> H{Agent exit}
    H -->|Success| I[Mark DONE]
    H -->|Fail| J[Mark FAILED, invoke check script]
    I --> K[Check advances or done]
    J --> B
```...