feat(voice): audio-native voice — the model hears you and answers in the same breath

.env.example

@@ -78,7 +78,11 @@ CSRF_SECRET=your_csrf_secret_here_generate_a_secure_random_string
 ENCRYPTION_KEY=your_encryption_key_here_32_byte_hex_string
 
 # Application URLs
-# WEB_APP_URL is also used for Origin header validation (CSRF defense-in-depth)
+# WEB_APP_URL is also used for Origin header validation (CSRF defense-in-depth),
+# and — since audio-native voice — as apps/realtime's address for the web tier: a
+# live call calls back to {WEB_APP_URL}/api/internal/voice/bridge to run tools and
+# persist transcripts. Unset, a voice call still connects and still bills; it just
+# runs without tools or a transcript.
 WEB_APP_URL=http://localhost:3000
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 NEXT_PUBLIC_ADMIN_APP_URL=http://localhost:3005

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable user-facing changes to PageSpace are documented here. Format follows
 
 ## [Unreleased]
 
+### Added
+
+- **A microphone in the top bar, on every page, that talks to whichever assistant you are already
+  looking at** — there is no separate voice screen and nothing to set up first. Press it on a page
+  and the assistant sidebar opens in voice mode, talking to the agent you had selected there; press
+  it on the dashboard and it talks to the assistant already in the middle of your screen. Nothing
+  connects until you press it.
+- **A spoken conversation is the same conversation you can read and type in** — voice is a way into
+  a thread that already existed and still exists after you hang up. What is said appears in that
+  thread as ordinary messages while the call is running, marked with a small microphone so you can
+  tell later what was spoken and what was typed. There is no separate voice history to go looking
+  for, and nothing to replay.
+- **The call survives you walking around the app** — moving between pages does not end it or move it
+  to a different assistant; it just tells the assistant where you now are. Closing the sidebar
+  minimizes the call rather than hanging up, and the top-bar microphone stays lit so you can get
+  back to it. Deliberately choosing a different agent in the sidebar's switcher does move the call,
+  because that is a different conversation. Ending a call is the End button on the call itself, and
+  refreshing the page ends it too.
+- **The assistant on the call is the one you picked, with the instructions and the tools its owner
+  gave it** — an agent you built to answer a particular way answers that way out loud too, and one
+  whose tools you restricted cannot reach past them just because the conversation is spoken.
+- **A call you cannot have does not start** — running out of credit, or already having as many calls
+  open as your plan allows, now says so and stops, instead of connecting anyway and leaving you
+  talking to something nobody was counting.
+- **When voice cannot start, it says which problem you have** — a microphone you declined is
+  different from a microphone you do not have, and the two now get different advice and only the
+  fixable one offers to try again. If the call connects but the transcript service does not, the
+  call says so rather than letting you talk for ten minutes into something that was never going to
+  be saved.
+
 ### Fixed
 
 - **A second agent in a session stays put instead of flashing up and vanishing** — opening a chat
@@ -31,6 +61,15 @@ All notable user-facing changes to PageSpace are documented here. Format follows
 
 ### Changed
 
+- **Voice mode is now audio-native, and the old hands-free mic in the chat box is gone** — talking
+  to an assistant used to mean recording a clip, having it transcribed into text, and having the
+  reply read back to you. Everything about how you said it — pace, hesitation, the moment you cut
+  in — was thrown away before the assistant ever saw your words, and you had to wait for a whole
+  reply to be written before hearing any of it. The assistant now hears you directly and answers in
+  the same breath, so you can interrupt it and it stops. The way in is the microphone in the top
+  bar, on every page; the hands-free button that used to sit in the chat box next to the model
+  picker has been removed, along with its separate panel of voice settings for reading speed,
+  spoken voice and tap-to-speak.
 - **What the AI has learned about you is now a set of pages you can read and edit** — your
   personalization lived in three text boxes in Settings that a nightly process also wrote to, with
   no indication of what it had added or why. It is now three pages in a Memory folder in your Home

apps/realtime/src/__tests__/index.test.ts

@@ -231,6 +231,20 @@ vi.mock('../kick-handler', () => ({
   handleKickRequest: mockHandleKickRequest,
 }));
 
