From dbcb83d035bd15431c1304f10c83ac2daef27970 Mon Sep 17 00:00:00 2001
From: kartikmanimuthu <kartikmanimuthu@gmail.com>
Date: Sat, 25 Jul 2026 10:14:33 +0530
Subject: [PATCH] feat(ui): voice dictation on AI prompt inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a mic button to every surface where a natural-language prompt is
typed, backed by the browser's Web Speech API — no new dependencies, no
API route, no AWS cost.

New modules:
- hooks/use-dictation.ts — binds speech recognition to an already-controlled
  text field. Snapshots the value at session start, then rewrites
  `snapshot + finalSoFar + interim` on each result event, so words appear
  live while the interim tail is swapped for the final transcript instead of
  duplicating after it. Continuous + interim recognition, mic released on
  unmount, session stopped when the field disables, and permission/capture
  errors surfaced as toasts while no-speech/aborted stay silent.
- components/voice/mic-button.tsx — ghost icon button that pulses and reports
  aria-pressed while listening; renders nothing on browsers without the API
  rather than showing a dead control.
- components/voice/dictation-textarea.tsx — drop-in Textarea wrapper that
  tucks the mic into the bottom-right corner.

Wired into nine surfaces: AI Ops composer, Inventory Ask AI, KB chat, Deep
Agent chat, Agent Ops new-run dialog, scheduled-task objective, both HIL
respond textareas, and the chat clarification card. Dictation appends to
existing text everywhere rather than replacing it.

Also fixes Deep Agent chat auto-resizing its textarea inside the onChange
handler off e.target, which meant programmatic writes never resized it. Moved
to an effect keyed on the value, which also fixes the box not shrinking when
cleared on send.

The engine is isolated inside useDictation, so a server-side model (Parakeet,
Transcribe) can be swapped in later without touching any call site.

Tests: 21 new (append-not-replace, interim to final swap, cumulative
multi-segment accumulation, maxLength clamping, unsupported browser,
disabled-mid-session, silence timeout, permission errors, unmount cleanup).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../web-ui/app/app/agent-ops/[runId]/page.tsx |   6 +-
 .../app/agent-ops/[runId]/respond/page.tsx    |   7 +-
 .../components/agent-ops/new-run-dialog.tsx   |   6 +-
 .../agent-ops/scheduled-task-dialog.tsx       |   6 +-
 .../agent/chat/clarification-card.tsx         |   2 +
 .../components/agent/workspace/composer.tsx   |   8 +
 .../components/deep-agent/deep-agent-chat.tsx |  14 +-
 .../components/inventory/ask-ai-dialog.tsx    |   7 +
 .../components/knowledge-base/kb-chat.tsx     |   2 +
 .../voice/__tests__/mic-button.test.tsx       |  95 +++++++
 .../components/voice/dictation-textarea.tsx   |  50 ++++
 apps/web-ui/components/voice/mic-button.tsx   |  72 +++++
 .../hooks/__tests__/use-dictation.test.tsx    | 214 +++++++++++++++
 apps/web-ui/hooks/use-dictation.ts            | 246 ++++++++++++++++++
 14 files changed, 720 insertions(+), 15 deletions(-)
 create mode 100644 apps/web-ui/components/voice/__tests__/mic-button.test.tsx
 create mode 100644 apps/web-ui/components/voice/dictation-textarea.tsx
 create mode 100644 apps/web-ui/components/voice/mic-button.tsx
 create mode 100644 apps/web-ui/hooks/__tests__/use-dictation.test.tsx
 create mode 100644 apps/web-ui/hooks/use-dictation.ts

