ccdeck 3.82.4 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/LICENSING.md +42 -4
  2. package/README.md +183 -72
  3. package/THIRD_PARTY_NOTICES.md +243 -17
  4. package/bin/cli/tui.js +58 -4
  5. package/bin/deck.js +27 -1
  6. package/dist/web/assets/AccountBridge-fp-fsMx-.js +1 -0
  7. package/dist/web/assets/AccountSection-Cu-96Q00.js +1 -0
  8. package/dist/web/assets/BrowserWatchModal-CvUx07C6.js +1 -0
  9. package/dist/web/assets/FeedbackConversations-BgVk0nkA.js +1 -0
  10. package/dist/web/assets/IntegrationModal-CEj5oJg4.js +7 -0
  11. package/dist/web/assets/IntegrationSkeleton-DD7YiFgd.js +1 -0
  12. package/dist/web/assets/RadioPanel-BhnzWRCT.js +1 -0
  13. package/dist/web/assets/StageShell-DmJu3dU1.js +4 -0
  14. package/dist/web/assets/TrafficRadar-C8-ieIw5.js +8 -0
  15. package/dist/web/assets/UsageHistoryModal-BThv9Kja.js +1 -0
  16. package/dist/web/assets/addon-unicode-graphemes-DW3WJwyh.js +18 -0
  17. package/dist/web/assets/addon-web-links-BWjmmSgS.js +12 -0
  18. package/dist/web/assets/addon-webgl-CLK4R-_u.js +75 -0
  19. package/dist/web/assets/app-DtosBis5.css +1 -0
  20. package/dist/web/assets/app-ZMmmEHxF.js +361 -0
  21. package/dist/web/assets/{index-B-l-VxLm.js → index-zSxC5ueJ.js} +1 -1
  22. package/dist/web/assets/inspector-status-pane-BgQG0bQi.js +1 -0
  23. package/dist/web/assets/screens-DD0uCtat.js +12 -0
  24. package/dist/web/assets/screens-DUniTTbC.css +1 -0
  25. package/dist/web/assets/stage-board-J2rKA9Pg.js +2 -0
  26. package/dist/web/assets/use-account-DvFObI4M.js +1 -0
  27. package/dist/web/assets/xterm-4jYizCpg.js +27 -0
  28. package/dist/web/assets/xterm-sheet-6GBZ9nXN.css +32 -0
  29. package/dist/web/index.html +16 -6
  30. package/package.json +13 -1
  31. package/release-notes.json +69 -1
  32. package/src/server/account-client.mjs +196 -0
  33. package/src/server/account-connect.mjs +238 -0
  34. package/src/server/account-flag.mjs +106 -0
  35. package/src/server/account-projects.mjs +1 -1
  36. package/src/server/account-service.mjs +532 -0
  37. package/src/server/account-status.mjs +293 -0
  38. package/src/server/account-store.mjs +137 -0
  39. package/src/server/account-sync.mjs +473 -0
  40. package/src/server/account-token-store.mjs +216 -0
  41. package/src/server/account-ui-fields.mjs +126 -0
  42. package/src/server/account-watch.mjs +1 -1
  43. package/src/server/browser-watch-log.mjs +1 -1
  44. package/src/server/browser-watch-store.mjs +1 -1
  45. package/src/server/ccdeck-account-routes.mjs +252 -0
  46. package/src/server/ccusage-install.mjs +2 -2
  47. package/src/server/ccusage-registry.mjs +4 -4
  48. package/src/server/ccusage-session.mjs +11 -0
  49. package/src/server/claude-accounts.mjs +1 -1
  50. package/src/server/claude-recovery.mjs +9 -4
  51. package/src/server/claude-settings-catalog.mjs +6 -6
  52. package/src/server/claude-settings.mjs +1 -1
  53. package/src/server/codex-auto.mjs +1 -1
  54. package/src/server/codex-cost-usage.mjs +7 -2
  55. package/src/server/codex-live-checkpoint.mjs +24 -9
  56. package/src/server/codex-live-engine.mjs +14 -4
  57. package/src/server/codex-live-handoff.mjs +53 -9
  58. package/src/server/codex-names.mjs +49 -0
  59. package/src/server/codex-translate.mjs +1 -1
  60. package/src/server/codex-ultrafast.d.mts +3 -0
  61. package/src/server/codex-ultrafast.mjs +5 -0
  62. package/src/server/codex-watch.mjs +25 -0
  63. package/src/server/command-panel-engine.mjs +300 -0
  64. package/src/server/command-panel-platform.mjs +99 -0
  65. package/src/server/cswap-auto-choice.mjs +1 -1
  66. package/src/server/cswap-auto-loop.mjs +1 -1
  67. package/src/server/cswap-install.mjs +21 -40
  68. package/src/server/deck-home.mjs +6 -0
  69. package/src/server/deck-prefs.mjs +53 -1
  70. package/src/server/detach.mjs +1 -1
  71. package/src/server/engine-download.mjs +277 -0
  72. package/src/server/engine-install.mjs +378 -0
  73. package/src/server/engine-package.mjs +267 -0
  74. package/src/server/event-log.mjs +7 -1
  75. package/src/server/event-pipeline.mjs +29 -1
  76. package/src/server/ghostty-handoff.mjs +81 -0
  77. package/src/server/index.mjs +143 -5
  78. package/src/server/installer.mjs +4 -1
  79. package/src/server/integrations/jira-write-guard.mjs +14 -208
  80. package/src/server/integrations/store.mjs +37 -19
  81. package/src/server/integrations/write-guard.mjs +223 -0
  82. package/src/server/intel-cpu-temperature.mjs +26 -0
  83. package/src/server/lifecycle.mjs +69 -6
  84. package/src/server/log-replay.mjs +4 -0
  85. package/src/server/login-service.mjs +7 -1
  86. package/src/server/macmon.mjs +1 -1
  87. package/src/server/npm-latest.mjs +1 -1
  88. package/src/server/org-telemetry.mjs +1 -1
  89. package/src/server/output-watch.mjs +4 -1
  90. package/src/server/panel-provenance.mjs +390 -0
  91. package/src/server/pinned-build.mjs +14 -0
  92. package/src/server/prefs-refusal.mjs +8 -1
  93. package/src/server/prefs-routes.mjs +60 -11
  94. package/src/server/pro-engine-client.mjs +339 -0
  95. package/src/server/pro-engine-install.mjs +294 -0
  96. package/src/server/pro-engine-terminal.mjs +308 -0
  97. package/src/server/project-discovery.mjs +139 -0
  98. package/src/server/provider-session-name.mjs +58 -0
  99. package/src/server/quota-closes.mjs +1 -1
  100. package/src/server/quota-history.mjs +1 -1
  101. package/src/server/reports.mjs +86 -21
  102. package/src/server/request-gates.mjs +34 -5
  103. package/src/server/restart-note.mjs +1 -1
  104. package/src/server/seed-boundary.mjs +489 -0
  105. package/src/server/session-counts.mjs +244 -0
  106. package/src/server/session-deck-names.mjs +143 -0
  107. package/src/server/session-enrichment.mjs +43 -6
  108. package/src/server/session-name-route.mjs +73 -0
  109. package/src/server/session-summary.mjs +12 -1
  110. package/src/server/session-transcript-routes.mjs +167 -0
  111. package/src/server/swap-log.mjs +1 -1
  112. package/src/server/system-metrics.mjs +57 -0
  113. package/src/server/terminal-bridge.mjs +485 -0
  114. package/src/server/terminal-folder.mjs +61 -0
  115. package/src/server/terminal-js-routes.mjs +752 -0
  116. package/src/server/terminal-routes.mjs +553 -0
  117. package/src/server/terminal-sessions.mjs +759 -0
  118. package/src/server/terminal-socket.mjs +403 -0
  119. package/src/server/terminal-target.mjs +928 -0
  120. package/src/server/thermal-metrics.mjs +13 -9
  121. package/src/server/tmux-control.mjs +1319 -0
  122. package/src/server/tmux-download.mjs +220 -0
  123. package/src/server/tmux.mjs +542 -0
  124. package/src/server/token-redact.mjs +42 -3
  125. package/src/server/tool-audit-report.mjs +44 -6
  126. package/src/server/tool-audit-routes.mjs +12 -1
  127. package/src/server/tool-audit.mjs +42 -8
  128. package/src/server/traffic-radar-monitor.mjs +1 -1
  129. package/src/server/traffic-radar-permission.mjs +1 -1
  130. package/src/server/transcript-gate.mjs +1 -1
  131. package/src/server/transcript-scan.mjs +15 -7
  132. package/src/server/transcript-turns.mjs +154 -0
  133. package/src/server/tui-network.mjs +1 -0
  134. package/src/server/tui-view.mjs +28 -0
  135. package/src/server/utf8-carry.mjs +159 -0
  136. package/src/server/uv-bootstrap.mjs +2 -2
  137. package/src/server/windows-acl.mjs +158 -0
  138. package/src/server/ws-frames.mjs +690 -0
  139. package/dist/web/assets/BrowserWatchModal-CWVooKxD.js +0 -1
  140. package/dist/web/assets/IntegrationModal-DLX43RIK.js +0 -7
  141. package/dist/web/assets/RadioPanel-Cj6PjrvQ.js +0 -1
  142. package/dist/web/assets/TrafficRadar-Bq1YcuHB.js +0 -8
  143. package/dist/web/assets/UsageHistoryModal-CMSCca5_.js +0 -1
  144. package/dist/web/assets/app-BHxsMz3-.js +0 -358
  145. package/dist/web/assets/app-CbXmr9rC.css +0 -1
