fix: improve Perplexity web_search defaults (#1131) (thanks @CMLKevin)

CHANGELOG.md

@@ -2,66 +2,15 @@
 
 Docs: https://docs.clawd.bot
 
-## 2026.1.18-3
-
-### Changes
-- Exec: add host/security/ask routing for gateway + node exec.
-- macOS: migrate exec approvals to `~/.clawdbot/exec-approvals.json` with per-agent allowlists and skill auto-allow toggle.
-- macOS: add approvals socket UI server + node exec lifecycle events.
-- Slash commands: replace `/cost` with `/usage off|tokens|full` to control per-response usage footer; `/usage` no longer aliases `/status`. (Supersedes #1140) — thanks @Nachx639.
-- Docs: refresh exec/elevated/exec-approvals docs for the new flow. https://docs.clawd.bot/tools/exec-approvals
-- CLI: add `clawdbot acp` ACP bridge for IDE integrations.
-
-### Fixes
-- Tools: return a companion-app-required message when node exec is requested with no paired node.
-
-## 2026.1.18-2
-
-### Fixes
-- Tests: stabilize plugin SDK resolution and embedded agent timeouts.
-
-## 2026.1.17-6
-
-### Changes
-- Plugins: add exclusive plugin slots with a dedicated memory slot selector.
-- Memory: ship core memory tools + CLI as the bundled `memory-core` plugin.
-- Docs: document plugin slots and memory plugin behavior.
-- Plugins: add the bundled BlueBubbles channel plugin (disabled by default).
-- Plugins: migrate bundled messaging extensions to the plugin SDK; resolve plugin-sdk imports in loader.
-- Plugins: migrate the Zalo plugin to the shared plugin SDK runtime.
-- Plugins: migrate the Zalo Personal plugin to the shared plugin SDK runtime.
-
-## 2026.1.17-5
-
-### Changes
-- Memory: add hybrid BM25 + vector search (FTS5) with weighted merging and fallback.
-- Memory: add SQLite embedding cache to speed up reindexing and frequent updates.
-- CLI: surface FTS + embedding cache state in `clawdbot memory status`.
-- Memory: render progress immediately, color batch statuses in verbose logs, and poll OpenAI batch status every 2s by default.
-- Plugins: allow optional agent tools with explicit allowlists and add plugin tool authoring guide. https://docs.clawd.bot/plugins/agent-tools
-- Tools: centralize plugin tool policy helpers.
-- Commands: add `/subagents info` and show sub-agent counts in `/status`.
-- Docs: clarify plugin agent tool configuration. https://docs.clawd.bot/plugins/agent-tools
-
-### Fixes
-- Voice call: include request query in Twilio webhook verification when publicUrl is set. (#864)
-
 ## 2026.1.18-1
 
 ### Changes
 - Tools: allow `sessions_spawn` to override thinking level for sub-agent runs.
-- Channels: unify thread/topic allowlist matching + command/mention gating helpers across core providers.
-- Models: add Qwen Portal OAuth provider support. (#1120) — thanks @mukhtharcm.
-- Memory: add `--verbose` logging for memory status + batch indexing details.
-- Memory: allow parallel OpenAI batch indexing jobs (default concurrency: 2).
-- macOS: add per-agent exec approvals with allowlists, skill CLI auto-allow, and settings UI.
-- Docs: add exec approvals guide and link from tools index. https://docs.clawd.bot/tools/exec-approvals
+- Tools: add Perplexity Sonar provider for `web_search` with direct Perplexity/OpenRouter support. (#1131) — thanks @CMLKevin.
 
 ### Fixes
 - Memory: apply OpenAI batch defaults even without explicit remote config.
-- macOS: bundle Textual resources in packaged app builds to avoid code block crashes. (#1006)
-- Tools: return a companion-app-required message when `system.run` is requested without a supporting node.
-- Discord: only emit slow listener warnings after 30s.
+
 ## 2026.1.17-3
 
 ### Changes

README.md

@@ -249,7 +249,7 @@ Send these in WhatsApp/Telegram/Slack/Microsoft Teams/WebChat (group commands ar
 - `/compact` — compact session context (summary)
 - `/think <level>` — off|minimal|low|medium|high|xhigh (GPT-5.2 + Codex models only)
 - `/verbose on|off`
-- `/usage off|tokens|full` — per-response usage footer
+- `/cost on|off` — append per-response token/cost usage lines
 - `/restart` — restart the gateway (owner-only in groups)
 - `/activation mention|always` — group activation toggle (groups only)
 

apps/macos/Sources/Clawdbot/AppState.swift

@@ -170,15 +170,8 @@ final class AppState {
         didSet { self.ifNotPreview { UserDefaults.standard.set(self.canvasEnabled, forKey: canvasEnabledKey) } }
     }
 
-    var execApprovalMode: ExecApprovalQuickMode {
-        didSet {
-            self.ifNotPreview {
-                ExecApprovalsStore.updateDefaults { defaults in
-                    defaults.security = self.execApprovalMode.security
-                    defaults.ask = self.execApprovalMode.ask
-                }
-            }
-        }
+    var systemRunPolicy: SystemRunPolicy {
+        didSet { self.ifNotPreview { MacNodeConfigFile.setSystemRunPolicy(self.systemRunPolicy) } }
     }
 
     /// Tracks whether the Canvas panel is currently visible (not persisted).
@@ -281,8 +274,7 @@ final class AppState {
         self.remoteProjectRoot = UserDefaults.standard.string(forKey: remoteProjectRootKey) ?? ""
         self.remoteCliPath = UserDefaults.standard.string(forKey: remoteCliPathKey) ?? ""
         self.canvasEnabled = UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
-        let execDefaults = ExecApprovalsStore.resolveDefaults()
-        self.execApprovalMode = ExecApprovalQuickMode.from(security: execDefaults.security, ask: execDefaults.ask)
+        self.systemRunPolicy = SystemRunPolicy.load()
         self.peekabooBridgeEnabled = UserDefaults.standard
             .object(forKey: peekabooBridgeEnabledKey) as? Bool ?? true
         if !self.isPreview {

apps/macos/Sources/Clawdbot/CommandResolver.swift

@@ -214,10 +214,9 @@ enum CommandResolver {
         subcommand: String,
         extraArgs: [String] = [],
         defaults: UserDefaults = .standard,
-        configRoot: [String: Any]? = nil,
         searchPaths: [String]? = nil) -> [String]
     {
-        let settings = self.connectionSettings(defaults: defaults, configRoot: configRoot)
+        let settings = self.connectionSettings(defaults: defaults)
         if settings.mode == .remote, let ssh = self.sshNodeCommand(
             subcommand: subcommand,
             extraArgs: extraArgs,
@@ -265,14 +264,12 @@ enum CommandResolver {
         subcommand: String,
         extraArgs: [String] = [],
         defaults: UserDefaults = .standard,
-        configRoot: [String: Any]? = nil,
         searchPaths: [String]? = nil) -> [String]
     {
         self.clawdbotNodeCommand(
             subcommand: subcommand,
             extraArgs: extraArgs,
             defaults: defaults,
-            configRoot: configRoot,
             searchPaths: searchPaths)
     }
 
@@ -387,11 +384,8 @@ enum CommandResolver {
         let cliPath: String
     }
 
-    static func connectionSettings(
-        defaults: UserDefaults = .standard,
-        configRoot: [String: Any]? = nil) -> RemoteSettings
-    {
-        let root = configRoot ?? ClawdbotConfigFile.loadDict()
+    static func connectionSettings(defaults: UserDefaults = .standard) -> RemoteSettings {
+        let root = ClawdbotConfigFile.loadDict()
         let mode = ConnectionModeResolver.resolve(root: root, defaults: defaults).mode
         let target = defaults.string(forKey: remoteTargetKey) ?? ""
         let identity = defaults.string(forKey: remoteIdentityKey) ?? ""

apps/macos/Sources/Clawdbot/ExecApprovals.swift

@@ -1,566 +0,0 @@
-import Foundation
-import OSLog
-import Security
-
-enum ExecSecurity: String, CaseIterable, Codable, Identifiable {
-    case deny
-    case allowlist
-    case full
-
-    var id: String { self.rawValue }
-
-    var title: String {
-        switch self {
-        case .deny: "Deny"
-        case .allowlist: "Allowlist"
-        case .full: "Always Allow"
-        }
-    }
-}
-
-enum ExecApprovalQuickMode: String, CaseIterable, Identifiable {
-    case deny
-    case ask
-    case allow
-
-    var id: String { self.rawValue }
-
-    var title: String {
-        switch self {
-        case .deny: "Deny"
-        case .ask: "Always Ask"
-        case .allow: "Always Allow"
-        }
-    }
-
-    var security: ExecSecurity {
-        switch self {
-        case .deny: .deny
-        case .ask: .allowlist
-        case .allow: .full
-        }
-    }
-
-    var ask: ExecAsk {
-        switch self {
-        case .deny: .off
-        case .ask: .onMiss
-        case .allow: .off
-        }
-    }
-
-    static func from(security: ExecSecurity, ask: ExecAsk) -> ExecApprovalQuickMode {
-        switch security {
-        case .deny:
-            return .deny
-        case .full:
-            return .allow
-        case .allowlist:
-            return .ask
-        }
-    }
-}
-
-enum ExecAsk: String, CaseIterable, Codable, Identifiable {
-    case off
-    case onMiss = "on-miss"
-    case always
-
-    var id: String { self.rawValue }
-
-    var title: String {
-        switch self {
-        case .off: "Never Ask"
-        case .onMiss: "Ask on Allowlist Miss"
-        case .always: "Always Ask"
-        }
-    }
-}
-
-enum ExecApprovalDecision: String, Codable, Sendable {
-    case allowOnce = "allow-once"
-    case allowAlways = "allow-always"
-    case deny
-}
-
-struct ExecAllowlistEntry: Codable, Hashable {
-    var pattern: String
-    var lastUsedAt: Double? = nil
-    var lastUsedCommand: String? = nil
-    var lastResolvedPath: String? = nil
-}
-
-struct ExecApprovalsDefaults: Codable {
-    var security: ExecSecurity?
-    var ask: ExecAsk?
-    var askFallback: ExecSecurity?
-    var autoAllowSkills: Bool?
-}
-
-struct ExecApprovalsAgent: Codable {
-    var security: ExecSecurity?
-    var ask: ExecAsk?
-    var askFallback: ExecSecurity?
-    var autoAllowSkills: Bool?
-    var allowlist: [ExecAllowlistEntry]?
-
-    var isEmpty: Bool {
-        security == nil && ask == nil && askFallback == nil && autoAllowSkills == nil && (allowlist?.isEmpty ?? true)
-    }
-}
-
-struct ExecApprovalsSocketConfig: Codable {
-    var path: String?
-    var token: String?
-}
-
-struct ExecApprovalsFile: Codable {
-    var version: Int
-    var socket: ExecApprovalsSocketConfig?
-    var defaults: ExecApprovalsDefaults?
-    var agents: [String: ExecApprovalsAgent]?
-}
-
-struct ExecApprovalsResolved {
-    let url: URL
-    let socketPath: String
-    let token: String
-    let defaults: ExecApprovalsResolvedDefaults
-    let agent: ExecApprovalsResolvedDefaults
-    let allowlist: [ExecAllowlistEntry]
-    var file: ExecApprovalsFile
-}
-
-struct ExecApprovalsResolvedDefaults {
-    var security: ExecSecurity
-    var ask: ExecAsk
-    var askFallback: ExecSecurity
-    var autoAllowSkills: Bool
-}
-
-enum ExecApprovalsStore {
-    private static let logger = Logger(subsystem: "com.clawdbot", category: "exec-approvals")
-    private static let defaultSecurity: ExecSecurity = .deny
-    private static let defaultAsk: ExecAsk = .onMiss
-    private static let defaultAskFallback: ExecSecurity = .deny
-    private static let defaultAutoAllowSkills = false
-
-    static func fileURL() -> URL {
-        ClawdbotPaths.stateDirURL.appendingPathComponent("exec-approvals.json")
-    }
-
-    static func socketPath() -> String {
-        ClawdbotPaths.stateDirURL.appendingPathComponent("exec-approvals.sock").path
-    }
-
-    static func loadFile() -> ExecApprovalsFile {
-        let url = self.fileURL()
-        guard FileManager.default.fileExists(atPath: url.path) else {
-            return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
-        }
-        do {
-            let data = try Data(contentsOf: url)
-            let decoded = try JSONDecoder().decode(ExecApprovalsFile.self, from: data)
-            if decoded.version != 1 {
-                return ExecApprovalsFile(version: 1, socket: decoded.socket, defaults: decoded.defaults, agents: decoded.agents)
-            }
-            return decoded
-        } catch {
-            self.logger.warning("exec approvals load failed: \(error.localizedDescription, privacy: .public)")
-            return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
-        }
-    }
-
-    static func saveFile(_ file: ExecApprovalsFile) {
-        do {
-            let encoder = JSONEncoder()
-            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-            let data = try encoder.encode(file)
-            let url = self.fileURL()
-            try FileManager.default.createDirectory(
-                at: url.deletingLastPathComponent(),
-                withIntermediateDirectories: true)
-            try data.write(to: url, options: [.atomic])
-            try? FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
-        } catch {
-            self.logger.error("exec approvals save failed: \(error.localizedDescription, privacy: .public)")
-        }
-    }
-
-    static func ensureFile() -> ExecApprovalsFile {
-        var file = self.loadFile()
-        if file.socket == nil { file.socket = ExecApprovalsSocketConfig(path: nil, token: nil) }
-        let path = file.socket?.path?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if path.isEmpty {
-            file.socket?.path = self.socketPath()
-        }
-        let token = file.socket?.token?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if token.isEmpty {
-            file.socket?.token = self.generateToken()
-        }
-        if file.agents == nil { file.agents = [:] }
-        self.saveFile(file)
-        return file
-    }
-
-    static func resolve(agentId: String?) -> ExecApprovalsResolved {
-        var file = self.ensureFile()
-        let defaults = file.defaults ?? ExecApprovalsDefaults()
-        let resolvedDefaults = ExecApprovalsResolvedDefaults(
-            security: defaults.security ?? self.defaultSecurity,
-            ask: defaults.ask ?? self.defaultAsk,
-            askFallback: defaults.askFallback ?? self.defaultAskFallback,
-            autoAllowSkills: defaults.autoAllowSkills ?? self.defaultAutoAllowSkills)
-        let key = (agentId?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false)
-            ? agentId!.trimmingCharacters(in: .whitespacesAndNewlines)
-            : "default"
-        let agentEntry = file.agents?[key] ?? ExecApprovalsAgent()
-        let resolvedAgent = ExecApprovalsResolvedDefaults(
-            security: agentEntry.security ?? resolvedDefaults.security,
-            ask: agentEntry.ask ?? resolvedDefaults.ask,
-            askFallback: agentEntry.askFallback ?? resolvedDefaults.askFallback,
-            autoAllowSkills: agentEntry.autoAllowSkills ?? resolvedDefaults.autoAllowSkills)
-        let allowlist = (agentEntry.allowlist ?? [])
-            .map { entry in
-                ExecAllowlistEntry(
-                    pattern: entry.pattern.trimmingCharacters(in: .whitespacesAndNewlines),
-                    lastUsedAt: entry.lastUsedAt,
-                    lastUsedCommand: entry.lastUsedCommand,
-                    lastResolvedPath: entry.lastResolvedPath)
-            }
-            .filter { !$0.pattern.isEmpty }
-        let socketPath = self.expandPath(file.socket?.path ?? self.socketPath())
-        let token = file.socket?.token ?? ""
-        return ExecApprovalsResolved(
-            url: self.fileURL(),
-            socketPath: socketPath,
-            token: token,
-            defaults: resolvedDefaults,
-            agent: resolvedAgent,
-            allowlist: allowlist,
-            file: file)
-    }
-
-    static func resolveDefaults() -> ExecApprovalsResolvedDefaults {
-        let file = self.ensureFile()
-        let defaults = file.defaults ?? ExecApprovalsDefaults()
-        return ExecApprovalsResolvedDefaults(
-            security: defaults.security ?? self.defaultSecurity,
-            ask: defaults.ask ?? self.defaultAsk,
-            askFallback: defaults.askFallback ?? self.defaultAskFallback,
-            autoAllowSkills: defaults.autoAllowSkills ?? self.defaultAutoAllowSkills)
-    }
-
-    static func saveDefaults(_ defaults: ExecApprovalsDefaults) {
-        self.updateFile { file in
-            file.defaults = defaults
-        }
-    }
-
-    static func updateDefaults(_ mutate: (inout ExecApprovalsDefaults) -> Void) {
-        self.updateFile { file in
-            var defaults = file.defaults ?? ExecApprovalsDefaults()
-            mutate(&defaults)
-            file.defaults = defaults
-        }
-    }
-
-    static func saveAgent(_ agent: ExecApprovalsAgent, agentId: String?) {
-        self.updateFile { file in
-            var agents = file.agents ?? [:]
-            let key = self.agentKey(agentId)
-            if agent.isEmpty {
-                agents.removeValue(forKey: key)
-            } else {
-                agents[key] = agent
-            }
-            file.agents = agents.isEmpty ? nil : agents
-        }
-    }
-
-    static func addAllowlistEntry(agentId: String?, pattern: String) {
-        let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return }
-        self.updateFile { file in
-            let key = self.agentKey(agentId)
-            var agents = file.agents ?? [:]
-            var entry = agents[key] ?? ExecApprovalsAgent()
-            var allowlist = entry.allowlist ?? []
-            if allowlist.contains(where: { $0.pattern == trimmed }) { return }
-            allowlist.append(ExecAllowlistEntry(pattern: trimmed, lastUsedAt: Date().timeIntervalSince1970 * 1000))
-            entry.allowlist = allowlist
-            agents[key] = entry
-            file.agents = agents
-        }
-    }
-
-    static func recordAllowlistUse(
-        agentId: String?,
-        pattern: String,
-        command: String,
-        resolvedPath: String?)
-    {
-        self.updateFile { file in
-            let key = self.agentKey(agentId)
-            var agents = file.agents ?? [:]
-            var entry = agents[key] ?? ExecApprovalsAgent()
-            let allowlist = (entry.allowlist ?? []).map { item -> ExecAllowlistEntry in
-                guard item.pattern == pattern else { return item }
-                return ExecAllowlistEntry(
-                    pattern: item.pattern,
-                    lastUsedAt: Date().timeIntervalSince1970 * 1000,
-                    lastUsedCommand: command,
-                    lastResolvedPath: resolvedPath)
-            }
-            entry.allowlist = allowlist
-            agents[key] = entry
-            file.agents = agents
-        }
-    }
-
-    static func updateAllowlist(agentId: String?, allowlist: [ExecAllowlistEntry]) {
-        self.updateFile { file in
-            let key = self.agentKey(agentId)
-            var agents = file.agents ?? [:]
-            var entry = agents[key] ?? ExecApprovalsAgent()
-            let cleaned = allowlist
-                .map { item in
-                    ExecAllowlistEntry(
-                        pattern: item.pattern.trimmingCharacters(in: .whitespacesAndNewlines),
-                        lastUsedAt: item.lastUsedAt,
-                        lastUsedCommand: item.lastUsedCommand,
-                        lastResolvedPath: item.lastResolvedPath)
-                }
-                .filter { !$0.pattern.isEmpty }
-            entry.allowlist = cleaned
-            agents[key] = entry
-            file.agents = agents
-        }
-    }
-
-    static func updateAgentSettings(agentId: String?, mutate: (inout ExecApprovalsAgent) -> Void) {
-        self.updateFile { file in
-            let key = self.agentKey(agentId)
-            var agents = file.agents ?? [:]
-            var entry = agents[key] ?? ExecApprovalsAgent()
-            mutate(&entry)
-            if entry.isEmpty {
-                agents.removeValue(forKey: key)
-            } else {
-                agents[key] = entry
-            }
-            file.agents = agents.isEmpty ? nil : agents
-        }
-    }
-
-    private static func updateFile(_ mutate: (inout ExecApprovalsFile) -> Void) {
-        var file = self.ensureFile()
-        mutate(&file)
-        self.saveFile(file)
-    }
-
-    private static func generateToken() -> String {
-        var bytes = [UInt8](repeating: 0, count: 24)
-        let status = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
-        if status == errSecSuccess {
-            return Data(bytes)
-                .base64EncodedString()
-                .replacingOccurrences(of: "+", with: "-")
-                .replacingOccurrences(of: "/", with: "_")
-                .replacingOccurrences(of: "=", with: "")
-        }
-        return UUID().uuidString
-    }
-
-    private static func expandPath(_ raw: String) -> String {
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        if trimmed == "~" {
-            return FileManager.default.homeDirectoryForCurrentUser.path
-        }
-        if trimmed.hasPrefix("~/") {
-            let suffix = trimmed.dropFirst(2)
-            return FileManager.default.homeDirectoryForCurrentUser
-                .appendingPathComponent(String(suffix)).path
-        }
-        return trimmed
-    }
-
-    private static func agentKey(_ agentId: String?) -> String {
-        let trimmed = agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        return trimmed.isEmpty ? "default" : trimmed
-    }
-}
-
-struct ExecCommandResolution: Sendable {
-    let rawExecutable: String
-    let resolvedPath: String?
-    let executableName: String
-    let cwd: String?
-
-    static func resolve(command: [String], cwd: String?, env: [String: String]?) -> ExecCommandResolution? {
-        guard let raw = command.first?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
-            return nil
-        }
-        let expanded = raw.hasPrefix("~") ? (raw as NSString).expandingTildeInPath : raw
-        let hasPathSeparator = expanded.contains("/") || expanded.contains("\\")
-        let resolvedPath: String? = {
-            if hasPathSeparator {
-                if expanded.hasPrefix("/") {
-                    return expanded
-                }
-                let base = cwd?.trimmingCharacters(in: .whitespacesAndNewlines)
-                let root = (base?.isEmpty == false) ? base! : FileManager.default.currentDirectoryPath
-                return URL(fileURLWithPath: root).appendingPathComponent(expanded).path
-            }
-            let searchPaths = self.searchPaths(from: env)
-            return CommandResolver.findExecutable(named: expanded, searchPaths: searchPaths)
-        }()
-        let name = resolvedPath.map { URL(fileURLWithPath: $0).lastPathComponent } ?? expanded
-        return ExecCommandResolution(rawExecutable: expanded, resolvedPath: resolvedPath, executableName: name, cwd: cwd)
-    }
-
-    private static func searchPaths(from env: [String: String]?) -> [String] {
-        let raw = env?["PATH"]
-        if let raw, !raw.isEmpty {
-            return raw.split(separator: ":").map(String.init)
-        }
-        return CommandResolver.preferredPaths()
-    }
-}
-
-enum ExecCommandFormatter {
-    static func displayString(for argv: [String]) -> String {
-        argv.map { arg in
-            let trimmed = arg.trimmingCharacters(in: .whitespacesAndNewlines)
-            guard !trimmed.isEmpty else { return "\"\"" }
-            let needsQuotes = trimmed.contains { $0.isWhitespace || $0 == "\"" }
-            if !needsQuotes { return trimmed }
-            let escaped = trimmed.replacingOccurrences(of: "\"", with: "\\\"")
-            return "\"\(escaped)\""
-        }.joined(separator: " ")
-    }
-}
-
-enum ExecAllowlistMatcher {
-    static func match(entries: [ExecAllowlistEntry], resolution: ExecCommandResolution?) -> ExecAllowlistEntry? {
-        guard let resolution, !entries.isEmpty else { return nil }
-        let rawExecutable = resolution.rawExecutable
-        let resolvedPath = resolution.resolvedPath
-        let executableName = resolution.executableName
-
-        for entry in entries {
-            let pattern = entry.pattern.trimmingCharacters(in: .whitespacesAndNewlines)
-            if pattern.isEmpty { continue }
-            let hasPath = pattern.contains("/") || pattern.contains("~") || pattern.contains("\\")
-            if hasPath {
-                let target = resolvedPath ?? rawExecutable
-                if self.matches(pattern: pattern, target: target) { return entry }
-            } else if self.matches(pattern: pattern, target: executableName) {
-                return entry
-            }
-        }
-        return nil
-    }
-
-    private static func matches(pattern: String, target: String) -> Bool {
-        let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return false }
-        let expanded = trimmed.hasPrefix("~") ? (trimmed as NSString).expandingTildeInPath : trimmed
-        let normalizedPattern = self.normalizeMatchTarget(expanded)
-        let normalizedTarget = self.normalizeMatchTarget(target)
-        guard let regex = self.regex(for: normalizedPattern) else { return false }
-        let range = NSRange(location: 0, length: normalizedTarget.utf16.count)
-        return regex.firstMatch(in: normalizedTarget, options: [], range: range) != nil
-    }
-
-    private static func normalizeMatchTarget(_ value: String) -> String {
-        value.replacingOccurrences(of: "\\\\", with: "/").lowercased()
-    }
-
-    private static func regex(for pattern: String) -> NSRegularExpression? {
-        var regex = "^"
-        var idx = pattern.startIndex
-        while idx < pattern.endIndex {
-            let ch = pattern[idx]
-            if ch == "*" {
-                let next = pattern.index(after: idx)
-                if next < pattern.endIndex, pattern[next] == "*" {
-                    regex += ".*"
-                    idx = pattern.index(after: next)
-                } else {
-                    regex += "[^/]*"
-                    idx = next
-                }
-                continue
-            }
-            if ch == "?" {
-                regex += "."
-                idx = pattern.index(after: idx)
-                continue
-            }
-            regex += NSRegularExpression.escapedPattern(for: String(ch))
-            idx = pattern.index(after: idx)
-        }
-        regex += "$"
-        return try? NSRegularExpression(pattern: regex, options: [.caseInsensitive])
-    }
-}
-
-struct ExecEventPayload: Codable, Sendable {
-    var sessionKey: String
-    var runId: String
-    var host: String
-    var command: String?
-    var exitCode: Int?
-    var timedOut: Bool?
-    var success: Bool?
-    var output: String?
-    var reason: String?
-
-    static func truncateOutput(_ raw: String, maxChars: Int = 20_000) -> String? {
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-        if trimmed.count <= maxChars { return trimmed }
-        let suffix = trimmed.suffix(maxChars)
-        return "… (truncated) \(suffix)"
-    }
-}
-
-actor SkillBinsCache {
-    static let shared = SkillBinsCache()
-
-    private var bins: Set<String> = []
-    private var lastRefresh: Date?
-    private let refreshInterval: TimeInterval = 90
-
-    func currentBins(force: Bool = false) async -> Set<String> {
-        if force || self.isStale() {
-            await self.refresh()
-        }
-        return self.bins
-    }
-
-    func refresh() async {
-        do {
-            let report = try await GatewayConnection.shared.skillsStatus()
-            var next = Set<String>()
-            for skill in report.skills {
-                for bin in skill.requirements.bins {
-                    let trimmed = bin.trimmingCharacters(in: .whitespacesAndNewlines)
-                    if !trimmed.isEmpty { next.insert(trimmed) }
-                }
-            }
-            self.bins = next
-            self.lastRefresh = Date()
-        } catch {
-            if self.lastRefresh == nil {
-                self.bins = []
-            }
-        }
-    }
-
-    private func isStale() -> Bool {
-        guard let lastRefresh else { return true }
-        return Date().timeIntervalSince(lastRefresh) > self.refreshInterval
-    }
-}

apps/macos/Sources/Clawdbot/ExecApprovalsSocket.swift

@@ -1,359 +0,0 @@
-import AppKit
-import ClawdbotKit
-import Darwin
-import Foundation
-import OSLog
-
-struct ExecApprovalPromptRequest: Codable, Sendable {
-    var command: String
-    var cwd: String?
-    var host: String?
-    var security: String?
-    var ask: String?
-    var agentId: String?
-    var resolvedPath: String?
-}
-
-private struct ExecApprovalSocketRequest: Codable {
-    var type: String
-    var token: String
-    var id: String
-    var request: ExecApprovalPromptRequest
-}
-
-private struct ExecApprovalSocketDecision: Codable {
-    var type: String
-    var id: String
-    var decision: ExecApprovalDecision
-}
-
-enum ExecApprovalsSocketClient {
-    private struct TimeoutError: LocalizedError {
-        var message: String
-        var errorDescription: String? { message }
-    }
-
-    static func requestDecision(
-        socketPath: String,
-        token: String,
-        request: ExecApprovalPromptRequest,
-        timeoutMs: Int = 15_000) async -> ExecApprovalDecision?
-    {
-        let trimmedPath = socketPath.trimmingCharacters(in: .whitespacesAndNewlines)
-        let trimmedToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmedPath.isEmpty, !trimmedToken.isEmpty else { return nil }
-        do {
-            return try await AsyncTimeout.withTimeoutMs(timeoutMs: timeoutMs, onTimeout: {
-                TimeoutError(message: "exec approvals socket timeout")
-            }, operation: {
-                try await Task.detached {
-                    try self.requestDecisionSync(
-                        socketPath: trimmedPath,
-                        token: trimmedToken,
-                        request: request)
-                }.value
-            })
-        } catch {
-            return nil
-        }
-    }
-
-    private static func requestDecisionSync(
-        socketPath: String,
-        token: String,
-        request: ExecApprovalPromptRequest) throws -> ExecApprovalDecision?
-    {
-        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
-        guard fd >= 0 else {
-            throw NSError(domain: "ExecApprovals", code: 1, userInfo: [
-                NSLocalizedDescriptionKey: "socket create failed",
-            ])
-        }
-
-        var addr = sockaddr_un()
-        addr.sun_family = sa_family_t(AF_UNIX)
-        let maxLen = MemoryLayout.size(ofValue: addr.sun_path)
-        if socketPath.utf8.count >= maxLen {
-            throw NSError(domain: "ExecApprovals", code: 2, userInfo: [
-                NSLocalizedDescriptionKey: "socket path too long",
-            ])
-        }
-        socketPath.withCString { cstr in
-            withUnsafeMutablePointer(to: &addr.sun_path) { ptr in
-                let raw = UnsafeMutableRawPointer(ptr).assumingMemoryBound(to: Int8.self)
-                strncpy(raw, cstr, maxLen - 1)
-            }
-        }
-        let size = socklen_t(MemoryLayout.size(ofValue: addr))
-        let result = withUnsafePointer(to: &addr) { ptr in
-            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
-                connect(fd, rebound, size)
-            }
-        }
-        if result != 0 {
-            throw NSError(domain: "ExecApprovals", code: 3, userInfo: [
-                NSLocalizedDescriptionKey: "socket connect failed",
-            ])
-        }
-
-        let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true)
-
-        let message = ExecApprovalSocketRequest(
-            type: "request",
-            token: token,
-            id: UUID().uuidString,
-            request: request)
-        let data = try JSONEncoder().encode(message)
-        var payload = data
-        payload.append(0x0A)
-        try handle.write(contentsOf: payload)
-
-        guard let line = try self.readLine(from: handle, maxBytes: 256_000),
-              let lineData = line.data(using: .utf8)
-        else { return nil }
-        let response = try JSONDecoder().decode(ExecApprovalSocketDecision.self, from: lineData)
-        return response.decision
-    }
-
-    private static func readLine(from handle: FileHandle, maxBytes: Int) throws -> String? {
-        var buffer = Data()
-        while buffer.count < maxBytes {
-            let chunk = try handle.read(upToCount: 4096) ?? Data()
-            if chunk.isEmpty { break }
-            buffer.append(chunk)
-            if buffer.contains(0x0A) { break }
-        }
-        guard let newlineIndex = buffer.firstIndex(of: 0x0A) else {
-            guard !buffer.isEmpty else { return nil }
-            return String(data: buffer, encoding: .utf8)
-        }
-        let lineData = buffer.subdata(in: 0..<newlineIndex)
-        return String(data: lineData, encoding: .utf8)
-    }
-}
-
-@MainActor
-final class ExecApprovalsPromptServer {
-    static let shared = ExecApprovalsPromptServer()
-
-    private var server: ExecApprovalsSocketServer?
-
-    func start() {
-        guard self.server == nil else { return }
-        let approvals = ExecApprovalsStore.resolve(agentId: nil)
-        let server = ExecApprovalsSocketServer(
-            socketPath: approvals.socketPath,
-            token: approvals.token,
-            onPrompt: { request in
-                await ExecApprovalsPromptPresenter.prompt(request)
-            })
-        server.start()
-        self.server = server
-    }
-
-    func stop() {
-        self.server?.stop()
-        self.server = nil
-    }
-}
-
-private enum ExecApprovalsPromptPresenter {
-    @MainActor
-    static func prompt(_ request: ExecApprovalPromptRequest) -> ExecApprovalDecision {
-        let alert = NSAlert()
-        alert.alertStyle = .warning
-        alert.messageText = "Allow this command?"
-
-        var details = "Clawdbot wants to run:\n\n\(request.command)"
-        let trimmedCwd = request.cwd?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if !trimmedCwd.isEmpty {
-            details += "\n\nWorking directory:\n\(trimmedCwd)"
-        }
-        let trimmedAgent = request.agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if !trimmedAgent.isEmpty {
-            details += "\n\nAgent:\n\(trimmedAgent)"
-        }
-        let trimmedPath = request.resolvedPath?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if !trimmedPath.isEmpty {
-            details += "\n\nExecutable:\n\(trimmedPath)"
-        }
-        let trimmedHost = request.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if !trimmedHost.isEmpty {
-            details += "\n\nHost:\n\(trimmedHost)"
-        }
-        if let security = request.security?.trimmingCharacters(in: .whitespacesAndNewlines), !security.isEmpty {
-            details += "\n\nSecurity:\n\(security)"
-        }
-        if let ask = request.ask?.trimmingCharacters(in: .whitespacesAndNewlines), !ask.isEmpty {
-            details += "\nAsk mode:\n\(ask)"
-        }
-        details += "\n\nThis runs on this machine."
-        alert.informativeText = details
-
-        alert.addButton(withTitle: "Allow Once")
-        alert.addButton(withTitle: "Always Allow")
-        alert.addButton(withTitle: "Don't Allow")
-
-        switch alert.runModal() {
-        case .alertFirstButtonReturn:
-            return .allowOnce
-        case .alertSecondButtonReturn:
-            return .allowAlways
-        default:
-            return .deny
-        }
-    }
-}
-
-private final class ExecApprovalsSocketServer {
-    private let logger = Logger(subsystem: "com.clawdbot", category: "exec-approvals.socket")
-    private let socketPath: String
-    private let token: String
-    private let onPrompt: @Sendable (ExecApprovalPromptRequest) async -> ExecApprovalDecision
-    private var socketFD: Int32 = -1
-    private var acceptTask: Task<Void, Never>?
-    private var isRunning = false
-
-    init(
-        socketPath: String,
-        token: String,
-        onPrompt: @escaping @Sendable (ExecApprovalPromptRequest) async -> ExecApprovalDecision)
-    {
-        self.socketPath = socketPath
-        self.token = token
-        self.onPrompt = onPrompt
-    }
-
-    func start() {
-        guard !self.isRunning else { return }
-        self.isRunning = true
-        self.acceptTask = Task.detached { [weak self] in
-            await self?.runAcceptLoop()
-        }
-    }
-
-    func stop() {
-        self.isRunning = false
-        self.acceptTask?.cancel()
-        self.acceptTask = nil
-        if self.socketFD >= 0 {
-            close(self.socketFD)
-            self.socketFD = -1
-        }
-        if !self.socketPath.isEmpty {
-            unlink(self.socketPath)
-        }
-    }
-
-    private func runAcceptLoop() async {
-        let fd = self.openSocket()
-        guard fd >= 0 else {
-            self.isRunning = false
-            return
-        }
-        self.socketFD = fd
-        while self.isRunning {
-            var addr = sockaddr_un()
-            var len = socklen_t(MemoryLayout.size(ofValue: addr))
-            let client = withUnsafeMutablePointer(to: &addr) { ptr in
-                ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
-                    accept(fd, rebound, &len)
-                }
-            }
-            if client < 0 {
-                if errno == EINTR { continue }
-                break
-            }
-            Task.detached { [weak self] in
-                await self?.handleClient(fd: client)
-            }
-        }
-    }
-
-    private func openSocket() -> Int32 {
-        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
-        guard fd >= 0 else {
-            self.logger.error("exec approvals socket create failed")
-            return -1
-        }
-        unlink(self.socketPath)
-        var addr = sockaddr_un()
-        addr.sun_family = sa_family_t(AF_UNIX)
-        let maxLen = MemoryLayout.size(ofValue: addr.sun_path)
-        if self.socketPath.utf8.count >= maxLen {
-            self.logger.error("exec approvals socket path too long")
-            close(fd)
-            return -1
-        }
-        self.socketPath.withCString { cstr in
-            withUnsafeMutablePointer(to: &addr.sun_path) { ptr in
-                let raw = UnsafeMutableRawPointer(ptr).assumingMemoryBound(to: Int8.self)
-                memset(raw, 0, maxLen)
-                strncpy(raw, cstr, maxLen - 1)
-            }
-        }
-        let size = socklen_t(MemoryLayout.size(ofValue: addr))
-        let result = withUnsafePointer(to: &addr) { ptr in
-            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
-                bind(fd, rebound, size)
-            }
-        }
-        if result != 0 {
-            self.logger.error("exec approvals socket bind failed")
-            close(fd)
-            return -1
-        }
-        if listen(fd, 16) != 0 {
-            self.logger.error("exec approvals socket listen failed")
-            close(fd)
-            return -1
-        }
-        chmod(self.socketPath, 0o600)
-        self.logger.info("exec approvals socket listening at \(self.socketPath, privacy: .public)")
-        return fd
-    }
-
-    private func handleClient(fd: Int32) async {
-        let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true)
-        do {
-            guard let line = try self.readLine(from: handle, maxBytes: 256_000),
-                  let data = line.data(using: .utf8)
-            else {
-                return
-            }
-            let request = try JSONDecoder().decode(ExecApprovalSocketRequest.self, from: data)
-            guard request.type == "request", request.token == self.token else {
-                let response = ExecApprovalSocketDecision(type: "decision", id: request.id, decision: .deny)
-                let data = try JSONEncoder().encode(response)
-                var payload = data
-                payload.append(0x0A)
-                try handle.write(contentsOf: payload)
-                return
-            }
-            let decision = await self.onPrompt(request.request)
-            let response = ExecApprovalSocketDecision(type: "decision", id: request.id, decision: decision)
-            let responseData = try JSONEncoder().encode(response)
-            var payload = responseData
-            payload.append(0x0A)
-            try handle.write(contentsOf: payload)
-        } catch {
-            self.logger.error("exec approvals socket handling failed: \(error.localizedDescription, privacy: .public)")
-        }
-    }
-
-    private func readLine(from handle: FileHandle, maxBytes: Int) throws -> String? {
-        var buffer = Data()
-        while buffer.count < maxBytes {
-            let chunk = try handle.read(upToCount: 4096) ?? Data()
-            if chunk.isEmpty { break }
-            buffer.append(chunk)
-            if buffer.contains(0x0A) { break }
-        }
-        guard let newlineIndex = buffer.firstIndex(of: 0x0A) else {
-            guard !buffer.isEmpty else { return nil }
-            return String(data: buffer, encoding: .utf8)
-        }
-        let lineData = buffer.subdata(in: 0..<newlineIndex)
-        return String(data: lineData, encoding: .utf8)
-    }
-}

apps/macos/Sources/Clawdbot/GatewayEnvironment.swift

@@ -27,11 +27,7 @@ struct Semver: Comparable, CustomStringConvertible, Sendable {
         else { return nil }
         // Strip prerelease suffix (e.g., "11-4" → "11", "5-beta.1" → "5")
         let patchRaw = String(parts[2])
-        guard let patchToken = patchRaw.split(whereSeparator: { $0 == "-" || $0 == "+" }).first,
-              let patchNumeric = Int(patchToken)
-        else {
-            return nil
-        }
+        let patchNumeric = patchRaw.split { $0 == "-" || $0 == "+" }.first.flatMap { Int($0) } ?? 0
         return Semver(major: major, minor: minor, patch: patchNumeric)
     }
 

apps/macos/Sources/Clawdbot/GeneralSettings.swift

@@ -83,7 +83,27 @@ struct GeneralSettings: View {
                         subtitle: "Allow the agent to capture a photo or short video via the built-in camera.",
                         binding: self.$cameraEnabled)
 
-                    SystemRunSettingsView()
+                    VStack(alignment: .leading, spacing: 6) {
+                        Text("Node Run Commands")
+                            .font(.body)
+
+                        Picker("", selection: self.$state.systemRunPolicy) {
+                            ForEach(SystemRunPolicy.allCases) { policy in
+                                Text(policy.title).tag(policy)
+                            }
+                        }
+                        .labelsHidden()
+                        .pickerStyle(.menu)
+
+                        Text("""
+                        Controls remote command execution on this Mac when it is paired as a node. \
+                        "Always Ask" prompts on each command; "Always Allow" runs without prompts; \
+                        "Never" disables `system.run`.
+                        """)
+                        .font(.footnote)
+                        .foregroundStyle(.tertiary)
+                        .fixedSize(horizontal: false, vertical: true)
+                    }
 
                     VStack(alignment: .leading, spacing: 6) {
                         Text("Location Access")

apps/macos/Sources/Clawdbot/MacNodeConfigFile.swift

@@ -0,0 +1,81 @@
+import Foundation
+import OSLog
+
+enum MacNodeConfigFile {
+    private static let logger = Logger(subsystem: "com.clawdbot", category: "mac-node-config")
+
+    static func url() -> URL {
+        ClawdbotPaths.stateDirURL.appendingPathComponent("macos-node.json")
+    }
+
+    static func loadDict() -> [String: Any] {
+        let url = self.url()
+        guard FileManager.default.fileExists(atPath: url.path) else { return [:] }
+        do {
+            let data = try Data(contentsOf: url)
+            guard let root = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+                self.logger.warning("mac node config JSON root invalid")
+                return [:]
+            }
+            return root
+        } catch {
+            self.logger.warning("mac node config read failed: \(error.localizedDescription, privacy: .public)")
+            return [:]
+        }
+    }
+
+    static func saveDict(_ dict: [String: Any]) {
+        do {
+            let data = try JSONSerialization.data(withJSONObject: dict, options: [.prettyPrinted, .sortedKeys])
+            let url = self.url()
+            try FileManager.default.createDirectory(
+                at: url.deletingLastPathComponent(),
+                withIntermediateDirectories: true)
+            try data.write(to: url, options: [.atomic])
+            try? FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
+        } catch {
+            self.logger.error("mac node config save failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    static func systemRunPolicy() -> SystemRunPolicy? {
+        let root = self.loadDict()
+        let systemRun = root["systemRun"] as? [String: Any]
+        let raw = systemRun?["policy"] as? String
+        guard let raw, let policy = SystemRunPolicy(rawValue: raw) else { return nil }
+        return policy
+    }
+
+    static func setSystemRunPolicy(_ policy: SystemRunPolicy) {
+        var root = self.loadDict()
+        var systemRun = root["systemRun"] as? [String: Any] ?? [:]
+        systemRun["policy"] = policy.rawValue
+        root["systemRun"] = systemRun
+        self.saveDict(root)
+    }
+
+    static func systemRunAllowlist() -> [String]? {
+        let root = self.loadDict()
+        let systemRun = root["systemRun"] as? [String: Any]
+        return systemRun?["allowlist"] as? [String]
+    }
+
+    static func setSystemRunAllowlist(_ allowlist: [String]) {
+        let cleaned = allowlist
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        var root = self.loadDict()
+        var systemRun = root["systemRun"] as? [String: Any] ?? [:]
+        if cleaned.isEmpty {
+            systemRun.removeValue(forKey: "allowlist")
+        } else {
+            systemRun["allowlist"] = cleaned
+        }
+        if systemRun.isEmpty {
+            root.removeValue(forKey: "systemRun")
+        } else {
+            root["systemRun"] = systemRun
+        }
+        self.saveDict(root)
+    }
+}

apps/macos/Sources/Clawdbot/MenuBar.swift

@@ -256,7 +256,6 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         }
         TerminationSignalWatcher.shared.start()
         NodePairingApprovalPrompter.shared.start()
-        ExecApprovalsPromptServer.shared.start()
         MacNodeModeCoordinator.shared.start()
         VoiceWakeGlobalSettingsSync.shared.start()
         Task { PresenceReporter.shared.start() }
@@ -281,7 +280,6 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
     func applicationWillTerminate(_ notification: Notification) {
         PresenceReporter.shared.stop()
         NodePairingApprovalPrompter.shared.stop()
-        ExecApprovalsPromptServer.shared.stop()
         MacNodeModeCoordinator.shared.stop()
         TerminationSignalWatcher.shared.stop()
         VoiceWakeGlobalSettingsSync.shared.stop()

apps/macos/Sources/Clawdbot/MenuContentView.swift

@@ -31,10 +31,10 @@ struct MenuContent: View {
         self._updateStatus = Bindable(wrappedValue: updater?.updateStatus ?? UpdateStatus.disabled)
     }
 
-    private var execApprovalModeBinding: Binding<ExecApprovalQuickMode> {
+    private var systemRunPolicyBinding: Binding<SystemRunPolicy> {
         Binding(
-            get: { self.state.execApprovalMode },
-            set: { self.state.execApprovalMode = $0 })
+            get: { self.state.systemRunPolicy },
+            set: { self.state.systemRunPolicy = $0 })
     }
 
     var body: some View {
@@ -74,12 +74,12 @@ struct MenuContent: View {
             Toggle(isOn: self.$cameraEnabled) {
                 Label("Allow Camera", systemImage: "camera")
             }
-            Picker(selection: self.execApprovalModeBinding) {
-                ForEach(ExecApprovalQuickMode.allCases) { mode in
-                    Text(mode.title).tag(mode)
+            Picker(selection: self.systemRunPolicyBinding) {
+                ForEach(SystemRunPolicy.allCases) { policy in
+                    Text(policy.title).tag(policy)
                 }
             } label: {
-                Label("Exec Approvals", systemImage: "terminal")
+                Label("Node Run Commands", systemImage: "terminal")
             }
             Toggle(isOn: Binding(get: { self.state.canvasEnabled }, set: { self.state.canvasEnabled = $0 })) {
                 Label("Allow Canvas", systemImage: "rectangle.and.pencil.and.ellipsis")

apps/macos/Sources/Clawdbot/NodeMode/MacNodeModeCoordinator.swift

@@ -43,6 +43,7 @@ final class MacNodeModeCoordinator {
     private func run() async {
         var retryDelay: UInt64 = 1_000_000_000
         var lastCameraEnabled: Bool?
+        var lastSystemRunPolicy: SystemRunPolicy?
         let defaults = UserDefaults.standard
         while !Task.isCancelled {
             if await MainActor.run(body: { AppStateStore.shared.isPaused }) {
@@ -59,6 +60,15 @@ final class MacNodeModeCoordinator {
                 try? await Task.sleep(nanoseconds: 200_000_000)
             }
 
+            let systemRunPolicy = SystemRunPolicy.load()
+            if lastSystemRunPolicy == nil {
+                lastSystemRunPolicy = systemRunPolicy
+            } else if lastSystemRunPolicy != systemRunPolicy {
+                lastSystemRunPolicy = systemRunPolicy
+                await self.session.disconnect()
+                try? await Task.sleep(nanoseconds: 200_000_000)
+            }
+
             guard let target = await self.resolveBridgeEndpoint(timeoutSeconds: 5) else {
                 try? await Task.sleep(nanoseconds: min(retryDelay, 5_000_000_000))
                 retryDelay = min(retryDelay * 2, 10_000_000_000)
@@ -79,13 +89,8 @@ final class MacNodeModeCoordinator {
                         if let mainSessionKey {
                             await self?.runtime.updateMainSessionKey(mainSessionKey)
                         }
-                        await self?.runtime.setEventSender { [weak self] event, payload in
-                            guard let self else { return }
-                            try? await self.session.sendEvent(event: event, payloadJSON: payload)
-                        }
                     },
-                    onDisconnected: { [weak self] reason in
-                        await self?.runtime.setEventSender(nil)
+                    onDisconnected: { reason in
                         await MacNodeModeCoordinator.handleBridgeDisconnect(reason: reason)
                     },
                     onInvoke: { [weak self] req in
@@ -156,10 +161,13 @@ final class MacNodeModeCoordinator {
             ClawdbotCanvasA2UICommand.reset.rawValue,
             MacNodeScreenCommand.record.rawValue,
             ClawdbotSystemCommand.notify.rawValue,
-            ClawdbotSystemCommand.which.rawValue,
-            ClawdbotSystemCommand.run.rawValue,
         ]
 
+        if SystemRunPolicy.load() != .never {
+            commands.append(ClawdbotSystemCommand.which.rawValue)
+            commands.append(ClawdbotSystemCommand.run.rawValue)
+        }
+
         let capsSet = Set(caps)
         if capsSet.contains(ClawdbotCapability.camera.rawValue) {
             commands.append(ClawdbotCameraCommand.list.rawValue)

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift

@@ -8,7 +8,6 @@ actor MacNodeRuntime {
     private let makeMainActorServices: () async -> any MacNodeRuntimeMainActorServices
     private var cachedMainActorServices: (any MacNodeRuntimeMainActorServices)?
     private var mainSessionKey: String = "main"
-    private var eventSender: (@Sendable (String, String?) async -> Void)?
 
     init(
         makeMainActorServices: @escaping () async -> any MacNodeRuntimeMainActorServices = {
@@ -24,10 +23,6 @@ actor MacNodeRuntime {
         self.mainSessionKey = trimmed
     }
 
-    func setEventSender(_ sender: (@Sendable (String, String?) async -> Void)?) {
-        self.eventSender = sender
-    }
-
     func handleInvoke(_ req: BridgeInvokeRequest) async -> BridgeInvokeResponse {
         let command = req.command
         if self.isCanvasCommand(command), !Self.canvasEnabled() {
@@ -433,129 +428,41 @@ actor MacNodeRuntime {
             return Self.errorResponse(req, code: .invalidRequest, message: "INVALID_REQUEST: command required")
         }
 
-        let trimmedAgent = params.agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        let agentId = trimmedAgent.isEmpty ? nil : trimmedAgent
-        let approvals = ExecApprovalsStore.resolve(agentId: agentId)
-        let security = approvals.agent.security
-        let ask = approvals.agent.ask
-        let askFallback = approvals.agent.askFallback
-        let autoAllowSkills = approvals.agent.autoAllowSkills
-        let sessionKey = (params.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false)
-            ? params.sessionKey!.trimmingCharacters(in: .whitespacesAndNewlines)
-            : self.mainSessionKey
-        let runId = UUID().uuidString
-        let resolution = ExecCommandResolution.resolve(command: command, cwd: params.cwd, env: params.env)
-        let allowlistMatch = security == .allowlist
-            ? ExecAllowlistMatcher.match(entries: approvals.allowlist, resolution: resolution)
-            : nil
-        let skillAllow: Bool
-        if autoAllowSkills, let name = resolution?.executableName {
-            let bins = await SkillBinsCache.shared.currentBins()
-            skillAllow = bins.contains(name)
-        } else {
-            skillAllow = false
-        }
-
-        if security == .deny {
-            await self.emitExecEvent(
-                "exec.denied",
-                payload: ExecEventPayload(
-                    sessionKey: sessionKey,
-                    runId: runId,
-                    host: "node",
-                    command: ExecCommandFormatter.displayString(for: command),
-                    reason: "security=deny"))
+        let wasAllowlisted = SystemRunAllowlist.contains(command)
+        switch Self.systemRunPolicy() {
+        case .never:
             return Self.errorResponse(
                 req,
                 code: .unavailable,
-                message: "SYSTEM_RUN_DISABLED: security=deny")
-        }
-
-        let requiresAsk: Bool = {
-            if ask == .always { return true }
-            if ask == .onMiss && security == .allowlist && allowlistMatch == nil && !skillAllow { return true }
-            return false
-        }()
-
-        if requiresAsk {
-            let decision = await ExecApprovalsSocketClient.requestDecision(
-                socketPath: approvals.socketPath,
-                token: approvals.token,
-                request: ExecApprovalPromptRequest(
-                    command: ExecCommandFormatter.displayString(for: command),
-                    cwd: params.cwd,
-                    host: "node",
-                    security: security.rawValue,
-                    ask: ask.rawValue,
-                    agentId: agentId,
-                    resolvedPath: resolution?.resolvedPath))
-
-            switch decision {
-            case .deny?:
-                await self.emitExecEvent(
-                    "exec.denied",
-                    payload: ExecEventPayload(
-                        sessionKey: sessionKey,
-                        runId: runId,
-                        host: "node",
-                        command: ExecCommandFormatter.displayString(for: command),
-                        reason: "user-denied"))
-                return Self.errorResponse(
-                    req,
-                    code: .unavailable,
-                    message: "SYSTEM_RUN_DENIED: user denied")
-            case nil:
-                if askFallback == .deny || (askFallback == .allowlist && allowlistMatch == nil && !skillAllow) {
-                    await self.emitExecEvent(
-                        "exec.denied",
-                        payload: ExecEventPayload(
-                            sessionKey: sessionKey,
-                            runId: runId,
-                            host: "node",
-                            command: ExecCommandFormatter.displayString(for: command),
-                            reason: "approval-required"))
+                message: "SYSTEM_RUN_DISABLED: policy=never")
+        case .always:
+            break
+        case .ask:
+            if !wasAllowlisted {
+                let services = await self.mainActorServices()
+                let decision = await services.confirmSystemRun(
+                    command: SystemRunAllowlist.displayString(for: command),
+                    cwd: params.cwd)
+                switch decision {
+                case .allowOnce:
+                    break
+                case .allowAlways:
+                    SystemRunAllowlist.add(command)
+                case .deny:
                     return Self.errorResponse(
                         req,
                         code: .unavailable,
-                        message: "SYSTEM_RUN_DENIED: approval required")
+                        message: "SYSTEM_RUN_DENIED: user denied")
                 }
-            case .allowAlways?:
-                if security == .allowlist {
-                    let pattern = resolution?.resolvedPath ??
-                        resolution?.rawExecutable ??
-                        command.first?.trimmingCharacters(in: .whitespacesAndNewlines) ??
-                        ""
-                    if !pattern.isEmpty {
-                        ExecApprovalsStore.addAllowlistEntry(agentId: agentId, pattern: pattern)
-                    }
-                }
-            case .allowOnce?:
-                break
             }
         }
 
-        if let match = allowlistMatch {
-            ExecApprovalsStore.recordAllowlistUse(
-                agentId: agentId,
-                pattern: match.pattern,
-                command: ExecCommandFormatter.displayString(for: command),
-                resolvedPath: resolution?.resolvedPath)
-        }
-
         let env = Self.sanitizedEnv(params.env)
 
         if params.needsScreenRecording == true {
             let authorized = await PermissionManager
                 .status([.screenRecording])[.screenRecording] ?? false
             if !authorized {
-                await self.emitExecEvent(
-                    "exec.denied",
-                    payload: ExecEventPayload(
-                        sessionKey: sessionKey,
-                        runId: runId,
-                        host: "node",
-                        command: ExecCommandFormatter.displayString(for: command),
-                        reason: "permission:screenRecording"))
                 return Self.errorResponse(
                     req,
                     code: .unavailable,
@@ -564,30 +471,11 @@ actor MacNodeRuntime {
         }
 
         let timeoutSec = params.timeoutMs.flatMap { Double($0) / 1000.0 }
-        await self.emitExecEvent(
-            "exec.started",
-            payload: ExecEventPayload(
-                sessionKey: sessionKey,
-                runId: runId,
-                host: "node",
-                command: ExecCommandFormatter.displayString(for: command)))
         let result = await ShellExecutor.runDetailed(
             command: command,
             cwd: params.cwd,
             env: env,
             timeout: timeoutSec)
-        let combined = [result.stdout, result.stderr, result.errorMessage].filter { !$0.isEmpty }.joined(separator: "\n")
-        await self.emitExecEvent(
-            "exec.finished",
-            payload: ExecEventPayload(
-                sessionKey: sessionKey,
-                runId: runId,
-                host: "node",
-                command: ExecCommandFormatter.displayString(for: command),
-                exitCode: result.exitCode,
-                timedOut: result.timedOut,
-                success: result.success,
-                output: ExecEventPayload.truncateOutput(combined)))
 
         struct RunPayload: Encodable {
             var exitCode: Int?
@@ -635,16 +523,6 @@ actor MacNodeRuntime {
         return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
     }
 
-    private func emitExecEvent(_ event: String, payload: ExecEventPayload) async {
-        guard let sender = self.eventSender else { return }
-        guard let data = try? JSONEncoder().encode(payload),
-              let json = String(data: data, encoding: .utf8)
-        else {
-            return
-        }
-        await sender(event, json)
-    }
-
     private func handleSystemNotify(_ req: BridgeInvokeRequest) async throws -> BridgeInvokeResponse {
         let params = try Self.decodeParams(ClawdbotSystemNotifyParams.self, from: req.paramsJSON)
         let title = params.title.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -711,6 +589,10 @@ actor MacNodeRuntime {
         UserDefaults.standard.object(forKey: cameraEnabledKey) as? Bool ?? false
     }
 
+    private nonisolated static func systemRunPolicy() -> SystemRunPolicy {
+        SystemRunPolicy.load()
+    }
+
     private static let blockedEnvKeys: Set<String> = [
         "PATH",
         "NODE_OPTIONS",

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntimeMainActorServices.swift

@@ -1,7 +1,14 @@
+import AppKit
 import ClawdbotKit
 import CoreLocation
 import Foundation
 
+enum SystemRunDecision: Sendable {
+    case allowOnce
+    case allowAlways
+    case deny
+}
+
 @MainActor
 protocol MacNodeRuntimeMainActorServices: Sendable {
     func recordScreen(
@@ -17,6 +24,8 @@ protocol MacNodeRuntimeMainActorServices: Sendable {
         desiredAccuracy: ClawdbotLocationAccuracy,
         maxAgeMs: Int?,
         timeoutMs: Int?) async throws -> CLLocation
+
+    func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision
 }
 
 @MainActor
@@ -58,4 +67,30 @@ final class LiveMacNodeRuntimeMainActorServices: MacNodeRuntimeMainActorServices
             timeoutMs: timeoutMs)
     }
 
+    func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision {
+        let alert = NSAlert()
+        alert.alertStyle = .warning
+        alert.messageText = "Allow this command?"
+
+        var details = "Clawdbot wants to run:\n\n\(command)"
+        let trimmedCwd = cwd?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedCwd.isEmpty {
+            details += "\n\nWorking directory:\n\(trimmedCwd)"
+        }
+        details += "\n\nThis runs on this Mac via node mode."
+        alert.informativeText = details
+
+        alert.addButton(withTitle: "Allow Once")
+        alert.addButton(withTitle: "Always Allow")
+        alert.addButton(withTitle: "Don't Allow")
+
+        switch alert.runModal() {
+        case .alertFirstButtonReturn:
+            return .allowOnce
+        case .alertSecondButtonReturn:
+            return .allowAlways
+        default:
+            return .deny
+        }
+    }
 }

apps/macos/Sources/Clawdbot/SystemRunPolicy.swift

@@ -0,0 +1,89 @@
+import Foundation
+
+enum SystemRunPolicy: String, CaseIterable, Identifiable {
+    case never
+    case ask
+    case always
+
+    var id: String { self.rawValue }
+
+    var title: String {
+        switch self {
+        case .never:
+            "Never"
+        case .ask:
+            "Always Ask"
+        case .always:
+            "Always Allow"
+        }
+    }
+
+    static func load(from defaults: UserDefaults = .standard) -> SystemRunPolicy {
+        if let policy = MacNodeConfigFile.systemRunPolicy() {
+            return policy
+        }
+        if let raw = defaults.string(forKey: systemRunPolicyKey),
+           let policy = SystemRunPolicy(rawValue: raw)
+        {
+            MacNodeConfigFile.setSystemRunPolicy(policy)
+            return policy
+        }
+        if let legacy = defaults.object(forKey: systemRunEnabledKey) as? Bool {
+            let policy: SystemRunPolicy = legacy ? .ask : .never
+            MacNodeConfigFile.setSystemRunPolicy(policy)
+            return policy
+        }
+        let fallback: SystemRunPolicy = .ask
+        MacNodeConfigFile.setSystemRunPolicy(fallback)
+        return fallback
+    }
+}
+
+enum SystemRunAllowlist {
+    static func key(for argv: [String]) -> String {
+        let trimmed = argv.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        guard !trimmed.isEmpty else { return "" }
+        if let data = try? JSONEncoder().encode(trimmed),
+           let json = String(data: data, encoding: .utf8)
+        {
+            return json
+        }
+        return trimmed.joined(separator: " ")
+    }
+
+    static func displayString(for argv: [String]) -> String {
+        argv.map { arg in
+            let trimmed = arg.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return "\"\"" }
+            let needsQuotes = trimmed.contains { $0.isWhitespace || $0 == "\"" }
+            if !needsQuotes { return trimmed }
+            let escaped = trimmed.replacingOccurrences(of: "\"", with: "\\\"")
+            return "\"\(escaped)\""
+        }.joined(separator: " ")
+    }
+
+    static func load(from defaults: UserDefaults = .standard) -> Set<String> {
+        if let allowlist = MacNodeConfigFile.systemRunAllowlist() {
+            return Set(allowlist)
+        }
+        if let legacy = defaults.stringArray(forKey: systemRunAllowlistKey), !legacy.isEmpty {
+            MacNodeConfigFile.setSystemRunAllowlist(legacy)
+            return Set(legacy)
+        }
+        return []
+    }
+
+    static func contains(_ argv: [String], defaults: UserDefaults = .standard) -> Bool {
+        let key = key(for: argv)
+        return self.load(from: defaults).contains(key)
+    }
+
+    static func add(_ argv: [String], defaults: UserDefaults = .standard) {
+        let key = key(for: argv)
+        guard !key.isEmpty else { return }
+        var allowlist = self.load(from: defaults)
+        if allowlist.insert(key).inserted {
+            MacNodeConfigFile.setSystemRunAllowlist(Array(allowlist).sorted())
+        }
+    }
+}

apps/macos/Sources/Clawdbot/SystemRunSettingsView.swift

@@ -1,330 +0,0 @@
-import Foundation
-import Observation
-import SwiftUI
-
-struct SystemRunSettingsView: View {
-    @State private var model = ExecApprovalsSettingsModel()
-    @State private var tab: ExecApprovalsSettingsTab = .policy
-    @State private var newPattern: String = ""
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 8) {
-            HStack(alignment: .center, spacing: 12) {
-                Text("Exec approvals")
-                    .font(.body)
-                Spacer(minLength: 0)
-                if self.model.agentIds.count > 1 {
-                    Picker("Agent", selection: Binding(
-                        get: { self.model.selectedAgentId },
-                        set: { self.model.selectAgent($0) }))
-                    {
-                        ForEach(self.model.agentIds, id: \.self) { id in
-                            Text(id).tag(id)
-                        }
-                    }
-                    .pickerStyle(.menu)
-                    .frame(width: 160, alignment: .trailing)
-                }
-            }
-
-            Picker("", selection: self.$tab) {
-                ForEach(ExecApprovalsSettingsTab.allCases) { tab in
-                    Text(tab.title).tag(tab)
-                }
-            }
-            .pickerStyle(.segmented)
-            .frame(width: 320)
-
-            if self.tab == .policy {
-                self.policyView
-            } else {
-                self.allowlistView
-            }
-        }
-        .task { await self.model.refresh() }
-        .onChange(of: self.tab) { _, _ in
-            Task { await self.model.refreshSkillBins() }
-        }
-    }
-
-    private var policyView: some View {
-        VStack(alignment: .leading, spacing: 8) {
-            Picker("", selection: Binding(
-                get: { self.model.security },
-                set: { self.model.setSecurity($0) }))
-            {
-                ForEach(ExecSecurity.allCases) { security in
-                    Text(security.title).tag(security)
-                }
-            }
-            .labelsHidden()
-            .pickerStyle(.menu)
-
-            Picker("", selection: Binding(
-                get: { self.model.ask },
-                set: { self.model.setAsk($0) }))
-            {
-                ForEach(ExecAsk.allCases) { ask in
-                    Text(ask.title).tag(ask)
-                }
-            }
-            .labelsHidden()
-            .pickerStyle(.menu)
-
-            Picker("", selection: Binding(
-                get: { self.model.askFallback },
-                set: { self.model.setAskFallback($0) }))
-            {
-                ForEach(ExecSecurity.allCases) { mode in
-                    Text("Fallback: \(mode.title)").tag(mode)
-                }
-            }
-            .labelsHidden()
-            .pickerStyle(.menu)
-
-            Text("Security controls whether system.run can execute on this Mac when paired as a node. Ask controls prompt behavior; fallback is used when no companion UI is reachable.")
-                .font(.footnote)
-                .foregroundStyle(.tertiary)
-                .fixedSize(horizontal: false, vertical: true)
-        }
-    }
-
-    private var allowlistView: some View {
-        VStack(alignment: .leading, spacing: 10) {
-            Toggle("Auto-allow skill CLIs", isOn: Binding(
-                get: { self.model.autoAllowSkills },
-                set: { self.model.setAutoAllowSkills($0) }))
-
-            if self.model.autoAllowSkills, !self.model.skillBins.isEmpty {
-                Text("Skill CLIs: \(self.model.skillBins.joined(separator: ", "))")
-                    .font(.footnote)
-                    .foregroundStyle(.secondary)
-            }
-
-            HStack(spacing: 8) {
-                TextField("Add allowlist pattern (case-insensitive globs)", text: self.$newPattern)
-                    .textFieldStyle(.roundedBorder)
-                Button("Add") {
-                    let pattern = self.newPattern.trimmingCharacters(in: .whitespacesAndNewlines)
-                    guard !pattern.isEmpty else { return }
-                    self.model.addEntry(pattern)
-                    self.newPattern = ""
-                }
-                .buttonStyle(.bordered)
-                .disabled(self.newPattern.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
-            }
-
-            if self.model.entries.isEmpty {
-                Text("No allowlisted commands yet.")
-                    .font(.footnote)
-                    .foregroundStyle(.secondary)
-            } else {
-                VStack(alignment: .leading, spacing: 8) {
-                    ForEach(Array(self.model.entries.enumerated()), id: \.offset) { index, _ in
-                        ExecAllowlistRow(
-                            entry: Binding(
-                                get: { self.model.entries[index] },
-                                set: { self.model.updateEntry($0, at: index) }),
-                            onRemove: { self.model.removeEntry(at: index) })
-                    }
-                }
-            }
-        }
-    }
-}
-
-private enum ExecApprovalsSettingsTab: String, CaseIterable, Identifiable {
-    case policy
-    case allowlist
-
-    var id: String { self.rawValue }
-
-    var title: String {
-        switch self {
-        case .policy: "Access"
-        case .allowlist: "Allowlist"
-        }
-    }
-}
-
-struct ExecAllowlistRow: View {
-    @Binding var entry: ExecAllowlistEntry
-    let onRemove: () -> Void
-    @State private var draftPattern: String = ""
-
-    private static let relativeFormatter: RelativeDateTimeFormatter = {
-        let formatter = RelativeDateTimeFormatter()
-        formatter.unitsStyle = .short
-        return formatter
-    }()
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 4) {
-            HStack(spacing: 8) {
-                TextField("Pattern", text: self.patternBinding)
-                    .textFieldStyle(.roundedBorder)
-
-                Button(role: .destructive) {
-                    self.onRemove()
-                } label: {
-                    Image(systemName: "trash")
-                }
-                .buttonStyle(.borderless)
-            }
-
-            if let lastUsedAt = self.entry.lastUsedAt {
-                let date = Date(timeIntervalSince1970: lastUsedAt / 1000.0)
-                Text("Last used \(Self.relativeFormatter.localizedString(for: date, relativeTo: Date()))")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            } else if let lastUsedCommand = self.entry.lastUsedCommand, !lastUsedCommand.isEmpty {
-                Text("Last used: \(lastUsedCommand)")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
-        }
-        .onAppear {
-            self.draftPattern = self.entry.pattern
-        }
-    }
-
-    private var patternBinding: Binding<String> {
-        Binding(
-            get: { self.draftPattern.isEmpty ? self.entry.pattern : self.draftPattern },
-            set: { newValue in
-                self.draftPattern = newValue
-                self.entry.pattern = newValue
-            })
-    }
-}
-
-@MainActor
-@Observable
-final class ExecApprovalsSettingsModel {
-    var agentIds: [String] = []
-    var selectedAgentId: String = "main"
-    var defaultAgentId: String = "main"
-    var security: ExecSecurity = .deny
-    var ask: ExecAsk = .onMiss
-    var askFallback: ExecSecurity = .deny
-    var autoAllowSkills = false
-    var entries: [ExecAllowlistEntry] = []
-    var skillBins: [String] = []
-
-    func refresh() async {
-        await self.refreshAgents()
-        self.loadSettings(for: self.selectedAgentId)
-        await self.refreshSkillBins()
-    }
-
-    func refreshAgents() async {
-        let root = await ConfigStore.load()
-        let agents = root["agents"] as? [String: Any]
-        let list = agents?["list"] as? [[String: Any]] ?? []
-        var ids: [String] = []
-        var seen = Set<String>()
-        var defaultId: String?
-        for entry in list {
-            guard let raw = entry["id"] as? String else { continue }
-            let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-            guard !trimmed.isEmpty else { continue }
-            if !seen.insert(trimmed).inserted { continue }
-            ids.append(trimmed)
-            if (entry["default"] as? Bool) == true, defaultId == nil {
-                defaultId = trimmed
-            }
-        }
-        if ids.isEmpty {
-            ids = ["main"]
-            defaultId = "main"
-        } else if defaultId == nil {
-            defaultId = ids.first
-        }
-        self.agentIds = ids
-        self.defaultAgentId = defaultId ?? "main"
-        if !self.agentIds.contains(self.selectedAgentId) {
-            self.selectedAgentId = self.defaultAgentId
-        }
-    }
-
-    func selectAgent(_ id: String) {
-        self.selectedAgentId = id
-        self.loadSettings(for: id)
-        Task { await self.refreshSkillBins() }
-    }
-
-    func loadSettings(for agentId: String) {
-        let resolved = ExecApprovalsStore.resolve(agentId: agentId)
-        self.security = resolved.agent.security
-        self.ask = resolved.agent.ask
-        self.askFallback = resolved.agent.askFallback
-        self.autoAllowSkills = resolved.agent.autoAllowSkills
-        self.entries = resolved.allowlist
-            .sorted { $0.pattern.localizedCaseInsensitiveCompare($1.pattern) == .orderedAscending }
-    }
-
-    func setSecurity(_ security: ExecSecurity) {
-        self.security = security
-        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
-            entry.security = security
-        }
-        self.syncQuickMode()
-    }
-
-    func setAsk(_ ask: ExecAsk) {
-        self.ask = ask
-        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
-            entry.ask = ask
-        }
-        self.syncQuickMode()
-    }
-
-    func setAskFallback(_ mode: ExecSecurity) {
-        self.askFallback = mode
-        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
-            entry.askFallback = mode
-        }
-    }
-
-    func setAutoAllowSkills(_ enabled: Bool) {
-        self.autoAllowSkills = enabled
-        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
-            entry.autoAllowSkills = enabled
-        }
-        Task { await self.refreshSkillBins(force: enabled) }
-    }
-
-    func addEntry(_ pattern: String) {
-        let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return }
-        self.entries.append(ExecAllowlistEntry(pattern: trimmed, lastUsedAt: nil))
-        ExecApprovalsStore.updateAllowlist(agentId: self.selectedAgentId, allowlist: self.entries)
-    }
-
-    func updateEntry(_ entry: ExecAllowlistEntry, at index: Int) {
-        guard self.entries.indices.contains(index) else { return }
-        self.entries[index] = entry
-        ExecApprovalsStore.updateAllowlist(agentId: self.selectedAgentId, allowlist: self.entries)
-    }
-
-    func removeEntry(at index: Int) {
-        guard self.entries.indices.contains(index) else { return }
-        self.entries.remove(at: index)
-        ExecApprovalsStore.updateAllowlist(agentId: self.selectedAgentId, allowlist: self.entries)
-    }
-
-    func refreshSkillBins(force: Bool = false) async {
-        guard self.autoAllowSkills else {
-            self.skillBins = []
-            return
-        }
-        let bins = await SkillBinsCache.shared.currentBins(force: force)
-        self.skillBins = bins.sorted()
-    }
-
-    private func syncQuickMode() {
-        if self.selectedAgentId == self.defaultAgentId || self.agentIds.count <= 1 {
-            AppStateStore.shared.execApprovalMode = ExecApprovalQuickMode.from(security: self.security, ask: self.ask)
-        }
-    }
-}

apps/macos/Tests/ClawdbotIPCTests/CommandResolverTests.swift

@@ -34,7 +34,7 @@ import Testing
         let clawdbotPath = tmp.appendingPathComponent("node_modules/.bin/clawdbot")
         try self.makeExec(at: clawdbotPath)
 
-        let cmd = CommandResolver.clawdbotCommand(subcommand: "gateway", defaults: defaults, configRoot: [:])
+        let cmd = CommandResolver.clawdbotCommand(subcommand: "gateway", defaults: defaults)
         #expect(cmd.prefix(2).elementsEqual([clawdbotPath.path, "gateway"]))
     }
 
@@ -55,7 +55,6 @@ import Testing
         let cmd = CommandResolver.clawdbotCommand(
             subcommand: "rpc",
             defaults: defaults,
-            configRoot: [:],
             searchPaths: [tmp.appendingPathComponent("node_modules/.bin").path])
 
         #expect(cmd.count >= 3)
@@ -76,7 +75,7 @@ import Testing
         let pnpmPath = tmp.appendingPathComponent("node_modules/.bin/pnpm")
         try self.makeExec(at: pnpmPath)
 
-        let cmd = CommandResolver.clawdbotCommand(subcommand: "rpc", defaults: defaults, configRoot: [:])
+        let cmd = CommandResolver.clawdbotCommand(subcommand: "rpc", defaults: defaults)
 
         #expect(cmd.prefix(4).elementsEqual([pnpmPath.path, "--silent", "clawdbot", "rpc"]))
     }
@@ -94,8 +93,7 @@ import Testing
         let cmd = CommandResolver.clawdbotCommand(
             subcommand: "health",
             extraArgs: ["--json", "--timeout", "5"],
-            defaults: defaults,
-            configRoot: [:])
+            defaults: defaults)
 
         #expect(cmd.prefix(5).elementsEqual([pnpmPath.path, "--silent", "clawdbot", "health", "--json"]))
         #expect(cmd.suffix(2).elementsEqual(["--timeout", "5"]))
@@ -116,11 +114,7 @@ import Testing
         defaults.set("/tmp/id_ed25519", forKey: remoteIdentityKey)
         defaults.set("/srv/clawdbot", forKey: remoteProjectRootKey)
 
-        let cmd = CommandResolver.clawdbotCommand(
-            subcommand: "status",
-            extraArgs: ["--json"],
-            defaults: defaults,
-            configRoot: [:])
+        let cmd = CommandResolver.clawdbotCommand(subcommand: "status", extraArgs: ["--json"], defaults: defaults)
 
         #expect(cmd.first == "/usr/bin/ssh")
         #expect(cmd.contains("clawd@example.com"))

apps/macos/Tests/ClawdbotIPCTests/ExecAllowlistTests.swift

@@ -1,49 +0,0 @@
-import Foundation
-import Testing
-@testable import Clawdbot
-
-struct ExecAllowlistTests {
-    @Test func matchUsesResolvedPath() {
-        let entry = ExecAllowlistEntry(pattern: "/opt/homebrew/bin/rg")
-        let resolution = ExecCommandResolution(
-            rawExecutable: "rg",
-            resolvedPath: "/opt/homebrew/bin/rg",
-            executableName: "rg",
-            cwd: nil)
-        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
-        #expect(match?.pattern == entry.pattern)
-    }
-
-    @Test func matchUsesBasenameForSimplePattern() {
-        let entry = ExecAllowlistEntry(pattern: "rg")
-        let resolution = ExecCommandResolution(
-            rawExecutable: "rg",
-            resolvedPath: "/opt/homebrew/bin/rg",
-            executableName: "rg",
-            cwd: nil)
-        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
-        #expect(match?.pattern == entry.pattern)
-    }
-
-    @Test func matchIsCaseInsensitive() {
-        let entry = ExecAllowlistEntry(pattern: "RG")
-        let resolution = ExecCommandResolution(
-            rawExecutable: "rg",
-            resolvedPath: "/opt/homebrew/bin/rg",
-            executableName: "rg",
-            cwd: nil)
-        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
-        #expect(match?.pattern == entry.pattern)
-    }
-
-    @Test func matchSupportsGlobStar() {
-        let entry = ExecAllowlistEntry(pattern: "/opt/**/rg")
-        let resolution = ExecCommandResolution(
-            rawExecutable: "rg",
-            resolvedPath: "/opt/homebrew/bin/rg",
-            executableName: "rg",
-            cwd: nil)
-        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
-        #expect(match?.pattern == entry.pattern)
-    }
-}

apps/macos/Tests/ClawdbotIPCTests/MacNodeRuntimeTests.swift

@@ -74,6 +74,10 @@ struct MacNodeRuntimeTests {
             {
                 CLLocation(latitude: 0, longitude: 0)
             }
+
+            func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision {
+                .allowOnce
+            }
         }
 
         let services = await MainActor.run { FakeMainActorServices() }

apps/macos/Tests/ClawdbotIPCTests/UtilitiesTests.swift

@@ -37,7 +37,7 @@ import Testing
         defaults.set(AppState.ConnectionMode.remote.rawValue, forKey: connectionModeKey)
         defaults.set("ssh  alice@example.com", forKey: remoteTargetKey)
 
-        let settings = CommandResolver.connectionSettings(defaults: defaults, configRoot: [:])
+        let settings = CommandResolver.connectionSettings(defaults: defaults)
         #expect(settings.mode == .remote)
         #expect(settings.target == "alice@example.com")
     }

apps/shared/ClawdbotKit/Sources/ClawdbotKit/SystemCommands.swift

@@ -24,25 +24,19 @@ public struct ClawdbotSystemRunParams: Codable, Sendable, Equatable {
     public var env: [String: String]?
     public var timeoutMs: Int?
     public var needsScreenRecording: Bool?
-    public var agentId: String?
-    public var sessionKey: String?
 
     public init(
         command: [String],
         cwd: String? = nil,
         env: [String: String]? = nil,
         timeoutMs: Int? = nil,
-        needsScreenRecording: Bool? = nil,
-        agentId: String? = nil,
-        sessionKey: String? = nil)
+        needsScreenRecording: Bool? = nil)
     {
         self.command = command
         self.cwd = cwd
         self.env = env
         self.timeoutMs = timeoutMs
         self.needsScreenRecording = needsScreenRecording
-        self.agentId = agentId
-        self.sessionKey = sessionKey
     }
 }
 

docs.acp.md

@@ -1,194 +0,0 @@
-# Clawdbot ACP Bridge
-
-This document describes how the Clawdbot ACP (Agent Client Protocol) bridge works,
-how it maps ACP sessions to Gateway sessions, and how IDEs should invoke it.
-
-## Overview
-
-`clawdbot acp` exposes an ACP agent over stdio and forwards prompts to a running
-Clawdbot Gateway over WebSocket. It keeps ACP session ids mapped to Gateway
-session keys so IDEs can reconnect to the same agent transcript or reset it on
-request.
-
-Key goals:
-
-- Minimal ACP surface area (stdio, NDJSON).
-- Stable session mapping across reconnects.
-- Works with existing Gateway session store (list/resolve/reset).
-- Safe defaults (isolated ACP session keys by default).
-
-## How can I use this
-
-Use ACP when an IDE or tooling speaks Agent Client Protocol and you want it to
-drive a Clawdbot Gateway session.
-
-Quick steps:
-
-1. Run a Gateway (local or remote).
-2. Configure the Gateway target (`gateway.remote.url` + auth) or pass flags.
-3. Point the IDE to run `clawdbot acp` over stdio.
-
-Example config:
-
-```bash
-clawdbot config set gateway.remote.url wss://gateway-host:18789
-clawdbot config set gateway.remote.token <token>
-```
-
-Example run:
-
-```bash
-clawdbot acp --url wss://gateway-host:18789 --token <token>
-```
-
-## Selecting agents
-
-ACP does not pick agents directly. It routes by the Gateway session key.
-
-Use agent-scoped session keys to target a specific agent:
-
-```bash
-clawdbot acp --session agent:main:main
-clawdbot acp --session agent:design:main
-clawdbot acp --session agent:qa:bug-123
-```
-
-Each ACP session maps to a single Gateway session key. One agent can have many
-sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
-the key or label.
-
-## Zed editor setup
-
-Add a custom ACP agent in `~/.config/zed/settings.json`:
-
-```json
-{
-  "agent_servers": {
-    "Clawdbot ACP": {
-      "type": "custom",
-      "command": "clawdbot",
-      "args": ["acp"],
-      "env": {}
-    }
-  }
-}
-```
-
-To target a specific Gateway or agent:
-
-```json
-{
-  "agent_servers": {
-    "Clawdbot ACP": {
-      "type": "custom",
-      "command": "clawdbot",
-      "args": [
-        "acp",
-        "--url", "wss://gateway-host:18789",
-        "--token", "<token>",
-        "--session", "agent:design:main"
-      ],
-      "env": {}
-    }
-  }
-}
-```
-
-In Zed, open the Agent panel and select “Clawdbot ACP” to start a thread.
-
-## Execution Model
-
-- ACP client spawns `clawdbot acp` and speaks ACP messages over stdio.
-- The bridge connects to the Gateway using existing auth config (or CLI flags).
-- ACP `prompt` translates to Gateway `chat.send`.
-- Gateway streaming events are translated back into ACP streaming events.
-- ACP `cancel` maps to Gateway `chat.abort` for the active run.
-
-## Session Mapping
-
-By default each ACP session is mapped to a dedicated Gateway session key:
-
-- `acp:<uuid>` unless overridden.
-
-You can override or reuse sessions in two ways:
-
-1) CLI defaults
-
-```bash
-clawdbot acp --session agent:main:main
-clawdbot acp --session-label "support inbox"
-clawdbot acp --reset-session
-```
-
-2) ACP metadata per session
-
-```json
-{
-  "_meta": {
-    "sessionKey": "agent:main:main",
-    "sessionLabel": "support inbox",
-    "resetSession": true,
-    "requireExisting": false
-  }
-}
-```
-
-Rules:
-
-- `sessionKey`: direct Gateway session key.
-- `sessionLabel`: resolve an existing session by label.
-- `resetSession`: mint a new transcript for the key before first use.
-- `requireExisting`: fail if the key/label does not exist.
-
-### Session Listing
-
-ACP `listSessions` maps to Gateway `sessions.list` and returns a filtered
-summary suitable for IDE session pickers. `_meta.limit` can cap the number of
-sessions returned.
-
-## Prompt Translation
-
-ACP prompt inputs are converted into a Gateway `chat.send`:
-
-- `text` and `resource` blocks become prompt text.
-- `resource_link` with image mime types become attachments.
-- The working directory can be prefixed into the prompt (default on, can be
-  disabled with `--no-prefix-cwd`).
-
-Gateway streaming events are translated into ACP `message` and `tool_call`
-updates. Terminal Gateway states map to ACP `done` with stop reasons:
-
-- `complete` -> `stop`
-- `aborted` -> `cancel`
-- `error` -> `error`
-
-## Auth + Gateway Discovery
-
-`clawdbot acp` resolves the Gateway URL and auth from CLI flags or config:
-
-- `--url` / `--token` / `--password` take precedence.
-- Otherwise use configured `gateway.remote.*` settings.
-
-## Operational Notes
-
-- ACP sessions are stored in memory for the bridge process lifetime.
-- Gateway session state is persisted by the Gateway itself.
-- `--verbose` logs ACP/Gateway bridge events to stderr (never stdout).
-- ACP runs can be canceled and the active run id is tracked per session.
-
-## Compatibility
-
-- ACP bridge uses `@agentclientprotocol/sdk` (currently 0.13.x).
-- Works with ACP clients that implement `initialize`, `newSession`,
-  `loadSession`, `prompt`, `cancel`, and `listSessions`.
-
-## Testing
-
-- Unit: `src/acp/session.test.ts` covers run id lifecycle.
-- Full gate: `pnpm lint && pnpm build && pnpm test && pnpm docs:build`.
-
-## Related Docs
-
-- CLI usage: `docs/cli/acp.md`
-- Session model: `docs/concepts/session.md`
-- Session management internals: `docs/reference/session-management-compaction.md`

docs/brave-search.md

@@ -1,40 +0,0 @@
----
-summary: "Brave Search API setup for web_search"
-read_when:
-  - You want to use Brave Search for web_search
-  - You need a BRAVE_API_KEY or plan details
----
-
-# Brave Search API
-
-Clawdbot uses Brave Search as the default provider for `web_search`.
-
-## Get an API key
-
-1) Create a Brave Search API account at https://brave.com/search/api/
-2) In the dashboard, choose the **Data for Search** plan and generate an API key.
-3) Store the key in config (recommended) or set `BRAVE_API_KEY` in the Gateway environment.
-
-## Config example
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        provider: "brave",
-        apiKey: "BRAVE_API_KEY_HERE",
-        maxResults: 5,
-        timeoutSeconds: 30
-      }
-    }
-  }
-}
-```
-
-## Notes
-
-- The Data for AI plan is **not** compatible with `web_search`.
-- Brave provides a free tier plus paid plans; check the Brave API portal for current limits.
-
-See [Web tools](/tools/web) for the full web_search configuration.

docs/channels/bluebubbles.md

@@ -1,64 +0,0 @@
----
-summary: "iMessage via BlueBubbles macOS server (REST send/receive, typing, reactions, pairing)."
-read_when:
-  - Setting up BlueBubbles channel
-  - Troubleshooting webhook pairing
----
-# BlueBubbles (macOS REST)
-
-Status: bundled plugin (disabled by default) that talks to the BlueBubbles macOS server over HTTP.
-
-## Overview
-- Runs on macOS via the BlueBubbles helper app (`https://bluebubbles.app`).
-- Clawdbot talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
-- Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
-- Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
-- Pairing/allowlist works the same way as other channels (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
-- Reactions are surfaced as system events just like Slack/Telegram so agents can “mention” them before replying.
-
-## Quick start
-1. Install the BlueBubbles server on your Mac (follows the app store instructions at `https://bluebubbles.app/install`).
-2. In the BlueBubbles config, enable the web API and set a password for `guid`/`password`.
-3. Configure Clawdbot:
-   ```json5
-   {
-     channels: {
-       bluebubbles: {
-         enabled: true,
-         serverUrl: "http://bluebubbles-host:1234",
-         password: "example-password",
-         webhookPath: "/bluebubbles-webhook",
-         actions: { reactions: true }
-       }
-     }
-   }
-   ```
-4. Point BlueBubbles webhooks to your gateway (example: `http://your-gateway-host/bluebubbles-webhook?password=<password>`).
-5. Start the gateway; it will register the webhook handler and start pairing.
-
-## Configuration notes
-- `channels.bluebubbles.serverUrl`: base URL of the BlueBubbles REST API.
-- `channels.bluebubbles.password`: password that BlueBubbles expects on every request (`?password=...` or header).
-- `channels.bluebubbles.webhookPath`: HTTP path the gateway exposes for BlueBubbles webhooks.
-- `channels.bluebubbles.dmPolicy` / `groupPolicy` + `allowFrom`/`groupAllowFrom` behave like other channels; pairing/allowlist info is stored in `/pairing`.
-- `channels.bluebubbles.actions.reactions` toggles whether the gateway enqueues system events for reactions/tapbacks.
-- `channels.bluebubbles.textChunkLimit` overrides the default 4k limit.
-- `channels.bluebubbles.mediaMaxMb` controls the max size of inbound attachments saved for analysis (default 8MB).
-
-## How it works
-- Outbound replies: `sendMessageBlueBubbles` resolves a chat GUID via `/api/v1/chat/query` and posts to `/api/v1/message/text`. Typing (`/api/v1/chat/<guid>/typing`) and read receipts (`/api/v1/chat/<guid>/read`) are sent before/after responses.
-- Webhooks: BlueBubbles POSTs JSON payloads with `type` and `data`. The plugin ignores non-message events (typing indicator, read status) and extracts `chatGuid` from `data.chats[0].guid`.
-- Reactions/tapbacks generate `BlueBubbles reaction added/removed` system events so agents can mention them. Agents can also trigger tapbacks via the `react` action with `messageId`, `emoji`, and a `to`/`chatGuid`.
-- Attachments are downloaded via the REST API and stored in the inbound media cache; text-less messages are converted into `<media:...>` placeholders so the agent knows something was sent.
-
-## Security
-- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted.
-- Keep the API password and webhook endpoint secret (treat them like credentials).
-- Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.
-
-## Troubleshooting
-- If Voice/typing events stop working, check the BlueBubbles webhook logs and verify the gateway path matches `channels.bluebubbles.webhookPath`.
-- Pairing codes expire after one hour; use `clawdbot pairing list bluebubbles` and `clawdbot pairing approve bluebubbles <code>`.
-- Reactions require the BlueBubbles private API (`POST /api/v1/message/react`); ensure the server version exposes it.
-
-For general channel workflow reference, see [/channels/index] and the [[plugins|/plugin]] guide.

docs/channels/discord.md

@@ -58,7 +58,7 @@ Minimal config:
     - The `discord` tool is only exposed when the current channel is Discord.
 13. Native commands use isolated session keys (`agent:<agentId>:discord:slash:<userId>`) rather than the shared `main` session.
 
-Note: Name → id resolution uses guild member search and requires Server Members Intent; if the bot can’t search members, use ids or `<@id>` mentions.
+Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or `<@id>` mentions for DM delivery targets.
 Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
 Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
 
@@ -175,7 +175,7 @@ Notes:
 - `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions for guild messages.
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
 - If `channels` is present, any channel not listed is denied by default.
-- Threads inherit parent channel config (allowlist, `requireMention`, skills, prompts, etc.) unless you add the thread channel id explicitly.
+- Threads inherit parent channel config (allowlist, `requireMention`, skills, prompts, etc.) unless you add the thread id explicitly.
 - Bot-authored messages are ignored by default; set `channels.discord.allowBots=true` to allow them (own messages remain filtered).
 - Warning: If you allow replies to other bots (`channels.discord.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.discord.guilds.*.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
 
@@ -193,11 +193,8 @@ Notes:
   - Your config requires mentions and you didn’t mention it, or
   - Your guild/channel allowlist denies the channel/user.
 - **`requireMention: false` but still no replies**:
-- `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or add a guild entry under `channels.discord.guilds` (optionally list channels under `channels.discord.guilds.<id>.channels` to restrict).
-  - If you only set `DISCORD_BOT_TOKEN` and never create a `channels.discord` section, the runtime
-    defaults `groupPolicy` to `open`. Add `channels.discord.groupPolicy`,
-    `channels.defaults.groupPolicy`, or a guild/channel allowlist to lock it down.
-- `requireMention` must live under `channels.discord.guilds` (or a specific channel). `channels.discord.requireMention` at the top level is ignored.
+  - `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or add a guild entry under `channels.discord.guilds` (optionally list channels under `channels.discord.guilds.<id>.channels` to restrict).
+  - `requireMention` must live under `channels.discord.guilds` (or a specific channel). `channels.discord.requireMention` at the top level is ignored.
 - **Permission audits** (`channels status --probe`) only check numeric channel IDs. If you use slugs/names as `channels.discord.guilds.*.channels` keys, the audit can’t verify permissions.
 - **DMs don’t work**: `channels.discord.dm.enabled=false`, `channels.discord.dm.policy="disabled"`, or you haven’t been approved yet (`channels.discord.dm.policy="pairing"`).
 
@@ -365,10 +362,6 @@ Allowlist matching notes:
 - Use `*` to allow any sender/channel.
 - When `guilds.<id>.channels` is present, channels not listed are denied by default.
 - When `guilds.<id>.channels` is omitted, all channels in the allowlisted guild are allowed.
-- To allow **no channels**, set `channels.discord.groupPolicy: "disabled"` (or keep an empty allowlist).
-- The configure wizard accepts `Guild/Channel` names (public + private) and resolves them to IDs when possible.
-- On startup, Clawdbot resolves channel/user names in allowlists to IDs (when the bot can search members)
-  and logs the mapping; unresolved entries are kept as typed.
 
 Native command notes:
 - The registered commands mirror Clawdbot’s chat commands.

docs/channels/index.md

@@ -17,7 +17,6 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Slack](/channels/slack) — Bolt SDK; workspace apps.
 - [Signal](/channels/signal) — signal-cli; privacy-focused.
 - [iMessage](/channels/imessage) — macOS only; native integration.
-- [BlueBubbles](/channels/bluebubbles) — iMessage via BlueBubbles macOS server (bundled plugin, disabled by default).
 - [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
 - [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
 - [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).

docs/channels/matrix.md

@@ -70,10 +70,9 @@ Matrix is an open messaging protocol. Clawdbot connects as a Matrix user and lis
   - `clawdbot pairing list matrix`
   - `clawdbot pairing approve matrix <CODE>`
 - Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
-- `channels.matrix.dm.allowFrom` accepts user IDs or display names (resolved at startup when directory search is available).
 
 ## Rooms (groups)
-- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.
+- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated).
 - Allowlist rooms with `channels.matrix.rooms`:
 ```json5
 {
@@ -87,9 +86,6 @@ Matrix is an open messaging protocol. Clawdbot connects as a Matrix user and lis
 }
 ```
 - `requireMention: false` enables auto-reply in that room.
-- The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names when possible.
-- On startup, Clawdbot resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
-- To allow **no rooms**, set `channels.matrix.groupPolicy: "disabled"` (or keep an empty allowlist).
 
 ## Threads
 - Reply threading is supported.

docs/channels/msteams.md

@@ -76,13 +76,12 @@ Disable with:
 
 **DM access**
 - Default: `channels.msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved.
-- `channels.msteams.allowFrom` accepts AAD object IDs, UPNs, or display names (resolved at startup when Graph allows).
+- `channels.msteams.allowFrom` accepts AAD object IDs or UPNs.
 
 **Group access**
-- Default: `channels.msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`). Use `channels.defaults.groupPolicy` to override the default when unset.
+- Default: `channels.msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`).
 - `channels.msteams.groupAllowFrom` controls which senders can trigger in group chats/channels (falls back to `channels.msteams.allowFrom`).
 - Set `groupPolicy: "open"` to allow any member (still mention‑gated by default).
-- To allow **no channels**, set `channels.msteams.groupPolicy: "disabled"`.
 
 Example:
 ```json5
@@ -96,32 +95,6 @@ Example:
 }
 ```
 
-**Teams + channel allowlist**
-- Scope group/channel replies by listing teams and channels under `channels.msteams.teams`.
-- Keys can be team IDs or names; channel keys can be conversation IDs or names.
-- When `groupPolicy="allowlist"` and a teams allowlist is present, only listed teams/channels are accepted (mention‑gated).
-- The configure wizard accepts `Team/Channel` entries and stores them for you.
-- On startup, Clawdbot resolves team/channel and user allowlist names to IDs (when Graph permissions allow)
-  and logs the mapping; unresolved entries are kept as typed.
-
-Example:
-```json5
-{
-  channels: {
-    msteams: {
-      groupPolicy: "allowlist",
-      teams: {
-        "My Team": {
-          channels: {
-            "General": { requireMention: true }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
 ## How it works
 1. Install the Microsoft Teams plugin.
 2. Create an **Azure Bot** (App ID + secret + tenant ID).

docs/channels/slack.md

@@ -343,19 +343,10 @@ For fine-grained control, use these tags in agent responses:
 - Default: `channels.slack.dm.policy="pairing"` — unknown DM senders get a pairing code (expires after 1 hour).
 - Approve via: `clawdbot pairing approve slack <code>`.
 - To allow anyone: set `channels.slack.dm.policy="open"` and `channels.slack.dm.allowFrom=["*"]`.
-- `channels.slack.dm.allowFrom` accepts user IDs, @handles, or emails (resolved at startup when tokens allow).
 
 ## Group policy
 - `channels.slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
 - `allowlist` requires channels to be listed in `channels.slack.channels`.
- - If you only set `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` and never create a `channels.slack` section,
-   the runtime defaults `groupPolicy` to `open`. Add `channels.slack.groupPolicy`,
-   `channels.defaults.groupPolicy`, or a channel allowlist to lock it down.
- - The configure wizard accepts `#channel` names and resolves them to IDs when possible
-   (public + private); if multiple matches exist, it prefers the active channel.
- - On startup, Clawdbot resolves channel/user names in allowlists to IDs (when tokens allow)
-   and logs the mapping; unresolved entries are kept as typed.
- - To allow **no channels**, set `channels.slack.groupPolicy: "disabled"` (or keep an empty allowlist).
 
 Channel options (`channels.slack.channels.<id>` or `channels.slack.channels.<name>`):
 - `allow`: allow/deny the channel when `groupPolicy="allowlist"`.

docs/channels/telegram.md

@@ -152,7 +152,6 @@ By default, the bot only responds to mentions in groups (`@botname` or patterns
 ```
 
 **Important:** Setting `channels.telegram.groups` creates an **allowlist** - only listed groups (or `"*"`) will be accepted.
-Forum topics inherit their parent group config (allowFrom, requireMention, skills, prompts) unless you add per-topic overrides under `channels.telegram.groups.<groupId>.topics.<topicId>`.
 
 To allow all groups with always-respond:
 ```json5

docs/channels/zalouser.md

@@ -66,36 +66,11 @@ clawdbot directory groups list --channel zalouser --query "work"
 
 ## Access control (DMs)
 `channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
-`channels.zalouser.allowFrom` accepts user IDs or names (resolved at startup when available).
 
 Approve via:
 - `clawdbot pairing list zalouser`
 - `clawdbot pairing approve zalouser <code>`
 
-## Group access (optional)
-- Default: `channels.zalouser.groupPolicy = "open"` (groups allowed). Use `channels.defaults.groupPolicy` to override the default when unset.
-- Restrict to an allowlist with:
-  - `channels.zalouser.groupPolicy = "allowlist"`
-  - `channels.zalouser.groups` (keys are group IDs or names)
-- Block all groups: `channels.zalouser.groupPolicy = "disabled"`.
-- The configure wizard can prompt for group allowlists.
-- On startup, Clawdbot resolves group/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
-
-Example:
-```json5
-{
-  channels: {
-    zalouser: {
-      groupPolicy: "allowlist",
-      groups: {
-        "123456789": { allow: true },
-        "Work Chat": { allow: true }
-      }
-    }
-  }
-}
-```
-
 ## Multi-account
 Accounts map to zca profiles. Example:
 

docs/cli/acp.md

@@ -1,143 +0,0 @@
----
-summary: "Run the ACP bridge for IDE integrations"
-read_when:
-  - Setting up ACP-based IDE integrations
-  - Debugging ACP session routing to the Gateway
----
-
-# acp
-
-Run the ACP (Agent Client Protocol) bridge that talks to a Clawdbot Gateway.
-
-This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway
-over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
-
-## Usage
-
-```bash
-clawdbot acp
-
-# Remote Gateway
-clawdbot acp --url wss://gateway-host:18789 --token <token>
-
-# Attach to an existing session key
-clawdbot acp --session agent:main:main
-
-# Attach by label (must already exist)
-clawdbot acp --session-label "support inbox"
-
-# Reset the session key before the first prompt
-clawdbot acp --session agent:main:main --reset-session
-```
-
-## How to use this
-
-Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
-it to drive a Clawdbot Gateway session.
-
-1. Ensure the Gateway is running (local or remote).
-2. Configure the Gateway target (config or flags).
-3. Point your IDE to run `clawdbot acp` over stdio.
-
-Example config (persisted):
-
-```bash
-clawdbot config set gateway.remote.url wss://gateway-host:18789
-clawdbot config set gateway.remote.token <token>
-```
-
-Example direct run (no config write):
-
-```bash
-clawdbot acp --url wss://gateway-host:18789 --token <token>
-```
-
-## Selecting agents
-
-ACP does not pick agents directly. It routes by the Gateway session key.
-
-Use agent-scoped session keys to target a specific agent:
-
-```bash
-clawdbot acp --session agent:main:main
-clawdbot acp --session agent:design:main
-clawdbot acp --session agent:qa:bug-123
-```
-
-Each ACP session maps to a single Gateway session key. One agent can have many
-sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
-the key or label.
-
-## Zed editor setup
-
-Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zed’s Settings UI):
-
-```json
-{
-  "agent_servers": {
-    "Clawdbot ACP": {
-      "type": "custom",
-      "command": "clawdbot",
-      "args": ["acp"],
-      "env": {}
-    }
-  }
-}
-```
-
-To target a specific Gateway or agent:
-
-```json
-{
-  "agent_servers": {
-    "Clawdbot ACP": {
-      "type": "custom",
-      "command": "clawdbot",
-      "args": [
-        "acp",
-        "--url", "wss://gateway-host:18789",
-        "--token", "<token>",
-        "--session", "agent:design:main"
-      ],
-      "env": {}
-    }
-  }
-}
-```
-
-In Zed, open the Agent panel and select “Clawdbot ACP” to start a thread.
-
-## Session mapping
-
-By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.
-To reuse a known session, pass a session key or label:
-
-- `--session <key>`: use a specific Gateway session key.
-- `--session-label <label>`: resolve an existing session by label.
-- `--reset-session`: mint a fresh session id for that key (same key, new transcript).
-
-If your ACP client supports metadata, you can override per session:
-
-```json
-{
-  "_meta": {
-    "sessionKey": "agent:main:main",
-    "sessionLabel": "support inbox",
-    "resetSession": true
-  }
-}
-```
-
-Learn more about session keys at [/concepts/session](/concepts/session).
-
-## Options
-
-- `--url <url>`: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
-- `--token <token>`: Gateway auth token.
-- `--password <password>`: Gateway auth password.
-- `--session <key>`: default session key.
-- `--session-label <label>`: default session label to resolve.
-- `--require-existing`: fail if the session key/label does not exist.
-- `--reset-session`: reset the session key before first use.
-- `--no-prefix-cwd`: do not prefix prompts with the working directory.
-- `--verbose, -v`: verbose logging to stderr.

docs/cli/channels.md

@@ -20,7 +20,6 @@ clawdbot channels list
 clawdbot channels status
 clawdbot channels capabilities
 clawdbot channels capabilities --channel discord --target channel:123
-clawdbot channels resolve --channel slack "#general" "@jane"
 clawdbot channels logs --channel all
 ```
 
@@ -58,17 +57,3 @@ Notes:
 - `--channel` is optional; omit it to list every channel (including extensions).
 - `--target` accepts `channel:<id>` or a raw numeric channel id and only applies to Discord.
 - Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; MS Teams app token + Graph roles/scopes (annotated where known). Channels without probes report `Probe: unavailable`.
-
-## Resolve names to IDs
-
-Resolve channel/user names to IDs using the provider directory:
-
-```bash
-clawdbot channels resolve --channel slack "#general" "@jane"
-clawdbot channels resolve --channel discord "My Server/#support" "@someone"
-clawdbot channels resolve --channel matrix "Project Room"
-```
-
-Notes:
-- Use `--kind user|group|auto` to force the target type.
-- Resolution prefers active matches when multiple entries share the same name.

docs/cli/configure.md

@@ -17,7 +17,6 @@ Related:
 
 Notes:
 - Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
-- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
 
 ## Examples
 

docs/cli/hooks.md

@@ -11,7 +11,6 @@ Manage agent hooks (event-driven automations for commands like `/new`, `/reset`,
 
 Related:
 - Hooks: [Hooks](/hooks)
-- Plugin hooks: [Plugins](/plugin#plugin-hooks)
 
 ## List All Hooks
 
@@ -119,9 +118,6 @@ clawdbot hooks enable <name>
 
 Enable a specific hook by adding it to your config (`~/.clawdbot/config.json`).
 
-**Note:** Hooks managed by plugins show `plugin:<id>` in `clawdbot hooks list` and
-can’t be enabled/disabled here. Enable/disable the plugin instead.
-
 **Arguments:**
 - `<name>`: Hook name (e.g., `session-memory`)
 
@@ -260,15 +256,3 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
 ```
 
 **See:** [command-logger documentation](/hooks#command-logger)
-
-### soul-evil
-
-Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance.
-
-**Enable:**
-
-```bash
-clawdbot hooks enable soul-evil
-```
-
-**See:** [soul-evil documentation](/hooks#soul-evil)

docs/cli/index.md

@@ -23,7 +23,6 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`message`](/cli/message)
 - [`agent`](/cli/agent)
 - [`agents`](/cli/agents)
-- [`acp`](/cli/acp)
 - [`status`](/cli/status)
 - [`health`](/cli/health)
 - [`sessions`](/cli/sessions)
@@ -126,7 +125,6 @@ clawdbot [--dev] [--profile <name>] <command>
     list
     add
     delete
-  acp
   status
   health
   sessions
@@ -508,11 +506,6 @@ Options:
 - `--force`
 - `--json`
 
-### `acp`
-Run the ACP bridge that connects IDEs to the Gateway.
-
-See [`acp`](/cli/acp) for full options and examples.
-
 ### `status`
 Show linked session health and recent recipients.
 
@@ -529,7 +522,7 @@ Options:
 Clawdbot can surface provider usage/quota when OAuth/API creds are available.
 
 Surfaces:
-- `/status` (adds a short provider usage line when available)
+- `/status` (alias: `/usage`; adds a short usage line when available)
 - `clawdbot status --usage` (prints full provider breakdown)
 - macOS menu bar (Usage section under Context)
 

docs/cli/memory.md

@@ -8,11 +8,9 @@ read_when:
 # `clawdbot memory`
 
 Memory search tools (semantic memory status/index/search).
-Provided by the active memory plugin (default: `memory-core`; use `plugins.slots.memory = "none"` to disable).
 
 Related:
 - Memory concept: [Memory](/concepts/memory)
- - Plugins: [Plugins](/plugins)
 
 ## Examples
 
@@ -20,11 +18,6 @@ Related:
 clawdbot memory status
 clawdbot memory status --deep
 clawdbot memory status --deep --index
-clawdbot memory status --deep --index --verbose
 clawdbot memory index
 clawdbot memory search "release checklist"
 ```
-
-## Options
-
-- `--verbose`: emit debug logs during memory probes and indexing.

docs/concepts/context.md

@@ -21,7 +21,7 @@ Context is *not the same thing* as “memory”: memory can be stored on disk an
 - `/status` → quick “how full is my window?” view + session settings.
 - `/context list` → what’s injected + rough sizes (per file + totals).
 - `/context detail` → deeper breakdown: per-file, per-tool schema sizes, per-skill entry sizes, and system prompt size.
-- `/usage tokens` → append per-reply usage footer to normal replies.
+- `/cost on` → append per-reply usage line to normal replies.
 - `/compact` → summarize older history into a compact entry to free window space.
 
 See also: [Slash commands](/tools/slash-commands), [Token use & costs](/token-use), [Compaction](/concepts/compaction).
@@ -149,3 +149,4 @@ Docs: [Session](/concepts/session), [Compaction](/concepts/compaction), [Session
 - `System prompt (estimate)` = computed on the fly when no run report exists (or when running via a CLI backend that doesn’t generate the report).
 
 Either way, it reports sizes and top contributors; it does **not** dump the full system prompt or tool schemas.
+

docs/concepts/memory.md

@@ -9,9 +9,6 @@ read_when:
 Clawdbot memory is **plain Markdown in the agent workspace**. The files are the
 source of truth; the model only "remembers" what gets written to disk.
 
-Memory search tools are provided by the active memory plugin (default:
-`memory-core`). Disable memory plugins with `plugins.slots.memory = "none"`.
-
 ## Memory files (Markdown)
 
 The default workspace layout uses two memory layers:
@@ -114,16 +111,8 @@ If you don't want to set an API key, use `memorySearch.provider = "local"` or se
 Batch indexing (OpenAI only):
 - Enabled by default for OpenAI embeddings. Set `agents.defaults.memorySearch.remote.batch.enabled = false` to disable.
 - Default behavior waits for batch completion; tune `remote.batch.wait`, `remote.batch.pollIntervalMs`, and `remote.batch.timeoutMinutes` if needed.
-- Set `remote.batch.concurrency` to control how many batch jobs we submit in parallel (default: 2).
 - Batch mode currently applies only when `memorySearch.provider = "openai"` and uses your OpenAI API key.
 
-Why OpenAI batch is fast + cheap:
-- For large backfills, OpenAI is typically the fastest option we support because we can submit many embedding requests in a single batch job and let OpenAI process them asynchronously.
-- OpenAI offers discounted pricing for Batch API workloads, so large indexing runs are usually cheaper than sending the same requests synchronously.
-- See the OpenAI Batch API docs and pricing for details:
-  - https://platform.openai.com/docs/api-reference/batch
-  - https://platform.openai.com/pricing
-
 Config example:
 
 ```json5
@@ -134,7 +123,7 @@ agents: {
       model: "text-embedding-3-small",
       fallback: "openai",
       remote: {
-        batch: { enabled: true, concurrency: 2 }
+        batch: { enabled: false }
       },
       sync: { watch: true }
     }
@@ -160,93 +149,8 @@ Local mode:
 ### What gets indexed (and when)
 
 - File type: Markdown only (`MEMORY.md`, `memory/**/*.md`).
-- Index storage: per-agent SQLite at `~/.clawdbot/memory/<agentId>.sqlite` (configurable via `agents.defaults.memorySearch.store.path`, supports `{agentId}` token).
-- Freshness: watcher on `MEMORY.md` + `memory/` marks the index dirty (debounce 1.5s). Sync runs on session start, on first search when dirty, and optionally on an interval.
-- Reindex triggers: the index stores the embedding **provider/model + endpoint fingerprint + chunking params**. If any of those change, Clawdbot automatically resets and reindexes the entire store.
-
-### Hybrid search (BM25 + vector)
-
-When enabled, Clawdbot combines:
-- **Vector similarity** (semantic match, wording can differ)
-- **BM25 keyword relevance** (exact tokens like IDs, env vars, code symbols)
-
-If full-text search is unavailable on your platform, Clawdbot falls back to vector-only search.
-
-#### Why hybrid?
-
-Vector search is great at “this means the same thing”:
-- “Mac Studio gateway host” vs “the machine running the gateway”
-- “debounce file updates” vs “avoid indexing on every write”
-
-But it can be weak at exact, high-signal tokens:
-- IDs (`a828e60`, `b3b9895a…`)
-- code symbols (`memorySearch.query.hybrid`)
-- error strings (“sqlite-vec unavailable”)
-
-BM25 (full-text) is the opposite: strong at exact tokens, weaker at paraphrases.
-Hybrid search is the pragmatic middle ground: **use both retrieval signals** so you get
-good results for both “natural language” queries and “needle in a haystack” queries.
-
-#### How we merge results (the current design)
-
-Implementation sketch:
-
-1) Retrieve a candidate pool from both sides:
-- **Vector**: top `maxResults * candidateMultiplier` by cosine similarity.
-- **BM25**: top `maxResults * candidateMultiplier` by FTS5 BM25 rank (lower is better).
-
-2) Convert BM25 rank into a 0..1-ish score:
-- `textScore = 1 / (1 + max(0, bm25Rank))`
-
-3) Union candidates by chunk id and compute a weighted score:
-- `finalScore = vectorWeight * vectorScore + textWeight * textScore`
-
-Notes:
-- `vectorWeight` + `textWeight` is normalized to 1.0 in config resolution, so weights behave as percentages.
-- If embeddings are unavailable (or the provider returns a zero-vector), we still run BM25 and return keyword matches.
-- If FTS5 can’t be created, we keep vector-only search (no hard failure).
-
-This isn’t “IR-theory perfect”, but it’s simple, fast, and tends to improve recall/precision on real notes.
-If we want to get fancier later, common next steps are Reciprocal Rank Fusion (RRF) or score normalization
-(min/max or z-score) before mixing.
-
-Config:
-
-```json5
-agents: {
-  defaults: {
-    memorySearch: {
-      query: {
-        hybrid: {
-          enabled: true,
-          vectorWeight: 0.7,
-          textWeight: 0.3,
-          candidateMultiplier: 4
-        }
-      }
-    }
-  }
-}
-```
-
-### Embedding cache
-
-Clawdbot can cache **chunk embeddings** in SQLite so reindexing and frequent updates (especially session transcripts) don't re-embed unchanged text.
-
-Config:
-
-```json5
-agents: {
-  defaults: {
-    memorySearch: {
-      cache: {
-        enabled: true,
-        maxEntries: 50000
-      }
-    }
-  }
-}
-```
+- Index storage: per-agent SQLite at `~/.clawdbot/state/memory/<agentId>.sqlite` (configurable via `agents.defaults.memorySearch.store.path`, supports `{agentId}` token).
+- Freshness: watcher on `MEMORY.md` + `memory/` marks the index dirty (debounce 1.5s). Sync runs on session start, on first search when dirty, and optionally on an interval. Reindex triggers when embedding model/provider or chunk sizes change.
 
 ### Session memory search (experimental)
 

docs/concepts/model-providers.md

@@ -183,22 +183,6 @@ Kimi Code uses a dedicated endpoint and key (separate from Moonshot):
 }
 ```
 
-### Qwen OAuth (free tier)
-
-Qwen provides OAuth access to Qwen Coder + Vision via a device-code flow.
-Enable the bundled plugin, then log in:
-
-```bash
-clawdbot plugins enable qwen-portal-auth
-clawdbot models auth login --provider qwen-portal --set-default
-```
-
-Model refs:
-- `qwen-portal/coder-model`
-- `qwen-portal/vision-model`
-
-See [/providers/qwen](/providers/qwen) for setup details and notes.
-
 ### Synthetic
 
 Synthetic provides Anthropic-compatible models behind the `synthetic` provider:

docs/concepts/session.md

@@ -25,7 +25,6 @@ All session state is **owned by the gateway** (the “master” Clawdbot). UI cl
 - Transcripts: `~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl` (Telegram topic sessions use `.../<SessionId>-topic-<threadId>.jsonl`).
 - The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
 - Group entries may include `displayName`, `channel`, `subject`, `room`, and `space` to label sessions in UIs.
-- Session entries include `origin` metadata (label + routing hints) so UIs can explain where a session came from.
 - Clawdbot does **not** read legacy Pi/Tau session folders.
 
 ## Session pruning
@@ -114,18 +113,3 @@ Send these as standalone messages so they register.
 ## Tips
 - Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
 - When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.
-
-## Session origin metadata
-Each session entry records where it came from (best-effort) in `origin`:
-- `label`: human label (resolved from conversation label + group subject/channel)
-- `provider`: normalized channel id (including extensions)
-- `from`/`to`: raw routing ids from the inbound envelope
-- `accountId`: provider account id (when multi-account)
-- `threadId`: thread/topic id when the channel supports it
-The origin fields are populated for direct messages, channels, and groups. If a
-connector only updates delivery routing (for example, to keep a DM main session
-fresh), it should still provide inbound context so the session keeps its
-explainer metadata. Extensions can do this by sending `ConversationLabel`,
-`GroupSubject`, `GroupChannel`, `GroupSpace`, and `SenderName` in the inbound
-context and calling `recordSessionMetaFromInbound` (or passing the same context
-to `updateLastRoute`).

docs/concepts/system-prompt.md

@@ -58,9 +58,6 @@ Large files are truncated with a marker. The max per-file size is controlled by
 `agents.defaults.bootstrapMaxChars` (default: 20000). Missing files inject a
 short missing-file marker.
 
-Internal hooks can intercept this step via `agent:bootstrap` to mutate or replace
-the injected bootstrap files (for example swapping `SOUL.md` for an alternate persona).
-
 To inspect how much each injected file contributes (raw vs injected, truncation, plus tool schema overhead), use `/context list` or `/context detail`. See [Context](/concepts/context).
 
 ## Time handling

docs/concepts/usage-tracking.md

@@ -12,7 +12,7 @@ read_when:
 
 ## Where it shows up
 - `/status` in chats: emoji‑rich status card with session tokens + estimated cost (API key only). Provider usage shows for the **current model provider** when available.
-- `/usage off|tokens|full` in chats: per-response usage footer (OAuth shows tokens only).
+- `/cost on|off` in chats: toggles per‑response usage lines (OAuth shows tokens only).
 - CLI: `clawdbot status --usage` prints a full per-provider breakdown.
 - CLI: `clawdbot channels list` prints the same usage snapshot alongside provider config (use `--no-usage` to skip).
 - macOS menu bar: “Usage” section under Context (only if available).

docs/gateway/configuration.md

@@ -678,11 +678,10 @@ Notes:
 - `"open"`: groups bypass allowlists; mention-gating still applies.
 - `"disabled"`: block all group/room messages.
 - `"allowlist"`: only allow groups/rooms that match the configured allowlist.
-- `channels.defaults.groupPolicy` sets the default when a provider’s `groupPolicy` is unset.
 - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams use `groupAllowFrom` (fallback: explicit `allowFrom`).
 - Discord/Slack use channel allowlists (`channels.discord.guilds.*.channels`, `channels.slack.channels`).
 - Group DMs (Discord/Slack) are still controlled by `dm.groupEnabled` + `dm.groupChannels`.
-- Default is `groupPolicy: "allowlist"` (unless overridden by `channels.defaults.groupPolicy`); if no allowlist is configured, group messages are blocked.
+- Default is `groupPolicy: "allowlist"`; if no allowlist is configured, group messages are blocked.
 
 ### Multi-agent routing (`agents.list` + `bindings`)
 

docs/hooks.md

@@ -14,8 +14,6 @@ Hooks are small scripts that run when something happens. There are two kinds:
 
 - **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
 - **Webhooks**: external HTTP webhooks that let other systems trigger work in Clawdbot. See [Webhook Hooks](/automation/webhook) or use `clawdbot webhooks` for Gmail helper commands.
-  
-Hooks can also be bundled inside plugins; see [Plugins](/plugin#plugin-hooks).
 
 Common uses:
 - Save a memory snapshot when you reset a session
@@ -205,8 +203,6 @@ Each event includes:
     sessionFile?: string,
     commandSource?: string,    // e.g., 'whatsapp', 'telegram'
     senderId?: string,
-    workspaceDir?: string,
-    bootstrapFiles?: WorkspaceBootstrapFile[],
     cfg?: ClawdbotConfig
   }
 }
@@ -223,10 +219,6 @@ Triggered when agent commands are issued:
 - **`command:reset`**: When `/reset` command is issued
 - **`command:stop`**: When `/stop` command is issued
 
-### Agent Events
-
-- **`agent:bootstrap`**: Before workspace bootstrap files are injected (hooks may mutate `context.bootstrapFiles`)
-
 ### Future Events
 
 Planned event types:
@@ -505,40 +497,6 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
 clawdbot hooks enable command-logger
 ```
 
-### soul-evil
-
-Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance.
-
-**Events**: `agent:bootstrap`
-
-**Output**: No files written; swaps happen in-memory only.
-
-**Enable**:
-
-```bash
-clawdbot hooks enable soul-evil
-```
-
-**Config**:
-
-```json
-{
-  "hooks": {
-    "internal": {
-      "enabled": true,
-      "entries": {
-        "soul-evil": {
-          "enabled": true,
-          "file": "SOUL_EVIL.md",
-          "chance": 0.1,
-          "purge": { "at": "21:00", "duration": "15m" }
-        }
-      }
-    }
-  }
-}
-```
-
 ## Best Practices
 
 ### Keep Handlers Fast

docs/perplexity.md

@@ -42,31 +42,10 @@ through Perplexity’s direct API or via OpenRouter.
 }
 ```
 
-## Switching from Brave
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai"
-        }
-      }
-    }
-  }
-}
-```
-
 If both `PERPLEXITY_API_KEY` and `OPENROUTER_API_KEY` are set, set
 `tools.web.search.perplexity.baseUrl` (or `tools.web.search.perplexity.apiKey`)
 to disambiguate.
 
-If `PERPLEXITY_API_KEY` is used from the environment and no base URL is set,
-Clawdbot defaults to the direct Perplexity endpoint. Set `baseUrl` to override.
-
 ## Models
 
 - `perplexity/sonar` — fast Q&A with web search

docs/plugin.md

@@ -36,7 +36,6 @@ See [Voice Call](/plugins/voice-call) for a concrete example plugin.
 ## Available plugins (official)
 
 - Microsoft Teams is plugin-only as of 2026.1.15; install `@clawdbot/msteams` if you use Teams.
-- Memory (Core) — bundled memory search plugin (enabled by default via `plugins.slots.memory`)
 - [Voice Call](/plugins/voice-call) — `@clawdbot/voice-call`
 - [Zalo Personal](/plugins/zalouser) — `@clawdbot/zalouser`
 - [Matrix](/channels/matrix) — `@clawdbot/matrix`
@@ -44,7 +43,6 @@ See [Voice Call](/plugins/voice-call) for a concrete example plugin.
 - [Microsoft Teams](/channels/msteams) — `@clawdbot/msteams`
 - Google Antigravity OAuth (provider auth) — bundled as `google-antigravity-auth` (disabled by default)
 - Gemini CLI OAuth (provider auth) — bundled as `google-gemini-cli-auth` (disabled by default)
-- Qwen OAuth (provider auth) — bundled as `qwen-portal-auth` (disabled by default)
 - Copilot Proxy (provider auth) — bundled as `copilot-proxy` (disabled by default)
 
 Clawdbot plugins are **TypeScript modules** loaded at runtime via jiti. They can
@@ -58,7 +56,6 @@ register:
 - Optional config validation
 
 Plugins run **in‑process** with the Gateway, so treat them as trusted code.
-Tool authoring guide: [Plugin agent tools](/plugins/agent-tools).
 
 ## Discovery & precedence
 
@@ -139,24 +136,6 @@ Fields:
 
 Config changes **require a gateway restart**.
 
-## Plugin slots (exclusive categories)
-
-Some plugin categories are **exclusive** (only one active at a time). Use
-`plugins.slots` to select which plugin owns the slot:
-
-```json5
-{
-  plugins: {
-    slots: {
-      memory: "memory-core" // or "none" to disable memory plugins
-    }
-  }
-}
-```
-
-If multiple plugins declare `kind: "memory"`, only the selected one loads. Others
-are disabled with diagnostics.
-
 ## Control UI (schema + labels)
 
 The Control UI uses `config.schema` (JSON Schema + `uiHints`) to render better forms.
@@ -215,27 +194,6 @@ Plugins export either:
 - A function: `(api) => { ... }`
 - An object: `{ id, name, configSchema, register(api) { ... } }`
 
-## Plugin hooks
-
-Plugins can ship hooks and register them at runtime. This lets a plugin bundle
-event-driven automation without a separate hook pack install.
-
-### Example
-
-```
-import { registerPluginHooksFromDir } from "clawdbot/plugin-sdk";
-
-export default function register(api) {
-  registerPluginHooksFromDir(api, "./hooks");
-}
-```
-
-Notes:
-- Hook directories follow the normal hook structure (`HOOK.md` + `handler.ts`).
-- Hook eligibility rules still apply (OS/bins/env/config requirements).
-- Plugin-managed hooks show up in `clawdbot hooks list` with `plugin:<id>`.
-- You cannot enable/disable plugin-managed hooks via `clawdbot hooks`; enable/disable the plugin instead.
-
 ## Provider plugins (model auth)
 
 Plugins can register **model provider auth** flows so users can run OAuth or
@@ -401,9 +359,24 @@ export default function (api) {
 Load the plugin (extensions dir or `plugins.load.paths`), restart the gateway,
 then configure `channels.<id>` in your config.
 
-### Agent tools
+### Register a tool
 
-See the dedicated guide: [Plugin agent tools](/plugins/agent-tools).
+```ts
+import { Type } from "@sinclair/typebox";
+
+export default function (api) {
+  api.registerTool({
+    name: "my_tool",
+    description: "Do a thing",
+    parameters: Type.Object({
+      input: Type.String(),
+    }),
+    async execute(_id, params) {
+      return { content: [{ type: "text", text: params.input }] };
+    },
+  });
+}
+```
 
 ### Register a gateway RPC method
 

docs/plugins/agent-tools.md

@@ -1,94 +0,0 @@
----
-summary: "Write agent tools in a plugin (schemas, optional tools, allowlists)"
-read_when:
-  - You want to add a new agent tool in a plugin
-  - You need to make a tool opt-in via allowlists
----
-# Plugin agent tools
-
-Clawdbot plugins can register **agent tools** (JSON‑schema functions) that are exposed
-to the LLM during agent runs. Tools can be **required** (always available) or
-**optional** (opt‑in).
-
-Agent tools are configured under `tools` in the main config, or per‑agent under
-`agents.list[].tools`. The allowlist/denylist policy controls which tools the agent
-can call.
-
-## Basic tool
-
-```ts
-import { Type } from "@sinclair/typebox";
-
-export default function (api) {
-  api.registerTool({
-    name: "my_tool",
-    description: "Do a thing",
-    parameters: Type.Object({
-      input: Type.String(),
-    }),
-    async execute(_id, params) {
-      return { content: [{ type: "text", text: params.input }] };
-    },
-  });
-}
-```
-
-## Optional tool (opt‑in)
-
-Optional tools are **never** auto‑enabled. Users must add them to an agent
-allowlist.
-
-```ts
-export default function (api) {
-  api.registerTool(
-    {
-      name: "workflow_tool",
-      description: "Run a local workflow",
-      parameters: {
-        type: "object",
-        properties: {
-          pipeline: { type: "string" },
-        },
-        required: ["pipeline"],
-      },
-      async execute(_id, params) {
-        return { content: [{ type: "text", text: params.pipeline }] };
-      },
-    },
-    { optional: true },
-  );
-}
-```
-
-Enable optional tools in `agents.list[].tools.allow` (or global `tools.allow`):
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "main",
-        tools: {
-          allow: [
-            "workflow_tool",  // specific tool name
-            "workflow",       // plugin id (enables all tools from that plugin)
-            "group:plugins"   // all plugin tools
-          ]
-        }
-      }
-    ]
-  }
-}
-```
-
-Other config knobs that affect tool availability:
-- `tools.profile` / `agents.list[].tools.profile` (base allowlist)
-- `tools.byProvider` / `agents.list[].tools.byProvider` (provider‑specific allow/deny)
-- `tools.sandbox.tools.*` (sandbox tool policy when sandboxed)
-
-## Rules + tips
-
-- Tool names must **not** clash with core tool names; conflicting tools are skipped.
-- Plugin ids used in allowlists must not clash with core tool names.
-- Prefer `optional: true` for tools that trigger side effects or require extra
-  binaries/credentials.

docs/providers/index.md

@@ -26,7 +26,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/etc.)? See [Chann
 
 - [OpenAI (API + Codex)](/providers/openai)
 - [Anthropic (API + Claude Code CLI)](/providers/anthropic)
-- [Qwen (OAuth)](/providers/qwen)
+- [Github Copilot](/providers/github-copilot)
 - [OpenRouter](/providers/openrouter)
 - [Vercel AI Gateway](/providers/vercel-ai-gateway)
 - [Moonshot AI (Kimi + Kimi Code)](/providers/moonshot)

docs/providers/qwen.md

@@ -1,51 +0,0 @@
----
-summary: "Use Qwen OAuth (free tier) in Clawdbot"
-read_when:
-  - You want to use Qwen with Clawdbot
-  - You want free-tier OAuth access to Qwen Coder
----
-# Qwen
-
-Qwen provides a free-tier OAuth flow for Qwen Coder and Qwen Vision models
-(2,000 requests/day, subject to Qwen rate limits).
-
-## Enable the plugin
-
-```bash
-clawdbot plugins enable qwen-portal-auth
-```
-
-Restart the Gateway after enabling.
-
-## Authenticate
-
-```bash
-clawdbot models auth login --provider qwen-portal --set-default
-```
-
-This runs the Qwen device-code OAuth flow and writes a provider entry to your
-`models.json` (plus a `qwen` alias for quick switching).
-
-## Model IDs
-
-- `qwen-portal/coder-model`
-- `qwen-portal/vision-model`
-
-Switch models with:
-
-```bash
-clawdbot models set qwen-portal/coder-model
-```
-
-## Reuse Qwen Code CLI login
-
-If you already logged in with the Qwen Code CLI, Clawdbot will sync credentials
-from `~/.qwen/oauth_creds.json` when it loads the auth store. You still need a
-`models.providers.qwen-portal` entry (use the login command above to create one).
-
-## Notes
-
-- Tokens auto-refresh; re-run the login command if refresh fails or access is revoked.
-- Default base URL: `https://portal.qwen.ai/v1` (override with
-  `models.providers.qwen-portal.baseUrl` if Qwen provides a different endpoint).
-- See [Model providers](/concepts/model-providers) for provider-wide rules.

docs/refactor/exec-host.md

@@ -1,251 +0,0 @@
----
-summary: "Refactor plan: exec host routing, node approvals, and headless runner"
-read_when:
-  - Designing exec host routing or exec approvals
-  - Implementing node runner + UI IPC
-  - Adding exec host security modes and slash commands
----
-
-# Exec host refactor plan
-
-## Goals
-- Add `exec.host` + `exec.security` to route execution across **sandbox**, **gateway**, and **node**.
-- Keep defaults **safe**: no cross-host execution unless explicitly enabled.
-- Split execution into a **headless runner service** with optional UI (macOS app) via local IPC.
-- Provide **per-agent** policy, allowlist, ask mode, and node binding.
-- Support **ask modes** that work *with* or *without* allowlists.
-- Cross-platform: Unix socket + token auth (macOS/Linux/Windows parity).
-
-## Non-goals
-- No legacy allowlist migration or legacy schema support.
-- No PTY/streaming for node exec (aggregated output only).
-- No new network layer beyond the existing Bridge + Gateway.
-
-## Decisions (locked)
-- **Config keys:** `exec.host` + `exec.security` (per-agent override allowed).
-- **Elevation:** keep `/elevated` as an alias for gateway full access.
-- **Ask default:** `on-miss`.
-- **Approvals store:** `~/.clawdbot/exec-approvals.json` (JSON, no legacy migration).
-- **Runner:** headless system service; UI app hosts a Unix socket for approvals.
-- **Node identity:** use existing `nodeId`.
-- **Socket auth:** Unix socket + token (cross-platform); split later if needed.
-
-## Key concepts
-### Host
-- `sandbox`: Docker exec (current behavior).
-- `gateway`: exec on gateway host.
-- `node`: exec on node runner via Bridge (`system.run`).
-
-### Security mode
-- `deny`: always block.
-- `allowlist`: allow only matches.
-- `full`: allow everything (equivalent to elevated).
-
-### Ask mode
-- `off`: never ask.
-- `on-miss`: ask only when allowlist does not match.
-- `always`: ask every time.
-
-Ask is **independent** of allowlist; allowlist can be used with `always` or `on-miss`.
-
-### Policy resolution (per exec)
-1) Resolve `exec.host` (tool param → agent override → global default).
-2) Resolve `exec.security` and `exec.ask` (same precedence).
-3) If host is `sandbox`, proceed with local sandbox exec.
-4) If host is `gateway` or `node`, apply security + ask policy on that host.
-
-## Default safety
-- Default `exec.host = sandbox`.
-- Default `exec.security = deny` for `gateway` and `node`.
-- Default `exec.ask = on-miss` (only relevant if security allows).
-- If no node binding is set, **agent may target any node**, but only if policy allows it.
-
-## Config surface
-### Tool parameters
-- `exec.host` (optional): `sandbox | gateway | node`.
-- `exec.security` (optional): `deny | allowlist | full`.
-- `exec.ask` (optional): `off | on-miss | always`.
-- `exec.node` (optional): node id/name to use when `host=node`.
-
-### Config keys (global)
-- `tools.exec.host`
-- `tools.exec.security`
-- `tools.exec.ask`
-- `tools.exec.node` (default node binding)
-
-### Config keys (per agent)
-- `agents.list[].tools.exec.host`
-- `agents.list[].tools.exec.security`
-- `agents.list[].tools.exec.ask`
-- `agents.list[].tools.exec.node`
-
-### Alias
-- `/elevated on` = set `tools.exec.host=gateway`, `tools.exec.security=full` for the agent session.
-- `/elevated off` = restore previous exec settings for the agent session.
-
-## Approvals store (JSON)
-Path: `~/.clawdbot/exec-approvals.json`
-
-Purpose:
-- Local policy + allowlists for the **execution host** (gateway or node runner).
-- Ask fallback when no UI is available.
-- IPC credentials for UI clients.
-
-Proposed schema (v1):
-```json
-{
-  "version": 1,
-  "socket": {
-    "path": "~/.clawdbot/exec-approvals.sock",
-    "token": "base64-opaque-token"
-  },
-  "defaults": {
-    "security": "deny",
-    "ask": "on-miss",
-    "askFallback": "deny"
-  },
-  "agents": {
-    "agent-id-1": {
-      "security": "allowlist",
-      "ask": "on-miss",
-      "allowlist": [
-        {
-          "pattern": "~/Projects/**/bin/rg",
-          "lastUsedAt": 0,
-          "lastUsedCommand": "rg -n TODO",
-          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
-        }
-      ]
-    }
-  }
-}
-```
-Notes:
-- No legacy allowlist formats.
-- `askFallback` applies only when `ask` is required and no UI is reachable.
-- File permissions: `0600`.
-
-## Runner service (headless)
-### Role
-- Enforce `exec.security` + `exec.ask` locally.
-- Execute system commands and return output.
-- Emit Bridge events for exec lifecycle (optional but recommended).
-
-### Service lifecycle
-- Launchd/daemon on macOS; system service on Linux/Windows.
-- Approvals JSON is local to the execution host.
-- UI hosts a local Unix socket; runners connect on demand.
-
-## UI integration (macOS app)
-### IPC
-- Unix socket at `~/.clawdbot/exec-approvals.sock`.
-- Runner connects and sends an approval request; UI responds with a decision.
-- Token stored in `exec-approvals.json`.
-
-### Ask flow
-1) Runner receives `system.run` from gateway.
-2) If ask required, runner connects to the socket and sends a prompt request.
-3) UI shows dialog; returns decision.
-4) Runner enforces decision and proceeds.
-
-If UI missing:
-- Apply `askFallback` (`deny|allowlist|full`).
-
-## Node identity + binding
-- Use existing `nodeId` from Bridge pairing.
-- Binding model:
-  - `tools.exec.node` restricts the agent to a specific node.
-  - If unset, agent can pick any node (policy still enforces defaults).
-- Node selection resolution:
-  - `nodeId` exact match
-  - `displayName` (normalized)
-  - `remoteIp`
-  - `nodeId` prefix (>= 6 chars)
-
-## Eventing
-### Who sees events
-- System events are **per session** and shown to the agent on the next prompt.
-- Stored in the gateway in-memory queue (`enqueueSystemEvent`).
-
-### Event text
-- `Exec started (host=node, node=<id>, id=<runId>)`
-- `Exec finished (exit=<code>, tail=<...>)`
-- `Exec denied (policy=<...>, reason=<...>)`
-
-### Transport
-Option A (recommended):
-- Runner sends Bridge `event` frames `exec.started` / `exec.finished`.
-- Gateway `handleBridgeEvent` maps these into `enqueueSystemEvent`.
-
-Option B:
-- Gateway `exec` tool handles lifecycle directly (synchronous only).
-
-## Exec flows
-### Sandbox host
-- Existing `exec` behavior (Docker or host when unsandboxed).
-- PTY supported in non-sandbox mode only.
-
-### Gateway host
-- Gateway process executes on its own machine.
-- Enforces local `exec-approvals.json` (security/ask/allowlist).
-
-### Node host
-- Gateway calls `node.invoke` with `system.run`.
-- Runner enforces local approvals.
-- Runner returns aggregated stdout/stderr.
-- Optional Bridge events for start/finish/deny.
-
-## Output caps
-- Cap combined stdout+stderr at **200k**; keep **tail 20k** for events.
-- Truncate with a clear suffix (e.g., `"… (truncated)"`).
-
-## Slash commands
-- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>`
-- Per-agent, per-session overrides; non-persistent unless saved via config.
-- `/elevated on|off` remains a shortcut for `host=gateway security=full`.
-
-## Cross-platform story
-- The runner service is the portable execution target.
-- UI is optional; if missing, `askFallback` applies.
-- Windows/Linux support the same approvals JSON + socket protocol.
-
-## Implementation phases
-### Phase 1: config + exec routing
-- Add config schema for `exec.host`, `exec.security`, `exec.ask`, `exec.node`.
-- Update tool plumbing to respect `exec.host`.
-- Add `/exec` slash command and keep `/elevated` alias.
-
-### Phase 2: approvals store + gateway enforcement
-- Implement `exec-approvals.json` reader/writer.
-- Enforce allowlist + ask modes for `gateway` host.
-- Add output caps.
-
-### Phase 3: node runner enforcement
-- Update node runner to enforce allowlist + ask.
-- Add Unix socket prompt bridge to macOS app UI.
-- Wire `askFallback`.
-
-### Phase 4: events
-- Add node → gateway Bridge events for exec lifecycle.
-- Map to `enqueueSystemEvent` for agent prompts.
-
-### Phase 5: UI polish
-- Mac app: allowlist editor, per-agent switcher, ask policy UI.
-- Node binding controls (optional).
-
-## Testing plan
-- Unit tests: allowlist matching (glob + case-insensitive).
-- Unit tests: policy resolution precedence (tool param → agent override → global).
-- Integration tests: node runner deny/allow/ask flows.
-- Bridge event tests: node event → system event routing.
-
-## Open risks
-- UI unavailability: ensure `askFallback` is respected.
-- Long-running commands: rely on timeout + output caps.
-- Multi-node ambiguity: error unless node binding or explicit node param.
-
-## Related docs
-- [Exec tool](/tools/exec)
-- [Exec approvals](/tools/exec-approvals)
-- [Nodes](/nodes)
-- [Elevated mode](/tools/elevated)

docs/refactor/plugin-sdk.md

@@ -1,187 +0,0 @@
----
-summary: "Plan: one clean plugin SDK + runtime for all messaging connectors"
-read_when:
-  - Defining or refactoring the plugin architecture
-  - Migrating channel connectors to the plugin SDK/runtime
----
-# Plugin SDK + Runtime Refactor Plan
-
-Goal: every messaging connector is a plugin (bundled or external) using one stable API.
-No plugin imports from `src/**` directly. All dependencies go through the SDK or runtime.
-
-## Why now
-- Current connectors mix patterns: direct core imports, dist-only bridges, and custom helpers.
-- This makes upgrades brittle and blocks a clean external plugin surface.
-
-## Target architecture (two layers)
-
-### 1) Plugin SDK (compile-time, stable, publishable)
-Scope: types, helpers, and config utilities. No runtime state, no side effects.
-
-Contents (examples):
-- Types: `ChannelPlugin`, adapters, `ChannelMeta`, `ChannelCapabilities`, `ChannelDirectoryEntry`.
-- Config helpers: `buildChannelConfigSchema`, `setAccountEnabledInConfigSection`, `deleteAccountFromConfigSection`,
-  `applyAccountNameToChannelSection`.
-- Pairing helpers: `PAIRING_APPROVED_MESSAGE`, `formatPairingApproveHint`.
-- Onboarding helpers: `promptChannelAccessConfig`, `addWildcardAllowFrom`, onboarding types.
-- Tool param helpers: `createActionGate`, `readStringParam`, `readNumberParam`, `readReactionParams`, `jsonResult`.
-- Docs link helper: `formatDocsLink`.
-
-Delivery:
-- Publish as `@clawdbot/plugin-sdk` (or export from core under `clawdbot/plugin-sdk`).
-- Semver with explicit stability guarantees.
-
-### 2) Plugin Runtime (execution surface, injected)
-Scope: everything that touches core runtime behavior.
-Accessed via `ClawdbotPluginApi.runtime` so plugins never import `src/**`.
-
-Proposed surface (minimal but complete):
-```ts
-export type PluginRuntime = {
-  channel: {
-    text: {
-      chunkMarkdownText(text: string, limit: number): string[];
-      resolveTextChunkLimit(cfg: ClawdbotConfig, channel: string, accountId?: string): number;
-      hasControlCommand(text: string, cfg: ClawdbotConfig): boolean;
-    };
-    reply: {
-      dispatchReplyWithBufferedBlockDispatcher(params: {
-        ctx: unknown;
-        cfg: unknown;
-        dispatcherOptions: {
-          deliver: (payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string }) =>
-            void | Promise<void>;
-          onError?: (err: unknown, info: { kind: string }) => void;
-        };
-      }): Promise<void>;
-      createReplyDispatcherWithTyping?: unknown; // adapter for Teams-style flows
-    };
-    routing: {
-      resolveAgentRoute(params: {
-        cfg: unknown;
-        channel: string;
-        accountId: string;
-        peer: { kind: "dm" | "group" | "channel"; id: string };
-      }): { sessionKey: string; accountId: string };
-    };
-    pairing: {
-      buildPairingReply(params: { channel: string; idLine: string; code: string }): string;
-      readAllowFromStore(channel: string): Promise<string[]>;
-      upsertPairingRequest(params: {
-        channel: string;
-        id: string;
-        meta?: { name?: string };
-      }): Promise<{ code: string; created: boolean }>;
-    };
-    media: {
-      fetchRemoteMedia(params: { url: string }): Promise<{ buffer: Buffer; contentType?: string }>;
-      saveMediaBuffer(
-        buffer: Uint8Array,
-        contentType: string | undefined,
-        direction: "inbound" | "outbound",
-        maxBytes: number,
-      ): Promise<{ path: string; contentType?: string }>;
-    };
-    mentions: {
-      buildMentionRegexes(cfg: ClawdbotConfig, agentId?: string): RegExp[];
-      matchesMentionPatterns(text: string, regexes: RegExp[]): boolean;
-    };
-    groups: {
-      resolveGroupPolicy(cfg: ClawdbotConfig, channel: string, accountId: string, groupId: string): {
-        allowlistEnabled: boolean;
-        allowed: boolean;
-        groupConfig?: unknown;
-        defaultConfig?: unknown;
-      };
-      resolveRequireMention(
-        cfg: ClawdbotConfig,
-        channel: string,
-        accountId: string,
-        groupId: string,
-        override?: boolean,
-      ): boolean;
-    };
-    debounce: {
-      createInboundDebouncer<T>(opts: {
-        debounceMs: number;
-        buildKey: (v: T) => string | null;
-        shouldDebounce: (v: T) => boolean;
-        onFlush: (entries: T[]) => Promise<void>;
-        onError?: (err: unknown) => void;
-      }): { push: (v: T) => void; flush: () => Promise<void> };
-      resolveInboundDebounceMs(cfg: ClawdbotConfig, channel: string): number;
-    };
-    commands: {
-      resolveCommandAuthorizedFromAuthorizers(params: {
-        useAccessGroups: boolean;
-        authorizers: Array<{ configured: boolean; allowed: boolean }>;
-      }): boolean;
-    };
-  };
-  logging: {
-    shouldLogVerbose(): boolean;
-    getChildLogger(name: string): PluginLogger;
-  };
-  state: {
-    resolveStateDir(cfg: ClawdbotConfig): string;
-  };
-};
-```
-
-Notes:
-- Runtime is the only way to access core behavior.
-- SDK is intentionally small and stable.
-- Each runtime method maps to an existing core implementation (no duplication).
-
-## Migration plan (phased, safe)
-
-### Phase 0: scaffolding
-- Introduce `@clawdbot/plugin-sdk`.
-- Add `api.runtime` to `ClawdbotPluginApi` with the surface above.
-- Maintain existing imports during a transition window (deprecation warnings).
-
-### Phase 1: bridge cleanup (low risk)
-- Replace per-extension `core-bridge.ts` with `api.runtime`.
-- Migrate BlueBubbles, Zalo, Zalo Personal first (already close).
-- Remove duplicated bridge code.
-
-### Phase 2: light direct-import plugins
-- Migrate Matrix to SDK + runtime.
-- Validate onboarding, directory, group mention logic.
-
-### Phase 3: heavy direct-import plugins
-- Migrate MS Teams (largest set of runtime helpers).
-- Ensure reply/typing semantics match current behavior.
-
-### Phase 4: iMessage pluginization
-- Move iMessage into `extensions/imessage`.
-- Replace direct core calls with `api.runtime`.
-- Keep config keys, CLI behavior, and docs intact.
-
-### Phase 5: enforcement
-- Add lint rule / CI check: no `extensions/**` imports from `src/**`.
-- Add plugin SDK/version compatibility checks (runtime + SDK semver).
-
-## Compatibility and versioning
-- SDK: semver, published, documented changes.
-- Runtime: versioned per core release. Add `api.runtime.version`.
-- Plugins declare a required runtime range (e.g., `clawdbotRuntime: ">=2026.2.0"`).
-
-## Testing strategy
-- Adapter-level unit tests (runtime functions exercised with real core implementation).
-- Golden tests per plugin: ensure no behavior drift (routing, pairing, allowlist, mention gating).
-- A single end-to-end plugin sample used in CI (install + run + smoke).
-
-## Open questions
-- Where to host SDK types: separate package or core export?
-- Runtime type distribution: in SDK (types only) or in core?
-- How to expose docs links for bundled vs external plugins?
-- Do we allow limited direct core imports for in-repo plugins during transition?
-
-## Success criteria
-- All channel connectors are plugins using SDK + runtime.
-- No `extensions/**` imports from `src/**`.
-- New connector templates depend only on SDK + runtime.
-- External plugins can be developed and updated without core source access.
-
-Related docs: [Plugins](/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).

docs/start/wizard.md

@@ -293,7 +293,6 @@ Typical fields in `~/.clawdbot/clawdbot.json`:
 - `agents.defaults.model` / `models.providers` (if Minimax chosen)
 - `gateway.*` (mode, bind, auth, tailscale)
 - `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
-- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
 - `skills.install.nodeManager`
 - `wizard.lastRunAt`
 - `wizard.lastRunVersion`

docs/token-use.md

@@ -42,13 +42,13 @@ Use these in chat:
 
 - `/status` → **emoji‑rich status card** with the session model, context usage,
   last response input/output tokens, and **estimated cost** (API key only).
-- `/usage off|tokens|full` → appends a **per-response usage footer** to every reply.
+- `/cost on|off` → appends a **per-response usage line** to every reply.
   - Persists per session (stored as `responseUsage`).
   - OAuth auth **hides cost** (tokens only).
 
 Other surfaces:
 
-- **TUI/Web TUI:** `/status` + `/usage` are supported.
+- **TUI/Web TUI:** `/status` + `/cost` are supported.
 - **CLI:** `clawdbot status --usage` and `clawdbot channels list` show
   provider quota windows (not per-response costs).
 

docs/tools/elevated.md

@@ -6,8 +6,9 @@ read_when:
 # Elevated Mode (/elevated directives)
 
 ## What it does
-- `/elevated on` is a **shortcut** for `exec.host=gateway` + `exec.security=full`.
-- Only changes behavior when the agent is **sandboxed** (otherwise exec already runs on the host).
+- Elevated mode allows the exec tool to run with elevated privileges when the feature is available and the sender is approved.
+- The bash chat command (`!`; `/bash` alias) uses the same `tools.elevated` allowlists because it always runs on the host.
+- **Optional for sandboxed agents**: elevated only changes behavior when the agent is running in a sandbox. If the agent already runs unsandboxed, elevated is effectively a no-op.
 - Directive forms: `/elevated on`, `/elevated off`, `/elev on`, `/elev off`.
 - Only `on|off` are accepted; anything else returns a hint and does not change state.
 
@@ -16,9 +17,18 @@ read_when:
 - **Per-session state**: `/elevated on|off` sets the elevated level for the current session key.
 - **Inline directive**: `/elevated on` inside a message applies to that message only.
 - **Groups**: In group chats, elevated directives are only honored when the agent is mentioned. Command-only messages that bypass mention requirements are treated as mentioned.
-- **Host execution**: elevated forces `exec` onto the gateway host with full security.
-- **Unsandboxed agents**: no-op for location; only affects gating, logging, and status.
+- **Host execution**: elevated runs `exec` on the host (bypasses sandbox).
+- **Unsandboxed agents**: when there is no sandbox to bypass, elevated does not change where `exec` runs.
 - **Tool policy still applies**: if `exec` is denied by tool policy, elevated cannot be used.
+- **Not skill-scoped**: elevated cannot be limited to a specific skill; it only changes `exec` location.
+
+Note:
+- Sandbox on: `/elevated on` runs that `exec` command on the host.
+- Sandbox off: `/elevated on` does not change execution (already on host).
+
+## When elevated matters
+- Only impacts `exec` when the agent is running sandboxed (it drops the sandbox for that command).
+- For unsandboxed agents, elevated does not change execution; it only affects gating, logging, and status.
 
 ## Resolution order
 1. Inline directive on the message (applies only to that message).
@@ -28,7 +38,7 @@ read_when:
 ## Setting a session default
 - Send a message that is **only** the directive (whitespace allowed), e.g. `/elevated on`.
 - Confirmation reply is sent (`Elevated mode enabled.` / `Elevated mode disabled.`).
-- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies with an actionable error and does not change session state.
+- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies with an actionable error (runtime sandboxed/direct + failing config key paths) and does not change session state.
 - Send `/elevated` (or `/elevated:`) with no argument to see the current elevated level.
 
 ## Availability + allowlists

docs/tools/exec-approvals.md

@@ -1,135 +0,0 @@
----
-summary: "Exec approvals, allowlists, and sandbox escape prompts"
-read_when:
-  - Configuring exec approvals or allowlists
-  - Implementing exec approval UX in the macOS app
-  - Reviewing sandbox escape prompts and implications
----
-
-# Exec approvals
-
-Exec approvals are the **companion app guardrail** for letting a sandboxed agent run
-commands on a real host (`gateway` or `node`). Think of it like a safety interlock:
-commands are allowed only when policy + allowlist + (optional) user approval all agree.
-Exec approvals are **in addition** to tool policy and elevated gating.
-
-If the companion app UI is **not available**, any request that requires a prompt is
-resolved by the **ask fallback** (default: deny).
-
-## Where it applies
-
-Exec approvals are enforced locally on the execution host:
-- **gateway host** → `clawdbot` process on the gateway machine
-- **node host** → node runner (macOS companion app or headless node)
-
-## Settings and storage
-
-Approvals live in a local JSON file:
-
-`~/.clawdbot/exec-approvals.json`
-
-Example schema:
-```json
-{
-  "version": 1,
-  "socket": {
-    "path": "~/.clawdbot/exec-approvals.sock",
-    "token": "base64url-token"
-  },
-  "defaults": {
-    "security": "deny",
-    "ask": "on-miss",
-    "askFallback": "deny",
-    "autoAllowSkills": false
-  },
-  "agents": {
-    "main": {
-      "security": "allowlist",
-      "ask": "on-miss",
-      "askFallback": "deny",
-      "autoAllowSkills": true,
-      "allowlist": [
-        {
-          "pattern": "~/Projects/**/bin/rg",
-          "lastUsedAt": 1737150000000,
-          "lastUsedCommand": "rg -n TODO",
-          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
-        }
-      ]
-    }
-  }
-}
-```
-
-## Policy knobs
-
-### Security (`exec.security`)
-- **deny**: block all host exec requests.
-- **allowlist**: allow only allowlisted commands.
-- **full**: allow everything (equivalent to elevated).
-
-### Ask (`exec.ask`)
-- **off**: never prompt.
-- **on-miss**: prompt only when allowlist does not match.
-- **always**: prompt on every command.
-
-### Ask fallback (`askFallback`)
-If a prompt is required but no UI is reachable, fallback decides:
-- **deny**: block.
-- **allowlist**: allow only if allowlist matches.
-- **full**: allow.
-
-## Allowlist (per agent)
-
-Allowlists are **per agent**. If multiple agents exist, switch which agent you’re
-editing in the macOS app. Patterns are **case-insensitive glob matches**.
-
-Examples:
-- `~/Projects/**/bin/bird`
-- `~/.local/bin/*`
-- `/opt/homebrew/bin/rg`
-
-Each allowlist entry tracks:
-- **last used** timestamp
-- **last used command**
-- **last resolved path**
-
-## Auto-allow skill CLIs
-
-When **Auto-allow skill CLIs** is enabled, executables referenced by known skills
-are treated as allowlisted (node hosts only). Disable this if you want strict
-manual allowlists.
-
-## Approval flow
-
-When a prompt is required, the companion app displays a confirmation dialog with:
-- command + args
-- cwd
-- agent id
-- resolved executable path
-- host + policy metadata
-
-Actions:
-- **Allow once** → run now
-- **Always allow** → add to allowlist + run
-- **Deny** → block
-
-## System events
-
-Exec lifecycle is surfaced as system messages:
-- `exec.started`
-- `exec.finished`
-- `exec.denied`
-
-These are posted to the agent’s session after the node reports the event.
-
-## Implications
-
-- **full** is powerful; prefer allowlists when possible.
-- **ask** keeps you in the loop while still allowing fast approvals.
-- Per-agent allowlists prevent one agent’s approvals from leaking into others.
-
-Related:
-- [Exec tool](/tools/exec)
-- [Elevated mode](/tools/elevated)
-- [Skills](/tools/skills)

docs/tools/exec.md

@@ -14,37 +14,17 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 ## Parameters
 
 - `command` (required)
-- `workdir` (defaults to cwd)
-- `env` (key/value overrides)
 - `yieldMs` (default 10000): auto-background after delay
 - `background` (bool): background immediately
 - `timeout` (seconds, default 1800): kill on expiry
 - `pty` (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs)
-- `host` (`sandbox | gateway | node`): where to execute
-- `security` (`deny | allowlist | full`): enforcement mode for `gateway`/`node`
-- `ask` (`off | on-miss | always`): approval prompts for `gateway`/`node`
-- `node` (string): node id/name for `host=node`
-- `elevated` (bool): alias for `host=gateway` + `security=full` when sandboxed and allowed
-
-Notes:
-- `host` defaults to `sandbox`.
-- `elevated` is ignored when sandboxing is off (exec already runs on the host).
-- `gateway`/`node` approvals are controlled by `~/.clawdbot/exec-approvals.json`.
-- `node` requires a paired node (macOS companion app).
-- If multiple nodes are available, set `exec.node` or `tools.exec.node` to select one.
+- `elevated` (bool): run on host if elevated mode is enabled/allowed (only changes behavior when the agent is sandboxed)
+- Need a fully interactive session? Use `pty: true` and the `process` tool for stdin/output.
+Note: `elevated` is ignored when sandboxing is off (exec already runs on the host).
 
 ## Config
 
 - `tools.exec.notifyOnExit` (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.
-- `tools.exec.host` (default: `sandbox`)
-- `tools.exec.security` (default: `deny`)
-- `tools.exec.ask` (default: `on-miss`)
-- `tools.exec.node` (default: unset)
-
-## Exec approvals (macOS app)
-
-Sandboxed agents can require per-request approval before `exec` runs on the gateway or node host.
-See [Exec approvals](/tools/exec-approvals) for the policy, allowlist, and UI flow.
 
 ## Examples
 

docs/tools/index.md

@@ -169,19 +169,14 @@ Core parameters:
 - `background` (immediate background)
 - `timeout` (seconds; kills the process if exceeded, default 1800)
 - `elevated` (bool; run on host if elevated mode is enabled/allowed; only changes behavior when the agent is sandboxed)
-- `host` (`sandbox | gateway | node`)
-- `security` (`deny | allowlist | full`)
-- `ask` (`off | on-miss | always`)
-- `node` (node id/name for `host=node`)
 - Need a real TTY? Set `pty: true`.
 
 Notes:
 - Returns `status: "running"` with a `sessionId` when backgrounded.
 - Use `process` to poll/log/write/kill/clear background sessions.
 - If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
-- `elevated` is gated by `tools.elevated` plus any `agents.list[].tools.elevated` override (both must allow) and is an alias for `host=gateway` + `security=full`.
+- `elevated` is gated by `tools.elevated` plus any `agents.list[].tools.elevated` override (both must allow) and runs on the host.
 - `elevated` only changes behavior when the agent is sandboxed (otherwise it’s a no-op).
-- gateway/node approvals and allowlists: [Exec approvals](/tools/exec-approvals).
 
 ### `process`
 Manage background exec sessions.

docs/tools/slash-commands.md

@@ -17,7 +17,7 @@ There are two related systems:
   - In normal chat messages (not directive-only), they are treated as “inline hints” and do **not** persist session settings.
   - In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
 
-There are also a few **inline shortcuts** (allowlisted/authorized senders only): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
+There are also a few **inline shortcuts** (allowlisted/authorized senders only): `/help`, `/commands`, `/status` (`/usage`), `/whoami` (`/id`).
 They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
 
 ## Config
@@ -60,11 +60,11 @@ Text + native (when enabled):
 - `/commands`
 - `/status` (show current status; includes provider usage/quota for the current model provider when available)
 - `/context [list|detail|json]` (explain “context”; `detail` shows per-file + per-tool + per-skill + system prompt size)
+- `/usage` (alias: `/status`)
 - `/whoami` (show your sender id; alias: `/id`)
-- `/subagents list|stop|log|info|send` (inspect, stop, log, or message sub-agent runs for the current session)
 - `/config show|get|set|unset` (persist config to disk, owner-only; requires `commands.config: true`)
 - `/debug show|set|unset|reset` (runtime overrides, owner-only; requires `commands.debug: true`)
-- `/usage off|tokens|full` (per-response usage footer)
+- `/cost on|off` (toggle per-response usage line)
 - `/stop`
 - `/restart`
 - `/dock-telegram` (alias: `/dock_telegram`) (switch replies to Telegram)
@@ -89,8 +89,8 @@ Text-only:
 
 Notes:
 - Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
-- For full provider usage breakdown, use `clawdbot status --usage`.
-- `/usage` controls the per-response usage footer. It only shows dollar cost when the model uses an API key (OAuth hides cost).
+- `/status` and `/usage` show the same status output; for full provider usage breakdown, use `clawdbot status --usage`.
+- `/cost` appends per-response token usage; it only shows dollar cost when the model uses an API key (OAuth hides cost).
 - `/restart` is disabled by default; set `commands.restart: true` to enable it.
 - `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
 - `/reasoning` (and `/verbose`) are risky in group settings: they may reveal internal reasoning or tool output you did not intend to expose. Prefer leaving them off, especially in group chats.
@@ -98,15 +98,15 @@ Notes:
 - **Group mention gating:** command-only messages from allowlisted senders bypass mention requirements.
 - **Inline shortcuts (allowlisted senders only):** certain commands also work when embedded in a normal message and are stripped before the model sees the remaining text.
   - Example: `hey /status` triggers a status reply, and the remaining text continues through the normal flow.
-- Currently: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
+  - Currently: `/help`, `/commands`, `/status` (`/usage`), `/whoami` (`/id`).
 - Unauthorized command-only messages are silently ignored, and inline `/...` tokens are treated as plain text.
 - **Skill commands:** `user-invocable` skills are exposed as slash commands. Names are sanitized to `a-z0-9_` (max 32 chars); collisions get numeric suffixes (e.g. `_2`).
 - **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg.
 
-## Usage surfaces (what shows where)
+## Usage vs cost (what shows where)
 
 - **Provider usage/quota** (example: “Claude 80% left”) shows up in `/status` for the current model provider when usage tracking is enabled.
-- **Per-response tokens/cost** is controlled by `/usage off|tokens|full` (appended to normal replies).
+- **Per-response tokens/cost** is controlled by `/cost on|off` (appended to normal replies).
 - `/model status` is about **models/auth/endpoints**, not usage.
 
 ## Model selection (`/model`)

docs/tools/subagents.md

@@ -9,17 +9,6 @@ read_when:
 
 Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel.
 
-## Slash command
-
-Use `/subagents` to inspect or control sub-agent runs for the **current session**:
-- `/subagents list`
-- `/subagents stop <id|#|all>`
-- `/subagents log <id|#> [limit] [tools]`
-- `/subagents info <id|#>`
-- `/subagents send <id|#> <message>`
-
-`/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup).
-
 Primary goals:
 - Parallelize “research / long task / slow tool” work without blocking the main run.
 - Keep sub-agents isolated by default (session separation + optional sandboxing).

docs/tools/web.md

@@ -1,5 +1,5 @@
 ---
-summary: "Web search + fetch tools (Brave Search API, Perplexity direct/OpenRouter)"
+summary: "Web search + fetch tools (Brave Search API, Perplexity Sonar)"
 read_when:
   - You want to enable web_search or web_fetch
   - You need Brave Search API key setup
@@ -10,7 +10,7 @@ read_when:
 
 Clawdbot ships two lightweight web tools:
 
-- `web_search` — Search the web via Brave Search API (default) or Perplexity Sonar (via OpenRouter).
+- `web_search` — Search the web via Brave Search API (default) or Perplexity Sonar (direct or via OpenRouter).
 - `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).
 
 These are **not** browser automation. For JS-heavy sites or logins, use the
@@ -28,12 +28,12 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
 
 ## Choosing a search provider
 
+Provider docs: [Brave Search API](https://brave.com/search/api/) and [Perplexity Sonar](/perplexity).
+
 | Provider | Pros | Cons | API Key |
 |----------|------|------|---------|
 | **Brave** (default) | Fast, structured results, free tier | Traditional search results | `BRAVE_API_KEY` |
-| **Perplexity** | AI-synthesized answers, citations, real-time | Requires OpenRouter credits | `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` |
-
-See [Brave Search setup](/brave-search) and [Perplexity Sonar](/perplexity) for provider-specific details.
+| **Perplexity** | AI-synthesized answers, citations, real-time | Requires Perplexity or OpenRouter credits | `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY` |
 
 Set the provider in config:
 
@@ -49,25 +49,6 @@ Set the provider in config:
 }
 ```
 
-Example: switch to Perplexity Sonar (direct API):
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-          model: "perplexity/sonar-pro"
-        }
-      }
-    }
-  }
-}
-```
-
 ## Getting a Brave API key
 
 1) Create a Brave Search API account at https://brave.com/search/api/
@@ -86,13 +67,22 @@ current limits and pricing.
 environment. For a daemon install, put it in `~/.clawdbot/.env` (or your
 service environment). See [Env vars](/start/faq#how-does-clawdbot-load-environment-variables).
 
-## Using Perplexity (direct or via OpenRouter)
+## Using Perplexity Sonar
 
 Perplexity Sonar models have built-in web search capabilities and return AI-synthesized
-answers with citations. You can use them via OpenRouter (no credit card required - supports
-crypto/prepaid).
+answers with citations. You can use them either directly via Perplexity’s API or via OpenRouter
+(supports crypto/prepaid).
 
-### Getting an OpenRouter API key
+See [Perplexity Sonar](/perplexity) for a dedicated setup guide.
+
+### Getting an API key
+
+**Perplexity (direct):**
+
+1) Create a Perplexity account and generate an API key.
+2) Set `PERPLEXITY_API_KEY` in the Gateway environment or store the key in config.
+
+**OpenRouter (alternative):**
 
 1) Create an account at https://openrouter.ai/
 2) Add credits (supports crypto, prepaid, or credit card)
@@ -109,9 +99,11 @@ crypto/prepaid).
         provider: "perplexity",
         perplexity: {
           // API key (optional if OPENROUTER_API_KEY or PERPLEXITY_API_KEY is set)
-          apiKey: "sk-or-v1-...",
-          // Base URL (defaults to OpenRouter)
-          baseUrl: "https://openrouter.ai/api/v1",
+          apiKey: "pplx-... or sk-or-v1-...",
+          // Base URL:
+          // - https://api.perplexity.ai (default when PERPLEXITY_API_KEY is set)
+          // - https://openrouter.ai/api/v1 (default when only OPENROUTER_API_KEY is set)
+          baseUrl: "https://api.perplexity.ai",
           // Model (defaults to perplexity/sonar-pro)
           model: "perplexity/sonar-pro"
         }
@@ -121,11 +113,9 @@ crypto/prepaid).
 }
 ```
 
-**Environment alternative:** set `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` in the Gateway
-environment. For a daemon install, put it in `~/.clawdbot/.env`.
-
-If `PERPLEXITY_API_KEY` is used from the environment and no base URL is set,
-Clawdbot defaults to the direct Perplexity endpoint (`https://api.perplexity.ai`).
+**Environment alternative:** set `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY` in the Gateway
+environment. For a daemon install, put it in `~/.clawdbot/.env`. If you set both keys, set
+`tools.web.search.perplexity.baseUrl` (or `tools.web.search.perplexity.apiKey`) to disambiguate.
 
 ### Available Perplexity models
 
@@ -144,7 +134,7 @@ Search the web using your configured provider.
 - `tools.web.search.enabled` must not be `false` (default: enabled)
 - API key for your chosen provider:
   - **Brave**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
-  - **Perplexity**: `OPENROUTER_API_KEY`, `PERPLEXITY_API_KEY`, or `tools.web.search.perplexity.apiKey`
+  - **Perplexity**: `PERPLEXITY_API_KEY` (direct), `OPENROUTER_API_KEY` (OpenRouter), or `tools.web.search.perplexity.apiKey`
 
 ### Config
 

docs/tui.md

@@ -77,7 +77,7 @@ Session controls:
 - `/think <off|minimal|low|medium|high>`
 - `/verbose <on|full|off>`
 - `/reasoning <on|off|stream>`
-- `/usage <off|tokens|full>`
+- `/cost <on|off>`
 - `/elevated <on|off>` (alias: `/elev`)
 - `/activation <mention|always>`
 - `/deliver <on|off>`

extensions/bluebubbles/index.ts

@@ -1,18 +0,0 @@
-import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
-
-import { bluebubblesPlugin } from "./src/channel.js";
-import { handleBlueBubblesWebhookRequest } from "./src/monitor.js";
-import { setBlueBubblesRuntime } from "./src/runtime.js";
-
-const plugin = {
-  id: "bluebubbles",
-  name: "BlueBubbles",
-  description: "BlueBubbles channel plugin (macOS app)",
-  register(api: ClawdbotPluginApi) {
-    setBlueBubblesRuntime(api.runtime);
-    api.registerChannel({ plugin: bluebubblesPlugin });
-    api.registerHttpHandler(handleBlueBubblesWebhookRequest);
-  },
-};
-
-export default plugin;

extensions/bluebubbles/package.json

@@ -1,9 +0,0 @@
-{
-  "name": "@clawdbot/bluebubbles",
-  "version": "2026.1.15",
-  "type": "module",
-  "description": "Clawdbot BlueBubbles channel plugin",
-  "clawdbot": {
-    "extensions": ["./index.ts"]
-  }
-}

extensions/bluebubbles/src/accounts.ts

@@ -1,79 +0,0 @@
-import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
-import { normalizeBlueBubblesServerUrl, type BlueBubblesAccountConfig } from "./types.js";
-
-export type ResolvedBlueBubblesAccount = {
-  accountId: string;
-  enabled: boolean;
-  name?: string;
-  config: BlueBubblesAccountConfig;
-  configured: boolean;
-  baseUrl?: string;
-};
-
-function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
-  const accounts = cfg.channels?.bluebubbles?.accounts;
-  if (!accounts || typeof accounts !== "object") return [];
-  return Object.keys(accounts).filter(Boolean);
-}
-
-export function listBlueBubblesAccountIds(cfg: ClawdbotConfig): string[] {
-  const ids = listConfiguredAccountIds(cfg);
-  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
-  return ids.sort((a, b) => a.localeCompare(b));
-}
-
-export function resolveDefaultBlueBubblesAccountId(cfg: ClawdbotConfig): string {
-  const ids = listBlueBubblesAccountIds(cfg);
-  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
-  return ids[0] ?? DEFAULT_ACCOUNT_ID;
-}
-
-function resolveAccountConfig(
-  cfg: ClawdbotConfig,
-  accountId: string,
-): BlueBubblesAccountConfig | undefined {
-  const accounts = cfg.channels?.bluebubbles?.accounts;
-  if (!accounts || typeof accounts !== "object") return undefined;
-  return accounts[accountId] as BlueBubblesAccountConfig | undefined;
-}
-
-function mergeBlueBubblesAccountConfig(
-  cfg: ClawdbotConfig,
-  accountId: string,
-): BlueBubblesAccountConfig {
-  const base = (cfg.channels?.bluebubbles ?? {}) as BlueBubblesAccountConfig & {
-    accounts?: unknown;
-  };
-  const { accounts: _ignored, ...rest } = base;
-  const account = resolveAccountConfig(cfg, accountId) ?? {};
-  return { ...rest, ...account };
-}
-
-export function resolveBlueBubblesAccount(params: {
-  cfg: ClawdbotConfig;
-  accountId?: string | null;
-}): ResolvedBlueBubblesAccount {
-  const accountId = normalizeAccountId(params.accountId);
-  const baseEnabled = params.cfg.channels?.bluebubbles?.enabled;
-  const merged = mergeBlueBubblesAccountConfig(params.cfg, accountId);
-  const accountEnabled = merged.enabled !== false;
-  const serverUrl = merged.serverUrl?.trim();
-  const password = merged.password?.trim();
-  const configured = Boolean(serverUrl && password);
-  const baseUrl = serverUrl ? normalizeBlueBubblesServerUrl(serverUrl) : undefined;
-  return {
-    accountId,
-    enabled: baseEnabled !== false && accountEnabled,
-    name: merged.name?.trim() || undefined,
-    config: merged,
-    configured,
-    baseUrl,
-  };
-}
-
-export function listEnabledBlueBubblesAccounts(cfg: ClawdbotConfig): ResolvedBlueBubblesAccount[] {
-  return listBlueBubblesAccountIds(cfg)
-    .map((accountId) => resolveBlueBubblesAccount({ cfg, accountId }))
-    .filter((account) => account.enabled);
-}

extensions/bluebubbles/src/actions.ts

@@ -1,121 +0,0 @@
-import {
-  createActionGate,
-  jsonResult,
-  readNumberParam,
-  readReactionParams,
-  readStringParam,
-  type ChannelMessageActionAdapter,
-  type ChannelMessageActionName,
-  type ChannelToolSend,
-  type ClawdbotConfig,
-} from "clawdbot/plugin-sdk";
-
-import { resolveBlueBubblesAccount } from "./accounts.js";
-import { sendBlueBubblesReaction } from "./reactions.js";
-import { resolveChatGuidForTarget } from "./send.js";
-import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.js";
-import type { BlueBubblesSendTarget } from "./types.js";
-
-const providerId = "bluebubbles";
-
-function mapTarget(raw: string): BlueBubblesSendTarget {
-  const parsed = parseBlueBubblesTarget(raw);
-  if (parsed.kind === "chat_guid") return { kind: "chat_guid", chatGuid: parsed.chatGuid };
-  if (parsed.kind === "chat_id") return { kind: "chat_id", chatId: parsed.chatId };
-  if (parsed.kind === "chat_identifier") {
-    return { kind: "chat_identifier", chatIdentifier: parsed.chatIdentifier };
-  }
-  return {
-    kind: "handle",
-    address: normalizeBlueBubblesHandle(parsed.to),
-    service: parsed.service,
-  };
-}
-
-export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
-  listActions: ({ cfg }) => {
-    const account = resolveBlueBubblesAccount({ cfg: cfg as ClawdbotConfig });
-    if (!account.enabled || !account.configured) return [];
-    const gate = createActionGate((cfg as ClawdbotConfig).channels?.bluebubbles?.actions);
-    const actions = new Set<ChannelMessageActionName>();
-    if (gate("reactions")) actions.add("react");
-    return Array.from(actions);
-  },
-  supportsAction: ({ action }) => action === "react",
-  extractToolSend: ({ args }): ChannelToolSend | null => {
-    const action = typeof args.action === "string" ? args.action.trim() : "";
-    if (action !== "sendMessage") return null;
-    const to = typeof args.to === "string" ? args.to : undefined;
-    if (!to) return null;
-    const accountId = typeof args.accountId === "string" ? args.accountId.trim() : undefined;
-    return { to, accountId };
-  },
-  handleAction: async ({ action, params, cfg, accountId }) => {
-    if (action !== "react") {
-      throw new Error(`Action ${action} is not supported for provider ${providerId}.`);
-    }
-    const { emoji, remove, isEmpty } = readReactionParams(params, {
-      removeErrorMessage: "Emoji is required to remove a BlueBubbles reaction.",
-    });
-    if (isEmpty && !remove) {
-      throw new Error("Emoji is required to send a BlueBubbles reaction.");
-    }
-    const messageId = readStringParam(params, "messageId", { required: true });
-    const chatGuid = readStringParam(params, "chatGuid");
-    const chatIdentifier = readStringParam(params, "chatIdentifier");
-    const chatId = readNumberParam(params, "chatId", { integer: true });
-    const to = readStringParam(params, "to");
-    const partIndex = readNumberParam(params, "partIndex", { integer: true });
-
-    const account = resolveBlueBubblesAccount({
-      cfg: cfg as ClawdbotConfig,
-      accountId: accountId ?? undefined,
-    });
-    const baseUrl = account.config.serverUrl?.trim();
-    const password = account.config.password?.trim();
-
-    let resolvedChatGuid = chatGuid?.trim() || "";
-    if (!resolvedChatGuid) {
-      const target =
-        chatIdentifier?.trim()
-          ? ({ kind: "chat_identifier", chatIdentifier: chatIdentifier.trim() } as BlueBubblesSendTarget)
-          : typeof chatId === "number"
-            ? ({ kind: "chat_id", chatId } as BlueBubblesSendTarget)
-            : to
-              ? mapTarget(to)
-              : null;
-      if (!target) {
-        throw new Error("BlueBubbles reaction requires chatGuid, chatIdentifier, chatId, or to.");
-      }
-      if (!baseUrl || !password) {
-        throw new Error("BlueBubbles reaction requires serverUrl and password.");
-      }
-      resolvedChatGuid =
-        (await resolveChatGuidForTarget({
-          baseUrl,
-          password,
-          target,
-        })) ?? "";
-    }
-    if (!resolvedChatGuid) {
-      throw new Error("BlueBubbles reaction failed: chatGuid not found for target.");
-    }
-
-    await sendBlueBubblesReaction({
-      chatGuid: resolvedChatGuid,
-      messageGuid: messageId,
-      emoji,
-      remove: remove || undefined,
-      partIndex: typeof partIndex === "number" ? partIndex : undefined,
-      opts: {
-        cfg: cfg as ClawdbotConfig,
-        accountId: accountId ?? undefined,
-      },
-    });
-
-    if (!remove) {
-      return jsonResult({ ok: true, added: emoji });
-    }
-    return jsonResult({ ok: true, removed: true });
-  },
-};

extensions/bluebubbles/src/attachments.ts

@@ -1,57 +0,0 @@
-import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
-import { resolveBlueBubblesAccount } from "./accounts.js";
-import {
-  blueBubblesFetchWithTimeout,
-  buildBlueBubblesApiUrl,
-  type BlueBubblesAttachment,
-} from "./types.js";
-
-export type BlueBubblesAttachmentOpts = {
-  serverUrl?: string;
-  password?: string;
-  accountId?: string;
-  timeoutMs?: number;
-  cfg?: ClawdbotConfig;
-};
-
-const DEFAULT_ATTACHMENT_MAX_BYTES = 8 * 1024 * 1024;
-
-function resolveAccount(params: BlueBubblesAttachmentOpts) {
-  const account = resolveBlueBubblesAccount({
-    cfg: params.cfg ?? {},
-    accountId: params.accountId,
-  });
-  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = params.password?.trim() || account.config.password?.trim();
-  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
-  if (!password) throw new Error("BlueBubbles password is required");
-  return { baseUrl, password };
-}
-
-export async function downloadBlueBubblesAttachment(
-  attachment: BlueBubblesAttachment,
-  opts: BlueBubblesAttachmentOpts & { maxBytes?: number } = {},
-): Promise<{ buffer: Uint8Array; contentType?: string }> {
-  const guid = attachment.guid?.trim();
-  if (!guid) throw new Error("BlueBubbles attachment guid is required");
-  const { baseUrl, password } = resolveAccount(opts);
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
-    path: `/api/v1/attachment/${encodeURIComponent(guid)}/download`,
-    password,
-  });
-  const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, opts.timeoutMs);
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(
-      `BlueBubbles attachment download failed (${res.status}): ${errorText || "unknown"}`,
-    );
-  }
-  const contentType = res.headers.get("content-type") ?? undefined;
-  const buf = new Uint8Array(await res.arrayBuffer());
-  const maxBytes = typeof opts.maxBytes === "number" ? opts.maxBytes : DEFAULT_ATTACHMENT_MAX_BYTES;
-  if (buf.byteLength > maxBytes) {
-    throw new Error(`BlueBubbles attachment too large (${buf.byteLength} bytes)`);
-  }
-  return { buffer: buf, contentType: contentType ?? attachment.mimeType ?? undefined };
-}

extensions/bluebubbles/src/channel.ts

@@ -1,284 +0,0 @@
-import type { ChannelAccountSnapshot, ChannelPlugin, ClawdbotConfig } from "clawdbot/plugin-sdk";
-import {
-  applyAccountNameToChannelSection,
-  buildChannelConfigSchema,
-  DEFAULT_ACCOUNT_ID,
-  deleteAccountFromConfigSection,
-  formatPairingApproveHint,
-  migrateBaseNameToDefaultAccount,
-  normalizeAccountId,
-  PAIRING_APPROVED_MESSAGE,
-  setAccountEnabledInConfigSection,
-} from "clawdbot/plugin-sdk";
-
-import {
-  listBlueBubblesAccountIds,
-  type ResolvedBlueBubblesAccount,
-  resolveBlueBubblesAccount,
-  resolveDefaultBlueBubblesAccountId,
-} from "./accounts.js";
-import { BlueBubblesConfigSchema } from "./config-schema.js";
-import { probeBlueBubbles } from "./probe.js";
-import { sendMessageBlueBubbles } from "./send.js";
-import { normalizeBlueBubblesHandle } from "./targets.js";
-import { bluebubblesMessageActions } from "./actions.js";
-import { monitorBlueBubblesProvider, resolveWebhookPathFromConfig } from "./monitor.js";
-
-const meta = {
-  id: "bluebubbles",
-  label: "BlueBubbles",
-  selectionLabel: "BlueBubbles (macOS app)",
-  docsPath: "/channels/bluebubbles",
-  docsLabel: "bluebubbles",
-  blurb: "iMessage via the BlueBubbles mac app + REST API.",
-  order: 75,
-};
-
-export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
-  id: "bluebubbles",
-  meta,
-  capabilities: {
-    chatTypes: ["direct", "group"],
-    media: false,
-    reactions: true,
-  },
-  reload: { configPrefixes: ["channels.bluebubbles"] },
-  configSchema: buildChannelConfigSchema(BlueBubblesConfigSchema),
-  config: {
-    listAccountIds: (cfg) => listBlueBubblesAccountIds(cfg as ClawdbotConfig),
-    resolveAccount: (cfg, accountId) =>
-      resolveBlueBubblesAccount({ cfg: cfg as ClawdbotConfig, accountId }),
-    defaultAccountId: (cfg) => resolveDefaultBlueBubblesAccountId(cfg as ClawdbotConfig),
-    setAccountEnabled: ({ cfg, accountId, enabled }) =>
-      setAccountEnabledInConfigSection({
-        cfg: cfg as ClawdbotConfig,
-        sectionKey: "bluebubbles",
-        accountId,
-        enabled,
-        allowTopLevel: true,
-      }),
-    deleteAccount: ({ cfg, accountId }) =>
-      deleteAccountFromConfigSection({
-        cfg: cfg as ClawdbotConfig,
-        sectionKey: "bluebubbles",
-        accountId,
-        clearBaseFields: ["serverUrl", "password", "name", "webhookPath"],
-      }),
-    isConfigured: (account) => account.configured,
-    describeAccount: (account): ChannelAccountSnapshot => ({
-      accountId: account.accountId,
-      name: account.name,
-      enabled: account.enabled,
-      configured: account.configured,
-      baseUrl: account.baseUrl,
-    }),
-    resolveAllowFrom: ({ cfg, accountId }) =>
-      (resolveBlueBubblesAccount({ cfg: cfg as ClawdbotConfig, accountId }).config.allowFrom ??
-        []).map(
-        (entry) => String(entry),
-      ),
-    formatAllowFrom: ({ allowFrom }) =>
-      allowFrom
-        .map((entry) => String(entry).trim())
-        .filter(Boolean)
-        .map((entry) => entry.replace(/^bluebubbles:/i, ""))
-        .map((entry) => normalizeBlueBubblesHandle(entry)),
-  },
-  actions: bluebubblesMessageActions,
-  security: {
-    resolveDmPolicy: ({ cfg, accountId, account }) => {
-      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
-      const useAccountPath = Boolean(
-        (cfg as ClawdbotConfig).channels?.bluebubbles?.accounts?.[resolvedAccountId],
-      );
-      const basePath = useAccountPath
-        ? `channels.bluebubbles.accounts.${resolvedAccountId}.`
-        : "channels.bluebubbles.";
-      return {
-        policy: account.config.dmPolicy ?? "pairing",
-        allowFrom: account.config.allowFrom ?? [],
-        policyPath: `${basePath}dmPolicy`,
-        allowFromPath: basePath,
-        approveHint: formatPairingApproveHint("bluebubbles"),
-        normalizeEntry: (raw) => normalizeBlueBubblesHandle(raw.replace(/^bluebubbles:/i, "")),
-      };
-    },
-    collectWarnings: ({ account }) => {
-      const groupPolicy = account.config.groupPolicy ?? "allowlist";
-      if (groupPolicy !== "open") return [];
-      return [
-        `- BlueBubbles groups: groupPolicy="open" allows any member to trigger the bot. Set channels.bluebubbles.groupPolicy="allowlist" + channels.bluebubbles.groupAllowFrom to restrict senders.`,
-      ];
-    },
-  },
-  setup: {
-    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
-    applyAccountName: ({ cfg, accountId, name }) =>
-      applyAccountNameToChannelSection({
-        cfg: cfg as ClawdbotConfig,
-        channelKey: "bluebubbles",
-        accountId,
-        name,
-      }),
-    validateInput: ({ input }) => {
-      if (!input.httpUrl && !input.password) {
-        return "BlueBubbles requires --http-url and --password.";
-      }
-      if (!input.httpUrl) return "BlueBubbles requires --http-url.";
-      if (!input.password) return "BlueBubbles requires --password.";
-      return null;
-    },
-    applyAccountConfig: ({ cfg, accountId, input }) => {
-      const namedConfig = applyAccountNameToChannelSection({
-        cfg: cfg as ClawdbotConfig,
-        channelKey: "bluebubbles",
-        accountId,
-        name: input.name,
-      });
-      const next =
-        accountId !== DEFAULT_ACCOUNT_ID
-          ? migrateBaseNameToDefaultAccount({
-              cfg: namedConfig,
-              channelKey: "bluebubbles",
-            })
-          : namedConfig;
-      if (accountId === DEFAULT_ACCOUNT_ID) {
-        return {
-          ...next,
-          channels: {
-            ...next.channels,
-            bluebubbles: {
-              ...next.channels?.bluebubbles,
-              enabled: true,
-              ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
-              ...(input.password ? { password: input.password } : {}),
-            },
-          },
-        } as ClawdbotConfig;
-      }
-      return {
-        ...next,
-        channels: {
-          ...next.channels,
-          bluebubbles: {
-            ...next.channels?.bluebubbles,
-            enabled: true,
-            accounts: {
-              ...(next.channels?.bluebubbles?.accounts ?? {}),
-              [accountId]: {
-                ...(next.channels?.bluebubbles?.accounts?.[accountId] ?? {}),
-                enabled: true,
-                ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
-                ...(input.password ? { password: input.password } : {}),
-              },
-            },
-          },
-        },
-      } as ClawdbotConfig;
-    },
-  },
-  pairing: {
-    idLabel: "bluebubblesSenderId",
-    normalizeAllowEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
-    notifyApproval: async ({ cfg, id }) => {
-      await sendMessageBlueBubbles(id, PAIRING_APPROVED_MESSAGE, {
-        cfg: cfg as ClawdbotConfig,
-      });
-    },
-  },
-  outbound: {
-    deliveryMode: "direct",
-    textChunkLimit: 4000,
-    resolveTarget: ({ to }) => {
-      const trimmed = to?.trim();
-      if (!trimmed) {
-        return {
-          ok: false,
-          error: new Error("Delivering to BlueBubbles requires --to <handle|chat_guid:GUID>"),
-        };
-      }
-      return { ok: true, to: trimmed };
-    },
-    sendText: async ({ cfg, to, text, accountId }) => {
-      const result = await sendMessageBlueBubbles(to, text, {
-        cfg: cfg as ClawdbotConfig,
-        accountId: accountId ?? undefined,
-      });
-      return { channel: "bluebubbles", ...result };
-    },
-    sendMedia: async () => {
-      throw new Error("BlueBubbles media delivery is not supported yet.");
-    },
-  },
-  status: {
-    defaultRuntime: {
-      accountId: DEFAULT_ACCOUNT_ID,
-      running: false,
-      lastStartAt: null,
-      lastStopAt: null,
-      lastError: null,
-    },
-    collectStatusIssues: (accounts) =>
-      accounts.flatMap((account) => {
-        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
-        if (!lastError) return [];
-        return [
-          {
-            channel: "bluebubbles",
-            accountId: account.accountId,
-            kind: "runtime",
-            message: `Channel error: ${lastError}`,
-          },
-        ];
-      }),
-    buildChannelSummary: ({ snapshot }) => ({
-      configured: snapshot.configured ?? false,
-      baseUrl: snapshot.baseUrl ?? null,
-      running: snapshot.running ?? false,
-      lastStartAt: snapshot.lastStartAt ?? null,
-      lastStopAt: snapshot.lastStopAt ?? null,
-      lastError: snapshot.lastError ?? null,
-      probe: snapshot.probe,
-      lastProbeAt: snapshot.lastProbeAt ?? null,
-    }),
-    probeAccount: async ({ account, timeoutMs }) =>
-      probeBlueBubbles({
-        baseUrl: account.baseUrl,
-        password: account.config.password ?? null,
-        timeoutMs,
-      }),
-    buildAccountSnapshot: ({ account, runtime, probe }) => ({
-      accountId: account.accountId,
-      name: account.name,
-      enabled: account.enabled,
-      configured: account.configured,
-      baseUrl: account.baseUrl,
-      running: runtime?.running ?? false,
-      lastStartAt: runtime?.lastStartAt ?? null,
-      lastStopAt: runtime?.lastStopAt ?? null,
-      lastError: runtime?.lastError ?? null,
-      probe,
-      lastInboundAt: runtime?.lastInboundAt ?? null,
-      lastOutboundAt: runtime?.lastOutboundAt ?? null,
-    }),
-  },
-  gateway: {
-    startAccount: async (ctx) => {
-      const account = ctx.account;
-      const webhookPath = resolveWebhookPathFromConfig(account.config);
-      ctx.setStatus({
-        accountId: account.accountId,
-        baseUrl: account.baseUrl,
-      });
-      ctx.log?.info(`[${account.accountId}] starting provider (webhook=${webhookPath})`);
-      return monitorBlueBubblesProvider({
-        account,
-        config: ctx.cfg as ClawdbotConfig,
-        runtime: ctx.runtime,
-        abortSignal: ctx.abortSignal,
-        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
-        webhookPath,
-      });
-    },
-  },
-};

extensions/bluebubbles/src/chat.ts

@@ -1,66 +0,0 @@
-import { resolveBlueBubblesAccount } from "./accounts.js";
-import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
-import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
-
-export type BlueBubblesChatOpts = {
-  serverUrl?: string;
-  password?: string;
-  accountId?: string;
-  timeoutMs?: number;
-  cfg?: ClawdbotConfig;
-};
-
-function resolveAccount(params: BlueBubblesChatOpts) {
-  const account = resolveBlueBubblesAccount({
-    cfg: params.cfg ?? {},
-    accountId: params.accountId,
-  });
-  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = params.password?.trim() || account.config.password?.trim();
-  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
-  if (!password) throw new Error("BlueBubbles password is required");
-  return { baseUrl, password };
-}
-
-export async function markBlueBubblesChatRead(
-  chatGuid: string,
-  opts: BlueBubblesChatOpts = {},
-): Promise<void> {
-  const trimmed = chatGuid.trim();
-  if (!trimmed) return;
-  const { baseUrl, password } = resolveAccount(opts);
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
-    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/read`,
-    password,
-  });
-  const res = await blueBubblesFetchWithTimeout(url, { method: "POST" }, opts.timeoutMs);
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(`BlueBubbles read failed (${res.status}): ${errorText || "unknown"}`);
-  }
-}
-
-export async function sendBlueBubblesTyping(
-  chatGuid: string,
-  typing: boolean,
-  opts: BlueBubblesChatOpts = {},
-): Promise<void> {
-  const trimmed = chatGuid.trim();
-  if (!trimmed) return;
-  const { baseUrl, password } = resolveAccount(opts);
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
-    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/typing`,
-    password,
-  });
-  const res = await blueBubblesFetchWithTimeout(
-    url,
-    { method: typing ? "POST" : "DELETE" },
-    opts.timeoutMs,
-  );
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(`BlueBubbles typing failed (${res.status}): ${errorText || "unknown"}`);
-  }
-}

extensions/bluebubbles/src/config-schema.ts

@@ -1,30 +0,0 @@
-import { z } from "zod";
-
-const allowFromEntry = z.union([z.string(), z.number()]);
-
-const bluebubblesActionSchema = z
-  .object({
-    reactions: z.boolean().optional(),
-  })
-  .optional();
-
-const bluebubblesAccountSchema = z.object({
-  name: z.string().optional(),
-  enabled: z.boolean().optional(),
-  serverUrl: z.string().optional(),
-  password: z.string().optional(),
-  webhookPath: z.string().optional(),
-  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
-  allowFrom: z.array(allowFromEntry).optional(),
-  groupAllowFrom: z.array(allowFromEntry).optional(),
-  groupPolicy: z.enum(["open", "disabled", "allowlist"]).optional(),
-  historyLimit: z.number().int().min(0).optional(),
-  dmHistoryLimit: z.number().int().min(0).optional(),
-  textChunkLimit: z.number().int().positive().optional(),
-  mediaMaxMb: z.number().int().positive().optional(),
-});
-
-export const BlueBubblesConfigSchema = bluebubblesAccountSchema.extend({
-  accounts: z.object({}).catchall(bluebubblesAccountSchema).optional(),
-  actions: bluebubblesActionSchema,
-});

extensions/bluebubbles/src/probe.ts

@@ -1,36 +0,0 @@
-import { buildBlueBubblesApiUrl, blueBubblesFetchWithTimeout } from "./types.js";
-
-export type BlueBubblesProbe = {
-  ok: boolean;
-  status?: number | null;
-  error?: string | null;
-};
-
-export async function probeBlueBubbles(params: {
-  baseUrl?: string | null;
-  password?: string | null;
-  timeoutMs?: number;
-}): Promise<BlueBubblesProbe> {
-  const baseUrl = params.baseUrl?.trim();
-  const password = params.password?.trim();
-  if (!baseUrl) return { ok: false, error: "serverUrl not configured" };
-  if (!password) return { ok: false, error: "password not configured" };
-  const url = buildBlueBubblesApiUrl({ baseUrl, path: "/api/v1/ping", password });
-  try {
-    const res = await blueBubblesFetchWithTimeout(
-      url,
-      { method: "GET" },
-      params.timeoutMs,
-    );
-    if (!res.ok) {
-      return { ok: false, status: res.status, error: `HTTP ${res.status}` };
-    }
-    return { ok: true, status: res.status };
-  } catch (err) {
-    return {
-      ok: false,
-      status: null,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}

extensions/bluebubbles/src/reactions.ts

@@ -1,114 +0,0 @@
-import { resolveBlueBubblesAccount } from "./accounts.js";
-import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
-import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
-
-export type BlueBubblesReactionOpts = {
-  serverUrl?: string;
-  password?: string;
-  accountId?: string;
-  timeoutMs?: number;
-  cfg?: ClawdbotConfig;
-};
-
-const REACTION_TYPES = new Set([
-  "love",
-  "like",
-  "dislike",
-  "laugh",
-  "emphasize",
-  "question",
-]);
-
-const REACTION_ALIASES = new Map<string, string>([
-  ["heart", "love"],
-  ["thumbs_up", "like"],
-  ["thumbs-down", "dislike"],
-  ["thumbs_down", "dislike"],
-  ["haha", "laugh"],
-  ["lol", "laugh"],
-  ["emphasis", "emphasize"],
-  ["exclaim", "emphasize"],
-  ["question", "question"],
-]);
-
-const REACTION_EMOJIS = new Map<string, string>([
-  ["❤️", "love"],
-  ["❤", "love"],
-  ["♥️", "love"],
-  ["😍", "love"],
-  ["👍", "like"],
-  ["👎", "dislike"],
-  ["😂", "laugh"],
-  ["🤣", "laugh"],
-  ["😆", "laugh"],
-  ["‼️", "emphasize"],
-  ["‼", "emphasize"],
-  ["❗", "emphasize"],
-  ["❓", "question"],
-  ["❔", "question"],
-]);
-
-function resolveAccount(params: BlueBubblesReactionOpts) {
-  const account = resolveBlueBubblesAccount({
-    cfg: params.cfg ?? {},
-    accountId: params.accountId,
-  });
-  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = params.password?.trim() || account.config.password?.trim();
-  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
-  if (!password) throw new Error("BlueBubbles password is required");
-  return { baseUrl, password };
-}
-
-function normalizeReactionInput(emoji: string, remove?: boolean): string {
-  const trimmed = emoji.trim();
-  if (!trimmed) throw new Error("BlueBubbles reaction requires an emoji or name.");
-  let raw = trimmed.toLowerCase();
-  if (raw.startsWith("-")) raw = raw.slice(1);
-  const aliased = REACTION_ALIASES.get(raw) ?? raw;
-  const mapped = REACTION_EMOJIS.get(trimmed) ?? REACTION_EMOJIS.get(raw) ?? aliased;
-  if (!REACTION_TYPES.has(mapped)) {
-    throw new Error(`Unsupported BlueBubbles reaction: ${trimmed}`);
-  }
-  return remove ? `-${mapped}` : mapped;
-}
-
-export async function sendBlueBubblesReaction(params: {
-  chatGuid: string;
-  messageGuid: string;
-  emoji: string;
-  remove?: boolean;
-  partIndex?: number;
-  opts?: BlueBubblesReactionOpts;
-}): Promise<void> {
-  const chatGuid = params.chatGuid.trim();
-  const messageGuid = params.messageGuid.trim();
-  if (!chatGuid) throw new Error("BlueBubbles reaction requires chatGuid.");
-  if (!messageGuid) throw new Error("BlueBubbles reaction requires messageGuid.");
-  const reaction = normalizeReactionInput(params.emoji, params.remove);
-  const { baseUrl, password } = resolveAccount(params.opts ?? {});
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
-    path: "/api/v1/message/react",
-    password,
-  });
-  const payload = {
-    chatGuid,
-    selectedMessageGuid: messageGuid,
-    reaction,
-    partIndex: typeof params.partIndex === "number" ? params.partIndex : 0,
-  };
-  const res = await blueBubblesFetchWithTimeout(
-    url,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(payload),
-    },
-    params.opts?.timeoutMs,
-  );
-  if (!res.ok) {
-    const errorText = await res.text();
-    throw new Error(`BlueBubbles reaction failed (${res.status}): ${errorText || "unknown"}`);
-  }
-}

extensions/bluebubbles/src/runtime.ts

@@ -1,14 +0,0 @@
-import type { PluginRuntime } from "clawdbot/plugin-sdk";
-
-let runtime: PluginRuntime | null = null;
-
-export function setBlueBubblesRuntime(next: PluginRuntime): void {
-  runtime = next;
-}
-
-export function getBlueBubblesRuntime(): PluginRuntime {
-  if (!runtime) {
-    throw new Error("BlueBubbles runtime not initialized");
-  }
-  return runtime;
-}

extensions/bluebubbles/src/send.ts

@@ -1,263 +0,0 @@
-import crypto from "node:crypto";
-
-import { resolveBlueBubblesAccount } from "./accounts.js";
-import { parseBlueBubblesTarget, normalizeBlueBubblesHandle } from "./targets.js";
-import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
-import {
-  blueBubblesFetchWithTimeout,
-  buildBlueBubblesApiUrl,
-  type BlueBubblesSendTarget,
-} from "./types.js";
-
-export type BlueBubblesSendOpts = {
-  serverUrl?: string;
-  password?: string;
-  accountId?: string;
-  timeoutMs?: number;
-  cfg?: ClawdbotConfig;
-};
-
-export type BlueBubblesSendResult = {
-  messageId: string;
-};
-
-function resolveSendTarget(raw: string): BlueBubblesSendTarget {
-  const parsed = parseBlueBubblesTarget(raw);
-  if (parsed.kind === "handle") {
-    return {
-      kind: "handle",
-      address: normalizeBlueBubblesHandle(parsed.to),
-      service: parsed.service,
-    };
-  }
-  if (parsed.kind === "chat_id") {
-    return { kind: "chat_id", chatId: parsed.chatId };
-  }
-  if (parsed.kind === "chat_guid") {
-    return { kind: "chat_guid", chatGuid: parsed.chatGuid };
-  }
-  return { kind: "chat_identifier", chatIdentifier: parsed.chatIdentifier };
-}
-
-function extractMessageId(payload: unknown): string {
-  if (!payload || typeof payload !== "object") return "unknown";
-  const record = payload as Record<string, unknown>;
-  const data = record.data && typeof record.data === "object" ? (record.data as Record<string, unknown>) : null;
-  const candidates = [
-    record.messageId,
-    record.guid,
-    record.id,
-    data?.messageId,
-    data?.guid,
-    data?.id,
-  ];
-  for (const candidate of candidates) {
-    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
-    if (typeof candidate === "number" && Number.isFinite(candidate)) return String(candidate);
-  }
-  return "unknown";
-}
-
-type BlueBubblesChatRecord = Record<string, unknown>;
-
-function extractChatGuid(chat: BlueBubblesChatRecord): string | null {
-  const candidates = [
-    chat.chatGuid,
-    chat.guid,
-    chat.chat_guid,
-    chat.identifier,
-    chat.chatIdentifier,
-    chat.chat_identifier,
-  ];
-  for (const candidate of candidates) {
-    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
-  }
-  return null;
-}
-
-function extractChatId(chat: BlueBubblesChatRecord): number | null {
-  const candidates = [chat.chatId, chat.id, chat.chat_id];
-  for (const candidate of candidates) {
-    if (typeof candidate === "number" && Number.isFinite(candidate)) return candidate;
-  }
-  return null;
-}
-
-function extractParticipantAddresses(chat: BlueBubblesChatRecord): string[] {
-  const raw =
-    (Array.isArray(chat.participants) ? chat.participants : null) ??
-    (Array.isArray(chat.handles) ? chat.handles : null) ??
-    (Array.isArray(chat.participantHandles) ? chat.participantHandles : null);
-  if (!raw) return [];
-  const out: string[] = [];
-  for (const entry of raw) {
-    if (typeof entry === "string") {
-      out.push(entry);
-      continue;
-    }
-    if (entry && typeof entry === "object") {
-      const record = entry as Record<string, unknown>;
-      const candidate =
-        (typeof record.address === "string" && record.address) ||
-        (typeof record.handle === "string" && record.handle) ||
-        (typeof record.id === "string" && record.id) ||
-        (typeof record.identifier === "string" && record.identifier);
-      if (candidate) out.push(candidate);
-    }
-  }
-  return out;
-}
-
-async function queryChats(params: {
-  baseUrl: string;
-  password: string;
-  timeoutMs?: number;
-  offset: number;
-  limit: number;
-}): Promise<BlueBubblesChatRecord[]> {
-  const url = buildBlueBubblesApiUrl({
-    baseUrl: params.baseUrl,
-    path: "/api/v1/chat/query",
-    password: params.password,
-  });
-  const res = await blueBubblesFetchWithTimeout(
-    url,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        limit: params.limit,
-        offset: params.offset,
-        with: ["participants"],
-      }),
-    },
-    params.timeoutMs,
-  );
-  if (!res.ok) return [];
-  const payload = (await res.json().catch(() => null)) as Record<string, unknown> | null;
-  const data = payload && typeof payload.data !== "undefined" ? (payload.data as unknown) : null;
-  return Array.isArray(data) ? (data as BlueBubblesChatRecord[]) : [];
-}
-
-export async function resolveChatGuidForTarget(params: {
-  baseUrl: string;
-  password: string;
-  timeoutMs?: number;
-  target: BlueBubblesSendTarget;
-}): Promise<string | null> {
-  if (params.target.kind === "chat_guid") return params.target.chatGuid;
-
-  const normalizedHandle =
-    params.target.kind === "handle" ? normalizeBlueBubblesHandle(params.target.address) : "";
-  const targetChatId = params.target.kind === "chat_id" ? params.target.chatId : null;
-  const targetChatIdentifier =
-    params.target.kind === "chat_identifier" ? params.target.chatIdentifier : null;
-
-  const limit = 500;
-  for (let offset = 0; offset < 5000; offset += limit) {
-    const chats = await queryChats({
-      baseUrl: params.baseUrl,
-      password: params.password,
-      timeoutMs: params.timeoutMs,
-      offset,
-      limit,
-    });
-    if (chats.length === 0) break;
-    for (const chat of chats) {
-      if (targetChatId != null) {
-        const chatId = extractChatId(chat);
-        if (chatId != null && chatId === targetChatId) {
-          return extractChatGuid(chat);
-        }
-      }
-      if (targetChatIdentifier) {
-        const guid = extractChatGuid(chat);
-        if (guid && guid === targetChatIdentifier) return guid;
-        const identifier =
-          typeof chat.identifier === "string"
-            ? chat.identifier
-            : typeof chat.chatIdentifier === "string"
-              ? chat.chatIdentifier
-              : typeof chat.chat_identifier === "string"
-                ? chat.chat_identifier
-                : "";
-        if (identifier && identifier === targetChatIdentifier) return extractChatGuid(chat);
-      }
-      if (normalizedHandle) {
-        const participants = extractParticipantAddresses(chat).map((entry) =>
-          normalizeBlueBubblesHandle(entry),
-        );
-        if (participants.includes(normalizedHandle)) {
-          return extractChatGuid(chat);
-        }
-      }
-    }
-  }
-  return null;
-}
-
-export async function sendMessageBlueBubbles(
-  to: string,
-  text: string,
-  opts: BlueBubblesSendOpts = {},
-): Promise<BlueBubblesSendResult> {
-  const trimmedText = text ?? "";
-  if (!trimmedText.trim()) {
-    throw new Error("BlueBubbles send requires text");
-  }
-
-  const account = resolveBlueBubblesAccount({
-    cfg: opts.cfg ?? {},
-    accountId: opts.accountId,
-  });
-  const baseUrl = opts.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = opts.password?.trim() || account.config.password?.trim();
-  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
-  if (!password) throw new Error("BlueBubbles password is required");
-
-  const target = resolveSendTarget(to);
-  const chatGuid = await resolveChatGuidForTarget({
-    baseUrl,
-    password,
-    timeoutMs: opts.timeoutMs,
-    target,
-  });
-  if (!chatGuid) {
-    throw new Error(
-      "BlueBubbles send failed: chatGuid not found for target. Use a chat_guid target or ensure the chat exists.",
-    );
-  }
-  const payload: Record<string, unknown> = {
-    chatGuid,
-    tempGuid: crypto.randomUUID(),
-    message: trimmedText,
-    method: "apple-script",
-  };
-
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
-    path: "/api/v1/message/text",
-    password,
-  });
-  const res = await blueBubblesFetchWithTimeout(
-    url,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(payload),
-    },
-    opts.timeoutMs,
-  );
-  if (!res.ok) {
-    const errorText = await res.text();
-    throw new Error(`BlueBubbles send failed (${res.status}): ${errorText || "unknown"}`);
-  }
-  const body = await res.text();
-  if (!body) return { messageId: "ok" };
-  try {
-    const parsed = JSON.parse(body) as unknown;
-    return { messageId: extractMessageId(parsed) };
-  } catch {
-    return { messageId: "ok" };
-  }
-}

extensions/bluebubbles/src/targets.ts

@@ -1,191 +0,0 @@
-export type BlueBubblesService = "imessage" | "sms" | "auto";
-
-export type BlueBubblesTarget =
-  | { kind: "chat_id"; chatId: number }
-  | { kind: "chat_guid"; chatGuid: string }
-  | { kind: "chat_identifier"; chatIdentifier: string }
-  | { kind: "handle"; to: string; service: BlueBubblesService };
-
-export type BlueBubblesAllowTarget =
-  | { kind: "chat_id"; chatId: number }
-  | { kind: "chat_guid"; chatGuid: string }
-  | { kind: "chat_identifier"; chatIdentifier: string }
-  | { kind: "handle"; handle: string };
-
-const CHAT_ID_PREFIXES = ["chat_id:", "chatid:", "chat:"];
-const CHAT_GUID_PREFIXES = ["chat_guid:", "chatguid:", "guid:"];
-const CHAT_IDENTIFIER_PREFIXES = ["chat_identifier:", "chatidentifier:", "chatident:"];
-const SERVICE_PREFIXES: Array<{ prefix: string; service: BlueBubblesService }> = [
-  { prefix: "imessage:", service: "imessage" },
-  { prefix: "sms:", service: "sms" },
-  { prefix: "auto:", service: "auto" },
-];
-
-function stripPrefix(value: string, prefix: string): string {
-  return value.slice(prefix.length).trim();
-}
-
-export function normalizeBlueBubblesHandle(raw: string): string {
-  const trimmed = raw.trim();
-  if (!trimmed) return "";
-  const lowered = trimmed.toLowerCase();
-  if (lowered.startsWith("imessage:")) return normalizeBlueBubblesHandle(trimmed.slice(9));
-  if (lowered.startsWith("sms:")) return normalizeBlueBubblesHandle(trimmed.slice(4));
-  if (lowered.startsWith("auto:")) return normalizeBlueBubblesHandle(trimmed.slice(5));
-  if (trimmed.includes("@")) return trimmed.toLowerCase();
-  return trimmed.replace(/\s+/g, "");
-}
-
-export function parseBlueBubblesTarget(raw: string): BlueBubblesTarget {
-  const trimmed = raw.trim();
-  if (!trimmed) throw new Error("BlueBubbles target is required");
-  const lower = trimmed.toLowerCase();
-
-  for (const { prefix, service } of SERVICE_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const remainder = stripPrefix(trimmed, prefix);
-      if (!remainder) throw new Error(`${prefix} target is required`);
-      const remainderLower = remainder.toLowerCase();
-      const isChatTarget =
-        CHAT_ID_PREFIXES.some((p) => remainderLower.startsWith(p)) ||
-        CHAT_GUID_PREFIXES.some((p) => remainderLower.startsWith(p)) ||
-        CHAT_IDENTIFIER_PREFIXES.some((p) => remainderLower.startsWith(p)) ||
-        remainderLower.startsWith("group:");
-      if (isChatTarget) {
-        return parseBlueBubblesTarget(remainder);
-      }
-      return { kind: "handle", to: remainder, service };
-    }
-  }
-
-  for (const prefix of CHAT_ID_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const value = stripPrefix(trimmed, prefix);
-      const chatId = Number.parseInt(value, 10);
-      if (!Number.isFinite(chatId)) {
-        throw new Error(`Invalid chat_id: ${value}`);
-      }
-      return { kind: "chat_id", chatId };
-    }
-  }
-
-  for (const prefix of CHAT_GUID_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const value = stripPrefix(trimmed, prefix);
-      if (!value) throw new Error("chat_guid is required");
-      return { kind: "chat_guid", chatGuid: value };
-    }
-  }
-
-  for (const prefix of CHAT_IDENTIFIER_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const value = stripPrefix(trimmed, prefix);
-      if (!value) throw new Error("chat_identifier is required");
-      return { kind: "chat_identifier", chatIdentifier: value };
-    }
-  }
-
-  if (lower.startsWith("group:")) {
-    const value = stripPrefix(trimmed, "group:");
-    const chatId = Number.parseInt(value, 10);
-    if (Number.isFinite(chatId)) {
-      return { kind: "chat_id", chatId };
-    }
-    if (!value) throw new Error("group target is required");
-    return { kind: "chat_guid", chatGuid: value };
-  }
-
-  return { kind: "handle", to: trimmed, service: "auto" };
-}
-
-export function parseBlueBubblesAllowTarget(raw: string): BlueBubblesAllowTarget {
-  const trimmed = raw.trim();
-  if (!trimmed) return { kind: "handle", handle: "" };
-  const lower = trimmed.toLowerCase();
-
-  for (const { prefix } of SERVICE_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const remainder = stripPrefix(trimmed, prefix);
-      if (!remainder) return { kind: "handle", handle: "" };
-      return parseBlueBubblesAllowTarget(remainder);
-    }
-  }
-
-  for (const prefix of CHAT_ID_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const value = stripPrefix(trimmed, prefix);
-      const chatId = Number.parseInt(value, 10);
-      if (Number.isFinite(chatId)) return { kind: "chat_id", chatId };
-    }
-  }
-
-  for (const prefix of CHAT_GUID_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const value = stripPrefix(trimmed, prefix);
-      if (value) return { kind: "chat_guid", chatGuid: value };
-    }
-  }
-
-  for (const prefix of CHAT_IDENTIFIER_PREFIXES) {
-    if (lower.startsWith(prefix)) {
-      const value = stripPrefix(trimmed, prefix);
-      if (value) return { kind: "chat_identifier", chatIdentifier: value };
-    }
-  }
-
-  if (lower.startsWith("group:")) {
-    const value = stripPrefix(trimmed, "group:");
-    const chatId = Number.parseInt(value, 10);
-    if (Number.isFinite(chatId)) return { kind: "chat_id", chatId };
-    if (value) return { kind: "chat_guid", chatGuid: value };
-  }
-
-  return { kind: "handle", handle: normalizeBlueBubblesHandle(trimmed) };
-}
-
-export function isAllowedBlueBubblesSender(params: {
-  allowFrom: Array<string | number>;
-  sender: string;
-  chatId?: number | null;
-  chatGuid?: string | null;
-  chatIdentifier?: string | null;
-}): boolean {
-  const allowFrom = params.allowFrom.map((entry) => String(entry).trim());
-  if (allowFrom.length === 0) return true;
-  if (allowFrom.includes("*")) return true;
-
-  const senderNormalized = normalizeBlueBubblesHandle(params.sender);
-  const chatId = params.chatId ?? undefined;
-  const chatGuid = params.chatGuid?.trim();
-  const chatIdentifier = params.chatIdentifier?.trim();
-
-  for (const entry of allowFrom) {
-    if (!entry) continue;
-    const parsed = parseBlueBubblesAllowTarget(entry);
-    if (parsed.kind === "chat_id" && chatId !== undefined) {
-      if (parsed.chatId === chatId) return true;
-    } else if (parsed.kind === "chat_guid" && chatGuid) {
-      if (parsed.chatGuid === chatGuid) return true;
-    } else if (parsed.kind === "chat_identifier" && chatIdentifier) {
-      if (parsed.chatIdentifier === chatIdentifier) return true;
-    } else if (parsed.kind === "handle" && senderNormalized) {
-      if (parsed.handle === senderNormalized) return true;
-    }
-  }
-  return false;
-}
-
-export function formatBlueBubblesChatTarget(params: {
-  chatId?: number | null;
-  chatGuid?: string | null;
-  chatIdentifier?: string | null;
-}): string {
-  if (params.chatId && Number.isFinite(params.chatId)) {
-    return `chat_id:${params.chatId}`;
-  }
-  const guid = params.chatGuid?.trim();
-  if (guid) return `chat_guid:${guid}`;
-  const identifier = params.chatIdentifier?.trim();
-  if (identifier) return `chat_identifier:${identifier}`;
-  return "";
-}

extensions/bluebubbles/src/types.ts

@@ -1,105 +0,0 @@
-export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
-export type GroupPolicy = "open" | "disabled" | "allowlist";
-
-export type BlueBubblesAccountConfig = {
-  /** Optional display name for this account (used in CLI/UI lists). */
-  name?: string;
-  /** Optional provider capability tags used for agent/runtime guidance. */
-  capabilities?: string[];
-  /** Allow channel-initiated config writes (default: true). */
-  configWrites?: boolean;
-  /** If false, do not start this BlueBubbles account. Default: true. */
-  enabled?: boolean;
-  /** Base URL for the BlueBubbles API. */
-  serverUrl?: string;
-  /** Password for BlueBubbles API authentication. */
-  password?: string;
-  /** Webhook path for the gateway HTTP server. */
-  webhookPath?: string;
-  /** Direct message access policy (default: pairing). */
-  dmPolicy?: DmPolicy;
-  allowFrom?: Array<string | number>;
-  /** Optional allowlist for group senders. */
-  groupAllowFrom?: Array<string | number>;
-  /** Group message handling policy. */
-  groupPolicy?: GroupPolicy;
-  /** Max group messages to keep as history context (0 disables). */
-  historyLimit?: number;
-  /** Max DM turns to keep as history context. */
-  dmHistoryLimit?: number;
-  /** Per-DM config overrides keyed by user ID. */
-  dms?: Record<string, unknown>;
-  /** Outbound text chunk size (chars). Default: 4000. */
-  textChunkLimit?: number;
-  blockStreaming?: boolean;
-  /** Merge streamed block replies before sending. */
-  blockStreamingCoalesce?: Record<string, unknown>;
-  /** Max outbound media size in MB. */
-  mediaMaxMb?: number;
-};
-
-export type BlueBubblesActionConfig = {
-  reactions?: boolean;
-};
-
-export type BlueBubblesConfig = {
-  /** Optional per-account BlueBubbles configuration (multi-account). */
-  accounts?: Record<string, BlueBubblesAccountConfig>;
-  /** Per-action tool gating (default: true for all). */
-  actions?: BlueBubblesActionConfig;
-} & BlueBubblesAccountConfig;
-
-export type BlueBubblesSendTarget =
-  | { kind: "chat_id"; chatId: number }
-  | { kind: "chat_guid"; chatGuid: string }
-  | { kind: "chat_identifier"; chatIdentifier: string }
-  | { kind: "handle"; address: string; service?: "imessage" | "sms" | "auto" };
-
-export type BlueBubblesAttachment = {
-  guid?: string;
-  uti?: string;
-  mimeType?: string;
-  transferName?: string;
-  totalBytes?: number;
-  height?: number;
-  width?: number;
-  originalROWID?: number;
-};
-
-const DEFAULT_TIMEOUT_MS = 10_000;
-
-export function normalizeBlueBubblesServerUrl(raw: string): string {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    throw new Error("BlueBubbles serverUrl is required");
-  }
-  const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
-  return withScheme.replace(/\/+$/, "");
-}
-
-export function buildBlueBubblesApiUrl(params: {
-  baseUrl: string;
-  path: string;
-  password?: string;
-}): string {
-  const normalized = normalizeBlueBubblesServerUrl(params.baseUrl);
-  const url = new URL(params.path, `${normalized}/`);
-  if (params.password) {
-    url.searchParams.set("password", params.password);
-  }
-  return url.toString();
-}
-
-export async function blueBubblesFetchWithTimeout(
-  url: string,
-  init: RequestInit,
-  timeoutMs = DEFAULT_TIMEOUT_MS,
-) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, { ...init, signal: controller.signal });
-  } finally {
-    clearTimeout(timer);
-  }
-}

