@clone/schema

Single source of truth for cross-stack Clone schemas. Every Clone surface — Desktop, CLI, Mobile, the Django API server, the MCP server — reads from this package. There is no other authoritative place for an event shape.

Layout

packages/schema/
├── events.ts           # canonical TypeScript types for the Recording layer
├── events.schema.json  # JSON Schema mirroring events.ts (for non-TS validators)
├── index.ts            # re-exports
└── package.json        # @clone/schema

events.ts and events.schema.json describe the same wire shape and move together. The Django server (apps/server/recording/views.py) loads events.schema.json at import time and validates every ingested event against it; TypeScript clients import directly from events.ts.

CloneEvent

CloneEvent is a discriminated union over type. Six event types are defined today:

type	Extra fields
session.started	(none)
session.stopped	(none)
app.focused	app: string, window_title: string | null
capture.frame	uri: string, content_hash: string | null, width: number, height: number
agent.prompt	agent: string, prompt: string
agent.response	agent: string, response: string, in_response_to: string | null

Every variant inherits five base fields: id, session_id, occurred_at (ISO-8601), source, type, plus an optional source_detail.

source enum

Value	Modality
desktop	Computer-use trajectory on macOS / Windows / Linux
cli	Terminal sessions
mobile	Smartphone-use trajectory (iOS / Android)
smartglass	Smart-glass-use trajectory (Meta Ray-Ban etc.)
agent	Server-side agent events (Anthropic, OpenAI, …)
integration	Third-party services — source_detail names the provider, and is required for this source

For integration events, source_detail is required and identifies the upstream provider — 'slack', 'notion', 'github', 'linear', 'drive', etc. New integrations add a new source_detail value, not a new source.

Adding a new event type

1. Add the new interface in packages/schema/events.ts and append it to CloneEvent / CLONE_EVENT_TYPES.
2. Mirror the change in packages/schema/events.schema.json (new oneOf entry).
3. Add the matching DRF serializer in apps/server/recording/serializers.py and the type's payload fields to RECORDING_PAYLOAD_FIELDS.
4. Update the Django ingest test in apps/server/recording/tests.py.

For full validation rules and ready-to-paste JSON examples, see Schema.