@cocorograph/hub-agent 0.8.23 → 0.8.25

package/src/pty-bridge.mjs

@@ -1,510 +0,0 @@
-/**
- * node-pty ベースの pty 多重化ブリッジ (Sprint D)。
- *
- * - 1 agent プロセス内で複数 stream を `Map<stream_id, PtyProcess>` で管理
- * - `attach()` で pty を spawn (plugin `interceptPtySpawn` が override 可)
- * - `write()` / `resize()` / `detach()` は stream_id で個別操作
- * - pty 出力は `'output'` イベント、終了は `'exit'` イベントで EventEmitter 経由
- *
- * デフォルト spawn は `tmux attach -t <session_name>` (Sprint E で tmux モジュール
- * が attach 前に session が存在することを保証する想定)。
- *
- * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
- * 移植元: D00000_cockpit/webapp/server/ws-server.mjs
- */
-import { EventEmitter } from "node:events"
-import { execFileSync } from "node:child_process"
-
-import { runHookChain } from "./plugin-loader.mjs"
-
-const DEFAULT_COLS = 120
-const DEFAULT_ROWS = 32
-
-// pty.onData の chunk を coalesce する待ち時間 (ms)。
-// 0 だと chunk 1 つにつき 1 WebSocket メッセージ + 1 JSON.stringify になり、
-// claude TUI の連続 redraw で秒間 100+ メッセージ → Hub → channels_redis pub/sub
-// → ブラウザ JSON.parse が詰まって瞬断・固まりの原因になる。12ms バッファに
-// 溜めて 80Hz 程度に丸めるとメッセージ数が 1/5〜1/10 に減り、画面は十分滑らか
-// に見える (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
-
-// 安全弁: 同時 attach できる pty の上限本数。万一リークが残っても macOS の
-// `kern.tty.ptmx_max` (=511) に到達する前に最古の stream を強制 reap して枯渇を
-// 防ぐ (504/511 まで溜めて新規ターミナルが開けなくなった 2026-06-16 障害の再発防止)。
-// 0 以下で無効化 (テスト用)。
-const DEFAULT_MAX_STREAMS = 256
-
-function resolveBin(name) {
-  try {
-    return execFileSync("/usr/bin/which", [name], { encoding: "utf-8" }).trim()
-  } catch {
-    return name
-  }
-}
-
-let _tmuxBin = null
-function tmuxBin() {
-  if (_tmuxBin === null) _tmuxBin = resolveBin("tmux")
-  return _tmuxBin
-}
-
-export class PtyBridge extends EventEmitter {
-  /**
-   * @param {object} opts
-   * @param {object} opts.ptyModule - `await import('node-pty')` の結果 (テストで stub 注入可)
-   * @param {import('pino').Logger} [opts.logger]
-   * @param {Array} [opts.plugins] - plugin-loader.mjs の loadPlugins() 結果
-   * @param {(args: {sessionName: string, cols: number, rows: number, env: object}) => {command: string, args: string[], env?: object}} [opts.defaultSpawnCommand]
-   *   - plugin が null を返したときに使うデフォルト spawn 仕様。省略時は
-   *     `/bin/sh -c "exec tmux attach -t <sessionName>"`
-   * @param {number} [opts.coalesceMs] - pty 出力を coalesce する間隔 (ms)。0 で無効。
-   */
-  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`
-     * および **pty 出力 (onData)** のたびに touch する。`gcIntervalMs` 周期で
-     * `gcStaleMs` を超えた stream を自動 detach する (= orphan GC)。**アクティブな
-     * stream は browser からの pty.data / pty.resize、または claude の出力で常に
-     * touch されるため絶対に kill されない** (生成中で出力は流れるが入力が間遠い
-     * 閲覧中の TUI チャットが reap される A-4 を出力 touch で塞ぐ)。
-     * リロード時の短時間切断 (秒〜十数秒) も `gcStaleMs` (デフォルト 10 分)
-     * 未満なので無傷。何時間も放置された孤児だけ掃除される。
-     *
-     * gcStaleMs を 0 以下にすると GC を無効化する (旧挙動)。テスト・特殊用途向け。
-     */
-    gcIntervalMs,
-    gcStaleMs,
-    /**
-     * 同時 attach 上限 (安全弁)。超過すると新規 attach 前に最古の stream を強制
-     * reap する。リーク回帰があっても PTY 枯渇に至らせないためのハードリミット。
-     */
-    maxStreams,
-  } = {}) {
-    super()
-    if (!ptyModule || typeof ptyModule.spawn !== "function") {
-      throw new TypeError("PtyBridge requires { ptyModule: { spawn } }")
-    }
-    this.ptyModule = ptyModule
-    this.logger = logger
-    this.plugins = plugins
-    this.defaultSpawnCommand =
-      defaultSpawnCommand ||
-      (({ sessionName }) => ({
-        command: "/bin/sh",
-        args: ["-c", `exec ${tmuxBin()} attach -t ${sessionName}`],
-        env: process.env,
-      }))
-    this.coalesceMs = coalesceMs ?? DEFAULT_COALESCE_MS
-    this.maxStreams = maxStreams ?? DEFAULT_MAX_STREAMS
-    /** @type {Map<string, import('node-pty').IPty>} */
-    this.streams = new Map()
-    /** @type {Map<string, {buf: string, timer: ReturnType<typeof setTimeout>|null}>} */
-    this.coalesceState = new Map()
-    /**
-     * stream_id → onData/onExit の IDisposable[]。
-     * reap 時に dispose() しないと listener が IPty を参照し続け、master fd が
-     * close されず leak する (= ユーザー指摘「リスナ経由の参照残り」)。
-     * @type {Map<string, Array<{dispose: () => void}>>}
-     */
-    this.disposables = new Map()
-    // 可観測性: 起動からの累計 spawn / reap 数。差分 (= held) が単調増加したら leak。
-    this._spawnedTotal = 0
-    this._reapedTotal = 0
-
-    // 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._logStats()
-      }, 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())
-  }
-
-  /**
-   * stream の最終 touch 時刻 (ms epoch) を返す。未登録 / 未 touch は 0。
-   * Plan ε (handleStreamsSyncResponse) の grace 判定で「直近 attach/write/resize/出力が
-   * あった stream は browser が再 attach 中なだけ」と見なして誤殺を防ぐために使う。
-   * @param {string} stream_id
-   * @returns {number}
-   */
-  getLastSeen(stream_id) {
-    return this.lastSeenAt.get(stream_id) ?? 0
-  }
-
-  /**
-   * `gcStaleMs` を超えて idle な stream を一括 reap する。
-   *
-   * `_gcTimer` から `gcIntervalMs` 周期で呼ばれる。手動でも呼べる (テスト用)。
-   *
-   * ⚠️ 走査対象は `this.streams` (= 実際に fd を保持している正本)。旧実装は
-   * `lastSeenAt` を走査していたが、`detach` が kill 前に `lastSeenAt` を消す一方で
-   * `streams` からの削除を `onExit` 頼みにしていたため、`onExit` が取りこぼされると
-   * 「streams に残る・lastSeenAt は無い」孤児が GC から不可視になり永久 leak した
-   * (2026-06-16 障害の主因)。streams を正本に走査することでこの不可視孤児を根絶する。
-   * @returns {string[]} reap した stream_id 一覧 (debug / test 用)
-   */
-  _gcStaleStreams() {
-    if (!(this.gcStaleMs > 0)) return []
-    const cutoff = this._now() - this.gcStaleMs
-    const killed = []
-    for (const stream_id of Array.from(this.streams.keys())) {
-      // lastSeenAt 欠落 (= 不可視孤児) は 0 扱い = 即 stale 判定で確実に回収する。
-      const ts = this.lastSeenAt.get(stream_id) ?? 0
-      if (ts < cutoff) {
-        this.logger?.warn(
-          { stream_id, stale_ms: this._now() - ts, gc_stale_ms: this.gcStaleMs },
-          "pty GC: orphaned stream killed",
-        )
-        this._reap(stream_id, { emitExit: true, code: null })
-        killed.push(stream_id)
-      }
-    }
-    return killed
-  }
-
-  /**
-   * 1 つの stream の後始末を一元化する (= 全リーク経路の単一出口)。
-   *
-   * 正常終了 (onExit) / browser detach / GC / 上限超過 / shutdown の全経路がここを
-   * 通る。冪等: 既に reap 済みなら何もしない (false を返す)。
-   *
-   * 順序が重要:
-   *  1. `streams` から **最初に** 削除する。`pty.kill()` が onExit を同期発火させる
-   *     実装 (テスト stub / 一部の node-pty 経路) で onExit ハンドラが再入しても、
-   *     その時点で stream が消えているので二重 emit / 二重カウントを防げる。
-   *  2. 残バッファを flush (取りこぼし防止)。
-   *  3. onData/onExit listener を dispose (参照残りによる fd 保持を断つ)。
-   *  4. 補助 Map をクリアし、最後に `pty.kill()` で master fd を解放する。
-   *
-   * @param {string} stream_id
-   * @param {{emitExit?: boolean, code?: number|null}} [opts]
-   * @returns {boolean} 実際に reap したら true
-   */
-  _reap(stream_id, { emitExit = false, code = null } = {}) {
-    const existed = this.streams.has(stream_id)
-    const pty = this.streams.get(stream_id)
-    // (1) streams から最初に外す → 以降の同期 onExit 再入は no-op。
-    this.streams.delete(stream_id)
-    // (2) 残バッファを取りこぼさない。
-    this._flushCoalesce(stream_id)
-    // (3) listener を dispose (node-pty の onData/onExit は IDisposable を返す)。
-    const disps = this.disposables.get(stream_id)
-    if (disps) {
-      for (const d of disps) {
-        try {
-          d?.dispose?.()
-        } catch {
-          /* ignore */
-        }
-      }
-    }
-    this.disposables.delete(stream_id)
-    this.coalesceState.delete(stream_id)
-    this.lastSeenAt.delete(stream_id)
-    // (4) master fd を解放。
-    //   ⚠️ `pty.kill()` は子プロセスに SIGHUP を送るだけで、master fd を握る
-    //   内部 socket を破棄しない。macOS では子終了後に socket の 'close' が
-    //   発火せず fd が残り続ける → これが 2026-06-16 の PTY 枯渇 (504/511) の真因。
-    //   node-pty UnixTerminal の `destroy()` は `_socket.destroy()` で fd を即時
-    //   close してから SIGHUP を送るので、こちらを使う (公開 typings に無い内部 API
-    //   のため feature-detect。Windows 等で未定義なら kill にフォールバック)。
-    if (pty) {
-      try {
-        if (typeof pty.destroy === "function") pty.destroy()
-        else pty.kill()
-      } catch {
-        /* already dead / socket already closed */
-      }
-    }
-    if (existed) {
-      this._reapedTotal += 1
-      if (emitExit) this.emit("exit", { stream_id, code })
-    }
-    return existed
-  }
-
-  /**
-   * 現在保持している pty 本数と累計 spawn/reap をログ出力する (可観測性)。
-   * `leak_delta` は理論上常に 0 (held === spawned - reaped)。非 0 が続いたら異常。
-   */
-  _logStats() {
-    const held = this.streams.size
-    this.logger?.info(
-      {
-        held,
-        spawned_total: this._spawnedTotal,
-        reaped_total: this._reapedTotal,
-        leak_delta: this._spawnedTotal - this._reapedTotal - held,
-        max_streams: this.maxStreams,
-      },
-      "pty stats",
-    )
-  }
-
-  /**
-   * 現在の保持本数・累計カウンタを返す (テスト / debug 用)。
-   * @returns {{held: number, spawnedTotal: number, reapedTotal: number}}
-   */
-  stats() {
-    return {
-      held: this.streams.size,
-      spawnedTotal: this._spawnedTotal,
-      reapedTotal: this._reapedTotal,
-    }
-  }
-
-  /**
-   * stream の coalesce buffer を即時 flush して emit する。
-   * detach / exit / shutdown のタイミングで残バッファの取りこぼしを防ぐ。
-   * @param {string} stream_id
-   */
-  _flushCoalesce(stream_id) {
-    const state = this.coalesceState.get(stream_id)
-    if (!state) return
-    if (state.timer) {
-      clearTimeout(state.timer)
-      state.timer = null
-    }
-    if (state.buf) {
-      const out = state.buf
-      state.buf = ""
-      this.emit("output", { stream_id, data: out })
-    }
-  }
-
-  /**
-   * 新しい pty を spawn して stream_id に紐付ける。
-   *
-   * @param {{stream_id: string, sessionName?: string, cols?: number, rows?: number, env?: object}} args
-   * @returns {Promise<{plugin: string|null, command: string, args: string[]}>}
-   */
-  async attach({ stream_id, sessionName = "", cols = DEFAULT_COLS, rows = DEFAULT_ROWS, env }) {
-    if (!stream_id) throw new TypeError("attach requires stream_id")
-    if (this.streams.has(stream_id)) {
-      throw new Error(`stream_id "${stream_id}" は既に attach 済みです`)
-    }
-    // 安全弁: 上限到達時は最古 (lastSeenAt 最小) の stream を強制 reap してから
-    // spawn する。リークが残っても PTY 枯渇に至らせないハードリミット。
-    if (this.maxStreams > 0 && this.streams.size >= this.maxStreams) {
-      let oldestId = null
-      let oldestTs = Infinity
-      for (const sid of this.streams.keys()) {
-        const ts = this.lastSeenAt.get(sid) ?? 0
-        if (ts < oldestTs) {
-          oldestTs = ts
-          oldestId = sid
-        }
-      }
-      if (oldestId) {
-        this.logger?.warn(
-          { stream_id, evicted: oldestId, held: this.streams.size, max_streams: this.maxStreams },
-          "pty cap exceeded: reaping oldest stream",
-        )
-        this._reap(oldestId, { emitExit: true, code: null })
-      }
-    }
-    const ctx = {
-      logger: this.logger,
-      sessionName,
-      cols,
-      rows,
-      env: env || process.env,
-    }
-
-    const hookResult = await runHookChain(this.plugins, "interceptPtySpawn", ctx)
-    const spec = hookResult?.result ?? this.defaultSpawnCommand(ctx)
-
-    let pty
-    try {
-      pty = this.ptyModule.spawn(spec.command, spec.args, {
-        name: "xterm-256color",
-        cols,
-        rows,
-        cwd: spec.env?.HOME || process.env.HOME,
-        env: spec.env || process.env,
-      })
-    } catch (err) {
-      this.logger?.error(
-        { stream_id, command: spec.command, err: err.message },
-        "pty spawn failed",
-      )
-      throw err
-    }
-
-    this.streams.set(stream_id, pty)
-    this._spawnedTotal += 1
-    this._touch(stream_id)
-    this.logger?.info(
-      { stream_id, sessionName, command: spec.command, plugin: hookResult?.plugin || null },
-      "pty attached",
-    )
-
-    // onData/onExit は IDisposable を返す。reap 時に dispose() するため保持する。
-    const disposables = []
-    if (this.coalesceMs > 0) {
-      const state = { buf: "", timer: null }
-      this.coalesceState.set(stream_id, state)
-      disposables.push(
-        pty.onData((data) => {
-          // 出力でも lastSeenAt を touch する (A-4 修正)。orphan GC は lastSeenAt が
-          // gcStaleMs 古い stream を reap するが、従来は write/resize/attach でしか
-          // touch していなかったため「生成中で出力は流れているが入力が間遠い閲覧中の
-          // TUI チャット」が 10 分で reap され、以後の送信が stream_missing で落ちていた
-          // (本番 agent.log で reaped_total 多数 + 同 input_id の再送 dedup を観測)。
-          // 出力が流れている = まだ生きて使われている stream なので touch して延命する。
-          // 真にブラウザが去った stream は claude がターン完了後に redraw を止めて出力が
-          // 止まり、gcStaleMs 経過で reap される。万一の runaway 出力 orphan は maxStreams
-          // 上限の最古 reap が backstop になる。
-          this._touch(stream_id)
-          state.buf += data
-          if (!state.timer) {
-            state.timer = setTimeout(() => {
-              state.timer = null
-              const out = state.buf
-              if (!out) return
-              state.buf = ""
-              this.emit("output", { stream_id, data: out })
-            }, this.coalesceMs)
-          }
-        }),
-      )
-    } else {
-      disposables.push(
-        pty.onData((data) => {
-          // 出力でも touch (A-4 修正)。理由は上の coalesce 経路のコメント参照。
-          this._touch(stream_id)
-          this.emit("output", { stream_id, data })
-        }),
-      )
-    }
-    // 正常終了経路。全後始末を _reap に一元化 (flush → dispose → fd 解放 → exit emit)。
-    disposables.push(
-      pty.onExit(({ exitCode }) => {
-        this._reap(stream_id, { emitExit: true, code: exitCode })
-      }),
-    )
-    this.disposables.set(stream_id, disposables)
-
-    return {
-      plugin: hookResult?.plugin || null,
-      command: spec.command,
-      args: spec.args,
-    }
-  }
-
-  /** ブラウザから来た入力を pty に流す。 */
-  write({ stream_id, data }) {
-    const pty = this.streams.get(stream_id)
-    if (!pty) {
-      this.logger?.warn({ stream_id }, "pty.write but stream missing")
-      return false
-    }
-    this._touch(stream_id)
-    pty.write(data)
-    return true
-  }
-
-  /** ターミナルサイズ変更。 */
-  resize({ stream_id, cols, rows }) {
-    const pty = this.streams.get(stream_id)
-    if (!pty) {
-      this.logger?.warn({ stream_id }, "pty.resize but stream missing")
-      return false
-    }
-    this._touch(stream_id)
-    try {
-      pty.resize(cols, rows)
-      return true
-    } catch (err) {
-      this.logger?.warn({ stream_id, err: err.message }, "pty.resize failed")
-      return false
-    }
-  }
-
-  /** pty を kill する。tmux session 自体は残る (detach 相当)。 */
-  detach({ stream_id }) {
-    const pty = this.streams.get(stream_id)
-    if (!pty) return false
-    // kill 前に残バッファを emit しておく (detach は browser 側都合なので最新を
-    // 確実に届けたい)。
-    this._flushCoalesce(stream_id)
-    try {
-      pty.kill()
-    } catch {
-      /* ignore */
-    }
-    // kill が onExit を同期発火する実装 (stub 等) では上の kill 内で _reap 済み。
-    // 実 node-pty は onExit が非同期なので、onExit を待たず即 reap して master fd を
-    // 解放する (= onExit 取りこぼし時の永久 leak を防ぐ核心)。_reap は冪等なので、
-    // 後から非同期 onExit が来ても no-op になる。
-    if (this.streams.has(stream_id)) {
-      this._reap(stream_id, { emitExit: true, code: null })
-    }
-    return true
-  }
-
-  /** 全 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._reap(stream_id, { emitExit: true, code: null })
-    }
-  }
-
-  /** 現在 attach 中の stream_id 一覧 (debug 用)。 */
-  list() {
-    return Array.from(this.streams.keys())
-  }
-}