diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 0000000000000000000000000000000000000000..d327e5befc6ecedddff56d7ef9a849c37d11629d --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,18 @@ +# CodeRabbit configuration. +# +# Auto-review is DISABLED repo-wide: the app was enabled at the org level on +# 2026-08-14 and immediately began reviewing every opened PR. This repo's +# merge gate is CI ("All required checks pass") plus maintainer review — +# CodeRabbit reviews carry no merge weight (protect-main ruleset requires +# 0 approving reviews), so auto-firing on the full PR firehose adds comment +# noise without gating value. +# +# The bot stays installed and summonable on demand: comment +# `@coderabbitai review` on any PR to request a one-off review, or +# `@coderabbitai ignore` to mute it on a PR it has already joined. +# +# To re-enable auto-review, flip `enabled: true` below (or delete this file — +# the app default is on). +reviews: + auto_review: + enabled: false diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000000000000000000000000000000000000..f773f5426316d5edea4af9d699b92d5bb2f7af63 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,114 @@ +# Git +.git +.gitignore +.gitmodules + +# Python +__pycache__ +*.py[cod] +*$py.class +*.so +.Python +*.egg-info/ +dist/ +build/ + +# Virtual environments +venv/ +env/ +ENV/ + +# Dependencies +node_modules +**/node_modules +.venv +**/.venv +.notebooklm-cli-venv/ +.notebooklm-playwright/ +.pip-cache/ +.uv-cache/ + +# Built artifacts that are regenerated inside the image. Excluded so local +# rebuilds on the developer's machine don't invalidate the npm-install layer +# that now depends on the full ui-tui/packages/hermes-ink/ tree being present. +ui-tui/dist/ +ui-tui/packages/hermes-ink/dist/ + +# CI/CD +.github + +# Environment files +.env +.env.* +# ...but keep the template: docker/stage2-hook.sh seeds $HERMES_HOME/.env from +# /opt/hermes/.env.example on first boot (OOF-285 — excluding it silently broke +# first-boot .env seeding and the API_SERVER_KEY generation that depends on it). +!.env.example + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# Testing +.pytest_cache/ +.coverage +htmlcov/ + +# Documentation +*.md + +# Runtime data (bind-mounted at /opt/data; must not leak into build context) +data/ +.hermes-docker/ +.notebooklm-home/ + +# Compose/profile runtime state (bind-mounted; avoid ownership/secret issues) +hermes-config/ +runtime/ + +# ---------- Not needed inside the Docker image ---------- + +# Desktop app source (Tauri/Electron); never installed in the container. +# apps/shared is the dashboard↔desktop websocket helper and is linked from +# web/package.json as a file: workspace dep — keep it in the build context. +apps/ +!apps/shared/ +!apps/shared/** + +# Test suite — not shipped in production images +tests/ + +# Documentation site (Docusaurus) +website/ + +# Assets only used by the GitHub README +assets/ +infographic/ + +# Plugin-level docs (hermes-achievements ships docs/ but the runtime doesn't read them) +plugins/hermes-achievements/docs/ + +# Nix / Homebrew / AUR packaging metadata — irrelevant to Docker +nix/ +flake.nix +flake.lock +packaging/ + +# Design and planning documents +plans/ +.plans/ + +# Repo-level dotfiles that are git-only or dev-tooling config +.envrc +.gitattributes +.hadolint.yaml +.mailmap + +# Debug/export artifacts — must never reach image layers (COPY . .) +/log.txt +/sqlite_leak_fix.png +/*.png.bak +*.tar.gz +*.tgz diff --git a/.env.example b/.env.example new file mode 100644 index 0000000000000000000000000000000000000000..78c0108e1c785df884b4c838e4e751016d15be19 --- /dev/null +++ b/.env.example @@ -0,0 +1,544 @@ +# Hermes Agent Environment Configuration +# Copy this file to .env and fill in your API keys + +# ============================================================================= +# LLM PROVIDER (Fireworks AI) +# ============================================================================= +# Get your key at: https://app.fireworks.ai/settings/users/api-keys +# Address models directly by catalog ID, e.g. +# accounts/fireworks/models/kimi-k2p6, accounts/fireworks/models/glm-5p2 +# FIREWORKS_API_KEY= +# ============================================================================= +# LLM PROVIDER (OpenRouter) +# ============================================================================= +# OpenRouter provides access to many models through one API +# All LLM calls go through OpenRouter - no direct provider keys needed +# Get your key at: https://openrouter.ai/keys +# OPENROUTER_API_KEY= + +# Default model is configured in ~/.hermes/config.yaml (model.default). +# Use 'hermes model' or 'hermes setup' to change it. +# LLM_MODEL is no longer read from .env — this line is kept for reference only. +# LLM_MODEL=anthropic/claude-opus-4.6 + +# ============================================================================= +# LLM PROVIDER (NovitaAI) +# ============================================================================= +# NovitaAI — 90+ models, pay-per-use +# Get your key at: https://novita.ai/settings/key-management +# NOVITA_API_KEY= +# NOVITA_BASE_URL=https://api.novita.ai/openai/v1 # Override default base URL + +# ============================================================================= +# LLM PROVIDER (Google AI Studio / Gemini) +# ============================================================================= +# Native Gemini API via Google's OpenAI-compatible endpoint. +# Get your key at: https://aistudio.google.com/app/apikey +# GOOGLE_API_KEY=your_google_ai_studio_key_here +# GEMINI_API_KEY=your_gemini_key_here # alias for GOOGLE_API_KEY +# Optional base URL override (default: Google's OpenAI-compatible endpoint) +# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai + +# ============================================================================= +# LLM PROVIDER (Ollama Cloud) +# ============================================================================= +# Cloud-hosted open models via Ollama's OpenAI-compatible endpoint. +# Get your key at: https://ollama.com/settings +# OLLAMA_API_KEY=your_ollama_key_here +# Optional base URL override (default: https://ollama.com/v1) +# OLLAMA_BASE_URL=https://ollama.com/v1 + +# ============================================================================= +# LLM PROVIDER (z.ai / GLM) +# ============================================================================= +# z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.) +# Get your key at: https://z.ai or https://open.bigmodel.cn +# GLM_API_KEY= +# GLM_BASE_URL=https://api.z.ai/api/paas/v4 # Override default base URL + +# ============================================================================= +# LLM PROVIDER (Kimi / Moonshot) +# ============================================================================= +# Kimi Code provides access to Moonshot AI coding models (kimi-k2.5, etc.) +# Get your key at: https://platform.kimi.ai (Kimi Code console) +# Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default. +# Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below. +# KIMI_API_KEY= +# KIMI_BASE_URL=https://api.kimi.com/coding/v1 # Default for sk-kimi- keys +# KIMI_BASE_URL=https://api.moonshot.ai/v1 # For legacy Moonshot keys +# KIMI_BASE_URL=https://api.moonshot.cn/v1 # For Moonshot China keys +# KIMI_CN_API_KEY= # Dedicated Moonshot China key + +# ============================================================================= +# LLM PROVIDER (Arcee AI) +# ============================================================================= +# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*) +# Get an Arcee key at: https://chat.arcee.ai/ +# ARCEEAI_API_KEY= +# ARCEE_BASE_URL= # Override default base URL + +# ============================================================================= +# LLM PROVIDER (MiniMax) +# ============================================================================= +# MiniMax provides access to MiniMax models (global endpoint) +# Get your key at: https://www.minimax.io +# MINIMAX_API_KEY= +# MINIMAX_BASE_URL=https://api.minimax.io/v1 # Override default base URL + +# MiniMax China endpoint (for users in mainland China) +# MINIMAX_CN_API_KEY= +# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1 # Override default base URL + +# ============================================================================= +# LLM PROVIDER (OpenCode Zen) +# ============================================================================= +# OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi) +# Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth +# OPENCODE_ZEN_API_KEY= +# OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1 # Override default base URL + +# ============================================================================= +# LLM PROVIDER (OpenCode Go) +# ============================================================================= +# OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5) +# $10/month subscription. Get your key at: https://opencode.ai/auth +# OPENCODE_GO_API_KEY= + +# ============================================================================= +# LLM PROVIDER (OpenCode Free) +# ============================================================================= +# OpenCode Free provides keyless free models (Ox Alpha / x-preview-f-free, +# big-pickle, etc.). NO env var and NO account needed — requests are sent +# anonymously (the free tier rejects any unrecognized Authorization header). +# Select it with `hermes model` or `/model free`. + +# ============================================================================= +# LLM PROVIDER (Hugging Face Inference Providers) +# ============================================================================= +# Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint. +# Free tier included ($0.10/month), no markup on provider rates. +# Get your token at: https://huggingface.co/settings/tokens +# Required permission: "Make calls to Inference Providers" +# HF_TOKEN= +# HF_BASE_URL=https://router.huggingface.co/v1 # Override default base URL +# OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1 # Override default base URL + +# DeepInfra — 100+ top open models, pay-per-use. +# Get your key at: https://deepinfra.com/dash/api_keys +# DEEPINFRA_API_KEY= + +# ============================================================================= +# LLM PROVIDER (Qwen OAuth) +# ============================================================================= +# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth). +# No API key needed — credentials come from ~/.qwen/oauth_creds.json. +# Optional base URL override: +# HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1 + +# ============================================================================= +# LLM PROVIDER (Xiaomi MiMo) +# ============================================================================= +# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash). +# Get your key at: https://platform.xiaomimimo.com +# XIAOMI_API_KEY=your_key_here +# Optional base URL override: +# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1 + +# ============================================================================= +# LLM PROVIDER (Upstage Solar) +# ============================================================================= +# Upstage provides access to Upstage Solar models. +# Get your key at: https://console.upstage.ai/api-keys +# UPSTAGE_API_KEY=your_key_here +# Optional base URL override: +# UPSTAGE_BASE_URL=https://api.upstage.ai/v1 + +# ============================================================================= +# LLM PROVIDER (Ramp Router) +# ============================================================================= +# Ramp Router (router.com) — Responses-native LLM gateway; model IDs come +# from your account's live catalog (GET /v1/models). +# Get your key at: https://app.router.com/keys +# RAMP_ROUTER_API_KEY=your_key_here +# Optional base URL override: +# RAMP_ROUTER_BASE_URL=https://api.router.com/v1 + +# ============================================================================= +# LLM PROVIDER (Nebius Token Factory) +# ============================================================================= +# Nebius Token Factory — OpenAI-compatible inference for open models. +# Get your key at: https://tokenfactory.nebius.com/ +# NEBIUS_API_KEY=your_key_here +# Optional base URL override: +# NEBIUS_BASE_URL=https://api.tokenfactory.nebius.com/v1 + +# ============================================================================= +# LLM PROVIDER (Tencent Hy — TokenHub & TokenPlan) +# ============================================================================= +# Tencent TokenHub (OpenAI-compatible): https://tokenhub.tencentmaas.com +# TOKENHUB_API_KEY=your_key_here +# TOKENHUB_BASE_URL=https://tokenhub.tencentmaas.com/v1 +# Tencent TokenPlan (Anthropic Messages endpoint via LKEAP): +# TOKENPLAN_API_KEY=your_key_here +# TOKENPLAN_BASE_URL=https://api.lkeap.cloud.tencent.com/plan/anthropic + +# ============================================================================= +# TOOL API KEYS +# ============================================================================= + +# Exa API Key - AI-native web search and contents +# Get at: https://exa.ai +# EXA_API_KEY= + +# Parallel API Key - AI-native web search and extract +# Get at: https://parallel.ai +# PARALLEL_API_KEY= + +# Firecrawl API Key - Web search, extract, and crawl +# Get at: https://firecrawl.dev/ +# FIRECRAWL_API_KEY= + + +# FAL.ai API Key - Image generation +# Get at: https://fal.ai/ +# FAL_KEY= + +# Honcho - Cross-session AI-native user modeling (optional) +# Builds a persistent understanding of the user across sessions and tools. +# Get at: https://app.honcho.dev +# Also requires ~/.honcho/config.json with enabled=true (see README). +# HONCHO_API_KEY= + +# ============================================================================= +# HYPERLIQUID OPTIONAL SKILL +# ============================================================================= +# Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid +# +# Hyperliquid API base URL override +# Default: https://api.hyperliquid.xyz +# HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz +# +# Default address for account-level commands like state, fills, orders, and review +# HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000 + +# ============================================================================= +# TERMINAL TOOL CONFIGURATION +# ============================================================================= +# Backend type: "local", "singularity", "docker", "modal", or "ssh" +# Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend). +# Use 'hermes setup' or 'hermes config set terminal.backend docker' to change. +# Supported: local, docker, singularity, modal, ssh +# +# Only override here if you need to force a backend without touching config.yaml: +# TERMINAL_ENV=local + +# Override the container runtime binary (e.g. to use Podman instead of Docker). +# Useful on systems where Docker's storage driver is broken or unavailable. +# HERMES_DOCKER_BINARY=/usr/local/bin/podman + +# Container images (for singularity/docker/modal backends) +# TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20 +# TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20 +TERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20 + + +# Working directory for terminal commands +# For local backend: "." means current directory (resolved automatically) +# For remote backends (ssh/docker/modal/singularity): use an absolute path +# INSIDE the target environment, or leave unset for the backend's default +# (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path. +# Usually managed by config.yaml (terminal.cwd) — uncomment to override +# TERMINAL_CWD=. + +# Default command timeout in seconds +TERMINAL_TIMEOUT=60 + +# Cleanup inactive environments after this many seconds +TERMINAL_LIFETIME_SECONDS=300 + +# ============================================================================= +# SSH REMOTE EXECUTION (for TERMINAL_ENV=ssh) +# ============================================================================= +# Run terminal commands on a remote server via SSH. +# Agent code stays on your machine, commands execute remotely. +# +# SECURITY BENEFITS: +# - Agent cannot read your .env file (API keys protected) +# - Agent cannot modify its own code +# - Remote server acts as isolated sandbox +# - Can safely configure passwordless sudo on remote +# +# TERMINAL_SSH_HOST=192.168.1.100 +# TERMINAL_SSH_USER=agent +# TERMINAL_SSH_PORT=22 +# TERMINAL_SSH_KEY=~/.ssh/id_rsa + +# ============================================================================= +# SUDO SUPPORT (works with ALL terminal backends) +# ============================================================================= +# If set, enables sudo commands by piping password via `sudo -S`. +# Works with: local, docker, singularity, modal, and ssh backends. +# +# SECURITY WARNING: Password stored in plaintext. Only use on trusted machines. +# +# ALTERNATIVES: +# - For SSH backend: Configure passwordless sudo on the remote server +# - For containers: Run as root inside the container (no sudo needed) +# - For local: Configure /etc/sudoers for specific commands +# - For CLI: Leave unset - you'll be prompted interactively with 45s timeout +# +# SUDO_PASSWORD=your_password_here + +# ============================================================================= +# MODAL CLOUD BACKEND (Optional - for TERMINAL_ENV=modal) +# ============================================================================= +# Modal uses CLI authentication, not environment variables. +# Run: pip install modal && modal setup +# This will authenticate via browser and store credentials locally. +# No API key needed in .env - Modal handles auth automatically. + +# ============================================================================= +# BROWSER TOOL CONFIGURATION (agent-browser + Browserbase) +# ============================================================================= +# Browser automation requires Browserbase cloud service for remote browser execution. +# This allows the agent to navigate websites, fill forms, and extract information. +# +# STEALTH MODES: +# - Basic Stealth: ALWAYS active (random fingerprints, auto CAPTCHA solving) +# - Advanced Stealth: Requires BROWSERBASE_ADVANCED_STEALTH=true (Scale Plan only) + +# Browserbase API Key - Cloud browser execution +# Get at: https://browserbase.com/ +# BROWSERBASE_API_KEY= + +# Browserbase Project ID - From your Browserbase dashboard +# BROWSERBASE_PROJECT_ID= + +# Enable residential proxies for better CAPTCHA solving (default: true) +# Routes traffic through residential IPs, significantly improves success rate +BROWSERBASE_PROXIES=true + +# Enable advanced stealth mode (default: false, requires Scale Plan) +# Uses custom Chromium build to avoid bot detection altogether +BROWSERBASE_ADVANCED_STEALTH=false + +# Local browser engine (default: auto = Chrome) +# "auto" — use Chrome +# "lightpanda" — use Lightpanda (faster navigation, no screenshots) +# "chrome" — explicitly request Chrome +# Browser Use mode (default) spawns `lightpanda serve` itself; the built-in +# browser tools pass --engine to agent-browser v0.25.3+ and retry failed or +# empty Lightpanda results with Chrome. Ignored while a cloud provider, +# Camofox or browser.cdp_url is active (`hermes doctor` reports that). +# Also configurable via browser.engine in config.yaml. +# AGENT_BROWSER_ENGINE=auto + +# Browser session timeout in seconds (default: 300) +# Sessions are cleaned up after this duration of inactivity +BROWSER_SESSION_TIMEOUT=300 + +# Browser inactivity timeout - auto-cleanup inactive sessions (default: 120 = 2 min) +# Browser sessions are automatically closed after this period of no activity +BROWSER_INACTIVITY_TIMEOUT=120 + +# Extra Chromium launch flags passed to agent-browser, comma- or newline-separated. +# Hermes auto-injects "--no-sandbox,--disable-dev-shm-usage" when it detects root +# or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark, +# many container images), so leave this unset unless you need extra flags. +# Setting this disables the auto-injection. +# AGENT_BROWSER_ARGS=--no-sandbox + +# Camofox local anti-detection browser (Camoufox-based Firefox). +# Set CAMOFOX_URL to route the browser tools through a local Camofox server +# instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md. +# CAMOFOX_URL=http://localhost:9377 + +# Externally managed Camofox sessions — when another app owns the visible +# Camofox browser, set these so Hermes shares the same userId/profile instead +# of creating its own isolated session. +# CAMOFOX_USER_ID= +# CAMOFOX_SESSION_KEY= +# Set to true to reuse an already-open Camofox tab for this identity before +# creating a new one (useful for gateway restarts). +# CAMOFOX_ADOPT_EXISTING_TAB=false + +# ============================================================================= +# SESSION LOGGING +# ============================================================================= +# Session trajectories are automatically saved to logs/ directory +# Format: logs/session_YYYYMMDD_HHMMSS_UUID.json +# Contains full conversation history in trajectory format for debugging/replay + +# ============================================================================= +# VOICE TRANSCRIPTION & OPENAI TTS +# ============================================================================= +# Required for voice message transcription (Whisper) and OpenAI TTS voices. +# Uses OpenAI's API directly (not via OpenRouter). +# Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter. +# Get at: https://platform.openai.com/api-keys +# VOICE_TOOLS_OPENAI_KEY= + +# ============================================================================= +# SLACK INTEGRATION +# ============================================================================= +# Slack Bot Token - From Slack App settings (OAuth & Permissions) +# Get at: https://api.slack.com/apps +# SLACK_BOT_TOKEN=xoxb-... + +# Slack App Token - For Socket Mode (App-Level Tokens in Slack App settings) +# SLACK_APP_TOKEN=xapp-... + +# Slack allowed users (comma-separated Slack user IDs) +# SLACK_ALLOWED_USERS= + +# ============================================================================= +# TELEGRAM INTEGRATION +# ============================================================================= +# Telegram Bot Token - From @BotFather (https://t.me/BotFather) +# TELEGRAM_BOT_TOKEN= +# TELEGRAM_ALLOWED_USERS= # Comma-separated user IDs +# TELEGRAM_HOME_CHANNEL= # Default chat for cron delivery +# TELEGRAM_HOME_CHANNEL_NAME= # Display name for home channel +# TELEGRAM_CRON_THREAD_ID= # Forum topic ID for cron deliveries; overrides TELEGRAM_HOME_CHANNEL_THREAD_ID for cron so replies work in topic mode + +# Webhook mode (optional — for cloud deployments like Fly.io/Railway) +# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode. +# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram +# TELEGRAM_WEBHOOK_PORT=8443 +# TELEGRAM_WEBHOOK_SECRET= # Recommended for production + +# WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair) +# WHATSAPP_ENABLED=false +# WHATSAPP_ALLOWED_USERS=15551234567 + +# Email (IMAP/SMTP — send and receive emails as Hermes) +# For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords +# EMAIL_ADDRESS=hermes@gmail.com +# EMAIL_PASSWORD=xxxx xxxx xxxx xxxx +# EMAIL_IMAP_HOST=imap.gmail.com +# EMAIL_IMAP_PORT=993 +# EMAIL_SMTP_HOST=smtp.gmail.com +# EMAIL_SMTP_PORT=587 +# EMAIL_POLL_INTERVAL=15 +# EMAIL_ALLOWED_USERS=your@email.com +# EMAIL_HOME_ADDRESS=your@email.com + +# Gateway-wide: allow ALL users without an allowlist (default: false = deny) +# Only set to true if you intentionally want open access. +# GATEWAY_ALLOW_ALL_USERS=false + +# ============================================================================= +# RESPONSE PACING +# ============================================================================= +# Human-like delays between message chunks on messaging platforms. +# Makes the bot feel less robotic. +# HERMES_HUMAN_DELAY_MODE=off # off | natural | custom +# HERMES_HUMAN_DELAY_MIN_MS=800 # Min delay in ms (custom mode) +# HERMES_HUMAN_DELAY_MAX_MS=2500 # Max delay in ms (custom mode) + +# ============================================================================= +# DEBUG OPTIONS +# ============================================================================= +WEB_TOOLS_DEBUG=false +VISION_TOOLS_DEBUG=false +MOA_TOOLS_DEBUG=false +IMAGE_TOOLS_DEBUG=false + +# ============================================================================= +# CONTEXT COMPRESSION (Auto-shrinks long conversations) +# ============================================================================= +# When conversation approaches model's context limit, middle turns are +# automatically summarized to free up space. +# +# Context compression is configured in ~/.hermes/config.yaml under compression: +# CONTEXT_COMPRESSION_ENABLED=true # Enable auto-compression (default: true) +# CONTEXT_COMPRESSION_THRESHOLD=0.85 # Compress at 85% of context limit +# Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview) + +# ============================================================================= +# SKILLS HUB (GitHub integration for skill search/install/publish) +# ============================================================================= + +# GitHub Personal Access Token — for higher API rate limits on skill search/install +# Get at: https://github.com/settings/tokens (Fine-grained recommended) +# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx + +# GitHub App credentials (optional — for bot identity on PRs) +# GITHUB_APP_ID= +# GITHUB_APP_PRIVATE_KEY_PATH= +# GITHUB_APP_INSTALLATION_ID= + +# Groq API key (free tier — used for Whisper STT in voice mode) +# GROQ_API_KEY= + +# ElevenLabs API key (cloud STT/TTS — Scribe transcription) +# ELEVENLABS_API_KEY= + +# ============================================================================= +# STT PROVIDER SELECTION +# ============================================================================= +# Default STT provider is "local" (faster-whisper) — runs on your machine, no API key needed. +# Install with: pip install faster-whisper +# Model downloads automatically on first use (~150 MB for "base"). +# To use cloud providers instead, set GROQ_API_KEY, VOICE_TOOLS_OPENAI_KEY, or ELEVENLABS_API_KEY above. +# Provider priority: local > groq > openai > mistral > xai > elevenlabs +# Configure in config.yaml: stt.provider: local | groq | openai | mistral | xai | elevenlabs + +# ============================================================================= +# STT ADVANCED OVERRIDES (optional) +# ============================================================================= +# Override default STT models per provider (normally set via stt.model in config.yaml) +# STT_GROQ_MODEL=whisper-large-v3-turbo +# STT_OPENAI_MODEL=whisper-1 +# STT_ELEVENLABS_MODEL=scribe_v2 + +# Override STT provider endpoints (for proxies or self-hosted instances) +# GROQ_BASE_URL=https://api.groq.com/openai/v1 +# STT_OPENAI_BASE_URL=https://api.openai.com/v1 +# ELEVENLABS_STT_BASE_URL=https://api.elevenlabs.io/v1 + +# ============================================================================= +# MICROSOFT TEAMS INTEGRATION +# ============================================================================= +# Register a Bot in Azure: https://dev.botframework.com/ → "Register a bot" +# Or use Azure Portal: Azure Active Directory → App registrations → New registration +# Then add the bot to Teams via the Bot Framework or App Studio. +# +# TEAMS_CLIENT_ID= # Azure AD App (client) ID +# TEAMS_CLIENT_SECRET= # Azure AD client secret value +# TEAMS_TENANT_ID= # Azure AD tenant ID (or "common" for multi-tenant) +# TEAMS_ALLOWED_USERS= # Comma-separated AAD object IDs or UPNs +# TEAMS_ALLOW_ALL_USERS=false # Set true to skip the allowlist +# TEAMS_HOME_CHANNEL= # Default channel/chat ID for cron delivery +# TEAMS_HOME_CHANNEL_NAME= # Display name for the home channel +# TEAMS_PORT=3978 # Webhook listen port (Bot Framework default) + +# ============================================================================= +# GOOGLE CHAT INTEGRATION +# ============================================================================= +# Connects via Cloud Pub/Sub pull subscription (no public URL required). +# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md. +# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub. +# 2. Create a Service Account with roles/pubsub.subscriber on the +# subscription (NOT project-wide); download the JSON key. +# 3. Configure your Chat app at console.cloud.google.com/apis/credentials +# → Google Chat API → Configuration → Cloud Pub/Sub topic. +# 4. (Optional, for native attachment delivery) Each user runs +# `/setup-files` once in their own DM after Pub/Sub is wired up. +# +# GOOGLE_CHAT_PROJECT_ID= # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT) +# GOOGLE_CHAT_SUBSCRIPTION_NAME= # Full path: projects//subscriptions/ +# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON= # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS) +# GOOGLE_CHAT_ALLOWED_USERS= # Comma-separated emails allowed to talk to the bot +# GOOGLE_CHAT_ALLOW_ALL_USERS=false # Set true to skip the allowlist +# GOOGLE_CHAT_HOME_CHANNEL= # Default space (spaces/XXXX) for cron delivery +# GOOGLE_CHAT_HOME_CHANNEL_NAME= # Display name for the home channel + +# ============================================================================= +# reddit-reading skill (optional) — app-only credentials, NOT a user login +# ============================================================================= +# The skill works with no credentials via Reddit's public feeds (~1 request/minute). +# For faster access with scores and nested comments, register a free "script" app +# at https://www.reddit.com/prefs/apps and paste its id and secret here. +# REDDIT_CLIENT_ID= +# REDDIT_CLIENT_SECRET= diff --git a/.gitattributes b/.gitattributes index a6344aac8c09253b3b630fb776ae94478aa0275b..80824c67581d7be781d3f457280f7f1dbbd22897 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,35 +1,34 @@ -*.7z filter=lfs diff=lfs merge=lfs -text -*.arrow filter=lfs diff=lfs merge=lfs -text -*.bin filter=lfs diff=lfs merge=lfs -text -*.bz2 filter=lfs diff=lfs merge=lfs -text -*.ckpt filter=lfs diff=lfs merge=lfs -text -*.ftz filter=lfs diff=lfs merge=lfs -text -*.gz filter=lfs diff=lfs merge=lfs -text -*.h5 filter=lfs diff=lfs merge=lfs -text -*.joblib filter=lfs diff=lfs merge=lfs -text -*.lfs.* filter=lfs diff=lfs merge=lfs -text -*.mlmodel filter=lfs diff=lfs merge=lfs -text -*.model filter=lfs diff=lfs merge=lfs -text -*.msgpack filter=lfs diff=lfs merge=lfs -text -*.npy filter=lfs diff=lfs merge=lfs -text -*.npz filter=lfs diff=lfs merge=lfs -text -*.onnx filter=lfs diff=lfs merge=lfs -text -*.ot filter=lfs diff=lfs merge=lfs -text -*.parquet filter=lfs diff=lfs merge=lfs -text -*.pb filter=lfs diff=lfs merge=lfs -text -*.pickle filter=lfs diff=lfs merge=lfs -text -*.pkl filter=lfs diff=lfs merge=lfs -text -*.pt filter=lfs diff=lfs merge=lfs -text -*.pth filter=lfs diff=lfs merge=lfs -text -*.rar filter=lfs diff=lfs merge=lfs -text -*.safetensors filter=lfs diff=lfs merge=lfs -text -saved_model/**/* filter=lfs diff=lfs merge=lfs -text -*.tar.* filter=lfs diff=lfs merge=lfs -text -*.tar filter=lfs diff=lfs merge=lfs -text -*.tflite filter=lfs diff=lfs merge=lfs -text -*.tgz filter=lfs diff=lfs merge=lfs -text -*.wasm filter=lfs diff=lfs merge=lfs -text -*.xz filter=lfs diff=lfs merge=lfs -text -*.zip filter=lfs diff=lfs merge=lfs -text -*.zst filter=lfs diff=lfs merge=lfs -text -*tfevents* filter=lfs diff=lfs merge=lfs -text +# Auto-generated files — collapse diffs and exclude from language stats +web/package-lock.json linguist-generated=true + +# Enforce LF for scripts that run inside Linux containers. +# Without this, Windows checkout converts to CRLF and breaks `exec` in the +# container entrypoint with "no such file or directory". +*.sh text eol=lf +Dockerfile text eol=lf +*.dockerfile text eol=lf +docker/entrypoint.sh text eol=lf + +# Enforce LF for all source/text files. Windows editors and tools default to +# CRLF; without normalization a Windows contributor's edit turns into a +# whole-file phantom diff (every line "changed" by its ending), breaks +# string-match patch tooling, and pollutes review. `text` normalizes to LF +# at check-in; `eol=lf` also checks out as LF so the working tree matches +# the index on every platform. PowerShell files are the deliberate +# exception (PS 5.1 tooling expects CRLF). +*.py text eol=lf +*.ts text eol=lf +*.tsx text eol=lf +*.js text eol=lf +*.mjs text eol=lf +*.cjs text eol=lf +*.jsx text eol=lf +*.json text eol=lf +*.yaml text eol=lf +*.yml text eol=lf +*.toml text eol=lf +*.md text eol=lf +*.css text eol=lf +*.html text eol=lf +*.svg text eol=lf +*.ps1 text eol=crlf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..53c8faa1abaddf4d4b64e9b66917abe106c36ec8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,280 @@ +.DS_Store +/venv/ +/venv.old/ +/venv.stale.runtime-*/ +/bin/ +/.hermes-runtime/ +/_pycache/ +*.pyc* +__pycache__/ +act/ +.act-sandbox-agent.* +.venv/ +.venv +.vscode/ +.env +.op.env +.env.local +.env.development.local +.env.test.local +.env.production.local +.env.development +.env.test +.hermes-docker/ +.notebooklm-home/ +.notebooklm-cli-venv/ +.notebooklm-playwright/ +.pip-cache/ +.uv-cache/ +compose.hermes.local.yml +export* +__pycache__/model_tools.cpython-310.pyc +__pycache__/web_tools.cpython-310.pyc +logs/ +data/ +# Bundled community plugin index seed (shipped as package data) — the bare +# `data/` pattern above would otherwise swallow it. +!hermes_cli/data/ +.pytest_cache/ +test_durations.json +.pytest-cache/ +tmp/ +temp_vision_images/ +hermes-*/* +examples/ +tests/quick_test_dataset.jsonl +tests/sample_dataset.jsonl +run_datagen_kimik2-thinking.sh +run_datagen_megascience_glm4-6.sh +run_datagen_sonnet.sh +source-data/* +run_datagen_megascience_glm4-6.sh +data/* +MagicMock/ +# No trailing slash: also matches node_modules SYMLINKS (worktrees often +# symlink node_modules to the main checkout; the dir-only pattern let one +# slip into a commit and break `npm ci` on CI with ENOTDIR). +node_modules +browser-use/ +agent-browser/ +# Private keys +*.ppk +*.pem +privvy* +images/ +__pycache__/ +hermes_agent.egg-info/ +wandb/ +testlogs +playwright-report/ +test-results/ +# Playwright visual regression baselines — cached from main in CI, not committed +*-snapshots/ + +# CLI config (may contain sensitive SSH paths) +cli-config.yaml + +# Skills Hub state (lives in ~/.hermes/skills/.hub/ at runtime, but just in case) +skills/.hub/ +ignored/ +.worktrees/ +environments/benchmarks/evals/ + +# Web UI build output +hermes_cli/web_dist/ +# Cross-process web UI build lock (flock target, always empty) +.web_ui_build.lock +apps/desktop/build/ +apps/desktop/dist/ + +# tsc-emitted artifacts (a stray `tsc -b` compiles into src/, and vite then +# resolves the stale .js OVER the .tsx — never track these) +apps/desktop/src/**/*.js +apps/desktop/src/**/*.js.map +apps/desktop/src/**/*.d.ts +# EXCEPT bundled plain-ESM plugin entries (adopted SDK-consumer plugins, +# e.g. hermes-bots): plugin.js IS the source, not tsc output. No .tsx +# sibling exists, so the stale-shadow hazard above cannot apply. +!apps/desktop/src/plugins/*/plugin.js +!apps/desktop/src/global.d.ts +!apps/desktop/src/vite-env.d.ts + +# Build/debug artifacts that must never be committed +/log.txt +/sqlite_leak_fix.png +/*.png.bak +*.tar.gz +*.tgz +apps/shared/src/**/*.js +apps/shared/src/**/*.js.map +apps/shared/src/**/*.d.ts +apps/desktop/release/ +# stage-and-swap Desktop rebuild output (#86443); removed after the swap, but +# a killed build must not leave the checkout dirty +apps/desktop/.staging-*/ +*.tsbuildinfo + +# Web UI assets — synced from @nous-research/ui at build time via +# `npm run sync-assets` (see web/package.json). +web/public/fonts/ +web/public/ds-assets/ + +# Release script temp files +.release_notes.md +mini-swe-agent/ + +# Nix +.direnv/ +.nix-stamps/ +result +website/static/api/skills-index.json +# skills.json + skills-meta.json are build artifacts emitted by +# website/scripts/extract-skills.py during prebuild — keep them out of +# git for the same reason as skills-index.json (large, generated, change +# every build). +website/static/api/skills.json +website/static/api/skills-meta.json +# plugins.json + plugins-meta.json are build artifacts emitted by +# website/scripts/extract-plugins.py during prebuild (Plugin Catalog page). +website/static/api/plugins.json +website/static/api/plugin-stars.json +website/static/api/plugin-catalog.json +website/static/api/plugins-meta.json +# automation-blueprints-index.json is a build artifact emitted by +# website/scripts/extract-automation-blueprints.py during prebuild. +website/static/api/automation-blueprints-index.json +models-dev-upstream/ + +# Local editor / agent tooling (machine-specific; keep in global config, not the repo) +.codex/ +.cursor/ +.gemini/ +.zed/ +.mcp.json +opencode.json +config/mcporter.json + +hermes_cli/tui_dist/* +hermes_cli/scripts/ +docs/superpowers/* +# Working directory for the Hermes Agent's session state (~/.hermes/ at runtime; +# also created in-repo when an agent operates in this checkout). Plans, audit +# logs, and per-session caches are never artifacts of the codebase. +.hermes/ + +# Desktop/bootstrap install marker written into the managed checkout root by the +# bootstrap installer. It is Hermes-managed runtime state, never a code change — +# ignore it so `hermes update`'s `git stash push --include-untracked` does not +# treat it as a local edit and autostash it on every run (#38529). +.hermes-bootstrap-complete + +# Flat-install runtime state (checkout root == $HERMES_HOME, e.g. installs made +# with HERMES_INSTALL_DIR=$HERMES_HOME or by older installers): every root-level +# SQLite store (state.db, kanban.db, response_store.db, ...) with its +# WAL/SHM/journal sidecars and retired-WAL capture dirs, the legacy transcripts, +# the cron job store (jobs.json) and executions ledger, gateway lock/pid/state +# files, cache/spill directories, and the profile's own config/credential/ +# memory/profile/pairing roots are Hermes-managed runtime state, never code +# changes. (`*-snapshots/` above already covers state-snapshots/.) +# Ignore them so `hermes update`'s `git stash push --include-untracked` cannot +# sweep the live state.db/-wal into the stash and unlink it under the running +# gateway (#110648). Nested installs keep all of this under $HERMES_HOME outside +# the checkout, where the `.hermes/` rule above already applies. +/*.db +/*.db-wal +/*.db-shm +/*.db-journal +/*.db.retired-wal-*/ +/gateway/discord_message_recovery.db* +/sessions/ +/browser-profile/ +/cron/executions.db* +/cron/jobs.json +/cron.pid +/gateway.lock +/gateway.pid +/gateway_state.json +/processes.json +/hook_outputs/ +/hooks/ +/cache/ +/checkpoints/ +/pending_messages/ +/plugin-data/ +/kanban/ +/config.yaml +/auth.json +/auth.lock +/auth/ +/.anthropic_oauth.json +/google_token.json +/google_oauth_pending.json +/webhook_subscriptions.json +/channel_directory.json +/channel_aliases.json +/feishu_comment_pairing.json +/memories/ +/profiles/ +/credentials/ +/mcp-tokens/ +/pairing/ +/platforms/ + +# Persistent dev sandbox dir (scripts/dev-sandbox.sh --persistent) +.hermes-sandbox/ +# Sandbox dirs used by the install/update E2E (tests/install/). The suffix is +# the route name, so each route gets its own tree and two can run at once. +.hermes-sandbox-e2e*/ + +# Interrupted-update breadcrumb + recovery lock written next to the shared venv +# by `hermes update` / launch-time self-heal. Runtime state, never a code change +# — ignore so `git status` stays clean and update's autostash skips them. +.update-incomplete +.update-incomplete.lock + +# Checkout fingerprint the __pycache__ tree was last validated against +# (launch-time stale-bytecode sweep). Runtime state, never a code change. +.bytecode-fingerprint +.bytecode-fingerprint.tmp + +# Installer-written method stamp in the managed checkout root (scripts/install.sh). +# Runtime metadata only — never a code change. Ignore so `git status` stays clean +# and `hermes update`'s untracked autostash does not treat it as a local edit (#66189 / #54855). +/.install_method + +# Tool Search live-test harness output — non-deterministic model transcripts, +# regenerated by evals/tool_search/tool_search_livetest*.py. Never an artifact of the repo. +evals/tool_search/out*/ + +# Per-release changelog drafts. These exist only transiently during a release +# cut (passed to `gh release create --notes-file`); the GitHub Release itself +# stores the published notes. They are not a build artifact and must never be +# committed to the repo root. See the hermes-release skill. +RELEASE_v*.md + +# Desktop demo-run scratch output (hermes writes demo/*.txt during recorded +# walkthroughs). Throwaway artifacts, never part of the app. +apps/desktop/demo/ + +# PR infographics are rendered locally and embedded in PR descriptions via the +# image-provider (fal.media) URL — they are NEVER committed to the repo. The +# PR body is the archive. See the hermes-agent-dev skill's +# pr-infographic-workflow reference (storage rule + lapse #8 / #COMMIT-1). +# +# Spelling variants are listed because a single `infographic/` pattern was +# sidestepped by an `infograficos/` directory (#70552). .gitignore is only +# the first line of defence and cannot stop `git add -f` at all — the +# infographic-check CI job is what actually enforces this. +infographic/ +infographics/ +infograficos/ +infografico/ +native/fts5_cjk/*.so +# Runtime marker written by hermes update when a lazy dependency refresh is +# interrupted; consumed by launch-time recovery. Never commit it (was tracked +# by accident via 3a69e34702, removed in the #72002 salvage). +.lazy-refresh-incomplete +.skills_prompt_snapshot.json + +# Disposable profile created by scripts/probe_active_session_exclusivity.py +.probe-home/ diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000000000000000000000000000000000000..5af0a658645a441fe111697af5a28972b39cbee9 --- /dev/null +++ b/.mailmap @@ -0,0 +1,109 @@ +# .mailmap — canonical author mapping for git shortlog / git log / GitHub +# Format: Canonical Name +# See: https://git-scm.com/docs/gitmailmap +# +# This maps commit emails to GitHub noreply addresses so that: +# 1. `git shortlog -sn` shows deduplicated contributor counts +# 2. GitHub's contributor graph can attribute commits correctly +# 3. Contributors with personal/work emails get proper credit +# +# When adding entries: use the contributor's GitHub noreply email as canonical +# so GitHub can link commits to their profile. + +# === Teknium (multiple emails) === +Teknium <127238744+teknium1@users.noreply.github.com> +Teknium <127238744+teknium1@users.noreply.github.com> + +# === Contributors — personal/work emails mapped to GitHub noreply === +# Format: Canonical Name + +# Verified via GH API email search +kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com> +luyao618 <364939526@qq.com> <364939526@qq.com> +ethernet8023 +nicoloboschi +cherifya +BongSuCHOI +dsocolobsky +pefontana +Helmi +hata1234 + +# Verified via PR investigation / salvage PR bodies +DeployFaith +flobo3 +gaixianggeng +KUSH42 +konsisumer +WorldInnovationsDepartment +m0n5t3r +sprmn24 +fancydirty +fxfitz +limars874 +AaronWong1999 +dippwho +duerzy +geoffwellman +hcshen0111 +jamesarch +stephenschoettler +Tranquil-Flow +Dusk1e +Awsh1 +WAXLYY +donrhmexe +hqhq1025 <1506751656@qq.com> <1506751656@qq.com> +BlackishGreen33 +tomqiaozc +MagicRay1217 +aaronagent <1115117931@qq.com> <1115117931@qq.com> +YoungYang963 +LongOddCode +Cafexss +Cygra +DomGrieco + +# Duplicate email mapping (same person, multiple emails) +Sertug17 <104278804+Sertug17@users.noreply.github.com> +yyovil +DomGrieco +dsocolobsky +olafthiele + +# Verified via git display name matching GH contributor username +cokemine +dalianmao000 +emozilla +jjovalle99 +kagura-agent +spniyant +olafthiele +r266-tech +xingkongliang +win4r +zhouboli +yongtenglei + +# Nous Research team +benbarclay +yoniebans + +# GH contributor list verified +spideystreet +dorukardahan +MustafaKara7 +Hmbown +kamil-gwozdz +kira-ariaki +knopki +Unayung +SeeYangZhi +Julientalbot +lesterli +JiayuuWang +tesseracttars-creator +xinbenlv +SaulJWu +angelos +MestreY0d4-Uninter <241404605+MestreY0d4-Uninter@users.noreply.github.com> diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000000000000000000000000000000000000..0e252084614feed7011cf11ee55865891e6416cd --- /dev/null +++ b/.npmrc @@ -0,0 +1,63 @@ +# needed to prevent bad npm that has min-release-age but not exclude +engine-strict=true + +min-release-age=14 +# allow assistant-ui packages & a couple specific deps since they update a LOT. +# remove this when we stabilize (or we haven't updated in 2 wks) +min-release-age-exclude[]=@assistant-ui/* +min-release-age-exclude[]=assistant-cloud +min-release-age-exclude[]=assistant-stream +min-release-age-exclude[]=@radix-ui/* +min-release-age-exclude[]=radix-ui +min-release-age-exclude[]=safe-content-frame + +# react-router 8.3.0 includes fixes for vulns. remove this when 8.3.0 is > 2wks old. +min-release-age-exclude[]=react-router + +# eslint 10.8.0 includes fixes for vulns. remove this when 10.8.0 is > 2wks old. +min-release-age-exclude[]=eslint +min-release-age-exclude[]=@eslint/* + +# tar 7.5.21 includes fixes for vulns. remove this when 7.5.21 is > 2wks old +min-release-age-exclude[]=tar + +# concurrently 10.0.4 includes fixes for vulns. remove this when 10.0.4 is > 2wks old +min-release-age-exclude[]=concurrently + +# fast-uri 3.1.4 includes fixes for vulns. remove this when 3.1.4 is > 2wks old +min-release-age-exclude[]=fast-uri + +# minimatch 10.2.6 includes fixes for vulns. remove this when 10.2.6 is > 2wks old +min-release-age-exclude[]=minimatch + + +# brace-expansion 5.0.9 includes fixes for vulns. remove this when 5.0.9 is > 2wks old +min-release-age-exclude[]=brace-expansion + +# js-yaml 4.3.1 includes fixes for GHSA-5p4m-2wfm-xmqj. remove when > 2wks old (rel 2026-07-31) +min-release-age-exclude[]=js-yaml + +# nanoid 3.3.17 includes fixes for GHSA-2v37-7h3g-55p8. remove when > 2wks old (rel 2026-08-03) +min-release-age-exclude[]=nanoid + +# mermaid 11.16.1 includes fixes for 5 GHSAs. remove when > 2wks old (rel 2026-08-04) +min-release-age-exclude[]=mermaid + +# dompurify 3.4.13 includes fixes for GHSA-55q2-fjhq-7xh7. remove when > 2wks old (rel 2026-08-03) +min-release-age-exclude[]=dompurify + +# vite 8.2.0 is the first release depending on rolldown >= 1.2.1, which fixes +# a rolldown panic that breaks `npm run build` in apps/desktop +# (rolldown/rolldown#10337 — a regression in 1.1.5, the version vite 8.1.5 +# pins as ~1.1.5). @oxc-project/types is here because rolldown 1.2.1 pins it +# as `=0.142.0` — an exact pin, so no older release satisfies it and the age +# gate would fail the whole install with ETARGET. +# remove these once vite 8.2.0 is > 2wks old. +min-release-age-exclude[]=vite +min-release-age-exclude[]=rolldown +min-release-age-exclude[]=@rolldown/* +min-release-age-exclude[]=@oxc-project/types + +# ink needs +min-release-age-exclude[]=lightningcss +min-release-age-exclude[]=postcss diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000000000000000000000000000000000000..6f4247a6255c99f420d1df558d68745592862ff7 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +26 diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000000000000000000000000000000000000..ca429279c2f0fa5dc8889427ba547f7be0222815 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,4 @@ +# Lockfiles must never be reformatted — main has a repo rule requiring +# team approval when lockfiles change, so an autofix PR touching one +# would hang waiting for review. +package-lock.json diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000000000000000000000000000000000000..12ec3ed7db1be6365793d53b49038956571b673b --- /dev/null +++ b/.prettierrc @@ -0,0 +1,11 @@ +{ + "arrowParens": "avoid", + "bracketSpacing": true, + "endOfLine": "auto", + "printWidth": 120, + "semi": false, + "singleQuote": true, + "tabWidth": 2, + "trailingComma": "none", + "useTabs": false +} diff --git a/.python-version b/.python-version new file mode 100644 index 0000000000000000000000000000000000000000..2c0733315e415bfb5e5b353f9996ecd964d395b2 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.11 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000000000000000000000000000000000..b8db958cd9e605d217587eb01806fc539e39be38 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,432 @@ +# Hermes Agent - Development Guide + +Instructions for AI coding assistants and developers working on the hermes-agent codebase. +This root file holds only what applies everywhere. Each area has its own `AGENTS.md` (aim for +~8k chars; `agent/subdirectory_hints.py` delivers up to 32k and truncates head/tail with a warning +past that); see the **routing table** at the end and read the area file before editing in that area. + +**Never give up on the right solution.** + +## What Hermes Is + +Hermes is a personal AI agent that runs the same agent core across a CLI, a messaging +gateway (Telegram, Discord, Slack, ~20 platforms), a TUI, and an Electron desktop app. It +learns across sessions (memory + skills), delegates to subagents, runs scheduled jobs, and +drives a real terminal and browser. It is extended primarily through **plugins and skills**, +not by growing the core. + +Two invariants shape almost every design decision and are the lens for reviewing any change: + +- **Per-conversation prompt caching is sacred.** A long-lived conversation reuses a cached + prefix every turn. Anything that mutates past context, swaps toolsets, reloads memories, or + rebuilds the system prompt mid-conversation invalidates that cache and multiplies the user's + cost. We do not do it; the ONE exception is context compression. Slash commands that mutate + system-prompt state (skills, tools, memory) must be **cache-aware**: default to deferred + invalidation (takes effect next session) with an opt-in `--now` flag (`/skills install --now` + is the canonical pattern). +- **The core is a narrow waist; capability lives at the edges.** Every model tool is sent on + every API call, so the bar for a new *core* tool is high. New capability should arrive as a + CLI command + skill, a service-gated tool, or a plugin — not as core surface. + +## Contribution Rubric — What We Want / What We Don't + +The project's intent layer. It serves humans aiming a contribution AND the automated triage +sweeper, which may only close on `implemented_on_main`, `cannot_reproduce`, or `incoherent`. +Taste-based "out of scope" closes are a human maintainer's call; the sweeper's job is to +recognize design intent and *avoid wrongly closing a legitimate contribution*. + +Read the balance right: Hermes ships a **lot**. Most merges are bug fixes to reported +behavior, and the product surface (platforms, providers, models, desktop/TUI features) +expands aggressively on purpose. The restraint below targets the **core agent + model tool +schema**, the one place where every addition is paid for on every API call. "Smallest +footprint" governs *how a capability is wired into the core*, not whether the product may +grow: expansive at the edges, conservative at the waist. + +### What we want + +- **Fix real bugs, well.** Reproduce the symptom on current `main`, point to the exact line + where it manifests, and fix the whole bug class — sibling call paths included. +- **Expand reach at the edges.** New adapters, channels, providers, models, desktop/TUI/ + dashboard features land routinely, including large ones — as long as they integrate with + the existing setup/config UX (`hermes tools`, `hermes setup`, auto-install) rather than + bolting on a raw env var. +- **Refactor god-files into clean modules.** Huge mechanical `+N/-N` extraction PRs are + wanted work. "Every line traces to the request" applies to *feature* PRs; a declared + refactor's request IS the extraction. +- **Keep the core narrow.** Prefer, in order: extend existing code → CLI command + skill → + service-gated tool (`check_fn`) → plugin → MCP server in the catalog → new core tool (last + resort). See the Footprint Ladder. +- **Extend, don't duplicate.** Check whether existing infrastructure covers the use case + before adding a module/manager/hook. When 3+ open PRs integrate the same *category* + (memory backends, providers, notifiers), design an ABC + orchestrator, wrap the existing + built-in as the first provider, and turn the competing PRs into plugins against it. +- **Behavior contracts over snapshots.** Tests assert how two pieces of data relate, never + freeze a current value (see Testing). +- **E2E validation, not just green unit mocks.** Anything touching resolution chains, config + propagation, security boundaries, remote backends, or file/network I/O must exercise the + real path with real imports against a temp `HERMES_HOME`. Mocks hide integration bugs. +- **Cache-, alternation-, and invariant-safe.** Preserve prompt caching, strict role + alternation (never two same-role messages in a row; never a synthetic user message injected + mid-loop), and a system prompt byte-stable for the life of a conversation. +- **Contributor credit preserved.** Salvage external work by cherry-picking (rebase-merge) so + authorship survives; build on top rather than reimplementing. + +### What we don't want (rejected even when well-built) + +- **Speculative infrastructure.** Hooks/callbacks/extension points with no concrete consumer. + Adding a hook is easy; removing one after plugins depend on it is hard. A hook with a real, + stated use case is NOT speculative even if the consumer ships separately. +- **New `HERMES_*` env vars for non-secret config.** `.env` is for secrets only. Behavioral + settings (timeouts, thresholds, flags, display prefs) go in `config.yaml`; bridge to an + internal env var in code if the mechanism needs one. Reject "set X in your .env" docs + unless X is a credential. +- **A new core tool when terminal + file (or a skill) already do the job.** If the only + barrier is file visibility on a remote backend, fix the mount, not the toolset. +- **Lazy-reading escape hatches on instructional tools.** No `offset`/`limit` pagination on + tools that load content the agent must read fully (skills, prompts, playbooks) — models + read page 1 and skip the rest. +- **"Fixes" that destroy the feature they secure.** Read the original intent + (`git log -p -S`) before restricting behavior; find a fix that preserves the feature. +- **Outbound telemetry / usage attribution without opt-in gating.** No analytics, + third-party identifier tagging, or attribution tags until a generic user-facing opt-in + (config gate + setup prompt + `hermes tools` toggle) exists. Park behind a label. +- **Change-detector tests, cache-breaking mid-conversation, dead code wired in without E2E + proof, plugins that touch core files.** Plugins work within the ABCs/hooks we provide; if + one needs more, widen the generic plugin surface, never special-case it in core. +- **Third-party products integrated into the core tree.** Observability backends, vendor + SaaS connectors, analytics dashboards, and other "someone else's product" plugins do NOT + land under `plugins/` — every one becomes our burden against a fast-moving core for a + backend we don't own. Ship as a **standalone plugin repo** (`~/.hermes/plugins/` or pip + entry point), promoted in the Nous Research Discord `#plugins-skills-and-skins`. This is a + coupling decision, not a quality bar; such PRs are closed with a pointer to publish. + +### Before you call it a bug — verify the premise (and when NOT to close) + +The most common reason a well-written PR is closed is a **wrong premise** or treating an +**intentional design as a gap**. These patterns tell a reviewer what to scrutinize and tell +the sweeper when a PR is NOT safe to close (when in doubt, leave it open for a human): + +- **"Intentional design, not a gap."** Ask whether the isolation IS the design. Profiles are + independent islands on purpose: a PR adding live config inheritance from the default + profile was closed because coupling profiles is exactly what the design prevents (`--clone` + already covers "start from my default"). Read `git log -p -S ""` before assuming + something is unfinished. +- **"The premise doesn't hold against how X actually works."** Trace the real runtime before + accepting a rationale. Real closes: a rate-limit "re-probe during cooldown" PR (the breaker + trips only on a *confirmed-empty* bucket, so re-probing hammers a bucket proven empty); a + usage fix whose new branch **never executes** because an earlier guard already popped the + state. If you can't point to the exact line where the bug manifests AND show the fix changes + that line's behavior, the premise is unverified. +- **"The absence was deliberate."** Restoring "missing" `__init__.py` files made a test tree + importable as a dotted package that shadowed the real plugin and deleted its `register()` + at import time. The omission was load-bearing. +- **"Overreached / resurrected an approach we moved past."** Scope creep beyond the agreed + base, or reviving a direction maintainers closed, is rejected even when it works. Offer the + rest as a focused follow-up. + +Throughline: **verify the claim AND the intent against the codebase before writing or merging +a fix.** A reproduction on current `main` plus a line-level account beats a plausible +rationale. When unsure about intent, asking is cheaper than shipping a fix that fights the +design. + +### The Footprint Ladder (new capability decision) + +Choose the highest (least-footprint) rung that correctly solves the problem: + +1. **Extend existing code** — a variation of something that exists. Zero new surface. +2. **CLI command + skill** — config/state/infra expressible as shell commands; the agent runs + `hermes ` guided by a skill. Default for subscriptions, scheduled tasks, + service setup (`hermes webhook`, `hermes cron`, `hermes tools`). +3. **Service-gated tool (`check_fn`)** — needs structured params/returns AND only appears when + a prerequisite is configured (Home Assistant tools, memory-provider tools). This rung gates + reachability/opt-in process-wide; a capability that varies per SESSION (who is watching) is + a named toolset folded in by the toolset resolver, not a `check_fn` — see "Surface capability + is a property of the SESSION" below. +4. **Plugin** — third-party/niche/user-specific; lives in `~/.hermes/plugins/` or a pip + package, discovered at runtime. +5. **MCP server (in the catalog)** — genuinely a tool but not core-fundamental. Zero permanent + core-schema footprint, reusable by any MCP host, reached via the built-in MCP client. +6. **New core tool** — only when fundamental, broadly useful to nearly every user, and + unreachable via terminal + file or an MCP server (terminal, read_file, web_search, + browser_navigate). + +### Surface capability is a property of the SESSION, never of the process env + +A tool that works only because of *who is on the other end* (desktop panes, in-app browser, +message reactions, Projects) must resolve availability from the **session's own source**, not +from an env var on the backend. Client and backend are separate machines: the desktop app may +drive a locally spawned backend, one over SSH, one behind URL + token, or Hermes Cloud, and +only the first two carry `HERMES_DESKTOP=1`. An env-keyed gate is a silent no-op on the other +topologies — the tool is stripped from the schema while the platform hint tells the model it +is "inside the Hermes desktop app". The pattern: + +- **The toolset is the surface gate.** Keep such tools off `_HERMES_CORE_TOOLS` and in a named + toolset (`desktop_ui`, `project`); the GUI gateway's `_load_enabled_toolsets(platform)` + folds it in when the session's platform says GUI. One resolver, every topology. +- **`check_fn` answers reachability or opt-in, not surface.** "Is the bridge wired?" — fine. + "Was I spawned by Electron?" — not. `check_fn` results are TTL-cached process-wide + (`tools/registry.py`); a per-session answer does not belong there. +- **Ask which identity you mean.** `HERMES_DESKTOP=1` legitimately means "this backend was + spawned by the app" (cron ticker, web-dist handling). It does NOT mean "a GUI is watching"; + the embedded terminal pane (`hermes --tui` against that backend) is the counterexample. + +Test: if the capability still makes sense with the client on another machine, it is +session-scoped. Assert the GUI session gets the tool **with the env var absent**. + +## Development Environment + +```bash +source .venv/bin/activate # or: source venv/bin/activate +``` +`scripts/run_tests.sh` probes `.venv`, then `venv`, then `$HOME/.hermes/hermes-agent/venv` +(worktrees sharing the main checkout's venv). + +## Project Structure + +Counts shift constantly; the filesystem is canonical. Load-bearing entry points: + +``` +hermes-agent/ +├── run_agent.py # AIAgent facade; the turn loop lives in agent/turn_*.py +├── model_tools.py # Tool orchestration, discover_builtin_tools(), handle_function_call() +├── toolsets.py # TOOLSETS dict, _HERMES_CORE_TOOLS +├── cli.py # HermesCLI (REPL, slash dispatch) + hermes_cli/cli_*_mixin.py +├── hermes_state.py # SessionDB facade; hermes_state_*.py siblings +├── hermes_constants.py # get_hermes_home(), display_hermes_home() — profile-aware paths +├── hermes_logging.py # agent.log / errors.log / gateway.log (profile-aware) +├── batch_runner.py # Parallel batch processing +├── agent/ # turn_*.py loop phases, providers, memory, compression, prompt builder +├── hermes_cli/ # CLI subcommands, setup, config, plugins loader, skins, updater +│ └── web_routers/ # Dashboard FastAPI routers (one per surface); web_server.py mounts them +├── tools/ # Tool implementations, auto-discovered via tools/registry.py +│ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, singularity) +├── gateway/ # run.py facade + run_*.py phases + session*.py + platforms/ +│ ├── platforms/ # One adapter per platform; see platforms/ADDING_A_PLATFORM.md +│ └── builtin_hooks/ # Always-registered gateway hooks (extension point; none shipped) +├── plugins/ # memory/, context_engine/, model-providers/, kanban/, image_gen/, ... +├── skills/ # Built-in skills (by category) optional-skills/: shipped, not active +├── ui-tui/ # Ink (React) terminal UI — `hermes --tui` +├── tui_gateway/ # Python JSON-RPC backend for TUI + Desktop — server.py + methods_*.py +├── apps/desktop/ # Electron desktop app (+ apps/shared JSON-RPC client) web/: dashboard SPA +├── acp_adapter/ # ACP server (VS Code / Zed / JetBrains) +├── cron/ # jobs.py + scheduler.py (+ scheduler_*.py) +├── evals/ # Offline benchmarks (codebase_navigability/, compaction/, ...) +├── scripts/ # run_tests.sh, release.py, check_compat_pointers.py, ci/ +├── website/ # Docusaurus docs (developer-guide/ holds the long-form area docs) +└── tests/ # Pytest suite (~39k tests / ~3.7k files, Sep 2026) +``` + +**User state:** `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (secrets only), +`~/.hermes/logs/` (`agent.log` INFO+, `errors.log` WARNING+, `gateway.log`); all +profile-aware via `get_hermes_home()`. Browse logs with `hermes logs [--follow] [--level] [--session]`. + +**Dependency chain:** `tools/registry.py` (no deps) ← `tools/*.py` (register at import) ← +`model_tools.py` (discovery) ← `run_agent.py`, `cli.py`, `batch_runner.py`, `environments/`. + +### Facade + siblings layout (Sep 2026 decomposition) + +Every former god file is a **facade** (public entry points + the names other packages import) +plus **siblings** `_.py` in the same directory, each owning one topic. Largest +families: `hermes_state.py` (21), `gateway/run.py` (15), `tools/mcp_tool.py` (15), +`hermes_cli/kanban.py` (14), `hermes_cli/web_server.py` (13 + 24 routers), `hermes_cli/auth.py` +(12), `tools/browser_tool.py` (11), `cli.py` (12 `hermes_cli/cli_*_mixin.py`), `run_agent.py` +(`agent/turn_*.py`, `agent_init.py`, `conversation_loop.py`). + +- **Find code by topic, not by facade:** `grep -rn "def name" /_*.py`. Reading the + facade first is the expensive way (`evals/codebase_navigability/`). +- **Siblings may import each other and late-import the facade** inside functions. A facade + never imports a sibling at module level *and* gets imported by that sibling at module level. +- **Patch where production reads.** Siblings often do `from import name` inside the + function so `monkeypatch.setattr(facade, "name", ...)` is the seam; a patch on the defining + module passes silently. Check the call site's binding before writing a patch target + (blind repointing to defining modules broke 130+ tests). +- **Compat pointers are OFF LIMITS in-tree.** Old import paths kept alive for external plugins + (`PLUGIN-COMPAT` blocks, `COMPAT_MANIFEST.md`, `compat_manifest.json`) must not be used by + in-tree code or tests; `scripts/check_compat_pointers.py` runs in CI, and + `-W error::hermes_cli.plugin_compat.HermesPluginCompatWarning` catches them in the suite. + They are removed 2026-09-14 by reverting one commit. Import from the defining module. +- **Don't recreate god files.** A file passing ~2,000 lines or a function passing ~300 lines / + cyclomatic complexity 30 is the signal to split along `_` FIRST, in its own + commit. New behaviour goes in a new or topical sibling — never appended to a facade. +- **No `if/elif` ladders ≥ 4 branches keyed on a name/kind** — use a dict/table → handler + (`_SLASH_DISPATCH` in `cli.py`, `_command_handler_table` in the gateway are the shape). +- **No re-export shims for internal moves** ("keep the old name importable"). Internal paths + are not API; external compat is handled ONCE by the compat layer, not per PR. +- **Moving a symbol means fixing its docs in the same PR:** grep `website/docs`, + `skills/`, and every `AGENTS.md` for the old `path.py` + symbol (23 doc files went stale + after the refactor). `evals/codebase_navigability/static_metrics.py