hyperclaw 5.0.1 → 5.0.2

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
@@ -126,7 +129,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 +189,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 +328,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 +360,134 @@ 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?"
+```
+
+---
+
+## 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 +500,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 +607,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 +705,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/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;