@cocorograph/hub-agent 0.5.31 → 0.5.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.5.31",
+  "version": "0.5.32",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/ws-client.mjs

@@ -23,6 +23,22 @@ const MIN_BACKOFF_MS = 1_000
 const MAX_BACKOFF_MS = 30_000
 const BUNDLE_WATCH_DEBOUNCE_MS = 500
 
+// CF / origin が 5xx を返した直後の再接続は短い backoff だと 5xx キャッシュに
+// 当たって連発失敗するため、最低 5s 待つ。30s リトライまで段階的に伸びる。
+const MIN_BACKOFF_AFTER_5XX_MS = 5_000
+
+// outbound pty.data buffer のサイズ上限。
+// WS not OPEN 中に pty.data を捨てると Cockpit 上のターミナル描画が欠落して
+// 「動かない / 一部だけ表示される」体感を生むため、reconnect 後に flush する。
+// pty.data は冪等で順序維持できれば xterm 側で正しく再現できる。
+// 1 frame は典型的に 数十〜数百 bytes (claude TUI の partial redraw)。
+// 500 frame ≒ 数十KB を 1 切断あたりの上限とする。
+const PTY_BUFFER_MAX_FRAMES = 500
+// outbound buffer に残った pty.data が古すぎると、ターミナルの履歴として
+// 再生する意味が薄れる (ユーザーが視覚的に「過去のもの」として無視する範囲)。
+// 30 秒以上経過した pty.data は flush 時に破棄する。
+const PTY_BUFFER_MAX_AGE_MS = 30_000
+
 export class WsClient extends EventEmitter {
   /**
    * @param {{ hub_url: string, agent_id: string, agent_token: string }} config
@@ -55,6 +71,11 @@ export class WsClient extends EventEmitter {
     this.backoff = MIN_BACKOFF_MS
     this.stopped = false
     this.startedAt = Date.now()
+    // pty.data の outbound buffer (WS not OPEN 中に積み、open 後 flush)。
+    // entry: { obj, ts }
+    this.ptyOutboundBuffer = []
+    // 直前の close 原因が CF/origin の 5xx か。次回 backoff の下限を引き上げる。
+    this.lastCloseWas5xx = false
   }
 
   /** WSS 接続を開始する。`stop()` まで自動で reconnect 続行。 */
@@ -92,6 +113,12 @@ export class WsClient extends EventEmitter {
 
     ws.on("error", (err) => {
       this.logger?.warn({ err: err.message }, "ws error")
+      // Upgrade で CF/origin が 5xx を返した場合 (典型: "Unexpected server
+      // response: 502") は、次回 reconnect の最低 backoff を引き上げる。
+      // CF が 5xx を short-cache するため、1s 連発リトライは逆に詰まる。
+      if (/Unexpected server response: 5\d\d/.test(err?.message || "")) {
+        this.lastCloseWas5xx = true
+      }
       this.emit("error", err)
       // close もほぼ続けて飛ぶので reconnect 予約は close 側に任せる
     })
@@ -110,7 +137,13 @@ export class WsClient extends EventEmitter {
    */
   _onOpen() {
     this.backoff = MIN_BACKOFF_MS
+    this.lastCloseWas5xx = false
     this.logger?.info("ws open")
+    // 切断中に積んだ pty.data を flush。hello より先に送ると backend で stream
+    // 未登録のため unknown_stream error になる可能性があるが、hello の応答待ち
+    // 同期は backend が承認するため hello 送信後の同期 send_json で問題ない。
+    // ただし flush は hello 直後ではなく streams.sync.request の後に置く方が
+    // 安全 (sync 完了で stream_id がサーバに復元される想定)。
     // hello 前に最新の bundle version を読み直す (再接続時の鮮度確保)
     this._refreshBundleVersion()
     this._sendJson({
@@ -129,20 +162,65 @@ export class WsClient extends EventEmitter {
       type: "agent.streams.sync.request",
       request_id: randomUUID(),
     })
+    this._flushPtyBuffer()
     this._startHeartbeat()
     this._startBundleWatcher()
     this.emit("open")
   }
 
-  /** メッセージを送る。未接続なら no-op (logger.warn)。 */
+  /** メッセージを送る。未接続時は pty.data だけ buffer に積み、reconnect 後に flush。
+   *
+   * heartbeat / hello / agent.streams.sync.* など制御系は古くなると意味が無いので
+   * buffer しない (warn のみ)。
+   */
   send(obj) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      if (obj?.type === "pty.data") {
+        this._bufferPtyData(obj)
+        return false
+      }
       this.logger?.warn({ type: obj?.type }, "ws send skipped (not open)")
       return false
     }
     return this._sendJson(obj)
   }
 
+  /** pty.data を outbound buffer に積む。リング (drop oldest on overflow)。 */
+  _bufferPtyData(obj) {
+    this.ptyOutboundBuffer.push({ obj, ts: Date.now() })
+    if (this.ptyOutboundBuffer.length > PTY_BUFFER_MAX_FRAMES) {
+      const dropped = this.ptyOutboundBuffer.length - PTY_BUFFER_MAX_FRAMES
+      this.ptyOutboundBuffer.splice(0, dropped)
+      this.logger?.warn(
+        { dropped, kept: this.ptyOutboundBuffer.length },
+        "pty outbound buffer overflow (oldest dropped)"
+      )
+    }
+  }
+
+  /** open 直後に buffer を flush。古すぎる entry は破棄する。 */
+  _flushPtyBuffer() {
+    if (this.ptyOutboundBuffer.length === 0) return
+    const now = Date.now()
+    const buf = this.ptyOutboundBuffer
+    this.ptyOutboundBuffer = []
+    let sent = 0
+    let expired = 0
+    for (const entry of buf) {
+      if (now - entry.ts > PTY_BUFFER_MAX_AGE_MS) {
+        expired += 1
+        continue
+      }
+      const ok = this._sendJson(entry.obj)
+      if (!ok) break
+      sent += 1
+    }
+    this.logger?.info(
+      { sent, expired, total: buf.length },
+      "pty outbound buffer flushed"
+    )
+  }
+
   /** Reconnect を止めて切断する。 */
   stop() {
     this.stopped = true
@@ -326,11 +404,16 @@ export class WsClient extends EventEmitter {
 
   _scheduleReconnect() {
     // exponential backoff + ±20% jitter で同時接続が同期しないようにする。
-    const base = this.backoff
+    // 直前が 5xx だった場合は CF キャッシュ回避のため最低 5s を確保する。
+    const minFloor = this.lastCloseWas5xx ? MIN_BACKOFF_AFTER_5XX_MS : MIN_BACKOFF_MS
+    const base = Math.max(this.backoff, minFloor)
     const jitter = base * 0.2 * (Math.random() * 2 - 1)
-    const delay = Math.max(MIN_BACKOFF_MS, Math.round(base + jitter))
-    this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS)
-    this.logger?.info({ delayMs: delay, nextBaseMs: this.backoff }, "ws reconnect scheduled")
+    const delay = Math.max(minFloor, Math.round(base + jitter))
+    this.backoff = Math.min(Math.max(this.backoff, minFloor) * 2, MAX_BACKOFF_MS)
+    this.logger?.info(
+      { delayMs: delay, nextBaseMs: this.backoff, after5xx: this.lastCloseWas5xx },
+      "ws reconnect scheduled"
+    )
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null
       this.connect()