docs(relay): move behavior-controls docs into the relay-connector contract
Relocate the platforms.relay.extra.<platform> documentation from a new user-guide page into docs/relay-connector-contract.md (the existing canonical relay doc, already linked from gateway-internals) as §8. The relay lane is an enterprise-only component: it gets minor coverage in the developer-facing contract doc, not a prominent user-guide page, and no links to private components.
This commit is contained in:
Victor Kyriazakos
parent
85a75f3155
commit
daefa8c34e
|
|
@ -711,7 +711,44 @@ per-gateway secret and the same host as `/relay/provision`.
|
|||
|
||||
---
|
||||
|
||||
## 8. Versioning policy
|
||||
## 8. Gateway-side platform behavior controls (enterprise)
|
||||
|
||||
Enterprise deployments configure fronted-platform behavior on the GATEWAY
|
||||
side, under `platforms.relay.extra.<platform>` — a supported subset of that
|
||||
platform's native options. The native platform block (e.g. `platforms.slack`)
|
||||
is not read on the relay lane; the connector receives the *outcome* of these
|
||||
controls as frame metadata (§4) and executes mechanically — it holds no
|
||||
platform behavior policy of its own.
|
||||
|
||||
```yaml
|
||||
platforms:
|
||||
relay:
|
||||
extra:
|
||||
slack:
|
||||
reply_in_thread: true # default
|
||||
```
|
||||
|
||||
Resolution: nested `extra.<platform>` object wins → legacy flat key on
|
||||
`extra` honored as fallback → default. Source of truth:
|
||||
`RelayAdapter._effective_reply_in_thread` (`gateway/relay/adapter.py`).
|
||||
|
||||
Current controls (Slack):
|
||||
|
||||
| Key | Default | Effect |
|
||||
| --- | --- | --- |
|
||||
| `reply_in_thread` | `true` | `true`: thread-per-message — each top-level DM message anchors its own thread (status, progress, prompts, final reply all carry that `metadata.thread_id`) and keys its own session, so concurrent messages run in parallel. `false`: flat rolling DM — send-lane frames carry NO thread anchor (stripped, not omitted), one shared session per DM. |
|
||||
|
||||
Typing/status frames always carry the triggering-ts anchor when one is known
|
||||
(liveliness is unconditional, both modes): Slack's status line is
|
||||
thread-scoped, and in flat mode the send-side anchor strip guarantees the
|
||||
status anchor can never leak into reply placement. Semantics of the native
|
||||
key: see `website/docs/user-guide/messaging/slack.md`.
|
||||
|
||||
Changes take effect on gateway restart; no connector involvement.
|
||||
|
||||
---
|
||||
|
||||
## 9. Versioning policy
|
||||
|
||||
- `contract_version` is an int; bump **only** for additive changes during the
|
||||
experimental phase (new optional fields, new `op`s).
|
||||
|
|
|
|||
|
|
@ -1,55 +0,0 @@
|
|||
# Relay (Team Gateway) — Enterprise
|
||||
|
||||
> **Enterprise-only.** The relay lane applies when your Hermes gateway is
|
||||
> fronted by a [Team Gateway connector](https://github.com/NousResearch/gateway-gateway)
|
||||
> — the enterprise deployment model where the connector owns the platform
|
||||
> credentials (e.g. one org Slack app) and Hermes speaks a relay protocol to
|
||||
> it instead of connecting to the platform natively. Standalone/native
|
||||
> installs can ignore this page; your platform's own page (e.g.
|
||||
> [Slack](slack.md)) applies instead.
|
||||
|
||||
## How configuration works on the relay lane
|
||||
|
||||
The relay adapter is platform-neutral: the connector tells Hermes which
|
||||
platform it fronts, and Hermes expresses per-turn decisions (threading,
|
||||
status, placement) as frame metadata the connector executes mechanically.
|
||||
|
||||
A small set of **platform behavior controls** exist for the fronted platform.
|
||||
They live under `platforms.relay.extra.<platform>` — a supported *subset* of
|
||||
that platform's native options — NOT under the native platform block:
|
||||
|
||||
```yaml
|
||||
platforms:
|
||||
slack: # native adapter settings — ignored on the relay lane
|
||||
...
|
||||
relay:
|
||||
extra:
|
||||
slack: # relay-lane subset for fronted Slack
|
||||
reply_in_thread: true
|
||||
```
|
||||
|
||||
Resolution order: the nested `extra.<platform>` object wins → a legacy flat
|
||||
key on `extra` is honored as a fallback → the option's default.
|
||||
|
||||
## Supported controls — Slack
|
||||
|
||||
| Key | Default | Effect |
|
||||
|---|---|---|
|
||||
| `reply_in_thread` | `true` | `true`: thread-per-message — each top-level DM message opens its own thread carrying the entire turn (status, tool progress, approval cards, final reply), and each message runs as its own session so concurrent messages execute in parallel. `false`: flat rolling DM — everything posts at the DM root, one shared session, a second message steers the in-flight turn. |
|
||||
|
||||
Semantics match the native Slack adapter's `reply_in_thread`
|
||||
([Slack docs](slack.md)); the relay subset exists so relay-fronted behavior
|
||||
is configured explicitly rather than inherited from a native block that the
|
||||
relay lane does not read.
|
||||
|
||||
In-progress "thinking…" statuses (with live per-tool phrases) are always on,
|
||||
in whatever form the mode supports: the thread's replies footer in
|
||||
thread-per-message mode, or anchored to the triggering message in flat mode.
|
||||
They require only the `chat:write` bot scope — no Slack assistant surface.
|
||||
|
||||
Changing a control takes effect on gateway restart — `hermes config set
|
||||
platforms.relay.extra.slack.reply_in_thread false` and restart; no connector
|
||||
deploy is involved.
|
||||
|
||||
Other fronted platforms currently have no relay-lane controls; the set grows
|
||||
as enterprise deployments need them (each addition is documented here).
|
||||
Loading…
Reference in New Issue