#!/usr/bin/env python3

"""

Hermes CLI - Main entry point.

Usage:

hermes # Interactive chat (default)

hermes chat # Interactive chat

hermes gateway # Run gateway in foreground

hermes gateway start # Start gateway as service

hermes gateway stop # Stop gateway service

hermes gateway status # Show gateway status

hermes gateway install # Install gateway service

hermes gateway uninstall # Uninstall gateway service

hermes setup # Interactive setup wizard

hermes logout # Clear stored authentication

hermes status # Show status of all components

hermes cron # Manage cron jobs

hermes cron list # List cron jobs

hermes cron status # Check if cron scheduler is running

hermes doctor # Check configuration and dependencies

hermes honcho setup # Configure Honcho AI memory integration

hermes honcho status # Show Honcho config and connection status

hermes honcho sessions # List directory → session name mappings

hermes honcho map <name> # Map current directory to a session name

hermes honcho peer # Show peer names and dialectic settings

hermes honcho peer --user NAME # Set user peer name

hermes honcho peer --ai NAME # Set AI peer name

hermes honcho peer --reasoning LEVEL # Set dialectic reasoning level

hermes honcho mode # Show current memory mode

hermes honcho mode [hybrid|honcho|local] # Set memory mode

hermes honcho tokens # Show token budget settings

hermes honcho tokens --context N # Set session.context() token cap

hermes honcho tokens --dialectic N # Set dialectic result char cap

hermes honcho identity # Show AI peer identity representation

hermes honcho identity <file> # Seed AI peer identity from a file (SOUL.md etc.)

hermes honcho migrate # Step-by-step migration guide: OpenClaw native → Hermes + Honcho

hermes version Show version

hermes update Update to latest version

hermes uninstall Uninstall Hermes Agent

hermes acp Run as an ACP server for editor integration

hermes sessions browse Interactive session picker with search

hermes claw migrate --dry-run # Preview migration without changes

"""

import argparse

import json

import os

import shutil

import subprocess

import sys

import urllib.error

import urllib.request

from contextlib import contextmanager

from pathlib import Path

from typing import Any, Dict, Optional

def _add_accept_hooks_flag(parser) -> None:

"""Attach the ``--accept-hooks`` flag. Shared across every agent

subparser so the flag works regardless of CLI position."""

parser.add_argument(

"--accept-hooks",

action="store_true",

default=argparse.SUPPRESS,

help=(

"Auto-approve unseen shell hooks without a TTY prompt "

"(equivalent to HERMES_ACCEPT_HOOKS=1 / hooks_auto_accept: true)."

),

)

def _require_tty(command_name: str) -> None:

"""Exit with a clear error if stdin is not a terminal.

Interactive TUI commands (hermes tools, hermes setup, hermes model) use

curses or input() prompts that spin at 100% CPU when stdin is a pipe.

This guard prevents accidental non-interactive invocation.

"""

if not sys.stdin.isatty():

print(

f"Error: 'hermes {command_name}' requires an interactive terminal.\n"

f"It cannot be run through a pipe or non-interactive subprocess.\n"

f"Run it directly in your terminal instead.",

file=sys.stderr,

)

sys.exit(1)

# Add project root to path

PROJECT_ROOT = Path(__file__).parent.parent.resolve()

sys.path.insert(0, str(PROJECT_ROOT))

# ---------------------------------------------------------------------------

# Profile override — MUST happen before any hermes module import.

#

# Many modules cache HERMES_HOME at import time (module-level constants).

# We intercept --profile/-p from sys.argv here and set the env var so that

# every subsequent ``os.getenv("HERMES_HOME", ...)`` resolves correctly.

# The flag is stripped from sys.argv so argparse never sees it.

# Falls back to ~/.hermes/active_profile for sticky default.

# ---------------------------------------------------------------------------

def _apply_profile_override() -> None:

"""Pre-parse --profile/-p and set HERMES_HOME before module imports."""

argv = sys.argv[1:]

profile_name = None

consume = 0

# 1. Check for explicit -p / --profile flag

for i, arg in enumerate(argv):

if arg in ("--profile", "-p") and i + 1 < len(argv):

profile_name = argv[i + 1]

consume = 2

break

elif arg.startswith("--profile="):

profile_name = arg.split("=", 1)[1]

consume = 1

break

# 2. If no flag, check active_profile in the hermes root

if profile_name is None:

try:

from hermes_constants import get_default_hermes_root

active_path = get_default_hermes_root() / "active_profile"

if active_path.exists():

name = active_path.read_text().strip()

if name and name != "default":

profile_name = name

consume = 0 # don't strip anything from argv

except (UnicodeDecodeError, OSError):

pass # corrupted file, skip

# 3. If we found a profile, resolve and set HERMES_HOME

if profile_name is not None:

try:

from hermes_cli.profiles import resolve_profile_env

hermes_home = resolve_profile_env(profile_name)

except (ValueError, FileNotFoundError) as exc:

print(f"Error: {exc}", file=sys.stderr)

sys.exit(1)

except Exception as exc:

# A bug in profiles.py must NEVER prevent hermes from starting

print(

f"Warning: profile override failed ({exc}), using default",

file=sys.stderr,

)

return

os.environ["HERMES_HOME"] = hermes_home

# Strip the flag from argv so argparse doesn't choke

if consume > 0:

for i, arg in enumerate(argv):

if arg in ("--profile", "-p"):

start = i + 1 # +1 because argv is sys.argv[1:]

sys.argv = sys.argv[:start] + sys.argv[start + consume :]

break

elif arg.startswith("--profile="):

start = i + 1

sys.argv = sys.argv[:start] + sys.argv[start + 1 :]

break

_apply_profile_override()

# Load .env from ~/.hermes/.env first, then project root as dev fallback.

# User-managed env files should override stale shell exports on restart.

from hermes_cli.config import get_hermes_home

from hermes_cli.env_loader import load_hermes_dotenv

load_hermes_dotenv(project_env=PROJECT_ROOT / ".env")

# Bridge security.redact_secrets from config.yaml → HERMES_REDACT_SECRETS env

# var BEFORE hermes_logging imports agent.redact (which snapshots the flag at

# module-import time). Without this, config.yaml's toggle is ignored because

# the setup_logging() call below imports agent.redact, which reads the env var

# exactly once. Env var in .env still wins — this is config.yaml fallback only.

try:

if "HERMES_REDACT_SECRETS" not in os.environ:

import yaml as _yaml_early

_cfg_path = get_hermes_home() / "config.yaml"

if _cfg_path.exists():

with open(_cfg_path, encoding="utf-8") as _f:

_early_sec_cfg = (_yaml_early.safe_load(_f) or {}).get("security", {})

if isinstance(_early_sec_cfg, dict):

_early_redact = _early_sec_cfg.get("redact_secrets")

if _early_redact is not None:

os.environ["HERMES_REDACT_SECRETS"] = str(_early_redact).lower()

del _early_sec_cfg

del _cfg_path

except Exception:

pass # best-effort — redaction stays at default (enabled) on config errors

# Initialize centralized file logging early — all `hermes` subcommands

# (chat, setup, gateway, config, etc.) write to agent.log + errors.log.

try:

from hermes_logging import setup_logging as _setup_logging

_setup_logging(mode="cli")

except Exception:

pass # best-effort — don't crash the CLI if logging setup fails

# Apply IPv4 preference early, before any HTTP clients are created.

try:

from hermes_cli.config import load_config as _load_config_early

from hermes_constants import apply_ipv4_preference as _apply_ipv4

_early_cfg = _load_config_early()

_net = _early_cfg.get("network", {})

if isinstance(_net, dict) and _net.get("force_ipv4"):

_apply_ipv4(force=True)

del _early_cfg, _net

except Exception:

pass # best-effort — don't crash if config isn't available yet

import logging

import time as _time

from datetime import datetime

from hermes_cli import __version__, __release_date__

from hermes_constants import AI_GATEWAY_BASE_URL, OPENROUTER_BASE_URL

logger = logging.getLogger(__name__)

def _relative_time(ts) -> str:

"""Format a timestamp as relative time (e.g., '2h ago', 'yesterday')."""

if not ts:

return "?"

delta = _time.time() - ts

if delta < 60:

return "just now"

if delta < 3600:

return f"{int(delta / 60)}m ago"

if delta < 86400:

return f"{int(delta / 3600)}h ago"

if delta < 172800:

return "yesterday"

if delta < 604800:

return f"{int(delta / 86400)}d ago"

return datetime.fromtimestamp(ts).strftime("%Y-%m-%d")

def _has_any_provider_configured() -> bool:

"""Check if at least one inference provider is usable."""

from hermes_cli.config import get_env_path, get_hermes_home, load_config

from hermes_cli.auth import get_auth_status

# Determine whether Hermes itself has been explicitly configured (model

# in config that isn't the hardcoded default). Used below to gate external

# tool credentials (Claude Code, Codex CLI) that shouldn't silently skip

# the setup wizard on a fresh install.

from hermes_cli.config import DEFAULT_CONFIG

_DEFAULT_MODEL = DEFAULT_CONFIG.get("model", "")

cfg = load_config()

model_cfg = cfg.get("model")

if isinstance(model_cfg, dict):

_model_name = (model_cfg.get("default") or "").strip()

elif isinstance(model_cfg, str):

_model_name = model_cfg.strip()

else:

_model_name = ""

_has_hermes_config = _model_name and _model_name != _DEFAULT_MODEL

# Check env vars (may be set by .env or shell).

# OPENAI_BASE_URL alone counts — local models (vLLM, llama.cpp, etc.)

# often don't require an API key.

from hermes_cli.auth import PROVIDER_REGISTRY

# Collect all provider env vars

provider_env_vars = {

"OPENROUTER_API_KEY",

"OPENAI_API_KEY",

"ANTHROPIC_API_KEY",

"ANTHROPIC_TOKEN",

"OPENAI_BASE_URL",

}

for pconfig in PROVIDER_REGISTRY.values():

if pconfig.auth_type == "api_key":

provider_env_vars.update(pconfig.api_key_env_vars)

if any(os.getenv(v) for v in provider_env_vars):

return True

# Check .env file for keys

env_file = get_env_path()

if env_file.exists():

try:

for line in env_file.read_text().splitlines():

line = line.strip()

if line.startswith("#") or "=" not in line:

continue

key, _, val = line.partition("=")

val = val.strip().strip("'\"")

if key.strip() in provider_env_vars and val:

return True

except Exception:

pass

# Check provider-specific auth fallbacks (for example, Copilot via gh auth).

try:

for provider_id, pconfig in PROVIDER_REGISTRY.items():

if pconfig.auth_type != "api_key":

continue

status = get_auth_status(provider_id)

if status.get("logged_in"):

return True

except Exception:

pass

# Check for Nous Portal OAuth credentials

auth_file = get_hermes_home() / "auth.json"

if auth_file.exists():

try:

import json

auth = json.loads(auth_file.read_text())

active = auth.get("active_provider")

if active:

status = get_auth_status(active)

if status.get("logged_in"):

return True

except Exception:

pass

# Check config.yaml — if model is a dict with an explicit provider set,

# the user has gone through setup (fresh installs have model as a plain

# string). Also covers custom endpoints that store api_key/base_url in

# config rather than .env.

if isinstance(model_cfg, dict):

cfg_provider = (model_cfg.get("provider") or "").strip()

cfg_base_url = (model_cfg.get("base_url") or "").strip()

cfg_api_key = (model_cfg.get("api_key") or "").strip()

if cfg_provider or cfg_base_url or cfg_api_key:

return True

# Check for Claude Code OAuth credentials (~/.claude/.credentials.json)

# Only count these if Hermes has been explicitly configured — Claude Code

# being installed doesn't mean the user wants Hermes to use their tokens.

if _has_hermes_config:

try:

from agent.anthropic_adapter import (

read_claude_code_credentials,

is_claude_code_token_valid,

)

