@cocorograph/hub-agent 0.5.27 → 0.5.28

package/package.json

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

package/src/pty-bridge.mjs

@@ -28,6 +28,18 @@ const DEFAULT_ROWS = 32
 // に見える (1 フレーム 16.7ms より短いので体感レイテンシは増えない)。
 const DEFAULT_COALESCE_MS = 12
 
+// orphan stream GC 設定。
+// - DEFAULT_GC_INTERVAL_MS: GC スキャン周期 (60s)。短すぎても CPU 負担、長すぎても
+//   pty 枯渇に到達してから掃除されるまでに時間がかかる。1 分は妥当な balance。
+// - DEFAULT_GC_STALE_MS: stream idle 判定の閾値 (10 min)。Cockpit window が
+//   通常使用中は 5s 周期で session.state 等で touch されるので絶対に達しない。
+//   リロード時の切断 (秒〜十数秒) も無傷。何時間も放置された孤児だけ掃除される。
+//   ※ アクティブ stream が「10 分間まったく操作されない」= ユーザー席離れ等。
+//      その場合のみ kill されるが、tmux session 自体は別 process なので作業内容
+//      は無傷、リロードで再 attach できる。
+const DEFAULT_GC_INTERVAL_MS = 60_000
+const DEFAULT_GC_STALE_MS = 10 * 60_000
+
 function resolveBin(name) {
   try {
     return execFileSync("/usr/bin/which", [name], { encoding: "utf-8" }).trim()
@@ -53,7 +65,32 @@ export class PtyBridge extends EventEmitter {
    *     `/bin/sh -c "exec tmux attach -t <sessionName>"`
    * @param {number} [opts.coalesceMs] - pty 出力を coalesce する間隔 (ms)。0 で無効。
    */
-  constructor({ ptyModule, logger, plugins = [], defaultSpawnCommand, coalesceMs } = {}) {
+  constructor({
+    ptyModule,
+    logger,
+    plugins = [],
+    defaultSpawnCommand,
+    coalesceMs,
+    /**
+     * 孤児 stream の GC 設定。
+     *
+     * 背景: 旧設計では WS reconnect / Cockpit window リロード / タブ閉じ等で
+     * `pty.detach` が agent に届かないケースがあり、pty fd が leak していた。
+     * macOS の `kern.tty.ptmx_max` は 511 個でその上限に到達すると新規
+     * posix_spawnp が `EAGAIN` で失敗する (= "posix_spawnp failed" の真因)。
+     *
+     * 対処: 各 stream に `lastSeenAt` を持たせ、`attach` / `write` / `resize`
+     * のたびに touch する。`gcIntervalMs` 周期で `gcStaleMs` を超えた stream を
+     * 自動 detach する (= orphan GC)。**アクティブな stream は browser からの
+     * pty.data / pty.resize で常に touch されるため絶対に kill されない**。
+     * リロード時の短時間切断 (秒〜十数秒) も `gcStaleMs` (デフォルト 10 分)
+     * 未満なので無傷。何時間も放置された孤児だけ掃除される。
+     *
+     * gcStaleMs を 0 以下にすると GC を無効化する (旧挙動)。テスト・特殊用途向け。
+     */
+    gcIntervalMs,
+    gcStaleMs,
+  } = {}) {
     super()
     if (!ptyModule || typeof ptyModule.spawn !== "function") {
       throw new TypeError("PtyBridge requires { ptyModule: { spawn } }")
@@ -73,6 +110,59 @@ export class PtyBridge extends EventEmitter {
     this.streams = new Map()
     /** @type {Map<string, {buf: string, timer: ReturnType<typeof setTimeout>|null}>} */
     this.coalesceState = new Map()
+
+    // orphan GC 設定。デフォルトは 1 分周期で 10 分間 idle の stream を kill。
+    this.gcIntervalMs = gcIntervalMs ?? DEFAULT_GC_INTERVAL_MS
+    this.gcStaleMs = gcStaleMs ?? DEFAULT_GC_STALE_MS
+    /** @type {Map<string, number>} stream_id → lastSeenAt (ms epoch) */
+    this.lastSeenAt = new Map()
+    /** @type {ReturnType<typeof setInterval>|null} */
+    this._gcTimer = null
+    if (this.gcStaleMs > 0 && this.gcIntervalMs > 0) {
+      this._gcTimer = setInterval(() => this._gcStaleStreams(), this.gcIntervalMs)
+      // unref で Node の event loop を止めない (test 環境で hang しないため)。
+      if (typeof this._gcTimer.unref === "function") this._gcTimer.unref()
+    }
+  }
+
+  /**
+   * 現在時刻を ms epoch で返す。テストで now を差し替えるため override 可能に。
+   * @returns {number}
+   */
+  _now() {
+    return Date.now()
+  }
+
+  /**
+   * stream_id を「最近 browser からアクセスがあった」と record する。
+   * attach / write / resize の各 entry point から呼ぶ。
+   * @param {string} stream_id
+   */
+  _touch(stream_id) {
+    this.lastSeenAt.set(stream_id, this._now())
+  }
+
+  /**
+   * `gcStaleMs` を超えて idle な stream を一括 detach する。
+   *
+   * `_gcTimer` から `gcIntervalMs` 周期で呼ばれる。手動でも呼べる (テスト用)。
+   * @returns {string[]} kill した stream_id 一覧 (debug / test 用)
+   */
+  _gcStaleStreams() {
+    if (!(this.gcStaleMs > 0)) return []
+    const cutoff = this._now() - this.gcStaleMs
+    const killed = []
+    for (const [stream_id, ts] of this.lastSeenAt) {
+      if (ts < cutoff && this.streams.has(stream_id)) {
+        this.logger?.warn(
+          { stream_id, stale_ms: this._now() - ts, gc_stale_ms: this.gcStaleMs },
+          "pty GC: orphaned stream killed",
+        )
+        this.detach({ stream_id })
+        killed.push(stream_id)
+      }
+    }
+    return killed
   }
 
   /**
@@ -134,6 +224,7 @@ export class PtyBridge extends EventEmitter {
     }
 
     this.streams.set(stream_id, pty)
+    this._touch(stream_id)
     this.logger?.info(
       { stream_id, sessionName, command: spec.command, plugin: hookResult?.plugin || null },
       "pty attached",
@@ -164,6 +255,7 @@ export class PtyBridge extends EventEmitter {
       this._flushCoalesce(stream_id)
       this.coalesceState.delete(stream_id)
       this.streams.delete(stream_id)
+      this.lastSeenAt.delete(stream_id)
       this.emit("exit", { stream_id, code: exitCode })
     })
 
@@ -181,6 +273,7 @@ export class PtyBridge extends EventEmitter {
       this.logger?.warn({ stream_id }, "pty.write but stream missing")
       return false
     }
+    this._touch(stream_id)
     pty.write(data)
     return true
   }
@@ -192,6 +285,7 @@ export class PtyBridge extends EventEmitter {
       this.logger?.warn({ stream_id }, "pty.resize but stream missing")
       return false
     }
+    this._touch(stream_id)
     try {
       pty.resize(cols, rows)
       return true
@@ -208,6 +302,9 @@ export class PtyBridge extends EventEmitter {
     // kill 前に残バッファを emit しておく (onExit にも flush はあるが、
     // detach は browser 側都合なので最新を確実に届けたい)。
     this._flushCoalesce(stream_id)
+    // GC tracking もここでクリア。pty.onExit でも消すが、onExit が来る前に
+    // 同じ stream_id が再 attach されると古い lastSeenAt が残るリスクを避ける。
+    this.lastSeenAt.delete(stream_id)
     try {
       pty.kill()
     } catch {
@@ -218,6 +315,10 @@ export class PtyBridge extends EventEmitter {
 
   /** 全 pty を即時 kill (agent shutdown 用)。 */
   shutdown() {
+    if (this._gcTimer) {
+      clearInterval(this._gcTimer)
+      this._gcTimer = null
+    }
     for (const stream_id of Array.from(this.streams.keys())) {
       this.detach({ stream_id })
     }