acpmux: pause two agents that keep messaging each other without progress

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AcpmuxDaemonLauncher.swift

@@ -45,7 +45,8 @@ nonisolated enum AcpmuxDaemonLauncher {
     /// The daemon's environment: this app's, without any inherited Computer
     /// Use secret, plus `childEnvironment`, non-secret Computer Use v2 state,
     /// the session offer tools while suggested tasks are on
-    /// (``AcpmuxEnvironment/offersSessionTools``), and the launch knobs.
+    /// (``AcpmuxEnvironment/offersSessionTools``), the agent message runaway guard
+    /// off when ``AcpmuxEnvironment/agentPairGuard`` is off (else its cap), and the launch knobs.
     static func spawnEnvironment(_ environment: AcpmuxEnvironment, inherited: [String: String]) -> [String: String] {
         let computerUse = Set(AcpmuxEnvironment.computerUseKeys + [AcpmuxEnvironment.computerUseHostKey])
         let safeInherited = inherited.filter { key, _ in
@@ -61,6 +62,12 @@ nonisolated enum AcpmuxDaemonLauncher {
             if !computerUse.contains(key) || developmentCredential { variables[key] = value }
         }
         if environment.offersSessionTools { variables[AcpmuxEnvironment.offerToolsKey] = "1" }
+        if environment.agentPairGuard {
+            variables[AcpmuxEnvironment.agentPairCapKey] = String(max(0, environment.agentPairCap))
+            variables[AcpmuxEnvironment.agentPairWindowKey] = String(max(0, environment.agentPairWindowSeconds))
+        } else {
+            variables[AcpmuxEnvironment.agentPairGuardKey] = "0"
+        }
         variables["ACPMUX_LAUNCH_LOG"] = environment.logPath
         variables["ACPMUX_LOGIN_ENV"] = "1"
         return variables

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AcpmuxEnvironment.swift

@@ -29,6 +29,14 @@ public nonisolated struct AcpmuxEnvironment: Sendable, Equatable {
     /// Settings toggle `agent.suggestedTasks` is on; ``AcpmuxHost`` reads it at each daemon start, so a running
     /// daemon keeps the value it started with.
     public var offersSessionTools = false
+    /// Whether the daemon this app spawns keeps the agent message runaway guard on (acpmux
+    /// `hub/agent_pairs.rs`); off, it gets ``agentPairGuardKey`` `0`. The Debug Settings toggle
+    /// `agent.pairGuard`, read at each daemon start like ``offersSessionTools``.
+    public var agentPairGuard = true
+    /// The guard's cap and its window in seconds (`agent.pairCap`, `agent.pairWindow`); `0` turns
+    /// the cap off. Passed as ``agentPairCapKey`` and ``agentPairWindowKey`` while the guard is on.
+    public var agentPairCap = 20
+    public var agentPairWindowSeconds = 600
     /// Whether an unsigned development daemon needs its person key on an
     /// inherited descriptor. Signed builds enroll only after checking the peer.
     public var passesPersonKeyAtSpawn = true
@@ -40,6 +48,11 @@ public nonisolated struct AcpmuxEnvironment: Sendable, Equatable {
     public static let computerUseHostKey = "CMUX_NEXT_CUA_SOCKET_HOST_AUTH_TOKEN"
     /// acpmux `agent_tools::OFFER_TOOLS_ENV`: `1` gives sessions `offer_session`.
     public static let offerToolsKey = "ACPMUX_OFFER_TOOLS"
+    /// acpmux `hub::agent_pairs::GUARD_ENV`: `0` turns the agent message runaway guard off.
+    public static let agentPairGuardKey = "ACPMUX_AGENT_PAIR_GUARD"
+    /// acpmux `hub::agent_pairs::MAX_MESSAGES_ENV` and `WINDOW_ENV`.
+    public static let agentPairCapKey = "ACPMUX_AGENT_PAIR_MAX_MESSAGES"
+    public static let agentPairWindowKey = "ACPMUX_AGENT_PAIR_WINDOW_SECS"
 
     /// The build-session kill switch (cx-9ettq): with either set, acpmux
     /// starts no agent and the Chief host does not start. A GUI test job sets

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AcpmuxPaneMethods+Params.swift

@@ -61,6 +61,8 @@ nonisolated extension AcpmuxPaneMethods {
         "_acpmux/offer_respond": (["sessionId", "offerId", "outcome", "childSessionId"], []),
         // `subagentSessionId`: a child of that chat, which acpmux looks up in the chat's own map.
         "_acpmux/subagent_stop": (["sessionId", "subagentSessionId"], []),
+        // `peerSessionId`: one of that chat's paused pairs, a selector only (acpmux checks the pair has the chat).
+        "_acpmux/agent_pair_resume": (["sessionId", "peerSessionId"], []),
         "acp.session.fork": (["sessionId", "throughSeq"], []),
         "acp.trust.get": (["cwd", "sessionId"], []),
         "acp.trust.set": (["cwd", "level", "sessionId"], []),

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AcpmuxPaneMethods+ReplyShapes.swift

@@ -0,0 +1,64 @@
+import Foundation
+
+/// The replies the relay filters itself (ad349), of ``AcpmuxPaneMethods``: read-only requests
+/// whose reply reaches the pane cut to the fields it renders.
+nonisolated extension AcpmuxPaneMethods {
+    /// The shape of a reply the relay filters itself, without relying on the daemon's redaction.
+    public nonisolated indirect enum ReplyShape: Sendable {
+        case string
+        case object([String: ReplyShape])
+        case list(ReplyShape)
+        /// Only the scheme of the URL in the sibling field `source` (`ssh`, `ws`, `wss`), so the
+        /// page learns a peer's transport without its URL (which can carry a user or a token).
+        case scheme(from: String)
+    }
+
+    /// The URL schemes a `.scheme` field may report; any other scheme is dropped.
+    static let reportedSchemes: Set<String> = ["ssh", "ws", "wss"]
+
+    /// Replies filtered to the fields the pane renders; everything else is dropped, at every depth.
+    /// `_acpmux/status`: the pane reads only `peers[].name` and each peer's `transport`, the
+    /// scheme of its `url` (direct.ts, after initialize; environments.ts peerKindsFromStatus).
+    public static let replyShapes: [String: ReplyShape] = [
+        "_acpmux/status": .object([
+            "peers": .list(.object(["name": .string, "transport": .scheme(from: "url")])),
+        ]),
+    ]
+
+    /// `value` cut to `shape`: nil when it does not fit (a list keeps only the items that fit).
+    static func filtered(_ value: Any, to shape: ReplyShape) -> Any? {
+        switch shape {
+        case .string:
+            return value as? String
+        case .scheme:
+            guard let scheme = (value as? String).flatMap({ URLComponents(string: $0)?.scheme?.lowercased() }),
+                  reportedSchemes.contains(scheme) else { return nil }
+            return scheme
+        case .list(let item):
+            return (value as? [Any])?.compactMap { filtered($0, to: item) }
+        case .object(let fields):
+            guard let object = value as? [String: Any] else { return nil }
+            let kept = fields.compactMap { key, field -> (String, Any)? in
+                let source: String
+                if case .scheme(let from) = field { source = from } else { source = key }
+                return object[source].flatMap { filtered($0, to: field) }.map { (key, $0) }
+            }
+            // An object with none of its fields is dropped (a peer with no name renders nothing).
+            return kept.isEmpty ? nil : Dictionary(uniqueKeysWithValues: kept)
+        }
+    }
+
+    /// A reply to a filtered request, rebuilt with the page's id (raw JSON) and its filtered
+    /// result. An error keeps only its code and message.
+    static func filteredReply(_ object: [String: Any], shape: ReplyShape, pageID: String) -> String {
+        let id = (try? JSONSerialization.jsonObject(with: Data(pageID.utf8), options: [.fragmentsAllowed])) ?? NSNull()
+        var reply: [String: Any] = ["jsonrpc": "2.0", "id": id]
+        if let error = object["error"] as? [String: Any] {
+            reply["error"] = ["code": error["code"] as? Int ?? -32603, "message": error["message"] as? String ?? ""]
+        } else {
+            reply["result"] = object["result"].flatMap { filtered($0, to: shape) } ?? [String: Any]()
+        }
+        let data = (try? JSONSerialization.data(withJSONObject: reply, options: [.sortedKeys])) ?? Data()
+        return String(decoding: data, as: UTF8.self)
+    }
+}

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AcpmuxPaneMethods.swift

@@ -78,67 +78,13 @@ nonisolated enum AcpmuxPaneMethods {
         // for that child (claude_stdio/workflows.rs). It stops work like `_acpmux/kill`, so no
         // gesture; caller params never reach Claude.
         "_acpmux/subagent_stop",
+        // Resume a paused agent pair of a chat in the pane's scope (the pause row's Resume; acpmux
+        // hub/agent_pairs.rs): delivers the messages the two agents already sent and the guard held.
+        // `peerSessionId` only picks one of that chat's paused pairs; acpmux resumes no pair the
+        // chat is not in, and only for a connection that proved the person key (hub/person.rs).
+        "_acpmux/agent_pair_resume",
     ]
 
-    /// The shape of a reply the relay filters itself, without relying on the daemon's redaction.
-    public nonisolated indirect enum ReplyShape: Sendable {
-        case string
-        case object([String: ReplyShape])
-        case list(ReplyShape)
-        /// Only the scheme of the URL in the sibling field `source` (`ssh`, `ws`, `wss`), so the
-        /// page learns a peer's transport without its URL (which can carry a user or a token).
-        case scheme(from: String)
-    }
-
-    /// The URL schemes a `.scheme` field may report; any other scheme is dropped.
-    static let reportedSchemes: Set<String> = ["ssh", "ws", "wss"]
-
-    /// Replies filtered to the fields the pane renders; everything else is dropped, at every depth.
-    /// `_acpmux/status`: the pane reads only `peers[].name` and each peer's `transport`, the
-    /// scheme of its `url` (direct.ts, after initialize; environments.ts peerKindsFromStatus).
-    public static let replyShapes: [String: ReplyShape] = [
-        "_acpmux/status": .object([
-            "peers": .list(.object(["name": .string, "transport": .scheme(from: "url")])),
-        ]),
-    ]
-
-    /// `value` cut to `shape`: nil when it does not fit (a list keeps only the items that fit).
-    static func filtered(_ value: Any, to shape: ReplyShape) -> Any? {
-        switch shape {
-        case .string:
-            return value as? String
-        case .scheme:
-            guard let scheme = (value as? String).flatMap({ URLComponents(string: $0)?.scheme?.lowercased() }),
-                  reportedSchemes.contains(scheme) else { return nil }
-            return scheme
-        case .list(let item):
-            return (value as? [Any])?.compactMap { filtered($0, to: item) }
-        case .object(let fields):
-            guard let object = value as? [String: Any] else { return nil }
-            let kept = fields.compactMap { key, field -> (String, Any)? in
-                let source: String
-                if case .scheme(let from) = field { source = from } else { source = key }
-                return object[source].flatMap { filtered($0, to: field) }.map { (key, $0) }
-            }
-            // An object with none of its fields is dropped (a peer with no name renders nothing).
-            return kept.isEmpty ? nil : Dictionary(uniqueKeysWithValues: kept)
-        }
-    }
-
-    /// A reply to a filtered request, rebuilt with the page's id (raw JSON) and its filtered
-    /// result. An error keeps only its code and message.
-    static func filteredReply(_ object: [String: Any], shape: ReplyShape, pageID: String) -> String {
-        let id = (try? JSONSerialization.jsonObject(with: Data(pageID.utf8), options: [.fragmentsAllowed])) ?? NSNull()
-        var reply: [String: Any] = ["jsonrpc": "2.0", "id": id]
-        if let error = object["error"] as? [String: Any] {
-            reply["error"] = ["code": error["code"] as? Int ?? -32603, "message": error["message"] as? String ?? ""]
-        } else {
-            reply["result"] = object["result"].flatMap { filtered($0, to: shape) } ?? [String: Any]()
-        }
-        let data = (try? JSONSerialization.data(withJSONObject: reply, options: [.sortedKeys])) ?? Data()
-        return String(decoding: data, as: UTF8.self)
-    }
-
     /// Notifications (no `id`).
     public static let notifications: Set<String> = ["session/cancel"]
 
@@ -232,7 +178,7 @@ nonisolated enum AcpmuxPaneMethods {
         "session/prompt", "session/set_mode", "session/set_config_option", "session/set_model", "session/cancel",
         "_acpmux/kill", "_acpmux/draft_get", "_acpmux/draft_set", "_acpmux/bookmark_get", "_acpmux/bookmark_set", "_acpmux/queue_remove", "_acpmux/queue_edit", "_acpmux/permission_respond", "_acpmux/permission_group_respond", "_acpmux/permission_chat_revoke",
         "_acpmux/secret_submit", "_acpmux/archive", "_acpmux/markUnread", "_acpmux/side", "_acpmux/btw",
-        "_acpmux/offer_respond", "_acpmux/subagent_stop",
+        "_acpmux/offer_respond", "_acpmux/subagent_stop", "_acpmux/agent_pair_resume",
     ]
 
     /// Params beside `sessionId` that name a session, which must be in the pane's scope too: New
@@ -304,6 +250,8 @@ nonisolated enum AcpmuxPaneMethods {
         "_acpmux/permission_group_respond": .whenDecisionAllows,
         // The card's Provide hands over a secret (its Decline is a click too).
         "_acpmux/secret_submit": .always,
+        // Resume runs turns: the held messages go to both chats of the pair.
+        "_acpmux/agent_pair_resume": .always,
         // _acpmux/permission_chat_revoke revokes: no gesture.
         // _acpmux/offer_respond declines, or links the page's own new chat: no gesture (the work
         // Start begins is its session/prompt, which has one).

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AgentPaneHost.swift

@@ -80,6 +80,11 @@ public actor AcpmuxHost: AgentPaneHostProviding {
     /// the `agent.suggestedTasks` Debug Settings toggle), read at each daemon start: a toggle applies to the next daemon
     /// this app starts, never to the one already running.
     private let offersSessionTools: @Sendable () -> Bool
+    /// Whether the daemon keeps the agent message runaway guard on now (`AcpmuxEnvironment.agentPairGuard`,
+    /// the `agent.pairGuard` Debug Settings toggle), read at each daemon start like the offer tools.
+    private let agentPairGuard: @Sendable () -> Bool
+    /// The guard's cap and window in seconds now (`agent.pairCap`, `agent.pairWindow`), read with it.
+    private let agentPairCap: @Sendable () -> (messages: Int, windowSeconds: Int)
     /// Called with the daemon socket after each successful find or start, so
     /// the Computer Use helper v2 can register this daemon.
     private let daemonReady: @Sendable (String) async -> Void
@@ -104,6 +109,8 @@ public actor AcpmuxHost: AgentPaneHostProviding {
         self.resolveEnvironment = { environment }
         self.computerUse = { [:] }
         self.offersSessionTools = { environment?.offersSessionTools ?? false }
+        self.agentPairGuard = { environment?.agentPairGuard ?? true }
+        self.agentPairCap = { (environment?.agentPairCap ?? 20, environment?.agentPairWindowSeconds ?? 600) }
         self.daemonReady = { _ in }
         self.startsDaemons = startsDaemons
         self.healReplaced = healReplaced
@@ -114,10 +121,16 @@ public actor AcpmuxHost: AgentPaneHostProviding {
     public init(resolve: @escaping @Sendable () -> AcpmuxEnvironment?,
                 computerUse: @escaping @Sendable () -> [String: String] = { [:] },
                 offersSessionTools: @escaping @Sendable () -> Bool = { AgentPaneTunables.suggestedTasks.value },
+                agentPairGuard: @escaping @Sendable () -> Bool = { AgentPaneTunables.agentPairGuard.value },
+                agentPairCap: @escaping @Sendable () -> (messages: Int, windowSeconds: Int) = {
+                    (Int(AgentPaneTunables.agentPairCap.value), Int(AgentPaneTunables.agentPairWindow.value))
+                },
                 daemonReady: (@Sendable (String) async -> Void)? = nil) {
         self.resolveEnvironment = resolve
         self.computerUse = computerUse
         self.offersSessionTools = offersSessionTools
+        self.agentPairGuard = agentPairGuard
+        self.agentPairCap = agentPairCap
         self.daemonReady = daemonReady ?? { _ in }
         self.startsDaemons = true
         self.healReplaced = nil
@@ -161,6 +174,8 @@ public actor AcpmuxHost: AgentPaneHostProviding {
         }
         environment.computerUse = computerUse()
         environment.offersSessionTools = offersSessionTools()
+        environment.agentPairGuard = agentPairGuard()
+        (environment.agentPairCap, environment.agentPairWindowSeconds) = agentPairCap()
         let daemonSocket = environment.socketPath
         Self.logger.info("acpmux environment resolved executable=\(environment.executable.path, privacy: .public) home=\(environment.home.path, privacy: .public) socket=\(environment.socketPath, privacy: .public) startsDaemon=\(startsDaemon, privacy: .public)")
         // task-owner: stored in inFlight and cleared when it settles; callers await its value

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AgentPaneTunables+AgentPairGuard.swift

@@ -0,0 +1,27 @@
+public import CmuxNextDesign
+import CmuxNextPages
+
+nonisolated extension AgentPaneTunables {
+    /// The runaway guard for agent-to-agent messages (acpmux `hub/agent_pairs.rs`): two agent
+    /// sessions that keep messaging each other without a tool call or file change in between, or
+    /// that keep sending the same message, are paused until the person resumes them. Off, the
+    /// daemon this app starts gets `ACPMUX_AGENT_PAIR_GUARD=0`. Read at each daemon start, so a
+    /// toggle applies to the next one.
+    public static let agentPairGuard = Tunable<Bool>.toggle(
+        "agent.pairGuard", PageTunables.section, "Pause agents messaging in a loop",
+        help: "Two agents that keep messaging each other without making progress are paused until you resume them.",
+        default: true, code: "AgentPaneTunables.agentPairGuard")
+
+    /// The guard's cap: two agents that exchange more than this many messages within
+    /// ``agentPairWindow`` with no prompt from the person are paused (`ACPMUX_AGENT_PAIR_MAX_MESSAGES`).
+    public static let agentPairCap = Tunable<Double>.number(
+        "agent.pairCap", PageTunables.section, "Agent message cap",
+        help: "Messages two agents may exchange without you. 0 is off.",
+        default: 20, range: 0...200, step: 1, unit: .count, code: "AgentPaneTunables.agentPairCap")
+
+    /// The window ``agentPairCap`` counts over (`ACPMUX_AGENT_PAIR_WINDOW_SECS`).
+    public static let agentPairWindow = Tunable<Double>.number(
+        "agent.pairWindow", PageTunables.section, "Agent message window",
+        help: "How long the cap counts. 0 is off.",
+        default: 600, range: 0...3600, step: 60, unit: .seconds, code: "AgentPaneTunables.agentPairWindow")
+}

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AgentPaneTunables.swift

@@ -350,6 +350,9 @@ public nonisolated struct AgentPaneTunables {
 
     public static var all: [TunableDescriptor] {
         [
+            agentPairGuard.descriptor,
+            agentPairCap.descriptor,
+            agentPairWindow.descriptor,
             chatWidth.descriptor,
             codexToolRuns.descriptor,
             composerPlainFooter.descriptor,