Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
import Cua
import Foundation
import SwiftUI
/// The app's live data layer: one Space, a roster of Bots, and one long-lived
/// agent thread per Bot.
///
/// **One Space, many Bots.** `SpacesClient.swift` argues this out in full: Koala
/// Bot is one persistent VM per user with a *screen* per Bot, and screens are
/// explicitly not security boundaries. So this store creates (or attaches to)
/// exactly one Space and starts one `agent_start` thread per Bot inside it. It
/// never creates a Space per Bot, and it never deletes the Space it attached
/// to.
///
/// Everything the views need comes through `BotDataSource`, so the same screens
/// render from `FixtureDataSource` during PNG export and from this store at
/// runtime.
@MainActor
final class BotStore: ObservableObject, BotDataSource {
// MARK: Published state
enum Connection: Equatable {
case detached
case connecting
case attached(String)
case failed(String)
var spaceID: String? { if case .attached(let s) = self { return s }; return nil }
}
/// A message the user must see rather than have swallowed: a refused
/// `agent_message`, a failed tool call. Refusals are *not* errors — the
/// harness refusing a mid-turn message is correct behaviour — but they are
/// also not nothing, so they surface here and in the transcript.
struct Notice: Identifiable, Equatable {
enum Kind: Equatable { case refusal, failure, info }
let id = UUID()
var kind: Kind
var botID: String?
var text: String
}
@Published private(set) var connection: Connection = .detached
/// The roster, most recently active first, pinned Bots keep their flag.
@Published private(set) var bots: [Bot] = []
@Published private(set) var presences: [String: BotPresence] = [:]
@Published private(set) var threads: [String: Thread] = [:]
@Published private(set) var notices: [Notice] = []
/// Windows in the Space — what the Agent Computer screens are opened against.
@Published private(set) var spaceWindows: [SpaceWindow] = []
// MARK: Internals
private let client: SpacesClient
/// Local Bot identity. The Space knows about *runs*, not about Bots: it has
/// no notion of a name, a colour or a pinned flag, so identity lives here
/// and is joined to the run list by marker (see `marker(for:)`).
private var identities: [String: Bot]
private var order: [String]
/// botID -> run id.
private var runs: [String: String] = [:]
/// botID -> the turns we know about, oldest first.
private var turns: [String: [BotTurn]] = [:]
/// botID -> the run's events folded by the SDK into transcript items
/// (`AgentTranscript`: agent messages, the prompt, and muted activity
/// groups). The one classification rule every sample shares.
private var transcripts: [String: CuaSDK.AgentTranscript] = [:]
/// botID -> the run its transcript was folded from.
private var transcriptRuns: [String: String] = [:]
/// botID -> the last runner turn a message of this app became (turn 1
/// is the prompt the run was started with).
private var runTurns: [String: UInt32] = [:]
/// botID -> messages this app put in the thread itself, before any agent
/// output: the greeting a freshly created Bot opens with and the choice
/// card under it. They are not derived from the run's tail, so
/// `rebuildThread` has to be told about them or the next poll erases them.
private var seeded: [String: [Message]] = [:]
/// botID -> the answers the user has given to choice cards, oldest first.
/// The nth card in a thread is resolved by the nth answer.
private var choiceAnswers: [String: [String]] = [:]
/// Bots whose choice cards the user dismissed.
private var dismissedChoices: Set<String> = []
/// Bots whose thread is showing a typing indicator rather than a greeting.
@Published private(set) var typing: Set<String> = []
/// Bots the user has spoken to and is waiting on, keyed to the runner turn
/// their message becomes.
///
/// This is the send-side half of the indicator, and it is deliberately
/// **not** `typing`: `typing` means "this Bot has never spoken and owes a
/// greeting", and it is cleared the moment the tail stops being empty. On
/// a send the tail is already long, so that test can never fire, which is
/// exactly why sending a message used to show nothing at all until the
/// whole reply landed.
///
/// The stored value is what makes the clear honest. A spinner driven by a
/// timer, or by a bare boolean, is a spinner that can get stuck; this one
/// is answered by the same offset arithmetic that attributes output to a
/// turn, so "the reply has begun" is a fact about the tail rather than a
/// guess about elapsed time.
@Published private(set) var pending: [String: UInt32] = [:]
/// Is this Bot owed something the user is visibly waiting for — a greeting
/// it has not given yet, or a reply to a message just sent?
///
/// The one question the transcript asks. Both halves clear on real state:
/// see `firstOutputArrived` and `clearPending`.
func isAwaitingReply(_ botID: String) -> Bool {
typing.contains(botID) || pending[botID] != nil
}
/// Stop waiting on `botID`. Every exit from a send funnels through here —
/// first token, turn finished, refusal, transport error, failed probe and
/// an explicit stop — because the failure mode being fixed is a spinner
/// with no path out of it.
private func clearPending(_ botID: String) {
if pending.removeValue(forKey: botID) != nil { objectWillChange.send() }
}
private var pollTask: Task<Void, Never>?
private let calendar = Calendar.current
/// One turn of a Bot's thread: what the user said, whether it was taken,
/// and which of the run's turns it became.
///
/// Every event the runner writes carries its turn number, so output is
/// attributed to the turn that caused it by that number (`runTurn`), not
/// by slicing a text tail. `nil` for a refused message or an attachment.
struct BotTurn {
var userText: String?
var attachments: [Attachment] = []
var refusalReason: String? = nil
var runTurn: UInt32? = nil
var reaction: String? = nil
var startedAt: Date = Date()
}
/// Whether a run this app did not start gets a roster row.
///
/// **Off.** The sidebar is a list of the user's *conversations*, and a run
/// somebody else started in the shared Space is not one of them. It used
/// to be on, with the reasoning that a run doing work in the user's Space
/// which the UI cannot see is worse than an ugly row — and on the live
/// demo Space, which has thirty-odd runs in it, that reasoning produced
/// exactly what the user reported: a sidebar full of threads they had
/// never opened. A Bot appears when the user creates one or installs one.
let adoptsForeignRuns: Bool
/// Where roster *names* are kept between launches. `nil` means "do not
/// persist", which is the default and is what every test gets: a store that
/// reads a file in Application Support is not hermetic, and a test that
/// passes or fails depending on what the app did the last time somebody ran
/// it is worse than no test. The app passes `rosterFileURL()`.
private let rosterFile: URL?
/// The roster this store starts with.
///
/// **Empty**, and that is the whole point of this parameter existing. It
/// used to default to `Fixtures.bots`, so launching the app showed nine
/// coworkers nobody had hired and no conversation existed with. The
/// fixtures are the *export path's* data (`FixtureDataSource`), and
/// `RUBRIC.md` grades thirteen renders built from them; they are not the
/// running app's roster and never were. Tests that want a populated store
/// pass one explicitly.
init(client: SpacesClient, identities roster: [Bot] = [],
adoptsForeignRuns: Bool = false, rosterFile: URL? = nil) {
self.client = client
self.adoptsForeignRuns = adoptsForeignRuns
self.rosterFile = rosterFile
self.identities = Dictionary(uniqueKeysWithValues: roster.map { ($0.id, $0) })
self.order = roster.map(\.id)
self.bots = roster
}
deinit { pollTask?.cancel() }
// MARK: - BotDataSource
func thread(for botID: String) -> Thread {
fixtureThreads[botID] ?? threads[botID] ?? Thread(botID: botID, messages: [])
}
/// Fixture transcripts for the design capture (`UICapture.designVariable`),
/// shown in place of a live thread. Never set in normal use.
@Published private(set) var fixtureThreads: [String: Thread] = [:]
func showFixture(_ thread: Thread) { fixtureThreads[thread.botID] = thread }
func presence(for botID: String) -> BotPresence {
presences[botID] ?? .unstarted
}
func bot(_ id: String) -> Bot? { identities[id] }
var spaceID: String? { connection.spaceID }
func runID(for botID: String) -> String? { runs[botID] }
// MARK: - Connecting
/// Attach to the user's single persistent Space and read the roster back.
///
/// Attaches; never deletes. With `OPENKOALABOTS_TEST_SPACE` set this is a
/// pure attach that creates nothing at all — the only safe way to run
/// against a Space someone demos from (`FRICTION.md` #5).
func connect() async {
connection = .connecting
do {
let space = try await client.ensureSpace()
connection = .attached(space)
// Names first, then the runs. The other order would let
// `improvisedBot` mint a name for a Bot the user already named.
loadRosterIdentities()
await refreshRoster()
} catch {
connection = .failed("\(error)")
post(.failure, nil, "could not attach to a Space: \(error)")
}
}
/// Read `agent_list` and join it to local Bot identity.
///
/// A run carries no Bot identity of its own, so the join is done on a
/// marker this store writes into the prompt (and which the harness echoes
/// back in `summary`). Runs with no marker are still shown — as Bots named
/// after their agent — rather than hidden, because a run doing work in the
/// user's Space that the UI cannot see is worse than an ugly row.
func refreshRoster() async {
guard let space = connection.spaceID else { return }
do {
let rows = try await client.listBots(space: space)
apply(roster: rows)
} catch {
post(.failure, nil, "agent_list failed: \(error)")
}
}
func apply(roster rows: [AgentRunSummary]) {
var seen = Set<String>()
for row in rows {
guard let botID = Self.botID(fromSummary: row.summary)
?? (adoptsForeignRuns ? adoptedID(for: row) : nil)
else { continue }
// A marked run whose identity this store no longer holds is a run
// from a previous launch. Adopt it: the conversation is real and
// the user had it. Without this the roster would empty itself on
// every restart, which is the opposite failure to the one above.
seen.insert(botID)
// Another run carrying the same marker (an earlier launch's)
// never takes over a Bot whose own run is still listed.
if let current = runs[botID], current != row.id,
rows.contains(where: { $0.id == current }) { continue }
runs[botID] = row.id
// A Bot is on the roster when its **run** is reported, never
// because an identity for it happens to be in memory or on disk.
// The condition is membership of `order`, not of `identities`,
// precisely so that a saved name cannot resurrect a conversation
// whose run is gone — which is the fixture-roster defect wearing a
// different hat.
if identities[botID] == nil {
identities[botID] = Self.improvisedBot(id: botID, row: row, index: order.count)
}
if !order.contains(botID) {
order.append(botID)
}
var p = presences[botID] ?? .unstarted
// agent_list carries state and accepts_message but no reason; keep
// the reason from the last agent_status rather than blanking it.
p.runID = row.id
p.state = row.state
p.acceptsMessage = row.acceptsMessage
if !row.summary.isEmpty { p.summary = Self.strippingMarker(row.summary) }
presences[botID] = p
if var b = identities[botID] {
b.preview = transcripts[botID]?.preview() ?? p.summary
if let t = row.createdAt { b.timestamp = Self.timestamp(Date(timeIntervalSince1970: t)) }
identities[botID] = b
}
}
for id in order where !seen.contains(id) {
if presences[id] == nil { presences[id] = .unstarted }
}
applySavedOrdering()
rebuildBots()
}
private func rebuildBots() {
bots = order.compactMap { identities[$0] }
}
/// Put the rows back in the order the user last saw them.
///
/// `agent_list` returns runs in the Space's order, which is not the
/// sidebar's: a Bot created most recently sits at the top, and that
/// position is the user's, not the harness's. Only rows that are already
/// on the roster are touched — this sorts, it never adds.
private func applySavedOrdering() {
guard !savedOrder.isEmpty else { return }
let rank = Dictionary(uniqueKeysWithValues: savedOrder.enumerated().map { ($1, $0) })
let known = order.filter { rank[$0] != nil }.sorted { rank[$0]! < rank[$1]! }
let unknown = order.filter { rank[$0] == nil }
order = known + unknown
}
// MARK: - Hiring and steering
/// Put a Bot on the roster before it is hired.
///
/// Hiring from the UI needs this because the Space has no notion of a Bot
/// at all: `agent_start` takes a prompt, not an identity (`FRICTION.md`
/// §21). So a new Bot exists *here* first — name, shape, colour, roster
/// position — and only then does `hire` start the run that gets joined back
/// to it by marker. Registering is idempotent and never starts anything.
func register(_ bot: Bot, atTop: Bool = false) {
if identities[bot.id] == nil {
if atTop { order.insert(bot.id, at: 0) } else { order.append(bot.id) }
}
identities[bot.id] = bot
if presences[bot.id] == nil { presences[bot.id] = .unstarted }
rebuildBots()
}
/// Create a Bot **and its conversation**, in that order, and return it.
///
/// The ordering is deliberate, not a convenience: creation starts
/// the agent first, refreshes the roster, and only then opens it, so a row
/// never exists before a real agent does. This app used to do the reverse —
/// mint a roster identity, show it, then try to start a run — which is how
/// a row could exist with nothing behind it and need a word for that state.
/// There is no such state here: if the start fails, no row appears and the
/// caller is told why.
///
/// The new Bot goes to the **top** of the list and opens immediately with a
/// greeting, preceded by a typing indicator.
/// Whether a Bot is still being created — its agent has been started but
/// nothing has come back from it yet. The row shows `Creating…` meanwhile.
@Published private(set) var creating: Set<String> = []
@discardableResult
func createConversation(named name: String, dark: Bool = true,
kickstart: Bool = true,
opening: String = BotStore.openingInstruction) async throws -> Bot {
guard let space = connection.spaceID else { throw StoreError.notAttached }
let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines)
let title = trimmed.isEmpty ? Self.newBotName : trimmed
let id = Self.identifier(for: title, taken: Set(identities.keys))
// Minted, not registered: nothing is on the roster yet.
var bot = Persona.bot(id: id, name: title, dark: dark,
timestamp: Self.timestamp(Date()),
screenIndex: order.count)
// `isKickstartRequested`: the Bot is told to speak first. This is why a
// fresh account's single row already has a last message — the greeting
// is a real turn the agent took, not a string the client drew.
let prompt = kickstart
? "\(Self.marker(for: id)) \(opening)\n\n\(Self.kickstartInstruction)"
: "\(Self.marker(for: id)) \(opening)"
let run = try await client.startBot(space: space, bot: bot, prompt: prompt)
// The agent exists. Only now does a row.
bot.preview = ""
runs[id] = run.runID
transcripts[id] = CuaSDK.AgentTranscript()
transcriptRuns[id] = run.runID
runTurns[id] = 1
// No turn: the opening instruction is not something the user said, so
// it must not appear in the transcript as their message.
turns[id] = []
seeded[id] = []
presences[id] = BotPresence(runID: run.runID, state: .running,
reason: "just started", acceptsMessage: false,
summary: "")
register(bot, atTop: true)
saveRosterIdentities()
creating.insert(id)
if kickstart { typing.insert(id) }
rebuildThread(id)
return bot
}
/// What `kickstartAwaitingFirstMessage` amounts to over this transport:
/// the agent is asked to open the conversation, and told how to put a
/// choice card in it if it wants one. No wording is dictated — see
/// `AgentOutputParser.choiceCard`.
static let kickstartInstruction =
"Open the conversation with one short greeting. "
+ "If you want to offer the user a small set of choices, emit them as "
+ "a block: a line `[[choices: <your question>]]`, then one option per "
+ "line, then `[[/choices]]`."
/// The default name a `Create new Bot` gives its Bot. `New Bot`, not
/// `New chat`: the roster is of Bots, not chats.
static let newBotName = "New Bot"
/// What a freshly created Bot is actually told to do in the Space. The
/// user never sees this — it is not a turn in the transcript — which is
/// why creating a Bot shows a greeting rather than an echoed prompt.
static let openingInstruction =
"You are a teammate agent working in a Cua Space. "
+ "Wait for the user's first instruction."
/// The Bot has spoken: it is no longer being created and no longer typing.
///
/// Called from `refresh` the moment the tail stops being empty. Nothing
/// here fabricates a greeting — the greeting is whatever the agent said,
/// which is the point of asking it to speak first.
private func firstOutputArrived(_ botID: String) {
creating.remove(botID)
typing.remove(botID)
}
/// Resolve a choice card in a Bot's thread: record the answer and send it.
///
/// The resolution is stored per Bot rather than written into the message,
/// because the message is rebuilt from the agent's tail on every poll and
/// anything written into it would be erased a second later.
func answer(_ text: String, to botID: String) async {
choiceAnswers[botID, default: []].append(text)
rebuildThread(botID)
_ = await send(text, to: botID)
}
/// Dismiss a choice card without answering it.
func dismissChoices(in botID: String) {
dismissedChoices.insert(botID)
rebuildThread(botID)
}
// MARK: - Roster identity, across launches
/// Where the roster's *names* live.
///
/// The Space stores runs, not Bots: a run has an agent, a state and a
/// prompt, and no name, colour or shape. So when the app restarts and
/// `agent_list` returns the user's own past conversations, the only thing
/// joining them back to the Bots they belong to is the marker in the
/// prompt — which gives an id but not a name. Without this file a Bot the
/// user called `Inbox Zero` came back as `claude-code`: a real conversation
/// wearing the wrong label, and a quieter version of the same defect this
/// rewrite is about. The sidebar must say what the user made.
///
/// Caught by photographing the running app twice, not by reading the code.
static func rosterFileURL() -> URL {
let dir = AppDataDirectory.url()
return dir.appendingPathComponent("roster.json")
}
/// The saved ordering, used only to sort rows whose runs came back. Never
/// used to decide *whether* a row exists.
private var savedOrder: [String] = []
private struct SavedRoster: Codable {
var order: [String]
var identities: [Bot]
}
/// Read the saved names back.
///
/// Nothing is *shown* because of this — a Bot still appears only when
/// `agent_list` reports its run — so a stale entry for a run that no longer
/// exists cannot resurrect a dead conversation. It supplies the name,
/// colour and shape for one that does.
func loadRosterIdentities(from url: URL? = nil) {
guard let file = url ?? rosterFile else { return }
guard let data = try? Data(contentsOf: file),
let saved = try? JSONDecoder().decode(SavedRoster.self, from: data)
else { return }
for bot in saved.identities where identities[bot.id] == nil {
identities[bot.id] = bot
}
// `order` is deliberately **not** restored. It is the list of Bots the
// sidebar shows, and that list is built from the runs `agent_list`
// reports. Restoring it here would put a row back for every Bot the
// user ever made, run or no run.
savedOrder = saved.order
}
@discardableResult
func saveRosterIdentities(to url: URL? = nil) -> Bool {
guard let file = url ?? rosterFile else { return false }
let saved = SavedRoster(order: order, identities: order.compactMap { identities[$0] })
do {
let encoder = JSONEncoder()
encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
try encoder.encode(saved).write(to: file, options: .atomic)
return true
} catch {
post(.failure, nil, "could not save the roster: \(error)")
return false
}
}
/// A stable, readable id from a display name, unique within the roster.
static func identifier(for name: String, taken: Set<String>) -> String {
let base = name.lowercased()
.components(separatedBy: CharacterSet.alphanumerics.inverted)
.filter { !$0.isEmpty }
.joined(separator: "-")
let root = base.isEmpty ? "bot" : base
if !taken.contains(root) { return root }
var n = 2
while taken.contains("\(root)-\(n)") { n += 1 }
return "\(root)-\(n)"
}
/// Start a Bot's one long-lived agent thread in the shared Space.
///
/// Kept for the paths that mint an identity themselves — the Routines
/// runner and the group messenger, which both have to be able to start a
/// Bot that is already on the roster. New conversations from the UI go
/// through `createConversation`, which starts the agent *first*.
@discardableResult
func hire(_ botID: String, prompt: String) async throws -> String {
guard let space = connection.spaceID else {
throw StoreError.notAttached
}
guard let bot = identities[botID] else { throw StoreError.unknownBot(botID) }
let marked = "\(Self.marker(for: botID)) \(prompt)"
let run = try await client.startBot(space: space, bot: bot, prompt: marked)
runs[botID] = run.runID
transcripts[botID] = CuaSDK.AgentTranscript()
transcriptRuns[botID] = run.runID
runTurns[botID] = 1
turns[botID] = [BotTurn(userText: prompt, runTurn: 1)]
presences[botID] = BotPresence(runID: run.runID, state: .running,
reason: "just started", acceptsMessage: false,
summary: prompt)
rebuildThread(botID)
await refresh(botID)
return run.runID
}
/// Speak to a Bot.
///
/// A refusal is **not** swallowed: it comes back as `false`, lands in
/// `notices`, and is written into the transcript as a centred system line,
/// so the user can see that their message did not reach the Bot.
@discardableResult
func send(_ text: String, to botID: String) async -> MessageOutcome {
guard let space = connection.spaceID else {
let o = MessageOutcome(accepted: false, reason: "not attached to a Space")
post(.failure, botID, o.reason)
return o
}
guard let run = runs[botID] else {
let o = MessageOutcome(accepted: false, reason: "this Bot has no agent thread")
post(.failure, botID, o.reason)
return o
}
// The runner numbers turns 1, 2, ...: an accepted message becomes the
// next one. A run adopted from an earlier launch may be further on.
let seen = transcripts[botID]?.items().map(\.turn).max() ?? 0
let nextTurn = max(runTurns[botID] ?? 1, seen) + 1
// The user's message goes into the transcript *before* the round trip,
// together with the pending marker. Appending it after the `await` is
// what made the window sit still after a send: on a Space that takes a
// beat to answer, neither the message nor any sign of it existed until
// the reply did. The turn is amended below if the send is refused.
turns[botID, default: []].append(BotTurn(userText: text))
let index = turns[botID]!.count - 1
pending[botID] = nextTurn
rebuildThread(botID)
do {
let outcome = try await client.message(space: space, runID: run, text: text)
if !outcome.accepted {
// A refusal is an exit, not a pause. FRICTION §24: there is no
// outbox, so a refused message is never going to be answered
// and must not leave a bubble waiting for an answer.
let reason = outcome.reason.isEmpty ? "refused" : outcome.reason
turns[botID]?[index].refusalReason = reason
clearPending(botID)
post(.refusal, botID, "\(name(botID)) did not take that message: \(reason)")
rebuildThread(botID)
} else {
// Accepted: the message is the run's next turn. The
// indicator stays up, and `refresh` takes it down on the
// turn's first output or when the turn ends.
runTurns[botID] = nextTurn
turns[botID]?[index].runTurn = nextTurn
await refresh(botID)
}
return outcome
} catch {
let o = MessageOutcome(accepted: false, reason: "\(error)")
turns[botID]?[index].refusalReason = o.reason
clearPending(botID)
post(.failure, botID, "agent_message failed: \(error)")
rebuildThread(botID)
return o
}
}
/// Attach a file to a Bot's thread: upload it into the shared Space and
/// echo it in the transcript so the user can see what the Bot was given.
@discardableResult
func attach(_ localPath: String, to botID: String,
remoteDirectory: String = "/tmp/openkoalabots") async -> Attachment? {
guard let space = connection.spaceID else {
post(.failure, botID, "not attached to a Space"); return nil
}
let name = (localPath as NSString).lastPathComponent
let remote = "\(remoteDirectory)/\(name)"
do {
try await client.upload(space: space, localPath: localPath, remotePath: remote)
let size = (try? FileManager.default.attributesOfItem(atPath: localPath)[.size] as? Int) ?? nil
let a = Attachment(name: name, byteCount: size ?? 0)
var turn = BotTurn(userText: nil, attachments: [a])
turn.userText = nil
turns[botID, default: []].append(turn)
rebuildThread(botID)
return a
} catch {
post(.failure, botID, "upload failed: \(error)")
return nil
}
}
/// Bring a file the Bot produced back out to the host.
@discardableResult
func fetch(_ remotePath: String, to directory: String? = nil) async -> String? {
guard let space = connection.spaceID else { return nil }
do { return try await client.download(space: space, remotePath: remotePath,
localDirectory: directory) }
catch { post(.failure, nil, "download failed: \(error)"); return nil }
}
/// Stop a Bot's turn. The outcome says whether it *actually* died.
@discardableResult
func stop(_ botID: String) async -> StopOutcome? {
guard let space = connection.spaceID, let run = runs[botID] else { return nil }
do {
let out = try await client.stopBot(space: space, runID: run)
if !out.stopped {
post(.failure, botID, "stop did not confirm the run died: \(out.reason)")
}
await refresh(botID)
return out
} catch {
post(.failure, botID, "agent_stop failed: \(error)")
// The user asked it to stop and we could not even ask. Whatever is
// true of the run, the user is no longer waiting on this turn.
clearPending(botID)
return nil
}
}
/// Attach a reaction to a Bot's most recent turn.
func react(_ emoji: String, to botID: String) {
guard var list = turns[botID], !list.isEmpty else { return }
list[list.count - 1].reaction = emoji
turns[botID] = list
rebuildThread(botID)
}
// MARK: - Polling
/// Pull one Bot's status and rebuild its transcript tail.
///
/// This is a poll because the protocol has no push. See `FRICTION.md` #2.
func refresh(_ botID: String) async {
guard let space = connection.spaceID, let run = runs[botID] else { return }
do {
// State only: the transcript comes from the structured events.
let status = try await client.status(space: space, runID: run, tail: 1)
var p = BotPresence(runID: run, status: status)
// The harness echoes the prompt back as `summary`, marker and all.
// The marker is this app's private join key and must never be shown.
p.summary = Self.strippingMarker(p.summary)
presences[botID] = p
// One fold per run: a Bot joined to another run starts over.
let transcript = transcriptRuns[botID] == run
? transcripts[botID] ?? CuaSDK.AgentTranscript() : CuaSDK.AgentTranscript()
transcripts[botID] = transcript
transcriptRuns[botID] = run
let before = transcript.revision()
// New events since the last poll, a page at a time. Absorbing is
// idempotent, so a re-read page cannot duplicate rows.
for _ in 0..<Self.eventPagesPerPoll {
let from = transcript.cursor()
let page = try await client.events(space: space, runID: run, cursor: from)
_ = try transcript.absorbJson(json: page)
if transcript.cursor() == from { break }
}
let items = transcript.items()
if items.contains(where: { $0.kind == "message" }) {
firstOutputArrived(botID)
}
// Two ways a send stops pending, both read off real state:
//
// * the reply has **begun**: the run wrote something (a message or
// activity) for the turn the message became, so an indicator
// next to it would be a lie;
// * the turn is **over**: the harness says the run is no longer
// working, so nothing further is coming. `awaitingInput` counts:
// the Bot has stopped and is waiting on the user.
if let turn = pending[botID] {
if items.contains(where: { $0.kind != "user" && $0.turn >= turn }) { clearPending(botID) }
else if p.state != .running { clearPending(botID) }
}
if var b = identities[botID] {
b.preview = transcript.preview() ?? Self.strippingMarker(status.summary)
b.timestamp = Self.timestamp(Date())
identities[botID] = b
}
if transcript.revision() != before || threads[botID] == nil { rebuildThread(botID) }
rebuildBots()
} catch {
// A failed probe must not be laundered into a state. Say unknown.
var p = presence(for: botID)
p.state = .unknown
p.reason = "status probe failed: \(error)"
p.acceptsMessage = false
presences[botID] = p
// The probe is the only thing that could take the indicator down,
// and it just failed. Leaving it up would spin forever on a Space
// that went away; the honest reading of "unknown" is not "still
// working".
clearPending(botID)
}
}
/// Event pages read per poll (500 events each) before the rest waits.
static let eventPagesPerPoll = 20
func refreshAll() async {
for id in order where runs[id] != nil { await refresh(id) }
}
/// The Bot whose thread is currently on screen, if any.
///
/// Set by `AppModel.open`. The poll loop uses it to decide what deserves a
/// round trip *this* tick — see `startPolling`.
private(set) var focusedBotID: String?
func focus(_ botID: String?) { focusedBotID = botID }
/// Round-robin cursor over `order`, so every hired Bot is still polled.
private var rotation = 0
/// Start the poll loop every consumer of `agent_status` has to write by
/// hand. One loop for the whole roster, not one per Bot.
///
/// **What this used to do, and why it made the app unusable.** Each tick
/// called `refreshRoster()` and then `refreshAll()` — one `agent_status`
/// per hired Bot, serially. On the live Space that is thirty-odd SSH round
/// trips per tick, and because `BotStore` is `@MainActor` the loop returned
/// to the main actor between every one of them to parse a 400-line tail
/// (`rebuildThread`) and republish the whole roster (`rebuildBots`). Thirty
/// parses and thirty full SwiftUI invalidations per tick, continuously, on
/// the thread that also has to handle clicks — which is what "unable to
/// click anything in the top bar without it freezing" was.
///
/// `FRICTION.md` §25 already named the shape of the fix: the *roster* needs
/// every Bot, but `agent_list` returns state, summary and accepts_message
/// for every run in **one** call. Only the transcript needs `agent_status`,
/// and only one transcript is ever on screen. So a tick is now:
///
/// * `agent_list` — one round trip, the whole roster;
/// * `agent_status` for the focused Bot, if there is one;
/// * `agent_status` for one other hired Bot, round-robin.
///
/// Two or three round trips instead of thirty-one, and no Bot loses
/// coverage — the rotation still reaches every one of them, which is what
/// keeps `testPollLoopRefreshesTheRosterFromOneTask` honest. See §51.
func startPolling(every interval: Duration = .seconds(2)) {
pollTask?.cancel()
pollTask = Task { [weak self] in
while !Task.isCancelled {
guard let self else { return }
await self.pollOnce()
try? await Task.sleep(for: interval)
}
}
}
/// One tick of the poll loop. Separated out so a test can drive it.
func pollOnce() async {
await refreshRoster()
let focused = focusedBotID
if let focused, runs[focused] != nil { await refresh(focused) }
if let next = nextInRotation(skipping: focused) { await refresh(next) }
}
private func nextInRotation(skipping: String?) -> String? {
let hired = order.filter { runs[$0] != nil && $0 != skipping }
guard !hired.isEmpty else { return nil }
rotation = (rotation + 1) % hired.count
return hired[rotation]
}
func stopPolling() { pollTask?.cancel(); pollTask = nil; focusedBotID = nil }
/// The live window list behind the Agent Computer screens.
@discardableResult
func refreshWindows() async -> [SpaceWindow] {
guard let space = connection.spaceID else { return [] }
do { spaceWindows = try await client.windows(space: space) }
catch { post(.failure, nil, "list_space_windows failed: \(error)") }
return spaceWindows
}
// MARK: - Transcript
/// Rebuild one Bot's thread from what the Space actually reported.
///
/// The thread is derived, not accumulated: every rebuild starts from the
/// turn list plus the SDK's transcript items, so a re-poll cannot
/// duplicate rows. The items' `user` entries (the prompt as the agent got
/// it) are skipped: the user's own words come from the turn list, so the
/// prompt is never shown twice. Each local turn goes in front of the
/// first output of the run turn it became; output before any of them
/// (the greeting a Bot opens with, install progress) comes first.
func rebuildThread(_ botID: String) {
let list = turns[botID] ?? []
let active = presence(for: botID).state == .running
let items = (transcripts[botID]?.items() ?? []).filter { $0.kind != "user" }
var messages: [Message] = []
/// The run turn of each bot message, for reactions.
var messageTurns: [UInt32?] = []
if let first = list.first {
messages.append(Message(sender: .bot, body: .systemEvent(Self.dayLabel(first.startedAt))))
} else if !items.isEmpty || seeded[botID]?.isEmpty == false {
messages.append(Message(sender: .bot, body: .systemEvent(Self.dayLabel(Date()))))
}
messages.append(contentsOf: seeded[botID] ?? [])
messageTurns = Array(repeating: nil, count: messages.count)
var next = 0
func emitTurns(through last: Int) {
while next <= last && next < list.count {
let turn = list[next]
next += 1
if let text = turn.userText {
messages.append(Message(sender: .user, body: .prose(text)))
messageTurns.append(nil)
}
for a in turn.attachments {
messages.append(Message(sender: .user, body: .linkFile(
LinkFile(title: a.name, subtitle: Self.byteLabel(a.byteCount), kind: .file))))
messageTurns.append(nil)
}
if let reason = turn.refusalReason {
// Refusal is shown, never swallowed.
messages.append(Message(sender: .bot, body: .systemEvent(
Message.refusalPrefix + reason)))
messageTurns.append(nil)
}
}
}
for item in items {
if let last = list.lastIndex(where: { ($0.runTurn ?? .max) <= item.turn }) {
emitTurns(through: last)
}
if item.kind == "activity" {
messages.append(Message(sender: .bot, body: .activity(
ActivityGroup(summary: item.text, steps: item.steps))))
messageTurns.append(item.turn)
} else {
for body in AgentOutputParser.bodies(from: item.text, active: active) {
messages.append(Message(sender: .bot, body: body))
messageTurns.append(item.turn)
}
}
}
emitTurns(through: list.count - 1)
// A reaction sits under the last thing the Bot said in that turn.
for turn in list {
guard let reaction = turn.reaction, let r = turn.runTurn,
let i = messages.indices.last(where: { k in
messageTurns[k] == r && messages[k].sender == .bot && !Self.isActivity(messages[k])
}) else { continue }
messages[i].reaction = reaction
}
threads[botID] = Thread(botID: botID, messages: applyChoiceState(messages, in: botID))
}
static func isActivity(_ m: Message) -> Bool {
if case .activity = m.body { return true }
return false
}
/// Re-apply the user's dealings with choice cards to a freshly rebuilt
/// thread. Dismissed cards are dropped; answered cards carry their answer.
private func applyChoiceState(_ messages: [Message], in botID: String) -> [Message] {
let answers = choiceAnswers[botID] ?? []
guard !answers.isEmpty || dismissedChoices.contains(botID) else { return messages }
var out: [Message] = []
var seen = 0
for m in messages {
guard case .choices(var card) = m.body else { out.append(m); continue }
if dismissedChoices.contains(botID) { continue }
if seen < answers.count { card.resolved = answers[seen] }
seen += 1
out.append(Message(sender: m.sender, body: .choices(card), reaction: m.reaction))
}
return out
}
// MARK: - Notices
private func post(_ kind: Notice.Kind, _ botID: String?, _ text: String) {
notices.append(Notice(kind: kind, botID: botID, text: text))
}
func dismiss(_ notice: Notice) {
notices.removeAll { $0.id == notice.id }
}
func clearNotices() { notices.removeAll() }
var latestNotice: Notice? { notices.last }
// MARK: - Identity join
enum StoreError: Error, CustomStringConvertible {
case notAttached
case unknownBot(String)
var description: String {
switch self {
case .notAttached: return "no Space attached: call connect() first"
case .unknownBot(let id): return "no such Bot: \(id)"
}
}
}
/// The marker written into a run's prompt so a later `agent_list` can be
/// joined back to the Bot that started it. A run has no metadata field, so
/// the prompt is the only carrier. `FRICTION.md` #12.
static func marker(for botID: String) -> String { "[openkoalabots:\(botID)]" }
static func botID(fromSummary summary: String) -> String? {
guard let open = summary.range(of: "[openkoalabots:"),
let close = summary.range(of: "]", range: open.upperBound..<summary.endIndex)
else { return nil }
let id = String(summary[open.upperBound..<close.lowerBound])
return id.isEmpty ? nil : id
}
static func strippingMarker(_ summary: String) -> String {
guard let open = summary.range(of: "[openkoalabots:"),
let close = summary.range(of: "]", range: open.upperBound..<summary.endIndex)
else { return summary }
return (summary.replacingCharacters(in: open.lowerBound..<close.upperBound, with: ""))
.trimmingCharacters(in: .whitespaces)
}
private func adoptedID(for row: AgentRunSummary) -> String { "run:\(row.id)" }
private func name(_ botID: String) -> String { identities[botID]?.name ?? botID }
/// A run this app did not start still gets a roster row, drawn from the
/// same shape/colour vocabulary so it does not look like an error.
private static func improvisedBot(id: String, row: AgentRunSummary, index: Int) -> Bot {
let shapes: [BlobShape] = [.circle, .teardrop, .cloud, .hexagon, .egg, .lozenge, .squircle]
let colors: [UInt32] = [0x8B5CF6, 0x2F80F0, 0x18BE4B, 0x11B5A0, 0xF97316, 0xF4234B, 0x5B5BE8]
return Bot(id: id,
name: row.agent.isEmpty ? "Bot" : row.agent,
shape: shapes[index % shapes.count],
colorHex: colors[index % colors.count],
preview: strippingMarker(row.summary),
timestamp: row.createdAt.map { timestamp(Date(timeIntervalSince1970: $0)) } ?? "",
screenIndex: index)
}
// MARK: - Formatting
static func timestamp(_ date: Date, now: Date = Date(),
calendar: Calendar = .current) -> String {
if calendar.isDate(date, inSameDayAs: now) {
let f = DateFormatter()
f.dateFormat = "h:mm a"
return f.string(from: date)
}
if let y = calendar.date(byAdding: .day, value: -1, to: now),
calendar.isDate(date, inSameDayAs: y) { return "Yesterday" }
let f = DateFormatter()
f.dateFormat = calendar.dateComponents([.day], from: date, to: now).day ?? 0 < 7
? "EEEE" : "d MMM"
return f.string(from: date)
}
static func dayLabel(_ date: Date, now: Date = Date(), calendar: Calendar = .current) -> String {
let f = DateFormatter()
f.dateFormat = "h:mm a"
if calendar.isDate(date, inSameDayAs: now) { return "Today \(f.string(from: date))" }
let d = DateFormatter()
d.dateFormat = "d MMM"
return "\(d.string(from: date)) \(f.string(from: date))"
}
static func byteLabel(_ bytes: Int) -> String {
if bytes <= 0 { return "file" }
if bytes < 1024 { return "\(bytes) B" }
if bytes < 1024 * 1024 { return String(format: "%.0f KB", Double(bytes) / 1024) }
return String(format: "%.1f MB", Double(bytes) / (1024 * 1024))
}
}