grix-connector 3.10.2 → 3.11.0

package/openclaw-plugin/skills/grix-admin/references/api-contract.md

@@ -16,7 +16,7 @@
 2. All remote creation and category actions must go through `grix_admin` via the current account's authenticated WS channel.
 3. If `agent_name` / `agent_id` / `api_endpoint` / `api_key` are incomplete, and the current account cannot create remotely, stop first and require backend admin to complete them.
 4. The current agent must first have the corresponding scope enabled on the frontend permissions page; without scope, WS will fail directly.
-5. For `bind-local` / `create-and-bind`, "config written successfully" does not equal completion; if this invocation already has real routing verification conditions, real verification passing must also be counted as part of the success criteria; otherwise explicitly hand the subsequent verification responsibility back to the upper-level flow.
+5. For `bind-local` / `create-and-bind` / `connector-bind-local` / `create-and-connector-bind`, "config written successfully" does not equal completion; if this invocation already has real routing verification conditions, real verification passing must also be counted as part of the success criteria; otherwise explicitly hand the subsequent verification responsibility back to the upper-level flow.
 
 ## Direct `grix_admin` Contract
 
@@ -116,7 +116,11 @@ Required scope:
 
 ## Local Bind Steps
 
-After remote agent parameters are complete, continue with local binding through the official OpenClaw CLI:
+After remote agent parameters are complete, continue with local binding. The target environment determines which path to follow.
+
+### Path A: OpenClaw
+
+Use official OpenClaw CLI commands:
 
 1. Prepare local directories:
    - `workspace=~/.openclaw/workspace-<agent_name>`
@@ -149,6 +153,35 @@ After remote agent parameters are complete, continue with local binding through
 7. Only when step 5 static validation passes and this invocation itself handles step 6 real verification but verification fails, is one `openclaw gateway restart` allowed; after restart, must redo the same round of real routing verification.
 8. If this invocation cannot perform real verification, can only state "config has been written, runtime not yet tested, needs subsequent flow to continue verification"; do not write it as "already fully taken effect".
 
+### Path B: grix-connector
+
+Directly manage `~/.grix/config/agents.json` and hot-reload the daemon:
+
+1. Target file: `~/.grix/config/agents.json`. Initialize as `{ "agents": [] }` if missing.
+2. Read the existing `agents` array. Match by `name === agent_name`:
+   - If found, update the existing entry in place.
+   - If not found, append a new entry.
+3. Write the entry with these fields:
+   - `name`: `agent_name`
+   - `ws_url`: `api_endpoint`
+   - `agent_id`: `agent_id`
+   - `api_key`: `api_key`
+   - `client_type`: `client_type` (default `pi`)
+4. Preserve valid JSON, set file permissions to `0o600`, and create a timestamped backup (also `0o600`) before writing.
+5. Trigger reload through the synchronous Admin API:
+   - Default endpoint: `POST http://127.0.0.1:19580/api/reload`
+   - The endpoint waits for `manager.reload()` to complete and returns `{ ok: true, result }` or an error. Use this instead of the CLI `grix-connector reload` to avoid races and to surface reload failures.
+   - If the admin port was customized via `GRIX_ADMIN_PORT` or `--admin-port`, read the actual port from `~/.grix/data/admin-port`.
+6. Verify via Admin API `GET http://127.0.0.1:<admin-port>/api/agents`:
+   - Find entry where `name === agent_name`.
+   - Confirm the entry exists and reports `alive === true`.
+   - **Caveat**: `alive=true` only means the daemon started the instance. It does **not** prove the Agent successfully authenticated with the Grix platform.
+7. Perform secondary platform-connection verification:
+   - Inspect daemon logs for WebSocket connection success / authentication failure messages for this Agent.
+   - Or ask the owner to send a test message to the Agent and confirm it responds.
+8. If verification fails, report the observed status and stop; do not claim success.
+9. If this invocation cannot perform real verification, can only state "config has been written, reload completed, runtime not yet tested"; do not write it as "already fully taken effect".
+
 ## `bind-local` Input Contract
 
 ```json
@@ -159,6 +192,32 @@ After remote agent parameters are complete, continue with local binding through
 
 This mode prioritizes local binding; if this invocation has real verification conditions, must also complete real routing verification before it counts as full convergence; otherwise only complete static binding and explicitly hand subsequent verification responsibility to the upper-level flow.
 
+## `connector-bind-local` Input Contract
+
+```json
+{
+  "task": "connector-bind-local\nagent_name=programmer-pi\nagent_id=2079349263263338496\napi_endpoint=wss://grix.dhf.pub/v1/agent-api/ws?agent_id=2079349263263338496\napi_key=ak_xxx\nclient_type=pi"
+}
+```
+
+Field mapping to `~/.grix/config/agents.json`:
+
+| Input field    | JSON field   | Notes                                      |
+| -------------- | ------------ | ------------------------------------------ |
+| `agent_name`   | `name`       | Also used as the matching key              |
+| `api_endpoint` | `ws_url`     | The WebSocket URL for the agent API        |
+| `agent_id`     | `agent_id`   | Platform agent ID                          |
+| `api_key`      | `api_key`    | Agent API key                              |
+| `client_type`  | `client_type`| Optional, default `pi`                     |
+
+Convergence rules:
+
+1. Backup `~/.grix/config/agents.json` before writing; set backup permissions to `0o600`.
+2. Preserve valid JSON and set file permissions to `0o600`.
+3. Trigger reload via synchronous Admin API `POST http://127.0.0.1:19580/api/reload` (or the port stored in `~/.grix/data/admin-port` if customized).
+4. Verify via `GET http://127.0.0.1:<admin-port>/api/agents` that the entry exists and has `alive=true`.
+5. Perform secondary platform-connection verification by checking daemon logs or sending a test message; do not treat `alive=true` as proof of successful platform authentication.
+
 ## `create-and-bind` Input Contract
 
 When the main agent already has an available account and `agent.api.create` scope, can enter the creation flow through `grix_admin.task`:
@@ -186,6 +245,30 @@ Notes:
 2. When matching `categoryName`, must also consider `parentCategoryId`
 3. If the remote return indicates missing `agent.api.create` or any `agent.category.*` scope, clearly state which specific scope is missing
 
+## `create-and-connector-bind` Input Contract
+
+When the main agent already has an available account and `agent.api.create` scope, and the target runtime is grix-connector:
+
+```json
+{
+  "task": "create-and-connector-bind\nagentName=程序员 pi\nintroduction=A coding assistant\nisMain=false\nclientType=pi\ncategoryName=Developers\nparentCategoryId=0\ncategorySortOrder=10"
+}
+```
+
+This mode requires steps in order:
+
+1. Make one direct call with `action=create_agent`, passing optional `categoryId` / `categoryName` / `parentCategoryId` / `categorySortOrder` together.
+2. If the return already includes the category assignment result, continue directly; otherwise supplement with the same category resolution logic as `create-and-bind`.
+3. Read `createdAgent.id`, `createdAgent.agent_name`, `createdAgent.api_endpoint`, `createdAgent.api_key` from the result.
+4. Follow the `connector-bind-local` local binding and runtime convergence flow, using `clientType` (default `pi`) for the `client_type` field.
+5. Trigger reload via the synchronous Admin API `POST /api/reload`, verify the Agent entry exists and `alive=true` via `GET /api/agents`, and perform secondary platform-connection verification (log inspection or test message).
+
+Notes:
+
+1. `categoryId` and `categoryName` cannot be provided simultaneously.
+2. `clientType` defaults to `pi` when omitted.
+3. If the remote return indicates missing `agent.api.create` or any `agent.category.*` scope, clearly state which specific scope is missing.
+
 ## `category-manage` Input Contract
 
 When only doing subsequent category management, enter through `grix_admin.task`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grix-connector",
-  "version": "3.10.2",
+  "version": "3.11.0",
   "description": "Connect local AI coding agents (Claude, Codex, Gemini, Qwen, DeepSeek, Cursor, OpenCode, Pi, OpenHuman, Reasonix) to the Grix scheduling platform. Also serves as an OpenClaw plugin for Grix channel transport.",
   "type": "module",
   "main": "dist/index.js",