feat(desktop): deliver background-agent completions into live voice sessions

.github/scripts/product_file_line_count_ratchet_baseline/desktop-swift-floatingcontrolbar.json

@@ -4,14 +4,14 @@
     "desktop/macos/Desktop/Sources/FloatingControlBar/FloatingControlBarView.swift": 2853,
     "desktop/macos/Desktop/Sources/FloatingControlBar/FloatingControlBarWindow.swift": 4842,
     "desktop/macos/Desktop/Sources/FloatingControlBar/PushToTalkManager.swift": 2423,
-    "desktop/macos/Desktop/Sources/FloatingControlBar/RealtimeHubSession.swift": 1621
+    "desktop/macos/Desktop/Sources/FloatingControlBar/RealtimeHubSession.swift": 1647
   },
   "raise_justifications": {
     "desktop/macos/Desktop/Sources/FloatingControlBar/AgentPill.swift": "Agent completion presentation now follows the canonical terminal lifecycle used by PTT and chat.",
     "desktop/macos/Desktop/Sources/FloatingControlBar/FloatingControlBarView.swift": "Onboarding bar glow, the reach-error card (Retry/Skip), and the notch hover/voice surface-state boundary render on the shared bar surface.",
     "desktop/macos/Desktop/Sources/FloatingControlBar/FloatingControlBarWindow.swift": "Reach-error state lives with the owning manager; savePreChatCenterIfNeeded snaps to the full stored restore frame so the pill no longer drifts per re-open cycle.",
     "desktop/macos/Desktop/Sources/FloatingControlBar/PushToTalkManager.swift": "Strict concurrency annotations (Ticket 14) add Sendable conformances and isolation qualifiers without changing runtime behavior.",
-    "desktop/macos/Desktop/Sources/FloatingControlBar/RealtimeHubSession.swift": "Strict concurrency annotations (Ticket 14) add Sendable conformances and isolation qualifiers without changing runtime behavior."
+    "desktop/macos/Desktop/Sources/FloatingControlBar/RealtimeHubSession.swift": "sendBackgroundAgentContext is a non-buffering delivery variant (returns false instead of buffering) so voice completion acks only after confirmed provider send; it lives beside the sendTextInput path it deliberately diverges from."
   },
   "threshold": 1500
 }

.github/scripts/product_file_line_count_ratchet_baseline/desktop-swift-root.json

@@ -4,13 +4,13 @@
     "desktop/macos/Desktop/Sources/CloudConnectorFormAutomation.swift": 1678,
     "desktop/macos/Desktop/Sources/DesktopAutomationBridge.swift": 4238,
     "desktop/macos/Desktop/Sources/MemoryExportService.swift": 1578,
-    "desktop/macos/Desktop/Sources/OmiApp.swift": 1646
+    "desktop/macos/Desktop/Sources/OmiApp.swift": 1649
   },
   "raise_justifications": {
     "desktop/macos/Desktop/Sources/AuthService.swift": "Apple first-auth name capture signals observers (authNameDidUpdate) and persists the name to Firebase so it survives reinstalls.",
     "desktop/macos/Desktop/Sources/DesktopAutomationBridge.swift": "Reach-error card gains a debug bridge action so the actionable failure surface is verifiable in-process.",
     "desktop/macos/Desktop/Sources/MemoryExportService.swift": "Pinned swift-format normalizes line layout without changing this source's runtime behavior.",
-    "desktop/macos/Desktop/Sources/OmiApp.swift": "openMainAppChat() gives the floating bar Continue-in-Omi affordances a chat-landing entry next to openMainAppWindow()."
+    "desktop/macos/Desktop/Sources/OmiApp.swift": "openMainAppChat() adds a chat-landing entry beside openMainAppWindow(), and one startup call wires AgentCompletionVoiceDelivery into launch beside the other singleton starts; the service is a separate file."
   },
   "threshold": 1500
 }

desktop/macos/Desktop/Sources/Chat/AgentCompletionVoiceDelivery.swift

