@dhfpub/clawpool-admin 0.1.2 → 0.2.1

package/README.md

@@ -14,7 +14,7 @@ If you are reading the channel plugin documentation first, also read:
 ## Which Package Do I Need?
 
 - Install only `@dhfpub/clawpool` when you only need ClawPool channel transport, website onboarding, and the bundled onboarding skill
-- Install both `@dhfpub/clawpool` and `@dhfpub/clawpool-admin` when you want typed group governance or typed API-agent admin actions inside OpenClaw
+- Install both `@dhfpub/clawpool` and `@dhfpub/clawpool-admin` when you want typed query, group governance, or typed API-agent admin actions inside OpenClaw
 - Do not install only `@dhfpub/clawpool-admin` and expect it to work alone, because it depends on the `channels.clawpool` credentials managed by `@dhfpub/clawpool`
 
 ## Install
@@ -48,7 +48,7 @@ For the channel-side setup flow, see:
 3. Enable the required tools in OpenClaw config
 4. Restart the OpenClaw gateway
 
-If the `tools` block is missing, the plugin may be installed and loaded, but the agent still cannot use `clawpool_group` or `clawpool_agent_admin`.
+If the `tools` block is missing, the plugin may be installed and loaded, but the agent still cannot use `clawpool_query`, `clawpool_group`, or `clawpool_agent_admin`.
 
 ## Configure `channels.clawpool` First
 
@@ -79,6 +79,7 @@ To make the admin capabilities available to the OpenClaw agent, configure `tools
     "profile": "coding",
     "alsoAllow": [
       "message",
+      "clawpool_query",
       "clawpool_group",
       "clawpool_agent_admin"
     ],
@@ -92,6 +93,7 @@ To make the admin capabilities available to the OpenClaw agent, configure `tools
 These fields are required for the intended ClawPool group-governance workflow:
 
 - `message`: lets the agent send and coordinate messages in the group workflow
+- `clawpool_query`: enables typed contact search, session search, and session message-history lookup
 - `clawpool_group`: enables typed group governance actions
 - `clawpool_agent_admin`: enables typed API-agent admin actions
 - `sessions.visibility = agent`: ensures the tool session context is visible to the agent runtime
@@ -112,6 +114,7 @@ These fields are required for the intended ClawPool group-governance workflow:
     "profile": "coding",
     "alsoAllow": [
       "message",
+      "clawpool_query",
       "clawpool_group",
       "clawpool_agent_admin"
     ],
@@ -134,11 +137,19 @@ openclaw clawpool-admin doctor
 Expected result:
 
 - `plugins info clawpool-admin` shows `enabled=true`, `status=loaded`
-- the plugin exposes `clawpool_group` and `clawpool_agent_admin`
+- the plugin exposes `clawpool_query`, `clawpool_group`, and `clawpool_agent_admin`
 - `clawpool-admin doctor` can see the configured `channels.clawpool` account
 
 ## Agent Tools
 
+### `clawpool_query`
+
+Typed query tool with these actions:
+
+- `contact_search`
+- `session_search`
+- `message_history`
+
 ### `clawpool_group`
 
 Typed group governance tool with these actions:
@@ -148,6 +159,8 @@ Typed group governance tool with these actions:
 - `add_members`
 - `remove_members`
 - `update_member_role`
+- `update_all_members_muted`
+- `update_member_speaking`
 - `dissolve`
 
 ### `clawpool_agent_admin`

package/dist/index.js

@@ -87,6 +87,32 @@ function readRequiredInt(params, key) {
   }
   return value;
 }
+function readOptionalBool(params, key) {
+  const raw = readRawParam(params, key);
+  if (raw == null) {
+    return void 0;
+  }
+  if (typeof raw === "boolean") {
+    return raw;
+  }
+  if (typeof raw === "number") {
+    if (raw === 1) return true;
+    if (raw === 0) return false;
+  }
+  if (typeof raw === "string") {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "true" || normalized === "1") return true;
+    if (normalized === "false" || normalized === "0") return false;
+  }
+  throw new Error(`Clawpool action ${key} must be a boolean.`);
+}
+function readRequiredBool(params, key) {
+  const value = readOptionalBool(params, key);
+  if (value == null) {
+    throw new Error(`Clawpool action requires ${key}.`);
+  }
+  return value;
+}
 function ensureMemberTypes(types) {
   for (const memberType of types) {
     if (memberType !== 1 && memberType !== 2) {
@@ -99,6 +125,11 @@ function ensureMemberType(memberType) {
     throw new Error("Clawpool action member_type only supports 1 for role update.");
   }
 }
+function ensureSpeakingMemberType(memberType) {
+  if (memberType !== 1 && memberType !== 2) {
+    throw new Error("Clawpool action member_type only supports 1 (human) or 2 (agent).");
+  }
+}
 function buildGroupCreateRequest(params) {
   const name = readRequiredStringParam(params, "name");
   const memberIDs = readNumericIDArray(params, "memberIds", false);
@@ -206,6 +237,52 @@ function buildGroupDissolveRequest(params) {
     }
   };
 }
+function buildGroupAllMembersMutedUpdateRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  const allMembersMuted = readRequiredBool(params, "allMembersMuted");
+  return {
+    actionName: "group_all_members_muted_update",
+    method: "POST",
+    path: "/sessions/speaking/all_muted",
+    body: {
+      session_id: sessionID,
+      all_members_muted: allMembersMuted
+    }
+  };
+}
+function buildGroupMemberSpeakingUpdateRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  const memberID = readRequiredStringParam(params, "memberId");
+  if (!/^\d+$/.test(memberID)) {
+    throw new Error("Clawpool action memberId must be numeric.");
+  }
+  const memberType = readOptionalInt(params, "memberType") ?? 1;
+  ensureSpeakingMemberType(memberType);
+  const isSpeakMuted = readOptionalBool(params, "isSpeakMuted");
+  const canSpeakWhenAllMuted = readOptionalBool(params, "canSpeakWhenAllMuted");
+  if (isSpeakMuted == null && canSpeakWhenAllMuted == null) {
+    throw new Error(
+      "Clawpool action update_member_speaking requires isSpeakMuted or canSpeakWhenAllMuted."
+    );
+  }
+  const body = {
+    session_id: sessionID,
+    member_id: memberID,
+    member_type: memberType
+  };
+  if (isSpeakMuted != null) {
+    body.is_speak_muted = isSpeakMuted;
+  }
+  if (canSpeakWhenAllMuted != null) {
+    body.can_speak_when_all_muted = canSpeakWhenAllMuted;
+  }
+  return {
+    actionName: "group_member_speaking_update",
+    method: "POST",
+    path: "/sessions/members/speaking",
+    body
+  };
+}
 function buildGroupDetailReadRequest(params) {
   const sessionID = readRequiredStringParam(params, "sessionId");
   return {
@@ -217,6 +294,66 @@ function buildGroupDetailReadRequest(params) {
     }
   };
 }
