• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

umputun / agterm / 43835400636

16 Nov 2026 08:56AM UTC coverage: 94.274% (+0.2%) from 94.081%
43835400636

push

github

web-flow
feat(catalog): open a Mac window as a remote window (#1018)

* docs(plans): add remote window on a Mac origin plan

Mac and server hosts should offer the same structural window controls.
Keep today's Attach Remote dialog rules; handoff is a separate follow-up.

* feat(catalog): share catalog stream, receipts and per-window Recent Closed

Prepare agtermCore for a Mac serving a window's catalog:
- hello names a window, a refused frame ends a stream with its reason,
  and version can advertise a Mac catalog apart from agterm-server's
- the catalog stream and the operation receipt book move from
  AgtermServerKit into agtermCore behind host protocols; the server runs
  on them unchanged
- ControlStreamOwner.sendFinal writes one last line, then closes
- Recent Closed entries record their window, with per-window list,
  clear and reopen that refuses an entry restored into another window
- catalog op takes --window

* feat(catalog): serve a Mac window as a remote window catalog

A Mac in Live sessions mode answers catalog.subscribe and catalog.op for the window --window names: one catalog per
window on originEpoch, kept until quit, fed by the window's store and by zmx inventory reads taken off the main actor
only when the window's panes may have changed.

- an op-bearing request runs in its window and never reaches the remote route; a targeted op must name its target
  and stay inside the window, and a workspace holding rows attached from another Mac is not deleted
- receipts persist through the store the window library has open now; a closed or deleted window's file is never
  written, and a receipt finished while the window was closed is recorded when it reopens
- creation runs without selecting and waits, bounded, for the new row's panes; undo, Recent Closed and workspace.new
  keep the origin's selection and report none
- mail counts and Recent Closed republish; closing the window ends its streams with a non-final refusal
- version reports macCatalog and... (continued)

823 of 850 new or added lines in 41 files covered. (96.82%)

15 existing lines in 6 files now uncovered.

30753 of 32621 relevant lines covered (94.27%)

2239757.58 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

25.83
/agtermCore/Sources/agtermCore/ControlActionsDefaults.swift
1
import Foundation
2

3
// Default `ControlActions` implementations, kept out of `ControlDispatcher.swift` so that file stays
4
// inside the 1000-line limit. They keep outside conformers building when the shared protocol grows:
5
// Mac-only commands refuse by name rather than answering an empty success, and compatibility overloads
6
// delegate to the older form.
7
public extension ControlActions {
8
    func resolveMessagePane(_: MessageAddress) -> Result<MessageRecipient, MessagePaneError> {
×
9
        .failure(.unsupported)
×
10
    }
×
11

12
    func messagePanes(workspace _: String?, window _: String?) -> Result<[MessageRecipient], MessagePaneError> {
×
13
        .failure(.unsupported)
×
14
    }
×
15

16
    func messageQueued(_: UUID, from _: String?, to _: [MessageRecipient]) {}
×
17

18
    func attachCompanionPage(_: String?, window _: String?) -> ControlResponse {
×
19
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.companion.page.attach"))
×
20
    }
×
21

22
    func duplicateAsCompanion(_: String?, window _: String?, select _: Bool) -> ControlResponse {
×
23
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.companion.duplicate"))
×
24
    }
×
25

26
    func convertToCompanion(_: String?, window _: String?) -> ControlResponse {
×
27
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.companion.convert"))
×
28
    }
×
29

30
    func moveCompanion(_: String?, parent _: String, index _: Int?, window _: String?) -> ControlResponse {
×
31
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.companion.move"))
×
32
    }
×
33

34
    func createPageCompanion(_: String?, window _: String?, options _: ControlSessionOverlayOpenOptions) -> ControlResponse {
×
35
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.companion.page"))
×
36
    }
×
37

38
    func createPageSession(_: String?, window _: String?, options _: ControlSessionOverlayOpenOptions) -> ControlResponse {
×
39
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.page"))
×
40
    }
×
41

42
    func createCompanion(_: String?, options _: CompanionOptions, window _: String?) -> ControlResponse {
×
43
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.companion.new"))
×
44
    }
×
45

46
    func setSessionExpansion(_: String?, window _: String?, expanded: Bool) -> ControlResponse {
×
47
        ControlResponse(ok: false, error: ControlActionsUnsupported.message(expanded ? "session.expand" : "session.collapse"))
×
48
    }
×
49

50
    func reloadSessionOverlay(_: String?, window _: String?, pane _: OverlayPane?, current _: Bool) -> ControlResponse {
×
51
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.reload"))
×
52
    }
×
53

54
    func navigateSessionOverlay(_: String?, window _: String?, pane _: OverlayPane?,
55
                                navigation _: HtmlNavigation) -> ControlResponse {
×
56
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.navigate"))
×
57
    }
×
58

59
    func submitSessionOverlay(_: String?, window _: String?, pane _: OverlayPane?, value _: String) -> ControlResponse {
×
60
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.submit"))
×
61
    }
×
62

63
    func setSessionOverlayVisibility(_: String?, window _: String?, pane _: OverlayPane?,
64
                                     mode: OverlayVisibilityMode) -> ControlResponse {
×
65
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.\(mode.rawValue)"))
×
66
    }
×
67

68
    func setSessionOverlayFollow(_: String?, window _: String?, pane _: OverlayPane?,
69
                                 mode _: ControlToggleMode) async -> ControlResponse {
×
70
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.follow"))
×
71
    }
×
72

73
    func setSessionOverlayWrap(_: String?, window _: String?, pane _: OverlayPane?,
74
                               mode _: ControlToggleMode) async -> ControlResponse {
×
75
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.wrap"))
×
76
    }
×
77

78
    func searchSessionOverlay(_: String?, window _: String?, pane _: OverlayPane?,
79
                              request _: TextSearchRequest) async -> ControlResponse {
×
80
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.search"))
×
81
    }
×
82

83
    func stepSessionOverlayChanges(_: String?, window _: String?, pane _: OverlayPane?,
84
                                   forward _: Bool) async -> ControlResponse {
×
85
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.changes"))
×
86
    }
×
87

88
    func goSessionOverlayFiles(_: String?, window _: String?, pane _: OverlayPane?, to _: String) async -> ControlResponse {
×
89
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.files"))
×
90
    }
×
91

92
    // outcomes live in agtermCore, so every host answers the read the same way and owes no conformance
93
    func htmlPageResult(_ pageID: UUID) -> ControlResponse {
×
94
        HtmlPageOutcomes.shared.response(for: pageID)
×
95
    }
×
96

97
    func openAsk(_: PendingAsk, target _: String?, window _: String?,
98
                 placement _: ControlAskPlacement, follow _: Bool) -> ControlResponse {
×
99
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("ask.open"))
×
100
    }
×
101

102
    func askResult(_: String, window _: String?) -> ControlResponse {
×
103
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("ask.result"))
×
104
    }
