better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/model-provider-plugin.md

@@ -1,327 +0,0 @@
----
-sidebar_position: 10
-title: "Model Provider Plugins"
-description: "How to build a model provider (inference backend) plugin for Hermes Agent"
----
-
-# Building a Model Provider Plugin
-
-Model provider plugins declare an inference backend — an OpenAI-compatible endpoint, an Anthropic Messages server, a Codex-style Responses API, or a Bedrock-native surface — that Hermes can route `AIAgent` calls through. Every built-in provider (OpenRouter, Anthropic, GMI, DeepSeek, Nvidia, …) ships as one of these plugins. Third parties can add their own by dropping a directory under `$HERMES_HOME/plugins/model-providers/` with zero changes to the repo.
-
-:::tip
-Model provider plugins are the third kind of **provider plugin**. The others are [Memory Provider Plugins](/developer-guide/memory-provider-plugin) (cross-session knowledge) and [Context Engine Plugins](/developer-guide/context-engine-plugin) (context compression strategies). All three follow the same "drop a directory, declare a profile, no repo edits" pattern.
-:::
-
-## How discovery works
-
-`providers/__init__.py._discover_providers()` runs lazily the first time any code calls `get_provider_profile()` or `list_providers()`. Discovery order:
-
-1. **Bundled plugins** — `<repo>/plugins/model-providers/<name>/` — ship with Hermes
-2. **User plugins** — `$HERMES_HOME/plugins/model-providers/<name>/` — drop in any directory; no restart required for subsequent sessions
-3. **Installed plugins** — `$HERMES_HOME/plugins/<name>/` (where `hermes plugins install owner/repo` clones) — imported only when `plugin.yaml` declares `kind: model-provider`; every other kind there belongs to the general PluginManager
-4. **Legacy single-file** — `<repo>/providers/<name>.py` — back-compat for out-of-tree editable installs
-
-**User plugins override bundled plugins of the same name** because `register_provider()` is last-writer-wins. Drop a `$HERMES_HOME/plugins/model-providers/gmi/` directory to replace the built-in GMI profile without touching the repo.
-
-## Directory structure
-
-```
-plugins/model-providers/my-provider/
-├── __init__.py       # Calls register_provider(profile) at module-level
-├── plugin.yaml       # kind: model-provider + metadata (optional but recommended)
-└── README.md         # Setup instructions (optional)
-```
-
-The only required file is `__init__.py`. `plugin.yaml` is used by `hermes plugins` for introspection and by the general PluginManager to route the plugin to the right loader; without it, the general loader falls back to a source-text heuristic.
-
-## Minimal example — a simple API-key provider
-
-```python
-# plugins/model-providers/acme-inference/__init__.py
-from providers import register_provider
-from providers.base import ProviderProfile
-
-acme = ProviderProfile(
-    name="acme-inference",
-    aliases=("acme",),
-    display_name="Acme Inference",
-    description="Acme — OpenAI-compatible direct API",
-    signup_url="https://acme.example.com/keys",
-    env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
-    base_url="https://api.acme.example.com/v1",
-    auth_type="api_key",
-    default_aux_model="acme-small-fast",
-    fallback_models=(
-        "acme-large-v3",
-        "acme-medium-v3",
-        "acme-small-fast",
-    ),
-)
-
-register_provider(acme)
-```
-
-```yaml
-# plugins/model-providers/acme-inference/plugin.yaml
-name: acme-inference
-kind: model-provider
-version: 1.0.0
-description: Acme Inference — OpenAI-compatible direct API
-author: Your Name
-```
-
-That's it. After dropping these two files, the following **auto-wire** with no other edits:
-
-| Integration | Where | What it gets |
-|---|---|---|
-| Credential resolution | `hermes_cli/auth.py` | `PROVIDER_REGISTRY["acme-inference"]` populated from profile |
-| `--provider` CLI flag | `hermes_cli/main.py` | Accepts `acme-inference` |
-| `hermes model` picker | `hermes_cli/models.py` | Appears in `CANONICAL_PROVIDERS`, model list fetched from `{base_url}/models` |
-| `hermes doctor` | `hermes_cli/doctor.py` | Health check for `ACME_API_KEY` + `{base_url}/models` probe |
-| `hermes setup` | `hermes_cli/config.py` | `ACME_API_KEY` appears in `OPTIONAL_ENV_VARS` and the setup wizard |
-| URL reverse-mapping | `agent/model_metadata.py` | Hostname → provider name for auto-detection |
-| Auxiliary model | `agent/auxiliary_client.py` | Uses `default_aux_model` for compression / summarization |
-| Runtime resolution | `hermes_cli/runtime_provider.py` | Returns correct `base_url`, `api_key`, `api_mode` |
-| Transport | `agent/transports/chat_completions.py` | Profile path generates kwargs via `prepare_messages` / `build_extra_body` / `build_api_kwargs_extras` |
-
-## ProviderProfile fields
-
-Full definition in `providers/base.py`. The most useful ones:
-
-| Field | Type | Purpose |
-|---|---|---|
-| `name` | str | Canonical id — matches `model.provider` in `config.yaml` and the `--provider` flag |
-| `aliases` | `tuple[str, ...]` | Alternative names resolved by `get_provider_profile()` (e.g. `grok` → `xai`) |
-| `api_mode` | str | `chat_completions` \| `codex_responses` \| `anthropic_messages` \| `bedrock_converse` |
-| `display_name` | str | Human label shown in `hermes model` picker |
-| `description` | str | Picker subtitle |
-| `signup_url` | str | Shown during first-run setup ("get an API key here") |
-| `env_vars` | `tuple[str, ...]` | API-key env vars in priority order; a final `*_BASE_URL` entry is used as the user base-URL override |
-| `base_url` | str | Default inference endpoint |
-| `models_url` | str | Explicit catalog URL (falls back to `{base_url}/models`) |
-| `auth_type` | str | `api_key` \| `oauth_device_code` \| `oauth_external` \| `copilot` \| `aws_sdk` \| `external_process` |
-| `fallback_models` | `tuple[str, ...]` | Curated list shown when live catalog fetch fails |
-| `default_headers` | `dict[str, str]` | Sent on every request (e.g. Copilot's `Editor-Version`) |
-| `fixed_temperature` | Any | `None` = use caller's value; `OMIT_TEMPERATURE` sentinel = don't send temperature at all (Kimi) |
-| `default_max_tokens` | `int \| None` | Provider-level max_tokens cap (Nvidia: 16384) |
-| `default_aux_model` | str | Cheap model for auxiliary tasks (compression, vision, summarization) |
-
-## Overridable hooks
-
-Subclass `ProviderProfile` for non-trivial quirks:
-
-```python
-from typing import Any
-from providers.base import ProviderProfile
-
-class AcmeProfile(ProviderProfile):
-    def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        """Provider-specific message preprocessing. Runs after codex
-        sanitization, before developer-role swap. Default: pass-through."""
-        # Example: Qwen normalizes plain-text content to a list-of-parts
-        # array and injects cache_control; Kimi rewrites tool-call JSON
-        return messages
-
-    def build_extra_body(self, *, session_id=None, **context) -> dict:
-        """Provider-specific extra_body fields merged into the API call.
-        Context includes: session_id, provider_preferences, model, base_url,
-        reasoning_config. Default: empty dict."""
-        # Example: OpenRouter's provider-preferences block,
-        # Gemini's thinking_config translation.
-        return {}
-
-    def build_api_kwargs_extras(self, *, reasoning_config=None, **context):
-        """Returns (extra_body_additions, top_level_kwargs). Needed when some
-        fields go top-level (Kimi's reasoning_effort, OpenRouter's verbosity for
-        adaptive Anthropic models) and some go in extra_body (OpenRouter's
-        reasoning dict). Default: ({}, {})."""
-        return {}, {}
-
-    def fetch_models(self, *, api_key=None, base_url=None, timeout=8.0) -> list[str] | None:
-        """Live catalog fetch. Default hits {models_url or base_url}/models with
-        Bearer auth. Override for: custom auth (Anthropic), no REST endpoint
-        (Bedrock → None), or public/unauthenticated catalogs (OpenRouter)."""
-        return super().fetch_models(api_key=api_key, base_url=base_url, timeout=timeout)
-
-    def create_client(self, **client_kwargs):
-        """Supply your own client object instead of the shared openai.OpenAI.
-        Default returns None (= use the standard client). Override when the
-        wire protocol is not OpenAI-over-HTTP — e.g. an ACP subprocess shim.
-        client_kwargs is what the core would have passed to openai.OpenAI
-        (api_key, base_url, command, args, timeouts, headers…); accept **kwargs
-        and pick what you need. A raise is logged and falls back to the
-        standard client."""
-        return None
-```
-
-## External-process (ACP) providers
-
-An agent CLI driven over stdio is not an HTTP endpoint. Set `auth_type="external_process"`, describe how to launch the binary, and supply the client with `create_client`. No core edits are needed — `hermes -m <name>`, `/model`, credential resolution, runtime resolution and the auxiliary client (compression, vision) all key on `auth_type`, not on the provider name. `plugins/model-providers/copilot-acp/` is the in-tree example.
-
-| Field | Purpose |
-|---|---|
-| `process_command` | Default binary, e.g. `"copilot"` |
-| `process_args` | Default argv tail, e.g. `("--acp", "--stdio")` |
-| `process_command_env_vars` | Env vars that override the binary, checked in order |
-| `process_args_env_var` | Env var that overrides argv (shlex-split) |
-
-The client your `create_client` returns receives `command` and `args` in `client_kwargs`. If it is already complete and async-safe, declare `HERMES_SKIP_TRANSPORT_WRAP = True` / `HERMES_SKIP_ASYNC_WRAP = True` as class attributes so the auxiliary client does not re-dispatch it through an HTTP wire adapter.
-
-## Hook reference examples
-
-Look at these bundled plugins for idioms:
-
-| Plugin | Why look |
-|---|---|
-| `plugins/model-providers/openrouter/` | Aggregator with provider preferences, public model catalog |
-| `plugins/model-providers/gemini/` | `thinking_config` translation (native + OpenAI-compat nested forms) |
-| `plugins/model-providers/kimi-coding/` | `OMIT_TEMPERATURE`, `extra_body.thinking`, top-level `reasoning_effort` |
-| `plugins/model-providers/qwen-oauth/` | Message normalization, `cache_control` injection, VL high-res |
-| `plugins/model-providers/nous/` | Attribution tags, "omit reasoning when disabled" |
-| `plugins/model-providers/custom/` | Ollama `num_ctx` + `think: false` quirks |
-| `plugins/model-providers/bedrock/` | `api_mode="bedrock_converse"`, `fetch_models` returns None (no REST endpoint) |
-
-## User overrides — replace a built-in without editing the repo
-
-Say you want to point `gmi` at your private staging endpoint for testing. Create `~/.hermes/plugins/model-providers/gmi/__init__.py`:
-
-```python
-from providers import register_provider
-from providers.base import ProviderProfile
-
-register_provider(ProviderProfile(
-    name="gmi",
-    aliases=("gmi-cloud", "gmicloud"),
-    env_vars=("GMI_API_KEY",),
-    base_url="https://gmi-staging.internal.example.com/v1",
-    auth_type="api_key",
-    default_aux_model="google/gemini-3.1-flash-lite-preview",
-))
-```
-
-Next session, `get_provider_profile("gmi").base_url` returns the staging URL. No repo patch, no rebuild. Because user plugins are discovered after bundled ones, the user `register_provider()` call wins.
-
-## api_mode selection
-
-Four values are recognized. Hermes picks one based on:
-
-1. User explicit override (`config.yaml` `model.api_mode` when set)
-2. OpenCode's per-model dispatch (`opencode_model_api_mode` for Zen and Go)
-3. URL auto-detection — `/anthropic` suffix → `anthropic_messages`, `api.openai.com` → `codex_responses`, `api.x.ai` → `codex_responses`, `/coding` on Kimi domains → `chat_completions`
-4. **Profile `api_mode`** as a fallback when URL detection finds nothing
-5. Default `chat_completions`
-
-Set `profile.api_mode` to match the default your provider ships — it acts as a hint. User URL overrides still win.
-
-## Auth types
-
-| `auth_type` | Meaning | Who uses it |
-|---|---|---|
-| `api_key` | Single env var carries a static API key | Most providers |
-| `oauth_device_code` | Device-code OAuth flow | — |
-| `oauth_external` | User signs in elsewhere, tokens land in `auth.json` | Anthropic OAuth, MiniMax OAuth, Qwen Portal, Nous Portal |
-| `copilot` | GitHub Copilot token refresh cycle | `copilot` plugin only |
-| `aws_sdk` | AWS SDK credential chain (IAM role, profile, env) | `bedrock` plugin only |
-| `external_process` | Auth handled by a subprocess the agent spawns (see [External-process providers](#external-process-acp-providers)) | `copilot-acp` plugin, out-of-tree ACP plugins |
-
-`auth_type` gates which codepaths treat your provider as a "simple api-key provider" — if it's not `api_key`, the PluginManager still records the manifest but Hermes' CLI-level automation (doctor checks, `--provider` flag, setup wizard delegation) may skip over it.
-
-## Discovery timing
-
-Provider discovery is **lazy** — triggered by the first `get_provider_profile()` or `list_providers()` call in the process. In practice this happens early at startup (`auth.py` module load extends `PROVIDER_REGISTRY` eagerly). If you need to verify your plugin loaded, run:
-
-```bash
-hermes doctor
-```
-
-— a successful `auth_type="api_key"` profile appears under the Provider Connectivity section with a `/models` probe.
-
-For programmatic inspection:
-
-```python
-from providers import list_providers
-for p in list_providers():
-    print(p.name, p.base_url, p.api_mode)
-```
-
-## Testing your plugin
-
-Point `HERMES_HOME` at a temp directory so you don't pollute your real config:
-
-```bash
-export HERMES_HOME=/tmp/hermes-plugin-test
-mkdir -p $HERMES_HOME/plugins/model-providers/my-provider
-cat > $HERMES_HOME/plugins/model-providers/my-provider/__init__.py <<'EOF'
-from providers import register_provider
-from providers.base import ProviderProfile
-register_provider(ProviderProfile(
-    name="my-provider",
-    env_vars=("MY_API_KEY",),
-    base_url="https://api.my-provider.example.com/v1",
-    auth_type="api_key",
-))
-EOF
-
-export MY_API_KEY=your-test-key
-hermes -z "hello" --provider my-provider -m some-model
-```
-
-## General PluginManager integration
-
-The general `PluginManager` (the thing `hermes plugins` operates on) **sees** model-provider plugins but does not import them — `providers/__init__.py` owns their lifecycle. The manager records the manifest for introspection and categorizes by `kind: model-provider`. When you drop an unlabeled user plugin into `$HERMES_HOME/plugins/` that happens to call `register_provider` with a `ProviderProfile`, the manager auto-coerces it to `kind: model-provider` via a source-text heuristic — so the plugin still routes correctly even without `plugin.yaml`.
-
-## Distribute via pip
-
-Model providers can ship as a pip package. Expose an entry point in the
-`hermes_agent.plugins` group in your `pyproject.toml`:
-
-```toml
-[project.entry-points."hermes_agent.plugins"]
-acme-inference = "acme_hermes_plugin:register"
-```
-
-The target may be either:
-
-- a **callable** (`module:func`) — invoked with no arguments; it should call
-  `register_provider(profile)`, or
-- a **bare module** (`module`) — imported for its module-level
-  `register_provider(...)` side effect, mirroring the directory-plugin
-  `__init__.py` contract.
-
-`providers/__init__.py` discovers these entry points itself — the general
-`PluginManager` never invokes provider registration for pip packages (its
-entry-point path targets `register(ctx)`-style general plugins, gated by
-`plugins.enabled`), so the provider registry does its own scan. Two rules
-apply:
-
-- **Opt-in required.** The same `plugins.enabled` allow-list (and
-  `plugins.disabled` deny-list) from `config.yaml` governs this scan. A pip
-  package is never imported just because it is installed — users must add the
-  entry-point name to `plugins.enabled`:
-
-  ```yaml
-  plugins:
-    enabled:
-      - acme-inference
-  ```
-
-- **Lowest precedence.** Entry-point plugins are discovered **before**
-  filesystem plugins: because `register_provider()` is last-writer-wins, a
-  bundled or `$HERMES_HOME` profile of the same name always overrides a
-  pip-installed one. A pip package can add a genuinely new provider, but
-  cannot silently hijack a first-party provider name.
-
-Targets that require arguments (a general plugin's `register(ctx)`) are
-skipped by the provider scan — they belong to the `PluginManager`. A broken
-entry point is isolated — it is logged at warning level and skipped, and never
-blocks discovery of the other providers.
-
-See [Building a Hermes Plugin](/developer-guide/plugins#distribute-via-pip) for the full entry-points setup.
-
-## Related pages
-
-- [Provider Runtime](/developer-guide/provider-runtime) — resolution precedence + where each layer reads the profile
-- [Adding Providers](/developer-guide/adding-providers) — end-to-end checklist for new inference backends (covers both the fast plugin path and the full CLI/auth integration)
-- [Memory Provider Plugins](/developer-guide/memory-provider-plugin)
-- [Context Engine Plugins](/developer-guide/context-engine-plugin)
-- [Building a Hermes Plugin](/developer-guide/plugins) — general plugin authoring

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/multiplexing-gateway.md

@@ -1,228 +0,0 @@
----
-title: "Multiplexing Gateway Internals"
-description: "Design of the one-gateway-for-all-profiles mode: scope composition, secret scope, inbound routing, persistence"
----
-
-# Multiplexing Gateway
-
-One gateway process can serve every profile in the install. The mode is on by
-default (`gateway.multiplex_profiles`, default `true`), and everything it
-changes reverts the moment the flag is off. An *unset* flag is settled at boot
-by `hermes_cli/gateway_multiplex_mode.py::resolve_multiplex_mode`, which runs
-the `hermes gateway migrate` preflight and keeps the gateway standalone when a
-secondary still runs its own gateway, a blocker exists, or the host cannot be
-migrated (see "The mode flag"). This document is the design rationale
-referenced from `agent/secret_scope.py` ("Workstream A"): what is isolated per
-profile, the mechanism that isolates it, and what deliberately stays
-process-global.
-
-## Overview
-
-Without multiplexing, one gateway process serves exactly one profile — its
-`.env`, sessions, skills, and platform adapters — and multi-profile installs
-run one process per profile. Multiplexing collapses that into a single
-process: the default profile plus every served named profile get their own
-adapters, secrets, sessions, and cron ticks, while sharing one event loop, one
-HTTP listener, one process lock, and one status surface.
-
-The design constraint that shapes everything below: **profile A's turns must
-never observe profile B's state**. Secrets, homes, sessions, and adapter lanes
-are isolated per profile; anything that cannot yet be isolated fails closed or
-is documented as a known limitation at the end of this document.
-
-## The mode flag
-
-- Config: `gateway.multiplex_profiles` (also accepted at top level). Parsed in
-  `gateway/config.py` with precedence env > config > unset. `GatewayConfig`
-  keeps an unset flag as `None` (readers test truthiness, so it reads as off);
-  `load_gateway_config_for_runner` then calls `resolve_multiplex_mode`, which
-  writes the boot verdict — `True` on a quiet multi-profile default install,
-  `False` with a logged reason otherwise. Explicit values pass through
-  verbatim; a config injected into `GatewayRunner(config=...)` is not resolved.
-- Other processes read the LIVE gateway's `served_profiles` record first and
-  the explicit flag second (`gateway_multiplex_mode.default_gateway_multiplexes`
-  / `explicit_multiplex_flag`), never the merged default: `named_profile_served_
-  by_running_multiplexer`, the enroll warning, the dashboard's listener guard,
-  the cron-fire port resolver, container boot, and the migration plan
-  (`_read_multiplex_flag`, so an unset default reads as "not yet multiplexed"
-  and the fold proceeds).
-- Env override: `GATEWAY_MULTIPLEX_PROFILES` accepts explicit truthy/falsy
-  tokens only; a blank or unrecognized value returns "no override" so an empty
-  deployment secret cannot shadow a config opt-in.
-- At startup, `GatewayRunner.__init__` calls
-  `agent.secret_scope.set_multiplex_active(...)` once. `_MULTIPLEX_ACTIVE` is
-  a plain module global, not a contextvar: it describes the deployment mode,
-  not a per-task value. Its only job is to arm the fail-closed behavior in
-  `get_secret()`.
-
-## Scope composition
-
-Every inbound event composes the same two context-local scopes before any
-profile-owned code runs:
-
-```
-platform event
-   │
-   ▼
-profile_routes match ──► served-set check ──► SessionSource.profile stamped
-   │                                           (gateway/profile_routing.py)
-   ▼
-_profile_runtime_scope(profile_home)           (gateway/run.py)
-   ├── set_hermes_home_override(home)          config / state.db / skills /
-   │                                           memory / sessions resolve here
-   └── set_secret_scope(profile .env + secret sources)
-   │                                           provider keys, platform tokens
-   ▼
-agent turn (worker thread via copy_context())
-   │
-   ▼
-scope unwound in finally
-```
-
-`_profile_runtime_scope` wraps every seam where profile-owned code executes:
-secondary adapter startup, connect and reconnect, the primary platform event
-handler, inbound preprocessing, `/model` and session-info resolution,
-background tasks, and the agent turn itself. Config reloads run under the
-default profile's scope so global gateway settings (`#64674`) resolve
-consistently.
-
-Both scopes are `contextvars`, so they propagate into executor worker threads
-via `copy_context()` and unwind deterministically — nothing is written to
-`os.environ`, ever.
-
-## Workstream A: context-local secret scope
-
-`agent/secret_scope.py` exists because the obvious implementation — union all
-profile `.env` files into `os.environ` — leaks profile A's keys into profile
-B's turns and into every subprocess spawned with `env=dict(os.environ)`.
-
-- `build_profile_secret_scope(home)` merges the profile's `.env` with its
-  configured secret sources, skipping globals.
-- `set_secret_scope(mapping)` installs it for the current task.
-- `get_secret(name)` resolves: global allowlist → active scope → fallback.
-  The fallback is the load-bearing part:
-  - multiplexing **off**: reads `os.environ`, so single-profile gateways and
-    every non-gateway caller behave exactly as before;
-  - multiplexing **on**, no scope installed: **raises `UnscopedSecretError`**
-    rather than silently reading the process environment. An un-migrated call
-    site fails loud at that exact line instead of leaking another profile's
-    value.
-- A small allowlist (`HERMES_HOME`, `HERMES_PROFILE`, proxy settings,
-  `API_SERVER_*` listener settings — but deliberately not `API_SERVER_KEY`)
-  stays global because those describe the process, not a profile.
-
-Because the per-turn `.env` reload is a no-op under multiplexing, rotated
-credentials are picked up through the profile scope on the next turn — never
-via `os.environ`. This holds at the loader boundary, not just the gateway's
-reload helper: `hermes_cli.env_loader.load_hermes_dotenv` skips the
-process-global load whenever multiplexing is active *and* a profile-home
-override is installed (import-time and cron callers hit it mid-turn), while
-still hydrating the profile's external secret sources into its private
-snapshot (`#77562`). The unscoped startup load is unchanged.
-
-The same scope-authoritative rule covers the other `os.environ` seams a
-routed turn can reach: `${VAR}` / `${env:VAR}` references in a profile's
-`config.yaml` resolve through `get_secret` when a scope is installed
-(`#84079`), and `.env` writes made under a scope (`save_env_value`, e.g. a
-`/pair` grant mirror) update the installed scope mapping instead of the
-process environment (`#88441`).
-
-## The HERMES_HOME override
-
-`hermes_constants.py` holds a context-local override consulted by
-`get_hermes_home()` before the `HERMES_HOME` env var. Everything that resolves
-paths through it — config, `state.db`, skills, memory, SOUL, sessions, kanban,
-goals, plugin discovery, MCP startup — follows the active profile
-automatically. `get_process_hermes_home()` exists for the few machine-level
-assets that must not follow the override. `hermes_home_key()` gives
-per-home registries a stable scope key. A one-shot warning (`#18594`) fires if
-profile-scoped code runs without the override where one is expected.
-
-## Inbound routing
-
-`gateway.profile_routes` maps `(platform, guild_id, chat_id, thread_id)` to a
-profile; matching is conjunctive, most-specific-first, with parent-chain chat
-matching for threads. Routing only runs when multiplexing is active, and a
-matched route whose target is outside the served set is rejected (the event is
-dropped, not misdelivered). Full schema and matching rules:
-[Routing shared-bot chats to profiles](../user-guide/multi-profile-gateways.md#routing-shared-bot-chats-to-profiles-profile_routes).
-
-## Serving selected profiles
-
-`profiles_to_serve(multiplex, profile_allowlist)` in `hermes_cli/profiles.py`
-is the single chokepoint for which profiles a multiplexer serves: default plus
-every valid profile directory, optionally filtered by allowlist. A malformed
-allowlist fails safe to default-only. The served set gates adapter startup,
-cron ticking (`#69377`), `/p/<profile>/` HTTP admission, route eligibility,
-and the runtime status surface. An excluded profile stays installed and can
-still run its own standalone gateway.
-
-## Per-profile persistence
-
-`SessionStore` binds no database handle at construction (`#88532`). Session
-DB handles are resolved at call time through the active HERMES_HOME override —
-one cached handle per resolved `profiles/<name>/state.db` — so sessions land
-in the owning profile's store even when the store object itself is shared.
-Pairing stores are constructed per served profile.
-
-## Per-bot session lanes
-
-Session keys are namespaced by profile (`agent:main` for default,
-`agent:<name>` for named profiles). Adapters carry `_owner_profile`
-(installed at adapter configuration time, before any inbound event) because
-adapter ingress runs before `SessionSource.profile` is stamped;
-`_session_key_profile` resolves source stamp → owner profile → store
-resolver. Text/media batching, active-session tracking, and the busy-session
-guard are all keyed per lane, so two bots sharing a chat do not share a
-session lane.
-
-## Control plane
-
-Desktop plugins reach the gateway only through the ws JSON-RPC door, so
-profile enumeration and configuration live in
-`tui_gateway/methods_profiles.py`: `profiles.list`, `profiles.create`,
-`profiles.describe`, `profiles.configure`, `profiles.set_asset`,
-`profiles.get_asset`. Reads and writes run under the target profile's
-HERMES_HOME override. Asset writes are atomic, type- and size-capped.
-
-## Failure modes
-
-- Fatal at startup: multiplex config errors and a secondary profile enabling a
-  port-binding platform (`MultiplexConfigError`,
-  `SecondaryPortBindingConfigError`) — one shared HTTP listener is owned by
-  the default profile.
-- Skipped, not fatal: a single misconfigured secondary adapter is skipped with
-  a warning rather than taking down the multiplexer.
-- Fail-closed: unscoped `get_secret()` under multiplexing raises; a routed
-  event targeting an unserved profile is dropped; an unscoped `/p/` request
-  enters the default profile's scope (`#61276`) rather than an undefined one.
-- Fallback: an external `cron.provider` does not support multiplexing and
-  falls back to the built-in ticker with a warning.
-
-## Known limitations
-
-Process-global state that is not yet profile-scoped:
-
-| Surface | State at time of writing |
-| --- | --- |
-| MCP discovery and tool registration | Process-global; the first profile to build an agent wins the discovery slot. Full per-profile MCP registries are tracked in `#67605`. |
-| Terminal / sandbox env (`TERMINAL_*`) | Global by allowlist; tools read it from the process environment. |
-| Built-in tool registry | Built-ins are process-global; plugin-registered tools are overlaid per profile via `hermes_home_key()`. |
-| Provider/capability registries | Same hybrid overlay pattern (browser, image-gen, TTS, transcription, video-gen, web-search, secret sources). |
-| HTTP listener, relay ingress, process lock | One per process, owned by the default/active profile. Per-profile `runtime_status.json` is still written. |
-
-## Non-goals
-
-Multiplexing isolates *profiles*; it does not authenticate or authorize *end
-users*. A profile is a configuration, not a person: the gateway trusts its
-transport and its routing table to decide which profile an event belongs to.
-Request-level identity and per-user authorization above the profile layer are
-out of scope for this document.
-
-## Related
-
-- [Multi-profile gateways](../user-guide/multi-profile-gateways.md) — user-facing guide, including `profile_routes`
-  and the standalone one-gateway-per-profile alternative.
-- `agent/secret_scope.py`, `hermes_constants.py`, `gateway/profile_routing.py`,
-  `gateway/run.py` (`_profile_runtime_scope`), `hermes_cli/profiles.py`
-  (`profiles_to_serve`), `gateway/session.py`, `tui_gateway/methods_profiles.py`.