creds = read_claude_code_credentials()

if creds and (

is_claude_code_token_valid(creds) or creds.get("refreshToken")

):

return True

except Exception:

pass

return False

def _session_browse_picker(sessions: list) -> Optional[str]:

"""Interactive curses-based session browser with live search filtering.

Returns the selected session ID, or None if cancelled.

Uses curses (not simple_term_menu) to avoid the ghost-duplication rendering

bug in tmux/iTerm when arrow keys are used.

"""

if not sessions:

print("No sessions found.")

return None

# Try curses-based picker first

try:

import curses

result_holder = [None]

def _format_row(s, max_x):

"""Format a session row for display."""

title = (s.get("title") or "").strip()

preview = (s.get("preview") or "").strip()

source = s.get("source", "")[:6]

last_active = _relative_time(s.get("last_active"))

sid = s["id"][:18]

# Adaptive column widths based on terminal width

# Layout: [arrow 3] [title/preview flexible] [active 12] [src 6] [id 18]

fixed_cols = 3 + 12 + 6 + 18 + 6 # arrow + active + src + id + padding

name_width = max(20, max_x - fixed_cols)

if title:

name = title[:name_width]

elif preview:

name = preview[:name_width]

else:

name = sid

return f"{name:<{name_width}} {last_active:<10} {source:<5} {sid}"

def _match(s, query):

"""Check if a session matches the search query (case-insensitive)."""

q = query.lower()

return (

q in (s.get("title") or "").lower()

or q in (s.get("preview") or "").lower()

or q in s.get("id", "").lower()

or q in (s.get("source") or "").lower()

)

def _curses_browse(stdscr):

curses.curs_set(0)

if curses.has_colors():

curses.start_color()

curses.use_default_colors()

curses.init_pair(1, curses.COLOR_GREEN, -1) # selected

curses.init_pair(2, curses.COLOR_YELLOW, -1) # header

curses.init_pair(3, curses.COLOR_CYAN, -1) # search

curses.init_pair(4, 8, -1) # dim

cursor = 0

scroll_offset = 0

search_text = ""

filtered = list(sessions)

while True:

stdscr.clear()

max_y, max_x = stdscr.getmaxyx()

if max_y < 5 or max_x < 40:

# Terminal too small

try:

stdscr.addstr(0, 0, "Terminal too small")

except curses.error:

pass

stdscr.refresh()

stdscr.getch()

return

# Header line

if search_text:

header = f" Browse sessions — filter: {search_text}█"

header_attr = curses.A_BOLD

if curses.has_colors():

header_attr |= curses.color_pair(3)

else:

header = " Browse sessions — ↑↓ navigate Enter select Type to filter Esc quit"

header_attr = curses.A_BOLD

if curses.has_colors():

header_attr |= curses.color_pair(2)

try:

stdscr.addnstr(0, 0, header, max_x - 1, header_attr)

except curses.error:

pass

# Column header line

fixed_cols = 3 + 12 + 6 + 18 + 6

name_width = max(20, max_x - fixed_cols)

col_header = f" {'Title / Preview':<{name_width}} {'Active':<10} {'Src':<5} {'ID'}"

try:

dim_attr = (

curses.color_pair(4) if curses.has_colors() else curses.A_DIM

)

stdscr.addnstr(1, 0, col_header, max_x - 1, dim_attr)

except curses.error:

pass

# Compute visible area

visible_rows = max_y - 4 # header + col header + blank + footer

if visible_rows < 1:

visible_rows = 1

# Clamp cursor and scroll

if not filtered:

try:

msg = " No sessions match the filter."

stdscr.addnstr(3, 0, msg, max_x - 1, curses.A_DIM)

except curses.error:

pass

else:

if cursor >= len(filtered):

cursor = len(filtered) - 1

if cursor < 0:

cursor = 0

if cursor < scroll_offset:

scroll_offset = cursor

elif cursor >= scroll_offset + visible_rows:

scroll_offset = cursor - visible_rows + 1

for draw_i, i in enumerate(

range(

scroll_offset,

min(len(filtered), scroll_offset + visible_rows),

)

):