×
105

106
    func cancelAsk(_: String, window _: String?) -> ControlResponse {
×
107
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("ask.cancel"))
×
108
    }
×
109

110
    func setFlaggedViewLayout(_: ControlFlaggedLayoutMode) -> ControlResponse {
×
111
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("sidebar.flagged-layout"))
×
112
    }
×
113

114
    func setSidebarDensity(_: ControlSidebarDensityMode) -> ControlResponse {
×
115
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("sidebar.density"))
×
116
    }
×
117

118
    func moveFlaggedSession(_: String?, window _: String?, anchor _: String,
119
                            placement _: FlaggedOrderPlacement) -> ControlResponse {
×
120
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.flag move"))
×
121
    }
×
122

123
    func setWorkspaceFlag(_: String?, window _: String?, mode _: ControlToggleMode) -> ControlResponse {
×
124
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("workspace.flag"))
×
125
    }
×
126

127
    func reloadHooks() -> ControlResponse {
×
128
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("hooks.reload"))
×
129
    }
×
130

131
    func listHooks() -> ControlResponse {
×
132
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("hooks.list"))
×
133
    }
×
134

135
    func clearBrowser() async -> ControlResponse {
×
136
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("browser.clear"))
×
137
    }
×
138

139
    func linkOpenMode(_: LinkOpenMode?) -> ControlResponse {
×
140
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("browser.links"))
×
141
    }
