Skip to content

armgit / chums

Public Imported from GitHub
0

Talk to Claude Code and Codex agents from an Apple Watch and an iPhone. Each agent is a character on the watch.

22.7 KB
Raw Blame
import Foundation
import Observation
#if os(watchOS)
import WatchKit
#else
import UIKit
#endif

struct SessionInfo: Decodable, Identifiable, Equatable {
    let id: String
    let name: String
    let status: String
    let lastLine: String?
    let subagents: Int?
}

/// One tool call a session made, from the Claude Code hooks: type is read, edit, bash, test, agent or stop.
struct ToolInfo: Decodable, Identifiable, Equatable {
    let id: String
    let session: String
    let type: String
    let text: String
    let ok: Bool?
    var at: Double? = nil       // when (ms since 1970)
}

struct Approval: Decodable, Identifiable, Equatable {
    let requestId: String
    let session: String
    let tool: String
    let description: String
    let preview: String
    let summary: String?
    var id: String { requestId }
}

struct Spoken: Decodable, Identifiable, Equatable {
    let id: String
    let session: String
    let text: String
    let kind: String
    let audio: String?          // the reply's voice, rendered on the Mac (GET it from the hub)
    var audioData: String? = nil // the same, in the answer that brought the line (base64 m4a): no second trip
    var device: String? = nil   // the device whose order this answers: it speaks it (none: the watch)
    /// Whether this device reads the line aloud: the one the order came from (lines with none are the watch's).
    var speaksHere: Bool { (device ?? "watch") == HubClient.device }
    let at: Double?             // when it was said (ms since 1970), to keep the conversation in order
    let artifact: Artifact?     // something it showed you (a screenshot, a page, an image)
    let agent: String?          // whose line it is (lines from before agents have none: they were the first agent's)
    /// The agent it belongs to.
    var owner: String { agent ?? Agents.fallback }
}

/// An agent: a character with its own Claude Code session and thread on the Mac (~/.chums/agents.json).
struct AgentInfo: Decodable, Identifiable, Equatable {
    let id: String
    let name: String
    let character: String
    let status: String          // idle, working, waiting, blocked, compacting, limited, offline
    let line: String?           // the last thing it said
    let needs: Bool             // it asks you something, or waits on an approval
    var owns: String? = nil     // what it looks after (its soul)
    var runtime: String? = nil  // claude or codex: what it runs on, switched on its soul screen
    var voice: String? = nil    // its voice on the Mac (a Kokoro voice id), chosen on its soul screen
    var model: String? = nil    // its model (an alias or a slug); nil: what its runtime is set to use
    var permission: String? = nil   // how it asks before acting (a mode id for its runtime); nil: its runtime's setting
}

/// How an agent may act, for a runtime: the modes it offers (Asks first, …) and what it uses when an agent has none.
struct PermissionChoices: Decodable, Equatable {
    let `default`: String?
    let modes: [ModelChoices.Model]
}

/// The models a runtime offers, and what it uses when an agent has none of its own ("Opus, 1M context").
struct ModelChoices: Decodable, Equatable {
    struct Model: Decodable, Identifiable, Equatable { let id: String; let name: String; var about: String? = nil }
    let `default`: String?
    let models: [Model]
}

/// One of the voices the Mac can speak in (Kokoro's English ones).
struct VoiceInfo: Decodable, Identifiable, Equatable {
    let id: String
    let name: String
    let grade: String
    let accent: String
    let gender: String
}

struct HubState: Decodable {
    let rev: Int
    let sessions: [SessionInfo]
    let approvals: [Approval]
    let spoken: [Spoken]
    let tools: [ToolInfo]?
    let agents: [AgentInfo]?
    var runtimes: [String]? = nil   // what an agent can be switched to on this Mac
}

/// An agent's soul as the watch shows it: who it is, what it looks after, what it refers to the others, its voice.
struct SoulCard: Decodable, Equatable {
    let id: String?
    let name: String
    let owns: String?
    let refers: String?
    let voice: String?
    var body: String? = nil
    let canUndo: Bool?
}

/// What you said on a soul screen, as a change to see before saving (or a question back, or why it failed).
struct SoulProposal: Decodable {
    let transcript: String?
    let proposal: String?
    let summary: String?
    let soul: SoulCard?
    let clarify: String?
    let error: String?
}

/// The hub's reason, when it says no.
struct HubFailure: Decodable { let error: String? }

