@cocorograph/hub-agent 0.4.1

package/src/tmux.mjs

@@ -0,0 +1,181 @@
+/**
+ * tmux サブプロセス呼び出し抽象 (Sprint E)。
+ *
+ * - `execTmux(args)`: raw 実行 (stdout / stderr / exit_code を返す)
+ * - `listSessions()`: 構造化された TmuxSession[] を返す。各 session に
+ *   status (state.mjs の detectSessionState) と cwd (active pane の current_path)
+ *   を並列で付与
+ * - `createSession(name, cwd, opts)`: detached new-session + CLAUDE_CMD を
+ *   send-keys。既存ならエラー throw
+ * - `killSession(name)`: 1 session を kill。存在しない場合は 'session not found' throw
+ * - `killManySessions(names)`: 複数 kill、存在しないものは無視
+ *
+ * 移植元: D00000_cockpit/webapp/lib/tmux.ts
+ * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
+ */
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+
+import { detectSessionState } from "./state.mjs"
+
+const execFileP = promisify(execFile)
+
+const DEFAULT_TMUX_BIN = "tmux"
+const DEFAULT_CLAUDE_CMD =
+  process.env.HUB_CLAUDE_CMD ||
+  "claude --continue --model claude-opus-4-7 --permission-mode auto || claude --model claude-opus-4-7 --permission-mode auto"
+
+function tmuxBin(opts = {}) {
+  return opts.tmuxBin || DEFAULT_TMUX_BIN
+}
+
+/**
+ * 汎用 tmux 実行。`tmux.exec` メッセージから呼び出される。
+ *
+ * @returns {Promise<{stdout: string, stderr: string, exit_code: number}>}
+ */
+export async function execTmux(args, opts = {}) {
+  if (!Array.isArray(args)) throw new TypeError("execTmux requires args: string[]")
+  try {
+    const { stdout, stderr } = await execFileP(tmuxBin(opts), args, {
+      env: opts.env || process.env,
+      maxBuffer: 4 * 1024 * 1024,
+    })
+    return { stdout, stderr, exit_code: 0 }
+  } catch (err) {
+    return {
+      stdout: err.stdout || "",
+      stderr: err.stderr || err.message || "",
+      exit_code: typeof err.code === "number" ? err.code : 1,
+    }
+  }
+}
+
+async function getSessionCwd(name, opts = {}) {
+  try {
+    const { stdout } = await execFileP(tmuxBin(opts), [
+      "display-message",
+      "-p",
+      "-t",
+      `${name}:`,
+      "-F",
+      "#{pane_current_path}",
+    ])
+    const s = stdout.trim()
+    return s || null
+  } catch {
+    return null
+  }
+}
+
+const TMUX_LIST_FIELDS = [
+  "#{session_name}",
+  "#{session_windows}",
+  "#{session_created}",
+  "#{session_attached}",
+  "#{session_activity}",
+  "#{session_last_attached}",
+].join("\t")
+
+export async function listSessions(opts = {}) {
+  let stdout = ""
+  try {
+    const r = await execFileP(tmuxBin(opts), [
+      "list-sessions",
+      "-F",
+      TMUX_LIST_FIELDS,
+    ])
+    stdout = r.stdout
+  } catch (err) {
+    const msg = err?.message || String(err)
+    if (msg.includes("no server running") || msg.includes("no current session")) {
+      return []
+    }
+    throw err
+  }
+
+  const base = stdout
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const [name, windows, created, attached, activity, lastAttached] = line.split("\t")
+      return {
+        name,
+        windows: Number(windows),
+        created: Number(created),
+        attached: attached !== "0",
+        activity: Number(activity) || 0,
+        lastAttached: Number(lastAttached) || 0,
+      }
+    })
+
+  // state + cwd を並列付与
+  return Promise.all(
+    base.map(async (s) => {
+      const [state, cwd] = await Promise.all([
+        detectSessionState(s.name, opts),
+        getSessionCwd(s.name, opts),
+      ])
+      return {
+        ...s,
+        status: state.status,
+        context_pct: state.context_pct,
+        cwd,
+      }
+    }),
+  )
+}
+
+export async function killSession(name, opts = {}) {
+  try {
+    await execFileP(tmuxBin(opts), ["kill-session", "-t", name])
+  } catch (err) {
+    const msg = err?.message || String(err)
+    if (
+      msg.includes("can't find session") ||
+      msg.includes("no current session") ||
+      msg.includes("no server running")
+    ) {
+      throw new Error("session not found")
+    }
+    throw err
+  }
+}
+
+export async function killManySessions(names, opts = {}) {
+  const killed = []
+  const failed = []
+  for (const n of names) {
+    try {
+      await killSession(n, opts)
+      killed.push(n)
+    } catch (err) {
+      const msg = err?.message || String(err)
+      if (msg === "session not found") continue
+      failed.push({ name: n, reason: msg })
+    }
+  }
+  return { killed, failed }
+}
+
+/**
+ * 新規 session を detached で作成して claude を起動する。
+ * - 同名 session が既にあれば 'duplicate session' throw
+ * - opts.claudeCmd で send-keys 内容を上書き可 (空文字なら claude 自動起動しない)
+ */
+export async function createSession(name, cwd, opts = {}) {
+  // 既存チェック
+  try {
+    await execFileP(tmuxBin(opts), ["has-session", "-t", name])
+    throw new Error("duplicate session")
+  } catch (err) {
+    const msg = err?.message || String(err)
+    if (msg === "duplicate session") throw err
+    // has-session が非 0 = セッション無し
+  }
+  await execFileP(tmuxBin(opts), ["new-session", "-d", "-s", name, "-c", cwd])
+  const claudeCmd = opts.claudeCmd ?? DEFAULT_CLAUDE_CMD
+  if (claudeCmd) {
+    await execFileP(tmuxBin(opts), ["send-keys", "-t", name, claudeCmd, "Enter"])
+  }
+}

package/src/usage.mjs

@@ -0,0 +1,288 @@
+/**
+ * Claude Code の usage 集計 (Sprint H part 3)。
+ *
+ * 優先順位:
+ *   1. `~/.hub/usage/latest.json` (Claude statusLine 2.1.80+ の公式値)
+ *   2. `~/.claude/projects/<proj>/<uuid>.jsonl` の `assistant.message.usage`
+ *      を 5h / 7d で集計したフォールバック (推定値)
+ *
+ * 環境変数で override:
+ *   - HUB_USAGE_CACHE          : statusLine cache のパス
+ *   - HUB_USAGE_SESSIONS_DIR   : session 別 statusLine ディレクトリ
+ *   - HUB_CLAUDE_PROJECTS_DIR  : ~/.claude/projects のパス差し替え
+ *   - HUB_PLAN                 : pro / max_5x / max_20x (default max_5x)
+ *   - HUB_LIMIT_5H / HUB_LIMIT_7D : limit 上書き
+ *
+ * 移植元: D00000_cockpit/webapp/lib/usage.ts
+ * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
+ */
+import { promises as fs } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+function configPath(envKey, ...fallback) {
+  return process.env[envKey] || path.join(...fallback)
+}
+
+function projectsDir() {
+  return configPath(
+    "HUB_CLAUDE_PROJECTS_DIR",
+    os.homedir(),
+    ".claude",
+    "projects",
+  )
+}
+
+function statuslineCache() {
+  return configPath(
+    "HUB_USAGE_CACHE",
+    os.homedir(),
+    ".hub",
+    "usage",
+    "latest.json",
+  )
+}
+
+function statuslineSessionsDir() {
+  return configPath(
+    "HUB_USAGE_SESSIONS_DIR",
+    os.homedir(),
+    ".hub",
+    "usage",
+    "sessions",
+  )
+}
+
+const SESSION_STALE_MS = 15 * 60 * 1000
+
+const PLAN_LIMITS = {
+  pro: { msg5h: 45, msg7d: 315 },
+  max_5x: { msg5h: 280, msg7d: 1960 },
+  max_20x: { msg5h: 1120, msg7d: 7840 },
+}
+
+function planLimits() {
+  const key = process.env.HUB_PLAN || "max_5x"
+  const base = PLAN_LIMITS[key] || PLAN_LIMITS.max_5x
+  return {
+    plan: key,
+    limit5h: Number(process.env.HUB_LIMIT_5H) || base.msg5h,
+    limit7d: Number(process.env.HUB_LIMIT_7D) || base.msg7d,
+  }
+}
+
+function emptyBucket(limit) {
+  return {
+    tokens: 0,
+    messages: 0,
+    limit,
+    percent: 0,
+    oldestTsMs: null,
+    resetAtMs: null,
+  }
+}
+
+function emptyStats(planKey, limit5h, limit7d, now) {
+  return {
+    plan: planKey,
+    computedAt: now,
+    source: "estimate",
+    context: null,
+    last5h: emptyBucket(limit5h),
+    last7d: emptyBucket(limit7d),
+  }
+}
+
+async function readOrNull(p) {
+  try {
+    return await fs.readFile(p, "utf-8")
+  } catch {
+    return null
+  }
+}
+
+async function readOfficial(now) {
+  const text = await readOrNull(statuslineCache())
+  if (!text) return null
+  let j
+  try {
+    j = JSON.parse(text)
+  } catch {
+    return null
+  }
+  const rl = j.rate_limits ?? j.rateLimits ?? {}
+  const five = rl.five_hour ?? rl.fiveHour ?? rl["5h"]
+  const seven = rl.seven_day ?? rl.sevenDay ?? rl["7d"]
+  if (!five && !seven) return null
+  const ctx = j.context_window?.used_percentage ?? j.contextWindow?.used_percentage ?? null
+
+  const bucketize = (b, defaultLimit) => {
+    if (!b) return { ...emptyBucket(defaultLimit), limit: defaultLimit }
+    const percent = typeof b.used_percentage === "number" ? b.used_percentage : 0
+    let resetMs = null
+    if (typeof b.resets_at === "number") {
+      resetMs = b.resets_at < 1e12 ? b.resets_at * 1000 : b.resets_at
+    } else if (typeof b.resets_at === "string") {
+      const t = Date.parse(b.resets_at)
+      if (!Number.isNaN(t)) resetMs = t
+    }
+    return {
+      tokens: 0,
+      messages: 0,
+      limit: b.limit ?? defaultLimit,
+      percent,
+      oldestTsMs: null,
+      resetAtMs: resetMs,
+    }
+  }
+
+  return {
+    plan: j.plan || "official",
+    computedAt: now,
+    source: "official",
+    context: typeof ctx === "number" ? ctx : null,
+    last5h: bucketize(five, 100),
+    last7d: bucketize(seven, 100),
+  }
+}
+
+async function readEstimate(now) {
+  const { plan, limit5h, limit7d } = planLimits()
+  const projects = await fs.readdir(projectsDir()).catch(() => null)
+  if (!projects) return emptyStats(plan, limit5h, limit7d, now)
+
+  const t5h = now - 5 * 60 * 60 * 1000
+  const t7d = now - 7 * 24 * 60 * 60 * 1000
+  const WIN_5H = 5 * 60 * 60 * 1000
+  const WIN_7D = 7 * 24 * 60 * 60 * 1000
+
+  let tokens5h = 0
+  let msgs5h = 0
+  let tokens7d = 0
+  let msgs7d = 0
+  let oldest5h = null
+  let oldest7d = null
+
+  await Promise.all(
+    projects.map(async (p) => {
+      const dir = path.join(projectsDir(), p)
+      const files = await fs.readdir(dir).catch(() => [])
+      for (const f of files) {
+        if (!f.endsWith(".jsonl")) continue
+        const fp = path.join(dir, f)
+        try {
+          const st = await fs.stat(fp)
+          if (st.mtimeMs < t7d) continue
+        } catch {
+          continue
+        }
+        const text = await readOrNull(fp)
+        if (!text) continue
+        for (const line of text.split("\n")) {
+          if (!line || line.length < 50) continue
+          if (!line.includes('"usage"')) continue
+          let d
+          try {
+            d = JSON.parse(line)
+          } catch {
+            continue
+          }
+          if (d.type !== "assistant") continue
+          const ts = d.timestamp ? Date.parse(d.timestamp) : 0
+          if (!ts || ts < t7d) continue
+          const u = d.message?.usage
+          if (!u) continue
+          const tok = (u.output_tokens || 0) + (u.input_tokens || 0)
+          tokens7d += tok
+          msgs7d += 1
+          if (oldest7d === null || ts < oldest7d) oldest7d = ts
+          if (ts >= t5h) {
+            tokens5h += tok
+            msgs5h += 1
+            if (oldest5h === null || ts < oldest5h) oldest5h = ts
+          }
+        }
+      }
+    }),
+  )
+
+  return {
+    plan,
+    computedAt: Date.now(),
+    source: "estimate",
+    context: null,
+    last5h: {
+      tokens: tokens5h,
+      messages: msgs5h,
+      limit: limit5h,
+      percent: limit5h > 0 ? Math.round((msgs5h / limit5h) * 1000) / 10 : 0,
+      oldestTsMs: oldest5h,
+      resetAtMs: oldest5h !== null ? oldest5h + WIN_5H : null,
+    },
+    last7d: {
+      tokens: tokens7d,
+      messages: msgs7d,
+      limit: limit7d,
+      percent: limit7d > 0 ? Math.round((msgs7d / limit7d) * 1000) / 10 : 0,
+      oldestTsMs: oldest7d,
+      resetAtMs: oldest7d !== null ? oldest7d + WIN_7D : null,
+    },
+  }
+}
+
+/**
+ * 5h / 7d 集計の UsageStats を返す。statusLine が無い環境では transcript
+ * から推定する。
+ */
+export async function getUsage() {
+  const now = Date.now()
+  const official = await readOfficial(now)
+  if (official) return official
+  return readEstimate(now)
+}
+
+/**
+ * statusLine が session_id 単位で残した JSON を読み、生きているものだけ返す。
+ * cwd と context_percent を返す。フロントで「この tmux session で動いている
+ * Claude のコンテキスト残量」表示に使う。
+ */
+export async function getSessionUsages() {
+  const now = Date.now()
+  const files = await fs.readdir(statuslineSessionsDir()).catch(() => null)
+  if (!files) return []
+  const out = []
+  await Promise.all(
+    files.map(async (f) => {
+      if (!f.endsWith(".json")) return
+      const fp = path.join(statuslineSessionsDir(), f)
+      let mtime = 0
+      try {
+        const st = await fs.stat(fp)
+        mtime = st.mtimeMs
+        if (now - mtime > SESSION_STALE_MS) return
+      } catch {
+        return
+      }
+      const text = await readOrNull(fp)
+      if (!text) return
+      let j
+      try {
+        j = JSON.parse(text)
+      } catch {
+        return
+      }
+      const ctx = j.context_window?.used_percentage ?? j.contextWindow?.used_percentage
+      const cwd =
+        j.workspace?.project_dir || j.workspace?.current_dir || j.cwd
+      const sid = j.session_id
+      if (typeof ctx !== "number" || !cwd || !sid) return
+      out.push({
+        sessionId: sid,
+        cwd,
+        contextPercent: ctx,
+        updatedAtMs: mtime,
+      })
+    }),
+  )
+  return out
+}

