Phase 2: Heartbeat & Autonomous Daemon

Overview

This phase adds scheduled autonomous behavior to AgenC agents. The Heartbeat system allows agents to wake up on a schedule (cron-like) and perform actions without user input. The Daemon subsystem provides production-ready process management with PID files, signal handling, systemd integration, and crash recovery.

What this enables:

Dependencies

Phase 1: Gateway & Channel Foundation

Existing runtime infrastructure:

Issue Dependency Graph

Implementation Order

1. 1081 — Heartbeat scheduler (M)

- Core scheduler, action dispatch, quiet heartbeat contract

2. 1084 — Built-in heartbeat actions (M)

- Task scan, daily summary, portfolio monitor

3. 1085 — Cron-like scheduling (S)

- Per-action cron expressions

4. 1078 — Daemon lifecycle (M)

- PID file, signal handling, systemd service, crash recovery

Rationale: Scheduler → actions → cron → daemon. Basic scheduler first, then actions to test it, then flexible scheduling, finally production hardening.

Issue Details

2.1: Heartbeat scheduler (#1081)

Goal: Create a scheduler that runs heartbeat actions on intervals.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface HeartbeatAction {
  readonly name: string;
  readonly description: string;
  execute(context: HeartbeatContext): PromiseHeartbeatResult>;
}

interface HeartbeatContext {
  gateway: Gateway;
  runtime: AgentRuntime;
  session: Session;
  logger: Logger;
}

interface HeartbeatResult {
  shouldNotify: boolean;
  message?: string;
  metadata?: Recordstring, unknown>;
}

interface HeartbeatScheduler {
  registerAction(action: HeartbeatAction, intervalMs: number): void;
  start(): Promisevoid>;
  stop(): Promisevoid>;
}

Testing strategy:

Estimated scope: M (400-500 lines)

2.2: Built-in heartbeat actions (task scan, summary, portfolio) (#1084)

Goal: Implement three core heartbeat actions.

Files to create:

Files to modify:

Integration points:

- Quiet heartbeat: only notify if new tasks found

- Message: "Found {count} new tasks matching your capabilities"

- Quiet heartbeat: always send (once per day)

- Message: "Daily summary: {completions} tasks completed, {earnings} earned"

- Quiet heartbeat: only notify if alerts found

- Message: "Alert: Task #{id} deadline in 2 hours"

Patterns to follow:

Key interfaces:

class TaskScanAction implements HeartbeatAction {
  readonly name = 'task-scan';
  readonly description = 'Scan for new claimable tasks';
  // implementation
}

class DailySummaryAction implements HeartbeatAction {
  readonly name = 'daily-summary';
  readonly description = 'Generate daily activity summary';
  // implementation
}

class PortfolioMonitorAction implements HeartbeatAction {
  readonly name = 'portfolio-monitor';
  readonly description = 'Monitor active tasks for alerts';
  // implementation
}

Testing strategy:

Estimated scope: M (500-700 lines total across 3 actions)

2.3: Cron-like scheduling with per-action schedules (#1085)

Goal: Replace fixed intervals with cron expressions for flexible scheduling.

Files to create:

Files to modify:

Integration points:

- TaskScanAction: */5 * * * * (every 5 minutes)

- DailySummaryAction: 0 9 * * * (9 AM daily)

- PortfolioMonitorAction: 0 * * * * (hourly)

Patterns to follow:

Key interfaces:

interface CronScheduler {
  schedule(action: HeartbeatAction, cronExpr: string): void;
  unschedule(actionName: string): void;
  start(): Promisevoid>;
  stop(): Promisevoid>;
}

interface CronExpression {
  minute: string;
  hour: string;
  dayOfMonth: string;
  month: string;
  dayOfWeek: string;
}

Testing strategy:

Estimated scope: S (250-350 lines)

2.4: Daemon lifecycle (PID, signals, systemd, crash recovery) (#1078)

Goal: Production-ready daemon management with process supervision.

Files to create:

Files to modify:

Integration points:

- SIGTERM → graceful shutdown (stop gateway, save state, exit)

- SIGHUP → reload config (re-read ~/.agenc/gateway.json)

- SIGINT → graceful shutdown (same as SIGTERM)

- Type=simple

- Restart=on-failure

- RestartSec=10s

- WatchdogSec=60s

Patterns to follow:

Key interfaces:

interface DaemonManager {
  start(): Promisevoid>;
  stop(): Promisevoid>;
  restart(): Promisevoid>;
  status(): DaemonStatus;
  setupSignalHandlers(): void;
}

interface DaemonStatus {
  running: boolean;
  pid?: number;
  uptime?: number;
  lastCrash?: number;
}

interface PidFile {
  write(pid: number): Promisevoid>;
  read(): Promisenumber | null>;
  remove(): Promisevoid>;
  exists(): Promiseboolean>;
}

Testing strategy:

Estimated scope: M (500-700 lines)

Integration Checklist

After completing all issues:

Configuration Example

{
  "heartbeat": {
    "enabled": true,
    "actions": [
      {
        "name": "task-scan",
        "schedule": "*/5 * * * *",
        "config": {
          "minReward": 100000000,
          "capabilities": 3
        }
      },
      {
        "name": "daily-summary",
        "schedule": "0 9 * * *"
      },
      {
        "name": "portfolio-monitor",
        "schedule": "0 * * * *"
      }
    ]
  },
  "daemon": {
    "pidFile": "~/.agenc/gateway.pid",
    "watchdogInterval": 60000
  }
}

Systemd Service Template

[Unit]
Description=AgenC Gateway Daemon
After=network.target

[Service]
Type=simple
User=%i
ExecStart=/usr/bin/node /path/to/gateway/dist/bin/cli.js daemon start
Restart=on-failure
RestartSec=10s
WatchdogSec=60s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Success Metrics