Skip to content

refactor(channels)!: close the streaming flat-key and intro-hint deprecation windows#107656

Closed
steipete wants to merge 6 commits into
mainfrom
claude/chanref-train-deletion
Closed

refactor(channels)!: close the streaming flat-key and intro-hint deprecation windows#107656
steipete wants to merge 6 commits into
mainfrom
claude/chanref-train-deletion

Conversation

@steipete

Copy link
Copy Markdown
Contributor

What Problem This Solves

Closes the two deprecation windows opened by the channel-config refactor program, deleting the compat surface that exists only to warn external plugin authors: the streaming flat-key/scalar fallback (streaming-flat-key-deprecation.ts and friends) and the never-consumed resolveGroupIntroHint adapter surface.

DO NOT MERGE until a release train has tagged a build containing the deprecation warnings (they landed unreleased on main 2026-07-12/14; latest tag at draft time is v2026.7.1-beta.5, which predates them). Merging earlier would ship warning and removal in the same release, giving external plugins zero notice.

Why This Change Was Made

The removal-plan comments in streaming.ts and types.adapters.ts name exactly this scope. Net −442 LOC: the four public streaming resolvers survive, rewritten nested-only and moved home to streaming.ts (single-use coercers inlined; file lands exactly at its ratcheted base of 1,210 lines); the warn-once module, leaf compat-entry type, scalar reads (shared, matrix monitor window, ACP), fallback-only tests, and the intro-hint adapter field + whatsapp export are deleted. Review-caught hardening: matrix's schema-open account entries would have silently resolved legacy scalar streaming to "off" — the account schema now rejects scalars with a doctor pointer (both directions test-pinned). QQBot's private engine resolveIntroHint is renamed, not removed — that feature is live and unrelated to the adapter field. All doctor migrations stay: openclaw doctor --fix remains the owner of legacy-config repair.

User Impact

Configs still carrying retired spellings fail validation with an actionable doctor message instead of being silently reinterpreted; doctor migrates them in place. Nested configs see zero change.

