DesktopCoordinatorService.swift

import Foundation

protocol DesktopCoordinatorRuntimeControlling: Sendable {
  func directControlTool(
    clientId: String,
    harnessMode: String,
    name: String,
    input: RuntimeJSONPayloadBox
  ) async throws -> String
}

extension AgentRuntimeProcess: DesktopCoordinatorRuntimeControlling {
  func directControlTool(
    clientId: String,
    harnessMode: String,
    name: String,
    input: RuntimeJSONPayloadBox
  ) async throws -> String {
    try await directControlTool(
      clientId: clientId,
      harnessMode: harnessMode,
      name: name,
      input: input,
      authorizationSnapshot: nil)
  }
}

enum DesktopCoordinatorOriginSurface: String, CaseIterable, Sendable {
  case mainChat = "main_chat"
  case floatingBar = "floating_bar"
  case realtime = "realtime"
  case taskChat = "task_chat"

  init(surfaceKind: String?) {
    switch surfaceKind {
    case "floating_bar": self = .floatingBar
    case "realtime", "realtime_voice": self = .realtime
    case "task_chat", "workstream": self = .taskChat
    default: self = .mainChat
    }
  }
}

struct DesktopCoordinatorAwarenessSnapshot: Codable {
  let generatedAt: String
  let source: String
  let runtimeControlTools: [String]
  let automation: DesktopCoordinatorAutomationProjection
  let sessions: [DesktopCoordinatorSessionProjection]
  let debugDispatches: [DesktopCoordinatorDispatchProjection]
  let runtimeError: String?
}

struct DesktopCoordinatorAutomationProjection: Codable {
  let bridgeEnabled: Bool
  let bridgePort: UInt16
  let bundleIdentifier: String
  let appState: String
  let selectedTab: String?
  let askOmiOpen: Bool
  let floatingBarVisible: Bool
}

struct DesktopCoordinatorSessionProjection: Codable {
  let sessionId: String?
  let title: String
  let surfaceKind: String?
  let externalRefKind: String?
  let externalRefId: String?
  let status: String
  let runId: String?
  let runStatus: String?
  let runMode: String?
  let attemptId: String?
  let provider: String?
  let updatedAt: String?
  let source: String
}

struct DesktopCoordinatorActionQueueItem: Codable {
  let id: String
  let rank: Int
  let kind: String
  let title: String
  let status: String
  let sessionId: String?
  let runId: String?
  let dispatchId: String?
  let source: String
}

struct DesktopCoordinatorOpenLoops: Codable {
  let generatedAt: String
  let items: [DesktopCoordinatorActionQueueItem]
}

enum DesktopCoordinatorIntentProposal: Equatable {
  case answerInline
  case spawnAgent
  case continueRun
  case clarify(missing: [String])

  var payload: [String: Any] {
    switch self {
    case .answerInline:
      return ["intent": "answer_inline"]
    case .spawnAgent:
      return ["intent": "spawn_agent"]
    case .continueRun:
      return ["intent": "continue_run"]
    case .clarify(let missing):
      return ["intent": "clarify", "missing": missing]
    }
  }
}

struct DesktopCoordinatorIntentSyntaxFacts: Equatable {
  var delegationNegated: Bool?
  var explicitSessionId: String?
  var explicitRunId: String?
  var parentRunId: String?
  var explicitProvider: String?
  var requestedAgentCount: Int?

  var payload: [String: Any] {
    var result: [String: Any] = [:]
    if let delegationNegated { result["delegationNegated"] = delegationNegated }
    if let explicitSessionId { result["explicitSessionId"] = explicitSessionId }
    if let explicitRunId { result["explicitRunId"] = explicitRunId }
    if let parentRunId { result["parentRunId"] = parentRunId }
    if let explicitProvider { result["explicitProvider"] = explicitProvider }
    if let requestedAgentCount { result["requestedAgentCount"] = requestedAgentCount }
    return result
  }
}

struct DesktopCoordinatorRouteDecision: Equatable {
  let decisionId: String
  let intent: String
  let surfaceKind: String
  let snapshotVersion: String
  let reasonCode: String
  let explanation: String
  let sessionId: String?
  let runId: String?
  let requestedProvider: String?
  let requestedAgentCount: Int?
  let parentRunId: String?
  let missing: [String]
  let rejectionCode: String?
}

struct DesktopCoordinatorDispatchProjection: Codable {
  let dispatchId: String
  let kind: String
  let status: String
  let title: String
  let decisionPrompt: String
  let recommendedDefault: String?
  let sourceSessionId: String?
  let sourceRunId: String?
  let createdAt: String
  let resolvedAt: String?
  let resolution: String?
  let source: String
}

struct DesktopCoordinatorCompletionDeltaItem: Codable {
  let id: String
  let title: String
  let surfaceKind: String?
  let externalRefKind: String?
  let externalRefId: String?
  let status: String
  let sessionId: String?
  let runId: String?
  let completedAtMs: Int?
  let finalText: String
  /// The prompt that spawned the run, when the kernel payload carries it. A
  /// completion is meaningless to the model without the question it answers.
  let inputPrompt: String?

  init(
    id: String,
    title: String,
    surfaceKind: String?,
    externalRefKind: String?,
    externalRefId: String?,
    status: String,
    sessionId: String?,
    runId: String?,
    completedAtMs: Int?,
    finalText: String,
    inputPrompt: String? = nil
  ) {
    self.id = id
    self.title = title
    self.surfaceKind = surfaceKind
    self.externalRefKind = externalRefKind
    self.externalRefId = externalRefId
    self.status = status
    self.sessionId = sessionId
    self.runId = runId
    self.completedAtMs = completedAtMs
    self.finalText = finalText
    self.inputPrompt = inputPrompt
  }
}

struct DesktopCoordinatorCompletionDelta: Codable {
  let ids: [String]
  let prompt: String
  let completedAtHighWaterMs: Int?
  // Artifacts produced by the newly-completed sub-agents in this delta, so the
  // consuming surface (main chat / notch) can render them as resource cards on
  // the parent's response.
  var artifacts: [AgentArtifactProjection] = []
}

struct DesktopCoordinatorSpawnedAgent: Codable {
  let sessionId: String
  let runId: String
  let attemptId: String?
  let title: String
  let externalRefId: String?
}

struct DesktopCoordinatorSpawnBatch: Codable {
  let requestedAgentCount: Int
  let agents: [DesktopCoordinatorSpawnedAgent]
}

struct DesktopCoordinatorProducerJournalDescriptor: Sendable {
  static let schemaVersion = 1

  let surface: AgentSurfaceReference
  let continuityKey: String
  let pillId: UUID
  let userText: String
  let assistantText: String
  let objective: String
  let title: String

  var dictionary: [String: Any] {
    [
      "schemaVersion": Self.schemaVersion,
      "surface": [
        "surfaceKind": surface.surfaceKind,
        "externalRefKind": surface.externalRefKind,
        "externalRefId": surface.externalRefId,
      ],
      "continuityKey": continuityKey,
      "pillId": pillId.uuidString,
      "userText": userText,
      "assistantText": assistantText,
      "objective": objective,
      "title": title,
    ]
  }
}

struct DesktopCoordinatorAgentRunInspection: Codable {
  let sessionId: String?
  let runId: String?
  let attemptId: String?
  let provider: String?
  let status: String
  let finalText: String?
  let errorMessage: String?
  let artifacts: [AgentArtifactProjection]
}

@MainActor
final class DesktopCoordinatorService {
  static let shared = DesktopCoordinatorService()

  private enum ToolName {
    static let listAgentSessions = "list_agent_sessions"
    static let getAgentRun = "get_agent_run"
    static let buildAwarenessSnapshot = "build_desktop_awareness_snapshot"
    static let listActionQueue = "list_desktop_action_queue"
    static let getOpenLoops = "get_desktop_open_loops"
    static let routeIntent = "route_desktop_intent"
    static let createDispatch = "create_desktop_dispatch"
    static let resolveDispatch = "resolve_desktop_dispatch"
    static let cancelAgentRun = "cancel_agent_run"
    static let inspectAgentArtifacts = "inspect_agent_artifacts"
    static let sendAgentMessage = "send_agent_message"
    static let spawnAgent = "spawn_agent"
    static let runAgentAndWait = "run_agent_and_wait"
    static let setDesktopAttentionOverride = "set_desktop_attention_override"
  }

  private let runtime: DesktopCoordinatorRuntimeControlling
  private let clientId: String
  private let harnessModeProvider: @MainActor () -> String
  private let formatter = ISO8601DateFormatter()
  private let checkpointDefaults: UserDefaults
  private let completionCheckpointPrefix = "desktopCoordinator.completedAgentDelta.seenRunIds"
  private let completionHighWaterPrefix = "desktopCoordinator.completedAgentDelta.highWaterMs"

  init(
    runtime: DesktopCoordinatorRuntimeControlling = AgentRuntimeProcess.shared,
    clientId: String = "desktop-coordinator",
    harnessModeProvider: @escaping @MainActor () -> String = AgentControlService.currentHarnessMode,
    checkpointDefaults: UserDefaults = .standard
  ) {
    self.runtime = runtime
    self.clientId = clientId
    self.harnessModeProvider = harnessModeProvider
    self.checkpointDefaults = checkpointDefaults
  }

  func awarenessSnapshot() async -> DesktopCoordinatorAwarenessSnapshot {
    let automationSnapshot = DesktopAutomationStateStore.shared.current()
    do {
      let raw = try await callRuntimeControlTool(ToolName.listAgentSessions, input: [:])
      return DesktopCoordinatorAwarenessSnapshot(
        generatedAt: nowString(),
        source: "swift_projection",
        runtimeControlTools: [ToolName.listAgentSessions],
        automation: DesktopCoordinatorAutomationProjection(snapshot: automationSnapshot),
        sessions: parseSessions(from: raw),
        debugDispatches: [],
        runtimeError: nil
      )
    } catch {
      return DesktopCoordinatorAwarenessSnapshot(
        generatedAt: nowString(),
        source: "swift_projection",
        runtimeControlTools: [ToolName.listAgentSessions],
        automation: DesktopCoordinatorAutomationProjection(snapshot: automationSnapshot),
        sessions: [],
        debugDispatches: [],
        runtimeError: error.localizedDescription
      )
    }
  }

  func awarenessSnapshotJSON(limit: Int = 50) async throws -> String {
    try await callRuntimeControlTool(ToolName.buildAwarenessSnapshot, input: ["limit": limit])
  }

  func actionQueueJSON(limit: Int = 50) async throws -> String {
    try await callRuntimeControlTool(ToolName.listActionQueue, input: ["limit": limit])
  }

  func openLoopsJSON(limit: Int = 50) async throws -> String {
    try await callRuntimeControlTool(ToolName.getOpenLoops, input: ["limit": limit])
  }

