grix-connector 4.2.3 → 4.2.4

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

@@ -1,310 +1,76 @@
 ---
 name: grix-update
-description: Handles subsequent version maintenance of the Grix plugin. Applicable for checking new versions, performing plugin upgrades, completing post-upgrade validation and restart, and silently or notifying the main agent according to rules; not responsible for initial installation, account registration, local binding, or install private chat flows.
+description: Version maintenance for the Grix OpenClaw plugin — check for a new version, apply the upgrade, validate and restart, and notify according to fixed rules. Not for initial installation, account registration, local binding, or egg install chats.
 ---
 
 # Grix Update
 
-This skill is solely responsible for **Grix plugin version maintenance**.  
-The goal is to enable `grix-connector`, once installed into OpenClaw, to perform update checks, upgrade acceptance, and failure alerts according to fixed rules.
-
-## Role Boundary
-
-1. This skill only performs plugin update-related actions: check, upgrade, validate, restart, notify.
-2. This skill does not perform initial installation, account registration, or agent binding.
-3. This skill does not take over install private chats; if the current context is still in an egg install flow, stop and hand back to `grix-egg` / `grix-admin`.
-4. Only use the official OpenClaw CLI; do not manually edit `openclaw.json` or write temporary scripts to modify the plugin install directory.
-
-## Applicable Scenarios
-
-1. User requests "check if grix has a new version".
-2. User requests "upgrade the grix plugin".
-3. Need to provide a standalone maintenance skill for subsequent automation.
-4. Scheduled tasks want to silently check, only notifying the main agent on failure.
-
-## Input Parameters
-
-### Common Parameters
-
-1. `mode` (required)
-   - `check-only`
-   - `apply-update`
-   - `check-and-apply`
-2. `plugin_id` (optional)
-   - Default: `grix`
-3. `notify_on` (optional)
-   - `failure` (default)
-   - `always`
-   - `never`
-4. `main_agent` (optional)
-   - Primarily used for cron's `--agent <main_agent>` or upper-level workflow marking "who is responsible for maintaining this machine"
-   - It is not itself a directly deliverable `to` / `session_id` target for Grix messages; if there is no explicit deliverable session, do not guess a notification target just because you have `main_agent`
-5. `allow_restart` (optional)
-   - Default: `true`
-
-### Recommended Default Input
-
-```json
-{
-  "mode": "check-and-apply",
-  "plugin_id": "grix",
-  "notify_on": "failure",
-  "allow_restart": true
-}
-```
-
-## Completion Standard
-
-Only when all of the following conditions are met is the task considered complete:
-
-1. Confirmed whether the target plugin exists.
-2. Confirmed whether the current installation method supports automatic updates.
-3. Executed the check action and provided a clear result: no update / upgraded / failed / unsupported.
-4. If an upgrade was performed, completed:
-   - `openclaw plugins doctor`
-   - `openclaw gateway restart` (only when `allow_restart=true`)
-   - `openclaw health`
-5. If notification rules are configured, completed notification or silently ended according to the rules.
-
-## Execution Rules
-
-### 0. Context Guard First
-
-1. If the current context is clearly an egg install private chat, or the context contains install-related fields like `install_id`, `egg`, `install.route`, do not perform the update — state that the current scenario is not suitable for plugin upgrade and stop.
-2. Do not trigger plugin upgrades during an ongoing installation conversation.
-
-### 1. Confirm Plugin Exists First
-
-Execute first:
-
-```bash
-openclaw plugins info <plugin_id> --json
-```
-
-Rules:
-
-1. If the plugin does not exist, return `failed/not_installed` and stop.
-2. If the command fails, return the failure reason; do not continue guessing.
-
-### 2. Confirm Whether Automatic Update Is Supported
-
-Execute first:
-
-```bash
-openclaw plugins update <plugin_id> --dry-run
-```
-
-Rules:
-
-1. If dry-run explicitly indicates the current plugin cannot be updated, is not tracked, or is not an npm install, return `unsupported/not_npm_install` and stop.
-2. Only proceed with subsequent steps when updates are supported.
-3. Do not force local directory installs, `--link` installs, or manual copy installs to be treated as auto-updatable.
-
-### 3. `check-only`
-
-Only check, do not upgrade.
-
-Rules:
-
-1. Run dry-run.
-2. If no new version:
-   - Return `no_update`
-   - Silently end by default
-3. If a new version is found:
-   - Return `update_available`
-   - Do not perform the actual upgrade
-
-### 4. `apply-update`
-
-Assumes the caller has already decided to upgrade; execute the upgrade directly.
-
-Execution order:
-
-```bash
-openclaw plugins update <plugin_id>
-openclaw plugins doctor
-openclaw gateway restart
-openclaw health
-```
-
-Rules:
-
-1. If `allow_restart=false`, skip `openclaw gateway restart`, but clearly state that the upgrade has not been restarted and the runtime may still be the old version.
-2. If any step fails, stop immediately and return the failure point.
-3. Do not automatically retry consecutively after failure.
-
-### 5. `check-and-apply`
-
-This is the most suitable mode for automation.
-
-Rules:
-
-1. Run dry-run first.
-2. If no new version:
-   - Return `no_update`
-   - Silently end
-3. If a new version is found:
-   - Execute the full `apply-update` flow
-
-## Validation Order
-
-If an upgrade was performed, validation must follow this order:
-
-1. `openclaw plugins doctor`
-2. `openclaw gateway restart` (if allowed)
-3. `openclaw health`
-
-Do not claim success immediately after writing the upgrade command.
-
-## Notification Rules
-
-The behavior of `notify_on` is fixed as follows:
-
-1. `never`
-   - Never send notifications
-2. `failure`
-   - Only notify the main agent on failure
-3. `always`
-   - Notify the main agent on both success and failure
-
-Supplementary rules:
-
-1. `main_agent` only represents the maintenance responsibility owner; it does not automatically equate to a message-deliverable session target.
-2. If the current context has no explicit maintenance session or reusable notification target, just return the result and let the upper-level cron / caller handle notification; do not guess `to`, `session_id`, or private chat targets on your own.
-3. Cron scenarios should prefer `notify_on=never`; let the cron run records handle convergence.
-
-Default is `failure`.
-
-## Notification Content Requirements
-
-Notifications must be brief, stating only the result without expanding on technical details.
-
-Recommended copy style:
-
-1. Success:
-   - `Grix plugin upgrade completed, current checks are normal.`
-2. No update:
-   - `Grix plugin checked, no new version available.`
-3. Failure:
-   - `Grix plugin auto-update failed, stuck at <step>.`
-4. Auto-update not supported:
-   - `Grix is not installed in an auto-updatable way; switch to npm install before enabling auto-update.`
-
-## Return Results
-
-The skill should return clear, stable result states, recommended to converge to these categories:
-
-1. `no_update`
-2. `update_available`
-3. `updated`
-4. `failed`
-5. `unsupported`
-
-If failed, must specify which step the failure belongs to:
-
-1. `plugins info`
-2. `plugins update --dry-run`
-3. `plugins update`
-4. `plugins doctor`
-5. `gateway restart`
-6. `health`
-
-## Guardrails
-
-1. Do not modify initial installation logic; do not replace `grix-register`, `grix-admin`, `grix-egg`.
-2. Do not perform plugin upgrades during install private chats.
-3. Only use official commands:
-   - `openclaw plugins info`
-   - `openclaw plugins update`
-   - `openclaw plugins doctor`
-   - `openclaw gateway restart`
-   - `openclaw health`
-4. Do not directly modify the plugin directory or manually overwrite npm package contents.
-5. Do not write bypass logic to "accommodate" old installation methods; unsupported means unsupported.
-6. If the upgrade has not been restarted, do not claim the runtime has completed the switch.
-7. Do not automatically retry at high frequency; after failure, hand off to the next scheduled cycle or manual intervention.
-
-## Recommended Automation Integration
-
-When used for scheduled tasks, prefer:
-
-```json
-{
-  "mode": "check-and-apply",
-  "plugin_id": "grix",
-  "notify_on": "failure",
-  "main_agent": "main",
-  "allow_restart": true
-}
-```
-
-Recommended frequency:
-
-1. Once per day
-2. Or once every 6 hours
-
-Default strategy:
-
-1. No update: silent
-2. Update successful: silent
-3. Update failed: notify main agent
-
-## Recommended Cron Setup
-
-If you want automatic maintenance after plugin installation, it is recommended to create an isolated cron task directly, rather than embedding the upgrade action into the main session heartbeat.
-
-Recommended command:
-
-```bash
-openclaw cron add \
-  --name "grix auto update" \
-  --every "6h" \
-  --agent <main_agent> \
-  --session isolated \
-  --light-context \
-  --no-deliver \
-  --message 'Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}. If there is no update or the update succeeds, reply exactly NO_REPLY. If the install is unsupported or any step fails, return one short failure summary.'
-```
-
-Rules:
-
-1. `--session isolated`: Do not bind to the main session to avoid updates and restarts interrupting the current chat.
-2. `--no-deliver`: Stay silent on success.
-3. `notify_on` in cron scenarios should be fixed to `never`; let the cron's own run records handle troubleshooting.
-4. `main_agent` should use the main agent responsible for maintaining this machine.
-5. Recommended frequency starts at `6h`; if you want to be more conservative, change to once per day.
-
-If a task with the same name already exists, do not create a duplicate; use edit instead:
-
-```bash
-openclaw cron edit <job_id> \
-  --every "6h" \
-  --agent <main_agent> \
-  --session isolated \
-  --light-context \
-  --no-deliver \
-  --message 'Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}. If there is no update or the update succeeds, reply exactly NO_REPLY. If the install is unsupported or any step fails, return one short failure summary.'
-```
-
-After creation, it is recommended to verify:
-
-```bash
-openclaw cron list
-openclaw cron status
-```
-
-## Division of Responsibilities with Other Skills
-
-1. `grix-register`
-   - Only responsible for cloud account and API agent parameters
-2. `grix-admin`
-   - Only responsible for local configuration and binding
-3. `grix-egg`
-   - Only responsible for the install private chat flow
-4. `grix-update`
-   - Only responsible for subsequent version maintenance
-
-## References
-
-1. [references/update-contract.md](references/update-contract.md)
-2. [references/cron-setup.md](references/cron-setup.md)
+Maintains the installed Grix plugin: check → upgrade → validate → restart →
+notify. Uses only the official OpenClaw CLI; never edits `openclaw.json`, the
+plugin directory, or npm package contents by hand.
+
+Not this skill's job: initial installation, registration, agent binding
+(`grix-register`, `grix-admin`, `grix-egg`). If the current context is an egg
+install chat or carries install fields (`install_id`, `egg`, `install.route`),
+say the scenario is not suitable for a plugin upgrade and stop.
+
+## Inputs
+
+| Field | Values | Default |
+|---|---|---|
+| `mode` (required) | `check-only` \| `apply-update` \| `check-and-apply` | — |
+| `plugin_id` | plugin id | `grix` |
+| `notify_on` | `failure` \| `always` \| `never` | `failure` |
+| `allow_restart` | boolean | `true` |
+| `main_agent` | maintainer marker for cron `--agent`; **not** a message target | — |
+
+Recommended automation input: `{"mode":"check-and-apply","plugin_id":"grix","notify_on":"failure","allow_restart":true}`.
+
+## Procedure
+
+1. `openclaw plugins info <plugin_id> --json` — plugin missing → result
+   `failed` at step `plugins info` (`not_installed`); stop.
+2. `openclaw plugins update <plugin_id> --dry-run` — if it says the plugin is
+   not tracked / not an npm install / cannot be updated → `unsupported`
+   (`not_npm_install`); stop. Never treat local-directory, `--link`, or
+   copied installs as updatable.
+3. No new version → `no_update`; end silently.
+4. New version and `mode=check-only` → `update_available`; do not upgrade.
+5. New version and `mode` is `apply-update` / `check-and-apply` → run in
+   order, stopping at the first failure (no automatic retry):
+   ```bash
+   openclaw plugins update <plugin_id>
+   openclaw plugins doctor
+   openclaw gateway restart      # skip when allow_restart=false
+   openclaw health
+   ```
+   If the restart was skipped, state that the runtime may still be the old
+   version. Success → `updated`. Never claim success before `health` passes.
+
+## Result
+
+Return one of `no_update` / `update_available` / `updated` / `failed` /
+`unsupported`. For `failed`, name the step: `plugins info`,
+`plugins update --dry-run`, `plugins update`, `plugins doctor`,
+`gateway restart`, or `health`.
+
+## Notification
+
+`never` → none; `failure` → only on failure; `always` → success and failure.
+Keep it to one line, e.g. "Grix plugin upgrade completed, current checks are
+normal." / "Grix plugin auto-update failed, stuck at <step>." / "Grix is not
+installed in an auto-updatable way; switch to npm install before enabling
+auto-update."
+
+Send a notification only when the context has an explicit deliverable
+session; `main_agent` is not one. Otherwise just return the result and let
+the caller or cron records handle it. In cron runs use `notify_on=never`.
+
+## Scheduled maintenance
+
+For automatic maintenance create an isolated cron job (`--session isolated
+--no-deliver`, every 6h or daily) rather than embedding upgrades in the main
+session; edit the existing job instead of creating a duplicate. Commands and
+the recommended message are in [references/cron-setup.md](references/cron-setup.md);
+the full state/notification contract is in
+[references/update-contract.md](references/update-contract.md).

package/openclaw-plugin/skills/message-send/SKILL.md

@@ -1,197 +1,66 @@
 ---
 name: message-send
-description: Send messages. Supports current session replies and cross-session sending. For cross-session, use an exact `session_id` or an existing `route.sessionKey` as the `to` target; do not use the legacy `target=agent:...` format. Trigger words: send DM, DM, send message, notify.
+description: Send messages through OpenClaw's `message` tool on the Grix channel — reply in the current session, or send to another session by its exact `session_id` in `to`. Also defines the `grix://card/conversation` link for pointing the user at a chat. Trigger words: send DM, DM, send message, notify.
 ---
 
-# Message Send Skill
+# Message Send
 
-This skill is used to send messages through OpenClaw's `message` tool.
+Send messages with OpenClaw's `message` tool, `action: "send"`,
+`channel: "grix"`.
 
-## Two Sending Modes
+## Parameters
 
-### 1. Current Session Reply
+| Parameter | Required | Value |
+|---|---|---|
+| `action` | ✅ | `"send"` |
+| `channel` | ✅ | `"grix"` |
+| `accountId` | ✅ | the current Grix account ID (never hardcode `default`) |
+| `message` | ✅ | text; plain text and Markdown are supported |
+| `to` | cross-session only | exact Grix `session_id` (usually a UUID), or an existing `route.sessionKey` |
 
