openclaw-quiubo 2.6.28 → 2.6.31

package/MULTI_AGENT.md

@@ -0,0 +1,281 @@
+# Multi-Agent Setup
+
+One gateway. Multiple agents. Each with its own chat, model, workspace, and schedule — completely isolated from each other.
+
+## What You Get
+
+- **Own chat** — separate Quiubo identity and conversation thread
+- **Own model** — Opus for heavy thinking, Haiku for lightweight jobs
+- **Own workspace** — files, memory, history are private
+- **Own schedule** — cron jobs scoped per agent
+- **One key** — all agents share your SDK API key (and its quota — see [API Key Quota](#api-key-quota))
+
+## Example
+
+**Bob** is your personal assistant (Opus, handles research and writing).
+**Sam** is your project manager (Sonnet, runs standups and tracks tasks).
+
+Both appear as separate chats in Quiubo — independent conversations, independent workspaces.
+
+## Setup
+
+### 1. Add a bot identity
+
+Run the interactive wizard to add a new account:
+
+```bash
+openclaw channels add
+```
+
+The wizard asks for three things:
+- **Account ID** — short name for this agent (e.g. `pm`, `research`). Your first agent uses `default`.
+- **SDK API Key** — reuse your existing `qub_...` key.
+- **Bot identity** — choose "Create new bot identity" to give this agent its own name in Quiubo.
+
+### 2. Register the agent
+
+Add an entry to `agents.list` in `~/.openclaw/openclaw.json`. Give it a unique ID and its own workspace path:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.openclaw/workspace"
+    },
+    "list": [
+      {
+        "id": "main",
+        "subagents": { "allowAgents": ["*"] }
+      },
+      {
+        "id": "project-manager",
+        "name": "Sam",
+        "model": "anthropic/claude-sonnet-4-5",
+        "workspace": "~/.openclaw/workspace-project-manager",
+        "agentDir": "~/.openclaw/agents/project-manager/agent",
+        "subagents": { "allowAgents": ["*"] }
+      }
+    ]
+  }
+}
+```
+
+The `main` agent inherits `workspace` from `agents.defaults`. Non-main agents override it with their own path.
+
+- **`workspace`** — the agent's working directory (files it creates, edits, and reads during tasks).
+- **`agentDir`** — the agent's identity/state directory (`IDENTITY.md`, `SOUL.md`, `AGENTS.md`, memory). Optional — defaults to a path under `~/.openclaw/agents/{id}/agent`. Set it explicitly if you want control over where identity files live.
+
+### 3. Bind account to agent
+
+Tell OpenClaw which Quiubo account maps to which agent using the `bindings` array:
+
+```json
+{
+  "bindings": [
+    {
+      "agentId": "main",
+      "match": {
+        "channel": "quiubo",
+        "accountId": "default"
+      }
+    },
+    {
+      "agentId": "project-manager",
+      "match": {
+        "channel": "quiubo",
+        "accountId": "pm"
+      }
+    }
+  ]
+}
+```
+
+*Without bindings, all messages route to the first agent in the list.*
+
+### 4. Create the workspace
+
+```bash
+mkdir -p ~/.openclaw/workspace-project-manager
+mkdir -p ~/.openclaw/agents/project-manager/agent/memory
+```
+
+Seed the agent dir with identity files: `SOUL.md`, `AGENTS.md`, `USER.md`, `IDENTITY.md`, `MEMORY.md`.
+
+To help the agent understand the multi-agent setup, add this to its `AGENTS.md`:
+
+```markdown
+## Multi-Agent Architecture
+This agent runs as part of a multi-agent OpenClaw gateway.
+Each agent has its own chat, workspace, and cron jobs.
+```
+
+> **Note:** If you use auth profiles (e.g. GitHub tokens), each agent workspace needs its own `config.json` or shared auth config.
+
+### 5. Restart
+
+```bash
+openclaw gateway restart
+```
+
+The new agent gets its own welcome chat automatically.
+
+## Config Integrity Warning
+
+Your config will have account data in **two** places:
+
+| Location | Who writes it | Who reads it |
+|----------|---------------|--------------|
+| `channels.quiubo.accounts` | `openclaw channels add` wizard | **The plugin** (source of truth) |
+| `plugins.entries.openclaw-quiubo.config.accounts` | OpenClaw core (mirrors plugin config) | OpenClaw core |
+
+The plugin reads **only** from `channels.quiubo.accounts`. If that section is missing or empty, the plugin silently does nothing — no `[quiubo]` logs, no errors, just gone.
+
+> **The #1 footgun:** an agent running `config.patch` that omits `channels` will wipe `channels.quiubo.accounts` entirely. The plugin dies on the next restart while everything else looks fine.
+>
+> **Rule of thumb:** never do a full config write/patch that doesn't preserve `channels`. Always merge rather than replace.
+
+## API Key Quota
+
+All accounts sharing the same `qub_...` API key share its monthly request quota. If one agent is chatty enough to exhaust the limit, **all** agents using that key stop working on the next restart.
+
+Options:
+- **One key, shared quota** — simpler setup, fine for low-traffic agents.
+- **Separate keys per account** — independent quotas, each agent can hit its own ceiling without affecting others.
+
+## How It Works
+
+```
+┌─────────────────────────┐
+│    OpenClaw Gateway     │
+└────────┬────────────────┘
+         │
+  ┌──────────────┼──────────────┐
+  ▼              ▼              ▼
+account:default  account:pm     account:research
+  │              │              │
+┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+│ gateway │    │ gateway │    │ gateway │
+│ client  │    │ client  │    │ client  │
+│ logger  │    │ logger  │    │ logger  │
+│ cursor  │    │ cursor  │    │ cursor  │
+└────┬────┘    └────┬────┘    └────┬────┘
+     │              │              │
+  binding ──→    binding ──→    binding ──→
+agent:main     agent:pm       agent:research
+```
+
+**Isolation boundaries:**
+
+- **Per-account Maps** — each account gets its own gateway, API client, config, and logger.
+- **Per-account cursors** — `~/.openclaw/cron/quiubo-cursors-{accountId}.json` — no clobbering between agents.
+- **Per-account E2EE keys** — `~/.openclaw/cron/quiubo-keys-{accountId}.json` — each account's key seed. If lost, the agent re-enrolls its keys (may break E2EE for existing conversations).
+- **Session keys** — main agent uses `quiubo:{groupId}`, others use `agent:{agentId}:quiubo:{groupId}` — conversations never cross.
+- **Cron jobs** — filtered by `agentId` in `getActivityData()` — each agent's chat shows only its own scheduled jobs.
+- **Auto-provisioning** — each new account gets a welcome `agent_channel` group with `externalGroupId: auto-{accountId}`.
+- **Auto-registration** — on first startup, each account auto-registers an agent record in the Quiubo directory if none exists for its bot identity.
+
+**Agent resolution** (`resolveAgentId`): searches `bindings[]` for matching channel + accountId. Falls back to first agent in `agents.list`, then to `"main"`.
+
+## Cron Jobs
+
+Cron jobs are scoped per agent via the `agentId` field:
+
+```json
+{
+  "jobs": [
+    {
+      "id": "daily-standup",
+      "agentId": "project-manager",
+      "schedule": "0 9 * * 1-5",
+      "enabled": true,
+      "delivery": {
+        "channel": "quiubo",
+        "to": "<group-uuid>"
+      }
+    }
+  ]
+}
+```
+
+- **`agentId`**: Ensures only the "project-manager" agent sees/runs this job. **Required** — jobs without `agentId` are invisible to all agents.
+- **`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.
+
+## Full Config Reference
+
+Quiubo-relevant sections of `openclaw.json` for a 2-agent setup:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.openclaw/workspace"
+    },
+    "list": [
+      {
+        "id": "main",
+        "subagents": { "allowAgents": ["*"] }
+      },
+      {
+        "id": "project-manager",
+        "name": "Sam",
+        "model": "anthropic/claude-sonnet-4-5",
+        "workspace": "~/.openclaw/workspace-project-manager",
+        "agentDir": "~/.openclaw/agents/project-manager/agent",
+        "subagents": { "allowAgents": ["*"] }
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "main",
+      "match": {
+        "channel": "quiubo",
+        "accountId": "default"
+      }
+    },
+    {
+      "agentId": "project-manager",
+      "match": {
+        "channel": "quiubo",
+        "accountId": "pm"
+      }
+    }
+  ],
+  "channels": {
+    "quiubo": {
+      "accounts": {
+        "default": {
+          "enabled": true,
+          "apiKey": "qub_your_key_here",
+          "botIdentityId": "<main-bot-uuid>",
+          "apiUrl": "https://api.quiubo.io"
+        },
+        "pm": {
+          "enabled": true,
+          "apiKey": "qub_your_key_here",
+          "botIdentityId": "<pm-bot-uuid>",
+          "apiUrl": "https://api.quiubo.io"
+        }
+      }
+    }
+  }
+}
+```
+
+> **Note:** OpenClaw also mirrors account data into `plugins.entries.openclaw-quiubo.config.accounts`. The plugin ignores that copy — `channels.quiubo.accounts` is the only location that matters. See [Config Integrity Warning](#config-integrity-warning).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Plugin silently stops — no `[quiubo]` logs on startup | `channels.quiubo.accounts` is missing from config. An agent's `config.patch` likely wiped it. Restore the `channels` block and restart. |
+| Second agent doesn't respond | Check `bindings[]` — accountId must match exactly. Run `openclaw gateway restart`. |
+| Both agents reply to the same message | Missing or duplicate bindings. Each accountId needs exactly one binding. |
+| Agent dies on restart, others work fine | Check logs for `[FATAL] STARTUP FAILED`. Common causes: invalid/expired API key (401), permission error (403), or quota exhausted. Rotate the key or check usage. |
+| Cron job runs in wrong chat | Verify `agentId` on the job matches the target agent, and `delivery.to` uses the correct group UUID. |
+| "welcome group already exists" on restart | Normal — auto-provisioning is safe. The existing group is reused. |
+| Agent shows other agent's cron jobs | The `agentId` on the job doesn't match. Double-check spelling. |
+| Cron job never runs / missing from activity | Missing `agentId` field on the job. Untagged jobs are invisible to all agents — the filter requires an exact match. |

package/README.md

@@ -17,7 +17,7 @@ openclaw plugins update openclaw-quiubo
 ## Setup
 
 ```bash