  func routeIntent(
    intent: String,
    surfaceKind: String,
    taskId: String? = nil,
    snapshotVersion: String? = nil,
    proposal: DesktopCoordinatorIntentProposal,
    syntaxFacts: DesktopCoordinatorIntentSyntaxFacts? = nil
  ) async throws -> DesktopCoordinatorRouteDecision {
    var input: [String: Any] = [
      "utterance": intent,
      "surfaceKind": surfaceKind.isEmpty ? "main_chat" : surfaceKind,
      "proposal": proposal.payload,
    ]
    if let taskId, !taskId.isEmpty {
      input["taskId"] = taskId
    }
    if let snapshotVersion, !snapshotVersion.isEmpty {
      input["snapshotVersion"] = snapshotVersion
    }
    if let syntaxFacts, !syntaxFacts.payload.isEmpty {
      input["syntaxFacts"] = syntaxFacts.payload
    }
    let raw = try await callRuntimeControlTool(ToolName.routeIntent, input: input)
    return try parseRouteDecision(from: raw)
  }

  func routeIntentJSON(
    intent: String,
    surfaceKind: String? = nil,
    taskId: String? = nil,
    snapshotVersion: String? = nil,
    proposal: DesktopCoordinatorIntentProposal,
    syntaxFacts: DesktopCoordinatorIntentSyntaxFacts? = nil
  ) async throws -> String {
    var input: [String: Any] = [
      "utterance": intent,
      "surfaceKind": surfaceKind?.isEmpty == false ? surfaceKind! : "main_chat",
      "proposal": proposal.payload,
    ]
    if let taskId, !taskId.isEmpty { input["taskId"] = taskId }
    if let snapshotVersion, !snapshotVersion.isEmpty { input["snapshotVersion"] = snapshotVersion }
    if let syntaxFacts, !syntaxFacts.payload.isEmpty { input["syntaxFacts"] = syntaxFacts.payload }
    return try await callRuntimeControlTool(ToolName.routeIntent, input: input)
  }

  func createDispatchJSON(
    kind: String,
    title: String,
    decisionPrompt: String,
    recommendedDefault: String? = nil,
    sourceSessionId: String? = nil,
    sourceRunId: String? = nil
  ) async throws -> String {
    var input: [String: Any] = [
      "kind": kind.isEmpty ? "routing_choice" : kind,
      "priority": 50,
      "title": title.isEmpty ? "Coordinator attention" : title,
      "decisionPrompt": decisionPrompt.isEmpty ? "Review this coordinator attention item." : decisionPrompt,
    ]
    if let recommendedDefault, !recommendedDefault.isEmpty { input["recommendedDefault"] = recommendedDefault }
    if let sourceSessionId, !sourceSessionId.isEmpty { input["sourceSessionId"] = sourceSessionId }
    if let sourceRunId, !sourceRunId.isEmpty { input["sourceRunId"] = sourceRunId }
    return try await callRuntimeControlTool(ToolName.createDispatch, input: input)
  }

  func resolveDispatchJSON(dispatchId: String, resolution: String) async throws -> String {
    try await callRuntimeControlTool(
      ToolName.resolveDispatch,
      input: [
        "dispatchId": dispatchId,
        "status": resolution == "cancelled" ? "cancelled" : "resolved",
        "resolution": ["decision": resolution.isEmpty ? "resolved" : resolution],
      ]
    )
  }

  func actionQueue() async -> [DesktopCoordinatorActionQueueItem] {
    let snapshot = await awarenessSnapshot()
    return deriveActionQueue(from: snapshot)
  }

  func openLoops() async -> DesktopCoordinatorOpenLoops {
    let queue = await actionQueue()
    let items = queue.filter { item in
      ["approval", "failed_run", "stale_or_active_run", "debug_dispatch"].contains(item.kind)
    }
    return DesktopCoordinatorOpenLoops(generatedAt: nowString(), items: items)
  }

  func inspectRun(runId: String) async throws -> String {
    let trimmedRunId = runId.trimmingCharacters(in: .whitespacesAndNewlines)
    guard !trimmedRunId.isEmpty else {
      throw NSError(
        domain: "DesktopCoordinatorService",
        code: 3,
        userInfo: [NSLocalizedDescriptionKey: "runId is required to inspect an agent run"]
      )
    }
    return try await callRuntimeControlTool(ToolName.getAgentRun, input: ["runId": trimmedRunId])
  }

  func cancelAgentRun(runId: String, reason: String = "Stopped by user") async throws -> String {
    try await callRuntimeControlTool(
      ToolName.cancelAgentRun,
      input: ["runId": runId]
    )
  }

  func spawnAgent(
    objective: String,
    title: String?,
    pillId: UUID,
    originSurface: DesktopCoordinatorOriginSurface,
    provider: String?,
    parentRunId: String?,
    visible: Bool,
    model: String?,
    harnessMode: AgentHarnessMode?,
    cwd: String?,
    producerJournal: DesktopCoordinatorProducerJournalDescriptor? = nil
  ) async throws -> DesktopCoordinatorSpawnedAgent {
    let batch = try await spawnAgents(
      objective: objective,
      title: title,
      pillId: pillId,
      requestedAgentCount: 1,
      originSurface: originSurface,
      provider: provider,
      parentRunId: parentRunId,
      visible: visible,
      model: model,
      harnessMode: harnessMode,
      cwd: cwd,
      producerJournal: producerJournal
    )
    guard let first = batch.agents.first else {
      throw NSError(
        domain: "DesktopCoordinatorService",
        code: 2,
        userInfo: [NSLocalizedDescriptionKey: "Background-agent spawn returned no agents"])
    }
    return first
  }

  func spawnAgents(
    objective: String,
    title: String?,
    pillId: UUID?,
    requestedAgentCount: Int,
    originSurface: DesktopCoordinatorOriginSurface,
    provider: String?,
    parentRunId: String?,
    visible: Bool,
    model: String?,
    harnessMode: AgentHarnessMode?,
    cwd: String?,
    producerJournal: DesktopCoordinatorProducerJournalDescriptor? = nil
  ) async throws -> DesktopCoordinatorSpawnBatch {
    let boundedCount = max(1, min(requestedAgentCount, 8))
    var metadata: [String: Any] = [
      "uiProjection": visible ? "floating_bar" : "delegated_agent"
    ]
    if let pillId {
      metadata["pillId"] = pillId.uuidString
      metadata["siblingGroupExternalRefId"] = pillId.uuidString
    }
    if let producerJournal {
      metadata["producerJournal"] = producerJournal.dictionary
    }
    var input: [String: Any] = [
      "objective": objective,
      "visible": visible,
      "requestedAgentCount": boundedCount,
      "clientId": "desktop-floating-pill",
      "originSurfaceKind": originSurface.rawValue,
      "metadata": metadata,
    ]
    if let pillId {
      input["externalRefId"] = pillId.uuidString
    }
    if let title, !title.isEmpty { input["title"] = title }
    if let provider, !provider.isEmpty { input["provider"] = provider }
    if let parentRunId, !parentRunId.isEmpty { input["parentRunId"] = parentRunId }
    if let model, !model.isEmpty { input["model"] = model }
    if let harnessMode { input["adapterId"] = AgentRuntimeRouting.adapterId(for: harnessMode).rawValue }
    if let cwd, !cwd.isEmpty { input["cwd"] = cwd }
    let raw = try await callRuntimeControlTool(ToolName.spawnAgent, input: input)
    return try parseSpawnedAgents(from: raw)
  }

  func dismissFloatingRunAttention(runId: String, reason: String = "Dismissed by user") async throws {
    _ = try await callRuntimeControlTool(
      ToolName.setDesktopAttentionOverride,
      input: [
        "subjectKind": "run",
        "subjectId": runId,
        "dismissed": true,
        "reason": reason,
      ]
    )
  }

  func continueAgent(
    sessionId: String,
    prompt: String,
    originSurface: DesktopCoordinatorOriginSurface,
    model: String?,
    cwd: String?
  ) async throws -> DesktopCoordinatorAgentRunInspection {
    var input: [String: Any] = [
      "sessionId": sessionId,
      "prompt": prompt,
      "mode": "act",
      "clientId": "desktop-floating-pill",
      "originSurfaceKind": originSurface.rawValue,
      "metadata": ["uiProjection": "floating_bar"],
    ]
    if let model, !model.isEmpty { input["model"] = model }
    if let cwd, !cwd.isEmpty { input["cwd"] = cwd }
    let raw = try await callRuntimeControlTool(ToolName.sendAgentMessage, input: input)
    return parseInspectedRun(from: raw)
  }

  func inspectAgentRun(runId: String) async throws -> DesktopCoordinatorAgentRunInspection {
    parseInspectedRun(from: try await inspectRun(runId: runId))
  }

  func inspectArtifactsForRun(runId: String) async throws -> [AgentArtifactProjection] {
    let trimmedRunId = runId.trimmingCharacters(in: .whitespacesAndNewlines)
    guard !trimmedRunId.isEmpty else {
      throw NSError(
        domain: "DesktopCoordinatorService",
        code: 4,
        userInfo: [NSLocalizedDescriptionKey: "runId is required to inspect agent artifacts"]
      )
    }
    let raw = try await callRuntimeControlTool(
      ToolName.inspectAgentArtifacts, input: ["runId": trimmedRunId, "limit": 100])
    return try AgentArtifactProjection.parseList(fromToolResult: raw)
  }

  func peekCompletedAgentDelta(surfaceKind: String, limit: Int = 5) async -> DesktopCoordinatorCompletionDelta? {
    await peekCompletedAgentDelta(surfaceKey: surfaceKind, surfaceLabel: surfaceKind, limit: limit)
  }

  func peekCompletedAgentDelta(surface: AgentSurfaceReference, limit: Int = 5) async
    -> DesktopCoordinatorCompletionDelta?
  {
    await peekCompletedAgentDelta(surfaceKey: surface.key, surfaceLabel: surface.surfaceKind, limit: limit)
  }

  private func peekCompletedAgentDelta(surfaceKey: String, surfaceLabel: String, limit: Int) async
    -> DesktopCoordinatorCompletionDelta?
  {
    do {
      let raw = try await callRuntimeControlTool(ToolName.listAgentSessions, input: ["limit": 50])
      let seen = Set(checkpointDefaults.stringArray(forKey: completionCheckpointKey(surfaceKey: surfaceKey)) ?? [])
      let nowMs = currentTimeMs()
      let highWaterKey = completionHighWaterKey(surfaceKey: surfaceKey)
      let minCompletedAtMs = nowMs - CompletionDeltaPolicy.maxAgeMs(forSurfaceKind: surfaceLabel)
      let highWaterMs: Int
      if checkpointDefaults.object(forKey: highWaterKey) != nil {
        highWaterMs = checkpointDefaults.integer(forKey: highWaterKey)
      } else {
        // First use starts at the bounded recent-window floor, not now. A parent
        // chat may not ask for deltas until after its sub-agent finishes, and that
        // first check still needs to surface the completed agent's resources.
        highWaterMs = minCompletedAtMs
        checkpointDefaults.set(minCompletedAtMs, forKey: highWaterKey)
      }
      let items = parseCompletionDeltaItems(from: raw)
        .filter {
          guard let completedAtMs = $0.completedAtMs else { return false }
          return completedAtMs > highWaterMs
            && completedAtMs >= minCompletedAtMs
            && !seen.contains($0.id)
        }
        .sorted { ($0.completedAtMs ?? 0) < ($1.completedAtMs ?? 0) }
        .prefix(limit)
        .map { $0 }

      guard !items.isEmpty else { return nil }
      return DesktopCoordinatorCompletionDelta(
        ids: items.map(\.id),
        prompt: CompletionDeltaPolicy.format(surfaceKind: surfaceLabel, items: items, nowMs: nowMs),
        completedAtHighWaterMs: items.compactMap(\.completedAtMs).max(),
        artifacts: await collectDeltaArtifacts(for: items)
      )
    } catch {
      logError("DesktopCoordinatorService: completed agent delta unavailable", error: error)
      return nil
    }
  }

