grix-connector 3.1.13 → 3.1.14

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

@@ -1,210 +1,210 @@
-# API Contract
-
-## Purpose
-
-`grix-admin` is responsible for local binding and runtime convergence, and when the current agent has the corresponding scope, supports completing the following through `grix_admin` via WS:
-
-1. Create new remote API agents
-2. Query agent categories under the current account
-3. Create categories
-4. Modify categories
-5. Assign or clear categories for specified agents
-
-## Base Rules
-
-1. Do not ask users to provide website account/password for this flow.
-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.
-
-## Direct `grix_admin` Contract
-
-### 1. Create Remote Agent
-
-```json
-{
-  "action": "create_agent",
-  "agentName": "ops helper",
-  "introduction": "Handles deployment and on-call collaboration",
-  "isMain": false,
-  "categoryName": "Project Assistant",
-  "parentCategoryId": "0",
-  "categorySortOrder": 10
-}
-```
-
-Key fields to read from the return:
-
-1. `createdAgent.id`
-2. `createdAgent.agent_name`
-3. `createdAgent.api_endpoint`
-4. `createdAgent.api_key`
-
-Required scope:
-
-1. `agent.api.create`
-2. If `categoryName` is included, may additionally need `agent.category.list`, `agent.category.create`, `agent.category.assign`
-3. If `categoryId` is included, additionally needs `agent.category.assign`
-
-### 2. List Categories
-
-```json
-{
-  "action": "list_categories"
-}
-```
-
-Required scope:
-
-1. `agent.category.list`
-
-### 3. Create Category
-
-```json
-{
-  "action": "create_category",
-  "name": "Project Assistant",
-  "parentId": "0",
-  "sortOrder": 10
-}
-```
-
-Required scope:
-
-1. `agent.category.create`
-
-### 4. Update Category
-
-```json
-{
-  "action": "update_category",
-  "categoryId": "20001",
-  "name": "On-call Assistant",
-  "parentId": "0",
-  "sortOrder": 20
-}
-```
-
-Required scope:
-
-1. `agent.category.update`
-
-### 5. Assign or Clear Category
-
-```json
-{
-  "action": "assign_category",
-  "agentId": "10001",
-  "categoryId": "20001"
-}
-```
-
-Clear category:
-
-```json
-{
-  "action": "assign_category",
-  "agentId": "10001",
-  "categoryId": "0"
-}
-```
-
-Required scope:
-
-1. `agent.category.assign`
-
-## Local Bind Steps
-
-After remote agent parameters are complete, continue with local binding through the official OpenClaw CLI:
-
-1. Prepare local directories:
-   - `workspace=~/.openclaw/workspace-<agent_name>`
-   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
-   - Add minimal `IDENTITY.md`, `SOUL.md`, `AGENTS.md` when required persona files are missing
-2. Resolve `model` in this order:
-   - The existing `model` from that local agent's entry
-   - `agents.defaults.model.primary`
-   - If still unavailable, clearly report error and stop
-3. Read current config and merge:
-   - `channels.grix.accounts`
-   - `agents.list`
-   - `tools.profile`
-   - `tools.alsoAllow`
-   - `tools.sessions.visibility`
-4. Write back using official CLI:
-   - `channels.grix.accounts.<agent_name>`
-   - `agents.list`
-   - `openclaw agents bind --agent <agent_name> --bind grix:<agent_name>`
-   - `tools.profile`
-   - `tools.alsoAllow`
-   - `tools.sessions.visibility`
-   - If needed, restore `channels.grix.enabled=true`
-5. After writing, perform static validation first:
-   - `openclaw config validate`
-   - `openclaw config get --json channels.grix.accounts.<agent_name>`
-   - `openclaw config get --json agents.list`
-   - `openclaw agents bindings --agent <agent_name> --json`
-6. If this invocation already has real verification conditions, must immediately perform a real routing verification; reuse the current install/acceptance context, do not invent additional probes. Reply falling to the main agent, default assistant, old persona, or old config are all considered failures.
-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".
-
-## `bind-local` Input Contract
-
-```json
-{
-  "task": "bind-local\nagent_name=grix-main\nagent_id=2029786829095440384\napi_endpoint=wss://grix.dhf.pub/v1/agent-api/ws?agent_id=2029786829095440384\napi_key=ak_xxx\ndo_not_create_remote_agent=true"
-}
-```
-
-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.
-
-## `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`:
-
-```json
-{
-  "task": "create-and-bind\nagentName=ops helper\nintroduction=Handles deployment and on-call collaboration\nisMain=false\ncategoryName=Project Assistant\nparentCategoryId=0\ncategorySortOrder=10"
-}
-```
-
-This mode requires steps in order:
-
-1. First 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
-3. If the caller used a legacy path, or the return does not include the category assignment result, supplement with:
-   - `categoryId` -> `action=assign_category`
-   - `categoryName` -> `action=list_categories`
-   - Not found -> `action=create_category`
-   - After obtaining category ID -> `action=assign_category`
-4. Finally follow the same local binding and runtime convergence flow as `bind-local`
-
-Notes:
-
-1. `categoryId` and `categoryName` cannot be provided simultaneously
-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
-
-## `category-manage` Input Contract
-
-When only doing subsequent category management, enter through `grix_admin.task`:
-
-```json
-{
-  "task": "category-manage\noperation=assign\nagentId=10001\ncategoryId=0"
-}
-```
-
-Mapping:
-
-1. `operation=list` -> `action=list_categories`
-2. `operation=create` -> `action=create_category`
-3. `operation=update` -> `action=update_category`
-4. `operation=assign` -> `action=assign_category`
-
-Notes:
-
-1. For `operation=assign`, `categoryId=0` means clear the category
-2. No step can be executed cross-account
-3. Do not hand-write HTTP or fall back to legacy scripts
+# API Contract
+
+## Purpose
+
+`grix-admin` is responsible for local binding and runtime convergence, and when the current agent has the corresponding scope, supports completing the following through `grix_admin` via WS:
+
+1. Create new remote API agents
+2. Query agent categories under the current account
+3. Create categories
+4. Modify categories
+5. Assign or clear categories for specified agents
+
+## Base Rules
+
+1. Do not ask users to provide website account/password for this flow.
+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.
+
+## Direct `grix_admin` Contract
+
+### 1. Create Remote Agent
+
+```json
+{
+  "action": "create_agent",
+  "agentName": "ops helper",
+  "introduction": "Handles deployment and on-call collaboration",
+  "isMain": false,
+  "categoryName": "Project Assistant",
+  "parentCategoryId": "0",
+  "categorySortOrder": 10
+}
+```
+
+Key fields to read from the return:
+
+1. `createdAgent.id`
+2. `createdAgent.agent_name`
+3. `createdAgent.api_endpoint`
+4. `createdAgent.api_key`
+
+Required scope:
+
+1. `agent.api.create`
+2. If `categoryName` is included, may additionally need `agent.category.list`, `agent.category.create`, `agent.category.assign`
+3. If `categoryId` is included, additionally needs `agent.category.assign`
+
+### 2. List Categories
+
+```json
+{
+  "action": "list_categories"
+}
+```
+
+Required scope:
+
+1. `agent.category.list`
+
+### 3. Create Category
+
+```json
+{
+  "action": "create_category",
+  "name": "Project Assistant",
+  "parentId": "0",
+  "sortOrder": 10
+}
+```
+
+Required scope:
+
+1. `agent.category.create`
+
+### 4. Update Category
+
+```json
+{
+  "action": "update_category",
+  "categoryId": "20001",
+  "name": "On-call Assistant",
+  "parentId": "0",
+  "sortOrder": 20
+}
+```
+
+Required scope:
+
+1. `agent.category.update`
+
+### 5. Assign or Clear Category
+
+```json
+{
+  "action": "assign_category",
+  "agentId": "10001",
+  "categoryId": "20001"
+}
+```
+
+Clear category:
+
+```json
+{
+  "action": "assign_category",
+  "agentId": "10001",
+  "categoryId": "0"
+}
+```
+
+Required scope:
+
+1. `agent.category.assign`
+
+## Local Bind Steps
+
+After remote agent parameters are complete, continue with local binding through the official OpenClaw CLI:
+
+1. Prepare local directories:
+   - `workspace=~/.openclaw/workspace-<agent_name>`
+   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
+   - Add minimal `IDENTITY.md`, `SOUL.md`, `AGENTS.md` when required persona files are missing
+2. Resolve `model` in this order:
+   - The existing `model` from that local agent's entry
+   - `agents.defaults.model.primary`
+   - If still unavailable, clearly report error and stop
+3. Read current config and merge:
+   - `channels.grix.accounts`
+   - `agents.list`
+   - `tools.profile`
+   - `tools.alsoAllow`
+   - `tools.sessions.visibility`
+4. Write back using official CLI:
+   - `channels.grix.accounts.<agent_name>`
+   - `agents.list`
+   - `openclaw agents bind --agent <agent_name> --bind grix:<agent_name>`
+   - `tools.profile`
+   - `tools.alsoAllow`
+   - `tools.sessions.visibility`
+   - If needed, restore `channels.grix.enabled=true`
+5. After writing, perform static validation first:
+   - `openclaw config validate`
+   - `openclaw config get --json channels.grix.accounts.<agent_name>`
+   - `openclaw config get --json agents.list`
+   - `openclaw agents bindings --agent <agent_name> --json`
+6. If this invocation already has real verification conditions, must immediately perform a real routing verification; reuse the current install/acceptance context, do not invent additional probes. Reply falling to the main agent, default assistant, old persona, or old config are all considered failures.
+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".
+
+## `bind-local` Input Contract
+
+```json
+{
+  "task": "bind-local\nagent_name=grix-main\nagent_id=2029786829095440384\napi_endpoint=wss://grix.dhf.pub/v1/agent-api/ws?agent_id=2029786829095440384\napi_key=ak_xxx\ndo_not_create_remote_agent=true"
+}
+```
+
+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.
+
+## `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`:
+
+```json
+{
+  "task": "create-and-bind\nagentName=ops helper\nintroduction=Handles deployment and on-call collaboration\nisMain=false\ncategoryName=Project Assistant\nparentCategoryId=0\ncategorySortOrder=10"
+}
+```
+
+This mode requires steps in order:
+
+1. First 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
+3. If the caller used a legacy path, or the return does not include the category assignment result, supplement with:
+   - `categoryId` -> `action=assign_category`
+   - `categoryName` -> `action=list_categories`
+   - Not found -> `action=create_category`
+   - After obtaining category ID -> `action=assign_category`
+4. Finally follow the same local binding and runtime convergence flow as `bind-local`
+
+Notes:
+
+1. `categoryId` and `categoryName` cannot be provided simultaneously
+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
+
+## `category-manage` Input Contract
+
+When only doing subsequent category management, enter through `grix_admin.task`:
+
+```json
+{
+  "task": "category-manage\noperation=assign\nagentId=10001\ncategoryId=0"
+}
+```
+
+Mapping:
+
+1. `operation=list` -> `action=list_categories`
+2. `operation=create` -> `action=create_category`
+3. `operation=update` -> `action=update_category`
+4. `operation=assign` -> `action=assign_category`
+
+Notes:
+
+1. For `operation=assign`, `categoryId=0` means clear the category
+2. No step can be executed cross-account
+3. Do not hand-write HTTP or fall back to legacy scripts

