Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(channels): pin the channel-authoring contract and document the recipe

Yufeng Hea57a71e16dba
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bbaa220c7..b97a1acf6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -137,6 +137,34 @@ merging. Authors are strongly encouraged to self-check first.
5. Open a PR. Every commit must include `Signed-off-by:` (use
`git commit -s`). Reviewers will walk the checklist above.
+## Adding a Channel (Quickstart)
+
+Channels ship through one authoring contract; the Web UI renders any channel's
+configuration with no per-channel frontend code.
+
+1. Create `agent/src/channels/<name>.py` with a `BaseChannel` subclass:
+ implement `start`, `stop`, and `send` (abstract), and `default_config()`
+ returning the stored config shape. The registry (`src/channels/registry.py`)
+ auto-discovers the module; delivery receipts, retries and manager wiring come
+ from the base class and manager.
+2. Field metadata lives in `agent/src/channels/config_meta.py`. Hand-written
+ `FIELD_HINTS[name]` entries supply labels and authoritative secret flags;
+ anything you omit is derived from `default_config()` with type inference, and
+ credential-shaped keys are masked by the unconditional `SECRET_KEY_RE`
+ fail-safe either way. If the platform has a credential endpoint, build the
+ connection probe on `token_probe.py` rather than writing a new client (see
+ `dingtalk_probe.py` for the pattern) and override `test_connection()`.
+3. Run the authoring contract locally:
+ ```bash
+ pytest agent/tests/test_channel_authoring_contract.py -q
+ ```
+ It walks every discovered channel and fails when one breaks the recipe
+ (abstracts unset, scalar config keys with no field hint, or an uncovered
+ credential-shaped key that would leak unmasked into the form).
+4. Open a PR with `Signed-off-by:` on every commit. Dict-valued config (e.g.
+ per-group maps) stays file-configured by design; the generic form edits
+ text/password/bool/list widgets only.
+
## Code Style
- Format with `black`; lint with `ruff` (config in `pyproject.toml`).
diff --git a/agent/tests/test_channel_authoring_contract.py b/agent/tests/test_channel_authoring_contract.py
new file mode 100644
index 000000000..ae5c8b4c9
--- /dev/null
+++ b/agent/tests/test_channel_authoring_contract.py
@@ -0,0 +1,67 @@
+"""Every channel must satisfy the authoring contract (#1625).
+
+A new channel ships as a ``BaseChannel`` subclass plus field metadata, and the
+generic Web UI renders it with no per-channel frontend code. This suite walks
+every built-in channel the registry discovers and checks the contract points
+the UI and settings flows depend on, so a channel that breaks the recipe fails
+here instead of in the browser.
+"""
+
+from __future__ import annotations
+
+from src.channels.config_meta import SECRET_KEY_RE, channel_field_hints, is_secret_key
+from src.channels.registry import discover_channel_names, load_channel_class
+
+
+def test_every_discovered_channel_satisfies_the_authoring_contract() -> None:
+ names = discover_channel_names()
+ assert names, "registry discovered no channels"
+
+ checked = 0
+ for name in names:
+ try:
+ cls = load_channel_class(name)
+ except ImportError:
+ # Optional stack not installed here (e.g. matrix needs [nio]); an
+ # environment gate, not a contract violation.
+ continue
+ checked += 1
+
+ # A concrete adapter: start/stop/send are abstract on BaseChannel.
+ assert not cls.__abstractmethods__, f"{name} leaves BaseChannel abstracts unset"
+
+ default_config = cls.default_config()
+ assert isinstance(default_config, dict), f"{name} default_config is not a dict"
+
+ # The generic form renders from hints; every configurable scalar key
+ # must resolve one. Dict-valued fields are exempt by design: the form
+ # cannot edit them, so they stay file-configured (see _derive_hints).
+ hints = channel_field_hints(name)
+ configurable = {k for k, v in default_config.items() if k != "enabled" and not isinstance(v, dict)}
+ hint_keys = {h["key"] for h in hints}
+ missing = configurable - hint_keys
+ assert not missing, f"{name} has scalar config keys with no field hint: {sorted(missing)}"
+
+ # Secret masking: hand-written hints are authoritative for their keys
+ # (an audited declaration may subtract an over-match, e.g. websocket's
+ # token_* path names); for every key no hint covers, the SECRET_KEY_RE
+ # fail-safe must fire.
+ hint_flags = {h["key"]: bool(h["secret"]) for h in hints}
+ for key in configurable:
+ if key in hint_flags:
+ continue
+ if SECRET_KEY_RE.search(key):
+ assert is_secret_key(name, key), f"{name}.{key} is credential-shaped, uncovered by hints, and unmasked"
+ for hint in hints:
+ if hint["type"] == "password":
+ assert hint["secret"], f"{name}.{hint['key']} is a password field not marked secret"
+
+ assert checked > 0, "every discovered channel failed to import"
+
+
+def test_test_connection_envelope_shape_is_documented_by_default() -> None:
+ # The base contract: a channel that does not override the probe reports
+ # "unsupported" rather than crashing the settings UI.
+ from src.channels.base import BaseChannel
+
+ assert "test_connection" not in BaseChannel.__abstractmethods__