hyperclaw 4.0.2 → 5.0.0

package/README.md

@@ -1,4 +1,4 @@
-<p align="center">
+<p align="center">
   <img src="assets/icon.png" width="120" alt="HyperClaw">
   <br>
   <h1 align="center">🦅 HyperClaw — Personal AI Assistant</h1>
@@ -6,7 +6,7 @@
 
 <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/release-v5.0.0-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">
   <img src="https://img.shields.io/badge/typescript-5.4-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="typescript">
@@ -68,6 +68,19 @@ hyperclaw onboard
 hyperclaw onboard --install-daemon
 ```
 
+## Uninstall
+
+```bash
+# Stop and remove daemon (if running)
+hyperclaw daemon uninstall
+
+# Remove the package
+npm uninstall -g hyperclaw
+
+# Remove config and data (optional)
+rm -rf ~/.hyperclaw
+```
+
 > **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.
 
@@ -104,7 +117,7 @@ Upgrading? Run `hyperclaw doctor` to check and migrate.
 
 ## Channels
 
-HyperClaw connects to the channels you already use (27 channels):
+HyperClaw connects to the channels you already use (28+ channels):
 
 | Channel | Status | Notes |
 |---------|--------|-------|
@@ -136,6 +149,8 @@ HyperClaw connects to the channels you already use (27 channels):
 | 🎙️ Voice Call | ✅ Available | Terminal voice session |
 | 🌐 Chrome Extension | ✅ Available | Browser sidebar |
 
+Twitch is also available via IRC over WebSocket.
+
 Add a channel:
 
 ```bash
@@ -290,6 +305,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

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;

package/dist/agents-routing-ChHiZp36.js

@@ -0,0 +1,327 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const chalk = require_chunk.__toESM(require("chalk"));
+const inquirer = require_chunk.__toESM(require("inquirer"));
+const fs_extra = require_chunk.__toESM(require("fs-extra"));
+const path = require_chunk.__toESM(require("path"));
+const os = require_chunk.__toESM(require("os"));
+
+//#region src/routing/session-key.ts
+/**
+
+* Compute the canonical session key for an inbound message context.
+
+*/
+function computeSessionKey(ctx) {
+	const { agentId, channel, peerKind, peerId, threadId, topicId, dmScope } = ctx;
+	if (peerKind === "dm") {
+		if (dmScope === "main" || dmScope === void 0) return `agent:${agentId}:main`;
+		return `agent:${agentId}:${channel}:dm:${peerId}`;
+	}
+	if (peerKind === "group") {
+		let key$1 = `agent:${agentId}:${channel}:group:${peerId}`;
+		if (topicId) key$1 += `:topic:${topicId}`;
+		if (threadId) key$1 += `:thread:${threadId}`;
+		return key$1;
+	}
+	let key = `agent:${agentId}:${channel}:channel:${peerId}`;
+	if (threadId) key += `:thread:${threadId}`;
+	return key;
+}
+
+//#endregion
+//#region src/routing/agents-routing.ts
+const STATE_FILE = path.default.join(os.default.homedir(), ".hyperclaw", "routing.json");
+const DEFAULT_AGENT = {
+	id: "main",
+	name: "main",
+	workspace: path.default.join(os.default.homedir(), ".hyperclaw", "workspace"),
+	default: true
+};
+var AgentRouter = class {
+	config;
+	constructor(config) {
+		this.config = config ?? this._loadConfig();
+	}
+	_loadConfig() {
+		try {
+			return fs_extra.default.readJsonSync(STATE_FILE);
+		} catch {
+			return {
+				agents: { list: [DEFAULT_AGENT] },
+				bindings: [],
+				session: { dmScope: "main" }
+			};
+		}
+	}
+	_saveConfig() {
+		fs_extra.default.ensureDirSync(path.default.dirname(STATE_FILE));
+		fs_extra.default.writeJsonSync(STATE_FILE, this.config, { spaces: 2 });
+	}
+	route(msg) {
+		const agents = this.config.agents?.list ?? [DEFAULT_AGENT];
+		const bindings = this.config.bindings ?? [];
+		const broadcastAgents = this._resolveBroadcast(msg);
+		const matched = this._matchBinding(msg, bindings, agents);
+		const agentDef = matched.agentDef;
+		const sessionKey = this._computeKey(msg, agentDef.id);
+		const skipLastRoute = msg.isDM ? this._shouldSkipLastRoute(msg) : false;
+		return {
+			agentId: agentDef.id,
+			agentDef,
+			sessionKey,
+			matchedBy: matched.matchedBy,
+			...broadcastAgents.length > 1 ? { broadcast: broadcastAgents } : {},
+			...skipLastRoute ? { skipLastRoute: true } : {}
+		};
+	}
+	_matchBinding(msg, bindings, agents) {
+		const find = (id) => agents.find((a) => a.id === id) ?? DEFAULT_AGENT;
+		for (const b of bindings) {
+			if (!this._matchesFilter(msg, b.match)) continue;
+			return {
+				agentDef: find(b.agentId),
+				matchedBy: this._describeMatch(b.match)
+			};
+		}
+		const defaultAgent = agents.find((a) => a.default) ?? agents[0] ?? DEFAULT_AGENT;
+		return {
+			agentDef: defaultAgent,
+			matchedBy: "default"
+		};
+	}
+	_matchesFilter(msg, match) {
+		if (match.channel && match.channel !== msg.channel) return false;
+		if (match.accountId && match.accountId !== "*" && match.accountId !== msg.accountId) return false;
+		if (match.peer) {
+			if (match.peer.kind !== msg.peer.kind) return false;
+			if (match.peer.id !== msg.peer.id) return false;
+		}
+		if (match.guildId && match.guildId !== msg.guildId) return false;
+		if (match.roles?.length) {
+			const senderRoles = msg.roles ?? [];
+			if (!match.roles.every((r) => senderRoles.includes(r))) return false;
+		}
+		if (match.teamId && match.teamId !== msg.teamId) return false;
+		return true;
+	}
+	_describeMatch(m) {
+		const parts = [];
+		if (m.channel) parts.push(`channel=${m.channel}`);
+		if (m.peer) parts.push(`peer=${m.peer.kind}:${m.peer.id}`);
+		if (m.guildId) parts.push(`guild=${m.guildId}`);
+		if (m.teamId) parts.push(`team=${m.teamId}`);
+		if (m.accountId) parts.push(`account=${m.accountId}`);
+		return parts.join(" ") || "channel-match";
+	}
+	_computeKey(msg, agentId) {
+		const dmScope = this.config.session?.dmScope ?? "main";
+		const ctx = {
+			agentId,
+			channel: msg.channel,
+			peerKind: msg.isDM ? "dm" : msg.peer.kind,
+			peerId: msg.peer.id,
+			threadId: msg.threadId,
+			topicId: msg.topicId,
+			dmScope: msg.isDM ? dmScope : void 0
+		};
+		return computeSessionKey(ctx);
+	}
+	_resolveBroadcast(msg) {
+		const bc = this.config.broadcast;
+		if (!bc) return [];
+		const agentIds = bc[msg.peer.id] ?? bc[msg.senderId];
+		if (Array.isArray(agentIds)) return agentIds;
+		return [];
+	}
+	/**
+	* Returns true when the inbound DM sender is not the pinned owner.
+	* Pinned owner = the single non-wildcard allowFrom entry for this channel.
+	*/
+	_shouldSkipLastRoute(msg) {
+		const chanCfg = this.config.channels?.[msg.channel];
+		if (!chanCfg?.allowFrom) return false;
+		const nonWild = chanCfg.allowFrom.filter((id) => id !== "*" && id !== "**");
+		if (nonWild.length !== 1) return false;
+		const pinnedOwner = nonWild[0];
+		return msg.senderId !== pinnedOwner;
+	}
+	resolveDefaultAccount(channelId) {
+		return this.config.channels?.[channelId]?.defaultAccount;
+	}
+	listBindings() {
+		const agents = this.config.agents?.list ?? [];
+		const bindings = this.config.bindings ?? [];
+		console.log(chalk.default.bold.cyan("\n  🦅 AGENT BINDINGS\n"));
+		if (agents.length === 0) {
+			console.log(chalk.default.gray("  No agents configured.\n"));
+			return;
+		}
+		for (const a of agents) {
+			const def = a.default ? chalk.default.green(" [default]") : "";
+			const model = a.model ? chalk.default.gray(` model:${a.model}`) : "";
+			console.log(`  ${chalk.default.bold(a.id)}${def}  ${chalk.default.gray(a.workspace)}${model}`);
+		}
+		console.log();
+		if (bindings.length === 0) {
+			console.log(chalk.default.gray("  No explicit bindings — all traffic → default agent.\n"));
+			return;
+		}
+		console.log(chalk.default.bold("  Bindings:\n"));
+		for (const b of bindings) {
+			const m = b.match;
+			const parts = [];
+			if (m.channel) parts.push(chalk.default.cyan(m.channel));
+			if (m.peer) parts.push(`peer:${m.peer.kind}/${chalk.default.white(m.peer.id)}`);
+			if (m.guildId) parts.push(`guild:${chalk.default.white(m.guildId)}`);
+			if (m.teamId) parts.push(`team:${chalk.default.white(m.teamId)}`);
+			if (m.roles?.length) parts.push(`roles:[${m.roles.join(",")}]`);
+			if (m.accountId) parts.push(`account:${m.accountId}`);
+			console.log(`  ${parts.join("  ")} ${chalk.default.gray("→")} ${chalk.default.bold(b.agentId)}`);
+		}
+		const bc = this.config.broadcast;
+		if (bc) {
+			console.log(chalk.default.bold("\n  Broadcast groups:\n"));
+			const strat = bc.strategy ?? "parallel";
+			for (const [peerId, agents$1] of Object.entries(bc)) {
+				if (peerId === "strategy") continue;
+				if (Array.isArray(agents$1)) console.log(`  ${chalk.default.white(peerId)}  ${chalk.default.gray(`→ [${agents$1.join(", ")}]`)}  ${chalk.default.gray(`(${strat})`)}`);
+			}
+		}
+		console.log();
+	}
+	async bind() {
+		console.log(chalk.default.cyan("\n  Bind a channel/peer to an agent\n"));
+		const { channel, matchType } = await inquirer.default.prompt([{
+			type: "input",
+			name: "channel",
+			message: "Channel ID (e.g. telegram, discord, slack, whatsapp):",
+			validate: (v) => v.trim().length > 0 || "Required"
+		}, {
+			type: "list",
+			name: "matchType",
+			message: "Match by:",
+			choices: [
+				{
+					name: "Any message on this channel",
+					value: "channel"
+				},
+				{
+					name: "Specific peer (group ID, user ID, channel ID)",
+					value: "peer"
+				},
+				{
+					name: "Discord guild",
+					value: "guild"
+				},
+				{
+					name: "Slack team",
+					value: "team"
+				},
+				{
+					name: "Account ID",
+					value: "account"
+				}
+			]
+		}]);
+		const match = { channel };
+		if (matchType === "peer") {
+			const { kind, peerId } = await inquirer.default.prompt([{
+				type: "list",
+				name: "kind",
+				message: "Peer type:",
+				choices: [
+					"group",
+					"channel",
+					"dm",
+					"room"
+				]
+			}, {
+				type: "input",
+				name: "peerId",
+				message: "Peer ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.peer = {
+				kind,
+				id: peerId
+			};
+		} else if (matchType === "guild") {
+			const { guildId } = await inquirer.default.prompt([{
+				type: "input",
+				name: "guildId",
+				message: "Discord guild ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.guildId = guildId;
+		} else if (matchType === "team") {
+			const { teamId } = await inquirer.default.prompt([{
+				type: "input",
+				name: "teamId",
+				message: "Slack team ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.teamId = teamId;
+		} else if (matchType === "account") {
+			const { accountId } = await inquirer.default.prompt([{
+				type: "input",
+				name: "accountId",
+				message: "Account ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.accountId = accountId;
+		}
+		const agentIds = (this.config.agents?.list ?? []).map((a) => a.id);
+		const { agentId } = await inquirer.default.prompt([{
+			type: agentIds.length > 1 ? "list" : "input",
+			name: "agentId",
+			message: "Route to agent ID:",
+			choices: agentIds.length > 1 ? agentIds : void 0,
+			default: agentIds[0] ?? "main"
+		}]);
+		if (!this.config.bindings) this.config.bindings = [];
+		this.config.bindings.unshift({
+			match,
+			agentId,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		this._saveConfig();
+		console.log(chalk.default.green(`\n  ✔  Binding added: ${channel}/${matchType} → ${agentId}\n`));
+	}
+	async unbind() {
+		const bindings = this.config.bindings ?? [];
+		if (bindings.length === 0) {
+			console.log(chalk.default.gray("\n  No bindings to remove.\n"));
+			return;
+		}
+		const { toRemove } = await inquirer.default.prompt([{
+			type: "checkbox",
+			name: "toRemove",
+			message: "Select bindings to remove:",
+			choices: bindings.map((b, i) => ({
+				name: `${this._describeMatch(b.match)} → ${b.agentId}`,
+				value: i
+			}))
+		}]);
+		for (const idx of toRemove.sort((a, b) => b - a)) bindings.splice(idx, 1);
+		this.config.bindings = bindings;
+		this._saveConfig();
+		console.log(chalk.default.green(`\n  ✔  Removed ${toRemove.length} binding(s)\n`));
+	}
+	getConfig() {
+		return this.config;
+	}
+	getAgents() {
+		return this.config.agents?.list ?? [DEFAULT_AGENT];
+	}
+	getBindings() {
+		return this.config.bindings ?? [];
+	}
+};
+
+//#endregion
+Object.defineProperty(exports, 'AgentRouter', {
+  enumerable: true,
+  get: function () {
+    return AgentRouter;
+  }
+});

package/dist/agents-routing-ChqZ6l2S.js

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

package/dist/api-keys-guide-BCcOl0Q7.js

@@ -0,0 +1,149 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/infra/api-keys-guide.ts
+const API_KEYS_GUIDE = [
+	{
+		serviceId: "anthropic",
+		name: "Anthropic (Claude)",
+		envVar: "ANTHROPIC_API_KEY",
+		url: "platform.anthropic.com",
+		setupSteps: [
+			"1. Go to platform.anthropic.com → API Keys.",
+			"2. Sign up / sign in with an Anthropic account.",
+			"3. Create Key — copy it (starts with sk-ant-). Not shown again!",
+			"",
+			"  🔗 platform.anthropic.com/settings/keys"
+		]
+	},
+	{
+		serviceId: "openai",
+		name: "OpenAI (GPT)",
+		envVar: "OPENAI_API_KEY",
+		url: "platform.openai.com",
+		setupSteps: [
+			"1. Go to platform.openai.com → API keys.",
+			"2. Create new secret key — copy it (starts with sk-). Not shown again!",
+			"3. You need billing enabled for production use.",
+			"",
+			"  🔗 platform.openai.com/api-keys"
+		]
+	},
+	{
+		serviceId: "openrouter",
+		name: "OpenRouter",
+		envVar: "OPENROUTER_API_KEY",
+		url: "openrouter.ai",
+		setupSteps: [
+			"1. Go to openrouter.ai → Keys.",
+			"2. Sign in (Google/GitHub).",
+			"3. Create Key — copy it. OpenRouter provides access to many models (Claude, GPT etc.).",
+			"",
+			"  🔗 openrouter.ai/keys"
+		]
+	},
+	{
+		serviceId: "tavily",
+		name: "Tavily (Web Search)",
+		envVar: "TAVILY_API_KEY",
+		url: "tavily.com",
+		setupSteps: [
+			"1. Go to tavily.com → Sign up.",
+			"2. Dashboard → API Keys → Create API Key.",
+			"3. Copy the key. Used for the web-search skill.",
+			"",
+			"  🔗 app.tavily.com"
+		]
+	},
+	{
+		serviceId: "elevenlabs",
+		name: "ElevenLabs (TTS)",
+		envVar: "ELEVENLABS_API_KEY",
+		url: "elevenlabs.io",
+		setupSteps: [
+			"1. Go to elevenlabs.io → Profile → API Key.",
+			"2. Copy the API key (or create a new one).",
+			"3. Used for talk mode (voice responses).",
+			"",
+			"  🔗 elevenlabs.io/app/settings/api-keys"
+		]
+	},
+	{
+		serviceId: "deepl",
+		name: "DeepL (Translation)",
+		envVar: "DEEPL_API_KEY",
+		url: "deepl.com",
+		setupSteps: [
+			"1. Go to deepl.com/pro-api → Get API key.",
+			"2. Sign up (free tier available).",
+			"3. Account → API keys — copy the Authentication Key.",
+			"",
+			"  🔗 deepl.com/pro-api"
+		]
+	},
+	{
+		serviceId: "github",
+		name: "GitHub (PAT)",
+		envVar: "GITHUB_TOKEN",
+		url: "github.com",
+		setupSteps: [
+			"1. GitHub → Settings → Developer settings → Personal access tokens.",
+			"2. Generate new token (classic or fine-grained).",
+			"3. Select scopes: repo, read:user etc. depending on use case.",
+			"",
+			"  🔗 github.com/settings/tokens"
+		]
+	},
+	{
+		serviceId: "xai",
+		name: "xAI (Grok)",
+		envVar: "XAI_API_KEY",
+		url: "x.ai",
+		setupSteps: [
+			"1. Go to console.x.ai → API keys.",
+			"2. Sign in and create a new key.",
+			"3. Copy the key.",
+			"",
+			"  🔗 console.x.ai"
+		]
+	},
+	{
+		serviceId: "google",
+		name: "Google AI (Gemini)",
+		envVar: "GOOGLE_AI_API_KEY",
+		url: "ai.google.dev",
+		setupSteps: [
+			"1. Go to aistudio.google.com/apikey.",
+			"2. Get API key or Create API key.",
+			"3. Copy the key.",
+			"",
+			"  🔗 aistudio.google.com/apikey"
+		]
+	}
+];
+const SERVICE_ID_MAP = new Map(API_KEYS_GUIDE.map((g) => [g.serviceId.toLowerCase(), g]));
+/** Known name aliases (e.g. anthropic, claude -> anthropic) */
+const ALIASES = {
+	claude: "anthropic",
+	gpt: "openai",
+	xai: "xai",
+	google: "google"
+};
+function getApiKeyGuide(serviceId) {
+	const id = serviceId.toLowerCase().replace(/[^a-z0-9-]/g, "");
+	return SERVICE_ID_MAP.get(id) ?? SERVICE_ID_MAP.get(ALIASES[id] ?? "") ?? null;
+}
+/** For unknown services — generic API key instructions */
+const GENERIC_API_KEY_STEPS = [
+	"For an unknown service:",
+	"1. Go to the official service website (e.g. developers.xxx.com).",
+	"2. Sign up / sign in. An account is usually required.",
+	"3. Look for \"API Keys\", \"Credentials\", \"Developer\" or \"Integrations\" section.",
+	"4. Create a new API key or token. Copy it immediately — many services do not show it again.",
+	"5. Keep it secret — do not share it or commit it to a repo.",
+	"",
+	"  💡 Known services: anthropic, openai, openrouter, tavily, elevenlabs, deepl, github, xai, google"
+];
+
+//#endregion
+exports.GENERIC_API_KEY_STEPS = GENERIC_API_KEY_STEPS;
+exports.getApiKeyGuide = getApiKeyGuide;