an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
feat(voice): explain the missing OpenAI key where it can be fixed
Chaitanya Giri9e5cc522367d
diff --git a/src/main/realtime.ts b/src/main/realtime.tsindex 86840ce3..fadaaf00 100644--- a/src/main/realtime.ts+++ b/src/main/realtime.ts@@ -24,8 +24,11 @@ import { getSecret, hasSecret } from './integrations';const OPENAI_KEY_REF = 'apikey:openai';/** GA speech-to-speech model for the voice orchestrator (v0.3.4: bumped to the- * July 2026 gpt-realtime-2.1 — 25% p95 latency cut, better interruption handling). */-export const REALTIME_MODEL = 'gpt-realtime-2.1';+ * July 2026 gpt-realtime-2.1 — 25% p95 latency cut, better interruption handling).+ * Defined in shared/ and re-exported here: Settings names this model in copy the+ * user reads, so main and the UI must not be able to disagree about it. */+export { REALTIME_MODEL } from '../shared/realtimePricing';+import { REALTIME_MODEL } from '../shared/realtimePricing';/** GA ephemeral-secret mint endpoint. If an account/tier still answers the legacy* beta shape, we fall back to /v1/realtime/sessions on a 404 and normalize both@@ -51,7 +54,7 @@ export function hasOpenAiKey(): boolean {export async function mintRealtimeToken(model: string = REALTIME_MODEL): Promise<MintResult> {const key = getSecret(OPENAI_KEY_REF);if (!key) {- return { ok: false, error: 'no OpenAI API key set — add one in Settings → AI Engines', code: 'no_key' };+ return { ok: false, error: 'no OpenAI API key set — add one in Settings → Voice', code: 'no_key' };}const post = async (url: string, body: unknown) => {diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsxindex 9ac4f7ff..b7a28a14 100644--- a/src/renderer/src/App.tsx+++ b/src/renderer/src/App.tsx@@ -17,7 +17,7 @@ import { CompletionToast } from '@/realtime/CompletionToast';import { UpdateToast } from '@/components/UpdateToast';import { UpdateBadge } from '@/components/UpdateBadge';import { useAppTheme, toggleAppTheme } from '@/design/theme';-import { SettingsModal } from '@/components/SettingsModal';+import { SettingsModal, type Section as SettingsSection } from '@/components/SettingsModal';import { PixelPanel } from '@/components/PixelPanel';import { PixelButton } from '@/components/PixelButton';import { Icon } from '@/components/Icon';@@ -63,10 +63,28 @@ export function App() {return false;});const [settingsOpen, setSettingsOpen] = useState(false);+ /** Which tab Settings opens on. Set by a `cth:open-settings` deep link, reset+ * to undefined (→ General) whenever the modal is opened the normal way. */+ const [settingsSection, setSettingsSection] = useState<SettingsSection | undefined>(undefined);const [quitWarn, setQuitWarn] = useState<{ ptyCount: number } | null>(null);const [closing, setClosing] = useState<ClosingTimeState | null>(null);const [vpWidth, setVpWidth] = useState<number>(window.innerWidth);+ // Deep link into Settings from anywhere in the tree. Settings' open state is+ // local to App, so a nested control (e.g. "set it now" beside a disabled Talk+ // button) has no path to it without threading a prop through every layer+ // between; a window event keeps that plumbing out of the components in+ // between, matching the existing `cth:` CustomEvent convention.+ useEffect(() => {+ const onOpenSettings = (e: Event): void => {+ const section = (e as CustomEvent<{ section?: SettingsSection }>).detail?.section;+ setSettingsSection(section);+ setSettingsOpen(true);+ };+ window.addEventListener('cth:open-settings', onOpenSettings);+ return () => window.removeEventListener('cth:open-settings', onOpenSettings);+ }, []);+// Initial config loaduseEffect(() => {let cancelled = false;@@ -314,7 +332,7 @@ export function App() {(sidebar detail, god Command Center, fullscreen) carries it. */}<buttonclassName="cth-titlebar-nodrag cth-settings-btn"- onClick={() => setSettingsOpen(true)}+ onClick={() => { setSettingsSection(undefined); setSettingsOpen(true); }}title="Settings"aria-label="Settings"style={{@@ -426,7 +444,11 @@ export function App() {)}{settingsOpen && (- <SettingsModal config={config} onClose={() => setSettingsOpen(false)} />+ <SettingsModal+ config={config}+ initialSection={settingsSection}+ onClose={() => { setSettingsOpen(false); setSettingsSection(undefined); }}+ />)}{quitWarn && (diff --git a/src/renderer/src/components/RealtimeMichaelToggle.tsx b/src/renderer/src/components/RealtimeMichaelToggle.tsxindex ab54d3b0..0dd75bc5 100644--- a/src/renderer/src/components/RealtimeMichaelToggle.tsx+++ b/src/renderer/src/components/RealtimeMichaelToggle.tsx@@ -16,6 +16,8 @@* Rendered in two places (AgentCard for the god card, FullscreenTerminal header when* Michael is fullscreen). It is intentionally state-only / hook-only so both can mount it.*/+import { useEffect, useRef, useState, type MouseEvent } from 'react';+import { createPortal } from 'react-dom';import { PixelButton } from './PixelButton';import { Icon } from './Icon';import { useStore } from '@/store/store';@@ -83,17 +85,26 @@ export interface RealtimeMichaelToggleProps {export function RealtimeMichaelToggle({ compact = false }: RealtimeMichaelToggleProps) {const hasOpenAiKey = useStore((s) => s.hasOpenAiKey);const { status, error, connect, disconnect } = useRealtimeMichael();+ // Measured viewport coords, not a CSS offset. The agent dock clips its+ // children, so a popover positioned inside the card gets sliced at the card's+ // edge no matter how it is anchored — which is exactly what happened. A portal+ // to <body> with fixed coordinates leaves that clipping context entirely.+ const [hint, setHint] = useState<{ left: number; top: number } | null>(null);+ const hintRef = useRef<HTMLSpanElement | null>(null);+ const iconRef = useRef<HTMLButtonElement | null>(null);+ const panelRef = useRef<HTMLDivElement | null>(null);+ const hintOpen = hint !== null;const view = STATE_VIEW[status];const noKey = !hasOpenAiKey;// Without a BYOK OpenAI key: stay visible but disabled (matches FreeFlowButton).// Talk mints an ephemeral token from the OpenAI key (apikey:openai) — the SAME- // OpenAI provider key set under AI Engines, used for the Realtime voice API. The- // tooltip carries the full WHY; the inline chip below gives a discoverable cue so- // the user never just hits a silently-dead button on connect.+ // OpenAI provider key set under Agents & Models, used for the Realtime voice API.+ // The tooltip carries the full WHY; the quiet info affordance below gives a+ // discoverable cue so the user never just hits a silently-dead button.const title = noKey- ? 'Talk needs your OpenAI API key (used for the Realtime voice API). Add it in Settings → AI Engines.'+ ? 'Talk needs your OpenAI API key (used for the Realtime voice API). Add it in Settings → Voice.': error? `${view.help} — ${error}`: view.help;@@ -104,13 +115,78 @@ export function RealtimeMichaelToggle({ compact = false }: RealtimeMichaelToggleelse disconnect();};+ // Jump straight to the tab that holds the key. App owns the Settings modal's+ // open state, so this goes through the `cth:` window-event convention rather+ // than threading a callback down through AgentCard/FullscreenTerminal.+ // Target is VOICE, not Agents & Models: the key is settable in both, but only+ // one of them explains what it is for.+ const openKeySettings = (e: MouseEvent): void => {+ e.stopPropagation();+ setHint(null);+ window.dispatchEvent(+ new CustomEvent('cth:open-settings', { detail: { section: 'Voice' } })+ );+ };++ const HINT_W = 210;+ const HINT_GAP = 8;++ /** Place the popover against the icon in VIEWPORT space, preferring above and+ * flipping below only when there is genuinely no room — the agent dock sits on+ * the bottom edge, so "above" is almost always right. Both axes are clamped to+ * the viewport so it can never hang off an edge. */+ const toggleHint = (e: MouseEvent): void => {+ e.stopPropagation();+ if (hint) { setHint(null); return; }+ const r = iconRef.current?.getBoundingClientRect();+ if (!r) return;+ // Height is content-dependent; this is the two-line + link case, and the+ // clamp below absorbs the error if it wraps to three.+ const estH = 78;+ const above = r.top - HINT_GAP - estH;+ const top = above >= 8 ? above : Math.min(r.bottom + HINT_GAP, window.innerHeight - estH - 8);+ const left = Math.max(8, Math.min(r.left, window.innerWidth - HINT_W - 8));+ setHint({ left, top: Math.max(8, top) });+ };++ // Click-to-open explanation. A hover title would do for a mouse, but this sits+ // on a disabled control — the one thing people click when nothing happens — so+ // the answer belongs behind that click.+ useEffect(() => {+ if (!hintOpen) return;+ const onDown = (ev: globalThis.MouseEvent): void => {+ const t = ev.target as Node;+ // The popover is portalled out of this subtree, so an inside-click has to+ // be tested against BOTH the anchor and the floating panel.+ if (hintRef.current?.contains(t) || panelRef.current?.contains(t)) return;+ setHint(null);+ };+ const onKey = (ev: KeyboardEvent): void => { if (ev.key === 'Escape') setHint(null); };+ // A dock that scrolls or a window that resizes leaves fixed coords stale, and+ // a popover stranded away from its icon is worse than one that closed.+ const onReflow = (): void => setHint(null);+ document.addEventListener('mousedown', onDown);+ document.addEventListener('keydown', onKey);+ window.addEventListener('resize', onReflow);+ window.addEventListener('scroll', onReflow, true);+ return () => {+ document.removeEventListener('mousedown', onDown);+ document.removeEventListener('keydown', onKey);+ window.removeEventListener('resize', onReflow);+ window.removeEventListener('scroll', onReflow, true);+ };+ }, [hintOpen]);+// Wrap in a (non-disabled) span so the native title tooltip still shows on hover even// when the inner button is disabled — Chromium suppresses tooltips on a disabled button.return (<spantitle={title}className="cth-titlebar-nodrag"- style={{ display: 'inline-flex', alignItems: 'center', gap: noKey ? 6 : 0 }}+ // minWidth:0 is what actually stops the overflow: without it this inline-flex+ // keeps its max-content width and pushes past the card's edge no matter what+ // the label inside does.+ style={{ display: 'inline-flex', alignItems: 'center', gap: noKey ? 4 : 0, minWidth: 0 }}// Stop the click bubbling to a parent card's onClick (selecting the agent).onClick={(e) => e.stopPropagation()}>@@ -145,28 +221,77 @@ export function RealtimeMichaelToggle({ compact = false }: RealtimeMichaelToggle)}</span></PixelButton>- {/* Inline, non-blocking caution chip — a discoverable cue for WHY the disabled- button won't connect (the native tooltip is hover-only). Only when no key is- set; once a key is added the store signal flips and this disappears. Compact- form (fullscreen toolbar) keeps it short to avoid crowding the header. */}+ {/* Missing key is a SETUP STATE, not a failure — so this is a quiet info mark+ and a way to fix it, never a warning chip. The old lemon chip spelled the+ whole problem out inline ("needs OpenAI key · Settings") and, being+ nowrap + flex-shrink:0, pushed itself past the agent card's edge instead+ of wrapping. The explanation now lives in the hover tooltip; what stays on+ screen is one 16px glyph plus a two-word action.++ In compact mode (fullscreen toolbar) the icon alone carries it — the+ tooltip still explains, and Settings is a click away in the same header. */}{noKey && (- <span- aria-label="Talk needs an OpenAI key"- style={{- display: 'inline-flex',- alignItems: 'center',- whiteSpace: 'nowrap',- fontFamily: 'var(--cth-font-ui)',- fontSize: 10,- lineHeight: '14px',- padding: '1px 5px 0',- background: 'var(--cth-lemon)',- color: 'var(--cth-ink-900)',- boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',- flexShrink: 0- }}- >- {compact ? 'needs OpenAI key' : 'needs OpenAI key · Settings'}+ <span ref={hintRef} style={{ display: 'inline-flex', flexShrink: 0 }}>+ <button+ ref={iconRef}+ type="button"+ aria-label="Why is Talk disabled?"+ aria-expanded={hintOpen}+ onClick={toggleHint}+ style={{+ border: 'none', background: 'none', padding: 0, cursor: 'pointer',+ display: 'inline-flex', alignItems: 'center',+ opacity: hintOpen ? 1 : 0.75+ }}+ >+ <Icon name="info" />+ </button>++ {hint && createPortal(+ <div+ ref={panelRef}+ role="dialog"+ onClick={(e) => e.stopPropagation()}+ style={{+ position: 'fixed',+ left: hint.left,+ top: hint.top,+ zIndex: 460,+ width: HINT_W,+ padding: '8px 10px',+ display: 'flex',+ flexDirection: 'column',+ gap: 5,+ boxSizing: 'border-box',+ background: 'var(--cth-paper-100)',+ // Matches the note editor's portalled popover: hairline + a hard+ // drop shadow, so it reads as floating above the dock rather than+ // as part of whichever card it happens to cover.+ boxShadow: 'inset 0 0 0 1.5px var(--cth-ink-500), 4px 4px 0 rgba(26,19,32,0.25)',+ fontFamily: 'var(--cth-font-ui)',+ fontSize: 11,+ lineHeight: '15px',+ color: 'var(--cth-ink-900)',+ textAlign: 'left',+ whiteSpace: 'normal'+ }}+ >+ <span>An <strong>OpenAI API key</strong> is needed to use this feature.</span>+ <button+ type="button"+ onClick={openKeySettings}+ style={{+ border: 'none', background: 'none', padding: 0, cursor: 'pointer',+ alignSelf: 'flex-start',+ fontFamily: 'var(--cth-font-ui)', fontSize: 11, lineHeight: '15px',+ color: 'var(--cth-ink-900)', textDecoration: 'underline'+ }}+ >+ set it up now+ </button>+ </div>,+ document.body+ )}</span>)}</span>diff --git a/src/renderer/src/components/SettingsModal.tsx b/src/renderer/src/components/SettingsModal.tsxindex 48f7ef89..c2cd90e7 100644--- a/src/renderer/src/components/SettingsModal.tsx+++ b/src/renderer/src/components/SettingsModal.tsx@@ -17,12 +17,17 @@ import { OfficeThemePicker } from './OfficeThemePicker';import { McpDefaultsSettings } from './McpDefaultsSettings';import { IntegrationsRegistry } from './IntegrationsRegistry';import { AiEnginesSettings } from './AiEnginesSettings';+import { REALTIME_MODEL } from '@shared/realtimePricing';import { RealtimeDevicePicker } from '@/realtime/DevicePicker';import { CostHud } from '@/realtime/CostHud';export interface SettingsModalProps {config: HarnessConfig;onClose: () => void;+ /** Open straight to a section instead of General. Used by deep links from+ * elsewhere in the UI — "set it now" beside a disabled Talk button lands on+ * the tab that actually holds the field, rather than making the user hunt. */+ initialSection?: Section;}/**@@ -148,7 +153,7 @@ function clearLocalState(): void {// v0.3.4 redesign: six tabs, one topic each. 'AI Engines' folded into// Agents & Models; MCP + Slack + webhook + REST live together in Connections;// voice gets its own tab; Danger Zone became a red row at the bottom of General.-type Section = 'General' | 'Agents & Models' | 'Autonomy & Budgets' | 'Connections' | 'Voice' | 'Memory & Knowledge';+export type Section = 'General' | 'Agents & Models' | 'Autonomy & Budgets' | 'Connections' | 'Voice' | 'Memory & Knowledge';const NAV_SECTIONS: Section[] = ['General', 'Agents & Models', 'Autonomy & Budgets', 'Connections', 'Voice', 'Memory & Knowledge'];/** One labelled on/off row. The surrounding settings pane repeats this@@ -183,10 +188,10 @@ function SettingRow({ title, blurb, on, onClick, disabled }: {);}-export function SettingsModal({ config, onClose }: SettingsModalProps) {+export function SettingsModal({ config, onClose, initialSection }: SettingsModalProps) {const [confirming, setConfirming] = useState(false);const [busy, setBusy] = useState(false);- const [activeSection, setActiveSection] = useState<Section>('General');+ const [activeSection, setActiveSection] = useState<Section>(initialSection ?? 'General');// Change-home flow: null until the user picks a new folder, then the sub-modal// confirms move-vs-fresh. Pre-selects 'move' (recommended - keeps the data).@@ -427,6 +432,26 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {// Talk (Realtime Michael) is gated on the OpenAI key — read the live presence// boolean so the Realtime Michael section can show its enabled/disabled status.const hasOpenAiKey = useStore((s) => s.hasOpenAiKey);+ // Voice-tab entry for the SAME broker slot Agents & Models writes (apikey:openai).+ // Mirroring presence into the store on save is what makes the Talk button light up+ // immediately instead of on next launch.+ const setHasOpenAiKey = useStore((s) => s.setHasOpenAiKey);+ const [openAiVoiceKey, setOpenAiVoiceKey] = useState('');+ const [openAiVoiceNote, setOpenAiVoiceNote] = useState('');+ const saveOpenAiVoiceKey = async (): Promise<void> => {+ const key = openAiVoiceKey.trim();+ if (!key) return;+ try {+ const r = await window.cth.providerKeySet({ backend: 'openai', key });+ if (r.ok) {+ setOpenAiVoiceKey('');+ setHasOpenAiKey(true);+ setOpenAiVoiceNote('Key saved — Talk is ready.');+ } else setOpenAiVoiceNote(r.error ?? 'Could not save the key.');+ } catch (e) {+ setOpenAiVoiceNote(e instanceof Error ? e.message : String(e));+ }+ };// v0.3.4 fix: the config default is ON ('now on by default', 0.2.7) — seeding// with `?? false` displayed OFF while the feature was actually running.const [freeflowEnabled, setFreeflowEnabled] = useState(config.freeflowEnabled !== false);@@ -1889,12 +1914,15 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {</span></div>- {/* OpenAI Realtime key — its own documented requirement. Talk mints an- ephemeral token from your OpenAI key (the same OpenAI provider key- under AI Engines), distinct from your Anthropic key. The status line- reads the live presence boolean (key value never leaves main). */}+ {/* OpenAI Realtime key — settable HERE, not just described here.+ This is where someone looking for voice actually lands (the Talk+ button deep-links to it), so sending them to another tab to type+ the key was a dead end dressed up as documentation. Same broker+ slot as Agents & Models (apikey:openai) — one key, two doorways,+ and saving in either flips the same gate. The value never leaves+ main; only the presence boolean comes back. */}<div style={{- display: 'flex', flexDirection: 'column', gap: 6,+ display: 'flex', flexDirection: 'column', gap: 8,padding: 10,background: 'var(--cth-paper-100)',boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)'@@ -1903,28 +1931,51 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {fontFamily: 'var(--cth-font-display)', fontSize: 8, lineHeight: '12px',color: 'var(--cth-ink-500)', textTransform: 'uppercase'}}>- OpenAI Realtime key+ OpenAI API key · voice</span><span style={{ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-700)' }}>- Talk uses OpenAI’s Realtime voice API, so it needs your <strong>OpenAI API key</strong> —- the same key you set under <strong>AI Engines → OpenAI</strong>. It is a separate provider- key from your Anthropic key. Main mints a short-lived token from it for each session; the- key itself never leaves your machine. <strong>Without an OpenAI key the Talk button stays- disabled.</strong>+ Talking to Michael runs on OpenAI’s Realtime API — speech in, speech out, over a+ live connection to <strong style={{ fontFamily: 'var(--cth-font-mono)' }}>{REALTIME_MODEL}</strong>.+ That is a different service from the Claude subscription your agents run on, so it needs+ its own <strong>OpenAI API key</strong>.</span>+ <span style={{ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-700)' }}>+ Paste it once below. It is encrypted on this machine and never shown again — each voice+ session mints its own short-lived token from it, and the key itself never leaves your+ computer. It is the same OpenAI key listed under <strong>Agents & Models</strong>;+ setting it in either place is enough.+ </span>+ <div style={{ display: 'flex', gap: 6, alignItems: 'center' }}>+ <input+ type="password"+ value={openAiVoiceKey}+ onChange={(e) => setOpenAiVoiceKey(e.target.value)}+ onKeyDown={(e) => { if (e.key === 'Enter') void saveOpenAiVoiceKey(); }}+ placeholder={hasOpenAiKey ? 'key saved — paste a new one to replace it' : 'sk-…'}+ style={{ ...slackInputStyle, flex: 1, fontFamily: 'var(--cth-font-mono)' }}+ />+ <PixelButton+ variant="secondary"+ size="sm"+ onClick={() => void saveOpenAiVoiceKey()}+ disabled={!openAiVoiceKey.trim()}+ >+ Save+ </PixelButton>+ </div><span style={{display: 'inline-flex', alignItems: 'center', gap: 6,fontSize: 12, lineHeight: '16px',- color: hasOpenAiKey ? 'var(--cth-ink-900)' : '#6E1423'+ color: hasOpenAiKey ? 'var(--cth-ink-900)' : 'var(--cth-ink-500)'}}><span aria-hidden style={{width: 8, height: 8, flexShrink: 0,- background: hasOpenAiKey ? 'var(--cth-mint)' : 'var(--cth-lemon)',+ background: hasOpenAiKey ? 'var(--cth-mint)' : 'var(--cth-ink-300)',boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)'}} />- {hasOpenAiKey- ? 'OpenAI key detected — Talk is enabled.'- : 'No OpenAI key set — Talk is disabled. Add it under AI Engines → OpenAI.'}+ {openAiVoiceNote || (hasOpenAiKey+ ? 'Key saved — Talk is ready. Start it from Michael’s card.'+ : 'No key yet — Talk stays disabled until one is saved.')}</span></div>diff --git a/src/shared/realtimePricing.ts b/src/shared/realtimePricing.tsindex a07a31d1..12d8347c 100644--- a/src/shared/realtimePricing.ts+++ b/src/shared/realtimePricing.ts@@ -14,6 +14,15 @@* raw token counts are surfaced alongside the dollar figure so it stays auditable.*/+/**+ * The realtime voice model Talk connects to. Lives HERE, in shared, because it is+ * named in user-facing Settings copy as well as used by the main-process mint —+ * a model string duplicated across a process boundary is one that eventually+ * disagrees with itself, and the half users read is the half nobody notices is+ * stale. `src/main/realtime.ts` re-exports this as its own REALTIME_MODEL.+ */+export const REALTIME_MODEL = 'gpt-realtime-2.1';+/** USD per 1,000,000 audio tokens (gpt-realtime-2). */export const REALTIME_AUDIO_INPUT_PER_MTOK = 32;export const REALTIME_AUDIO_OUTPUT_PER_MTOK = 64;