conductor-remote 1.117.0 → 1.118.0

package/dist-node/src/http/routes/state.js

@@ -0,0 +1,186 @@
+import { isDefaultEffortLevel, readDefaultEfforts, writeDefaultEfforts } from "../../agents/conductor-settings.js";
+import { decodeRoles, roleModelIssues } from "../../agents/roles.js";
+import { attachRunActivity } from "../../dev-server/run-activity.js";
+import { attachChangeStats } from "../../git/change-stats.js";
+import { attachPrStatus } from "../../git/pr.js";
+import { updateStatus } from "../../host/autoupdate.js";
+import { isRoute, routes } from "../../routes.js";
+import { foldHits, queryTokens } from "../../search/coordinator.js";
+import { scrubWorkflowSecrets } from "../../shared.js";
+import { isToolUsageRange } from "../../usage/tool-usage.js";
+import { describeActuator } from "../../writes/actuator.js";
+import { NOT_HANDLED } from "../router-types.js";
+export function createStateRoutes(services) {
+    const { reads, attachDelegationState, attachWorkflowState, wireUiQuarantine, parkedPrompts, firstPrompts, json, orchestration, orchestrationUnavailableReason, actuator, search, modelCache, readBody, planUsage, toolUsage, roleStore } = services;
+    return async (req, res, url) => {
+        const { pathname } = url;
+        // GET /api/state — workspace list with active-session status
+        if (isRoute(routes.state, req.method, pathname)) {
+            const update = updateStatus();
+            const workspaces = reads.listWorkspaces();
+            attachChangeStats(workspaces); // serves the cache now; refreshes stale git stats in the background
+            attachPrStatus(workspaces); // colours pr_status from cache; refreshes stale entries in the background
+            attachRunActivity(workspaces); // flags a live Run wrapper from a cached ps snapshot
+            attachDelegationState(workspaces);
+            const workflows = attachWorkflowState(workspaces);
+            const uiQuarantine = wireUiQuarantine();
+            // An undelivered first prompt rides along with its workspace: the phone renders it
+            // in that chat rather than tracking delivery itself (see src/delivery/firstprompt.ts).
+            // Prompts parked for the lock screen ride the same way, one list per workspace,
+            // each entry naming its chat (src/delivery/parked.ts).
+            const parked = parkedPrompts.list();
+            for (const ws of workspaces) {
+                ws.pending_prompt = firstPrompts.get(ws.id);
+                const mine = parked.filter(p => p.workspaceId === ws.id);
+                if (mine.length)
+                    ws.parked_prompts = mine;
+            }
+            return json(req, res, 200, {
+                workspaces,
+                workflows,
+                ...(uiQuarantine ? { uiQuarantine } : {}),
+                ...(orchestration.writable
+                    ? {}
+                    : { workflowWarning: scrubWorkflowSecrets(orchestrationUnavailableReason()).slice(0, 500) }),
+                actuator: await describeActuator(actuator),
+                version: update.current,
+                update
+            });
+        }
+        // GET /api/search?q= — find a workspace by its name or by what was said in its chats.
+        //
+        // Two sources, merged. `findWorkspacesByName` matches the workspace's own identity
+        // and wins ties, because someone who types a name wants that workspace and not the
+        // twelve chats that mention it. The transcript index answers the harder question —
+        // "which workspace did I do this in" — and is the only one that can, since the
+        // words you remember are usually the agent's, not the branch's.
+        //
+        // Both reach archived workspaces. That is the point: 1,846 of the 1,886 here are
+        // archived, so a search limited to the live sidebar would miss almost everything.
+        //
+        // `repo=` (repeatable) and `archived=0` scope both halves. They are resolved to
+        // chat ids and pushed *into* the FTS query rather than applied to its top 300
+        // chunks, or excluded work would fill every slot (src/search/coordinator.ts ▸ search).
+        if (isRoute(routes.search, req.method, pathname)) {
+            const q = url.searchParams.get('q') ?? '';
+            const repos = [...new Set(url.searchParams.getAll('repo').filter(Boolean))];
+            // Archived search predates the toggle and stays the default for cached PWAs and MCP.
+            const includeArchived = url.searchParams.get('archived') !== '0';
+            // 12, not 50: an OR query over common words ("add", "remove") has a long weak tail,
+            // and past the first screenful nobody scrolls — they retype instead.
+            const limit = Math.min(50, Math.max(1, Number(url.searchParams.get('limit') ?? 12) || 12));
+            const index = search.status();
+            const tokens = queryTokens(q);
+            if (!tokens.length)
+                return json(req, res, 200, { query: q, repos, results: [], index });
+            const scoped = repos.length > 0 || !includeArchived;
+            const scope = scoped
+                ? { sessionIds: reads.searchSessionIds(repos.length ? repos : undefined, includeArchived) }
+                : {};
+            const hits = await search.search(q, scope);
+            const targets = reads.searchTargets([...new Set(hits.map(h => h.sessionId))]);
+            const fromChats = foldHits(hits, sid => {
+                const workspace = targets.get(sid)?.workspace ?? null;
+                return !includeArchived && workspace?.archived ? null : workspace;
+            });
+            const remaining = new Map(fromChats.map(r => [r.workspace.id, r]));
+            const merged = [];
+            for (const workspace of reads.findWorkspacesByName(tokens, limit, repos.length ? repos : undefined, includeArchived)) {
+                const evidence = remaining.get(workspace.id);
+                remaining.delete(workspace.id);
+                // Keep the chat evidence when there is any: the snippet is what tells you this
+                // is the right "fix-lamp-thing" out of three with similar names.
+                merged.push(evidence
+                    ? { ...evidence, byName: true }
+                    : { workspace, sessionId: null, hits: 0, score: 0, at: null, snippets: [], byName: true });
+            }
+            merged.push(...remaining.values());
+            return json(req, res, 200, {
+                query: q,
+                repos,
+                index,
+                results: merged.slice(0, limit).map(r => ({
+                    ...r,
+                    sessionTitle: r.sessionId ? (targets.get(r.sessionId)?.sessionTitle ?? null) : null
+                }))
+            });
+        }
+        // GET /api/repos — repos a new workspace can be created in
+        if (isRoute(routes.repos, req.method, pathname)) {
+            return json(req, res, 200, { repos: reads.listRepos() });
+        }
+        // GET /api/models — prior live picker reads, without activating Conductor. A
+        // new workspace has no chat yet, so this is its only safe source of choices.
+        if (isRoute(routes.modelCatalog, req.method, pathname)) {
+            return json(req, res, 200, { groups: modelCache.list(), defaultModel: modelCache.defaultModel() });
+        }
+        // GET/PATCH /api/models/defaults — the live user-wide effort defaults.
+        // These are file-backed settings, not the stale rows conductor.db still carries.
+        if (isRoute(routes.modelDefaults, req.method, pathname)) {
+            return json(req, res, 200, { defaultEfforts: readDefaultEfforts() });
+        }
+        if (isRoute(routes.updateModelDefaults, req.method, pathname)) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const patch = {};
+            if (body.claude !== undefined) {
+                if (!isDefaultEffortLevel(body.claude))
+                    return json(req, res, 400, { error: 'unknown Claude effort level' });
+                patch.claude = body.claude;
+            }
+            if (body.codex !== undefined) {
+                if (!isDefaultEffortLevel(body.codex))
+                    return json(req, res, 400, { error: 'unknown Codex effort level' });
+                patch.codex = body.codex;
+            }
+            if (Object.keys(patch).length === 0)
+                return json(req, res, 400, { error: 'nothing to change' });
+            return json(req, res, 200, { defaultEfforts: writeDefaultEfforts(patch) });
+        }
+        // GET /api/usage — structured subscription limits from the CLIs Conductor
+        // itself bundles. Both reads are prompt-free and cached; `refresh=1` is the
+        // explicit user action in the sheet, never a background poll.
+        if (isRoute(routes.planUsage, req.method, pathname)) {
+            return json(req, res, 200, await planUsage.read(url.searchParams.get('refresh') === '1'));
+        }
+        if (isRoute(routes.toolUsage, req.method, pathname)) {
+            const range = url.searchParams.get('range') ?? '24h';
+            if (!isToolUsageRange(range))
+                return json(req, res, 400, { error: 'Choose 24h, 7d, or 30d for tool usage.' });
+            return json(req, res, 200, await toolUsage.read(range, url.searchParams.get('refresh') === '1'));
+        }
+        if (isRoute(routes.roles, req.method, pathname)) {
+            const stored = roleStore.read();
+            return json(req, res, 200, {
+                ...stored.config,
+                issues: roleModelIssues(stored.config, modelCache.list()),
+                ...(stored.warning ? { warning: stored.warning } : {})
+            });
+        }
+        if (isRoute(routes.updateRoles, req.method, pathname)) {
+            let config;
+            try {
+                config = decodeRoles(JSON.parse((await readBody(req)) || '{}'));
+            }
+            catch (err) {
+                const error = {
+                    code: 'invalid_request',
+                    message: err instanceof Error ? err.message : String(err),
+                    retryable: false
+                };
+                return json(req, res, 400, { ok: false, error });
+            }
+            const issues = roleModelIssues(config, modelCache.list());
+            if (issues.length)
+                return json(req, res, 409, { ok: false, error: issues[0].error, issues });
+            const written = roleStore.write(config);
+            if (!written.ok) {
+                return json(req, res, 500, {
+                    ok: false,
+                    error: { code: 'state_invalid', message: written.error, retryable: true }
+                });
+            }
+            return json(req, res, 200, { ok: true, config: written.config });
+        }
+        return NOT_HANDLED;
+    };
+}

