@oh-my-pi/pi-tui 18.8.7 → 18.8.9

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 (78) hide show
  1. package/CHANGELOG.md +52 -86
  2. package/dist/types/charts/chart-plan.d.ts +11 -5
  3. package/dist/types/charts/chart-svg.d.ts +11 -7
  4. package/dist/types/charts/table-data.d.ts +6 -1
  5. package/dist/types/chat/execution-shared.d.ts +6 -5
  6. package/dist/types/keybinding-matchers.d.ts +3 -0
  7. package/dist/types/kitty-graphics.d.ts +2 -2
  8. package/dist/types/multiplexers/cmux.d.ts +16 -0
  9. package/dist/types/multiplexers/herdr.d.ts +26 -0
  10. package/dist/types/multiplexers/notify.d.ts +13 -0
  11. package/dist/types/multiplexers/orca.d.ts +12 -0
  12. package/dist/types/multiplexers/screen.d.ts +9 -0
  13. package/dist/types/multiplexers/tmux.d.ts +29 -0
  14. package/dist/types/multiplexers/types.d.ts +100 -0
  15. package/dist/types/multiplexers/wmux.d.ts +12 -0
  16. package/dist/types/multiplexers/zellij.d.ts +12 -0
  17. package/dist/types/overlays/annotation-overlay.d.ts +12 -0
  18. package/dist/types/overlays/annotation-types.d.ts +2 -0
  19. package/dist/types/overlays/hook-selector.d.ts +9 -4
  20. package/dist/types/overlays/model-browser.d.ts +2 -2
  21. package/dist/types/overlays/model-hub.d.ts +21 -4
  22. package/dist/types/overlays/session-observer-registry.d.ts +2 -0
  23. package/dist/types/overlays/usage-dashboard.d.ts +3 -1
  24. package/dist/types/status-line/types.d.ts +3 -3
  25. package/dist/types/terminal-capabilities.d.ts +24 -32
  26. package/dist/types/terminal-multiplexer.d.ts +127 -14
  27. package/dist/types/terminal.d.ts +5 -4
  28. package/dist/types/theme/symbols.d.ts +1 -1
  29. package/dist/types/tmux.d.ts +1 -4
  30. package/dist/types/tools/eval.d.ts +1 -1
  31. package/dist/types/tools/native-view.d.ts +47 -0
  32. package/dist/types/tools/renderer.d.ts +15 -2
  33. package/dist/types/tui.d.ts +20 -0
  34. package/dist/types/vim.d.ts +19 -5
  35. package/package.json +9 -9
  36. package/src/charts/chart-plan.ts +152 -12
  37. package/src/charts/chart-svg.ts +479 -126
  38. package/src/charts/table-data.ts +43 -8
  39. package/src/chat/execution-shared.ts +42 -25
  40. package/src/chat/svg-figure.ts +45 -8
  41. package/src/chat/tool-execution.ts +9 -2
  42. package/src/components/editor.ts +182 -5
  43. package/src/keybinding-matchers.ts +6 -2
  44. package/src/kitty-graphics.ts +4 -4
  45. package/src/multiplexers/cmux.ts +29 -0
  46. package/src/multiplexers/herdr.ts +64 -0
  47. package/src/multiplexers/notify.ts +24 -0
  48. package/src/multiplexers/orca.ts +16 -0
  49. package/src/multiplexers/screen.ts +15 -0
  50. package/src/multiplexers/tmux.ts +40 -0
  51. package/src/multiplexers/types.ts +110 -0
  52. package/src/multiplexers/wmux.ts +16 -0
  53. package/src/multiplexers/zellij.ts +24 -0
  54. package/src/overlays/agent-hub.ts +7 -3
  55. package/src/overlays/annotation-overlay.ts +87 -6
  56. package/src/overlays/annotation-types.ts +2 -0
  57. package/src/overlays/hook-selector.ts +12 -5
  58. package/src/overlays/model-browser.ts +3 -3
  59. package/src/overlays/model-hub.ts +107 -27
  60. package/src/overlays/session-observer-registry.ts +10 -2
  61. package/src/overlays/usage-dashboard.ts +70 -23
  62. package/src/prompt/composer.ts +1 -0
  63. package/src/status-line/component.ts +12 -8
  64. package/src/status-line/segments.ts +10 -11
  65. package/src/status-line/types.ts +3 -3
  66. package/src/terminal-capabilities.ts +65 -181
  67. package/src/terminal-multiplexer.ts +112 -33
  68. package/src/terminal.ts +34 -28
  69. package/src/theme/session-color.ts +1 -7
  70. package/src/theme/symbols.ts +5 -0
  71. package/src/theme/theme.ts +7 -4
  72. package/src/tmux.ts +4 -11
  73. package/src/tools/bash.ts +82 -31
  74. package/src/tools/eval.ts +149 -123
  75. package/src/tools/native-view.ts +102 -1
  76. package/src/tools/renderer.ts +15 -2
  77. package/src/tui.ts +86 -12
  78. package/src/vim.ts +333 -18
@@ -10,12 +10,17 @@ import {
10
10
  renderKittyPlaceholderLines,
11
11
  setKittyGraphics,
12
12
  } from "./kitty-graphics";
13
- import { isInsideHerdr, isInsideTerminalMultiplexer } from "./terminal-multiplexer";
14
- import { isInsideTmux, resolveTmuxClientTerminalName, wrapTmuxPassthrough, wrapTmuxPassthroughIfNeeded } from "./tmux";
13
+ import {
14
+ isInsideTerminalMultiplexer,
15
+ routeTerminalMultiplexerNotification,
16
+ terminalMultiplexerForTerm,
17
+ terminalMultiplexerSessions,
18
+ } from "./terminal-multiplexer";
19
+ import { resolveTmuxClientTerminalName, wrapTmuxPassthroughIfNeeded } from "./tmux";
15
20
  import type { HangulCompatibilityJamoWidth } from "./utils";
16
21
 
17
22
  export * from "./terminal-multiplexer";
18
- export { isInsideTmux, wrapTmuxPassthrough } from "./tmux";
23
+ export { wrapTmuxPassthrough } from "./tmux";
19
24
 
20
25
  export enum ImageProtocol {
21
26
  Kitty = "\x1b_G",
@@ -45,92 +50,6 @@ export type TerminalId =
45
50
  | "base"
46
51
  | "trueColor";
47
52
 
48
- const CMUX_NOTIFICATION_TITLE = "omp";
49
- const CMUX_SURFACE_ID_PATTERN = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu;
50
-
51
- /** Title and body for an out-of-band multiplexer notification (cmux, Herdr). */
52
- function notificationTitleAndBody(message: string | TerminalNotification): { title: string; body: string } {
53
- if (typeof message === "string") return { title: CMUX_NOTIFICATION_TITLE, body: message };
54
- return { title: message.title?.trim() || CMUX_NOTIFICATION_TITLE, body: message.body ?? "" };
55
- }
56
-
57
- /**
58
- * Route a notification through cmux when the process belongs to a concrete
59
- * surface. Workspace/socket state alone is not enough: only the injected
60
- * surface UUID identifies the pane that should receive the notification.
61
- * Returns whether cmux owns delivery so the caller can preserve every existing
62
- * terminal fallback unchanged when no valid surface is present.
63
- */
64
- function sendCmuxNotification(message: string | TerminalNotification, env: NodeJS.ProcessEnv = Bun.env): boolean {
65
- const surfaceId = env.CMUX_SURFACE_ID?.trim();
66
- if (!surfaceId || !CMUX_SURFACE_ID_PATTERN.test(surfaceId)) return false;
67
-
68
- const { title, body } = notificationTitleAndBody(message);
69
- try {
70
- const child = Bun.spawn({
71
- cmd: ["cmux", "notify", "--surface", surfaceId, "--title", title, "--body", body],
72
- stdin: "ignore",
73
- stdout: "ignore",
74
- stderr: "ignore",
75
- });
76
- child.unref();
77
- } catch {
78
- // A missing cmux binary leaves delivery to the existing terminal fallback.
79
- return false;
80
- }
81
- return true;
82
- }
83
-
84
- const HERDR_PANE_ID_PATTERN = /^[0-9A-Za-z:_-]{1,64}$/u;
85
- /**
86
- * `herdr notification show` takes the title as its first positional and reads
87
- * exactly these three values there as a help request; it has no `--`
88
- * terminator. Any other text, including one starting with `-`, is a title.
89
- */
90
- const HERDR_USAGE_TOKENS = new Set(["help", "--help", "-h"]);
91
-
92
- /**
93
- * Route a notification through Herdr when the process runs inside one of its
94
- * panes. Herdr multiplexes panes like tmux but swallows bare OSC 9 / OSC 99 and
95
- * has no DCS passthrough envelope, and its bell relay does not flag a
96
- * backgrounded tab — so without this branch a backgrounded pane gets no signal
97
- * at all that the agent finished or is waiting for input.
98
- *
99
- * `sound` maps the notification kind onto what Herdr offers: a question waiting
100
- * on the user and a turn that stopped with an error both need the human and
101
- * ring `request`, a settled turn rings `done`, anything else stays
102
- * silent. Returns whether Herdr owns delivery, so every existing terminal
103
- * fallback is preserved when the pane id is absent or the binary is missing.
104
- */
105
- function sendHerdrNotification(message: string | TerminalNotification, env: NodeJS.ProcessEnv = Bun.env): boolean {
106
- // Pane-only detection, like `isInsideHerdr`: an env-sanitizing launcher can
107
- // drop HERDR_ENV and keep the pane identity, and that pane can still be
108
- // backgrounded. The pane id itself is what the CLI needs, so it stays required.
109
- if (!isInsideHerdr(env)) return false;
110
- const paneId = env.HERDR_PANE_ID?.trim();
111
- if (!paneId || !HERDR_PANE_ID_PATTERN.test(paneId)) return false;
112
-
113
- const parsed = notificationTitleAndBody(message);
114
- const title = HERDR_USAGE_TOKENS.has(parsed.title) ? CMUX_NOTIFICATION_TITLE : parsed.title;
115
- const body = parsed.body;
116
- const kinds = typeof message === "string" ? [] : [message.type ?? []].flat();
117
- const sound =
118
- kinds.includes("ask") || kinds.includes("error") ? "request" : kinds.includes("completion") ? "done" : "none";
119
- try {
120
- const child = Bun.spawn({
121
- cmd: ["herdr", "notification", "show", title, "--body", body, "--sound", sound],
122
- stdin: "ignore",
123
- stdout: "ignore",
124
- stderr: "ignore",
125
- });
126
- child.unref();
127
- } catch {
128
- // A missing herdr binary leaves delivery to the existing terminal fallback.
129
- return false;
130
- }
131
- return true;
132
- }
133
-
134
53
  const IMAGE_MARKER_SCAN_LIMIT = 512;
135
54
  const SIXEL_MARKER_SCAN_LIMIT = 128;
136
55
  const KITTY_PLACEHOLDER_HIGH_SURROGATE = KITTY_PLACEHOLDER.charCodeAt(0);
@@ -236,33 +155,16 @@ export class TerminalInfo {
236
155
 
237
156
  sendNotification(message: string | TerminalNotification): void {
238
157
  if (isNotificationSuppressed() || isTerminalHeadless()) return;
239
- // Innermost surface first. A Herdr pane launched inside a cmux surface
240
- // inherits both `HERDR_PANE_ID` and the outer `CMUX_SURFACE_ID`; routing to
241
- // cmux there would flag the containing surface and leave the backgrounded
242
- // Herdr pane — the one actually waiting — without a sound or a marker.
243
- if (sendHerdrNotification(message)) return;
244
- if (sendCmuxNotification(message)) return;
245
158
  const formatted = this.formatNotification(message);
246
- // Under tmux, terminals whose notify protocol is OSC 9 / OSC 99 would
247
- // otherwise lose the notification entirely: tmux does not forward bare
248
- // OSC 9/99 to the outer terminal, and the bare sequence does not flag
249
- // tmux's own `monitor-bell` / `monitor-activity`. Wrap the OSC in tmux's
250
- // DCS passthrough envelope so users with `allow-passthrough on` still
251
- // get the desktop toast, then append a BEL so `monitor-bell` flags the
252
- // pane/window for everyone else — the only signal a backgrounded pane
253
- // has that the agent finished or is waiting for input. `Bell` protocol
254
- // already self-flags via tmux's bell monitoring, so leave it alone.
255
- if (this.notifyProtocol !== NotifyProtocol.Bell && isInsideTmux()) {
256
- writeTerminalSequence(`${wrapTmuxPassthrough(formatted)}\x07`);
257
- return;
258
- }
259
- // Zellij drops OSC 9/99 and has no DCS passthrough envelope, but raises its
260
- // `[!]` bell flag on a bare BEL — the same backgrounded-pane signal tmux
261
- // users get. So follow the (Zellij-swallowed) OSC with a plain BEL.
262
- if (this.notifyProtocol !== NotifyProtocol.Bell && isInsideZellij()) {
263
- writeTerminalSequence(`${formatted}\x07`);
264
- return;
265
- }
159
+ // Multiplexers that swallow or rewrite the terminal's notification get it
160
+ // first, innermost target first; the terminal sequence is the fallback.
161
+ const routed = routeTerminalMultiplexerNotification({
162
+ message,
163
+ env: Bun.env,
164
+ sequence: this.notifyProtocol === NotifyProtocol.Bell ? null : formatted,
165
+ write: writeTerminalSequence,
166
+ });
167
+ if (routed) return;
266
168
  writeTerminalSequence(formatted);
267
169
  // VTE-family terminals (Ptyxis, GNOME Terminal, Tilix, …) plus Alacritty
268
170
  // and bare xterm-on-Wayland have no in-band escape that surfaces an
@@ -276,15 +178,6 @@ export class TerminalInfo {
276
178
  }
277
179
  }
278
180
 
279
- /**
280
- * Whether the agent process is running inside a Zellij session. Read fresh on
281
- * each call (like {@link isInsideTmux}) so a session attached/detached mid-run
282
- * is observed and tests can toggle `Bun.env.ZELLIJ` per case.
283
- */
284
- export function isInsideZellij(env: NodeJS.ProcessEnv = Bun.env): boolean {
285
- return Boolean(env.ZELLIJ);
286
- }
287
-
288
181
  /**
289
182
  * Whether the agent process runs in an SSH session, so the terminal emulator
290
183
  * is remote and host-local input/keyboard modes cannot be assumed.
@@ -381,12 +274,12 @@ function advertisesSynchronizedOutput(termFeatures: string | undefined): boolean
381
274
  * 2. Positive `TERM_FEATURES` advertisement (`Sy`) — survives SSH/mux wrapping.
382
275
  * 3. Windows Terminal (1.24+) via `WT_SESSION`, on native win32 and the
383
276
  * WSL/SSH-fronted host alike.
384
- * 4. Herdr panes. Herdr is otherwise treated as a multiplexer so leaked
385
- * kitty/ghostty identities cannot enable placeholder graphics, but its
386
- * pane VTE is libghostty and already suppresses compositing while DEC 2026
387
- * is set. Leaving sync off lets CUP-diff paints and split write(2) chunks
388
- * composite as dirty-row patches — the live viewport tears, with the top
389
- * frozen while only the bottom refreshes.
277
+ * 4. A multiplexer session whose pane VTE honors DEC 2026 regardless of its
278
+ * DECRQM reply (Herdr's libghostty pane). Such a multiplexer still owns
279
+ * the grid, so leaked kitty/ghostty identities cannot enable placeholder
280
+ * graphics, but leaving sync off lets CUP-diff paints and split write(2)
281
+ * chunks composite as dirty-row patches — the live viewport tears, with
282
+ * the top frozen while only the bottom refreshes.
390
283
  * 5. Known direct terminals with confirmed support. SSH does *not* disable —
391
284
  * DEC 2026 passes through SSH when the outer terminal honors it.
392
285
  * 6. Everything else starts off, including risky multiplexers; the runtime
@@ -402,7 +295,7 @@ export function shouldEnableSynchronizedOutputByDefault(
402
295
 
403
296
  if (advertisesSynchronizedOutput(env.TERM_FEATURES)) return true;
404
297
  if (env.WT_SESSION && (!env.TERM_PROGRAM || env.TERM_PROGRAM.toLowerCase() === "windows_terminal")) return true;
405
- if (isInsideHerdr(env)) return true;
298
+ if (terminalMultiplexerSessions(env).some(multiplexer => multiplexer.honorsSynchronizedOutput)) return true;
406
299
 
407
300
  // Risky multiplexers start off even when an inner terminal id leaks through:
408
301
  // older tmux/screen synchronized-output handling is flaky and a mux may not
@@ -510,44 +403,31 @@ export function hyperlinksUserOverride(env: NodeJS.ProcessEnv = Bun.env): boolea
510
403
  return null;
511
404
  }
512
405
 
513
- /**
514
- * Parse tmux's self-reported version from `TERM_PROGRAM_VERSION`. tmux sets
515
- * `TERM_PROGRAM=tmux` and `TERM_PROGRAM_VERSION=<version>` automatically since
516
- * 3.2a; older releases (or any path that does not surface the version) yield
517
- * `null` and the caller treats tmux conservatively.
518
- */
519
- function parseTmuxVersionFromEnv(env: NodeJS.ProcessEnv): { major: number; minor: number } | null {
520
- if (env.TERM_PROGRAM?.toLowerCase() !== "tmux") return null;
521
- return parseMajorMinorVersion(env.TERM_PROGRAM_VERSION);
522
- }
523
-
524
406
  /**
525
407
  * Whether OSC 8 hyperlinks should be enabled by default.
526
408
  *
527
409
  * Policy (highest precedence first):
528
410
  * 1. Explicit user override (`PI_NO_HYPERLINKS=1` off, `PI_FORCE_HYPERLINKS=1`
529
411
  * on). Opt-out wins ties.
530
- * 2. Herdr pane with no nested screen/tmux: on. Herdr hides the outer
531
- * terminal (`TERM=xterm-256color`, no `TERM_PROGRAM`), but it renders
532
- * OSC 8 in its own grid and opens links itself on Ctrl+click, so the
533
- * outer terminal's support does not matter.
412
+ * 2. Every multiplexer session with a hyperlink policy renders OSC 8 itself
413
+ * (`render`, e.g. Herdr): on. Herdr hides the outer terminal
414
+ * (`TERM=xterm-256color`, no `TERM_PROGRAM`), so the outer terminal's
415
+ * support does not matter.
534
416
  * 3. Static terminal capability — terminals whose {@link TerminalInfo} marks
535
417
  * `hyperlinks: false` (e.g. `base`) stay off unless the user forced on.
536
- * 4. GNU screen's explicit session marker (`STY`) always off, even if tmux is
537
- * also present: a screen layer anywhere in the path cannot forward OSC 8.
538
- * 5. tmux session (`TMUX` set): enabled when tmux self-reports >= 3.4 via
539
- * `TERM_PROGRAM_VERSION` (tmux 3.4 stores OSC 8 as a cell attribute and
540
- * forwards it to outer terminals whose `terminal-features` include
541
- * `hyperlinks`). Older or unknown versions stay off; on outer terminals
542
- * without the feature configured, tmux silently drops the sequence —
543
- * identical to today. Checked before the screen-family TERM heuristic
544
- * because tmux's historical `default-terminal` is `screen-256color`, so
545
- * `TERM=screen*` inside a tmux session must NOT short-circuit to off.
546
- * 6. screen-family TERM without `TMUX` always off: screen never gained OSC 8
547
- * support.
548
- * 7. tmux-family TERM without `TMUX` env — unusual (e.g. inspection scripts);
549
- * no version available, so off.
550
- * 8. Otherwise honor the static terminal capability.
418
+ * 4. A session that never forwards OSC 8 (`drop`, e.g. GNU screen's `STY`)
419
+ * always off, even when a forwarding multiplexer is also present.
420
+ * 5. Forwarding sessions (`forward`, e.g. `TMUX`): enabled when every one
421
+ * self-reports at least its forwarding version via `TERM_PROGRAM` /
422
+ * `TERM_PROGRAM_VERSION` (tmux 3.4). Older or unknown versions stay off;
423
+ * on outer terminals without the feature configured, tmux silently drops
424
+ * the sequence. Checked before the TERM heuristic because tmux's
425
+ * historical `default-terminal` is `screen-256color`, so `TERM=screen*`
426
+ * inside a tmux session must NOT short-circuit to off.
427
+ * 6. TERM naming a multiplexer whose session markers were stripped: off,
428
+ * since no session proves the multiplexer forwards OSC 8 (screen never
429
+ * does; tmux has no version to check).
430
+ * 7. Otherwise honor the static terminal capability.
551
431
  */
552
432
  export function shouldEnableHyperlinksByDefault(
553
433
  env: NodeJS.ProcessEnv = Bun.env,
@@ -556,27 +436,27 @@ export function shouldEnableHyperlinksByDefault(
556
436
  const override = hyperlinksUserOverride(env);
557
437
  if (override !== null) return override;
558
438
 
559
- if (isInsideHerdr(env) && !env.STY && !env.TMUX) return true;
439
+ const policies = terminalMultiplexerSessions(env).flatMap(multiplexer =>
440
+ multiplexer.hyperlinks === undefined ? [] : [multiplexer.hyperlinks],
441
+ );
442
+ if (policies.length > 0 && policies.every(policy => policy === "render")) return true;
560
443
 
561
444
  if (!getTerminalInfo(terminalId).hyperlinks) return false;
562
445
 
563
- // STY is GNU screen's explicit session marker. It vetoes tmux enabling when
564
- // multiplexers are nested because screen cannot forward OSC 8 anywhere in the
565
- // path.
566
- if (env.STY) return false;
567
-
568
- // tmux check before TERM heuristics: TMUX is the authoritative current-session
569
- // signal and supersedes TERM, which may be `screen-256color` under tmux's
570
- // historical default-terminal setting.
571
- if (env.TMUX) {
572
- const version = parseTmuxVersionFromEnv(env);
573
- if (!version) return false;
574
- return version.major > 3 || (version.major === 3 && version.minor >= 4);
446
+ if (policies.includes("drop")) return false;
447
+
448
+ const forwarders = policies.flatMap(policy => (typeof policy === "object" ? [policy.forward] : []));
449
+ if (forwarders.length > 0) {
450
+ const termProgram = env.TERM_PROGRAM?.toLowerCase();
451
+ return forwarders.every(forward => {
452
+ if (termProgram !== forward.termProgram) return false;
453
+ const version = parseMajorMinorVersion(env.TERM_PROGRAM_VERSION);
454
+ if (!version) return false;
455
+ return version.major > forward.major || (version.major === forward.major && version.minor >= forward.minor);
456
+ });
575
457
  }
576
458
 
577
- const term = env.TERM?.toLowerCase() ?? "";
578
- if (term.startsWith("screen")) return false;
579
- if (term.startsWith("tmux")) return false;
459
+ if (terminalMultiplexerForTerm(env)) return false;
580
460
 
581
461
  return true;
582
462
  }
@@ -650,10 +530,14 @@ export function resolveImageProtocol(
650
530
  if (imageProtocol !== null && isPaseoEmbedder(env)) {
651
531
  return null;
652
532
  }
653
- // Herdr owns the pane grid but does not expose whether the attached client
654
- // enabled its experimental Kitty renderer. Outer-terminal identity variables
655
- // can leak into the pane, so only the explicit protocol override is safe.
656
- if (imageProtocol !== null && isInsideHerdr(env)) {
533
+ // Some multiplexers own the pane grid without exposing whether the attached
534
+ // client renders graphics (Herdr's experimental Kitty renderer). Outer-
535
+ // terminal identity variables can leak into the pane, so only the explicit
536
+ // protocol override is safe.
537
+ if (
538
+ imageProtocol !== null &&
539
+ terminalMultiplexerSessions(env).some(multiplexer => multiplexer.imagesRequireOverride)
540
+ ) {
657
541
  return null;
658
542
  }
659
543
  return imageProtocol;
@@ -1,45 +1,124 @@
1
- /** True when this process is running inside a Herdr pane. */
2
- export function isInsideHerdr(env: NodeJS.ProcessEnv = Bun.env): boolean {
3
- // HERDR_ENV=1 is canonical. Identity vars survive env-sanitizing launchers
4
- // that drop HERDR_ENV. Do not use HERDR_SOCKET_PATH, HERDR_BIN_PATH,
5
- // HERDR_SESSION, HERDR_CONFIG_PATH, or HERDR_CLIENT_SOCKET_PATH here: they
6
- // are client-side and can be set outside a Herdr pane, matching the
7
- // CMUX_SOCKET_PATH warning below.
8
- if (env.HERDR_ENV === "1") return true;
9
- if (env.HERDR_PANE_ID || env.HERDR_TAB_ID || env.HERDR_WORKSPACE_ID) return true;
10
- return false;
1
+ import { cmuxMultiplexer } from "./multiplexers/cmux";
2
+ import { herdrMultiplexer } from "./multiplexers/herdr";
3
+ import { orcaMultiplexer } from "./multiplexers/orca";
4
+ import { screenMultiplexer } from "./multiplexers/screen";
5
+ import { tmuxMultiplexer } from "./multiplexers/tmux";
6
+ import type { TerminalMultiplexerModule, TerminalMultiplexerNotificationRequest } from "./multiplexers/types";
7
+ import { wmuxMultiplexer } from "./multiplexers/wmux";
8
+ import { zellijMultiplexer } from "./multiplexers/zellij";
9
+
10
+ /**
11
+ * Every multiplexer omp recognizes, in classification order within each
12
+ * precedence tier. Adding a multiplexer means adding its module here.
13
+ */
14
+ const registry = [
15
+ herdrMultiplexer,
16
+ tmuxMultiplexer,
17
+ screenMultiplexer,
18
+ zellijMultiplexer,
19
+ cmuxMultiplexer,
20
+ wmuxMultiplexer,
21
+ orcaMultiplexer,
22
+ ] as const satisfies readonly TerminalMultiplexerModule[];
23
+
24
+ /** Terminal multiplexers omp recognizes. */
25
+ export type TerminalMultiplexer = (typeof registry)[number]["id"];
26
+
27
+ const TERMINAL_MULTIPLEXERS: readonly TerminalMultiplexerModule<TerminalMultiplexer>[] = registry;
28
+ const MULTIPLEXERS_BY_ID = Object.fromEntries(
29
+ TERMINAL_MULTIPLEXERS.map(multiplexer => [multiplexer.id, multiplexer]),
30
+ ) as Record<TerminalMultiplexer, TerminalMultiplexerModule<TerminalMultiplexer>>;
31
+ const SESSION_TIER = TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.precedence === "session");
32
+ const OUTER_APP_TIER = TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.precedence === "outerApp");
33
+ const NOTIFICATION_TIER_ORDER = ["pane", "surface", "inBand"] as const;
34
+ // Innermost target first: a pane inside a surface must receive its own signal
35
+ // before the containing surface, followed by in-band rewrites. Registry order
36
+ // breaks ties within a tier (sort is stable).
37
+ const NOTIFIERS = TERMINAL_MULTIPLEXERS.flatMap(multiplexer =>
38
+ multiplexer.notifier ? [{ multiplexer, notifier: multiplexer.notifier }] : [],
39
+ ).sort((a, b) => NOTIFICATION_TIER_ORDER.indexOf(a.notifier.tier) - NOTIFICATION_TIER_ORDER.indexOf(b.notifier.tier));
40
+
41
+ /** Every environment variable multiplexer classification reads, including the TERM fallback. */
42
+ export const TERMINAL_MULTIPLEXER_ENV_KEYS: readonly string[] = [
43
+ ...TERMINAL_MULTIPLEXERS.flatMap(multiplexer => multiplexer.sessionEnvKeys),
44
+ "TERM",
45
+ ];
46
+
47
+ /**
48
+ * Whether an explicit session marker identifies the current provider.
49
+ *
50
+ * TERM is intentionally excluded: it is a classification fallback, not proof
51
+ * that a particular multiplexer session owns the current grid.
52
+ */
53
+ export function hasTerminalMultiplexerSession(
54
+ multiplexer: TerminalMultiplexer,
55
+ env: NodeJS.ProcessEnv = Bun.env,
56
+ ): boolean {
57
+ return MULTIPLEXERS_BY_ID[multiplexer].isInside(env);
11
58
  }
12
59
 
13
- /** Terminal multiplexers omp recognizes as owning the screen grid. */
14
- export type TerminalMultiplexer = "herdr" | "tmux" | "screen" | "zellij" | "cmux" | "wmux";
60
+ /**
61
+ * Every multiplexer whose explicit session markers are present, in registry
62
+ * order. Nested sessions all appear; TERM is not consulted.
63
+ */
64
+ export function terminalMultiplexerSessions(
65
+ env: NodeJS.ProcessEnv = Bun.env,
66
+ ): TerminalMultiplexerModule<TerminalMultiplexer>[] {
67
+ return TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.isInside(env));
68
+ }
15
69
 
16
70
  /**
17
- * Classify which terminal multiplexer owns the current screen grid, or `null`
18
- * for a direct terminal. Single source of truth for both the render-path gate
71
+ * The multiplexer TERM names, whether or not its session markers survived.
72
+ * This is classification's TERM fallback; session markers are not consulted.
73
+ */
74
+ export function terminalMultiplexerForTerm(
75
+ env: NodeJS.ProcessEnv = Bun.env,
76
+ ): TerminalMultiplexerModule<TerminalMultiplexer> | undefined {
77
+ const term = env.TERM?.toLowerCase() ?? "";
78
+ return TERMINAL_MULTIPLEXERS.find(
79
+ multiplexer => multiplexer.termPrefix !== undefined && term.startsWith(multiplexer.termPrefix),
80
+ );
81
+ }
82
+
83
+ /**
84
+ * Registry entry for the multiplexer hosting the current process, or
85
+ * `undefined` for a direct terminal. Same precedence as
86
+ * {@link classifyTerminalMultiplexer}.
87
+ */
88
+ export function classifyTerminalMultiplexerModule(
89
+ env: NodeJS.ProcessEnv = Bun.env,
90
+ ): TerminalMultiplexerModule<TerminalMultiplexer> | undefined {
91
+ return (
92
+ SESSION_TIER.find(multiplexer => multiplexer.isInside(env)) ??
93
+ terminalMultiplexerForTerm(env) ??
94
+ OUTER_APP_TIER.find(multiplexer => multiplexer.isInside(env))
95
+ );
96
+ }
97
+
98
+ /**
99
+ * Classify which terminal multiplexer hosts the current process, or `null` for
100
+ * a direct terminal. Single source of truth for both the render-path gate
19
101
  * (`isInsideTerminalMultiplexer`) and the debug snapshot label.
20
102
  *
21
- * TMUX/STY/ZELLIJ, Herdr, and the CMUX/WMUX workspace/surface/remote-transport
22
- * markers are authoritative session signals. TERM can also survive when those
23
- * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh). Do not
24
- * use CMUX_SOCKET_PATH / WMUX_CLI / WMUX_PIPE here: they are CLI socket/path
25
- * overrides and can be set outside a CMUX/WMUX terminal. wmux is a Windows
26
- * multiplexer (Electron + xterm.js) modeled on cmux/herdr that repaints its
27
- * pane in place and exports WMUX=1 plus a native WMUX_SURFACE_ID.
103
+ * Session markers are authoritative. TERM can also survive when those markers
104
+ * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh), so a
105
+ * `tmux`/`screen` TERM prefix comes next. Outer applications such as Orca rank
106
+ * last so a multiplexer running inside them wins.
28
107
  */
29
108
  export function classifyTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): TerminalMultiplexer | null {
30
- if (isInsideHerdr(env)) return "herdr";
31
- if (env.TMUX) return "tmux";
32
- if (env.STY) return "screen";
33
- if (env.ZELLIJ) return "zellij";
34
- if (env.CMUX_WORKSPACE_ID || env.CMUX_SURFACE_ID || env.CMUX_REMOTE_TRANSPORT) return "cmux";
35
- if (env.WMUX === "1" || env.WMUX_SURFACE_ID) return "wmux";
36
- const term = env.TERM?.toLowerCase() ?? "";
37
- if (term.startsWith("tmux")) return "tmux";
38
- if (term.startsWith("screen")) return "screen";
39
- return null;
109
+ return classifyTerminalMultiplexerModule(env)?.id ?? null;
40
110
  }
41
111
 
42
- /** True when a terminal multiplexer owns the current screen grid. */
112
+ /** True when the classified multiplexer owns the current screen grid. */
43
113
  export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
44
- return classifyTerminalMultiplexer(env) !== null;
114
+ return classifyTerminalMultiplexerModule(env)?.ownsScreenGrid ?? false;
115
+ }
116
+
117
+ /**
118
+ * Offer a notification to every active session's notifier, innermost tier
119
+ * first. Returns whether one delivered it; otherwise the terminal fallback
120
+ * applies unchanged.
121
+ */
122
+ export function routeTerminalMultiplexerNotification(request: TerminalMultiplexerNotificationRequest): boolean {
123
+ return NOTIFIERS.some(({ multiplexer, notifier }) => multiplexer.isInside(request.env) && notifier.send(request));
45
124
  }
package/src/terminal.ts CHANGED
@@ -27,7 +27,8 @@ import {
27
27
  setTerminalGlyphProtocol,
28
28
  TERMINAL,
29
29
  } from "./terminal-capabilities";
30
- import { isInsideTmux, wrapTmuxPassthrough } from "./tmux";
30
+ import type { TerminalMultiplexerBackgroundColorCache } from "./multiplexers/types";
31
+ import { terminalMultiplexerSessions } from "./terminal-multiplexer";
31
32
  import { setHangulCompatibilityJamoWidth } from "./utils";
32
33
  import { translateWindowsAltGrSequence } from "./windows-altgr";
33
34
  import { Win32InputModeDecoder, Win32PasteMarkerNormalizer } from "./windows-input-mode";
@@ -726,8 +727,6 @@ function parseOsc99KeyValues(section: string): Map<string, string> {
726
727
  const PROBE_GUARD_BEGIN = "\x1b7\x1b[?7l\x1b[8m";
727
728
  const PROBE_GUARD_END = "\x1b[28m\x1b[?7h\x1b8";
728
729
  const XTERM_SCROLL_TO_BOTTOM_MODES = [1010, 1011] as const;
729
- type Osc11QueryRoute = "direct" | "tmux";
730
- const TMUX_OSC11_CACHE_REFRESH_DELAY_MS = 100;
731
730
 
732
731
  function isXtermScrollToBottomMode(mode: number): boolean {
733
732
  return mode === 1010 || mode === 1011;
@@ -848,10 +847,10 @@ export class ProcessTerminal implements Terminal {
848
847
  #appearance: TerminalAppearance | undefined;
849
848
  #osc11Pending = false;
850
849
  #osc11ActiveToken?: TerminalAppearanceRequestToken;
851
- #osc11QueuedQuery?: { route: Osc11QueryRoute; token?: TerminalAppearanceRequestToken };
850
+ #osc11QueuedQuery?: { cache?: TerminalMultiplexerBackgroundColorCache; token?: TerminalAppearanceRequestToken };
852
851
  #nextAppearanceRequestToken = 1;
853
852
  #osc11ResponseBuffer = "";
854
- #osc11TmuxRefreshTimer?: Timer;
853
+ #osc11CacheRefreshTimer?: Timer;
855
854
  #osc99PendingId: string | undefined;
856
855
  #osc99ResponseBuffer = "";
857
856
  #osc99Capabilities = new Map<string, string>();
@@ -949,10 +948,11 @@ export class ProcessTerminal implements Terminal {
949
948
 
950
949
  /**
951
950
  * Re-query the terminal background through the startup DA1-sentinel FIFO,
952
- * pending/queued gating, parsing, dedup, and appearance callbacks. Inside
953
- * tmux, only this explicit path first passes an OSC 11 query to the outer
954
- * terminal, waits briefly for tmux to consume the response into its cache,
955
- * then reads that cache with a direct query. The outer query deliberately has
951
+ * pending/queued gating, parsing, dedup, and appearance callbacks. Inside a
952
+ * multiplexer that answers OSC 11 from a cache (tmux), only this explicit
953
+ * path first passes an OSC 11 query to the outer terminal, waits briefly for
954
+ * the multiplexer to consume the response into its cache, then reads that
955
+ * cache with a direct query. The outer query deliberately has
956
956
  * no DA1 sentinel: multiplexers can decode a fragmented DA1 response as a key
957
957
  * sequence and leak the remaining bytes into the editor. Startup and Mode 2031
958
958
  * probes remain direct. Suppressed while inactive, headless, or after teardown.
@@ -963,7 +963,10 @@ export class ProcessTerminal implements Terminal {
963
963
  if (token >= this.#nextAppearanceRequestToken) {
964
964
  this.#nextAppearanceRequestToken = token + 1;
965
965
  }
966
- this.#queryBackgroundColor(isInsideTmux() ? "tmux" : "direct", token);
966
+ const cache = terminalMultiplexerSessions().find(
967
+ multiplexer => multiplexer.backgroundColorCache,
968
+ )?.backgroundColorCache;
969
+ this.#queryBackgroundColor(cache, token);
967
970
  return token;
968
971
  }
969
972
 
@@ -1427,7 +1430,7 @@ export class ProcessTerminal implements Terminal {
1427
1430
  ) {
1428
1431
  const query = this.#osc11QueuedQuery;
1429
1432
  this.#osc11QueuedQuery = undefined;
1430
- this.#startOsc11Query(query.route, query.token);
1433
+ this.#startOsc11Query(query.cache, query.token);
1431
1434
  }
1432
1435
  break;
1433
1436
  }
@@ -1645,36 +1648,39 @@ export class ProcessTerminal implements Terminal {
1645
1648
  * DA1 avoids indefinite hangs: if DA1 response arrives before OSC 11,
1646
1649
  * the terminal does not support OSC 11.
1647
1650
  */
1648
- #queryBackgroundColor(route: Osc11QueryRoute = "direct", token?: TerminalAppearanceRequestToken): void {
1651
+ #queryBackgroundColor(
1652
+ cache?: TerminalMultiplexerBackgroundColorCache,
1653
+ token?: TerminalAppearanceRequestToken,
1654
+ ): void {
1649
1655
  if (this.#dead) return;
1650
1656
  // Queue if an OSC 11 query is in flight or its DA1 sentinel hasn't been
1651
1657
  // consumed yet. Starting a new query while a DA1 is outstanding would
1652
1658
  // increment the sentinel counter, and the old DA1 arrival would then
1653
1659
  // prematurely clear the new query's pending state. Preserve a requested
1654
- // tmux passthrough route when coalescing direct and explicit queries, and
1655
- // retain the latest explicit request identity across automatic queries.
1660
+ // cache refresh when coalescing direct and explicit queries, and retain
1661
+ // the latest explicit request identity across automatic queries.
1656
1662
  if (this.#osc11Pending || this.#da1SentinelOwners.some(o => o.kind === "osc11")) {
1657
1663
  const queued = this.#osc11QueuedQuery;
1658
- this.#osc11QueuedQuery = {
1659
- route: queued?.route === "tmux" || route === "tmux" ? "tmux" : "direct",
1660
- token: token ?? queued?.token,
1661
- };
1664
+ this.#osc11QueuedQuery = { cache: queued?.cache ?? cache, token: token ?? queued?.token };
1662
1665
  return;
1663
1666
  }
1664
- this.#startOsc11Query(route, token);
1667
+ this.#startOsc11Query(cache, token);
1665
1668
  }
1666
1669
 
1667
- #startOsc11Query(route: Osc11QueryRoute, token?: TerminalAppearanceRequestToken): void {
1670
+ #startOsc11Query(
1671
+ cache: TerminalMultiplexerBackgroundColorCache | undefined,
1672
+ token?: TerminalAppearanceRequestToken,
1673
+ ): void {
1668
1674
  this.#osc11Pending = true;
1669
1675
  this.#osc11ActiveToken = token;
1670
1676
  this.#osc11ResponseBuffer = "";
1671
- if (route === "tmux") {
1672
- this.#safeWrite(wrapTmuxPassthrough("\x1b]11;?\x07"));
1673
- this.#osc11TmuxRefreshTimer = setTimeout(() => {
1674
- this.#osc11TmuxRefreshTimer = undefined;
1677
+ if (cache) {
1678
+ this.#safeWrite(cache.passthrough("\x1b]11;?\x07"));
1679
+ this.#osc11CacheRefreshTimer = setTimeout(() => {
1680
+ this.#osc11CacheRefreshTimer = undefined;
1675
1681
  if (this.#dead || !this.#osc11Pending) return;
1676
1682
  this.#startDirectOsc11Query();
1677
- }, TMUX_OSC11_CACHE_REFRESH_DELAY_MS);
1683
+ }, cache.settleMs);
1678
1684
  return;
1679
1685
  }
1680
1686
  this.#startDirectOsc11Query();
@@ -2198,9 +2204,9 @@ export class ProcessTerminal implements Terminal {
2198
2204
  clearTimeout(this.#mode2031DebounceTimer);
2199
2205
  this.#mode2031DebounceTimer = undefined;
2200
2206
  }
2201
- if (this.#osc11TmuxRefreshTimer) {
2202
- clearTimeout(this.#osc11TmuxRefreshTimer);
2203
- this.#osc11TmuxRefreshTimer = undefined;
2207
+ if (this.#osc11CacheRefreshTimer) {
2208
+ clearTimeout(this.#osc11CacheRefreshTimer);
2209
+ this.#osc11CacheRefreshTimer = undefined;
2204
2210
  }
2205
2211
  this.#appearanceCallbacks = [];
2206
2212
  this.#appearanceReportCallbacks = [];
@@ -1,5 +1,5 @@
1
1
  import { TERMINAL } from "../terminal-capabilities";
2
- import { hexToOklch, oklchCusp, oklchToHex, relativeLuminance } from "@oh-my-pi/pi-utils";
2
+ import { hexToOklch, hueDistance, oklchCusp, oklchToHex, relativeLuminance } from "@oh-my-pi/pi-utils";
3
3
 
4
4
  /**
5
5
  * Derive a stable 32-bit hash from a string using djb2.
@@ -49,12 +49,6 @@ const MIN_HUE_DISTANCE = 10;
49
49
  /** OKLCH chroma threshold below which hue is meaningless (near-gray). */
50
50
  const MIN_CHROMA_FOR_HUE = 0.03;
51
51
 
52
- /** Angular distance between two hue values (0-360). */
53
- function hueDistance(a: number, b: number): number {
54
- const d = Math.abs(a - b);
55
- return Math.min(d, 360 - d);
56
- }
57
-
58
52
  /**
59
53
  * Parse OKLCH hue (0-360) from a hex color string.
60
54
  * Returns undefined for near-gray colors where hue is not meaningful.