  func acknowledgeCompletedAgentDelta(surfaceKind: String, ids: [String]) {
    guard !ids.isEmpty else { return }
    checkpointCompletionDelta(surfaceKind: surfaceKind, ids: ids, completedAtHighWaterMs: nil)
  }

  func acknowledgeCompletedAgentDelta(surfaceKind: String, ids: [String], completedAtHighWaterMs: Int?) {
    guard !ids.isEmpty else { return }
    checkpointCompletionDelta(surfaceKind: surfaceKind, ids: ids, completedAtHighWaterMs: completedAtHighWaterMs)
  }

  func acknowledgeCompletedAgentDelta(surface: AgentSurfaceReference, ids: [String]) {
    guard !ids.isEmpty else { return }
    checkpointCompletionDelta(surfaceKey: surface.key, ids: ids, completedAtHighWaterMs: nil)
  }

  func acknowledgeCompletedAgentDelta(surface: AgentSurfaceReference, ids: [String], completedAtHighWaterMs: Int?) {
    guard !ids.isEmpty else { return }
    checkpointCompletionDelta(surfaceKey: surface.key, ids: ids, completedAtHighWaterMs: completedAtHighWaterMs)
  }

  func runtimeControlManifest() -> [String] {
    [
      ToolName.listAgentSessions,
      ToolName.getAgentRun,
      ToolName.buildAwarenessSnapshot,
      ToolName.listActionQueue,
      ToolName.getOpenLoops,
      ToolName.routeIntent,
      ToolName.createDispatch,
      ToolName.resolveDispatch,
      ToolName.cancelAgentRun,
      ToolName.inspectAgentArtifacts,
      ToolName.sendAgentMessage,
      ToolName.spawnAgent,
      ToolName.runAgentAndWait,
      ToolName.setDesktopAttentionOverride,
    ]
  }

  func listFloatingAgentPills(limit: Int = 50) async throws -> [[String: Any]] {
    let raw = try await callRuntimeControlTool(
      ToolName.listAgentSessions,
      input: ["limit": limit, "surfaceKind": "floating_bar"]
    )
    guard let data = raw.data(using: .utf8),
      let object = try JSONSerialization.jsonObject(with: data) as? [String: Any],
      object["ok"] as? Bool == true
    else {
      return []
    }
    return object["floating_agent_pills"] as? [[String: Any]] ?? []
  }

  func floatingAgentStatusSummary(limit: Int = 8) async -> String {
    do {
      let pills = try await listFloatingAgentPills(limit: limit)
      guard !pills.isEmpty else {
        return "No floating agent pills are running or recently finished."
      }
      let lines = pills.map { entry -> String in
        let title = stringValue(entry["title"]) ?? "Background agent"
        let id = (stringValue(entry["id"]) ?? "").prefix(8)
        let status = stringValue(entry["status"]) ?? "unknown"
        let activity = stringValue(entry["latestActivity"]) ?? ""
        return "- \(title) [\(id)]: \(status); \(activity)"
      }
      return "Floating agent pills:\n" + lines.joined(separator: "\n")
    } catch {
      logError("DesktopCoordinatorService: floating agent status unavailable", error: error)
      return ""
    }
  }

  private func callRuntimeControlTool(_ name: String, input: [String: Any]) async throws -> String {
    try await runtime.directControlTool(
      clientId: clientId,
      harnessMode: harnessModeProvider(),
      name: name,
      input: RuntimeJSONPayloadBox(input)
    )
  }

  private func deriveActionQueue(from snapshot: DesktopCoordinatorAwarenessSnapshot)
    -> [DesktopCoordinatorActionQueueItem]
  {
    var items: [DesktopCoordinatorActionQueueItem] = []

    for dispatch in snapshot.debugDispatches {
      items.append(
        DesktopCoordinatorActionQueueItem(
          id: dispatch.dispatchId,
          rank: 1,
          kind: "debug_dispatch",
          title: dispatch.title,
          status: dispatch.status,
          sessionId: dispatch.sourceSessionId,
          runId: dispatch.sourceRunId,
          dispatchId: dispatch.dispatchId,
          source: dispatch.source
        )
      )
    }

    for session in snapshot.sessions {
      let status = session.runStatus ?? session.status
      let id = session.runId ?? session.sessionId ?? "\(session.title)_\(session.status)"
      if status == "waiting_approval" {
        items.append(queueItem(id: id, rank: 1, kind: "approval", session: session, status: status))
      } else if ["failed", "orphaned", "timed_out"].contains(status) {
        items.append(queueItem(id: id, rank: 2, kind: "failed_run", session: session, status: status))
      } else if isActive(status) {
        items.append(queueItem(id: id, rank: 4, kind: "stale_or_active_run", session: session, status: status))
      } else if ["succeeded", "completed"].contains(status) {
        items.append(queueItem(id: id, rank: 5, kind: "completed_run_review", session: session, status: status))
      }
    }

    return items.sorted {
      if $0.rank == $1.rank { return $0.id < $1.id }
      return $0.rank < $1.rank
    }
  }

