hyperclaw 4.0.2 → 5.0.1

package/README.md

@@ -1,40 +1,55 @@
-<p align="center">
-  <img src="assets/icon.png" width="120" alt="HyperClaw">
-  <br>
-  <h1 align="center">🦅 HyperClaw — Personal AI Assistant</h1>
-</p>
+<div align="center">
+  <img src="assets/icon.png" width="140" alt="HyperClaw">
+  <h1>🦅 HyperClaw</h1>
+  <p><strong>Your personal AI assistant — running on your hardware, talking on your channels.</strong></p>
+  <p><em>One command to install. Works on Telegram, Discord, WhatsApp, Signal, iMessage and 25+ more.</em></p>
+</div>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/build-passing-brightgreen?style=flat-square" alt="build">
-  <img src="https://img.shields.io/badge/release-v4.0.2-blue?style=flat-square" alt="release">
-  <img src="https://img.shields.io/badge/node-%E2%89%A522-green?style=flat-square" alt="node">
-  <img src="https://img.shields.io/badge/license-MIT-gray?style=flat-square" alt="license">
+  <a href="https://github.com/mylo-2001/hyperclaw/stargazers"><img src="https://img.shields.io/github/stars/mylo-2001/hyperclaw?style=flat-square&logo=github&color=yellow" alt="GitHub Stars"></a>
+  <a href="https://github.com/mylo-2001/hyperclaw/network/members"><img src="https://img.shields.io/github/forks/mylo-2001/hyperclaw?style=flat-square&logo=github" alt="GitHub Forks"></a>
+  <a href="https://www.npmjs.com/package/hyperclaw"><img src="https://img.shields.io/npm/dw/hyperclaw?style=flat-square&logo=npm&color=red" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/hyperclaw"><img src="https://img.shields.io/npm/v/hyperclaw?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
+  <a href="https://github.com/mylo-2001/hyperclaw/actions"><img src="https://img.shields.io/github/actions/workflow/status/mylo-2001/hyperclaw/secrets-scan.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A522-green?style=flat-square&logo=node.js" alt="node">
   <img src="https://img.shields.io/badge/typescript-5.4-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="typescript">
-  <img src="https://img.shields.io/badge/security-ethical%20hacking-red?style=flat-square&logo=hackthebox&logoColor=white" alt="security">
+  <img src="https://img.shields.io/badge/license-MIT-gray?style=flat-square" alt="license">
+  <img src="https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue?style=flat-square" alt="platforms">
 </p>
 
 <p align="center">
-  <strong>HyperClaw</strong> is a personal AI assistant you run on your own devices.<br>
-  It answers you on the channels you already use — Telegram, Discord, WhatsApp, Slack, Signal, iMessage,<br>
-  Matrix, IRC, Mattermost, Google Chat, Microsoft Teams, Nostr, and more.<br>
-  It can speak and listen on macOS/iOS/Android, and render a live Canvas you control.<br>
-  The Gateway is just the control plane — the product is the assistant.
+  <a href="docs/README.md">📚 Docs</a> ·
+  <a href="docs/architecture.md">🏗 Architecture</a> ·
+  <a href="docs/configuration.md">⚙️ Config</a> ·
+  <a href="docs/security.md">🔒 Security</a> ·
+  <a href="docs/sandboxing.md">🐳 Sandboxing</a> ·
+  <a href="docs/tlon.md">🌊 Tlon</a> ·
+  <a href="docs/google-chat.md">💬 Google Chat</a> ·
+  <a href="CONTRIBUTING.md">🤝 Contributing</a>
 </p>
 
-<p align="center">
-  <em>If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.</em><br>
-  <em>Built for developers, security researchers, and power users who want full control.</em>
-</p>
+---
 
