The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
docs(platforms): adding-a-platform guides point at the plugin declarations
Tekniumfb5e7b614394
diff --git a/gateway/platforms/ADDING_A_PLATFORM.md b/gateway/platforms/ADDING_A_PLATFORM.mdindex aa4759c7d1a..0d3b823eed9 100644--- a/gateway/platforms/ADDING_A_PLATFORM.md+++ b/gateway/platforms/ADDING_A_PLATFORM.md@@ -177,12 +177,19 @@ class Platform(Enum):YOUR_PLATFORM = "your_platform"```-Add a row to `_ENV_STEPS` in `gateway/config_env.py` (source order = application order);-`_Cred` enables the platform when the named env vars resolve and copies them into `extra`:+Env credentials reach the config through the plugin's own `gateway_env.py` (the template is+`plugins/platforms/telegram/gateway_env.py`), passed to `ctx.register_platform` as+`env_overrides=gateway_env.ENV_OVERRIDES` and `env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS`.+Steps run in order; `EnvCred` (`gateway/platform_env.py`) enables the platform when the named env+vars resolve and copies them into `extra`. Import only `gateway.*` there: core reads the file+directly, without the adapter, when the plugin is not loaded.```python-_Cred(Platform.YOUR_PLATFORM, ("YOUR_PLATFORM_TOKEN",), token="YOUR_PLATFORM_TOKEN"),-_Home(Platform.YOUR_PLATFORM, "YOUR_PLATFORM_HOME_CHANNEL"),+ENV_ENABLE_CREDENTIALS = ("YOUR_PLATFORM_TOKEN",)+ENV_OVERRIDES = (+ EnvCred(Platform.YOUR_PLATFORM, ("YOUR_PLATFORM_TOKEN",), token="YOUR_PLATFORM_TOKEN"),+ home_step(Platform.YOUR_PLATFORM, "YOUR_PLATFORM_HOME_CHANNEL"),+)```Every read goes through `gateway/config.py::_getenv` (the active profile's secret scope when one@@ -192,8 +199,9 @@ platform for the wrong profile with the wrong credentials, and a write pins oneprocess-wide (first profile wins). Adapter-side reads use `gateway.platforms._shared.get_scoped_secret`/ `extra_or_secret`.-Update `get_connected_platforms()` if your platform doesn't use token/api_key-(e.g., WhatsApp uses `enabled` flag, Signal uses `extra` dict).+If your platform is "configured" without a token/api_key (WhatsApp uses the `enabled` flag,+Signal the `extra` dict), declare `config_connected_fn` on the entry; `get_connected_platforms()`+reads it.---@@ -219,18 +227,20 @@ before `connect()`.## 4. Authorization Maps (`gateway/pairing.py`, `gateway/authz_mixin.py`)-Add the allowlist var to `_PLATFORM_ALLOWLIST_ENV` in `gateway/pairing.py`;-`authz_mixin.py` derives `_ALLOWED_USERS_ENV` / `_ALLOW_ALL_ENV` from it (the `*_ALLOW_ALL_USERS`-name is computed, not hand-listed):+Declare the allowlist names in the plugin's `gateway_env.py` and pass them with+`**gateway_env.AUTHZ`; pairing, the authz ladder, the dashboard and the startup policy gate read+them from the entry, and from this file when the entry is missing (safe mode, plugin disabled) or a+user plugin overriding yours omits them:```python-_PLATFORM_ALLOWLIST_ENV = {- ...- "your_platform": "YOUR_PLATFORM_ALLOWED_USERS",+AUTHZ = {+ "allowed_users_env": "YOUR_PLATFORM_ALLOWED_USERS",+ "allow_all_env": "YOUR_PLATFORM_ALLOW_ALL_USERS",+ # optional: "allow_bots_env": "YOUR_PLATFORM_ALLOW_BOTS",+ # optional, adapters that gate DMs/groups themselves: "own_policy_env": ("..._DM_POLICY", "..._GROUP_POLICY"),}```-Plugin adapters declare `allowed_users_env` / `allow_all_env` on `ctx.register_platform` instead.`_is_user_authorized()` reads every gate through `_shared.platform_gate_env` (`_auth_env`), whichanswers from the routed profile's secret scope under multiplex — never add an `os.getenv` here.@@ -244,18 +254,17 @@ and update `to_dict()`, `from_dict()`, and `build_source()` in base.py.----## 6. System Prompt Hints (`agent/prompt_builder.py`)+## 6. System Prompt Hints (`platform_hint`)-Add a `PLATFORM_HINTS` entry so the agent knows what platform it's on:+Declare `platform_hint=` on `ctx.register_platform` (keep the text in a light sibling such as+`adapter_hint.py`) so the agent knows what platform it's on. `agent/prompt_builder.py::PLATFORM_HINTS`+holds only core surfaces (CLI, TUI, API server, ...):```python-PLATFORM_HINTS = {- ...- "your_platform": (- "You are on Your Platform. "- "Describe formatting capabilities, media support, etc."- ),-}+PLATFORM_HINT = (+ "You are on Your Platform. "+ "Describe formatting capabilities, media support, etc."+)```Without this, the agent won't know it's on your platform and may usediff --git a/plugins/platforms/sms/adapter.py b/plugins/platforms/sms/adapter.pyindex 1af18e063ec..8fed447b951 100644--- a/plugins/platforms/sms/adapter.py+++ b/plugins/platforms/sms/adapter.py@@ -292,7 +292,7 @@ _SMS_MARKDOWN_SUBS = (# register() exposes the platform via the registry, replacing the Platform.SMS elif in gateway/run.py, the# _PLATFORM_CONNECTED_CHECKERS entry in gateway/config.py, the _PLATFORMS["sms"] static dict in# hermes_cli/gateway.py, and the _send_sms dispatch in tools/send_message_tool.py. TWILIO_*-# env→PlatformConfig seeding stays in core.+# env→PlatformConfig seeding lives in this plugin's gateway_env.py.# ──────────────────────────────────────────────────────────────────────────def _strip_markdown_for_sms(message: str) -> str:"""Strip markdown — SMS renders it as literal characters."""@@ -349,12 +349,11 @@ def register(ctx) -> None:dashboard_required_env=("TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN"),check_fn=check_sms_requirements, is_connected=_is_connected,required_env=["TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN", "TWILIO_PHONE_NUMBER"],- install_hint="pip install aiohttp", allowed_users_env="SMS_ALLOWED_USERS",- allow_all_env="SMS_ALLOW_ALL_USERS", cron_deliver_env_var="SMS_HOME_CHANNEL",+ install_hint="pip install aiohttp", cron_deliver_env_var="SMS_HOME_CHANNEL",standalone_sender_fn=_standalone_send, max_message_length=MAX_SMS_LENGTH, pii_safe=True,emoji="📱", allow_update_command=True,platform_hint=_PLATFORM_HINT,display_tier="minimal",env_overrides=gateway_env.ENV_OVERRIDES,- env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS,+ env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,)diff --git a/website/docs/developer-guide/adding-platform-adapters.md b/website/docs/developer-guide/adding-platform-adapters.mdindex 5f23b286fdf..a16cbbaecef 100644--- a/website/docs/developer-guide/adding-platform-adapters.md+++ b/website/docs/developer-guide/adding-platform-adapters.md@@ -712,16 +712,13 @@ Six touchpoints:### 9. Optional: Platform Hints-**`agent/prompt_builder.py`** — If your platform has specific rendering limitations (no markdown, message length limits, etc.), add an entry to the `PLATFORM_HINTS` dict. This injects platform-specific guidance into the system prompt:+**`platform_hint=`** on `ctx.register_platform` — If your platform has specific rendering limitations (no markdown, message length limits, etc.), declare a hint on its registry entry (keep the text in a light sibling such as `adapter_hint.py`). It is injected into the system prompt; `agent/prompt_builder.py::PLATFORM_HINTS` holds only core surfaces:```python-PLATFORM_HINTS = {- # ...- "newplat": (- "You are chatting via NewPlat. It supports markdown formatting "- "but has a 4000-character message limit."- ),-}+PLATFORM_HINT = (+ "You are chatting via NewPlat. It supports markdown formatting "+ "but has a 4000-character message limit."+)```Not all platforms need hints — only add one if the agent's behavior should differ.diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-platform-adapters.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-platform-adapters.mdindex 4a97faeaf9d..6511ff09675 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-platform-adapters.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-platform-adapters.md@@ -570,16 +570,13 @@ await self.handle_message(event)### 9. 可选:平台提示-**`agent/prompt_builder.py`** — 如果你的平台有特定渲染限制(不支持 markdown、消息长度限制等),在 `_PLATFORM_HINTS` 字典中添加条目。这会将平台专属指导注入系统 prompt:+**`ctx.register_platform` 的 `platform_hint=`** — 如果你的平台有特定渲染限制(不支持 markdown、消息长度限制等),在其注册表条目上声明提示(文本可放在 `adapter_hint.py` 这类轻量同级模块中)。它会被注入系统 prompt;`agent/prompt_builder.py::PLATFORM_HINTS` 只保留核心界面:```python-_PLATFORM_HINTS = {- # ...- "newplat": (- "You are chatting via NewPlat. It supports markdown formatting "- "but has a 4000-character message limit."- ),-}+PLATFORM_HINT = (+ "You are chatting via NewPlat. It supports markdown formatting "+ "but has a 4000-character message limit."+)```并非所有平台都需要提示 — 仅在 agent 行为应有所不同时添加。