×
142

143
    func runCustomCommand(name _: String, target _: String?, window _: String?) -> ControlResponse {
×
144
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("keymap.run"))
×
145
    }
×
146

147
    func readRestoreMode() -> ControlResponse {
×
148
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("restore.mode"))
×
149
    }
×
150

151
    func setRestoreMode(_: RestoreMode) -> ControlResponse {
×
152
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("restore.mode"))
×
153
    }
×
154

155
    func listZmxDaemons() -> ControlResponse {
×
156
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.list"))
×
157
    }
×
158

159
    func pruneZmxDaemons() -> ControlResponse {
×
160
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.prune"))
×
161
    }
×
162

163
    func readZmxScreen(name _: String, fullBuffer _: Bool, lines _: Int?) -> ControlResponse {
×
164
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.screen"))
×
165
    }
×
166

167
    func killZmxPane(target _: String, window _: String?, pane _: ZmxPaneRole, paneID _: String) -> ControlResponse {
×
168
        ControlResponse(ok: false, error: "zmx.kill.pane is not supported by this control host")
×
169
    }
×
170

171
    func killZmxDaemon(target _: String, window _: String?, pane _: ZmxPaneRole) -> ControlResponse {
×
172
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.kill"))
×
173
    }
×
174

175
    func resetLiveSessions() -> ControlResponse {
×
176
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.reset"))
×
177
    }
×
178

179
    func openPresentation(session _: String) -> ControlResponse {
×
180
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.present"))
×
181
    }
×
182

183
    // only a headless server owns a catalog; a remote window must never bind to a live Mac's windows
184
    func catalogSubscribe() -> ControlResponse {
1 ✔
185
        ControlResponse(ok: false, error: "catalog.subscribe is not served by this agterm")
1 ✔
186
    }
1 ✔
187

188
    func detachSessions(_: [String], window _: String?) -> ControlResponse { Self.remoteWindowOnly("session.detach") }
1 ✔
189
    func reattachSession(_: String, window _: String?) -> ControlResponse { Self.remoteWindowOnly("session.reattach") }
1 ✔
190
    func detachWorkspace(_: String?, window _: String?) -> ControlResponse { Self.remoteWindowOnly("workspace.detach") }
1 ✔
191
    func reattachWorkspace(_: String, window _: String?) -> ControlResponse { Self.remoteWindowOnly("workspace.reattach") }
1 ✔
192
    func dismissRemoteUnknown(window _: String?) -> ControlResponse { Self.remoteWindowOnly("window.remote.dismiss") }
1 ✔
193

194
    static func remoteWindowOnly(_ command: String) -> ControlResponse {
5 ✔
195
        ControlResponse(ok: false, error: "\(command) acts only on a remote window")
5 ✔
196
    }
5 ✔
197

NEW
198
    func catalogOperation(_: String, sent _: CatalogPosition?, window _: String?) -> ControlResponse {
×
NEW
199
        ControlResponse(ok: false, error: "catalog.op is not served by this agterm")
×
UNCOV
200
    }
×
201

202
    var takesOperationReceipts: Bool { false }
1 ✔
203

204
    func windowRemoteOpen(host _: String) async -> ControlResponse {
1 ✔
205
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("window.remote.open"))
1 ✔
206
    }
1 ✔
207

208
    func windowRemoteOpen(host: String, originWindow: String?) async -> ControlResponse {
1 ✔
209
        guard originWindow == nil else { return ControlResponse(ok: false, error: ControlActionsUnsupported.message("--origin-window")) }
1 ✔
NEW
210
        return await windowRemoteOpen(host: host)
×
211
    }
1 ✔
212

213
    func claimOverlayJob(_ job: String, token: String?) -> ControlResponse {
1 ✔
214
        token == nil ? claimOverlayJob(job) : ControlResponse(ok: false, error: "job not claimable")
1 ✔
215
    }
1 ✔
216

217
    func claimOverlayJob(_: String) -> ControlResponse {
×
218
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.job.run"))
×
219
    }
×
220