-<p align="center">
-  <a href="docs/README.md">Docs</a> ·
-  <a href="docs/architecture.md">Architecture</a> ·
-  <a href="docs/configuration.md">Configuration</a> ·
-  <a href="docs/security.md">Security</a> ·
-  <a href="docs/deployment.md">Docker</a> ·
-  <a href="docs/tailscale.md">Tailscale</a> ·
-  <a href="CONTRIBUTING.md">Contributing</a>
-</p>
+> **"One `npm install -g hyperclaw` and your AI is live on Telegram."**
+
+---
+
+## Why HyperClaw?
+
+| Feature | HyperClaw | Cloud assistants | Self-hosted alternatives |
+|---------|:---------:|:----------------:|:------------------------:|
+| Runs on your own hardware | ✅ | ❌ | ✅ |
+| No subscription / pay-per-token only | ✅ | ❌ | ✅ |
+| 28+ messaging channels built-in | ✅ | ❌ | ⚠️ few |
+| Windows native (no WSL) | ✅ | — | ❌ |
+| Config hot-reload (no restart) | ✅ | — | ❌ |
+| Built-in security audit (`--fix`) | ✅ | — | ❌ |
+| DM pairing / allowlist by default | ✅ | — | ⚠️ manual |
+| Voice (TTS + STT) | ✅ | ✅ | ⚠️ |
+| Docker sandbox for agent tools | ✅ | — | ⚠️ |
+| MCP (Model Context Protocol) | ✅ | ⚠️ | ⚠️ |
+| One-command wizard (`hyperclaw onboard`) | ✅ | — | ❌ |
+| OSINT / Ethical hacking mode (`hyperclaw osint`) | ✅ | ❌ | ❌ |
 
 ---
 
@@ -53,58 +68,58 @@
 
 ---
 
-## Install
+## 🚀 Get started in 60 seconds
 
-Runtime: Node ≥ 22. Runs **natively on Windows, macOS, and Linux** — no WSL2 required.
+**Requires Node ≥ 22.** Runs natively on Windows, macOS, and Linux — no WSL2 required.
 
 ```bash
+# Install
 npm install -g hyperclaw@latest
-# or: pnpm add -g hyperclaw@latest
 
-# First-time setup wizard
+# Run the interactive setup wizard
 hyperclaw onboard
-
-# Or install with daemon (auto-start on boot, full PC access)
+# Run the interactive setup wizard with deamon
 hyperclaw onboard --install-daemon
 ```
 
-> **Windows users**: HyperClaw runs natively via Node.js. No WSL2, no admin rights needed.
-> The daemon uses **Task Scheduler** and runs as your user account with full desktop access.
-
-The wizard guides you step by step — provider, model, gateway, channels, and skills.
-Works on **macOS, Linux, and Windows** (native — no WSL2 required). Compatible with npm, pnpm, and bun.
+The wizard walks you through: AI provider → model → channels → skills. Done.
 
----
+```bash
+# After setup, start your assistant
+hyperclaw daemon start
 
-## Quick start
+# Send a test message
+hyperclaw agent --message "What can you do?"
 
-```bash
-# 1. Run the onboarding wizard (first time)
-hyperclaw onboard
+# Health check
+hyperclaw doctor
+```
 
-# 2a. Start the gateway in foreground
-hyperclaw gateway --port 18789 --verbose
+> **Windows**: No WSL2, no admin rights needed. The daemon uses Task Scheduler and runs as your account.
 
-# 2b. Or run as a background daemon (auto-start on boot)
-hyperclaw daemon start
+<details>
+<summary>More install options</summary>
 
-# 3. Talk to your assistant
-hyperclaw agent --message "What can you do?"
+```bash
+# pnpm
+pnpm add -g hyperclaw@latest
 
-# 4. Security / bug bounty — run recon from your phone
-# Just message your Telegram bot: "search HackerOne for targets on acme.com"
+# Install with daemon (auto-start on boot + full PC access)
+hyperclaw onboard --install-daemon
 
