grix-connector 3.1.15 → 3.1.16

package/README.md

@@ -1,241 +1,241 @@
-# grix-connector
-
-A command-line daemon that connects your local AI coding agents to the [Grix](https://grix.im) platform.
-
-## What is Grix?
-
-Grix is an AI Agent scheduling platform. It lets you manage and interact with multiple AI coding agents through a unified chat interface. Register at [grix.im](https://grix.im) to get started.
-
-## Get the Client
-
-After installing grix-connector, download the Grix client from [grix.im](https://grix.im) to chat with your agents. Clients are available for iOS, Android, macOS, Windows, and Linux.
-
-## Supported Agents
-
-Set `client_type` in your config to one of the values below. Each `client_type` maps to a built-in adapter and CLI command — you only need the corresponding CLI installed locally.
-
-| `client_type` | Agent | Adapter | Required CLI |
-|---|---|---|---|
-| `claude` | Claude Code (Anthropic) | claude | `claude` |
-| `codex` | Codex (OpenAI) | codex | `codex` |
-| `gemini` | Gemini (Google) | acp | `gemini` |
-| `qwen` | Qwen (Alibaba) | acp | `qwen` |
-| `copilot` | GitHub Copilot | acp | `copilot` or `gh` |
-| `kiro` | Kiro | acp | `kiro-cli` |
-| `reasonix` | Reasonix | acp | `reasonix` |
-| `cursor` | Cursor Agent | cursor | `agent` |
-| `codewhale` | CodeWhale | codewhale | `codewhale` |
-| `opencode` | OpenCode | opencode | `opencode` |
-| `pi` | Pi | pi | `pi` |
-| `openhuman` | OpenHuman | openhuman | `openhuman-core` |
-| `agy` | Agy (Antigravity) | agy | `agy` |
-| `hermes` | [Hermes](https://github.com/askie/grix-hermes-python) | external | `hermes` |
-
-The ACP adapter (Agent Client Protocol over JSON-RPC) backs Gemini, Qwen, Copilot, Kiro and Reasonix. Hermes is an external agent maintained in a separate project — see [grix-hermes-python](https://github.com/askie/grix-hermes-python) for setup.
-
-You need to have the corresponding CLI tool installed locally before connecting an agent.
-
-## Install
-
-```bash
-npm install -g grix-connector
-```
-
-Requires Node.js >= 18.
-
-On Windows, `grix-connector` uses the built-in Task Scheduler with a hidden WScript launcher (no extra dependency required).
-
-## Quick Start
-
-### 1. Register a Grix account
-
-Go to [grix.im](https://grix.im), sign up and get your API key.
-
-### 2. Create agent config
-
-Create `~/.grix/config/agents.json`. Choose the `ws_url` for your region — the two regions use different WebSocket domains:
-
-- China mainland: `wss://grix.dhf.pub/v1/agent-api/ws`
-- Global: `wss://ws.grix.im/v1/agent-api/ws`
-
-China mainland example:
-
-```json
-{
-  "agents": [
-    {
-      "name": "my-agent",
-      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
-      "agent_id": "your-agent-id",
-      "api_key": "your-grix-api-key",
-      "client_type": "claude"
-    }
-  ]
-}
-```
-
-Global example:
-
-```json
-{
-  "agents": [
-    {
-      "name": "my-agent",
-      "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
-      "agent_id": "your-agent-id",
-      "api_key": "your-grix-api-key",
-      "client_type": "claude"
-    }
-  ]
-}
-```
-
-Change `client_type` to match the agent you want to connect (see table above). You can define multiple agents in one file, or use separate files under `~/.grix/config/`.
-
-### Config Reference
-
-Each agent entry uses one flat structure:
-
-| Field | Required | Description |
-|---|---|---|
-| `name` | yes | Display name for this agent |
-| `ws_url` | yes | WebSocket endpoint URL (region-specific). China mainland: `wss://grix.dhf.pub/v1/agent-api/ws`; Global: `wss://ws.grix.im/v1/agent-api/ws` |
-| `agent_id` | yes | Agent ID from Grix platform |
-| `api_key` | yes | API key for authentication |
-| `client_type` | yes | See Supported Agents table above |
-| `prompt_timeout_ms` | no | Prompt execution timeout (ms) |
-| `pool.maxSize` | no | Max adapter pool size (default 20) |
-| `pool.idleTimeoutMs` | no | Idle adapter eviction timeout (default 300000 = 5 min) |
-
-Adapter command/args/options are built in and resolved from `client_type`. To connect a different agent, simply change `client_type` — no other config changes needed.
-
-### Multi-agent Example
-
-China mainland region (swap the `ws_url` domain to `ws.grix.im` for the global region):
-
-```json
-{
-  "agents": [
-    {
-      "name": "my-claude",
-      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
-      "agent_id": "your-agent-id",
-      "api_key": "your-grix-api-key",
-      "client_type": "claude"
-    },
-    {
-      "name": "my-gemini",
-      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
-      "agent_id": "another-agent-id",
-      "api_key": "your-grix-api-key",
-      "client_type": "gemini"
-    }
-  ]
-}
-```
-
-### 3. Start the daemon
-
-```bash
-grix-connector start
-```
-
-The daemon connects to Grix via WebSocket and starts routing chat messages to your agents.
-
-### Commands
-
-```bash
-grix-connector start     # Start as system service (auto-installs on first run)
-grix-connector stop      # Stop the service
-grix-connector restart   # Restart the service
-grix-connector reload    # Hot-reload agent configs without restarting the daemon
-grix-connector status    # Check service status
-```
-
-### Reloading config (`reload`)
-
-`reload` applies changes to your config files **without restarting the daemon**. It re-reads `~/.grix/config/*.json`, diffs against what's currently running, and acts per agent:
-
-| Change in config | What happens |
-|---|---|
-| Agent added | Started and connected |
-| Agent removed | Stopped and disconnected |
-| Agent config changed | That agent restarts (stop old, start new) |
-| Agent unchanged | **Left running untouched** — its sessions are not interrupted |
-
-**When to use it.** You run a multi-agent setup and want to add, remove, or re-key one agent — or tweak one agent's settings — without dropping the live sessions of the *other* agents. A full `restart` would reconnect every agent and interrupt all in-flight conversations; `reload` only touches the agents whose config actually changed.
-
-**Safety.** If any config file fails to parse (e.g. you're mid-edit and the JSON is broken), or no valid agent config is found, the reload aborts and the running agents are left exactly as they are — nothing is torn down on a bad config.
-
-Three equivalent ways to trigger it:
-
-```bash
-grix-connector reload                          # CLI (sends SIGHUP to the daemon)
-kill -HUP "$(cat ~/.grix/grix-acp.pid)"        # raw signal (Unix)
-curl -XPOST http://127.0.0.1:19580/api/reload  # Admin API — returns the per-agent result as JSON
-```
-
-The CLI/signal form is fire-and-forget; the per-agent result is written to the daemon log. The Admin API form returns the result (added/removed/restarted/unchanged/failed) synchronously.
-
-### Ports
-
-The daemon binds two local loopback ports (127.0.0.1 only):
-
-| Purpose | Default | Override (env) | Override (CLI) |
-|---|---|---|---|
-| Health check (`/healthz`) | `19579` | `GRIX_HEALTH_PORT` | `--health-port <port>` |
-| Admin API (used by the local CLI) | `19580` | `GRIX_ADMIN_PORT` | `--admin-port <port>` |
-
-If a port is already in use, the daemon refuses to start and writes a clear message to `~/.grix/service/daemon.err.log` and the main log, and marks `~/.grix/daemon-status.json` as `state: "failed"` with a `reason` like `port_bind_in_use:health:19579`.
-
-To pick different ports:
-
-```bash
-# via environment
-GRIX_HEALTH_PORT=29579 GRIX_ADMIN_PORT=29580 grix-connector restart
-
-# or via CLI flags (when running the daemon directly)
-grix-connector --health-port 29579 --admin-port 29580
-```
-
-To find what is occupying a port:
-
-```bash
-# macOS / Linux
-lsof -nP -iTCP:19579 -sTCP:LISTEN
-
-# Windows (PowerShell or cmd)
-netstat -ano | findstr :19579
-```
-
-## OpenClaw Plugin
-
-grix-connector can also be installed as an [OpenClaw](https://openclaw.io) plugin, providing a Grix channel transport with admin tools and operator CLI.
-
-### Install
-
-```bash
-openclaw plugin install grix-connector
-```
-
-Or manually add to your OpenClaw project:
-
-```bash
-npm install grix-connector
-```
-
-### Plugin Features
-
-- **Channel**: Grix chat transport — routes messages between OpenClaw and your Grix deployment
-- **Tools**: `grix_query`, `grix_group`, `grix_admin`, `grix_egg`, `grix_register`, `grix_update`, `grix_message_send`, `grix_message_unsend`, `openclaw_memory_setup`
-- **CLI**: `openclaw grix` — agent management and admin commands
-- **Skills**: 9 bundled skills for admin, group, query, registration, update, messaging, memory setup, and egg orchestration
-
-### Requirements
-
-- OpenClaw >= 2026.4.8
-- A Grix account with agent ID and API key
-
-## License
-
-MIT
+# grix-connector
+
+A command-line daemon that connects your local AI coding agents to the [Grix](https://grix.im) platform.
+
+## What is Grix?
+
+Grix is an AI Agent scheduling platform. It lets you manage and interact with multiple AI coding agents through a unified chat interface. Register at [grix.im](https://grix.im) to get started.
+
+## Get the Client
+
+After installing grix-connector, download the Grix client from [grix.im](https://grix.im) to chat with your agents. Clients are available for iOS, Android, macOS, Windows, and Linux.
+
+## Supported Agents
+
+Set `client_type` in your config to one of the values below. Each `client_type` maps to a built-in adapter and CLI command — you only need the corresponding CLI installed locally.
+
+| `client_type` | Agent | Adapter | Required CLI |
+|---|---|---|---|
+| `claude` | Claude Code (Anthropic) | claude | `claude` |
+| `codex` | Codex (OpenAI) | codex | `codex` |
+| `gemini` | Gemini (Google) | acp | `gemini` |
+| `qwen` | Qwen (Alibaba) | acp | `qwen` |
+| `copilot` | GitHub Copilot | acp | `copilot` or `gh` |
+| `kiro` | Kiro | acp | `kiro-cli` |
+| `reasonix` | Reasonix | acp | `reasonix` |
+| `cursor` | Cursor Agent | cursor | `agent` |
+| `codewhale` | CodeWhale | codewhale | `codewhale` |
+| `opencode` | OpenCode | opencode | `opencode` |
+| `pi` | Pi | pi | `pi` |
+| `openhuman` | OpenHuman | openhuman | `openhuman-core` |
+| `agy` | Agy (Antigravity) | agy | `agy` |
+| `hermes` | [Hermes](https://github.com/askie/grix-hermes-python) | external | `hermes` |
+
+The ACP adapter (Agent Client Protocol over JSON-RPC) backs Gemini, Qwen, Copilot, Kiro and Reasonix. Hermes is an external agent maintained in a separate project — see [grix-hermes-python](https://github.com/askie/grix-hermes-python) for setup.
+
+You need to have the corresponding CLI tool installed locally before connecting an agent.
+
+## Install
+
+```bash
+npm install -g grix-connector
+```
+
+Requires Node.js >= 18.
+
+On Windows, `grix-connector` uses the built-in Task Scheduler with a hidden WScript launcher (no extra dependency required).
+
+## Quick Start
+
+### 1. Register a Grix account
+
+Go to [grix.im](https://grix.im), sign up and get your API key.
+
+### 2. Create agent config
+
+Create `~/.grix/config/agents.json`. Choose the `ws_url` for your region — the two regions use different WebSocket domains:
+
+- China mainland: `wss://grix.dhf.pub/v1/agent-api/ws`
+- Global: `wss://ws.grix.im/v1/agent-api/ws`
+
+China mainland example:
+
+```json
+{
+  "agents": [
+    {
+      "name": "my-agent",
+      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
+      "agent_id": "your-agent-id",
+      "api_key": "your-grix-api-key",
+      "client_type": "claude"
+    }
+  ]
+}
+```
+
+Global example:
+
+```json
+{
+  "agents": [
+    {
+      "name": "my-agent",
+      "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
+      "agent_id": "your-agent-id",
+      "api_key": "your-grix-api-key",
+      "client_type": "claude"
+    }
+  ]
+}
+```
+
+Change `client_type` to match the agent you want to connect (see table above). You can define multiple agents in one file, or use separate files under `~/.grix/config/`.
+
+### Config Reference
+
+Each agent entry uses one flat structure:
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | yes | Display name for this agent |
+| `ws_url` | yes | WebSocket endpoint URL (region-specific). China mainland: `wss://grix.dhf.pub/v1/agent-api/ws`; Global: `wss://ws.grix.im/v1/agent-api/ws` |
+| `agent_id` | yes | Agent ID from Grix platform |
+| `api_key` | yes | API key for authentication |
+| `client_type` | yes | See Supported Agents table above |
+| `prompt_timeout_ms` | no | Prompt execution timeout (ms) |
+| `pool.maxSize` | no | Max adapter pool size (default 20) |
+| `pool.idleTimeoutMs` | no | Idle adapter eviction timeout (default 300000 = 5 min) |
+
+Adapter command/args/options are built in and resolved from `client_type`. To connect a different agent, simply change `client_type` — no other config changes needed.
+
+### Multi-agent Example
+
+China mainland region (swap the `ws_url` domain to `ws.grix.im` for the global region):
+
+```json
+{
+  "agents": [
+    {
+      "name": "my-claude",
+      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
+      "agent_id": "your-agent-id",
+      "api_key": "your-grix-api-key",
+      "client_type": "claude"
+    },
+    {
+      "name": "my-gemini",
+      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
+      "agent_id": "another-agent-id",
+      "api_key": "your-grix-api-key",
+      "client_type": "gemini"
+    }
+  ]
+}
+```
+
+### 3. Start the daemon
+
+```bash
+grix-connector start
+```
+
+The daemon connects to Grix via WebSocket and starts routing chat messages to your agents.
+
+### Commands
+
+```bash
+grix-connector start     # Start as system service (auto-installs on first run)
+grix-connector stop      # Stop the service
+grix-connector restart   # Restart the service
+grix-connector reload    # Hot-reload agent configs without restarting the daemon
+grix-connector status    # Check service status
+```
+
+### Reloading config (`reload`)
+
+`reload` applies changes to your config files **without restarting the daemon**. It re-reads `~/.grix/config/*.json`, diffs against what's currently running, and acts per agent:
+
+| Change in config | What happens |
+|---|---|
+| Agent added | Started and connected |
+| Agent removed | Stopped and disconnected |
+| Agent config changed | That agent restarts (stop old, start new) |
+| Agent unchanged | **Left running untouched** — its sessions are not interrupted |
+
+**When to use it.** You run a multi-agent setup and want to add, remove, or re-key one agent — or tweak one agent's settings — without dropping the live sessions of the *other* agents. A full `restart` would reconnect every agent and interrupt all in-flight conversations; `reload` only touches the agents whose config actually changed.
+
+**Safety.** If any config file fails to parse (e.g. you're mid-edit and the JSON is broken), or no valid agent config is found, the reload aborts and the running agents are left exactly as they are — nothing is torn down on a bad config.
+
+Three equivalent ways to trigger it:
+
+```bash
+grix-connector reload                          # CLI (sends SIGHUP to the daemon)
+kill -HUP "$(cat ~/.grix/grix-acp.pid)"        # raw signal (Unix)
+curl -XPOST http://127.0.0.1:19580/api/reload  # Admin API — returns the per-agent result as JSON
+```
+
+The CLI/signal form is fire-and-forget; the per-agent result is written to the daemon log. The Admin API form returns the result (added/removed/restarted/unchanged/failed) synchronously.
+
+### Ports
+
+The daemon binds two local loopback ports (127.0.0.1 only):
+
+| Purpose | Default | Override (env) | Override (CLI) |
+|---|---|---|---|
+| Health check (`/healthz`) | `19579` | `GRIX_HEALTH_PORT` | `--health-port <port>` |
+| Admin API (used by the local CLI) | `19580` | `GRIX_ADMIN_PORT` | `--admin-port <port>` |
+
+If a port is already in use, the daemon refuses to start and writes a clear message to `~/.grix/service/daemon.err.log` and the main log, and marks `~/.grix/daemon-status.json` as `state: "failed"` with a `reason` like `port_bind_in_use:health:19579`.
+
+To pick different ports:
+
+```bash
+# via environment
+GRIX_HEALTH_PORT=29579 GRIX_ADMIN_PORT=29580 grix-connector restart
+
+# or via CLI flags (when running the daemon directly)
+grix-connector --health-port 29579 --admin-port 29580
+```
+
+To find what is occupying a port:
+
+```bash
+# macOS / Linux
+lsof -nP -iTCP:19579 -sTCP:LISTEN
+
+# Windows (PowerShell or cmd)
+netstat -ano | findstr :19579
+```
+
+## OpenClaw Plugin
+
+grix-connector can also be installed as an [OpenClaw](https://openclaw.io) plugin, providing a Grix channel transport with admin tools and operator CLI.
+
+### Install
+
+```bash
+openclaw plugin install grix-connector
+```
+
+Or manually add to your OpenClaw project:
+
+```bash
+npm install grix-connector
+```
+
+### Plugin Features
+
+- **Channel**: Grix chat transport — routes messages between OpenClaw and your Grix deployment
+- **Tools**: `grix_query`, `grix_group`, `grix_admin`, `grix_egg`, `grix_register`, `grix_update`, `grix_message_send`, `grix_message_unsend`, `openclaw_memory_setup`
+- **CLI**: `openclaw grix` — agent management and admin commands
+- **Skills**: 9 bundled skills for admin, group, query, registration, update, messaging, memory setup, and egg orchestration
+
+### Requirements
+
+- OpenClaw >= 2026.4.8
+- A Grix account with agent ID and API key
+
+## License
+
+MIT