@cocorograph/hub-agent 0.5.27 → 0.5.29

package/package.json

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

package/src/main.mjs

@@ -403,6 +403,45 @@ export async function maybeSyncClaudeSettings(msg, ctx) {
   }
 }
 
+/**
+ * Plan ε: `agent.streams.sync.response` を受けて backend ↔ agent の現存
+ * stream_id を能動同期する。
+ *
+ * - local にあって backend にない → ptyBridge.detach で即時 kill (孤児)
+ * - backend にあって local にない → backend に pty.error を通知 (browser に
+ *   "pty 死んでます" を表示するため)
+ *
+ * dispatch から呼ぶ用のヘルパーだが、テストから直接叩けるよう export している。
+ */
+export function handleStreamsSyncResponse(msg, ctx) {
+  const activeIds = new Set(
+    Array.isArray(msg?.active_stream_ids) ? msg.active_stream_ids : [],
+  )
+  const localIds = new Set(ctx.ptyBridge.list())
+  for (const sid of localIds) {
+    if (!activeIds.has(sid)) {
+      ctx.logger?.warn?.(
+        { stream_id: sid, request_id: msg?.request_id },
+        "Plan ε: orphan stream detected, detaching",
+      )
+      ctx.ptyBridge.detach({ stream_id: sid })
+    }
+  }
+  for (const sid of activeIds) {
+    if (!localIds.has(sid)) {
+      ctx.logger?.warn?.(
+        { stream_id: sid, request_id: msg?.request_id },
+        "Plan ε: stream missing on agent, notifying backend (pty.error)",
+      )
+      ctx.client.send({
+        type: "pty.error",
+        stream_id: sid,
+        error: "stream_not_found_on_agent",
+      })
+    }
+  }
+}
+
 async function dispatch(msg, ctx) {
   const t = msg?.type || ""
   try {
@@ -456,6 +495,15 @@ async function dispatch(msg, ctx) {
       case "pty.detach":
         ctx.ptyBridge.detach({ stream_id: msg.stream_id })
         return
+      case "agent.streams.sync.response":
+        // Plan ε: backend ↔ agent の現存 stream_id 能動同期 (WS reconnect 直後に
+        // ws-client が agent.streams.sync.request を送って取得した結果)。
+        // ロジックは handleStreamsSyncResponse へ抽出 (テストから直接呼べる)。
+        // backend が旧 (= Plan ε 未対応) で response が一切来ないケースは何もしない。
+        // 5s タイムアウトのような明示的な timer は持たず、再接続時に再度 request
+        // が飛ぶので無害。
+        handleStreamsSyncResponse(msg, ctx)
+        return
       case "tmux.exec": {
         const args = Array.isArray(msg.args) ? msg.args : []
         const hookResult = await runHookChain(ctx.plugins, "interceptTmuxExec", {

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 })
     }

package/src/ws-client.mjs

@@ -11,6 +11,7 @@
  *
  * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
  */
+import { randomUUID } from "node:crypto"
 import { EventEmitter } from "node:events"
 import fs from "node:fs"
 import os from "node:os"
@@ -68,22 +69,7 @@ export class WsClient extends EventEmitter {
     const ws = new WebSocket(wsUrl, { headers })
     this.ws = ws
 
-    ws.on("open", () => {
-      this.backoff = MIN_BACKOFF_MS
-      this.logger?.info("ws open")
-      // hello 前に最新の bundle version を読み直す (再接続時の鮮度確保)
-      this._refreshBundleVersion()
-      this._sendJson({
-        type: "hello",
-        agent_id: this.config.agent_id,
-        hostname: this.hostname,
-        version: this.version,
-        bundle_version: this.bundleVersion,
-      })
-      this._startHeartbeat()
-      this._startBundleWatcher()
-      this.emit("open")
-    })
+    ws.on("open", () => this._onOpen())
 
     ws.on("message", (data) => {
       let msg
@@ -111,6 +97,43 @@ export class WsClient extends EventEmitter {
     })
   }
 
+  /**
+   * WS open 時の初期送信 + 後続タスク起動。
+   *
+   * - backoff をリセット
+   * - bundle version を最新化 → hello 送信
+   * - Plan ε: agent.streams.sync.request を送信 (毎 reconnect で能動同期)
+   * - heartbeat + bundle watcher を起動
+   *
+   * test からも直接呼べるように method として切り出している (`ws.on("open")`
+   * のクロージャだと spy しづらい)。
+   */
+  _onOpen() {
+    this.backoff = MIN_BACKOFF_MS
+    this.logger?.info("ws open")
+    // hello 前に最新の bundle version を読み直す (再接続時の鮮度確保)
+    this._refreshBundleVersion()
+    this._sendJson({
+      type: "hello",
+      agent_id: this.config.agent_id,
+      hostname: this.hostname,
+      version: this.version,
+      bundle_version: this.bundleVersion,
+    })
+    // Plan ε: 毎回 reconnect 直後に backend ↔ agent の stream_id を能動同期する
+    // (orphan stream の即時 kill 用)。response は main.mjs の dispatch が拾い、
+    // ptyBridge.list() と差分を取って kill する。request_id は uuid で
+    // 重複排除。backend が古い (= Plan ε 未対応) なら "unknown_type" error が
+    // 返るだけで動作には影響しない。
+    this._sendJson({
+      type: "agent.streams.sync.request",
+      request_id: randomUUID(),
+    })
+    this._startHeartbeat()
+    this._startBundleWatcher()
+    this.emit("open")
+  }
+
   /** メッセージを送る。未接続なら no-op (logger.warn)。 */
   send(obj) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {