8000 Voice dictation cannot work on a production start without undocumented env vars (#27) by simon-inkie · Pull Request #58 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 125 additions & 0 deletions .specs/27-voice-proxy-origins/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# #27: Voice dictation cannot work on a production start without undocumented env vars

- Issue: #27
- Branch: 27-voice-proxy-origins
- Started: 2026-10-07

## TL;DR

The voice proxy only accepts WebSocket upgrades from `http://localhost:5174`,
an old dev port, so on a production start (port 4242) the mic fails with a
console WebSocket error. Default the allowlist to Deck's own
`http://localhost:${PORT || 4242}` plus the dev port, document the three
`VOICE_*` variables in `.env.example` and INSTALL.md (including reaching Deck
over Tailscale with `wss://`), and make the mic show "voice disabled: no
DEEPGRAM_API_KEY" when no key is set.

## Scope

In scope:
- `packages/deck/server/voice-relay.mjs` and `voice-proxy.mjs`: compute the
default allowed origins from `PORT`.
- `packages/deck/.env.example`: commented entries for `VOICE_ALLOWED_ORIGINS`,
`VOICE_PROXY_URL`, `VOICE_PROXY_HOST`.
- `INSTALL.md`: voice dictation walkthrough, with the Tailscale case.
- Mic component: a clear disabled state when the key is missing.
- Unit tests for the default-origin computation.

Out of scope (and where it goes instead):
- Anything else in the voice pipeline. See Follow-ups.

## Acceptance

- With only `DEEPGRAM_API_KEY` set, the mic works on a local production start
at port 4242.
- Without it, the mic shows a clear disabled state.
- A test covers the default-origin calculation.

## Test plan

- `test/voice-proxy-origins.test.ts`: pure tests for `defaultAllowedOrigins`
and `resolveAllowedOrigins` (unset, blank, custom `PORT`, `PORT=5174`
de-duplication, explicit override), plus a process test that spawns the real
proxy with only `PORT` set and checks an upgrade from
`http://localhost:4242` is accepted and `http://localhost:4243` is refused.
- `test/voice-server.test.ts`: `getVoiceDisabledReason` and `getVoiceProxyUrl`.
- Repo checks: typecheck, test, boundaries, leaks, licence, lib-version,
dashes.
- Manual, run 2026-10-07 on a real `pnpm build` and `start-production.mjs`
with `PORT` unset: with only `DEEPGRAM_API_KEY` set, the proxy logged
`origins: http://localhost:4242, http://localhost:5174` and a WebSocket
upgrade with `Origin: http://localhost:4242` was accepted. With no key, the
thread page's loader data carried "voice disabled: no DEEPGRAM_API_KEY" and
the rendered page contained the disabled note. Not measured: a real browser
and a real Deepgram session (needs a key and a microphone), and the
Tailscale steps.
- Gates: typecheck, deck tests, boundaries, leaks, licence, lib-version and
dashes pass. `check:leaks:messages` is red from commits already on main, none
of this branch's. `packages/base` has 4 failing shell-suite tests in this
sandbox, unrelated to this change (not touched).

## Decisions log

- 2026-10-07: Branch started from the latest `origin/main`.
- 2026-10-07: The computation lives in `voice-relay.mjs` only, not also in
`voice-relay.ts`. That file already has a hand-kept twin and a cross-copy
suite; adding a third thing to keep in step buys nothing, because the proxy
imports the `.mjs` and the new tests import it directly.
- 2026-10-07: Explicit `VOICE_ALLOWED_ORIGINS` replaces the default rather than
extending it, as before. A blank value now falls back to the default, since
an empty allowlist would reject every upgrade.
- 2026-10-07: Default hosts are `localhost` only. A page opened as
`http://127.0.0.1:4242` sends a different origin and still needs
`VOICE_ALLOWED_ORIGINS`.
- 2026-10-07: "No key" is decided before the browser connects, not by waiting
for the proxy's `no_key` frame, which removes the failed WebSocket attempt
and its console error. Dead end: the first version read the key in the
loader and put the message in `Compose.tsx`, which `test/seam.test.ts`
rejects, because that test bans the key's name from everything under `app/`
(FND-02). Rather than loosen a guard, the launchers (outside `app/`, and the
ones that hand the proxy its key) set `VOICE_DISABLED_REASON` for the app
server when no key is present; the loader passes it on and `Compose` shows it
as given. A start that bypasses the launchers (`pnpm start`, unsupported)
leaves it unset, so the mic behaves as before there. If a maintainer would rather
allow the key name in `app/`, the loader could check it directly.
The proxy's `no_key` frame stays as a fallback.
- 2026-10-07: The Tailscale walkthrough uses `tailscale serve` for both Deck
and the proxy, because the mic needs a secure context and `https://` pages
need `wss://`. The `tailscale serve` flags are written from documentation
and were not run here; INSTALL.md says so.
- 2026-10-07: Corrected the stale voice claims in `INSTALL.md` limitations,
`scripts/start-production.mjs` header and `rig/container-image-note.md`,
which said the three variables were absent from `.env.example`.

## Follow-ups

- `127.0.0.1` and `[::1]` origins are not in the default list.
- `dev.mjs` does not load `packages/deck/.env`, so a key set only there does
not reach the proxy in dev, although `.env.example` says dev reads it.
- `start-production.mjs` could set `VOICE_PROXY_URL` itself from a configured
public origin; left alone.

## Review feedback

### Opus review, 2026-10-07: approve with nits

- Check whether `dev.mjs` decides the reason from the same environment the
proxy gets. Verified: `dev.mjs` does not load `.env` at all (it spreads
`process.env` into `env`, which feeds the app and, via `proxyEnv`, the
proxy), so the two always agree; a key set only in `.env` reaches neither in
dev. That gap is not new and is out of scope, filed under Follow-ups. The
reason is now computed from the same `env` object the child receives, via
the shared helper below. Not run end to end in dev: dev needs a seeded
sandbox and a Vite server; the helper is unit tested instead.
- Trailing slash in `VOICE_ALLOWED_ORIGINS` never matches: fixed, stripped in
`resolveAllowedOrigins`, with a test.
- Disabled note could overlap typed text: fixed, moved out of the textarea box
into its own line below it.
- Process test hardening: fixed. `attempt()` has a 5s timeout, `afterEach`
awaits child exit, `VOICE_PROXY_HOST` is deleted from the child env, stderr
is inherited.
- Message string duplicated in two launchers: fixed, `scripts/voice-env.mjs`
holds the text and the rule; `test/voice-env.test.ts` covers it.
- Component test: added, `test/compose-voice-disabled.test.tsx`.
- Optional `PORT` validation: done, a non-numeric `PORT` falls back to 4242.
- Kept `VOICE_DISABLED_REASON`, as the reviewer recommended.
84 changes: 69 additions & 15 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,68 @@ has not been checked here. On WSL, systemd has to be switched on in
`/etc/wsl.conf`, which recent Ubuntu images already do; that is unverified
here too.

### Voice dictation (optional)

Skip this unless you want the microphone in the compose box. Voice needs a
Deepgram API key and nothing else when the browser runs on the same machine as
Deck. None of the blocks in this section is executed by the rig (see
[How this document is tested](#how-this-document-is-tested)), and they are
tagged `text` for that reason.

**On the machine Deck runs on.** Put the key in `packages/deck/.env`:

```text
DEEPGRAM_API_KEY=your-key-here
```

Start Deck as above and open `http://localhost:4242/`. The launcher prints
`[prod] DEEPGRAM_API_KEY present`. Voice is a second listener on port 5176,
bound to loopback, and it accepts WebSocket upgrades from
`http://localhost:$PORT` (4242 unless you set `PORT`) and the dev port
`http://localhost:5174` with no further settings.

Without a key the microphone is disabled and reads "voice disabled: no
DEEPGRAM_API_KEY". The launcher prints `ABSENT - voice disabled` too.

**From another machine over Tailscale.** The browser sends the address bar's
origin with every WebSocket upgrade, and the proxy rejects any origin it was
not told about. Browsers also refuse the microphone on a page that is not a
secure context, which `http://` over a tailnet address is not, and refuse a
plain `ws://` connection from an `https://` page. So the working shape is
HTTPS for Deck and `wss://` for the proxy, both terminated by `tailscale
serve`, with Deck and the proxy left on loopback:

```text
tailscale serve --bg --https=443 http://127.0.0.1:4242
tailscale serve --bg --https=8443 http://127.0.0.1:5176
```

Then tell the proxy about the origin and the browser about the proxy, where
`<tailnet-host>` is your machine's full tailnet name, as `tailscale status` and
the admin console show it:

```text
VOICE_ALLOWED_ORIGINS=https://<tailnet-host>
VOICE_PROXY_URL=wss://<tailnet-host>:8443/voice
```

Restart the launcher and open `https://<tailnet-host>/`. Note the origin
has no port, because the page is on 443. `VOICE_ALLOWED_ORIGINS` replaces the
default rather than adding to it, so list `http://localhost:4242` as well
(comma-separated) if you also use Deck on the machine itself.
`VOICE_PROXY_HOST` stays unset here: `tailscale serve` reaches the proxy over
loopback. Set it (to `0.0.0.0`, or a specific address) only if something
that is not on this machine must connect to the proxy directly, and remember
the proxy spends your Deepgram key for anyone who is allowed in.

The `tailscale serve` flags vary between Tailscale versions; check `tailscale
serve --help` against the lines above. They have not been run here.

**If the microphone does nothing.** Look at the proxy's output. A line reading
`rejected upgrade from origin "..."` names the exact origin to put in
`VOICE_ALLOWED_ORIGINS`. No line at all means the browser never reached the
proxy, which points at `VOICE_PROXY_URL` or at the proxy's bind address.

## 5. Bring your agents to life

**This tier is manual, and cannot be otherwise from here.** An agent is a
Expand Down Expand Up @@ -692,21 +754,13 @@ image descriptions (Gemini) and web push all need keys, are off without them,
and are not exercised by the rig. They degrade rather than fail: the voice
proxy starts without a key and tells the client it has none.

Voice carries one more thing worth knowing before you reach for it, because
the dev command hides it. Voice is a SECOND listener, on its own port, and
`pnpm dev` configures it for you while `node scripts/start-production.mjs` does
not. In production the proxy keeps its own defaults: it binds `127.0.0.1`
unless `VOICE_PROXY_HOST` says otherwise, it accepts WebSocket upgrades only
from `http://localhost:5174`, which is the dev server's old port and not one
anything here serves by default, and the URL handed to your browser falls back
to `ws://localhost:5176/voice` when `VOICE_PROXY_URL` is unset, which your
browser resolves against the machine YOU are sitting at rather than the one
Deck is on.
10000 So on a production start, voice needs `VOICE_ALLOWED_ORIGINS` and
`VOICE_PROXY_URL` set by hand even on the machine Deck is running on, and
`VOICE_PROXY_HOST` as well to reach it from anywhere else. A rejected upgrade
is logged by the proxy and looks, in the browser, like a microphone that does
nothing. None of those three is in `.env.example` yet.
Voice is a SECOND listener, on its own port, and a few of its settings are not
the app's. See [Voice dictation](#voice-dictation-optional) for the working
setups. The short version: on the machine Deck runs on, `DEEPGRAM_API_KEY` is
enough; anywhere else the proxy needs `VOICE_ALLOWED_ORIGINS` and
`VOICE_PROXY_URL` (and `VOICE_PROXY_HOST` if it is to be reached directly), all
three documented in `.env.example`. A rejected upgrade is logged by the proxy
and looks, in the browser, like a microphone that does nothing.

**Everything here has only ever been measured as root.** The rig's containers
run as root, and not by oversight that could be fixed in passing: the
Expand Down
26 changes: 26 additions & 0 deletions packages/deck/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,32 @@ MC_TMUX_SESSION=
# by the voice proxy and is never sent downstream to a browser.
DEEPGRAM_API_KEY=

# Optional: origins the voice proxy accepts WebSocket upgrades from,
# comma-separated, exact match. Unset or blank = this app's own
# http://localhost:$PORT (4242 unless PORT is set) plus the dev port
# http://localhost:5174, so a local start needs nothing here. Set it when you
# reach Deck by any other name, because the browser sends the page's own origin
# and the proxy rejects the rest (the browser shows a mic that does nothing and
# the proxy logs "rejected upgrade"). Setting it REPLACES the default.
# VOICE_ALLOWED_ORIGINS=http://localhost:4242,https://<tailnet-host>
# VOICE_ALLOWED_ORIGINS=

# Optional: the WebSocket URL handed to the browser for the voice proxy.
# Unset = ws://localhost:5176/voice, which the BROWSER resolves, so it is only
# right when the browser runs on the machine Deck runs on. Reaching Deck from
# another machine needs a URL that machine can reach; over HTTPS it must be
# wss://, since browsers block ws:// from an https page. See INSTALL.md,
# "Voice dictation".
# VOICE_PROXY_URL=wss://<tailnet-host>:8443/voice
# VOICE_PROXY_URL=

# Optional: the address the voice proxy binds. Default 127.0.0.1 (this machine
# only), on purpose: the proxy spends your Deepgram key. Widen it only behind
# something that terminates TLS and limits who can connect, such as
# `tailscale serve`, which can keep the proxy on loopback.
# VOICE_PROXY_HOST=0.0.0.0
# VOICE_PROXY_HOST=

# Optional: comma-separated speech-recognition keyterms, boosting the words
# dictation is most likely to get wrong. THIS IS WHERE YOUR AGENTS' NAMES GO.
# Unset = a built-in default naming the DEMO roster. That default exists so the
Expand Down
52 changes: 39 additions & 13 deletions packages/deck/app/components/Compose.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@
*/
import { useRef, useState, useEffect, useCallback } from "react";
import { useFetcher } from "react-router";
import { FileImage, FileText, Mic, Paperclip, Settings2, X } from "lucide-react";
import { FileImage, FileText, Mic, MicOff, Paperclip, Settings2, X } from "lucide-react";
import { Button } from "./ui/button";
import { Switch } from "./ui/switch";
import type { BatchPrefs, HoldIndicator } from "~/lib/batch-prefs";
Expand Down Expand Up @@ -110,6 +110,12 @@ interface ComposeProps {
* When omitted the mic renders in the unavailable state.
*/
voiceProxyUrl?: string;
/**
* Why voice is off, supplied by the loader (#27), e.g. "voice disabled: no
* <key name>". When set the mic renders disabled with this text instead of
* opening a WebSocket that can only fail. Null or absent means voice is on.
*/
voiceDisabledReason?: string | null;
/**
* When true, mount the voice debug panel and emit debug events.
* Driven by ?debug=1 search param in the thread route (FND-02: pure UI state,
Expand Down Expand Up @@ -520,6 +526,7 @@ export function Compose({
onSent,
onCancel,
voiceProxyUrl,
voiceDisabledReason = null,
debug,
onBatchSubmit,
onBatchType,
Expand Down Expand Up @@ -737,6 +744,15 @@ export function Compose({
debug
);

const voiceEnabled = voiceDisabledReason === null;
const micLabel = voiceDisabledReason !== null
? voiceDisabledReason
: !micAvailable
? "Voice unavailable"
: isActive
? "Stop voice recording"
: "Start voice recording";

// Capture the anchor at the voice-session activation edge; clear on end so
// the next session re-anchors at the then-current cursor. Deliberately NOT
// re-captured as the user types mid-session.
Expand Down Expand Up @@ -1136,7 +1152,8 @@ export function Compose({

<div className="flex items-end gap-2">
{/* Textarea wrapper: mic + attach icons sit inside the border, bottom-right */}
<div className="relative flex-1">
<div className="flex-1">
<div className="relative">
<textarea
id="compose-body"
ref={textareaRef}
Expand Down Expand Up @@ -1181,20 +1198,15 @@ export function Compose({
<Paperclip className={cn("h-5 w-5", uploading ? "animate-pulse" : "")} />
</Button>

{/* Mic button - live when voiceProxyUrl present and mic available */}
{/* Mic button - live when voiceProxyUrl present and mic available;
disabled with an explicit reason when no key is configured (#27). */}
<Button
type="button"
variant="ghost"
size="icon"
disabled={!micAvailable}
aria-label={
!micAvailable
? "Voice unavailable"
: isActive
? "Stop voice recording"
: "Start voice recording"
}
title={!micAvailable ? "Voice unavailable" : isActive ? "Stop voice recording" : "Start voice recording"}
disabled={!voiceEnabled || !micAvailable}
aria-label={micLabel}
title={micLabel}
className="relative h-9 w-9 p-0 min-h-0 min-w-0 text-muted-foreground"
>
data-testid="mic-button"
Expand All @@ -1203,10 +1215,24 @@ export function Compose({
{isActive ? (
<span className="absolute top-0.5 right-0.5 size-1.5 rounded-full bg-primary animate-pulse" />
) : null}
<Mic className={cn("h-5 w-5", isActive ? "text-primary" : "")} />
{voiceEnabled ? (
<Mic className={cn("h-5 w-5", isActive ? "text-primary" : "")} />
) : (
<MicOff className="h-5 w-5" />
)}
</Button>
</div>
</div>
{/* Outside the textarea box so it can never sit over typed text (#27). */}
{!voiceEnabled ? (
<p
className="mt-1 text-xs text-muted-foreground"
data-testid="voice-disabled-note"
>
{voiceDisabledReason}
</p>
) : null}
</div>

{/* Right-hand column: gear above, Send below */}
<div className="flex flex-col items-center gap-1">
Expand Down
17 changes: 17 additions & 0 deletions packages/deck/app/lib/voice.server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,20 @@
export function getVoiceProxyUrl(env: NodeJS.ProcessEnv = process.env): string {
return env["VOICE_PROXY_URL"] ?? "ws://localhost:5176/voice";
}

/**
* Why the mic is disabled, or null when voice is on (issue #27).
*
* This module is under app/, where the speech key's name is banned
* (test/seam.test.ts), so the app never looks at the key. The launchers, which
* live outside app/ and hand the proxy its key, set VOICE_DISABLED_REASON for
* the app server when there is none, and the loader passes it on as display
* text. Unset or blank means voice is on, so a start that bypasses the
* launchers behaves as it did before.
*/
export function getVoiceDisabledReason(
env: NodeJS.ProcessEnv = process.env
): string | null {
const reason = (env["VOICE_DISABLED_REASON"] ?? "").trim();
return reason === "" ? null : reason;
}
Loading
Loading
0