Simplify Agent Relay core surfaces#1010
Merged
Merged
Conversation
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
Contributor
|
Important Review skippedToo many files! This PR contains 298 files, which is 148 over the limit of 150. To get a review, narrow the scope: ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (298)
You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 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 |
![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: 86fe101dd6
ℹ️ 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".
| "@agent-relay/config": "7.1.1", | ||
| "@agent-relay/hooks": "7.1.1", | ||
| "@agent-relay/memory": "7.1.1", | ||
| "@agent-relay/driver": "7.1.1", |
There was a problem hiding this comment.
Adding @agent-relay/driver as a runtime dependency means the agent-relay npm package cannot be installed until that exact driver version exists on npm. I checked the publish workflow matrices (.github/workflows/publish.yml publish-sdk-internal-deps lines 801-807 and publish-packages lines 1017-1035), and none of them publish driver, so a release of the CLI will point at an unpublished @agent-relay/driver@7.1.1 and fresh installs fail with an npm not-found/dependency resolution error.
Useful? React with 👍 / 👎.
Comment on lines
+28
to
32
| "./capabilities": { | ||
| "types": "./dist/capabilities.d.ts", | ||
| "import": "./dist/capabilities.js", | ||
| "default": "./dist/capabilities.js" | ||
| } |
There was a problem hiding this comment.
This shortened SDK export map removes the broker-path/driver APIs, but the SDK release smoke still imports them: .github/workflows/publish.yml uses @agent-relay/sdk/broker-path at line 717 and AgentRelayClient from @agent-relay/sdk at line 737, and scripts/post-publish-verify/verify-install.sh does the same at line 232. Any SDK publish/smoke run will now fail before validating the package unless those checks are moved to @agent-relay/driver or the compatibility exports are kept.
Useful? React with 👍 / 👎.
| @@ -1,59 +0,0 @@ | |||
| { | |||
There was a problem hiding this comment.
Deleting this package directory leaves the package=all release workflow pointing at paths that no longer exist: I checked .github/workflows/publish.yml and the publish-packages matrix still includes acp-bridge and openclaw at lines 1027-1028. Those matrix jobs run with working-directory: packages/${{ matrix.package }}, so the next all-package release will fail as soon as it tries to publish either deleted package.
Useful? React with 👍 / 👎.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
4 issues found across 269 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="packages/sdk/src/delivery/runner.ts">
<violation number="1" location="packages/sdk/src/delivery/runner.ts:38">
P1: `stop()` does not cancel the inbox subscription, so the runner can hang indefinitely while waiting for the next message.</violation>
<violation number="2" location="packages/sdk/src/delivery/runner.ts:81">
P1: Exceptions from `onError` prevent `inbox.fail(...)` from running, which can leave errored items without delivery-state updates and terminate processing.</violation>
</file>
<file name="packages/driver/package.json">
<violation number="1" location="packages/driver/package.json:43">
P1: Add a `prepack` hook so this package builds before `npm pack`/`npm publish`; otherwise it can be published without the `dist` files that `main`/`exports` reference.</violation>
</file>
<file name="packages/driver/src/broker-driver.ts">
<violation number="1" location="packages/driver/src/broker-driver.ts:53">
P1: Don't auto-spawn a broker in the shared client initializer; status/release should require an existing client or separate initialization path.</violation>
</file>
Note: This PR contains a large number of files. cubic only reviews up to 100 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.
Re-trigger cubic
| private async run(): Promise<void> { | ||
| await this.options.delivery.connect?.(); | ||
| try { | ||
| for await (const item of this.options.messaging.inbox.subscribe({ |
There was a problem hiding this comment.
P1: stop() does not cancel the inbox subscription, so the runner can hang indefinitely while waiting for the next message.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/sdk/src/delivery/runner.ts, line 38:
<comment>`stop()` does not cancel the inbox subscription, so the runner can hang indefinitely while waiting for the next message.</comment>
<file context>
@@ -0,0 +1,89 @@
+ private async run(): Promise<void> {
+ await this.options.delivery.connect?.();
+ try {
+ for await (const item of this.options.messaging.inbox.subscribe({
+ agentName: this.options.agentName,
+ })) {
</file context>
| metadata: result.metadata, | ||
| }); | ||
| } catch (error) { | ||
| await Promise.resolve(this.options.onError?.(item, error)); |
There was a problem hiding this comment.
P1: Exceptions from onError prevent inbox.fail(...) from running, which can leave errored items without delivery-state updates and terminate processing.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/sdk/src/delivery/runner.ts, line 81:
<comment>Exceptions from `onError` prevent `inbox.fail(...)` from running, which can leave errored items without delivery-state updates and terminate processing.</comment>
<file context>
@@ -0,0 +1,89 @@
+ metadata: result.metadata,
+ });
+ } catch (error) {
+ await Promise.resolve(this.options.onError?.(item, error));
+ await this.options.messaging.inbox.fail({
+ inboxItemId: item.id,
</file context>
| "package.json" | ||
| ], | ||
| "scripts": { | ||
| "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json", |
There was a problem hiding this comment.
P1: Add a prepack hook so this package builds before npm pack/npm publish; otherwise it can be published without the dist files that main/exports reference.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/driver/package.json, line 43:
<comment>Add a `prepack` hook so this package builds before `npm pack`/`npm publish`; otherwise it can be published without the `dist` files that `main`/`exports` reference.</comment>
<file context>
@@ -0,0 +1,67 @@
+ "package.json"
+ ],
+ "scripts": {
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+ "check": "tsc -p tsconfig.json --noEmit"
+ },
</file context>
|
|
||
| private async ensureClient(): Promise<AgentRelayClient> { | ||
| if (!this.client) { | ||
| this.client = await AgentRelayClient.spawn(this.options); |
There was a problem hiding this comment.
P1: Don't auto-spawn a broker in the shared client initializer; status/release should require an existing client or separate initialization path.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/driver/src/broker-driver.ts, line 53:
<comment>Don't auto-spawn a broker in the shared client initializer; status/release should require an existing client or separate initialization path.</comment>
<file context>
@@ -0,0 +1,79 @@
+
+ private async ensureClient(): Promise<AgentRelayClient> {
+ if (!this.client) {
+ this.client = await AgentRelayClient.spawn(this.options);
+ }
+ return this.client;
</file context>
There was a problem hiding this comment.
2 issues found across 4 files (changes from recent commits).
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="packages/sdk/src/delivery/runner.ts">
<violation number="1" location="packages/sdk/src/delivery/runner.ts:38">
P1: `stop()` does not cancel the inbox subscription, so the runner can hang indefinitely while waiting for the next message.</violation>
<violation number="2" location="packages/sdk/src/delivery/runner.ts:81">
P1: Exceptions from `onError` prevent `inbox.fail(...)` from running, which can leave errored items without delivery-state updates and terminate processing.</violation>
</file>
<file name="packages/driver/package.json">
<violation number="1" location="packages/driver/package.json:43">
P1: Add a `prepack` hook so this package builds before `npm pack`/`npm publish`; otherwise it can be published without the `dist` files that `main`/`exports` reference.</violation>
</file>
<file name="packages/driver/src/broker-driver.ts">
<violation number="1" location="packages/driver/src/broker-driver.ts:53">
P1: Don't auto-spawn a broker in the shared client initializer; status/release should require an existing client or separate initialization path.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
There was a problem hiding this comment.
3 issues found across 1 file (changes from recent commits).
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="packages/sdk/src/delivery/runner.ts">
<violation number="1" location="packages/sdk/src/delivery/runner.ts:38">
P1: `stop()` does not cancel the inbox subscription, so the runner can hang indefinitely while waiting for the next message.</violation>
<violation number="2" location="packages/sdk/src/delivery/runner.ts:81">
P1: Exceptions from `onError` prevent `inbox.fail(...)` from running, which can leave errored items without delivery-state updates and terminate processing.</violation>
</file>
<file name="packages/driver/package.json">
<violation number="1" location="packages/driver/package.json:43">
P1: Add a `prepack` hook so this package builds before `npm pack`/`npm publish`; otherwise it can be published without the `dist` files that `main`/`exports` reference.</violation>
</file>
<file name="packages/driver/src/broker-driver.ts">
<violation number="1" location="packages/driver/src/broker-driver.ts:53">
P1: Don't auto-spawn a broker in the shared client initializer; status/release should require an existing client or separate initialization path.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
There was a problem hiding this comment.
2 issues found across 1 file (changes from recent commits).
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="packages/sdk/src/delivery/runner.ts">
<violation number="1" location="packages/sdk/src/delivery/runner.ts:38">
P1: `stop()` does not cancel the inbox subscription, so the runner can hang indefinitely while waiting for the next message.</violation>
<violation number="2" location="packages/sdk/src/delivery/runner.ts:81">
P1: Exceptions from `onError` prevent `inbox.fail(...)` from running, which can leave errored items without delivery-state updates and terminate processing.</violation>
</file>
<file name="packages/driver/package.json">
<violation number="1" location="packages/driver/package.json:43">
P1: Add a `prepack` hook so this package builds before `npm pack`/`npm publish`; otherwise it can be published without the `dist` files that `main`/`exports` reference.</violation>
</file>
<file name="packages/driver/src/broker-driver.ts">
<violation number="1" location="packages/driver/src/broker-driver.ts:53">
P1: Don't auto-spawn a broker in the shared client initializer; status/release should require an existing client or separate initialization path.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
…codex/core-simplification
…codex/core-simplification
Rename @agent-relay/runtime to @agent-relay/harness-driver across the repo for a SemVer-major release. Update APIs and exports (RuntimeClient → HarnessDriverClient and companion types such as Options/Events/ProtocolError), move package sources (packages/runtime → packages/harness-driver), and adjust imports, tests, and docs (README, CHANGELOG, CORE_SIMPLIFICATION_SCOPE, SDK rules, web docs). Also add harness-driver to CI publish matrices, update .gitignore and workspace/package manifests, and refresh related tooling configs (knip, package.json, tsconfigs, etc.) to reflect the new package boundary.
Update README and harness-driver docs to reflect recent SDK API changes. README quickstart: createWorkspace now returns a relay/client (workspaceKey available), reflowed step numbering, switch realtime APIs to client.events.on(...) and client.events.connect()/subscribe(), replace send(...) with sendMessage({...}), and use client.events.disconnect() for cleanup. harness-driver docs: rename sample file, replace createRuntime/registerRuntimeActions with BrokerDriver and registerDriverActions, remove manual relay.actions.register examples and add a concise agent.create invocation example; document actionPrefix and that BrokerDriver is the built-in managed driver.
Introduce relay-bound BrokerDriver and live PTY spawning for harnesses. Added packages/harnesses/src/broker-binding.ts which caches one BrokerDriver per AgentRelay and requires a workspace key (sets RELAY_API_KEY) or throws a clear error. Modified definePtyHarness to accept create({ relay }) to spawn a live PTY via the driver (handle keyed by registered agent name) while preserving the descriptor-only create/new behavior when relay is omitted. Added tests (define-spawn.test.ts, readme-quickstart.test.ts) and updated SDK session helpers (defineHarness, nextHarnessName, harness agent shapes) plus README, CHANGELOG, and migration docs to document the new spawn/workspace model and example usage.
Add a collection of new v8 documentation pages (actions-callbacks, channels, cli-agent-management, cli-broker-lifecycle, cli-messaging, dms, emoji-reactions, and related docs), update docs links and nav (docs-nav icons and docs-nav data), and add CLI/SDK framing and references to /docs/8.0.0. Adjust blog index to move the RSS icon into the section header and update CSS (.blogHeader removed, .sectionTitleRow added). Edit the blog post content and metadata (title, description, and copy refinements). Also append a decision entry to the active trajectory JSON.
Mark the trajectory as completed: remove the active .agentworkforce trajectory and add completed artifacts (trace.json, trajectory.json, summary.md) under .agentworkforce/trajectories/completed/2026-06/. Also update CHANGELOG.md and package metadata (packages/cli, packages/openclaw, packages/sdk) and refresh package-lock.json.
Remove the separate actions-callbacks doc and merge its content into actions.mdx, updating examples, schema shapes, and API guidance (facade vs registry) accordingly. Adjust references across the site (quickstart, cli-overview, webhooks) to use the unified "Actions" page. Update docs navigation and grouping (rename sections, add Interfaces group, reorder items) and remove the now-unused actions-callbacks nav icon mapping.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
workspaceKey/RELAY_WORKSPACE_KEYand keepapiKey/RELAY_API_KEYonly as compatibility aliases@agent-relay/driverto@agent-relay/runtimeand add@agent-relay/harnessesas the CLI harness catalogVerification
npm run build:corenpm --prefix packages/sdk test(35 tests)npm --prefix packages/openclaw test(83 tests, run with loopback access)npm run knipgit diff --cached --checkAgent Relay Core Simplification Scope
This document defines the package boundary for the SemVer-major Agent Relay core simplification and records what remains in scope after the implementation cutover.
Product framing
Agent Relay is the public product. It provides real-time coordination between AI agents, tools, services, and humans through shared workspaces.
The backing message bus is an implementation detail. Public docs should lead with Agent Relay concepts: messaging, delivery, and actions. Transport-specific names should appear only in code internals, compatibility notes, or migration details that cannot be explained accurately otherwise.
Core SDK scope
@agent-relay/sdkis the core communication SDK. It should document and expose the primitives needed by any runtime that wants to participate in Agent Relay:The core SDK should remain useful in service agents, hosted agents, browser-compatible clients, tests, terminal harness integrations, and human-operated tooling.
Out of core SDK scope
The following capabilities are not core SDK responsibilities:
Those features can still exist in Agent Relay. They should be documented as optional layers rather than the core SDK contract.
Package split
@agent-relay/sdk@agent-relay/harness-driveragent-relayThe dependency direction should stay simple: runtime depends on the SDK, not the other way around.
Documentation requirements
@agent-relay/sdkas messaging, delivery/read state, presence, and action APIs.@agent-relay/harness-driveras optional managed harness infrastructure.Migration guidance
@agent-relay/sdk.@agent-relay/harness-driver.Removed from this branch
Kept as adapters
@agent-relay/openclawremains as an OpenClaw adapter package and uses SDK messaging plus@agent-relay/harness-driverfor managed spawn internals instead of spawn-first SDK APIs.Moved out
@agent-relay/acp-bridgelives inAgentWorkforce/agent-relay-acp-bridgeand is no longer a workspace package in this repository.Non-goals