struct RouteResult: Decodable {
    let transcript: String?
    let kind: String
    let echo: String?
    let target: String?
}

/// HTTP only: watchOS allows WebSockets only while streaming audio (TN3135), so state comes from a
/// long-poll that runs while Chums is on screen.
@MainActor @Observable
final class HubClient {
    private(set) var state: HubState?
    private(set) var connected = false
    private(set) var lastError: String?

    /// Fired for lines that arrive after the first load, so old lines are never re-spoken.
    var onSpoken: ((Spoken) -> Void)?
    var onApproval: ((Approval) -> Void)?

    private var rev = 0
    /// The first state since launch is in. Lines and approvals after it are news, those that came while the poll was
    /// stopped too (the app in the background, the Mac out of reach): a restarted poll doesn't mark them seen.
    @ObservationIgnored private var loaded = false
    private var seenSpoken = Set<String>()
    private var seenApprovals = Set<String>()
    private var pollTask: Task<Void, Never>?
    private var hostIndex = 0
    private var failingSince: Date?          // the first failure since the last success
    /// The hub's addresses to try. 127.0.0.1 is the Mac only in the Simulator; on a real watch it's the watch itself.
    private static let hosts: [String] = {
#if targetEnvironment(simulator)
        // Simulator captures: a stand-in hub playing a scripted session (-hub http://127.0.0.1:7799)
        if let h = UserDefaults.standard.string(forKey: "hub") { return [h] }
        return HubConfig.hosts
#else
        HubConfig.hosts.filter { !$0.contains("127.0.0.1") && !$0.contains("localhost") }
#endif
    }()
    private let urlSession: URLSession = {
        let c = URLSessionConfiguration.default
        c.timeoutIntervalForRequest = 30
        c.timeoutIntervalForResource = 40
        c.waitsForConnectivity = true          // watchOS brings a network path up on demand; wait for it instead of failing
        return URLSession(configuration: c)
    }()

    private var base: String { Self.hosts[hostIndex % Self.hosts.count] }

    /// Pings every address at once (4 s each) and keeps the first in the list that answers: the public one (Tailscale
    /// Funnel), then 127.0.0.1 (the Simulator's hub; a real watch or iPhone drops it). Asked again whenever requests
    /// start failing.
    private func pickHost() async {
        let hosts = Self.hosts
        let ok = await withTaskGroup(of: (Int, Bool).self) { g -> Set<Int> in
            for (i, h) in hosts.enumerated() { g.addTask { (i, await Self.ping(h)) } }
            var s = Set<Int>()
            for await (i, good) in g where good { s.insert(i) }
            return s
        }
        if let best = ok.min() { hostIndex = best } else { hostIndex = (hostIndex + 1) % hosts.count }
        let now = ok.isEmpty ? "none answered" : hosts[hostIndex]
        if now != route { route = now; if !ok.isEmpty { event("network: using \(now) (\(ok.count) of \(hosts.count) answered)") } }
    }
    /// Which address answered last, for the event log.
    private(set) var route = ""
    private nonisolated static let probeSession: URLSession = {
        let c = URLSessionConfiguration.ephemeral
        c.timeoutIntervalForRequest = 4; c.timeoutIntervalForResource = 4
        return URLSession(configuration: c)
    }()
    private nonisolated static func ping(_ host: String) async -> Bool {
        guard let url = URL(string: host + "/v1/ping") else { return false }
        var r = URLRequest(url: url, timeoutInterval: 4)
        r.setValue("Bearer \(HubConfig.token)", forHTTPHeaderField: "Authorization")
        guard let (_, resp) = try? await probeSession.data(for: r) else { return false }
        return (resp as? HTTPURLResponse)?.statusCode == 200
    }

    /// Sent with each poll so the hub can log what keyring mode costs (~/.chums/watch-battery.csv).
    @ObservationIgnored var screen = "on"
    @ObservationIgnored var keyring = false
    private var deviceQuery: String {
#if os(watchOS)
        let d = WKInterfaceDevice.current()
        d.isBatteryMonitoringEnabled = true
        let charging = d.batteryState == .charging || d.batteryState == .full
        return "&battery=\(String(format: "%.2f", d.batteryLevel))&charging=\(charging ? 1 : 0)&screen=\(screen)&keyring=\(keyring ? 1 : 0)&device=watch"
#else
        return "&device=phone"
#endif
    }
    /// Which device this is, for the hub: a reply is spoken on the device the order came from.
#if os(watchOS)
    nonisolated static let device = "watch"
#else
    nonisolated static let device = "phone"
#endif