Evidence

  • Blacksmith Testbox: streaming/auto-reply/matrix-monitor/whatsapp/qqbot/ACP/plugin-sdk suites green; check:changed lanes green except two lint core errors in ui test files this branch does not touch (already fixed on main by fix(ui): restore lint for context test imports #107618 — stale base, resolved by the pre-land rebase); Plugin SDK surface budgets exact (zero export delta) with the regenerated API baseline hash committed.
  • Autoreview (codex gpt-5.6-sol, xhigh): one real finding — the matrix schema-open scalar hole — fixed as above.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation channel: matrix Channel integration: matrix channel: mattermost Channel integration: mattermost channel: telegram Channel integration: telegram channel: whatsapp-web Channel integration: whatsapp-web commands Command implementations agents Agent runtime and tooling channel: qqbot size: L maintainer Maintainer-authored PR labels Jul 14, 2026
@steipete

Copy link
Copy Markdown
Contributor Author

Landing gate research (codex sweep of 77 external channel packages — catalogs, npm, ClawHub; full file:line evidence archived in the maintainer notes): 13 packages use the surface this PR deletes. Flat/scalar streaming config ships in 11 (notably @srinathh/openclaw-channel-twilio-whatsapp carries flat chunkMode in its own plugin.json defaults — operator-side doctor cannot fix that; only a plugin update can), and resolveGroupIntroHint is registered by @soimy/dingtalk (4.3k downloads), @tencent-connect/openclaw-qqbot, @cxyhhhhh/openclaw-qqbot, @nevis/talk (type-level break only; core never read the hint). The deprecated channel-streaming subpath (used by @inline-openclaw/inline and @roamhq/openclaw-roam) is NOT deleted here. Tag math: the warnings first shipped in v2026.7.2-beta.1; v2026.7.1 stable predates them. Earliest policy-compliant landing: after the 2026.7.2 STABLE tag (which must also pick up the intro-hint deprecation from #107252), into the 2026.7.3 train — realistically 2026-07-16/17 at current cadence, ideally after notifying the affected package owners.

@steipete

Copy link
Copy Markdown
Contributor Author

Deprecation umbrella issue with the affected-package list, migration snippet, and train timeline: #107860

@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. labels Jul 15, 2026
@clawsweeper

clawsweeper Bot commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed July 15, 2026, 12:23 AM ET / 04:23 UTC.

Summary
Removes flat and scalar channel-streaming compatibility reads, removes the deprecated group intro-hint adapter and WhatsApp export, and rejects legacy Matrix account streaming scalars with a doctor pointer.

PR surface: Source -185, Tests -227, Docs -2, Generated 0. Total -414 across 29 files.

Reproducibility: not applicable. This PR intentionally removes deprecated compatibility behavior rather than fixing a reported current-main bug. The affected upgrade paths are clearly identified from source and the external-package audit.

Review metrics: 3 noteworthy metrics.

  • Deprecated config spellings: 5 compatibility forms removed. Four flat delivery keys plus scalar streaming are still used by external packages and can change upgrade behavior.
  • Public plugin surfaces: 1 adapter field and 1 export removed. These removals create compile-time compatibility breaks for third-party plugin code.
  • Known external consumers: 13 packages affected. The ecosystem sweep establishes concrete blast radius beyond hypothetical compatibility concerns.

Stored data model
Persistent data-model change detected: migration/backfill/repair: docs/concepts/streaming.md, migration/backfill/repair: extensions/matrix/src/config-schema.test.ts, migration/backfill/repair: extensions/matrix/src/config-schema.ts, migration/backfill/repair: src/commands/doctor/shared/deprecation-compat.ts, serialized state: extensions/matrix/src/config-schema.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #107860
Summary: The open deprecation notice issue is the canonical release and ecosystem-migration tracker; this PR is its candidate removal implementation.

Members:

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

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup is added.

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

Rank-up moves:

  • [P1] Add redacted real-setup upgrade proof covering legacy failure, doctor migration, restart, and preserved nested behavior.
  • After v2026.7.2 stable, record explicit approval for the public API removal train and affected-package migration plan.
  • Rebase onto current main and refresh the review against the conflict-resolved head.

Proof guidance:

  • [P1] Needs real behavior proof before merge: Automated Testbox suites are supplemental only; add a redacted terminal or live upgrade transcript showing legacy rejection, openclaw doctor --fix, restart, and nested behavior, then update the PR body or ask a maintainer for @clawsweeper re-review. Redact keys, phone numbers, IPs, endpoints, and other private data.

Risk before merge

  • [P1] Landing before v2026.7.2 stable would break known external consumers without any stable-release warning window; one affected plugin embeds legacy defaults that doctor cannot repair.
  • [P1] The branch removes a public Plugin SDK field and export despite scoped policy reserving breaking removals for major-version work, so the intended 2026.7.3 exception requires explicit owner approval.
  • [P1] Existing legacy configurations can silently fall back to different streaming behavior, while Matrix account scalar configurations can block startup until doctor or plugin updates are applied.
  • [P1] The current head is draft and conflict-marked against newer main, so the exact rebased merge result still needs review.

Maintainer options:

  1. Finish the deprecation window (recommended)
    Ship v2026.7.2 stable, migrate or notify known consumers, rebase the branch, and add live upgrade proof before reconsidering merge.
  2. Preserve the public compatibility layer
    Keep the deprecated reads and adapter types until an explicitly approved major-version removal window.
  3. Own the breaking train
    A release owner may accept the 2026.7.3 break with explicit compatibility approval and clear upgrade communication.

Next step before merge

  • [P1] Hold the draft until v2026.7.2 stable ships, then have the compatibility owner confirm the breaking-release exception, affected-package handling, real upgrade proof, and rebased merge result.

Maintainer decision needed

  • Question: After v2026.7.2 stable ships the warnings, may the 2026.7.3 train intentionally remove these public compatibility surfaces, or must they remain until a major-version boundary?
  • Rationale: The code cleanup matches the canonical-config direction, but repository Plugin SDK policy, 13 known external consumers, and the absence of a stable warning release make the permissible removal train a maintainer-owned compatibility decision.
  • Likely owner: steipete — Their merged deprecation work, ecosystem audit, tracking issue, and current branch provide the strongest evidence of ownership over the removal plan.
  • Options:
    • Wait, migrate, and approve (recommended): After v2026.7.2 stable, notify or update affected packages, obtain explicit approval for the breaking train, rebase, and require live upgrade proof before merge.
    • Keep compatibility until major: Retain the deprecated resolver and adapter surfaces until the next explicitly designated major-version boundary.
    • Accept the 2026.7.3 break: Land after the stable tag while explicitly accepting plugin breakage and documenting required operator and package-owner action.

Security
Cleared: The diff changes compatibility resolution, validation, tests, docs, and generated API hashes without adding dependencies, executable downloads, workflow permissions, secret access, or package-resolution changes.

Review details

Best possible solution:

Keep doctor migrations, notify or update affected plugin packages, then remove the compatibility surfaces in an explicitly approved breaking train with fresh-install and real upgrade proof.

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

Not applicable: this PR intentionally removes deprecated compatibility behavior rather than fixing a reported current-main bug. The affected upgrade paths are clearly identified from source and the external-package audit.

Is this the best way to solve the issue?

Not yet. Nested-only runtime reads with doctor-owned migration are the right end state, but removal should follow a stable warning release, affected-plugin migration or notification, explicit API-break approval, and real upgrade proof.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

  • add P2: This is a planned compatibility cleanup with significant but not currently active user impact; it needs normal-priority release-owner review rather than urgent landing.
  • add merge-risk: 🚨 compatibility: Merging removes runtime config fallbacks and public plugin types used by known external packages.
  • add merge-risk: 🚨 availability: Existing Matrix account scalar configurations can fail validation and prevent normal startup until repaired.
  • add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
  • add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Automated Testbox suites are supplemental only; add a redacted terminal or live upgrade transcript showing legacy rejection, openclaw doctor --fix, restart, and nested behavior, then update the PR body or ask a maintainer for @clawsweeper re-review. Redact keys, phone numbers, IPs, endpoints, and other private data.

Label justifications:

  • P2: This is a planned compatibility cleanup with significant but not currently active user impact; it needs normal-priority release-owner review rather than urgent landing.
  • merge-risk: 🚨 compatibility: Merging removes runtime config fallbacks and public plugin types used by known external packages.
  • merge-risk: 🚨 availability: Existing Matrix account scalar configurations can fail validation and prevent normal startup until repaired.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Automated Testbox suites are supplemental only; add a redacted terminal or live upgrade transcript showing legacy rejection, openclaw doctor --fix, restart, and nested behavior, then update the PR body or ask a maintainer for @clawsweeper re-review. Redact keys, phone numbers, IPs, endpoints, and other private data.
Evidence reviewed

PR surface:

Source -185, Tests -227, Docs -2, Generated 0. Total -414 across 29 files.

View PR surface stats
Area Files Added Removed Net
Source 16 68 253 -185
Tests 11 32 259 -227
Docs 1 2 4 -2
Config 0 0 0 0
Generated 1 2 2 0
Other 0 0 0 0
Total 29 104 518 -414

What I checked:

Likely related people:

  • steipete: Introduced the merged intro-hint deprecation, prepared this removal branch, documented the external-package sweep, and opened the canonical deprecation-tracking issue. (role: feature-history and recent area contributor; confidence: high; commits: 5bcee076a5ed, 934b15b0dc5b, 63d2b927b696; files: src/channels/streaming.ts, src/channels/plugins/types.adapters.ts, extensions/matrix/src/config-schema.ts)
  • vincentkoc: The latest stable release tag is attached to their release commit, making them relevant to confirming when a stable warning window has actually shipped. citeturn6view0. (role: recent release-train contributor; confidence: medium; commits: 2d2ddc43d0dc; files: CHANGELOG.md)
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.

@steipete

Copy link
Copy Markdown
Contributor Author

Superseded by #113533, which carries the maintainer-approved v2026.7.2 compatibility decision, current reviewed scope, exact-head proof, and final landing validation.

Landed on main as d2b6573.

@steipete steipete closed this Jul 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling channel: matrix Channel integration: matrix channel: mattermost Channel integration: mattermost channel: qqbot channel: telegram Channel integration: telegram channel: whatsapp-web Channel integration: whatsapp-web commands Command implementations docs Improvements or additions to documentation maintainer Maintainer-authored PR merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P2 Normal backlog priority with limited blast radius. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. size: L status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant