Docs: nodes and providers#19
Conversation
📝 WalkthroughWalkthroughDocumentation across the site is rewritten to replace the broker/broker-pty-engine/action-runner model with a node + provider + agent runtime model, introducing "actions" vs "capacity" terminology. A new "Nodes and providers" page is added, navigation is updated, and related docs, CLI text, and one test expectation are revised. ChangesNode/Provider Documentation Model
Estimated code review effort: 2 (Simple) | ~15 minutes Sequence Diagram(s)sequenceDiagram
participant Client
participant Engine
participant Provider
participant AgentRuntime
Client->>Engine: POST /v1/nodes/:node/actions/:name/invoke
Engine->>Provider: route invoke to registering provider
Provider->>AgentRuntime: delegate spawn/release or run handler
Provider-->>Engine: action.completed / action.failed
Engine-->>Client: acknowledgement + result event
Possibly related PRs
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 updates the Agent Relay documentation to transition from the 'local broker' model to the new 'nodes and providers' architecture, renaming CLI commands from 'local' to 'node' and introducing a dedicated guide for nodes and providers. The review feedback highlights a couple of minor issues in the updated documentation: an inconsistent API call in a Python code example (using 'ctx.relay.send_message' instead of 'ctx.send_message') and a missing preposition ('to') in a sentence describing WebSocket connections.
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.
|
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: c6c9838ca0
ℹ️ 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".
Add the nodes-and-providers overview — workspace/agents/nodes/providers, action vs capacity registrations, node-addressed invoke, per-provider liveness, spawn wrapping, and the enroll + node up onboarding. Align the delivery, action, and CLI pages to the node-provider model: providers connect directly to the engine, the node's agent runtime hosts spawn/release capacity, and invocation is node-addressed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
9 issues found across 9 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="web/content/docs/nodes-and-providers.mdx">
<violation number="1" location="web/content/docs/nodes-and-providers.mdx:122">
P2: This example overwrites `agent["cli"]` from the harness selector (`claude`) to a full command string. Earlier in the page, `cli` is described as the field that addresses spawn capacity (e.g., `spawn:claude`). After this mutation, `ctx.spawn_agent(agent)` may no longer match the native `spawn:claude` capacity. Consider leaving `cli` unchanged and passing additional flags through an `args` key or `harnessConfig` instead, to keep the delegation routable.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
The introduction quickstart banner copy changed in #18; update the docs-markdown export assertion to the shipped text so the suite is green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
c6c9838 to
29821aa
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
web/content/docs/nodes.mdx (1)
184-184: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueMinor style: "all of the node's providers" → "all the node's providers".
LanguageTool flags this as unnecessarily verbose. Quick readability improvement.
Proposed fix
- across restarts; all of the node's providers share it. + across restarts; all the node's providers share it.🤖 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` at line 184, The wording in the node enrollment description is slightly verbose; update the sentence in nodes.mdx to use “all the node’s providers” instead of “all of the node’s providers” for cleaner readability. Keep the surrounding explanation about node token reuse and provider ownership unchanged.Source: Linters/SAST tools
web/content/docs/architecture.mdx (1)
8-8: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueHyphenate "end-to-end" when used as a compound modifier.
"end to end" should be "end-to-end" before the noun it modifies.
Proposed fix
- This page describes the - delivery side end to end: the node and provider model, the agent runtime that hosts sessions on a + This page describes the + delivery side end-to-end: the node and provider model, the agent runtime that hosts sessions on a🤖 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/architecture.mdx` at line 8, The phrase in the architecture docs uses “end to end” as a compound modifier, so update the wording in the affected prose to “end-to-end” where it appears before the noun; adjust the surrounding sentence in the documentation content so the phrasing is consistent and grammatically correct.Source: Linters/SAST tools
🤖 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-and-providers.mdx`:
- Line 25: The token notation in nodes-and-providers.mdx is inconsistent with
the rest of the docs: the text in the node identity section should use the same
`nt_live_*` prefix pattern used elsewhere. Update the wording around the
`nt_live_` token reference so it matches the shared notation and stays
consistent with the `name`/identity description in that section.
---
Nitpick comments:
In `@web/content/docs/architecture.mdx`:
- Line 8: The phrase in the architecture docs uses “end to end” as a compound
modifier, so update the wording in the affected prose to “end-to-end” where it
appears before the noun; adjust the surrounding sentence in the documentation
content so the phrasing is consistent and grammatically correct.
In `@web/content/docs/nodes.mdx`:
- Line 184: The wording in the node enrollment description is slightly verbose;
update the sentence in nodes.mdx to use “all the node’s providers” instead of
“all of the node’s providers” for cleaner readability. Keep the surrounding
explanation about node token reuse and provider ownership unchanged.
🪄 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: d8d69721-0583-4e5d-bfa3-5aecb8da37d4
📒 Files selected for processing (9)
web/content/docs/actions.mdxweb/content/docs/architecture.mdxweb/content/docs/harness-driver.mdxweb/content/docs/nodes-and-providers.mdxweb/content/docs/nodes.mdxweb/content/docs/orchestrating-with-actions.mdxweb/content/docs/reference-cli.mdxweb/lib/docs-nav.tsweb/lib/test/docs-markdown-components.test.ts
- Use the direct `ctx.send_message` helper in the spawn-wrap example, matching the stated ctx surface and the sibling `ctx.spawn_agent` call. - Broaden the Capability glossary entry to cover both actions and capacity. - Say capacity is "never materialized as an invokable action" so it does not read as contradicting the action.invoke dispatch frames on the Actions page. - Fix "connects to /v1/node/ws" grammar. - Scope the orchestrating cross-reference to the shared invocation model. - Keep the harness-driver caller/host boundary explicit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 participant
Documents the node-provider architecture: a workspace has agents that converse and nodes that do work, and providers attach to a node, connect directly to the engine, and register its capabilities.
Pages
nodes-and-providers.mdx(new): the newcomer overview — the workspace → nodes → providers → capabilities model, action vs capacity registrations, node-addressed invoke (POST /v1/nodes/:node/actions/:name/invoke) with a curl and SDK example, per-provider liveness, spawn wrapping, and thecloud enroll+node uponboarding. Added to the docs nav under "Delivery and sessions."architecture.mdx: the delivery deep-dive, rewritten to the provider topology — the engine is the hub, each provider connects directly to/v1/node/ws, and the node's agent runtime (Rust) hosts PTYs and registers spawn/release capacity.nodes.mdx: node, provider, capability (action/capacity), placement, heartbeat, and node API aligned to the provider model, including node-addressed invoke and provider retirement routes.actions.mdx: the node-actions section reframed to providers, capacity, node-addressed invoke, and spawn shadowing.harness-driver.mdx:@agent-relay/harness-driverdescribed as the client SDK for the node's agent runtime.cli-broker-lifecycle.mdx: retitled "Node lifecycle" —cloud enroll,node up, and node-runtime commands.reference-cli.mdx:nodeandfleetcommand groups pluscloud enroll.orchestrating-with-actions.mdx: one line noting registration and invocation are one model whether an agent connection or a node provider hosts the handler.Merge alongside the relay release that ships node providers (spec §8 step 5) — describes the end state.
🤖 Generated with Claude Code
Summary by cubic
Adds a newcomer “Nodes and providers” overview and rewrites docs to the provider model: providers attach to a node, connect directly to the engine, and register actions vs capacity. Documents node‑addressed invocation, per‑provider liveness, and spawn wrapping.
New Features
POST /v1/nodes/:node/actions/:name/invoke), per‑provider liveness,spawn:<harness>wrapping, and quick start (agent-relay cloud enroll+agent-relay node up). Added to docs nav.spawn:*/releasecapacity and owns PTYs; capability providers connect directly to/v1/node/ws; invocation is node‑addressed.ctx.spawnAgent; added provider retirement (DELETE /v1/nodes/:node/providers/:name) and clarified action name uniqueness within a node.fleet statusnow describes node/capability health from provider attachment; “Orchestrating with actions” notes the shared invocation model across agent‑ and node‑hosted handlers; harness driver docs frame@agent-relay/harness-driveras the PTY client for the node’s agent runtime.Bug Fixes
ctx.send_message; Capability glossary covers actions and capacity and notes capacity is never materialized as an invokable action; fixed “connects to/v1/node/ws” wording; alignednt_live_*token notation; tightened the orchestrating cross‑reference; kept the harness‑driver caller/host boundary explicit; updated the docs‑markdown export test to the current quickstart banner copy.Written for commit dc2c0a1. Summary will update on new commits.