@clawling/clawchat-plugin-openclaw 2026.9.26-3 → 2026.10.7-2

package/src/tools.ts

@@ -148,6 +148,17 @@ function extractRequestId(err: ClawlingApiError): string | undefined {
   return undefined;
 }
 
+/**
+ * What the agent must do with the later `permission_result` receipt
+ * (agent-protocol §2.8): on approval the SERVER executes the gated call, so a
+ * second call would duplicate it or raise a fresh card. Only `approved_retry`
+ * (reads, which are never replayed) asks for exactly one more call.
+ */
+const PERMISSION_RECEIPT_RULE =
+  "When the result arrives: outcome \"approved\" (or \"auto_allowed\") means the server has already done it for you — do not call this tool again; " +
+  "only outcome \"approved_retry\" means call this same tool once more with the same arguments. " +
+  "Anything the server produced (a new id, a code, read data) comes in that message's Result line.";
+
 function permissionGateResult(err: ClawlingApiError) {
   const code = (err.meta as Record<string, unknown> | undefined)?.code;
   const requestId = extractRequestId(err);
@@ -158,7 +169,8 @@ function permissionGateResult(err: ClawlingApiError) {
       "This operation requires the owner's approval and has been submitted for review" +
       (requestId ? ` (request_id=${requestId})` : "") +
       ". It has NOT failed. Do not retry — the result will arrive later as a normal " +
-      "chat message; wait for it instead of calling this tool again.";
+      "chat message; wait for it instead of calling this tool again. " +
+      PERMISSION_RECEIPT_RULE;
     status = "pending";
   } else {
     message =
@@ -257,6 +269,50 @@ function inferMimeFromPath(filePath: string): string {
   return MIME_BY_EXT[ext] ?? "application/octet-stream";
 }
 
+type MomentImageEntry = { kind: "url"; url: string } | { kind: "local"; path: string };
+
+/**
+ * Classify `clawchat_create_moment` image entries: http(s) URLs pass through;
+ * an existing absolute local regular file (≤ 20MB) is marked for upload; any
+ * other value is a validation error naming the offending index.
+ */
+function planMomentImages(
+  images: unknown[],
+): { ok: true; entries: MomentImageEntry[] } | { ok: false; message: string } {
+  const entries: MomentImageEntry[] = [];
+  for (const [i, raw] of images.entries()) {
+    const where = `clawchat-plugin-openclaw: images[${i}]`;
+    const value = typeof raw === "string" ? raw.trim() : "";
+    if (!value) {
+      return { ok: false, message: `${where} must be an http(s) image URL or an absolute local image path` };
+    }
+    if (/^https?:\/\/\S+$/i.test(value)) {
+      entries.push({ kind: "url", url: value });
+      continue;
+    }
+    if (!path.isAbsolute(value)) {
+      return {
+        ok: false,
+        message: `${where} (${JSON.stringify(value)}) is neither an http(s) URL nor an absolute local file path; no moment was created`,
+      };
+    }
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(value);
+    } catch {
+      return { ok: false, message: `${where}: local file ${value} does not exist; no moment was created` };
+    }
+    if (!stat.isFile()) {
+      return { ok: false, message: `${where}: ${value} is not a regular file; no moment was created` };
+    }
+    if (stat.size > MAX_UPLOAD_BYTES) {
+      return { ok: false, message: `${where}: ${value} is too large (${stat.size} bytes; max 20MB)` };
+    }
+    entries.push({ kind: "local", path: value });
+  }
+  return { ok: true, entries };
+}
+
 function validateMentionMessageParams(params: unknown):
   | { ok: true; params: ClawchatMentionMessageParams }
   | { ok: false; message: string } {
@@ -442,6 +498,7 @@ export function registerOpenclawClawlingTools(
       ok: true,
       client: createOpenclawClawlingApiClient({
         baseUrl: acct.baseUrl,
+        mediaBaseUrl: acct.mediaBaseUrl,
         token: acct.token,
         userId: acct.userId,
       }),
@@ -490,7 +547,19 @@ export function registerOpenclawClawlingTools(
                 ? (rawData as Record<string, unknown>)
                 : {};
             const outcome = mapGateOutcome(code, gateData);
-            if (outcome !== null) return jsonResponse(outcome);
+            if (outcome !== null) {
+              // `next_step` is added here, not in mapGateOutcome: that mapping
+              // is pinned byte-for-byte against the Hermes parity fixtures.
+              return jsonResponse(
+                outcome.status === "pending_owner_approval"
+                  ? {
+                      ...outcome,
+                      next_step:
+                        "Waiting for the owner's approval; do not call this tool again now. " + PERMISSION_RECEIPT_RULE,
+                    }
+                  : outcome,
+              );
+            }
           }
           return apiError(err);
         }
@@ -1413,7 +1482,7 @@ export function registerOpenclawClawlingTools(
         description: toolDescription(
           "Create a new ClawChat moment/dynamic for the configured ClawChat account. " +
           "TRIGGER - invoke when the user asks to publish, post, or send a ClawChat moment/dynamic, such as \"post a ClawChat moment saying ...\", \"publish a dynamic ...\", or \"send a friend moment ...\". " +
-          "At least one of text or images must be present. For local image files, upload first with the appropriate media upload tool and pass the returned URLs in images; do not pass local file paths as images.",
+          "At least one of text or images must be present. Each images entry is either an http(s) image URL (used as-is) or an absolute local image path (max 20MB) — for a local path this tool uploads it to ClawChat media itself and uses the hosted URL, so no separate upload step is needed. Any other value (relative path, file:// or data: URI, missing file) is rejected and no moment is created.",
         ),
         parameters: ClawchatCreateMomentSchema,
         async execute(_callId, params) {
@@ -1424,12 +1493,34 @@ export function registerOpenclawClawlingTools(
             if (!text && (!images || images.length === 0)) {
               return validationError("clawchat-plugin-openclaw: at least one of text or images is required");
             }
-            return await withGatedClient(accountId, (c) =>
-              c.createMoment({
+            // Validate every entry before touching the network, so a bad value
+            // never leaves a half-uploaded batch or a moment with a broken image.
+            const plan = images !== undefined ? planMomentImages(images) : { ok: true as const, entries: [] };
+            if (!plan.ok) return validationError(plan.message);
+            return await withGatedClient(accountId, async (c) => {
+              const resolved: string[] = [];
+              for (const entry of plan.entries) {
+                if (entry.kind === "url") {
+                  resolved.push(entry.url);
+                  continue;
+                }
+                const uploaded = await c.uploadMedia({
+                  buffer: fs.readFileSync(entry.path),
+                  filename: path.basename(entry.path),
+                  mime: inferMimeFromPath(entry.path),
+                });
+                if (uploaded.kind !== "image") {
+                  throw new Error(
+                    `clawchat-plugin-openclaw: ${entry.path} is not an image (media service classified it as ${uploaded.kind}); no moment was created`,
+                  );
+                }
+                resolved.push(uploaded.url);
+              }
+              return await c.createMoment({
                 ...(text !== undefined ? { text } : {}),
-                ...(images !== undefined ? { images } : {}),
-              }),
-            );
+                ...(images !== undefined ? { images: resolved } : {}),
+              });
+            });
           });
         },
       };
@@ -1867,11 +1958,18 @@ export function registerOpenclawClawlingTools(
         name: "clawchat_orchestrate_set_agent_behavior",
         label: "Rewrite A Sibling's System Prompt",
         description: toolDescription(
+          "Stage/room speaking rules go in the group description, not here; for a stage, append the stage sentence below to off-desktop members (clawchat-orchestration skill). " +
           "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.",
+          "Nickname and bio cannot be changed here. " +
+          "Behavior follows an agent into every room, so one room's rules never go here — they go in that group's description (clawchat_orchestrate_set_group_prompt). " +
+          "A stage (a group whose description has its agents chime in freely) adds only one line here, the same for every room: " +
+          "give each member that the ClawChat desktop app does not run on the owner's computer — Hermes and OpenClaw plugin agents among them — this sentence, verbatim, " +
+          "appended without deleting anything and without naming the room: " +
+          "\"In a group whose description makes it a stage, you are one of the players: pick up the other characters' lines without waiting to be called.\" " +
+          "Older plugin versions rank the group description below their own reply rules; this line is what lets them speak on a stage.",
         ),
         parameters: ClawchatOrchSetAgentBehaviorSchema,
         async execute(_callId, params) {
@@ -1940,11 +2038,15 @@ export function registerOpenclawClawlingTools(
         name: "clawchat_orchestrate_set_group_prompt",
         label: "Rewrite A Group's System Prompt",
         description: toolDescription(
+          "Stage/room speaking rules go here, in the group description; for a stage, also append the stage sentence to off-desktop members' behavior (clawchat-orchestration skill). " +
           "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.",
+          "The group title cannot be changed here. " +
+          "A room where agents should chime in freely, a stage, says so in its description, and its own rules go nowhere else: behavior follows an agent into every room. " +
+          "A stage also needs one room-independent line in the behavior of each member the ClawChat desktop app does not run on the owner's computer, appended verbatim with clawchat_orchestrate_set_agent_behavior: " +
+          "\"In a group whose description makes it a stage, you are one of the players: pick up the other characters' lines without waiting to be called.\"",
         ),
         parameters: ClawchatOrchSetGroupPromptSchema,
         async execute(_callId, params) {