    func start() {
        guard pollTask == nil else { return }
        pollTask = Task { await pollLoop() }
    }

    func stop() {
        pollTask?.cancel()
        pollTask = nil
    }

    private func request(_ path: String, method: String = "GET", body: Data? = nil,
                         contentType: String = "application/json", timeout: TimeInterval = 30) -> URLRequest {
        var r = URLRequest(url: URL(string: base + path)!, timeoutInterval: timeout)
        r.httpMethod = method
        r.setValue("Bearer \(HubConfig.token)", forHTTPHeaderField: "Authorization")
        if let body {
            r.httpBody = body
            r.setValue(contentType, forHTTPHeaderField: "Content-Type")
        }
        return r
    }

    private func pollLoop() async {
        var first = true, failures = 0          // first: this poll's first request asks for the whole state at once
        await pickHost()
        while !Task.isCancelled {
            do {
                let (data, resp) = try await urlSession.data(for: request("/v1/state?since=\(first ? 0 : rev)\(deviceQuery)", timeout: 28))
                let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
                guard code == 200 else { throw code == 401 ? URLError(.userAuthenticationRequired) : URLError(.badServerResponse) }
                apply(try JSONDecoder().decode(HubState.self, from: data), initial: !loaded)
                first = false; loaded = true
                connected = true
                lastError = nil
                failingSince = nil
                failures = 0
            } catch {
                if Task.isCancelled { break }
                // A request fails every time the watch sleeps and wakes, so one failure says nothing. Stay on the
                // address that worked and retry it; only say the Mac is unreachable after 8 s of failing, and only
                // move to the next address after a couple of failures in a row on this one.
                let now = Date(), since = failingSince ?? now
                failingSince = since
                let refused = (error as? URLError)?.code == .userAuthenticationRequired
                if refused || now.timeIntervalSince(since) > 8 {
                    connected = false
                    lastError = refused ? "Hub refused the token" : "Can't reach your Mac"
                }
                failures += 1
                if failures >= 2 { failures = 0; await pickHost() }      // the path changed: find the address that answers now
                else { try? await Task.sleep(for: .seconds(1)) }
            }
        }
    }

    private func apply(_ s: HubState, initial: Bool) {
        rev = s.rev
        state = s
        for line in s.spoken where !seenSpoken.contains(line.id) {
            seenSpoken.insert(line.id)
            if !initial { onSpoken?(line) }
        }
        for a in s.approvals where !seenApprovals.contains(a.requestId) {
            seenApprovals.insert(a.requestId)
            if !initial { onApproval?(a) }
        }
        // the hub only ever sends the last few lines and the open approvals, so older ids can go
        if seenSpoken.count > 300 { seenSpoken = Set(s.spoken.map(\.id)) }
        if seenApprovals.count > 100 { seenApprovals = Set(s.approvals.map(\.requestId)) }
    }

    /// `approval` is the approval card that was on screen while you spoke: a spoken yes or no answers that one.
    /// What you said, for the agent you were talking to when you started (and the approval card that was on screen).
    func send(audio url: URL, approval: String?, agent: String) async -> RouteResult? {
        guard let data = try? Data(contentsOf: url) else { return nil }
        var h = ["X-Chums-Agent": agent, "X-Chums-Device": Self.device]
        if let approval { h["X-Chums-Approval"] = approval }
        return await post("/v1/utterance", body: data, contentType: "audio/m4a", headers: h)
    }

    /// One line for the hub's log (~/.chums/watch-events.log): what the watch did, so it can be checked from the Mac.
    func event(_ text: String) {
#if targetEnvironment(simulator)
        let text = "[sim] " + text                                   // the Simulator reports to the same hub
#endif
        guard let body = try? JSONSerialization.data(withJSONObject: ["text": text]) else { return }
        let r = request("/v1/event", method: "POST", body: body, timeout: 5)
        Task { _ = try? await urlSession.data(for: r) }
    }

    /// The voices the Mac can speak in; nil when it can't say.
    func voices() async -> [VoiceInfo]? {
        struct R: Decodable { let voices: [VoiceInfo] }
        let r: (R?, String?) = await exchange(request("/v1/voices", timeout: 10))
        return r.0?.voices
    }
    /// The models each runtime offers ("claude", "codex").
    func models() async -> [String: ModelChoices]? {
        await exchange(request("/v1/models", timeout: 10)).0
    }
    /// The permission modes each runtime offers ("claude", "codex").
    func permissions() async -> [String: PermissionChoices]? {
        await exchange(request("/v1/permissions", timeout: 10)).0
    }
    /// An agent's permission mode (nil: its runtime's own): it restarts with it. nil once it has, else why not.
    func setPermission(_ agent: String, mode: String?) async -> String? {
        let body = try? JSONSerialization.data(withJSONObject: ["mode": mode.map { $0 as Any } ?? NSNull()])
        let req = request("/v1/agents/\(agent)/permission", method: "POST", body: body, timeout: 90)
        guard let (data, resp) = try? await urlSession.data(for: req) else { return "Can't reach your Mac" }
        if (resp as? HTTPURLResponse)?.statusCode == 200 { return nil }
        return (try? JSONDecoder().decode([String: String].self, from: data))?["error"] ?? "Couldn't change it"
    }
    /// An agent's model (nil: its runtime's own): it restarts on it. nil once it has, else why not.
    func setModel(_ agent: String, model: String?) async -> String? {
        let body = try? JSONSerialization.data(withJSONObject: ["model": model.map { $0 as Any } ?? NSNull()])
        let req = request("/v1/agents/\(agent)/model", method: "POST", body: body, timeout: 90)
        guard let (data, resp) = try? await urlSession.data(for: req) else { return "Can't reach your Mac" }
        if (resp as? HTTPURLResponse)?.statusCode == 200 { return nil }
        return (try? JSONDecoder().decode([String: String].self, from: data))?["error"] ?? "Couldn't change it"
    }
    /// An agent's voice; nil once the hub has it, else why not.
    func setVoice(_ agent: String, voice: String) async -> String? {
        let req = request("/v1/agents/\(agent)/voice", method: "POST", body: try? JSONEncoder().encode(["voice": voice]), timeout: 10)
        guard let (data, resp) = try? await urlSession.data(for: req) else { return "Can't reach your Mac" }
        if (resp as? HTTPURLResponse)?.statusCode == 200 { return nil }
        return (try? JSONDecoder().decode([String: String].self, from: data))?["error"] ?? "Couldn't change it"
    }

    /// A reply's voice from the hub, nil when there's none or it can't be fetched.
    /// A file from the hub (an artifact's original, for the iPhone's viewers): nil when it can't be had. Big files take time.
    func fetch(_ path: String, timeout: Double = 90) async -> Data? {
        guard let (data, resp) = try? await urlSession.data(for: request(path, timeout: timeout)),
              (resp as? HTTPURLResponse)?.statusCode == 200 else { return nil }
        return data
    }
    func speech(_ path: String) async -> Data? {
        guard let (data, resp) = try? await urlSession.data(for: request(path, timeout: 8)),
              (resp as? HTTPURLResponse)?.statusCode == 200 else { return nil }
        return data
    }

    // MARK: souls

    func soul(_ agent: String) async -> SoulCard? { await exchange(request("/v1/agents/\(agent)/soul", timeout: 10)).0 }
    /// What you said about an agent's soul: the hub transcribes it and proposes a change (nothing is saved yet).
    func sendSoul(audio url: URL, agent: String) async -> SoulProposal? {
        guard let data = try? Data(contentsOf: url) else { return nil }
        var r = request("/v1/utterance", method: "POST", body: data, contentType: "audio/m4a", timeout: 90)
        r.setValue(agent, forHTTPHeaderField: "X-Chums-Soul")
        return await exchange(r).0
    }
    /// Typed words to an agent, as if said (the iPhone's composer, Siri, the widget).
    func say(_ text: String, agent: String, approval: String? = nil, files: [String] = []) async -> RouteResult? {
        var body: [String: Any] = ["text": text, "agent": agent, "device": Self.device]
        if let approval { body["approval"] = approval }
        if !files.isEmpty { body["files"] = files }
        return await exchange(request("/v1/say", method: "POST", body: try? JSONSerialization.data(withJSONObject: body), timeout: 30)).0
    }

    /// A picture or a file, to the Mac (the hub keeps it in ~/.chums/uploads); its path there goes with the next order.
    struct Upload: Decodable { let path: String; let name: String; let artifact: Artifact? }
    func upload(_ data: Data, name: String, type: String) async -> Upload? {
        let q = name.addingPercentEncoding(withAllowedCharacters: .alphanumerics) ?? "file"
        let req = request("/v1/upload?name=\(q)", method: "POST", body: data, contentType: type, timeout: 120)
        guard let (d, resp) = try? await urlSession.data(for: req), (resp as? HTTPURLResponse)?.statusCode == 200 else { return nil }
        return try? JSONDecoder().decode(Upload.self, from: d)
    }

    /// The agent the iPhone shows now: the widgets show it too, when no agent is picked in them.
    func focus(_ agent: String) async {
        let body = try? JSONEncoder().encode(["agent": agent])
        _ = try? await urlSession.data(for: request("/v1/focus", method: "POST", body: body, timeout: 10))
    }

    /// The address the hub answers at now, and how long it takes to answer (ms; nil: it didn't).
    var address: String { base }
    func ping() async -> Double? {
        let t0 = Date()
        guard let (_, resp) = try? await urlSession.data(for: request("/v1/ping", timeout: 10)),
              (resp as? HTTPURLResponse)?.statusCode == 200 else { return nil }
        return Date().timeIntervalSince(t0) * 1000
    }

    /// The same with typed words (Simulator captures: -soulSay "…").
    func soulFromText(_ text: String, agent: String) async -> SoulProposal? {
        await exchange(request("/v1/say", method: "POST", body: try? JSONEncoder().encode(["soul": agent, "text": text]), timeout: 90)).0
    }
    func saveSoul(_ agent: String, proposal: String) async -> (SoulCard?, String?) {
        await exchange(request("/v1/agents/\(agent)/soul/save", method: "POST", body: try? JSONEncoder().encode(["proposal": proposal]), timeout: 20))
    }
    /// Switches an agent to Claude Code ("claude") or Codex ("codex"); nil once it runs on it, else why not.
    func setRuntime(_ agent: String, runtime: String) async -> String? {
        let req = request("/v1/agents/\(agent)/runtime", method: "POST", body: try? JSONEncoder().encode(["runtime": runtime]), timeout: 150)
        guard let (data, resp) = try? await urlSession.data(for: req) else { return "Can't reach your Mac" }
        if (resp as? HTTPURLResponse)?.statusCode == 200 { return nil }
        return (try? JSONDecoder().decode([String: String].self, from: data))?["error"] ?? "Couldn't switch it"
    }
    /// One part of a soul (name, owns, refers, voice, body), written as given.
    func setSoul(_ agent: String, field: String, value: String) async -> (SoulCard?, String?) {
        await exchange(request("/v1/agents/\(agent)/soul/set", method: "POST",
                               body: try? JSONEncoder().encode(["field": field, "value": value]), timeout: 20))
    }
    func undoSoul(_ agent: String) async -> (SoulCard?, String?) {
        await exchange(request("/v1/agents/\(agent)/soul/undo", method: "POST", body: Data("{}".utf8), timeout: 20))
    }
    /// A request whose failure has a reason worth showing (the hub's error message).
    private func exchange<T: Decodable>(_ r: URLRequest) async -> (T?, String?) {
        guard let (data, resp) = try? await urlSession.data(for: r) else { return (nil, "Can't reach your Mac") }
        let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
        if code == 200, let v = try? JSONDecoder().decode(T.self, from: data) { return (v, nil) }
        return (nil, (try? JSONDecoder().decode(HubFailure.self, from: data))?.error ?? "Something went wrong (\(code))")
    }

    /// True once the hub has the verdict.
    func verdict(_ requestId: String, allow: Bool) async -> Bool {
        let body = try? JSONEncoder().encode(["requestId": requestId, "behavior": allow ? "allow" : "deny"])
        let r: RouteResult? = await post("/v1/verdict", body: body ?? Data())
        return r != nil
    }

    /// The screen woke or you touched it while the Mac was out of reach: look again now instead of after the timeout.
    func nudge() {
        guard pollTask != nil, !connected || lastError != nil else { return }
        stop(); start()
    }

    private func post<T: Decodable>(_ path: String, body: Data, contentType: String = "application/json", headers: [String: String] = [:]) async -> T? {
        var r = request(path, method: "POST", body: body, contentType: contentType)
        for (k, v) in headers { r.setValue(v, forHTTPHeaderField: k) }
        do {
            let (data, resp) = try await urlSession.data(for: r)
            let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
            if code == 401 { lastError = "Hub refused the token"; return nil }
            guard code == 200 else { return nil }
            return try JSONDecoder().decode(T.self, from: data)
        } catch {
            return nil
        }
    }
}