Desktop embed contract and Pairable status for host apps - #52
Draft
jatinkrmalik wants to merge 3 commits into
Draft
Desktop embed contract and Pairable status for host apps#52jatinkrmalik wants to merge 3 commits into
jatinkrmalik wants to merge 3 commits into
Conversation
Freeze the Planned desktop embed contract for VocaMac/VocaWin/VocaLinux, reject loopback PUBLIC_URL overrides from pairing discovery, and add pairable / pairing_url / ready_for_dictation on authenticated status so host apps can show Pair before Ready without reading the bearer token.
✅ Deploy Preview for voca-gateway canceled.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Draft spike for Planned desktop embed of VocaGateway (VocaMac / VocaWin / VocaLinux). Host apps need a frozen pairing and readiness contract before they ship Compose or native launchers.
This PR documents that contract and adds a thin authenticated status surface so a desktop UI can show Pair / QR while a model is still downloading.
Out of scope: idle offload / whisper-server (#50) stays separate and is not folded in.
What desktop apps get
docs/desktop-embed.md: platform matrix (Mac native-primary, Win Compose-primary, Linux podman-first), pair-v1 payload rules, Pairable-before-Ready state machine, Compose pin to release tagv0.1.0, and data-dir ownership underVOCAGATEWAY_DATA_DIR(never under the host app's Application Support).GET /v1/admin/statusnow includespairable,pairing_url(no bearer token), andready_for_dictation.VOCAGATEWAY_PUBLIC_URL/VOCAGATEWAY_PAIRING_URLvalues are dropped from discovery; when no phone-reachable candidate remains, pairing fails loud with the bad env key named in the 503 detail.Clients must keep decoding
payloadfromGET /v1/admin/pairingfor{v,url,token}. Status never carries the secret.Pairable-before-Ready
GET /health/livemeans the process is up.GET /health/readymeans the engine can transcribe. Show Pair / QR when live and a non-loopback pairing URL exists, even if ready is still 503. Dictation waits for Ready; pairing does not.Test plan
pairable/pairing_url/ready_for_dictationwithout expecting a top-level token on statusVOCAGATEWAY_IMAGEto av0.1.0build (or digest), not a invented tagNOTES (known limits)
vocagateway:v0.1.0from the published GitHub Release; a public registry path is not assumed.DiagnosticsBundledoes not mirror the new status fields; desktop should use/v1/admin/status.