+// The voice attach endpoint receives a LIVE OpenAI ephemeral credential, so
+// what is asserted here is the wiring — that the signature gate runs before the
+// handler sees the body — not the handler's own behaviour (that has its own
+// suite). Mocked so no socket is ever opened by these tests.
+const mockHandleRealtimeAttachRequest = vi.fn().mockResolvedValue({
+  status: 200,
+  body: { success: true, callId: 'rtc_test' },
+});
+
+vi.mock('../voice/attach-handler', () => ({
+  handleRealtimeAttachRequest: mockHandleRealtimeAttachRequest,
+  defaultAttachHandlerDeps: { registry: {}, attach: vi.fn() },
+}));
+
 // ---------------------------------------------------------------------------
 // 2. Mock http.createServer and Socket.IO Server to capture callbacks
 // ---------------------------------------------------------------------------
@@ -700,6 +714,102 @@ describe('requestListener - /api/kick', () => {
   });
 });
 
+describe('requestListener - /api/realtime/attach', () => {
+  const attachBody = JSON.stringify({
+    callId: 'rtc_abc123',
+    secret: 'ek_secret_value',
+    userId: 'u1',
+    tools: [],
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockHandleRealtimeAttachRequest.mockResolvedValue({
+      status: 200,
+      body: { success: true, callId: 'rtc_abc123' },
+    });
+  });
+
+  it('given a valid signature, should delegate the RAW body to the attach handler', async () => {
+    vi.mocked(verifyBroadcastSignature).mockReturnValue(true);
+
+    const req = createMockReq({
+      method: 'POST',
+      url: '/api/realtime/attach',
+      headers: { 'x-broadcast-signature': 'valid-sig' },
+    });
+    const res = createMockRes();
+
+    capturedRequestListener!(req, res);
+    req._emit('data', Buffer.from(attachBody));
+    req._emit('end');
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    // The raw body, byte for byte — it is what the HMAC was computed over.
+    expect(mockHandleRealtimeAttachRequest).toHaveBeenCalledWith(expect.anything(), attachBody);
+    expect(res.writeHead).toHaveBeenCalledWith(200, { 'Content-Type': 'application/json' });
+  });
+
+  it('given NO signature, should 401 without the handler ever seeing the secret', async () => {
+    const req = createMockReq({
+      method: 'POST',
+      url: '/api/realtime/attach',
+      headers: {},
+    });
+    const res = createMockRes();
+
+    capturedRequestListener!(req, res);
+    req._emit('data', Buffer.from(attachBody));
+    req._emit('end');
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    expect(res.writeHead).toHaveBeenCalledWith(401, { 'Content-Type': 'application/json' });
+    expect(mockHandleRealtimeAttachRequest).not.toHaveBeenCalled();
+  });
+
+  it('given an INVALID signature, should 401 without the handler ever seeing the secret', async () => {
+    vi.mocked(verifyBroadcastSignature).mockReturnValue(false);
+
+    const req = createMockReq({
+      method: 'POST',
+      url: '/api/realtime/attach',
+      headers: { 'x-broadcast-signature': 'forged-sig' },
+    });
+    const res = createMockRes();
+
+    capturedRequestListener!(req, res);
+    req._emit('data', Buffer.from(attachBody));
+    req._emit('end');
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    expect(res.writeHead).toHaveBeenCalledWith(401, { 'Content-Type': 'application/json' });
+    expect(mockHandleRealtimeAttachRequest).not.toHaveBeenCalled();
+  });
+
+  it('given the handler rejects, should 500 rather than leaving the request hanging', async () => {
+    vi.mocked(verifyBroadcastSignature).mockReturnValue(true);
+    mockHandleRealtimeAttachRequest.mockRejectedValue(new Error('boom'));
+
+    const req = createMockReq({
+      method: 'POST',
+      url: '/api/realtime/attach',
+      headers: { 'x-broadcast-signature': 'valid-sig' },
+    });
+    const res = createMockRes();
+
+    capturedRequestListener!(req, res);
+    req._emit('data', Buffer.from(attachBody));
+    req._emit('end');
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    expect(res.writeHead).toHaveBeenCalledWith(500, { 'Content-Type': 'application/json' });
+  });
+});
+
 describe('requestListener - 404', () => {
   it('given unknown route, should return 404', () => {
     const req = createMockReq({