Scheduled Actions

Use Scheduled Actions for recurring prompts that should run on a timetable.

Examples:

• Daily repository health checks
• Hourly sync/status summaries
• Weekday release readiness checks
• Routine maintenance prompts

If you need to process a finite list of todos until completion, use Todo Runner instead.

Open Scheduler

Go to Settings -> Schedules.

Each schedule includes:

• name
• cron expression
• working directory
• prompt
• YOLO mode toggle
• runtime status (idle, running, success, error)

Create A Schedule

1. Click + Add Schedule.
2. Fill in:
   • Task name
   • Cron: minute hour day month weekday
   • Directory: target workspace path
   • Prompt: exact recurring work instruction
3. Save the task.
4. Click Run now once to validate before waiting for cron.

Cron Expression Reference

Agent Observer uses a 5-field cron format:

minute hour day month weekday

Common examples:

• */15 * * * * every 15 minutes
• 0 * * * * every hour
• 0 9 * * 1-5 9:00 AM weekdays
• 30 18 * * * 6:30 PM every day
• 0 2 * * 0 2:00 AM every Sunday

Prompt Design For Recurring Jobs

Use deterministic prompt structure:

1. State objective in one sentence.
2. Define scope (repo/path/system).
3. Define output format (short report, checklist, pass/fail summary).
4. Define failure behavior (stop, retry externally, or alert).

Good recurring prompt shape:

• "Run X checks in Y directory, summarize failures grouped by severity, include next 3 actions."

Avoid:

• open-ended prompts with no expected output structure
• prompts that mutate many files without strict boundaries

Validation Checklist

After saving a schedule:

1. Run now succeeds once.
2. Last run and duration fields update.
3. Next run is populated as expected.
4. Errors (if any) are visible in the schedule card.

Runtime Model

• Scheduler loop checks tasks regularly.
• Only enabled tasks run.
• Running tasks are not started twice.
• Manual and cron-triggered runs share the same execution path.
• Schedule definitions are persisted locally.

Pending Backlog Cap

• Pending cron backlog is bounded per task to prevent unbounded memory growth.
• Default per-task cap: 240 pending minute entries.
• Oldest pending entries are dropped first (newest entries are retained).
• Operator signal: diagnostics event scheduler.tick.backlog_capped.
• Optional override: AGENT_SPACE_SCHEDULER_PENDING_BACKLOG_LIMIT (1 to 1440).

Minute Dedupe Ledger

• Scheduler persists the last processed cron minute per task across app restarts.
• Deduplication window defaults to 1440 minutes (24h).
• Optional override: AGENT_SPACE_SCHEDULER_MINUTE_LEDGER_RETENTION_MINUTES (0 to 43200).
• Operator signal: diagnostics event scheduler.ledger.pruned.

Persistence location:

• ~/.agent-observer/schedules.json
• ~/.agent-observer/scheduler-minute-ledger.json

Failure Modes And Fixes

Schedule stays idle

• Verify it is enabled.
• Verify cron is valid (5 fields).
• Verify app is running at scheduled time.

Immediate error on run

• Verify directory exists and is readable.
• Verify prompt is non-empty.
• Verify underlying runner/tooling dependencies are available.

Wrong files being touched

• Correct working directory.
• Tighten prompt scope with explicit path constraints.
• Disable task until prompt is corrected.

Operational Safety

For high-impact recurring tasks:

1. Test with a short interval in a staging repo.
2. Review 2-3 consecutive successful runs.
3. Move to production schedule.
4. Keep a rollback plan for unintended changes.