@swarmclawai/swarmclaw 0.7.1 → 0.7.3

package/README.md

@@ -14,6 +14,19 @@ Inspired by [OpenClaw](https://github.com/openclaw).
 
 **[Documentation](https://swarmclaw.ai/docs)** | **[Plugin Tutorial](https://swarmclaw.ai/docs/plugin-tutorial)** | **[Website](https://swarmclaw.ai)**
 
+## Documentation Map
+
+- [Getting Started](https://swarmclaw.ai/docs/getting-started) - install and first-run setup
+- [Providers](https://swarmclaw.ai/docs/providers) - provider setup and failover options
+- [Agents](https://swarmclaw.ai/docs/agents) - agent configuration, tools, and platform capabilities
+- [Tools](https://swarmclaw.ai/docs/tools) - built-in tool reference and guardrails
+- [Orchestration](https://swarmclaw.ai/docs/orchestration) - multi-agent flows, checkpoints, and restore
+- [Chatrooms](https://swarmclaw.ai/docs/chatrooms) - multi-agent rooms and routing
+- [Connectors](https://swarmclaw.ai/docs/connectors) - Discord/Slack/Telegram/WhatsApp and more
+- [Plugins](https://swarmclaw.ai/docs/plugins) - plugin architecture and extension points
+- [CLI Reference](https://swarmclaw.ai/docs/cli) - complete command reference
+- [Deployment](https://swarmclaw.ai/docs/deployment) - VPS, Docker, and production setup
+
 ![Dashboard](public/screenshots/dashboard.png)
 ![Agent Builder](public/screenshots/agents.png)
 ![Task Board](public/screenshots/tasks.png)
@@ -46,7 +59,7 @@ URLs without a protocol are auto-prefixed with `http://`. For remote gateways wi
 
 ## SwarmClaw ClawHub Skill
 
-Use the `swarmclaw` ClawHub skill when you want an OpenClaw agent to operate your SwarmClaw control plane directly from chat: list agents, dispatch tasks, check sessions, run diagnostics, and coordinate multi-agent work.
+Use the `swarmclaw` ClawHub skill when you want an OpenClaw agent to operate your SwarmClaw control plane directly from chat: list agents, dispatch tasks, check chats, run diagnostics, and coordinate multi-agent work.
 
 Install it from ClawHub:
 
@@ -68,6 +81,7 @@ Skill source and runbook: [`swarmclaw/SKILL.md`](swarmclaw/SKILL.md).
 - **Claude Code CLI** (optional, for `claude-cli` provider) — [Install](https://docs.anthropic.com/en/docs/claude-code/overview)
 - **OpenAI Codex CLI** (optional, for `codex-cli` provider) — [Install](https://github.com/openai/codex)
 - **OpenCode CLI** (optional, for `opencode-cli` provider) — [Install](https://github.com/opencode-ai/opencode)
+- **Gemini CLI** (optional, for `delegate` backend `gemini`) — install and authenticate `gemini` on your host
 
 ## Quick Start
 
@@ -85,7 +99,7 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 ```
 
 The installer resolves the latest stable release tag and installs that version by default.
-To pin a version: `SWARMCLAW_VERSION=v0.7.1 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v0.7.3 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -149,52 +163,23 @@ Notes:
 
 ## Features
 
-- **15 Built-in Providers** — Claude Code CLI, OpenAI Codex CLI, OpenCode CLI, Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, Together AI, Mistral AI, xAI (Grok), Fireworks AI, Ollama, plus custom OpenAI-compatible endpoints
-- **OpenClaw Gateway** — Per-agent toggle to connect any agent to a local or remote OpenClaw gateway. Each agent gets its own gateway URL and token — run a swarm of OpenClaws from one dashboard. The `openclaw` CLI ships as a bundled dependency (no separate install needed)
-- **OpenClaw Control Plane** — Built-in gateway connection controls, reload mode switching (hot/hybrid/full), config issue detection/repair, remote history sync, and live execution approval handling
-- **Gateway Watchdog** — Proactive gateway health monitoring with auto-repair via `openclaw doctor`, outbound ops alerts to Discord/Slack/custom webhooks, workspace backup/rollback/history tools for agents, and connector liveness detection
-- **Agent Builder** — Create agents with custom personalities (soul), system prompts, tools, and skills. AI-powered generation from a description
-- **Agent Inspector Panel** — Per-agent side panel for OpenClaw file editing (`SOUL.md`, `IDENTITY.md`, `USER.md`, etc.), guided personality editing, skill install/enable/remove, permission presets, sandbox env allowlist, and cron automations
-- **Agent Fleet Management** — Avatar seeds with generated avatars, running/approval fleet filters, soft-delete agent trash with restore/permanent delete, and approval counters in agent cards
-- **Agent Tools** — Shell, process control for long-running commands, files, edit file, send file, web search, web fetch, CLI delegation (Claude/Codex/OpenCode), Playwright browser automation, sub-agent spawning, canvas presentation, direct HTTP requests, git operations, persistent memory, and sandboxed code execution (JS/TS via Deno, Python)
-- **Platform Tools** — Agents can manage other agents, tasks, schedules, skills, connectors, sessions, and encrypted secrets via built-in platform tools
-- **Orchestration** — Multi-agent workflows powered by LangGraph with automatic sub-agent routing, checkpointed execution, checkpoint timeline with time-travel restore, and rich delegation cards that link to sub-agent chat threads
-- **Agentic Execution Policy** — Tool-first autonomous action loop with progress updates, evidence-driven answers, and better use of platform tools for long-lived work
-- **Runtime Date/Time Grounding** — Session, orchestrator, chatroom, and connector prompts include authoritative current timestamp context to reduce stale-date behavior
-- **Task Board** — Queue and track agent tasks with status, comments, structured result artifacts (`outputFiles`, uploads), completion reports, and archiving. Strict capability policy pauses tasks for human approval before tool execution
-- **Task Metrics API** — Built-in analytics endpoint for WIP, cycle times, throughput velocity, completion/failure by agent, and priority distribution
-- **Background Daemon** — Auto-processes queued tasks and scheduled jobs with a 30s heartbeat plus recurring health monitoring
-- **Scheduling** — Cron-based agent scheduling with human-friendly presets
-- **Loop Runtime Controls** — Switch between bounded and ongoing loops with configurable step caps, runtime guards, heartbeat cadence, and timeout budgets
-- **Session Run Queue** — Per-session queued runs with followup/steer/collect modes, collect coalescing for bursty inputs, and run-state APIs
-- **Chat Iteration Workflow** — Edit-and-resend user turns, fork a new session from any message, bookmark key messages, use contextual follow-up suggestion chips, and auto-continue after tool access grants
-- **Agent Chatrooms** — Multi-agent room conversations with `@mention` routing, chained agent replies, reactions, file/image-aware context, health-aware member filtering, and persistent context compaction for long-lived rooms
-- **Live Chat Telemetry** — Thinking/tool/responding stream phases, live main-loop status badges, connector activity presence, tone indicator, and optional sound notifications
-- **Global Search Palette** — `Cmd/Ctrl+K` search across agents, tasks, sessions, schedules, webhooks, and skills from anywhere in the app
-- **Notification Center** — Real-time in-app notifications for task/schedule/daemon events with unread tracking, mark-all/clear-read controls, and optional action links
-- **Preview-Rich Chat UI** — Side preview panel for tool outputs (image/browser/html/code), inline code/PDF previews for attachments, and image lightbox support
-- **Voice Settings** — Per-instance ElevenLabs API key + voice ID for TTS replies, plus configurable speech recognition language for chat input
-- **Chat Connectors** — Bridge agents to Discord, Slack, Telegram, WhatsApp, BlueBubbles (iMessage), Signal, Microsoft Teams, Google Chat, Matrix, and OpenClaw with media-aware inbound handling, inbound voice-note transcription (ElevenLabs/OpenAI fallback), and WhatsApp-friendly plain-text formatting
-- **Skills System** — Discover local skills, import skills from URL, and load OpenClaw `SKILL.md` files (frontmatter-compatible)
-- **Execution Logging** — Structured audit trail for triggers, tool calls, file ops, commits, and errors in a dedicated `logs.db`
-- **Context Management** — Auto-compaction of conversation history when approaching context limits, with manual `context_status` and `context_summarize` tools for agents
-- **Memory** — Per-agent and per-session memory with hybrid FTS5 + vector embeddings search, query expansion (LLM-generated semantic variants), MMR diversity ranking, cross-agent search (`scope: all`), pinned memories (always preloaded), memory sharing between agents, linked memory graph with interactive visualization, image attachments, and periodic auto-journaling for durable execution context
-- **Knowledge Base** — Shared knowledge store (`knowledge_store` / `knowledge_search` actions) with tags, source tracking, and provenance URLs — separate from per-agent memories
-- **Memory Graph Visualization** — Interactive force-directed graph view of linked memories with node details and relationship exploration
-- **Cost Tracking** — Per-message token counting and cost estimation displayed in the chat header, with per-agent monthly budget caps (`warn` or `block` enforcement)
-- **Provider Health Metrics** — Usage dashboard surfaces provider request volume, success rates, average latency, models used, and last-used timestamps
-- **Model Failover** — Automatic key rotation on rate limits and auth errors with configurable fallback credentials
-- **Plugin System** — Extend agent behavior with JS plugins (hooks: beforeAgentStart, afterAgentComplete, beforeToolExec, afterToolExec, onMessage, onTaskComplete, onAgentDelegation). Plugins can also define custom tools that agents can use
-- **Secrets Vault** — Encrypted storage for API keys and service tokens
-- **Custom Providers** — Add any OpenAI-compatible API as a provider
-- **MCP Servers** — Connect agents to any Model Context Protocol server. Per-agent server selection with tool discovery and per-tool disable toggles
-- **Sandboxed Code Execution** — Agents can write and run JS/TS (Deno) or Python scripts in an isolated sandbox with network access, scoped filesystem, and artifact output
-- **Eval Framework** — Built-in agent evaluation with scenario-based testing across categories (coding, research, companionship, multi-step, memory, planning, tool-usage), weighted scoring criteria, and LLM judge support
-- **Guardian Auto-Recovery** — Automatic workspace recovery when agents fail critically, rolling back to the last known good state via git reset
-- **Soul Library** — Browse and apply pre-built personality templates (archetypes) to agents, or create custom souls for reuse across your swarm
-- **Context Degradation Warnings** — Proactive alerts when context usage exceeds 85%, with strategy recommendations (save to memory, summarize, checkpoint)
-- **Real-Time Sync** — WebSocket push notifications for instant UI updates across tabs and devices (fallback to polling when WS is unavailable)
-- **Mobile-First UI** — Responsive glass-themed dark interface, works on phone and desktop
+- **15 providers out of the box** - CLI providers + major hosted APIs + OpenAI-compatible custom endpoints
+- **OpenClaw-native control plane** - per-agent gateway mapping, reload modes, sync, and approval flows
+- **Agent builder + inspector** - personality/system tuning, skill management, and OpenClaw file editing
+- **Rich toolset** - shell, files, browser, git, sandbox execution, memory, MCP, and delegation
+- **Platform automation** - agents can manage tasks, schedules, chats, connectors, secrets, and more
+- **LangGraph orchestration** - routing to sub-agents with checkpoint timeline and restore
+- **Task board + daemon + scheduler** - long-running autonomous workflows with heartbeat safety
+- **Chat UX** - edit/resend, fork, bookmarks, previews, telemetry, notifications, and search palette
+- **Multi-agent chatrooms** - room routing with mentions, reactions, and persistent context compaction
+- **Connector bridge** - Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, and others
+- **Memory + knowledge** - hybrid search, memory graph, shared knowledge store, and auto-journaling
+- **Operational guardrails** - capability policy, cost tracking, provider health, and credential failover
+- **Extensibility** - plugin hooks/tools/UI extensions plus reusable skills
+
+For the full feature matrix and per-capability details, see:
+- https://swarmclaw.ai/docs
+- https://swarmclaw.ai/docs/release-notes
 
 ## Configuration
 
@@ -206,7 +191,7 @@ CREDENTIAL_SECRET=<auto-generated>          # AES-256 encryption key for stored
 SWARMCLAW_PLUGIN_FAILURE_THRESHOLD=3        # Consecutive failures before auto-disabling a plugin
 ```
 
-Data is stored in `data/swarmclaw.db` (SQLite with WAL mode), `data/memory.db` (agent memory with FTS5 + vector embeddings), `data/logs.db` (execution audit trail), and `data/langgraph-checkpoints.db` (orchestrator checkpoints). Back the `data/` directory up if you care about your sessions, agents, and credentials. Existing JSON file data is auto-migrated to SQLite on first run.
+Data is stored in `data/swarmclaw.db` (SQLite with WAL mode), `data/memory.db` (agent memory with FTS5 + vector embeddings), `data/logs.db` (execution audit trail), and `data/langgraph-checkpoints.db` (orchestrator checkpoints). Back the `data/` directory up if you care about your chats, agents, and credentials. Existing JSON file data is auto-migrated to SQLite on first run.
 Agent wallet private keys are stored encrypted (AES-256 via `CREDENTIAL_SECRET`) in `data/swarmclaw.db` and are never returned by wallet API responses; keep `data/` out of version control.
 
 The app listens on two ports: `PORT` (default 3456) for the HTTP/SSE API, and `PORT + 1` (default 3457) for WebSocket push notifications. The WS port can be customized with `--ws-port`.
@@ -264,6 +249,8 @@ src/
 | xAI (Grok) | api.x.ai | Grok 3, Grok 3 Fast, Grok 3 Mini |
 | Fireworks AI | api.fireworks.ai | DeepSeek R1, Llama 3.3 70B, Qwen 3 |
 
+If a provider is configured, SwarmClaw can populate the model dropdown from that provider’s advertised model list. For OpenAI this means the selector can auto-fill current OpenAI models, while still allowing users to type a newer or custom model manually if it is not in the fetched list yet.
+
 ### Local & Remote
 
 | Provider | Type | Notes |
@@ -289,7 +276,7 @@ Bridge any agent to a chat platform:
 | Matrix | matrix-bot-sdk | Homeserver URL + access token |
 | OpenClaw | gateway protocol | OpenClaw connector credentials |
 
-Connector sessions preserve attachment visibility in chat context:
+Connector chats preserve attachment visibility in chat context:
 - WhatsApp media is decoded and persisted to `/api/uploads/...` when possible
 - Telegram and Slack attachments are downloaded to uploads when possible
 - Discord attachments are captured as media metadata/URLs
@@ -309,21 +296,25 @@ Agents can use the following tools when enabled:
 
 | Tool | Description |
 |-|-|
-| Shell | Execute commands in the session working directory |
+| Shell | Execute commands in the chat working directory |
 | Process | Control long-running shell commands (`process_tool`) |
 | Files | Read, write, list, and send files |
-| Copy/Move/Delete File | Optional file ops (`copy_file`, `move_file`, `delete_file`) configurable per agent/session (`delete_file` is off by default) |
+| Copy/Move/Delete File | Optional file ops (`copy_file`, `move_file`, `delete_file`) configurable per agent/chat (`delete_file` is off by default) |
 | Edit File | Search-and-replace editing (exact match required) |
 | Web Search | Search the web via DuckDuckGo HTML scraping |
 | Web Fetch | Fetch and extract text content from URLs (uses cheerio) |
-| CLI Delegation | Delegate complex tasks to Claude Code, Codex CLI, or OpenCode CLI |
-| Spawn Subagent | Delegate a sub-task to another agent and capture its response in the current run |
-| Browser | Playwright-powered web browsing via MCP (navigate, click, type, screenshot, PDF) |
-| Canvas | Present/hide/snapshot live HTML content in a session canvas panel |
+| CLI Delegation | Delegate complex tasks to Claude Code, Codex CLI, OpenCode CLI, or Gemini CLI, either inline or as a background job handle |
+| Spawn Subagent | Delegate a sub-task to another agent with `status` / `list` / `wait` / `cancel` handles and inherited browser state when needed |
+| Browser | Playwright-powered web browsing via MCP with persistent profiles, structured page reads, form helpers, verification actions, and resumable state |
+| Canvas | Present/hide/snapshot live HTML content in a chat canvas panel |
 | HTTP Request | Make direct API calls with method, headers, body, redirect control, and timeout |
 | Git | Run structured git subcommands (`status`, `diff`, `log`, `add`, `commit`, `push`, etc.) with repo safety checks |
 | Memory | Store and retrieve long-term memories with FTS5 + vector search, file references, image attachments, and linked memory graph traversal |
+| Monitor | Inspect system state and create durable watches over files, endpoints, tasks, webhooks, and page/content changes (`monitor_tool`) |
 | Wallet | Manage an agent-linked Solana wallet (`wallet_tool`) to check balance/address, send SOL (limits + approval), and review transaction history |
+| Image Generation | Generate images from prompts (`generate_image`) via OpenAI, Stability, Replicate, fal.ai, Together, Fireworks, BFL, or custom endpoints; saved to uploads |
+| Email | Send outbound email via SMTP (`email`) with `send`/`status` actions |
+| Calendar | Manage Google/Outlook events (`calendar`) with list/create/update/delete/status actions |
 | Sandbox | Run JS/TS (Deno) or Python code in an isolated sandbox. Created files are returned as downloadable artifacts |
 | MCP Servers | Connect to external Model Context Protocol servers. Tools from MCP servers are injected as first-class agent tools |
 
@@ -336,16 +327,16 @@ Agents with platform tools enabled can manage the SwarmClaw instance:
 | Manage Agents | List, create, update, delete agents |
 | Manage Tasks | Create and manage task board items with agent assignment |
 | Manage Schedules | Create cron, interval, or one-time scheduled jobs |
-| Reminders | Schedule a conversational wake event in the current chat (`schedule_wake`) |
+| Reminders | Schedule a durable conversational wake event in the current chat (`schedule_wake`) |
 | Manage Skills | List, create, update reusable skill definitions |
 | Manage Documents | Upload/search/get/delete indexed docs for lightweight RAG workflows |
-| Manage Webhooks | Register external webhook endpoints that trigger agent sessions |
+| Manage Webhooks | Register external webhook endpoints that trigger agent chats |
 | Manage Connectors | Manage chat platform bridges |
 | Manage Chatrooms | Create/list/update chatrooms, manage members, and post room messages for multi-agent collaboration |
-| Manage Sessions | Enable `sessions_tool` for list/history/status/send/spawn/stop, plus `context_status` and `context_summarize` for context window management |
+| Manage Chats | Enable `sessions_tool` for list/history/status/send/spawn/stop across chats, plus `context_status` and `context_summarize` for context window management |
 | Manage Secrets | Store and retrieve encrypted reusable secrets |
 
-Enable tools per-session or per-agent in the UI. CLI providers (Claude Code, Codex, OpenCode) handle tools natively through their own CLI.
+Enable tools per-chat or per-agent in the UI. CLI providers (Claude Code, Codex, OpenCode) handle tools natively through their own CLI.
 OpenClaw provider capabilities are also managed remotely in OpenClaw itself, so local Tools/Platform toggles are hidden for OpenClaw agents.
 
 ## Starter Skills (URL Import)
@@ -359,7 +350,7 @@ Import these directly in **Skills → Import via URL**:
 
 Token usage and estimated costs are tracked per message for API-based providers (Anthropic, OpenAI). After each response, a badge in the chat header shows token count and estimated cost.
 
-- **API endpoint:** `GET /api/usage` — returns usage summary by session and provider
+- **API endpoint:** `GET /api/usage` — returns usage summary by agent/provider plus plugin-level token rollups (`byPlugin`)
 - **Data:** Stored in `data/swarmclaw.db` (usage table)
 - Cost estimates use published model pricing (updated manually in `src/lib/server/cost.ts`)
 
@@ -372,7 +363,7 @@ Task analytics are available via API for dashboarding and release-readiness chec
 
 ## Background Daemon
 
-The daemon auto-processes queued tasks from the scheduler on a 30-second interval. It also runs recurring health checks that detect stale heartbeat sessions and can send proactive WhatsApp alerts when issues are detected. Toggle the daemon from the sidebar indicator or via API.
+The daemon auto-processes queued tasks from the scheduler on a 30-second interval. It also runs recurring health checks that detect stale heartbeat chats and can send proactive WhatsApp alerts when issues are detected. Toggle the daemon from the sidebar indicator or via API.
 
 Daemon runtime also triggers memory consolidation (daily summary generation plus recurring dedupe/prune maintenance).
 
@@ -381,7 +372,7 @@ Daemon runtime also triggers memory consolidation (daily summary generation plus
 
 ## Main Agent Loop
 
-For autonomous long-running missions, enable the **Main Loop** on a session. This lets an agent pursue a goal continuously with heartbeat-driven progress checks and automatic followups.
+For autonomous long-running missions, enable the **Main Loop** on an agent-thread or orchestrated chat. This lets an agent pursue a goal continuously with heartbeat-driven progress checks and automatic followups.
 
 - **Heartbeat prompts:** `SWARM_MAIN_MISSION_TICK` triggers on each heartbeat, giving the agent its goal, status, and pending events
 - **Auto-followup:** When an agent returns `[MAIN_LOOP_META] {"follow_up":true}`, the loop schedules another tick after `delay_sec`
@@ -389,8 +380,8 @@ For autonomous long-running missions, enable the **Main Loop** on a session. Thi
 - **Autonomy modes:**
   - `autonomous`: Agent executes safe actions without confirmation, only asks when blocked by permissions/credentials
   - `assist`: Agent asks before irreversible external actions (sending messages, purchases, account mutations)
-- **API:** `POST /api/sessions/[id]/main-loop` with `{"tick":true}` to trigger a mission tick
-- **CLI:** `swarmclaw sessions main-loop <id>` to inspect loop state, or `swarmclaw sessions main-loop-action <id> --data '{"action":"nudge"}'` to control it
+- **API:** `POST /api/chats/[id]/main-loop` with `{"tick":true}` to trigger a mission tick
+- **CLI:** `swarmclaw chats main-loop <id>` to inspect loop state, or `swarmclaw chats main-loop-action <id> --data '{"action":"nudge"}'` to control it
 
 Use this for background agents that should "keep working" on a goal until blocked or complete.
 
@@ -412,7 +403,7 @@ Configure this in **Settings → Capability Policy** to centrally govern tool ac
 - **Blocked tools:** specific tool families or concrete tool names
 - **Allowed tools:** explicit overrides when running stricter modes
 
-Policy is enforced in both session tool construction and direct forced tool invocations, so auto-routing and explicit tool requests use the same guardrails.
+Policy is enforced in both chat tool construction and direct forced tool invocations, so auto-routing and explicit tool requests use the same guardrails.
 
 ## CLI Troubleshooting
 
@@ -430,11 +421,11 @@ Policy is enforced in both session tool construction and direct forced tool invo
 Configure these in **Settings**:
 
 - **Voice** — set `ElevenLabs API Key`, `ElevenLabs Voice ID`, and `Speech Recognition Language`
-- **Heartbeat** — set `Heartbeat Interval (Seconds)` and `Heartbeat Prompt` for ongoing session pings
-- **Global heartbeat safety** — use `Stop All Session Heartbeats` to disable heartbeat across all sessions and cancel in-flight heartbeat runs.
+- **Heartbeat** — set `Heartbeat Interval (Seconds)` and `Heartbeat Prompt` for ongoing chat pings
+- **Global heartbeat safety** — use `Stop All Heartbeats` to disable heartbeat across all chats and cancel in-flight heartbeat runs.
 
-Heartbeat pings are internal checks for ongoing sessions. If there's no new status, the assistant returns `HEARTBEAT_OK`; otherwise it returns a concise progress update and next step. In chat UI, heartbeat entries render as compact expandable cards and consecutive heartbeat streaks are collapsed to the latest item.
-The daemon health monitor also auto-disables heartbeat on sessions that remain stale for an extended period.
+Heartbeat pings are internal checks for ongoing chats. If there's no new status, the assistant returns `HEARTBEAT_OK`; otherwise it returns a concise progress update and next step. In chat UI, heartbeat entries render as compact expandable cards and consecutive heartbeat streaks are collapsed to the latest item.
+The daemon health monitor also auto-disables heartbeat on chats that remain stale for an extended period.
 
 ## Embeddings & Hybrid Memory Search
 
@@ -448,13 +439,13 @@ When enabled, new memories get vector embeddings. Search uses both FTS5 keyword
 
 ## Model Failover
 
-Agents and sessions can have **fallback credentials**. If the primary API key gets a 401, 429, or 500 error, SwarmClaw automatically retries with the next credential. Configure fallback keys in the agent builder UI.
+Agents and chats can have **fallback credentials**. If the primary API key gets a 401, 429, or 500 error, SwarmClaw automatically retries with the next credential. Configure fallback keys in the agent builder UI.
 
 ## Plugin System
 
-SwarmClaw features a powerful, modular plugin system designed for both agent enhancement and application extensibility. It is fully compatible with the **OpenClaw** plugin format.
+SwarmClaw features a modular plugin system for agent capabilities, UI extensions, provider/connectors, and post-turn automation. It supports the native SwarmClaw hook/tool format and the **OpenClaw** register/activate formats.
 
-Plugins can be managed in **Settings → Plugins** and installed via the Marketplace, URL, or by dropping `.js` files into `data/plugins/`.
+Plugins can be managed in **Settings → Plugins** and installed via the Marketplace, HTTPS URL, or by dropping `.js` / `.mjs` files into `data/plugins/`.
 
 Docs:
 - Full docs: https://swarmclaw.ai/docs
@@ -465,17 +456,30 @@ Docs:
 Unlike standard tool systems, SwarmClaw plugins can modify the application itself:
 
 - **Agent Tools**: Define custom tools that agents can autonomously discover and use.
-- **Lifecycle Hooks**: Intercept events like `beforeAgentStart`, `afterToolExec`, and `onMessage`.
+- **Lifecycle Hooks**: Intercept events like `beforeAgentStart`, `beforeToolExec`, `afterToolExec`, `afterChatTurn`, and `onMessage`.
 - **UI Extensions**:
   - `sidebarItems`: Inject new navigation links into the main sidebar.
   - `headerWidgets`: Add status badges or indicators to the chat header (e.g., Wallet Balance).
   - `chatInputActions`: Add custom action buttons next to the chat input (e.g., "Quick Scan").
   - `plugin-ui` Messages: Render rich, interactive React cards in the chat stream.
 - **Deep Chat Hooks**:
-  - `transformInboundMessage`: Modify user messages before they reach the agent.
-  - `transformOutboundMessage`: Modify agent responses before they are saved or displayed.
+  - `transformInboundMessage`: Modify user messages before they reach the agent runtime.
+  - `transformOutboundMessage`: Modify agent responses before they are persisted or displayed.
+  - `beforeToolExec`: Can rewrite tool input before the selected tool executes.
 - **Custom Providers**: Add new LLM backends (e.g., a specialized local model or a new API).
 - **Custom Connectors**: Build new chat platform bridges (e.g., a proprietary internal messenger).
+- **Per-plugin Settings**: Declare `ui.settingsFields` and read/write them via `/api/plugins/settings`. Fields marked `type: 'secret'` are encrypted at rest.
+
+### Canonical Plugin IDs
+
+Built-in capabilities now resolve to a single canonical plugin family ID across agent configs, policy rules, approvals, and the Plugins UI. Legacy aliases still work, but the canonical IDs are what you should document and store going forward.
+
+- `manage_sessions` instead of `session_info`
+- `manage_connectors` instead of `connectors`
+- `http_request` instead of `http`
+- `spawn_subagent` instead of `subagent`
+- `manage_chatrooms` instead of `chatroom`
+- `schedule_wake` instead of `schedule`
 
 ### Autonomous Capability Discovery
 
@@ -506,12 +510,53 @@ module.exports = {
 };
 ```
 
+Hook signatures of note:
+
+- `beforeToolExec({ toolName, input })` may return a replacement input object.
+- `afterToolExec({ session, toolName, input, output })` observes completed tool executions.
+- `transformInboundMessage({ session, text })` and `transformOutboundMessage({ session, text })` run sequentially across enabled plugins.
+
+### Building Plugins
+
+The shortest reliable workflow for a new plugin:
+
+1. Create a focused `.js` or `.mjs` file under `data/plugins/`.
+2. Export `name`, `description`, any `hooks`, and optional `tools` / `ui.settingsFields`.
+3. Keep tool outputs structured when the agent needs to chain them into later steps.
+4. Use `settingsFields` for secrets or environment-specific values instead of hardcoding them.
+5. If the plugin needs third-party npm packages, attach a `package.json` manifest so SwarmClaw can manage it in a per-plugin workspace.
+6. Enable the plugin in **Settings → Plugins** and test both the tool path and any hook behavior.
+7. If you host it remotely, install from a stable HTTPS URL so SwarmClaw can record source metadata and update it later.
+
+A fuller step-by-step walkthrough lives at https://swarmclaw.ai/docs/plugin-tutorial.
+
 ### Lifecycle Management
 
 - **Versioning**: All plugins support semantic versioning (e.g., `v1.2.3`).
-- **Updates**: Plugins can be updated individually or in bulk via the Plugins manager.
-- **Hot-Reload**: The system automatically reloads plugin logic when a file is updated or a new plugin is installed.
-- **Stability Guardrails**: Consecutive plugin failures are tracked in `data/plugin-failures.json`; failing plugins are auto-disabled, a warning notification is emitted in-app, and users can re-enable manually from the Plugins manager.
+- **Updates**: External plugins installed from a recorded source URL can be updated individually or in bulk via the Plugins manager. Built-ins update with the app release.
+- **Hot Reload**: Changes inside `data/plugins/` invalidate the plugin registry automatically, and installs/updates trigger an immediate reload.
+- **Plugin Workspaces**: Plugins with a manifest are managed under `data/plugins/.workspaces/<plugin>/`, and dependency installs can be triggered from the plugin detail sheet or `POST /api/plugins/dependencies`.
+- **Stability Guardrails**: Consecutive plugin failures are tracked in `data/plugin-failures.json`; failing external plugins are auto-disabled, a warning notification is emitted in-app, and users can re-enable manually from the Plugins manager.
+- **Source Metadata**: Marketplace/URL installs record the normalized source URL and source hash in `data/plugins.json`.
+- **Settings Safety**: Plugin settings are validated against declared `settingsFields`; unknown keys are ignored and `secret` values are stored encrypted.
+
+### Browser, Watch, and Delegation Upgrades
+
+- **Persistent Browser Profiles**: The built-in `browser` plugin now keeps a reusable profile per chat/session, and subagents inherit the parent profile by default. Profiles live under `~/.swarmclaw/browser-profiles` unless you override `BROWSER_PROFILES_DIR`, so cookies, storage, and authenticated state survive longer-running work without polluting the project tree. Browser state is exposed at `GET /api/chats/[id]/browser`.
+- **Higher-Level Browser Actions**: In addition to raw Playwright-style actions, `browser` supports workflow-oriented actions such as `read_page`, `extract_links`, `extract_form_fields`, `extract_table`, `fill_form`, `submit_form`, `scroll_until`, `download_file`, `complete_web_task`, `verify_text`, `verify_element`, `verify_list`, `verify_value`, `profile`, and `reset_profile`.
+- **Structured Browser State**: Browser sessions persist recent observations, tabs, artifacts (screenshots / PDFs / downloads), current URL, and last errors in `browser_sessions`, which makes autonomous browser tasks easier to resume, inspect, and hand off across turns.
+- **Durable Watches**: `schedule_wake` now uses persisted watch jobs instead of an in-memory timer, and `monitor_tool` supports `create_watch`, `list_watches`, `get_watch`, and `cancel_watch` across `time`, `http`, `file`, `task`, `webhook`, and `page` conditions. The same watch system also powers the new `mailbox`, session-mailbox, and approval waits used by human-loop flows. Watches support common checks like status/status sets, regex or text matches, content changes, existence checks, inbound mailbox correlation IDs, and webhook event filters.
+- **Long-Running Delegation Handles**: `delegate` and `spawn_subagent` support handle-based flows instead of only synchronous final text. Use `background=true` or `waitForCompletion=false` to launch long-running work, then inspect or stop it with `action=status|list|wait|cancel`.
+- **Delegation Job Persistence**: Delegate and subagent runs are recorded in `delegation_jobs` with checkpoints, backend/session metadata, resume IDs, child session IDs, and terminal-status recovery after daemon restarts. Late completions no longer overwrite cancelled jobs.
+
+### New Primitive Plugins
+
+- **Mailbox / Inbox Automation**: The built-in `mailbox` plugin adds IMAP/SMTP inbox access with `status`, `list_messages`, `list_threads`, `search_messages`, `read_message`, `download_attachment`, `reply`, and `wait_for_email`. It supports durable inbound-email waits and reuses plugin settings / connector config where possible. Configure it in **Settings → Plugins** with `imapHost`, `smtpHost`, `user`, `password`, and optional reply defaults.
+- **Human-in-the-Loop Requests**: The built-in `ask_human` plugin provides `request_input`, `request_approval`, `wait_for_reply`, `wait_for_approval`, `list_mailbox`, `ack_mailbox`, and `status`. It is backed by session mailbox envelopes plus approval records so agents can pause and resume on real human responses instead of polling ad hoc state.
+- **Document Parsing / OCR**: The built-in `document` plugin adds `read`, `metadata`, `ocr`, `extract_tables`, `store`, `list`, `search`, `get`, and `delete`. It uses the shared document extraction helpers for PDFs, Office docs, OCR-able images, HTML, CSV/TSV/XLSX, ZIP inspection, and plain text files.
+- **Schema-Driven Extraction**: The built-in `extract` plugin adds `extract_structured` and `summarize`, using the current session model/provider to turn raw text or local files into validated JSON objects. This is the primitive to combine with browser / document / crawl output when an agent needs structured records instead of prose.
+- **Tabular Data Operations**: The built-in `table` plugin adds `read`, `load_csv`, `load_xlsx`, `summarize`, `filter`, `sort`, `group`, `pivot`, `dedupe`, `join`, and `write`. It operates on CSV, TSV, JSON array-of-objects, or XLSX inputs without forcing agents to drop into shell or Python for basic spreadsheet work, and transformed tables can be persisted with `outputPath` / `saveTo`.
+- **Multi-Page Crawling**: The built-in `crawl` plugin adds `crawl_site`, `follow_pagination`, `extract_sitemap`, `dedupe_pages`, and `batch_extract`. It handles BFS-style same-origin site traversal, accepts either a fresh start URL or an explicit page list, and can hand the aggregate page set directly into structured extraction for research-heavy autonomous tasks.
 
 ## Deploy to a VPS
 
@@ -612,8 +657,8 @@ npm run update:easy     # safe update helper for local installs
 SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
 
 ```bash
-# example minor release (v0.7.0 style)
-npm version minor
+# example patch release (v0.7.3 style)
+npm version patch
 git push origin main --follow-tags
 ```
 
@@ -622,19 +667,22 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.7.0 Release Readiness Notes
+#### v0.7.3 Release Readiness Notes
 
-Before shipping `v0.7.0`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.7.3`, confirm the following user-facing changes are reflected in docs:
 
-1. Plugins UI now shows richer installed plugin details (description fallback, source/status, capability badges, and clearer detail sheet metadata).
-2. Marketplace plugin installs normalize legacy URLs from `swarmclawai/plugins` to `swarmclawai/swarmforge` to avoid 404 installs.
-3. Hydration fixes removed nested `<button>` structures in list-card UIs (Plugins, Providers, Secrets, MCP Servers).
-4. Clipboard actions now use a browser-safe fallback when `navigator.clipboard` is unavailable.
-5. Site docs/release notes are updated in `swarmclaw-site` (especially `content/docs/plugins.md`, `content/docs/release-notes.md`, and `public/registry/plugins.json`).
+1. New primitive plugins are documented in README and site docs: `mailbox`, `ask_human`, `document`, `extract`, `table`, and `crawl`.
+2. Browser persistence, higher-level browser actions, durable watch jobs, and delegation handles are covered in docs.
+3. Plugin docs mention canonical built-in IDs, source-backed installs/updates, hot reload, and encrypted `secret` settings.
+4. Plugin docs cover per-plugin workspaces and dependency installs for plugins that ship with a `package.json` manifest.
+5. Connector docs and CLI docs cover the connector doctor diagnostics endpoints/commands.
+6. The plugin tutorial reflects the current hook behavior, including `beforeToolExec` input rewriting and `settingsFields`.
+7. Site install/version strings are updated to `v0.7.3`, including the release notes index, install snippets, and sidebar footer.
+8. Provider docs mention that configured OpenAI models can populate the model dropdown while still allowing custom/manual entries.
 
 ## CLI
 
-SwarmClaw ships a built-in CLI for core operational workflows:
+SwarmClaw ships a built-in CLI for setup and day-to-day operations.
 
 ```bash
 # show command help
@@ -644,80 +692,37 @@ npm run cli -- --help
 node ./bin/swarmclaw.js --help
 ```
 
-### Usage
+Primary groups:
+- `chats` (canonical)
+- `tasks`
+- `schedules`
+- `chatrooms`
+- `connectors`
+- `memory`
+- `setup`
 
-```bash
-swarmclaw [global-options] <group> <command> [command-options]
-```
-
-### Global Options
+Legacy note: some compatibility paths still accept `sessions`, but `chats` is the canonical command group.
 
-| Flag | Description |
-|-|-|
-| `--base-url <url>` | API base URL (default: `http://localhost:3456`) |
-| `--access-key <key>` | Access key override (else `SWARMCLAW_API_KEY` or `platform-api-key.txt`) |
-| `--data <json\|@file\|->` | Request JSON body |
-| `--query key=value` | Query parameter (repeatable) |
-| `--header key=value` | Extra HTTP header (repeatable) |
-| `--json` | Compact JSON output |
-| `--wait` | Wait for run/task completion when IDs are returned |
-| `--timeout-ms <ms>` | Request/wait timeout (default `300000`) |
-| `--interval-ms <ms>` | Poll interval for `--wait` (default `2000`) |
-| `--out <file>` | Write binary response to file |
-
-Routing note: `swarmclaw` uses a hybrid router. Some legacy rich commands still support `-u/--url`, `-k/--key`, and `--raw`; mapped API commands use the options above.
-
-### Command Groups
-
-Run `swarmclaw --help` to list all groups and commands (the list evolves as APIs are added).
-Notable setup/operations groups include:
-
-| Group | Purpose |
-|-|-|
-| `setup` | Setup helpers like provider checks and `doctor` diagnostics |
-| `version` | Version status and update helpers |
-| `sessions` | Session lifecycle, chat, browser/devserver controls, mailbox |
-| `chatrooms` | Multi-agent chatrooms (members, reactions, streamed room chat) |
-| `memory` | Memory CRUD and maintenance utilities |
-| `notifications` | In-app notification listing and read-state controls |
-
-### Examples
+Quick examples:
 
 ```bash
 # list agents
 swarmclaw agents list
 
-# get agent details
-swarmclaw agents get <agentId>
+# create and inspect a chat
+swarmclaw chats create --name "Main Ops" --agent-id <agentId>
+swarmclaw chats list
 
-# create a task
-swarmclaw tasks create --title "Fix flaky CI test" --description "Stabilize retry logic" --agent-id <agentId>
+# run a main loop action
+swarmclaw chats main-loop-action <chatId> --data '{"action":"nudge"}'
 
 # run setup diagnostics
 swarmclaw setup doctor
-
-# interactive setup (walks through provider selection, supports multiple providers)
-swarmclaw setup init
-
-# or non-interactive setup with flags
-swarmclaw setup init --provider openai --api-key "$OPENAI_API_KEY"
-
-# run memory maintenance analysis
-swarmclaw memory maintenance
-
-# list chatrooms
-swarmclaw chatrooms list
-
-# send a room message and stream agent replies
-swarmclaw chatrooms chat <chatroomId> --data '{"text":"@all status update?"}'
-
-# react to a room message
-swarmclaw chatrooms react <chatroomId> --data '{"messageId":"<messageId>","emoji":"👍"}'
-
-# pin/unpin a room message
-swarmclaw chatrooms pin <chatroomId> --data '{"messageId":"<messageId>"}'
 ```
 
+Full reference (groups, commands, and options):
+- https://swarmclaw.ai/docs/cli
+
 ## Credits
 
 - Inspired by [OpenClaw](https://github.com/openclaw)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "repository": {

package/src/app/api/agents/[id]/route.ts

@@ -11,17 +11,43 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   const body = await req.json()
   const result = mutateItem(ops, id, (agent) => {
     Object.assign(agent, body, { updatedAt: Date.now() })
+    if (body.platformAssignScope === 'all' || body.platformAssignScope === 'self') {
+      agent.platformAssignScope = body.platformAssignScope
+      agent.isOrchestrator = body.platformAssignScope === 'all'
+    } else if (agent.platformAssignScope === 'all' || agent.platformAssignScope === 'self') {
+      agent.isOrchestrator = agent.platformAssignScope === 'all'
+    }
     if (body.apiEndpoint !== undefined) {
       agent.apiEndpoint = normalizeProviderEndpoint(
         body.provider || agent.provider,
         body.apiEndpoint,
       )
     }
+    delete (agent as Record<string, unknown>).isOrchestrator
+    agent.isOrchestrator = agent.platformAssignScope === 'all'
     delete (agent as Record<string, unknown>).id
     agent.id = id
     return agent
   })
   if (!result) return notFound()
+
+  if (result.threadSessionId) {
+    const sessions = loadSessions()
+    const shortcut = sessions[result.threadSessionId]
+    if (shortcut) {
+      let changed = false
+      if (shortcut.name !== result.name) {
+        shortcut.name = result.name
+        changed = true
+      }
+      if (shortcut.shortcutForAgentId !== id) {
+        shortcut.shortcutForAgentId = id
+        changed = true
+      }
+      if (changed) saveSessions(sessions)
+    }
+  }
+
   logActivity({ entityType: 'agent', entityId: id, action: 'updated', actor: 'user', summary: `Agent updated: "${result.name}"` })
   return NextResponse.json(result)
 }