openclaw-quiubo 2.6.42 → 2.6.44

package/MULTI_AGENT.md

@@ -201,7 +201,15 @@ Cron jobs are scoped per agent via the `agentId` field:
 - **`delivery.channel`**: Must be `"quiubo"`.
 - **`delivery.to`**: The raw group UUID (e.g. `eec8a4ce-d08d-483a-ba5d-90a43ce8f521`). Find it in the agent's welcome chat or via the API.
 
-> **Multi-agent caveat:** The fallback resolver (`resolveAnnounceGroupId`) reads cron jobs from disk but does not filter by accountId. If multiple agents have cron jobs, it may resolve to the wrong agent's target group. Keep one cron job per agent, or ensure each agent's delivery target is unambiguous.
+> **Multi-agent caveat:** The announce delivery path does not reliably resolve targets for named agents ([openclaw/openclaw#32432](https://github.com/openclaw/openclaw/issues/32432)). Use `--no-deliver` so the agent sends messages itself:
+>
+> ```bash
+> openclaw cron add --name "standup" --agent project-manager --every 24h \
+>   --no-deliver --to <group-uuid> \
+>   --message 'Post the daily standup to the group chat.'
+> ```
+>
+> With `--no-deliver`, the agent uses its own channel binding to send messages, which correctly resolves identity and routing. See the [README cron section](./README.md#named-agent-crons) for details.
 
 ## Full Config Reference
 

package/README.md

@@ -34,6 +34,45 @@ The interactive wizard will:
 | SDK API Key | Quiubo app > Settings > Developer > API Keys |
 | Bot Identity | Created during setup wizard, or pre-create in Developer console |
 
+## Quick Start: Talking to your agent
+
+Once setup completes, your agent is ready to chat:
+
+1. **Open Quiubo** — your agent appears as a contact with its own chat
+2. **Send a message** — the agent receives it and responds automatically
+3. **Add to groups** — invite the agent to any group, then @mention it to get its attention
+
+### How agents receive messages
+
+| Context | How to trigger the agent |
+|---------|------------------------|
+| 1:1 chat (agent channel) | Just send a message — the agent always responds |
+| Group (agent is a member) | @mention the agent: `@BotName do something` |
+| Group (agent-only) | Every message triggers all agents (auto-broadcast) |
+| Group (directory agent) | @mention required — agents with `triggerMode: "mention"` only respond when mentioned |
+
+### @team shortcut
+
+In groups with 2+ agents, type `@Team` to mention all agents at once. The @Team mention expands to individual agent mentions before delivery.
+
+### Scheduled messages
+
+Agents can send messages on a schedule using cron jobs:
+
+```bash
+# Default agent — announce mode works
+openclaw cron add --name "daily-report" --every 24h \
+  --channel quiubo --to <group-uuid> --announce \
+  --message "Generate and post the daily report."
+
+# Named agent — use --no-deliver (agent sends the message itself)
+openclaw cron add --name "standup" --agent my-agent --every 24h \
+  --no-deliver --to <group-uuid> \
+  --message "Post the daily standup to the group chat."
+```
+
+See [Cron delivery](#scheduled-messages--cron-delivery) for details on delivery modes.
+
 ## Configuration
 
 ```yaml
@@ -204,13 +243,36 @@ A typing indicator is sent immediately when processing begins, then repeated eve
 Cron jobs that deliver to Quiubo groups **must** include `--to <groupId>`:
 
 ```bash
-openclaw cron add --every 30m --channel quiubo --to 7868cc21-... "Check in with the team"
+openclaw cron add --name "team-checkin" --every 30m --channel quiubo --to 7868cc21-... "Check in with the team"
 ```
 
 Without `--to`, the extension cannot determine which group to deliver to. Unlike 1:1 sessions (which have a single bound chat), group sessions are multi-tenant — the target must be explicit.
 
 > **Note:** The `--to` value is the Quiubo group UUID, visible in the group detail screen or conversation URL.
 
+#### Named agent crons
+
+The `--announce` delivery mode does not work reliably with `--agent <id>` (see [openclaw/openclaw#32432](https://github.com/openclaw/openclaw/issues/32432)). The workaround is `--no-deliver` — the agent sends the message itself using the message tool:
+
+```bash
+openclaw cron add --name "giskard-standup" --agent giskard --every 24h \
+  --no-deliver \
+  --to 7868cc21-... \
+  --message 'Post the daily standup summary to the Quiubo group chat.'
+```
+
+With `--no-deliver`, the cron skips the announce pipeline entirely. The agent receives the prompt and sends messages through its own account binding, which correctly resolves identity and group routing.
+
+**Why this works:** Announce delivery resolves targets using a different code path that lacks proper account resolution for named agents. With `--no-deliver`, the agent uses the standard message tool path, which goes through the agent's own channel binding (`quiubo:accountId`).
+
+#### Delivery mode comparison
+
+| Mode | Flag | How it works | Named agent support |
+|------|------|-------------|-------------------|
+| Announce | `--announce` (default) | Cron delivers output via channel adapter | ❌ Fails for `--agent` |
+| No deliver | `--no-deliver` | Agent sends messages itself via message tool | ✅ Works |
+| Webhook | `--webhook --to <url>` | Cron POSTs to your endpoint | ✅ Works |
+
 See [#84](https://github.com/bitlabs-com/quiubo/issues/84) for a planned improvement to auto-resolve the target from the session bound group.
 
 ## Managing Accounts

package/dist/index.d.ts

@@ -12,12 +12,17 @@ export { startWebhookServer, type WebhookHandlerOptions } from './src/webhook-ha
 export type { QuiuboAccountConfig, QuiuboGroup, QuiuboMessage, QuiuboIdentity, QuiuboJoinToken, QuiuboAuthResponse, WebhookPayload, WebhookMessageData, WebhookJoinTokenRedeemedData, } from './src/types.js';
 interface OpenClawPluginApi {
     runtime: unknown;
+    config?: unknown;
     registerChannel: (opts: {
         plugin: any;
     }) => void;
     registerTool: (tool: any, opts?: {
         name?: string;
     }) => void;
+    registerHook: (events: string | string[], handler: (...args: any[]) => any, opts?: {
+        name?: string;
+        description?: 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;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,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;IACjB,MAAM,CAAC,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;IAE5D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACrI;AAED,QAAA,MAAM,MAAM;;;;kBAII,iBAAiB;CAMhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -14818,6 +14818,123 @@ function createQuiuboPostToolFactory(ctx) {
   };
 }
 
+// src/group-context-hook.ts
+var CACHE_TTL_MS = 6e4;
+var cache = /* @__PURE__ */ new Map();
+function getCached(groupId) {
+  const entry = cache.get(groupId);
+  if (!entry) return void 0;
+  if (Date.now() > entry.expiry) {
+    cache.delete(groupId);
+    return void 0;
+  }
+  return entry.data;
+}
+function setCache(groupId, data) {
+  cache.set(groupId, { data, expiry: Date.now() + CACHE_TTL_MS });
+}
+function extractGroupIdFromSessionKey2(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 extractAgentIdFromSessionKey2(key) {
+  if (!key) return "main";
+  const match = key.match(/^agent:([^:]+):quiubo:/);
+  return match?.[1] ?? "main";
+}
+function resolveAccountId2(config, agentId) {
+  const bindings = config?.bindings ?? [];
+  const matched = bindings.find(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (b) => b?.match?.channel === "quiubo" && b?.agentId === agentId
+  );
+  return matched?.match?.accountId ?? "default";
+}
+var DEFAULT_API_URL3 = "https://api.quiubo.chat/v1";
+async function fetchGroupContext(config, sessionKey) {
+  const groupId = extractGroupIdFromSessionKey2(sessionKey);
+  if (!groupId) return void 0;
+  const cached = getCached(groupId);
+  if (cached) return cached;
+  const agentId = extractAgentIdFromSessionKey2(sessionKey);
+  const accountId = resolveAccountId2(config, agentId);
+  const quiuboConfig = config?.channels?.quiubo;
+  const accountCfg = quiuboConfig?.accounts?.[accountId];
+  if (!accountCfg?.apiKey) return void 0;
+  const client = new QuiuboApiClient(
+    accountCfg.apiUrl ?? DEFAULT_API_URL3,
+    accountCfg.apiKey
+  );
+  const [group, { members }, { agents }] = await Promise.all([
+    client.getGroup(groupId),
+    client.listGroupMembers(groupId),
+    client.listAgents()
+  ]);
+  const botIdentityIds = new Set(agents.map((a) => a.identityId));
+  const currentAgent = agents.find((a) => a.identityId === accountCfg.botIdentityId);
+  const e2eeEnabled = currentAgent?.e2eeConfigured ?? false;
+  let scopes = [];
+  if (currentAgent) {
+    try {
+      const status = await client.getGroupAgent(currentAgent.id, groupId);
+      scopes = status?.grantedScopes ?? [];
+    } catch {
+    }
+  }
+  const data = {
+    groupId,
+    groupName: group.name,
+    groupType: group.groupType ?? "standard",
+    e2ee: e2eeEnabled,
+    members: members.map((m) => ({
+      displayName: m.displayName ?? m.identityId,
+      isBot: botIdentityIds.has(m.identityId),
+      role: m.role
+    })),
+    scopes
+  };
+  setCache(groupId, data);
+  return data;
+}
+function formatContextBlock(data) {
+  const memberList = data.members.map((m) => `${m.displayName} (${m.isBot ? "bot" : "human"}${m.role === "owner" ? ", owner" : ""})`).join(", ");
+  const lines = [
+    "[Quiubo Group Context]",
+    `Group: "${data.groupName}" (${data.groupId})`,
+    `Type: ${data.groupType === "agent_channel" ? "agent channel" : data.groupType}`,
+    `Members: ${memberList}`,
+    `E2EE: ${data.e2ee ? "enabled" : "disabled"}`
+  ];
+  if (data.scopes.length > 0) {
+    lines.push(`Scopes: ${data.scopes.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function registerGroupContextHook(api) {
+  api.registerHook(
+    "before_prompt_build",
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async (_event, ctx) => {
+      if (ctx.channelId !== "quiubo") return;
+      try {
+        const config = api.runtime?.config ?? api.config;
+        const data = await fetchGroupContext(config, ctx.sessionKey);
+        if (!data) return;
+        return {
+          prependSystemContext: formatContextBlock(data)
+        };
+      } catch (err) {
+        console.warn(`[quiubo] group-context-hook failed: ${err}`);
+        return;
+      }
+    },
+    { name: "quiubo-group-context" }
+  );
+}
+
 // src/polling-gateway.ts
 var PollingGateway = class {
   client;
@@ -14966,6 +15083,7 @@ var plugin = {
     setQuiuboRuntime(api.runtime);
     api.registerChannel({ plugin: quiuboPlugin });
     api.registerTool(createQuiuboPostToolFactory, { name: "quiubo_create_post" });
+    registerGroupContextHook(api);
   }
 };
 var index_default = plugin;