Skip to content

docs(relay): match Core's relay behaviour in the guide, skill and help (v2.16.1) - #244

Merged
paulkr merged 1 commit into
mainfrom
docs/relay-server-behaviour
Nov 20, 2026
Merged

paulkr merged 1 commit into
mainfrom
docs/relay-server-behaviour

Conversation

@paulkr

@paulkr paulkr commented Nov 20, 2026

Copy link
Copy Markdown
Member

Why

Agents set up relays by following one guide relay and the skill's references/relay.md. Both had claims that don't match Core's relay code, and the worst one makes relays fail without any error: they told agents that Airtable needs no --metadata, so an agent would create an Airtable relay whose webhook never gets registered.

What changed

src/lib/guide-content.ts (GUIDE_RELAY) and skills/one/references/relay.md:

  • --metadata: the table now lists all 49 platforms that need it (Airtable, Asana, Calendly, Monday and more), not only GitHub and Typeform. A warning in the create response means the webhook wasn't registered: show it to the user, delete the endpoint, and create it again.
  • --webhook-secret: a wrong secret doesn't give "events but 0 deliveries". It replaces the secret stored for the whole connection, so One answers the source's webhooks with 401 and records no events. Agents should pass it only when activate asks for one.
  • Template values: every rendered value is a string, {{json}} gives a string, and pathVariables are templated and fail on a missing value. Triple braces are refused in headers and pathVariables.
  • url action: the request body is a JSON envelope, not the raw event. The guide and skill now list the X-Relay-* headers and the X-Relay-Signature HMAC.
  • agent action: it only delivers through an agent's event trigger, so agents are told to use a url action to reach the user's own agent or server.
  • New "How changes behave" section:
    • update replaces lists.
    • Event filters only filter on One's side.
    • --no-active still records events.
    • delete leaves the webhook at the source.
    • There is one relay per source connection.
    • Retries.
  • Debugging is split by symptom: no events at all, or events with no deliveries.

src/cli.ts: the relay create --metadata and relay activate --webhook-secret help text say the same.

Version 2.16.0 → 2.16.1, so users' installed skill files refresh.

Testing

  • tsc --noEmit passes.
  • npm test: 910 of 918 pass. The 6 failures are the resolveConfig tests, which fail the same way on main.
  • Built and ran one --agent guide relay and the two --help outputs with an empty HOME; the new text is there.
  • I read the behaviour from Core's code on main (webhook/src/registration/platform/*.rs for the metadata keys, webhook/src/inbound and core/src/http/routes/common/webhook_relay.rs for signatures and delivery). I did not trigger live webhooks.

Companion website PR: withoneai/landing#190. It also lists the Core and dashboard issues found along the way.

🤖 Generated with Claude Code

…p (v2.16.1)

`one guide relay` and the skill's relay reference were checked against
Core's relay code. What agents were told that was wrong:

- Only GitHub and Typeform need --metadata, and Airtable needs none.
  49 platforms need it, Airtable included; the full table is in both.
  A create response with a warning means the webhook wasn't registered.
- A wrong --webhook-secret gives "events but 0 deliveries". It gives no
  events at all (401 at the door) on every relay on the connection.
- url actions forward the raw event. They POST a JSON envelope signed
  with X-Relay-Signature.
- agent actions can be built from the CLI. They only deliver through an
  agent's event trigger, so the guide now says to use a url action.

Also: rendered template values are always strings, pathVariables are
templated, update replaces lists, delete leaves the source webhook,
retries, and one relay per source connection. --metadata and
--webhook-secret help text say the same. Version bump so installed
skill files refresh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paulkr
paulkr merged commit 804f490 into main Nov 20, 2026
8 checks passed
@paulkr
paulkr deleted the docs/relay-server-behaviour branch November 20, 2026 02:39
paulkr added a commit to RachitSrivastava12/cli that referenced this pull request Nov 20, 2026
main took 2.16.1 (withoneai#244) while this PR was open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant