agent-relay 11.2.0 → 11.3.0

package/dist/cli/lib/attach.js

@@ -276,6 +276,195 @@ export function pickInitialTerminalRows(localSize, snapshotRows) {
         return snapshotRows;
     return undefined;
 }
+/**
+ * Pick the status-line width. Same precedence as
+ * {@link pickInitialTerminalRows} — the LOCAL terminal wins, because the
+ * status line has to fit the pane the human is looking at, not the agent's
+ * PTY.
+ */
+export function pickInitialTerminalCols(localSize, snapshotCols) {
+    if (localSize)
+        return localSize.cols;
+    if (typeof snapshotCols === 'number' && snapshotCols > 0)
+        return snapshotCols;
+    return undefined;
+}
+/** Width assumed when the local terminal never reported one. */
+export const DEFAULT_STATUS_LINE_COLS = 80;
+/**
+ * Clamp a status-line label to the terminal width.
+ *
+ * The interactive verbs paint their status line at the bottom row inside an
+ * `ESC 7` / `ESC 8` (DECSC/DECRC) pair. That is only safe while the text
+ * *fits*: a label wider than the pane wraps past the last row, which scrolls
+ * the screen. Because the label is painted on the bottom row, every repaint
+ * then scrolls again — promoting the previous status line into the scrollback
+ * as content and eating one row of the agent's output each time. A narrow
+ * pane therefore turns a single status line into a growing stack of them with
+ * the agent's TUI shredded behind it. The `drive` label is 87 columns, so this
+ * fired on a standard 80-column terminal too; at 66 columns six repaints cost
+ * six rows of agent output.
+ *
+ * Truncation keeps the paint inside one row, so the wrap — and the scroll
+ * cascade it triggers — can never happen. Callers painting a terminal row can
+ * reserve the final column as well, avoiding the emulator's wrap-pending state.
+ * The tail is the part that carries the key hints, so an over-long label is
+ * trimmed from the *middle*: the verb and agent name stay readable and the
+ * `Ctrl+…` hints survive.
+ *
+ * Measured in display columns, not UTF-16 code units: an agent name carrying
+ * CJK or emoji is double-width, so a code-unit count would pass a label that
+ * still wraps — re-arming the exact cascade this prevents. Slicing is done on
+ * whole code points so a surrogate pair is never split in half.
+ */
+export function clampStatusLineText(text, cols, reserveFinalColumn = false) {
+    const terminalWidth = typeof cols === 'number' && cols > 0 ? Math.floor(cols) : DEFAULT_STATUS_LINE_COLS;
+    const width = reserveFinalColumn ? Math.max(terminalWidth - 1, 0) : terminalWidth;
+    if (displayWidth(text) <= width)
+        return text;
+    // Too narrow to say anything useful — a bare head is still better than a
+    // wrap, and `…` alone would be meaningless.
+    if (width <= 1)
+        return width === 1 ? takeColumns(text, 1).text : '';
+    const keep = width - 1; // the ellipsis occupies one column
+    const tailBudget = Math.floor(keep / 2);
+    const headBudget = keep - tailBudget;
+    const head = takeColumns(text, headBudget);
+    const tail = tailBudget > 0 ? takeColumns(text, tailBudget, 'end') : { text: '' };
+    return `${head.text}…${tail.text}`;
+}
+/**
+ * Column width of a string, counting East Asian Wide/Fullwidth characters and
+ * emoji as two columns and zero-width joiners/combining marks as none. This is
+ * the pragmatic subset a status line needs — it is not a full `wcwidth`.
+ */
+function displayWidth(text) {
+    let total = 0;
+    for (const char of text)
+        total += charWidth(char);
+    return total;
+}
+/** Codepoints that occupy no column: combining marks, ZWJ, variation selectors. */
+const ZERO_WIDTH_RANGES = [
+    [0x0300, 0x036f],
+    [0x200d, 0x200d],
+    [0xfe00, 0xfe0f],
+];
+/** East Asian Wide / Fullwidth blocks, plus the emoji planes. */
+const DOUBLE_WIDTH_RANGES = [
+    [0x1100, 0x115f],
+    [0x2e80, 0xa4cf],
+    [0xac00, 0xd7a3],
+    [0xf900, 0xfaff],
+    [0xfe30, 0xfe6f],
+    [0xff00, 0xff60],
+    [0xffe0, 0xffe6],
+    [0x1f300, 0x1faff],
+    [0x20000, 0x3fffd],
+];
+function inRanges(code, ranges) {
+    return ranges.some(([lo, hi]) => code >= lo && code <= hi);
+}
+function charWidth(char) {
+    const code = char.codePointAt(0) ?? 0;
+    if (inRanges(code, ZERO_WIDTH_RANGES))
+        return 0;
+    return inRanges(code, DOUBLE_WIDTH_RANGES) ? 2 : 1;
+}
+/**
+ * Take whole code points from `text` until `budget` columns are used, from the
+ * start or the `end`. Never splits a surrogate pair, and never overshoots the
+ * budget — a double-width character that would exceed it is dropped.
+ */
+function takeColumns(text, budget, from = 'start') {
+    const chars = Array.from(text);
+    const ordered = from === 'end' ? chars.slice().reverse() : chars;
+    const taken = [];
+    let used = 0;
+    for (const char of ordered) {
+        const w = charWidth(char);
+        if (used + w > budget)
+            break;
+        used += w;
+        taken.push(char);
+    }
+    return { text: (from === 'end' ? taken.reverse() : taken).join('') };
+}
+/**
+ * Reserve the local terminal's final row for an attach status line.
+ *
+ * Full-screen CLIs treat every PTY row as application-owned. If the remote PTY
+ * is resized to the local terminal's full height and Relay then paints a status
+ * line over its final row, both renderers continually overwrite each other.
+ * The result is the duplicated status text and torn TUI frames seen in drive
+ * and passthrough sessions. Give the child one fewer row and column: the row
+ * prevents cursor-addressed overlap, while the spare column prevents terminal
+ * autowrap from stepping past the child scroll margin into Relay's row.
+ */
+export function reserveStatusLineRow(localSize) {
+    if (!localSize)
+        return null;
+    if (localSize.rows < 3 || localSize.cols < 2)
+        return localSize;
+    return {
+        rows: localSize.rows - 1,
+        cols: localSize.cols - 1,
+    };
+}
+/** Whether a terminal is large enough to dedicate a non-wrapping status row. */
+export function canReserveStatusLine(localSize) {
+    return localSize !== null && localSize.rows >= 3 && localSize.cols >= 2;
+}
+/**
+ * Constrain local scrolling to the child PTY's rows while preserving the
+ * current cursor. DECSTBM otherwise defaults to the physical terminal height,
+ * which includes Relay's status row.
+ */
+export function renderChildScrollRegion(rows) {
+    // CSI s/u save only the cursor. DEC ESC 7/8 also preserve terminal state in
+    // common emulators and would therefore undo the newly installed margins.
+    return `\x1b[s\x1b[1;${Math.max(1, Math.floor(rows))}r\x1b[u`;
+}
+/**
+ * Keep a status label strictly inside one terminal row.
+ *
+ * Writing the final column with autowrap enabled advances to the next row and,
+ * on the terminal's bottom row, scrolls the entire TUI. Leave one cell unused
+ * and conservatively count non-ASCII code points as two cells so even unusual
+ * agent names cannot trigger a wrap.
+ */
+function conservativeTerminalCellWidth(character) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint >= 0x20 && codePoint <= 0x7e ? 1 : 2;
+}
+export function fitStatusLineText(text, columns) {
+    if (columns === undefined || !Number.isFinite(columns))
+        return text;
+    const available = Math.max(0, Math.floor(columns) - 1);
+    if (available === 0)
+        return '';
+    let width = 0;
+    let result = '';
+    let truncated = false;
+    for (const character of text) {
+        const characterWidth = conservativeTerminalCellWidth(character);
+        if (width + characterWidth > available) {
+            truncated = true;
+            break;
+        }
+        result += character;
+        width += characterWidth;
+    }
+    if (!truncated)
+        return result;
+    while (width + 1 > available && result.length > 0) {
+        const characters = Array.from(result);
+        const removed = characters.pop() ?? '';
+        width -= conservativeTerminalCellWidth(removed);
+        result = characters.join('');
+    }
+    return `${result}~`;
+}
 /**
  * Sync the agent's PTY to the driver's local terminal size. tmux /
  * screen / ssh all do this — without it a TUI in the agent renders into
@@ -285,20 +474,27 @@ export function pickInitialTerminalRows(localSize, snapshotRows) {
  */
 export async function syncInitialPtySize(connection, name, localSize, verb, deps, options) {
     if (!localSize)
-        return;
+        return false;
     try {
-        await createBrokerClient(connection, deps.fetch).resizePty(name, localSize.rows, localSize.cols, options);
+        const result = await createBrokerClient(connection, deps.fetch).resizePty(name, localSize.rows, localSize.cols, options);
+        if (result.applied === false) {
+            deps.log(`[${verb}] broker did not apply the reserved PTY size; using status repaint fallback`);
+            return false;
+        }
+        return true;
     }
     catch (err) {
         const failure = mapBrokerSdkFailure(err);
         deps.log(`[${verb}] could not sync agent PTY size to local terminal (${failure.message ?? 'unknown'}); continuing`);
+        return false;
     }
 }
 /**
  * Read the worker's prior inbound delivery mode and flip it to
  * `targetMode`. Returns the previous mode on success so the caller can
  * restore it on detach; returns `null` (and writes an error) when the
- * flip fails so the caller bails before touching the terminal.
+ * request fails or the broker reports that the requested transition did not
+ * complete, so the caller bails before touching the terminal.
  *
  * Non-404 errors are surfaced as `Error: could not ${actionPhrase}:
  * ${message}` so callers pass verb-appropriate wording (e.g. "switch to
@@ -316,6 +512,15 @@ export async function switchInboundDeliveryModeOrAbort(connection, name, targetM
     }
     try {
         const result = await createBrokerClient(connection, deps.fetch).setInboundDeliveryMode(name, targetMode);
+        // A manual_flush → auto_inject transition can fail partway through when
+        // draining a parked message into the harness fails. The broker deliberately
+        // keeps and reports manual_flush in that case even though the PUT itself
+        // succeeded. Starting an attach session as if the target mode landed would
+        // render false state and make its first guarded toggle a no-op.
+        if (result.mode !== targetMode) {
+            deps.error(`Error: could not ${actionPhrase}: broker remained in ${result.mode} mode while draining queued messages`);
+            return null;
+        }
         return { previousMode, sessionRevision: result.revision };
     }
     catch (err) {
@@ -419,6 +624,12 @@ export class AnsiBoundaryScanner {
             case 'ground':
                 if (c === 0x1b)
                     this.state = 'esc';
+                else if (c === 0x9b)
+                    this.state = 'csi';
+                else if (c === 0x9d)
+                    this.state = 'osc';
+                else if (c === 0x90 || c === 0x98 || c === 0x9e || c === 0x9f)
+                    this.state = 'str';
                 return;
             case 'esc':
                 if (c === 0x5b)
@@ -431,30 +642,260 @@ export class AnsiBoundaryScanner {
                     this.state = 'ground'; // 2-byte escape (ESC 7, ESC 8, ESC c, …)
                 return;
             case 'csi':
-                if (c === 0x1b)
+                if (c === 0x18 || c === 0x1a)
+                    this.state = 'ground'; // CAN / SUB cancel the sequence
+                else if (c === 0x1b)
                     this.state = 'esc'; // stray ESC restarts
                 else if (c >= 0x40 && c <= 0x7e)
                     this.state = 'ground'; // final byte ends the CSI
                 return;
             case 'osc':
-                if (c === 0x07)
+                if (c === 0x07 || c === 0x9c || c === 0x18 || c === 0x1a)
                     this.state = 'ground'; // BEL terminator
                 else if (c === 0x1b)
                     this.state = 'osc_esc'; // possible ST (ESC \)
                 return;
             case 'osc_esc':
-                this.state = c === 0x5c ? 'ground' : 'osc';
+                this.state =
+                    c === 0x5c || c === 0x9c || c === 0x18 || c === 0x1a ? 'ground' : c === 0x1b ? 'osc_esc' : 'osc';
                 return;
             case 'str':
-                if (c === 0x1b)
+                if (c === 0x9c || c === 0x18 || c === 0x1a)
+                    this.state = 'ground';
+                else if (c === 0x1b)
                     this.state = 'str_esc';
                 return;
             case 'str_esc':
-                this.state = c === 0x5c ? 'ground' : 'str';
+                this.state =
+                    c === 0x5c || c === 0x9c || c === 0x18 || c === 0x1a ? 'ground' : c === 0x1b ? 'str_esc' : 'str';
                 return;
         }
     }
 }
+/**
+ * Detect terminal controls that can erase or replace Relay's reserved status
+ * row even though the child PTY itself is one row shorter.
+ *
+ * Cursor-addressed TUI drawing stays inside the child grid, but erase-display,
+ * terminal reset, and alternate-screen switches act on the local terminal as a
+ * whole. Attach clients reinstall their child scroll region after those
+ * operations; the status controller separately repaints at a safe ANSI
+ * boundary. A short carry handles controls split across WS frames.
+ */
+export class StatusLineInvalidationScanner {
+    carry = '';
+    push(chunk) {
+        const input = this.carry + chunk;
+        const esc = String.fromCharCode(0x1b);
+        const privateModes = new RegExp(`${esc}\\[\\?([0-9;]+)[hl]`, 'g');
+        let invalidatesDisplay = false;
+        let privateMatch;
+        while ((privateMatch = privateModes.exec(input)) !== null) {
+            if (privateMatch[1].split(';').some((mode) => ['47', '1047', '1049'].includes(mode))) {
+                invalidatesDisplay = true;
+            }
+        }
+        // Retain only an incomplete candidate control. Keeping arbitrary completed
+        // output would rediscover the same erase on later chunks and recreate the
+        // repaint storm this scanner exists to prevent.
+        const lastEscape = input.lastIndexOf(esc);
+        const suffix = lastEscape >= 0 ? input.slice(lastEscape) : '';
+        const incompleteCsi = suffix.startsWith(`${esc}[`) && /^[?0-9;]*$/.test(suffix.slice(2));
+        this.carry = suffix === esc || incompleteCsi ? suffix : '';
+        return (
+        // ED 0/default clears from the cursor through the reserved final row;
+        // ED 2 clears the full display.
+        input.includes(`${esc}[J`) ||
+            input.includes(`${esc}[0J`) ||
+            input.includes(`${esc}[2J`) ||
+            // Alternate-screen changes replace the entire visible buffer.
+            invalidatesDisplay ||
+            // RIS resets the terminal and clears the active display.
+            input.includes(`${esc}c`));
+    }
+}
+/** Track the child application's active DECSTBM margins across streamed ANSI. */
+export class TerminalScrollRegionTracker {
+    parserState = 'ground';
+    csiParams = '';
+    csiSupported = true;
+    stringAllowsBel = false;
+    rows;
+    top = 1;
+    bottom;
+    originMode = false;
+    alternateActive = false;
+    primaryRegion;
+    alternateRegion;
+    constructor(rows) {
+        this.rows = Math.max(1, Math.floor(rows));
+        this.bottom = this.rows;
+        this.primaryRegion = { top: 1, bottom: this.rows };
+        this.alternateRegion = { top: 1, bottom: this.rows };
+    }
+    setRows(rows) {
+        this.rows = Math.max(1, Math.floor(rows));
+        this.top = 1;
+        this.bottom = this.rows;
+        this.primaryRegion = { top: 1, bottom: this.rows };
+        this.alternateRegion = { top: 1, bottom: this.rows };
+    }
+    push(chunk) {
+        for (const character of chunk)
+            this.consumeCharacter(character);
+    }
+    get region() {
+        return { top: this.top, bottom: this.bottom };
+    }
+    get isOriginMode() {
+        return this.originMode;
+    }
+    consumeCharacter(character) {
+        switch (this.parserState) {
+            case 'ground':
+                this.consumeGround(character);
+                break;
+            case 'escape':
+                this.consumeEscape(character);
+                break;
+            case 'csi':
+                this.consumeCsi(character);
+                break;
+            case 'string':
+                this.consumeString(character);
+                break;
+            case 'string_escape':
+                this.consumeStringEscape(character);
+                break;
+        }
+    }
+    consumeString(character) {
+        if (character === '\x1b') {
+            this.parserState = 'string_escape';
+            return;
+        }
+        if (character === '\x9c' ||
+            character === '\x18' ||
+            character === '\x1a' ||
+            (this.stringAllowsBel && character === '\x07')) {
+            this.parserState = 'ground';
+        }
+    }
+    consumeStringEscape(character) {
+        if (character === '\\' || character === '\x9c' || character === '\x18' || character === '\x1a') {
+            this.parserState = 'ground';
+        }
+        else {
+            this.parserState = character === '\x1b' ? 'string_escape' : 'string';
+        }
+    }
+    consumeGround(character) {
+        if (character === '\x1b')
+            this.parserState = 'escape';
+        else if (character === '\x9b')
+            this.beginCsi();
+        else if (['\x90', '\x98', '\x9d', '\x9e', '\x9f'].includes(character)) {
+            this.beginString(character === '\x9d');
+        }
+    }
+    consumeEscape(character) {
+        if (character === '[')
+            this.beginCsi();
+        else if (['P', 'X', ']', '^', '_'].includes(character))
+            this.beginString(character === ']');
+        else {
+            if (character === 'c')
+                this.resetTrackedState();
+            this.parserState = character === '\x1b' ? 'escape' : 'ground';
+        }
+    }
+    beginCsi() {
+        this.parserState = 'csi';
+        this.csiParams = '';
+        this.csiSupported = true;
+    }
+    beginString(allowsBel) {
+        this.parserState = 'string';
+        this.stringAllowsBel = allowsBel;
+    }
+    consumeCsi(character) {
+        if (character === '\x18' || character === '\x1a') {
+            this.parserState = 'ground';
+            return;
+        }
+        if (character === '\x1b') {
+            this.parserState = 'escape';
+            return;
+        }
+        const code = character.codePointAt(0) ?? 0;
+        if (code >= 0x30 && code <= 0x3f) {
+            this.csiParams += character;
+            return;
+        }
+        if (code >= 0x20 && code <= 0x2f) {
+            this.csiSupported = false;
+            return;
+        }
+        if (code >= 0x40 && code <= 0x7e) {
+            if (this.csiSupported)
+                this.applyCsi(this.csiParams, character);
+            this.parserState = 'ground';
+        }
+    }
+    applyCsi(params, final) {
+        if ((final === 'h' || final === 'l') && params.startsWith('?')) {
+            this.applyPrivateModes(params.slice(1).split(';'), final === 'h');
+            return;
+        }
+        if (final !== 'r' || params.startsWith('?'))
+            return;
+        const [topRaw = '', bottomRaw = ''] = params.split(';');
+        const parsedTop = topRaw === '' ? 0 : Number.parseInt(topRaw, 10);
+        const parsedBottom = bottomRaw === '' ? 0 : Number.parseInt(bottomRaw, 10);
+        const top = parsedTop === 0 ? 1 : parsedTop;
+        const bottom = parsedBottom === 0 ? this.rows : parsedBottom;
+        if (Number.isFinite(top) && Number.isFinite(bottom) && top >= 1 && bottom > top) {
+            const clampedTop = Math.min(top, this.rows);
+            const clampedBottom = Math.min(bottom, this.rows);
+            if (clampedBottom > clampedTop) {
+                this.top = clampedTop;
+                this.bottom = clampedBottom;
+            }
+        }
+    }
+    applyPrivateModes(modes, enabled) {
+        if (modes.includes('6'))
+            this.originMode = enabled;
+        if (modes.some((mode) => ['47', '1047', '1049'].includes(mode))) {
+            this.switchScreenBuffer(enabled, enabled);
+        }
+    }
+    resetTrackedState() {
+        this.top = 1;
+        this.bottom = this.rows;
+        this.originMode = false;
+        this.alternateActive = false;
+        this.primaryRegion = { top: 1, bottom: this.rows };
+        this.alternateRegion = { top: 1, bottom: this.rows };
+    }
+    switchScreenBuffer(enterAlternate, resetAlternate) {
+        if (enterAlternate === this.alternateActive)
+            return;
+        if (resetAlternate) {
+            this.alternateRegion = { top: 1, bottom: this.rows };
+        }
+        if (this.alternateActive) {
+            this.alternateRegion = { top: this.top, bottom: this.bottom };
+        }
+        else {
+            this.primaryRegion = { top: this.top, bottom: this.bottom };
+        }
+        this.alternateActive = enterAlternate;
+        const region = enterAlternate ? this.alternateRegion : this.primaryRegion;
+        this.top = region.top;
+        this.bottom = region.bottom;
+    }
+}
 /**
  * Coordinates status-line repaints for the interactive attach clients.
  *
@@ -462,8 +903,8 @@ export class AnsiBoundaryScanner {
  *  - **Non-TTY skip** — when `enabled` is false, nothing is ever written.
  *  - **Boundary-hold** — a repaint is deferred while the observed output ends
  *    mid ANSI escape sequence, so the status line never splices into a
- *    half-transmitted CSI. It paints as soon as the next chunk lands at a
- *    boundary (or after `boundaryHoldMs` as a bounded fallback).
+ *    half-transmitted CSI. It paints only after a later chunk returns the
+ *    stream to a real boundary.
  *  - **Coalescing** — repaints are rate-limited to at most one per
  *    `coalesceMs`, shrinking the window in which our save/restore-cursor wrap
  *    can clobber the agent's own pending DECSC.
@@ -478,25 +919,32 @@ export class StatusLineController {
     opts;
     scanner = new AnsiBoundaryScanner();
     timer = null;
-    timerForce = false;
     wantPaint = false;
     lastPaintAt = Number.NEGATIVE_INFINITY;
     disposed = false;
     constructor(opts) {
         this.opts = opts;
     }
+    isEnabled() {
+        return typeof this.opts.enabled === 'function' ? this.opts.enabled() : this.opts.enabled;
+    }
     /** Record server output for boundary tracking; flush a held repaint if the
      *  stream is now back at a sequence boundary. */
     observeOutput(chunk) {
         if (this.disposed)
             return;
         this.scanner.push(chunk);
+        if (!this.isEnabled()) {
+            this.wantPaint = false;
+            this.clearTimer();
+            return;
+        }
         if (this.wantPaint)
             this.flush();
     }
     /** Request a repaint (coalesced + boundary-held). */
     request() {
-        if (this.disposed || !this.opts.enabled)
+        if (this.disposed || !this.isEnabled())
             return;
         this.wantPaint = true;
         this.flush();
@@ -511,39 +959,32 @@ export class StatusLineController {
         return (this.opts.now ?? Date.now)();
     }
     flush() {
-        if (this.disposed || !this.wantPaint)
+        if (this.disposed || !this.wantPaint || !this.isEnabled())
             return;
         if (!this.scanner.atBoundary) {
-            this.arm(this.opts.boundaryHoldMs ?? 100, true);
             return;
         }
-        // Back at a boundary: any pending *force* (boundary-hold) timer carries the
-        // wrong deadline now — it was armed to paint mid-sequence after
-        // `boundaryHoldMs`, which would either paint later than the coalescing
-        // window needs or bypass the window entirely. Clear it so the normal
-        // coalescing logic below re-arms a plain timer for the correct remainder.
-        // A non-force (coalescing) timer already has the right deadline, so leave
-        // it in place.
-        if (this.timer && this.timerForce)
-            this.clearTimer();
         const elapsed = this.now() - this.lastPaintAt;
         if (elapsed >= this.opts.coalesceMs) {
             this.paintNow();
         }
         else {
-            this.arm(this.opts.coalesceMs - elapsed, false);
+            this.arm(this.opts.coalesceMs - elapsed);
         }
     }
     paintNow() {
         this.clearTimer();
+        if (!this.isEnabled()) {
+            this.wantPaint = false;
+            return;
+        }
         this.wantPaint = false;
         this.lastPaintAt = this.now();
         this.opts.write(this.opts.render());
     }
-    arm(ms, force) {
+    arm(ms) {
         if (this.timer)
             return;
-        this.timerForce = force;
         const set = this.opts.setTimer ??
             ((fn, delay) => {
                 const t = setTimeout(fn, delay);
@@ -552,12 +993,11 @@ export class StatusLineController {
             });
         this.timer = set(() => {
             this.timer = null;
-            if (this.disposed || !this.wantPaint)
+            if (this.disposed || !this.wantPaint || !this.isEnabled()) {
+                this.wantPaint = false;
                 return;
-            if (this.timerForce)
-                this.paintNow();
-            else
-                this.flush();
+            }
+            this.flush();
         }, ms);
     }
     clearTimer() {