Event Reference

Events are validated by AgentEventSchema in packages/event-schema.

Persistence

Events are not the durable source of truth for current agent state. The API applies each event to the relevant Agent, Task, or WorldState document and streams it to connected clients. The events collection is retained only for short-lived telemetry and audit breadcrumbs.

By default, CommonOS persists only error, task_start, and task_complete events. Token usage is aggregated into the compact telemetry_usage rollup collection instead of being stored as raw event history. Noisy or large events such as heartbeat, browser_status, workspace_snapshot, file_changed, world movement, and chat/action previews are handled live and written to the current-state documents instead of being appended to event history.

Set EVENT_PERSISTENCE_MODE=all to keep every event, EVENT_PERSISTENCE_MODE=off to keep none, or PERSIST_EVENT_TYPES=token_usage,error to customize the minimal set. Retained events expire after EVENT_TTL_SECONDS, which defaults to seven days.

To reclaim storage after deploying rollups, backfill existing raw token usage and clear event history:

MONGODB_URI=... node scripts/backfill-telemetry-and-clear-events.mjs

Status

{ "type": "state_change", "payload": { "status": "working" } }

Allowed statuses:

online, idle, working, error, offline

Tasks

{ "type": "task_start", "payload": { "taskId": "tsk_xxx", "description": "Build auth" } }

{ "type": "task_complete", "payload": { "taskId": "tsk_xxx", "output": "Done" } }

Actions

{ "type": "action", "payload": { "label": "Writing API schema", "detail": "api-schema.md" } }

Messages

{ "type": "message_sent", "payload": { "toAgentId": "agt_xxx", "preview": "Schema is ready" } }

{ "type": "message_recv", "payload": { "fromAgentId": "agt_xxx", "preview": "Starting implementation" } }

World

{ "type": "world_move", "payload": { "room": "dev-room", "x": 4, "y": 8 } }

{
  "type": "world_interact",
  "payload": {
    "objectId": "desk-1",
    "action": "typing",
    "room": "dev-room",
    "x": 4,
    "y": 8
  }
}

{
  "type": "world_create_object",
  "payload": {
    "objectId": "artifact-api-schema",
    "objectType": "artifact",
    "room": "dev-room",
    "x": 5,
    "y": 8,
    "label": "API Schema v1"
  }
}

Workspace

{ "type": "file_changed", "payload": { "path": "/workspace/api.ts", "op": "modify" } }

{
  "type": "workspace_snapshot",
  "payload": {
    "rootDir": "/mnt/shared",
    "snapshot": "backend/feed.ts\nbackend/feed.test.md"
  }
}

Health And Errors

{ "type": "heartbeat", "payload": { "runtime": "common-os-daemon", "commitSha": "abc123" } }

{ "type": "error", "payload": { "message": "Runner unavailable" } }

On this page