@cocorograph/hub-agent 0.4.1

package/src/main.mjs

@@ -0,0 +1,362 @@
+/**
+ * hub-agent daemon 本体。
+ *
+ * - 設定読み込み (~/.hub/agent.json) → WsClient 起動
+ * - plugin discovery + onAgentStart broadcast
+ * - WS メッセージのディスパッチ:
+ *   - pty.attach / pty.data / pty.resize / pty.detach → PtyBridge
+ *   - pty 出力 → WsClient で type=pty.data として送信
+ *   - tmux.exec は Sprint E で tmux module に渡す
+ *
+ * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
+ */
+import pino from "pino"
+
+import { readConfig } from "./config.mjs"
+import { loadPlugins, runHookBroadcast, runHookChain } from "./plugin-loader.mjs"
+import { WsClient } from "./ws-client.mjs"
+import { PtyBridge } from "./pty-bridge.mjs"
+import { listSkills } from "./skills.mjs"
+import { listSessionStates } from "./state.mjs"
+import {
+  createSession as createTmuxSession,
+  execTmux,
+  killManySessions,
+  killSession as killTmuxSession,
+  listSessions as listTmuxSessions,
+} from "./tmux.mjs"
+import { getSessionUsages, getUsage } from "./usage.mjs"
+
+const logger = pino({ name: "hub-agent" })
+
+export async function startDaemon({ version, ptyModule } = {}) {
+  const config = await readConfig()
+  if (!config) {
+    throw new Error(
+      "~/.hub/agent.json が見つかりません。`hub-agent enroll <token>` を先に実行してください。",
+    )
+  }
+
+  const plugins = await loadPlugins(logger)
+  const ctx = { logger, config, plugins }
+
+  await runHookBroadcast(plugins, "onAgentStart", ctx)
+
+  const resolvedPty = ptyModule || (await import("node-pty"))
+  const ptyBridge = new PtyBridge({ ptyModule: resolvedPty, logger, plugins })
+
+  const client = new WsClient(config, { logger, version })
+
+  // EventEmitter の 'error' は listener が無いと process が落ちる。
+  // ws-client は close 側で reconnect を予約しているので、ここでは log だけ。
+  client.on("error", (err) => {
+    logger.warn({ err: err.message }, "ws client error (will retry via close handler)")
+  })
+
+  ptyBridge.on("output", ({ stream_id, data }) => {
+    client.send({ type: "pty.data", stream_id, data })
+  })
+  ptyBridge.on("exit", ({ stream_id, code }) => {
+    client.send({ type: "pty.exit", stream_id, code })
+  })
+
+  client.on("message", async (msg) => {
+    await dispatch(msg, { ...ctx, client, ptyBridge })
+  })
+
+  client.connect()
+
+  // 5s 周期で全 tmux session の状態を捕捉し、変化したものだけ session.state を push。
+  // browser がフォーカスしていない session でも常時更新するためのバックグラウンド職人。
+  const stateLoop = startStateLoop({ client, plugins, logger, intervalMs: 5_000 })
+
+  const shutdown = async (signal) => {
+    logger.info({ signal }, "shutting down")
+    await runHookBroadcast(plugins, "onAgentStop", ctx)
+    stateLoop.stop()
+    ptyBridge.shutdown()
+    client.stop()
+    process.exit(0)
+  }
+  process.on("SIGINT", () => shutdown("SIGINT"))
+  process.on("SIGTERM", () => shutdown("SIGTERM"))
+
+  return { client, plugins, ptyBridge }
+}
+
+/**
+ * 全 tmux session の状態を定期 capture し、変化したものだけ Hub に push する。
+ *
+ * - 前回値との比較で status / context_pct のどちらかが変化したら送る
+ * - 新規 session は無条件 push、消えた session は無視 (browser 側で
+ *   pty.exit 受信時に処理する)
+ * - tmux 自体が動いてない場合 (listSessionStates → []) は何も push しない
+ */
+function startStateLoop({ client, plugins, logger, intervalMs }) {
+  const lastByName = new Map() // session_name → {status, context_pct}
+  let stopped = false
+
+  const tick = async () => {
+    if (stopped) return
+    try {
+      const states = await listSessionStates({ plugins, logger })
+      for (const s of states) {
+        const prev = lastByName.get(s.session_name)
+        if (
+          !prev ||
+          prev.status !== s.status ||
+          prev.context_pct !== s.context_pct
+        ) {
+          lastByName.set(s.session_name, {
+            status: s.status,
+            context_pct: s.context_pct,
+          })
+          client.send({
+            type: "session.state",
+            session_name: s.session_name,
+            status: s.status,
+            context_pct: s.context_pct,
+          })
+        }
+      }
+    } catch (err) {
+      logger?.warn({ err: err.message }, "state loop tick failed")
+    }
+  }
+
+  // 起動直後に 1 回 + 以後 intervalMs 周期
+  const t0 = setTimeout(tick, 500)
+  const ti = setInterval(tick, intervalMs)
+  ti.unref?.()
+  t0.unref?.()
+
+  return {
+    stop() {
+      stopped = true
+      clearInterval(ti)
+      clearTimeout(t0)
+    },
+  }
+}
+
+/**
+ * Hub からのメッセージを type で分岐する。
+ *
+ * `pty.*` は PtyBridge にそのまま流す。`tmux.exec` は Sprint E で tmux 抽象に
+ * 渡す予定なので、現状は plugin hook chain だけ走らせて log に残す。
+ */
+async function dispatch(msg, ctx) {
+  const t = msg?.type || ""
+  try {
+    switch (t) {
+      case "ready":
+        ctx.logger.info({ msg }, "hub ready")
+        return
+      case "ack":
+        ctx.logger.debug({ echo: msg.echo }, "hub ack")
+        return
+      case "error":
+        ctx.logger.warn({ msg }, "hub error")
+        return
+      case "pty.attach": {
+        const stream_id = msg.stream_id
+        try {
+          const info = await ctx.ptyBridge.attach({
+            stream_id,
+            sessionName: msg.session_name || "",
+            cols: msg.cols,
+            rows: msg.rows,
+          })
+          ctx.client.send({
+            type: "pty.ready",
+            stream_id,
+            session_name: msg.session_name || "",
+            plugin: info.plugin,
+          })
+        } catch (err) {
+          ctx.client.send({
+            type: "pty.exit",
+            stream_id,
+            code: -1,
+            error: err.message,
+          })
+        }
+        return
+      }
+      case "pty.data":
+        ctx.ptyBridge.write({ stream_id: msg.stream_id, data: msg.data })
+        return
+      case "pty.resize":
+        ctx.ptyBridge.resize({
+          stream_id: msg.stream_id,
+          cols: msg.cols,
+          rows: msg.rows,
+        })
+        return
+      case "pty.detach":
+        ctx.ptyBridge.detach({ stream_id: msg.stream_id })
+        return
+      case "tmux.exec": {
+        const args = Array.isArray(msg.args) ? msg.args : []
+        const hookResult = await runHookChain(ctx.plugins, "interceptTmuxExec", {
+          logger: ctx.logger,
+          args,
+          env: process.env,
+        })
+        let result
+        if (hookResult?.result?.command) {
+          // plugin が独自 command で差し替え (例: remote-ops プラグインで ssh 越し)
+          const { command, args: spawnArgs, env } = hookResult.result
+          try {
+            const { execFile } = await import("node:child_process")
+            const { promisify } = await import("node:util")
+            const execFileP = promisify(execFile)
+            const { stdout, stderr } = await execFileP(command, spawnArgs, {
+              env: env || process.env,
+              maxBuffer: 4 * 1024 * 1024,
+            })
+            result = { stdout, stderr, exit_code: 0 }
+          } catch (err) {
+            result = {
+              stdout: err.stdout || "",
+              stderr: err.stderr || err.message || "",
+              exit_code: typeof err.code === "number" ? err.code : 1,
+            }
+          }
+        } else {
+          result = await execTmux(args)
+        }
+        ctx.client.send({
+          type: "tmux.result",
+          request_id: msg.request_id,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exit_code: result.exit_code,
+          plugin: hookResult?.plugin || null,
+        })
+        return
+      }
+      case "tmux.list_sessions": {
+        try {
+          const sessions = await listTmuxSessions({ plugins: ctx.plugins, logger: ctx.logger })
+          ctx.client.send({
+            type: "tmux.sessions",
+            request_id: msg.request_id,
+            sessions,
+          })
+        } catch (err) {
+          ctx.client.send({
+            type: "tmux.sessions",
+            request_id: msg.request_id,
+            sessions: [],
+            error: err.message,
+          })
+        }
+        return
+      }
+      case "tmux.create_session": {
+        const name = (msg.session_name || "").trim()
+        const cwd = (msg.cwd || process.env.HOME || "/").trim()
+        if (!name) {
+          ctx.client.send({
+            type: "tmux.create_session.result",
+            request_id: msg.request_id,
+            ok: false,
+            error: "session_name is required",
+          })
+          return
+        }
+        try {
+          await createTmuxSession(name, cwd, {
+            claudeCmd: typeof msg.claude_cmd === "string" ? msg.claude_cmd : undefined,
+          })
+          ctx.client.send({
+            type: "tmux.create_session.result",
+            request_id: msg.request_id,
+            ok: true,
+            session_name: name,
+          })
+        } catch (err) {
+          ctx.client.send({
+            type: "tmux.create_session.result",
+            request_id: msg.request_id,
+            ok: false,
+            error: err.message,
+          })
+        }
+        return
+      }
+      case "tmux.kill_session": {
+        const names = Array.isArray(msg.session_names)
+          ? msg.session_names
+          : msg.session_name
+            ? [msg.session_name]
+            : []
+        if (names.length === 0) {
+          ctx.client.send({
+            type: "tmux.kill_session.result",
+            request_id: msg.request_id,
+            killed: [],
+            failed: [{ name: "", reason: "session_name(s) required" }],
+          })
+          return
+        }
+        const r = await killManySessions(names)
+        ctx.client.send({
+          type: "tmux.kill_session.result",
+          request_id: msg.request_id,
+          killed: r.killed,
+          failed: r.failed,
+        })
+        return
+      }
+      case "skills.request": {
+        try {
+          const skills = await listSkills({ sessionName: msg.session_name })
+          ctx.client.send({
+            type: "skills.response",
+            request_id: msg.request_id,
+            session_name: msg.session_name || "",
+            skills,
+          })
+        } catch (err) {
+          ctx.client.send({
+            type: "skills.response",
+            request_id: msg.request_id,
+            session_name: msg.session_name || "",
+            skills: [],
+            error: err.message,
+          })
+        }
+        return
+      }
+      case "usage.request": {
+        try {
+          const [usage, sessions] = await Promise.all([
+            getUsage(),
+            getSessionUsages(),
+          ])
+          ctx.client.send({
+            type: "usage.response",
+            request_id: msg.request_id,
+            usage,
+            sessions,
+          })
+        } catch (err) {
+          ctx.client.send({
+            type: "usage.response",
+            request_id: msg.request_id,
+            usage: null,
+            sessions: [],
+            error: err.message,
+          })
+        }
+        return
+      }
+      default:
+        ctx.logger.debug({ type: t }, "unknown message type")
+    }
+  } catch (err) {
+    ctx.logger.error({ type: t, err: err.message }, "dispatch threw")
+  }
+}

package/src/plugin-install.mjs

@@ -0,0 +1,111 @@
+/**
+ * `hub-agent plugins install <name>` / `uninstall <name>` の実装 (Sprint K)。
+ *
+ * リポ同梱の `plugins/<name>/` を `~/.hub/plugins/<name>/` にコピーする。
+ * uninstall は `~/.hub/plugins/<name>/` を rm -rf する。
+ *
+ * config.json は plugin によって user 編集が必要なため、existing なら上書き
+ * しない (force オプションで強制可)。
+ */
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { paths as configPaths } from "./config.mjs"
+
+function repoPluginsDir() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "plugins")
+}
+
+export async function listInstallableExamples() {
+  const dir = repoPluginsDir()
+  let entries
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const out = []
+  for (const e of entries) {
+    if (!e.isDirectory()) continue
+    const pluginFile = path.join(dir, e.name, "plugin.mjs")
+    try {
+      await fs.access(pluginFile)
+      out.push(e.name)
+    } catch {
+      /* plugin.mjs 無いディレクトリは skip */
+    }
+  }
+  return out
+}
+
+async function copyDir(src, dest, { skipExisting = [] } = {}) {
+  await fs.mkdir(dest, { recursive: true, mode: 0o700 })
+  const entries = await fs.readdir(src, { withFileTypes: true })
+  for (const e of entries) {
+    const s = path.join(src, e.name)
+    const d = path.join(dest, e.name)
+    if (e.isDirectory()) {
+      await copyDir(s, d, { skipExisting })
+    } else {
+      if (skipExisting.includes(e.name)) {
+        try {
+          await fs.access(d)
+          continue // 既存ならコピーしない (user 編集を尊重)
+        } catch {
+          /* fall through to copy */
+        }
+      }
+      await fs.copyFile(s, d)
+    }
+  }
+}
+
+/** @returns {Promise<{ source: string, dest: string, copied: boolean }>} */
+export async function installPlugin(name, { force = false } = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error("plugin name is required")
+  }
+  const src = path.join(repoPluginsDir(), name)
+  try {
+    const st = await fs.stat(src)
+    if (!st.isDirectory()) throw new Error("not a directory")
+  } catch {
+    const available = await listInstallableExamples()
+    const hint = available.length ? ` Available: ${available.join(", ")}` : ""
+    throw new Error(`plugin "${name}" not found in repo plugins/.${hint}`)
+  }
+  const dest = path.join(configPaths.pluginsDir, name)
+  if (!force) {
+    try {
+      await fs.access(dest)
+      throw new Error(
+        `${dest} already exists. Pass --force to overwrite (config.json は常に温存)`,
+      )
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        // dest exists かつ force でない
+        if (err.message && err.message.includes("already exists")) throw err
+        if (err.code !== undefined) throw err
+      }
+    }
+  }
+  // config.json は既存なら skip して user 編集を温存
+  await copyDir(src, dest, { skipExisting: ["config.json"] })
+  return { source: src, dest, copied: true }
+}
+
+export async function uninstallPlugin(name) {
+  if (!name || typeof name !== "string") {
+    throw new Error("plugin name is required")
+  }
+  const dest = path.join(configPaths.pluginsDir, name)
+  try {
+    await fs.rm(dest, { recursive: true, force: true })
+  } catch (err) {
+    throw new Error(`failed to remove ${dest}: ${err.message}`)
+  }
+  return { dest, removed: true }
+}
+
+export const _internal = { repoPluginsDir, copyDir }

