refactor(channels): separate status output from snapshot input by RomneyDa · Pull Request #102272 · openclaw/openclaw

RomneyDa · 2026-07-08T18:34:31Z

What Problem This Solves

Resolves a problem where channel status data used one public snapshot type for two different trust boundaries: plugin/runtime contributions could carry channel-specific or credential-shaped fields, while Gateway and Control UI consumers expected a credential-free status response. This made the public status contract permissive and left the UI maintaining a separate handwritten mirror.

Why This Change Was Made

This change defines the Gateway protocol schema as the canonical closed ChannelAccountStatus output, projects plugin contributions through an explicit redaction boundary, and introduces ChannelAccountSnapshotInput for permissive plugin/runtime input. The shipped ChannelAccountSnapshot name remains as a deprecated alias for one migration window, and all bundled callers plus shipped plugin barrels are migrated or preserved additively.

The final refactor is net-negative against current main: 501 additions and 502 deletions. It removes the duplicated UI/core type surface and redundant test/documentation scaffolding rather than adding a parallel status path.

User Impact

Operators and UI clients receive a consistent, credential-free channel status shape. Plugin developers can migrate input-producing code to ChannelAccountSnapshotInput and output-consuming code to ChannelAccountStatus without an immediate breaking change, because the deprecated alias remains exported until a future major cleanup.

Evidence

Exact head: dd5acf11fab38342756cadd49f2f8296ac68e6b6
Diff versus current main: 501 additions, 502 deletions, net -1
Blacksmith Testbox: provider blacksmith-testbox, lease tbx_01kx4wgfy78t8yc2kedmczgzdt (violet-hermit)
Focused status/SDK gate: 4 Vitest shards, 39 tests passed
- packages/gateway-protocol/src/channels.schema.test.ts
- src/channels/account-snapshot-fields.test.ts
- src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts
- src/plugins/contracts/plugin-sdk-subpaths.test.ts
- test/scripts/plugin-sdk-surface-report.test.ts
pnpm check:test-types — passed
pnpm plugin-sdk:check-exports — passed
pnpm plugin-sdk:api:check — passed
pnpm plugin-sdk:surface:check — passed
pnpm docs:list — passed
Path-scoped oxfmt --check — passed on Testbox
git diff --check — passed
Fresh mandatory autoreview — clean, no accepted/actionable findings (patch is correct, confidence 0.78)

AI-Assisted Development

This PR was developed with Codex assistance. The agent transcript was not included at the user's request. All changes were reviewed through the repository's mandatory autoreview workflow and validated on Blacksmith Testbox as listed above.

clawsweeper · 2026-07-08T18:35:32Z

Codex review: needs maintainer review before merge. Reviewed July 10, 2026, 5:50 AM ET / 09:50 UTC.

Summary
The PR separates permissive channel runtime status input from the credential-free public channel status output contract and migrates core, plugin, protocol, UI, tests, and docs to the split types.

Reproducibility: yes. at source level: current main uses one permissive ChannelAccountSnapshot type for runtime contributions and public status consumers while the UI maintains a separate mirror. This is a contract-duplication reproduction, not a failing runtime scenario.

Review metrics: 1 noteworthy metric.

Public channel status types: 2 added, 1 deprecated alias retained. The shipped Plugin SDK vocabulary changes and therefore needs an explicit compatibility decision before merge.

Stored data model
Persistent data-model change detected: migration/backfill/repair: docs/docs_map.md, serialized state: test/scripts/plugin-sdk-surface-report.test.ts, unknown-truncated-pull-files, vector/embedding metadata: src/channels/account-snapshot-fields.test.ts. Migration or upgrade compatibility proof is recorded; maintainers should verify it before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #102258
Summary: This PR is the channel-status implementation candidate for one independently reviewable workstream in the canonical contract-consolidation issue.

Members:

canonical: refactor: canonicalize correctness-critical UI and channel contracts #102258 - The issue explicitly specifies the channel status output/input split and redaction boundary implemented here.
adjacent_distinct: refactor(workboard): share Control UI contract #102271 - The sibling PR addresses the separate Workboard contract workstream from the same umbrella issue.

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

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

Resolve the dirty merge state against current main and rerun the focused SDK/status gates.
Record maintainer acceptance of the alias migration window, removal plan, and output-field replacements.

Risk before merge