-If replying to the current Grix session, send directly without providing an additional target session.
-
-**Parameters**:
-- `action`: "send"
-- `channel`: "grix"
-- `accountId`: current account ID
-- `message`: message content
-
-**Example**:
+- **Current session reply**: omit `to`.
+- **Another session**: set `to` to the bare `session_id`, e.g.
+  `to=e72ce987-2d2e-40ed-bcc9-b336b4974512`. `grix:<id>` / `session:<id>`
+  are parsed for compatibility but are not the default. Never use
+  `target=agent:…`, a bare numeric user/agent ID (fails, no auto-conversion),
+  or an invented alias.
 
 ```json
-{
-  "action": "send",
-  "channel": "grix",
-  "accountId": "{accountId}",
-  "message": "Got it, processing now..."
-}
+{ "action": "send", "channel": "grix", "accountId": "{accountId}", "to": "{sessionId}", "message": "Task completed, please check the results." }
 ```
 
-### 2. Cross-Session Sending
-
-If sending to another private chat or group chat, use `to` to point to the target session.
-
-**Parameters**:
-- `action`: "send"
-- `channel`: "grix"
-- `accountId`: current account ID
-- `to`: target session identifier
-- `message`: message content
-
-**Example**:
-
-```json
-{
-  "action": "send",
-  "channel": "grix",
-  "accountId": "{accountId}",
-  "to": "{targetSessionId}",
-  "message": "Need your confirmation on a development decision: ..."
-}
-```
+Finding the target: reuse a `session_id` already known from context or
+MEMORY.md; otherwise resolve it with `grix_query` (`session_search`). Confirm
+the account may send to that session, and do not spam proactive messages.
 
