Skip to content

refactor(channels): shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier#112319

Merged
steipete merged 3 commits into
mainfrom
steipete/channel-setup-input-envelope
Jul 22, 2026
Merged

refactor(channels): shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier#112319
steipete merged 3 commits into
mainfrom
steipete/channel-setup-input-envelope

Conversation

@steipete

Copy link
Copy Markdown
Contributor

What Problem This Solves

Part 3 (final) of #112238 — the type Jesse's original observation was about. ChannelSetupInput in core was a ~50-field union of every channel's setup vocabulary (botToken, signalNumber, homeserver, ship, cliPath, ...), exported as public SDK surface. Core declared every channel's fields; plugins read their own off the shared bag.

Why This Change Was Made

Per the SDK migration policy (new contract → deprecation window → removal at major):

  • ChannelSetupInput is now ChannelSetupEnvelope & DeprecatedChannelSetupFields. The envelope keeps the genuinely cross-channel fields (name, token, tokenFile, useEnv, allowFrom, defaultTo); all 43 channel-owned fields move to a clearly-bounded deprecated tier with identical value types and per-field @deprecated JSDoc pointing at the plugin-local pattern and the removal milestone (next Plugin SDK major).
  • Every in-repo plugin now declares its own setup-input type locally (SlackSetupInput, MatrixSetupInput, ...); a compatibility-off compile proof (deprecated tier temporarily disconnected, full core+extensions typecheck lanes green) shows in-repo code no longer touches the tier — it exists purely for third parties.
  • No index signature: the type stays structurally assignable exactly as before, so interface-typed third-party inputs keep compiling. Unknown plugin keys remain a runtime fact that plugin-local types/schemas narrow at the adapter boundary (an earlier draft intersected Record<string, unknown>; review showed that breaks interface assignability and was never needed — withdrawn).
  • A type fixture (expectTypeOf + interface-assignability guard) locks the contract, deliberately covering the API-baseline blind spot: the baseline renders re-exported type aliases by name and produced byte-identical hashes across this change, so the fixture is the field-level guard.
  • docs/plugins/sdk-migration.md records the deprecation and removal window; docs/plugins/sdk-setup.md documents the envelope + plugin-local pattern.

Third-party impact verified by tarball inspection of all four published out-of-tree plugins (WeCom, Yuanbao, Weixin, Zalo ClawBot): zero runtime impact (compiled dist), zero rebuild break (deprecated tier + preserved assignability).

User Impact

None at runtime. Plugin authors get deprecation guidance in their IDE and a documented migration pattern; the actual field removal is reserved for the next SDK major.

Evidence

  • Compatibility-off compile proof: tsgo:core + tsgo:extensions green with the deprecated tier disconnected (Blacksmith run 29837400152), tier restored after; final full type lanes green (core, core:test, extensions, extensions:test — rerun locally after the assignability correction during a Blacksmith outage, noted as the sanctioned fallback).
  • Type fixture + SDK surface/api checks green; API baseline byte-identical (blind spot confirmed, fixture guards).
  • Focused setup suites green (slack, matrix, nextcloud-talk, tlon + fixture, 60 tests in the final round).
  • Structured review (Codex gpt-5.6-sol): one P1 accepted and fixed (index-signature intersection broke interface assignability — removed); final run clean, 0.97.

@steipete
steipete marked this pull request as ready for review July 21, 2026 14:54
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation channel: googlechat Channel integration: googlechat channel: imessage Channel integration: imessage channel: line Channel integration: line channel: matrix Channel integration: matrix channel: mattermost Channel integration: mattermost channel: nextcloud-talk Channel integration: nextcloud-talk channel: nostr Channel integration: nostr channel: signal Channel integration: signal channel: slack Channel integration: slack channel: tlon Channel integration: tlon channel: whatsapp-web Channel integration: whatsapp-web channel: qa-channel Channel integration: qa-channel channel: synology-chat channel: sms Channel integration: sms channel: raft Channel integration: Raft size: L maintainer Maintainer-authored PR labels Jul 21, 2026
@steipete steipete closed this Jul 21, 2026
@steipete steipete reopened this Jul 21, 2026
@steipete steipete closed this Jul 21, 2026
@steipete steipete reopened this Jul 21, 2026
@steipete
steipete force-pushed the steipete/channel-setup-input-envelope branch 3 times, most recently from 9e542f6 to e172129 Compare July 21, 2026 21:16
@steipete steipete closed this Jul 22, 2026
@steipete steipete reopened this Jul 22, 2026
@steipete
steipete force-pushed the steipete/channel-setup-input-envelope branch from e75396c to 202574f Compare July 22, 2026 04:32
@clawsweeper

clawsweeper Bot commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

ClawSweeper status: review started.

I am starting a fresh review of this pull request: refactor(channels): shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier 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.

@steipete
steipete force-pushed the steipete/channel-setup-input-envelope branch from 202574f to fd9223c Compare July 22, 2026 04:57
@clawsweeper

clawsweeper Bot commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

ClawSweeper status: review started.

I am starting a fresh review of this pull request: refactor(channels): shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier 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.

@steipete
steipete force-pushed the steipete/channel-setup-input-envelope branch from fd9223c to 8391097 Compare July 22, 2026 05:07
@clawsweeper

clawsweeper Bot commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

ClawSweeper status: review started.

I am starting a fresh review of this pull request: refactor(channels): shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier 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.

@steipete
steipete merged commit f236e83 into main Jul 22, 2026
120 checks passed
@steipete
steipete deleted the steipete/channel-setup-input-envelope branch July 22, 2026 05:17
@steipete

Copy link
Copy Markdown
Contributor Author

Merged via squash.

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 22, 2026
…th a deprecated compatibility tier (openclaw#112319)

* refactor(channels)!: shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier

* fix(channels): keep ChannelSetupInput structurally assignable without an index signature

* docs: regenerate docs map
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

channel: googlechat Channel integration: googlechat channel: imessage Channel integration: imessage channel: line Channel integration: line channel: matrix Channel integration: matrix channel: mattermost Channel integration: mattermost channel: nextcloud-talk Channel integration: nextcloud-talk channel: nostr Channel integration: nostr channel: qa-channel Channel integration: qa-channel channel: raft Channel integration: Raft channel: signal Channel integration: signal channel: slack Channel integration: slack channel: sms Channel integration: sms channel: synology-chat channel: tlon Channel integration: tlon channel: whatsapp-web Channel integration: whatsapp-web docs Improvements or additions to documentation maintainer Maintainer-authored PR size: L

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant