@cocorograph/hub-agent 0.4.1

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Cocorograph Inc.
+
+All rights reserved. This package is proprietary and may be used only by
+authorized members of Cocorograph Inc. Redistribution or modification
+without prior written permission is prohibited.

package/README.md

@@ -0,0 +1,108 @@
+# @cocorograph/hub-agent
+
+Hub Hosted Cockpit のローカル常駐 agent。`hub.cocorograph.com` から outbound WSS で接続を受け、ローカルマシンの tmux / Claude Code セッションを Hub のブラウザ UI に中継する。
+
+仕様書: [`ナレッジ/インフラ/cockpit-hub-hosted-integration-spec`](https://hub.cocorograph.com/knowledge/spec/cockpit-hub-hosted-integration-spec) (Hub knowledge id=6080)
+
+## インストール
+
+### ワンライナー (推奨)
+
+Hub Cockpit Agents ページ (`https://hub.cocorograph.com/user/cockpit/agents`) で
+「**ワンライナーセットアップ**」をクリックして表示される curl コマンドをコピー → ターミナルで実行:
+
+```bash
+curl -fsSL https://api.hub.cocorograph.com/api/cockpit/agents/install-script | bash
+```
+
+このスクリプトは以下を **全自動** で実行します:
+- Homebrew (macOS で無ければ install)
+- tmux + node 20+ (無ければ install)
+- `npm i -g @cocorograph/hub-agent`
+- `hub-agent enroll <token>` (token は Hub session 経由で埋め込み済、5 分有効)
+- `hub-agent install-service` で OS サービス登録
+
+### 手動インストール (デバッグ用)
+
+```bash
+npm i -g @cocorograph/hub-agent
+hub-agent enroll <token> --hub-url https://api.hub.cocorograph.com
+hub-agent install-service
+```
+
+詳細は `scripts/install.sh` を参照。
+
+## CLI
+
+```bash
+hub-agent enroll <enrollment_token> [--hub-url URL] [--hostname NAME] [--force]
+hub-agent start                       # 前景 daemon (install-service 不使用時)
+hub-agent status                      # 現在の設定 + 接続状態
+hub-agent stop                        # 停止方法のヒント表示
+hub-agent install-service [--bin PATH]
+hub-agent uninstall-service
+hub-agent plugins list                # ~/.hub/plugins/ から読み込み済プラグイン
+hub-agent plugins examples            # repo 同梱の install 可能 example
+hub-agent plugins install <name> [--force]
+hub-agent plugins uninstall <name>
+```
+
+## 設定ファイル
+
+- `~/.hub/agent.json` — `{ agent_id, agent_token, hub_url }` (chmod 600)
+- `~/.hub/plugins/<prio>-<name>/plugin.mjs` — プラグイン
+- `~/.hub/plugins/<prio>-<name>/config.json` — プラグイン個別設定
+- `~/.hub/agent.log` — install-service 経由起動時のログ
+- `~/.hub/usage/latest.json` — Claude Code statusLine cache (使用量集計の元データ、任意)
+
+## 構成
+
+```
+hub-agent/
+├── bin/
+│   └── hub-agent.mjs          # CLI entry (commander)
+├── src/
+│   ├── main.mjs               # daemon 本体 + dispatcher
+│   ├── config.mjs             # ~/.hub/agent.json 管理
+│   ├── enroll.mjs             # enrollment フロー
+│   ├── ws-client.mjs          # outbound WSS + reconnect with jitter
+│   ├── pty-bridge.mjs         # node-pty 多重化
+│   ├── tmux.mjs               # tmux exec/list/create/kill
+│   ├── state.mjs              # session status / context_pct 検知
+│   ├── skills.mjs             # ~/.claude/skills 集計
+│   ├── usage.mjs              # Claude Code 使用量集計
+│   ├── plugin-loader.mjs      # plugin discovery + hook chain
+│   ├── hooks.mjs              # hook 名・型定義
+│   └── service-install.mjs    # launchd / systemd install
+├── templates/
+│   ├── co.cocorograph.hub-agent.plist
+│   └── hub-agent.service
+├── scripts/
+│   └── fix-node-pty-perms.mjs # node-pty spawn-helper +x 修復 (postinstall)
+└── test/
+```
+
+## 開発状況
+
+- [x] Sprint A: 仕様書 (Hub knowledge id=6080)
+- [x] Sprint B: Hub 側 enrollment API + WS endpoint 雛形
+- [x] Sprint C: 本リポジトリの雛形 + outbound WSS + hook system
+- [x] Sprint D: pty bridge
+- [x] Sprint E: tmux exec/list/create/kill 移植 + auto list UI
+- [x] Sprint F: Hub Browser↔Agent multiplex 中継
+- [x] Sprint G: Hub frontend /user/cockpit/{agents,terminal} ページ
+- [x] Sprint H: skills / state dot / usage badge リレー
+- [x] Sprint I: 接続復旧 (jitter + force reconnect + Celery stale 検知)
+- [x] Sprint J: 本リポジトリ publish 準備 + launchd/systemd 連携
+- [x] Sprint K: remote-ops プラグイン例 (`plugins/10-tailscale-remote/`)
+
+## 同梱プラグイン
+
+- [`plugins/10-tailscale-remote`](./plugins/10-tailscale-remote/README.md) — 自宅
+  Mac (hub-agent host) を会社 Mac (`remote_host`) の tmux に対する透過プロキシ化。
+  `hub-agent plugins install 10-tailscale-remote` で `~/.hub/plugins/` にコピー、
+  `config.json` を編集して restart で有効化
+
+## ライセンス
+
+UNLICENSED. Cocorograph Inc. 社内専用。

package/bin/hub-agent.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * @cocorograph/hub-agent CLI entry。
+ *
+ * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
+ *
+ * Sprint C 時点で実装する subcommand:
+ *   - enroll <token>   : 初回 enrollment
+ *   - start            : daemon 起動
+ *   - status           : 現在の設定 / 接続状態
+ *   - stop             : daemon 停止 (Sprint J で launchd / systemd と併用)
+ *   - plugins list     : プラグイン一覧
+ */
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import path from "node:path"
+
+import { Command } from "commander"
+
+import { hasConfig, readConfig } from "../src/config.mjs"
+import { enroll } from "../src/enroll.mjs"
+import {
+  installPlugin,
+  listInstallableExamples,
+  uninstallPlugin,
+} from "../src/plugin-install.mjs"
+import { loadPlugins } from "../src/plugin-loader.mjs"
+import { installService, uninstallService } from "../src/service-install.mjs"
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(path.join(here, "..", "package.json"), "utf-8"))
+
+const program = new Command()
+program
+  .name("hub-agent")
+  .description("Hub Hosted Cockpit のローカル常駐 agent")
+  .version(pkg.version)
+
+program
+  .command("enroll <enrollment_token>")
+  .description("Hub から発行された enrollment token で agent を登録する")
+  .option("--hub-url <url>", "Hub の base URL (default: $HUB_URL or https://hub.cocorograph.com)")
+  .option("--hostname <name>", "Hub に表示するホスト名 (default: os.hostname())")
+  .option("--force", "既存設定を上書きする")
+  .action(async (token, opts) => {
+    try {
+      const r = await enroll(token, {
+        hubUrl: opts.hubUrl,
+        hostname: opts.hostname,
+        version: pkg.version,
+        force: !!opts.force,
+      })
+      console.log(`enroll succeeded: agent_id=${r.agent_id} primary=${r.is_primary} hub=${r.hub_url}`)
+    } catch (err) {
+      console.error(`enroll failed: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command("start")
+  .description("daemon を起動して Hub と WSS 接続する")
+  .action(async () => {
+    const { startDaemon } = await import("../src/main.mjs")
+    try {
+      await startDaemon({ version: pkg.version })
+    } catch (err) {
+      console.error(`start failed: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command("status")
+  .description("設定と接続状態を表示する")
+  .action(async () => {
+    const exists = await hasConfig()
+    if (!exists) {
+      console.log("not enrolled (run `hub-agent enroll <token>`)")
+      process.exit(2)
+    }
+    const cfg = await readConfig()
+    console.log(`agent_id: ${cfg.agent_id}`)
+    console.log(`hub_url : ${cfg.hub_url}`)
+    console.log("(use ps/launchctl/systemctl to check if daemon is running)")
+  })
+
+program
+  .command("stop")
+  .description("daemon を停止する (install-service してある場合は OS サービスを停止)")
+  .action(() => {
+    if (process.platform === "darwin") {
+      console.log("launchctl kill SIGTERM gui/$UID/co.cocorograph.hub-agent")
+      console.log("or `hub-agent uninstall-service` で常駐解除")
+    } else if (process.platform === "linux") {
+      console.log("systemctl --user stop hub-agent.service")
+      console.log("or `hub-agent uninstall-service` で常駐解除")
+    } else {
+      console.log("pkill -INT -f hub-agent でプロセス停止してください")
+    }
+  })
+
+program
+  .command("install-service")
+  .description("OS サービスとして自動起動を有効化 (macOS=launchd / Linux=systemd --user)")
+  .option("--bin <path>", "明示的に hub-agent CLI のパスを指定")
+  .action(async (opts) => {
+    try {
+      const r = await installService({ bin: opts.bin })
+      console.log(`installed: ${r.platform} ${r.path}`)
+      console.log(`bin: ${r.bin}`)
+      if (r.platform === "darwin") {
+        console.log(`label: ${r.label}`)
+        console.log("確認: launchctl list | grep co.cocorograph.hub-agent")
+      } else {
+        console.log(`unit: ${r.unit}`)
+        console.log("確認: systemctl --user status hub-agent.service")
+      }
+      console.log("ログ: ~/.hub/agent.log")
+    } catch (err) {
+      console.error(`install-service failed: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command("uninstall-service")
+  .description("OS サービス登録を解除")
+  .action(async () => {
+    try {
+      const r = await uninstallService()
+      console.log(`uninstalled: ${r.platform} ${r.path}`)
+    } catch (err) {
+      console.error(`uninstall-service failed: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+const plugins = program.command("plugins").description("プラグイン管理")
+plugins
+  .command("list")
+  .description("~/.hub/plugins/ から読み込み可能なプラグインを表示する")
+  .action(async () => {
+    const list = await loadPlugins(null)
+    if (list.length === 0) {
+      console.log("(no plugins)")
+      return
+    }
+    for (const p of list) {
+      console.log(`- ${p._prio}: ${p.name}`)
+    }
+  })
+
+plugins
+  .command("examples")
+  .description("リポ同梱の install 可能 example プラグイン一覧")
+  .action(async () => {
+    const list = await listInstallableExamples()
+    if (list.length === 0) {
+      console.log("(no examples bundled)")
+      return
+    }
+    for (const name of list) {
+      console.log(`- ${name}`)
+    }
+  })
+
+plugins
+  .command("install <name>")
+  .description("repo plugins/<name>/ を ~/.hub/plugins/<name>/ にコピー (config.json は温存)")
+  .option("--force", "既存ディレクトリを上書きする")
+  .action(async (name, opts) => {
+    try {
+      const r = await installPlugin(name, { force: !!opts.force })
+      console.log(`installed: ${r.dest}`)
+      console.log("次のステップ:")
+      console.log(`  $EDITOR ${r.dest}/config.json    # 既存なら温存、新規なら example をコピー`)
+      console.log(`  hub-agent restart (launchctl kickstart / systemctl restart)`)
+    } catch (err) {
+      console.error(`plugins install failed: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+plugins
+  .command("uninstall <name>")
+  .description("~/.hub/plugins/<name>/ を削除")
+  .action(async (name) => {
+    try {
+      const r = await uninstallPlugin(name)
+      console.log(`uninstalled: ${r.dest}`)
+    } catch (err) {
+      console.error(`plugins uninstall failed: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cocorograph/hub-agent",
+  "version": "0.4.1",
+  "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "hub-agent": "bin/hub-agent.mjs"
+  },
+  "main": "src/main.mjs",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node bin/hub-agent.mjs start",
+    "test": "node --test test/*.test.mjs",
+    "postinstall": "node scripts/fix-node-pty-perms.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "templates/",
+    "plugins/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "node-pty": "^1.0.0",
+    "pino": "^9.0.0",
+    "ws": "^8.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cocorograph/D00000_hub-agent.git"
+  },
+  "homepage": "https://github.com/cocorograph/D00000_hub-agent#readme",
+  "bugs": {
+    "url": "https://github.com/cocorograph/D00000_hub-agent/issues"
+  },
+  "keywords": [
+    "cockpit",
+    "hub",
+    "tmux",
+    "remote",
+    "agent",
+    "cocorograph"
+  ]
+}

package/plugins/10-tailscale-remote/README.md

@@ -0,0 +1,71 @@
+# 10-tailscale-remote
+
+自宅 Mac (hub-agent host) を、Tailscale 等で繋がった会社 Mac (`remote_host`) の
+tmux に対する透過プロキシ化するサンプル plugin。
+
+## 何が起きるか
+
+| Browser action | 通常 (plugin 無し) | このプラグイン有効時 |
+|---|---|---|
+| `pty.attach` | ローカル `tmux attach -t SESSION` | `mosh remote_host -- tmux attach -t SESSION` |
+| `tmux.exec [...]` | ローカル `tmux ...` | `ssh remote_host tmux ...` |
+
+つまり、`hub.cocorograph.com/user/cockpit/terminal` から開くセッションが、
+あなたの手元 Mac ではなく `remote_host` の tmux に直接繋がります。Cockpit UI の
+`session.state` / `tmux.list_sessions` も全て `remote_host` 側の値です。
+
+## セットアップ
+
+1. ディレクトリを `~/.hub/plugins/10-tailscale-remote/` にコピー
+   ```bash
+   # CLI 経由 (推奨)
+   hub-agent plugins install 10-tailscale-remote
+
+   # 手動
+   mkdir -p ~/.hub/plugins/10-tailscale-remote
+   cp -r $(npm root -g)/@cocorograph/hub-agent/plugins/10-tailscale-remote/* \
+     ~/.hub/plugins/10-tailscale-remote/
+   ```
+
+2. `config.json` を編集
+   ```bash
+   cp ~/.hub/plugins/10-tailscale-remote/config.example.json \
+      ~/.hub/plugins/10-tailscale-remote/config.json
+   $EDITOR ~/.hub/plugins/10-tailscale-remote/config.json
+   ```
+
+   ```jsonc
+   {
+     "remote_host": "mbpm5-office",                       // ssh ホスト名
+     "ssh_key": "/Users/kaz/.ssh/mbpm5-office/id_ed25519",
+     "mosh_server": "/opt/homebrew/bin/mosh-server"       // remote_host 側のパス
+   }
+   ```
+
+3. remote 側の準備
+   - 同じユーザーで ssh 鍵ログイン可能であること
+   - `tmux` + `mosh-server` がインストール済みであること
+   - tmux session が既に走っていること (or `hub-agent` の `tmux.create_session` 経由で作る)
+
+4. hub-agent restart
+   ```bash
+   launchctl kickstart -k gui/$UID/co.cocorograph.hub-agent  # macOS
+   # or
+   systemctl --user restart hub-agent.service  # Linux
+   ```
+
+5. agent log で `tailscale-remote-ops 有効` の表示を確認
+   ```bash
+   tail -f ~/.hub/agent.log
+   ```
+
+## トラブルシューティング
+
+- `config.json` 無し → plugin は no-op で読み込まれます (`agent.log` に WARN)
+- ssh が「Host key verification failed」→ `ssh remote_host` で 1 度手動接続して known_hosts に追加
+- mosh が `Did not find mosh server startup message` → remote_host の `mosh_server` パスを確認 (`which mosh-server`)
+- Tailscale が落ちて remote_host に届かない → cockpit terminal を開くと WS 接続自体は成功するが pty が即 exit する
+
+## 仕様書
+
+[`ナレッジ/インフラ/cockpit-hub-hosted-integration-spec`](https://hub.cocorograph.com/knowledge/spec/cockpit-hub-hosted-integration-spec) (id=6080)

package/plugins/10-tailscale-remote/config.example.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "このファイルを config.json にコピーしてから編集してください。",
+  "remote_host": "mbpm5-office",
+  "ssh_key": "/Users/kaz/.ssh/mbpm5-office/id_ed25519",
+  "mosh_server": "/opt/homebrew/bin/mosh-server"
+}

package/plugins/10-tailscale-remote/plugin.mjs

@@ -0,0 +1,99 @@
+/**
+ * tailscale-remote: 自宅 Mac (hub-agent host) を 会社 Mac (remote_host) の
+ * tmux に対する透過プロキシ化するプラグイン (Sprint K サンプル)。
+ *
+ * - `interceptPtySpawn`: ブラウザの attach を mosh + ssh + tmux attach に差し替え
+ * - `interceptTmuxExec`: tmux.* RPC (list/create/kill 等) を ssh 越しに発行
+ *
+ * 使い方:
+ *   1. `~/.hub/plugins/10-tailscale-remote/` にこのファイル + config.json を置く
+ *      (`hub-agent plugins install 10-tailscale-remote` で自動コピー可)
+ *   2. config.json の remote_host / ssh_key / mosh_server を埋める
+ *   3. hub-agent restart (`hub-agent install-service` してあれば
+ *      `launchctl kickstart -k gui/$UID/co.cocorograph.hub-agent`)
+ *
+ * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
+ */
+import { readFileSync } from "node:fs"
+
+const cfgUrl = new URL("./config.json", import.meta.url)
+let cfg = { remote_host: "", ssh_key: "", mosh_server: "/opt/homebrew/bin/mosh-server" }
+try {
+  cfg = { ...cfg, ...JSON.parse(readFileSync(cfgUrl, "utf-8")) }
+} catch (err) {
+  // config.json が無い場合は plugin を no-op で読み込む (hook は何も上書きしない)
+  // user が編集してから restart する想定
+  cfg.__error = err.message
+}
+
+function isConfigured() {
+  return Boolean(cfg.remote_host && cfg.ssh_key && !cfg.__error)
+}
+
+function sshOpts() {
+  return ["-o", "IdentityAgent=none", "-i", cfg.ssh_key]
+}
+
+export default {
+  name: "tailscale-remote-ops",
+  hooks: {
+    async onAgentStart({ logger }) {
+      if (cfg.__error) {
+        logger?.warn(
+          { err: cfg.__error },
+          "tailscale-remote-ops: config.json が読めません。plugin は no-op で動作します",
+        )
+        return
+      }
+      if (!isConfigured()) {
+        logger?.warn(
+          { config: cfg },
+          "tailscale-remote-ops: remote_host / ssh_key が未設定。plugin は no-op",
+        )
+        return
+      }
+      logger?.info(
+        { remote_host: cfg.remote_host },
+        "tailscale-remote-ops 有効: pty.attach / tmux.exec を ssh 越しに発行します",
+      )
+    },
+
+    /**
+     * Browser からの attach を mosh + ssh + tmux attach に差し替える。
+     * pty bridge は通常通り node-pty で /bin/sh を spawn するが、その中身が
+     * remote_host への mosh ssh セッションになる。
+     */
+    async interceptPtySpawn({ sessionName }) {
+      if (!isConfigured()) return null
+      const sshOpt = sshOpts().join(" ")
+      const command = "/bin/sh"
+      const inner = [
+        `exec mosh`,
+        `--predict=adaptive`,
+        `--server=${cfg.mosh_server}`,
+        `--ssh="ssh ${sshOpt}"`,
+        cfg.remote_host,
+        `--`,
+        `bash -l -c "tmux attach -t ${sessionName}"`,
+      ].join(" ")
+      return {
+        command,
+        args: ["-c", inner],
+      }
+    },
+
+    /**
+     * tmux.* RPC (list-sessions / new-session / kill-session 等) を
+     * ssh 越しに remote_host で実行する。
+     */
+    async interceptTmuxExec({ args }) {
+      if (!isConfigured()) return null
+      return {
+        command: "ssh",
+        args: [...sshOpts(), cfg.remote_host, "tmux", ...args],
+      }
+    },
+  },
+}
+
+export const _internal = { cfg, isConfigured, sshOpts }

package/scripts/fix-node-pty-perms.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// pnpm 経由インストールだと node-pty/prebuilds/*/spawn-helper の実行権限が
+// 剥がれて posix_spawnp が失敗する事象への workaround.
+// postinstall で確実に +x を付与する。
+import { readdirSync, statSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+
+const PNPM_GLOB = "node_modules/.pnpm";
+const FALLBACK = "node_modules/node-pty/prebuilds";
+
+function fixDir(dir) {
+  let count = 0;
+  for (const platform of readdirSync(dir)) {
+    const helper = join(dir, platform, "spawn-helper");
+    try {
+      const st = statSync(helper);
+      if (!(st.mode & 0o111)) {
+        chmodSync(helper, st.mode | 0o755);
+        console.log(`[fix-perms] chmod +x ${helper}`);
+        count++;
+      }
+    } catch {
+      // not present (e.g. win32 dir has no spawn-helper)
+    }
+  }
+  return count;
+}
+
+function findPnpmPrebuilds() {
+  const out = [];
+  try {
+    for (const entry of readdirSync(PNPM_GLOB)) {
+      if (!entry.startsWith("node-pty@")) continue;
+      const p = join(PNPM_GLOB, entry, "node_modules/node-pty/prebuilds");
+      try {
+        statSync(p);
+        out.push(p);
+      } catch { /* skip */ }
+    }
+  } catch { /* no pnpm dir */ }
+  return out;
+}
+
+let fixed = 0;
+for (const dir of findPnpmPrebuilds()) {
+  fixed += fixDir(dir);
+}
+try {
+  statSync(FALLBACK);
+  fixed += fixDir(FALLBACK);
+} catch { /* not hoisted */ }
+
+if (fixed === 0) {
+  // 何も修正しなかった = 既に OK or node-pty 未インストール。サイレント終了。
+}