hovclaw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HOVClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+<h1 align="center">HOVClaw</h1>
+
+<p align="center">
+  <strong>Lean self-hosted AI agent gateway with OpenClaw-compatible control surface</strong>
+</p>
+
+<p align="center">
+  <a href="#philosophy">Philosophy</a> •
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#architecture">Architecture</a>
+</p>
+
+---
+
+## Philosophy
+
+HOVClaw is built on a simple principle: **run your own AI agent infrastructure, controlled from the channels you already use**.
+
+- **Self-hosted first** - Everything runs on your machine, no cloud dependency
+- **Channel-native** - Talk to your agent via Telegram or Discord, not a custom app
+- **OpenClaw-compatible** - Mirror config to `~/.openclaw` for ClawHub discovery and tooling interop
+- **Gateway-first control** - WebSocket protocol v3 for programmatic access, with a built-in web UI for quick ops
+
+## Features
+
+### Multi-Channel Agent Gateway
+
+- **Telegram** - Polling/webhook intake, callback queries, topic routing (`chatId#threadId`), media send, reactions
+- **Discord** - Full bot adapter via discord.js
+- **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
+
+### 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
+- **LaunchAgent integration** - `hovclaw gateway install/start/stop` for macOS background service
+- **Programmatic access** - `hovclaw gateway call <method>` for scripting
+
+### Agent Runtime
+
+- **Pi agent core** - `@mariozechner/pi-agent-core` for agent loop and tool orchestration
+- **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
+- **Session persistence** - SQLite-backed sessions, messages, agent state, and usage tracking
+
+### Scheduling & Automation
+
+- **Cron jobs** - `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
+
+### OpenClaw Compatibility
+
+- **Mirror strategy** - HOVClaw is source of truth; mirror files written to `~/.openclaw`
+- **ClawHub discovery** - `~/.openclaw/openclaw.json` + `~/.openclaw/skills` symlink
+- **Compat CLI** - `hovclaw compat status --sync` to verify mirror state
+
+## Installation
+
+### Prerequisites
+
+- Node.js 22+
+- Bun package manager
+
+### Build
+
+```bash
+# Clone the repository
+git clone https://github.com/user/hovclaw.git
+cd hovclaw
+
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Run tests
+bun run test
+```
+
+### First-Time Setup
+
+```bash
+# Interactive onboarding (configures channels, models, credentials)
+bun run onboard
+
+# Or if hovclaw is linked globally
+hovclaw onboard
+```
+
+## Configuration
+
+Run the onboarding wizard to get started:
+
+```bash
+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`.
+
+### 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`
+  - `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`
+  - capped at 4,000 chars per file and 12,000 chars total
+
+### Config Structure
+
+| Key | Purpose |
+|-----|---------|
+| `assistant` | Assistant name and identity |
+| `agents` | Agent definitions and defaults |
+| `bindings` | Inbound message routing rules |
+| `models` | Model slots, fallback policy, aliases |
+| `runtime` | Execution mode, timeouts, allowed paths/commands |
+| `channels` | Telegram and Discord channel config |
+| `gateway` | Gateway host, port, auth, web UI settings |
+| `scheduler` | Cron poll interval, concurrency, timezone |
+
+Environment overrides are supported for most fields. See [docs/config-reference.md](docs/config-reference.md).
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        Channels                               │
+│  ┌──────────┐  ┌─────────┐  ┌─────┐  ┌───────────┐          │
+│  │ Telegram │  │ Discord │  │ CLI │  │ Scheduler │          │
+│  └────┬─────┘  └────┬────┘  └──┬──┘  └─────┬─────┘          │
+│       └──────────────┴─────────┴────────────┘                 │
+│                          │                                     │
+│                   ┌──────▼──────┐                             │
+│                   │   Router    │  Binding-based agent        │
+│                   │             │  resolution                 │
+│                   └──────┬──────┘                             │
+│                          │                                     │
+│                ┌─────────▼─────────┐                          │
+│                │  Agent Manager    │  Session lifecycle       │
+│                │                   │  + persistence           │
+│                └─────────┬─────────┘                          │
+│                          │                                     │
+│         ┌────────────────┼────────────────┐                   │
+│         ▼                ▼                ▼                   │
+│   ┌──────────┐    ┌──────────┐    ┌──────────┐              │
+│   │ Agent    │    │ Agent    │    │ Agent    │  pi-agent     │
+│   │ Session  │    │ Session  │    │ Session  │  core loop    │
+│   └────┬─────┘    └────┬─────┘    └────┬─────┘              │
+│        └────────────────┼────────────────┘                    │
+│                         │                                     │
+│              ┌──────────▼──────────┐                          │
+│              │    Tool Runtime     │                          │
+│              │  ┌───────────────┐  │                          │
+│              │  │ Built-in      │  │                          │
+│              │  │ Skills        │  │                          │
+│              │  │ Local / Docker│  │                          │
+│              │  └───────────────┘  │                          │
+│              └─────────────────────┘                          │
+│                                                               │
+│  ┌────────────────────────────────────────────────────────┐   │
+│  │                    Gateway (ws + http)                  │   │
+│  │  WebSocket v3 protocol  •  Web UI  •  21 methods       │   │
+│  └────────────────────────────────────────────────────────┘   │
+│                                                               │
+│  ┌────────────────────────────────────────────────────────┐   │
+│  │                    SQLite (better-sqlite3)              │   │
+│  │  sessions • messages • agent_state • usage_costs       │   │
+│  │  scheduled_jobs • task_run_logs • audit_log            │   │
+│  └────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Core Components
+
+| Component | Purpose |
+|-----------|---------|
+| **Agent Manager** | Per-session agent lifecycle, state persistence, model resolution |
+| **Router** | Binding-based inbound routing with peer/guild/account/channel cascade |
+| **Scheduler** | Cron job loading, execution, and channel notifications |
+| **Gateway** | WebSocket v3 server with 21 methods, 5 event types, built-in web UI |
+| **Skill Loader** | SKILL.md frontmatter parsing and dependency checking |
+| **Channels** | Telegram (multi-account, policy, pairing) and Discord adapters |
+
+## CLI Overview
+
+```bash
+# Setup
+hovclaw onboard
+hovclaw login [provider]
+hovclaw doctor [--fix] [--deep] [--json]
+hovclaw status [--json]
+
+# Messaging
+hovclaw message send --channel telegram --to <chat_id> --message "hello"
+
+# Channel management
+hovclaw channels list|status|add|remove|login|logout [--account <id>] [--json]
+
+# Model management
+hovclaw models list|status|set [--model <ref>] [--target <slot>] [--json]
+
+# Gateway lifecycle
+hovclaw gateway run
+hovclaw gateway install|uninstall|start|stop|restart [--json]
+hovclaw gateway status|health [--json]
+hovclaw gateway call <method> [--params '{...}'] [--json]
+hovclaw gateway open-ui
+
+# Daemon
+hovclaw daemon install|uninstall|start|stop|restart|status|logs
+
+# Compatibility
+hovclaw compat status [--sync] [--json]
+```
+
+## Gateway Methods (v3)
+
+| Method | Purpose |
+|--------|---------|
+| `health` | Uptime, active sessions, channels |
+| `status` | Gateway config, channel status, session counts |
+| `channels.status` | Per-channel enabled/connected status |
+| `channels.logout` | Log out a channel (optionally scoped) |
+| `config.get` / `config.set` / `config.patch` | Read/write/merge config |
+| `models.list` / `models.set` / `models.status` | Model catalog and routing |
+| `skills.status` | Skill list with dependency checks |
+| `sessions.list` / `sessions.preview` | Session listing and message history |
+| `send` | Send text/media/reaction to a channel |
+| `agent` | Run agent loop, stream events |
+| `chat.history` / `chat.send` / `chat.abort` | Chat session interaction |
+| `cron.list` / `cron.status` | Scheduled job listing and status |
+| `logs.tail` | Recent audit events |
+
+Events: `tick`, `health`, `agent`, `chat`, `shutdown`
+
+## Development
+
+```bash
+bun run build          # tsc compile to dist/
+bun run typecheck      # tsc --noEmit
+bun run dev            # start daemon (tsx src/index.ts)
+bun run test           # vitest run
+bun run test:watch     # vitest watch
+```
+
+## OpenClaw Heritage
+
+HOVClaw is a lean TypeScript implementation inspired by [OpenClaw](https://github.com/openclaw/openclaw). See [FEATURE_PARITY.md](FEATURE_PARITY.md) for the complete tracking matrix.
+
+Key differences:
+
+- **Lean scope** - Telegram + Discord only, not all 20+ channels
+- **Gateway-first** - WebSocket v3 control plane with built-in web UI
+- **SQLite persistence** - Single-file database, no external services
+- **Pi agent runtime** - `@mariozechner/pi-agent-core` for agent loop orchestration
+- **Multi-account Telegram** - Per-account config, policy, and pairing
+
+## Docs
+
+- [docs/concept.md](docs/concept.md)
+- [docs/architecture.md](docs/architecture.md)
+- [docs/config-reference.md](docs/config-reference.md)
+- [docs/gateway-compat.md](docs/gateway-compat.md)
+
+## License
+
+MIT

package/dist/doctor-I8YVuapp.js

@@ -0,0 +1,211 @@
+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 fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { intro, log, outro } from "@clack/prompts";
+import { spawnSync } from "node:child_process";
+
+//#region src/cli/doctor.ts
+function addFinding(findings, id, status, title, detail) {
+	findings.push({
+		id,
+		status,
+		title,
+		detail
+	});
+}
+function summarize(findings) {
+	return findings.reduce((acc, finding) => {
+		acc[finding.status] += 1;
+		return acc;
+	}, {
+		pass: 0,
+		warn: 0,
+		fail: 0,
+		repair: 0
+	});
+}
+function hasAtLeastOneCredential(credentials) {
+	return Object.keys(credentials).length > 0;
+}
+function isValidTimezone(tz) {
+	try {
+		Intl.DateTimeFormat("en-US", { timeZone: tz }).format(/* @__PURE__ */ new Date());
+		return true;
+	} catch {
+		return false;
+	}
+}
+function pathInsideAnyRoot(filePath, roots) {
+	const resolved = path.resolve(filePath);
+	return roots.some((root) => {
+		const resolvedRoot = path.resolve(root);
+		return resolved === resolvedRoot || resolved.startsWith(`${resolvedRoot}${path.sep}`);
+	});
+}
+function checkDockerAvailability() {
+	const result = spawnSync("docker", [
+		"version",
+		"--format",
+		"{{.Server.Version}}"
+	], {
+		encoding: "utf8",
+		timeout: 1e4
+	});
+	if (result.status === 0) return {
+		ok: true,
+		detail: `Docker available (${result.stdout.trim() || "unknown"}).`
+	};
+	return {
+		ok: false,
+		detail: result.stderr?.trim() || result.stdout?.trim() || "docker command failed. Install/start Docker Desktop and retry."
+	};
+}
+function parseDoctorArgs(args) {
+	const options = {
+		repair: false,
+		deep: false,
+		json: false
+	};
+	for (const arg of args) {
+		if (arg === "--repair" || arg === "--fix") {
+			options.repair = true;
+			continue;
+		}
+		if (arg === "--deep") {
+			options.deep = true;
+			continue;
+		}
+		if (arg === "--json") {
+			options.json = true;
+			continue;
+		}
+		throw new Error(`Unknown flag: ${arg}`);
+	}
+	return options;
+}
+function runDoctorChecks(options, env = process.env) {
+	const findings = [];
+	const hovclawHome = getHovclawHome(env);
+	const configPath = getConfigPath(env);
+	const credentialsPath = getCredentialsPath(env);
+	if (!fs.existsSync(hovclawHome)) if (options.repair) {
+		fs.mkdirSync(hovclawHome, {
+			recursive: true,
+			mode: 448
+		});
+		addFinding(findings, "home-dir", "repair", "Created HovClaw home directory", hovclawHome);
+	} else addFinding(findings, "home-dir", "warn", "HovClaw home directory missing", `${hovclawHome} (run 'npm run onboard' or re-run doctor with --fix)`);
+	else addFinding(findings, "home-dir", "pass", "HovClaw home directory", hovclawHome);
+	let configLoaded = false;
+	let loadedConfig = null;
+	if (!hasConfigFile(env)) if (options.repair && detectLegacyEnvConfig(env)) if (ensureConfigFromLegacyEnv(env)) addFinding(findings, "config-file", "repair", "Imported legacy env config", `Config created at ${configPath}`);
+	else addFinding(findings, "config-file", "fail", "Config file missing", `No config found at ${configPath}. Run 'npm run onboard'.`);
+	else addFinding(findings, "config-file", "fail", "Config file missing", `No config found at ${configPath}. Run 'npm run onboard'.`);
+	try {
+		loadedConfig = loadConfig(env);
+		configLoaded = true;
+		addFinding(findings, "config-parse", "pass", "Config parsed successfully", configPath);
+	} catch (error) {
+		addFinding(findings, "config-parse", "fail", "Config is invalid", `${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!hasCredentialsFile(env)) if (options.repair) {
+		saveCredentials({}, env);
+		addFinding(findings, "credentials-file", "repair", "Created credentials file", credentialsPath);
+	} else addFinding(findings, "credentials-file", "warn", "Credentials file missing", `${credentialsPath} (run 'npm run onboard' to configure providers).`);
+	try {
+		const credentials = loadCredentials(env);
+		if (hasAtLeastOneCredential(credentials)) addFinding(findings, "credentials-presence", "pass", "Credentials are configured", `Providers: ${Object.keys(credentials).sort().join(", ")}`);
+		else addFinding(findings, "credentials-presence", "warn", "No provider credentials configured", "Run 'npm run onboard' or 'npm run login -- <provider>'.");
+	} catch (error) {
+		addFinding(findings, "credentials-parse", "fail", "Credentials file is invalid", `${credentialsPath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (configLoaded && loadedConfig) {
+		if (!loadedConfig.channels.discord.enabled && !loadedConfig.channels.telegram.enabled) addFinding(findings, "channels-enabled", "warn", "No channels enabled", "Enable at least one channel in onboarding or config.");
+		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.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.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.");
+		if (loadedConfig.runtime.allowedReadRoots.length === 0) addFinding(findings, "runtime-read-roots", "fail", "No read roots configured", "Set runtime.allowedReadRoots in onboarding/config.");
+		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)`);
+		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) {
+			fs.mkdirSync(writeRoot, {
+				recursive: true,
+				mode: 448
+			});
+			addFinding(findings, "runtime-write-root-create", "repair", "Created missing write root", writeRoot);
+		} else addFinding(findings, "runtime-write-root-missing", "warn", "Write root does not exist", `${writeRoot} (re-run doctor with --fix to create).`);
+		if (!isValidTimezone(loadedConfig.scheduler.timezone)) addFinding(findings, "scheduler-timezone", "fail", "Scheduler timezone is invalid", loadedConfig.scheduler.timezone);
+		else addFinding(findings, "scheduler-timezone", "pass", "Scheduler timezone valid", loadedConfig.scheduler.timezone);
+		const mainAgentPath = path.join(loadedConfig.agentsDir, "main", "agent.json");
+		if (!fs.existsSync(mainAgentPath)) addFinding(findings, "main-agent", "fail", "Main agent config missing", `${mainAgentPath} not found.`);
+		else {
+			addFinding(findings, "main-agent", "pass", "Main agent config present", mainAgentPath);
+			try {
+				const parsed = JSON.parse(fs.readFileSync(mainAgentPath, "utf8"));
+				if (Array.isArray(parsed.skills)) {
+					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");
+			} catch (error) {
+				addFinding(findings, "main-agent-parse", "fail", "Main agent config is invalid JSON", error instanceof Error ? error.message : String(error));
+			}
+		}
+		if (options.deep && loadedConfig.runtime.mode === "container") {
+			const docker = checkDockerAvailability();
+			if (docker.ok) addFinding(findings, "docker", "pass", "Docker is available", docker.detail);
+			else addFinding(findings, "docker", "fail", "Docker unavailable for container runtime", docker.detail);
+		}
+	}
+	const summary = summarize(findings);
+	return {
+		findings,
+		summary,
+		ok: summary.fail === 0
+	};
+}
+function printReport(report) {
+	for (const finding of report.findings) {
+		const line = `[${finding.status === "pass" ? "PASS" : finding.status === "warn" ? "WARN" : finding.status === "repair" ? "REPAIR" : "FAIL"}] ${finding.title}: ${finding.detail}`;
+		if (finding.status === "pass") log.success(line);
+		else if (finding.status === "warn") log.warn(line);
+		else if (finding.status === "repair") log.info(line);
+		else log.error(line);
+	}
+	const { pass, warn, fail, repair } = report.summary;
+	log.message(`Summary: ${pass} pass, ${warn} warn, ${fail} fail, ${repair} repair`);
+}
+async function main(argv = process.argv.slice(2)) {
+	let options;
+	try {
+		options = parseDoctorArgs(argv);
+	} catch (error) {
+		log.error(error instanceof Error ? error.message : String(error));
+		log.error("Usage: hovclaw doctor [--fix|--repair] [--deep] [--json]");
+		process.exit(1);
+		return;
+	}
+	if (!options.json) intro("HovClaw Doctor");
+	const report = runDoctorChecks(options);
+	if (options.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+	else {
+		printReport(report);
+		outro(report.ok ? "Doctor complete." : "Doctor found issues.");
+	}
+	if (!report.ok) process.exit(1);
+}
+if (process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) main();
+
+//#endregion
+export { main };