+function buildContactSearchRequest(params) {
+  const keyword = readRequiredStringParam(params, "keyword");
+  const limit = readOptionalInt(params, "limit");
+  const offset = readOptionalInt(params, "offset");
+  const query = {
+    keyword
+  };
+  if (limit != null) {
+    query.limit = String(limit);
+  }
+  if (offset != null) {
+    query.offset = String(offset);
+  }
+  return {
+    actionName: "contact_search",
+    method: "GET",
+    path: "/contacts/search",
+    query
+  };
+}
+function buildSessionSearchRequest(params) {
+  const keyword = readRequiredStringParam(params, "keyword");
+  const limit = readOptionalInt(params, "limit");
+  const offset = readOptionalInt(params, "offset");
+  const query = {
+    keyword
+  };
+  if (limit != null) {
+    query.limit = String(limit);
+  }
+  if (offset != null) {
+    query.offset = String(offset);
+  }
+  return {
+    actionName: "session_search",
+    method: "GET",
+    path: "/sessions/search",
+    query
+  };
+}
+function buildMessageHistoryRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  const beforeID = readStringParam(params, "beforeId");
+  const limit = readOptionalInt(params, "limit");
+  const query = {
+    session_id: sessionID
+  };
+  if (beforeID) {
+    query.before_id = beforeID;
+  }
+  if (limit != null) {
+    query.limit = String(limit);
+  }
+  return {
+    actionName: "message_history",
+    method: "GET",
+    path: "/messages/history",
+    query
+  };
+}
 function buildAgentAPICreateRequest(params) {
   const agentName = readRequiredStringParam(params, "agentName");
   if (!AGENT_NAME_RE.test(agentName)) {
@@ -238,6 +375,12 @@ function buildAgentAPICreateRequest(params) {
 }
 function buildAgentHTTPRequest(action, params) {
   switch (action) {
+    case "contact_search":
+      return buildContactSearchRequest(params);
+    case "session_search":
+      return buildSessionSearchRequest(params);
+    case "message_history":
+      return buildMessageHistoryRequest(params);
     case "group_create":
       return buildGroupCreateRequest(params);
     case "group_member_add":
@@ -246,6 +389,10 @@ function buildAgentHTTPRequest(action, params) {
       return buildGroupMemberRemoveRequest(params);
     case "group_member_role_update":
       return buildGroupMemberRoleUpdateRequest(params);
+    case "group_all_members_muted_update":
+      return buildGroupAllMembersMutedUpdateRequest(params);
+    case "group_member_speaking_update":
+      return buildGroupMemberSpeakingUpdateRequest(params);
     case "group_dissolve":
       return buildGroupDissolveRequest(params);
     case "group_detail_read":
@@ -668,6 +815,10 @@ function mapGroupActionToRequestAction(action) {
       return "group_member_remove";
     case "update_member_role":
       return "group_member_role_update";
+    case "update_all_members_muted":
+      return "group_all_members_muted_update";
+    case "update_member_speaking":
+      return "group_member_speaking_update";
     case "dissolve":
       return "group_dissolve";
     default:
@@ -770,6 +921,35 @@ var ClawpoolGroupToolSchema = {
       },
       required: ["action", "sessionId", "memberId", "role"]
     },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "update_all_members_muted" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 },
+        allMembersMuted: { type: "boolean" }
+      },
+      required: ["action", "sessionId", "allMembersMuted"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "update_member_speaking" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 },
+        memberId: numericIdSchema,
+        memberType: { type: "integer", enum: [1, 2] },
+        isSpeakMuted: { type: "boolean" },
+        canSpeakWhenAllMuted: { type: "boolean" }
+      },
+      required: ["action", "sessionId", "memberId"],
+      anyOf: [
+        { required: ["isSpeakMuted"] },
+        { required: ["canSpeakWhenAllMuted"] }
+      ]
+    },
     {
       type: "object",
       additionalProperties: false,
@@ -805,6 +985,113 @@ function createClawpoolGroupTool(api) {
   };
 }
 
+// src/query-service.ts
+function mapQueryActionToRequestAction(action) {
+  switch (action) {
+    case "contact_search":
+      return "contact_search";
+    case "session_search":
+      return "session_search";
+    case "message_history":
+      return "message_history";
+    default:
+      action;
+      throw new Error(`Unsupported Clawpool query action: ${String(action)}`);
+  }
+}
+async function runClawpoolQueryAction(params) {
+  const account = resolveClawpoolAccount({
+    cfg: params.cfg,
+    accountId: params.toolParams.accountId
+  });
+  if (!account.enabled) {
+    throw new Error(`Clawpool account "${account.accountId}" is disabled.`);
+  }
+  if (!account.configured) {
+    throw new Error(`Clawpool account "${account.accountId}" is not configured.`);
+  }
+  const requestAction = mapQueryActionToRequestAction(params.toolParams.action);
+  const request = buildAgentHTTPRequest(requestAction, params.toolParams);
+  const data = await callAgentAPI({
+    account,
+    actionName: request.actionName,
+    method: request.method,
+    path: request.path,
+    query: request.query,
+    body: request.body
+  });
+  return {
+    ok: true,
+    accountId: account.accountId,
+    action: params.toolParams.action,
+    data
+  };
+}
+
+// src/query-tool.ts
+var ClawpoolQueryToolSchema = {
+  oneOf: [
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "contact_search" },
+        accountId: { type: "string", minLength: 1 },
+        keyword: { type: "string", minLength: 1 },
+        limit: { type: "integer", minimum: 1 },
+        offset: { type: "integer", minimum: 0 }
+      },
+      required: ["action", "keyword"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "session_search" },
+        accountId: { type: "string", minLength: 1 },
+        keyword: { type: "string", minLength: 1 },
+        limit: { type: "integer", minimum: 1 },
+        offset: { type: "integer", minimum: 0 }
+      },
+      required: ["action", "keyword"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "message_history" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 },
+        beforeId: { type: "string", pattern: "^[0-9]+$" },
+        limit: { type: "integer", minimum: 1 }
+      },
+      required: ["action", "sessionId"]
+    }
+  ]
+};
+function createClawpoolQueryTool(api) {
+  return {
+    name: "clawpool_query",
+    label: "Clawpool Query",
+    description: "Search Clawpool contacts and sessions, or read session message history through typed query operations.",
+    parameters: ClawpoolQueryToolSchema,
+    async execute(_toolCallId, params) {
+      try {
+        return jsonToolResult(
+          await runClawpoolQueryAction({
+            cfg: api.config,
+            toolParams: params
+          })
+        );
+      } catch (err) {
+        return jsonToolResult({
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  };
+}
+
 // index.ts
 var plugin = {
   id: "clawpool-admin",
@@ -812,6 +1099,7 @@ var plugin = {
   description: "Typed optional admin tools and operator CLI for Clawpool",
   configSchema: emptyPluginConfigSchema(),
   register(api) {
+    api.registerTool(createClawpoolQueryTool(api), { optional: true });
     api.registerTool(createClawpoolGroupTool(api), { optional: true });
     api.registerTool(createClawpoolAgentAdminTool(api), { optional: true });
     api.registerCli(({ program }) => registerClawpoolAdminCli({ api, program }), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhfpub/clawpool-admin",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "OpenClaw admin tools plugin for ClawPool",
   "type": "module",
   "main": "./dist/index.js",

package/skills/clawpool-group-governance/SKILL.md

@@ -11,7 +11,7 @@ This skill is about tool selection and guardrails, not protocol bridging.
 ## Workflow
 
 1. Parse the user request into one action:
-   `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, or `dissolve`.
+   `create`, `detail`, `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 `clawpool_group` exactly once per business action.
 4. Classify failures by HTTP/BizCode and return exact remediation.
@@ -23,13 +23,13 @@ This skill is about tool selection and guardrails, not protocol bridging.
 For Clawpool group governance, always call:
 
 1. Tool: `clawpool_group`
-2. `action`: one of `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `dissolve`
+2. `action`: one of `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, `dissolve`
 3. `accountId`: optional; include it when the configured account is ambiguous
 
 Rules:
 
 1. Pass business parameters with their exact typed field names.
-2. Use `sessionId`, `memberIds`, `memberTypes`, `memberId`, `memberType`, and `role` explicitly.
+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.
 
@@ -87,6 +87,32 @@ 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:
@@ -109,7 +135,7 @@ Required input:
 ## Response Style
 
 1. State action result first.
-2. Include key identifiers (`session_id`, member count) when successful.
+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.
 

package/skills/clawpool-group-governance/references/api-contract.md

@@ -29,6 +29,8 @@ Use the native `clawpool_group` tool with typed fields:
 | `add_members` | `group_member_add` | `sessionId`, `memberIds` |
 | `remove_members` | `group_member_remove` | `sessionId`, `memberIds` |
 | `update_member_role` | `group_member_role_update` | `sessionId`, `memberId`, `role` |
+| `update_all_members_muted` | `group_all_members_muted_update` | `sessionId`, `allMembersMuted` |
+| `update_member_speaking` | `group_member_speaking_update` | `sessionId`, `memberId`, `isSpeakMuted` or `canSpeakWhenAllMuted` |
 | `dissolve` | `group_dissolve` | `sessionId` |
 
 ## Payload Templates

package/skills/clawpool-query/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: clawpool-query
+description: Use the typed `clawpool_query` tool for Clawpool contact search, session search, and session message history lookup. Trigger when users ask to find contacts, locate a conversation, or inspect recent messages in a known session.
+---
+
+# Clawpool Query
+
+Use the `clawpool_query` tool for read-only Clawpool lookup actions.  
+This skill is only for querying existing contacts, sessions, and message history.
+
+## Workflow
+
+1. Parse the user request into one action:
+   `contact_search`, `session_search`, or `message_history`.
+2. Validate required fields before any tool call.
+3. Call `clawpool_query` exactly once per business action.
+4. If the user wants message history but no `sessionId` is known, locate the target session first through `session_search` or ask the user for a precise target.
+5. Return exact remediation for scope, auth, and parameter failures.
+
+## Tool Contract
+
+For Clawpool query actions, always call:
+
+1. Tool: `clawpool_query`
+2. `action`: one of `contact_search`, `session_search`, or `message_history`
+3. `accountId`: optional; include it when the configured account is ambiguous
+
+Rules:
+
+1. Pass query parameters with their exact typed field names.
+2. Use `keyword` for search actions.
+3. Use `sessionId`, `beforeId`, and `limit` explicitly for message history.
+4. Never invent a `sessionId`. Resolve it from context, from a previous tool result, or ask the user.
+5. Keep one tool call per action for audit clarity.
+
+## Action Contracts
+
+### contact_search
+
+Purpose: search the owner's Clawpool contact directory.
+
+Required input:
+
+1. `keyword` (non-empty string)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the user is trying to find a person or active agent by display name, remark, nickname, username, or agent name.
+2. 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 by final display title.
+
+Required input:
+
+1. `keyword` (non-empty string)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the user describes a conversation by session title, group name, or known list title.
+2. 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`
+
+Guardrails:
+
+1. Only call this after the target session is unambiguous.
+2. Use `beforeId` only for older-page pagination.
+3. Do not claim to have full history if only one page was fetched.
+
+## 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 history results may be partial, state that clearly.
+4. Never hide scope or auth errors behind generic wording.

package/skills/clawpool-query/agents/openai.yaml

@@ -0,0 +1,4 @@
+version: 1
+agent:
+  name: clawpool-query
+  default_prompt: "Use this skill when users ask to find Clawpool contacts, locate sessions, or inspect a known session's message history. Validate required parameters, call clawpool_query exactly once per action, and do not fabricate a sessionId."