From 592140f22148191ee84ee24367e51274134926fb Mon Sep 17 00:00:00 2001
From: oratis <wangharp@gmail.com>
Date: Thu, 28 May 2026 15:23:33 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20M6-rest=20part=202=20+=20M8=20voice=20?=
 =?UTF-8?q?=E2=80=94=204=20more=20desktop=20screens=20+=20whisper.cpp=20wr?=
 =?UTF-8?q?apper?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two parallel pieces of polish.

Core:
  · packages/core/src/voice/index.ts (NEW) — VoiceProvider interface +
    WhisperCppProvider (spawns whisper CLI, parses timestamped output) +
    StubVoiceProvider for tests / unconfigured installs. parseWhisperOutput
    is exported so format expectations are pinned.
  · 7 unit tests covering output parsing + spawn-via-fake + missing-file
    + non-zero-exit cases.

Desktop:
  · apps/desktop/src/components/Nav.tsx (NEW) — top tab bar for
    REPL/Chat/Sessions/MCP/Settings.
  · apps/desktop/src/screens/Sessions.tsx — list + filter + new-session
    button (IPC wired in next M6-rest PR).
  · apps/desktop/src/screens/Settings.tsx — flat-key view of
    settings.json with filter.
  · apps/desktop/src/screens/MCPManager.tsx — list of connected servers
    + JSON snippet for adding one.
  · apps/desktop/src/screens/Chat.tsx — REPL + (hidden lg-only) file
    panel placeholder pointing at M7.
  · apps/desktop/src/App.tsx — routes to the active screen.
  · apps/desktop/src/index.css — additional utility classes for the new
    layouts (lg:block, w-1/3, border-l, hover:*, font-mono, table).

Tests: core 438 → 445 (+7 voice); cli 47 unchanged; scripts 16 unchanged.
Total 501 → 508 passing. Build clean across all 4 packages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apps/desktop/src/App.tsx                |  22 +++-
 apps/desktop/src/components/Nav.tsx     |  39 +++++++
 apps/desktop/src/index.css              |  24 +++++
 apps/desktop/src/screens/Chat.tsx       |  27 ++++-
 apps/desktop/src/screens/MCPManager.tsx |  90 +++++++++++++++-
 apps/desktop/src/screens/Sessions.tsx   |  91 +++++++++++++++-
 apps/desktop/src/screens/Settings.tsx   |  86 ++++++++++++++-
 packages/core/src/index.ts              |  11 ++
 packages/core/src/voice/index.test.ts   |  95 +++++++++++++++++
 packages/core/src/voice/index.ts        | 133 ++++++++++++++++++++++++
 10 files changed, 596 insertions(+), 22 deletions(-)
 create mode 100644 apps/desktop/src/components/Nav.tsx
 create mode 100644 packages/core/src/voice/index.test.ts
 create mode 100644 packages/core/src/voice/index.ts

diff --git a/apps/desktop/src/App.tsx b/apps/desktop/src/App.tsx
index 5250e15..846b117 100644
--- a/apps/desktop/src/App.tsx
+++ b/apps/desktop/src/App.tsx
@@ -1,17 +1,23 @@
 // Top-level React component for desktop client.
 // Spec: docs/VISUAL_DESIGN.html
-// Milestone: M6 skeleton — onboarding + REPL placeholder + update banner
+// Milestone: M6-rest — Onboarding gate + Nav + 5 screens
 
 import { useEffect, useState } from 'react';
+import { Nav, type ScreenName } from './components/Nav.js';
+import { UpdateBanner } from './components/UpdateBanner.js';
+import { ChatScreen } from './screens/Chat.js';
+import { MCPManagerScreen } from './screens/MCPManager.js';
 import { OnboardingScreen } from './screens/Onboarding.js';
 import { ReplScreen } from './screens/Repl.js';
