hovclaw 0.1.0 → 0.1.2

package/README.md

@@ -32,11 +32,15 @@ HOVClaw is built on a simple principle: **run your own AI agent infrastructure,
 - **Multi-account Telegram** - Multiple bot accounts with per-account status and logout
 - **Text mode controls** - Per-channel `plain|markdown` rendering mode (default `plain`)
 - **Policy layer** - `dmPolicy`, `groupPolicy`, per-group/per-topic overrides, pairing flow
+- **Native Telegram commands** - Auto-registered slash command menu (including skill aliases)
+- **Thinking controls** - `/think <level> <task>` plus persisted default via `commands.defaultThinkingLevel`
 
 ### Gateway & Control Plane
 
 - **WebSocket protocol v3** - Request/response/event frames with 21 methods
 - **Built-in web UI** - Connection, health, channels, sessions, and chat in one page
+- **Fail-closed auth defaults** - Gateway auth is required unless explicitly opting into insecure mode
+- **Origin-aware WS policy** - Browser `Origin` headers must be same-origin or allowlisted
 - **LaunchAgent integration** - `hovclaw gateway install/start/stop` for macOS background service
 - **Programmatic access** - `hovclaw gateway call <method>` for scripting
 
@@ -46,11 +50,12 @@ HOVClaw is built on a simple principle: **run your own AI agent infrastructure,
 - **Multi-provider models** - Anthropic, Google, OpenAI, OpenRouter via `@mariozechner/pi-ai`
 - **Model routing** - Per-target model slots (interactive, discord, cron) with fallback policy
 - **Workspace-first tools** - Relative file tool paths resolve from agent workspace
+- **Least-privilege tools** - Bash tool disabled by default (`runtime.tools.bashEnabled=false`)
 - **Session persistence** - SQLite-backed sessions, messages, agent state, and usage tracking
 
 ### Scheduling & Automation
 
-- **Cron jobs** - `agents/*/cron.json` with configurable schedules and timezone support
+- **Cron jobs** - `~/.hovclaw/agents/*/cron.json` with configurable schedules and timezone support
 - **Channel notifications** - Scheduled job results delivered to Telegram or Discord
 - **Concurrent execution** - Configurable max concurrent jobs
 
@@ -105,17 +110,33 @@ hovclaw onboard
 The wizard handles channel tokens, model provider credentials (via OAuth or API key),
 and agent configuration. All settings are saved to `~/.hovclaw/config.json`.
 
+Security defaults in this release are intentionally strict:
+- gateway start fails if `gateway.enabled=true` and neither `gateway.auth.token` nor `gateway.auth.password` is set (unless `gateway.auth.allowUnauthenticated=true`)
+- Telegram webhook mode requires a non-empty webhook secret
+- bash runtime tool is opt-in only via `runtime.tools.bashEnabled=true`
+
+Agent and skill definitions are loaded from:
+- `~/.hovclaw/agents/<name>/agent.json` (`CLAUDE.md`, `cron.json`)
+  - missing `~/.hovclaw/agents/main/agent.json` is auto-bootstrapped with a minimal scaffold (`name`, `skills`)
+- `~/.agents/skills/<name>/SKILL.md`
+  - legacy `~/.hovclaw/skills` content is copied once when shared skills are empty
+
+Runtime state is written under:
+- `~/.hovclaw/store` (SQLite `hovclaw.db`, pairing store)
+- `~/.hovclaw/data`
+
 ### Workspace Defaults and Bootstrap
 
 - Default workspace: `~/.hovclaw/workspace`
 - Blank agent workspace values resolve to the same default workspace
 - On startup and onboarding, HOVClaw auto-creates missing workspace files:
   - `AGENTS.md`
+  - `SOUL.md`
   - `IDENTITY.md`
   - `USER.md`
   - `BOOTSTRAP.md` (only when the workspace is effectively empty)
 - Workspace files are appended to the system prompt in this order:
-  - `AGENTS.md` -> `IDENTITY.md` -> `USER.md` -> `BOOTSTRAP.md`
+  - `AGENTS.md` -> `SOUL.md` -> `IDENTITY.md` -> `USER.md` -> `BOOTSTRAP.md`
   - capped at 4,000 chars per file and 12,000 chars total
 
 ### Config Structure
@@ -126,6 +147,7 @@ and agent configuration. All settings are saved to `~/.hovclaw/config.json`.
 | `agents` | Agent definitions and defaults |
 | `bindings` | Inbound message routing rules |
 | `models` | Model slots, fallback policy, aliases |
+| `commands` | Native command behavior, slash registration, authorization |
 | `runtime` | Execution mode, timeouts, allowed paths/commands |
 | `channels` | Telegram and Discord channel config |
 | `gateway` | Gateway host, port, auth, web UI settings |
@@ -200,6 +222,7 @@ Environment overrides are supported for most fields. See [docs/config-reference.
 # Setup
 hovclaw onboard
 hovclaw login [provider]
+hovclaw reset [--scope config|config+creds+sessions|full] [--yes] [--non-interactive] [--dry-run] [--json]
 hovclaw doctor [--fix] [--deep] [--json]
 hovclaw status [--json]
 
@@ -209,9 +232,16 @@ hovclaw message send --channel telegram --to <chat_id> --message "hello"
 # Channel management
 hovclaw channels list|status|add|remove|login|logout [--account <id>] [--json]
 
+# Pairing management
+hovclaw pairing approve telegram <code>
+hovclaw pairing approve --channel telegram [--account <id>] <code> [--json]
+
 # Model management
 hovclaw models list|status|set [--model <ref>] [--target <slot>] [--json]
 
+# Skill management
+hovclaw skills list|info|check|init [--json]
+
 # Gateway lifecycle
 hovclaw gateway run
 hovclaw gateway install|uninstall|start|stop|restart [--json]

package/dist/{doctor-I8YVuapp.js → doctor-D52M80De.js}

@@ -1,8 +1,9 @@
-import { A as hasCredentialsFile, C as detectLegacyEnvConfig, E as getCredentialsPath, I as saveCredentials, M as loadCredentials, O as getHovclawHome, T as getConfigPath, j as loadConfig, k as hasConfigFile, w as ensureConfigFromLegacyEnv } from "./hovclaw.js";
+import { A as ensureConfigFromLegacyEnv, F as hasConfigFile, H as saveCredentials, I as hasCredentialsFile, L as loadConfig, M as getCredentialsPath, P as getHovclawHome, R as loadCredentials, V as saveConfigFile, j as getConfigPath, k as detectLegacyEnvConfig, z as loadFileConfig } from "./hovclaw.js";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { intro, log, outro } from "@clack/prompts";
+import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
 
 //#region src/cli/doctor.ts
@@ -61,6 +62,11 @@ function checkDockerAvailability() {
 		detail: result.stderr?.trim() || result.stdout?.trim() || "docker command failed. Install/start Docker Desktop and retry."
 	};
 }
+function mutateFileConfig(env, mutate) {
+	const fileConfig = loadFileConfig(env);
+	mutate(fileConfig);
+	saveConfigFile(fileConfig, env);
+}
 function parseDoctorArgs(args) {
 	const options = {
 		repair: false,
@@ -125,10 +131,35 @@ function runDoctorChecks(options, env = process.env) {
 		else addFinding(findings, "channels-enabled", "pass", "At least one channel enabled", "OK");
 		if (loadedConfig.channels.discord.enabled) if (!loadedConfig.channels.discord.botToken.trim()) addFinding(findings, "discord-token", "fail", "Discord enabled without token", "Set channels.discord.botToken via onboarding.");
 		else addFinding(findings, "discord-token", "pass", "Discord token configured", "OK");
-		if (loadedConfig.channels.telegram.enabled) if (!loadedConfig.channels.telegram.botToken.trim()) addFinding(findings, "telegram-token", "fail", "Telegram enabled without token", "Set channels.telegram.botToken via onboarding.");
-		else addFinding(findings, "telegram-token", "pass", "Telegram token configured", "OK");
+		if (loadedConfig.channels.telegram.enabled) {
+			if (!loadedConfig.channels.telegram.botToken.trim()) addFinding(findings, "telegram-token", "fail", "Telegram enabled without token", "Set channels.telegram.botToken via onboarding.");
+			else addFinding(findings, "telegram-token", "pass", "Telegram token configured", "OK");
+			const webhookAccountsMissingSecret = Object.entries(loadedConfig.channels.telegram.accounts).filter(([, account]) => account.webhook.enabled && !account.webhook.secret.trim()).map(([accountId]) => accountId);
+			if (webhookAccountsMissingSecret.length > 0) if (options.repair) {
+				mutateFileConfig(env, (fileConfig) => {
+					for (const accountId of webhookAccountsMissingSecret) {
+						const account = fileConfig.channels.telegram.accounts[accountId];
+						if (!account || !account.webhook.enabled) continue;
+						account.webhook.secret = randomBytes(24).toString("base64url");
+						if (accountId === fileConfig.channels.telegram.defaultAccountId) fileConfig.channels.telegram.webhook.secret = account.webhook.secret;
+					}
+				});
+				addFinding(findings, "telegram-webhook-secret", "repair", "Generated missing Telegram webhook secret(s)", webhookAccountsMissingSecret.join(", "));
+			} else addFinding(findings, "telegram-webhook-secret", "fail", "Telegram webhook secret missing", `Accounts: ${webhookAccountsMissingSecret.join(", ")}`);
+			else addFinding(findings, "telegram-webhook-secret", "pass", "Telegram webhook secret policy", "OK");
+		}
 		if (!loadedConfig.gateway.enabled) addFinding(findings, "gateway-enabled", "warn", "Gateway is disabled", "Enable gateway for OpenClaw/ClawHub compatibility.");
 		else addFinding(findings, "gateway-enabled", "pass", "Gateway enabled", "OK");
+		if (loadedConfig.gateway.auth.allowUnauthenticated) addFinding(findings, "gateway-auth-mode", "warn", "Gateway unauthenticated mode is enabled", "Set gateway.auth.allowUnauthenticated=false for secure deployments.");
+		else if (!loadedConfig.gateway.auth.token.trim() && !loadedConfig.gateway.auth.password.trim()) if (options.repair) {
+			const generatedToken = randomBytes(24).toString("base64url");
+			mutateFileConfig(env, (fileConfig) => {
+				fileConfig.gateway.auth.allowUnauthenticated = false;
+				fileConfig.gateway.auth.token = generatedToken;
+			});
+			addFinding(findings, "gateway-auth-required", "repair", "Generated gateway auth token", "Set in gateway.auth.token to satisfy strict auth mode.");
+		} else addFinding(findings, "gateway-auth-required", "fail", "Gateway auth secrets are missing", "Set gateway.auth.token or gateway.auth.password, or explicitly enable allowUnauthenticated.");
+		else addFinding(findings, "gateway-auth-required", "pass", "Gateway auth configured", "OK");
 		if (!loadedConfig.gateway.host.trim() || loadedConfig.gateway.port <= 0) addFinding(findings, "gateway-bind", "fail", "Gateway bind is invalid", "Set gateway.host and gateway.port to valid values.");
 		else addFinding(findings, "gateway-bind", "pass", "Gateway bind configured", `${loadedConfig.gateway.host}:${loadedConfig.gateway.port}`);
 		if (loadedConfig.gateway.mode === "remote" && !loadedConfig.gateway.remote.url.trim()) addFinding(findings, "gateway-remote-url", "fail", "Gateway remote mode missing URL", "Set gateway.remote.url or switch gateway.mode to local.");
@@ -136,6 +167,13 @@ function runDoctorChecks(options, env = process.env) {
 		else addFinding(findings, "runtime-read-roots", "pass", "Read roots configured", `${loadedConfig.runtime.allowedReadRoots.length} root(s)`);
 		if (loadedConfig.runtime.allowedWriteRoots.length === 0) addFinding(findings, "runtime-write-roots", "warn", "No write roots configured", "Agent will not be able to write files.");
 		else addFinding(findings, "runtime-write-roots", "pass", "Write roots configured", `${loadedConfig.runtime.allowedWriteRoots.length} root(s)`);
+		if (loadedConfig.runtime.tools.bashEnabled) if (options.repair) {
+			mutateFileConfig(env, (fileConfig) => {
+				fileConfig.runtime.tools.bashEnabled = false;
+			});
+			addFinding(findings, "runtime-bash-enabled", "repair", "Disabled bash tool by default", "Set runtime.tools.bashEnabled=true only for trusted environments.");
+		} else addFinding(findings, "runtime-bash-enabled", "warn", "Bash tool is enabled", "High-risk surface. Prefer runtime.tools.bashEnabled=false.");
+		else addFinding(findings, "runtime-bash-enabled", "pass", "Bash tool disabled", "OK");
 		const unreadableWriteRoots = loadedConfig.runtime.allowedWriteRoots.filter((writeRoot) => !pathInsideAnyRoot(writeRoot, loadedConfig.runtime.allowedReadRoots));
 		if (unreadableWriteRoots.length > 0) addFinding(findings, "runtime-write-without-read", "warn", "Some write roots are not in read roots", unreadableWriteRoots.join(", "));
 		for (const writeRoot of loadedConfig.runtime.allowedWriteRoots) if (!fs.existsSync(writeRoot)) if (options.repair) {
@@ -157,7 +195,7 @@ function runDoctorChecks(options, env = process.env) {
 					const missingSkills = parsed.skills.filter((entry) => typeof entry === "string").filter((skill) => !fs.existsSync(path.join(loadedConfig.skillsDir, skill, "SKILL.md")));
 					if (missingSkills.length > 0) addFinding(findings, "main-agent-skills", "fail", "Main agent references missing skills", missingSkills.join(", "));
 					else addFinding(findings, "main-agent-skills", "pass", "Main agent skills are resolvable", "OK");
-				} else addFinding(findings, "main-agent-skills", "warn", "Main agent skills list is missing or invalid", "Expected skills: string[] in agents/main/agent.json");
+				} else addFinding(findings, "main-agent-skills", "warn", "Main agent skills list is missing or invalid", `Expected skills: string[] in ${mainAgentPath}`);
 			} catch (error) {
 				addFinding(findings, "main-agent-parse", "fail", "Main agent config is invalid JSON", error instanceof Error ? error.message : String(error));
 			}

package/dist/gateway/ui/app.js

@@ -194,7 +194,7 @@ function appendChatMessage(role, text) {
 function showChatEmpty(text) {
   chatOutput.innerHTML = "";
   const p = document.createElement("p");
-  p.className = "text-gray-500 text-sm text-center m-auto";
+  p.className = "chat-empty";
   p.textContent = text;
   chatOutput.appendChild(p);
 }
@@ -372,7 +372,7 @@ async function connectGateway(event) {
       });
 
       connected = true;
-      saveStoredConnection({ gatewayUrl, token });
+      saveStoredConnection({ gatewayUrl });
       const connId = hello?.server?.connId || "ok";
       setConnectionState(true, `Connected (${connId})`);
       logLine(`Connected to ${gatewayUrl}`);
@@ -501,7 +501,7 @@ function wireEvents() {
 function bootstrap() {
   const stored = loadStoredConnection();
   gatewayUrlInput.value = stored.gatewayUrl || defaultGatewayUrl();
-  tokenInput.value = stored.token || "";
+  tokenInput.value = "";
   passwordInput.value = "";
   setConnectionState(false, "Disconnected");
   setupPanels();

package/dist/gateway/ui/credentials.d.ts

@@ -2,7 +2,6 @@ export const STORAGE_KEY: string;
 
 export interface StoredConnection {
   gatewayUrl: string;
-  token: string;
 }
 
 export interface StorageLike {
@@ -13,7 +12,7 @@ export interface StorageLike {
 
 export function loadStoredConnection(storage?: StorageLike | null): StoredConnection;
 export function saveStoredConnection(
-  connection: { gatewayUrl?: string; token?: string; [key: string]: unknown },
+  connection: { gatewayUrl?: string; [key: string]: unknown },
   storage?: StorageLike | null,
 ): void;
 export function clearStoredConnection(storage?: StorageLike | null): void;

package/dist/gateway/ui/credentials.js

@@ -17,26 +17,25 @@ function resolveStorage(storage) {
 export function loadStoredConnection(storage) {
   const targetStorage = resolveStorage(storage);
   if (!targetStorage) {
-    return { gatewayUrl: "", token: "" };
+    return { gatewayUrl: "" };
   }
 
   const raw = targetStorage.getItem(STORAGE_KEY);
   if (!raw) {
-    return { gatewayUrl: "", token: "" };
+    return { gatewayUrl: "" };
   }
 
   try {
     const parsed = JSON.parse(raw);
     if (!isRecord(parsed)) {
-      return { gatewayUrl: "", token: "" };
+      return { gatewayUrl: "" };
     }
 
     const gatewayUrl =
       typeof parsed.gatewayUrl === "string" ? parsed.gatewayUrl : "";
-    const token = typeof parsed.token === "string" ? parsed.token : "";
-    return { gatewayUrl, token };
+    return { gatewayUrl };
   } catch {
-    return { gatewayUrl: "", token: "" };
+    return { gatewayUrl: "" };
   }
 }
 
@@ -49,7 +48,6 @@ export function saveStoredConnection(connection, storage) {
   const payload = {
     gatewayUrl:
       typeof connection?.gatewayUrl === "string" ? connection.gatewayUrl : "",
-    token: typeof connection?.token === "string" ? connection.token : "",
   };
 
   targetStorage.setItem(STORAGE_KEY, JSON.stringify(payload));