package/openclaw-plugin/skills/grix-egg/SKILL.md

@@ -1,81 +1,81 @@
----
-name: grix-egg
-description: Program-driven hatching: AI only organizes parameters and calls `grix_egg`; the program handles creation, installation, binding, acceptance, and status reporting.
----
-
-# Grix Egg
-
-`grix-egg` follows a "program-first, AI-assists" approach.
-AI no longer manually relays create/bind/accept.
-
-## 1. AI Role Boundary
-
-You only do three things:
-
-1. Organize user input into standard parameters
-2. Call `grix_egg`
-3. Report results / request supplementary parameters based on the returned JSON
-
-Do not manually execute these actions:
-
-1. Remote agent creation
-2. Local bind
-3. Gateway operations
-4. Test group acceptance
-
-## 2. Standard Call Entry
-
-Prefer passing the raw install card:
-
-```json
-{ "installContext": "<raw json>" }
-```
-
-If there is no install card, pass structured parameters:
-
-1. `route`: `create_new` | `existing` | `existing_claude`
-2. `agentName`
-3. `agentIdSlug` or `localAgentName`
-4. `downloadUrl`
-5. `existingCredentials` (required for `existing`)
-6. Optional: `packageHash`, `soulContent`, `soulFile`, `categoryId`, `categoryName`, `isMain`, `expectedSubstring`, `statusTarget`, `resume`, `installId`
-
-## 3. Route Behavior
-
-1. `create_new`: program automatically completes creation, installation, binding, acceptance, and status reporting
-2. `existing`: program automatically completes existing credential installation and acceptance
-3. `existing_claude`: program returns `unsupported_route`, handled by a standalone Claude installer
-
-## 4. Acceptance Rules
-
-Program has fixed acceptance logic:
-
-1. Test group members must include: main agent, trigger user, target agent
-2. Probe uses `@<target_agent_id>` mention
-3. Only the first non-empty reply after the probe from the target agent is accepted
-4. `expectedSubstring` is only an optional enhancement condition
-
-## 5. Result Reporting
-
-When `ok=true`:
-
-1. Report `install_id`, `route`, target agent, acceptance result
-2. If `acceptance.reply_content` and `testGroup` are present, include them for the user
-3. If `interaction_status=degraded`, explain that the main flow succeeded but status reporting partially failed
-
-When `ok=false`:
-
-1. Use `reason` and `suggestion` directly to explain the failure
-2. Only supplement external inputs that the program explicitly identifies as missing
-3. Use `resume=true` + `installId` when continuation is needed
-
-## 6. Prohibited Actions
-
-1. Do not use `curl`/`fetch`/`axios` to directly connect to `/v1/agent-api`
-2. Do not manually modify `openclaw.json`
-3. Remote actions must only go through typed tools: `grix_admin`, `grix_group`, `grix_query`
-4. Do not claim installation success before acceptance is complete
-
-## References
-
-1. [references/api-contract.md](references/api-contract.md)
+---
+name: grix-egg
+description: Program-driven hatching: AI only organizes parameters and calls `grix_egg`; the program handles creation, installation, binding, acceptance, and status reporting.
+---
+
+# Grix Egg
+
+`grix-egg` follows a "program-first, AI-assists" approach.
+AI no longer manually relays create/bind/accept.
+
+## 1. AI Role Boundary
+
+You only do three things:
+
+1. Organize user input into standard parameters
+2. Call `grix_egg`
+3. Report results / request supplementary parameters based on the returned JSON
+
+Do not manually execute these actions:
+
+1. Remote agent creation
+2. Local bind
+3. Gateway operations
+4. Test group acceptance
+
+## 2. Standard Call Entry
+
+Prefer passing the raw install card:
+
+```json
+{ "installContext": "<raw json>" }
+```
+
+If there is no install card, pass structured parameters:
+
+1. `route`: `create_new` | `existing` | `existing_claude`
+2. `agentName`
+3. `agentIdSlug` or `localAgentName`
+4. `downloadUrl`
+5. `existingCredentials` (required for `existing`)
+6. Optional: `packageHash`, `soulContent`, `soulFile`, `categoryId`, `categoryName`, `isMain`, `expectedSubstring`, `statusTarget`, `resume`, `installId`
+
+## 3. Route Behavior
+
+1. `create_new`: program automatically completes creation, installation, binding, acceptance, and status reporting
+2. `existing`: program automatically completes existing credential installation and acceptance
+3. `existing_claude`: program returns `unsupported_route`, handled by a standalone Claude installer
+
+## 4. Acceptance Rules
+
+Program has fixed acceptance logic:
+
+1. Test group members must include: main agent, trigger user, target agent
+2. Probe uses `@<target_agent_id>` mention
+3. Only the first non-empty reply after the probe from the target agent is accepted
+4. `expectedSubstring` is only an optional enhancement condition
+
+## 5. Result Reporting
+
+When `ok=true`:
+
+1. Report `install_id`, `route`, target agent, acceptance result
+2. If `acceptance.reply_content` and `testGroup` are present, include them for the user
+3. If `interaction_status=degraded`, explain that the main flow succeeded but status reporting partially failed
+
+When `ok=false`:
+
+1. Use `reason` and `suggestion` directly to explain the failure
+2. Only supplement external inputs that the program explicitly identifies as missing
+3. Use `resume=true` + `installId` when continuation is needed
+
+## 6. Prohibited Actions
+
+1. Do not use `curl`/`fetch`/`axios` to directly connect to `/v1/agent-api`
+2. Do not manually modify `openclaw.json`
+3. Remote actions must only go through typed tools: `grix_admin`, `grix_group`, `grix_query`
+4. Do not claim installation success before acceptance is complete
+
+## References
+
+1. [references/api-contract.md](references/api-contract.md)

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