-## Real Format of `to`
+Errors: unresolvable `to` → check the `session_id`; permission denied → the
+account cannot send to that session; missing parameter → supply it.
 
-The current plugin recognizes these two types of targets:
+## Conversation card — `grix://card/conversation`
 
-1. Exact Grix `session_id` (recommended, usually a UUID)
-2. An existing `route.sessionKey` in the current runtime
-
-Recommended to pass the bare `session_id` directly:
+When you want the user to **open a group or private chat** and you already
+know its exact `session_id`, send a card link instead of prose or a web link;
+the client renders it as a clickable conversation card.
 
 ```text
-to=e72ce987-2d2e-40ed-bcc9-b336b4974512
+[Open Group](grix://card/conversation?session_id=<SESSION_ID>&session_type=group&title=<ENCODED_TITLE>)
+[Open Conversation](grix://card/conversation?session_id=<SESSION_ID>&session_type=private&title=<ENCODED_TITLE>&peer_id=<ENCODED_PEER_ID>)
 ```
 
-In compatible formats, `grix:<session_id>` or `session:<session_id>` can also be parsed, but should not be used as the default format.
-
-Do not use these legacy formats:
-
-1. `target=agent:{agentId}:grix:direct:{sessionId}`
-2. Pure numeric user ID / agent ID
-3. Non-existent session aliases
-
-## How to Obtain the Target Session
-
-1. If replying to the current session, simply omit `to`
-2. If MEMORY.md already records the target `session_id`, reuse it directly
-3. If the target session is unknown, first use `grix_query`'s `session_search` to find the exact `session_id`
+- `session_id` (required, exact), `session_type` (required: `group` |
+  `private`), `title` (required, shown to the user), `peer_id` (private only,
+  optional).
+- URI-component-encode `title`, `peer_id`, and any other text value; the link
+  text outside the parentheses is plain copy and needs no encoding.
+- The card must be **one line, alone in its own message** — one card per
+  message; put any explanation in a separate message sent first.
+- No `session_id` → plain-text explanation only; never fabricate a card.
+- Never emit `chat://…` links, "click here" prose, or frontend-internal
+  `biz_card` JSON.
 
 Example:
 
