An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
import Foundation
import UserNotifications
struct Lockfile: Decodable, Equatable {
let pid: Int
let port: Int
let token: String
let daemonVersion: String?
}
struct BridgeStatus: Decodable, Equatable {
let connected: Bool
let daemonVersion: String
let protocolVersion: Int
let port: Int
let manifestInSync: Bool
let extensionVersion: String?
let pairedBrowsers: Int
let pairingPending: Bool
/// Absent from a Bridge before automatic pairing.
let pairing: PairingSetting?
}
enum PairingMode: String, CaseIterable, Identifiable {
case auto, ask, code
var id: String { rawValue }
var label: String {
switch self {
case .auto: "Automatic"
case .ask: "Ask me"
case .code: "Code only"
}
}
var detail: String {
switch self {
case .auto: "A browser with Browsentic connects by itself."
case .ask: "You allow each new browser here first."
case .code: "A browser connects only with a code you type into it."
}
}
var pairsByItself: Bool { self != .code }
}
/// The `pairing` answer, and the same pair inside `status`. The mode stays a string so a mode this app does not know yet still decodes.
struct PairingSetting: Decodable, Equatable {
let mode: String
let approver: String
let error: String?
var kind: PairingMode? { PairingMode(rawValue: mode) }
}
enum PairedBy: String {
case code, auto, approved
var label: String {
switch self {
case .auto: "Paired by itself"
case .approved: "Allowed"
case .code: "Paired with a code"
}
}
}
struct BrowserSession: Decodable, Identifiable, Equatable {
/// Absent from a daemon that still knows a browser by its origin alone.
let sessionId: String?
let browser: String?
let origin: String
/// Where its extension came from; absent from a daemon before 0.8, which knew only the unpacked copy.
let source: String?
let extensionVersion: String
let pairedAt: String
let lastSeenAt: String
let connected: Bool
let label: String?
/// Absent from a Bridge before automatic pairing, when every browser paired with a code.
let pairedBy: String?
enum CodingKeys: String, CodingKey {
case sessionId = "id"
case browser, origin, source, extensionVersion, pairedAt, lastSeenAt, connected, label, pairedBy
}
var id: String { sessionId ?? origin }
var extensionId: String { origin.replacingOccurrences(of: #"^[a-z-]+-extension://"#, with: "", options: .regularExpression) }
var name: String? { label ?? browser }
var displayName: String { name ?? "This browser" }
var paired: PairedBy { pairedBy.flatMap(PairedBy.init(rawValue:)) ?? .code }
/// Changes when the same browser pairs again, so a second pairing counts as new.
var pairing: String { "\(id)@\(pairedAt)" }
}
/// A browser waiting for someone to let it in, from `pairRequests`.
struct PairRequest: Decodable, Identifiable, Equatable {
let id: String
let installId: String
let browser: String?
let source: String
let extensionVersion: String
let firstAt: Double
let lastAskAt: Double
/// Minted by the Bridge per request and handed only to approvers, so an answer can prove which request it is for.
let nonce: String
var name: String { browser ?? "A browser" }
var shortId: String { String(installId.prefix(8)) }
var askedAt: Date { Date(timeIntervalSince1970: firstAt / 1000) }
}
/// A browser kept out after an Unpair or a Deny, until someone reconnects it.
struct BlockedBrowser: Decodable, Identifiable, Equatable {
let installId: String
let browser: String?
let origin: String
let at: String
let reason: String
var id: String { installId }
var name: String { browser ?? "A browser" }
var shortId: String { String(installId.prefix(8)) }
var why: String { reason == "denied" ? "Denied" : "Unpaired" }
}
/// A monitor, task or timer that finished while its browser was out of sight, handed over by the Bridge.
/// `kind` and `tone` stay strings so a value this app does not know yet never drops the notice.
struct QueuedNotice: Decodable, Identifiable, Equatable {
let id: String
let kind: String?
let title: String
let body: String
let tone: String?
let browser: String?
}
/// Decodes every element it can and skips the rest, so one malformed entry never costs the others.
struct LossyList<Element: Decodable>: Decodable {
let items: [Element]
private struct Skipped: Decodable {
init(from _: Decoder) {}
}
init(from decoder: Decoder) throws {
var container = try decoder.unkeyedContainer()
var items: [Element] = []
while !container.isAtEnd {
if let item = try? container.decode(Element.self) { items.append(item) } else { _ = try container.decode(Skipped.self) }
}
self.items = items
}
}
enum NoticeWatch {
/// The first Bridge protocol with `notices`, `takeNotices` and `openNotice`; an older Bridge never answers them.
static let protocolVersion = 24
static func supported(by status: BridgeStatus?) -> Bool { (status?.protocolVersion ?? 0) >= protocolVersion }
/// Allowed, and somewhere to appear: with alerts off and Notification Center off a notice shows nowhere.
static func allows(_ status: UNAuthorizationStatus, visible: Bool) -> Bool { (status == .authorized || status == .provisional) && visible }
/// Nil `reported` is a socket that has not been told yet.
static func needsReport(allowed: Bool, reported: Bool?) -> Bool { reported != allowed }
/// A repeat of the same event replaces the notification instead of stacking another.
static func identifier(for notice: String) -> String { "notice:\(notice)" }
}
/// The apps behind each brand a browser reports, every channel of one browser sharing its brand, so a notice
/// click can let the browser it came from take the front.
enum BrowserApps {
static let bundleIds: [String: [String]] = [
"Google Chrome": ["com.google.Chrome", "com.google.Chrome.beta", "com.google.Chrome.dev", "com.google.Chrome.canary"],
"Chromium": ["org.chromium.Chromium"],
"Microsoft Edge": ["com.microsoft.edgemac", "com.microsoft.edgemac.Beta", "com.microsoft.edgemac.Dev", "com.microsoft.edgemac.Canary"],
"Brave": ["com.brave.Browser", "com.brave.Browser.beta", "com.brave.Browser.nightly"],
"Opera": ["com.operasoftware.Opera"],
"Opera GX": ["com.operasoftware.OperaGX"],
"Vivaldi": ["com.vivaldi.Vivaldi"],
"Arc": ["company.thebrowser.Browser"],
"Firefox": ["org.mozilla.firefox", "org.mozilla.firefoxdeveloperedition", "org.mozilla.nightly"],
"Google Chrome for Testing": ["com.google.chrome.for.testing"],
"Zen": ["app.zen-browser.zen"],
"LibreWolf": ["io.gitlab.librewolf-community"],
"Waterfox": ["net.waterfox.waterfox"],
"Floorp": ["one.ablaze.floorp"],
]
static func candidates(for brand: String?) -> [String] {
guard let brand else { return [] }
return bundleIds.first { $0.key.caseInsensitiveCompare(brand) == .orderedSame }?.value ?? []
}
/// The running apps of the brand the notice came from; an unknown brand, or none of its apps running, names none.
static func named(_ brand: String?, among running: Set<String>) -> [String] {
candidates(for: brand).filter(running.contains)
}
/// Those, or every running browser when they are none, since Vivaldi and Arc report no brand of their own:
/// only the browser the notice came from asks to come forward.
static func yielded(for brand: String?, among running: Set<String>) -> [String] {
let named = named(brand, among: running)
return named.isEmpty ? bundleIds.values.flatMap { $0 }.filter(running.contains).sorted() : named
}
}
/// What the Bridge answers an op that only succeeds or fails.
struct Acknowledgement: Decodable {
let ok: Bool
let error: String?
}
struct BridgeRefusal: LocalizedError {
let message: String
var errorDescription: String? { message }
}
/// The pure decisions behind the approval sheet and the notifications, kept apart so they can be tested.
enum PairingWatch {
/// Oldest first, so the sheet shows requests in the order browsers asked.
static func queue(_ requests: [PairRequest]) -> [PairRequest] {
requests.sorted { ($0.firstAt, $0.id) < ($1.firstAt, $1.id) }
}
static func arrived(_ requests: [PairRequest], announced: Set<String>) -> [PairRequest] {
requests.filter { !announced.contains($0.id) }
}
static func gone(_ requests: [PairRequest], previous: [PairRequest]) -> Set<String> {
Set(previous.map(\.id)).subtracting(requests.map(\.id))
}
/// Nil `seen` is the first look at a Bridge: everything already there is old news.
static func pairedByThemselves(_ sessions: [BrowserSession], seen: Set<String>?) -> [BrowserSession] {
guard let seen else { return [] }
return sessions.filter { $0.paired == .auto && !seen.contains($0.pairing) }
}
/// An answer from a notification counts only for a request still waiting, with the nonce the Bridge gave it.
static func answerable(_ id: String, nonce: String, in requests: [PairRequest]) -> PairRequest? {
requests.first { $0.id == id && $0.nonce == nonce && !nonce.isEmpty }
}
}
struct PairingCode: Decodable, Equatable {
let code: String
let expiresAt: Double
var expiry: Date { Date(timeIntervalSince1970: expiresAt / 1000) }
var grouped: String { code.count > 4 ? "\(code.prefix(4))-\(code.dropFirst(4))" : code }
}
struct AgentProblem: Decodable, Equatable {
let code: String
let message: String
let fix: String?
let grantable: Bool?
}
struct RunnerStatus: Decodable, Identifiable, Equatable {
let kind: String
let bin: String
let ready: Bool
let version: String?
let model: String?
let problem: AgentProblem?
var id: String { kind }
}
struct AgentDescriptor: Decodable, Identifiable, Equatable {
let kind: String
let label: String
let vendor: String
let bin: String
let install: String
let docs: String
let models: [String]
var id: String { kind }
var installsWithNpm: Bool { install.hasPrefix("npm ") }
}
struct AgentState: Decodable, Equatable {
let active: String
let runners: [RunnerStatus]
var catalog: [AgentDescriptor]?
}
/// What config.json holds for every surface. The extension's settings page reads and writes the same values.
struct Preferences: Decodable, Equatable {
/// Nil until someone picks one; every paired browser shows Ember until then.
let theme: String?
let guardrails: GuardrailSettings
}
struct GuardrailSettings: Decodable, Equatable {
struct Switch: Decodable, Equatable {
let enabled: Bool
let overridden: Bool
}
struct Unattended: Decodable, Equatable {
let effect: String
let overridden: Bool
}
let rules: [GuardrailRule]
let fence: Switch
let unattended: Unattended
let hosts: [String]
let configPath: String
}
struct GuardrailRule: Decodable, Identifiable, Equatable {
let id: String
let title: String
let reason: String
/// The effect with nothing overridden.
let fallback: String
/// Present only when someone chose one.
let choice: String?
let locked: Bool?
var isLocked: Bool { locked == true }
enum CodingKeys: String, CodingKey {
case choice = "override"
case id, title, reason, fallback, locked
}
}
enum RuleEffect: String, CaseIterable, Identifiable {
case allow, confirm, deny
var id: String { rawValue }
var label: String {
switch self {
case .allow: "Allow"
case .confirm: "Ask"
case .deny: "Block"
}
}
static func label(_ raw: String) -> String { RuleEffect(rawValue: raw)?.label ?? raw.capitalized }
}
/// A daemon answer shaped `{ ok, data }` or `{ ok, error }`, as the whole socket protocol is.
struct Outcome<Value: Decodable>: Decodable {
struct Failure: Decodable, LocalizedError {
let code: String
let message: String
var errorDescription: String? { message }
}
let ok: Bool
let data: Value?
let error: Failure?
func value() throws -> Value {
if ok, let data { return data }
throw error ?? Failure(code: "MALFORMED", message: ControlError.malformed.localizedDescription)
}
}
struct Skill: Decodable, Identifiable, Equatable {
let name: String
let description: String
let triggers: [String]
let isDefault: Bool
let category: String
let domains: [String]
let source: String
let provenance: String
let path: String?
var id: String { "\(source)/\(name)" }
}
struct AgentSkill: Decodable, Identifiable, Equatable {
let name: String
let description: String?
var id: String { name }
}
struct SkillListing: Decodable, Equatable {
let skills: [Skill]
let dirs: [String]
let agent: String
let agentSkills: [AgentSkill]
}
struct Grant: Decodable, Identifiable, Equatable {
let action: String
let host: String
let at: String
var id: String { "\(action)@\(host)" }
}
struct GrantListing: Decodable { let grants: [Grant] }
struct DownloadRecord: Decodable, Identifiable, Equatable {
let id: String
let name: String
let mime: String
let size: Int
let url: String
let host: String?
let notes: String
let savedTo: String
let capturedAt: String
}
struct DownloadListing: Decodable, Equatable {
let dir: String
let downloads: [DownloadRecord]
}
struct SetupResult: Decodable {
struct Daemon: Decodable { let port: Int; let pid: Int }
struct Chosen: Decodable { let id: String; let opened: Bool; let connected: Bool }
let version: String
/// Set only when the unpacked folder was written or was already there.
let extensionDir: String?
let daemon: Daemon
let alreadyPaired: Bool
let chosen: Chosen?
let pairingCode: String?
let expiresAt: Double?
}
/// One browser as `browsentic browsers --json` describes it: where it gets the extension, and the copies it runs.
struct BrowserRow: Decodable, Identifiable, Equatable {
struct Copy: Decodable, Equatable {
let id: String
let source: String?
let extensionVersion: String
let connected: Bool
}
let id: String
let label: String
let installed: Bool
let source: String
let store: String
let storeUrl: String
let steps: [String]
let extensionsPage: String
let connected: Bool
let sessions: [Copy]
var copy: Copy? { sessions.first(where: \.connected) ?? sessions.first }
var addTitle: String { id == "firefox" ? "Get the Firefox add-on" : "Add to \(label)" }
}
struct BrowserListing: Decodable { let browsers: [BrowserRow] }
enum SourceLabel {
static func of(_ source: String?) -> String {
switch source {
case "chrome-web-store": "Chrome Web Store"
case "edge-add-ons": "Edge Add-ons"
case "firefox": "Firefox add-on"
default: "unpacked"
}
}
}
struct InstallStamp: Decodable, Equatable {
let version: String
let installedAt: String
}
enum Timestamp {
private static let parser: ISO8601DateFormatter = {
let formatter = ISO8601DateFormatter()
formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
return formatter
}()
private static let relative: RelativeDateTimeFormatter = {
let formatter = RelativeDateTimeFormatter()
formatter.unitsStyle = .full
return formatter
}()
static func date(_ text: String) -> Date? { parser.date(from: text) }
static func ago(_ text: String, now: Date = Date()) -> String {
guard let date = date(text) else { return text }
return ago(date, now: now)
}
static func ago(_ date: Date, now: Date = Date()) -> String {
if now.timeIntervalSince(date) < 5 { return "just now" }
return relative.localizedString(for: date, relativeTo: now)
}
}
enum Version {
static func isNewer(_ candidate: String, than current: String) -> Bool {
let release: (String) -> [Int] = { version in
version.split(separator: "-")[0].split(separator: ".").map { Int($0) ?? 0 }
}
let a = release(candidate), b = release(current)
for index in 0..<3 {
let left = index < a.count ? a[index] : 0, right = index < b.count ? b[index] : 0
if left != right { return left > right }
}
return false
}
static func major(_ version: String) -> Int {
Int(version.trimmingCharacters(in: CharacterSet(charactersIn: "v \n")).split(separator: ".").first ?? "") ?? 0
}
}
/// `browsentic android --json`, and the control socket's `android` answer without `guide` and `report`. Every field is optional, so an older or newer Bridge still decodes.
struct AndroidState: Decodable, Equatable {
struct Problem: Decodable, Equatable {
let code: String
let message: String
let fix: String?
let action: String?
}
struct Adb: Decodable, Equatable {
let found: Bool?
let path: String?
let version: String?
let problem: Problem?
}
struct Chrome: Decodable, Equatable {
let installed: Bool?
let version: String?
let running: Bool?
let debuggable: Bool?
}
struct Device: Decodable, Identifiable, Equatable {
let serial: String
let transport: String?
let state: String?
let model: String?
let android: String?
let chrome: Chrome?
let problem: Problem?
var id: String { serial }
}
struct Session: Decodable, Equatable {
let serial: String
let since: String?
}
struct GuideStep: Decodable, Equatable, Identifiable {
let title: String
let detail: String
let platform: String?
var id: String { title }
}
/// One row of the checklist the CLI prints, worded once in src/lib/phone/checks.ts for every surface.
struct Check: Decodable, Equatable, Identifiable {
let label: String
let mark: String
let value: String
let fix: String?
let action: String?
let code: String?
var id: String { label }
var failed: Bool { mark == "failed" }
}
struct Section: Decodable, Equatable, Identifiable {
let serial: String?
let checks: [Check]
var id: String { serial ?? checks.first?.label ?? "" }
}
struct Report: Decodable, Equatable {
let sections: [Section]
let ready: Bool?
let guided: Bool?
let summary: String?
}
let enabled: Bool?
let ready: Bool?
let adb: Adb?
let devices: [Device]?
let problem: Problem?
let session: Session?
let guide: [GuideStep]?
let report: Report?
var isReady: Bool { ready == true }
}