221
    func claimPageServe(_: String) -> ControlResponse {
1 ✔
222
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.overlay.page.serve"))
1 ✔
223
    }
1 ✔
224

225
    func remoteTree(host _: String?) async -> ControlResponse {
×
226
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.tree"))
×
227
    }
×
228

229
    func attachRemoteSession(host: String, session: String, window: String?) async -> ControlResponse {
2 ✔
230
        guard window?.trimmedOrNil == nil else {
2 ✔
231
            return ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.attach --window"))
1 ✔
232
        }
1 ✔
233
        return await attachRemoteSession(host: host, session: session)
1 ✔
234
    }
2 ✔
235

236
    func openPick(_: PendingPick, session _: String, window _: String?, follow _: Bool) -> ControlResponse {
1 ✔
237
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("pick.open --session"))
1 ✔
238
    }
1 ✔
239

240
    func readSurfaceCursor(_ target: String?, window: String?, paneID: String?) -> ControlResponse {
×
241
        guard paneID?.isEmpty != false else {
×
242
            return ControlResponse(ok: false, error: ControlActionsUnsupported.message("surface.cursor --pane-id"))
×
243
        }
×
244
        return readSurfaceCursor(target, window: window)
×
245
    }
×
246

247
    func attachRemoteSession(host _: String, session _: String) async -> ControlResponse {
×
248
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.attach"))
×
249
    }
×
250

251
    func attachRemoteGroup(host _: String, session _: String, window _: String?) async -> ControlResponse {
1 ✔
252
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("zmx.attach.group"))
1 ✔
253
    }
1 ✔
254

255
    func splitSession(_ target: String?, window: String?, mode: String?, axis _: SplitAxis?) -> ControlResponse {
×
256
        splitSession(target, window: window, mode: mode)
×
257
    }
×
258

259
    func scratchSession(_ target: String?, window: String?, mode: String?, command: String?,
260
                        follow _: Bool) -> ControlResponse {
4 ✔
261
        scratchSession(target, window: window, mode: mode, command: command)
4 ✔
262
    }
4 ✔
263

264
    func swapSessionPanes(_: String?, window _: String?) async -> ControlResponse {
×
265
        ControlResponse(ok: false, error: "session.swap is not supported by this host")
×
266
    }
×
267

268
    func restartSessionPane(_: String?, window _: String?,
269
                            options _: ControlSessionRestartOptions) async -> ControlResponse {
×
270
        ControlResponse(ok: false, error: "session.restart is not supported by this host")
×
271
    }
×
272

273
    func takeSessionLead(_: String?, window _: String?, pane _: StatusPane?) -> ControlResponse {
×
274
        ControlResponse(ok: false, error: "session.lead is not supported by this host")
×
275
    }
×
276

277
    /// Not `ControlActionsUnsupported.message`, which says "on this platform": the divider exists wherever
278
    /// there is a sidebar, so a host refusing this has not implemented the command rather than lacking the
279
    /// thing it moves.
280
    func setSidebarWidth(_: Double, window _: String?) -> ControlResponse {
×
281
        ControlResponse(ok: false, error: "sidebar.width is not supported by this control host")
×
282
    }
×
283

284
    func closeSession(_ target: String?, window: String?, undoable: Bool) -> ControlResponse {
1 ✔
285
        guard !undoable else {
1 ✔
286
            return ControlResponse(ok: false, error: "session.close --undoable is not supported by this control host")
1 ✔
287
        }
1 ✔
288
        return closeSession(target, window: window)
×
289
    }
1 ✔
290

291
    func closeSessions(_ targets: [String], window: String?, undoable: Bool) -> ControlResponse {
1 ✔
292
        guard !undoable else {
1 ✔
293
            return ControlResponse(ok: false, error: "session.close --undoable is not supported by this control host")
1 ✔
294
        }
1 ✔
295
        return closeSessions(targets, window: window)
×
296
    }
1 ✔
297

298
    func terminateSessions(_: [String], window _: String?, undoable _: Bool) -> ControlResponse {
×
299
        ControlResponse(ok: false, error: "session.terminate is not supported by this control host")
×
300
    }
×
301