diff --git a/apps/web-ui/app/app/agent-ops/[runId]/page.tsx b/apps/web-ui/app/app/agent-ops/[runId]/page.tsx
index 859bd156..2a96f8c4 100644
--- a/apps/web-ui/app/app/agent-ops/[runId]/page.tsx
+++ b/apps/web-ui/app/app/agent-ops/[runId]/page.tsx
@@ -5,7 +5,7 @@ import { useParams, useRouter } from "next/navigation"
 import { Button } from "@/components/ui/button"
 import { Badge } from "@/components/ui/badge"
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
-import { Textarea } from "@/components/ui/textarea"
+import { DictationTextarea } from "@/components/voice/dictation-textarea"
 import { MarkdownContent } from "@/components/ui/markdown-content"
 import { Spinner } from "@/components/ui/spinner"
 import {
@@ -187,10 +187,10 @@ export default function RunDetailPage() {
               <div className="mb-3 rounded-md border bg-background p-3">
                 <MarkdownContent content={run.clarification.question} />
               </div>
-              <Textarea
+              <DictationTextarea
                 placeholder="Type your response…"
                 value={clarificationText}
-                onChange={e => setClarificationText(e.target.value)}
+                onValueChange={setClarificationText}
                 rows={3}
                 disabled={resumeRun.isPending}
               />
diff --git a/apps/web-ui/app/app/agent-ops/[runId]/respond/page.tsx b/apps/web-ui/app/app/agent-ops/[runId]/respond/page.tsx
index 86533095..29420122 100644
--- a/apps/web-ui/app/app/agent-ops/[runId]/respond/page.tsx
+++ b/apps/web-ui/app/app/agent-ops/[runId]/respond/page.tsx
@@ -4,7 +4,7 @@
 import { useState, useEffect } from 'react';
 import { useParams, useRouter } from 'next/navigation';
 import { Button } from '@/components/ui/button';
-import { Textarea } from '@/components/ui/textarea';
+import { DictationTextarea } from '@/components/voice/dictation-textarea';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { Badge } from '@/components/ui/badge';
 
@@ -129,11 +129,12 @@ export default function RespondPage() {
                                 <p className="text-sm font-medium">Clarification needed:</p>
                                 <p className="text-sm mt-1">{run.clarification.question}</p>
                             </div>
-                            <Textarea
+                            <DictationTextarea
                                 placeholder="Type your response..."
                                 value={clarificationText}
-                                onChange={e => setClarificationText(e.target.value)}
+                                onValueChange={setClarificationText}
                                 rows={4}
+                                disabled={submitting}
                             />
                             <Button onClick={handleClarification} disabled={submitting || !clarificationText.trim()}>
                                 {submitting ? 'Submitting...' : 'Submit Response'}
diff --git a/apps/web-ui/components/agent-ops/new-run-dialog.tsx b/apps/web-ui/components/agent-ops/new-run-dialog.tsx
index cefdebb6..d2f66eb7 100644
--- a/apps/web-ui/components/agent-ops/new-run-dialog.tsx
+++ b/apps/web-ui/components/agent-ops/new-run-dialog.tsx
@@ -13,7 +13,7 @@ import {
     DialogTrigger,
 } from "@/components/ui/dialog"
 import { Button } from "@/components/ui/button"
-import { Textarea } from "@/components/ui/textarea"
+import { DictationTextarea } from "@/components/voice/dictation-textarea"
 import { Label } from "@/components/ui/label"
 
 export function NewRunDialog({
@@ -79,11 +79,11 @@ export function NewRunDialog({
                     {/* Task Description */}
                     <div className="space-y-2">
                         <Label>Objective</Label>
-                        <Textarea
+                        <DictationTextarea
                             placeholder="What do you want the agent to do? e.g., 'Check all Lambda functions in us-east-1 for public access'"
                             className="min-h-[100px]"
                             value={taskDescription}
-                            onChange={(e) => setTaskDescription(e.target.value)}
+                            onValueChange={setTaskDescription}
                         />
                     </div>
 
diff --git a/apps/web-ui/components/agent-ops/scheduled-task-dialog.tsx b/apps/web-ui/components/agent-ops/scheduled-task-dialog.tsx
index 55889577..68b643bb 100644
--- a/apps/web-ui/components/agent-ops/scheduled-task-dialog.tsx
+++ b/apps/web-ui/components/agent-ops/scheduled-task-dialog.tsx
@@ -13,7 +13,7 @@ import {
 } from "@/components/ui/dialog"
 import { Button } from "@/components/ui/button"
 import { Input } from "@/components/ui/input"
-import { Textarea } from "@/components/ui/textarea"
+import { DictationTextarea } from "@/components/voice/dictation-textarea"
 import { Label } from "@/components/ui/label"
 import { Switch } from "@/components/ui/switch"
 import {
@@ -181,11 +181,11 @@ export function ScheduledTaskDialog({ tenantId = "default", task, prefill, onSav
 
                     <div className="space-y-1.5">
                         <Label>Objective</Label>
-                        <Textarea
+                        <DictationTextarea
                             placeholder="What should the agent do on each run?"
                             className="min-h-[80px]"
                             value={form.description}
-                            onChange={e => set("description", e.target.value)}
+                            onValueChange={v => set("description", v)}
                         />
                     </div>
 
diff --git a/apps/web-ui/components/agent/chat/clarification-card.tsx b/apps/web-ui/components/agent/chat/clarification-card.tsx
index b402dbd1..5b5357cc 100644
--- a/apps/web-ui/components/agent/chat/clarification-card.tsx
+++ b/apps/web-ui/components/agent/chat/clarification-card.tsx
@@ -3,6 +3,7 @@
 import { useState } from "react";
 import { Button } from "@/components/ui/button";
 import { Textarea } from "@/components/ui/textarea";
+import { MicButton } from "@/components/voice/mic-button";
 import { Check, HelpCircle, Send } from "lucide-react";
 import type { PendingClarification } from "./run-state";
 
@@ -85,6 +86,7 @@ export function ClarificationCard({
                 }
               }}
             />
+            <MicButton value={text} onChange={setText} size="sm" />
             <Button size="sm" className="h-8 shrink-0" disabled={!text.trim()} onClick={() => submit(text)} aria-label="Send answer">
               <Send className="h-3.5 w-3.5" />
             </Button>
diff --git a/apps/web-ui/components/agent/workspace/composer.tsx b/apps/web-ui/components/agent/workspace/composer.tsx
index 97a42c21..57d4ba19 100644
--- a/apps/web-ui/components/agent/workspace/composer.tsx
+++ b/apps/web-ui/components/agent/workspace/composer.tsx
@@ -10,6 +10,7 @@ import { Switch } from "@/components/ui/switch";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
 import { FileUpload, type FileAttachment } from "@/components/agent/file-upload";
+import { MicButton } from "@/components/voice/mic-button";
 import { AccountChip, KbSection, ModelChip, SkillChip, ToolsSection, type ComposerContext } from "./composer-pickers";
 
 export type { ComposerContext } from "./composer-pickers";
@@ -241,6 +242,13 @@ export function Composer({
             </PopoverContent>
           </Popover>
 
+          <MicButton
+            value={value}
+            onChange={onChange}
+            disabled={disabled || isStreaming}
+            maxLength={MAX_CHARS}
+          />
+
           {onEnhance && (
             <Button
               type="button"
diff --git a/apps/web-ui/components/deep-agent/deep-agent-chat.tsx b/apps/web-ui/components/deep-agent/deep-agent-chat.tsx
index 6194cdcd..a6b4d75d 100644
--- a/apps/web-ui/components/deep-agent/deep-agent-chat.tsx
+++ b/apps/web-ui/components/deep-agent/deep-agent-chat.tsx
@@ -11,6 +11,7 @@ import { TodoPanel } from './todo-panel';
 import { ApprovalDialog } from './approval-dialog';
 import { McpSkillSelector } from './mcp-skill-selector';
 import { AccountSelector } from './account-selector';
+import { MicButton } from '@/components/voice/mic-button';
 import {
   Send,
   Bot,
@@ -478,10 +479,16 @@ export function DeepAgentChat() {
 
   function handleInput(e: React.ChangeEvent<HTMLTextAreaElement>) {
     setInput(e.target.value);
-    const el = e.target;
+  }
+
+  // Keyed on `input` rather than done inside handleInput so programmatic writes
+  // (voice dictation, clearing on send) resize the box too.
+  useEffect(() => {
+    const el = textareaRef.current;
+    if (!el) return;
     el.style.height = 'auto';
     el.style.height = Math.min(el.scrollHeight, 200) + 'px';
-  }
+  }, [input]);
 
   // ---------------------------------------------------------------------------
   // Render
@@ -618,7 +625,8 @@ export function DeepAgentChat() {
                 className="w-full bg-transparent px-4 pt-3 pb-11 text-sm text-foreground placeholder:text-muted-foreground outline-none resize-none overflow-y-auto"
                 disabled={isLoading}
               />
-              <div className="absolute bottom-2.5 right-2.5">
+              <div className="absolute bottom-2.5 right-2.5 flex items-center gap-1">
+                <MicButton value={input} onChange={setInput} disabled={isLoading} size="sm" />
                 <button
                   onClick={handleSend}
                   disabled={!input.trim() || isLoading}
diff --git a/apps/web-ui/components/inventory/ask-ai-dialog.tsx b/apps/web-ui/components/inventory/ask-ai-dialog.tsx
index 69ca0e74..b38c3cc7 100644
--- a/apps/web-ui/components/inventory/ask-ai-dialog.tsx
+++ b/apps/web-ui/components/inventory/ask-ai-dialog.tsx
@@ -5,6 +5,7 @@ import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { Badge } from "@/components/ui/badge";
+import { MicButton } from "@/components/voice/mic-button";
 import { Bot, Send, Sparkles, User, RefreshCw, Trash2, ChevronDown } from "lucide-react";
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
@@ -367,6 +368,12 @@ export function AskAIDialog({ open, onOpenChange, filters }: AskAIDialogProps) {
                             className="flex-1"
                             autoFocus
                         />
+                        <MicButton
+                            value={input}
+                            onChange={setInput}
+                            disabled={isLoading || isStreaming}
+                            className="self-center"
+                        />
                         <Button type="submit" disabled={isLoading || isStreaming || !input.trim()}>
                             <Send className="h-4 w-4" />
                             <span className="sr-only">Send</span>
diff --git a/apps/web-ui/components/knowledge-base/kb-chat.tsx b/apps/web-ui/components/knowledge-base/kb-chat.tsx
index f0423171..a051b4cd 100644
--- a/apps/web-ui/components/knowledge-base/kb-chat.tsx
+++ b/apps/web-ui/components/knowledge-base/kb-chat.tsx
@@ -12,6 +12,7 @@ import remarkGfm from "remark-gfm";
 import { KBChatSources, KBSource } from "./kb-chat-sources";
 import { KBChatSidebar } from "./kb-chat-sidebar";
 import { FileUpload, FileAttachment } from "@/components/agent/file-upload";
+import { MicButton } from "@/components/voice/mic-button";
 import { useKnowledgeBases } from "@/lib/queries/knowledge-base";
 import { useKBChatMessages } from "@/lib/queries/kb-chat";
 import { useProviderModels, defaultModelId } from "@/lib/queries/providers";
@@ -402,6 +403,7 @@ export function KBChat({ initialKbId }: KBChatProps) {
                   rows={1}
                   className="flex-1 resize-none bg-transparent text-sm outline-none placeholder:text-muted-foreground min-h-[24px] max-h-[160px] py-0.5 leading-relaxed"
                 />
+                <MicButton value={input} onChange={setInput} disabled={isBusy} />
                 <Button
                   type="button"
                   size="icon"
diff --git a/apps/web-ui/components/voice/__tests__/mic-button.test.tsx b/apps/web-ui/components/voice/__tests__/mic-button.test.tsx
new file mode 100644
index 00000000..ced6d32f
--- /dev/null
+++ b/apps/web-ui/components/voice/__tests__/mic-button.test.tsx
@@ -0,0 +1,95 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { MicButton } from '../mic-button';
+
+vi.mock('sonner', () => ({ toast: { error: vi.fn() } }));
+
+class MockRecognition {
+    static instances: MockRecognition[] = [];
+    lang = '';
+    continuous = false;
+    interimResults = false;
+    maxAlternatives = 0;
+    started = false;
+    onresult: ((event: unknown) => void) | null = null;
+    onerror: ((event: { error: string }) => void) | null = null;
+    onend: (() => void) | null = null;
+
+    constructor() {
+        MockRecognition.instances.push(this);
+    }
+    start() {
+        this.started = true;
+    }
+    stop() {
+        this.started = false;
+    }
+    abort() {
+        this.started = false;
+    }
+}
+
+const noop = () => {};
+
+describe('MicButton', () => {
+    beforeEach(() => {
+        MockRecognition.instances = [];
+        (window as unknown as { SpeechRecognition?: unknown }).SpeechRecognition = MockRecognition;
+    });
+
+    afterEach(() => {
+        delete (window as unknown as { SpeechRecognition?: unknown }).SpeechRecognition;
+    });
+
+    it('renders nothing on browsers without the Web Speech API', () => {
+        delete (window as unknown as { SpeechRecognition?: unknown }).SpeechRecognition;
+        render(<MicButton value="" onChange={noop} />);
+        expect(screen.queryByTestId('mic-button')).toBeNull();
+    });
+
+    it('renders an idle, unpressed mic when supported', () => {
+        render(<MicButton value="" onChange={noop} />);
+        const button = screen.getByTestId('mic-button');
+        expect(button.getAttribute('aria-label')).toBe('Start voice input');
+        expect(button.getAttribute('aria-pressed')).toBe('false');
+    });
+
+    it('flips to the pressed listening state on click', () => {
+        render(<MicButton value="" onChange={noop} />);
+        fireEvent.click(screen.getByTestId('mic-button'));
+
+        const button = screen.getByTestId('mic-button');
+        expect(button.getAttribute('aria-pressed')).toBe('true');
+        expect(button.getAttribute('aria-label')).toBe('Stop voice input');
+        expect(button.getAttribute('data-listening')).toBe('true');
+        expect(MockRecognition.instances).toHaveLength(1);
+    });
+
+    it('is disabled while idle and the field is disabled', () => {
+        render(<MicButton value="" onChange={noop} disabled />);
+        expect((screen.getByTestId('mic-button') as HTMLButtonElement).disabled).toBe(true);
+    });
+
+    it('stays clickable while listening even once the field disables, so it can be stopped', () => {
+        const { rerender } = render(<MicButton value="" onChange={noop} />);
+        fireEvent.click(screen.getByTestId('mic-button'));
+        rerender(<MicButton value="" onChange={noop} disabled />);
+        // The disabled prop stops the session; the button returns to idle.
+        expect(screen.getByTestId('mic-button').getAttribute('aria-pressed')).toBe('false');
+    });
+
+    it('writes the dictated transcript back through onChange', () => {
+        const onChange = vi.fn();
+        render(<MicButton value="scale" onChange={onChange} />);
+        fireEvent.click(screen.getByTestId('mic-button'));
+
+        const results = [{ length: 1, isFinal: true, 0: { transcript: 'the cluster' } }];
+        MockRecognition.instances[0].onresult?.({
+            resultIndex: 0,
+            results: Object.assign(results, { length: 1 }),
+        });
+
+        expect(onChange).toHaveBeenCalledWith('scale the cluster');
+    });
+});
diff --git a/apps/web-ui/components/voice/dictation-textarea.tsx b/apps/web-ui/components/voice/dictation-textarea.tsx
new file mode 100644
index 00000000..e600a490
--- /dev/null
+++ b/apps/web-ui/components/voice/dictation-textarea.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "@/lib/utils";
+import { Textarea } from "@/components/ui/textarea";
+import { MicButton } from "./mic-button";
+
+export interface DictationTextareaProps
+  extends Omit<React.ComponentProps<"textarea">, "value" | "onChange"> {
+  value: string;
+  /** Receives the new text directly — no ChangeEvent unwrapping at call sites. */
+  onValueChange: (next: string) => void;
+  /** Extra classes for the positioning wrapper, not the textarea. */
+  wrapperClassName?: string;
+}
+
+/**
+ * `Textarea` with a dictation mic tucked into its bottom-right corner.
+ *
+ * For standalone prompt fields that have no adjacent control row of their own.
+ * Surfaces that already render a send button next to the field should compose
+ * `MicButton` into that row instead.
+ */
+export const DictationTextarea = React.forwardRef<HTMLTextAreaElement, DictationTextareaProps>(
+  ({ value, onValueChange, className, wrapperClassName, disabled, maxLength, ...props }, ref) => {
+    return (
+      <div className={cn("relative", wrapperClassName)}>
+        <Textarea
+          ref={ref}
+          value={value}
+          onChange={(e) => onValueChange(e.target.value)}
+          disabled={disabled}
+          maxLength={maxLength}
+          // Reserve the corner the mic occupies so text never slides under it.
+          className={cn("pr-11", className)}
+          {...props}
+        />
+        <MicButton
+          value={value}
+          onChange={onValueChange}
+          disabled={disabled}
+          maxLength={maxLength}
+          size="sm"
+          className="absolute bottom-1.5 right-1.5"
+        />
+      </div>
+    );
+  },
+);
+DictationTextarea.displayName = "DictationTextarea";
diff --git a/apps/web-ui/components/voice/mic-button.tsx b/apps/web-ui/components/voice/mic-button.tsx
new file mode 100644
index 00000000..723b4893
--- /dev/null
+++ b/apps/web-ui/components/voice/mic-button.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import { Mic } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+import { useDictation } from "@/hooks/use-dictation";
+
+export interface MicButtonProps {
+  /** Current field value — dictation appends to it. */
+  value: string;
+  /** Controlled-field setter the transcript is written back through. */
+  onChange: (next: string) => void;
+  disabled?: boolean;
+  /** Mirrors the field's own `maxLength`, so dictation respects the same cap. */
+  maxLength?: number;
+  /** `sm` (h-7) suits dense inline rows; `default` (h-8) matches send buttons. */
+  size?: "sm" | "default";
+  className?: string;
+}
+
+/**
+ * Push-to-dictate button for a controlled text field.
+ *
+ * Renders nothing on browsers without the Web Speech API (e.g. Firefox) — a
+ * visible-but-dead mic is worse than no mic at all.
+ */
+export function MicButton({
+  value,
+  onChange,
+  disabled = false,
+  maxLength,
+  size = "default",
+  className,
+}: MicButtonProps) {
+  const { isSupported, isListening, toggle } = useDictation({
+    value,
+    onChange,
+    disabled,
+    maxLength,
+  });
+
+  if (!isSupported) return null;
+
+  const label = isListening ? "Stop voice input" : "Start voice input";
+
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="icon"
+      onClick={toggle}
+      // While listening the button must stay clickable so dictation can be
+      // stopped even if the field itself has just been disabled.
+      disabled={disabled && !isListening}
+      aria-label={label}
+      aria-pressed={isListening}
+      title={label}
+      data-testid="mic-button"
+      data-listening={isListening ? "true" : "false"}
+      className={cn(
+        "shrink-0 rounded-full text-muted-foreground transition-colors hover:text-foreground",
+        size === "sm" ? "h-7 w-7" : "h-8 w-8",
+        isListening && "bg-destructive/10 text-destructive hover:text-destructive",
+        className,
+      )}
+    >
+      <Mic
+        className={cn(size === "sm" ? "h-3.5 w-3.5" : "h-4 w-4", isListening && "animate-pulse")}
+      />
+    </Button>
+  );
+}
diff --git a/apps/web-ui/hooks/__tests__/use-dictation.test.tsx b/apps/web-ui/hooks/__tests__/use-dictation.test.tsx
new file mode 100644
index 00000000..a679388e
--- /dev/null
+++ b/apps/web-ui/hooks/__tests__/use-dictation.test.tsx
@@ -0,0 +1,214 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { act, render } from '@testing-library/react';
+import { useDictation, type UseDictation } from '../use-dictation';
+
+const toastError = vi.fn();
+vi.mock('sonner', () => ({ toast: { error: (...args: unknown[]) => toastError(...args) } }));
+
+/** Stand-in for the browser's SpeechRecognition, driveable from tests. */
+class MockRecognition {
+    static instances: MockRecognition[] = [];
+
+    lang = '';
+    continuous = false;
+    interimResults = false;
+    maxAlternatives = 0;
+    started = false;
+    aborted = false;
+
+    onresult: ((event: unknown) => void) | null = null;
+    onerror: ((event: { error: string }) => void) | null = null;
+    onend: (() => void) | null = null;
+
+    constructor() {
+        MockRecognition.instances.push(this);
+    }
+
+    start() {
+        this.started = true;
+    }
+    stop() {
+        this.started = false;
+    }
+    abort() {
+        this.aborted = true;
+        this.started = false;
+    }
+
+    /**
+     * Emit a result event shaped like the real API's: `results` is the
+     * cumulative list for the session and `resultIndex` marks the first entry
+     * that changed, so consumers only re-read from there.
+     */
+    emit(segments: Array<{ transcript: string; isFinal: boolean }>, resultIndex = 0) {
+        const results = segments.map((s) => ({
+            length: 1,
+            isFinal: s.isFinal,
+            0: { transcript: s.transcript },
+        }));
+        this.onresult?.({
+            resultIndex,
+            results: Object.assign(results, { length: results.length }),
+        });
+    }
+}
+
+/** Renders the hook and exposes its latest return value plus the live value. */
+function setup(initial = '', options: { maxLength?: number; disabled?: boolean } = {}) {
+    const state = { value: initial, hook: null as UseDictation | null };
+
+    function Harness({ disabled }: { disabled?: boolean }) {
+        const [value, setValue] = React.useState(initial);
+        state.value = value;
+        state.hook = useDictation({
+            value,
+            onChange: setValue,
+            disabled,
+            maxLength: options.maxLength,
+        });
+        return null;
+    }
+
+    const utils = render(<Harness disabled={options.disabled} />);
+    return { state, utils, Harness };
+}
+
+describe('useDictation', () => {
+    beforeEach(() => {
+        MockRecognition.instances = [];
+        toastError.mockClear();
+        (window as unknown as { SpeechRecognition?: unknown }).SpeechRecognition = MockRecognition;
+    });
+
+    afterEach(() => {
+        delete (window as unknown as { SpeechRecognition?: unknown }).SpeechRecognition;
+    });
+
+    it('reports support once mounted on a browser exposing the API', () => {
+        const { state } = setup();
+        expect(state.hook?.isSupported).toBe(true);
+    });
+
+    it('reports no support when the API is absent', () => {
+        delete (window as unknown as { SpeechRecognition?: unknown }).SpeechRecognition;
+        const { state } = setup();
+        expect(state.hook?.isSupported).toBe(false);
+    });
+
+    it('appends the transcript after existing text instead of replacing it', () => {
+        const { state } = setup('check the');
+        act(() => state.hook!.toggle());
+        act(() => MockRecognition.instances[0].emit([{ transcript: 'lambda logs', isFinal: true }]));
+        expect(state.value).toBe('check the lambda logs');
+    });
+
+    it('does not insert a separator when the existing text already ends in a space', () => {
+        const { state } = setup('check the ');
+        act(() => state.hook!.toggle());
+        act(() => MockRecognition.instances[0].emit([{ transcript: 'logs', isFinal: true }]));
+        expect(state.value).toBe('check the logs');
+    });
+
+    it('replaces the interim tail with the final transcript rather than duplicating it', () => {
+        const { state } = setup();
+        act(() => state.hook!.toggle());
+
+        act(() => MockRecognition.instances[0].emit([{ transcript: 'restart the', isFinal: false }]));
+        expect(state.value).toBe('restart the');
+
+        act(() => MockRecognition.instances[0].emit([{ transcript: 'restart the database', isFinal: true }]));
+        expect(state.value).toBe('restart the database');
+    });
+
+    it('accumulates successive final segments across result events', () => {
+        const { state } = setup();
+        act(() => state.hook!.toggle());
+        act(() => MockRecognition.instances[0].emit([{ transcript: 'one ', isFinal: true }], 0));
+        act(() =>
+            MockRecognition.instances[0].emit(
+                [
+                    { transcript: 'one ', isFinal: true },
+                    { transcript: 'two', isFinal: true },
+                ],
+                1,
+            ),
+        );
+        expect(state.value).toBe('one two');
+    });
+
+    it('clamps the transcript to maxLength', () => {
+        const { state } = setup('', { maxLength: 8 });
+        act(() => state.hook!.toggle());
+        act(() => MockRecognition.instances[0].emit([{ transcript: 'far too long', isFinal: true }]));
+        expect(state.value).toBe('far too ');
+    });
+
+    it('configures continuous recognition with interim results', () => {
+        const { state } = setup();
+        act(() => state.hook!.toggle());
+        const recognition = MockRecognition.instances[0];
+        expect(recognition.continuous).toBe(true);
+        expect(recognition.interimResults).toBe(true);
+        expect(recognition.started).toBe(true);
+        expect(state.hook?.isListening).toBe(true);
+    });
+
+    it('toggles a live session off', () => {
+        const { state } = setup();
+        act(() => state.hook!.toggle());
+        act(() => state.hook!.toggle());
+        expect(state.hook?.isListening).toBe(false);
+        expect(MockRecognition.instances).toHaveLength(1);
+        expect(MockRecognition.instances[0].started).toBe(false);
+    });
+
+    it('does not start while disabled', () => {
+        const { state } = setup('', { disabled: true });
+        act(() => state.hook!.toggle());
+        expect(MockRecognition.instances).toHaveLength(0);
+        expect(state.hook?.isListening).toBe(false);
+    });
+
+    it('stops an in-flight session when the field becomes disabled', () => {
+        const { state, utils, Harness } = setup();
+        act(() => state.hook!.toggle());
+        expect(state.hook?.isListening).toBe(true);
+
+        utils.rerender(<Harness disabled />);
+        expect(state.hook?.isListening).toBe(false);
+        expect(MockRecognition.instances[0].started).toBe(false);
+    });
+
+    it('clears listening state when the browser ends the session on silence', () => {
+        const { state } = setup();
+        act(() => state.hook!.toggle());
+        act(() => MockRecognition.instances[0].onend?.());
+        expect(state.hook?.isListening).toBe(false);
+    });
+
+    it('surfaces a toast and stops on a permission error', () => {
+        const { state } = setup();
+        act(() => state.hook!.toggle());
+        act(() => MockRecognition.instances[0].onerror?.({ error: 'not-allowed' }));
+        expect(toastError).toHaveBeenCalledOnce();
+        expect(state.hook?.isListening).toBe(false);
+    });
+
+    it('stays silent on no-speech and aborted, which are normal end signals', () => {
+        const { state } = setup();
+        act(() => state.hook!.toggle());
+        act(() => MockRecognition.instances[0].onerror?.({ error: 'no-speech' }));
+        expect(toastError).not.toHaveBeenCalled();
+        expect(state.hook?.isListening).toBe(false);
+    });
+
+    it('releases the microphone when the field unmounts mid-session', () => {
+        const { state, utils } = setup();
+        act(() => state.hook!.toggle());
+        const recognition = MockRecognition.instances[0];
+        utils.unmount();
+        expect(recognition.aborted).toBe(true);
+    });
+});
diff --git a/apps/web-ui/hooks/use-dictation.ts b/apps/web-ui/hooks/use-dictation.ts
new file mode 100644
index 00000000..a89b990f
--- /dev/null
+++ b/apps/web-ui/hooks/use-dictation.ts
@@ -0,0 +1,246 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+
+/**
+ * Minimal structural types for the Web Speech API. `lib.dom` does not ship
+ * these reliably across TS versions, and we only touch the handful of members
+ * below, so we declare them locally rather than pulling in a types package.
+ */
+interface SpeechRecognitionAlternativeLike {
+    transcript: string;
+}
+
+interface SpeechRecognitionResultLike {
+    readonly length: number;
+    readonly isFinal: boolean;
+    [index: number]: SpeechRecognitionAlternativeLike;
+}
+
+interface SpeechRecognitionResultListLike {
+    readonly length: number;
+    [index: number]: SpeechRecognitionResultLike;
+}
+
+interface SpeechRecognitionEventLike {
+    readonly resultIndex: number;
+    readonly results: SpeechRecognitionResultListLike;
+}
+
+interface SpeechRecognitionErrorEventLike {
+    readonly error: string;
+}
+
+interface SpeechRecognitionLike {
+    lang: string;
+    continuous: boolean;
+    interimResults: boolean;
+    maxAlternatives: number;
+    start(): void;
+    stop(): void;
+    abort(): void;
+    onresult: ((event: SpeechRecognitionEventLike) => void) | null;
+    onerror: ((event: SpeechRecognitionErrorEventLike) => void) | null;
+    onend: (() => void) | null;
+}
+
+type SpeechRecognitionCtor = new () => SpeechRecognitionLike;
+
+function getSpeechRecognitionCtor(): SpeechRecognitionCtor | null {
+    if (typeof window === "undefined") return null;
+    const w = window as unknown as {
+        SpeechRecognition?: SpeechRecognitionCtor;
+        webkitSpeechRecognition?: SpeechRecognitionCtor;
+    };
+    return w.SpeechRecognition ?? w.webkitSpeechRecognition ?? null;
+}
+
+/** Human-readable messages for the error codes worth surfacing to the user. */
+const ERROR_MESSAGES: Record<string, string> = {
+    "not-allowed": "Microphone access was blocked. Allow it in your browser settings to dictate.",
+    "service-not-allowed": "Speech recognition is unavailable in this browser session.",
+    "audio-capture": "No microphone was found. Connect one and try again.",
+    network: "Speech recognition lost its network connection.",
+};
+
+/** Error codes that are normal end-of-utterance signals, not real failures. */
+const SILENT_ERRORS = new Set(["no-speech", "aborted"]);
+
+export interface UseDictationOptions {
+    /** Current field value — the hook appends to it rather than replacing it. */
+    value: string;
+    /** Controlled-field setter the transcript is written back through. */
+    onChange: (next: string) => void;
+    /** When true, an in-flight session is stopped and `toggle` is a no-op. */
+    disabled?: boolean;
+    /** Mirrors the field's own `maxLength`; the transcript is clamped to it. */
+    maxLength?: number;
+    /** BCP-47 tag. Defaults to the browser's language, then `en-US`. */
+    lang?: string;
+}
+
+export interface UseDictation {
+    /** False during SSR and on browsers without the Web Speech API. */
+    isSupported: boolean;
+    isListening: boolean;
+    /** Start if idle, stop if listening. */
+    toggle: () => void;
+    stop: () => void;
+}
+
+/**
+ * Binds the browser's speech recognition to an already-controlled text field.
+ *
+ * Dictation *appends*: the value is snapshotted when a session starts, and each
+ * `result` event rewrites `snapshot + finalSoFar + interim`. That makes words
+ * appear live as they are spoken while the interim tail is swapped for the
+ * final transcript instead of being duplicated after it.
+ */
+export function useDictation({
+    value,
+    onChange,
+    disabled = false,
+    maxLength,
+    lang,
+}: UseDictationOptions): UseDictation {
+    const [isSupported, setIsSupported] = useState(false);
+    const [isListening, setIsListening] = useState(false);
+
+    const recognitionRef = useRef<SpeechRecognitionLike | null>(null);
+    // Value at the moment the session started; every result rebuilds from it.
+    const baseRef = useRef("");
+    // Final transcript accumulated across result events in this session.
+    const finalRef = useRef("");
+
+    // Callbacks below are attached once per session, so read live values via refs.
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const valueRef = useRef(value);
+    valueRef.current = value;
+    const maxLengthRef = useRef(maxLength);
+    maxLengthRef.current = maxLength;
+
+    // Resolved in an effect (not during render) so the server and the first
+    // client render agree and hydration does not mismatch.
+    useEffect(() => {
+        setIsSupported(getSpeechRecognitionCtor() !== null);
+    }, []);
+
+    const stop = useCallback(() => {
+        const recognition = recognitionRef.current;
+        recognitionRef.current = null;
+        setIsListening(false);
+        if (recognition) {
+            recognition.onresult = null;
+            recognition.onerror = null;
+            recognition.onend = null;
+            try {
+                recognition.stop();
+            } catch {
+                // Already stopped — nothing to unwind.
+            }
+        }
+    }, []);
+
+    const start = useCallback(() => {
+        const Ctor = getSpeechRecognitionCtor();
+        if (!Ctor || recognitionRef.current) return;
+
+        let recognition: SpeechRecognitionLike;
+        try {
+            recognition = new Ctor();
+        } catch {
+            toast.error("Voice input could not be started in this browser.");
+            return;
+        }
+
+        recognition.lang =
+            lang ?? (typeof navigator !== "undefined" ? navigator.language : "") ?? "en-US";
+        recognition.continuous = true;
+        recognition.interimResults = true;
+        recognition.maxAlternatives = 1;
+
+        // Start a fresh utterance after whatever is already in the field.
+        const existing = valueRef.current;
+        baseRef.current = existing && !existing.endsWith(" ") ? `${existing} ` : existing;
+        finalRef.current = "";
+
+        recognition.onresult = (event) => {
+            let interim = "";
+            for (let i = event.resultIndex; i < event.results.length; i++) {
+                const result = event.results[i];
+                const transcript = result[0]?.transcript ?? "";
+                if (result.isFinal) {
+                    finalRef.current += transcript;
+                } else {
+                    interim += transcript;
+                }
+            }
+            let next = baseRef.current + finalRef.current + interim;
+            const limit = maxLengthRef.current;
+            if (typeof limit === "number" && next.length > limit) {
+                next = next.slice(0, limit);
+            }
+            onChangeRef.current(next);
+        };
+
+        recognition.onerror = (event) => {
+            if (!SILENT_ERRORS.has(event.error)) {
+                toast.error(ERROR_MESSAGES[event.error] ?? "Voice input failed. Please try again.");
+            }
+            stop();
+        };
+
+        recognition.onend = () => {
+            // The browser ends the session on its own after a silence timeout.
+            recognitionRef.current = null;
+            setIsListening(false);
+        };
+
+        try {
+            recognition.start();
+        } catch {
+            toast.error("Voice input could not be started. Please try again.");
+            return;
+        }
+
+        recognitionRef.current = recognition;
+        setIsListening(true);
+    }, [lang, stop]);
+
+    const toggle = useCallback(() => {
+        if (recognitionRef.current) {
+            stop();
+            return;
+        }
+        if (disabled) return;
+        start();
+    }, [disabled, start, stop]);
+
+    // A field that becomes disabled (submitting, streaming) must not keep the
+    // mic hot — the transcript would have nowhere to land.
+    useEffect(() => {
+        if (disabled && recognitionRef.current) stop();
+    }, [disabled, stop]);
+
+    // Release the microphone if the field unmounts mid-session.
+    useEffect(() => {
+        return () => {
+            const recognition = recognitionRef.current;
+            recognitionRef.current = null;
+            if (recognition) {
+                recognition.onresult = null;
+                recognition.onerror = null;
+                recognition.onend = null;
+                try {
+                    recognition.abort();
+                } catch {
+                    // Already torn down.
+                }
+            }
+        };
+    }, []);
+
+    return { isSupported, isListening, toggle, stop };
+}