package/dist-node/src/http/routes/system.js

@@ -0,0 +1,220 @@
+import { discardStagedAttachment, stageAttachment } from "../../files/staged-attachments.js";
+import { isManaged, LOG_FILE_NAMES, logFiles, processStartedAt, recentLogs, redactSecrets, tailLogFile } from "../../host/logbuf.js";
+import { armNoSleep, disarmNoSleep, MAX_SECONDS as NOSLEEP_MAX_SECONDS, nosleepState } from "../../host/nosleep.js";
+import { autoJoinHotspotMode, currentSsid, looksLikeHotspot, preferredNetworks } from "../../host/wifi.js";
+import { notifyDevice, pushConfig, subscribeDevice, unsubscribeDevice } from "../../notifications/notify.js";
+import { readPrefs, writePrefs } from "../../prefs.js";
+import { isRoute, routeParam, routes } from "../../routes.js";
+import { readSettings, writeSettings } from "../../settings.js";
+import { screenLocked } from "../../writes/guards.js";
+import { restartConductorApp } from "../../writes/system.js";
+import { NOT_HANDLED } from "../router-types.js";
+export function createSystemRoutes(services) {
+    const { json, readBody, cfg, reads, attachmentHeaderName, readAttachmentBody, STAGED_ATTACHMENTS_DIR } = services;
+    return async (req, res, url) => {
+        const { pathname } = url;
+        // GET /api/settings — relay preferences plus what the phone needs to edit them:
+        // the SSIDs this Mac already holds credentials for, so the picker offers a choice
+        // instead of asking someone to type a network name from memory on a phone keyboard.
+        // `ssid` is best-effort and often null (macOS gates it behind Location Services).
+        if (isRoute(routes.settings, req.method, pathname)) {
+            // Five subprocesses, all concurrent: this is the one route that shells out more
+            // than once, and serialising them would put the phone's polls behind the sum.
+            const [known, current, autoJoinHotspot, nosleep, locked] = await Promise.all([
+                preferredNetworks(),
+                currentSsid(),
+                // macOS's own Auto-join Hotspot setting. On "Never" the Mac won't reach for
+                // your phone unprompted, which no amount of relay code can substitute for.
+                autoJoinHotspotMode(),
+                nosleepState(),
+                // Read here rather than polled: this sheet is where someone goes when the Mac
+                // stopped answering, and a keep-awake window that says "automatic screen lock
+                // is off" beside a Mac that is locked right now reads as the relay lying. The
+                // assertion blocks the *idle* lock; it cannot lift one already up, and a lid
+                // close or a manual lock puts one up whatever it holds.
+                screenLocked()
+            ]);
+            return json(req, res, 200, {
+                settings: readSettings(),
+                wifi: {
+                    current,
+                    known,
+                    // A guess from the name, never a fact — see src/host/wifi.ts. It only sorts the picker.
+                    likelyHotspots: known.filter(looksLikeHotspot),
+                    autoJoinHotspot
+                },
+                nosleep: { ...nosleep, maxSeconds: NOSLEEP_MAX_SECONDS },
+                screenLocked: locked
+            });
+        }
+        // PATCH /api/settings { fallbackSsids?, autoRejoin? } — merge and persist.
+        if (isRoute(routes.updateSettings, req.method, pathname)) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const patch = {};
+            if (Array.isArray(body.fallbackSsids))
+                patch.fallbackSsids = body.fallbackSsids;
+            if (typeof body.autoRejoin === 'boolean')
+                patch.autoRejoin = body.autoRejoin;
+            if (Object.keys(patch).length === 0)
+                return json(req, res, 400, { error: 'nothing to change' });
+            return json(req, res, 200, { settings: writeSettings(patch) });
+        }
+        // PWA state remains local-first; this host copy survives origin changes and
+        // reconciles phones. PATCH accepts a full client snapshot and merges per key.
+        if (isRoute(routes.prefs, req.method, pathname)) {
+            return json(req, res, 200, { prefs: readPrefs() });
+        }
+        if (isRoute(routes.updatePrefs, req.method, pathname)) {
+            const raw = JSON.parse((await readBody(req)) || '{}');
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                return json(req, res, 400, { error: 'preferences must be an object' });
+            }
+            const body = raw;
+            if (!Object.hasOwn(body, 'readMarks') && !Object.hasOwn(body, 'drafts')) {
+                return json(req, res, 400, { error: 'nothing to sync' });
+            }
+            return json(req, res, 200, { prefs: writePrefs(body) });
+        }
+        // GET /api/nosleep — is the Mac being held awake, and can this relay do it at all
+        if (isRoute(routes.nosleep, req.method, pathname)) {
+            return json(req, res, 200, { ...(await nosleepState()), maxSeconds: NOSLEEP_MAX_SECONDS });
+        }
+        // POST /api/nosleep { seconds } — hold this Mac awake, lid closed, for a bounded window.
+        // Only works once `conductor-remote nosleep setup` has installed the scoped sudoers
+        // rule; without it there is no way for a TTY-less daemon to reach root, and the
+        // response says so rather than failing vaguely.
+        if (isRoute(routes.armNoSleep, req.method, pathname)) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const seconds = Number(body.seconds);
+            // Whole seconds, not just "> 0": the helper reads 0 as "until killed", and 0.4
+            // truncates to 0 — an unbounded window from a request that looked bounded.
+            if (!Number.isInteger(seconds) || seconds < 1)
+                return json(req, res, 400, { error: 'need a whole number of seconds >= 1' });
+            const result = await armNoSleep(seconds, cfg.preventScreenLock);
+            return json(req, res, result.ok ? 200 : result.state.available ? 502 : 409, result);
+        }
+        // DELETE /api/nosleep — let it sleep again now, rather than at the window's end
+        if (isRoute(routes.disarmNoSleep, req.method, pathname)) {
+            const result = await disarmNoSleep();
+            return json(req, res, result.ok ? 200 : result.state.available ? 502 : 409, result);
+        }
+        // POST /api/conductor/restart { stopAgents? } — quit Conductor and start it again.
+        //
+        // The lever exists in the actuator already, but only as activateConductor's last
+        // resort, which fires exclusively for a *windowless* Conductor. This is for the
+        // other shape: window up, prompts landing as rows, and no agent output behind any
+        // of it (measured 2026-09-02 — 2h35m of user rows after the last agent frame).
+        // The running agents are counted from the DB before the UI is touched and refused
+        // unless the caller meant it, the same way archiving is: quitting ends every turn
+        // in flight. The lock screen is the actuator's own gate, since only it can ask.
+        if (isRoute(routes.restartConductor, req.method, pathname)) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const working = reads.listSessionStates().filter(state => state.status === 'working').length;
+            if (working > 0 && body.stopAgents !== true) {
+                return json(req, res, 409, {
+                    ok: false,
+                    agentsRunning: true,
+                    working,
+                    error: `${working} chat${working === 1 ? ' is' : 's are'} mid-turn. Restarting Conductor ends ${working === 1 ? 'it' : 'them'}.`
+                });
+            }
+            const startedAt = Date.now();
+            const result = await restartConductorApp();
+            const ms = Date.now() - startedAt;
+            if (!result.ok) {
+                console.warn(`[restart] Conductor restart failed after ${(ms / 1000).toFixed(1)}s: ${result.error}`);
+                return json(req, res, 502, { ok: false, ms, error: result.error });
+            }
+            console.log(`[restart] quit Conductor and relaunched it in ${(ms / 1000).toFixed(1)}s`);
+            return json(req, res, 200, { ok: true, ms });
+        }
+        // GET /api/logs?file=&limit= — the relay's own log, so a phone can diagnose a failed send
+        // without reaching the Mac. Default is this process's captured console (ordered, timestamped);
+        // `file` tails the daemon's stdout/stderr on disk, which is the only place the *previous*
+        // process's crash survives. Everything is redacted: the startup banner prints the token.
+        if (isRoute(routes.logs, req.method, pathname)) {
+            const file = url.searchParams.get('file');
+            if (file && !LOG_FILE_NAMES.includes(file)) {
+                return json(req, res, 404, { error: `unknown log file ${file}`, files: LOG_FILE_NAMES });
+            }
+            const asked = Number(url.searchParams.get('limit') ?? 300);
+            const limit = Number.isFinite(asked) ? Math.min(2000, Math.max(1, Math.trunc(asked))) : 300;
+            let entries;
+            try {
+                entries = file ? tailLogFile(file, limit) : recentLogs(limit);
+            }
+            catch (err) {
+                // The file only exists once the LaunchAgent has run; say so instead of a bare 500.
+                return json(req, res, 404, { error: `can’t read ${file}: ${err instanceof Error ? err.message : err}` });
+            }
+            return json(req, res, 200, {
+                source: file ?? 'live',
+                // False → the files below are some *other* (daemon) process's output, not this relay's.
+                managed: isManaged(),
+                startedAt: processStartedAt(),
+                now: Date.now(),
+                files: logFiles(),
+                entries: entries.map(e => ({ ...e, text: redactSecrets(e.text, cfg.token) }))
+            });
+        }
+        // GET /api/push — the VAPID public key the phone subscribes with, plus who's already subscribed
+        if (isRoute(routes.push, req.method, pathname)) {
+            return json(req, res, 200, pushConfig());
+        }
+        // POST /api/push/subscribe { subscription, label? } — register (or refresh) this device.
+        // Idempotent by endpoint: the app re-sends on every load, which is what heals a relay that
+        // lost its store, or a subscription the browser silently renewed.
+        if (isRoute(routes.pushSubscribe, req.method, pathname)) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const sub = body.subscription;
+            if (!sub?.endpoint || !sub.keys?.p256dh || !sub.keys.auth) {
+                return json(req, res, 400, { error: 'need a subscription with endpoint and keys' });
+            }
+            // An endpoint is a URL we will POST to — never accept a non-HTTPS one.
+            if (!/^https:\/\//i.test(sub.endpoint))
+                return json(req, res, 400, { error: 'endpoint must be https' });
+            const registered = subscribeDevice({ endpoint: sub.endpoint, keys: { p256dh: sub.keys.p256dh, auth: sub.keys.auth } }, (body.label ?? '').slice(0, 64));
+            return json(req, res, 200, { ok: true, ...registered });
+        }
+        // POST /api/push/unsubscribe { endpoint } — the phone turned notifications off
+        if (isRoute(routes.pushUnsubscribe, req.method, pathname)) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            if (!body.endpoint)
+                return json(req, res, 400, { error: 'need the endpoint' });
+            return json(req, res, 200, { ok: unsubscribeDevice(body.endpoint), devices: pushConfig().devices });
+        }
+        // POST /api/push/test { id } — push to one device, so "is this actually wired up?" has an answer
+        if (isRoute(routes.pushTest, req.method, pathname)) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            if (!body.id)
+                return json(req, res, 400, { error: 'need the device id' });
+            const result = await notifyDevice(body.id, {
+                title: 'Conductor Remote',
+                body: 'Notifications are working. You’ll get one when an agent finishes.',
+                tag: 'test',
+                url: '/',
+                kind: 'test',
+                ts: Date.now()
+            });
+            return json(req, res, result.ok ? 200 : 502, result);
+        }
+        // POST /api/attachments — hold one phone file until its new workspace has a worktree.
+        if (isRoute(routes.stageAttachment, req.method, pathname)) {
+            const name = attachmentHeaderName(req);
+            if (!name)
+                return json(req, res, 400, { error: 'missing attachment name' });
+            const bytes = await readAttachmentBody(req);
+            if (!bytes.length)
+                return json(req, res, 400, { error: 'empty attachment' });
+            const attachment = stageAttachment(STAGED_ATTACHMENTS_DIR, name, bytes);
+            return json(req, res, 201, { ok: true, attachment });
+        }
+        // DELETE /api/attachments/:id — an upload cancelled before it became a synced draft attachment.
+        const stagedAttachment = routeParam(routes.discardStagedAttachment, req.method, pathname);
+        if (stagedAttachment)
+            return json(req, res, discardStagedAttachment(STAGED_ATTACHMENTS_DIR, stagedAttachment) ? 200 : 404, {
+                ok: true
+            });
+        return NOT_HANDLED;
+    };
+}

