hyperclaw 4.0.1 → 5.0.0

package/README.md

@@ -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.1-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">
@@ -55,7 +55,7 @@
 
 ## Install
 
-Runtime: Node ≥ 22.
+Runtime: Node ≥ 22. Runs **natively on Windows, macOS, and Linux** — no WSL2 required.
 
 ```bash
 npm install -g hyperclaw@latest
@@ -68,8 +68,24 @@ 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.
+
 The wizard guides you step by step — provider, model, gateway, channels, and skills.
-Works on **macOS, Linux, and Windows** (via WSL2 recommended). Compatible with npm, pnpm, and bun.
+Works on **macOS, Linux, and Windows** (native — no WSL2 required). Compatible with npm, pnpm, and bun.
 
 ---
 
@@ -101,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 |
 |---------|--------|-------|
@@ -133,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
@@ -287,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-CT_jDEU9.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/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-683Q2JGp.js

@@ -0,0 +1,129 @@
+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/agents-routing.ts
+var AgentRouter = class {
+	stateFile;
+	agents = [];
+	constructor() {
+		this.stateFile = path.default.join(os.default.homedir(), ".hyperclaw", "agents.json");
+		this.load();
+	}
+	load() {
+		try {
+			this.agents = fs_extra.default.readJsonSync(this.stateFile);
+		} catch {
+			this.agents = [{
+				workspace: path.default.join(os.default.homedir(), ".hyperclaw", "workspace"),
+				name: "default",
+				model: void 0,
+				bindings: []
+			}];
+		}
+	}
+	save() {
+		fs_extra.default.ensureDirSync(path.default.dirname(this.stateFile));
+		fs_extra.default.writeJsonSync(this.stateFile, this.agents, { spaces: 2 });
+	}
+	listBindings() {
+		console.log(chalk.default.bold.cyan("\n  🦅 AGENT BINDINGS\n"));
+		if (this.agents.length === 0) {
+			console.log(chalk.default.gray("  No agents configured."));
+			return;
+		}
+		for (const agent of this.agents) {
+			console.log(`  ${chalk.default.bold(agent.name)}  ${chalk.default.gray(agent.workspace)}`);
+			if (agent.bindings.length === 0) console.log(`    ${chalk.default.gray("No channel bindings — receives from all channels")}`);
+			else for (const b of agent.bindings) {
+				const acct = b.accountId ? chalk.default.gray(`@${b.accountId}`) : chalk.default.gray("(all accounts)");
+				const role = b.role === "primary" ? chalk.default.green("[primary]") : chalk.default.gray("[secondary]");
+				console.log(`    ${chalk.default.cyan(b.channelId)} ${acct} ${role}`);
+			}
+			console.log();
+		}
+	}
+	async bind() {
+		console.log(chalk.default.cyan("\n  Bind a channel to an agent workspace\n"));
+		const { channel, workspace, role } = await inquirer.default.prompt([
+			{
+				type: "input",
+				name: "channel",
+				message: "Channel ID (e.g. telegram, discord, slack):",
+				validate: (v) => v.trim().length > 0 || "Required"
+			},
+			{
+				type: "input",
+				name: "workspace",
+				message: "Agent workspace (directory or name):",
+				default: "default"
+			},
+			{
+				type: "list",
+				name: "role",
+				message: "Binding role:",
+				choices: [{
+					name: "primary — routes all traffic from this channel",
+					value: "primary"
+				}, {
+					name: "secondary — fallback if primary is busy",
+					value: "secondary"
+				}]
+			}
+		]);
+		let agent = this.agents.find((a) => a.name === workspace || a.workspace === workspace);
+		if (!agent) {
+			agent = {
+				workspace,
+				name: workspace,
+				bindings: []
+			};
+			this.agents.push(agent);
+		}
+		agent.bindings.push({
+			channelId: channel,
+			agentWorkspace: agent.workspace,
+			role,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		this.save();
+		console.log(chalk.default.green(`\n  ✔  Bound ${channel} → ${workspace} (${role})\n`));
+	}
+	async unbind() {
+		const allBindings = [];
+		for (const agent of this.agents) for (const b of agent.bindings) allBindings.push({
+			agent: agent.name,
+			channel: b.channelId
+		});
+		if (allBindings.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: allBindings.map((b) => ({
+				name: `${b.channel} → ${b.agent}`,
+				value: b
+			}))
+		}]);
+		for (const { agent: agentName, channel } of toRemove) {
+			const agent = this.agents.find((a) => a.name === agentName);
+			if (agent) agent.bindings = agent.bindings.filter((b) => b.channelId !== channel);
+		}
+		this.save();
+		console.log(chalk.default.green(`\n  ✔  Removed ${toRemove.length} binding(s)\n`));
+	}
+};
+
+//#endregion
+Object.defineProperty(exports, 'AgentRouter', {
+  enumerable: true,
+  get: function () {
+    return AgentRouter;
+  }
+});

package/dist/agents-routing-BpZBswBH.js

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