@0xmaxma/claude-gateway 1.3.4 → 1.3.6

package/dist/shell/emitter.d.ts

@@ -1,4 +1,5 @@
 import type { AssistantRecord, UsageInfo } from './tailer';
+import type { MenuOption } from './screen';
 /**
  * Synthesizes the stream-json events the gateway's SessionProcess stdout
  * parser consumes (src/session/process.ts). Every assistant event is emitted
@@ -25,6 +26,18 @@ export declare class ProtocolEmitter {
      * Returns the text contained in the record, '' if none.
      */
     emitAssistant(record: AssistantRecord, sessionId: string): string;
+    /**
+     * Signal that the TUI is blocked on an interactive select menu. The gateway
+     * (runner.ts) renders this as channel-native UI — inline buttons on
+     * Telegram/Discord — while the turn's result text carries the same numbered
+     * list as a fallback (and for API, which has no buttons). callback_data /
+     * custom_id only ever carry the 1-based choice index.
+     */
+    emitMenuPrompt(opts: {
+        sessionId: string;
+        prompt: string;
+        options: MenuOption[];
+    }): void;
     emitResult(opts: {
         sessionId: string;
         isError: boolean;

package/dist/shell/emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/shell/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE3D;;;;;;GAMG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,MAAM,CAAC,cAA+B;IAExE,OAAO,CAAC,SAAS;IAIjB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAW7D;;;;;OAKG;IACH,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAiB/D;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAmBjE,UAAU,CAAC,IAAI,EAAE;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;KACzB,GAAG,IAAI;CAaT"}
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/shell/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,MAAM,CAAC,cAA+B;IAExE,OAAO,CAAC,SAAS;IAIjB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAW7D;;;;;OAKG;IACH,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAiB/D;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAmBjE;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,EAAE,CAAA;KAAE,GAAG,IAAI;IAUxF,UAAU,CAAC,IAAI,EAAE;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;KACzB,GAAG,IAAI;CAaT"}

package/dist/shell/emitter.js

@@ -68,6 +68,22 @@ class ProtocolEmitter {
             .map((b) => String(b.text ?? ''))
             .join('');
     }
+    /**
+     * Signal that the TUI is blocked on an interactive select menu. The gateway
+     * (runner.ts) renders this as channel-native UI — inline buttons on
+     * Telegram/Discord — while the turn's result text carries the same numbered
+     * list as a fallback (and for API, which has no buttons). callback_data /
+     * custom_id only ever carry the 1-based choice index.
+     */
+    emitMenuPrompt(opts) {
+        this.writeLine({
+            type: 'system',
+            subtype: 'menu_prompt',
+            session_id: opts.sessionId,
+            prompt: opts.prompt,
+            options: opts.options,
+        });
+    }
     emitResult(opts) {
         this.writeLine({
             type: 'result',

package/dist/shell/emitter.js.map

@@ -1 +1 @@
-{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/shell/emitter.ts"],"names":[],"mappings":";;;AAEA;;;;;;GAMG;AACH,MAAa,eAAe;IAC1B,YAA6B,MAA6B,OAAO,CAAC,MAAM;QAA3C,QAAG,GAAH,GAAG,CAAwC;IAAG,CAAC;IAEpE,SAAS,CAAC,GAA4B;QAC5C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,QAAQ,CAAC,SAAiB,EAAE,KAAa,EAAE,GAAW;QACpD,IAAI,CAAC,SAAS,CAAC;YACb,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,MAAM;YACf,UAAU,EAAE,SAAS;YACrB,KAAK;YACL,GAAG;YACH,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,KAAgB,EAAE,SAAiB;QACtD,IAAI,CAAC,SAAS,CAAC;YACb,IAAI,EAAE,cAAc;YACpB,UAAU,EAAE,SAAS;YACrB,KAAK,EAAE;gBACL,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE;oBACP,KAAK,EAAE;wBACL,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,CAAC;wBACrC,uBAAuB,EAAE,KAAK,CAAC,uBAAuB,IAAI,CAAC;wBAC3D,2BAA2B,EAAE,KAAK,CAAC,2BAA2B,IAAI,CAAC;qBACpE;iBACF;aACF;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,MAAuB,EAAE,SAAiB;QACtD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAC1C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAClD,CAAC;QACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEnC,IAAI,CAAC,SAAS,CAAC;YACb,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,SAAS;YACrB,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,WAAW,IAAI,UAAU;YACrD,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE;SAChD,CAAC,CAAC;QAEH,OAAO,MAAM;aACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;aAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAE,CAAwB,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;aACxD,IAAI,CAAC,EAAE,CAAC,CAAC;IACd,CAAC;IAED,UAAU,CAAC,IAMV;QACC,IAAI,CAAC,SAAS,CAAC;YACb,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;YAC5D,QAAQ,EAAE,IAAI,CAAC,OAAO;YACtB,MAAM,EAAE,IAAI,CAAC,IAAI;YACjB,WAAW,EAAE,IAAI,CAAC,UAAU;YAC5B,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,IAAI,CAAC,SAAS;YAC1B,KAAK,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,KAAK,EAAE,aAAa,IAAI,CAAC,EAAE;SACzD,CAAC,CAAC;IACL,CAAC;CAEF;AArFD,0CAqFC"}
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/shell/emitter.ts"],"names":[],"mappings":"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"}

package/dist/shell/menu-cancel.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Decision logic for submitting a queued prompt after ESC-cancelling a bridged
+ * interactive menu.
+ *
+ * When the user replies to a bridged menu with free text instead of a number,
+ * the wrapper sends ESC to dismiss the menu and then wants to submit the text as
+ * a fresh prompt. But ESC makes Claude resume (it processes the cancellation),
+ * so the TUI is briefly busy/redrawing. Submitting into that transition races —
+ * the paste lands in a non-prompt state, the Enter is swallowed, and the turn
+ * never starts (→ 30-min watchdog hang). So submission is deferred until the TUI
+ * settles back to an idle prompt.
+ *
+ * This module is the pure decision: given the current observations, return the
+ * action the caller should take. Kept free of node-pty / screen imports so it is
+ * cheap to unit-test in isolation.
+ */
+export declare const MENU_CANCEL_MIN_WAIT_MS = 800;
+export declare const MENU_CANCEL_SETTLE_QUIET_MS = 600;
+export declare const MENU_CANCEL_ESC_RETRY_MS = 1500;
+export declare const MENU_CANCEL_MAX_ESC = 3;
+export declare const MENU_CANCEL_TIMEOUT_MS = 15000;
+export type MenuCancelAction = 'wait' | 'resend-esc' | 'submit';
+export interface MenuCancelState {
+    /** Timestamp (ms) of the first ESC that started this cancel. */
+    since: number;
+    /** Timestamp (ms) of the most recent ESC sent. */
+    lastEscAt: number;
+    /** How many ESCs have been sent so far (starts at 1). */
+    escs: number;
+}
+export interface MenuCancelObs {
+    now: number;
+    /** Is an interactive select menu still on screen? */
+    menuVisible: boolean;
+    /** Is the normal input prompt box present? */
+    hasPrompt: boolean;
+    /** Is the TUI busy (spinner / processing)? */
+    isBusy: boolean;
+    /** Milliseconds since the last PTY output. */
+    quietMs: number;
+}
+/**
+ * Decide what to do while waiting for the TUI to settle after a menu-cancel.
+ *
+ * - `submit`    — the queued prompt is safe to type now (or the hard timeout hit).
+ * - `resend-esc` — the menu is still up; ESC was likely swallowed, send it again.
+ * - `wait`      — keep waiting; nothing to do this tick.
+ */
+export declare function decideMenuCancel(state: MenuCancelState, obs: MenuCancelObs): MenuCancelAction;
+//# sourceMappingURL=menu-cancel.d.ts.map

package/dist/shell/menu-cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-cancel.d.ts","sourceRoot":"","sources":["../../src/shell/menu-cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,aAAa,GAAG,gBAAgB,CAyB7F"}

package/dist/shell/menu-cancel.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Decision logic for submitting a queued prompt after ESC-cancelling a bridged
+ * interactive menu.
+ *
+ * When the user replies to a bridged menu with free text instead of a number,
+ * the wrapper sends ESC to dismiss the menu and then wants to submit the text as
+ * a fresh prompt. But ESC makes Claude resume (it processes the cancellation),
+ * so the TUI is briefly busy/redrawing. Submitting into that transition races —
+ * the paste lands in a non-prompt state, the Enter is swallowed, and the turn
+ * never starts (→ 30-min watchdog hang). So submission is deferred until the TUI
+ * settles back to an idle prompt.
+ *
+ * This module is the pure decision: given the current observations, return the
+ * action the caller should take. Kept free of node-pty / screen imports so it is
+ * cheap to unit-test in isolation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MENU_CANCEL_TIMEOUT_MS = exports.MENU_CANCEL_MAX_ESC = exports.MENU_CANCEL_ESC_RETRY_MS = exports.MENU_CANCEL_SETTLE_QUIET_MS = exports.MENU_CANCEL_MIN_WAIT_MS = void 0;
+exports.decideMenuCancel = decideMenuCancel;
+// Minimum delay after the ESC before we allow a submit. Gives Claude time to
+// start any cancellation response so `isBusy` can catch it (and block us).
+exports.MENU_CANCEL_MIN_WAIT_MS = 800;
+// The PTY must be quiet at least this long, once back at an idle prompt.
+exports.MENU_CANCEL_SETTLE_QUIET_MS = 600;
+// If the menu lingers (ESC swallowed), re-send ESC no more often than this.
+exports.MENU_CANCEL_ESC_RETRY_MS = 1500;
+// Cap on ESC re-sends before we stop retrying.
+exports.MENU_CANCEL_MAX_ESC = 3;
+// Hard fallback: submit anyway after this long so a stuck TUI never hangs.
+exports.MENU_CANCEL_TIMEOUT_MS = 15000;
+/**
+ * Decide what to do while waiting for the TUI to settle after a menu-cancel.
+ *
+ * - `submit`    — the queued prompt is safe to type now (or the hard timeout hit).
+ * - `resend-esc` — the menu is still up; ESC was likely swallowed, send it again.
+ * - `wait`      — keep waiting; nothing to do this tick.
+ */
+function decideMenuCancel(state, obs) {
+    const { since, lastEscAt, escs } = state;
+    const { now, menuVisible, hasPrompt, isBusy, quietMs } = obs;
+    // Hard timeout: never hang — submit regardless of screen state. The turn's
+    // own Enter-retry logic is the last line of defence for a swallowed submit.
+    if (now - since > exports.MENU_CANCEL_TIMEOUT_MS)
+        return 'submit';
+    // Settled back to an idle prompt → safe to submit the queued text.
+    if (!menuVisible
+        && hasPrompt
+        && !isBusy
+        && now - since >= exports.MENU_CANCEL_MIN_WAIT_MS
+        && quietMs >= exports.MENU_CANCEL_SETTLE_QUIET_MS) {
+        return 'submit';
+    }
+    // Menu still lingering → ESC may have been swallowed; re-send periodically.
+    if (menuVisible
+        && now - lastEscAt > exports.MENU_CANCEL_ESC_RETRY_MS
+        && escs < exports.MENU_CANCEL_MAX_ESC) {
+        return 'resend-esc';
+    }
+    return 'wait';
+}
+//# sourceMappingURL=menu-cancel.js.map

package/dist/shell/menu-cancel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-cancel.js","sourceRoot":"","sources":["../../src/shell/menu-cancel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AA4CH,4CAyBC;AAnED,6EAA6E;AAC7E,2EAA2E;AAC9D,QAAA,uBAAuB,GAAG,GAAG,CAAC;AAC3C,yEAAyE;AAC5D,QAAA,2BAA2B,GAAG,GAAG,CAAC;AAC/C,4EAA4E;AAC/D,QAAA,wBAAwB,GAAG,IAAI,CAAC;AAC7C,+CAA+C;AAClC,QAAA,mBAAmB,GAAG,CAAC,CAAC;AACrC,2EAA2E;AAC9D,QAAA,sBAAsB,GAAG,KAAM,CAAC;AAyB7C;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAAsB,EAAE,GAAkB;IACzE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACzC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;IAE7D,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAI,GAAG,GAAG,KAAK,GAAG,8BAAsB;QAAE,OAAO,QAAQ,CAAC;IAE1D,mEAAmE;IACnE,IAAI,CAAC,WAAW;WACT,SAAS;WACT,CAAC,MAAM;WACP,GAAG,GAAG,KAAK,IAAI,+BAAuB;WACtC,OAAO,IAAI,mCAA2B,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,4EAA4E;IAC5E,IAAI,WAAW;WACR,GAAG,GAAG,SAAS,GAAG,gCAAwB;WAC1C,IAAI,GAAG,2BAAmB,EAAE,CAAC;QAClC,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/shell/pty-serialize.d.ts

@@ -0,0 +1,23 @@
+import type { Terminal } from '@xterm/headless';
+/**
+ * Serialize a headless terminal's CURRENT visible screen into a self-contained
+ * sequence of escape codes that, written into a fresh xterm, reproduces the same
+ * screen exactly.
+ *
+ * Why this exists: the PTY stream registry used to replay the last N KB of RAW
+ * bytes on every (re)connect. An alt-screen TUI (Claude Code runs in the
+ * alternate buffer) cannot be reconstructed from a truncated byte tail — the
+ * visible screen is the *cumulative* result of every byte since session start.
+ * Once output exceeds the ring-buffer cap (which happens fast during an active
+ * turn), the front is trimmed mid-sequence: the alt-screen-enter, scroll-region
+ * setup, cursor moves, and even multi-byte UTF-8 codepoints get cut in half, so
+ * xterm desyncs and renders a blank or garbled screen (notably the infrequently
+ * repainted bottom status/cost bar). Serializing the live screen grid instead
+ * guarantees the viewer always receives one complete, coherent frame regardless
+ * of how much history has scrolled past.
+ *
+ * The output is a Unicode string (cell chars are decoded) — callers MUST encode
+ * it as UTF-8 on the wire, not latin1.
+ */
+export declare function serializeScreen(term: Terminal): string;
+//# sourceMappingURL=pty-serialize.d.ts.map

package/dist/shell/pty-serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-serialize.d.ts","sourceRoot":"","sources":["../../src/shell/pty-serialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAqDtD"}

package/dist/shell/pty-serialize.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeScreen = serializeScreen;
+/**
+ * Serialize a headless terminal's CURRENT visible screen into a self-contained
+ * sequence of escape codes that, written into a fresh xterm, reproduces the same
+ * screen exactly.
+ *
+ * Why this exists: the PTY stream registry used to replay the last N KB of RAW
+ * bytes on every (re)connect. An alt-screen TUI (Claude Code runs in the
+ * alternate buffer) cannot be reconstructed from a truncated byte tail — the
+ * visible screen is the *cumulative* result of every byte since session start.
+ * Once output exceeds the ring-buffer cap (which happens fast during an active
+ * turn), the front is trimmed mid-sequence: the alt-screen-enter, scroll-region
+ * setup, cursor moves, and even multi-byte UTF-8 codepoints get cut in half, so
+ * xterm desyncs and renders a blank or garbled screen (notably the infrequently
+ * repainted bottom status/cost bar). Serializing the live screen grid instead
+ * guarantees the viewer always receives one complete, coherent frame regardless
+ * of how much history has scrolled past.
+ *
+ * The output is a Unicode string (cell chars are decoded) — callers MUST encode
+ * it as UTF-8 on the wire, not latin1.
+ */
+function serializeScreen(term) {
+    const buf = term.buffer.active;
+    const cols = term.cols;
+    const rows = term.rows;
+    let out = '\x1b[0m';
+    // Match the server's buffer mode so a later '?1049l' (session exit) behaves
+    // correctly on the client; alt-screen also clears its own scrollback.
+    if (buf.type === 'alternate')
+        out += '\x1b[?1049h';
+    out += '\x1b[2J';
+    let cell;
+    for (let y = 0; y < rows; y++) {
+        const line = buf.getLine(buf.viewportY + y);
+        out += `\x1b[${y + 1};1H`;
+        if (!line)
+            continue;
+        // Find the last column that paints something visible. The screen was already
+        // cleared by '\x1b[2J', so trailing blanks need not be emitted — this keeps
+        // null cells null (faithful reconstruction) and shrinks the frame a lot.
+        let last = -1;
+        for (let x = cols - 1; x >= 0; x--) {
+            cell = line.getCell(x, cell);
+            if (cell && isVisible(cell)) {
+                last = x;
+                break;
+            }
+        }
+        if (last < 0)
+            continue;
+        let curSgr = '';
+        for (let x = 0; x <= last; x++) {
+            cell = line.getCell(x, cell);
+            if (!cell) {
+                out += ' ';
+                continue;
+            }
+            // Width 0 = the spacer cell that follows a wide (CJK/emoji) glyph; the
+            // glyph itself already emitted its full width, so skip the spacer.
+            if (cell.getWidth() === 0)
+                continue;
+            const sgr = sgrFor(cell);
+            if (sgr !== curSgr) {
+                // Reset first so attributes never leak from the previous cell.
+                out += '\x1b[0m' + sgr;
+                curSgr = sgr;
+            }
+            const chars = cell.getChars();
+            out += chars === '' ? ' ' : chars;
+        }
+        out += '\x1b[0m';
+    }
+    // Restore the cursor to where the live screen has it (1-based, viewport-relative).
+    out += `\x1b[${buf.cursorY + 1};${buf.cursorX + 1}H`;
+    return out;
+}
+/**
+ * Whether a cell paints anything the eye can see. A space with default colors is
+ * invisible (so it can be trimmed from a cleared screen), but a space with a
+ * background color, or under inverse video (which swaps fg/bg), is visible.
+ */
+function isVisible(cell) {
+    const ch = cell.getChars();
+    if (ch !== '' && ch !== ' ')
+        return true;
+    if (!cell.isBgDefault())
+        return true;
+    if (cell.isInverse())
+        return true;
+    return false;
+}
+/** Build the SGR (Select Graphic Rendition) escape for a single cell's attributes. */
+function sgrFor(cell) {
+    const codes = [];
+    if (cell.isBold())
+        codes.push(1);
+    if (cell.isDim())
+        codes.push(2);
+    if (cell.isItalic())
+        codes.push(3);
+    if (cell.isUnderline())
+        codes.push(4);
+    if (cell.isBlink())
+        codes.push(5);
+    if (cell.isInverse())
+        codes.push(7);
+    if (cell.isInvisible())
+        codes.push(8);
+    if (cell.isStrikethrough())
+        codes.push(9);
+    if (cell.isOverline())
+        codes.push(53);
+    if (cell.isFgRGB()) {
+        const c = cell.getFgColor();
+        codes.push(38, 2, (c >> 16) & 0xff, (c >> 8) & 0xff, c & 0xff);
+    }
+    else if (cell.isFgPalette()) {
+        codes.push(38, 5, cell.getFgColor());
+    }
+    if (cell.isBgRGB()) {
+        const c = cell.getBgColor();
+        codes.push(48, 2, (c >> 16) & 0xff, (c >> 8) & 0xff, c & 0xff);
+    }
+    else if (cell.isBgPalette()) {
+        codes.push(48, 5, cell.getBgColor());
+    }
+    return codes.length ? `\x1b[${codes.join(';')}m` : '';
+}
+//# sourceMappingURL=pty-serialize.js.map

package/dist/shell/pty-serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-serialize.js","sourceRoot":"","sources":["../../src/shell/pty-serialize.ts"],"names":[],"mappings":"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"}

package/dist/shell/pty-stream-registry.d.ts

@@ -0,0 +1,59 @@
+import { WebSocket } from 'ws';
+/**
+ * Tracks live PTY output streams so the dashboard can mirror a running shell.
+ *
+ * Everything is keyed by `streamKey` — the per-session id, NOT the agent id. A
+ * single agent can run several concurrent sessions (e.g. a Telegram session and
+ * an API/cron session), each its own PTY with its own screen. Keying by agent
+ * id would merge them: both sessions would feed one shared mirror (interleaved,
+ * unreadable output) and the viewer could not target a specific session. Keying
+ * by session id keeps each stream isolated.
+ */
+export declare class PtyStreamRegistry {
+    private readonly clients;
+    private readonly servers;
+    private readonly streamSockets;
+    /**
+     * Headless terminal mirror per stream. Fed every PTY byte so it always holds
+     * the session's current screen grid; on subscribe we serialize this into one
+     * complete frame instead of replaying a (lossy, truncatable) raw-byte tail.
+     */
+    private readonly screens;
+    /** Per-session unix socket path. Derived from the session id so each session gets its own stream. */
+    socketPath(streamKey: string): string;
+    listen(streamKey: string, socketPath: string): void;
+    close(socketPath: string): void;
+    /** Returns true if at least one active PTY socket server is registered for this stream/session. */
+    hasSockets(streamKey: string): boolean;
+    /**
+     * Return the current visible screen as plain text — ANSI escape codes stripped,
+     * trailing blank lines removed. Each screen row becomes one line in the output.
+     * Returns null if no headless mirror exists for the given stream key (session
+     * not running in PTY mode, or not yet started).
+     *
+     * Intended for agents that need to observe what is currently displayed in the
+     * PTY shell (e.g. to detect hang states, unexpected prompts, or tool output)
+     * without having to parse ANSI/VT100 sequences.
+     *
+     * Async: flushes the terminal's write queue (same as subscribe does for the
+     * serialized frame) so the snapshot reflects every byte received so far.
+     */
+    screenText(streamKey: string): Promise<{
+        text: string;
+        cursorRow: number;
+        cursorCol: number;
+        cols: number;
+        rows: number;
+    } | null>;
+    subscribe(streamKey: string, ws: WebSocket): void;
+    unsubscribe(streamKey: string, ws: WebSocket): void;
+    broadcast(streamKey: string, data: string): void;
+    /** Feed raw PTY bytes into the stream's headless mirror, creating it on first use. */
+    private feedScreen;
+    /** Start a clean mirror for a fresh session, disposing any prior one. */
+    private resetScreen;
+    private disposeScreen;
+    private createTerm;
+}
+export declare const ptyStreamRegistry: PtyStreamRegistry;
+//# sourceMappingURL=pty-stream-registry.d.ts.map

package/dist/shell/pty-stream-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-stream-registry.d.ts","sourceRoot":"","sources":["../../src/shell/pty-stream-registry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAS/B;;;;;;;;;GASG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,qGAAqG;IACrG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAOrC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAoBnD,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAe/B,mGAAmG;IACnG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAItC;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAoDvI,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI;IAqBjD,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI;IAOnD,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAYhD,sFAAsF;IACtF,OAAO,CAAC,UAAU;IAalB,yEAAyE;IACzE,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,UAAU;CAKnB;AAED,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}