Skip to content

The agent that grows with you

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.md
index 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 one
process-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`), which
answers 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 use
diff --git a/plugins/platforms/sms/adapter.py b/plugins/platforms/sms/adapter.py
index 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.md
index 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.md
index 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 行为应有所不同时添加。