302
    func undoClose(_: String) -> ControlResponse {
1 ✔
303
        ControlResponse(ok: false, error: "session.undo is not supported by this control host")
1 ✔
304
    }
1 ✔
305

306
    func resizeSessionOverlay(_ target: String?, window: String?, sizePercent: Int?,
307
                              points: OverlayPointSize) -> ControlResponse {
×
308
        guard points.isEmpty else {
×
309
            return ControlResponse(ok: false, error: "session.overlay.resize: --width/--height are not supported by this control host")
×
310
        }
×
311
        return resizeSessionOverlay(target, window: window, sizePercent: sizePercent)
×
312
    }
×
313

314
    func setSessionContext(_: String?, window _: String?, context _: String?) -> ControlResponse {
×
315
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.context"))
×
316
    }
×
317

318
    func setSessionInfo(_: String?, window _: String?, info _: SessionInfo?) -> ControlResponse {
×
319
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.info"))
×
320
    }
×
321

322
    func setSessionTint(_: String?, window _: String?, update _: ControlTintUpdate) -> ControlResponse {
×
323
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.tint"))
×
324
    }
×
325

326
    func setWorkspaceTint(_: String?, window _: String?, update _: ControlTintUpdate) -> ControlResponse {
×
327
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("workspace.tint"))
×
328
    }
×
329

330
    /// A host that predates tints creates an untinted session through its own form and refuses a tint,
331
    /// so the request never answers ok over a tint it dropped.
332
    func createSession(_ options: ControlSessionCreateOptions, tint: SidebarTint?) -> ControlResponse {
7 ✔
333
        guard tint == nil else {
7 ✔
334
            return ControlResponse(ok: false, error: ControlActionsUnsupported.message("session.new --tint"))
1 ✔
335
        }
6 ✔
336
        return createSession(options)
6 ✔
337
    }
7 ✔
338

339
    /// The workspace twin of the session default above.
340
    func createWorkspace(window: String?, name: String?, collapsed: Bool, tint: SidebarTint?) -> ControlResponse {
4 ✔
341
        guard tint == nil else {
4 ✔
342
            return ControlResponse(ok: false, error: ControlActionsUnsupported.message("workspace.new --tint"))
1 ✔
343
        }
3 ✔
344
        return createWorkspace(window: window, name: name, collapsed: collapsed)
3 ✔
345
    }
4 ✔
346

347
    func windowGo(direction _: WorkspaceNavigation) -> ControlResponse {
×
348
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("window.go"))
×
349
    }
×
350

351
    /// `agterm-linux` may implement the original session-wide HUD methods. New dispatchers preserve that
352
    /// behavior when the host has not adopted pane placement yet.
353
    func openHud(_ target: String?, window: String?, spec: HudSpec,
354
                 placement _: ControlHudPlacement) -> ControlResponse {
×
355
        openHud(target, window: window, spec: spec)
×
356
    }
×
357

358
    func updateHud(_ target: String?, window: String?, spec: HudSpec,
359
                   placement _: ControlHudPlacement) -> ControlResponse {
×
360
        updateHud(target, window: window, spec: spec)
×
361
    }
×
362

363
    func listRecentClosed() -> ControlResponse {
×
364
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("recent.list"))
×
365
    }
×
366

367
    func clearRecentClosed() -> ControlResponse {
×
368
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("recent.clear"))
×
369
    }
×
370

371
    func listRecentClosed(window: String?) -> ControlResponse {
1 ✔
372
        guard window == nil else { return ControlResponse(ok: false, error: "recent.list takes no --window on this control host") }
1 ✔
373
        return listRecentClosed()
×
374
    }
1 ✔
375

376
    func clearRecentClosed(window: String?) -> ControlResponse {
1 ✔
377
        guard window == nil else { return ControlResponse(ok: false, error: "recent.clear takes no --window on this control host") }
1 ✔
378
        return clearRecentClosed()
×
379
    }
1 ✔
380

381
    func openRecentClosed(_: String?, window _: String?) -> ControlResponse {
×
382
        ControlResponse(ok: false, error: ControlActionsUnsupported.message("recent.open"))
×
383
    }
×
384
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE TRIAL · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc