System Event Triggers
Relevant source files
The following files were used as context for generating this wiki page:System Event Triggers are a foundational concept in Loom, enabling AI agents to operate as long-running services that respond to real-world occurrences. Unlike traditional agent libraries where agents are activated only by direct code calls, Loom's event-driven architecture allows agents to react to a variety of system-level and external events, such as hotkeys, file changes, timers, clipboard modifications, and audio input. This capability is a key differentiator, transforming agents from simple script executors into proactive, continuously running entities integrated into a user's environment.
This system is central to Loom's vision of building long-lifecycle, desktop/edge agents. The architecture is designed to support cross-process and even cross-language agent collaboration, all orchestrated through a central Event Bus.
Sources: README.md:11-15, ROADMAP.md:4-10
Core Event Architecture
At the heart of Loom's event-driven model is the Event Bus, a high-performance pub/sub system managed by the Rust Core. All communication, including system triggers, flows through this bus. Producers publish events to specific topics, and the Event Bus delivers them asynchronously to any agent subscribed to those topics.
This diagram illustrates the basic publish-subscribe flow:
This diagram shows an event producer sending an event to the Event Bus, which then distributes it to all subscribed agents.
Sources: README.md:33-41, core/src/dashboard/README.md:28-30
Event Message Structure
All events in the system conform to the Event message structure defined in the protobuf schema. This standardized format ensures interoperability between different system components and agents.
| Field | Type | Description |
|---|---|---|
id | string | Unique event ID. |
type | string | Event type (e.g., video_frame, audio_chunk, hotkey.pressed). |
timestamp_ms | int64 | Timestamp in milliseconds. |
source | string | Event source (e.g., camera.front, mic.primary, system.hotkey). |
metadata | map<string,string> | Key-value pairs for additional context. |
payload | bytes | The main data associated with the event. |
confidence | float | A score from 0.0 to 1.0 indicating the confidence in the event's data. |
tags | repeated string | A list of tags for filtering and categorization. |
priority | int32 | Priority from 0 (lowest) to 100 (highest) for event processing. |
Sources: loom-proto/proto/event.proto:6-28
Types of Event Triggers
Loom supports and plans to support various types of event triggers, ranging from direct system integrations to application-specific data streams.
Planned System Integrations
A core part of the Loom roadmap is to enable deep integration with the host operating system, primarily for the "Desktop Assistant" application. These features will allow agents to become truly responsive personal assistants.
| Trigger Type | Description | Planned Application |
|---|---|---|
| Global Hotkey | Agents can register to be triggered by a global hotkey (e.g., Ctrl+Space). | Desktop Assistant |
| Clipboard Monitoring | Agents can react to changes in the system clipboard. | Desktop Assistant |
| Scheduled Triggers | Agents can be scheduled to run at specific times or intervals. | Market Analyst |
| File System Events | Agents can be triggered by file changes (e.g., a new file in Downloads). | Desktop Assistant |
These triggers are key to enabling long-lifecycle, proactive agents that can assist users without requiring explicit invocation for every task.
Sources: README.md:13, ROADMAP.md:10, 114, 122-125
Implemented System Triggers: Audio Pipeline
The loom-audio module provides a concrete, working example of a system-level event trigger pipeline. It captures audio from a microphone and processes it through several stages, each generating events that other agents can subscribe to.
The audio pipeline demonstrates how a raw system input is transformed into a series of increasingly abstract events:
This flowchart shows the progression of audio data from the microphone through VAD and STT, with each stage communicating via the Event Bus.
Key events generated by this pipeline include:
audio_chunk: Raw audio data from the microphone.vad.speech_start/vad.speech_end: Marks the beginning and end of detected speech.audio_voiced: Audio chunks that contain speech.transcript.final: The final text transcription of a speech segment.
This pipeline allows, for example, a "wake word" agent to listen for transcript.final events to activate a cognitive agent.
Sources: loom-audio/src/README.md:6-57, 126-134
Application-Level Event Triggers: Market Data
The Market Analyst application showcases how the event-driven architecture can be used for complex, multi-agent workflows triggered by external data streams. In this example, a data_agent listens to a WebSocket for real-time market prices and publishes events like market.price.BTC.
This single event triggers a "fan-out" to multiple specialized analysis agents, which work in parallel. Their results are then aggregated by a planner_agent.
This graph illustrates the multi-agent collaboration in the Market Analyst demo, triggered by a market price event.
This example, while not a "system" trigger in the OS sense, demonstrates the power of the event-driven paradigm that underpins all triggers in Loom.
Sources: apps/market-analyst/README.md:12-20, 150-155
Agent Interaction with Events
Agents interact with the event system primarily through subscriptions. An agent can subscribe to one or more topics to receive relevant events. The SubscribeRequest message defines the parameters for a subscription.
This sequence diagram shows an agent subscribing to a topic and subsequently receiving an event published to that topic.
The SubscribeRequest allows for fine-grained control over event delivery.
| Field | Type | Description |
|---|---|---|
topic | string | The topic to subscribe to (e.g., vad, market.price.*). |
event_types | repeated string | A list of specific event types to receive within the topic. |
qos | QoSLevel | The Quality of Service level (REALTIME, BATCHED, BACKGROUND). |
filters | map<string,string> | Additional key-value filters to apply to event metadata. |
Sources: loom-proto/proto/event.proto:41-46, loom-audio/src/README.md:88-92
Event Observability
The Loom Dashboard provides real-time observability into the event stream, which is crucial for debugging systems based on event triggers. It consumes events from the /api/events/stream endpoint and visualizes the flow of events between agents, the agent network topology, and various metrics. This allows developers to see how a trigger, like a microphone input or a market data update, propagates through the entire system.
Sources: core/src/dashboard/README.md:4-7, 22-25
Summary
System Event Triggers are a cornerstone of the Loom runtime, enabling the creation of sophisticated, long-running AI agents that are deeply integrated with their environment. The architecture is built around a robust, centralized Event Bus that handles everything from low-level system events like audio capture to high-level application events like market data. While many direct OS-level integrations like hotkeys and clipboard monitoring are part of the future roadmap, the existing audio pipeline and application examples demonstrate a powerful and flexible event-driven foundation that sets Loom apart from traditional agent libraries.
Sources: README.md:11-15, ROADMAP.md:4-10