@@ -1,40 +1,40 @@
-# API Contract
-
-## Purpose
-
-Keep `grix-egg` deterministic and tool-bounded:
-AI only provides params, program executes.
-
-## Required Paths
-
-1. Remote create/category actions: `grix_admin`
-2. Group lifecycle and membership actions: `grix_group`
-3. Message/session query actions: `grix_query`
-4. Local bind/update actions: official `openclaw` CLI (`config set`, `agents bind`, `config validate`)
-
-## Prohibited Paths
-
-1. Do not call `/v1/agent-api` using `curl`, `fetch`, `axios`, or ad hoc scripts.
-2. Do not hand-edit `openclaw.json`.
-3. Do not bypass typed tools with hidden protocol payloads.
-
-## Delivery Rules
-
-Program should emit these links on the install private chat:
-
-1. Running/failed/success status card:
-   `grix://card/egg_install_status`
-2. Acceptance group entry card:
-   `grix://card/conversation`
-3. Final profile card on success:
-   `grix://card/user_profile`
-
-If delivery fails, mark `interaction_status=degraded` but keep the main installation result unchanged.
-
-## Acceptance Rules
-
-1. Acceptance group must include:
-   main agent, trigger user, target agent.
-2. Probe uses `@<target_agent_id>` mention.
-3. Only the first non-empty reply after probe is valid.
-4. `expectedSubstring` is an optional additional condition.
+# API Contract
+
+## Purpose
+
+Keep `grix-egg` deterministic and tool-bounded:
+AI only provides params, program executes.
+
+## Required Paths
+
+1. Remote create/category actions: `grix_admin`
+2. Group lifecycle and membership actions: `grix_group`
+3. Message/session query actions: `grix_query`
+4. Local bind/update actions: official `openclaw` CLI (`config set`, `agents bind`, `config validate`)
+
+## Prohibited Paths
+
+1. Do not call `/v1/agent-api` using `curl`, `fetch`, `axios`, or ad hoc scripts.
+2. Do not hand-edit `openclaw.json`.
+3. Do not bypass typed tools with hidden protocol payloads.
+
+## Delivery Rules
+
+Program should emit these links on the install private chat:
+
+1. Running/failed/success status card:
+   `grix://card/egg_install_status`
+2. Acceptance group entry card:
+   `grix://card/conversation`
+3. Final profile card on success:
+   `grix://card/user_profile`
+
+If delivery fails, mark `interaction_status=degraded` but keep the main installation result unchanged.
+
+## Acceptance Rules
+
+1. Acceptance group must include:
+   main agent, trigger user, target agent.
+2. Probe uses `@<target_agent_id>` mention.
+3. Only the first non-empty reply after probe is valid.
+4. `expectedSubstring` is an optional additional condition.