@@ -0,0 +1,553 @@
1
+ // The Command Panel's eight HTTP routes the engine answers, the folder check
2
+ // the deck answers itself (terminal-folder.mjs), and the wiring that hands its socket
3
+ // to the upgrade in terminal-socket.mjs.
4
+ //
5
+ // GET /api/terminal/status is tmux here, and new enough? No paths.
6
+ // GET /api/terminal/target can this session be attached to, and how?
7
+ // GET /api/terminal/hosts sessions still on an older session host
8
+ // POST /api/terminal/open attach: a ticket for the socket, or why not
9
+ // POST /api/terminal/adopt reopen a session started outside the deck, here
10
+ // POST /api/terminal/launch start a new agent in a deck-owned tmux session
11
+ // POST /api/terminal/claim is this new Codex the one a launch started?
12
+ // POST /api/terminal/hosts/end end the sessions on one older host, as reviewed
13
+ // POST /api/terminal/folder can an agent start in this folder? (the deck answers)
14
+ //
15
+ // And the engine's own install, which the page offers where the engine is not
16
+ // here (engine-install.mjs), under the same switch and the same gates:
17
+ //
18
+ // GET /api/terminal/engine which engine is here, an install's progress
19
+ // POST /api/terminal/engine/install download the pinned package and install it
20
+ // POST /api/terminal/engine/install-file install a package file sent as the body
21
+ // POST /api/terminal/engine/cancel cancel a download
22
+ // POST /api/terminal/engine/remove remove the installed engine
23
+ //
24
+ // The two hosts routes are the Windows session host's: an engine with no
25
+ // session host answers that it cannot (`no-terminal`), which the page reads
26
+ // as nothing to show.
27
+ //
28
+ // SWITCHED OFF, THEY ARE NOT THERE. Every handler asks terminalOn first and,
29
+ // when it says no, answers exactly what index.mjs answers for an /api path
30
+ // with no route — the same status and the same body — so a deck with the
31
+ // panel off is indistinguishable from one built before it existed, and none of
32
+ // this asks anything of anyone. A POST asks again once its body is in, right
33
+ // before the engine would be asked (`answer`): a switch-off that lands while
34
+ // the body arrives is a switch-off before the request. And once more when the
35
+ // engine has answered: a switch-off that lands while it works on the question
36
+ // mints no ticket, and the page is told what was done (answeredAfterOff).
37
+ // The request gates still run first, as they do
38
+ // for every path: the three reads are in GUARDED_READS and the five POSTs are
39
+ // mutations, so what is refused there is refused whatever the switch says.
40
+ //
41
+ // THE ENGINE ANSWERS THEM. Everything HTTP stays here — the switch, the gates,
42
+ // the body under its cap, the ticket store — and each route's question goes
43
+ // to the optional local engine (`engine`, pro-engine-terminal.mjs), which
44
+ // answers the status and body the page reads. There is no other terminal
45
+ // behind it: a deck whose engine cannot take the question answers `{ ok:
46
+ // false, error, code }` (engineRefusal), 409 for a state of this machine the
47
+ // panel can say, 503 for a moment it waits out, and never serves the route
48
+ // some other way. The JS backend these routes once ran is a test's
49
+ // (terminal-js-routes.mjs, handed in as `jsBackend`); nothing here imports it.
50
+ //
51
+ // THE DECK STILL FETCHES ITS OWN TMUX. On Linux and macOS the engine runs each
52
+ // session inside the deck's own tmux server, which needs tmux 3.2 or newer,
53
+ // and many machines have none: no Mac ships one. The engine's status says so
54
+ // with `fixable`, and the deck then does what it did before the engine: it
55
+ // fetches ccdeck's own build (tmux-download.mjs: pinned SHA-256, into
56
+ // <data>/tools/tmux, the folder the engine's lookup also reads), answers
57
+ // "installing" with how far it has got, and once the build has landed tells
58
+ // the engine to look again (`terminal.forgetTmux`). That download is the one
59
+ // piece of the JS backend's tmux handling on the product's path;
60
+ // terminal-js-offpath.test.ts holds that nothing else of it is.
61
+ //
62
+ // THE PAGE NEVER NAMES A PANE. It names a session — an id, a provider, a
63
+ // folder — and the engine works the rest out. Where its answer carries a
64
+ // ticket, the engine gives an opaque handle instead, and the ticket is minted
65
+ // here over it: the handle never reaches the page, and nothing the page sends
66
+ // is ever used as a pane.
67
+ import { backgroundInGhostty } from "./ghostty-handoff.mjs";
68
+ import { existsSync } from "node:fs";
69
+ import { PRODUCT } from "./brand.mjs";
70
+ import { commandPanel } from "./command-panel-engine.mjs";
71
+ import { deckDataDir } from "./deck-home.mjs";
72
+ import { terminalOn } from "./deck-prefs.mjs";
73
+ import { ENGINE_TARBALL_MAX } from "./engine-download.mjs";
74
+ import { readBody, readBytes, send } from "./http-io.mjs";
75
+ import { panelProvenance, withProvenance } from "./panel-provenance.mjs";
76
+ import { heldPrefs } from "./prefs-state.mjs";
77
+ import { engineRefusal } from "./pro-engine-terminal.mjs";
78
+ import { checkFolder } from "./terminal-folder.mjs";
79
+ import { discoverProjects } from "./project-discovery.mjs";
80
+ import { createTicketStore } from "./terminal-socket.mjs";
81
+ import {
82
+ TMUX_BUILD, ensureManagedTmux, managedTmuxPath, recentTmuxFailure, tmuxDownloadBlocked, tmuxDownloadProgress,
83
+ } from "./tmux-download.mjs";
84
+
85
+ /** The bodies here are an id, a provider and a folder. A few kilobytes is far
86
+ * above any of them, and readBody answers 413 for anything larger. */
87
+ const BODY_LIMIT = 8 * 1024;
88
+
89
+ // The tickets every route here mints and the upgrade redeems. One per
90
+ // process, like the deck's token: a restarted deck has none of the old ones,
91
+ // and a panel that reconnects asks for a new ticket first.
92
+ const TICKETS = createTicketStore();
93
+
94
+ /**
95
+ * ccdeck's own tmux (tmux-download.mjs), as the status route asks about it:
96
+ *
97
+ * blocked() why no download may start here, or null: switched off
98
+ * (AGENTS_DECK_NO_INSTALL=1, AGENTS_DECK_NO_DOWNLOAD=1), or
99
+ * no build for this machine (Windows, an arch other than
100
+ * x64 and arm64);
101
+ * landed() whether the build is in its folder already;
102
+ * recentFailure() the last download's failure while it is believed;
103
+ * out whether a download started here is still out;
104
+ * progress() how far that one has got, "checking" once its build has
105
+ * landed and the engine is being told, or null;
106
+ * start(then) start one unless one is out, and run `then` once its
107
+ * build has landed. Never awaited, never rejects.
108
+ *
109
+ * The download itself is ensureManagedTmux's, shared by everyone who asks
110
+ * while it is out. `env`, `platform` and `arch` say where it goes and which
111
+ * build it is; `build`, `fetchImpl` and `execImpl` are for tests.
112
+ */
113
+ export function ownTmux({
114
+ env = process.env, platform = process.platform, arch = process.arch, build = TMUX_BUILD, fetchImpl, execImpl,
115
+ } = {}) {
116
+ const dataDir = () => deckDataDir(platform, env);
117
+ let out = null; // { landed }
118
+ return Object.freeze({
119
+ blocked: () => tmuxDownloadBlocked({ env, platform, arch, build }),
120
+ landed: () => existsSync(managedTmuxPath(dataDir(), build)),
121
+ recentFailure: () => recentTmuxFailure(),
122
+ get out() { return out !== null; },
123
+ progress: () => (out ? tmuxDownloadProgress() ?? (out.landed ? { stage: "checking" } : null) : null),
124
+ start(then) {
125
+ if (out) return;
126
+ const run = { landed: false };
127
+ out = run;
128
+ void ensureManagedTmux({
129
+ env, platform, arch, build, dataDir: dataDir(),
130
+ ...(fetchImpl ? { fetchImpl } : {}), ...(execImpl ? { execImpl } : {}),
131
+ })
132
+ .then(async (r) => {
133
+ if (!r?.ok) return;
134
+ run.landed = true;
135
+ await then();
136
+ })
137
+ .catch(() => {})
138
+ .finally(() => { if (out === run) out = null; });
139
+ },
140
+ });
141
+ }
142
+
143
+ /** The deck's own: the default `ownTmux` of the routes below. */
144
+ const OWN_TMUX = ownTmux();
145
+
146
+ /**
147
+ * Everything these routes reach outside themselves, with the real ones as
148
+ * defaults: the switch, the ticket store and the engine. startServer passes
149
+ * its `terminal` option through here; the product passes nothing.
150
+ *
151
+ * `engine` is the optional local engine's terminal, as engineTerminals in
152
+ * pro-engine-terminal.mjs builds it for a client. The deck's own is the
153
+ * Command Panel's (command-panel-engine.mjs), which looks for an engine only
154
+ * once a route asks it — so only with the switch on. A caller may hand
155
+ * another; with none, or one that is switched off, every route answers that
156
+ * the engine is not installed and nothing is asked of it.
157
+ *
158
+ * `jsBackend` is TESTS ONLY: the JS backend (terminal-js-routes.mjs'
159
+ * jsTerminalBackend), which a test hands startServer to run the routes on a
160
+ * tmux of its own — the parity oracle the engine is checked against. Nothing
161
+ * the deck runs imports it, so no setting, variable, flag or request can turn
162
+ * it on; when it is there, it answers in the engine's place.
163
+ *
164
+ * `provenance` is the deck's record of the sessions its panel started
165
+ * (panel-provenance.mjs): told of each launch, adopt and claim the engine
166
+ * answers, and asked for the provenance a case C target carries. Never asked
167
+ * whether anything may be done.
168
+ *
169
+ * `ownTmux` is ccdeck's own tmux download (ownTmux above), which a status the
170
+ * engine calls `fixable` runs (withOwnTmux). A test hands one that fetches
171
+ * from a stand-in, never from the network.
172
+ */
173
+ export function terminalDeps(overrides = {}) {
174
+ return {
175
+ enabled: () => terminalOn(heldPrefs.current()),
176
+ tickets: TICKETS,
177
+ engine: commandPanel,
178
+ provenance: panelProvenance,
179
+ ownTmux: OWN_TMUX,
180
+ jsBackend: null,
181
+ ...(overrides ?? {}),
182
+ };
183
+ }
184
+
185
+ /**
186
+ * What terminal-socket's installTerminalUpgrade needs from this side: the
187
+ * switch, the ticket store the routes mint into, and the engine. A test's JS
188
+ * backend adds its bridge, for the tickets it minted. Same `overrides` as
189
+ * terminalDeps.
190
+ */
191
+ export function terminalUpgradeOptions(overrides = {}) {
192
+ const d = terminalDeps(overrides);
193
+ return {
194
+ enabled: () => d.enabled(),
195
+ tickets: d.tickets,
196
+ ...(d.engine ? { engine: d.engine } : {}),
197
+ ...(d.jsBackend ? { openBridge: d.jsBackend.openBridge(d) } : {}),
198
+ };
199
+ }
200
+
201
+ /** GET /api/terminal/status → `{ ok: true, platform, tmux }`, or why not. */
202
+ export async function handleTerminalStatus(req, res, options) {
203
+ const d = terminalDeps(options);
204
+ if (!d.enabled()) return notFound(res);
205
+ return answer(d, req, res, "status", null);
206
+ }
207
+
208
+ /** Guarded, bounded suggestions from this user's working folders. */
209
+ export async function handleTerminalProjects(_req, res, options) {
210
+ const d = terminalDeps(options);
211
+ if (!d.enabled()) return notFound(res);
212
+ if (!d.jsBackend && d.engine?.enabled !== true) {
213
+ const { status, body } = engineRefusal("not-installed");
214
+ return send(res, status, body);
215
+ }
216
+ const result = await (d.discoverProjects ?? discoverProjects)();
217
+ if (!d.enabled()) return notFound(res);
218
+ return send(res, 200, { ok: true, ...result });
219
+ }
220
+
221
+ /** GET /api/terminal/target?session=&provider=&cwd= → `{ ok: true, target }`. */
222
+ export async function handleTerminalTarget(req, res, url, options) {
223
+ const d = terminalDeps(options);
224
+ if (!d.enabled()) return notFound(res);
225
+ const query = {
226
+ sessionId: url?.searchParams.get("session") ?? "",
227
+ provider: url?.searchParams.get("provider") ?? "",
228
+ cwd: url?.searchParams.get("cwd") ?? "",
229
+ };
230
+ return answer(d, req, res, "target", query);
231
+ }
232
+
233
+ /** GET /api/terminal/hosts → `{ ok: true, hosts, launchesRefused }`: the
234
+ * older session hosts still running sessions, each `{ generation, state,
235
+ * sessions }`, and why new sessions are refused while they run, or null. */
236
+ export async function handleTerminalHosts(req, res, options) {
237
+ const d = terminalDeps(options);
238
+ if (!d.enabled()) return notFound(res);
239
+ return answer(d, req, res, "hosts", null);
240
+ }
241
+
242
+ /** POST /api/terminal/hosts/end `{ generation, sessions }` → `{ ok: true,
243
+ * ended }`: end exactly the sessions the reader reviewed on that host. 409
244
+ * `consent-outdated` when its sessions changed since, `host-gone` when it no
245
+ * longer runs. */
246
+ export async function handleTerminalEndHosts(req, res, options) {
247
+ return posted(req, res, options, "endHosts");
248
+ }
249
+
250
+ /** POST /api/terminal/claim `{ key, sessionId, provider, cwd }` → `{ ok: true,
251
+ * claimed, target }`: whether the session runs in the pane the page launched
252
+ * under `key`. */
253
+ export async function handleTerminalClaim(req, res, options) {
254
+ return posted(req, res, options, "claim");
255
+ }
256
+
257
+ /** POST /api/terminal/open `{ sessionId, provider, cwd, cols?, rows?, colours?
258
+ * }` → a ticket, or `{ ok: false, target }` with HTTP 200: not attachable is
259
+ * a state. The optional pane size and colours are adopt's, passed on as they
260
+ * came: when the engine opens the session by starting a client, the client
261
+ * starts at that size and in those colours. */
262
+ export async function handleTerminalOpen(req, res, options) {
263
+ return posted(req, res, options, "open");
264
+ }
265
+
266
+ /** POST /api/terminal/adopt `{ sessionId, provider, cwd }`: reopen an ended
267
+ * session in a deck pane. 409 `still-running` while its process lives. */
268
+ export async function handleTerminalAdopt(req, res, options) {
269
+ return posted(req, res, options, "adopt");
270
+ }
271
+
272
+ const backgroundRequests = new Map();
273
+ const BACKGROUND_REQUEST_COOLDOWN = 15_000;
274
+
275
+ /** A local request to use Claude's background shortcut on its exact Ghostty surface.
276
+ * With `check: true` it sends nothing and answers `{ ok: true, movable }`:
277
+ * whether the same request without `check` could be made. The pane offers
278
+ * the move only when `movable` is true. */
279
+ export async function handleTerminalBackground(req, res, options) {
280
+ const d = terminalDeps(options);
281
+ if (!d.enabled()) return notFound(res);
282
+ if (!["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(req.socket.remoteAddress)) {
283
+ return send(res, 403, { ok: false });
284
+ }
285
+ const body = await jsonBody(req, res);
286
+ if (res.headersSent) return;
287
+ if (!d.enabled()) return notFound(res);
288
+ if (body?.provider !== "claude" || typeof body.cwd !== "string" || !body.cwd.startsWith("/") ||
289
+ typeof body.sessionId !== "string" || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(body.sessionId)) {
290
+ return send(res, 400, { ok: false });
291
+ }
292
+ const session = { sessionId: body.sessionId.toLowerCase(), provider: "claude", cwd: body.cwd };
293
+ if (body.check === true) {
294
+ let movable = false;
295
+ if (d.engine?.enabled === true) {
296
+ const answer = await d.engine.route("target", session);
297
+ if (answer.status === 200 && answer.body?.target?.kind === "C") {
298
+ movable = await (d.background ?? backgroundInGhostty)(session, { enabled: d.enabled, check: true });
299
+ }
300
+ }
301
+ return send(res, 200, { ok: true, movable: movable === true });
302
+ }
303
+ if (backgroundRequests.has(session.sessionId)) return send(res, 409, { ok: false });
304
+ backgroundRequests.set(session.sessionId, true);
305
+ let sent = false;
306
+ try {
307
+ if (d.engine?.enabled !== true) return send(res, 409, { ok: false });
308
+ const answer = await d.engine.route("target", session);
309
+ if (answer.status !== 200 || answer.body?.target?.kind !== "C") return send(res, 409, { ok: false });
310
+ sent = await (d.background ?? backgroundInGhostty)(session, { enabled: d.enabled });
311
+ return send(res, sent ? 200 : 409, { ok: sent });
312
+ } finally {
313
+ if (sent) setTimeout(() => backgroundRequests.delete(session.sessionId), BACKGROUND_REQUEST_COOLDOWN).unref();
314
+ else backgroundRequests.delete(session.sessionId);
315
+ }
316
+ }
317
+
318
+ /** POST /api/terminal/launch `{ agent, cwd, key? }` → `{ ok: true, sessionId,
319
+ * name, ticket }`. The key makes asking again safe: one agent per key. */
320
+ export async function handleTerminalLaunch(req, res, options) {
321
+ return posted(req, res, options, "launch");
322
+ }
323
+
324
+ /** POST /api/terminal/folder `{ cwd }` → `{ ok: true, cwd }`, or `{ ok: false,
325
+ * code }` with why an agent could not start there (terminal-folder.mjs). The
326
+ * New session picker's question before a launch; answered here, by the deck,
327
+ * since it is about this machine's folders and not a terminal's. */
328
+ export async function handleTerminalFolder(req, res, options) {
329
+ const d = terminalDeps(options);
330
+ if (!d.enabled()) return notFound(res);
331
+ let raw;
332
+ try { raw = await readBody(req, res, BODY_LIMIT); } catch { return; } // answered 413 already
333
+ // Off while the body came in: the route is not there.
334
+ if (!d.enabled()) return notFound(res);
335
+ // As the engine's own routes: a deck with no engine to start an agent has
336
+ // no folder to check for one, and says so in the same words and bytes
337
+ // (pro-engine-routes-off.test.ts), before it reads the question.
338
+ if (!d.jsBackend && d.engine?.enabled !== true) {
339
+ const { status, body } = engineRefusal("not-installed");
340
+ return send(res, status, body);
341
+ }
342
+ let cwd = null;
343
+ try {
344
+ const body = JSON.parse(raw);
345
+ if (body && typeof body === "object" && typeof body.cwd === "string") cwd = body.cwd;
346
+ } catch {}
347
+ if (cwd === null) return send(res, 400, { ok: false, code: "bad-request" });
348
+ return send(res, 200, await (d.checkFolder ?? checkFolder)(cwd));
349
+ }
350
+
351
+ /** GET /api/terminal/engine → `{ ok: true, engine }`: the engine's install
352
+ * state on this machine (engine-install.mjs' status, never the network), or
353
+ * null for an engine handed in by a caller, which has no installer. */
354
+ export async function handleEngineStatus(req, res, options) {
355
+ const d = terminalDeps(options);
356
+ if (!d.enabled()) return notFound(res);
357
+ const installer = d.engine?.installer;
358
+ return send(res, 200, { ok: true, engine: installer ? await installer.status() : null });
359
+ }
360
+
361
+ const ENGINE_ACTIONS = new Set(["install", "install-file", "cancel", "remove"]);
362
+
363
+ /** POST /api/terminal/engine/<action> → `{ ok: true, id? }`, or 409 `{ ok:
364
+ * false, code }` naming why not (engine-install.mjs). `install-file` takes
365
+ * the package file as the body, up to the size a download may be. */
366
+ export async function handleEngineAction(req, res, action, options) {
367
+ const d = terminalDeps(options);
368
+ if (!d.enabled() || !ENGINE_ACTIONS.has(action)) return notFound(res);
369
+ let bytes = null;
370
+ try {
371
+ if (action === "install-file") bytes = await readBytes(req, res, ENGINE_TARBALL_MAX, { ok: false, code: "too-large" });
372
+ else await readBody(req, res, BODY_LIMIT);
373
+ } catch {
374
+ return; // answered 413 already
375
+ }
376
+ // Off while the body came in: the route is not there.
377
+ if (!d.enabled()) return notFound(res);
378
+ const installer = d.engine?.installer;
379
+ if (!installer) return send(res, 409, { ok: false, code: "unavailable" });
380
+ const out = action === "install" ? await installer.install()
381
+ : action === "install-file" ? await installer.installFile(bytes)
382
+ : action === "cancel" ? installer.cancel()
383
+ : await installer.remove();
384
+ return send(res, out.ok ? 200 : 409, out);
385
+ }
386
+
387
+ // ---------------------------------------------------------------------------
388
+
389
+ /** A POST route: the switch, then the body under its cap, then the answer. */
390
+ async function posted(req, res, options, method) {
391
+ const d = terminalDeps(options);
392
+ if (!d.enabled()) return notFound(res);
393
+ const body = await jsonBody(req, res);
394
+ return answer(d, req, res, method, body);
395
+ }
396
+
397
+ /** The routes that only ask: answered after the switch-off, they changed nothing. */
398
+ const READS = new Set(["status", "target", "hosts"]);
399
+ /** The routes that start an agent: the deck notes each before the engine is asked. */
400
+ const LAUNCHES = new Set(["launch", "adopt"]);
401
+
402
+ /** The answer index.mjs gives an /api path with no route, byte for byte. */
403
+ function notFound(res) {
404
+ return send(res, 404, { error: "not found" });
405
+ }
406
+
407
+ /** What the page is told of a launch or an adopt the engine ran, when the switch went off before it answered. */
408
+ export const STARTED_TURNED_OFF = "The session was started, but the Command Panel was turned off in Settings. Switch it on to open the session.";
409
+ /** And of an open or a claim that went through: what an open panel is told at the switch-off (prefs-routes.mjs). */
410
+ export const REACHED_TURNED_OFF = "The Command Panel was turned off in Settings. The session is still running.";
411
+ /** And of an end of an older host's sessions that went through. */
412
+ export const ENDED_TURNED_OFF = "The sessions were ended, but the Command Panel was turned off in Settings.";
413
+
414
+ /**
415
+ * A question asked while on, answered by the engine after the switch went off. Nothing is minted — the socket
416
+ * is refused while off — and the page is told what is now true: what a launch, an adopt, an open or a claim
417
+ * did is not undone, so the page hears that its session runs and the panel is off (409 `turned-off`, a state
418
+ * it shows and stops at); anything else, which changed nothing, is the 404 a request after the switch-off gets.
419
+ */
420
+ function answeredAfterOff(res, method, said) {
421
+ const body = said.body && typeof said.body === "object" ? said.body : {};
422
+ const done = !READS.has(method) && said.status >= 200 && said.status < 300
423
+ && body.ok === true && (method !== "claim" || body.claimed === true);
424
+ if (!done) return notFound(res);
425
+ const error = method === "launch" || method === "adopt" ? STARTED_TURNED_OFF
426
+ : method === "endHosts" ? ENDED_TURNED_OFF : REACHED_TURNED_OFF;
427
+ return send(res, 409, { ok: false, error, code: "turned-off" });
428
+ }
429
+
430
+ /** The body as a plain object, or null for anything else. A body over the cap
431
+ * has already been answered 413 by readBody, and nothing is sent after it. */
432
+ async function jsonBody(req, res) {
433
+ let raw;
434
+ try { raw = await readBody(req, res, BODY_LIMIT); } catch { return null; }
435
+ try {
436
+ const value = JSON.parse(raw);
437
+ return value && typeof value === "object" && !Array.isArray(value) ? value : null;
438
+ } catch {
439
+ return null;
440
+ }
441
+ }
442
+
443
+ /**
444
+ * The route answered by the engine (or by a test's JS backend in its place).
445
+ * `question` is the route's parsed question: the body, the query's three
446
+ * values, or null for status.
447
+ *
448
+ * The engine answers `{ status, body, handle?, log? }`: the status and body
449
+ * are sent as they are. Where the body's ticket is null and a `handle` stands
450
+ * beside it, the ticket is minted here, in the same store, 30 s and single
451
+ * use, bound to `{ handle, origin }` — the page's origin, as for any ticket —
452
+ * and the upgrade relays it to the engine. The `log` line goes to the deck's
453
+ * log, never to the page. A status it calls `fixable` runs the deck's own tmux
454
+ * download first (withOwnTmux). An engine that could not take the question answers
455
+ * its refusal in the same shape (routeThroughEngine); one that failed in a way
456
+ * that must not be asked again throws, which is `guard`'s 500.
457
+ */
458
+ async function answer(d, req, res, method, question) {
459
+ if (res.headersSent) return;
460
+ // The switch again, now that the question is whole: a POST's body is read after the route's first look, and
461
+ // the switch can go off while it arrives. Off by now, the route is not there, as for a request sent after
462
+ // the switch-off: nothing is asked of the engine, which would otherwise run a launch the switch had already
463
+ // closed and put off the engine's stop (command-panel-engine.mjs) with the switch off.
464
+ if (!d.enabled()) return notFound(res);
465
+ if (d.jsBackend) {
466
+ // The test's tmux has no session host: what an engine without one answers.
467
+ if (typeof d.jsBackend[method] !== "function") {
468
+ const { status, body } = engineRefusal("no-terminal");
469
+ return send(res, status, body);
470
+ }
471
+ return d.jsBackend[method](req, res, question, d);
472
+ }
473
+ // A launch or an adopt is noted before the engine is asked, so that one it ran and never answered (the
474
+ // deck stopped in between) leaves its session "unknown" rather than "external" (panel-provenance.mjs).
475
+ const engineOn = d.engine?.enabled === true;
476
+ const ref = engineOn && d.provenance && LAUNCHES.has(method) ? d.provenance.started(method, question) : null;
477
+ let said = engineOn ? await d.engine.route(method, question) : engineRefusal("not-installed");
478
+ if (said.log) console.error(`${PRODUCT}: terminal: ${said.log}`);
479
+ // What the engine did, it did whatever the switch now says: noted before the switch is asked again.
480
+ d.provenance?.answered(method, question, ref, said.status, said.body);
481
+ // And once more, now that the engine has answered: a question asked while on can be answered after the
482
+ // switch-off, since the engine is stopped only once it has answered (command-panel-engine.mjs).
483
+ if (!d.enabled()) return answeredAfterOff(res, method, said);
484
+ if (method === "status" && fixable(said)) {
485
+ said = await withOwnTmux(d, said);
486
+ // It may have asked the engine again on the way: the switch once more.
487
+ if (!d.enabled()) return answeredAfterOff(res, method, said);
488
+ }
489
+ let out = withProvenance(d.provenance, question, said.body);
490
+ if (said.handle) {
491
+ const origin = typeof req?.headers?.origin === "string" ? req.headers.origin.trim().toLowerCase() : "";
492
+ out = { ...out, ticket: d.tickets.mint({ handle: said.handle, ...(origin ? { origin } : {}) }) };
493
+ }
494
+ return send(res, said.status, out);
495
+ }
496
+
497
+ /** The tmux states the deck's own build answers: none at all, or one older than 3.2. */
498
+ const FETCHABLE = new Set(["missing", "too-old"]);
499
+
500
+ /** Whether the engine's answer is a status it calls `fixable`: no tmux here it
501
+ * can use, and one the deck could fetch. Asked of the body too, so an answer
502
+ * that says fixable beside a tmux that works fetches nothing. */
503
+ function fixable(said) {
504
+ const tmux = said?.body?.tmux;
505
+ return said?.fixable === true && said.status === 200 && said.body.ok === true
506
+ && !!tmux && typeof tmux === "object" && tmux.ok !== true && FETCHABLE.has(tmux.reason);
507
+ }
508
+
509
+ /** `said` with its body's `tmux` replaced by `tmux`. */
510
+ function withTmux(said, tmux) {
511
+ return { ...said, body: { ...said.body, tmux } };
512
+ }
513
+
514
+ /**
515
+ * A status the engine called `fixable`, answered as the deck answered it
516
+ * before the engine served the panel:
517
+ *
518
+ * - no download may start here (switched off, or no build for this
519
+ * machine): the engine's answer as it is, the install line included;
520
+ * - a download out: `reason: "installing"`, with `progress` once it has
521
+ * said, and the page asks again;
522
+ * - the build already in its folder: the engine may remember a miss from
523
+ * before it landed (this deck's, a moment ago, or another deck's), so it
524
+ * is told to forget it and asked once more. Still none, and the build is
525
+ * not fetched again — the same bytes would land in the same place, every
526
+ * time the page asks — but answered as the plain fact with `download:
527
+ * "not_used"`;
528
+ * - a download that failed lately (RETRY_AFTER_MS): the plain fact with
529
+ * `download: <why>`, so the panel offers the install line instead;
530
+ * - otherwise one starts, not awaited, and is answered `installing`: once
531
+ * its build lands the engine is told to look again (`terminal.forgetTmux`),
532
+ * and the page's next ask finds it.
533
+ *
534
+ * The deck never decides on its own that tmux is missing: only the engine's
535
+ * `fixable` starts any of this.
536
+ */
537
+ async function withOwnTmux(d, said) {
538
+ const own = d.ownTmux;
539
+ if (!own || own.blocked()) return said;
540
+ if (!own.out) {
541
+ if (own.landed()) {
542
+ await d.engine.forgetTmux?.();
543
+ const again = await d.engine.route("status", null);
544
+ if (again.log) console.error(`${PRODUCT}: terminal: ${again.log}`);
545
+ return fixable(again) ? withTmux(again, { ...again.body.tmux, download: "not_used" }) : again;
546
+ }
547
+ const failed = own.recentFailure();
548
+ if (failed) return withTmux(said, { ...said.body.tmux, download: failed.reason });
549
+ own.start(() => d.engine.forgetTmux?.());
550
+ }
551
+ const progress = own.progress();
552
+ return withTmux(said, { ok: false, reason: "installing", ...(progress ? { progress } : {}) });
553
+ }