extensions/matrix/index.ts

@@ -1,14 +1,12 @@
-import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import type { ClawdbotPluginApi } from "../../src/plugins/types.js";
 
 import { matrixPlugin } from "./src/channel.js";
-import { setMatrixRuntime } from "./src/runtime.js";
 
 const plugin = {
   id: "matrix",
   name: "Matrix",
   description: "Matrix channel plugin (matrix-js-sdk)",
   register(api: ClawdbotPluginApi) {
-    setMatrixRuntime(api.runtime);
     api.registerChannel({ plugin: matrixPlugin });
   },
 };

extensions/matrix/package.json

@@ -9,7 +9,6 @@
     ]
   },
   "dependencies": {
-    "clawdbot": "workspace:*",
     "markdown-it": "14.1.0",
     "matrix-js-sdk": "40.0.0"
   }

extensions/matrix/src/actions.ts

@@ -1,15 +1,13 @@
-import {
-  createActionGate,
-  readNumberParam,
-  readStringParam,
-  type ChannelMessageActionAdapter,
-  type ChannelMessageActionContext,
-  type ChannelMessageActionName,
-  type ChannelToolSend,
-} from "clawdbot/plugin-sdk";
+import { createActionGate, readNumberParam, readStringParam } from "../../../src/agents/tools/common.js";
 import { resolveMatrixAccount } from "./matrix/accounts.js";
 import { handleMatrixAction } from "./tool-actions.js";
 import type { CoreConfig } from "./types.js";
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+  ChannelMessageActionName,
+  ChannelToolSend,
+} from "../../../src/channels/plugins/types.js";
 
 export const matrixMessageActions: ChannelMessageActionAdapter = {
   listActions: ({ cfg }) => {

extensions/matrix/src/channel.ts

@@ -1,14 +1,13 @@
+import type { ChannelPlugin } from "../../../src/channels/plugins/types.js";
 import {
-  applyAccountNameToChannelSection,
-  buildChannelConfigSchema,
-  DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
-  formatPairingApproveHint,
-  normalizeAccountId,
-  PAIRING_APPROVED_MESSAGE,
   setAccountEnabledInConfigSection,
-  type ChannelPlugin,
-} from "clawdbot/plugin-sdk";
+} from "../../../src/channels/plugins/config-helpers.js";
+import { buildChannelConfigSchema } from "../../../src/channels/plugins/config-schema.js";
+import { formatPairingApproveHint } from "../../../src/channels/plugins/helpers.js";
+import { PAIRING_APPROVED_MESSAGE } from "../../../src/channels/plugins/pairing-message.js";
+import { applyAccountNameToChannelSection } from "../../../src/channels/plugins/setup-helpers.js";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../../src/routing/session-key.js";
 
 import { matrixMessageActions } from "./actions.js";
 import { MatrixConfigSchema } from "./config-schema.js";
@@ -26,11 +25,6 @@ import { probeMatrix } from "./matrix/probe.js";
 import { sendMessageMatrix } from "./matrix/send.js";
 import { matrixOnboardingAdapter } from "./onboarding.js";
 import { matrixOutbound } from "./outbound.js";
-import { resolveMatrixTargets } from "./resolve-targets.js";
-import {
-  listMatrixDirectoryGroupsLive,
-  listMatrixDirectoryPeersLive,
-} from "./directory-live.js";
 
 const meta = {
   id: "matrix",
@@ -153,9 +147,8 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
       approveHint: formatPairingApproveHint("matrix"),
       normalizeEntry: (raw) => raw.replace(/^matrix:/i, "").trim().toLowerCase(),
     }),