-import { UpdateBanner } from './components/UpdateBanner.js';
+import { SessionsScreen } from './screens/Sessions.js';
+import { SettingsScreen } from './screens/Settings.js';
 import type { UpdateInfo } from './types/global.js';
 
 export function App(): JSX.Element {
   const [version, setVersion] = useState<string>('');
   const [hasKey, setHasKey] = useState<boolean | null>(null);
   const [update, setUpdate] = useState<UpdateInfo | null>(null);
+  const [screen, setScreen] = useState<ScreenName>('repl');
 
   useEffect(() => {
     void window.deepcode.version().then(setVersion);
@@ -35,9 +41,21 @@ export function App(): JSX.Element {
         <span className="font-semibold">DeepCode</span>
         <span className="text-muted">v{version}</span>
       </header>
+      {hasKey && <Nav active={screen} onChange={setScreen} />}
       <main className="flex-1 overflow-hidden">
         {!hasKey ? (
           <OnboardingScreen onComplete={() => setHasKey(true)} />
+        ) : screen === 'chat' ? (
+          <ChatScreen />
+        ) : screen === 'sessions' ? (
+          <SessionsScreen
+            onPick={() => setScreen('repl')}
+            onNew={() => setScreen('repl')}
+          />
+        ) : screen === 'settings' ? (
+          <SettingsScreen />
+        ) : screen === 'mcp' ? (
+          <MCPManagerScreen />
         ) : (
           <ReplScreen />
         )}
diff --git a/apps/desktop/src/components/Nav.tsx b/apps/desktop/src/components/Nav.tsx
new file mode 100644
index 0000000..872fc7b
--- /dev/null
+++ b/apps/desktop/src/components/Nav.tsx
@@ -0,0 +1,39 @@
+// Top nav — switches between the main screens.
+// Spec: docs/VISUAL_DESIGN.html screen #1 header
+// Milestone: M6-rest
+
+export type ScreenName = 'repl' | 'chat' | 'sessions' | 'settings' | 'mcp';
+
+interface NavProps {
+  active: ScreenName;
+  onChange: (next: ScreenName) => void;
+}
+
+const ITEMS: Array<{ name: ScreenName; label: string }> = [
+  { name: 'repl', label: 'REPL' },
+  { name: 'chat', label: 'Chat' },
+  { name: 'sessions', label: 'Sessions' },
+  { name: 'mcp', label: 'MCP' },
+  { name: 'settings', label: 'Settings' },
+];
+
+export function Nav({ active, onChange }: NavProps): JSX.Element {
+  return (
+    <nav className="flex gap-1 border-b border-border bg-bg-elevated px-2 text-sm">
+      {ITEMS.map((item) => (
+        <button
+          key={item.name}
+          onClick={() => onChange(item.name)}
+          className={
+            'px-3 py-2 ' +
+            (active === item.name
+              ? 'border-b-2 border-accent text-fg'
+              : 'text-muted hover:text-fg')
+          }
+        >
+          {item.label}
+        </button>
+      ))}
+    </nav>
+  );
+}
diff --git a/apps/desktop/src/index.css b/apps/desktop/src/index.css
index 0eefd44..f32cf40 100644
--- a/apps/desktop/src/index.css
+++ b/apps/desktop/src/index.css
@@ -96,3 +96,27 @@ code {
   font-family: ui-monospace, SFMono-Regular, monospace;
   font-size: 0.95em;
 }
+
+/* Additional utility classes used by the M6-rest screens. */
+.border-l { border-left-width: 1px; border-left-style: solid; }
+.border-b-2 { border-bottom-width: 2px; border-bottom-style: solid; }
+.border-accent { border-color: var(--accent); }
+.cursor-pointer { cursor: pointer; }
+.hidden { display: none; }
+@media (min-width: 1024px) { .lg\:block { display: block; } }
+.w-1\/3 { width: 33.333%; }
+.max-w-xl { max-width: 36rem; }
+.mx-auto { margin-left: auto; margin-right: auto; }
+.ml-2 { margin-left: 0.5rem; }
+.mt-2 { margin-top: 0.5rem; }
+.mt-3 { margin-top: 0.75rem; }
+.mt-4 { margin-top: 1rem; }
+.p-2 { padding: 0.5rem; }
+.gap-1 { gap: 0.25rem; }
+.space-y-2 > * + * { margin-top: 0.5rem; }
+.text-center { text-align: center; }
+.text-left { text-align: left; }
+.font-mono { font-family: ui-monospace, SFMono-Regular, monospace; }
+.hover\:border-accent:hover { border-color: var(--accent); }
+.hover\:text-fg:hover { color: var(--fg); }
+table { border-collapse: collapse; width: 100%; }
diff --git a/apps/desktop/src/screens/Chat.tsx b/apps/desktop/src/screens/Chat.tsx
index e339f3d..f575994 100644
--- a/apps/desktop/src/screens/Chat.tsx
+++ b/apps/desktop/src/screens/Chat.tsx
@@ -1,6 +1,23 @@
-// Screen: Chat
-// Milestone: M6
-// Spec: docs/VISUAL_DESIGN.html
-// Status: placeholder
+// Chat screen — same shape as REPL but with split file panel.
+// Spec: docs/VISUAL_DESIGN.html screen #2 + #8
+// Milestone: M6-rest (file panel itself is M7)
 
-export {};
+import { ReplScreen } from './Repl.js';
+
+export function ChatScreen(): JSX.Element {
+  return (
+    <div className="flex h-full">
+      <div className="flex-1">
+        <ReplScreen />
+      </div>
+      <div className="hidden w-1/3 border-l border-border lg:block">
+        <div className="p-4 text-center text-muted">
+          <p>File panel</p>
+          <p className="mt-2 text-xs">
+            Monaco-based file viewer · Source / Diff / History tabs — M7
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/screens/MCPManager.tsx b/apps/desktop/src/screens/MCPManager.tsx
index 4934954..66d0cba 100644
--- a/apps/desktop/src/screens/MCPManager.tsx
+++ b/apps/desktop/src/screens/MCPManager.tsx
@@ -1,6 +1,86 @@
-// Screen: MCPManager
-// Milestone: M6
-// Spec: docs/VISUAL_DESIGN.html
-// Status: placeholder
+// MCP server manager screen — list / connect / test MCP servers.
+// Spec: docs/VISUAL_DESIGN.html screen #7
+// Milestone: M6-rest
 
-export {};
+import { useEffect, useState } from 'react';
+
+interface McpServerStatus {
+  name: string;
+  status: 'connected' | 'failed' | 'disabled';
+  toolCount?: number;
+  error?: string;
+}
+
+export function MCPManagerScreen(): JSX.Element {
+  const [servers, setServers] = useState<McpServerStatus[] | null>(null);
+
+  useEffect(() => {
+    // Real impl: window.deepcode.mcp.list() — wired in M6-rest IPC PR.
+    setServers([]);
+  }, []);
+
+  if (servers === null) {
+    return <div className="p-8 text-muted">Loading MCP servers…</div>;
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <header className="border-b border-border p-3">
+        <h2 className="font-semibold">MCP Servers</h2>
+        <p className="mt-1 text-xs text-muted">
+          Connected via settings.json &gt; <code>mcpServers</code>.{' '}
+          {servers.length === 0
+            ? 'None configured.'
+            : `${servers.filter((s) => s.status === 'connected').length} of ${servers.length} connected.`}
+        </p>
+      </header>
+      <div className="flex-1 overflow-y-auto p-3">
+        {servers.length === 0 ? (
+          <div className="p-8 text-center text-muted">
+            <p>No MCP servers configured.</p>
+            <pre className="mx-auto mt-4 max-w-xl rounded bg-bg-elevated p-3 text-left text-xs">
+              {`{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-filesystem", "/tmp"]
+    }
+  }
+}`}
+            </pre>
+            <p className="mt-3 text-xs">
+              Add the snippet above to your settings.json then relaunch.
+            </p>
+          </div>
+        ) : (
+          <ul className="space-y-2">
+            {servers.map((s) => (
+              <li key={s.name} className="rounded border border-border p-3">
+                <div className="flex items-center justify-between">
+                  <span className="font-medium">{s.name}</span>
+                  <span
+                    className={
+                      s.status === 'connected'
+                        ? 'text-accent'
+                        : s.status === 'failed'
+                          ? 'text-error'
+                          : 'text-muted'
+                    }
+                  >
+                    {s.status}
+                    {s.toolCount !== undefined && s.status === 'connected'
+                      ? ` · ${s.toolCount} tools`
+                      : ''}
+                  </span>
+                </div>
+                {s.error && (
+                  <div className="mt-1 text-xs text-error">{s.error}</div>
+                )}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/screens/Sessions.tsx b/apps/desktop/src/screens/Sessions.tsx
index 599313c..9722b11 100644
--- a/apps/desktop/src/screens/Sessions.tsx
+++ b/apps/desktop/src/screens/Sessions.tsx
@@ -1,6 +1,87 @@
-// Screen: Sessions
-// Milestone: M6
-// Spec: docs/VISUAL_DESIGN.html
-// Status: placeholder
+// Sessions list screen — resume / inspect past conversations.
+// Spec: docs/VISUAL_DESIGN.html screen #5
+// Milestone: M6-rest
 
-export {};
+import { useEffect, useState } from 'react';
+
+interface SessionMeta {
+  id: string;
+  title?: string;
+  cwd: string;
+  createdAt: string;
+  updatedAt: string;
+  model?: string;
+}
+
+interface SessionsProps {
+  onPick: (sessionId: string) => void;
+  onNew: () => void;
+}
+
+export function SessionsScreen({ onPick, onNew }: SessionsProps): JSX.Element {
+  const [sessions, setSessions] = useState<SessionMeta[] | null>(null);
+  const [filter, setFilter] = useState('');
+
+  useEffect(() => {
+    // Real impl wires through window.deepcode.sessions.list — added in
+    // M6-rest IPC PR. For now, render an empty state.
+    setSessions([]);
+  }, []);
+
+  if (sessions === null) {
+    return <div className="p-8 text-muted">Loading sessions…</div>;
+  }
+
+  const visible = sessions.filter(
+    (s) =>
+      !filter ||
+      (s.title ?? '').toLowerCase().includes(filter.toLowerCase()) ||
+      s.cwd.toLowerCase().includes(filter.toLowerCase()),
+  );
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex items-center justify-between border-b border-border p-3">
+        <input
+          type="search"
+          placeholder="Filter sessions…"
+          value={filter}
+          onChange={(e) => setFilter(e.target.value)}
+          className="flex-1 rounded border border-border bg-bg px-3 py-2 text-fg outline-none focus:border-accent"
+        />
+        <button
+          onClick={onNew}
+          className="ml-2 rounded bg-accent px-4 py-2 font-medium text-bg"
+        >
+          + New session
+        </button>
+      </div>
+      <div className="flex-1 overflow-y-auto p-3">
+        {visible.length === 0 ? (
+          <div className="p-8 text-center text-muted">
+            <p>No previous sessions yet.</p>
+            <p className="mt-2 text-xs">Start one with the New session button above.</p>
+          </div>
+        ) : (
+          <ul className="space-y-2">
+            {visible.map((s) => (
+              <li
+                key={s.id}
+                onClick={() => onPick(s.id)}
+                className="cursor-pointer rounded border border-border p-3 hover:border-accent"
+              >
+                <div className="flex items-center justify-between">
+                  <span className="font-medium">{s.title ?? s.id.slice(0, 8)}</span>
+                  <span className="text-xs text-muted">
+                    {new Date(s.updatedAt).toLocaleString()}
+                  </span>
+                </div>
+                <div className="mt-1 text-xs text-muted">{s.cwd}</div>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/screens/Settings.tsx b/apps/desktop/src/screens/Settings.tsx
index e61a764..9c0725e 100644
--- a/apps/desktop/src/screens/Settings.tsx
+++ b/apps/desktop/src/screens/Settings.tsx
@@ -1,6 +1,82 @@
-// Screen: Settings
-// Milestone: M6
-// Spec: docs/VISUAL_DESIGN.html
-// Status: placeholder
+// Settings screen — inspect + edit ~/.deepcode/settings.json
+// Spec: docs/VISUAL_DESIGN.html screen #6
+// Milestone: M6-rest
 
-export {};
+import { useEffect, useState } from 'react';
+
+export function SettingsScreen(): JSX.Element {
+  const [settings, setSettings] = useState<Record<string, unknown> | null>(null);
+  const [search, setSearch] = useState('');
+
+  useEffect(() => {
+    void window.deepcode.settings.load().then((s) => setSettings(s));
+  }, []);
+
+  if (settings === null) {
+    return <div className="p-8 text-muted">Loading settings…</div>;
+  }
+
+  // Flat-key view: convert nested settings to dot.notation entries for display
+  const flat: Array<{ key: string; value: string }> = [];
+  function walk(prefix: string, obj: unknown): void {
+    if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+      for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+        walk(prefix ? `${prefix}.${k}` : k, v);
+      }
+    } else {
+      flat.push({ key: prefix, value: JSON.stringify(obj) });
+    }
+  }
+  walk('', settings);
+
+  const visible = flat.filter(
+    (e) =>
+      !search ||
+      e.key.toLowerCase().includes(search.toLowerCase()) ||
+      e.value.toLowerCase().includes(search.toLowerCase()),
+  );
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="border-b border-border p-3">
+        <input
+          type="search"
+          placeholder="Filter settings…"
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+          className="w-full rounded border border-border bg-bg px-3 py-2 text-fg outline-none focus:border-accent"
+        />
+      </div>
+      <div className="flex-1 overflow-y-auto p-3">
+        {visible.length === 0 ? (
+          <div className="p-8 text-center text-muted">
+            <p>No matching settings.</p>
+            <p className="mt-2 text-xs">
+              Default config: ~/.deepcode/settings.json · project: .deepcode/settings.json
+            </p>
+          </div>
+        ) : (
+          <table className="w-full text-sm">
+            <thead className="text-xs text-muted">
+              <tr>
+                <th className="p-2 text-left">Key</th>
+                <th className="p-2 text-left">Value</th>
+              </tr>
+            </thead>
+            <tbody>
+              {visible.map((e) => (
+                <tr key={e.key} className="border-t border-border">
+                  <td className="p-2 font-mono">{e.key}</td>
+                  <td className="p-2 font-mono text-muted">{e.value}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </div>
+      <div className="border-t border-border p-3 text-xs text-muted">
+        Edit by opening ~/.deepcode/settings.json in your editor (visual editor lands in M7).
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 2e0f8f8..050eee8 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -241,6 +241,17 @@ export {
   type MarketplaceConfig,
 } from './plugins/index.js';
 
+// Voice input (M8 — whisper.cpp wrapper + stub provider)
+export {
+  WhisperCppProvider,
+  StubVoiceProvider,
+  parseWhisperOutput,
+  type VoiceProvider,
+  type VoiceTranscript,
+  type TranscribeOpts,
+  type WhisperCppOpts,
+} from './voice/index.js';
+
 // Auto-mode classifier (M3c-rest — LLM-judged tool gate when mode === 'auto')
 export {
   classifyAutoMode,
diff --git a/packages/core/src/voice/index.test.ts b/packages/core/src/voice/index.test.ts
new file mode 100644
index 0000000..2618e86
--- /dev/null
+++ b/packages/core/src/voice/index.test.ts
@@ -0,0 +1,95 @@
+import { EventEmitter } from 'node:events';
+import { promises as fs } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { parseWhisperOutput, StubVoiceProvider, WhisperCppProvider } from './index.js';
+
+describe('parseWhisperOutput', () => {
+  it('strips per-line timestamps', () => {
+    const raw =
+      '[00:00:00.000 --> 00:00:02.500]  hello world\n' +
+      '[00:00:02.500 --> 00:00:05.000]  another line';
+    expect(parseWhisperOutput(raw)).toBe('hello world another line');
+  });
+
+  it('drops whisper_ log lines and system_info', () => {
+    const raw =
+      'whisper_init_from_file: loading\n' +
+      'system_info: AVX2\n' +
+      '[00:00:00.000 --> 00:00:01.000]  real text';
+    expect(parseWhisperOutput(raw)).toBe('real text');
+  });
+
+  it('returns empty string on log-only input', () => {
+    expect(parseWhisperOutput('whisper_init\nsystem_info: X')).toBe('');
+  });
+});
+
+describe('StubVoiceProvider', () => {
+  it('returns empty transcript', async () => {
+    const r = await new StubVoiceProvider().transcribe();
+    expect(r.text).toBe('');
+    expect(r.latencyMs).toBe(0);
+  });
+});
+
+describe('WhisperCppProvider', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dc-voice-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('throws when audio file does not exist', async () => {
+    const p = new WhisperCppProvider({ modelPath: '/no/such/model.bin' });
+    await expect(p.transcribe('/no/such/audio.wav')).rejects.toThrow();
+  });
+
+  it('uses a custom spawn function and parses its stdout', async () => {
+    const audioPath = join(dir, 'a.wav');
+    await fs.writeFile(audioPath, ''); // empty placeholder
+    // Fake spawn that returns a synthetic whisper stdout
+    const fakeSpawn = (() => {
+      const ee = new EventEmitter() as unknown as import('node:child_process').ChildProcess;
+      const stdout = new EventEmitter() as unknown as NodeJS.ReadableStream;
+      const stderr = new EventEmitter() as unknown as NodeJS.ReadableStream;
+      Object.defineProperty(ee, 'stdout', { value: stdout });
+      Object.defineProperty(ee, 'stderr', { value: stderr });
+      setImmediate(() => {
+        (stdout as unknown as EventEmitter).emit(
+          'data',
+          Buffer.from('[00:00:00.000 --> 00:00:01.000]  hello'),
+        );
+        ee.emit('close', 0);
+      });
+      return ee;
+    }) as unknown as typeof import('node:child_process').spawn;
+    const p = new WhisperCppProvider({ modelPath: 'fake', exec: fakeSpawn });
+    const r = await p.transcribe(audioPath);
+    expect(r.text).toBe('hello');
+    expect(r.latencyMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it('throws when whisper exits non-zero', async () => {
+    const audioPath = join(dir, 'a.wav');
+    await fs.writeFile(audioPath, '');
+    const fakeSpawn = (() => {
+      const ee = new EventEmitter() as unknown as import('node:child_process').ChildProcess;
+      const stdout = new EventEmitter() as unknown as NodeJS.ReadableStream;
+      const stderr = new EventEmitter() as unknown as NodeJS.ReadableStream;
+      Object.defineProperty(ee, 'stdout', { value: stdout });
+      Object.defineProperty(ee, 'stderr', { value: stderr });
+      setImmediate(() => {
+        (stderr as unknown as EventEmitter).emit('data', Buffer.from('model not found'));
+        ee.emit('close', 1);
+      });
+      return ee;
+    }) as unknown as typeof import('node:child_process').spawn;
+    const p = new WhisperCppProvider({ modelPath: 'fake', exec: fakeSpawn });
+    await expect(p.transcribe(audioPath)).rejects.toThrow(/exited 1/);
+  });
+});
diff --git a/packages/core/src/voice/index.ts b/packages/core/src/voice/index.ts
new file mode 100644
index 0000000..0789cd0
--- /dev/null
+++ b/packages/core/src/voice/index.ts
@@ -0,0 +1,133 @@
+// Voice input subsystem — wraps a local Whisper.cpp model for ASR.
+// Spec: docs/DEVELOPMENT_PLAN.md §3.15 (M8)
+//
+// This is the abstraction layer; the actual whisper.cpp binary install +
+// model download is left to the user. Pluggable VoiceProvider lets us
+// swap in cloud APIs or a different local engine later.
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+
+export interface VoiceTranscript {
+  /** Transcribed text. */
+  text: string;
+  /** Detected language code (e.g. 'en', 'zh'). Optional — whisper can guess. */
+  language?: string;
+  /** Audio duration in seconds. */
+  durationSec?: number;
+  /** Time the transcription took. */
+  latencyMs: number;
+}
+
+export interface VoiceProvider {
+  readonly name: string;
+  /** Transcribe the audio at `audioPath` (typically a .wav file). */
+  transcribe(audioPath: string, opts?: TranscribeOpts): Promise<VoiceTranscript>;
+}
+
+export interface TranscribeOpts {
+  /** Force a language (skip auto-detect). */
+  language?: string;
+  /** Abort the transcription. */
+  signal?: AbortSignal;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// whisper.cpp provider — calls the `whisper` CLI
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface WhisperCppOpts {
+  /** Path to the whisper CLI binary. Defaults to `whisper` on PATH. */
+  binPath?: string;
+  /** Path to the model file. Required. */
+  modelPath: string;
+  /** Working dir for the CLI. */
+  cwd?: string;
+  /** Override exec for tests. */
+  exec?: typeof spawn;
+}
+
+export class WhisperCppProvider implements VoiceProvider {
+  readonly name = 'whisper.cpp';
+  constructor(private readonly opts: WhisperCppOpts) {}
+
+  async transcribe(audioPath: string, opts: TranscribeOpts = {}): Promise<VoiceTranscript> {
+    await fs.access(audioPath); // throws if missing
+    const t0 = Date.now();
+    const args = ['-m', this.opts.modelPath, '-f', audioPath, '--output-txt'];
+    if (opts.language) args.push('-l', opts.language);
+    const bin = this.opts.binPath ?? 'whisper';
+    const spawnFn = this.opts.exec ?? spawn;
+    const { stdout, stderr, code } = await runCommand(spawnFn, bin, args, this.opts.cwd, opts.signal);
+    const latency = Date.now() - t0;
+    if (code !== 0) {
+      throw new Error(`whisper.cpp exited ${code}: ${stderr.slice(0, 300)}`);
+    }
+    return {
+      text: parseWhisperOutput(stdout),
+      language: opts.language,
+      latencyMs: latency,
+    };
+  }
+}
+
+function runCommand(
+  spawnFn: typeof spawn,
+  bin: string,
+  args: string[],
+  cwd: string | undefined,
+  signal?: AbortSignal,
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((resolve, reject) => {
+    const p: ChildProcess = spawnFn(bin, args, { cwd });
+    let stdout = '';
+    let stderr = '';
+    p.stdout?.on('data', (c: Buffer) => (stdout += c.toString()));
+    p.stderr?.on('data', (c: Buffer) => (stderr += c.toString()));
+    p.on('error', reject);
+    p.on('close', (code) => resolve({ stdout, stderr, code: code ?? 0 }));
+    if (signal) {
+      signal.addEventListener('abort', () => {
+        try {
+          p.kill('SIGTERM');
+        } catch {
+          /* already dead */
+        }
+      });
+    }
+  });
+}
+
+/**
+ * Strip whisper.cpp's leading log lines and per-line timestamps to get the
+ * raw transcript. Public so tests can pin format details.
+ */
+export function parseWhisperOutput(raw: string): string {
+  const lines = raw.split('\n');
+  // whisper.cpp emits `[00:00:00.000 --> 00:00:01.234]  text...`
+  const tsRe = /^\[\d\d:\d\d:\d\d\.\d{3} --> \d\d:\d\d:\d\d\.\d{3}\]\s*/;
+  const parts: string[] = [];
+  for (const line of lines) {
+    const m = tsRe.exec(line);
+    if (m) {
+      parts.push(line.slice(m[0].length).trim());
+    } else if (line.trim() && !line.startsWith('whisper_') && !line.startsWith('system_info:')) {
+      // Plain text line not matching the timestamp prefix — include only
+      // if it doesn't look like a log message.
+      if (parts.length > 0 || /\w/.test(line)) parts.push(line.trim());
+    }
+  }
+  return parts.filter(Boolean).join(' ').trim();
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Stub provider — returns empty transcript. Useful in tests + when no
+// engine is configured.
+// ──────────────────────────────────────────────────────────────────────────
+
+export class StubVoiceProvider implements VoiceProvider {
+  readonly name = 'stub';
+  async transcribe(): Promise<VoiceTranscript> {
+    return { text: '', latencyMs: 0 };
+  }
+}