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:

```bash
# === 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

- [x] Each file assessed: useful (port) or dead (archive)
- [x] 16 dead files archived in `hermes-agent/agent/archive/`
- [x] 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