# Hope unified chat contract — implementation target

This is a coordinated implementation contract, not a deployment receipt.

## Boundary
Hope authenticates and owns product metadata/message projections; Hermes alone reasons and executes tools. No public Hermes credentials/URLs. Private workspaces do not imply tool sandbox isolation. Durable conversation IDs are independent of LiveKit rooms. Auth derives owner, never caller user_id. All public routes use existing cookie/Origin or native bearer authorization.

## JSON shapes
Times: Unix seconds. IDs: opaque strings. snake_case keys. Collections use named envelope and next_cursor (null when exhausted).
Conversation: {id,title,workspace_id:null|string,pinned:bool,pin_rank:int,archived:bool,temporary:bool,revision:int,created_at:float,updated_at:float}. Message: {id,conversation_id,role:user|assistant,content:string,status:pending|streaming|completed|failed|cancelled,run_id:null|string,created_at:float,attachments:[]}. Workspace: {id,name,instructions,revision,created_at,updated_at}. Run: {id,conversation_id,status:queued|running|awaiting_approval|completed|failed|cancelled,message_id,created_at,updated_at,error:null|string}. Preferences: {palette:opal|graphite|ocean|sage|lavender,appearance:system|light|dark,revision:int}.

## Routes
- GET /api/capabilities → {version:1,features:{...},limits:{...}}; availability truthful.
- GET /api/conversations?q=&workspace_id=&archived=false&cursor=&limit= → {conversations:[],next_cursor:null|string}
- POST /api/conversations {title?,workspace_id?,temporary?} → {conversation}
- GET /api/conversations/{id} → {conversation,messages:[],runs:[],next_cursor}
- PATCH /api/conversations/{id} {revision,title?,workspace_id?,pinned?,pin_rank?,archived?} → {conversation}; stale revision409.
- DELETE /api/conversations/{id} → {ok:true}; deletion does not erase account memory.
- POST /api/conversations/{id}/messages {content,idempotency_key,attachment_ids?:[]} →202 {message,run}; repeat same key returns same operation, changed payload409.
- POST /api/conversations/{id}/branch {message_id,content?,title?} → {conversation}; preserve parent history.
- GET /api/runs/{id} → {run,messages:[]}
- GET /api/runs/{id}/events?after=0 → SSE id=monotonic sequence, event=message|run|progress|approval|done, data JSON. Reconnect replays; no hidden reasoning.
- POST /api/runs/{id}/cancel → {run}
- POST /api/runs/{id}/approval {approval_id,decision:approve|deny} → {run}
- GET /api/workspaces → {workspaces:[]}
- POST /api/workspaces {name,instructions?} → {workspace}
- PATCH /api/workspaces/{id} {revision,name?,instructions?} → {workspace}
- DELETE /api/workspaces/{id} → {ok:true}; retain chats outside workspace.
- GET /api/preferences → {preferences}
- PUT /api/preferences {revision,palette,appearance} → {preferences}
- GET /api/sync?after=cursor → {changes:[],cursor:int}; account-owned metadata tombstones.

## Implementation notes
Bounded bodies, ownership validation, offloaded SQLite, redacted errors. Serialize account execution. Revocation must terminate streams and cancel/detach execution according to documented policy. Text needs no LiveKit. Voice joins the same durable conversation/coordinator, not a competing loop. Existing transcript snapshots are not auto-imported as reasoning context.
Advanced attachments/artifacts/tasks/memory/research contracts follow pinned Hermes qualification. Clients cannot fabricate enabled capabilities. Fake adapters offline; real deployment qualification separately.

## Design direction
Personal all-purpose chat on web and native iPhone. Screenshot-inspired desktop sidebar (New chat, Search, Pinned, Workspaces, Recents), quiet readable message column. Existing Opal pink identity default; semantic palettes plus appearance. Native iOS adapts navigation. Preserve focus, contrast, reading position, large text, reduced motion. Shared features ship together.

## Completion
User requests broad parity, full qualification and deployment. Incremental gates are not full completion. Provider/hardware limitations require explicit evidence/scope, not silent substitute features.