Bumping this for visibility, this is a great improvement for Hermes

Test Report: Topic Profile Routing (PR #18510)

Successfully tested this PR with a real Telegram supergroup setup — it works! Here are the details:

Setup

• Telegram supergroup with forum topics enabled
• 3 topics: General (Thread 1, default profile), Reisen (Thread 10 → profile reisen), Projekte (Thread 2 → profile projekte)
• External profile homes outside ~/.hermes/profiles/ using topic_profiles_safe_root and profile_home config
• Each profile with its own SOUL.md, isolated sessions, memory

What works ✓

• Topic-to-profile routing resolves correctly — messages in each topic hit the corresponding profile
• Profile isolation: separate state.db per profile, separate sessions, separate SOUL.md
• Log entries now include the resolved profile name (very helpful for debugging)
• Model override per profile works (one profile on kimi-k2.6:cloud, another on deepseek-v4-pro:cloud)

Issues encountered

1. Agent cache doesn't bust on SOUL.md changes (critical)
When a profile's SOUL.md is created or modified after the agent was first initialized for that topic, the cached agent is reused with the old (or default) identity. Neither /new nor gateway restart reliably clears this.

Workaround: Delete the profile's state.db* files before first use, or ensure SOUL.md exists before the first message arrives in the topic.

2. ContextVar propagation gap in tool execution (critical)
When a routed agent calls tools like write_file, the hermes_home_override ContextVar is lost. This causes get_hermes_home() to fall back to the gateway's default ~/.hermes/ instead of the profile home. Consequence: the agent can accidentally write to ~/.hermes/SOUL.md instead of the profile's SOUL.md, overwriting the main identity.

Workaround: Pre-populate all profile SOUL.md files before starting the gateway. Avoid asking routed agents to modify their own identity files.

3. Profile config must stay minimal
Adding agent.personalities, agent.personality, or agent.system_prompt to a profile config caused the ContextVar override to behave unpredictably. The agent loaded the main ~/.hermes/SOUL.md identity despite the override being set.

Workaround: Keep profile configs minimal — only model, memory, and agent.max_turns. Let SOUL.md handle identity exclusively.

Summary

The core routing works well and is production-ready for the happy path. The two cached-agent issues are solvable with the workarounds above. A proper fix would involve:

• Including profile home path in the agent cache signature
• Ensuring ContextVar propagation survives through all tool execution paths (not just asyncio.to_thread)

Thanks for this PR — it bridges the last major gap between Hermes and multi-agent forum-topic setups! 🚀

Update on the topic-profile routing hardening work:
I pushed another round of fixes that should address the issues Donmeusi surfaced during real Telegram topic testing.

Covered now:

• SOUL.md changes in a routed profile bust both the gateway agent cache and the stored system-prompt snapshot, so deleting state.db* should no longer be needed.
• Routed profile tool execution now keeps the active profile HERMES_HOME across the relevant thread/executor paths.
• /reload-mcp and /reload-skills now reload against the routed profile home when invoked from a routed topic.
• Background process metadata now persists profile identity, completion events rebuild the routed source correctly, and process actions/listing are scoped to the active profile so raw session_id leakage should not cross profiles.
• Profile config isolation has regression coverage for SOUL.md, agent.system_prompt, model/toolsets, .env, memory, sessions, process notifications, and concurrent routed topics.

Validation run locally:

• Targeted regression suite: 71 passed
• verify-dev --scope quick --skip-deps: passed

@Donmeusi if you have time, it would be very helpful to retest your same Telegram supergroup setup with the latest branch. In particular, the previous workarounds should no longer be necessary:

• no need to delete profile state.db* after editing SOUL.md
• no need to ensure SOUL.md exists before the first routed message
• profile configs should no longer need to stay artificially minimal to avoid fallback to the main profile

hope this helps

Heya. How can we help finalize this work?

Ho hey Teknium ; thanks for checking in.

I reproduced the current main merge locally. The PR is blocked by two conflict files:

• gateway/run.py: current main added Telegram DM topic-mode/session binding support while this PR added topic -> Hermes profile routing. The resolution is to keep both, but make sure routed profile flows keep using the active profile SessionStore/SessionDB for /new, auto-title, and topic rebinding instead of falling back to the global store.
• tools/process_registry.py: current main added safe cwd recovery for deleted working directories. The resolution is straightforward: keep that _resolve_safe_cwd(...) behavior and also preserve the routed agent_profile / agent_hermes_home metadata from this PR.

I tested that resolution in a scratch merge against current main with the relevant targeted suite:

tests/gateway/test_topic_profile_routing.py tests/gateway/test_telegram_topic_mode.py tests/tools/test_local_env_cwd_recovery.py tests/test_subprocess_home_isolation.py

Result: 110 passed.

What remains before merge:

• 1. I’ll push a small conflict-resolution update to the PR branch.
• 2. Maintainers can rerun CI on the updated branch.
• 3. If possible, one final real Telegram retest would be useful for the routed profile path, especially SOUL/profile isolation and tool/process behavior from a forum topic.
• 4. Once CI and/or that smoke test look good, I can mark the PR ready for review.

And I guess we will be good

Follow-up pushed: e8fc2247f fix(skills): respect routed topic profile homes

I re-checked the reported gaps against the current PR and made one targeted hardening fix plus regression coverage:

• Fixed the reproducible profile leak in skills tooling: skills_list, skill_view, slash skill reload/invocation, and skill_manage now resolve the active routed profile home dynamically instead of relying on an import-time SKILLS_DIR.
• Added regression tests for importing skills tooling under the gateway home, then running under a routed topic profile home.
• Added an end-to-end _handle_message topic-profile test to verify the production message path loads the routed profile’s SOUL.md, model/toolset config, and active Hermes home.
• Added a diagnostic for the intentional tool boundary: gateway-level custom platform_toolsets / mcp_servers are not implicitly inherited by isolated routed profiles.
• Documented that routed profiles must declare custom toolsets/MCP servers in their own config.yaml if they need them.

Important behavior note: this PR still intentionally does not proxy gateway tools/MCP servers into routed profiles by default. That keeps the isolation boundary explicit and avoids leaking gateway secrets/capabilities into a specialized profile. A true gateway tool bridge should be a separate opt-in feature with its own security review and tests. Unless you have other ideas/needs.

Validation run locally:

• targeted topic-profile/subprocess/skills regression suite: passed
• existing skills tool/manager/slash-command suites: passed

🧪 E2E Field Report — Telegram Topic Profile Routing (7 Topics)

Environment: macOS (Darwin ARM64), Hermes Gateway with Telegram forum topic routing enabled, latest PR branch including a8baef794.

Verified against latest fixes (comment #4372690748)

New Profile Created Under Latest Branch — News Agent (Topic Profile)

Created a new topic-routed profile using the exact PR workflow (no pre-PR workarounds):

mkdir -p ~/.hermes-topic-profiles/<profile>
# config.yaml — fully declarative: model, memory, toolsets, skills
# SOUL.md — English system instructions, agent responds in German
# .env — API keys only

Key observation: Full declarative configs work without falling back to the main profile.

Cron-Routing as Stress Test

schedule: '0 7 * * *'
deliver: 'telegram:CHAT_ID:THREAD_ID'

The scheduler resolves the delivery target into the isolated profile context autonomously — no interactive message handler required. Result: profile context built correctly, tools scoped to routed profile.

Edge Cases Discovered

1. FUSE Deadlock on macOS + Cloud Storage Mount

When routed profiles write to cloud-mounted filesystems (macOS FUSE-based Google Drive, iCloud, etc.), heavy I/O can deadlock (Resource deadlock avoided). This is not a Hermes bug. Recommendation: profile skills using cloud storage should implement a local staging directory with manual or automated sync.

2. user_profile_enabled Default (minor)

New profiles implicitly inherit user_profile_enabled: false. Recommendation: Set user_profile_enabled: true as explicit default in profile creation, since cross-session user modeling is essential for routed agents.

3. ContextVar Tool Propagation (known Python limitation)

Hermes file-write tools (write_file, patch) execute in a separate context where ContextVar-bound profile routing doesn't propagate. Workaround: use terminal() commands for file writes in routed profiles. This is contextvars-level behavior, not a PR bug.

Test Checklist

Conclusion

PR #18510 is production-ready for Telegram topic-to-profile routing. All reported gaps from the initial E2E test are addressed by the latest fixes. No pre-PR workarounds are required anymore.

Ready for merge once the current merge conflicts with main are resolved.

Possible follow-up: an opt-in gateway tool bridge for routed profiles that need gateway-level MCP servers without duplicating configuration.

CC @teknium1 @ayoahha

@teknium1
guys, can we move forward on this PR ?

ayoahha everybody is waiting for this. Thanks for pushing it. And hope to be merged in the next rel

Update: rebased/merged the branch with current main and resolved the gateway/run.py conflict.

Current status:

• PR is mergeable again locally / via GitHub API.
• Scoped validation passed:
  • topic profile + subprocess + skills profile isolation: 75 passed
  • impacted skills suites: 249 passed

The PR still shows “workflows awaiting approval”, so CI cannot run until a maintainer approves the fork workflow run. Could a maintainer please approve the workflows when convenient?

Regression Report — Merge Commit 480e5dc90

Previously confirmed working: The topic-profile routing worked correctly on commit a8baef794 in a real Telegram supergroup with forum topics. All reported issues from the initial test were addressed by @ayoahha'''s follow-up fixes.

Regression found after latest merge (May 8):
Commit 480e5dc90 attempted to resolve conflicts with current main but accidentally deleted _profile_home_for_source() from gateway/run.py entirely. The merge commit message claims "topic profile routing preserved", but the function responsible for switching hermes_home to the routed profile directory was completely removed.

What currently breaks:

• build_session_key still generates profile-scoped keys like agent:reisen:...
• But without _profile_home_for_source(), no profile home override ever happens
• All topic messages fall back to the global default profile
• The routing code exists in telegram.py (assigns agent_profile), but run.py never acts on it

Fix needed:
The _profile_home_for_source() function must be restored in gateway/run.py, or the merge resolution revisited.

cc @ayoahha @teknium1

Regression Report — Merge Commit 480e5dc90

Previously confirmed working: The topic-profile routing worked correctly on commit a8baef794 in a real Telegram supergroup with forum topics. All reported issues from the initial test were addressed by @ayoahha'''s follow-up fixes.

Regression found after latest merge (May 8): Commit 480e5dc90 attempted to resolve conflicts with current main but accidentally deleted _profile_home_for_source() from gateway/run.py entirely. The merge commit message claims "topic profile routing preserved", but the function responsible for switching hermes_home to the routed profile directory was completely removed.

What currently breaks:

• build_session_key still generates profile-scoped keys like agent:reisen:...
• But without _profile_home_for_source(), no profile home override ever happens
• All topic messages fall back to the global default profile
• The routing code exists in telegram.py (assigns agent_profile), but run.py never acts on it

Fix needed: The _profile_home_for_source() function must be restored in gateway/run.py, or the merge resolution revisited.

cc @ayoahha @teknium1

Thanks @Donmeusi

I checked this carefully

But your report looks accurate for the previous merge attempt you tested, but the current PR head is now:
42cc55176ebb65bcbb08507979a5872ce87aed97

On that head, _profile_home_for_source() is present again in gateway/run.py and is wired into the routed profile path:

• profile-scoped SessionStore / SessionDB
• routed profile .env loading
• active HERMES_HOME override before _handle_message_with_agent
• _run_agent profile-home resolution

I also re-checked the remote branch content directly and reran the targeted profile routing tests locally:

• tests/gateway/test_topic_profile_routing.py: 44 passed

So I believe the regression you saw was from the previous head, not the current PR branch.

Could you retest against 42cc55176 when you have a chance?

One more note: GitHub Actions still have not actually run. The current workflow runs are all action_required with jobs: [] and no logs, so a maintainer still needs to approve the fork workflows before we get real CI signal.

@ayoahha Thanks for the quick turnaround. We retested against 42cc55176 — unfortunately same result.

Setup: Real Telegram supergroup with forum topics, Topic 10 → profile atlas, fresh state.db + sessions.json, gateway restart.

What works:

• _profile_home_for_source() exists in gateway/run.py ✅
• agent_hermes_home is assigned in telegram.py ✅

What does not work:

• In Topic 10 the agent still replies as agent:main / default agent instead of agent:atlas
• The session seems to be created/reused under agent:main before the topic-profile routing takes effect

We suspect an ordering issue in the session lifecycle (SessionDB initializes or reuses agent:main before the profile override happens), but we cannot verify this conclusively without attaching a debugger to a running gateway.

Should I open a separate issue for this, or does it fit within the scope of this PR?

@ayoahha Thanks for the quick turnaround. We retested against 42cc55176 — unfortunately same result.

Setup: Real Telegram supergroup with forum topics, Topic 10 → profile atlas, fresh state.db + sessions.json, gateway restart.

What works:

• _profile_home_for_source() exists in gateway/run.py ✅
• agent_hermes_home is assigned in telegram.py ✅

What does not work:

• In Topic 10 the agent still replies as agent:main / default agent instead of agent:atlas
• The session seems to be created/reused under agent:main before the topic-profile routing takes effect

We suspect an ordering issue in the session lifecycle (SessionDB initializes or reuses agent:main before the profile override happens), but we cannot verify this conclusively without attaching a debugger to a running gateway.

Should I open a separate issue for this, or does it fit within the scope of this PR?

Thanks @Donmeusi .

I think we are in the PR scope, so I fixed the ordering issue you reproduced on 42cc55176.

Root cause: the adapter could compute its active-session/batch key from event.source before topic-profile routing was guaranteed on the source, so the adapter path could create/queue under agent:main even though the runner later knew the route.

What changed:

• hydrate event/source profile routing before adapter session-key creation
• inject a runner fallback resolver into adapters for Telegram topic_profiles
• make Telegram text/photo/media-group batching keys profile-aware
• preserve existing _profile_home_for_source() fail-closed validation and DM topic mode behavior

Targeted verification:

• 82 passed: topic profile routing + subprocess/tool isolation scope
• 109 passed: Telegram topic mode/thread fallback/documents scope

You can test again and tell me

Update: Topic-profile routing is now working successfully on our end after a clean reinstall of Hermes and checking out this branch.

We have set up multiple sub-agents, each with their own isolated profile home containing SOUL.md, config.yaml, and .env. The routing correctly maps forum topics to their designated profiles.

A few things we learned during setup that might help others:

1. Each profile needs its own config.yaml — not just SOUL.md and .env. Without model/provider settings in the profile's config.yaml, you'll get "No inference provider configured" because the gateway loads the profile's config independently.

2. topic_profiles must be at root-level platforms: — not nested under ui.platforms:. We initially placed it in the wrong section and routing silently fell back to the default profile.

3. The .env file must be copied to each profile home — API keys aren't inherited from the default ~/.hermes/.env automatically.

4. Thread IDs from Telegram forum topics need to be determined from gateway logs or bot API, as they aren't always obvious from the UI.

The isolation works well: each agent has its own sessions, memory, and state. Looking forward to seeing this merged!

Thanks for the great work on this feature.

Great great thanks @Donmeusi for the real Telegram supergroup retest and for documenting the setup findings. That was very helpful for separating actual routing bugs from profile-isolation configuration details.

I merged latest origin/main and resolved the remaining conflicts...

What was preserved:

• topic-profile routing and profile-scoped session keys
• routed profile HERMES_HOME isolation
• profile-scoped session store / SessionDB usage
• runtime_provider(..., env=...) so routed profiles do not fall back to global env
• existing Telegram DM topic mode behavior

I also added a small non-blocking warning for misplaced ui.platforms.telegram.topic_profiles, routing still only uses platforms.telegram.extra.topic_profiles or the legacy top-level telegram.topic_profiles bridge.
No inheritance was added for profile config.yaml, .env, tools, or MCP servers.

Local targeted verification:

• 83 passed: topic profile routing + subprocess/tool isolation
• 109 passed: Telegram topic mode/thread fallback/documents
• 182 passed: runtime provider/fallback/session env

CI still needs maintainer approval for fork workflows.

I really hope this will be merged soon, I've been waiting for this. And btw it isn't a 'P3' at all.

Hi maintainers, quick status update on this PR.
This branch has been rebased on the latest main; the PR is now mergeable and has no base conflicts.

Why this matters:

• Adds Telegram topic → profile routing, so specific forum topics can route to isolated Hermes profiles.
• Isolates routed profile state via scoped HERMES_HOME, runtime env, .env, auth.json, credential pools, sessions, tools, skills, compression, title generation, and auxiliary clients.
• Hardens fallback-provider behavior so routed profiles fail closed when scoped credentials are missing, instead of silently falling back to global credentials or the wrong topic/context.
• Adds targeted regression coverage for routing, scoped credentials, provider fallback, subprocess/tool isolation, and Telegram topic behavior.

All targeted tests pass locally. I also ran a live Telegram Bot API smoke test covering as much as I can previous @Donmeusi tests.

Could a maintainer approve the pending workflows so CI can run on this fork PR?
@teknium1 @alt-glitch 🙏

If the scope is too large to review in one pass, I’m also happy to split this into smaller PRs, but the current branch is structured around the conflict-resolution + routing/isolation hardening needed for this feature to be safe.

After a huge update of the team on telegram, I made some improvements

The last updates rebase the Telegram topic-to-profile routing work on the latest upstream main and tightens the isolation model around routed profiles.

What changed:

• Added topic_profiles routing for Telegram topics so one bot/gateway can route selected topics to dedicated Hermes profiles.
• Kept upstream Telegram behavior intact: allowed_topics, mention filtering, topic/thread fallback behavior, DM topics, media handling, and background notifications remain separate concerns.
• Added fail-closed profile routing:
  • routed topics require a configured safe root;
  • profile homes are canonicalized and validated;
  • symlink/path escape cases are rejected;
  • routed profile identity is validated with .hermes_profile.json.
• Scoped runtime behavior to the routed profile:
  • HERMES_HOME, config, sessions, runtime env, provider resolution, auxiliary clients, compression, tools, and process registry state follow the routed profile.
• Hardened strict auth for routed profiles:
  • no silent fallback to global/main credentials;
  • external-process credentials are blocked in strict routed-profile mode;
  • missing profile-scoped credentials fail visibly instead of falling back.
• Added hermes profile audit-isolation to detect profile/main overlap without printing secrets.
• Added/updated tests for topic routing, strict auth, profile audit, process scoping, status/compress behavior, and Telegram topic regressions.

Why:
The goal is to support multi-profile Telegram topic routing while preserving the newer upstream Telegram/auth/runtime behavior and preventing cross-profile leakage. A routed topic should behave like an isolated Hermes profile, not like a cosmetic session label.

Validation:

• Rebased on latest upstream main.
• Ran targeted topic/profile/auth/process/session tests.
• Ran verify-dev --scope standard locally.
• Performed manual live validation of routed topics, profile-scoped runtime info, session isolation, and tool environment scoping using generic routed profiles.

I really hope some maintainers will find some time to launch the CI.

Merge conflict analysis with current main — please prioritize merge

I tested merging origin/main (HEAD ~2026-05-31) into the pr-18510 branch. Result: 16 files with real content conflicts — not auto-mergeable.

Critical conflict files for topic-profile routing:

• gateway/platforms/telegram.py
• gateway/run.py
• gateway/config.py
• gateway/session_context.py
• gateway/platforms/base.py
• hermes_constants.py
• hermes_state.py

Additional utility conflicts: run_agent.py, tools/terminal_tool.py, tools/skill_manager_tool.py, tools/environments/local.py, agent/skill_commands.py, hermes_cli/auth.py, hermes_cli/runtime_provider.py, plus 2 test files.

The feature is actively used in production (multi-agent Telegram groups with isolated profiles per topic). As main diverges further, the rebase/merge cost grows exponentially. Would appreciate prioritization to get this landed before the conflict surface becomes unmanageable.

Thanks @Donmeusi for this last detailed testing and the latest conflict analysis.

To all,
I’m going to step back from maintaining this PR.

Since this was opened, main has moved a lot, the PR has grown difficult to keep rebased, and it is now conflicting across many core files. Given that it has remained tagged as P3 and has not received a clear maintainer review/merge path, I do not think it makes sense for me to keep spending time resolving conflicts on this branch.

No hard feelings here. I understand maintainers have to prioritize. But from my side, I will no longer maintain or rebase this PR.

If the team or another contributor still wants this feature, please feel free to take over the branch, cherry-pick parts of it, or close this PR and restart from a smaller scoped implementation.