TypeBox as protocol source of truth
Last updated: 2026-09-30 TypeBox is a TypeScript-first schema library. We use it to define the Gateway WebSocket protocol (handshake, request/response, server events). Those schemas drive runtime validation, JSON Schema export, and Swift codegen for the macOS app. One source of truth; everything else is generated. If you want the higher-level protocol context, start with Gateway architecture.Mental model (30 seconds)
Every Gateway WS message is one of three frames:- Request:
{ type: "req", id, method, params } - Response:
{ type: "res", id, ok, payload | error } - Event:
{ type: "event", event, payload, seq?, stateVersion? }
connect request. After that, clients can call
methods (e.g. health, send, chat.send) and subscribe to events (e.g.
presence, tick, agent).
Connection flow (minimal):
Authoritative lists live in
src/gateway/server-methods-list.ts (listGatewayMethods() and
GATEWAY_EVENTS).
Where the schemas live
- Source:
src/gateway/protocol/schema.ts, which re-exports the per-area files insrc/gateway/protocol/schema/(the registry isschema/protocol-schemas.ts) - Runtime validators (AJV):
src/gateway/protocol/index.ts - Server handshake:
src/gateway/server/ws-connection/message-handler.ts; method dispatch and scope checks:src/gateway/server-methods.ts - Node client:
src/gateway/client.ts - Committed JSON Schema snapshot:
src/gateway/protocol/gateway-protocol.schema.json. The root carriesx-protocol-version(thePROTOCOL_VERSIONnumber) andx-error-codes(theErrorCodesvalues), and every nested position that reuses a named definition carriesx-schema-nameso non-TypeScript generators can name shared types. The npm tarball ships the same file atdist/contracts/gateway-protocol.schema.json, alongside the exec and system-run parity fixtures underdist/contracts/fixtures/(used by the native apps’ parity tests). - Generated Swift models: owned by the
WednesdayAI-apps repository, which regenerates
them from the synced snapshot (
npm run contracts:sync).
Current pipeline
pnpm protocol:gen- writes JSON Schema (draft‑07) to
src/gateway/protocol/gateway-protocol.schema.json
- writes JSON Schema (draft‑07) to
pnpm protocol:check- regenerates the snapshot and verifies it is committed
- Swift gateway models are generated in WednesdayAI-apps from the synced snapshot, not in core.
How the schemas are used at runtime
- Server side: every inbound frame is validated with AJV. The handshake only
accepts a
connectrequest whose params matchConnectParams. - Client side: the JS client validates event and response frames before using them.
- Method surface: the Gateway advertises the supported
methodsandeventsinhello-ok.
Example frames
Connect (first message):Minimal client (Node.js)
Smallest useful flow: connect + health.Worked example: add a method end‑to‑end
Example: add a newsystem.echo request that returns { ok: true, text }.
- Schema (source of truth)
src/gateway/protocol/schema/ (here a new system-echo.ts, re-exported
from src/gateway/protocol/schema.ts):
ProtocolSchemas in schema/protocol-schemas.ts and export types:
- Validation
src/gateway/protocol/index.ts, export an AJV validator:
- Server behavior
src/gateway/server-methods/system.ts:
src/gateway/server-methods.ts (already merges systemHandlers), add
"system.echo" to BASE_METHODS in src/gateway/server-methods-list.ts, and classify it in
src/gateway/method-scopes.ts (METHOD_SCOPE_GROUPS). A method with no scope needs
operator.admin, and a test fails if an advertised method is unclassified. The narrow
operator.sessions.* web client can call a method only if it is also listed in
NARROW_SESSION_READ_METHODS or NARROW_SESSION_WRITE_METHODS, which is an ADR 0077 amendment; a
rule that depends on the call’s params (like the sessions.patch field guard) is ADR 0083.
- Regenerate
- Tests + docs
src/gateway/server.*.test.ts and note the method in docs.
Swift codegen behavior
Swift codegen lives in the WednesdayAI-apps repository. Its generator reads the synced schema snapshot and emits:GatewayFrameenum withreq,res,event, andunknowncases- Strongly typed payload structs/enums (named via
x-schema-namefor reused definitions) ErrorCodevalues andGATEWAY_PROTOCOL_VERSION(fromx-protocol-versionandx-error-codes)
Versioning + compatibility
PROTOCOL_VERSIONis defined insrc/gateway/protocol/schema/protocol-schemas.tsand exported fromsrc/gateway/protocol/schema.ts.- Clients send
minProtocol+maxProtocol; the server rejects mismatches. - The Swift models keep unknown frame types to avoid breaking older clients.
Schema patterns and conventions
- Most objects use
additionalProperties: falsefor strict payloads. NonEmptyStringis the default for IDs and method/event names.- The top-level
GatewayFrameuses a discriminator ontype. - Methods with side effects usually require an
idempotencyKeyin params (example:send,poll,agent,chat.send). agentaccepts optionalinternalEventsfor runtime-generated orchestration context (for example subagent/cron task completion handoff); treat this as internal API surface.
Live schema JSON
The committed snapshot issrc/gateway/protocol/gateway-protocol.schema.json in this repository.
The published npm package ships the same file at dist/contracts/gateway-protocol.schema.json
plus the exec and system-run parity fixtures under dist/contracts/fixtures/; native clients
read both from there (WednesdayAI-apps syncs them with npm run contracts:sync).
When you change schemas
- Update the TypeBox schemas.
- Run
pnpm protocol:check. - Commit the regenerated schema snapshot. Swift models are not generated here: WednesdayAI-apps
picks them up through its
contracts:syncflow (a weekly bot PR against the pinned core version).