  private func queueItem(
    id: String,
    rank: Int,
    kind: String,
    session: DesktopCoordinatorSessionProjection,
    status: String
  ) -> DesktopCoordinatorActionQueueItem {
    DesktopCoordinatorActionQueueItem(
      id: id,
      rank: rank,
      kind: kind,
      title: session.title,
      status: status,
      sessionId: session.sessionId,
      runId: session.runId,
      dispatchId: nil,
      source: session.source
    )
  }

  private func parseSessions(from raw: String) -> [DesktopCoordinatorSessionProjection] {
    guard let object = jsonObject(from: raw), object["ok"] as? Bool != false else {
      return []
    }
    let sessions = object["sessions"] as? [[String: Any]] ?? []
    return sessions.map { summary in
      let session = summary["session"] as? [String: Any] ?? [:]
      let latestRun = summary["latestRun"] as? [String: Any] ?? [:]
      let activeRun = summary["activeRun"] as? [String: Any] ?? [:]
      let selectedRun = activeRun.isEmpty ? latestRun : activeRun
      let latestAttempt = summary["latestAttempt"] as? [String: Any] ?? [:]
      let activeAttempt = summary["activeAttempt"] as? [String: Any] ?? [:]
      let selectedAttempt = activeRun.isEmpty ? latestAttempt : activeAttempt
      let sessionStatus = stringValue(session["status"]) ?? "unknown"
      let title =
        stringValue(session["title"])
        ?? stringValue(session["surfaceKind"])
        ?? "Untitled agent"

      return DesktopCoordinatorSessionProjection(
        sessionId: stringValue(session["sessionId"]),
        title: title,
        surfaceKind: stringValue(session["surfaceKind"]),
        externalRefKind: stringValue(session["externalRefKind"]),
        externalRefId: stringValue(session["externalRefId"]),
        status: sessionStatus,
        runId: stringValue(selectedRun["runId"]),
        runStatus: stringValue(selectedRun["status"]),
        runMode: stringValue(selectedRun["mode"]),
        attemptId: stringValue(selectedAttempt["attemptId"]),
        provider: stringValue((session["metadata"] as? [String: Any])?["provider"]),
        updatedAt: stringValue(session["updatedAt"]) ?? stringValue(selectedRun["updatedAt"]),
        source: "runtime_control_tool:list_agent_sessions"
      )
    }
  }

  private func parseCompletionDeltaItems(from raw: String) -> [DesktopCoordinatorCompletionDeltaItem] {
    guard let object = jsonObject(from: raw), object["ok"] as? Bool != false else {
      return []
    }
    let sessions = object["sessions"] as? [[String: Any]] ?? []
    return sessions.compactMap { summary in
      let session = summary["session"] as? [String: Any] ?? [:]
      let latestRun = summary["latestRun"] as? [String: Any] ?? [:]
      guard !latestRun.isEmpty else { return nil }
      let status = stringValue(latestRun["status"]) ?? stringValue(session["status"]) ?? "unknown"
      // Only runs that actually completed carry deliverable work. Terminal-but-
      // not-succeeded statuses (cancelled, timed_out, orphaned, failed) used to
      // pass here and were injected as "newly completed work" with a synthetic
      // placeholder body — noise that pushed the model to weave dead threads
      // into the live answer.
      guard CompletionDeltaPolicy.eligibleStatuses.contains(status) else { return nil }
      let runId = stringValue(latestRun["runId"])
      let sessionId = stringValue(session["sessionId"])
      let completedAtMs = intValue(latestRun["completedAtMs"])
      // When runId is absent, include completedAtMs so that each distinct
      // terminal run completion carries a unique id even if the same session
      // produces multiple completions over time.
      let id = runId ?? (sessionId.map { "\($0)_\(completedAtMs ?? 0)" })
      guard let id else { return nil }

      let surfaceKind = stringValue(session["surfaceKind"])
      guard surfaceKind != "main_chat" else { return nil }

      let title =
        stringValue(session["title"])
        ?? surfaceKind
        ?? "Completed agent"
      let sanitizedTitle = sanitizePromptLine(title, maxLength: 120)
      let finalText =
        stringValue(latestRun["finalText"])
        ?? stringValue(latestRun["errorMessage"])
        ?? stringValue((latestRun["result"] as? [String: Any])?["text"])
        ?? "\(sanitizedTitle) finished with status \(status). Inspect the agentRef for details if the user asks."
      let inputPrompt = sanitizePromptLine(
        stringValue((latestRun["input"] as? [String: Any])?["prompt"]) ?? "",
        maxLength: 200)

      return DesktopCoordinatorCompletionDeltaItem(
        id: id,
        title: sanitizedTitle,
        surfaceKind: surfaceKind,
        externalRefKind: stringValue(session["externalRefKind"]),
        externalRefId: stringValue(session["externalRefId"]),
        status: status,
        sessionId: sessionId,
        runId: runId,
        completedAtMs: completedAtMs,
        finalText: sanitizePromptLine(finalText, maxLength: 1_200),
        inputPrompt: inputPrompt.isEmpty ? nil : inputPrompt
      )
    }
  }

  private func checkpointCompletionDelta(surfaceKind: String, ids: [String], completedAtHighWaterMs: Int?) {
    checkpointCompletionDelta(surfaceKey: surfaceKind, ids: ids, completedAtHighWaterMs: completedAtHighWaterMs)
  }

  private func checkpointCompletionDelta(surfaceKey: String, ids: [String], completedAtHighWaterMs: Int?) {
    let key = completionCheckpointKey(surfaceKey: surfaceKey)
    var seen = checkpointDefaults.stringArray(forKey: key) ?? []
    seen.append(contentsOf: ids)
    checkpointDefaults.set(Array(seen.suffix(100)), forKey: key)
    if let completedAtHighWaterMs {
      let highWaterKey = completionHighWaterKey(surfaceKey: surfaceKey)
      checkpointDefaults.set(
        max(checkpointDefaults.integer(forKey: highWaterKey), completedAtHighWaterMs), forKey: highWaterKey)
    }
  }

