hyperclaw 4.0.0 → 4.0.1

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,10 +6,11 @@
 
 <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.0-blue?style=flat-square" alt="release">
+  <img src="https://img.shields.io/badge/release-v4.0.1-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">
+  <img src="https://img.shields.io/badge/security-ethical%20hacking-red?style=flat-square&logo=hackthebox&logoColor=white" alt="security">
 </p>
 
 <p align="center">
@@ -21,7 +22,8 @@
 </p>
 
 <p align="center">
-  <em>If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.</em>
+  <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">
@@ -36,19 +38,34 @@
 
 ---
 
+## Use cases
+
+| Use case | How |
+|----------|-----|
+| **Personal assistant** | Chat via Telegram/Discord, voice on macOS/iOS, always-on daemon |
+| **Bug bounty & OSINT** | HackerOne/Bugcrowd/Synack API keys, web-search skill, clipboard & screenshot tools |
+| **Ethical hacking / pentest** | PC access tools (bash, file read/write), sandboxed execution, MCP tool servers |
+| **Cybersecurity research** | Automate recon, triage findings, draft reports — all from your phone via Telegram |
+| **Developer productivity** | Code review, GitHub integration, local shell access, memory across sessions |
+| **Home automation** | Cron skills, morning briefing, calendar events, device commands (macOS/Android) |
+
+> HyperClaw runs **locally on your machine** — your data, your keys, your control.
+
+---
+
 ## Install
 
 Runtime: Node ≥ 22.
 
 ```bash
-npm install -g github:hyperclaw-ai/hyperclaw
-# ή
-npm install -g https://github.com/hyperclaw-ai/hyperclaw
 npm install -g hyperclaw@latest
 # or: pnpm add -g hyperclaw@latest
-hyperclaw onboard --install deamon 
 
+# First-time setup wizard
 hyperclaw onboard
+
+# Or install with daemon (auto-start on boot, full PC access)
+hyperclaw onboard --install-daemon
 ```
 
 The wizard guides you step by step — provider, model, gateway, channels, and skills.
@@ -62,17 +79,20 @@ Works on **macOS, Linux, and Windows** (via WSL2 recommended). Compatible with n
 # 1. Run the onboarding wizard (first time)
 hyperclaw onboard
 
-# 2. Start the gateway (stays running in foreground)
+# 2a. Start the gateway in foreground
 hyperclaw gateway --port 18789 --verbose
 
-# 3. Or install as a background daemon (launchd / systemd)
-hyperclaw daemon install && hyperclaw daemon start
+# 2b. Or run as a background daemon (auto-start on boot)
+hyperclaw daemon start
 
-# 4. Talk to your assistant
+# 3. Talk to your assistant
 hyperclaw agent --message "What can you do?"
 
-# 5. Send a message to a connected channel
-hyperclaw message send --to +1234567890 --message "Hello from HyperClaw"
+# 4. Security / bug bounty — run recon from your phone
+# Just message your Telegram bot: "search HackerOne for targets on acme.com"
+
+# 5. Check status
+hyperclaw doctor
 ```
 
 Upgrading? Run `hyperclaw doctor` to check and migrate.
@@ -213,7 +233,7 @@ Full guide: [docs/security.md](docs/security.md)
 ## Features
 
 - **Local-first Gateway** — single control plane for sessions, channels, tools, and events
-- **Multi-channel inbox** — 14+ channels, unified session model
+- **Multi-channel inbox** — 27+ 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
@@ -312,10 +332,19 @@ docker build -f Dockerfile.sandbox -t hyperclaw:sandbox .
 ```
 hyperclaw/
 ├── src/                    # Core CLI, gateway, channels, tools
-│   ├── cli/                # CLI entry point + commands
+│   ├── cli/                # CLI entry point + onboarding wizard
 │   ├── gateway/            # Gateway server + manager (re-exports)
 │   ├── channels/           # Channel connectors + registry
-│   └── services/           # MCP, memory, heartbeat, cron
+│   ├── services/           # MCP, memory, heartbeat, cron
+│   ├── agent/              # Agent loop, orchestrator, tool dispatch
+│   ├── canvas/             # A2UI Canvas renderer
+│   ├── commands/           # CLI sub-commands (channels, pairing…)
+│   ├── hooks/              # Lifecycle hooks (boot, cron, memory)
+│   ├── infra/              # Tool policy, destructive gate, secrets
+│   ├── media/              # Voice, TTS, STT, audio
+│   ├── routing/            # Session routing + multi-agent dispatch
+│   ├── security/           # Auth, sandboxing, DM policy
+│   └── …                  # (sdk, types, webhooks, logging, plugins…)
 ├── packages/
 │   ├── core/               # Inference engine, agent loop
 │   ├── gateway/            # Gateway package (standalone)
@@ -324,9 +353,12 @@ hyperclaw/
 │   ├── ios/                # iOS node app
 │   ├── android/            # Android node app
 │   ├── macos/              # macOS menu bar app
-│   └── macos-menubar/      # Tauri macOS menu bar
+│   ├── macos-menubar/      # Tauri macOS menu bar
+│   └── web/                # Web UI (React + Vite)
 ├── extensions/             # Channel connectors (Telegram, Discord…)
 ├── skills/                 # Bundled skills (reminders, translator)
+├── workspace-templates/    # Agent config templates (AGENTS.md, SOUL.md, TOOLS.md…)
+├── scripts/                # Build + utility scripts
 ├── tests/                  # Vitest — unit / integration / e2e
 └── docs/                   # Full documentation
 ```

package/dist/api-keys-guide-Bzig1R5W.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;

package/dist/connector-DRv1ahC_.js

@@ -0,0 +1,343 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const chalk = require_chunk.__toESM(require("chalk"));
+const fs_extra = require_chunk.__toESM(require("fs-extra"));
+const path = require_chunk.__toESM(require("path"));
+const os = require_chunk.__toESM(require("os"));
+const ws = require_chunk.__toESM(require("ws"));
+const https = require_chunk.__toESM(require("https"));
+const events = require_chunk.__toESM(require("events"));
+
+//#region extensions/discord/src/connector.ts
+const STATE_FILE = path.default.join(os.default.homedir(), ".hyperclaw", "discord-state.json");
+const OPC = {
+	DISPATCH: 0,
+	HEARTBEAT: 1,
+	IDENTIFY: 2,
+	RESUME: 6,
+	RECONNECT: 7,
+	INVALID_SESSION: 9,
+	HELLO: 10,
+	HEARTBEAT_ACK: 11
+};
+const INTENTS = {
+	GUILDS: 1,
+	GUILD_MESSAGES: 512,
+	GUILD_MESSAGE_CONTENT: 32768,
+	DIRECT_MESSAGES: 4096,
+	DIRECT_MESSAGE_CONTENT: 16384
+};
+function discordRest(token, method, endpoint, body) {
+	return new Promise((resolve, reject) => {
+		const payload = body ? JSON.stringify(body) : null;
+		const req = https.default.request({
+			hostname: "discord.com",
+			port: 443,
+			path: `/api/v10${endpoint}`,
+			method,
+			headers: {
+				"Authorization": `Bot ${token}`,
+				"User-Agent": "HyperClaw/4.0.1 (https://hyperclaw.ai)",
+				...payload ? {
+					"Content-Type": "application/json",
+					"Content-Length": Buffer.byteLength(payload)
+				} : {}
+			}
+		}, (res) => {
+			let data = "";
+			res.on("data", (c) => data += c);
+			res.on("end", () => {
+				if (res.statusCode === 204) return resolve(null);
+				try {
+					const r = JSON.parse(data);
+					if (res.statusCode && res.statusCode >= 400) reject(new Error(`Discord API ${res.statusCode}: ${r.message || data}`));
+					else resolve(r);
+				} catch {
+					reject(new Error(`Invalid JSON (${res.statusCode})`));
+				}
+			});
+		});
+		req.on("error", reject);
+		if (payload) req.write(payload);
+		req.end();
+	});
+}
+var DiscordConnector = class extends events.EventEmitter {
+	token;
+	config;
+	ws = null;
+	heartbeatInterval = null;
+	lastSequence = null;
+	sessionId = null;
+	resumeGatewayUrl = null;
+	running = false;
+	botUser = null;
+	constructor(token, config) {
+		super();
+		this.token = token;
+		this.config = {
+			token,
+			dmPolicy: "allowlist",
+			allowFrom: [],
+			approvedPairings: [],
+			pendingPairings: {},
+			listenGuildIds: [],
+			commandPrefix: "!",
+			...config
+		};
+	}
+	async connect() {
+		const gateway = await discordRest(this.token, "GET", "/gateway/bot");
+		const wsUrl = (gateway.url || "wss://gateway.discord.gg") + "/?v=10&encoding=json";
+		this.botUser = await discordRest(this.token, "GET", "/users/@me");
+		console.log(chalk.default.green(`  🦅 Discord: @${this.botUser?.username} connected`));
+		await this.loadState();
+		this.running = true;
+		await this.openWebSocket(wsUrl);
+	}
+	async disconnect() {
+		this.running = false;
+		if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+		this.ws?.close(1e3);
+		await this.saveState();
+	}
+	async openWebSocket(url) {
+		this.ws = new ws.WebSocket(url, { headers: { "User-Agent": "HyperClaw/4.0.1" } });
+		this.ws.on("message", async (data) => {
+			const payload = JSON.parse(data.toString());
+			await this.handlePayload(payload);
+		});
+		this.ws.on("close", (code) => {
+			if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+			if (!this.running) return;
+			const resumable = ![
+				1e3,
+				4004,
+				4010,
+				4011,
+				4012,
+				4013,
+				4014
+			].includes(code);
+			console.log(chalk.default.yellow(`  ⚠  Discord WS closed (${code}) — ${resumable ? "resuming" : "reconnecting"} in 5s`));
+			setTimeout(() => {
+				if (this.running) {
+					const url$1 = resumable && this.resumeGatewayUrl ? this.resumeGatewayUrl + "/?v=10&encoding=json" : "wss://gateway.discord.gg/?v=10&encoding=json";
+					this.openWebSocket(url$1);
+				}
+			}, 5e3);
+		});
+		this.ws.on("error", (e) => console.log(chalk.default.yellow(`  ⚠  Discord WS error: ${e.message}`)));
+	}
+	async handlePayload(payload) {
+		const { op, d, s, t } = payload;
+		if (s !== null && s !== void 0) this.lastSequence = s;
+		switch (op) {
+			case OPC.HELLO:
+				this.startHeartbeat(d.heartbeat_interval);
+				if (this.sessionId && this.lastSequence) this.resume();
+				else this.identify();
+				break;
+			case OPC.HEARTBEAT_ACK: break;
+			case OPC.HEARTBEAT:
+				this.sendWs({
+					op: OPC.HEARTBEAT,
+					d: this.lastSequence
+				});
+				break;
+			case OPC.RECONNECT:
+				this.ws?.close(4e3);
+				break;
+			case OPC.INVALID_SESSION:
+				if (d) setTimeout(() => this.resume(), 2e3);
+				else {
+					this.sessionId = null;
+					this.lastSequence = null;
+					setTimeout(() => this.identify(), 2e3);
+				}
+				break;
+			case OPC.DISPATCH:
+				await this.handleEvent(t, d);
+				break;
+		}
+	}
+	identify() {
+		const intents = INTENTS.GUILDS | INTENTS.GUILD_MESSAGES | INTENTS.GUILD_MESSAGE_CONTENT | INTENTS.DIRECT_MESSAGES;
+		this.sendWs({
+			op: OPC.IDENTIFY,
+			d: {
+				token: this.token,
+				intents,
+				properties: {
+					os: process.platform,
+					browser: "HyperClaw",
+					device: "HyperClaw"
+				}
+			}
+		});
+	}
+	resume() {
+		this.sendWs({
+			op: OPC.RESUME,
+			d: {
+				token: this.token,
+				session_id: this.sessionId,
+				seq: this.lastSequence
+			}
+		});
+	}
+	startHeartbeat(interval) {
+		if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+		this.heartbeatInterval = setInterval(() => {
+			this.sendWs({
+				op: OPC.HEARTBEAT,
+				d: this.lastSequence
+			});
+		}, interval);
+	}
+	sendWs(payload) {
+		if (this.ws?.readyState === ws.WebSocket.OPEN) this.ws.send(JSON.stringify(payload));
+	}
+	async handleEvent(type, data) {
+		switch (type) {
+			case "READY":
+				this.sessionId = data.session_id;
+				this.resumeGatewayUrl = data.resume_gateway_url;
+				this.botUser = data.user;
+				await this.saveState();
+				this.emit("ready", data.user);
+				break;
+			case "RESUMED":
+				console.log(chalk.default.gray("  Discord session resumed"));
+				break;
+			case "MESSAGE_CREATE":
+				await this.handleMessage(data);
+				break;
+		}
+	}
+	async handleMessage(msg) {
+		if (msg.author.id === this.botUser?.id) return;
+		if (msg.author.bot) return;
+		const isDM = !msg.channel_id.startsWith("0") && await this.isDirectMessage(msg.channel_id);
+		const userId = msg.author.id;
+		if (isDM) {
+			const allowed = await this.checkDMPolicy(userId, msg.channel_id, msg.content);
+			if (!allowed) return;
+		}
+		this.emit("message", {
+			id: msg.id,
+			channelId: "discord",
+			from: userId,
+			fromUsername: msg.author.global_name || msg.author.username,
+			chatId: msg.channel_id,
+			text: msg.content,
+			timestamp: msg.timestamp,
+			isDM
+		});
+	}
+	dmChannelCache = /* @__PURE__ */ new Set();
+	async isDirectMessage(channelId) {
+		if (this.dmChannelCache.has(channelId)) return true;
+		try {
+			const channel = await discordRest(this.token, "GET", `/channels/${channelId}`);
+			if (channel.type === 1) {
+				this.dmChannelCache.add(channelId);
+				return true;
+			}
+		} catch {}
+		return false;
+	}
+	async checkDMPolicy(userId, channelId, text) {
+		if (this.config.dmPolicy === "none") return false;
+		if (this.config.dmPolicy === "open") return true;
+		if (this.config.dmPolicy === "allowlist") {
+			if (this.config.allowFrom.includes(userId)) return true;
+			await this.sendMessage(channelId, "🦅 **HyperClaw**\n\nYou are not on the allowlist.");
+			return false;
+		}
+		if (this.config.dmPolicy === "pairing") {
+			if (this.config.approvedPairings.includes(userId)) return true;
+			const upper = text.trim().toUpperCase();
+			if (this.config.pendingPairings[upper]) {
+				this.config.approvedPairings.push(userId);
+				delete this.config.pendingPairings[upper];
+				await this.saveState();
+				await this.sendMessage(channelId, "🦅 **Paired!** You can now send messages.");
+				this.emit("pairing:approved", {
+					userId,
+					channelId: "discord"
+				});
+				return true;
+			}
+			const code = this.generateCode();
+			this.config.pendingPairings[code] = userId;
+			await this.saveState();
+			await this.sendMessage(channelId, `🦅 **HyperClaw Pairing**\n\nSend the owner this code:\n\`${code}\`\n\nApprove with:\n\`hyperclaw pairing approve discord ${code}\``);
+			return false;
+		}
+		return false;
+	}
+	async sendMessage(channelId, content) {
+		const chunks = content.match(/.{1,2000}/gs) || [content];
+		let last = null;
+		for (const chunk of chunks) last = await discordRest(this.token, "POST", `/channels/${channelId}/messages`, { content: chunk });
+		return last;
+	}
+	async sendTyping(channelId) {
+		await discordRest(this.token, "POST", `/channels/${channelId}/typing`).catch(() => {});
+	}
+	async createDMChannel(userId) {
+		const ch = await discordRest(this.token, "POST", "/users/@me/channels", { recipient_id: userId });
+		return ch.id;
+	}
+	async sendDM(userId, content) {
+		const channelId = await this.createDMChannel(userId);
+		await this.sendMessage(channelId, content);
+	}
+	generateCode() {
+		const chars = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+		return Array.from({ length: 6 }, () => chars[Math.floor(Math.random() * chars.length)]).join("");
+	}
+	approvePairing(code) {
+		const upper = code.toUpperCase();
+		if (!this.config.pendingPairings[upper]) return false;
+		this.config.approvedPairings.push(this.config.pendingPairings[upper]);
+		delete this.config.pendingPairings[upper];
+		this.saveState();
+		return true;
+	}
+	addToAllowlist(userId) {
+		if (!this.config.allowFrom.includes(userId)) {
+			this.config.allowFrom.push(userId);
+			this.saveState();
+		}
+	}
+	async loadState() {
+		try {
+			const s = await fs_extra.default.readJson(STATE_FILE);
+			this.sessionId = s.sessionId || null;
+			this.lastSequence = s.lastSequence || null;
+			this.resumeGatewayUrl = s.resumeGatewayUrl || null;
+			if (s.pendingPairings) this.config.pendingPairings = s.pendingPairings;
+			if (s.approvedPairings) this.config.approvedPairings = s.approvedPairings;
+		} catch {}
+	}
+	async saveState() {
+		await fs_extra.default.ensureDir(path.default.dirname(STATE_FILE));
+		await fs_extra.default.writeJson(STATE_FILE, {
+			sessionId: this.sessionId,
+			lastSequence: this.lastSequence,
+			resumeGatewayUrl: this.resumeGatewayUrl,
+			pendingPairings: this.config.pendingPairings,
+			approvedPairings: this.config.approvedPairings
+		}, { spaces: 2 });
+	}
+	isRunning() {
+		return this.running;
+	}
+	getBotUser() {
+		return this.botUser;
+	}
+};
+
+//#endregion
+exports.DiscordConnector = DiscordConnector;