package/src/plugin-loader.mjs

@@ -0,0 +1,105 @@
+/**
+ * `~/.hub/plugins/<prio>-<name>/plugin.mjs` を discovery し、hook chain を構築する。
+ *
+ * - ディレクトリ名の `<prio>` 数字昇順で並ぶ
+ * - 各 plugin の default export が `{ name, hooks }` を持つ
+ * - `runHookChain(name, ctx)` は最初に non-null を返した hook の戻り値を採用
+ *
+ * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
+ */
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { paths } from "./config.mjs"
+
+const PLUGIN_DIR_REGEX = /^(\d+)-(.+)$/
+
+/**
+ * Plugins discovery。読み込み順は dirname の数値昇順。
+ *
+ * @returns {Promise<import('./hooks.mjs').Plugin[]>}
+ */
+export async function loadPlugins(logger) {
+  const pluginsDir = paths.pluginsDir
+  let entries
+  try {
+    entries = await fs.readdir(pluginsDir, { withFileTypes: true })
+  } catch (err) {
+    if (err.code === "ENOENT") return []
+    throw err
+  }
+
+  const candidates = entries
+    .filter((d) => d.isDirectory())
+    .map((d) => {
+      const m = PLUGIN_DIR_REGEX.exec(d.name)
+      if (!m) return null
+      return { dir: d.name, prio: Number(m[1]), name: m[2] }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.prio - b.prio)
+
+  const plugins = []
+  for (const c of candidates) {
+    const pluginFile = path.join(pluginsDir, c.dir, "plugin.mjs")
+    // plugin.mjs が存在しないディレクトリ (空 stub, README only 等) は警告のみで skip。
+    // import 例外を always-error にすると Sprint K 前の段階的展開で煩い。
+    try {
+      await fs.access(pluginFile)
+    } catch {
+      logger?.warn({ pluginFile }, "plugin.mjs not found (skipped)")
+      continue
+    }
+    try {
+      const mod = await import(pathToFileURL(pluginFile).href)
+      const plugin = mod.default
+      if (!plugin || typeof plugin !== "object" || !plugin.hooks) {
+        logger?.warn({ pluginFile }, "plugin shape invalid (default export must be { hooks })")
+        continue
+      }
+      plugin.name = plugin.name || c.name
+      plugin._prio = c.prio
+      plugins.push(plugin)
+      logger?.info({ plugin: plugin.name, prio: c.prio }, "plugin loaded")
+    } catch (err) {
+      logger?.error({ pluginFile, err: err.message }, "plugin load failed")
+    }
+  }
+  return plugins
+}
+
+/**
+ * 指定 hook を chain 実行し、最初に non-null を返した結果を採用する。
+ * すべて null なら null を返す (= caller 側で default 実装に fall through)。
+ */
+export async function runHookChain(plugins, hookName, ctx) {
+  for (const plugin of plugins) {
+    const hook = plugin.hooks?.[hookName]
+    if (typeof hook !== "function") continue
+    try {
+      const result = await hook(ctx)
+      if (result !== null && result !== undefined) {
+        return { plugin: plugin.name, result }
+      }
+    } catch (err) {
+      ctx?.logger?.error?.({ plugin: plugin.name, hookName, err: err.message }, "hook threw")
+    }
+  }
+  return null
+}
+
+/**
+ * void を返す hook (onAgentStart / onAgentStop) を全 plugin で実行する。
+ */
+export async function runHookBroadcast(plugins, hookName, ctx) {
+  for (const plugin of plugins) {
+    const hook = plugin.hooks?.[hookName]
+    if (typeof hook !== "function") continue
+    try {
+      await hook(ctx)
+    } catch (err) {
+      ctx?.logger?.error?.({ plugin: plugin.name, hookName, err: err.message }, "hook threw")
+    }
+  }
+}