  private func completionCheckpointKey(surfaceKind: String) -> String {
    completionCheckpointKey(surfaceKey: surfaceKind)
  }

  private func completionCheckpointKey(surfaceKey: String) -> String {
    "\(completionCheckpointPrefix).\(surfaceKey.isEmpty ? "unknown" : surfaceKey)"
  }

  private func completionHighWaterKey(surfaceKey: String) -> String {
    "\(completionHighWaterPrefix).\(surfaceKey.isEmpty ? "unknown" : surfaceKey)"
  }

  /// Fetches the artifacts produced by each successfully-completed sub-agent in
  /// the delta so the consuming surface can render them as resource cards.
  /// Bounded by the delta `limit`; failed runs are skipped (no artifacts to show).
  private func collectDeltaArtifacts(for items: [DesktopCoordinatorCompletionDeltaItem]) async
    -> [AgentArtifactProjection]
  {
    let inspectable = items.filter { item in
      guard let runId = item.runId, !runId.isEmpty else { return false }
      return ["succeeded", "completed"].contains(item.status)
    }
    guard !inspectable.isEmpty else { return [] }

    var collected: [AgentArtifactProjection] = []
    var seenIds = Set<String>()
    for item in inspectable {
      guard let runId = item.runId else { continue }
      let inspection: DesktopCoordinatorAgentRunInspection
      do {
        inspection = try await inspectAgentRun(runId: runId)
      } catch {
        let fallbackArtifacts = (try? await inspectArtifactsForRun(runId: runId)) ?? []
        for artifact in fallbackArtifacts where artifact.isUserFacingResult {
          guard seenIds.insert(artifact.artifactId).inserted else { continue }
          collected.append(artifact)
        }
        continue
      }
      if inspection.status == "failed", inspection.artifacts.isEmpty {
        let fallbackArtifacts = (try? await inspectArtifactsForRun(runId: runId)) ?? []
        for artifact in fallbackArtifacts where artifact.isUserFacingResult {
          guard seenIds.insert(artifact.artifactId).inserted else { continue }
          collected.append(artifact)
        }
        continue
      }
      for artifact in inspection.artifacts where artifact.isUserFacingResult {
        guard seenIds.insert(artifact.artifactId).inserted else { continue }
        collected.append(artifact)
      }
    }
    return collected
  }

  private func isActive(_ status: String) -> Bool {
    ["queued", "starting", "running", "waiting_input", "waiting_approval", "cancelling"].contains(status)
  }

  private func nowString() -> String {
    formatter.string(from: Date())
  }

  private func jsonObject(from raw: String) -> [String: Any]? {
    guard let data = raw.data(using: .utf8) else { return nil }
    return try? JSONSerialization.jsonObject(with: data) as? [String: Any]
  }

  private func parseRouteDecision(from raw: String) throws -> DesktopCoordinatorRouteDecision {
    guard let object = jsonObject(from: raw) else {
      throw NSError(
        domain: "DesktopCoordinatorService",
        code: 5,
        userInfo: [NSLocalizedDescriptionKey: "Invalid kernel route response"])
    }
    if object["ok"] as? Bool == false {
      throw NSError(
        domain: "DesktopCoordinatorService",
        code: 5,
        userInfo: [
          NSLocalizedDescriptionKey: runtimeErrorMessage(from: object)
            ?? "Kernel route request was rejected"
        ])
    }
    let route = object["route"] as? [String: Any] ?? [:]
    guard
      let decisionId = stringValue(route["decisionId"]),
      let intent = stringValue(route["intent"]),
      let surfaceKind = stringValue(route["surfaceKind"]),
      let snapshotVersion = stringValue(route["snapshotVersion"]),
      let reasonCode = stringValue(route["reasonCode"]),
      let explanation = stringValue(route["explanation"])
    else {
      throw NSError(
        domain: "DesktopCoordinatorService",
        code: 5,
        userInfo: [NSLocalizedDescriptionKey: "Kernel route response omitted typed decision fields"])
    }
    return DesktopCoordinatorRouteDecision(
      decisionId: decisionId,
      intent: intent,
      surfaceKind: surfaceKind,
      snapshotVersion: snapshotVersion,
      reasonCode: reasonCode,
      explanation: explanation,
      sessionId: stringValue(route["sessionId"]),
      runId: stringValue(route["runId"]),
      requestedProvider: stringValue(route["requestedProvider"]),
      requestedAgentCount: intValue(route["requestedAgentCount"]),
      parentRunId: stringValue(route["parentRunId"]),
      missing: route["missing"] as? [String] ?? [],
      rejectionCode: stringValue(route["code"]))
  }