-openclaw channels add --channel quiubo
+openclaw channels add
 ```
 
 The interactive wizard will:
@@ -58,7 +58,7 @@ channels:
 
 ### Multiple accounts
 
-Run the setup wizard again and enter a different Account ID when prompted (e.g., `support-bot`, `sales-bot`). Each account gets its own gateway instance, cursor file, and bot config cache.
+Run the setup wizard again and enter a different Account ID when prompted (e.g., `support-bot`, `sales-bot`). Each account gets its own gateway instance, cursor file, and bot config cache. For full multi-agent isolation (separate workspaces, models, cron jobs), see the **[Multi-Agent Setup guide](./MULTI_AGENT.md)**.
 
 ## Architecture
 
@@ -98,7 +98,7 @@ Four layers prevent old messages from being reprocessed on restart:
 
 The plugin supports Quiubo's E2EE protocol for groups that require it:
 
-- **Key generation**: Deterministic Ed25519 + X25519 keypairs derived from a 32-byte seed (persisted in config)
+- **Key generation**: Deterministic Ed25519 + X25519 keypairs derived from a 32-byte seed (persisted to `~/.openclaw/cron/quiubo-keys-{accountId}.json`)
 - **Auto-enrollment**: On first startup, generates keypair and enrolls via challenge-response (`requestKeyChallenge` > `signChallenge` > `verifyKeyChallenge`)
 - **Inbound decryption**: GroupEnvelopeV2 messages decrypted using XChaCha20-Poly1305 with epoch keys
 - **Outbound encryption**: Plaintext encrypted before sending when E2EE is granted for the group
@@ -143,95 +143,16 @@ On first gateway startup, if the bot has no groups, the plugin automatically cre
 
 ## Multi-Agent Setup
 
-Run multiple AI agents on a single OpenClaw gateway — each with their own Quiubo chat, workspace, model, and cron jobs.
+Run multiple agents on a single gateway — each with its own chat, model, workspace, and cron jobs.
 
-### Step 1: Add the agent
+1. `openclaw channels add` — create a new bot identity
+2. Add the agent and binding to `~/.openclaw/openclaw.json`
+3. Create the agent's workspace
+4. `openclaw gateway restart`
 
-In `~/.openclaw/openclaw.json`:
+All agents share one SDK API key (and its quota). Each gets fully isolated conversations, cursors, and session keys.
 
-```json
-{
-  "agents": {
-    "list": [
-      { "id": "main" },
-      {
-        "id": "project-manager",
-        "model": "anthropic/claude-sonnet-4-5",
-        "workspace": "~/.openclaw/workspace-project-manager"
-      }
-    ]
-  }
-}
-```
-
-### Step 2: Add a Quiubo account for the agent
-
-Each account needs its own bot identity (can share the same API key):
-
-```json
-{
-  "plugins": {
-    "quiubo": {
-      "accounts": {
-        "default": {
-          "sdkApiKey": "qub_...",
-          "botIdentityId": "<main-bot-uuid>"
-        },
-        "pm": {
-          "sdkApiKey": "qub_...",
-          "botIdentityId": "<pm-bot-uuid>"
-        }
-      }
-    }
-  }
-}
-```
-
-### Step 3: Bind accounts to agents
-
-```json
-{
-  "bindings": [
-    {
-      "match": { "channel": "quiubo", "accountId": "default" },
-      "agentId": "main"
-    },
-    {
-      "match": { "channel": "quiubo", "accountId": "pm" },
-      "agentId": "project-manager"
-    }
-  ]
-}
-```
-
-Without bindings, all messages route to the first agent.
-
-### Step 4: Create the agent's workspace
-
-```bash
-mkdir -p ~/.openclaw/workspace-project-manager/memory
-```
-
-Seed it with: `SOUL.md`, `AGENTS.md`, `USER.md`, `IDENTITY.md`, `MEMORY.md`.
-
-### Step 5: Restart
-
-```bash
-openclaw gateway restart
-```
-
-### How routing works
-
-```
-Quiubo Chat (You + Main Bot)  → account: default → binding → agent: main
-Quiubo Chat (You + PM Bot)    → account: pm      → binding → agent: project-manager
-```
-
-- **Messages**: AccountId resolves the agent via bindings
-- **Cron jobs**: Filtered by agentId — each agent's chat shows only its own
-- **Sessions**: Isolated session namespaces per agent, no cross-talk
-- **Workspaces**: Fully isolated — agents can't see each other's files
-- **Cursors**: Each account has its own cursor file — no clobbering
+**[Full guide](./MULTI_AGENT.md)** — architecture, config examples, cron setup, and troubleshooting.
 
 ## Markdown Attachments
 
@@ -239,7 +160,7 @@ Agents can send `.md` file attachments alongside messages. Attachments appear as
 
 OpenClaw's `MEDIA:` token protocol is used: when an agent writes a file and includes `MEDIA: /path/to/file.md` in its response, the plugin reads the file and sends it as a structured attachment.
 
-**Supported:** `.md` files only, max 1MB each. Source tracking distinguishes `agent` vs `subagent` attachments.
+**Supported:** `.md` files (max 1MB) and images — `.jpg`, `.jpeg`, `.png`, `.webp` (max 5MB, uploaded via S3 presign). Source tracking distinguishes `agent` vs `subagent` attachments.
 
 Add this to your agent's `AGENTS.md`:
 
@@ -256,20 +177,19 @@ Example response:
   MEDIA: /tmp/daily-report.md
 
 The file will be delivered as a tappable attachment card in the chat.
-Only `.md` files are supported. Files over 1MB are skipped.
+Supported: `.md` (max 1MB) and images `.jpg`/`.png`/`.webp` (max 5MB).
 ```
 
 ## Operational Notes
 
-### Cursor files
-
-Cursors are persisted at:
+### Per-account state files
 
-```
-~/.openclaw/cron/quiubo-cursors-{accountId}.json
-```
+Each account persists its own state files under `~/.openclaw/cron/`:
 
-Each account writes to its own file to avoid clobbering in multi-account setups. Safe to delete — the gateway will `seekToLatest()` on next start (no replay).
+| File | Purpose | Safe to delete? |
+|------|---------|-----------------|
+| `quiubo-cursors-{accountId}.json` | Message cursor positions | Yes — gateway will `seekToLatest()` on next start (no replay) |
+| `quiubo-keys-{accountId}.json` | E2EE key seed (32 bytes) | **No** — deleting forces re-enrollment, may break E2EE for existing conversations |
 
 ### Heartbeat
 
@@ -283,7 +203,7 @@ A typing indicator is sent immediately when processing begins, then repeated eve
 
 ```bash
 openclaw channels disable --channel quiubo  # Disable
-openclaw channels add --channel quiubo      # Re-configure
+openclaw channels add      # Re-configure
 ```
 
 ## Development