LifeOSAI — Companies & Orchestration
Wakeup source → agentWakeupRequest queue → HeartbeatService → agent-invoker → runtime → heartbeatRun + LIVE_EVENTS → SSE / persistence. Right rail shows the company data model and event sinks.
WAKEUP SOURCES
canonical WakeupSource enum · heartbeat.ts:52
Timer Heartbeat
"timer" · scheduled
Issue Assignment
"assignment"
Manual Run
"on_demand"
Routine Trigger
"automation" · cron
Direct Chat
"direct_chat"
Channel Inbound
"channel" · WA/TG
COMPANY DOMAIN
Company
tenant boundary
Agent
role · instructions · skills
Project
files · env · goals
Issue / Task
status · priority · policy
Routine
cron schedule
Goal
company objective
TENANT-SCOPED ENTITIES
Every entity is scoped to a Company.
Issue execution policy: "normal" or "auto"
Stages: "review" · "approval"
PERSISTENCE + SINKS
SSE Stream
subscribeToCompany
Frontend
CompanyEventsContext
runs + runEvents
heartbeatRun table
Activity Log
audit timeline
Cost Tracker
recordCost · budget
Approvals
execution-stage gate
FAN-OUT FROM EVENT BUS
Every publishRunEvent / publishAgentStatus call
fans out to SSE + DB + activity + cost.
ORCHESTRATION ENGINE
apps/api/src/orchestration/engine · event-driven, not polling
WAKEUP QUEUE
wakeup.ts
agentWakeupRequest
DB row · status, source, payload
enqueueWakeup → claim
queued → claimed → completed/failed
WakeupReason
issue_assigned · _commented · _mentioned · …
HEARTBEAT SERVICE
heartbeat.ts · event-driven dispatcher
wakeup() → startNext()
chained from route handlers
Routine Scheduler
60s tick · creates issues from cron
Recovery Loop
5-min orphan reaper · safety net
AGENT INVOKER
engine/agent-invoker.ts
resolveAdapterConfig
reads agent.adapterConfig
→ "claude-code" | "pi-agent"
Mount Skills + MCP
channels (auto)
whatsapp · phone · files · …
mintAgentRunToken
run-scoped JWT
LIFEOSAI_RUN_TOKEN
Build Env
agent env → project env
→ run env (precedence)
RUNTIME DISPATCH · heartbeatRun LIFECYCLE
Claude Code SDK
@anthropic-ai/
claude-agent-sdk
Pi Coding Agent
pi-agent-runtime
custom adapter
heartbeatRun row
sessionId · usage · result
cost · status
Run Status
queued → running →
completed / failed / cancelled
EVENT BUS · LIVE_EVENTS publishing
event-bus.ts · publishRunEvent · publishAgentStatus · publishIssue*
heartbeat.run.*
queued · running · log
finished · completed · failed · cancelled
agent.status
idle · running · paused
publishAgentStatus()
issue.*
created · updated · deleted
comment-created
activity.logged
logActivity()
audit timeline
cost
recordCost · budget
pause if blocked
enqueueWakeup()
claimNextWakeup()
invokeAgent()
runtime.query()
publishRunEvent
fan-out to sinks