feat: single gateway, multiple agents — rebased onto current main (supersedes #25660)

[jethac]

Rebase of #25660 (@02356abc's single-gateway multi-agent MVP) onto current main, per @02356abc's own May 31 suggestion there to open a follow-on PR with a rebased base — which never landed, so here it is.

Credit: the feature and all 7 commits are @02356abc's — authorship is preserved unchanged. My contribution is the rebase itself plus two commits on top (a cron path-resolution fix + a test update the rebase surfaced).

What's here

The 7 original commits rebased onto current main (~6.5k commits of drift), resolved onto main's newer structure rather than reverting it:

• main had independently grown the same agent:<ns> session prefix — collapses byte-identical to agent:main.
• telegram.py was replaced by the new adapter — ported the _attach_agent_id injections.
• Several hooks moved homes (turn_context/turn_finalizer, slash_commands) — re-attached agent_id.
• The PR's registry / per-profile-path changes threaded through main's cron refactor.

Plus two commits of mine on top:

• fix(cron): _get_cron_dir() detected a test monkeypatch of CRON_DIR by comparing it to a live get_hermes_home() / "cron". That held when get_hermes_home() was static, but this PR makes it profile-/HERMES_HOME-dynamic — so any active-profile or env change was mistaken for a monkeypatch and returned the stale import-time path. Now compares to a frozen import-time default (_CRON_DIR_IMPORT_DEFAULT). Fixes an order-dependent cron-suite failure.
• test(cron): four TELEGRAM_CRON_THREAD_ID delivery-target assertions (added upstream after this PR's base) still asserted the pre-multi-agent dict shape; they now expect the agent_id field.

Verification (runtime, against current main)

Every module the rebase touches has a passing suite — ~1,600 tests across the blast radius:

Area	Result
Multi-agent core — session-key namespace + precedence, resolve_agent_id, AgentProfile/use_profile	184 ✓
Cron (full suite)	679 ✓
tools/approval	298 ✓
tools/delegate (+ toolset scope)	165 ✓
gateway/delivery	28 ✓
gateway/config	99 ✓
gateway/slash_access	21 ✓
gateway/agent_cache	78 ✓
gateway/runtime_footer	25 ✓
hermes_cli/agent (CLI + end-to-end agent add/list/show)	24 ✓
model_tools (hand-merged hooks)	✓

Not run: integration tests requiring network / API keys / live session infra — those are environmental and fail identically on main.

Tracking: #7517, #9514.

File-location note (2026-07-30): since upstream's 21c7ae856 split SessionDB into mixins, this PR's schema changes live in their new homes — the sessions.agent_id column in hermes_state_common.py (SCHEMA_SQL) and the idx_sessions_agent index in hermes_state_schema.py; only the create_session INSERT remains in hermes_state.py.

[alt-glitch]

This was generated by AI during triage.

Related: #25660 (the original single-gateway multi-agent MVP by @02356abc, still open — this PR is a rebase onto current main that supersedes it, with authorship preserved) and #34741 (an earlier closed rebase attempt). Salvage/rebase, not a duplicate. Note: the failing check-attribution CI job is the attribution workflow (expected for a rebase preserving upstream commits), not a Nix failure. A maintainer should pick between this rebased branch and #25660.

[teknium1]

Thanks for preserving the original authorship and rebasing this substantial feature.

Problems

• gateway/platforms/base.py:2936 is not safe for existing adapter construction paths. PR CI shows _attach_agent_id() raises because _default_agent_id is absent, failing active-session merge and Telegram tests.
• gateway/run.py:3933 reads a profile API key from os.getenv. Current multiplexing deliberately uses fail-closed scoped secret reads (agent/secret_scope.py:123-159); this bypass risks selecting another profile's process-global credential.
• hermes_cli/agent.py:181 nests profiles/ below the active HERMES_HOME; --from-profile is therefore wrong when invoked from a named profile. Existing profile enumeration is root-anchored (hermes_cli/profiles.py:949-987).

Suggested changes

• Guard/fallback routing state in _attach_agent_id and add regressions for the failing adapter paths.
• Use the existing secret-scope accessor for api_key_env and test two multiplexed profiles.
• Reuse existing profile-root APIs for cloning.
• Reconcile the route-table proposal with main's existing gateway.multiplex_profiles lifecycle before salvaging the parallel profile implementation.

Automated hermes-sweeper review.

[teknium1]

Blocking: this assumes every adapter instance ran BasePlatformAdapter.__init__. CI shows _DummyAdapter and TelegramAdapter paths reach here without _default_agent_id, raising AttributeError and failing existing batching/auth tests. Use a safe default/guard and add a regression test.

[jethac]

Fixed in d7d2d4c — _default_agent_id now has a class-level default ("main"), so adapter instances and test doubles built via object.__new__ (bypassing __init__) resolve to the legacy main agent instead of raising in _attach_agent_id. The active-session-merge and Telegram suites that were failing on this pass on the current head.

[teknium1]

Blocking: this bypasses the multiplexing secret scope with a direct process-environment read. Current agent.secret_scope.get_secret() intentionally makes scoped profile secrets authoritative and prevents cross-profile fallback; use that accessor (or the scope-aware runtime-provider helper) here.

[jethac]

Fixed in d30cdaf — the pinned credential now resolves through agent.secret_scope.get_secret(): a scoped turn reads its own profile's secrets, an unscoped read under gateway.multiplex_profiles raises UnscopedSecretError (fail closed) instead of touching the process environment, and single-profile installs keep the legacy os.getenv behavior. Regression tests in tests/gateway/test_profile_overrides.py cover two multiplexed profiles resolving distinct keys from their own scopes (with a decoy value planted in os.environ) plus the unscoped fail-closed path.

[teknium1]

Use the existing root-anchored profile helpers here. With a named active profile, get_hermes_home() is already <root>/profiles/<active>, so this resolves a nonexistent nested profiles/ directory and breaks --from-profile.

[jethac]

Fixed in aee7f0b — cloning now delegates to the root-anchored hermes_cli.profiles.create_profile(clone_from=…, clone_all=True, no_alias=True), which also picks up name validation, default-profile source handling, runtime-file stripping, and .env permission tightening. Added a regression test that runs hermes agent add --from-profile from inside a named profile (HERMES_HOME=<root>/profiles/<name>) and asserts the clone lands under the root profiles/ dir rather than nesting.

[jethac]

Thanks @teknium1 for the thorough review — the pointers to the exact seams (secret_scope, the root-anchored profile APIs) made these quick to fix. All three problems are addressed on the branch (_attach_agent_id in d7d2d4c, api_key_env → get_secret() in d30cdaf, root-anchored --from-profile cloning in aee7f0b), each with regression tests — I've replied inline on each of your three threads with the specifics. CI is green on the new head.

On reconciling the routes table with the gateway.multiplex_profiles lifecycle: agreed this is the real design question. The intent in this rebase is that the AgentProfile registry layers on top of the multiplex lifecycle rather than replacing it — the get_secret() fix closes the one spot where the two disagreed on credential resolution. A fuller unification (expressing multiplexed profiles as registry entries so profiles_to_serve() and config.agents share one source of truth) feels like it deserves its own PR; happy to take that as a follow-up, or fold it in here if you consider it blocking.

[davidgut1982]

@jethac — ceding the rebased base to you; thanks for picking it up and getting it green. It's in better shape than my May branch ever was, and the LINE/delivery background makes you the right person to carry the single-adapter routing.

One gap worth flagging: gateway/platforms/api_server.py still isn't agent-aware on main. It reads the active profile name only to label the advertised model (_resolve_model_name) — there's no _attach_agent_id stamping and no profile-scoped routing. Your rebase ports _attach_agent_id into the messaging adapters (telegram/discord/slack/matrix/feishu/wecom), but — mirroring the original MVP — it looks like api_server stays uncovered, so an inbound API-server request won't carry an agent_id.

I have the _attach_agent_id wiring for api_server (the follow-on I mentioned back in May). Happy to send it as a small standalone PR on top once yours lands — crediting your base, no need to widen your diff. Ping me if you'd rather fold it in.

[jethac]

@davidgut1982 - thanks for that! I'd love to take a look at what you've got, and to fold your work in as your original authored commits. How would you like to do it - maybe rebase your work on this, then send me a link to your branch?

[davidgut1982]

Sounds good — I'll pull in my api_server wiring as 643bbbf5a (feat(gateway): wire api_server adapter to multi-agent routing): the _attach_agent_id path for the API-server adapter plus a test_api_server_routing.py suite.

One heads-up on the base so you know what you're getting: that commit was authored against v0.17.0, and api_server.py has since been through the session-context refactor on main, so it won't cherry-pick clean. I'll port it onto your branch — re-fit the wiring to main's current _attach_agent_id / session-context shape, carry the test over, and get the api_server suite green — and keep it as my authored commit so you can fold it in with authorship preserved. I'll push to my fork and send you the branch link.

[davidgut1982]

Branch's up: https://github.com/davidgut1982/hermes-agent/tree/feat/api-server-agent-routing

One commit, authored by me, ported onto your rebased base — re-fit to the current api_server.py (post session-context refactor), not the v0.17.0 shape it was written against. It reuses your machinery rather than reintroducing old shapes: reads X-Hermes-Chat-Id / X-Hermes-User-Id / X-Hermes-Thread-Id, resolves the agent via the shared _attach_agent_id routes table + select_agent hook, and runs both the sync _run_agent path and the async _handle_runs (executor-thread) path under the resolved profile via use_profile. Unmapped requests fall back to main with no wrapper, so single-agent installs are unaffected.

tests/gateway/test_api_server_routing.py → 20/20 green, ruff clean, no new regressions in the existing api_server suites. Pull it into the PR however suits you — authorship's set so credit carries.

[jethac]

Nice work on the api_server routing wiring, David. I did an architectural pass over it plus a coverage audit of the wider multi-agent PR, and pushed your commit (b43a05a33) plus three of mine on top. Nothing here blocks — one real fix, one doc nit, and a coverage fill.

1. Credential scope gap in the routed run (fix — e06904247)

The routed-run path binds the agent profile's home via use_profile, but not its fail-closed credential scope. Under gateway.multiplex_profiles, provider/LLM keys are profile-scoped (not global env), so credential_pool → get_secret in the routed run would fail closed with UnscopedSecretError (or read another profile's process-global value) instead of resolving the routed agent's key.

Fix installs the secret scope alongside the home in both executor threads via a shared _use_profile_and_secret_scope helper, mirroring the base adapter's _profile_runtime_scope. None profile stays a pure home no-op. Regression tests include one that drives _run_agent itself and asserts the scope is live at agent-creation time — mutation-verified to fail if the fix is reverted.

2. _attach_agent_id docstring precedence was backwards (doc-only — 83f939ca2)

The docstring listed "declarative routes → select_agent hook → default," which reads as routes-first fallback. The code is hook_pick or route_match or default or "main" — the hook is always consulted, is handed route_match, and a truthy hook result overrides the route. That's clearly the intent (it matches set_routing_context's own doc: the hook "overriding the route result"), so I corrected the stale docstring to match. Flag me if the prose was right and the precedence is what's actually off — I read it as intended.

3. Session agent_id is first-writer-wins (flag only — no change)

SessionDB.create_session uses COALESCE(sessions.agent_id, excluded.agent_id) on a NOT NULL DEFAULT 'main' column. Net effect: a session first created without an agent_id is permanently main — a later routed create_session(..., agent_id="research") on the same id won't upgrade it. So agent routing has to be decided at session creation, not backfilled. Might be exactly what you want; I didn't touch it, just pinned the behavior in a test so it's explicit.

4. Coverage fill (4a1402ec6 — tests only, 69 tests)

Audited the PR against its base and filled the gaps that were silent-cross-agent-leak or core-propagation shaped:

• delivery — DeliveryRouter.deliver runs each target inside its routed profile; unknown/absent agent_id → nullcontext fallback.
• base adapter — _attach_agent_id resolution order, idempotency, hook override, fail-open on resolver/hook/replace errors (the routing linchpin had no direct tests; select_agent had none anywhere).
• cron — load_all_jobs/get_all_due_jobs per-profile stamping (main default; one bad profile doesn't starve siblings); _resolve_single_delivery_target propagates job.agent_id; cron-dir stays profile-dynamic.
• config/state — GatewayConfig.from_dict routes/agents/default parsing + malformed fallbacks; create_session persistence + legacy-column reconcile.
• session/hooks — SessionEntry roundtrip + legacy default; build_session_key agent_id-over-profile precedence; post_tool_call/transform_tool_result carry the active profile's agent_id.

Full touched-file suite is green (965 passed), ruff clean. Happy to squash the doc commit into yours, or split anything out if you'd rather.