package/dist-node/src/http/routes/voice.js

@@ -0,0 +1,117 @@
+import { isRoute, routeParam, routes } from "../../routes.js";
+import { isOpenAIRealtimeVoice, isVoiceLanguage, OPENAI_REALTIME_VOICES } from "../../shared.js";
+import { openAIOriginForSipHost } from "../../voice/config.js";
+import { parseVoiceCallTarget, readVoiceChatContext, VoiceContextError } from "../../voice/context.js";
+import { MAX_VOICE_SEARCH_CHARS } from "../../voice/history.js";
+import { mintSipTicket, missingTicketConfig } from "../../voice/ticket.js";
+import { createWebRtcCall, MAX_SDP_CHARS } from "../../voice/webrtc.js";
+import { NOT_HANDLED } from "../router-types.js";
+export function createVoiceRoutes(services) {
+    const { json, voiceHistory, voiceConfig, voiceBroker, readBody, reads, voiceSafetyIdentifier } = services;
+    return async (req, res, url) => {
+        const { pathname } = url;
+        const voiceTranscript = routeParam(routes.voiceTranscript, req.method, pathname);
+        if (isRoute(routes.voiceHistory, req.method, pathname) ||
+            isRoute(routes.voiceSearch, req.method, pathname) ||
+            voiceTranscript) {
+            try {
+                if (isRoute(routes.voiceSearch, req.method, pathname)) {
+                    const query = url.searchParams.get('q')?.trim() ?? '';
+                    if (!query || query.length > MAX_VOICE_SEARCH_CHARS)
+                        return json(req, res, 400, { error: `q must contain 1–${MAX_VOICE_SEARCH_CHARS} characters` });
+                    return json(req, res, 200, voiceHistory.search(query, {
+                        limit: Math.max(1, Math.min(50, Number(url.searchParams.get('limit')) || 12)),
+                        offset: Math.max(0, Math.min(1_000_000, Number(url.searchParams.get('offset')) || 0)),
+                        callId: url.searchParams.get('callId') || undefined
+                    }));
+                }
+                if (!voiceTranscript) {
+                    const limit = Math.max(1, Math.min(100, Number(url.searchParams.get('limit')) || 30));
+                    const offset = Math.max(0, Math.min(1_000_000, Number(url.searchParams.get('offset')) || 0));
+                    return json(req, res, 200, voiceHistory.list(Math.floor(limit), Math.floor(offset)));
+                }
+                const call = url.searchParams.get('summary') === '1'
+                    ? voiceHistory.status(voiceTranscript)
+                    : voiceHistory.read(voiceTranscript);
+                return call ? json(req, res, 200, call) : json(req, res, 404, { error: 'Saved voice call not found' });
+            }
+            catch (error) {
+                console.warn('[voice] could not read call history:', error);
+                return json(req, res, 503, { error: 'Call history is unavailable. Check the relay logs.' });
+            }
+        }
+        // POST /api/voice/ticket — the native app presents the same relay bearer as
+        // the PWA, and receives only a two-minute SIP URI. The OpenAI key, webhook
+        // secret and marker key never leave this Mac.
+        if (isRoute(routes.voiceTicket, req.method, pathname)) {
+            const missing = missingTicketConfig(voiceConfig);
+            if (missing.length || !voiceBroker) {
+                return json(req, res, 503, {
+                    error: 'voice calls are not fully configured on this relay',
+                    missing
+                });
+            }
+            return json(req, res, 200, mintSipTicket(voiceConfig));
+        }
+        // POST /api/voice/calls — the PWA sends its SDP offer to this authenticated
+        // relay. The relay loads the selected chat context or the fleet session and
+        // keeps OpenAI's permanent key and every function tool on the Mac.
+        if (isRoute(routes.voiceCall, req.method, pathname)) {
+            if (!voiceConfig.openaiKey || !voiceBroker)
+                return json(req, res, 503, { error: 'voice needs an OpenAI API key on this relay' });
+            const raw = await readBody(req);
+            if (raw.length > MAX_SDP_CHARS * 2)
+                return json(req, res, 413, { error: 'WebRTC offer is too large' });
+            const body = JSON.parse(raw || '{}');
+            if (typeof body.sdp !== 'string' || !body.sdp.trim())
+                return json(req, res, 400, { error: 'WebRTC offer is required' });
+            if (body.sdp.length > MAX_SDP_CHARS)
+                return json(req, res, 413, { error: 'WebRTC offer is too large' });
+            if (!isOpenAIRealtimeVoice(body.voice))
+                return json(req, res, 400, { error: `voice must be one of ${OPENAI_REALTIME_VOICES.join(', ')}` });
+            if (!isVoiceLanguage(body.language))
+                return json(req, res, 400, { error: 'unsupported voice language' });
+            try {
+                const target = parseVoiceCallTarget(body.target);
+                const context = target ? readVoiceChatContext(reads, target) : undefined;
+                const call = await createWebRtcCall(voiceConfig.openaiKey, openAIOriginForSipHost(voiceConfig.sipHost), body.sdp, {
+                    model: voiceConfig.model,
+                    voice: body.voice,
+                    language: body.language,
+                    context
+                }, voiceSafetyIdentifier);
+                voiceBroker.registerWebRtc(call.callId, { voice: body.voice, language: body.language });
+                return json(req, res, 200, call);
+            }
+            catch (err) {
+                if (err instanceof VoiceContextError)
+                    return json(req, res, err.status, { error: err.message });
+                console.warn('[voice] could not create WebRTC orchestrator call:', err);
+                return json(req, res, 502, { error: err instanceof Error ? err.message : 'voice call failed' });
+            }
+        }
+        const readyVoiceCall = routeParam(routes.voiceCallReady, req.method, pathname);
+        if (readyVoiceCall) {
+            if (!voiceBroker)
+                return json(req, res, 503, { error: 'voice is not configured on this relay' });
+            if (!voiceBroker.beginWebRtc(readyVoiceCall))
+                return json(req, res, 404, { error: 'voice call not found' });
+            return json(req, res, 200, { ok: true });
+        }
+        const endedVoiceCall = routeParam(routes.voiceCallEnd, req.method, pathname);
+        if (endedVoiceCall) {
+            if (!voiceBroker)
+                return json(req, res, 503, { error: 'voice is not configured on this relay' });
+            try {
+                if (!(await voiceBroker.hangupWebRtc(endedVoiceCall)))
+                    return json(req, res, 404, { error: 'voice call not found' });
+                return json(req, res, 200, { ok: true });
+            }
+            catch (err) {
+                console.warn('[voice] could not hang up WebRTC orchestrator call:', err);
+                return json(req, res, 502, { error: err instanceof Error ? err.message : 'voice hangup failed' });
+            }
+        }
+        return NOT_HANDLED;
+    };
+}