AIPass/src/aipass/daemon/README.md

← Back to AIPass

DAEMON

Purpose: Cron-triggered task scheduler with plugin system. Routes commands to modules for scheduled tasks, activity reports, action management, and status digests. Module: aipass.daemon Created: 2026-03-07 Citizen Class: builder Last Updated: 2026-04-07

---

Quick Start

drone @daemon                           # Show discovered modules
drone @daemon update                    # Status digest
drone @daemon activity                  # Quick 24h activity summary
drone @daemon queue                     # View pending scheduled jobs
drone @daemon run                       # Fire all due jobs now
drone @daemon branch-health DAEMON      # Deep dive on a branch
drone @daemon install-timer             # Enable systemd 2-min timer

---

Overview

Builder citizen -- full 3-layer architecture with identity and memory. DAEMON serves as the background orchestration branch: it discovers modules at startup, routes CLI commands to them, and provides introspection and help output via Rich console.

What I Do

• Route CLI commands to discovered modules (update, schedule, activity_report, actions)
• Manage scheduled follow-ups with CRUD operations and due-date processing
• Generate activity reports across all branches (24h summary, detailed, per-branch)
• Run action registry (list, toggle, set reminder/schedule, migrate plugins)
• Auto-discover and dispatch plugins (community_rotation, daily_audit, heartbeat)
• Detect red flags (code changes without memory updates, stale branches)
• Produce status digests (inbox, actionable items, escalations)

---

Architecture

daemon/
├── __init__.py
├── README.md
├── DASHBOARD.local.json
├── apps/
│   ├── daemon.py              # Entry point (CLI) — module discovery + command routing
│   ├── daemon_wakeup.py       # Wakeup / cron trigger
│   ├── scheduler_cron.py      # Cron scheduler
│   ├── modules/
│   │   ├── update.py          # Status digest module — summarizes DAEMON activity
│   │   ├── schedule.py        # Scheduled follow-ups — fire-and-forget task management
│   │   ├── activity_report.py # Branch activity report generator
│   │   ├── actions.py         # Action registry CLI — list, toggle, info, reminders
│   │   ├── scheduler_ops.py   # Scheduler cron operations facade
│   │   └── wakeup_ops.py      # Wake-up cron operations facade
│   ├── handlers/
│   │   ├── actions/
│   │   │   └── actions_registry.py   # Action registry implementation
│   │   ├── json/
│   │   │   └── json_handler.py       # JSON data operations
│   │   ├── monitoring/
│   │   │   ├── activity_collector.py  # Collects branch activity data
│   │   │   ├── memory_health.py       # Memory health checks
│   │   │   └── red_flag_detector.py   # Detects anomalies / red flags
│   │   ├── schedule/
│   │   │   ├── task_registry.py       # Task registry for scheduled items
│   │   │   └── .archive/             # assistant_notifier, telegram_notifier (archived)
│   │   ├── telegram/                  # ARCHIVED — moving to skills system
│   │   │   └── .archive/             # assistant_chat (archived)
│   │   └── update/
│   │       └── data_loader.py         # Data loading for status digests
│   ├── extensions/             # Extension point for additional capabilities
│   ├── json_templates/         # JSON template definitions
│   └── plugins/
│       ├── community_rotation.py      # Community rotation plugin
│       ├── daily_audit.py             # Daily audit plugin
│       ├── heartbeat.py               # Heartbeat / liveness plugin
│       └── .archive/                  # botfather_reminder, devpulse_monitor (archived)
├── daemon_json/                # JSON tracking data
├── docs/                       # Documentation
├── dropbox/                    # Incoming file drops
├── logs/                       # Prax log output
├── tools/                      # Branch verification utilities
└── tests/                      # Test suite

---

Commands / Usage

drone @daemon                       # Show discovered modules (introspection)
drone @daemon --help                # Rich-formatted help with all commands
drone @daemon --version             # Print version

