feat(voice): add OpenAI Realtime Expert and Spokesperson mode

docs/app-e2e.md

@@ -44,3 +44,47 @@ Windows uses the same runtime contract through `scripts/windows/Dev-Windows.ps1`
 Set `BERD_E2E_MODE=1`, `BERD_E2E_RUN_ROOT`, and the optional provider bootstrap
 environment above before invoking it; the app owns its random driver port and
 publishes readiness under the run root.
+
+## Live Realtime Expert–Spokesperson evaluation
+
+`tests/app-e2e/realtime-expert-spokesperson.eval.test.ts` is an opt-in live
+evaluation driven by typed chat messages. It starts a fresh Realtime voice
+conversation, mutes its microphone so ambient audio cannot affect the run, asks
+how many repositories are in the user's Development folder, then asks whether
+any are symbolic links. It verifies that each typed question is followed in
+order by visible Expert-to-Spokesperson coordination and a visible terminal Expert
+turn. Each turn may contain one finalized Spokesperson answer, or an
+acknowledgement and waiting update before the answer. More than three finalized
+utterances fails the evaluation as a likely coordination loop.
+
+The app-test-driver protocol serves one command per TCP connection, so
+the client opens a fresh authenticated connection for every command. Home
+navigation and promotion of its composer draft may temporarily replace the app
+webview; this eval waits for the expected destination after those two known
+boundaries without replaying the navigation or call-button click. Mutating
+actions remain single-shot.
+
+This scenario intentionally uses the normal local dev profile, not isolated
+E2E mode: Realtime needs the Berd-owned API key stored from Voice settings, and
+the Expert needs the normal configured agent/tool environment for inspecting the
+real Development folder. Before running it, select **OpenAI Realtime** as the
+Voice mode and save the Realtime API key in Berd.
+
+Start the instrumented app in one terminal:
+
+```bash
+APP_TEST_DRIVER_TOKEN=local-realtime-eval just dev-e2e
+```
+
+Then run only the live scenario in another terminal:
+
+```bash
+APP_TEST_DRIVER_TOKEN=local-realtime-eval \
+BERD_E2E_REALTIME_EVAL=1 \
+pnpm exec vitest run --config vitest.app-e2e.config.ts \
+  tests/app-e2e/realtime-expert-spokesperson.eval.test.ts
+```
+
+Without `BERD_E2E_REALTIME_EVAL=1`, the live scenario is skipped so the normal
+app E2E suite never makes network/model calls or depends on a developer's local
+filesystem and credentials.

scripts/block-feature-gates.sh

@@ -21,10 +21,6 @@ done
 [[ "${VITE_MANAGED_CONNECTIONS:-0}" == "1" ]] && features+=(block-managed-connections)
 [[ "${VITE_SKILL_DISCOVERY:-0}" == "1" ]] && features+=(block-skill-discovery)
 [[ "${VITE_TELEMETRY_ENFORCED:-0}" == "1" ]] && features+=(block-telemetry-enforced)
-if [[ "${VITE_VOICE_DICTATION:-0}" == "1" ]]; then
-  features+=(block-voice-dictation)
-else
-  features+=(no-voice-dictation)
-fi
+[[ "${VITE_VOICE_DICTATION:-0}" == "1" ]] && features+=(block-voice-dictation)
 
-(IFS=,; echo "${features[*]}")
+(IFS=,; echo "${features[*]:-}")

scripts/release/build-macos.sh

@@ -420,11 +420,7 @@ done
 # the user setting in Gate A and hides the toggle, the feature does the same
 # for the native Gate B in export_otel_logs.
 [[ "$VITE_TELEMETRY_ENFORCED_VALUE" == "1" ]] && CARGO_FEATURES="$CARGO_FEATURES,block-telemetry-enforced"
-if [[ "$VITE_VOICE_DICTATION_VALUE" == "1" ]]; then
-  CARGO_FEATURES="$CARGO_FEATURES,block-voice-dictation"
-else
-  CARGO_FEATURES="$CARGO_FEATURES,no-voice-dictation"
-fi
+[[ "$VITE_VOICE_DICTATION_VALUE" == "1" ]] && CARGO_FEATURES="$CARGO_FEATURES,block-voice-dictation"
 
 # bb CLI PATH install has no runtime-config representation; the custom pipeline
 # exposes a dedicated select that disables it via the Cargo feature.

scripts/release/tests/release-scripts.test.mjs

