agent

what the agent does

how it runs

The agent runs as a Windows service managed by NSSM (Non-Sucking Service Manager). NSSM ensures the service starts automatically on boot and restarts on failure.

NSSM (Service Manager)
  └── owlette_runner.py (Bridge)
        └── owlette_service.py (Main Service Loop)
              ├── firebase_client.py (Cloud Sync)
              │     ├── auth_manager.py (OAuth Tokens)
              │     ├── firestore_rest_client.py (REST API)
              │     └── connection_manager.py (State Machine)
              ├── shared_utils.py (Config, Logging, Metrics)
              ├── health_probe.py (Startup Health Checks)
              ├── installer_utils.py (Remote Deployment)
              ├── project_utils.py (Project Distribution)
              ├── registry_utils.py (Software Inventory)
              └── mcp_tools.py (Remote Command Execution)

Spawned into user session by the service:
  ├── owlette_tray.py (System Tray Icon)
  ├── owlette_cortex.py (Local AI Agent)
  │     ├── cortex_firestore.py (Message Polling & Response Writing)
  │     ├── cortex_tools.py (MCP Tool Server for Agent SDK)
  │     └── mcp_tools.py (Tool Implementations)
  ├── process_launcher.py (Application Launcher)
  └── session_exec.py (User Session Command Executor)

Launched on demand:
  ├── owlette_gui.py (Configuration GUI)
  ├── configure_site.py (Device Code Pairing)
  └── report_issue.py (Bug Report Dialog)

See Cortex tools reference for the current tool list.

service lifecycle

startup

1. Initialize logging (RotatingFileHandler, 10 MB per file, 5 backups)
2. Upgrade config schema if needed (automatic migration)
3. Initialize Firebase client (lazy, soft-fail if no credentials)
4. Classify the previous session's end (see below) and emit a warning event if the machine came back up in an unexpected way
5. Recover running processes (adopt PIDs from previous session)
6. Launch system tray icon as user process
7. Launch Cortex process as user process (if enabled)
8. Enter main loop

session state classification

On every startup the agent reads C:\ProgramData\Owlette\tmp\session_state.json (written continuously by the previous run — alongside app_states.json and reboot_state.json) and uses the "alive heartbeat" and any recorded shutdown intent to categorise how the last session ended:

The classifier depends only on shared_utils and stdlib — no Firebase, no logging config — so it is safe to import from any agent context (main loop, metrics thread, signal handler, user-space dialogs). Source: agent/src/session_state.py.

main loop (every 5 seconds)

1. Check all configured processes — detect crashes, stalls, exits
2. Auto-restart crashed processes when launch mode is active
3. Firestore commands are processed by the Firebase command listener; the 5-second service loop handles process monitoring, Cortex IPC, Firebase enable/disable checks, and periodic maintenance
4. Ensure Cortex is running (if enabled)
5. Process Cortex IPC commands (Tier 2 tool calls)
6. Check for Firebase state changes (enable/disable)

shutdown

1. Mark machine offline in Firestore
2. Terminate Cortex process
3. Stop Firebase client and background threads
4. Clean up resources

key directories