y = draw_i + 3

if y >= max_y - 1:

break

s = filtered[i]

arrow = " → " if i == cursor else " "

row = arrow + _format_row(s, max_x - 3)

attr = curses.A_NORMAL

if i == cursor:

attr = curses.A_BOLD

if curses.has_colors():

attr |= curses.color_pair(1)

try:

stdscr.addnstr(y, 0, row, max_x - 1, attr)

except curses.error:

pass

# Footer

footer_y = max_y - 1

if filtered:

footer = f" {cursor + 1}/{len(filtered)} sessions"

if len(filtered) < len(sessions):

footer += f" (filtered from {len(sessions)})"

else:

footer = f" 0/{len(sessions)} sessions"

try:

stdscr.addnstr(

footer_y,

0,

footer,

max_x - 1,

curses.color_pair(4) if curses.has_colors() else curses.A_DIM,

)

except curses.error:

pass

stdscr.refresh()

key = stdscr.getch()

if key in (curses.KEY_UP,):

if filtered:

cursor = (cursor - 1) % len(filtered)

elif key in (curses.KEY_DOWN,):

if filtered:

cursor = (cursor + 1) % len(filtered)

elif key in (curses.KEY_ENTER, 10, 13):

if filtered:

result_holder[0] = filtered[cursor]["id"]

return

elif key == 27: # Esc

if search_text:

# First Esc clears the search

search_text = ""

filtered = list(sessions)

cursor = 0

scroll_offset = 0

else:

# Second Esc exits

return

elif key in (curses.KEY_BACKSPACE, 127, 8):

if search_text:

search_text = search_text[:-1]

if search_text:

filtered = [s for s in sessions if _match(s, search_text)]

else:

filtered = list(sessions)

cursor = 0

scroll_offset = 0

elif key == ord("q") and not search_text:

return

elif 32 <= key <= 126:

# Printable character → add to search filter

search_text += chr(key)

filtered = [s for s in sessions if _match(s, search_text)]

cursor = 0

scroll_offset = 0

curses.wrapper(_curses_browse)

return result_holder[0]

except Exception:

pass

# Fallback: numbered list (Windows without curses, etc.)

print("\n Browse sessions (enter number to resume, q to cancel)\n")

for i, s in enumerate(sessions):

title = (s.get("title") or "").strip()

preview = (s.get("preview") or "").strip()

label = title or preview or s["id"]

if len(label) > 50:

label = label[:47] + "..."

last_active = _relative_time(s.get("last_active"))

src = s.get("source", "")[:6]

print(f" {i + 1:>3}. {label:<50} {last_active:<10} {src}")

while True:

try:

val = input(f"\n Select [1-{len(sessions)}]: ").strip()

if not val or val.lower() in ("q", "quit", "exit"):

return None

idx = int(val) - 1

if 0 <= idx < len(sessions):

return sessions[idx]["id"]

print(f" Invalid selection. Enter 1-{len(sessions)} or q to cancel.")

except ValueError:

print(" Invalid input. Enter a number or q to cancel.")

except (KeyboardInterrupt, EOFError):

print()

return None

def _resolve_last_session(source: str = "cli") -> Optional[str]:

"""Look up the most recent session ID for a source."""

try:

from hermes_state import SessionDB

db = SessionDB()

sessions = db.search_sessions(source=source, limit=1)

db.close()

if sessions:

return sessions[0]["id"]

except Exception:

pass

return None

def _probe_container(cmd: list, backend: str, via_sudo: bool = False):

"""Run a container inspect probe, returning the CompletedProcess.

Catches TimeoutExpired specifically for a human-readable message;

all other exceptions propagate naturally.

"""

try:

return subprocess.run(cmd, capture_output=True, text=True, timeout=15)

except subprocess.TimeoutExpired:

label = f"sudo {backend}" if via_sudo else backend

print(

f"Error: timed out waiting for {label} to respond.\n"

f"The {backend} daemon may be unresponsive or starting up.",

file=sys.stderr,

)

sys.exit(1)

def _exec_in_container(container_info: dict, cli_args: list):

"""Replace the current process with a command inside the managed container.

Probes whether sudo is needed (rootful containers), then os.execvp

into the container. On success the Python process is replaced entirely

and the container's exit code becomes the process exit code (OS semantics).

On failure, OSError propagates naturally.

Args:

container_info: dict with backend, container_name, exec_user, hermes_bin

cli_args: the original CLI arguments (everything after 'hermes')

"""

backend = container_info["backend"]

container_name = container_info["container_name"]

exec_user = container_info["exec_user"]

hermes_bin = container_info["hermes_bin"]

runtime = shutil.which(backend)

if not runtime:

print(

f"Error: {backend} not found on PATH. Cannot route to container.",

file=sys.stderr,

)

sys.exit(1)

# Rootful containers (NixOS systemd service) are invisible to unprivileged

# users — Podman uses per-user namespaces, Docker needs group access.

# Probe whether the runtime can see the container; if not, try via sudo.

sudo_path = None

probe = _probe_container(

[runtime, "inspect", "--format", "ok", container_name],

backend,

)

if probe.returncode != 0:

sudo_path = shutil.which("sudo")

if sudo_path:

probe2 = _probe_container(

[sudo_path, "-n", runtime, "inspect", "--format", "ok", container_name],

backend,

via_sudo=True,

)

if probe2.returncode != 0:

print(

f"Error: container '{container_name}' not found via {backend}.\n"

f"\n"

f"The container is likely running as root. Your user cannot see it\n"

f"because {backend} uses per-user namespaces. Grant passwordless\n"

f"sudo for {backend} — the -n (non-interactive) flag is required\n"

f"because a password prompt would hang or break piped commands.\n"

f"\n"

f"On NixOS:\n"

f"\n"

f" security.sudo.extraRules = [{{\n"

f' users = [ "{os.getenv("USER", "your-user")}" ];\n'

f' commands = [{{ command = "{runtime}"; options = [ "NOPASSWD" ]; }}];\n'

f" }}];\n"

f"\n"

f"Or run: sudo hermes {' '.join(cli_args)}",

file=sys.stderr,

)

sys.exit(1)

else:

print(

f"Error: container '{container_name}' not found via {backend}.\n"

f"The container may be running under root. Try: sudo hermes {' '.join(cli_args)}",

file=sys.stderr,

)

sys.exit(1)

is_tty = sys.stdin.isatty()

tty_flags = ["-it"] if is_tty else ["-i"]

env_flags = []

for var in ("TERM", "COLORTERM", "LANG", "LC_ALL"):

val = os.environ.get(var)

if val:

env_flags.extend(["-e", f"{var}={val}"])

cmd_prefix = [sudo_path, "-n", runtime] if sudo_path else [runtime]

exec_cmd = (

cmd_prefix

+ ["exec"]

+ tty_flags

+ ["-u", exec_user]

+ env_flags

+ [container_name, hermes_bin]

+ cli_args

)

os.execvp(exec_cmd[0], exec_cmd)

def _resolve_session_by_name_or_id(name_or_id: str) -> Optional[str]:

"""Resolve a session name (title) or ID to a session ID.

- If it looks like a session ID (contains underscore + hex), try direct lookup first.

- Otherwise, treat it as a title and use resolve_session_by_title (auto-latest).

- Falls back to the other method if the first doesn't match.

- If the resolved session is a compression root, follow the chain forward

to the latest continuation. Users who remember the old root ID (e.g.

from an exit summary printed before the bug fix, or from notes) get

resumed at the live tip instead of a stale parent with no messages.

"""

try:

from hermes_state import SessionDB

db = SessionDB()

# Try as exact session ID first

session = db.get_session(name_or_id)

resolved_id: Optional[str] = None

if session:

resolved_id = session["id"]

else:

# Try as title (with auto-latest for lineage)

resolved_id = db.resolve_session_by_title(name_or_id)

if resolved_id:

# Project forward through compression chain so resumes land on

# the live tip instead of a dead compressed parent.

try:

resolved_id = db.get_compression_tip(resolved_id) or resolved_id

except Exception:

pass

db.close()

return resolved_id

except Exception:

pass

return None

def _print_tui_exit_summary(session_id: Optional[str]) -> None:

"""Print a shell-visible epilogue after TUI exits."""

target = session_id or _resolve_last_session(source="tui")

if not target:

return

db = None

try:

from hermes_state import SessionDB

db = SessionDB()

session = db.get_session(target)

if not session:

return

title = db.get_session_title(target)

message_count = int(session.get("message_count") or 0)

input_tokens = int(session.get("input_tokens") or 0)

output_tokens = int(session.get("output_tokens") or 0)

cache_read_tokens = int(session.get("cache_read_tokens") or 0)

cache_write_tokens = int(session.get("cache_write_tokens") or 0)

reasoning_tokens = int(session.get("reasoning_tokens") or 0)

total_tokens = (

input_tokens

+ output_tokens

+ cache_read_tokens

+ cache_write_tokens

+ reasoning_tokens

)

except Exception:

return

finally:

if db is not None:

db.close()

print()

print("Resume this session with:")

print(f" hermes --tui --resume {target}")

if title:

print(f' hermes --tui -c "{title}"')

print()

print(f"Session: {target}")

if title:

print(f"Title: {title}")

print(f"Messages: {message_count}")

print(

"Tokens: "

f"{total_tokens} (in {input_tokens}, out {output_tokens}, "

f"cache {cache_read_tokens + cache_write_tokens}, reasoning {reasoning_tokens})"

)

def _tui_need_npm_install(root: Path) -> bool:

"""True when @hermes/ink is missing or node_modules is behind package-lock.json (post-pull)."""

ink = root / "node_modules" / "@hermes" / "ink" / "package.json"

if not ink.is_file():

return True

lock = root / "package-lock.json"

if not lock.is_file():

return False

marker = root / "node_modules" / ".package-lock.json"

if not marker.is_file():

return True

return lock.stat().st_mtime > marker.stat().st_mtime

def _find_bundled_tui(tui_dir: Path) -> Optional[Path]:

"""Directory whose dist/entry.js we should run: HERMES_TUI_DIR first, else repo ui-tui."""

env = os.environ.get("HERMES_TUI_DIR")

if env:

p = Path(env)

if (p / "dist" / "entry.js").exists() and not _tui_need_npm_install(p):

return p

if (tui_dir / "dist" / "entry.js").exists() and not _tui_need_npm_install(tui_dir):

return tui_dir

return None

def _tui_build_needed(tui_dir: Path) -> bool:

if _hermes_ink_bundle_stale(tui_dir):

return True

entry = tui_dir / "dist" / "entry.js"

if not entry.exists():

return True

dist_m = entry.stat().st_mtime

skip = frozenset({"node_modules", "dist"})

for dirpath, dirnames, filenames in os.walk(tui_dir, topdown=True):

dirnames[:] = [d for d in dirnames if d not in skip]

for fn in filenames:

if fn.endswith((".ts", ".tsx")):

if os.path.getmtime(os.path.join(dirpath, fn)) > dist_m:

return True

for meta in (

"package.json",

"package-lock.json",

"tsconfig.json",

"tsconfig.build.json",

):

mp = tui_dir / meta

if mp.exists() and mp.stat().st_mtime > dist_m:

return True

return False

def _hermes_ink_bundle_stale(tui_dir: Path) -> bool:

ink_root = tui_dir / "packages" / "hermes-ink"

bundle = ink_root / "dist" / "ink-bundle.js"

if not bundle.exists():

return True

bm = bundle.stat().st_mtime

skip = frozenset({"node_modules", "dist"})

for dirpath, dirnames, filenames in os.walk(ink_root, topdown=True):

dirnames[:] = [d for d in dirnames if d not in skip]

for fn in filenames:

if fn.endswith((".ts", ".tsx")):

if os.path.getmtime(os.path.join(dirpath, fn)) > bm:

return True

mp = ink_root / "package.json"

if mp.exists() and mp.stat().st_mtime > bm:

return True

return False

def _ensure_tui_node() -> None:

"""Make sure `node` + `npm` are on PATH for the TUI.

If either is missing and scripts/lib/node-bootstrap.sh is available, source

it and call `ensure_node` (fnm/nvm/proto/brew/bundled cascade). After

install, capture the resolved node binary path from the bash subprocess

and prepend its directory to os.environ["PATH"] so shutil.which finds the

new binaries in this Python process — regardless of which version manager

was used (nvm, fnm, proto, brew, or the bundled fallback).

Idempotent no-op when node+npm are already discoverable. Set

``HERMES_SKIP_NODE_BOOTSTRAP=1`` to disable auto-install.

"""

if shutil.which("node") and shutil.which("npm"):

return

if os.environ.get("HERMES_SKIP_NODE_BOOTSTRAP"):

return

helper = PROJECT_ROOT / "scripts" / "lib" / "node-bootstrap.sh"

if not helper.is_file():

return

hermes_home = os.environ.get("HERMES_HOME") or str(Path.home() / ".hermes")

try:

# Helper writes logs to stderr; we ask bash to print `command -v node`

# on stdout once ensure_node succeeds. Subshell PATH edits don't leak

# back into Python, so the stdout capture is the bridge.

result = subprocess.run(

[

"bash",

"-c",

f'source "{helper}" >&2 && ensure_node >&2 && command -v node',

],

env={**os.environ, "HERMES_HOME": hermes_home},

capture_output=True,

text=True,

check=False,

)

except (OSError, subprocess.SubprocessError):

return

parts = os.environ.get("PATH", "").split(os.pathsep)

extras: list[Path] = []

resolved = (result.stdout or "").strip()

if resolved:

extras.append(Path(resolved).resolve().parent)

extras.extend([Path(hermes_home) / "node" / "bin", Path.home() / ".local" / "bin"])

for extra in extras:

s = str(extra)

if extra.is_dir() and s not in parts:

parts.insert(0, s)

os.environ["PATH"] = os.pathsep.join(parts)

def _make_tui_argv(tui_dir: Path, tui_dev: bool) -> tuple[list[str], Path]:

"""TUI: --dev → tsx src; else node dist (HERMES_TUI_DIR or ui-tui, build when stale)."""

_ensure_tui_node()

def _node_bin(bin: str) -> str:

if bin == "node":

env_node = os.environ.get("HERMES_NODE")

if env_node and os.path.isfile(env_node) and os.access(env_node, os.X_OK):

return env_node

path = shutil.which(bin)

if not path:

print(f"{bin} not found — install Node.js to use the TUI.")

sys.exit(1)

return path

# pre-built dist + node_modules (nix / full HERMES_TUI_DIR) skips npm.

if not tui_dev:

ext_dir = os.environ.get("HERMES_TUI_DIR")

if ext_dir:

p = Path(ext_dir)

if (p / "dist" / "entry.js").exists() and not _tui_need_npm_install(p):

node = _node_bin("node")

return [node, str(p / "dist" / "entry.js")], p

npm = _node_bin("npm")

if _tui_need_npm_install(tui_dir):

if not os.environ.get("HERMES_QUIET"):

print("Installing TUI dependencies…")

result = subprocess.run(

[npm, "install", "--silent", "--no-fund", "--no-audit", "--progress=false"],

cwd=str(tui_dir),

stdout=subprocess.DEVNULL,

stderr=subprocess.PIPE,

text=True,

env={**os.environ, "CI": "1"},

)

if result.returncode != 0:

err = (result.stderr or "").strip()

preview = "\n".join(err.splitlines()[-30:])

print("npm install failed.")

if preview:

print(preview)

sys.exit(1)

if tui_dev:

if _hermes_ink_bundle_stale(tui_dir):

result = subprocess.run(

[npm, "run", "build", "--prefix", "packages/hermes-ink"],

cwd=str(tui_dir),

capture_output=True,

text=True,

)

if result.returncode != 0:

combined = f"{result.stdout or ''}{result.stderr or ''}".strip()