@@ -527,7 +527,6 @@ describe("build-macos Block-service feature seam", () => {
     expect(script).not.toContain(
       'VITE_AUTH_GATE_VALUE="$VITE_BUILDERBOT_VALUE"',
     );
-    expect(script).toContain("no-voice-dictation");
     expect(script).toContain('if [[ "$VITE_AGENT_TOOLS_VALUE" == "1" ]]; then');
     expect(script).toContain(
       'jq \'.bundle.resources["../resources/bb"] = "bb"\'',
@@ -2155,10 +2154,16 @@ async function canonicalGates() {
 }
 
 describe("Block feature gate propagation", () => {
+  it("supports an empty base feature set", () => {
+    const result = run("bash", ["scripts/block-feature-gates.sh"]);
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBe("");
+  });
+
   it("maps every updater-off default to the fail-closed Cargo posture", () => {
     const result = run("bash", ["scripts/block-feature-gates.sh", "berdctl"]);
     expect(result.status).toBe(0);
-    expect(result.stdout.trim()).toBe("berdctl,no-voice-dictation");
+    expect(result.stdout.trim()).toBe("berdctl");
   });
 
   it("maps every renderer gate to its matching Cargo feature", () => {

scripts/windows/Test-WindowsDev.ps1

@@ -77,7 +77,7 @@ try {
     Assert-Equal "process args: trailing backslash doubled inside quotes" (Join-WindowsProcessArguments -Arguments @("C:\Program Files\")) '"C:\Program Files\\"'
     Assert-Equal "process args: embedded quote escaped" (Join-WindowsProcessArguments -Arguments @('say "hi"')) '"say \"hi\""'
 
-    Assert-Equal "public app feature defaults fail closed" (Get-BerdAppFeatures) "berdctl,app-test-driver,no-voice-dictation"
+    Assert-Equal "public app feature defaults fail closed" (Get-BerdAppFeatures) "berdctl,app-test-driver"
     $featureGateNames = @("VITE_AGENT_TOOLS", "VITE_AUTOMATIONS", "VITE_BUILDERBOT", "VITE_FEEDBACK", "VITE_MANAGED_CONNECTIONS", "VITE_SKILL_DISCOVERY", "VITE_TELEMETRY_ENFORCED", "VITE_VOICE_DICTATION")
     $savedFeatureGates = @{}
     foreach ($name in $featureGateNames) {

scripts/windows/WindowsDev.psm1

@@ -513,9 +513,6 @@ function Get-BerdAppFeatures {
         }
         if ($value -eq "1") { $features.Add($gate.Feature) }
     }
-    if ([Environment]::GetEnvironmentVariable("VITE_VOICE_DICTATION", "Process") -ne "1") {
-        $features.Add("no-voice-dictation")
-    }
     return ($features -join ",")
 }
 

src-tauri/Cargo.toml

@@ -142,9 +142,6 @@ devtools = ["tauri/devtools"]
 # restricted build is expressed by ADDING these (never with
 # --no-default-features + re-listing everything you want to keep).
 #
-# no-voice-dictation: the realtime client secret is never requested
-# (`get_openai_realtime_status` reports `configured: false`).
-no-voice-dictation = []
 # no-bb-cli-install: the app never auto-installs or offers to symlink the
 # bundled berdctl into /usr/local/bin/bb. The bundled binary still ships for
 # direct `berdctl` use (gated separately by the `berdctl` protocol-server
@@ -177,6 +174,8 @@ block-skill-discovery = []
 # For managed internal distributions where consent is an employment-policy
 # fact, not a per-user choice.
 block-telemetry-enforced = []
+# Enables Block-service-backed voice dictation. Public Realtime voice is a
+# separate, user-configured path and does not depend on Block services.
 block-voice-dictation = []
 # Admin runtime-config endpoint fetch. Default-OFF: a normal build never
 # compiles the kgoose-backed fetch/cache path and instead loads the bundled

src-tauri/crates/berdctl/api-surface-feedback.json

@@ -3,7 +3,7 @@
   "protocolVersion": 4,
   "groups": {
     "sessions": {
-      "description": "Manage the user's chat sessions: create (fire-and-forget, on any installed agent harness), send, open, list, get, rename, move, move to group, clear project, fork, archive.",
+      "description": "Manage the user's chat sessions: create (fire-and-forget, on any installed agent harness), send, open, list, get, rename, move, move to group, clear project, send to a live voice Spokesperson, dismiss voice handoffs, fork, archive.",
       "actions": {
         "create": {
           "description": "Create a new chat session on any installed agent harness and send the prompt in it. Fire-and-forget: returns the session id immediately and the session runs in the background without changing what the user sees; the user can open it themselves. Use --from to give the delegating session or tool a concise visible label on the initial message. Only check on it later (action \"get\") if the user asks.",
@@ -427,6 +427,159 @@
             "additionalProperties": false
           }
         },
+        "send_to_spokesperson": {
+          "description": "Inject a private coordination message into the OpenAI Realtime voice Spokesperson owned by an existing Berd session. The Spokesperson receives the message either as silent context for future turns or as a request to speak now. The command fails when the target session has no live Realtime voice conversation.",
+          "fields": [
+            {
+              "name": "session_id",
+              "required": true,
+              "kind": "string",
+              "description": "Id of the session that owns the live Realtime Spokesperson.",
+              "min": 1
+            },
+            {
+              "name": "message",
+              "required": true,
+              "kind": "string",
+              "description": "Private coordination message to inject into the Spokesperson.",
+              "min": 1,
+              "max": 20000
+            },
+            {
+              "name": "cursor",
+              "required": true,
+              "kind": "number",
+              "description": "Newest cursor from any Expert-bound voice transcript, handoff, reminder, or bridge result.",
+              "min": 0,
+              "max": 4294967295
+            },
+            {
+              "name": "mode",
+              "required": false,
+              "kind": "string",
+              "description": "Delivery mode: context updates future turns silently; say asks the Spokesperson to speak now.",
+              "values": ["context", "say"]
+            },
+            {
+              "name": "resolves",
+              "required": false,
+              "kind": "string_array",
+              "description": "Open handoff id resolved by this say message; repeat for multiple handoffs."
+            }
+          ],
+          "schema": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "session_id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Id of the session that owns the live Realtime Spokesperson."
+              },
+              "message": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 20000,
+                "description": "Private coordination message to inject into the Spokesperson."
+              },
+              "cursor": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 4294967295,
+                "description": "Newest cursor from any Expert-bound voice transcript, handoff, reminder, or bridge result."
+              },
+              "mode": {
+                "default": "say",
+                "description": "Delivery mode: context updates future turns silently; say asks the Spokesperson to speak now.",
+                "type": "string",
+                "enum": ["context", "say"]
+              },
+              "resolves": {
+                "default": [],
+                "description": "Open handoff id resolved by this say message; repeat for multiple handoffs.",
+                "maxItems": 100,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 100
+                }
+              }
+            },
+            "required": ["session_id", "message", "cursor"],
+            "additionalProperties": false
+          }
+        },
+        "dismiss_handoffs": {
+          "description": "Explicitly close one or more open Realtime Spokesperson handoffs and deliver the reason as silent context without waking the Spokesperson. Use this only when a spoken response is obsolete, superseded, or already handled. The command and its reason remain visible in the Expert's normal Berd activity.",
+          "fields": [
+            {
+              "name": "session_id",
+              "required": true,
+              "kind": "string",
+              "description": "Id of the session that owns the live Realtime Spokesperson.",
+              "min": 1
+            },
+            {
+              "name": "cursor",
+              "required": true,
+              "kind": "number",
+              "description": "Newest cursor from any Expert-bound voice transcript, handoff, reminder, or bridge result.",
+              "min": 0,
+              "max": 4294967295
+            },
+            {
+              "name": "handoff_id",
+              "required": true,
+              "kind": "string_array",
+              "description": "Open handoff id to dismiss; repeat for multiple handoffs."
+            },
+            {
+              "name": "reason",
+              "required": true,
+              "kind": "string",
+              "description": "Why no spoken response is needed for these handoffs.",
+              "min": 1,
+              "max": 2000
+            }
+          ],
+          "schema": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "session_id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Id of the session that owns the live Realtime Spokesperson."
+              },
+              "cursor": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 4294967295,
+                "description": "Newest cursor from any Expert-bound voice transcript, handoff, reminder, or bridge result."
+              },
+              "handoff_id": {
+                "minItems": 1,
+                "maxItems": 100,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 100
+                },
+                "description": "Open handoff id to dismiss; repeat for multiple handoffs."
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 2000,
+                "description": "Why no spoken response is needed for these handoffs."
+              }
+            },
+            "required": ["session_id", "cursor", "handoff_id", "reason"],
+            "additionalProperties": false
+          }
+        },
         "fork": {
           "description": "Duplicate an existing chat session, copying its full conversation history into a new session the user can continue down an independent path. The fork appears in the app's session list; the user's current view does not change.",
           "fields": [