Shared Protocol Schemas
Relevant source files
The following files were used as context for generating this wiki page:
Shared Protocol Schemas (contained in the @magic-agent/protocol package) serve as the single source of truth for all API types and communication protocols within the Happy ecosystem. By utilizing Zod for runtime validation and TypeScript for static typing, this module ensures consistency across the project's diverse consumers, including the Node.js CLI, Fastify server, React Native mobile app, and Cloudflare Workers.
The architecture is designed to prevent schema drift—a historical issue where duplicated types led to inconsistencies such as varied session ID field names. The package provides a unified definition for persistent updates (state changes), ephemeral events (real-time status), and payload wrappers.
Sources: packages/schema/protocol/README.md, packages/schema/protocol/CLAUDE.md, knowledge.md:21-25
Architecture and Data Flow
The protocol acts as a contract between the primary system components. All communication, which is end-to-end encrypted via TweetNaCl, must conform to these schemas before processing.
The diagram above illustrates how the shared protocol package provides validation and typing to every major application in the monorepo.
Sources: knowledge.md:34-45, packages/schema/protocol/CLAUDE.md
Core Schema Categories
The protocol is divided into three primary categories based on the lifecycle and persistence of the data.
1. Persistent Updates
These represent state changes that are stored in the database and synchronized across devices to maintain a consistent application state.
| Schema Name | Discriminator (t) | Purpose |
|---|---|---|
ApiUpdateNewSessionSchema | new-session | Notification of a newly created session. |
ApiUpdateNewMessageSchema | new-message | New encrypted message delivered to a session. |
ApiUpdateSessionStateSchema | update-session | Changes to session metadata or status. |
ApiNewMachineSchema | new-machine | Registration of a new CLI agent/machine. |
ApiNewArtifactSchema | new-artifact | Creation of a new file or artifact in a session. |
Sources: packages/schema/protocol/README.md, packages/schema/protocol/coverage/src/updates/index.ts.html:49-63
2. Ephemeral Events
These are transient, real-time events that provide immediate feedback but do not require long-term persistence.
| Schema Name | Discriminator (type) | Purpose |
|---|---|---|
ApiEphemeralActivityUpdateSchema | activity | Real-time session activity status. |
ApiEphemeralUsageUpdateSchema | usage | Token or cost usage updates. |
ApiEphemeralMachineStatusUpdateSchema | machine-status | Online/Offline status for machines. |
Sources: packages/schema/protocol/README.md, packages/schema/protocol/scripts/extract-schemas.ts:89-95
3. Payload Wrappers
Containers used for WebSocket message sequencing and wire-format encapsulation.
Design Patterns and Conventions
Versioned Values
For optimistic concurrency control, the protocol utilizes a VersionedValue pattern. This ensures that state updates are applied in the correct order and prevents stale data from overwriting newer updates.
import { VersionedValueSchema, NullableVersionedValueSchema } from '@magic-agent/protocol';
// Usage in an object schema
const MetadataSchema = z.object({
title: z.string(),
state: VersionedValueSchema, // Non-nullable versioned field
agentState: NullableVersionedValueSchema // Nullable versioned field
});
Sources: packages/schema/protocol/CLAUDE.md, packages/schema/protocol/scripts/extract-schemas.ts:57-58
Naming Inconsistencies (HAP-383 Legacy)
While the protocol aims for standardization, certain historical inconsistencies are preserved for backward compatibility.
- Discriminator Fields: Persistent updates use
t, while ephemeral events usetype. - ID Mapping: Session IDs are referenced as
idinnew-sessionupdates but assidinmessageupdates. - Machine IDs: Consistently use
machineIdacross all schemas.
Sources: packages/schema/protocol/README.md, knowledge.md:65-71
Schema Drift and Validation
To ensure the server's OpenAPI implementation matches the client expectations, the project employs a drift detection system.
The extract-schemas.ts script converts Zod schemas into JSON Schema format, which compare-schemas.ts then validates against the generated server OpenAPI specification.
Sources: packages/schema/protocol/scripts/extract-schemas.ts, scripts/compare-schemas.ts:18-35
Conclusion
Shared Protocol Schemas provide the structural foundation for the Happy ecosystem. By centralizing type definitions and validation logic in @magic-agent/protocol, the project maintains high technical accuracy across different languages (TypeScript and Swift) and runtime environments. This centralized approach reduces bugs related to field naming and ensures that end-to-end encrypted data maintains its integrity throughout the lifecycle of a session.
Sources: packages/schema/protocol/README.md, packages/schema/protocol/CLAUDE.md