hypervibes 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+<h1 align="center">HyperVibes</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+---
+
+<p align="center">
+  Agentic Trading Harness, built on <a href="https://earendil.com/posts/pi-durable/">Pi Durable</a>
+</p>
+
+<p align="center">
+  <a href="https://hypervibes.ai"><img src="https://img.shields.io/badge/Website-hypervibes.ai-0f766e?logo=googlechrome&logoColor=white" alt="Website"></a>
+  <a href="https://hypervibes.ai/docs/"><img src="https://img.shields.io/badge/Documentation-2563eb?logo=readthedocs&logoColor=white" alt="Documentation"></a>
+  <a href="https://discord.gg/Up39Qvqmkh"><img src="https://img.shields.io/badge/Discord-5865f2?logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://x.com/HyperVibesAI"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="X"></a>
+</p>
+
+![HyperVibes dashboard](website/static/img/dashboard.png)
+
+## Quick start
+
+HyperVibes is a self-hosted app for running AI trading agents on Hyperliquid.
+Install Node.js 22.23.3 or newer, then run:
+
+```sh
+npx hypervibes@beta
+```
+
+Open <http://localhost:3003>. No `.env` file is required.
+
+1. Sign in with the browser wallet that owns your Hyperliquid account.
+2. Open Account to generate or import a Hyperliquid API key and approve the builder fee. Never import your main wallet's private key.
+3. Connect an AI provider, create an agent, and review its instructions and risk settings.
+
+Agents can place real orders. AI can make mistakes, and trading can lose money.
+Start with trading disabled while you check your setup.
+
+See the [quick start guide](docs/QuickStart.md) for your first agent.
+
+## Features
+
+- **Batteries included:** agent tools for research, analysis, trading, and accounting, ready to use.
+- **Self-hosted:** run on your own hardware and keep your data under your control.
+- **Decentralized:** trade on Hyperliquid with just an Ethereum account.
+- **Built on [Pi Durable](https://earendil.com/posts/pi-durable/):** durable agent execution that survives restarts.
+
+Explore the [user guide](https://hypervibes.ai/docs/) for more.
+
+## Installation
+
+- **NPX:** `npx hypervibes@beta` runs the published beta without cloning or building the source.
+- **Global npm install:** `npm install -g hypervibes@beta`, then run `hypervibes`.
+- **From source:** clone the repository, run `pnpm install`, then `pnpm start`. See [Development](#development).
+- **Docker Compose — coming soon.**
+- **Desktop download — coming soon:** planned builds for macOS, Windows, and Linux.
+- **Local release package:** run `pnpm pack` from a source checkout to build an npm tarball. See [Build](#build).
+- **Local container build:** run `pnpm pack --out artifacts/hypervibes.tgz`, then `docker build -f Containerfile -t hypervibes:local .`.
+
+See the [installation guide](docs/Installation.md) for setup, persistent storage,
+and remote access.
+
+## Configuration
+
+HyperVibes keeps its SQLite database (`hypervibes.sqlite`) and secrets file
+(`config.json`) outside the project:
+
+| OS | Database directory | Config directory |
+| --- | --- | --- |
+| Linux | `~/.local/share/hypervibes/` | `~/.config/hypervibes/` |
+| macOS | `~/Library/Application Support/HyperVibes/` | Same as database |
+| Windows | `%APPDATA%\HyperVibes\` | Same as database |
+
+Linux respects `XDG_DATA_HOME` and `XDG_CONFIG_HOME` when set to absolute paths.
+Back up both files together; losing the encryption key prevents recovery of stored credentials.
+
+See [Configuration](docs/Configuration.md) for all file settings, environment
+variables, and path overrides.
+
+## Development
+
+Install Node.js 22.23.3 or newer and pnpm.
+
+```sh
+git clone https://github.com/idft/hypervibes.git
+cd hypervibes
+pnpm install
+pnpm dev
+```
+
+Open <http://localhost:3003>. The development server supports hot reload.
+See [`AGENTS.md`](AGENTS.md) for architecture and project conventions.
+
+### Build
+
+```sh
+pnpm build          # Compiled backend, frontend, and runtime resources
+pnpm start:built    # Run that build without rebuilding
+pnpm pack           # Rebuild and create a local npm tarball
+```
+
+`pnpm start` builds fresh production assets before serving. Keep development
+dependencies installed for source builds. The release package exposes the
+`hypervibes` executable and needs only Node.js and runtime dependencies to launch.
+Run `node bin/hypervibes.js --help` for usage. The npm package is published as
+`hypervibes`; use the `beta` tag for the current beta release.
+
+### Checks
+
+```sh
+pnpm typecheck:server
+pnpm lint:server
+pnpm test
+```
+
+`pnpm test` runs application, startup, container health-check, and screenshot-tool
+tests without building the trading app or requiring Docker or Chromium.
+For release checks, run `pnpm build`, `pnpm test:build`, and `pnpm test:package`;
+package testing performs a clean install.
+
+GitHub Actions validates pull requests, pushes to `master` and `v*` branches,
+and manual runs. It tests the release package on Linux, macOS, and Windows,
+and non-root containers on native AMD64 and ARM64 runners.
+Publishing a GitHub release validates again before publishing images to GHCR.
+Tag pushes only create draft releases; branch pushes do not publish images.
+
+## License
+
+HyperVibes is licensed under the [GNU Affero General Public License v3.0 only](LICENSE)
+(`AGPL-3.0-only`).
+
+## Disclaimer
+
+HyperVibes is open-source software that can enable agents to submit orders to
+Hyperliquid using user-authorized signing keys. It is not financial,
+investment, trading, legal, or tax advice, and is not a broker, dealer,
+exchange, custodian, or financial intermediary.
+
+Trading digital assets and derivatives involves substantial risk, including the
+possible loss of all capital. AI-generated analysis, automated strategies, and
+software outputs may be incorrect or unsuitable for any purpose. You are solely
+responsible for your trading decisions, agent configuration, credentials,
+monitoring, and compliance with applicable laws and regulations.
+
+The software and related materials are provided "as is" without warranties of
+any kind. To the maximum extent permitted by law, the authors and copyright
+holders are not liable for losses, damages, or expenses arising from use of the
+software, including trading losses, software defects, configuration errors,
+service outages, or third-party failures.

package/bin/hypervibes.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { assertSupportedNode } from "../scripts/check-node.mjs";
+
+try {
+  assertSupportedNode();
+  const args = process.argv.slice(2);
+  if (args.length === 1 && ["--help", "-h"].includes(args[0])) {
+    console.log("Usage: hypervibes [--help | --version]\n\nStarts HyperVibes at http://localhost:3003 by default.\nConfigure with environment variables or an optional .env in the current directory.\nPress Ctrl+C to stop.");
+  } else if (args.length === 1 && ["--version", "-v"].includes(args[0])) {
+    const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    console.log(version);
+  } else if (args.length !== 0) {
+    throw new Error("Unknown arguments. Run hypervibes --help for usage.");
+  } else {
+    try { process.loadEnvFile(); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    const { main } = await import("../dist/main.js");
+    await main([]);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+}

package/dist/agents/agent-enablement.js

@@ -0,0 +1,10 @@
+import { AgentError } from "./agent-input.js";
+/** Execution permission is independent of initialization/deletion lifecycle. */
+export async function agentExecutable(db, id) {
+    const agent = await db.get("SELECT enabled,state FROM hv_agents WHERE id=?", id);
+    return agent?.enabled === 1 && agent.state === "ready";
+}
+export async function assertAgentExecutable(db, id) {
+    if (!await agentExecutable(db, id))
+        throw new AgentError("Agent is disabled or unavailable. Enable it before starting work.", 409);
+}

package/dist/agents/agent-input.js

@@ -0,0 +1,38 @@
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const agentErrorBrand = Symbol.for("hypervibes.AgentError");
+export class AgentError extends Error {
+    status;
+    [agentErrorBrand] = true;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Fastify and Vite SSR load separate copies of this module in development. */
+export function isAgentError(error) {
+    return error instanceof Error && Reflect.get(error, agentErrorBrand) === true;
+}
+export function agentId(value) {
+    if (!uuid.test(value) || value.trim() !== value)
+        throw new AgentError("Agent not found", 404);
+    return value.toLowerCase();
+}
+export function requestId(value) {
+    if (!uuid.test(value) || value.trim() !== value)
+        throw new AgentError("A valid request ID is required");
+    return value.toLowerCase();
+}
+export function agentName(value) {
+    const name = value.trim();
+    if (!name || name.length > 80 || [...name].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127))
+        throw new AgentError("Name must contain 1–80 printable characters");
+    return name;
+}
+export function chatMessage(value) {
+    const message = value.trim();
+    if (!message || message.length > 16_000)
+        throw new AgentError("Message must contain 1–16,000 characters");
+    return message;
+}
+/** Persistent storage identity: changing this format requires data migration. */
+export function harnessPrefix(id) { return `pi_${agentId(id).replaceAll("-", "")}_`; }