  private func parseSpawnedAgents(from raw: String) throws -> DesktopCoordinatorSpawnBatch {
    guard let object = jsonObject(from: raw) else {
      throw NSError(
        domain: "DesktopCoordinatorService", code: 1,
        userInfo: [NSLocalizedDescriptionKey: "Invalid background-agent spawn response"])
    }
    if object["ok"] as? Bool == false {
      let error = object["error"] as? [String: Any]
      let code = stringValue(error?["code"])
      let message = stringValue(error?["message"]) ?? "Background-agent spawn was rejected by the runtime"
      let detail = code.map { "\($0): \(message)" } ?? message
      throw NSError(domain: "DesktopCoordinatorService", code: 1, userInfo: [NSLocalizedDescriptionKey: detail])
    }
    let rawAgents =
      object["agents"] as? [[String: Any]] ?? [
        [
          "session": object["session"] as? [String: Any] ?? [:],
          "run": object["run"] as? [String: Any] ?? [:],
          "attempt": object["attempt"] ?? NSNull(),
        ]
      ]
    let agents = try rawAgents.map { item -> DesktopCoordinatorSpawnedAgent in
      let session = item["session"] as? [String: Any] ?? [:]
      let run = item["run"] as? [String: Any] ?? [:]
      let attempt = item["attempt"] as? [String: Any] ?? [:]
      guard let sessionId = stringValue(session["sessionId"]),
        let runId = stringValue(run["runId"])
      else {
        throw NSError(
          domain: "DesktopCoordinatorService",
          code: 2,
          userInfo: [NSLocalizedDescriptionKey: "Background-agent spawn response did not include canonical handles"])
      }
      return DesktopCoordinatorSpawnedAgent(
        sessionId: sessionId,
        runId: runId,
        attemptId: stringValue(attempt["attemptId"]),
        title: stringValue(session["title"]) ?? "Background agent",
        externalRefId: stringValue(session["externalRefId"])
      )
    }
    let requestedAgentCount = intValue(object["requestedAgentCount"]) ?? agents.count
    guard requestedAgentCount == agents.count, (1...8).contains(requestedAgentCount) else {
      throw NSError(
        domain: "DesktopCoordinatorService",
        code: 2,
        userInfo: [NSLocalizedDescriptionKey: "Background-agent spawn response count did not match canonical agents"])
    }
    return DesktopCoordinatorSpawnBatch(
      requestedAgentCount: requestedAgentCount,
      agents: agents
    )
  }

  private func parseInspectedRun(from raw: String) -> DesktopCoordinatorAgentRunInspection {
    guard let object = jsonObject(from: raw) else {
      return DesktopCoordinatorAgentRunInspection(
        sessionId: nil, runId: nil, attemptId: nil, provider: nil, status: "failed", finalText: nil,
        errorMessage: "Unable to inspect agent run: invalid runtime response", artifacts: [])
    }
    if object["ok"] as? Bool == false {
      return DesktopCoordinatorAgentRunInspection(
        sessionId: nil, runId: nil, attemptId: nil, provider: nil, status: "failed", finalText: nil,
        errorMessage: runtimeErrorMessage(from: object) ?? "Unable to inspect agent run", artifacts: [])
    }
    let session = object["session"] as? [String: Any] ?? [:]
    let run = object["run"] as? [String: Any] ?? [:]
    let result = run["result"] as? [String: Any] ?? [:]
    let attempt = object["attempt"] as? [String: Any] ?? [:]
    return DesktopCoordinatorAgentRunInspection(
      sessionId: stringValue(session["sessionId"]),
      runId: stringValue(run["runId"]),
      attemptId: stringValue(attempt["attemptId"]) ?? stringValue(run["attemptId"]) ?? stringValue(object["attemptId"]),
      provider: stringValue((session["metadata"] as? [String: Any])?["provider"]),
      status: stringValue(run["status"]) ?? stringValue(object["terminalStatus"]) ?? "unknown",
      finalText: stringValue(run["finalText"]) ?? stringValue(result["text"]) ?? stringValue(object["text"]),
      errorMessage: stringValue(run["errorMessage"]) ?? runtimeErrorMessage(from: object),
      artifacts: AgentArtifactProjection.parseList(fromJSONArray: object["artifacts"] as? [[String: Any]] ?? [])
    )
  }

  private func runtimeErrorMessage(from object: [String: Any]) -> String? {
    if let message = stringValue(object["error"]) {
      return message
    }
    if let error = object["error"] as? [String: Any] {
      let code = stringValue(error["code"])
      let message = stringValue(error["message"])
      if let code, let message { return "\(code): \(message)" }
      return message ?? code
    }
    return nil
  }

  private func stringValue(_ value: Any?) -> String? {
    guard let text = value as? String else { return nil }
    let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
    return trimmed.isEmpty ? nil : trimmed
  }

  private func intValue(_ value: Any?) -> Int? {
    if let int = value as? Int { return int }
    if let number = value as? NSNumber { return number.intValue }
    return nil
  }

  private func currentTimeMs() -> Int {
    Int(Date().timeIntervalSince1970 * 1_000)
  }

  private func sanitizePromptLine(_ text: String, maxLength: Int) -> String {
    let scalars = text.unicodeScalars.map { scalar -> Character in
      if CharacterSet.newlines.contains(scalar) || CharacterSet.controlCharacters.contains(scalar) {
        return " "
      }
      return Character(scalar)
    }
    let cleaned = String(scalars)
      .replacingOccurrences(of: "`", with: "'")
      .trimmingCharacters(in: .whitespacesAndNewlines)
    return String(cleaned.prefix(maxLength))
  }
}

extension DesktopCoordinatorAutomationProjection {
  init(snapshot: DesktopAutomationSnapshot) {
    self.init(
      bridgeEnabled: snapshot.bridgeEnabled,
      bridgePort: snapshot.bridgePort,
      bundleIdentifier: snapshot.bundleIdentifier,
      appState: snapshot.appState,
      selectedTab: snapshot.selectedTab,
      askOmiOpen: snapshot.askOmiOpen,
      floatingBarVisible: snapshot.floatingBarVisible
    )
  }
}

extension Encodable {
  func desktopCoordinatorJSONString() -> String {
    let encoder = JSONEncoder()
    encoder.outputFormatting = [.sortedKeys]
    guard let data = try? encoder.encode(self),
      let string = String(data: data, encoding: .utf8)
    else {
      return "{}"
    }
    return string
  }
}