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.

4.1 KiB Raw Blame History