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

---

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

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
schedule	Fire-and-forget scheduled follow-ups and task management	Operational
activity_report	Branch activity reports: activity, activity-report, branch-health	Operational
actions	Action registry CLI — list, toggle, info, set reminder, set schedule, migrate	Operational
scheduler_ops	Scheduler cron operations facade for scheduler_cron.py	Operational
wakeup_ops	Wake-up cron operations facade for daemon_wakeup.py	Operational

---

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

• 448 tests across 19 test files
• 8/8 modules covered, 43/51 public functions tested
• Seedgo audit: 100% across all standards

Last Updated: 2026-04-07

---

← Back to AIPass