Contracts

Contracts Overview

Every interface that crosses a process, machine, or trust boundary. If you change anything here, change it in the contract first, then in code, then in the tests.

Source of truth in-repo: docs/CONTRACTS.md.

---

Status legend

Status	Meaning
SPEC	Designed, not yet verified against the real thing
VERIFIED	Confirmed against a running service, with a date

---

Contract index

#	Boundary	Transport	Wiki page
1	Bridge ↔ Kiosk	ws://127.0.0.1:8777	Bridge ↔ Kiosk
2	Bridge ↔ Audio	ws://127.0.0.1:8778	Bridge ↔ Audio
3	Bridge → CodeProject.AI	HTTP :32168	CodeProject.AI
4	Bridge → AO via ao_reach	HTTP/WS	AO Reach
5	MCP tools	Hosted HTTP + tunnel	MCP Tools
6	Audio routing	Decision	ADR 0001
7	Config schema	YAML	Configuration
8	Attention state machine	Pure logic	Attention State Machine
9	Kiosk avatar	TalkingHead / HTMLAudio	Kiosk & Avatar
10	Admin console + OAuth	HTTP :8781	Admin Console

---

Shared message envelope

Every local WebSocket message (kiosk and audio), both directions:

{
  "v": 1,
  "id": "msg_01J...",
  "type": "<type>",
  "ts": 1754160000000,
  "turn_id": "t_01J...",
  "data": {}
}

• turn_id is null outside a turn.
• id is a ULID.
• Unknown type is logged and ignored — never fatal. This is how kiosk and bridge ship independently.

---

Dev-mode LAN exception

During development the bridge may run on the Mac and Pi processes connect over the LAN. This binds to the LAN interface instead of loopback, which production must never do.

Three gates, all required:

1. COMSTAR_ENV=dev
2. Config file named comstar.dev.yaml (not comstar.yaml)
3. Matching non-empty dev.lan_token on every connection

A T0 test asserts comstar.example.yaml ships with dev.bind_lan: false.

→ Security · Dev Loop

---

Admin console (:8781/admin) — VERIFIED 2026-08-07

Always-on HTTP in the bridge. Path split: /admin/* (ops), /oauth/google/* (Desktop OAuth, no admin token), /health → /admin/health.

LAN bind for admin is independent of the WS triple-gate (COMSTAR_ADMIN_BIND_LAN + COMSTAR_ADMIN_TOKEN, or admin: in YAML). When LAN-bound with a token, /admin/* needs X-Comstar-Lan-Token or ?token= except GET /admin/health and static assets (.js/.css/.svg/…).

Ops APIs include /admin/api/road, /admin/api/network, /admin/api/ao_mtls. AO health probe uses mTLS client material when enabled. Offline SoftAP feeds admin.qr with hotspot / ssid (ADR 0014).

Full route table and Warpgate notes: Admin Console.

AO Reach session contract (HTTPS + mTLS): Contracts — AO Reach.

---

Related pages

• Architecture
• Admin Console
• Contributing for Agents
• ADR Index