grix-connector 4.2.3 → 4.2.5

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

@@ -3,162 +3,55 @@ name: grix-group
 description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, leave, update, or dissolve groups, or when these operations fail with scope or permission errors.
 ---
 
-# Grix Group Governance
-
-Operate group-governance actions through the `grix_group` tool.  
-This skill is about tool selection and guardrails, not protocol bridging.
-
-## Workflow
-
-1. Parse the user request into one action:
-   `create`, `detail`, `leave`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, or `dissolve`.
-2. Validate required fields before any call.
-3. Call `grix_group` exactly once per business action.
-4. Classify failures by HTTP/BizCode and return exact remediation.
-5. Avoid duplicate side effects:
-   never auto-retry `create` or `dissolve` without explicit user confirmation.
-
-## Tool Contract
-
-For Grix group governance, always call:
-
-1. Tool: `grix_group`
-2. `action`: one of `create`, `detail`, `leave`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, `dissolve`
-3. `accountId`: always pass `{{AccountId}}` from the current conversation context for every action, including `leave`.
-
-Rules:
-
-1. Pass business parameters with their exact typed field names.
-2. Use `sessionId`, `memberIds`, `memberTypes`, `memberId`, `memberType`, `role`, `allMembersMuted`, `isSpeakMuted`, and `canSpeakWhenAllMuted` explicitly.
-3. Do not invent aliases or fallback fields.
-4. Keep one tool call per action for audit clarity.
-
-## Action Contracts
-
-### create
-
-Purpose: create a new group session.
-
-Required input:
-
-1. `name` (non-empty string)
-2. `memberIds` (optional string array; each item numeric text)
-3. `memberTypes` (optional int array; align with `memberIds`)
-
-Guardrails:
-
-1. Ask for clarification if group name is missing.
-2. Ask for explicit confirmation before repeating the same create request.
-3. Treat this action as non-idempotent.
-
-### add_members
-
-Purpose: add members into an existing group.
-
-Required input:
-
-1. `sessionId` (non-empty string)
-2. `memberIds` (non-empty string array; each item numeric text)
-3. `memberTypes` (optional int array; align with `memberIds`)
-
-Guardrails:
-
-1. Reject empty `sessionId` before calling the tool.
-2. Reject non-numeric `memberIds` before calling the tool.
-3. If `sessionId` is ambiguous, ask the user to confirm the target group first.
-
-### leave
-
-Purpose: let the current Agent leave a group by itself.
-
-Required input:
-
-1. `sessionId`
-
-Guardrails:
-
-1. Only execute this when the requester is clearly the current Agent owner, or an already-established authorized operator in the current context.
-2. If the requester identity is unclear, ask for confirmation first; if it is clearly unauthorized, reject directly and do not call `grix_group`.
-3. This action is only for the current Agent leaving its own group membership.
-4. Never translate a request to remove other members into `leave`; use `remove_members` for that.
-5. Do not send `memberId`, `memberIds`, or `memberTypes` with this action.
-6. This action does not require scope and should not be described as a scope-grant workflow.
-7. Execute `leave` silently: do not send any pre-leave or farewell message to the group before leaving.
-
-### remove_members
-
-Required input:
-
-1. `sessionId`
-2. `memberIds`
-
-### update_member_role
-
-Required input:
-
-1. `sessionId`
-2. `memberId`
-3. `role`
-
-Guardrails:
-
-1. Only use `memberType=1` for role updates.
-2. Never guess a role value; confirm when unclear.
-
-### update_all_members_muted
-
-Required input:
-
-1. `sessionId`
-2. `allMembersMuted`
-
-Guardrails:
-
-1. Only use this for group-wide mute state changes.
-2. Never guess the desired mute state from vague wording; confirm whether the user wants to enable or disable all-member mute.
-
-### update_member_speaking
-
-Required input:
-
-1. `sessionId`
-2. `memberId`
-3. At least one of `isSpeakMuted` or `canSpeakWhenAllMuted`
-
-Guardrails:
-
-1. Only use `memberType=1` or `memberType=2`.
-2. Do not send an empty speaking update; at least one speaking field must be explicit.
-3. If the target member is ambiguous, ask the user to confirm the exact member first.
-
-### detail / dissolve
-
-Required input:
-
-1. `sessionId`
-
-## Error Handling Rules
-
-1. `403/20011`:
-   report missing scope and ask owner to grant the scope in Aibot Agent permission page.
-   Do not use this remediation for `leave`, because `leave` is scope-free.
-2. `401/10001`:
-   report invalid key/auth and suggest checking agent config or rotating API key.
-3. `403/10002`:
-   report agent is not active or invalid provider type.
-4. `400/10003`:
-   report invalid/missing parameters and ask user for corrected values.
-5. Other errors:
-   return backend `msg` and stop automatic retries.
-
-## Response Style
-
-1. State action result first.
-2. Include key identifiers (`session_id`, member count, mute state) when successful.
-3. Include exact remediation when failed.
-4. Never hide scope or auth errors behind generic wording.
-5. For `leave`, report result to the requester only; do not post extra messages into the group session.
-
-## References
-
-1. Load [references/api-contract.md](references/api-contract.md) when you need exact tool mapping, payload examples, and scope matrix.
+# Grix Group
+
+Use `grix_group` for group lifecycle and membership management. The Grix
+account is resolved from the current agent context; you do not pass it.
+
+## Tool contract
+
+Call `grix_group` with one `action`; use the exact typed field names below.
+
+| `action` | Required | Optional |
+|---|---|---|
+| `create` | `name` | `memberIds` (numeric strings) + `memberTypes` (1=user, 2=agent), aligned by index |
+| `detail` | `sessionId` | — |
+| `leave` | `sessionId` | — (never send member fields) |
+| `dissolve` | `sessionId` | — |
+| `add_members` / `remove_members` | `sessionId`, `memberIds` | `memberTypes`, aligned by index |
+| `update_member_role` | `sessionId`, `memberId`, `role` (1=admin, 2=member) | — (`memberType` is always 1) |
+| `update_all_members_muted` | `sessionId`, `allMembersMuted` | — |
+| `update_member_speaking` | `sessionId`, `memberId`, at least one of `isSpeakMuted` / `canSpeakWhenAllMuted` | `memberType` (1 or 2) |
+
+## Rules
+
+1. Validate required fields before calling; reject non-numeric `memberIds`
+   and empty `sessionId` yourself. Resolve an unknown or ambiguous group with
+   `grix_query` (`session_search`) and confirm with the user first.
+2. One call per business action. `create` and `dissolve` are not idempotent —
+   never auto-retry them; ask for explicit confirmation before repeating.
+3. Never guess a role or mute state from vague wording; confirm whether the
+   user wants it enabled or disabled.
+4. `leave` removes only the current agent from the group. Execute it only
+   for the owner or an already-established authorized operator; if identity
+   is unclear, confirm first. Leave silently — no farewell message — and
+   report the result only to the requester. To remove someone else use
+   `remove_members`. `leave` needs no scope, so never answer a `leave`
+   failure with scope-grant guidance.
+5. On errors, report the exact failure and fix; do not retry blindly:
+   - `403/20011` — missing scope (usually not an admin of that group); ask the
+     owner to grant it in the agent permission page.
+   - `401/10001` — invalid key/auth; check agent config or rotate the key.
+   - `403/10002` — agent not active or invalid provider type.
+   - `400/10003` — invalid or missing parameters.
+
+## Response style
+
+State the result first with key identifiers (`session_id`, member count,
+mute state); on failure give the exact remediation and never hide scope or
+auth errors behind generic wording.
+
+## Reference
+
+[references/api-contract.md](references/api-contract.md) — exact tool
+mapping, payload examples, and scope matrix.

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