-# 5. Check status
-hyperclaw doctor
+# Uninstall
+hyperclaw daemon uninstall
+npm uninstall -g hyperclaw
+rm -rf ~/.hyperclaw   # optional — removes config and data
 ```
 
-Upgrading? Run `hyperclaw doctor` to check and migrate.
+</details>
 
 ---
 
 ## Channels
 
-HyperClaw connects to the channels you already use (27 channels):
+HyperClaw connects to the channels you already use (28+ channels):
 
 | Channel | Status | Notes |
 |---------|--------|-------|
@@ -135,6 +150,9 @@ HyperClaw connects to the channels you already use (27 channels):
 | 📧 Email | ✅ Available | SMTP + IMAP |
 | 🎙️ Voice Call | ✅ Available | Terminal voice session |
 | 🌐 Chrome Extension | ✅ Available | Browser sidebar |
+| 🌊 Tlon (Urbit Groups) | ✅ Available | Decentralized — see [docs/tlon.md](docs/tlon.md) |
+
+Twitch is also available via IRC over WebSocket.
 
 Add a channel:
 
@@ -214,6 +232,47 @@ Or use OpenRouter (access to all models with one key):
 
 Full reference: [docs/configuration.md](docs/configuration.md)
 
+### Config hot reload
+
+The gateway watches `~/.hyperclaw/hyperclaw.json` and applies changes automatically — no restart needed for most settings:
+
+```json
+{
+  "gateway": {
+    "reload": { "mode": "hybrid", "debounceMs": 300 }
+  }
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `hybrid` _(default)_ | Hot-applies safe changes, auto-restarts for critical ones |
+| `hot` | Hot-applies only — warns when a restart is needed |
+| `restart` | Restarts on any change |
+| `off` | Disables file watching |
+
+### Reverse proxy / trustedProxies
+
+If you run behind Nginx, Caddy, or Cloudflare Tunnel, set `trustedProxies` so the gateway resolves the real client IP from `X-Forwarded-For`:
+
+```json
+{
+  "gateway": {
+    "trustedProxies": ["127.0.0.1", "10.0.0.0/8"]
+  }
+}
+```
+
+### DM scope isolation
+
+Isolate DM sessions per channel/peer (useful when multiple people share one gateway):
+
+```json
+{
+  "session": { "dmScope": "per-channel-peer" }
+}
+```
+
 ---
 
 ## Security defaults
@@ -227,7 +286,14 @@ HyperClaw connects to real messaging surfaces. Inbound DMs are treated as untrus
 - Set `dmPolicy: "open"` only if you want anyone to reach your assistant.
 - Non-main sessions (groups/channels) can run in Docker sandboxes: `agents.defaults.sandbox.mode: "non-main"`
 
-Run `hyperclaw doctor` to surface risky/misconfigured policies.
+Run the security audit regularly:
+
+```bash
+hyperclaw security audit           # standard scan
+hyperclaw security audit --deep    # live gateway probe
+hyperclaw security audit --fix     # auto-fix safe issues
+hyperclaw security audit --json    # machine-readable output
+```
 
 Full guide: [docs/security.md](docs/security.md)
 
@@ -236,7 +302,8 @@ Full guide: [docs/security.md](docs/security.md)
 ## Features
 
 - **Local-first Gateway** — single control plane for sessions, channels, tools, and events
-- **Multi-channel inbox** — 27+ channels, unified session model
+- **Config hot reload** — gateway watches `~/.hyperclaw/hyperclaw.json`, hot-applies changes (hybrid/hot/restart/off)
+- **Multi-channel inbox** — 28+ channels, unified session model
 - **Multi-agent routing** — route channels/accounts to isolated agent workspaces
 - **Extended thinking** — Claude extended thinking with `/think high` in chat
 - **Voice** — Talk Mode with ElevenLabs TTS + system TTS fallback
@@ -290,6 +357,42 @@ Send these in any connected channel (Telegram, Discord, Slack, etc.):
 | `/verbose on\|off` | Verbose mode |
 | `/usage off\|tokens\|full` | Per-response usage footer |
 
+## HyperClaw Bot commands
+
+Control the gateway remotely via your Telegram or Discord bot (`hyperclaw bot start`):
+
+| Command | Description |
+|---------|-------------|
+| `/status` | Gateway + daemon status |
+| `/restart` | Restart the gateway |
+| `/logs [n]` | Last N log lines (default 20) |
+| `/channels` | List configured channels |
+| `/approve <ch> <code>` | Approve a DM pairing code |
+| `/hook list` | List all hooks |
+| `/hook on <id>` | Enable a hook |
+| `/hook off <id>` | Disable a hook |
+| `/agent <msg>` | Send a message to the AI agent |
+| `/activation` | Show current group activation mode |
+| `/activation mention` | Bot responds only to @mentions and replies _(default)_ |
+| `/activation always` | Bot responds to all messages in a group |
+| `/security` | Security audit summary |
+| `/help` | List all commands |
+
+## Agent-to-Agent (session tools)
+
+When the gateway is running, the agent has access to session tools for agent-to-agent communication:
+
+| Tool | Description |
+|------|-------------|
+| `sessions_list` | List all active WebSocket sessions connected to the gateway |
+| `sessions_send` | Send a message to another session (by session ID) |
+| `sessions_history` | Get the chat transcript of a session (`"self"` for current) |
+
+Example — ask the agent to ping another session:
+```
+"List all connected sessions and send a hello to the first one"
+```
+
 ---
 
 ## From source
@@ -328,6 +431,18 @@ Sandbox image (no PC access, restricted tools):
 docker build -f Dockerfile.sandbox -t hyperclaw:sandbox .
 ```
 
+Or use **Docker Compose** for the full stack (gateway + browser sandbox):
+
+```bash
+# Copy and fill in your API keys
+cp env.example .env
+
+# Start gateway + sandbox
+docker compose --profile full up -d
+```
+
+See [`docker-compose.yml`](docker-compose.yml) and [`env.example`](env.example) for all options.
+
 ---
 
 ## Monorepo structure
@@ -347,7 +462,7 @@ hyperclaw/
 │   ├── media/              # Voice, TTS, STT, audio
 │   ├── routing/            # Session routing + multi-agent dispatch
 │   ├── security/           # Auth, sandboxing, DM policy
-│   └── …                  # (sdk, types, webhooks, logging, plugins…)
+│   └── …                   # (sdk, types, webhooks, logging, plugins…)
 ├── packages/
 │   ├── core/               # Inference engine, agent loop
 │   ├── gateway/            # Gateway package (standalone)
@@ -368,9 +483,80 @@ hyperclaw/
 
 ---
 
+## Documentation
+
+| Topic | File |
+|-------|------|
+| **Getting started** | [docs/README.md](docs/README.md) |
+| Architecture overview | [docs/architecture.md](docs/architecture.md) |
+| Configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Environment variables | [docs/environment.md](docs/environment.md) |
+| API keys guide | [docs/API-KEYS-README.md](docs/API-KEYS-README.md) |
+| OAuth providers | [docs/oauth-providers.md](docs/oauth-providers.md) |
+| **Security** | [docs/security.md](docs/security.md) · [SECURITY.md](SECURITY.md) |
+| Deployment / Docker | [docs/deployment.md](docs/deployment.md) |
+| Tailscale remote access | [docs/tailscale.md](docs/tailscale.md) |
+| Remote gateway setup | [docs/remote-gateway-setup.md](docs/remote-gateway-setup.md) |
+| Multi-agent routing | [docs/multi-agent.md](docs/multi-agent.md) |
+| Session management | [docs/session-management.md](docs/session-management.md) |
+| Sandboxing (Docker isolation) | [docs/sandboxing.md](docs/sandboxing.md) |
+| MCP (Model Context Protocol) | [docs/mcp.md](docs/mcp.md) |
+| OSINT / Ethical Hacking mode | [docs/osint.md](docs/osint.md) |
+| Voice / Talk Mode | [docs/voice.md](docs/voice.md) |
+| Canvas (A2UI) | [docs/canvas-a2ui.md](docs/canvas-a2ui.md) |
+| Browser control | [docs/browser.md](docs/browser.md) |
+| **Channel guides** | |
+| Telegram | [docs/telegram.md](docs/telegram.md) |
+| Discord | [docs/discord-setup.md](docs/discord-setup.md) |
+| WhatsApp | [docs/whatsapp.md](docs/whatsapp.md) |
+| Slack | [docs/slack.md](docs/slack.md) |
+| Google Chat | [docs/google-chat.md](docs/google-chat.md) |
+| Tlon (Urbit Groups) | [docs/tlon.md](docs/tlon.md) |
+| Matrix | [docs/matrix.md](docs/matrix.md) |
+| Zalo / Zalo Personal | [docs/zalo.md](docs/zalo.md) · [docs/zalo-personal.md](docs/zalo-personal.md) |
+| LINE | [docs/line.md](docs/line.md) |
+| Nostr | [docs/nostr.md](docs/nostr.md) |
+| Nextcloud Talk | [docs/nextcloud-talk.md](docs/nextcloud-talk.md) |
+| Microsoft Teams | [docs/msteams.md](docs/msteams.md) |
+| Twitch | [docs/twitch.md](docs/twitch.md) |
+| iMessage (BlueBubbles) | [docs/imessage-native.md](docs/imessage-native.md) |
+| **Apps** | |
+| Mobile & Desktop apps | [docs/mobile-desktop-apps.md](docs/mobile-desktop-apps.md) |
+| Mobile nodes (iOS/Android) | [docs/mobile-nodes.md](docs/mobile-nodes.md) |
+| macOS remote control | [docs/macos-remote-control.md](docs/macos-remote-control.md) |
+| **Help** | |
+| FAQ | [docs/faq.md](docs/faq.md) |
+| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Contributing | [docs/contributing.md](docs/contributing.md) |
+
+---
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. AI/vibe-coded PRs welcome! 🤖
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. AI/vibe-coded PRs welcome!
+
+Found a bug? [Open an issue](https://github.com/mylo-2001/hyperclaw/issues/new/choose).  
+Found a vulnerability? Email [securityhyperclaw.ai@gmail.com](mailto:securityhyperclaw.ai@gmail.com) — we respond within 48 h.
+
+---
+
+## Community
+
+| | |
+|--|--|
+| 💬 **Discussions** | [GitHub Discussions](https://github.com/mylo-2001/hyperclaw/discussions) — questions, ideas, show & tell |
+| 🐛 **Bug reports** | [GitHub Issues](https://github.com/mylo-2001/hyperclaw/issues) — templates for bugs & features |
+| 🔒 **Security** | [SECURITY.md](SECURITY.md) — responsible disclosure |
+
+---
+
+<div align="center">
+
+**If HyperClaw is useful to you, a ⭐ helps others find it.**
+
+[![Star on GitHub](https://img.shields.io/github/stars/mylo-2001/hyperclaw?style=social)](https://github.com/mylo-2001/hyperclaw)
+
+</div>
 
 ---
 

package/dist/a2ui-protocol-CfBI44-Q.js

@@ -0,0 +1,75 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/canvas/a2ui-protocol.ts
+/** Map HyperClaw component type to A2UI-compatible type. */
+function toA2UIType(t) {
+	const map = {
+		chart: "chart",
+		table: "table",
+		form: "form",
+		markdown: "markdown",
+		image: "image",
+		custom: "custom",
+		script: "script"
+	};
+	return map[t] || "custom";
+}
+/** Convert a CanvasComponent to A2UI surface. */
+function componentToSurface(c) {
+	return {
+		id: c.id,
+		type: toA2UIType(c.type),
+		props: {
+			title: c.title,
+			width: c.width || "half"
+		},
+		data: c.data
+	};
+}
+/** Generate beginRendering from canvas state (full sync). */
+function toBeginRendering(canvas) {
+	const surfaces = canvas.components.map(componentToSurface);
+	const dataModel = {};
+	for (const c of canvas.components) if (c.data != null) dataModel[c.id] = c.data;
+	return {
+		type: "beginRendering",
+		surfaceId: canvas.id,
+		surfaces,
+		dataModel: Object.keys(dataModel).length ? dataModel : void 0
+	};
+}
+/** Generate surfaceUpdate for newly added component. */
+function toSurfaceUpdate(canvasId, component) {
+	return {
+		type: "surfaceUpdate",
+		surfaceId: canvasId,
+		surfaces: [componentToSurface(component)]
+	};
+}
+/** Generate dataModelUpdate when component data changes. */
+function toDataModelUpdate(canvasId, componentId, data) {
+	return {
+		type: "dataModelUpdate",
+		surfaceId: canvasId,
+		updates: { [componentId]: data }
+	};
+}
+/** Generate deleteSurface for removed components. */
+function toDeleteSurface(canvasId, componentIds) {
+	return {
+		type: "deleteSurface",
+		surfaceId: canvasId,
+		surfaceIds: componentIds
+	};
+}
+/** Serialize A2UI messages to JSONL (one message per line). */
+function toJSONL(messages) {
+	return messages.map((m) => JSON.stringify(m)).join("\n");
+}
+
+//#endregion
+exports.toBeginRendering = toBeginRendering;
+exports.toDataModelUpdate = toDataModelUpdate;
+exports.toDeleteSurface = toDeleteSurface;
+exports.toJSONL = toJSONL;
+exports.toSurfaceUpdate = toSurfaceUpdate;