openclaw-quiubo 2.6.36 → 2.6.37

package/POSTS.md

@@ -0,0 +1,122 @@
+# Agent Posts
+
+Let agents create posts in Quiubo groups — image + optional caption, visible in the group's post feed, auto-expires after 24 hours.
+
+## Why This Exists
+
+Without this tool, an agent asked to "create a post" will generate an image and send it as a chat message via `sendMedia`. The agent has no way to distinguish "send a message with an image" from "create a post" — both route through the same `deliver-callback` pipeline.
+
+The `quiubo_create_post` tool gives agents an explicit action for posts. The agent calls it by name, the image goes through the presigned upload flow, and the result appears in the post feed — not the chat.
+
+## Requirements
+
+- A configured Quiubo account with `apiKey` and `botIdentityId` in `channels.quiubo.accounts`
+- The agent must have an image file on disk (`.jpg`, `.jpeg`, `.png`, or `.webp`, max 5MB)
+
+If the Quiubo channel isn't configured, the tool silently doesn't register — agents won't see it.
+
+## How It Works
+
+```
+Agent decides to create a post
+  │
+  ▼
+quiubo_create_post(image_path, caption?, group_id?)
+  │
+  ├─ Reads image from disk
+  ├─ Validates format + size
+  ├─ POST /v1/sdk/posts/presign  →  gets upload URL + post record
+  ├─ PUT to presigned S3 URL     →  uploads image bytes
+  │
+  ▼
+Post appears in group feed (not chat)
+```
+
+The tool creates its own API client from the account config — no shared state with the channel gateway.
+
+## Tool Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `image_path` | string | Yes | Absolute path to image file on disk |
+| `caption` | string | No | Text caption (max 500 chars) |
+| `group_id` | string | No | Target group UUID. Defaults to the current conversation group. |
+
+## Tool Response
+
+**Success:**
+```json
+{
+  "ok": true,
+  "postId": "post-uuid",
+  "imageUrl": "https://...",
+  "groupId": "group-uuid"
+}
+```
+
+**Error:**
+```json
+{
+  "ok": false,
+  "error": "Unsupported image format: .gif. Use .jpg, .png, or .webp"
+}
+```
+
+## Teaching Your Agent
+
+Add something like this to the agent's identity/instructions file (`SOUL.md`, `IDENTITY.md`, or system prompt):
+
+```markdown
+## Posts
+
+You have a `quiubo_create_post` tool. Use it when asked to create a post, share a photo to the feed, or post an update.
+
+Posts are different from messages:
+- Posts appear in the group's **post feed**, not the chat
+- Posts require an **image** (messages don't)
+- Posts auto-expire after **24 hours**
+
+Workflow:
+1. Generate or locate the image file
+2. Call `quiubo_create_post` with `image_path` and optional `caption`
+3. The post appears in the group feed automatically
+
+Do NOT use sendMessage/sendMedia for posts — that sends a chat message, not a post.
+```
+
+## Group Targeting
+
+The tool resolves the target group in this order:
+
+1. **`group_id` parameter** — if the agent passes it explicitly
+2. **Session key** — extracted from the OpenClaw session key (`agent:<name>:quiubo:<uuid>`)
+
+For most conversational use ("create a post in this group"), the session key auto-resolves. The `group_id` parameter is for cross-posting to a different group.
+
+## Example Agent Interaction
+
+```
+User: Create a post with today's weather forecast
+
+Agent: (generates weather image → saves to /tmp/weather-2026-02-28.png)
+Agent: (calls quiubo_create_post)
+  image_path: /tmp/weather-2026-02-28.png
+  caption: "☀️ Today's forecast: Clear skies, 22°C"
+
+Tool result: { ok: true, postId: "abc-123", groupId: "def-456" }
+
+Agent: Done — the weather forecast is now in the group's post feed.
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Agent sends image as chat message instead of post | Agent doesn't know about the tool. Add instructions to its identity file (see [Teaching Your Agent](#teaching-your-agent)). |
+| Tool doesn't appear for the agent | Check that `channels.quiubo.accounts.default` has both `apiKey` and `botIdentityId`. The factory returns null without them. |
+| "No group_id provided and could not resolve from session context" | The session key doesn't contain a group UUID. Pass `group_id` explicitly. |
+| "No botIdentityId configured" | Add `botIdentityId` to the account config in `channels.quiubo.accounts`. |
+| "Unsupported image format" | Only `.jpg`, `.jpeg`, `.png`, `.webp` are supported. Convert the image first. |
+| "Image exceeds 5MB limit" | Compress or resize the image before calling the tool. |
+| "Cannot read image" | The `image_path` doesn't exist or isn't readable. Check the path is absolute and the file was saved. |
+| Post created but not visible | Check the group UUID is correct. Posts are scoped to a group and expire after 24 hours. |

package/dist/index.d.ts

@@ -15,6 +15,9 @@ interface OpenClawPluginApi {
     registerChannel: (opts: {
         plugin: any;
     }) => void;
+    registerTool: (tool: any, opts?: {
+        name?: string;
+    }) => void;
 }
 declare const plugin: {
     id: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACvK,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAGxB,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IAEjB,eAAe,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,GAAG,CAAA;KAAE,KAAK,IAAI,CAAC;CAClD;AAED,QAAA,MAAM,MAAM;;;;kBAII,iBAAiB;CAIhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACvK,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAGxB,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IAEjB,eAAe,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,GAAG,CAAA;KAAE,KAAK,IAAI,CAAC;IAEjD,YAAY,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC7D;AAED,QAAA,MAAM,MAAM;;;;kBAII,iBAAiB;CAKhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -14343,11 +14343,11 @@ function resolveOutboundGroupId(ctx) {
 }
 async function resolveAnnounceGroupId(accountId, log) {
   try {
-    const { readFile: readFile3 } = await import("node:fs/promises");
+    const { readFile: readFile4 } = await import("node:fs/promises");
     const { join: join3 } = await import("node:path");
     const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? "";
     const cronPath = join3(homeDir, ".openclaw", "cron", "jobs.json");
-    const raw = await readFile3(cronPath, "utf-8");
+    const raw = await readFile4(cronPath, "utf-8");
     const parsed = JSON.parse(raw);
     const jobs = parsed?.jobs ?? [];
     for (const job of jobs) {
@@ -14367,12 +14367,12 @@ async function resolveAnnounceGroupId(accountId, log) {
 }
 async function getActivityData(runtime2, log, agentId) {
   try {
-    const { readFile: readFile3 } = await import("node:fs/promises");
+    const { readFile: readFile4 } = await import("node:fs/promises");
     const { join: join3 } = await import("node:path");
     const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? "";
     const cronPath = join3(homeDir, ".openclaw", "cron", "jobs.json");
     log?.info?.(`getActivityData: reading ${cronPath} (agentId=${agentId})`);
-    const raw = await readFile3(cronPath, "utf-8");
+    const raw = await readFile4(cronPath, "utf-8");
     const parsed = JSON.parse(raw);
     const jobs = parsed?.jobs ?? [];
     const items = jobs.filter((j) => j.enabled !== false && (!agentId || j.agentId === agentId)).map((job) => ({
@@ -14623,6 +14623,116 @@ async function routeInboundMessage(opts) {
   log?.info?.(`[${accountId}] Quiubo: message processed from ${senderId}`);
 }
 
+// src/create-post-tool.ts
+import { readFile as readFile3 } from "fs/promises";
+var IMAGE_MIME_TYPES2 = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp"
+};
+var MAX_IMAGE_BYTES2 = 5 * 1024 * 1024;
+var DEFAULT_API_URL2 = "https://api.quiubo.io";
+function extractGroupIdFromSessionKey(key) {
+  if (!key) return void 0;
+  const match = key.match(/quiubo:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i);
+  return match?.[1];
+}
+function jsonResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    details: payload
+  };
+}
+function errorResult(msg) {
+  return {
+    content: [{ type: "text", text: msg }],
+    details: { ok: false, error: msg }
+  };
+}
+function createQuiuboPostToolFactory(ctx) {
+  const quiuboConfig = ctx.config?.channels?.quiubo;
+  const accountCfg = quiuboConfig?.accounts?.default;
+  if (!accountCfg?.apiKey) return null;
+  const client = new QuiuboApiClient(
+    accountCfg.apiUrl ?? DEFAULT_API_URL2,
+    accountCfg.apiKey
+  );
+  const botIdentityId = accountCfg.botIdentityId;
+  const defaultGroupId = extractGroupIdFromSessionKey(ctx.sessionKey);
+  return {
+    name: "quiubo_create_post",
+    label: "Create Quiubo Post",
+    description: "Create a post with an image in a Quiubo group. Posts appear in the group post feed and auto-expire after 24 hours. REQUIRES an image file path on disk (.jpg/.jpeg/.png/.webp, max 5MB). Optionally include a caption (max 500 chars).",
+    parameters: {
+      type: "object",
+      properties: {
+        image_path: {
+          type: "string",
+          description: "Absolute path to image file on disk"
+        },
+        caption: {
+          type: "string",
+          description: "Optional text caption (max 500 chars)"
+        },
+        group_id: {
+          type: "string",
+          description: "Target group UUID. Omit to use current conversation group."
+        }
+      },
+      required: ["image_path"]
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    execute: async (_toolCallId, params) => {
+      const groupId = params.group_id || defaultGroupId;
+      if (!groupId) {
+        return errorResult("No group_id provided and could not resolve from session context");
+      }
+      if (!botIdentityId) {
+        return errorResult("No botIdentityId configured");
+      }
+      const imagePath = params.image_path;
+      const ext = imagePath.substring(imagePath.lastIndexOf(".")).toLowerCase();
+      if (!(ext in IMAGE_MIME_TYPES2)) {
+        return errorResult(`Unsupported image format: ${ext}. Use .jpg, .png, or .webp`);
+      }
+      let imageBuffer;
+      try {
+        imageBuffer = await readFile3(imagePath);
+      } catch {
+        return errorResult(`Cannot read image: ${imagePath}`);
+      }
+      if (imageBuffer.length > MAX_IMAGE_BYTES2) {
+        return errorResult(
+          `Image exceeds 5MB limit (${(imageBuffer.length / 1024 / 1024).toFixed(1)}MB)`
+        );
+      }
+      const contentType = IMAGE_MIME_TYPES2[ext];
+      try {
+        const presign = await client.createPost({
+          identityId: botIdentityId,
+          contentType,
+          content: params.caption || void 0,
+          groupId
+        });
+        await client.uploadToPresignedUrl(presign.uploadUrl, imageBuffer, contentType);
+        return jsonResult({
+          ok: true,
+          postId: presign.post.id,
+          imageUrl: presign.imageUrl,
+          groupId
+        });
+      } catch (error) {
+        if (error instanceof QuiuboApiError) {
+          return errorResult(`Quiubo API error: ${error.status} \u2014 ${error.body}`);
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Post creation failed: ${msg}`);
+      }
+    }
+  };
+}
+
 // src/polling-gateway.ts
 var PollingGateway = class {
   client;
@@ -14770,6 +14880,7 @@ var plugin = {
   register(api) {
     setQuiuboRuntime(api.runtime);
     api.registerChannel({ plugin: quiuboPlugin });
+    api.registerTool(createQuiuboPostToolFactory, { name: "quiubo_create_post" });
   }
 };
 var index_default = plugin;