RFC: Remote Agent Harness Bridge and Event Protocol

[efpiva]

Summary

Adds a draft RFC for a first-class remote AgentHarness bridge and event protocol. This expands the remote harness direction from #29 with a fuller protocol/workflow contract covering event preservation, Gateway-owned decisions, terminal persistence, transport/container boundaries, and conformance expectations.

Notes

• Draft status: this is intended for review/discussion, not merge as accepted.
• Related draft: RFC: Remote Agent Harness Bridge #29.
• Maintainer discussion thread: pending.
• issue remains blank until acceptance, per RFC lifecycle.

Validation

• git diff --check
• RFC shape/placeholder checks locally

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 6, 2026, 7:57 AM ET / 11:57 UTC.

ClawSweeper review

What this changes

Adds a draft RFC and supporting reference for a transport-neutral remote AgentHarness bridge that preserves events and Gateway-owned decisions across a remote host boundary.

Merge readiness

⚠️ Ready for maintainer review - 9 items remain

Keep open for maintainer design review. This docs-only RFC is not on current main, and acceptance remains blocked on the required discussion plus a contradictory v1 workspace-data boundary.

Priority: P2
Reviewed head: b337b35023421ecc87f58fe46a8389d632f119ce
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is detailed and useful, but unresolved contract decisions and required lifecycle discussion prevent acceptance.
Proof confidence	🌊 off-meta tidepool	Not applicable: This RFC-only documentation PR changes no runnable behavior; real behavior proof is not applicable.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This RFC-only documentation PR changes no runnable behavior; real behavior proof is not applicable.
Evidence reviewed	4 items	Current main does not contain the RFC: The proposed RFC and its supporting reference are absent from current main, so the requested public contract is not already implemented in this repository. RFC lifecycle requires discussion: The repository requires every new RFC to have a maintainer-discussion thread; the RFC has no such link, while the PR body says that discussion is pending. Workspace boundary is internally unresolved: The v1 context schema includes host-visible workspaceDir and cwd, but the RFC still lists opaque workspaceId versus workspace path/mount exposure as unresolved.
Findings	3 actionable findings	[P2] Link the required maintainer discussion [P2] Resolve workspace-path exposure before fixing the v1 context [P3] Update the RFC revision date
Security	Needs attention	Workspace paths cross an unresolved host boundary: The v1 schema permits host-visible workspaceDir and cwd even though the RFC still leaves workspace metadata exposure undecided, risking unnecessary path disclosure to remote harness hosts.

How this fits together

OpenClaw’s Gateway selects an AgentHarness for a provider/model turn and normally receives its lifecycle, output, and policy requests locally. This proposed bridge would carry those events and decisions to and from a separately hosted harness while keeping Gateway policy and persistence authoritative.

flowchart LR
  A[Provider or model policy] --> B[OpenClaw Gateway]
  B --> C[Remote harness bridge]
  C --> D[Host runtime]
  D --> E[Selected agent harness]
  E --> F[Events and decision requests]
  F --> B

Loading

Decision needed

Question	Recommendation
Should v1 standardize only opaque workspace identity, or permit workspace path and cwd metadata to cross into a remote host?	Approve opaque identity-only v1: Remove workspaceDir and cwd from the v1 context and defer any path or mount capability to a separately reviewed extension.

Why: This controls a public protocol and security boundary; the RFC itself lists the choice as unresolved while already defining path fields.

Before merge

• Add real behavior proof - Not applicable: This RFC-only documentation PR changes no runnable behavior; real behavior proof is not applicable.
• Link the required maintainer discussion (P2) - The repository lifecycle requires a maintainer-discussion thread for every new RFC, but this draft has no link and the PR body still says it is pending. Add the thread and record the resulting decisions before this becomes an accepted contract.
• Resolve workspace-path exposure before fixing the v1 context (P2) - Late review: the schema permits workspaceDir and cwd, but the unresolved questions still ask whether v1 exposes anything beyond opaque workspaceId. Choose and document one boundary before implementations treat these paths as part of the public protocol.
• Update the RFC revision date (P3) - The final clarification commit is dated July 7, but frontmatter still reports last_updated: 2026-07-06; update it so readers can identify the current draft revision.
• Resolve security concern: Workspace paths cross an unresolved host boundary - The v1 schema permits host-visible workspaceDir and cwd even though the RFC still leaves workspace metadata exposure undecided, risking unnecessary path disclosure to remote harness hosts.
• Resolve merge risk (P1) - Merging a versioned protocol before resolving whether workspace paths and cwd cross the remote-host boundary could normalize sensitive host metadata exposure.
• Resolve merge risk (P1) - Without the required maintainer discussion, the RFC’s transport, frame, package-ownership, and compatibility choices lack an accepted product contract.
• Complete next step (P2) - A maintainer must choose the public workspace-metadata and v1 protocol boundary before a documentation repair can be safely scoped.

Findings

• [P2] Link the required maintainer discussion — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:10
• [P2] Resolve workspace-path exposure before fixing the v1 context — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:361-362
• [P3] Update the RFC revision date — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:7
• [medium] Workspace paths cross an unresolved host boundary — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:361

Agent review details

Security

Needs attention: The RFC introduces a security-sensitive remote-host metadata boundary that must be resolved before acceptance.

Review metrics

Metric	Value	Why it matters
Protocol proposal surface	2 new RFC documents, 858 added lines	The entire change defines a new public protocol contract, so its unresolved compatibility and security choices need explicit acceptance.

Root-cause cluster

Relationship: canonical
Canonical: #31
Summary: This PR is the canonical open remote-harness RFC; the earlier draft was explicitly closed in favor of it.

Members:

• superseded: RFC: Remote Agent Harness Bridge #29 - Its author explicitly closed that earlier remote-harness draft in favor of this broader RFC.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Resolve the public contract before merge (recommended)
   Link the required maintainer discussion, decide the workspace metadata boundary, and align the schema, unresolved questions, and revision metadata with that decision.
2. Keep the RFC as a draft proposal
   Leave the branch open for discussion without treating its v1 frame and metadata schema as an accepted compatibility contract.

Technical review

Best possible solution:

Settle the v1 scope in the maintainer discussion, keep opaque workspace identity by default unless an explicit metadata capability is accepted, then publish the resulting contract with current revision metadata.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is an RFC-only documentation change with no implemented runtime behavior to reproduce.

Is this the best way to solve the issue?

No: the proposed contract should not be accepted until the required discussion resolves the workspace metadata boundary and the RFC consistently reflects that choice.

Full review comments:

• [P2] Link the required maintainer discussion — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:10
  The repository lifecycle requires a maintainer-discussion thread for every new RFC, but this draft has no link and the PR body still says it is pending. Add the thread and record the resulting decisions before this becomes an accepted contract.
  Confidence: 0.99
• [P2] Resolve workspace-path exposure before fixing the v1 context — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:361-362
  Late review: the schema permits workspaceDir and cwd, but the unresolved questions still ask whether v1 exposes anything beyond opaque workspaceId. Choose and document one boundary before implementations treat these paths as part of the public protocol.
  Confidence: 0.95
  Late finding: first raised on code an earlier review cycle already covered.
• [P3] Update the RFC revision date — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:7
  The final clarification commit is dated July 7, but frontmatter still reports last_updated: 2026-07-06; update it so readers can identify the current draft revision.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.96

AGENTS.md: found, but no applicable review policy affected this item.

Codex review notes: model internal, reasoning high; reviewed against af708f0ddb6f.

Labels

Label justifications:

• P2: The PR proposes a broad but non-emergency public execution and event protocol requiring maintainer decisions.
• merge-risk: 🚨 compatibility: The new versioned frame, transport, and context schema would become an interoperability contract for remote-host implementations.
• merge-risk: 🚨 security-boundary: The proposed v1 context includes host-visible workspace paths while the RFC still leaves workspace metadata exposure unresolved.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This RFC-only documentation PR changes no runnable behavior; real behavior proof is not applicable.

Evidence

Security concerns:

• [medium] Workspace paths cross an unresolved host boundary — rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:361
  The v1 schema permits host-visible workspaceDir and cwd even though the RFC still leaves workspace metadata exposure undecided, risking unnecessary path disclosure to remote harness hosts.
  Confidence: 0.95

What I checked:

• Current main does not contain the RFC: The proposed RFC and its supporting reference are absent from current main, so the requested public contract is not already implemented in this repository. (rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md, af708f0ddb6f)
• RFC lifecycle requires discussion: The repository requires every new RFC to have a maintainer-discussion thread; the RFC has no such link, while the PR body says that discussion is pending. (README.md:83, af708f0ddb6f)
• Workspace boundary is internally unresolved: The v1 context schema includes host-visible workspaceDir and cwd, but the RFC still lists opaque workspaceId versus workspace path/mount exposure as unresolved. (rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:361, b337b3502342)
• Head provenance and review continuity: The current head is the July 7 clarification commit; comparison of that head with the prior reviewed head is empty, so the previously raised lifecycle and revision-date findings remain unresolved. (rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md:7, b337b3502342)

Likely related people:

• omarshahine: He authored multiple merged RFC changes, authored the earlier remote-harness RFC, and supplied the detailed contract-boundary review for this proposal. (role: recent RFC contributor and remote-harness boundary reviewer; confidence: high; commits: c876de6210bf, 89f22c320e30; files: README.md, rfcs/0010-remote-agent-harness-bridge-and-event-protocol.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Link the maintainer-discussion thread and capture its decisions.
• Resolve the workspace identity versus path-metadata boundary in the schema and unresolved questions.
• Update the frontmatter revision date.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (22 earlier review cycles; latest 8 shown)

• reviewed 2026-08-03T06:40:12.372Z sha b337b35 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-03T17:33:34.905Z sha b337b35 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-05T10:31:17.132Z sha b337b35 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-05T12:09:17.838Z sha b337b35 :: needs real behavior proof before merge. :: [P3] Update the RFC revision date
• reviewed 2026-08-05T16:33:56.534Z sha b337b35 :: needs real behavior proof before merge. :: [P3] Update the RFC revision date
• reviewed 2026-08-05T22:45:13.459Z sha b337b35 :: needs real behavior proof before merge. :: [P3] Update the RFC revision date
• reviewed 2026-08-06T03:01:03.610Z sha b337b35 :: needs real behavior proof before merge. :: [P3] Update the RFC revision date
• reviewed 2026-08-06T10:16:09.718Z sha b337b35 :: needs real behavior proof before merge. :: [P2] Link the required maintainer discussion | [P3] Update the RFC revision date

[omarshahine]

I'm closing #29 in favor of this draft.

This PR has the stronger shape for the remote AgentHarness proposal because it covers the bridge and the event protocol together: event preservation, Gateway-owned decisions, terminal/persistence semantics, transport/container boundaries, and conformance expectations. Let's use this as the canonical RFC discussion thread.

[omarshahine]

Reviewed this against the remote-harness implementation we built in Lobster.

Two correctness issues to fix before treating this as the authoritative upstream contract:

1. Transport naming/status does not match the implemented bridge. The RFC uses generic host-adapter language and leaves the name open as hostUri / hostAdapter, but the portable plugin schema currently accepts fakeUri as the host-adapter transport and explicitly rejects connector and grpc fail-closed. The Lobster reverse-proxy gate is also specifically tied to the fake URI route being admitted only while trusted runtime state says remote-harness dispatch is active. Either make the RFC intentionally rename fakeUri to the upstream term and call out the migration, or use the implemented fakeUri name in v1 and leave a rename as an unresolved bikeshed. Right now it reads like a new contract that does not map cleanly to the checked-in implementation.

2. The v1 frame tables are broader and differently shaped than the implemented protocol. The current plugin contract has RunStart, approval/tool/memory decisions, cancel/reset/compact/heartbeat, ModelRequest from host to gateway, and ModelChunk / ModelFinal / ModelError back to host. RunAccepted uses selected_inner_harness_id and selected_inner_harness_version. This RFC instead defines ModelProxyRequest / ModelProxyChunk / ModelProxyFinal / ModelProxyError, camelCase selectedInnerHarnessId, and many additional frames (AgentEvent, PermissionRequested, UserInputRequested, DynamicToolCallRequested, VisibleReply, usage/lifecycle/plan/item/patch/compaction streams, etc.). I agree with the direction, but the RFC should explicitly say these are proposed upstream v1 changes beyond Lobster’s current portable plugin, or split them into “current bridge baseline” and “proposed event-protocol expansion.” Without that, implementers will assume Lobster already proves this exact v1 schema, which it does not.

Validation I ran:

• git diff --check origin/main...origin/pr/31 in openclaw/rfcs: passed.
• python3 scripts/remote_harness_contract_test.py in Lobster: passed.
• python3 scripts/remote_harness_platform_test.py in Lobster: passed.
• npm test -- --run tests/protocolSerde.test.ts tests/remoteHarness.test.ts in the portable plugin checkout: could not run because vitest is not installed in that package checkout.

Suggested next edit: add a short “Relationship to Lobster implementation” section that names the current portable baseline, then marks the richer event frames as the proposed upstream contract and lists the required migration points (fakeUri naming, model frame naming, RunAccepted field casing, and newly required decision/event frames).

[omarshahine]

One clarification on the intent: the goal is not to document Lobster’s current side version as-is. The goal is to get an upstream OpenClaw contract we can consume directly and build on, so Lobster does not keep carrying a divergent remote-harness dialect.

That means the RFC should draw a crisp boundary:

• Upstream-owned: portable remote-harness plugin shape, protocol envelope, frame names/field casing, event preservation contract, fail-closed selection semantics, conformance fixtures, and SDK/package ownership.
• Lobster-owned adapter layer: runtime rollout gates, ECS/feature-flag targeting, fake URI / reverse-proxy admission, container allocation, ProxyPipe transport plumbing, deployment health gates, and any Microsoft-specific identity/routing concerns.

For the current mismatch with Lobster, I would prefer the RFC not merely say “Lobster does X today.” It should define the upstream target contract and list the migration needed for Lobster to adopt it without forking:

• settle the upstream host-adapter transport name and map/migrate Lobster’s current fakeUri implementation to it;
• settle canonical frame names and casing, then update Lobster’s plugin if the RFC chooses ModelProxy* and camelCase RunAccepted fields;
• decide whether the richer event frames are required for upstream v1 or staged behind a version/capability gate;
• make conformance fixtures executable enough that Lobster can replace side-version assertions with upstream fixtures.

The acceptance criterion I care about: after this RFC lands, Lobster should be able to delete or thin its local protocol decisions and treat upstream OpenClaw as the source of truth, with only the runtime/container adapter remaining Lobster-specific.

[efpiva]

Thanks for the detailed review. I pushed an update that addresses this as a public upstream-contract boundary rather than documenting any host-specific side version.

Changes in b337b35:

• Added Upstream contract and host adapter boundary.
• Made the upstream contract own the portable remote-harness shape, protocol envelope, frame families/names/wire casing, event preservation semantics, fail-closed selection, conformance fixtures, and SDK/package ownership.
• Made host/container adapters own rollout/deployment policy, worker/container allocation, reverse-proxy/sidecar/service-mesh/service-DNS admission, certificates, retries, route auth, deployment health, and platform-specific routing below RunStart.
• Chose hostAdapter as the public v1 host adapter transport term.
• Clarified connector and grpc are not v1 OpenClaw transport kinds; connector-like reachability is handled by the host/container/platform layer outside the spec.
• Clarified host-specific aliases, URLs, hostnames, and routing terms are translated at the adapter boundary and do not become v1 protocol names unless this RFC lists them.
• Renamed reserved model-egress frames to ModelRequest, ModelChunk, ModelFinal, and ModelError.
• Added the v1 wire-casing rule: wire fields use the casing listed in the schema tables; adapter-local aliases are not v1 conformance surface.
• Clarified richer event preservation: v1 preserves event classes the selected inner harness observes or produces; a host does not need to synthesize unsupported event classes, but must not collapse supported structured events into plain text or terminal-only output.
• Clarified conformance depth: this RFC defines scenarios and reviewable golden transcript sketches; implementation PRs claiming v1 support should add executable fixtures or a fake-host test harness.
• Removed product/internal implementation names from the public RFC text.

Still intentionally draft/open for maintainer discussion:

• whether reserved model-egress frames should remain in v1 or move entirely to a follow-up RFC;
• which package owns the public frame types;
• whether v1 should carry only opaque workspaceId or expose workspace path/mount metadata;
• extension stream allowlisting policy;
• whether the Gateway should require hosts to emit both typed frames and canonical events, or synthesize canonical events from typed frames;
• whether native subagent/task mirroring belongs in this RFC or a follow-up.

I’ll keep this as draft until those public upstream naming/versioning/conformance decisions are settled.