@@ -5,251 +5,57 @@ description: Use the typed `grix_query` tool for Grix contact lookup, keyword se
 
 # Grix Query
 
-Use the `grix_query` tool for read-only Grix lookup actions.  
-This skill is only for querying existing contacts, sessions, and raw session messages.
-
-## Workflow
-
-1. Parse the user request into one action:
-   `contact_search`, `session_search`, `message_history`, or `message_search`.
-2. Validate required fields before any tool call.
-3. Start with one `grix_query` call for the first page.
-4. If the result is paginated and `has_more` is `true`, continue paging when the user asked for all results, when the target is still unresolved, or when one page is clearly insufficient.
-5. If the user wants message history or in-session keyword search but no `sessionId` is known, locate the target session first through `session_search` or ask the user for a precise target.
-6. Return exact remediation for scope, auth, and parameter failures.
-
-## Tool Contract
-
-For Grix query actions, always call:
-
-1. Tool: `grix_query`
-2. `action`: one of `contact_search`, `session_search`, `message_history`, or `message_search`
-3. `accountId`: required; pass the exact current Grix account ID
-
-Rules:
-
-1. Pass query parameters with their exact typed field names.
-2. For `contact_search` and `session_search`, use exactly one of these modes:
-   exact lookup with `id`, keyword search with `keyword`, or list-all with neither.
-3. If both `id` and `keyword` are present, the backend will prioritize `id`; avoid sending both unless you explicitly want exact-match behavior.
-4. Use `sessionId`, `beforeId`, and `limit` explicitly for message reads; `message_search` also requires `keyword`.
-5. Never invent a `sessionId`. Resolve it from context, from a previous tool result, or ask the user.
-6. Use one tool call per page. Repeated calls are allowed only for pagination or for resolving an ambiguous target.
-7. When paging `contact_search` or `session_search`, keep the same filter and advance `offset`.
-8. `message_history` defaults to the newest one clean message. When paging it or
-   `message_search`, reuse the same `sessionId` and set `beforeId` to the oldest
-   message ID from the previous page.
-
-## Lookup Usage
-
-### Single Lookup (with ID)
-
-When the user provides one exact ID, pass it for a precise match:
-
-1. Single contact lookup: `action: "contact_search"` + `id`
-2. Single session lookup: `action: "session_search"` + `id`
-
-ID meaning:
-
-1. `contact_search.id`: contact or Agent numeric ID, e.g. `1002`
-2. `session_search.id`: exact session ID string, e.g. `task_room_9083`
-
-Examples:
-
-```json
-{
-  "action": "contact_search",
-  "accountId": "primary",
-  "id": "1002"
-}
-```
-
-```json
-{
-  "action": "session_search",
-  "accountId": "primary",
-  "id": "task_room_9083"
-}
-```
-
-### Keyword Search
-
-When the user provides a fuzzy name, title, username, or other search phrase, pass `keyword`:
-
-```json
-{
-  "action": "contact_search",
-  "accountId": "primary",
-  "keyword": "atlas user"
-}
-```
-
-```json
-{
-  "action": "session_search",
-  "accountId": "primary",
-  "keyword": "taskroom9083"
-}
-```
-
-### List All (without ID or keyword)
-
-When the user asks to list all contacts or sessions, call without `id` and without `keyword`:
-
-```json
-{
-  "action": "contact_search",
-  "accountId": "primary"
-}
-```
-
-```json
-{
-  "action": "session_search",
-  "accountId": "primary"
-}
-```
-
-Returns a paginated result with `has_more`, `list`, and default page size of 20.
-Use `limit` and `offset` to paginate through results.
-
-If the user asks for all results, keep fetching additional pages until `has_more` is `false`.
-If the user only needs one match or one page is enough to answer, stop after the first sufficient page.
-
-```json
-{
-  "action": "contact_search",
-  "accountId": "primary",
-  "limit": 50,
-  "offset": 20
-}
-```
-
-## Action Contracts
-
-### contact_search
-
-Purpose: search the owner's Grix contact directory.
-
-**Without `id` and without `keyword`**: returns all contacts (friends + agents) in a paginated list, sorted by `created_at` descending. Default page size 20.
-
-**With `id`**: returns the exact matching contact record.
-
-**With `keyword`**: searches contact remark name, nickname, username, and numeric ID prefix.
-
-Input:
-
-1. `id` (contact ID, numeric string) — optional
-2. `keyword` — optional
-3. `limit` — optional, default 20
-4. `offset` — optional, default 0
-
-Guardrails:
-
-1. Use `id` when the target contact ID is already known and you need the exact entry.
-2. Use `keyword` for fuzzy search; do not use `id` for partial matches.
-3. Without `id` and `keyword`, the result includes both user contacts and agent contacts merged and sorted.
-4. Check `has_more` to determine if additional pages exist.
-5. When paging, keep the same filters and increase `offset` by the number of items already fetched.
-6. If the user asked for all matches, continue until `has_more` is `false`.
-7. Do not jump directly to session history from a vague contact hint; resolve the contact or session first.
-
-### session_search
-
-Purpose: search the owner's visible sessions.
-
-**Without `id` and without `keyword`**: returns all visible sessions in a paginated list, ordered by pinned status and `last_active_at`. Default page size 20.
-
-**With `id`**: returns the exact matching session.
-
-**With `keyword`**: searches session title and `session_id`.
-
-Each result item includes `session_type`: `1` = private chat, `2` = group chat.
-
-Input:
-
-1. `id` (session ID) — optional
-2. `keyword` — optional
-3. `sessionType` — optional; `1` = private chats only, `2` = group chats only. **Omit to return all sessions regardless of type.**
-4. `limit` — optional, default 20
-5. `offset` — optional, default 0
-
-Guardrails:
-
-1. Use `id` when the target session ID is already known.
-2. Use `keyword` for fuzzy search by title or session ID text.
-3. Use `sessionType` when the user explicitly wants only private chats or only group chats.
-4. Without `id` and `keyword`, the result shows all sessions the agent can see.
-5. Check `has_more` to determine if additional pages exist.
-6. When paging, keep the same filters and increase `offset` by the number of items already fetched.
-7. If the user asked for all matches, continue until `has_more` is `false`.
-8. If multiple sessions match, present the candidates and let the user choose before reading history.
-
-### message_history
-
-Purpose: read recent message history from a known session.
-
-Required input:
-
-1. `sessionId`
-
-Optional input:
-
-1. `beforeId`
-2. `limit` — defaults to 1
-
-Guardrails:
-
-1. Only call this after the target session is unambiguous.
-2. Use `beforeId` only for older-page pagination.
-3. For the next page, set `beforeId` to the oldest message ID returned in the previous page.
-4. If the user asked for more history and `has_more` is `true`, keep paging until enough history is collected or no more pages remain.
-5. Do not claim to have full history if only one page was fetched.
-6. History contains plain text and approval-family cards; tool, status, and
-   binding process cards are filtered by the service.
-
-### message_search
-
-Purpose: search messages by keyword inside one known session.
-
-Required input:
-
-1. `sessionId`
-2. `keyword`
-
-Optional input:
-
-1. `beforeId`
-2. `limit`
-
-Guardrails:
-
-1. Only call this after the target session is unambiguous.
-2. `keyword` must be the real search phrase; do not fake an empty keyword just to reuse this action.
-3. For the next page, keep the same `keyword` and `sessionId`, and set `beforeId` to the oldest message ID returned in the previous page.
-4. If the user asked for all matches and `has_more` is `true`, keep paging until enough matches are collected or no more pages remain.
-5. If the user only asked whether a keyword appeared, one sufficient page can stop the search, but state clearly that the result is partial when you did not exhaust all pages.
-
-## Error Handling Rules
-
-1. `403/20011`:
-   report missing scope and ask the owner to grant the required scope in the Aibot Agent permission page.
-2. `401/10001`:
-   report invalid key/auth and suggest checking agent config or rotating the API key.
-3. `403/10002`:
-   report the agent is not active or has an invalid provider type.
-4. `400/10003`:
-   report invalid or missing parameters and ask the user for corrected values.
-5. `404/4004`:
-   report the target session does not exist or is not visible.
-6. Other errors:
-   return the backend `msg` and stop automatic retries.
-
-## Response Style
-
-1. State the query result first.
-2. Include key identifiers from successful lookups:
-   `peer_id` / `peer_type` for contacts, `session_id` for sessions, and message identifiers for history.
-3. If only part of a paginated result was fetched, state that clearly.
-4. If multiple pages were fetched, summarize that the answer is merged from several pages.
-5. Never hide scope or auth errors behind generic wording.
+Use `grix_query` for read-only Grix lookup. It only queries existing contacts,
+sessions, and raw session messages — it never sends or changes anything. The
+Grix account is resolved from the current agent context; you do not pass it.
+
+## Tool contract
+
+Call `grix_query` with one `action`:
+
+- `contact_search` — the owner's contact directory (friends + agents). Use
+  exactly one mode: exact lookup with `id` (numeric contact/agent ID), keyword
+  search with `keyword` (matches remark name, nickname, username, ID prefix),
+  or list-all with neither (sorted by `created_at` desc).
+- `session_search` — the owner's visible sessions. Same three modes: `id`
+  (exact session ID), `keyword` (matches title and session ID), or neither
+  (ordered by pinned status and `last_active_at`). Each result carries
+  `session_type` (`1` private, `2` group); pass `sessionType` to filter by
+  type, omit to get both.
+- `message_history` — recent clean messages of one session. Requires
+  `sessionId`; `limit` defaults to 1; page backwards with `beforeId` = the
+  oldest message ID from the previous page. History contains plain text and
+  approval-family cards; tool/status/binding process cards are filtered out.
+- `message_search` — keyword search inside one session. Requires `sessionId`
+  and a real `keyword`; pages like `message_history`.
+
+Pagination: `limit` (default 20, max 100) and `offset` for the two search
+actions; `beforeId` for the two message actions. Results include `has_more`.
+
+## Rules
+
+1. Parse the request into exactly one action and validate required fields
+   before calling.
+2. If both `id` and `keyword` are given the backend prioritizes `id`; send
+   only one unless you explicitly want exact-match behavior.
+3. Never invent a `sessionId`. For message history or in-session search with
+   no known session, resolve it via `session_search` first — if several
+   sessions match, present the candidates and let the user choose.
+4. One call per page. Keep paging only when the user asked for everything,
+   the target is still unresolved, or one page is clearly insufficient; keep
+   the same filters while paging. When you stop early, say the result is
+   partial.
+5. On errors, report the exact failure and fix; do not retry with guessed
+   parameters:
+   - `403/20011` — missing scope; ask the owner to grant it in the agent
+     permission page.
+   - `401/10001` — invalid key/auth; check agent config or rotate the key.
+   - `403/10002` — agent not active or invalid provider type.
+   - `400/10003` — invalid or missing parameters.
+   - `404/4004` — session does not exist or is not visible.
+
+## Response style
+
+State the result first and include the key identifiers (`peer_id` /
+`peer_type` for contacts, `session_id` for sessions, message IDs for
+history). Never hide scope or auth errors behind generic wording.