hyperclaw 5.0.1 → 5.0.3

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2024 HyperClaw Team
+Copyright (c) 2025 Peter Steinberger
+Copyright (c) 2026 HyperClaw Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,4 +1,4 @@
-<div align="center">
+<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>
@@ -88,7 +88,10 @@ The wizard walks you through: AI provider → model → channels → skills. Don
 # After setup, start your assistant
 hyperclaw daemon start
 
-# Send a test message
+# Interactive terminal chat (multi-turn, streams responses)
+hyperclaw chat
+
+# Send a single message (non-interactive)
 hyperclaw agent --message "What can you do?"
 
 # Health check
@@ -97,6 +100,8 @@ hyperclaw doctor
 
 > **Windows**: No WSL2, no admin rights needed. The daemon uses Task Scheduler and runs as your account.
 
+> **Linux**: If you get an `EACCES: permission denied` error during `npm install -g`, see the [Linux install fix](#-linux-permission-fix) below.
+
 <details>
 <summary>More install options</summary>
 
@@ -115,6 +120,84 @@ rm -rf ~/.hyperclaw   # optional — removes config and data
 
 </details>
 
+<details>
+<summary id="-linux-permission-fix">🐧 Linux / macOS permission fix (EACCES error)</summary>
+
+If `npm install -g hyperclaw@latest` fails with `EACCES: permission denied`, it means npm is trying to write to a system directory it doesn't own. This can happen on **any Linux distro or macOS** depending on how Node.js was installed.
+
+---
+
+### ✅ Universal fix — user-local npm prefix (works on ALL distros + macOS)
+
+This is the **recommended permanent solution** — works on Ubuntu, Debian, Arch, Fedora, Kali, openSUSE, macOS, and any other Unix system:
+
+```bash
+# 1. Create a user-owned npm directory
+mkdir -p ~/.npm-global
+
+# 2. Tell npm to use it
+npm config set prefix '~/.npm-global'
+
+# 3. Add it to your PATH
+#    bash users:
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
+#    zsh users (macOS default, Kali zsh, etc.):
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc
+#    fish users:
+echo 'set -x PATH ~/.npm-global/bin $PATH' >> ~/.config/fish/config.fish
+
+# 4. Install (no sudo needed)
+npm install -g hyperclaw@latest
+```
+
+---
+
+### Distro-specific notes
+
+| Distro | Node install method | Typical fix |
+|--------|-------------------|-------------|
+| Ubuntu / Debian | `apt install nodejs` | User-local prefix (above) |
+| **Arch / Manjaro** | `pacman -S nodejs npm` | User-local prefix — **do NOT use sudo** with pacman-installed npm |
+| Fedora / RHEL | `dnf install nodejs` | User-local prefix (above) |
+| Kali Linux | `apt install nodejs` | User-local prefix (above) |
+| openSUSE | `zypper install nodejs` | User-local prefix (above) |
+| **Any distro** via `nvm` | `nvm install 22` | ✅ No fix needed — nvm installs to `~/.nvm`, no permissions issue |
+| macOS via Homebrew | `brew install node` | ✅ Usually works out of the box |
+| macOS via system Node | (not recommended) | User-local prefix (above) |
+
+> **Arch Linux note**: `sudo npm install -g` can break your system's npm installation because pacman manages `/usr/lib/node_modules`. Always use the user-local prefix on Arch.
+
+---
+
+### Alternative: Use nvm (Node Version Manager)
+
+[nvm](https://github.com/nvm-sh/nvm) manages Node per-user with no root access needed — the cleanest long-term solution:
+
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+source ~/.bashrc   # or ~/.zshrc
+
+# Install Node 22
+nvm install 22
+nvm use 22
+
+# Install HyperClaw (no sudo, no prefix config needed)
+npm install -g hyperclaw@latest
+```
+
+---
+
+### macOS: Quick fix with sudo (if all else fails)
+
+```bash
+sudo npm install -g hyperclaw@latest
+```
+
+> On macOS with **Homebrew Node**, `sudo` is usually not needed. If it is, prefer the user-local prefix or nvm approach above.
+
+</details>
+
 ---
 
 ## Channels
@@ -126,7 +209,7 @@ HyperClaw connects to the channels you already use (28+ channels):
 | ✈️ Telegram | ✅ Recommended | Bot API via @BotFather |
 | 🎮 Discord | ✅ Recommended | discord.js — full bot |
 | 🌐 WebChat | ✅ Built-in | Gateway WebSocket, no setup |
-| 🖥️ CLI / Terminal | ✅ Built-in | `hyperclaw agent` |
+| 🖥️ CLI / Terminal | ✅ Built-in | `hyperclaw chat` (interactive) · `hyperclaw agent -m "..."` (single) |
 | 📲 WhatsApp (Baileys) | ✅ Available | No Meta API — scan QR |
 | 📱 WhatsApp (Cloud API) | ✅ Available | Meta Business API |
 | 💼 Slack | ✅ Available | Bolt — Events API |
@@ -186,18 +269,30 @@ Google Chat / Matrix / IRC / Mattermost / Teams / Nostr / WebChat
 
 ---
 
-## Providers
-
-HyperClaw supports any OpenAI-compatible API and Anthropic natively:
-
-| Provider | IDs |
-|----------|-----|
-| **Anthropic** | `anthropic` — Claude 4 Opus/Sonnet/Haiku |
-| **OpenRouter** | `openrouter` — 200+ models |
-| **OpenAI** | `openai` — GPT-4o, GPT-4.1 |
-| **xAI** | `xai` — Grok |
-| **Groq** | `groq` — Llama, Mixtral (fast) |
-| **Custom** | `custom` — any OpenAI-compatible endpoint |
+## AI Models
+
+HyperClaw supports 20+ providers. Pick one in the wizard or set `provider.providerId` in config:
+
+| Provider | ID | Notes |
+|----------|-----|-------|
+| **Anthropic** | `anthropic` | Claude Opus/Sonnet/Haiku — native streaming |
+| **Anthropic OAuth** | `anthropic-oauth` | Claude Code / Max subscription |
+| **OpenRouter** | `openrouter` | 200+ models — one key |
+| **OpenAI** | `openai` | GPT-4o, o3, o4-mini |
+| **Google** | `google` | Gemini 2.5 Pro, 2.0 Flash |
+| **xAI** | `xai` | Grok 3, Grok 3 Mini |
+| **Groq** | `groq` | Llama 3.3, Mixtral — fast inference |
+| **Mistral** | `mistral` | Mistral Large, Codestral |
+| **DeepSeek** | `deepseek` | DeepSeek V3, R1 reasoning |
+| **Perplexity** | `perplexity` | Sonar — search-augmented AI |
+| **Hugging Face** | `huggingface` | Open-source models |
+| **MiniMax** | `minimax` | MiniMax Text-01 |
+| **Qwen** | `qwen` | Alibaba Qwen 3, Qwen Max |
+| **Z.AI** | `zai` | GLM-4 models |
+| **Vercel AI Gateway** | `vercel-ai` | Multi-model proxy |
+| **Ollama** | `ollama` | Local models — `ollama serve` |
+| **LM Studio** | `lmstudio` | Local models — enable local server |
+| **Custom** | `custom` | Any OpenAI-compatible `/chat/completions` |
 
 ---
 
@@ -313,6 +408,7 @@ Full guide: [docs/security.md](docs/security.md)
 - **Auto-memory** — extracts facts from conversations automatically
 - **Skills** — bundled and workspace skills (reminders, translator, web search, etc.)
 - **Daemon mode** — launchd/systemd user service, auto-restart, `🩸` icon
+- **Update notifications** — notifies when a newer version is available on npm (non-blocking check at startup)
 - **MCP support** — Model Context Protocol server and client
 - **Docker** — sandboxed agent execution, browser tools with Puppeteer
 - **Tailscale** — Serve/Funnel for remote access without port forwarding
@@ -344,6 +440,180 @@ The Gateway alone delivers a great experience. Apps add extra features:
 
 ---
 
+## Development channels
+
+Three release channels, switch any time:
+
+```bash
+hyperclaw update --channel stable   # tagged releases (default)
+hyperclaw update --channel beta     # prereleases
+hyperclaw update --channel dev      # moving head of main
+```
+
+| Channel | npm dist-tag | Notes |
+|---------|-------------|-------|
+| `stable` | `latest` | Tagged releases — recommended |
+| `beta` | `beta` | Prerelease — new features, may have rough edges |
+| `dev` | `dev` | Latest main branch (when published) |
+
+---
+
+## Integrations (Skills & Tools)
+
+The agent has built-in tools for common integrations — no extra packages needed. Full reference: [docs/integrations.md](docs/integrations.md)
+
+### Core Tools
+
+| Tool | How to enable |
+|------|---------------|
+| **Weather** | Free — no key needed (Open-Meteo) |
+| **Image generation** | Set `OPENAI_API_KEY` (DALL-E 3) or `STABILITY_API_KEY` |
+| **GIF search** | Set `GIPHY_API_KEY` or `TENOR_API_KEY` |
+| **Spotify** | Set `SPOTIFY_CLIENT_ID` + `SPOTIFY_CLIENT_SECRET` + `SPOTIFY_REFRESH_TOKEN` |
+| **Home Assistant** | Set `HA_URL` + `HA_TOKEN` (long-lived access token) |
+| **GitHub** | Set `GITHUB_TOKEN` |
+| **Canvas** | Built-in — view at `http://localhost:18789/canvas` |
+| **Browser** | Built-in — enable `browser.enabled: true` |
+| **Gmail** | Set `GOOGLE_CREDENTIALS_PATH` + configure Pub/Sub |
+
+### Productivity
+
+| Tool | How to enable |
+|------|---------------|
+| **Apple Notes** | macOS only — built-in (requires Accessibility permissions) |
+| **Apple Reminders** | macOS only — built-in (requires Accessibility permissions) |
+| **Things 3** | macOS only — install Things 3, no extra config |
+| **Obsidian** | Install Local REST API plugin, set `OBSIDIAN_API_KEY` (and optionally `OBSIDIAN_PORT`, default 27123) |
+| **Bear Notes** | macOS only — install Bear, no extra config |
+| **Trello** | Set `TRELLO_API_KEY` + `TRELLO_TOKEN` (from trello.com/app-key) |
+
+### Music
+
+| Tool | How to enable |
+|------|---------------|
+| **Sonos** | Set `SONOS_IP` to your speaker's local IP address |
+| **Music search** | Free — no key needed (iTunes Search API) |
+
+### Smart Home
+
+| Tool | How to enable |
+|------|---------------|
+| **Philips Hue** | Set `HUE_BRIDGE_IP` + `HUE_USERNAME` (from bridge discovery) |
+| **8Sleep** | Set `EIGHTSLEEP_EMAIL` + `EIGHTSLEEP_PASSWORD` |
+
+### Security & Messaging
+
+| Tool | How to enable |
+|------|---------------|
+| **1Password** | Install `op` CLI, set `OP_SERVICE_ACCOUNT_TOKEN` |
+| **iMessage** | macOS only — built-in (requires Full Disk Access + Accessibility) |
+
+Example — ask the agent:
+```
+"What's the weather in Athens for the next 3 days?"
+"Generate an image of a space lobster"
+"Play some Daft Punk on Spotify"
+"Turn on the living room lights"      # Home Assistant or Philips Hue
+"List my open GitHub issues"
+"Add 'Buy milk' to my Reminders"
+"Create a note in Obsidian: Meeting notes..."
+"Add a card to my Trello board"
+"Set my 8Sleep to temperature 20 on the left side"
+"Get my GitHub password from 1Password"
+"Send an iMessage to +1234567890: I'll be late"
+"What's playing on my Sonos?"
+```
+
+### How to add integration API keys
+
+**Option 1 — During onboarding wizard** (recommended for first setup):
+```bash
+hyperclaw onboard
+# At the end of the wizard, you'll be asked:
+# "Configure integrations now? (Spotify, Home Assistant, GitHub, Trello, etc.)"
+# Select the ones you want and enter your keys interactively.
+```
+
+**Option 2 — Tell the agent** (easiest after setup):
+```
+You › Save my Spotify keys:
+      CLIENT_ID: abc123
+      CLIENT_SECRET: xyz456
+      REFRESH_TOKEN: def789
+```
+
+**Option 3 — CLI command**:
+```bash
+hyperclaw config set-key SPOTIFY_CLIENT_ID abc123
+hyperclaw config set-key SPOTIFY_CLIENT_SECRET xyz456
+hyperclaw config set-key GITHUB_TOKEN ghp_xxxx
+hyperclaw config set-key HA_URL http://homeassistant.local:8123
+hyperclaw config set-key HA_TOKEN your-long-lived-token
+```
+
+**Option 4 — Edit directly** `~/.hyperclaw/.env`:
+```bash
+SPOTIFY_CLIENT_ID=abc123
+SPOTIFY_CLIENT_SECRET=xyz456
+GITHUB_TOKEN=ghp_xxxx
+HA_URL=http://homeassistant.local:8123
+HA_TOKEN=your-token
+TRELLO_API_KEY=abc
+TRELLO_TOKEN=xyz
+OBSIDIAN_API_KEY=abc
+HUE_BRIDGE_IP=192.168.1.100
+HUE_USERNAME=your-username
+SONOS_IP=192.168.1.50
+GIPHY_API_KEY=abc
+OP_SERVICE_ACCOUNT_TOKEN=ops_xxxx
+```
+
+All keys are stored locally in `~/.hyperclaw/.env` — never sent anywhere except the respective service.
+
+---
+
+## Agent-to-Agent (sessions tools)
+
+When the gateway is running, the agent can communicate with other connected sessions:
+
+| Tool | Description |
+|------|-------------|
+| `sessions_list` | List all active 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:
+```
+"List all connected sessions and send a briefing to the first one"
+```
+
+---
+
+## Terminal chat (`hyperclaw chat`)
+
+Interactive multi-turn chat with the agent directly from your terminal:
+
+```bash
+hyperclaw chat                          # start a session
+hyperclaw chat --thinking high          # enable extended thinking
+hyperclaw chat --session my-session     # named session
+hyperclaw chat --model claude-opus-4-6  # override model
+```
+
+| Input | Action |
+|-------|--------|
+| Any text + Enter | Send message to agent |
+| `exit` / `quit` / `bye` | Quit the chat |
+| `/exit` / `/quit` / `/bye` | Quit the chat |
+| `Ctrl+C` | Quit the chat |
+| `/clear` | Clear conversation history |
+| `/model` | Show current model |
+| `/help` | Show available commands |
+
+Responses stream token-by-token as they are generated. The full conversation history is kept for the entire session (true multi-turn context).
+
+---
+
 ## Chat commands
 
 Send these in any connected channel (Telegram, Discord, Slack, etc.):
@@ -356,6 +626,91 @@ Send these in any connected channel (Telegram, Discord, Slack, etc.):
 | `/think <level>` | `off` · `low` · `medium` · `high` · `xhigh` |
 | `/verbose on\|off` | Verbose mode |
 | `/usage off\|tokens\|full` | Per-response usage footer |
+| `/restart` | Restart the gateway (owner-only in groups) |
+| `/activation mention\|always` | Group activation toggle |
+
+## SkillHub
+
+SkillHub is HyperClaw's skill registry. Full guide: [docs/skillhub.md](docs/skillhub.md)
+
+The agent can install skills on demand or you can install them via the wizard:
+
+```bash
+# Install a skill
+hyperclaw skills install web-search
+
+# List installed skills
+hyperclaw skills list
+```
+
+Featured skills: `web-search` · `file-manager` · `code-runner` · `github-tools` · `calendar-tools` · `summarizer`
+
+### Installing skills — 3 ways
+
+**Option 1 — tell the agent (easiest):**
+
+```
+You › Install the web-search skill
+You › Install this: https://clawhub.ai/user/skill-name
+```
+
+The agent automatically calls `install_skill_from_hub` — no commands needed.
+
+**Option 2 — `/skills` inside `hyperclaw chat`:**
+
+```
+You › /skills
+```
+
+Shows installed skills and how to add more:
+
+```
+  Installed skills:
+  • Web Search      (web-search)
+  • File Manager    (file-manager)
+
+  How to add a skill:
+  1. Tell the agent:  "Install the web-search skill"
+  2. Paste a link:    "Install this: https://clawhub.ai/user/skill-name"
+  3. CLI:             hyperclaw skill install <name>
+  4. Re-run wizard:   hyperclaw onboard
+```
+
+`/skills` also appears in `/help` and in the chat header when you open `hyperclaw chat`.
+
+**Option 3 — CLI:**
+
+```bash
+hyperclaw skill install web-search
+hyperclaw skills list
+```
+
+### Install from URL
+
+Give the agent a clawhub.ai link and it installs automatically:
+
+```
+"Install this skill: https://clawhub.ai/b0tresch/stealth-browser"
+```
+
+The agent calls `install_skill_from_hub` — fetches SKILL.md + extra files, writes them to `~/.hyperclaw/workspace/skills/`, and runs `npm install` if needed.
+
+### Self-writing skills
+
+The agent can create fully custom skills on demand:
+
+```
+"Create a skill that summarizes my daily Telegram messages"
+```
+
+`create_skill` supports:
+- **`content`** — SKILL.md instructions
+- **`files`** — JSON map of extra files (e.g. `{"scripts/run.js": "..."}`)
+- **`npmInstall: "true"`** — auto-runs `npm install` after writing files
+
+Skills are saved to `~/.hyperclaw/workspace/skills/{id}/` and loaded on the next message.
+
+---
 
 ## HyperClaw Bot commands
 
@@ -378,23 +733,6 @@ Control the gateway remotely via your Telegram or Discord bot (`hyperclaw bot st
 | `/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
 
 ```bash
@@ -493,6 +831,9 @@ hyperclaw/
 | 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) |
+| **Integrations (all tools)** | [docs/integrations.md](docs/integrations.md) |
+| **SkillHub & custom skills** | [docs/skillhub.md](docs/skillhub.md) |
+| **Update notifications** | [docs/update-notifications.md](docs/update-notifications.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) |

package/bin/hyperclaw.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('../dist/run-main.js');

package/dist/a2ui-protocol-Gzm29Gaw.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;

package/dist/agents-routing-Biy5ew4a.js

@@ -0,0 +1,4 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const require_agents_routing = require('./agents-routing-CL3HQNoM.js');
+
+exports.AgentRouter = require_agents_routing.AgentRouter;