-```json
-{
-  "action": "send",
-  "channel": "grix",
-  "accountId": "{accountId}",
-  "to": "{groupSessionId}",
-  "message": "Task completed, please check the results"
-}
-```
-
-## Key Parameter Reference
-
-| Parameter | Required | Description |
-|------|------|------|
-| `action` | ✅ | Fixed value `"send"` |
-| `channel` | ✅ | Fixed value `"grix"` |
-| `accountId` | ✅ | Current Grix account ID |
-| `message` | ✅ | Message content |
-| `to` | Required for cross-session | Exact `session_id` or resolvable `route.sessionKey` |
-
-## Important Notes
-
-1. Use `to`, not `target`
-2. `to` should preferably be an exact `session_id`; do not confuse user ID, agent ID, and session ID
-3. Pure numeric targets will fail directly; they will not auto-convert to private chats
-4. Before sending cross-session messages, confirm the current account has send permission for the target session
-5. Message content supports plain text and markdown
-
-## Conversation Card Message Protocol
-
-When the message content is **reminding the user to open a group chat**, **open a private chat conversation**, or **referencing a specific conversation entry point**, and you already have the exact `session_id`, do not send natural language links or frontend internal JSON; you must send a standalone `grix://card/conversation` Markdown link, which the frontend will uniformly parse and render as a clickable conversation card.
-
-### Standard Format
-
-Group chat:
-
 ```text
-[Open Group](grix://card/conversation?session_id=<SESSION_ID>&session_type=group&title=<URI_ENCODED_GROUP_TITLE>)
-```
-
-Private chat:
-
-```text
-[Open Conversation](grix://card/conversation?session_id=<SESSION_ID>&session_type=private&title=<URI_ENCODED_CHAT_TITLE>&peer_id=<URI_ENCODED_PEER_ID>)
-```
-
-### Field Rules
-
-- `session_id`: Required. Must be the exact target session ID.
-- `session_type`: Required. Can only be `group` or `private`.
-- `title`: Required. The group title or private chat title displayed to the user.
-- `peer_id`: Optional for private chat only. Used to supplement private chat peer information, but frontend open behavior is still based on `session_id`.
-
-### Encoding Rules
-
-To prevent spaces, newlines, or reserved characters in titles, nicknames, URLs, and other fields from breaking the link, query parameter values should be URI component encoded before being written into the `grix://card` link.
-
-- Recommended: uniformly apply URI component encoding to `title`, `peer_id`, and any future text fields
-- `session_id` and `session_type` can be output as-is if they only contain safe characters
-- Link text is plain copy for the user to see and does not need URI encoding
-
-Example:
-
-```text
-[Open Group](grix://card/conversation?session_id=session-9&session_type=group&title=%E4%BA%A7%E5%93%81%E8%AE%A8%E8%AE%BA%E7%BE%A4%20A)
-```
-
-### Usage Requirements
-
-1. Only output a conversation card when the **exact `session_id` is known**
-2. If there is no `session_id`, can only send plain text explanation; cannot fabricate a conversation card
-3. Do not output `chat://...`, web links, or "click here to open session" style natural language link alternatives
-4. Do not construct frontend internal `biz_card` JSON or attempt to send Flutter/frontend private protocol structures
-5. The `grix://card/conversation` link must be on a single line and must be sent as a standalone message
-6. If additional explanation is needed, send the explanation text and the card as two separate messages; do not mix explanation and card in the same message
-7. Do not put multiple cards in the same message; when multiple jump entries are needed, send multiple messages
-8. If field values contain special characters, apply URI component encoding first, then assemble into the link
-
-### Examples
-
-Example 1: Remind user to enter a group chat
-
-```text
-[Open Product Group](grix://card/conversation?session_id=9d6a4b1d-5d37-4e38-ae6a-0c12a2c4c901&session_type=group&title=%E4%BA%A7%E5%93%81%E7%BE%A4)
-```
-
-Example 2: Remind user to enter a private chat
-
-```text
-[Open Alice Conversation](grix://card/conversation?session_id=e72ce987-2d2e-40ed-bcc9-b336b4974512&session_type=private&title=Alice&peer_id=1001)
-```
-
-Example 3: Send explanation and card as two separate messages
-
-```text
-Message 1: The test group has been created. Check the next card to enter directly.
+Message 1: The test group has been created — tap the card below to open it.
 Message 2: [Open Test Group](grix://card/conversation?session_id=0fa947bd-bb4e-46ad-8308-5526bc98e002&session_type=group&title=%E6%B5%8B%E8%AF%95%E7%BE%A4)
 ```
-
-## Error Handling
-
-- `to` cannot be resolved: confirm whether the `session_id` or `route.sessionKey` is correct
-- Insufficient permissions: check whether the current `accountId` has send permission for the target session
-- Missing parameters: ensure all required parameters are provided
-- Target format error: check whether `to` is an exact `session_id` or valid `route.sessionKey`
-
-## Best Practices
-
-1. For cross-session sending, prefer recording and reusing exact `session_id`
-2. When you need to find a session, use `grix_query.session_search` first
-3. Keep message content concise and highlight key points
-4. Do not abuse proactive messages to avoid disturbing the owner
-5. Prefer conversation cards over plain text explanations when navigation is needed