Compare commits

..

20 Commits

Author SHA1 Message Date
Sam Herring e3123be445 Removing old patches 2026-03-30 10:06:08 -07:00
Sam Herring e46d5b2c13 Removing old files 2026-03-30 09:58:05 -07:00
Sam Herring 34cc666105 Updating with trainer config pieces 2026-03-30 09:46:24 -07:00
Sam Herring d6832260f9 Fixing eval steps to be a set number of tasks 2026-03-30 09:46:24 -07:00
Sam Herring d2652e980f Adding random jitter for agent temp to add variance into rollouts 2026-03-30 09:46:24 -07:00
Sam Herring 89cea9fd2d Test basic Atropos trainer 2026-03-30 09:46:24 -07:00
Sam Herring 143e72c145 Updating endless terminals env with silenced warnings 2026-03-30 09:46:24 -07:00
Sam Herring 51305b3f3d Tool call changes 2026-03-30 09:46:24 -07:00
Sam Herring 570e52b342 Monkey patching chat template kwargs 2026-03-30 09:46:24 -07:00
Sam Herring d6e874491d Env changes for tool use 2026-03-30 09:46:24 -07:00
Sam Herring dd3812dffe Adding tool call parser default 2026-03-30 09:46:24 -07:00
Sam Herring 6e17630bac Eval splits for holdout sets 2026-03-30 09:46:24 -07:00
Sam Herring 53b710b13f Changing return type to be ScoredDataGroup to account for multiple trajectories 2026-03-30 09:46:24 -07:00
Sam Herring 5b1e8059cb Added task sppecific metris and evals 2026-03-30 09:46:24 -07:00
Sam Herring ff16a33cdd Wandb changes 2026-03-30 09:46:24 -07:00
Sam Herring 7cfb9eb1f6 Updating config 2026-03-30 09:46:24 -07:00
Sam Herring c7b15f8ce1 Adding config init method 2026-03-30 09:46:24 -07:00
Sam Herring 7602c462ee Updating path vars and dataset loading 2026-03-30 09:46:24 -07:00
Sam Herring e38c24363c Updating to use hermes-agent backend and parse container definition out of provided .sif files 2026-03-30 09:46:24 -07:00
Sam Herring d768b244a5 Adding endless terminal environment after rebase: 2026-03-30 09:46:24 -07:00
134 changed files with 1440 additions and 3884 deletions
-15
View File
@@ -231,21 +231,6 @@ VOICE_TOOLS_OPENAI_KEY=
# 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
# 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
+1 -26
View File
@@ -162,21 +162,6 @@ def _is_oauth_token(key: str) -> bool:
return True
def _requires_bearer_auth(base_url: str | None) -> bool:
"""Return True for Anthropic-compatible providers that require Bearer auth.
Some third-party /anthropic endpoints implement Anthropic's Messages API but
require Authorization: Bearer instead of Anthropic's native x-api-key header.
MiniMax's global and China Anthropic-compatible endpoints follow this pattern.
"""
if not base_url:
return False
normalized = base_url.rstrip("/").lower()
return normalized.startswith("https://api.minimax.io/anthropic") or normalized.startswith(
"https://api.minimaxi.com/anthropic"
)
def build_anthropic_client(api_key: str, base_url: str = None):
"""Create an Anthropic client, auto-detecting setup-tokens vs API keys.
@@ -195,17 +180,7 @@ def build_anthropic_client(api_key: str, base_url: str = None):
if base_url:
kwargs["base_url"] = base_url
if _requires_bearer_auth(base_url):
# Some Anthropic-compatible providers (e.g. MiniMax) expect the API key in
# Authorization: Bearer even for regular API keys. Route those endpoints
# through auth_token so the SDK sends Bearer auth instead of x-api-key.
# Check this before OAuth token shape detection because MiniMax secrets do
# not use Anthropic's sk-ant-api prefix and would otherwise be misread as
# Anthropic OAuth/setup tokens.
kwargs["auth_token"] = api_key
if _COMMON_BETAS:
kwargs["default_headers"] = {"anthropic-beta": ",".join(_COMMON_BETAS)}
elif _is_oauth_token(api_key):
if _is_oauth_token(api_key):
# OAuth access token / setup-token → Bearer auth + Claude Code identity.
# Anthropic routes OAuth requests based on user-agent and headers;
# without Claude Code's fingerprint, requests get intermittent 500s.
-39
View File
@@ -2837,28 +2837,6 @@ class HermesCLI:
print(" Example: python cli.py --toolsets web,terminal")
print()
def _handle_profile_command(self):
"""Display active profile name and home directory."""
from hermes_constants import get_hermes_home, display_hermes_home
home = get_hermes_home()
display = display_hermes_home()
profiles_parent = Path.home() / ".hermes" / "profiles"
try:
rel = home.relative_to(profiles_parent)
profile_name = str(rel).split("/")[0]
except ValueError:
profile_name = None
print()
if profile_name:
print(f" Profile: {profile_name}")
else:
print(" Profile: default")
print(f" Home: {display}")
print()
def show_config(self):
"""Display current configuration with kawaii ASCII art."""
# Get terminal config from environment (which was set from cli-config.yaml)
@@ -3701,8 +3679,6 @@ class HermesCLI:
return False
elif canonical == "help":
self.show_help()
elif canonical == "profile":
self._handle_profile_command()
elif canonical == "tools":
self._handle_tools_command(cmd_original)
elif canonical == "toolsets":
@@ -3860,8 +3836,6 @@ class HermesCLI:
self.console.print(f" Status bar {state}")
elif canonical == "verbose":
self._toggle_verbose()
elif canonical == "yolo":
self._toggle_yolo()
elif canonical == "reasoning":
self._handle_reasoning_command(cmd_original)
elif canonical == "compress":
@@ -4460,17 +4434,6 @@ class HermesCLI:
}
_cprint(labels.get(self.tool_progress_mode, ""))
def _toggle_yolo(self):
"""Toggle YOLO mode — skip all dangerous command approval prompts."""
import os
current = bool(os.environ.get("HERMES_YOLO_MODE"))
if current:
os.environ.pop("HERMES_YOLO_MODE", None)
self.console.print(" ⚠ YOLO mode [bold red]OFF[/] — dangerous commands will require approval.")
else:
os.environ["HERMES_YOLO_MODE"] = "1"
self.console.print(" ⚡ YOLO mode [bold green]ON[/] — all commands auto-approved. Use with caution.")
def _handle_reasoning_command(self, cmd: str):
"""Handle /reasoning — manage effort level and display toggle.
@@ -5597,8 +5560,6 @@ class HermesCLI:
self.agent = None
# Initialize agent if needed
if self.agent is None:
_cprint(f"{_DIM}Initializing agent...{_RST}")
if not self._init_agent(
model_override=turn_route["model"],
runtime_override=turn_route["runtime"],
+1
View File
@@ -13,6 +13,7 @@ Core layers:
Concrete environments:
- terminal_test_env/: Simple file-creation tasks for testing the stack
- hermes_swe_env/: SWE-bench style tasks with Modal sandboxes
- endless_terminals/: Terminal tasks from HuggingFace dataset with Apptainer containers
Benchmarks (eval-only):
- benchmarks/terminalbench_2/: Terminal-Bench 2.0 evaluation
@@ -0,0 +1,5 @@
"""Endless Terminals Environment - Terminal task training from HuggingFace dataset."""
from .endless_terminals_env import EndlessTerminalsEnv, EndlessTerminalsEnvConfig
__all__ = ["EndlessTerminalsEnv", "EndlessTerminalsEnvConfig"]
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,91 @@
# Endless Terminals - Qwen3-4B-Instruct-2507
# Single config for both trainer (launch_training.py) and env (endless_terminals_env.py serve)
#
# Usage:
# Terminal 1: run-api
# Terminal 2: cd tinker-atropos && python launch_training.py --config ../environments/endless_terminals/tinker_qwen.yaml
# Terminal 3: python environments/endless_terminals/endless_terminals_env.py serve --config environments/endless_terminals/tinker_qwen.yaml
env:
# Toolsets
enabled_toolsets: ["terminal", "file"]
# Model / tokenizer
tokenizer_name: "Qwen/Qwen3-4B-Instruct-2507"
# Agent configuration
max_agent_turns: 16
max_token_length: 2048
agent_temperature: 0.6
extra_body:
chat_template_kwargs:
enable_thinking: false
tool_call_parser: "hermes"
# Terminal backend
terminal_backend: "docker"
# Dataset settings
use_dataset: true
dataset_name: "obiwan96/endless-terminals"
dataset_split: "train"
dataset_cache_dir: "~/.cache/huggingface/datasets"
tasks_base_dir: "/Users/samherring/Desktop/Projects/Hermes-Agent/endless-terminals"
# Test execution
test_timeout_s: 180
default_docker_image: "ubuntu:22.04"
max_concurrent_containers: 16
# Training configuration
group_size: 16
batch_size: 64 # 4 groups × 16 rollouts per step
total_steps: 500
steps_per_eval: 5
min_items_sent_before_logging: 1
ensure_scores_are_not_same: true
max_num_workers: 2048
worker_timeout: 3600
inference_weight: 1.0
eval_limit_ratio: 0.1
rollout_server_url: "http://localhost:8000"
# Evaluation configuration
num_eval_tasks: 20
eval_split_ratio: 0.1
# Logging
use_wandb: true
wandb_name: "endless-terminals-qwen3-4b"
# System prompt
system_prompt: >
You are a skilled Linux system administrator and programmer.
You have access to a terminal and file tools to complete system administration
and programming tasks. Use the tools effectively to solve the given task,
and verify your solution works correctly before finishing.
Keep each command short and focused — break complex tasks into multiple steps
rather than writing long one-liners.
tinker:
lora_rank: 32
learning_rate: 0.0000005
max_token_trainer_length: 32768
checkpoint_dir: "./temp/"
save_checkpoint_interval: 50
wandb_project: "endless-terminals"
wandb_group: null
wandb_run_name: "qwen3-4b"
tool_call_parser: "hermes"
openai:
- model_name: "Qwen/Qwen3-4B-Instruct-2507"
base_url: "http://localhost:8001/v1"
api_key: "x"
weight: 1.0
num_requests_for_eval: 64
timeout: 600
server_type: "sglang"
slurm: false
testing: false
-1
View File
@@ -298,7 +298,6 @@ class HermesAgentBaseEnv(BaseEnv):
return False
server = self.server.servers[0]
# If the server is an OpenAI server (not VLLM/SGLang), use direct mode
from atroposlib.envs.server_handling.openai_server import OpenAIServer
return not isinstance(server, OpenAIServer)
@@ -48,7 +48,13 @@ class HermesToolCallParser(ToolCallParser):
if not raw_json.strip():
continue
tc_data = json.loads(raw_json)
try:
tc_data = json.loads(raw_json)
except json.JSONDecodeError:
# Fix invalid backslash escapes from shell commands in JSON strings
# e.g. \s \w \d \n (unescaped) → \\s \\w \\d \\n
fixed = re.sub(r'\\([^"\\/bfnrtu0-9\n])', r'\\\\\1', raw_json)
tc_data = json.loads(fixed)
tool_calls.append(
ChatCompletionMessageToolCall(
id=f"call_{uuid.uuid4().hex[:8]}",
+2 -9
View File
@@ -27,16 +27,9 @@ def _coerce_bool(value: Any, default: bool = True) -> bool:
return default
if isinstance(value, bool):
return value
if isinstance(value, int):
return value != 0
if isinstance(value, str):
lowered = value.strip().lower()
if lowered in ("true", "1", "yes", "on"):
return True
if lowered in ("false", "0", "no", "off"):
return False
return default
return default
return value.strip().lower() in ("true", "1", "yes", "on")
return bool(value)
def _normalize_unauthorized_dm_behavior(value: Any, default: str = "pair") -> str:
+4 -164
View File
@@ -49,14 +49,6 @@ _STORE_DIR = _get_hermes_dir("platforms/matrix/store", "matrix/store")
# Grace period: ignore messages older than this many seconds before startup.
_STARTUP_GRACE_SECONDS = 5
# E2EE key export file for persistence across restarts.
_KEY_EXPORT_FILE = _STORE_DIR / "exported_keys.txt"
_KEY_EXPORT_PASSPHRASE = "hermes-matrix-e2ee-keys"
# Pending undecrypted events: cap and TTL for retry buffer.
_MAX_PENDING_EVENTS = 100
_PENDING_EVENT_TTL = 300 # seconds — stop retrying after 5 min
def check_matrix_requirements() -> bool:
"""Return True if the Matrix adapter can be used."""
@@ -119,10 +111,6 @@ class MatrixAdapter(BasePlatformAdapter):
self._processed_events: deque = deque(maxlen=1000)
self._processed_events_set: set = set()
# Buffer for undecrypted events pending key receipt.
# Each entry: (room, event, timestamp)
self._pending_megolm: list = []
def _is_duplicate_event(self, event_id) -> bool:
"""Return True if this event was already processed. Tracks the ID otherwise."""
if not event_id:
@@ -244,16 +232,6 @@ class MatrixAdapter(BasePlatformAdapter):
logger.info("Matrix: E2EE crypto initialized")
except Exception as exc:
logger.warning("Matrix: crypto init issue: %s", exc)
# Import previously exported Megolm keys (survives restarts).
if _KEY_EXPORT_FILE.exists():
try:
await client.import_keys(
str(_KEY_EXPORT_FILE), _KEY_EXPORT_PASSPHRASE,
)
logger.info("Matrix: imported Megolm keys from backup")
except Exception as exc:
logger.debug("Matrix: could not import keys: %s", exc)
elif self._encryption:
logger.warning(
"Matrix: E2EE requested but crypto store is not loaded; "
@@ -308,18 +286,6 @@ class MatrixAdapter(BasePlatformAdapter):
except (asyncio.CancelledError, Exception):
pass
# Export Megolm keys before closing so the next restart can decrypt
# events that used sessions from this run.
if self._client and self._encryption and getattr(self._client, "olm", None):
try:
_STORE_DIR.mkdir(parents=True, exist_ok=True)
await self._client.export_keys(
str(_KEY_EXPORT_FILE), _KEY_EXPORT_PASSPHRASE,
)
logger.info("Matrix: exported Megolm keys for next restart")
except Exception as exc:
logger.debug("Matrix: could not export keys on disconnect: %s", exc)
if self._client:
await self._client.close()
self._client = None
@@ -699,22 +665,17 @@ class MatrixAdapter(BasePlatformAdapter):
Hermes uses a custom sync loop instead of matrix-nio's sync_forever(),
so we need to explicitly drive the key management work that sync_forever()
normally handles for encrypted rooms.
Also auto-trusts all devices (so senders share session keys with us)
and retries decryption for any buffered MegolmEvents.
"""
client = self._client
if not client or not self._encryption or not getattr(client, "olm", None):
return
did_query_keys = client.should_query_keys
tasks = [asyncio.create_task(client.send_to_device_messages())]
if client.should_upload_keys:
tasks.append(asyncio.create_task(client.keys_upload()))
if did_query_keys:
if client.should_query_keys:
tasks.append(asyncio.create_task(client.keys_query()))
if client.should_claim_keys:
@@ -730,111 +691,6 @@ class MatrixAdapter(BasePlatformAdapter):
except Exception as exc:
logger.warning("Matrix: E2EE maintenance task failed: %s", exc)
# After key queries, auto-trust all devices so senders share keys with
# us. For a bot this is the right default — we want to decrypt
# everything, not enforce manual verification.
if did_query_keys:
self._auto_trust_devices()
# Retry any buffered undecrypted events now that new keys may have
# arrived (from key requests, key queries, or to-device forwarding).
if self._pending_megolm:
await self._retry_pending_decryptions()
def _auto_trust_devices(self) -> None:
"""Trust/verify all unverified devices we know about.
When other clients see our device as verified, they proactively share
Megolm session keys with us. Without this, many clients will refuse
to include an unverified device in key distributions.
"""
client = self._client
if not client:
return
device_store = getattr(client, "device_store", None)
if not device_store:
return
own_device = getattr(client, "device_id", None)
trusted_count = 0
try:
# DeviceStore.__iter__ yields OlmDevice objects directly.
for device in device_store:
if getattr(device, "device_id", None) == own_device:
continue
if not getattr(device, "verified", False):
client.verify_device(device)
trusted_count += 1
except Exception as exc:
logger.debug("Matrix: auto-trust error: %s", exc)
if trusted_count:
logger.info("Matrix: auto-trusted %d new device(s)", trusted_count)
async def _retry_pending_decryptions(self) -> None:
"""Retry decrypting buffered MegolmEvents after new keys arrive."""
import nio
client = self._client
if not client or not self._pending_megolm:
return
now = time.time()
still_pending: list = []
for room, event, ts in self._pending_megolm:
# Drop events that have aged past the TTL.
if now - ts > _PENDING_EVENT_TTL:
logger.debug(
"Matrix: dropping expired pending event %s (age %.0fs)",
getattr(event, "event_id", "?"), now - ts,
)
continue
try:
decrypted = client.decrypt_event(event)
except Exception:
# Still missing the key — keep in buffer.
still_pending.append((room, event, ts))
continue
if isinstance(decrypted, nio.MegolmEvent):
# decrypt_event returned the same undecryptable event.
still_pending.append((room, event, ts))
continue
logger.info(
"Matrix: decrypted buffered event %s (%s)",
getattr(event, "event_id", "?"),
type(decrypted).__name__,
)
# Route to the appropriate handler based on decrypted type.
try:
if isinstance(decrypted, nio.RoomMessageText):
await self._on_room_message(room, decrypted)
elif isinstance(
decrypted,
(nio.RoomMessageImage, nio.RoomMessageAudio,
nio.RoomMessageVideo, nio.RoomMessageFile),
):
await self._on_room_message_media(room, decrypted)
else:
logger.debug(
"Matrix: decrypted event %s has unhandled type %s",
getattr(event, "event_id", "?"),
type(decrypted).__name__,
)
except Exception as exc:
logger.warning(
"Matrix: error processing decrypted event %s: %s",
getattr(event, "event_id", "?"), exc,
)
self._pending_megolm = still_pending
# ------------------------------------------------------------------
# Event callbacks
# ------------------------------------------------------------------
@@ -856,29 +712,13 @@ class MatrixAdapter(BasePlatformAdapter):
if event_ts and event_ts < self._startup_ts - _STARTUP_GRACE_SECONDS:
return
# Handle undecryptable MegolmEvents: request the missing session key
# and buffer the event for retry once the key arrives.
# Handle decrypted MegolmEvents — extract the inner event.
if isinstance(event, nio.MegolmEvent):
# Failed to decrypt.
logger.warning(
"Matrix: could not decrypt event %s in %s — requesting key",
"Matrix: could not decrypt event %s in %s",
event.event_id, room.room_id,
)
# Ask other devices in the room to forward the session key.
try:
resp = await self._client.request_room_key(event)
if hasattr(resp, "event_id") or not isinstance(resp, Exception):
logger.debug(
"Matrix: room key request sent for session %s",
getattr(event, "session_id", "?"),
)
except Exception as exc:
logger.debug("Matrix: room key request failed: %s", exc)
# Buffer for retry on next maintenance cycle.
self._pending_megolm.append((room, event, time.time()))
if len(self._pending_megolm) > _MAX_PENDING_EVENTS:
self._pending_megolm = self._pending_megolm[-_MAX_PENDING_EVENTS:]
return
# Skip edits (m.replace relation).
+2 -11
View File
@@ -622,19 +622,10 @@ class TelegramAdapter(BasePlatformAdapter):
# gateway command there automatically adds it to the Telegram menu.
try:
from telegram import BotCommand
from hermes_cli.commands import telegram_menu_commands
# Telegram allows up to 100 commands but has an undocumented
# payload size limit. Skill descriptions are truncated to 40
# chars in telegram_menu_commands() to fit 100 commands safely.
menu_commands, hidden_count = telegram_menu_commands(max_commands=100)
from hermes_cli.commands import telegram_bot_commands
await self._bot.set_my_commands([
BotCommand(name, desc) for name, desc in menu_commands
BotCommand(name, desc) for name, desc in telegram_bot_commands()
])
if hidden_count:
logger.info(
"[%s] Telegram menu: %d commands registered, %d hidden (over 100 limit). Use /commands for full list.",
self.name, len(menu_commands), hidden_count,
)
except Exception as e:
logger.warning(
"[%s] Could not register Telegram command menu: %s",
+4 -205
View File
@@ -301,50 +301,6 @@ def _resolve_runtime_agent_kwargs() -> dict:
}
def _check_unavailable_skill(command_name: str) -> str | None:
"""Check if a command matches a known-but-inactive skill.
Returns a helpful message if the skill exists but is disabled or only
available as an optional install. Returns None if no match found.
"""
# Normalize: command uses hyphens, skill names may use hyphens or underscores
normalized = command_name.lower().replace("_", "-")
try:
from tools.skills_tool import SKILLS_DIR, _get_disabled_skill_names
disabled = _get_disabled_skill_names()
# Check disabled built-in skills
for skill_md in SKILLS_DIR.rglob("SKILL.md"):
if any(part in ('.git', '.github', '.hub') for part in skill_md.parts):
continue
name = skill_md.parent.name.lower().replace("_", "-")
if name == normalized and name in disabled:
return (
f"The **{command_name}** skill is installed but disabled.\n"
f"Enable it with: `hermes skills config`"
)
# Check optional skills (shipped with repo but not installed)
from hermes_constants import get_hermes_home
repo_root = Path(__file__).resolve().parent.parent
optional_dir = repo_root / "optional-skills"
if optional_dir.exists():
for skill_md in optional_dir.rglob("SKILL.md"):
name = skill_md.parent.name.lower().replace("_", "-")
if name == normalized:
# Build install path: official/<category>/<name>
rel = skill_md.parent.relative_to(optional_dir)
parts = list(rel.parts)
install_path = f"official/{'/'.join(parts)}"
return (
f"The **{command_name}** skill is available but not installed.\n"
f"Install it with: `hermes skills install {install_path}`"
)
except Exception:
pass
return None
def _platform_config_key(platform: "Platform") -> str:
"""Map a Platform enum to its config.yaml key (LOCAL→"cli", rest→enum value)."""
return "cli" if platform == Platform.LOCAL else platform.value
@@ -476,13 +432,6 @@ class GatewayRunner:
self._honcho_managers: Dict[str, Any] = {}
self._honcho_configs: Dict[str, Any] = {}
# Rate-limit compression warning messages sent to users.
# Keyed by chat_id — value is the timestamp of the last warning sent.
# Prevents the warning from firing on every message when a session
# remains above the threshold after compression.
self._compression_warn_sent: Dict[str, float] = {}
self._compression_warn_cooldown: int = 3600 # seconds (1 hour)
# Ensure tirith security scanner is available (downloads if needed)
try:
from tools.tirith_security import ensure_installed
@@ -1702,11 +1651,6 @@ class GatewayRunner:
# In DMs: offer pairing code. In groups: silently ignore.
if source.chat_type == "dm" and self._get_unauthorized_dm_behavior(source.platform) == "pair":
platform_name = source.platform.value if source.platform else "unknown"
# Rate-limit ALL pairing responses (code or rejection) to
# prevent spamming the user with repeated messages when
# multiple DMs arrive in quick succession.
if self.pairing_store._is_rate_limited(platform_name, source.user_id):
return None
code = self.pairing_store.generate_code(
platform_name, source.user_id, source.user_name or ""
)
@@ -1728,8 +1672,6 @@ class GatewayRunner:
"Too many pairing requests right now~ "
"Please try again later!"
)
# Record rate limit so subsequent messages are silently ignored
self.pairing_store._record_rate_limit(platform_name, source.user_id)
return None
# PRIORITY handling when an agent is already running for this session.
@@ -1875,13 +1817,7 @@ class GatewayRunner:
if canonical == "help":
return await self._handle_help_command(event)
if canonical == "commands":
return await self._handle_commands_command(event)
if canonical == "profile":
return await self._handle_profile_command(event)
if canonical == "status":
return await self._handle_status_command(event)
@@ -1894,9 +1830,6 @@ class GatewayRunner:
if canonical == "verbose":
return await self._handle_verbose_command(event)
if canonical == "yolo":
return await self._handle_yolo_command(event)
if canonical == "provider":
return await self._handle_provider_command(event)
@@ -2041,12 +1974,6 @@ class GatewayRunner:
if msg:
event.text = msg
# Fall through to normal message processing with skill content
else:
# Not an active skill — check if it's a known-but-disabled or
# uninstalled skill and give actionable guidance.
_unavail_msg = _check_unavailable_skill(command)
if _unavail_msg:
return _unavail_msg
except Exception as e:
logger.debug("Skill command check failed (non-fatal): %s", e)
@@ -2284,29 +2211,6 @@ class GatewayRunner:
_hyg_api_key = _hyg_runtime.get("api_key")
except Exception:
pass
# Check custom_providers per-model context_length
# (same fallback as run_agent.py lines 1171-1189).
# Must run after runtime resolution so _hyg_base_url is set.
if _hyg_config_context_length is None and _hyg_base_url:
try:
_hyg_custom_providers = _hyg_data.get("custom_providers")
if isinstance(_hyg_custom_providers, list):
for _cp in _hyg_custom_providers:
if not isinstance(_cp, dict):
continue
_cp_url = (_cp.get("base_url") or "").rstrip("/")
if _cp_url and _cp_url == _hyg_base_url.rstrip("/"):
_cp_models = _cp.get("models", {})
if isinstance(_cp_models, dict):
_cp_model_cfg = _cp_models.get(_hyg_model, {})
if isinstance(_cp_model_cfg, dict):
_cp_ctx = _cp_model_cfg.get("context_length")
if _cp_ctx is not None:
_hyg_config_context_length = int(_cp_ctx)
break
except (TypeError, ValueError):
pass
except Exception:
pass
@@ -2440,18 +2344,13 @@ class GatewayRunner:
pass
# Still too large after compression — warn user
# Rate-limited to once per cooldown period per
# chat to avoid spamming on every message.
if _new_tokens >= _warn_token_threshold:
logger.warning(
"Session hygiene: still ~%s tokens after "
"compression — suggesting /reset",
f"{_new_tokens:,}",
)
_now = time.time()
_last_warn = self._compression_warn_sent.get(source.chat_id, 0)
if _hyg_adapter and _now - _last_warn >= self._compression_warn_cooldown:
self._compression_warn_sent[source.chat_id] = _now
if _hyg_adapter:
try:
await _hyg_adapter.send(
source.chat_id,
@@ -2473,10 +2372,7 @@ class GatewayRunner:
if _approx_tokens >= _warn_token_threshold:
_hyg_adapter = self.adapters.get(source.platform)
_hyg_meta = {"thread_id": source.thread_id} if source.thread_id else None
_now = time.time()
_last_warn = self._compression_warn_sent.get(source.chat_id, 0)
if _hyg_adapter and _now - _last_warn >= self._compression_warn_cooldown:
self._compression_warn_sent[source.chat_id] = _now
if _hyg_adapter:
try:
await _hyg_adapter.send(
source.chat_id,
@@ -3103,36 +2999,6 @@ class GatewayRunner:
return f"{header}\n\n{session_info}"
return header
async def _handle_profile_command(self, event: MessageEvent) -> str:
"""Handle /profile — show active profile name and home directory."""
from hermes_constants import get_hermes_home, display_hermes_home
from pathlib import Path
home = get_hermes_home()
display = display_hermes_home()
# Detect profile name from HERMES_HOME path
# Profile paths look like: ~/.hermes/profiles/<name>
profiles_parent = Path.home() / ".hermes" / "profiles"
try:
rel = home.relative_to(profiles_parent)
profile_name = str(rel).split("/")[0]
except ValueError:
profile_name = None
if profile_name:
lines = [
f"👤 **Profile:** `{profile_name}`",
f"📂 **Home:** `{display}`",
]
else:
lines = [
"👤 **Profile:** default",
f"📂 **Home:** `{display}`",
]
return "\n".join(lines)
async def _handle_status_command(self, event: MessageEvent) -> str:
"""Handle /status command."""
source = event.source
@@ -3199,68 +3065,11 @@ class GatewayRunner:
from agent.skill_commands import get_skill_commands
skill_cmds = get_skill_commands()
if skill_cmds:
lines.append(f"\n⚡ **Skill Commands** ({len(skill_cmds)} active):")
# Show first 10, then point to /commands for the rest
sorted_cmds = sorted(skill_cmds)
for cmd in sorted_cmds[:10]:
lines.append(f"`{cmd}` — {skill_cmds[cmd]['description']}")
if len(sorted_cmds) > 10:
lines.append(f"\n... and {len(sorted_cmds) - 10} more. Use `/commands` for the full paginated list.")
except Exception:
pass
return "\n".join(lines)
async def _handle_commands_command(self, event: MessageEvent) -> str:
"""Handle /commands [page] - paginated list of all commands and skills."""
from hermes_cli.commands import gateway_help_lines
raw_args = event.get_command_args().strip()
if raw_args:
try:
requested_page = int(raw_args)
except ValueError:
return "Usage: `/commands [page]`"
else:
requested_page = 1
# Build combined entry list: built-in commands + skill commands
entries = list(gateway_help_lines())
try:
from agent.skill_commands import get_skill_commands
skill_cmds = get_skill_commands()
if skill_cmds:
entries.append("")
entries.append("⚡ **Skill Commands**:")
lines.append(f"\n⚡ **Skill Commands** ({len(skill_cmds)} installed):")
for cmd in sorted(skill_cmds):
desc = skill_cmds[cmd].get("description", "").strip() or "Skill command"
entries.append(f"`{cmd}` — {desc}")
lines.append(f"`{cmd}` — {skill_cmds[cmd]['description']}")
except Exception:
pass
if not entries:
return "No commands available."
from gateway.config import Platform
page_size = 15 if event.source.platform == Platform.TELEGRAM else 20
total_pages = max(1, (len(entries) + page_size - 1) // page_size)
page = max(1, min(requested_page, total_pages))
start = (page - 1) * page_size
page_entries = entries[start:start + page_size]
lines = [
f"📚 **Commands** ({len(entries)} total, page {page}/{total_pages})",
"",
*page_entries,
]
if total_pages > 1:
nav_parts = []
if page > 1:
nav_parts.append(f"`/commands {page - 1}` ← prev")
if page < total_pages:
nav_parts.append(f"next → `/commands {page + 1}`")
lines.extend(["", " | ".join(nav_parts)])
if page != requested_page:
lines.append(f"_(Requested page {requested_page} was out of range, showing page {page}.)_")
return "\n".join(lines)
async def _handle_provider_command(self, event: MessageEvent) -> str:
@@ -4190,16 +3999,6 @@ class GatewayRunner:
else:
return f"🧠 ✓ Reasoning effort set to `{effort}` (this session only)"
async def _handle_yolo_command(self, event: MessageEvent) -> str:
"""Handle /yolo — toggle dangerous command approval bypass."""
current = bool(os.environ.get("HERMES_YOLO_MODE"))
if current:
os.environ.pop("HERMES_YOLO_MODE", None)
return "⚠️ YOLO mode **OFF** — dangerous commands will require approval."
else:
os.environ["HERMES_YOLO_MODE"] = "1"
return "⚡ YOLO mode **ON** — all commands auto-approved. Use with caution."
async def _handle_verbose_command(self, event: MessageEvent) -> str:
"""Handle /verbose command — cycle tool progress display mode.
+2 -18
View File
@@ -1,24 +1,8 @@
"""Shared ANSI color utilities for Hermes CLI modules."""
import os
import sys
def should_use_color() -> bool:
"""Return True when colored output is appropriate.
Respects the NO_COLOR environment variable (https://no-color.org/)
and TERM=dumb, in addition to the existing TTY check.
"""
if os.environ.get("NO_COLOR") is not None:
return False
if os.environ.get("TERM") == "dumb":
return False
if not sys.stdout.isatty():
return False
return True
class Colors:
RESET = "\033[0m"
BOLD = "\033[1m"
@@ -32,7 +16,7 @@ class Colors:
def color(text: str, *codes) -> str:
"""Apply color codes to text (only when color output is appropriate)."""
if not should_use_color():
"""Apply color codes to text (only when output is a TTY)."""
if not sys.stdout.isatty():
return text
return "".join(codes) + text + Colors.RESET
-68
View File
@@ -71,7 +71,6 @@ COMMAND_REGISTRY: list[CommandDef] = [
aliases=("q",), args_hint="<prompt>"),
CommandDef("status", "Show session info", "Session",
gateway_only=True),
CommandDef("profile", "Show active profile name and home directory", "Info"),
CommandDef("sethome", "Set this chat as the home channel", "Session",
gateway_only=True, aliases=("set-home",)),
CommandDef("resume", "Resume a previously-named session", "Session",
@@ -91,8 +90,6 @@ COMMAND_REGISTRY: list[CommandDef] = [
CommandDef("verbose", "Cycle tool progress display: off -> new -> all -> verbose",
"Configuration", cli_only=True,
gateway_config_gate="display.tool_progress_command"),
CommandDef("yolo", "Toggle YOLO mode (skip all dangerous command approvals)",
"Configuration"),
CommandDef("reasoning", "Manage reasoning effort and display", "Configuration",
args_hint="[level|show|hide]",
subcommands=("none", "low", "minimal", "medium", "high", "xhigh", "show", "hide", "on", "off")),
@@ -121,8 +118,6 @@ COMMAND_REGISTRY: list[CommandDef] = [
"Tools & Skills", cli_only=True),
# Info
CommandDef("commands", "Browse all commands and skills (paginated)", "Info",
gateway_only=True, args_hint="[page]"),
CommandDef("help", "Show available commands", "Info"),
CommandDef("usage", "Show token usage for the current session", "Info"),
CommandDef("insights", "Show usage insights and analytics", "Info",
@@ -366,69 +361,6 @@ def telegram_bot_commands() -> list[tuple[str, str]]:
return result
def telegram_menu_commands(max_commands: int = 100) -> tuple[list[tuple[str, str]], int]:
"""Return Telegram menu commands capped to the Bot API limit.
Priority order (higher priority = never bumped by overflow):
1. Core CommandDef commands (always included)
2. Plugin slash commands (take precedence over skills)
3. Built-in skill commands (fill remaining slots, alphabetical)
Skills are the only tier that gets trimmed when the cap is hit.
User-installed hub skills are excluded accessible via /skills.
Returns:
(menu_commands, hidden_count) where hidden_count is the number of
skill commands omitted due to the cap.
"""
all_commands = list(telegram_bot_commands())
# Plugin slash commands get priority over skills
try:
from hermes_cli.plugins import get_plugin_manager
pm = get_plugin_manager()
plugin_cmds = getattr(pm, "_plugin_commands", {})
for cmd_name in sorted(plugin_cmds):
tg_name = cmd_name.replace("-", "_")
desc = "Plugin command"
if len(desc) > 40:
desc = desc[:37] + "..."
all_commands.append((tg_name, desc))
except Exception:
pass
# Remaining slots go to built-in skill commands (not hub-installed).
skill_entries: list[tuple[str, str]] = []
try:
from agent.skill_commands import get_skill_commands
from tools.skills_tool import SKILLS_DIR
_skills_dir = str(SKILLS_DIR.resolve())
_hub_dir = str((SKILLS_DIR / ".hub").resolve())
skill_cmds = get_skill_commands()
for cmd_key in sorted(skill_cmds):
info = skill_cmds[cmd_key]
skill_path = info.get("skill_md_path", "")
if not skill_path.startswith(_skills_dir):
continue
if skill_path.startswith(_hub_dir):
continue
name = cmd_key.lstrip("/").replace("-", "_")
desc = info.get("description", "")
# Keep descriptions short — setMyCommands has an undocumented
# total payload limit. 40 chars fits 100 commands safely.
if len(desc) > 40:
desc = desc[:37] + "..."
skill_entries.append((name, desc))
except Exception:
pass
# Skills fill remaining slots — they're the only tier that gets trimmed
remaining_slots = max(0, max_commands - len(all_commands))
hidden_count = max(0, len(skill_entries) - remaining_slots)
all_commands.extend(skill_entries[:remaining_slots])
return all_commands[:max_commands], hidden_count
def slack_subcommand_map() -> dict[str, str]:
"""Return subcommand -> /command mapping for Slack /hermes handler.
-8
View File
@@ -706,14 +706,6 @@ OPTIONAL_ENV_VARS = {
"password": True,
"category": "tool",
},
"CAMOFOX_URL": {
"description": "Camofox browser server URL for local anti-detection browsing (e.g. http://localhost:9377)",
"prompt": "Camofox server URL",
"url": "https://github.com/jo-inc/camofox-browser",
"tools": ["browser_navigate", "browser_click"],
"password": False,
"category": "tool",
},
"FAL_KEY": {
"description": "FAL API key for image generation",
"prompt": "FAL API key",
+8 -15
View File
@@ -406,11 +406,8 @@ def run_doctor(args):
if terminal_env == "docker":
if shutil.which("docker"):
# Check if docker daemon is running
try:
result = subprocess.run(["docker", "info"], capture_output=True, timeout=10)
except subprocess.TimeoutExpired:
result = None
if result is not None and result.returncode == 0:
result = subprocess.run(["docker", "info"], capture_output=True)
if result.returncode == 0:
check_ok("docker", "(daemon running)")
else:
check_fail("docker daemon not running")
@@ -429,16 +426,12 @@ def run_doctor(args):
ssh_host = os.getenv("TERMINAL_SSH_HOST")
if ssh_host:
# Try to connect
try:
result = subprocess.run(
["ssh", "-o", "ConnectTimeout=5", "-o", "BatchMode=yes", ssh_host, "echo ok"],
capture_output=True,
text=True,
timeout=15
)
except subprocess.TimeoutExpired:
result = None
if result is not None and result.returncode == 0:
result = subprocess.run(
["ssh", "-o", "ConnectTimeout=5", "-o", "BatchMode=yes", ssh_host, "echo ok"],
capture_output=True,
text=True
)
if result.returncode == 0:
check_ok(f"SSH connection to {ssh_host}")
else:
check_fail(f"SSH connection to {ssh_host}")
+2 -4
View File
@@ -601,15 +601,13 @@ def _print_setup_summary(config: dict, hermes_home):
Path(__file__).parent.parent / "node_modules" / ".bin" / "agent-browser"
).exists()
)
if get_env_value("CAMOFOX_URL"):
tool_status.append(("Browser Automation (Camofox)", True, None))
elif get_env_value("BROWSERBASE_API_KEY"):
if get_env_value("BROWSERBASE_API_KEY"):
tool_status.append(("Browser Automation (Browserbase)", True, None))
elif _ab_found:
tool_status.append(("Browser Automation (local)", True, None))
else:
tool_status.append(
("Browser Automation", False, "npm install -g agent-browser or set CAMOFOX_URL")
("Browser Automation", False, "npm install -g agent-browser")
)
# FAL (image generation)
+12 -20
View File
@@ -285,31 +285,23 @@ def show_status(args):
_gw_svc = get_service_name()
except Exception:
_gw_svc = "hermes-gateway"
try:
result = subprocess.run(
["systemctl", "--user", "is-active", _gw_svc],
capture_output=True,
text=True,
timeout=5
)
is_active = result.stdout.strip() == "active"
except subprocess.TimeoutExpired:
is_active = False
result = subprocess.run(
["systemctl", "--user", "is-active", _gw_svc],
capture_output=True,
text=True
)
is_active = result.stdout.strip() == "active"
print(f" Status: {check_mark(is_active)} {'running' if is_active else 'stopped'}")
print(" Manager: systemd (user)")
elif sys.platform == 'darwin':
from hermes_cli.gateway import get_launchd_label
try:
result = subprocess.run(
["launchctl", "list", get_launchd_label()],
capture_output=True,
text=True,
timeout=5
)
is_loaded = result.returncode == 0
except subprocess.TimeoutExpired:
is_loaded = False
result = subprocess.run(
["launchctl", "list", get_launchd_label()],
capture_output=True,
text=True
)
is_loaded = result.returncode == 0
print(f" Status: {check_mark(is_loaded)} {'loaded' if is_loaded else 'not loaded'}")
print(" Manager: launchd")
else:
+1 -35
View File
@@ -273,16 +273,6 @@ TOOL_CATEGORIES = {
"browser_provider": "browser-use",
"post_setup": "browserbase",
},
{
"name": "Camofox",
"tag": "Local anti-detection browser (Firefox/Camoufox)",
"env_vars": [
{"key": "CAMOFOX_URL", "prompt": "Camofox server URL", "default": "http://localhost:9377",
"url": "https://github.com/jo-inc/camofox-browser"},
],
"browser_provider": "camofox",
"post_setup": "camofox",
},
],
},
"homeassistant": {
@@ -347,28 +337,6 @@ def _run_post_setup(post_setup_key: str):
elif not node_modules.exists():
_print_warning(" Node.js not found - browser tools require: npm install (in hermes-agent directory)")
elif post_setup_key == "camofox":
camofox_dir = PROJECT_ROOT / "node_modules" / "@askjo" / "camoufox-browser"
if not camofox_dir.exists() and shutil.which("npm"):
_print_info(" Installing Camofox browser server...")
import subprocess
result = subprocess.run(
["npm", "install", "--silent"],
capture_output=True, text=True, cwd=str(PROJECT_ROOT)
)
if result.returncode == 0:
_print_success(" Camofox installed")
else:
_print_warning(" npm install failed - run manually: npm install")
if camofox_dir.exists():
_print_info(" Start the Camofox server:")
_print_info(" npx @askjo/camoufox-browser")
_print_info(" First run downloads the Camoufox engine (~300MB)")
_print_info(" Or use Docker: docker run -p 9377:9377 jo-inc/camofox-browser")
elif not shutil.which("npm"):
_print_warning(" Node.js not found. Install Camofox via Docker:")
_print_info(" docker run -p 9377:9377 jo-inc/camofox-browser")
elif post_setup_key == "rl_training":
try:
__import__("tinker_atropos")
@@ -597,9 +565,7 @@ def _toolset_has_keys(ts_key: str) -> bool:
if cat:
for provider in cat.get("providers", []):
env_vars = provider.get("env_vars", [])
if not env_vars:
return True # No-key provider (e.g. Local Browser, Edge TTS)
if all(get_env_value(e["key"]) for e in env_vars):
if env_vars and all(get_env_value(e["key"]) for e in env_vars):
return True
return False
+8 -22
View File
@@ -10,27 +10,16 @@ import os
import sys
from pathlib import Path
from hermes_constants import get_hermes_home
from honcho_integration.client import resolve_config_path, GLOBAL_CONFIG_PATH
HOST = "hermes"
def _config_path() -> Path:
"""Return the active Honcho config path for reading (instance-local or global)."""
"""Return the active Honcho config path (instance-local or global)."""
return resolve_config_path()
def _local_config_path() -> Path:
"""Return the instance-local Honcho config path for writing.
Always returns $HERMES_HOME/honcho.json so each profile/instance gets
its own config file. The global ~/.honcho/config.json is only used as
a read fallback (via resolve_config_path) for cross-app interop.
"""
return get_hermes_home() / "honcho.json"
def _read_config() -> dict:
path = _config_path()
if path.exists():
@@ -42,7 +31,7 @@ def _read_config() -> dict:
def _write_config(cfg: dict, path: Path | None = None) -> None:
path = path or _local_config_path()
path = path or _config_path()
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(
json.dumps(cfg, indent=2, ensure_ascii=False) + "\n",
@@ -106,13 +95,13 @@ def cmd_setup(args) -> None:
"""Interactive Honcho setup wizard."""
cfg = _read_config()
write_path = _local_config_path()
read_path = _config_path()
active_path = _config_path()
print("\nHoncho memory setup\n" + "" * 40)
print(" Honcho gives Hermes persistent cross-session memory.")
print(f" Config: {write_path}")
if read_path != write_path and read_path.exists():
print(f" (seeding from existing config at {read_path})")
if active_path != GLOBAL_CONFIG_PATH:
print(f" Instance config: {active_path}")
else:
print(" Config is shared with other hosts at ~/.honcho/config.json")
print()
if not _ensure_sdk_installed():
@@ -200,7 +189,7 @@ def cmd_setup(args) -> None:
hermes_host.setdefault("saveMessages", True)
_write_config(cfg)
print(f"\n Config written to {write_path}")
print(f"\n Config written to {active_path}")
# Test connection
print(" Testing connection... ", end="", flush=True)
@@ -248,7 +237,6 @@ def cmd_status(args) -> None:
cfg = _read_config()
active_path = _config_path()
write_path = _local_config_path()
if not cfg:
print(f" No Honcho config found at {active_path}")
@@ -271,8 +259,6 @@ def cmd_status(args) -> None:
print(f" Workspace: {hcfg.workspace_id}")
print(f" Host: {hcfg.host}")
print(f" Config path: {active_path}")
if write_path != active_path:
print(f" Write path: {write_path} (instance-local)")
print(f" AI peer: {hcfg.ai_peer}")
print(f" User peer: {hcfg.peer_name or 'not set'}")
print(f" Session key: {hcfg.resolve_session_name()}")
+1 -2
View File
@@ -16,8 +16,7 @@
},
"homepage": "https://github.com/NousResearch/Hermes-Agent#readme",
"dependencies": {
"agent-browser": "^0.13.0",
"@askjo/camoufox-browser": "^1.0.0"
"agent-browser": "^0.13.0"
},
"engines": {
"node": ">=18.0.0"
+5 -12
View File
@@ -5221,8 +5221,11 @@ class AIAgent:
except Exception as e:
logger.warning("Session DB compression split failed — new session will NOT be indexed: %s", e)
# Update token estimate after compaction so pressure calculations
# use the post-compression count, not the stale pre-compression one.
# Reset context pressure warning and token estimate — usage drops
# after compaction. Without this, the stale last_prompt_tokens from
# the previous API call causes the pressure calculation to stay at
# >1000% and spam warnings / re-trigger compression in a loop.
self._context_pressure_warned = False
_compressed_est = (
estimate_tokens_rough(new_system_prompt)
+ estimate_messages_tokens_rough(compressed)
@@ -5230,16 +5233,6 @@ class AIAgent:
self.context_compressor.last_prompt_tokens = _compressed_est
self.context_compressor.last_completion_tokens = 0
# Only reset the pressure warning if compression actually brought
# us below the warning level (85% of threshold). When compression
# can't reduce enough (e.g. threshold is very low, or system prompt
# alone exceeds the warning level), keep the flag set to prevent
# spamming the user with repeated warnings every loop iteration.
if self.context_compressor.threshold_tokens > 0:
_post_progress = _compressed_est / self.context_compressor.threshold_tokens
if _post_progress < 0.85:
self._context_pressure_warned = False
return compressed, new_system_prompt
def _execute_tool_calls(self, assistant_message, messages: list, effective_task_id: str, api_call_count: int = 0) -> None:
+3 -15
View File
@@ -94,7 +94,7 @@ print_banner() {
echo ""
echo -e "${MAGENTA}${BOLD}"
echo "┌─────────────────────────────────────────────────────────┐"
echo "│ ⚕ Hermes Agent Installer │"
echo "│ ⚕ Hermes Agent Installer │"
echo "├─────────────────────────────────────────────────────────┤"
echo "│ An open source AI agent by Nous Research. │"
echo "└─────────────────────────────────────────────────────────┘"
@@ -699,19 +699,14 @@ install_deps() {
# Install the main package in editable mode with all extras.
# Try [all] first, fall back to base install if extras have issues.
ALL_INSTALL_LOG=$(mktemp)
if ! $UV_CMD pip install -e ".[all]" 2>"$ALL_INSTALL_LOG"; then
if ! $UV_CMD pip install -e ".[all]" 2>/dev/null; then
log_warn "Full install (.[all]) failed, trying base install..."
log_info "Reason: $(tail -5 "$ALL_INSTALL_LOG" | head -3)"
rm -f "$ALL_INSTALL_LOG"
if ! $UV_CMD pip install -e "."; then
log_error "Package installation failed."
log_info "Check that build tools are installed: sudo apt install build-essential python3-dev"
log_info "Then re-run: cd $INSTALL_DIR && uv pip install -e '.[all]'"
exit 1
fi
else
rm -f "$ALL_INSTALL_LOG"
fi
log_success "Main package installed"
@@ -1075,14 +1070,7 @@ print_success() {
echo ""
echo -e "${YELLOW}⚡ Reload your shell to use 'hermes' command:${NC}"
echo ""
LOGIN_SHELL="$(basename "${SHELL:-/bin/bash}")"
if [ "$LOGIN_SHELL" = "zsh" ]; then
echo " source ~/.zshrc"
elif [ "$LOGIN_SHELL" = "bash" ]; then
echo " source ~/.bashrc"
else
echo " source ~/.bashrc # or ~/.zshrc"
fi
echo " source ~/.bashrc # or ~/.zshrc"
echo ""
# Show Node.js warning if auto-install failed
@@ -744,149 +744,3 @@ class PixelBlendStack:
result = blend_canvas(result, canvas, mode, opacity)
return result
```
## Text Backdrop (Readability Mask)
When placing readable text over busy multi-grid ASCII backgrounds, the text will blend into the background and become illegible. **Always apply a dark backdrop behind text regions.**
The technique: compute the bounding box of all text glyphs, create a gaussian-blurred dark mask covering that area with padding, and multiply the background by `(1 - mask * darkness)` before rendering text on top.
```python
from scipy.ndimage import gaussian_filter
def apply_text_backdrop(canvas, glyphs, padding=80, darkness=0.75):
"""Darken the background behind text for readability.
Call AFTER rendering background, BEFORE rendering text.
Args:
canvas: (VH, VW, 3) uint8 background
glyphs: list of {"x": float, "y": float, ...} glyph positions
padding: pixel padding around text bounding box
darkness: 0.0 = no darkening, 1.0 = fully black
Returns:
darkened canvas (uint8)
"""
if not glyphs:
return canvas
xs = [g['x'] for g in glyphs]
ys = [g['y'] for g in glyphs]
x0 = max(0, int(min(xs)) - padding)
y0 = max(0, int(min(ys)) - padding)
x1 = min(VW, int(max(xs)) + padding + 50) # extra for char width
y1 = min(VH, int(max(ys)) + padding + 60) # extra for char height
# Soft dark mask with gaussian blur for feathered edges
mask = np.zeros((VH, VW), dtype=np.float32)
mask[y0:y1, x0:x1] = 1.0
mask = gaussian_filter(mask, sigma=padding * 0.6)
factor = 1.0 - mask * darkness
return (canvas.astype(np.float32) * factor[:, :, np.newaxis]).astype(np.uint8)
```
### Usage in render pipeline
Insert between background rendering and text rendering:
```python
# 1. Render background (multi-grid ASCII effects)
bg = render_background(cfg, t)
# 2. Darken behind text region
bg = apply_text_backdrop(bg, frame_glyphs, padding=80, darkness=0.75)
# 3. Render text on top (now readable against dark backdrop)
bg = text_renderer.render(bg, frame_glyphs, color=(255, 255, 255))
```
Combine with **reverse vignette** (see shaders.md) for scenes where text is always centered — the reverse vignette provides a persistent center-dark zone, while the backdrop handles per-frame glyph positions.
## External Layout Oracle Pattern
For text-heavy videos where text needs to dynamically reflow around obstacles (shapes, icons, other text), use an external layout engine to pre-compute glyph positions and feed them into the Python renderer via JSON.
### Architecture
```
Layout Engine (browser/Node.js) → layouts.json → Python ASCII Renderer
↑ ↑
Computes per-frame Reads glyph positions,
glyph (x,y) positions renders as ASCII chars
with obstacle-aware reflow with full effect pipeline
```
### JSON interchange format
```json
{
"meta": {
"canvas_width": 1080, "canvas_height": 1080,
"fps": 24, "total_frames": 1248,
"fonts": {
"body": {"charW": 12.04, "charH": 24, "fontSize": 20},
"hero": {"charW": 24.08, "charH": 48, "fontSize": 40}
}
},
"scenes": [
{
"id": "scene_name",
"start_frame": 0, "end_frame": 96,
"frames": {
"0": {
"glyphs": [
{"char": "H", "x": 287.1, "y": 400.0, "alpha": 1.0},
{"char": "e", "x": 311.2, "y": 400.0, "alpha": 1.0}
],
"obstacles": [
{"type": "circle", "cx": 540, "cy": 540, "r": 80},
{"type": "rect", "x": 300, "y": 500, "w": 120, "h": 80}
]
}
}
}
]
}
```
### When to use
- Text that dynamically reflows around moving objects
- Per-glyph animation (reveal, scatter, physics)
- Variable typography that needs precise measurement
- Any case where Python's Pillow text layout is insufficient
### When NOT to use
- Static centered text (just use PIL `draw.text()` directly)
- Text that only fades in/out without spatial animation
- Simple typewriter effects (handle in Python with a character counter)
### Running the oracle
Use Playwright to run the layout engine in a headless browser:
```javascript
// extract.mjs
import { chromium } from 'playwright';
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.goto(`file://${oraclePath}`);
await page.waitForFunction(() => window.__ORACLE_DONE__ === true, null, { timeout: 60000 });
const result = await page.evaluate(() => window.__ORACLE_RESULT__);
writeFileSync('layouts.json', JSON.stringify(result));
await browser.close();
```
### Consuming in Python
```python
# In the renderer, map pixel positions to the canvas:
for glyph in frame_data['glyphs']:
char, px, py = glyph['char'], glyph['x'], glyph['y']
alpha = glyph.get('alpha', 1.0)
# Render using PIL draw.text() at exact pixel position
draw.text((px, py), char, fill=(int(255*alpha),)*3, font=font)
```
Obstacles from the JSON can also be rendered as glowing ASCII shapes (circles, rectangles) to visualize the reflow zones.
@@ -834,39 +834,6 @@ def sh_vignette(c, s=0.22):
return np.clip(c * _vig_cache[k][:,:,None], 0, 255).astype(np.uint8)
```
#### Reverse Vignette
Inverted vignette: darkens the **center** and leaves edges bright. Useful when text is centered over busy backgrounds — creates a natural dark zone for readability without a hard-edged box.
Combine with `apply_text_backdrop()` (see composition.md) for per-frame glyph-aware darkening.
```python
_rvignette_cache = {}
def sh_reverse_vignette(c, strength=0.5):
"""Center darkening, edge brightening. Cached."""
k = ('rv', c.shape[0], c.shape[1], round(strength, 2))
if k not in _rvignette_cache:
h, w = c.shape[:2]
Y = np.linspace(-1, 1, h)[:, None]
X = np.linspace(-1, 1, w)[None, :]
d = np.sqrt(X**2 + Y**2)
# Invert: bright at edges, dark at center
mask = np.clip(1.0 - (1.0 - d * 0.7) * strength, 0.2, 1.0)
_rvignette_cache[k] = mask[:, :, np.newaxis].astype(np.float32)
return np.clip(c.astype(np.float32) * _rvignette_cache[k], 0, 255).astype(np.uint8)
```
| Param | Default | Effect |
|-------|---------|--------|
| `strength` | 0.5 | 0 = no effect, 1.0 = center nearly black |
Add to ShaderChain dispatch:
```python
elif name == "reverse_vignette":
return sh_reverse_vignette(canvas, kwargs.get("strength", 0.5))
```
#### Contrast
```python
def sh_contrast(c, factor=1.3):
@@ -14,8 +14,6 @@
| Random dark holes in output | Font missing Unicode glyphs | Validate palettes at init |
| Audio-visual desync | Frame timing accumulation | Use integer frame counter, compute t fresh each frame |
| Single-color flat output | Hue field shape mismatch | Ensure h,s,v arrays all (rows,cols) before hsv2rgb |
| Text unreadable over busy bg | No contrast between text and background | Use `apply_text_backdrop()` (composition.md) + `reverse_vignette` shader (shaders.md) |
| Text garbled/mirrored | Kaleidoscope or mirror shader applied to text scene | **Never apply kaleidoscope, mirror_h/v/quad/diag to scenes with readable text** — radial folding destroys legibility. Apply these only to background layers or text-free scenes |
Common bugs, gotchas, and platform-specific issues encountered during ASCII video development.
-350
View File
@@ -643,353 +643,3 @@ class TestMatrixEncryptedSendFallback:
assert fake_client.room_send.await_count == 2
second_call = fake_client.room_send.await_args_list[1]
assert second_call.kwargs.get("ignore_unverified_devices") is True
# ---------------------------------------------------------------------------
# E2EE: Auto-trust devices
# ---------------------------------------------------------------------------
class TestMatrixAutoTrustDevices:
def test_auto_trust_verifies_unverified_devices(self):
adapter = _make_adapter()
# DeviceStore.__iter__ yields OlmDevice objects directly.
device_a = MagicMock()
device_a.device_id = "DEVICE_A"
device_a.verified = False
device_b = MagicMock()
device_b.device_id = "DEVICE_B"
device_b.verified = True # already trusted
device_c = MagicMock()
device_c.device_id = "DEVICE_C"
device_c.verified = False
fake_client = MagicMock()
fake_client.device_id = "OWN_DEVICE"
fake_client.verify_device = MagicMock()
# Simulate DeviceStore iteration (yields OlmDevice objects)
fake_client.device_store = MagicMock()
fake_client.device_store.__iter__ = MagicMock(
return_value=iter([device_a, device_b, device_c])
)
adapter._client = fake_client
adapter._auto_trust_devices()
# Should have verified device_a and device_c (not device_b, already verified)
assert fake_client.verify_device.call_count == 2
verified_devices = [call.args[0] for call in fake_client.verify_device.call_args_list]
assert device_a in verified_devices
assert device_c in verified_devices
assert device_b not in verified_devices
def test_auto_trust_skips_own_device(self):
adapter = _make_adapter()
own_device = MagicMock()
own_device.device_id = "MY_DEVICE"
own_device.verified = False
fake_client = MagicMock()
fake_client.device_id = "MY_DEVICE"
fake_client.verify_device = MagicMock()
fake_client.device_store = MagicMock()
fake_client.device_store.__iter__ = MagicMock(
return_value=iter([own_device])
)
adapter._client = fake_client
adapter._auto_trust_devices()
fake_client.verify_device.assert_not_called()
def test_auto_trust_handles_missing_device_store(self):
adapter = _make_adapter()
fake_client = MagicMock(spec=[]) # empty spec — no attributes
adapter._client = fake_client
# Should not raise
adapter._auto_trust_devices()
# ---------------------------------------------------------------------------
# E2EE: MegolmEvent key request + buffering
# ---------------------------------------------------------------------------
class TestMatrixMegolmEventHandling:
@pytest.mark.asyncio
async def test_megolm_event_requests_room_key_and_buffers(self):
adapter = _make_adapter()
adapter._user_id = "@bot:example.org"
adapter._startup_ts = 0.0
adapter._dm_rooms = {}
fake_megolm = MagicMock()
fake_megolm.sender = "@alice:example.org"
fake_megolm.event_id = "$encrypted_event"
fake_megolm.server_timestamp = 9999999999000 # future
fake_megolm.session_id = "SESSION123"
fake_room = MagicMock()
fake_room.room_id = "!room:example.org"
fake_client = MagicMock()
fake_client.request_room_key = AsyncMock(return_value=MagicMock())
adapter._client = fake_client
# Create a MegolmEvent class for isinstance check
fake_nio = MagicMock()
FakeMegolmEvent = type("MegolmEvent", (), {})
fake_megolm.__class__ = FakeMegolmEvent
fake_nio.MegolmEvent = FakeMegolmEvent
with patch.dict("sys.modules", {"nio": fake_nio}):
await adapter._on_room_message(fake_room, fake_megolm)
# Should have requested the room key
fake_client.request_room_key.assert_awaited_once_with(fake_megolm)
# Should have buffered the event
assert len(adapter._pending_megolm) == 1
room, event, ts = adapter._pending_megolm[0]
assert room is fake_room
assert event is fake_megolm
@pytest.mark.asyncio
async def test_megolm_buffer_capped(self):
adapter = _make_adapter()
adapter._user_id = "@bot:example.org"
adapter._startup_ts = 0.0
adapter._dm_rooms = {}
fake_client = MagicMock()
fake_client.request_room_key = AsyncMock(return_value=MagicMock())
adapter._client = fake_client
FakeMegolmEvent = type("MegolmEvent", (), {})
fake_nio = MagicMock()
fake_nio.MegolmEvent = FakeMegolmEvent
# Fill the buffer past max
from gateway.platforms.matrix import _MAX_PENDING_EVENTS
with patch.dict("sys.modules", {"nio": fake_nio}):
for i in range(_MAX_PENDING_EVENTS + 10):
evt = MagicMock()
evt.__class__ = FakeMegolmEvent
evt.sender = "@alice:example.org"
evt.event_id = f"$event_{i}"
evt.server_timestamp = 9999999999000
evt.session_id = f"SESSION_{i}"
room = MagicMock()
room.room_id = "!room:example.org"
await adapter._on_room_message(room, evt)
assert len(adapter._pending_megolm) == _MAX_PENDING_EVENTS
# ---------------------------------------------------------------------------
# E2EE: Retry pending decryptions
# ---------------------------------------------------------------------------
class TestMatrixRetryPendingDecryptions:
@pytest.mark.asyncio
async def test_successful_decryption_routes_to_text_handler(self):
import time as _time
adapter = _make_adapter()
adapter._user_id = "@bot:example.org"
adapter._startup_ts = 0.0
adapter._dm_rooms = {}
# Create types
FakeMegolmEvent = type("MegolmEvent", (), {})
FakeRoomMessageText = type("RoomMessageText", (), {})
decrypted_event = MagicMock()
decrypted_event.__class__ = FakeRoomMessageText
fake_megolm = MagicMock()
fake_megolm.__class__ = FakeMegolmEvent
fake_megolm.event_id = "$encrypted"
fake_room = MagicMock()
now = _time.time()
adapter._pending_megolm = [(fake_room, fake_megolm, now)]
fake_client = MagicMock()
fake_client.decrypt_event = MagicMock(return_value=decrypted_event)
adapter._client = fake_client
fake_nio = MagicMock()
fake_nio.MegolmEvent = FakeMegolmEvent
fake_nio.RoomMessageText = FakeRoomMessageText
fake_nio.RoomMessageImage = type("RoomMessageImage", (), {})
fake_nio.RoomMessageAudio = type("RoomMessageAudio", (), {})
fake_nio.RoomMessageVideo = type("RoomMessageVideo", (), {})
fake_nio.RoomMessageFile = type("RoomMessageFile", (), {})
with patch.dict("sys.modules", {"nio": fake_nio}):
with patch.object(adapter, "_on_room_message", AsyncMock()) as mock_handler:
await adapter._retry_pending_decryptions()
mock_handler.assert_awaited_once_with(fake_room, decrypted_event)
# Buffer should be empty now
assert len(adapter._pending_megolm) == 0
@pytest.mark.asyncio
async def test_still_undecryptable_stays_in_buffer(self):
import time as _time
adapter = _make_adapter()
FakeMegolmEvent = type("MegolmEvent", (), {})
fake_megolm = MagicMock()
fake_megolm.__class__ = FakeMegolmEvent
fake_megolm.event_id = "$still_encrypted"
now = _time.time()
adapter._pending_megolm = [(MagicMock(), fake_megolm, now)]
fake_client = MagicMock()
# decrypt_event raises when key is still missing
fake_client.decrypt_event = MagicMock(side_effect=Exception("missing key"))
adapter._client = fake_client
fake_nio = MagicMock()
fake_nio.MegolmEvent = FakeMegolmEvent
with patch.dict("sys.modules", {"nio": fake_nio}):
await adapter._retry_pending_decryptions()
assert len(adapter._pending_megolm) == 1
@pytest.mark.asyncio
async def test_expired_events_dropped(self):
import time as _time
adapter = _make_adapter()
from gateway.platforms.matrix import _PENDING_EVENT_TTL
fake_megolm = MagicMock()
fake_megolm.event_id = "$old_event"
fake_megolm.__class__ = type("MegolmEvent", (), {})
# Timestamp well past TTL
old_ts = _time.time() - _PENDING_EVENT_TTL - 60
adapter._pending_megolm = [(MagicMock(), fake_megolm, old_ts)]
fake_client = MagicMock()
adapter._client = fake_client
fake_nio = MagicMock()
fake_nio.MegolmEvent = type("MegolmEvent", (), {})
with patch.dict("sys.modules", {"nio": fake_nio}):
await adapter._retry_pending_decryptions()
# Should have been dropped
assert len(adapter._pending_megolm) == 0
# Should NOT have tried to decrypt
fake_client.decrypt_event.assert_not_called()
@pytest.mark.asyncio
async def test_media_event_routes_to_media_handler(self):
import time as _time
adapter = _make_adapter()
adapter._user_id = "@bot:example.org"
adapter._startup_ts = 0.0
FakeMegolmEvent = type("MegolmEvent", (), {})
FakeRoomMessageImage = type("RoomMessageImage", (), {})
decrypted_image = MagicMock()
decrypted_image.__class__ = FakeRoomMessageImage
fake_megolm = MagicMock()
fake_megolm.__class__ = FakeMegolmEvent
fake_megolm.event_id = "$encrypted_image"
fake_room = MagicMock()
now = _time.time()
adapter._pending_megolm = [(fake_room, fake_megolm, now)]
fake_client = MagicMock()
fake_client.decrypt_event = MagicMock(return_value=decrypted_image)
adapter._client = fake_client
fake_nio = MagicMock()
fake_nio.MegolmEvent = FakeMegolmEvent
fake_nio.RoomMessageText = type("RoomMessageText", (), {})
fake_nio.RoomMessageImage = FakeRoomMessageImage
fake_nio.RoomMessageAudio = type("RoomMessageAudio", (), {})
fake_nio.RoomMessageVideo = type("RoomMessageVideo", (), {})
fake_nio.RoomMessageFile = type("RoomMessageFile", (), {})
with patch.dict("sys.modules", {"nio": fake_nio}):
with patch.object(adapter, "_on_room_message_media", AsyncMock()) as mock_media:
await adapter._retry_pending_decryptions()
mock_media.assert_awaited_once_with(fake_room, decrypted_image)
assert len(adapter._pending_megolm) == 0
# ---------------------------------------------------------------------------
# E2EE: Key export / import
# ---------------------------------------------------------------------------
class TestMatrixKeyExportImport:
@pytest.mark.asyncio
async def test_disconnect_exports_keys(self):
adapter = _make_adapter()
adapter._encryption = True
adapter._sync_task = None
fake_client = MagicMock()
fake_client.olm = object()
fake_client.export_keys = AsyncMock()
fake_client.close = AsyncMock()
adapter._client = fake_client
from gateway.platforms.matrix import _KEY_EXPORT_FILE, _KEY_EXPORT_PASSPHRASE
await adapter.disconnect()
fake_client.export_keys.assert_awaited_once_with(
str(_KEY_EXPORT_FILE), _KEY_EXPORT_PASSPHRASE,
)
@pytest.mark.asyncio
async def test_disconnect_handles_export_failure(self):
adapter = _make_adapter()
adapter._encryption = True
adapter._sync_task = None
fake_client = MagicMock()
fake_client.olm = object()
fake_client.export_keys = AsyncMock(side_effect=Exception("export failed"))
fake_client.close = AsyncMock()
adapter._client = fake_client
# Should not raise
await adapter.disconnect()
assert adapter._client is None # still cleaned up
@pytest.mark.asyncio
async def test_disconnect_skips_export_when_no_encryption(self):
adapter = _make_adapter()
adapter._encryption = False
adapter._sync_task = None
fake_client = MagicMock()
fake_client.close = AsyncMock()
adapter._client = fake_client
await adapter.disconnect()
# Should not have tried to export
assert not hasattr(fake_client, "export_keys") or \
not fake_client.export_keys.called
-43
View File
@@ -212,49 +212,6 @@ class TestSessionHygieneWarnThreshold:
assert post_compress_tokens < warn_threshold
class TestCompressionWarnRateLimit:
"""Compression warning messages must be rate-limited per chat_id."""
def _make_runner(self):
from unittest.mock import MagicMock, patch
with patch("gateway.run.load_gateway_config"), \
patch("gateway.run.SessionStore"), \
patch("gateway.run.DeliveryRouter"):
from gateway.run import GatewayRunner
runner = GatewayRunner.__new__(GatewayRunner)
runner._compression_warn_sent = {}
runner._compression_warn_cooldown = 3600
return runner
def test_first_warn_is_sent(self):
runner = self._make_runner()
now = 1_000_000.0
last = runner._compression_warn_sent.get("chat:1", 0)
assert now - last >= runner._compression_warn_cooldown
def test_second_warn_suppressed_within_cooldown(self):
runner = self._make_runner()
now = 1_000_000.0
runner._compression_warn_sent["chat:1"] = now - 60 # 1 minute ago
last = runner._compression_warn_sent.get("chat:1", 0)
assert now - last < runner._compression_warn_cooldown
def test_warn_allowed_after_cooldown(self):
runner = self._make_runner()
now = 1_000_000.0
runner._compression_warn_sent["chat:1"] = now - 3601 # just past cooldown
last = runner._compression_warn_sent.get("chat:1", 0)
assert now - last >= runner._compression_warn_cooldown
def test_rate_limit_is_per_chat(self):
"""Rate-limiting one chat must not suppress warnings for another."""
runner = self._make_runner()
now = 1_000_000.0
runner._compression_warn_sent["chat:1"] = now - 60 # suppressed
last_other = runner._compression_warn_sent.get("chat:2", 0)
assert now - last_other >= runner._compression_warn_cooldown
class TestEstimatedTokenThreshold:
"""Verify that hygiene thresholds are always below the model's context
limit for both actual and estimated token counts.
@@ -60,7 +60,6 @@ def _make_runner(platform: Platform, config: GatewayConfig):
runner.adapters = {platform: adapter}
runner.pairing_store = MagicMock()
runner.pairing_store.is_approved.return_value = False
runner.pairing_store._is_rate_limited.return_value = False
return runner, adapter
@@ -143,56 +142,6 @@ async def test_unauthorized_whatsapp_dm_can_be_ignored(monkeypatch):
adapter.send.assert_not_awaited()
@pytest.mark.asyncio
async def test_rate_limited_user_gets_no_response(monkeypatch):
"""When a user is already rate-limited, pairing messages are silently ignored."""
_clear_auth_env(monkeypatch)
config = GatewayConfig(
platforms={Platform.WHATSAPP: PlatformConfig(enabled=True)},
)
runner, adapter = _make_runner(Platform.WHATSAPP, config)
runner.pairing_store._is_rate_limited.return_value = True
result = await runner._handle_message(
_make_event(
Platform.WHATSAPP,
"15551234567@s.whatsapp.net",
"15551234567@s.whatsapp.net",
)
)
assert result is None
runner.pairing_store.generate_code.assert_not_called()
adapter.send.assert_not_awaited()
@pytest.mark.asyncio
async def test_rejection_message_records_rate_limit(monkeypatch):
"""After sending a 'too many requests' rejection, rate limit is recorded
so subsequent messages are silently ignored."""
_clear_auth_env(monkeypatch)
config = GatewayConfig(
platforms={Platform.WHATSAPP: PlatformConfig(enabled=True)},
)
runner, adapter = _make_runner(Platform.WHATSAPP, config)
runner.pairing_store.generate_code.return_value = None # triggers rejection
result = await runner._handle_message(
_make_event(
Platform.WHATSAPP,
"15551234567@s.whatsapp.net",
"15551234567@s.whatsapp.net",
)
)
assert result is None
adapter.send.assert_awaited_once()
assert "Too many" in adapter.send.await_args.args[1]
runner.pairing_store._record_rate_limit.assert_called_once_with(
"whatsapp", "15551234567@s.whatsapp.net"
)
@pytest.mark.asyncio
async def test_global_ignore_suppresses_pairing_reply(monkeypatch):
_clear_auth_env(monkeypatch)

Some files were not shown because too many files have changed in this diff Show More