@cocorograph/hub-agent 0.7.69 → 0.7.71

package/package.json

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

package/src/codex-stream-bridge.mjs

@@ -11,6 +11,7 @@
  *   claude.input              → input()    (turn/start、ターン中は turn/steer)
  *   claude.interrupt          → interrupt() (turn/interrupt)
  *   claude.detach              → detach()   (TTL 付き graceful close)
+ *   (codex 固有)               → keepalive() (閲覧中の生存シグナル。pty.resize 相当)
  *   claude.permission.reply    → permissionReply() (client.respond/respondError)
  *   claude.event (生 SDK イベント素通し) → 'event' (生 notification 素通し、同じ思想)
  *   claude.permission.request  → 'permission' (承認/入力要求の生 method+params 素通し)
@@ -509,6 +510,26 @@ export class CodexStreamBridge extends EventEmitter {
     session.client.respond(request_id, result)
   }
 
+  /**
+   * ブラウザ閲覧中の生存シグナル (codex.keepalive)。frontend が Codex チャットを開いて
+   * いる間だけ定期送信するため、これが届く = 「人が見ている」の観測可能な証跡になる。
+   * gcAbandonedSessions は lastActivityMs しか見ないので、touch するだけで
+   * 「開いたまま無入力でも 1h で殺される」ギャップが閉じる (TTL の数字を増やす必要は無い)。
+   *
+   * ⚠️ 意図的に `_cancelIdleReap` を **呼ばない**。detach 済みセッションの 5 分 TTL は
+   * 「ブラウザが去った」という別事実に基づく予約であり、detach と in-flight keepalive が
+   * 競合しても予約を解除しない (= 明示 detach は必ず 5 分で回収される) 方が意味論が明快。
+   * 閲覧を再開したブラウザは必ず attach を送り直すので、再養子はそちらの経路で足りる。
+   *
+   * @returns {boolean} 生きているセッションを touch できたら true (未知 stream は false)。
+   */
+  keepalive({ stream_id }) {
+    const session = this.sessions.get(stream_id)
+    if (!session || session.dead) return false
+    this._touch(session)
+    return true
+  }
+
   /**
    * グレースフル切断。ターン実行中は完走を待ち、非 busy ならアイドル TTL 後に
    * プロセスを reap する (claude-stream-bridge.mjs の softDetach と同じ思想。
@@ -744,17 +765,17 @@ export class CodexStreamBridge extends EventEmitter {
    * 進行中の正常なターンは app-server 通知で都度 touch されるので回収されない。
    * main.mjs の state loop から claudeBridge.gcDeadTerminals と並べて定期実行する想定。
    *
-   * ⚠️ 既知のギャップ (2026-07-17、次段の keepalive PR で解消予定): この reaper は
-   * `detachRequested` を参照せず、`_touch()` は input() と app-server 通知でしか呼ばれない。
-   * そのため **ブラウザで Codex チャットを開いたままでも、1 時間まったく入力も生成も
-   * 無ければ回収される**。アイドル TTL(5 分) の誤爆を直しても、この 1h が次の上限になる。
-   * TTL の数字を大きくするのではなく「見ている」を観測可能にするのが正しい解:
-   * frontend/components/cockpit/CockpitTerminal.tsx の PTY keepalive (閲覧中は定期的に
-   * pty.resize で lastSeenAt を触り、ブラウザが離れれば keepalive も止まるので orphan GC が
-   * 正しく効く) と同じ構造を codex チャットへ移植する (codex.keepalive を新設し、backend
-   * consumers.py の中継テーブルと main.mjs の dispatch をセットで変更する)。そうすれば
-   * 「ブラウザ開 = 無期限 / 明示 detach = 5 分 / ブラウザ落ち = 1h reaper」になり、
-   * 「N 時間放置しても生きていてほしい」という数字合わせ自体が不要になる。
+   * この reaper は `detachRequested` を **意図的に参照しない**。detach を送れずに消えた
+   * ブラウザ (タブごとクラッシュ / 端末スリープ) は detachRequested が立たないまま残るため、
+   * ここでフラグを見ると回収不能になりリークする。「無通信が続いた事実」だけで回収する。
+   *
+   * 閲覧中の誤爆は keepalive で防ぐ (2026-07-17 に解消。旧: 開いたままでも 1h 無入力で
+   * 回収されていた)。frontend は Codex チャットを開いている間 codex.keepalive を定期送信し、
+   * keepalive() が lastActivityMs を touch する。ブラウザが閉じれば keepalive も止まるので
+   * この reaper は本来の orphan GC として正しく効く。CockpitTerminal.tsx の PTY keepalive
+   * (pty.resize で lastSeenAt を触る) と同じ構造。結果として TTL の意味は
+   * 「ブラウザ開 = 無期限 / 明示 detach = 5 分 / ブラウザ落ち = 1h reaper」に整理され、
+   * 「N 時間放置しても生きていてほしい」という数字合わせ自体が不要になった。
    *
    * @param {number} [ttlMs] 無通信とみなす閾値 (テスト用に上書き可)。
    * @returns {number} 回収したセッション数。

package/src/config.mjs

@@ -10,6 +10,7 @@
 import { promises as fs, constants as fsConsts, readFileSync } from "node:fs"
 import path from "node:path"
 import os from "node:os"
+import { randomUUID } from "node:crypto"
 import { execFile, execFileSync } from "node:child_process"
 import { promisify } from "node:util"
 
@@ -90,6 +91,9 @@ function resolveConfigDir() {
   return path.join(os.homedir(), ".hub")
 }
 
+/** canonical UUID (v4 想定だが版は問わない)。host_key の契約。 */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
 export const paths = {
   get configDir() {
     return resolveConfigDir()
@@ -97,11 +101,111 @@ export const paths = {
   get configFile() {
     return path.join(resolveConfigDir(), "agent.json")
   },
+  get hostKeyFile() {
+    return path.join(resolveConfigDir(), "host_key")
+  },
   get pluginsDir() {
     return path.join(resolveConfigDir(), "plugins")
   },
 }
 
+/**
+ * このインストール (物理ホスト) の不変な識別子を返す (無ければ生成して永続化)。
+ *
+ * ## なぜ必要か (2026-07-17)
+ *
+ * Hub 側に「このワークスペースで今どの会話 (claude=session_id / codex=thread_id) を
+ * 開くか」を保存するにあたり、**その会話がどのホストのファイルシステムに存在するか**
+ * を指す必要がある。ところが Hub には物理ホストの安定した ID が無かった:
+ *
+ * - `CockpitAgent`(agent_id) = **credential のレコード**。再 enroll のたびに revoke /
+ *   再作成される (= ホストの同一性を表さない)
+ * - `hostname` = **表示用の属性**。Hub の PATCH API で変更でき、OS rename でも変わり、
+ *   別の物理端末が同名を名乗れる (= 一意でも不変でもない)
+ *
+ * そこで install 単位の opaque UUID をここで生成し、enroll 時に Hub へ送る。
+ *
+ * ## なぜ agent.json ではなく専用ファイルなのか
+ *
+ * `writeConfig()` は **agent.json を全置換**し、`clearConfig()` は **削除**する。
+ * host_key を agent.json に入れると credential のライフサイクルに巻き込まれ、
+ * 再 enroll / unenroll で消える = 「credential から独立した ID」という目的を
+ * 自ら壊す。別ファイルにして、credential の rotate と完全に分離する。
+ *
+ * ## 並行安全 (2026-07-17, Codex レビュー指摘)
+ *
+ * read → ENOENT → write の check-then-create は非原子的で、同じ config dir で 2 つの
+ * プロセスが初回起動すると **別々の UUID を生成して互いに上書きし得る** (片方が A を
+ * Hub へ送ったのに最終ファイルは B になり、次回起動で B を送る = identity が変わる)。
+ * 「install 単位で不変」を生成関数自身が保証できない。
+ *
+ * ⚠️ 単純な `flag: "wx"` でも不十分だった (2026-07-17、Codex レビュー 6 巡目):
+ * wx は **open の排他性**しか保証せず、勝者が open → write → close する間に、
+ * EEXIST を受けた敗者が**空 / 書きかけのファイルを読む窓**が残る (その起動だけ
+ * host_key の解決に失敗し、ポインタ機能が無効化される)。
+ *
+ * そこで **temp file へ完成品を書いてから `link()` で公開**する:
+ * link(2) は「リンク先が既に存在すれば EEXIST」で原子的なので、**排他性と
+ * 「公開されたファイルは常に完成済み」の両方**が同時に満たされる。敗者は勝者の
+ * 完成済みファイルを読むだけでよい。
+ *
+ * @param {{ randomUUIDImpl?: () => string, onBeforePublish?: () => Promise<void> }} [opts]
+ *   テスト用の注入口 (onBeforePublish は publish 直前に割り込んで競合窓を再現する)
+ * @returns {Promise<string>} 既存の値、または新規生成した UUID
+ */
+export async function getOrCreateHostKey(opts = {}) {
+  const existing = await _readHostKey()
+  if (existing) return existing
+
+  await ensureConfigDir()
+  const uuid = (opts.randomUUIDImpl || randomUUID)()
+  // 一意な temp 名 (同一 dir。link は同一 FS でしか張れないため)。
+  const tmp = `${paths.hostKeyFile}.${process.pid}.${randomUUID()}.tmp`
+  try {
+    // 0o600 は秘密だからではなく、書き換えられると別ホストになりすませるため。
+    await fs.writeFile(tmp, `${uuid}\n`, { mode: 0o600 })
+    if (opts.onBeforePublish) await opts.onBeforePublish()
+    try {
+      // 原子的 publish: 既にあれば EEXIST (= 競合の敗者)。
+      await fs.link(tmp, paths.hostKeyFile)
+      return uuid
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err
+      // 敗者: 勝者が publish したのは **完成済み**のファイルなので、そのまま読める。
+      const winner = await _readHostKey()
+      if (!winner) {
+        throw new Error("host_key の生成が競合し、勝者の値も読めませんでした")
+      }
+      return winner
+    }
+  } finally {
+    await fs.unlink(tmp).catch(() => {})
+  }
+}
+
+/** host_key ファイルを読む。無ければ null。中身が UUID でなければ throw。 */
+async function _readHostKey() {
+  let raw
+  try {
+    raw = await fs.readFile(paths.hostKeyFile, "utf-8")
+  } catch (err) {
+    if (err.code === "ENOENT") return null
+    throw err
+  }
+  const value = raw.trim()
+  if (!value) return null
+  if (!UUID_RE.test(value)) {
+    // ⚠️ 黙って新しい値へ rotate しない: identity が静かに変わると、Hub 側の
+    // 「今どの会話を開くか」が別ホスト扱いで引けなくなり、原因も追えない
+    // (Codex レビュー指摘、2026-07-17)。壊れているなら明示的に落とす。
+    throw new Error(
+      `${paths.hostKeyFile} の内容が UUID ではありません (${value.slice(0, 16)}...)。` +
+        "手動で修復するか、ファイルを削除して再生成してください。",
+    )
+  }
+  return value
+}
+
 /** ~/.hub を作成する (chmod 700)。 */
 export async function ensureConfigDir() {
   await fs.mkdir(paths.configDir, { recursive: true, mode: 0o700 })

package/src/enroll.mjs

@@ -8,7 +8,13 @@
  */
 import os from "node:os"
 
-import { detectAvailableClis, detectPlatform, hasConfig, writeConfig } from "./config.mjs"
+import {
+  detectAvailableClis,
+  detectPlatform,
+  getOrCreateHostKey,
+  hasConfig,
+  writeConfig,
+} from "./config.mjs"
 
 const DEFAULT_HUB_URL = process.env.HUB_URL || "https://hub.cocorograph.com"
 
@@ -35,6 +41,11 @@ export async function enroll(enrollmentToken, opts = {}) {
   }
 
   const availableClis = await detectAvailableClis()
+  // このインストール (物理ホスト) の不変な ID。credential (agent_id) と違い、
+  // 再 enroll しても同じ値を送り続けるため、Hub 側は「同じホスト」だと分かる。
+  // Hub の「今どの会話を開くか」ポインタがこれをキーにする (config.mjs の
+  // getOrCreateHostKey の docstring 参照)。
+  const hostKey = await getOrCreateHostKey()
 
   const res = await fetchImpl(`${hubUrl}/api/cockpit/agents/enroll-complete/`, {
     method: "POST",
@@ -42,6 +53,7 @@ export async function enroll(enrollmentToken, opts = {}) {
     body: JSON.stringify({
       enrollment_token: enrollmentToken,
       hostname,
+      host_key: hostKey,
       version,
       platform: detectPlatform(),
       available_clis: availableClis,

package/src/main.mjs

@@ -19,7 +19,13 @@ import path from "node:path"
 
 import pino from "pino"
 
-import { detectAvailableClis, detectPlatform, readConfig, writeConfig } from "./config.mjs"
+import {
+  detectAvailableClis,
+  detectPlatform,
+  getOrCreateHostKey,
+  readConfig,
+  writeConfig,
+} from "./config.mjs"
 import {
   codexTerminalSkipVersion,
   compareBundleVersions,
@@ -775,9 +781,25 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
     }
   }
 
+  // 物理ホストの不変 ID。**全起動が通るこの経路で解決**し hello に載せる
+  // (enroll 専用にすると既存端末が更新しても Hub に届かない。config.mjs の
+  // getOrCreateHostKey docstring 参照)。読めない/壊れている場合は fail-soft:
+  // 空文字で続行し、Hub 側はポインタ機能だけを無効化する (agent は通常どおり動く)。
+  let hostKey = ""
+  try {
+    hostKey = await getOrCreateHostKey()
+    logger.info({ host_key: hostKey }, "host key resolved")
+  } catch (err) {
+    logger.warn(
+      { err: err.message },
+      "host key の解決に失敗 (会話ポインタ機能のみ無効化。agent は通常どおり動作)",
+    )
+  }
+
   const client = new WsClient(config, {
     logger,
     version,
+    hostKey,
     platform: detectPlatform(),
     availableClis,
     bundleVersion,
@@ -4335,6 +4357,13 @@ async function dispatch(msg, ctx) {
         if (!ctx.codexBridge) return
         ctx.codexBridge.detach({ stream_id: msg.stream_id })
         return
+      case "codex.keepalive":
+        // ブラウザが Codex チャットを開いている間の生存シグナル (CockpitTerminal.tsx の
+        // PTY keepalive と同じ構造)。閲覧中に gcAbandonedSessions (既定 1h 無通信) が
+        // 誤爆するのを防ぐ。未知 stream_id は false が返るだけ (無害な no-op)。
+        if (!ctx.codexBridge) return
+        ctx.codexBridge.keepalive({ stream_id: msg.stream_id })
+        return
       case "codex.sessions.request": {
         // cwd 配下の Codex thread 一覧を返す (claude.sessions.request と対称。
         // Cockpit のセッションピッカー/最新セッション自動選択用)。

package/src/ws-client.mjs

@@ -114,6 +114,11 @@ export class WsClient extends EventEmitter {
     this.config = config
     this.logger = opts.logger
     this.version = opts.version || "0.1.0"
+    // このインストール (物理ホスト) の不変 ID。**enroll だけでなく毎起動の hello で送る**:
+    // 既に enroll 済みの端末は更新後も enroll-complete を通らないため、enroll 専用に
+    // すると「更新しても host_key が Hub に届かず機能が永久に無効」になる
+    // (Codex レビュー指摘、2026-07-17)。backend は hello で空の host_key を backfill する。
+    this.hostKey = opts.hostKey || ""
     this.bundleVersion = opts.bundleVersion || null
     this.bundleVersionProvider =
       typeof opts.bundleVersionProvider === "function"
@@ -243,6 +248,7 @@ export class WsClient extends EventEmitter {
       type: "hello",
       agent_id: this.config.agent_id,
       hostname: this.hostname,
+      host_key: this.hostKey,
       version: this.version,
       bundle_version: this.bundleVersion,
       platform: this.platform,