@@ -0,0 +1,158 @@
+import Combine
+import Foundation
+
+/// Bridges completed background-agent runs into the live realtime voice
+/// conversation.
+///
+/// The kernel journals a completed run and the floating pill shows it, but a
+/// live voice session has no eyes: nothing tells the realtime model that the
+/// agent it spawned has finished. This service watches run projections for
+/// transitions into a terminal state on background surfaces, reads the
+/// canonical completion delta from the kernel (`peekCompletedAgentDelta`,
+/// exactly-once via the per-surface checkpoint), and injects the delta prompt
+/// into the live provider session as untrusted context. No synthetic response
+/// is requested — the voice turn coordinator's output authority is untouched;
+/// the model mentions the completion at the next natural turn boundary and can
+/// answer follow-ups. The checkpoint advances only after the session confirms
+/// the send, so an undelivered completion is retried instead of lost.
+@MainActor
+final class AgentCompletionVoiceDelivery {
+  static let shared = AgentCompletionVoiceDelivery()
+
+  /// Background surfaces whose terminal transitions can carry a user-facing
+  /// completion. Primary conversational surfaces (main_chat, realtime_voice,
+  /// task_chat, …) reach a terminal state on every ordinary answer and must
+  /// not trigger kernel delta reads.
+  static let triggerSurfaceKinds: Set<String> = ["floating_bar", "service", "workstream"]
+
+  struct Delta {
+    let ids: [String]
+    let prompt: String
+    let completedAtHighWaterMs: Int?
+  }
+
+  private let isVoiceSessionLive: @MainActor () -> Bool
+  private let peekDelta: @MainActor () async -> Delta?
+  private let injectContext: @MainActor (String) async -> Bool
+  private let acknowledge: @MainActor (Delta) -> Void
+  private let scheduleWork: @MainActor (@escaping @MainActor () async -> Void) -> Void
+
+  private var cancellable: AnyCancellable?
+  private var lastStatusBySurface: [String: AgentRunProjectionStatus] = [:]
+  private var deliveryInFlight = false
+  private var deliveryQueued = false
+  /// The shared instance stays completely inert — no status subscription, no
+  /// delivery, no reach into the agent runtime — until `start()` runs at app
+  /// launch. This keeps `voiceSessionDidConnect()`, which the realtime hub calls
+  /// from `hubDidConnect` (exercised by RealtimeHub unit tests), a no-op in any
+  /// context that never started the service.
+  private var hasStarted: Bool
+
+  init(
+    isVoiceSessionLive: (@MainActor () -> Bool)? = nil,
+    peekDelta: (@MainActor () async -> Delta?)? = nil,
+    injectContext: (@MainActor (String) async -> Bool)? = nil,
+    acknowledge: (@MainActor (Delta) -> Void)? = nil,
+    scheduleWork: (@MainActor (@escaping @MainActor () async -> Void) -> Void)? = nil,
+    hasStarted: Bool = false
+  ) {
+    self.hasStarted = hasStarted
+    self.isVoiceSessionLive =
+      isVoiceSessionLive ?? { RealtimeHubController.shared.hasLiveVoiceSession }
+    self.peekDelta =
+      peekDelta
+      ?? {
+        guard
+          let delta = await DesktopCoordinatorService.shared.peekCompletedAgentDelta(
+            surface: .realtimeVoice())
+        else { return nil }
+        return Delta(
+          ids: delta.ids,
+          prompt: delta.prompt,
+          completedAtHighWaterMs: delta.completedAtHighWaterMs)
+      }
+    self.injectContext =
+      injectContext
+      ?? { text in
+        await RealtimeHubController.shared.injectBackgroundAgentCompletionContext(text)
+      }
+    self.acknowledge =
+      acknowledge
+      ?? { delta in
+        DesktopCoordinatorService.shared.acknowledgeCompletedAgentDelta(
+          surface: .realtimeVoice(),
+          ids: delta.ids,
+          completedAtHighWaterMs: delta.completedAtHighWaterMs)
+      }
+    self.scheduleWork = scheduleWork ?? { work in Task { await work() } }
+  }
+
+  /// Idempotent; called once from app launch.
+  func start() {
+    guard cancellable == nil else { return }
+    hasStarted = true
+    cancellable = AgentRuntimeStatusStore.shared.$projectionsBySurface
+      .sink { [weak self] projections in
+        self?.observe(projections)
+      }
+  }
+
+  /// A newly connected voice session drains completions that finished while no
+  /// session was live (their checkpoint was deliberately left unadvanced). Inert
+  /// until `start()` so the realtime hub's `hubDidConnect` hook never drives the
+  /// unstarted shared instance into the agent runtime during tests.
+  func voiceSessionDidConnect() {
+    guard hasStarted else { return }
+    scheduleDelivery()
+  }
+
+  func observe(_ projections: [String: AgentRunProjection]) {
+    var fired = false
+    for (key, projection) in projections {
+      let previous = lastStatusBySurface[key]
+      lastStatusBySurface[key] = projection.status
+      guard
+        projection.status.isTerminal,
+        previous != projection.status,
+        previous?.isTerminal != true,
+        Self.triggerSurfaceKinds.contains(projection.surface.surfaceKind)
+      else { continue }
+      fired = true
+    }
+    // Prune surfaces that disappeared so a cleared-and-recreated surface is a
+    // fresh transition rather than a suppressed repeat.
+    lastStatusBySurface = lastStatusBySurface.filter { projections[$0.key] != nil }
+    if fired {
+      scheduleDelivery()
+    }
+  }
+
+  private func scheduleDelivery() {
+    if deliveryInFlight {
+      deliveryQueued = true
+      return
+    }
+    deliveryInFlight = true
+    scheduleWork { [weak self] in
+      await self?.runDelivery()
+    }
+  }
+
+  private func runDelivery() async {
+    defer {
+      deliveryInFlight = false
+      if deliveryQueued {
+        deliveryQueued = false
+        scheduleDelivery()
+      }
+    }
+    guard isVoiceSessionLive() else { return }
+    guard let delta = await peekDelta() else { return }
+    guard await injectContext(delta.prompt) else {
+      log("AgentCompletionVoiceDelivery: completion context not delivered; checkpoint unadvanced")
+      return
+    }
+    acknowledge(delta)
+    log("AgentCompletionVoiceDelivery: delivered \(delta.ids.count) completion(s) to live voice session")
+  }
+}

desktop/macos/Desktop/Sources/FloatingControlBar/RealtimeHubController+AgentCompletionContext.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+/// Seam for `AgentCompletionVoiceDelivery`: lets completed background-agent
+/// results reach the live voice conversation as silent context, without
+/// touching the voice turn coordinator's output authority.
+extension RealtimeHubController {
+  /// True when a physical provider session exists (including warm-idle).
+  var hasLiveVoiceSession: Bool { session != nil }
+
+  /// Adds completed background-agent context to the live conversation without
+  /// requesting a response. Returns false when no session is live so the
+  /// caller leaves the completion checkpoint unadvanced and retries later.
+  func injectBackgroundAgentCompletionContext(_ text: String) async -> Bool {
+    guard let session else { return false }
+    return await session.sendBackgroundAgentContext(text)
+  }
+}

desktop/macos/Desktop/Sources/FloatingControlBar/RealtimeHubController+SessionDelegate.swift

@@ -1,4 +1,4 @@
 import AppKit
 import CoreGraphics
 import Foundation
 import OmiSupport
@@ -608,6 +608,7 @@
     guard isCurrentSession(source) else { return }
     lastWarmAt = Date()
     hubConnected = true  // authenticated + ready — PTT may now route turns to the hub
+    AgentCompletionVoiceDelivery.shared.voiceSessionDidConnect()
     let replayedReconnectTurn = reconnectAudioBuffer != nil
     let replayedReplacementTurn = replacementAudioBuffer != nil
     if replayedReplacementTurn {
@@ -1171,7 +1172,7 @@
     return false
   }
 
   func hubDidError(_ message: String, source: RealtimeHubSession) {
     guard isCurrentSession(source) else { return }
     if reconnectAudioBuffer == nil {
       _ = beginTransportRebindForActiveInputIfNeeded()

desktop/macos/Desktop/Sources/FloatingControlBar/RealtimeHubSession.swift

@@ -1,4 +1,4 @@
 import Foundation
 import Network
 import VoiceTurnDomain
 
@@ -118,6 +118,7 @@
   struct RealtimeHubInputLifecycleSnapshot: Equatable {
     let isOpen: Bool
     let activityOpen: Bool
+    let pendingTextInputCount: Int
     let pendingAudioChunkCount: Int
     let pendingVideoFrameCount: Int
     let pendingCommit: Bool
@@ -404,6 +405,7 @@
             returning: RealtimeHubInputLifecycleSnapshot(
               isOpen: self.isOpen,
               activityOpen: self.activityOpen,
+              pendingTextInputCount: self.pendingTextInputs.count,
               pendingAudioChunkCount: self.pendingAudio.count,
               pendingVideoFrameCount: self.pendingVideo.count,
               pendingCommit: self.pendingCommit,
@@ -500,6 +502,30 @@
     await sendTextInput(text, logLabel: "test text input")
   }
 
+  /// Silently appends completed background-agent context to the conversation
+  /// without requesting a response — the model uses it on its next turn.
+  ///
+  /// Unlike `sendTextInput`, this deliberately does NOT buffer: it returns
+  /// `true` only when the text is written to the live provider this call, and
+  /// `false` when the session cannot accept it right now (socket closed, or
+  /// Gemini has no open activity window). Buffering would let the completion be
+  /// dropped by `stop()`/`close()` (which clears `pendingTextInputs`) after the
+  /// caller already advanced its exactly-once checkpoint. Returning `false`
+  /// keeps the checkpoint unadvanced so the caller retries on the next terminal
+  /// transition or session connect.
+  func sendBackgroundAgentContext(_ text: String) async -> Bool {
+    await withCheckedContinuation { continuation in
+      q.async { [weak self] in
+        guard let self, self.isOpen, self.provider == .openai || self.activityOpen else {
+          continuation.resume(returning: false)
+          return
+        }
+        self.sendTextInputNow(text, logLabel: "background agent completion context")
+        continuation.resume(returning: true)
+      }
+    }
+  }
+
   /// A provider can complete a tool-only response after accepting the final tool
   /// result without emitting a user-facing reply. Continue the same physical turn
   /// once, never as a synthetic user request. The continuation is bounded here so

desktop/macos/Desktop/Sources/OmiApp.swift

@@ -1,4 +1,4 @@
 import FirebaseAuth
 import FirebaseCore
 import OmiSupport
 import OmiTheme
@@ -263,7 +263,7 @@
       isExporting: ViewExporter.shouldExport())
   }
 
   func applicationDidFinishLaunching(_ notification: Notification) {
     if ViewExporter.shouldExport() {
       ViewExporter.run()
       return
@@ -484,6 +484,9 @@
     // Start resource monitoring (memory, CPU, disk)
     ResourceMonitor.shared.start()
 
+    // Route completed background-agent results into live voice sessions.
+    AgentCompletionVoiceDelivery.shared.start()
+
     scheduleAppLifecycleMaintenance()
 
     // Identify user if already signed in