Inngest Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
Inngest Orchestration serves as the backbone for durable, event-driven execution within the Cogmo personal agent runtime. It enables a hub-and-spoke architecture where an orchestrator centralizes validation and routes requests to specialized workers. By leveraging Inngest, the system ensures that long-running tasks—such as agentic loops, scheduled ingestion, and memory extraction—are resilient to process restarts and maintain state across asynchronous boundaries.
Sources: CLAUDE.md, design/architecture.md:21-42, README.md
Architectural Role
The orchestration layer decouples components by communicating via Inngest events rather than direct imports. The main Node.js process acts as a controller, receiving events, calling domain services (like LLMs or memory stores), and emitting new events to trigger downstream actions. This setup allows the system to be "stateless per invocation," where every agent call reads the latest configuration and memory from the database without relying on in-memory state between turns.
Sources: CLAUDE.md, design/architecture.md:8-15
Component Interaction Map
The following diagram illustrates how the Orchestrator interacts with various specialized agents and external interfaces via the event bus.
Event-Driven Lifecycle
The system utilizes a specific set of event patterns to manage the transition from user input to agent response and background maintenance.
| Event Type | Triggering Source | Primary Consumer | Purpose |
|---|---|---|---|
inbound/arrived | Channel Adapter | Orchestrator | Signals a new message from a user platform (e.g., Telegram). |
outbound/deliver | Conversation Agent | Channel Adapter | Routes the final agent response to the specific delivery platform. |
conversation/idle | System Timer | Observer Agent | Triggers post-conversation fact extraction for long-term memory. |
scheduled/trigger | Inngest Cron | Ingestion Agents | Initiates periodic tasks like email or calendar sync. |
Sources: CLAUDE.md, design/architecture.md:46-59, design/transport/adapters.md:87-94
Long-Running Task Pattern
For tasks exceeding standard execution windows (such as complex coding refactors), the orchestration layer uses a suspension pattern.
Sources: design/architecture.md:129-141
Infrastructure and Configuration
Inngest orchestration requires a Redis instance for queue management and state persistence. The system can run in two modes: connect (recommended for local dev and long-poll stability) and serve (standard HTTP delivery).
| Variable | Default | Description |
|---|---|---|
INNGEST_MODE | connect | Determines if the SDK uses long-polling (connect) or HTTP (serve). |
INNGEST_BASE_URL | — | The URL of the Inngest server (e.g., http://inngest.internal:8288). |
INNGEST_EVENT_KEY | — | Security key for emitting events to the Inngest platform. |
INNGEST_SIGNING_KEY | — | Key used to verify requests from Inngest to the application. |
Sources: DEPLOYMENT.md:92-105, README.md:27-31
Observability in Orchestration
Inngest functions are automatically instrumented via OpenTelemetry. Each function run creates an inngest.execution root span. While individual retries of a function run create fresh traces, they can be correlated using the inngest.runId attribute to track a complete logical operation across failures.
Sources: DEPLOYMENT.md:252-273
Summary
Inngest Orchestration provides the durable execution environment necessary for Cogmo's modular, evolving architecture. By strictly separating business logic in domain modules from the orchestration infrastructure in src/inngest/, the project ensures that its complex agentic loops and multi-step background tasks remain resilient, traceable, and easily extensible.
Sources: CLAUDE.md, design/architecture.md:65-79