-    collectWarnings: ({ account, cfg }) => {
-      const defaultGroupPolicy = (cfg as CoreConfig).channels?.defaults?.groupPolicy;
-      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+    collectWarnings: ({ account }) => {
+      const groupPolicy = account.config.groupPolicy ?? "allowlist";
       if (groupPolicy !== "open") return [];
       return [
         "- Matrix rooms: groupPolicy=\"open\" allows any room to trigger (mention-gated). Set channels.matrix.groupPolicy=\"allowlist\" + channels.matrix.rooms to restrict rooms.",
@@ -241,14 +234,6 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         .map((id) => ({ kind: "group", id }) as const);
       return ids;
     },
-    listPeersLive: async ({ cfg, query, limit }) =>
-      listMatrixDirectoryPeersLive({ cfg, query, limit }),
-    listGroupsLive: async ({ cfg, query, limit }) =>
-      listMatrixDirectoryGroupsLive({ cfg, query, limit }),
-  },
-  resolver: {
-    resolveTargets: async ({ cfg, inputs, kind, runtime }) =>
-      resolveMatrixTargets({ cfg, inputs, kind, runtime }),
   },
   actions: matrixMessageActions,
   setup: {

extensions/matrix/src/directory-live.ts

@@ -1,175 +0,0 @@
-import type { ChannelDirectoryEntry } from "clawdbot/plugin-sdk";
-
-import { resolveMatrixAuth } from "./matrix/client.js";
-
-type MatrixUserResult = {
-  user_id?: string;
-  display_name?: string;
-};
-
-type MatrixUserDirectoryResponse = {
-  results?: MatrixUserResult[];
-};
-
-type MatrixJoinedRoomsResponse = {
-  joined_rooms?: string[];
-};
-
-type MatrixRoomNameState = {
-  name?: string;
-};
-
-type MatrixAliasLookup = {
-  room_id?: string;
-};
-
-async function fetchMatrixJson<T>(params: {
-  homeserver: string;
-  path: string;
-  accessToken: string;
-  method?: "GET" | "POST";
-  body?: unknown;
-}): Promise<T> {
-  const res = await fetch(`${params.homeserver}${params.path}`, {
-    method: params.method ?? "GET",
-    headers: {
-      Authorization: `Bearer ${params.accessToken}`,
-      "Content-Type": "application/json",
-    },
-    body: params.body ? JSON.stringify(params.body) : undefined,
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`Matrix API ${params.path} failed (${res.status}): ${text || "unknown error"}`);
-  }
-  return (await res.json()) as T;
-}
-
-function normalizeQuery(value?: string | null): string {
-  return value?.trim().toLowerCase() ?? "";
-}
-
-export async function listMatrixDirectoryPeersLive(params: {
-  cfg: unknown;
-  query?: string | null;
-  limit?: number | null;
-}): Promise<ChannelDirectoryEntry[]> {
-  const query = normalizeQuery(params.query);
-  if (!query) return [];
-  const auth = await resolveMatrixAuth({ cfg: params.cfg as never });
-  const res = await fetchMatrixJson<MatrixUserDirectoryResponse>({
-    homeserver: auth.homeserver,
-    accessToken: auth.accessToken,
-    path: "/_matrix/client/v3/user_directory/search",
-    method: "POST",
-    body: {
-      search_term: query,
-      limit: typeof params.limit === "number" && params.limit > 0 ? params.limit : 20,
-    },
-  });
-  const results = res.results ?? [];
-  return results
-    .map((entry) => {
-      const userId = entry.user_id?.trim();
-      if (!userId) return null;
-      return {
-        kind: "user",
-        id: userId,
-        name: entry.display_name?.trim() || undefined,
-        handle: entry.display_name ? `@${entry.display_name.trim()}` : undefined,
-        raw: entry,
-      } satisfies ChannelDirectoryEntry;
-    })
-    .filter(Boolean) as ChannelDirectoryEntry[];
-}
-
-async function resolveMatrixRoomAlias(
-  homeserver: string,
-  accessToken: string,
-  alias: string,
-): Promise<string | null> {
-  try {
-    const res = await fetchMatrixJson<MatrixAliasLookup>({
-      homeserver,
-      accessToken,
-      path: `/_matrix/client/v3/directory/room/${encodeURIComponent(alias)}`,
-    });
-    return res.room_id?.trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-async function fetchMatrixRoomName(
-  homeserver: string,
-  accessToken: string,
-  roomId: string,
-): Promise<string | null> {
-  try {
-    const res = await fetchMatrixJson<MatrixRoomNameState>({
-      homeserver,
-      accessToken,
-      path: `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/state/m.room.name`,
-    });
-    return res.name?.trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-export async function listMatrixDirectoryGroupsLive(params: {
-  cfg: unknown;
-  query?: string | null;
-  limit?: number | null;
-}): Promise<ChannelDirectoryEntry[]> {
-  const query = normalizeQuery(params.query);
-  if (!query) return [];
-  const auth = await resolveMatrixAuth({ cfg: params.cfg as never });
-  const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 20;
-
-  if (query.startsWith("#")) {
-    const roomId = await resolveMatrixRoomAlias(auth.homeserver, auth.accessToken, query);
-    if (!roomId) return [];
-    return [
-      {
-        kind: "group",
-        id: roomId,
-        name: query,
-        handle: query,
-      } satisfies ChannelDirectoryEntry,
-    ];
-  }
-
-  if (query.startsWith("!")) {
-    return [
-      {
-        kind: "group",
-        id: query,
-        name: query,
-      } satisfies ChannelDirectoryEntry,
-    ];
-  }
-
-  const joined = await fetchMatrixJson<MatrixJoinedRoomsResponse>({
-    homeserver: auth.homeserver,
-    accessToken: auth.accessToken,
-    path: "/_matrix/client/v3/joined_rooms",
-  });
-  const rooms = joined.joined_rooms ?? [];
-  const results: ChannelDirectoryEntry[] = [];
-
-  for (const roomId of rooms) {
-    const name = await fetchMatrixRoomName(auth.homeserver, auth.accessToken, roomId);
-    if (!name) continue;
-    if (!name.toLowerCase().includes(query)) continue;
-    results.push({
-      kind: "group",
-      id: roomId,
-      name,
-      handle: `#${name}`,
-    });
-    if (results.length >= limit) break;
-  }
-
-  return results;
-}

extensions/matrix/src/group-mentions.ts

@@ -1,4 +1,4 @@
-import type { ChannelGroupContext } from "clawdbot/plugin-sdk";
+import type { ChannelGroupContext } from "../../../src/channels/plugins/types.js";
 
 import { resolveMatrixRoomConfig } from "./matrix/monitor/rooms.js";
 import type { CoreConfig } from "./types.js";

extensions/matrix/src/matrix/accounts.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../../../src/routing/session-key.js";
 import type { CoreConfig, MatrixConfig } from "../types.js";
 import { resolveMatrixConfig } from "./client.js";
 import { credentialsMatchConfig, loadMatrixCredentials } from "./credentials.js";

extensions/matrix/src/matrix/actions.ts

@@ -15,7 +15,7 @@ import type {
   RoomTopicEventContent,
 } from "matrix-js-sdk/lib/@types/state_events.js";
 
-import { loadConfig } from "clawdbot/plugin-sdk";
+import { loadConfig } from "../../../../src/config/config.js";
 import type { CoreConfig } from "../types.js";
 import { getActiveMatrixClient } from "./active-client.js";
 import {

extensions/matrix/src/matrix/client.ts

@@ -1,6 +1,6 @@
 import { ClientEvent, type MatrixClient, SyncState } from "matrix-js-sdk";
 
-import { loadConfig } from "clawdbot/plugin-sdk";
+import { loadConfig } from "../../../../src/config/config.js";
 import type { CoreConfig } from "../types.js";
 
 export type MatrixResolvedConfig = {

extensions/matrix/src/matrix/credentials.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { resolveStateDir } from "clawdbot/plugin-sdk";
+import { resolveStateDir } from "../../../../src/config/paths.js";
 
 export type MatrixStoredCredentials = {
   homeserver: string;

extensions/matrix/src/matrix/deps.ts

@@ -3,7 +3,8 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 
-import { runCommandWithTimeout, type RuntimeEnv } from "clawdbot/plugin-sdk";
+import { runCommandWithTimeout } from "../../../../src/process/exec.js";
+import type { RuntimeEnv } from "../../../../src/runtime.js";
 
 const MATRIX_SDK_PACKAGE = "matrix-js-sdk";
 

extensions/matrix/src/matrix/monitor/allowlist.ts

@@ -1,5 +1,3 @@
-import type { AllowlistMatch } from "clawdbot/plugin-sdk";
-
 function normalizeAllowList(list?: Array<string | number>) {
   return (list ?? []).map((entry) => String(entry).trim()).filter(Boolean);
 }
@@ -12,9 +10,11 @@ function normalizeMatrixUser(raw?: string | null): string {
   return (raw ?? "").trim().toLowerCase();
 }
 
-export type MatrixAllowListMatch = AllowlistMatch<
-  "wildcard" | "id" | "prefixed-id" | "prefixed-user" | "name" | "localpart"
->;
+export type MatrixAllowListMatch = {
+  allowed: boolean;
+  matchKey?: string;
+  matchSource?: "wildcard" | "id" | "prefixed-id" | "prefixed-user" | "name" | "localpart";
+};
 
 export function resolveMatrixAllowListMatch(params: {
   allowList: string[];

extensions/matrix/src/matrix/monitor/auto-join.ts

@@ -1,7 +1,8 @@
 import type { MatrixClient, MatrixEvent, RoomMember } from "matrix-js-sdk";
 import { RoomMemberEvent } from "matrix-js-sdk";
 
-import { danger, logVerbose, type RuntimeEnv } from "clawdbot/plugin-sdk";
+import { danger, logVerbose } from "../../../../../src/globals.js";
+import type { RuntimeEnv } from "../../../../../src/runtime.js";
 import type { CoreConfig } from "../../types.js";
 
 export function registerMatrixAutoJoin(params: {

extensions/matrix/src/matrix/monitor/index.ts

@@ -2,38 +2,31 @@ import type { MatrixEvent, Room } from "matrix-js-sdk";
 import { EventType, RelationType, RoomEvent } from "matrix-js-sdk";
 import type { RoomMessageEventContent } from "matrix-js-sdk/lib/@types/events.js";
 
+import { resolveEffectiveMessagesConfig, resolveHumanDelayConfig } from "../../../../../src/agents/identity.js";
+import { chunkMarkdownText, resolveTextChunkLimit } from "../../../../../src/auto-reply/chunk.js";
+import { hasControlCommand } from "../../../../../src/auto-reply/command-detection.js";
+import { shouldHandleTextCommands } from "../../../../../src/auto-reply/commands-registry.js";
+import { formatAgentEnvelope } from "../../../../../src/auto-reply/envelope.js";
+import { dispatchReplyFromConfig } from "../../../../../src/auto-reply/reply/dispatch-from-config.js";
+import { finalizeInboundContext } from "../../../../../src/auto-reply/reply/inbound-context.js";
 import {
   buildMentionRegexes,
-  chunkMarkdownText,
-  createReplyDispatcherWithTyping,
-  danger,
-  dispatchReplyFromConfig,
-  enqueueSystemEvent,
-  finalizeInboundContext,
-  formatAgentEnvelope,
-  formatAllowlistMatchMeta,
-  getChildLogger,
-  hasControlCommand,
-  loadConfig,
-  logVerbose,
-  mergeAllowlist,
   matchesMentionPatterns,
+} from "../../../../../src/auto-reply/reply/mentions.js";
+import { createReplyDispatcherWithTyping } from "../../../../../src/auto-reply/reply/reply-dispatcher.js";
+import type { ReplyPayload } from "../../../../../src/auto-reply/types.js";
+import { resolveCommandAuthorizedFromAuthorizers } from "../../../../../src/channels/command-gating.js";
+import { loadConfig } from "../../../../../src/config/config.js";
+import { resolveStorePath, updateLastRoute } from "../../../../../src/config/sessions.js";
+import { danger, logVerbose, shouldLogVerbose } from "../../../../../src/globals.js";
+import { enqueueSystemEvent } from "../../../../../src/infra/system-events.js";
+import { getChildLogger } from "../../../../../src/logging.js";
+import {
   readChannelAllowFromStore,
-  recordSessionMetaFromInbound,
-  resolveAgentRoute,
-  resolveCommandAuthorizedFromAuthorizers,
-  resolveEffectiveMessagesConfig,
-  resolveHumanDelayConfig,
-  resolveStorePath,
-  resolveTextChunkLimit,
-  shouldHandleTextCommands,
-  shouldLogVerbose,
-  summarizeMapping,
-  updateLastRoute,
   upsertChannelPairingRequest,
-  type ReplyPayload,
-  type RuntimeEnv,
-} from "clawdbot/plugin-sdk";
+} from "../../../../../src/pairing/pairing-store.js";
+import { resolveAgentRoute } from "../../../../../src/routing/resolve-route.js";
+import type { RuntimeEnv } from "../../../../../src/runtime.js";
 import type { CoreConfig, ReplyToMode } from "../../types.js";
 import { setActiveMatrixClient } from "../active-client.js";
 import {
@@ -60,7 +53,6 @@ import { resolveMentions } from "./mentions.js";
 import { deliverMatrixReplies } from "./replies.js";
 import { resolveMatrixRoomConfig } from "./rooms.js";
 import { resolveMatrixThreadRootId, resolveMatrixThreadTarget } from "./threads.js";
-import { resolveMatrixTargets } from "../../resolve-targets.js";
 
 export type MonitorMatrixOpts = {
   runtime?: RuntimeEnv;
@@ -76,7 +68,7 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
   if (isBunRuntime()) {
     throw new Error("Matrix provider requires Node (bun runtime not supported)");
   }
-  let cfg = loadConfig() as CoreConfig;
+  const cfg = loadConfig() as CoreConfig;
   if (cfg.channels?.matrix?.enabled === false) return;
 
   const runtime: RuntimeEnv = opts.runtime ?? {
@@ -87,110 +79,6 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
     },
   };
 
-  const normalizeUserEntry = (raw: string) =>
-    raw.replace(/^matrix:/i, "").replace(/^user:/i, "").trim();
-  const normalizeRoomEntry = (raw: string) =>
-    raw.replace(/^matrix:/i, "").replace(/^(room|channel):/i, "").trim();
-  const isMatrixUserId = (value: string) => value.startsWith("@") && value.includes(":");
-
-  let allowFrom = cfg.channels?.matrix?.dm?.allowFrom ?? [];
-  let roomsConfig = cfg.channels?.matrix?.rooms;
-
-  if (allowFrom.length > 0) {
-    const entries = allowFrom
-      .map((entry) => normalizeUserEntry(String(entry)))
-      .filter((entry) => entry && entry !== "*");
-    if (entries.length > 0) {
-      const mapping: string[] = [];
-      const unresolved: string[] = [];
-      const additions: string[] = [];
-      const pending: string[] = [];
-      for (const entry of entries) {
-        if (isMatrixUserId(entry)) {
-          additions.push(entry);
-          continue;
-        }
-        pending.push(entry);
-      }
-      if (pending.length > 0) {
-        const resolved = await resolveMatrixTargets({
-          cfg,
-          inputs: pending,
-          kind: "user",
-          runtime,
-        });
-        for (const entry of resolved) {
-          if (entry.resolved && entry.id) {
-            additions.push(entry.id);
-            mapping.push(`${entry.input}→${entry.id}`);
-          } else {
-            unresolved.push(entry.input);
-          }
-        }
-      }
-      allowFrom = mergeAllowlist({ existing: allowFrom, additions });
-      summarizeMapping("matrix users", mapping, unresolved, runtime);
-    }
-  }
-
-  if (roomsConfig && Object.keys(roomsConfig).length > 0) {
-    const entries = Object.keys(roomsConfig).filter((key) => key !== "*");
-    const mapping: string[] = [];
-    const unresolved: string[] = [];
-    const nextRooms = { ...roomsConfig };
-    const pending: Array<{ input: string; query: string }> = [];
-    for (const entry of entries) {
-      const trimmed = entry.trim();
-      if (!trimmed) continue;
-      const cleaned = normalizeRoomEntry(trimmed);
-      if (cleaned.startsWith("!") && cleaned.includes(":")) {
-        if (!nextRooms[cleaned]) {
-          nextRooms[cleaned] = roomsConfig[entry];
-        }
-        mapping.push(`${entry}→${cleaned}`);
-        continue;
-      }
-      pending.push({ input: entry, query: trimmed });
-    }
-    if (pending.length > 0) {
-      const resolved = await resolveMatrixTargets({
-        cfg,
-        inputs: pending.map((entry) => entry.query),
-        kind: "group",
-        runtime,
-      });
-      resolved.forEach((entry, index) => {
-        const source = pending[index];
-        if (!source) return;
-        if (entry.resolved && entry.id) {
-          if (!nextRooms[entry.id]) {
-            nextRooms[entry.id] = roomsConfig[source.input];
-          }
-          mapping.push(`${source.input}→${entry.id}`);
-        } else {
-          unresolved.push(source.input);
-        }
-      });
-    }
-    roomsConfig = nextRooms;
-    summarizeMapping("matrix rooms", mapping, unresolved, runtime);
-  }
-
-  cfg = {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      matrix: {
-        ...cfg.channels?.matrix,
-        dm: {
-          ...cfg.channels?.matrix?.dm,
-          allowFrom,
-        },
-        rooms: roomsConfig,
-      },
-    },
-  };
-
   const auth = await resolveMatrixAuth({ cfg });
   const resolvedInitialSyncLimit =
     typeof opts.initialSyncLimit === "number"
@@ -210,8 +98,7 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
   const mentionRegexes = buildMentionRegexes(cfg);
   const logger = getChildLogger({ module: "matrix-auto-reply" });
   const allowlistOnly = cfg.channels?.matrix?.allowlistOnly === true;
-  const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
-  const groupPolicyRaw = cfg.channels?.matrix?.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+  const groupPolicyRaw = cfg.channels?.matrix?.groupPolicy ?? "allowlist";
   const groupPolicy = allowlistOnly && groupPolicyRaw === "open" ? "allowlist" : groupPolicyRaw;
   const replyToMode = opts.replyToMode ?? cfg.channels?.matrix?.replyToMode ?? "off";
   const threadReplies = cfg.channels?.matrix?.threadReplies ?? "inbound";
@@ -332,7 +219,9 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
             userId: senderId,
             userName: senderName,
           });
-          const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
+          const allowMatchMeta = `matchKey=${allowMatch.matchKey ?? "none"} matchSource=${
+            allowMatch.matchSource ?? "none"
+          }`;
           if (!allowMatch.allowed) {
             if (dmPolicy === "pairing") {
               const { code, created } = await upsertChannelPairingRequest({
@@ -373,16 +262,14 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
       }
 
       if (isRoom && roomConfigInfo.config?.users?.length) {
-        const userMatch = resolveMatrixAllowListMatch({
+        const userAllowed = resolveMatrixAllowListMatches({
           allowList: normalizeAllowListLower(roomConfigInfo.config.users),
           userId: senderId,
           userName: senderName,
         });
-        if (!userMatch.allowed) {
+        if (!userAllowed) {
           logVerbose(
-            `matrix: blocked sender ${senderId} (room users allowlist, ${roomMatchMeta}, ${formatAllowlistMatchMeta(
-              userMatch,
-            )})`,
+            `matrix: blocked sender ${senderId} (room users allowlist, ${roomMatchMeta})`,
           );
           return;
         }
@@ -499,7 +386,7 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
       });
 
       const groupSystemPrompt = roomConfigInfo.config?.systemPrompt?.trim() || undefined;
-      const ctxPayload = finalizeInboundContext({
+	      const ctxPayload = finalizeInboundContext({
 	        Body: body,
 	        RawBody: bodyText,
 	        CommandBody: bodyText,
@@ -531,28 +418,16 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
 	        OriginatingTo: `room:${roomId}`,
 	      });
 
-      const storePath = resolveStorePath(cfg.session?.store, {
-        agentId: route.agentId,
-      });
-      void recordSessionMetaFromInbound({
-        storePath,
-        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-        ctx: ctxPayload,
-      }).catch((err) => {
-        logger.warn(
-          { error: String(err), storePath, sessionKey: ctxPayload.SessionKey ?? route.sessionKey },
-          "failed updating session meta",
-        );
-      });
-
       if (isDirectMessage) {
+        const storePath = resolveStorePath(cfg.session?.store, {
+          agentId: route.agentId,
+        });
         await updateLastRoute({
           storePath,
           sessionKey: route.mainSessionKey,
           channel: "matrix",
           to: `room:${roomId}`,
           accountId: route.accountId,
-          ctx: ctxPayload,
         });
       }
 

extensions/matrix/src/matrix/monitor/media.ts

@@ -1,6 +1,6 @@
 import type { MatrixClient } from "matrix-js-sdk";
 
-import { saveMediaBuffer } from "clawdbot/plugin-sdk";
+import { saveMediaBuffer } from "../../../../../src/media/store.js";
 
 async function fetchMatrixMediaBuffer(params: {
   client: MatrixClient;

extensions/matrix/src/matrix/monitor/mentions.ts

@@ -1,6 +1,6 @@
 import type { RoomMessageEventContent } from "matrix-js-sdk/lib/@types/events.js";
 
-import { matchesMentionPatterns } from "clawdbot/plugin-sdk";
+import { matchesMentionPatterns } from "../../../../../src/auto-reply/reply/mentions.js";
 
 export function resolveMentions(params: {
   content: RoomMessageEventContent;

extensions/matrix/src/matrix/monitor/replies.ts

@@ -1,12 +1,9 @@
 import type { MatrixClient } from "matrix-js-sdk";
 
-import {
-  chunkMarkdownText,
-  danger,
-  logVerbose,
-  type ReplyPayload,
-  type RuntimeEnv,
-} from "clawdbot/plugin-sdk";
+import { chunkMarkdownText } from "../../../../../src/auto-reply/chunk.js";
+import type { ReplyPayload } from "../../../../../src/auto-reply/types.js";
+import { danger, logVerbose } from "../../../../../src/globals.js";
+import type { RuntimeEnv } from "../../../../../src/runtime.js";
 import { sendMessageMatrix } from "../send.js";
 
 export async function deliverMatrixReplies(params: {

extensions/matrix/src/matrix/monitor/rooms.ts

@@ -1,5 +1,8 @@
 import type { MatrixConfig, MatrixRoomConfig } from "../../types.js";
-import { buildChannelKeyCandidates, resolveChannelEntryMatch } from "clawdbot/plugin-sdk";
+import {
+  buildChannelKeyCandidates,
+  resolveChannelEntryMatch,
+} from "../../../../../src/channels/plugins/channel-config.js";
 
 export type MatrixRoomConfigResolved = {
   allowed: boolean;

extensions/matrix/src/matrix/poll-types.ts

@@ -9,7 +9,7 @@
 
 import type { TimelineEvents } from "matrix-js-sdk/lib/@types/event.js";
 import type { ExtensibleAnyMessageEventContent } from "matrix-js-sdk/lib/@types/extensible_events.js";
-import type { PollInput } from "clawdbot/plugin-sdk";
+import type { PollInput } from "../../../../src/polls.js";
 
 export const M_POLL_START = "m.poll.start" as const;
 export const M_POLL_RESPONSE = "m.poll.response" as const;

extensions/matrix/src/matrix/send.test.ts

@@ -18,18 +18,20 @@ vi.mock("matrix-js-sdk", () => ({
   },
 }));
 
-vi.mock("clawdbot/plugin-sdk", () => ({
+vi.mock("../../../../src/config/config.js", () => ({
   loadConfig: () => ({}),
-  resolveTextChunkLimit: () => 4000,
-  chunkMarkdownText: (text: string) => (text ? [text] : []),
+}));
+
+vi.mock("../../../../src/web/media.js", () => ({
   loadWebMedia: vi.fn().mockResolvedValue({
     buffer: Buffer.from("media"),
     fileName: "photo.png",
     contentType: "image/png",
     kind: "image",
   }),
-  mediaKindFromMime: () => "image",
-  isVoiceCompatibleAudio: () => false,
+}));
+
+vi.mock("../../../../src/media/image-ops.js", () => ({
   getImageMetadata: vi.fn().mockResolvedValue(null),
   resizeToJpeg: vi.fn(),
 }));

extensions/matrix/src/matrix/send.ts

@@ -5,17 +5,13 @@ import type {
   ReactionEventContent,
 } from "matrix-js-sdk/lib/@types/events.js";
 
-import {
-  chunkMarkdownText,
-  getImageMetadata,
-  isVoiceCompatibleAudio,
-  loadConfig,
-  loadWebMedia,
-  mediaKindFromMime,
-  type PollInput,
-  resolveTextChunkLimit,
-  resizeToJpeg,
-} from "clawdbot/plugin-sdk";
+import { chunkMarkdownText, resolveTextChunkLimit } from "../../../../src/auto-reply/chunk.js";
+import { loadConfig } from "../../../../src/config/config.js";
+import { isVoiceCompatibleAudio } from "../../../../src/media/audio.js";
+import { mediaKindFromMime } from "../../../../src/media/constants.js";
+import { getImageMetadata, resizeToJpeg } from "../../../../src/media/image-ops.js";
+import type { PollInput } from "../../../../src/polls.js";
+import { loadWebMedia } from "../../../../src/web/media.js";
 import { getActiveMatrixClient } from "./active-client.js";
 import {
   createMatrixClient,

extensions/matrix/src/onboarding.ts

@@ -1,12 +1,10 @@
-import {
-  addWildcardAllowFrom,
-  formatDocsLink,
-  promptChannelAccessConfig,
-  type ChannelOnboardingAdapter,
-  type ChannelOnboardingDmPolicy,
-  type WizardPrompter,
-} from "clawdbot/plugin-sdk";
-import { listMatrixDirectoryGroupsLive } from "./directory-live.js";
+import { addWildcardAllowFrom } from "../../../src/channels/plugins/onboarding/helpers.js";
+import type {
+  ChannelOnboardingAdapter,
+  ChannelOnboardingDmPolicy,
+} from "../../../src/channels/plugins/onboarding-types.js";
+import { formatDocsLink } from "../../../src/terminal/links.js";
+import type { WizardPrompter } from "../../../src/wizard/prompts.js";
 import { resolveMatrixAccount } from "./matrix/accounts.js";
 import { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./matrix/deps.js";
 import type { CoreConfig, DmPolicy } from "./types.js";
@@ -85,35 +83,6 @@ async function promptMatrixAllowFrom(params: {
   };
 }
 
-function setMatrixGroupPolicy(cfg: CoreConfig, groupPolicy: "open" | "allowlist" | "disabled") {
-  return {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      matrix: {
-        ...cfg.channels?.matrix,
-        enabled: true,
-        groupPolicy,
-      },
-    },
-  };
-}
-
-function setMatrixRoomAllowlist(cfg: CoreConfig, roomKeys: string[]) {
-  const rooms = Object.fromEntries(roomKeys.map((key) => [key, { allow: true }]));
-  return {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      matrix: {
-        ...cfg.channels?.matrix,
-        enabled: true,
-        rooms,
-      },
-    },
-  };
-}
-
 const dmPolicy: ChannelOnboardingDmPolicy = {
   label: "Matrix",
   channel,
@@ -285,75 +254,6 @@ export const matrixOnboardingAdapter: ChannelOnboardingAdapter = {
       next = await promptMatrixAllowFrom({ cfg: next, prompter });
     }
 
-    const accessConfig = await promptChannelAccessConfig({
-      prompter,
-      label: "Matrix rooms",
-      currentPolicy: next.channels?.matrix?.groupPolicy ?? "allowlist",
-      currentEntries: Object.keys(next.channels?.matrix?.rooms ?? {}),
-      placeholder: "!roomId:server, #alias:server, Project Room",
-      updatePrompt: Boolean(next.channels?.matrix?.rooms),
-    });
-    if (accessConfig) {
-      if (accessConfig.policy !== "allowlist") {
-        next = setMatrixGroupPolicy(next, accessConfig.policy);
-      } else {
-        let roomKeys = accessConfig.entries;
-        if (accessConfig.entries.length > 0) {
-          try {
-            const resolvedIds: string[] = [];
-            const unresolved: string[] = [];
-            for (const entry of accessConfig.entries) {
-              const trimmed = entry.trim();
-              if (!trimmed) continue;
-              const cleaned = trimmed.replace(/^(room|channel):/i, "").trim();
-              if (cleaned.startsWith("!") && cleaned.includes(":")) {
-                resolvedIds.push(cleaned);
-                continue;
-              }
-              const matches = await listMatrixDirectoryGroupsLive({
-                cfg: next,
-                query: trimmed,
-                limit: 10,
-              });
-              const exact = matches.find(
-                (match) => (match.name ?? "").toLowerCase() === trimmed.toLowerCase(),
-              );
-              const best = exact ?? matches[0];
-              if (best?.id) {
-                resolvedIds.push(best.id);
-              } else {
-                unresolved.push(entry);
-              }
-            }
-            roomKeys = [
-              ...resolvedIds,
-              ...unresolved.map((entry) => entry.trim()).filter(Boolean),
-            ];
-            if (resolvedIds.length > 0 || unresolved.length > 0) {
-              await prompter.note(
-                [
-                  resolvedIds.length > 0 ? `Resolved: ${resolvedIds.join(", ")}` : undefined,
-                  unresolved.length > 0
-                    ? `Unresolved (kept as typed): ${unresolved.join(", ")}`
-                    : undefined,
-                ]
-                  .filter(Boolean)
-                  .join("\n"),
-                "Matrix rooms",
-              );
-            }
-          } catch (err) {
-            await prompter.note(
-              `Room lookup failed; keeping entries as typed. ${String(err)}`,
-              "Matrix rooms",
-            );
-          }
-        }
-        next = setMatrixGroupPolicy(next, "allowlist");
-        next = setMatrixRoomAllowlist(next, roomKeys);
-      }
-    }
-
     return { cfg: next };
   },
   dmPolicy,

extensions/matrix/src/outbound.ts

@@ -1,11 +1,10 @@
-import type { ChannelOutboundAdapter } from "clawdbot/plugin-sdk";
-
-import { getMatrixRuntime } from "./runtime.js";
+import { chunkMarkdownText } from "../../../src/auto-reply/chunk.js";
+import type { ChannelOutboundAdapter } from "../../../src/channels/plugins/types.js";
 import { sendMessageMatrix, sendPollMatrix } from "./matrix/send.js";
 
 export const matrixOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",
-  chunker: (text, limit) => getMatrixRuntime().channel.text.chunkMarkdownText(text, limit),
+  chunker: chunkMarkdownText,
   textChunkLimit: 4000,
   sendText: async ({ to, text, deps, replyToId, threadId }) => {
     const send = deps?.sendMatrix ?? sendMessageMatrix;