# @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 サービス登録

### Windows (WSL2 方式)

Windows では WSL2 (Ubuntu) の中で hub-agent を動かします。Cockpit Agents ページで
OS を Windows に切り替えると **管理者 PowerShell 用ワンライナー**が表示されるので、
**管理者として実行した PowerShell** にコピペします:

```powershell
$env:HUB_AGENT_TOKEN="<tok>"; $env:HUB_AGENT_URL="https://api.hub.cocorograph.com"; `
  irm https://unpkg.com/@cocorograph/hub-agent@latest/scripts/install.ps1 | iex
```

このスクリプトは WSL2 (`Ubuntu-24.04`) を導入 (要再起動 1 回・再起動後に自動再開)、
Ubuntu 初回ユーザーを無人作成 (Windows と同名 / パスワードなし / NOPASSWD sudo)、
WSL 内で既存 `install.sh` を実行、Task Scheduler でログオン時の常駐起動を登録します。

> ⚠️ 作業リポジトリは **WSL 内 FS** (`/home/<user>/...`) に置いてください。Windows ドライブ
> (`/mnt/c/...`) はファイル監視 (inotify) が WSL 跨ぎで不安定です。

詳細・設計判断は `scripts/install.ps1` と `docs/windows-installer-design.md` を参照。

### 手動インストール (デバッグ用)

```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 uninstall <name>    # ~/.hub/plugins/<prio>-<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
│   ├── claude-stream-bridge.mjs # Claude Agent SDK チャット中継
│   ├── codex-stream-bridge.mjs  # Codex app-server チャット中継
│   ├── 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/
│   ├── install.sh             # ワンライナーセットアップ (macOS / Linux / WSL)
│   └── install.ps1            # Windows (WSL2 導入 + Task Scheduler 登録)
└── 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 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 連携

## プラグイン

プラグインは利用者が `~/.hub/plugins/<prio>-<name>/plugin.mjs` を自分で置く運用です。
置けば `plugins list` から読み込まれ、`plugins uninstall <prio>-<name>` で削除できます。

リポジトリ同梱の example プラグインはありません。唯一同梱していた
`plugins/10-tailscale-remote/` は pty spawn を横取りするプラグインで、pty 中継の撤去と
同時に削除しました。同梱 example が 0 件になったため、それを配る `plugins examples` /
`plugins install` と `package.json` の `files` の `plugins/` も外しています。

## ライセンス

UNLICENSED. Cocorograph Inc. 社内専用。