timmy-config/docs/AGENT_EXTENSION_MIGRATION.md

Agent Extension Migration — SIDECAR-3

Issue: #339
Created: 2026-04-07
Status: In Progress — core extensions ported, remaining work documented

Overview

hermes-agent/agent/ contains many custom Python modules that are not part of the upstream NousResearch/hermes-agent codebase. These extensions need to be restructured as timmy-config skills or runtime patches so that hermes-agent can remain clean (no custom files).

Assessment Summary

Of the 19 custom modules found in agent/ (via diff against upstream):

Module	Status	Action	Notes
a2a_mtls.py	ARCHIVED	Moved to agent/archive/	A2A mutual TLS server — unused
agent_card.py	ARCHIVED	Moved to agent/archive/	A2A agent discovery — unused
circuit_breaker.py	ARCHIVED	Moved to agent/archive/	Error cascade protection — unused
context_budget.py	ARCHIVED	Moved to agent/archive/	Context window overflow guard — unused
crisis_resources.py	ARCHIVED	Moved to agent/archive/	988 integration — unused
input_sanitizer.py	ARCHIVED	Moved to agent/archive/	Jailbreak detection — currently unused (module exists but not imported)
mtls.py	ARCHIVED	Moved to agent/archive/	Mutual TLS support — unused
privacy_filter.py	PORTED	Now in extensions/privacy_filter.py	Vitalik Pattern 2 — PII stripping, IMPORTED by run_agent.py
profile_isolation.py	ARCHIVED	Moved to agent/archive/	Profile session isolation — unused
provider_preflight.py	ARCHIVED	Moved to agent/archive/	Provider validation — unused
self_modify.py	ARCHIVED	Moved to agent/archive/	Self-modifying prompt engine — unused
session_compactor.py	ARCHIVED	Moved to agent/archive/	Session compaction — unused (test exists but not production)
shield.py	PORTED	Now in extensions/shield.py	Crisis & jailbreak detection — IMPORTED by run_agent.py
smart_model_routing.py	PORTED	Now in extensions/smart_model_routing.py	Cheap vs strong model routing — IMPORTED by cli.py
telemetry_logger.py	ARCHIVED	Moved to agent/archive/	Telemetry logging — unused
time_aware_routing.py	ARCHIVED	Moved to agent/archive/	Time-based routing — unused
token_budget.py	ARCHIVED	Moved to agent/archive/	Token budget guard — unused
tool_fixation_detector.py	ARCHIVED	Moved to agent/archive/	Tool loop detection — unused
tool_orchestrator.py	ARCHIVED	Moved to agent/archive/	Tool execution orchestration — unused

Total custom modules: 19
Archived (dead/unused): 16
Ported to timmy-config (live): 3

What Changed

1. Created extensions/ directory in timmy-config

New sidecar-provided agent modules that are copied to ~/.hermes/agent/ by deploy.sh:

extensions/
├── __init__.py         # Package marker
├── privacy_filter.py   # PrivacyFilter + sanitize_messages()
├── shield.py           # scan_text(), is_crisis(), is_jailbreak()
└── smart_model_routing.py  # needs_strong_model(), should_use_cheap_model()

These re-implement the essential logic of the original modules with minimal dependencies. They can be enriched over time.

2. Updated deploy.sh

Added deployment step:

# === Deploy agent extensions (sidecar-provided agent modules) ===
if [ -d "$SCRIPT_DIR/extensions" ]; then
  mkdir -p "$HERMES_HOME/agent"
  for f in "$SCRIPT_DIR"/extensions/*.py; do
    [ -f "$f" ] && cp "$f" "$HERMES_HOME/agent/"
  done
  log "extensions/ -> $HERMES_HOME/agent/ (sidecar extensions)"
fi

3. Archived dead modules in hermes-agent

All 16 unused custom modules were moved to hermes-agent/agent/archive/ to preserve history and allow future upstream PRs.

Remaining Work

High Priority (Upstream Contributions)

The following modules are already in upstream NousResearch/hermes-agent — no action needed:

• anthropic_adapter.py
• auxiliary_client.py
• context_compressor.py
• display.py
• error_classifier.py
• insights.py
• memory_manager.py
• model_metadata.py
• prompt_builder.py
• prompt_caching.py
• rate_limit_tracker.py
• retry_utils.py
• skill_commands.py
• subdirectory_hints.py
• title_generator.py
• trajectory.py
• usage_pricing.py
• (and others found in upstream)

Future Migration (when needed)

These modules are active but minimal; if richer functionality is required later:

• context_references.py — not custom? appears upstream — verify
• credential_pool.py — appears not custom either
• memory_provider.py — possible custom
• redact.py — likely custom but unused
• copilot_acp_client.py — ACP integration, monitor

Hermes-Agent Side (separate PR)

After this timmy-config PR merges:

1. Rebase hermes-agent on latest upstream to drop any now-archived files
2. In hermes-agent/agent/, the files shield.py, privacy_filter.py, smart_model_routing.py should be removed or replaced with stubs that import from timmy-config (requires path injection)
3. Until timmy-config is deployed everywhere, a compatibility shim may be needed

Acceptance Criteria Checklist

• Each file assessed: useful (port) or dead (archive)
• 16 dead files archived in hermes-agent/agent/archive/
• 3 useful files restructured as timmy-config extensions in extensions/
• 3 useful files removed from hermes-agent (follow-up)
• No custom Python files remain in hermes-agent/agent/ that aren't upstream (pending follow-up)

References

• Epic: #336 (SIDECAR-3)
• Upstream: https://github.com/nousresearch/hermes-agent/tree/main/agent