better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,327 @@
+---
+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

@@ -0,0 +1,228 @@
+---
+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`.