[P1] The PR is currently conflicting with current main, so its eventual three-way merge result and exact-head validation are not yet known.
[P1] The branch changes the recommended meaning and use of a shipped Plugin SDK type while retaining a deprecated alias; maintainers must explicitly own the migration window and eventual removal plan.
[P1] Narrowing the public output intentionally drops channel-specific top-level fields such as webhook details, so maintainers should confirm every supported operator-facing replacement remains available through channel summaries, configuration, or diagnostics.

Maintainer options:

Rebase and preserve the migration window (recommended)
Resolve current-main conflicts, retain the deprecated alias, document intentionally removed output fields, and rerun SDK and channel-status proof on the rebased head.
Defer the public contract change
Pause the PR until maintainers schedule the type split for a breaking SDK release.

Next step before merge

[P2] A maintainer must accept the shipped SDK compatibility direction and review a conflict-resolved exact head before merge.

Maintainer decision needed

Question: Should OpenClaw adopt the split ChannelAccountStatus/ChannelAccountSnapshotInput public SDK contract with ChannelAccountSnapshot retained as a deprecated alias for one migration window?
Rationale: The implementation is coherent, but it changes shipped Plugin SDK vocabulary and intentionally narrows public status output, so compatibility and deprecation policy require explicit maintainer intent.
Likely owner: steipete — This person has the broadest merged history across the status, protocol, UI, and plugin compatibility surfaces affected by the choice.
Options:
- Approve additive migration (recommended): Keep the deprecated alias, document output-field replacements and the removal plan, then merge after a clean rebase and exact-head validation.
- Defer to breaking release: Hold the public type split until a major SDK release can change the contract without a compatibility alias.
- Keep current contract: Retain the permissive snapshot type and address only specific redaction gaps without changing public SDK names.

Security
Cleared: The diff strengthens top-level credential redaction through an allowlist and closed protocol schema without adding dependencies, permissions, secret access, or executable supply-chain changes.

Review details

Best possible solution:

Rebase the focused contract split onto current main, retain a documented additive SDK migration window, and land only after exact-head protocol, Plugin SDK, status, and UI validation confirms that the narrowed output preserves intended operator diagnostics.

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

Yes at source level: current main uses one permissive ChannelAccountSnapshot type for runtime contributions and public status consumers while the UI maintains a separate mirror. This is a contract-duplication reproduction, not a failing runtime scenario.

Is this the best way to solve the issue?

Yes, the protocol-owned output plus permissive input split is the narrowest maintainable architecture; the unresolved parts are the shipped SDK migration policy and conflict-free exact-head proof.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

P2: This is bounded correctness and maintainability work with meaningful SDK impact but no urgent current user outage.
merge-risk: 🚨 compatibility: The PR narrows channel status output and changes recommended use of a shipped Plugin SDK type across external and bundled plugins.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The repository-member author is exempt from the external-contributor proof gate; the supplied Testbox and focused SDK/status evidence is strong supplemental validation.

Evidence reviewed

What I checked:

Current main still uses one permissive type: Current main still defines ChannelAccountSnapshot as the shared runtime-input and status-output shape, including arbitrary channel and credential-shaped fields. (src/channels/plugins/types.core.ts:189, 1f3ea6faaab0)
PR separates the trust boundaries: The branch derives ChannelAccountStatus from the Gateway protocol, introduces permissive ChannelAccountSnapshotInput, and retains the old name as a deprecated input alias. (src/channels/plugins/types.core.ts:190, dd5acf11fab3)
Protocol output is closed: The branch changes the per-account Gateway response to an explicit schema with additionalProperties: false. (packages/gateway-protocol/src/schema/channels.ts:756, dd5acf11fab3)
Credential-shaped output is rejected: Focused protocol coverage verifies that adding an undeclared channelAccessToken to a returned account makes validation fail. (packages/gateway-protocol/src/channels.schema.test.ts:72, dd5acf11fab3)
Output projection is centralized: Status construction projects plugin and runtime contributions through the status-field allowlist before returning the protocol-derived output type. (src/channels/plugins/status.ts:54, dd5acf11fab3)
Compatibility path is documented and tested: The branch documents the output/input migration, updates the public SDK exports, and reports focused Testbox validation for protocol, SDK surface, generated API, types, formatting, and docs checks. Public docs: docs/plugins/sdk-migration.md. (docs/plugins/sdk-migration.md:91, dd5acf11fab3)

Likely related people:

steipete: Repeated merged history spans channel status construction and projection, Gateway protocol schemas, Control UI contracts, and plugin compatibility documentation. (role: feature owner; confidence: high; commits: cc73ef8ba59a, e49703def652, 4dd2768c4b1a; files: src/channels/plugins/status.ts, src/channels/account-snapshot-fields.ts, packages/gateway-protocol/src/schema/channels.ts)
vincentkoc: Recent merged work covers the Gateway channel handler, UI type localization, Plugin SDK boundaries, and channel status projection. (role: recent area contributor; confidence: high; commits: f565138ddc91, 835e6a75325a, e2524e043865; files: src/gateway/server-methods/channels.ts, ui/src/api/types.ts, src/plugin-sdk/channel-contract.ts)
openperf: Recent merged channel-status work changed terminal WhatsApp restart behavior in the central snapshot type and projection paths. (role: recent behavior contributor; confidence: medium; commits: e29448df08e2; files: src/channels/plugins/types.core.ts, src/channels/account-snapshot-fields.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 (3 earlier review cycles)

reviewed 2026-07-08T18:42:44.349Z sha a3005f6 :: needs maintainer review before merge. :: none
reviewed 2026-07-08T19:08:05.627Z sha 4a2af8f :: needs maintainer review before merge. :: none
reviewed 2026-07-08T19:26:52.654Z sha 4a2af8f :: needs maintainer review before merge. :: none

RomneyDa · 2026-07-10T02:19:19Z

@clawsweeper re-review

clawsweeper · 2026-07-10T02:19:22Z

🦞🧹
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 · 2026-07-23T01:29:08Z

reworking this to make it non-breaking

clawsweeper · 2026-07-23T02:26:51Z

ClawSweeper status: review started.

I am starting a fresh review of this pull request: refactor(channels): separate status output from snapshot input This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

clawsweeper Bot mentioned this pull request Jul 8, 2026

refactor: canonicalize correctness-critical UI and channel contracts #102258

Open

RomneyDa marked this pull request as draft July 8, 2026 19:21

clawsweeper Bot mentioned this pull request Jul 8, 2026

refactor(workboard): share Control UI contract #102271

Merged

RomneyDa force-pushed the refactor/channel-status-contract branch from 4a2af8f to dd5acf1 Compare July 10, 2026 02:18

openclaw-barnacle Bot added size: L and removed size: XL labels Jul 10, 2026

joshavant mentioned this pull request Jul 14, 2026

fix(channels): prevent base URL credentials in status output #107754

Merged

RomneyDa assigned steipete Jul 23, 2026

RomneyDa force-pushed the refactor/channel-status-contract branch from dd5acf1 to 4e69848 Compare July 23, 2026 01:06

openclaw-barnacle Bot removed the channel: whatsapp-web Channel integration: whatsapp-web label Jul 23, 2026

RomneyDa force-pushed the refactor/channel-status-contract branch from 4e69848 to 83eb7cc Compare July 23, 2026 01:08

RomneyDa added 5 commits July 23, 2026 10:09

refactor(channels): separate status output from snapshot input

b5ddf3c

test(plugin-sdk): align generated validation fixtures

db6f1f6

docs: keep synced template routes in map

1fa1891

refactor(channels): keep status contract net-negative

ccbd9ff

fix(channels): complete status contract rebase

0ef68b0

RomneyDa force-pushed the refactor/channel-status-contract branch from 83eb7cc to 0ef68b0 Compare July 23, 2026 01:09

docs(plugins): drop status type migration prose

92da9a8

RomneyDa added 2 commits July 23, 2026 10:30

fix(plugin-sdk): retain legacy channel status inputs

04d4d18

fix(channels): preserve input status boundary

c7aea94

openclaw-barnacle Bot added channel: whatsapp-web Channel integration: whatsapp-web channel: reef Channel integration: reef labels Jul 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor(channels): separate status output from snapshot input#102272

refactor(channels): separate status output from snapshot input#102272
RomneyDa wants to merge 8 commits into
mainfrom
refactor/channel-status-contract

RomneyDa commented Jul 8, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 10, 2026

Uh oh!

clawsweeper Bot commented Jul 10, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 23, 2026

Uh oh!

clawsweeper Bot commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

RomneyDa commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

AI-Assisted Development

Uh oh!

clawsweeper Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RomneyDa commented Jul 10, 2026

Uh oh!

clawsweeper Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RomneyDa commented Jul 23, 2026

Uh oh!

clawsweeper Bot commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

RomneyDa commented Jul 8, 2026 •

edited

Loading

clawsweeper Bot commented Jul 8, 2026 •

edited

Loading

clawsweeper Bot commented Jul 10, 2026 •

edited

Loading