package/src/ws-client.mjs

@@ -0,0 +1,194 @@
+/**
+ * Hub の `/ws/cockpit/agent/` への outbound WSS クライアント。
+ *
+ * - 接続: `Authorization: Bearer <agent_id>:<agent_token>`
+ * - 起動時に `hello`、30s おきに `heartbeat` を送信
+ * - 切断時は exponential backoff (1s, 2s, 4s, ..., max 30s) で再接続
+ * - サーバから受け取った JSON は `onMessage` callback に渡す
+ *
+ * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
+ */
+import { EventEmitter } from "node:events"
+import os from "node:os"
+
+import WebSocket from "ws"
+
+const HEARTBEAT_INTERVAL_MS = 30_000
+const MIN_BACKOFF_MS = 1_000
+const MAX_BACKOFF_MS = 30_000
+
+export class WsClient extends EventEmitter {
+  /**
+   * @param {{ hub_url: string, agent_id: string, agent_token: string }} config
+   * @param {{ logger?: import('pino').Logger, version?: string }} opts
+   */
+  constructor(config, opts = {}) {
+    super()
+    this.config = config
+    this.logger = opts.logger
+    this.version = opts.version || "0.1.0"
+    this.hostname = opts.hostname || os.hostname()
+    this.ws = null
+    this.heartbeatTimer = null
+    this.reconnectTimer = null
+    this.backoff = MIN_BACKOFF_MS
+    this.stopped = false
+    this.startedAt = Date.now()
+  }
+
+  /** WSS 接続を開始する。`stop()` まで自動で reconnect 続行。 */
+  connect() {
+    if (this.stopped) return
+    const wsUrl = this._buildWsUrl()
+    this.logger?.info({ wsUrl }, "ws connecting")
+
+    const headers = {
+      Authorization: `Bearer ${this.config.agent_id}:${this.config.agent_token}`,
+    }
+    const ws = new WebSocket(wsUrl, { headers })
+    this.ws = ws
+
+    ws.on("open", () => {
+      this.backoff = MIN_BACKOFF_MS
+      this.logger?.info("ws open")
+      this._sendJson({
+        type: "hello",
+        agent_id: this.config.agent_id,
+        hostname: this.hostname,
+        version: this.version,
+      })
+      this._startHeartbeat()
+      this.emit("open")
+    })
+
+    ws.on("message", (data) => {
+      let msg
+      try {
+        msg = JSON.parse(data.toString("utf-8"))
+      } catch (err) {
+        this.logger?.warn({ err: err.message }, "ws json parse failed")
+        return
+      }
+      this.emit("message", msg)
+    })
+
+    ws.on("close", (code, reason) => {
+      this._stopHeartbeat()
+      this.logger?.info({ code, reason: reason?.toString() }, "ws close")
+      this.emit("close", { code, reason })
+      if (!this.stopped) this._scheduleReconnect()
+    })
+
+    ws.on("error", (err) => {
+      this.logger?.warn({ err: err.message }, "ws error")
+      this.emit("error", err)
+      // close もほぼ続けて飛ぶので reconnect 予約は close 側に任せる
+    })
+  }
+
+  /** メッセージを送る。未接続なら no-op (logger.warn)。 */
+  send(obj) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      this.logger?.warn({ type: obj?.type }, "ws send skipped (not open)")
+      return false
+    }
+    return this._sendJson(obj)
+  }
+
+  /** Reconnect を止めて切断する。 */
+  stop() {
+    this.stopped = true
+    this._stopHeartbeat()
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+    if (this.ws) {
+      try {
+        this.ws.close(1000, "client_stop")
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  // ------------------------------------------------------------
+  // internals
+  // ------------------------------------------------------------
+
+  _buildWsUrl() {
+    const hub = this.config.hub_url.replace(/\/+$/, "")
+    const scheme = hub.startsWith("https:") ? "wss:" : "ws:"
+    const host = hub.replace(/^https?:\/\//, "")
+    return `${scheme}//${host}/ws/cockpit/agent/`
+  }
+
+  _sendJson(obj) {
+    try {
+      this.ws.send(JSON.stringify(obj))
+      return true
+    } catch (err) {
+      this.logger?.warn({ err: err.message }, "ws send failed")
+      return false
+    }
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat()
+    this.heartbeatTimer = setInterval(() => {
+      // 送信失敗 (= ws not OPEN) を検知したら即時 close + reconnect 発火。
+      // setInterval を放置すると死んだコネクションに heartbeat を投げ続けて
+      // 30s 間気付かないので、close を強制トリガーする。
+      const ok = this._sendJson({
+        type: "heartbeat",
+        uptime_sec: Math.floor((Date.now() - this.startedAt) / 1000),
+      })
+      if (!ok) {
+        this.logger?.warn("heartbeat send failed, forcing reconnect")
+        this._forceReconnect()
+      }
+    }, HEARTBEAT_INTERVAL_MS)
+    // unref して node プロセスが timer 1 個で抜けられなくならないように
+    this.heartbeatTimer.unref?.()
+  }
+
+  _stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
+  }
+
+  _forceReconnect() {
+    // 現在の ws を強制 close。close ハンドラが _scheduleReconnect を呼ぶので
+    // それ以上の処理は不要。stopped 中は no-op。
+    // ws 実装によって terminate (ws npm package) と close (browser WebSocket
+    // 互換) どちらが生えているか異なるので両対応する。
+    if (this.stopped) return
+    if (!this.ws) return
+    if (this.ws.readyState === WebSocket.CLOSED) return
+    try {
+      if (typeof this.ws.terminate === "function") {
+        this.ws.terminate()
+      } else if (typeof this.ws.close === "function") {
+        this.ws.close(1006, "heartbeat_failed")
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  _scheduleReconnect() {
+    // exponential backoff + ±20% jitter で同時接続が同期しないようにする。
+    const base = this.backoff
+    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")
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.connect()
+    }, delay)
+    this.reconnectTimer.unref?.()
+  }
+}

package/templates/co.cocorograph.hub-agent.plist

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>co.cocorograph.hub-agent</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>__HUB_AGENT_BIN__</string>
+    <string>start</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+    <key>NetworkState</key>
+    <true/>
+  </dict>
+
+  <key>StandardOutPath</key>
+  <string>__HOME__/.hub/agent.log</string>
+  <key>StandardErrorPath</key>
+  <string>__HOME__/.hub/agent.log</string>
+
+  <key>WorkingDirectory</key>
+  <string>__HOME__</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>__PATH__</string>
+    <key>HOME</key>
+    <string>__HOME__</string>
+  </dict>
+
+  <!-- KeepAlive で過剰再起動した時に 10 秒スロットルする -->
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+</dict>
+</plist>