drone @daemon update                # Status digest — inbox, session info, escalations (partial — reads stale data paths)
drone @daemon schedule list         # List pending scheduled tasks
drone @daemon schedule create "task" --due 7d --to @branch
drone @daemon schedule run-due      # Fire all due tasks (sends emails)
drone @daemon activity              # Quick 24h activity summary
drone @daemon activity-report       # Full detailed report (--json for raw)
drone @daemon branch-health BRANCH  # Single branch deep dive
drone @daemon actions list          # Action registry
drone @daemon actions <id> on/off   # Toggle action
drone @daemon actions set reminder 7d "msg" --to @branch
drone @daemon actions set schedule @branch "prompt" daily 04:00
drone @daemon install-timer           # Install + enable systemd user timer
drone @daemon uninstall-timer         # Stop + remove systemd user timer

Each module accepts --help for module-specific usage:

drone @daemon <command> --help

---

Modules

Module	Description	Status
update	Status digest of DAEMON activity	(partial) — reads inbox/sessions but data_loader paths return empty
queue	Unified job queue view — Rich table or --json (frozen schema for @skills bot)	Operational
schedule	(retired) Fire-and-forget follow-ups — superseded by .daemon/schedule.json	Retired
activity_report	Branch activity reports: activity, activity-report, branch-health	Operational
actions	(retired) Action registry — superseded by .daemon/schedule.json	Retired
scheduler_ops	Scheduler cron operations facade for scheduler_cron.py	Operational
wakeup_ops	Wake-up cron operations facade for daemon_wakeup.py	Operational
timer_install	Idempotent systemd user timer installer for daemon scheduler	Operational
run	Decentralized scheduler tick: discover .daemon/ jobs, fire due ones	Operational

---

Scheduling Jobs

Each branch owns its schedule at src/aipass/<branch>/.daemon/schedule.json. The daemon discovers and fires — branches define their own jobs.

Job file schema

{
  "version": 1,
  "branch": "@<branch>",
  "jobs": [
    {
      "id": "my-job",
      "enabled": true,
      "schedule": { "type": "interval", "interval_minutes": 30 },
      "wake": { "fresh": true, "model": "haiku" },
      "prompt": "Do something, then STOP."
    }
  ]
}

Schedule types

Type	Fields	Due when
interval	interval_minutes: N	Elapsed >= N since last_run. Fires immediately if never run.
daily	time: "HH:MM"	Within +/-15 min of target time, once per day.
hourly	time: "M" (minute)	Within +/-15 min of target minute, once per hour.
once	due_date: "YYYY-MM-DD"	Date <= today, then marks completed.

Wake options

• fresh (bool) — start a fresh Claude session (true) or resume (false)
• model (string, optional) — "haiku" or "sonnet" recommended for light wakes

Staggering

No native offset field. To stagger jobs, seed different last_run values in daemon_json/daemon_runstate.json.

---

Integration Points

Depends On

• rich -- Console output and formatted display
• Python stdlib (sys, typing, logging)

Provides To

• All modules — background task scheduling, activity monitoring, action tracking
• Plugins — extensible plugin system for recurring tasks (community_rotation, daily_audit, heartbeat)
• Note: Telegram handlers archived — moving to skills system. See apps/handlers/telegram/.archive/

---

Plugins

Plugin	Target	Schedule	Status
community_rotation	@rotating	every 4h	Operational — requires AIPASS_WAKE_SCRIPT env var
daily_audit	@seed	daily 04:00	(not operational) — targets @seed (renamed to @seedgo)
heartbeat	@vera	every 4h	(not operational) — @vera not in branch registry

---

Known Issues

• update command shows empty data (0 sessions, no focus) — data_loader reads from different paths than .trinity/local.json
• daily_audit plugin targets @seed which was renamed to @seedgo
• heartbeat plugin targets @vera which is not registered in the branch registry
• All plugins require AIPASS_WAKE_SCRIPT env var to dispatch — without it, plugins discover but can't execute
• drone @daemon activity_report (underscore) fails — use activity, activity-report, or branch-health instead

---

Identity

• Passport: .trinity/passport.json
• Session History: .trinity/local.json
• Observations: .trinity/observations.json
• Branch Prompt: .aipass/branch_system_prompt.md

---

Test Suite

• 300 tests across 15 test files
• 8/8 modules covered, 30/36 public functions tested
• Seedgo audit: 100% across all standards

Last Updated: 2026-06-29

---

← Back to AIPass