@clawling/clawchat-plugin-openclaw 2026.9.22-2 → 2026.9.23-1

package/src/tools.ts

@@ -77,6 +77,17 @@ import {
   ClawchatListAppsSchema,
   ClawchatUnregisterAppSchema,
   ClawchatLivewareLoginSchema,
+  ClawchatOrchListAgentsSchema,
+  ClawchatOrchGetAgentSchema,
+  ClawchatOrchSetAgentBehaviorSchema,
+  ClawchatOrchListGroupsSchema,
+  ClawchatOrchGetGroupSchema,
+  ClawchatOrchSetGroupPromptSchema,
+  ClawchatOrchCreateGroupSchema,
+  ClawchatOrchGroupMemberSchema,
+  ClawchatOrchSetGroupAgentSettingsSchema,
+  ClawchatOrchCreateConnectCodeSchema,
+  ClawchatOrchGetConnectCodeSchema,
   type ClawchatMemoryEditParams,
   type ClawchatMemoryReadParams,
   type ClawchatMemorySearchParams,
@@ -109,6 +120,14 @@ import {
   type ClawchatRegisterAppParams,
   type ClawchatUnregisterAppParams,
   type ClawchatLivewareLoginParams,
+  type ClawchatOrchGetAgentParams,
+  type ClawchatOrchSetAgentBehaviorParams,
+  type ClawchatOrchGetGroupParams,
+  type ClawchatOrchSetGroupPromptParams,
+  type ClawchatOrchCreateGroupParams,
+  type ClawchatOrchGroupMemberParams,
+  type ClawchatOrchSetGroupAgentSettingsParams,
+  type ClawchatOrchGetConnectCodeParams,
 } from "./tools-schema.ts";
 
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
@@ -1762,7 +1781,328 @@ export function registerOpenclawClawlingTools(
     { name: "clawchat_liveware_login" },
   );
 
+  // --- cloud orchestration (`agent.orchestrate`) ---------------------------
+  // Twelve tools, 1:1 with docs/features/agentorch.md. Every response is HTTP
+  // 200 with the business code in the envelope (a 21003 owner-approval
+  // denial is the single most common outcome), so these use plain
+  // `withClient` — never `withGatedClient` — and hand the caller the raw
+  // envelope untouched. The shared orchestration skill text tells the model
+  // to read `code` itself; rewriting the shape here would make the same
+  // sentence behave differently than on the Hermes side.
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_list_agents",
+        label: "List The Owner's Agents",
+        description: toolDescription(
+          "List every agent the owner owns, including this one (flagged is_self). " +
+          "TRIGGER — invoke first whenever the owner asks about, or asks to change, one of their OTHER agents. " +
+          "This is the only way to learn a sibling's agentId; never guess one from a nickname.",
+        ),
+        parameters: ClawchatOrchListAgentsSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(accountId, "clawchat_orchestrate_list_agents", params, async () =>
+            withClient(accountId, (c) => c.orchListAgents()),
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_list_agents" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_get_agent",
+        label: "Get A Sibling Agent",
+        description: toolDescription(
+          "Read one of the owner's agents by explicit agentId, including its read-only permission map. " +
+          "TRIGGER — invoke before rewriting a sibling's system prompt (the PATCH replaces the whole field, so read it first), " +
+          "or to explain why a sibling cannot do something instead of retrying on its behalf.",
+        ),
+        parameters: ClawchatOrchGetAgentSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(accountId, "clawchat_orchestrate_get_agent", params, async () => {
+            const p = params as ClawchatOrchGetAgentParams;
+            return await withClient(accountId, (c) => c.orchGetAgent(p.agentId));
+          });
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_get_agent" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_set_agent_behavior",
+        label: "Rewrite A Sibling's System Prompt",
+        description: toolDescription(
+          "Replace the WHOLE system prompt (behavior) of one of the owner's other agents. " +
+          "TRIGGER — invoke when the owner asks to change how another agent behaves, talks, or what it is for. " +
+          "This REPLACES the entire field — call clawchat_orchestrate_get_agent first, edit the text you got back, and send the full new value. " +
+          "Sending a fragment deletes everything else and the owner cannot recover it. Max 3000 runes. " +
+          "Nickname and bio cannot be changed here.",
+        ),
+        parameters: ClawchatOrchSetAgentBehaviorSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(
+            accountId,
+            "clawchat_orchestrate_set_agent_behavior",
+            params,
+            async () => {
+              const p = params as ClawchatOrchSetAgentBehaviorParams;
+              return await withClient(accountId, (c) => c.orchSetAgentBehavior(p.agentId, p.behavior));
+            },
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_set_agent_behavior" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_list_groups",
+        label: "List Manageable Groups",
+        description: toolDescription(
+          "List the groups the owner can administer. " +
+          "TRIGGER — invoke when the owner talks about a group of their agents without naming a conversation id.",
+        ),
+        parameters: ClawchatOrchListGroupsSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(accountId, "clawchat_orchestrate_list_groups", params, async () =>
+            withClient(accountId, (c) => c.orchListGroups()),
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_list_groups" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_get_group",
+        label: "Get A Managed Group",
+        description: toolDescription(
+          "Read one group by explicit conversationId, including its system prompt and member agent ids. " +
+          "TRIGGER — invoke before rewriting a group prompt, and after any write, to report what the server now says.",
+        ),
+        parameters: ClawchatOrchGetGroupSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(accountId, "clawchat_orchestrate_get_group", params, async () => {
+            const p = params as ClawchatOrchGetGroupParams;
+            return await withClient(accountId, (c) => c.orchGetGroup(p.conversationId));
+          });
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_get_group" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_set_group_prompt",
+        label: "Rewrite A Group's System Prompt",
+        description: toolDescription(
+          "Replace the WHOLE system prompt (description) of a group the owner administers. " +
+          "TRIGGER — invoke when the owner asks to change how a group behaves as a whole. " +
+          "This REPLACES the entire field — call clawchat_orchestrate_get_group first and send the full new value. " +
+          "Sending a fragment deletes everything else and the owner cannot recover it. Max 3000 runes. " +
+          "The group title cannot be changed here.",
+        ),
+        parameters: ClawchatOrchSetGroupPromptSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(
+            accountId,
+            "clawchat_orchestrate_set_group_prompt",
+            params,
+            async () => {
+              const p = params as ClawchatOrchSetGroupPromptParams;
+              return await withClient(accountId, (c) => c.orchSetGroupPrompt(p.conversationId, p.description));
+            },
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_set_group_prompt" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_create_group",
+        label: "Create A Group Of The Owner's Agents",
+        description: toolDescription(
+          "Create a new group containing the owner's own agents. " +
+          "TRIGGER — invoke when the owner asks to put several of their agents in a group together.",
+        ),
+        parameters: ClawchatOrchCreateGroupSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(accountId, "clawchat_orchestrate_create_group", params, async () => {
+            const p = params as ClawchatOrchCreateGroupParams;
+            return await withClient(accountId, (c) => c.orchCreateGroup(p.title, p.agentIds));
+          });
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_create_group" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_add_group_member",
+        label: "Add An Agent To A Group",
+        description: toolDescription(
+          "Add one of the owner's agents to a group the owner administers. " +
+          "TRIGGER — invoke when the owner asks to bring another of their agents into an existing group. " +
+          "You cannot add yourself; that is rejected outright.",
+        ),
+        parameters: ClawchatOrchGroupMemberSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(
+            accountId,
+            "clawchat_orchestrate_add_group_member",
+            params,
+            async () => {
+              const p = params as ClawchatOrchGroupMemberParams;
+              return await withClient(accountId, (c) => c.orchAddGroupMember(p.conversationId, p.agentId));
+            },
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_add_group_member" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_remove_group_member",
+        label: "Remove An Agent From A Group",
+        description: toolDescription(
+          "Remove one of the owner's agents from a group the owner administers. " +
+          "TRIGGER — invoke when the owner asks to take an agent out of a group.",
+        ),
+        parameters: ClawchatOrchGroupMemberSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(
+            accountId,
+            "clawchat_orchestrate_remove_group_member",
+            params,
+            async () => {
+              const p = params as ClawchatOrchGroupMemberParams;
+              return await withClient(accountId, (c) => c.orchRemoveGroupMember(p.conversationId, p.agentId));
+            },
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_remove_group_member" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_set_group_agent_settings",
+        label: "Set An Agent's Speaking Settings In A Group",
+        description: toolDescription(
+          "Set how one agent speaks inside one group: muted, reply mode, and batching delay. " +
+          "TRIGGER — invoke FIRST when a group is flooding, echoing, or an agent will not stop. " +
+          "These are the hard controls; a rule written into a prompt stops working after compaction or a restart, so pair every soft rule with one of these. " +
+          "Omitted fields are left unchanged.",
+        ),
+        parameters: ClawchatOrchSetGroupAgentSettingsSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(
+            accountId,
+            "clawchat_orchestrate_set_group_agent_settings",
+            params,
+            async () => {
+              const p = params as ClawchatOrchSetGroupAgentSettingsParams;
+              return await withClient(accountId, (c) =>
+                c.orchSetGroupAgentSettings(p.conversationId, p.agentId, {
+                  muted: p.muted,
+                  replyMode: p.replyMode,
+                  batchDelaySeconds: p.batchDelaySeconds,
+                }),
+              );
+            },
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_set_group_agent_settings" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_create_connect_code",
+        label: "Issue A Connect Code",
+        description: toolDescription(
+          "Mint a connect code on the owner's behalf, valid 30 minutes. " +
+          "TRIGGER — invoke when the owner asks for a code to connect a new agent. " +
+          "The rate limit bucket belongs to the owner and is shared with their own manual issuance, so do not retry on a limit.",
+        ),
+        parameters: ClawchatOrchCreateConnectCodeSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(
+            accountId,
+            "clawchat_orchestrate_create_connect_code",
+            params,
+            async () => withClient(accountId, (c) => c.orchCreateConnectCode()),
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_create_connect_code" },
+  );
+
+  api.registerTool(
+    (ctx) => {
+      const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+      return {
+        name: "clawchat_orchestrate_get_connect_code",
+        label: "Read A Connect Code's Status",
+        description: toolDescription(
+          "Read the status of a connect code the owner minted. " +
+          "TRIGGER — invoke when the owner asks whether a code was used or has expired.",
+        ),
+        parameters: ClawchatOrchGetConnectCodeSchema,
+        async execute(_callId, params) {
+          return await recordClawchatToolCall(
+            accountId,
+            "clawchat_orchestrate_get_connect_code",
+            params,
+            async () => {
+              const p = params as ClawchatOrchGetConnectCodeParams;
+              return await withClient(accountId, (c) => c.orchGetConnectCode(p.code));
+            },
+          );
+        },
+      };
+    },
+    { name: "clawchat_orchestrate_get_connect_code" },
+  );
+
   api.logger.debug?.(
-    "clawchat-plugin-openclaw: registered 31 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, get_moment, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update, register_app, list_apps, unregister_app, liveware_login)",
+    "clawchat-plugin-openclaw: registered 43 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, get_moment, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update, register_app, list_apps, unregister_app, liveware_login, orchestrate_list_agents, orchestrate_get_agent, orchestrate_set_agent_behavior, orchestrate_list_groups, orchestrate_get_group, orchestrate_set_group_prompt, orchestrate_create_group, orchestrate_add_group_member, orchestrate_remove_group_member, orchestrate_set_group_agent_settings, orchestrate_create_connect_code, orchestrate_get_connect_code)",
   );
 }