[codex] Update node delivery docs#9
Conversation
📝 WalkthroughWalkthroughThis PR updates documentation and navigation to describe nodes, token types, delivery routing, and related SDK and CLI references across the site. ChangesDocumentation, tokens, and delivery routing
SDK, navigation, and CLI references
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request refactors the documentation to replace the concept of 'Fleets' with 'Nodes' as first-class delivery hosts, removing the fleets.mdx file and updating references across the documentation, CLI reference, and navigation. The feedback suggests minor improvements to the documentation, specifically adding the maxAgents configuration to the http_push node creation code example and clarifying redundant phrasing in the description of the manual acknowledgement mode.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| const node = await relay.nodes.create({ | ||
| name: 'billing-agent-http', | ||
| kind: 'http_push', | ||
| delivery: { |
There was a problem hiding this comment.
The text below mentions that http_push nodes default to maxAgents: 1 and that this can be raised. It would be helpful to show where maxAgents is configured in the relay.nodes.create payload within the code example.
const node = await relay.nodes.create({
name: 'billing-agent-http',
kind: 'http_push',
maxAgents: 1,
delivery: {
|
|
||
| `ackMode` controls acknowledgement: | ||
|
|
||
| - `manual` leaves the delivery delivered until the receiver calls the ack endpoint with the bound agent token. |
There was a problem hiding this comment.
The phrase 'leaves the delivery delivered' is slightly redundant. Clarifying that it records the delivery as delivered and waits for the receiver to acknowledge it makes the explanation clearer and consistent with the description in nodes.mdx.
- `manual` records the delivery as `delivered` and waits for the receiver to call the ack endpoint with the bound agent token.
|
Preview deployed!
This is a Cloudflare Workers preview version of this PR's build. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7642674788
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| title: 'Delivery and sessions', | ||
| items: [ | ||
| { title: 'Delivery', slug: 'delivery' }, | ||
| { title: 'Nodes', slug: 'nodes' }, |
There was a problem hiding this comment.
When this replacement adds nodes and removes the old fleets slug/file, existing /docs/fleets and /docs/fleets.md URLs no longer resolve: generateStaticParams() only includes getAllDocSlugs(), and getDefaultDocsVersionForSlug('fleets') falls through to v8 where getDoc('fleets') returns null and the docs page 404s. Since this is a rename/replacement of the Fleets guidance, users with bookmarks, search results, or external links to the old page lose the migration path unless we add a redirect or a stub alias to /docs/nodes.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@web/content/docs/nodes.mdx`:
- Around line 77-85: The `ackMode` documentation in the `nodes` content and the
corresponding Delivery page need a normative contract for `response`, since
`response` is currently described too loosely. Update the `ackMode` section to
explicitly define the accepted response schema and malformed-response behavior
for `response`, using the `ackMode` description and the Delivery page wording
consistently so both docs say the same thing.
In `@web/content/docs/typescript-sdk.mdx`:
- Around line 131-132: The wording in the TypeScript SDK docs is misleading
because “REST resources use snake_case” implies the endpoint paths change, when
only request/response field names do. Update the copy near the SDK examples and
the Nodes reference so it clearly says REST fields use snake_case while
resources/endpoints remain unchanged, using the existing `deliveryAdapter`,
`activeAgents`, and `agentName` examples as the contrast.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 1f6b93a0-a3b6-4aef-9e88-f138733a9efa
📒 Files selected for processing (9)
web/content/docs/agent-relay-mcp.mdxweb/content/docs/delivery.mdxweb/content/docs/fleets.mdxweb/content/docs/introduction.mdxweb/content/docs/nodes.mdxweb/content/docs/reference-cli.mdxweb/content/docs/typescript-sdk.mdxweb/content/docs/workspaces.mdxweb/lib/docs-nav.ts
💤 Files with no reviewable changes (2)
- web/content/docs/fleets.mdx
- web/content/docs/reference-cli.mdx
| `ackMode` controls when Relay marks an HTTP push delivery as acknowledged: | ||
|
|
||
| | Mode | Meaning | | ||
| | --- | --- | | ||
| | `manual` | Relay records the delivery as delivered and waits for the receiver to call the delivery ack endpoint with the bound agent token. | | ||
| | `on_2xx` | Any 2xx HTTP response acknowledges the delivery. | | ||
| | `response` | The response body decides, for example `{ "ack": true }`. | | ||
|
|
||
| Use `on_2xx` or `response` for pure webhook receivers that should not store an agent token. Use `manual` only when the receiver can securely hold that token and ack after its own processing boundary. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Make the response ack contract explicit.
response is documented as “the response body decides” and { "ack": true } is only presented as an example. For a first-class delivery path, that leaves receivers guessing about the exact payload and malformed-response behavior, which can turn into retry/redrive loops. Please define the accepted response schema normatively here and mirror the same wording in the Delivery page.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@web/content/docs/nodes.mdx` around lines 77 - 85, The `ackMode` documentation
in the `nodes` content and the corresponding Delivery page need a normative
contract for `response`, since `response` is currently described too loosely.
Update the `ackMode` section to explicitly define the accepted response schema
and malformed-response behavior for `response`, using the `ackMode` description
and the Delivery page wording consistently so both docs say the same thing.
| The SDK uses camelCase (`deliveryAdapter`, `activeAgents`, `agentName`). REST resources use snake_case. | ||
| See [Nodes](/docs/nodes) for node kinds, HTTP ack modes, and agent-node binding behavior. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Clarify that snake_case applies to REST fields, not resources.
“REST resources use snake_case” reads like the endpoint paths change, but the resources here remain /v1/nodes...; it’s the request/response field names that differ. Rewording this avoids sending readers to the wrong contract surface.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@web/content/docs/typescript-sdk.mdx` around lines 131 - 132, The wording in
the TypeScript SDK docs is misleading because “REST resources use snake_case”
implies the endpoint paths change, when only request/response field names do.
Update the copy near the SDK examples and the Nodes reference so it clearly says
REST fields use snake_case while resources/endpoints remain unchanged, using the
existing `deliveryAdapter`, `activeAgents`, and `agentName` examples as the
contrast.
Document the node delivery model (node-only reliable delivery, broker vs direct roles, node-bound spawns), the per-machine broker stack (broker, broker-pty-engine, @agent-relay/harness-driver, action runners), the delivery and spawn flows, and a vocabulary table. Add it to the "Delivery and sessions" nav group. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Describe the node/fleet/capability/placement model and broker stack as it works today across the delivery-and-sessions pages: - nodes: add roles (broker/direct), fleets, capability kinds (spawn/action), defineNode, placement (capability/liveness/capacity/least-loaded), targeting (target_node/self), heartbeat roster, and node enrollment + identity - delivery: node-only realtime delivery, deliver/ack with per-agent seq, observer-only workspace stream, reactions/receipts/action-results - architecture: capabilities + placement in the action flow; concrete spawn flow (action.invoke/action.result, declared harness, via_node, resume) - actions: spawn and release as node actions, capabilities, placement - harnesses: spawn capabilities declare the harness the node runs - harness-driver: clarify it is the client SDK for the broker-pty-engine - session-capabilities: disambiguate session vs node capabilities Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Summary
Updates the current docs for the new first-class node delivery model from the relaycast node delivery contracts work.
direct_ws,fleet_ws,http_push,poll, node bindings, HTTP auth, and ack modes.agent-relay fleet ...CLI reference from current docs.Impact
Readers now see nodes as always-available delivery hosts instead of a per-workspace fleet feature flag. Agent registration is documented as identity creation/adoption, while node binding is documented as the delivery route for future messages.
Validation
npm --workspace web run testnpm run buildThe build passed with existing warnings for Next middleware deprecation and PostHog Edge runtime usage.
Summary by cubic
Replaces Fleets with first-class Nodes and documents node‑only reliable delivery, broker/direct roles, and spawn/release as actions. Adds Authentication and Architecture pages, updates Delivery/SDK/MCP/CLI, and removes the Fleets docs.
Refactors
direct_ws,fleet_ws,http_push,poll), roles (broker/direct), fleets and capability kinds (spawn/action), placement rules (capability → liveness → capacity → least‑loaded), targeted placement (target_node/self), heartbeat roster, enrollment andnt_live_*node tokens, agent binding, and HTTP ack modes (manual,on_2xx,response).deliver/delivery.ack(per‑agent sequencing, cumulative acks), reactions/reads/action results over the same channel, an observer‑only/v1/wsstream, and an HTTP push redrive note.@agent-relay/harness-driver, action runners), spawn flow (action.invoke/action.result, declared harness,via_node, resume), and vocabulary; Actions now document spawn/release as node actions; Harnesses clarify that spawn capabilities declare the harness; Session capabilities page disambiguates session vs node capabilities.rk_live_*,at_live_*,nt_live_*,ot_live_*), observer scopes/filters/lifecycle, and the observer WebSocket stream; updated TypeScript SDK (relay.nodesAPI and Observer Tokens API), MCP (implicitdirect_ws, node discovery), Events (workspace observer stream + required scopes), Workspaces (node binding and implicit direct routes), and CLI (remove Fleets, token prefix examples, add Authentication). Removed the Fleets page and nav; added Architecture/Nodes/Authentication to the nav.Migration
direct_ws.http_pushnode, bind the agent, and choosemanual,on_2xx, orresponseack mode.ot_live_*observer tokens for dashboards instead of sharing workspace keys.Written for commit 3709459. Summary will update on new commits.