Skip to content

refactor(gateway): consolidate client contracts#101012

Merged
RomneyDa merged 1 commit into
mainfrom
refactor/gateway-client-contract
Jul 8, 2026
Merged

refactor(gateway): consolidate client contracts#101012
RomneyDa merged 1 commit into
mainfrom
refactor/gateway-client-contract

Conversation

@RomneyDa

@RomneyDa RomneyDa commented Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Related: #100977

What Problem This Solves

The core gateway client and the shared gateway-client package maintained parallel option, event, error, validation, and connection-metadata contracts. That duplication made the internal client boundary easy to drift and required core-specific casts and repeated frame guards.

Why This Change Was Made

This makes @openclaw/gateway-client the canonical client contract owner and moves lightweight inbound frame validation to the published @openclaw/gateway-protocol/frame-guards leaf. The core facade retains only OpenClaw-owned dependency injection and defaults. The dedicated leaf avoids pulling the large TypeBox schema runtime into the reusable client, while package build, TS/Vitest resolution, and plugin source-loader entries cover the repository's existing resolution modes.

The request method stays validated directly at the client boundary because request IDs are generated internally with randomUUID(); no exported one-caller request validator or unreachable ID branch remains. The complete PR is net negative: 208 additions / 239 deletions (net -31).

User Impact

No user-visible runtime behavior changes. Maintainers get one canonical gateway client contract path, preserved permissive inbound frame handling, private connection secrets, and fewer duplicate declarations and one-use helpers.

Evidence

  • Rebased onto current origin/main 534ace4d8a4988c8fbcd54ada1209a86eb12dcc4; current PR head e62ab453dd2dea832f7c6d735e0395c3eb1dcaef.
  • Blacksmith Testbox tbx_01kx1944meqepwmps1watngd1g (violet-prawn), Actions run https://github.com/openclaw/openclaw/actions/runs/28958947642: 278 focused tests passed (18 package/protocol unit, 183 gateway, 77 plugin loader aliases).
  • @openclaw/gateway-protocol build, @openclaw/gateway-client build, and repository root tsdown build passed.
  • Explicit path-scoped check:changed passed, including full tsgo project typecheck, core/extensions/scripts lint, guards, and runtime import-cycle check.
  • Fresh current-main full-branch Codex autoreview reported no actionable findings (patch is correct, confidence 0.86).

@openclaw-barnacle openclaw-barnacle Bot added app: web-ui App: web-ui gateway Gateway runtime size: M maintainer Maintainer-authored PR labels Jul 6, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jul 6, 2026
Merged
@clawsweeper

clawsweeper Bot commented Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 8, 2026, 12:54 PM ET / 16:54 UTC.

Summary
This branch moves gateway client option/error/metadata contracts into packages/gateway-client, adds a @openclaw/gateway-protocol/frame-guards subpath, and updates the core facade plus build/test/plugin-loader aliases.

PR surface: Source -134, Tests +94, Config +8, Other +1. Total -31 across 11 files.

Reproducibility: not applicable. This PR is an internal refactor, not a user-visible bug report. Source inspection on current main confirms the duplicated gateway client and protocol contracts that the PR targets.

Review metrics: 1 noteworthy metric.

  • Protocol package subpath: 1 added. The new @openclaw/gateway-protocol/frame-guards export must stay aligned across package exports, build entries, TS/Vitest aliases, and plugin-loader aliases before merge.

Stored data model
Persistent data-model change detected: vector/embedding metadata: packages/gateway-client/src/client.watchdog.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #100977
Summary: This PR is the gateway-client/protocol implementation slice for the open Wave 1 internal type-contract cleanup umbrella.

Members:

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

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

  • [P1] The PR is protected by maintainer and changes an internal package subpath/contract boundary, so automation should not close or merge it without maintainer sequencing intent.
  • [P1] Three exact-head CI jobs were still in progress in the live check rollup, so final merge readiness depends on required checks completing on e62ab453dd2dea832f7c6d735e0395c3eb1dcaef.

Maintainer options:

  1. Decide the mitigation before merge
    Land this gateway slice after maintainer review and exact-head checks, keeping package-owned client contracts and protocol-owned lightweight frame guards aligned across exports, build entries, and aliases.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • [P2] Protected member-authored refactor has no actionable automated repair; the next step is maintainer review plus exact-head check completion.

Maintainer decision needed

  • Question: Should maintainers land this gateway-client/protocol consolidation as the gateway slice of the Wave 1 internal type-contract cleanup once exact-head checks finish?
  • Rationale: The PR is protected by the maintainer label, is assigned to the cleanup owner, and changes an internal package subpath/API boundary that should be sequenced by a human maintainer.
  • Likely owner: RomneyDa — RomneyDa owns the umbrella cleanup plan, is assigned to this PR, and authored the current gateway-client/protocol implementation slice.
  • Options:
    • Land this gateway slice (recommended): Review and land this PR after required exact-head checks finish, preserving the new protocol frame-guards leaf and package-owned gateway client metadata contract.
    • Hold for umbrella sequencing: Keep this PR open until maintainers decide whether remaining Wave 1 cleanup should land in a particular order or batch.
    • Request a narrower reroll: Ask for a reroll only if maintainers do not want the new protocol guard subpath or package-owned metadata surface in this slice.

Security
Cleared: No concrete security or supply-chain concern found; the diff changes internal package exports, local guards, tests, and resolver aliases without changing workflows, dependencies, lockfiles, secrets, or permissions.

Review details

Best possible solution:

Land this gateway slice after maintainer review and exact-head checks, keeping package-owned client contracts and protocol-owned lightweight frame guards aligned across exports, build entries, and aliases.

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

Not applicable: this PR is an internal refactor, not a user-visible bug report. Source inspection on current main confirms the duplicated gateway client and protocol contracts that the PR targets.

Is this the best way to solve the issue?

Yes. Moving shared client contracts to packages/gateway-client, moving lightweight frame guards to packages/gateway-protocol, and leaving core with only host dependency injection is the narrow owner-boundary fix for the duplicated-contract problem.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

  • P3: This is a low-risk internal maintainability refactor with no intended user-visible runtime behavior change.
  • rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Maintainer/member internal refactor; the external contributor real-behavior proof gate does not apply, and the PR body supplies Testbox/build/check evidence for maintainer review.
Evidence reviewed

PR surface:

Source -134, Tests +94, Config +8, Other +1. Total -31 across 11 files.

View PR surface stats
Area Files Added Removed Net
Source 4 104 238 -134
Tests 4 94 0 +94
Docs 0 0 0 0
Config 2 9 1 +8
Generated 0 0 0 0
Other 1 1 0 +1
Total 11 208 239 -31

What I checked:

  • Live PR state: Live GitHub data shows this PR is open, non-draft, author association MEMBER, assigned to RomneyDa, labeled maintainer, and at head e62ab453dd2dea832f7c6d735e0395c3eb1dcaef against base 534ace4d8a4988c8fbcd54ada1209a86eb12dcc4. (e62ab453dd2d)
  • Current main duplicated core contract: Current main redeclares gateway client host deps, request options, error wrapper typing, option shape, and connection metadata in the core facade, so main has not already superseded the cleanup. (src/gateway/client.ts:36, 534ace4d8a49)
  • Current main package-local guards: Current main keeps the event, response, and gateway-client error-shape guards inside packages/gateway-client, matching the duplicated protocol/client contract surface the PR targets. (packages/gateway-client/src/client.ts:81, 534ace4d8a49)
  • PR head core facade shape: The PR head re-exports package-owned gateway client types/helpers from the core facade and leaves src/gateway/client.ts responsible for OpenClaw host dependency injection and defaults. (src/gateway/client.ts:29, e62ab453dd2d)
  • PR head protocol guard owner: The new guard leaf validates dispatch-critical event/response envelope fields without compiling the full schema or rejecting additive frame fields, matching the stated owner-boundary goal. (packages/gateway-protocol/src/frame-guards.ts:28, e62ab453dd2d)
  • Package export/build wiring: The protocol package export map and package build command both include the new ./frame-guards entry. (packages/gateway-protocol/package.json:27, e62ab453dd2d)

Likely related people:

  • RomneyDa: RomneyDa authored the Wave 1 umbrella, is assigned to this protected PR, authored the current gateway-client/protocol slice, and authored the two merged sibling cleanup slices. (role: cleanup owner and likely follow-up owner; confidence: high; commits: e62ab453dd2d, a45c0999cec7, d2e6ccf4bb43; files: src/gateway/client.ts, packages/gateway-client/src/client.ts, packages/gateway-protocol/src/frame-guards.ts)
  • vincentkoc: Current-main blame on the sampled gateway client, core facade, protocol alias, and plugin alias lines points to Vincent Koc's recent commit touching these surfaces. (role: recent area contributor; confidence: medium; commits: 22ae651e9ab5, e085fa1a3ffd; files: src/gateway/client.ts, packages/gateway-client/src/client.ts, src/plugins/sdk-alias.ts)
  • steipete: Targeted history shows Peter Steinberger's earlier Gateway: finalize WS control plane commit in the gateway client history, making him useful historical context for this boundary. (role: historical area contributor; confidence: medium; commits: b2e7fb01a926; files: src/gateway/client.ts, packages/gateway-client/src/client.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works
  • 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.
Review history (4 earlier review cycles)
  • reviewed 2026-07-06T17:27:27.694Z sha 9629daf :: needs maintainer review before merge. :: none
  • reviewed 2026-07-06T23:56:39.239Z sha b6563c9 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-07T00:09:02.372Z sha b6563c9 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-08T16:47:51.617Z sha e62ab45 :: needs maintainer review before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jul 6, 2026
@RomneyDa
RomneyDa force-pushed the refactor/gateway-client-contract branch from 9629daf to b6563c9 Compare July 6, 2026 23:41
@RomneyDa

RomneyDa commented Jul 6, 2026

Copy link
Copy Markdown
Member Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@RomneyDa RomneyDa self-assigned this Jul 8, 2026
@RomneyDa
RomneyDa force-pushed the refactor/gateway-client-contract branch from b6563c9 to e62ab45 Compare July 8, 2026 16:41
@RomneyDa
RomneyDa merged commit 8fa83d2 into main Jul 8, 2026
103 of 107 checks passed
@RomneyDa
RomneyDa deleted the refactor/gateway-client-contract branch July 8, 2026 16:56
@clawsweeper clawsweeper Bot mentioned this pull request Jul 8, 2026
Open
giodl73-repo pushed a commit to giodl73-repo/openclaw that referenced this pull request Jul 8, 2026
@RomneyDa @giodl73-repo
refactor(gateway): consolidate client contracts (openclaw#101012)
09fb0fa
This was referenced Jul 9, 2026
Closed
Merged
Merged
Merged
Merged
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 9, 2026
@RomneyDa
refactor(gateway): consolidate client contracts (openclaw#101012)
83b2d81
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@RomneyDa RomneyDa

Labels

app: web-ui App: web-ui gateway Gateway runtime maintainer Maintainer-authored PR P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. size: M status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@RomneyDa