refactor(plugins): add lane-oriented channel interface by huntharo · Pull Request #59986 · openclaw/openclaw

huntharo · 2026-04-03T01:28:55Z

Summary

Describe the problem and fix in 2–5 bullets:

Problem: plugin-facing channel runtime and interactive APIs were still shaped around channel-specific surfaces, which pushed plugins toward Telegram/Discord/Slack-specific logic.
Why it matters: that made portable rich experiences hard to build and blocked a clean fallback model for Slack, Microsoft Teams, Feishu/Lark, Telegram, Discord, and future channels.
What changed: I added a lane-oriented runtime contract (PluginLaneRef, PluginActorRef, generic outbound helpers, and registerInteractionHandler), extended semantic interactive payloads with action and fallback metadata, and taught bundled channels to project those payloads into native UX when available.
What did NOT change (scope boundary): I did not remove every raw channel runtime namespace yet; they remain host-owned escape hatches, and I kept the implementation plan in a separate commit so it can be dropped cleanly if desired.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #
This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

Root cause: the older plugin runtime exposed channel-shaped interaction and outbound seams, so plugin authors had to think in terms of per-channel transports instead of reply lanes, actors, semantic actions, and fallbacks.
Missing detection / guardrail: there was no normalized plugin-facing lane/actor contract and no shared semantic interactive fallback model.
Prior context (git blame, prior PR, issue, or refactor if known): this work follows the lane-oriented interface plan and the discussion around removing Telegram Bot API / Discord API ownership from plugins.
Why this regressed now: N/A
If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should have caught this. Otherwise write N/A.

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: src/plugins/runtime.channel-outbound-delivery.test.ts, src/plugins/interactive.test.ts, extensions/msteams/src/outbound.test.ts, extensions/feishu/src/outbound.test.ts
Scenario the test should lock in: a plugin can target normalized lanes/actors and semantic interactive payloads, and bundled channels project those payloads into native channel UX correctly.
Why this is the smallest reliable guardrail: the risky part is the contract seam between plugin runtime, interactive dispatch, and channel outbound projection rather than a single leaf helper.
Existing test that already covers this (if any): src/plugins/commands.test.ts and src/interactive/payload.test.ts now cover normalized lane refs and interactive fallback normalization.
If no new test is added, why not: N/A

User-visible / Behavior Changes

List user-visible changes (including defaults/config).
If none, write None.

Plugin authors now have a lane-oriented interaction/outbound contract instead of relying on channel-shaped runtime helpers.
Semantic interactive replies now carry action ids plus text/command fallbacks.
Microsoft Teams and Feishu/Lark channel plugins can project semantic interactive replies into native card UI instead of collapsing to plain text only.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

Before:
[plugin] -> [channel-specific send/callback helpers] -> [per-channel branching]

After:
[plugin semantic reply/action] -> [lane/actor runtime] -> [channel projection]
                                               -> [native rich UI or text/command fallback]

Security Impact (required)

New permissions/capabilities? (Yes/No) No
Secrets/tokens handling changed? (Yes/No) No
New/changed network calls? (Yes/No) No
Command/tool execution surface changed? (Yes/No) No
Data access scope changed? (Yes/No) No
If any Yes, explain risk + mitigation:

Repro + Verification

Environment

OS: macOS
Runtime/container: Node 22 + pnpm
Model/provider: N/A
Integration/channel (if any): plugin runtime, Telegram, Discord, Slack, Microsoft Teams, Feishu/Lark
Relevant config (redacted): local bundled-plugin/dev config only

Steps

Run pnpm lint.
Run pnpm test -- src/interactive/payload.test.ts src/plugins/commands.test.ts src/plugins/interactive.test.ts src/plugins/runtime.channel-outbound-delivery.test.ts extensions/msteams/src/outbound.test.ts extensions/feishu/src/outbound.test.ts.
Run pnpm build.

Expected

The lane-oriented runtime compiles, targeted tests pass, and bundled channel projections build successfully.

Actual

pnpm lint passed.
The targeted tests passed.
pnpm build passed.
pnpm check is still blocked by a pre-existing unresolved merge-conflict marker in CHANGELOG.md:94, which is unrelated to this PR.

Evidence

Attach at least one:

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

Verified scenarios: I verified the normalized lane/actor runtime flow, generic interaction registration, interactive fallback normalization, and Teams/Feishu rich projection through the targeted tests above, and I verified the full repo build completed successfully.
Edge cases checked: Telegram topic lane normalization, Slack interaction response typing, and generic fallback behavior when a channel cannot render rich UI.
What you did not verify: I did not run a full end-to-end manual chat flow across live Slack/Teams/Feishu/Telegram accounts in this branch.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

Backward compatible? (Yes/No) No
Config/env changes? (Yes/No) No
Migration needed? (Yes/No) Yes
If yes, exact upgrade steps:
1. Move plugin reply routing to PluginLaneRef / PluginActorRef.
2. Use api.runtime.channel.outbound.sendToLane(...) and sendToActorDm(...) instead of channel-branded outbound helpers where possible.
3. Prefer api.registerInteractionHandler(...) plus semantic InteractiveReply payloads with fallbacks.
4. Treat raw api.runtime.channel.<id> namespaces as escape hatches for host-owned runtime work, not the default plugin contract.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

Risk: third-party plugins using the older channel-shaped interaction surface will need migration.
- Mitigation: the PR includes migration docs and keeps the old channel-specific registration path available as a compatibility bridge for now.
Risk: rich interactive projection can drift across bundled channels.
- Mitigation: I added targeted outbound tests for Teams and Feishu and a seam test for normalized lane delivery.

clawsweeper · 2026-05-21T19:09:18Z

Codex review: found issues before merge. Reviewed July 3, 2026, 2:07 AM ET / 06:07 UTC.

Summary
This PR adds lane/actor plugin refs, generic interaction and outbound helpers, rich interaction fallback/projection helpers, bundled channel projections, SDK docs, generated API baselines, and tests.

PR surface: Source +1435, Tests +669, Docs +938, Generated +90. Total +3132 across 52 files.

Reproducibility: yes. for the review blockers: source inspection shows the PR head delays callback dedupe until after handler completion and renders Teams submit payloads that current main routes as agent text. I did not run live transport proof for this read-only review.

Review metrics: 2 noteworthy metrics.

Public Plugin API Additions: 2 ref types, 1 registration method, 3 outbound helpers, 2 capability groups added. These become plugin-facing contracts for bundled and third-party plugins after merge.
Declared Compatibility State: 1 non-backward-compatible SDK migration declared. The PR body says older channel-shaped helper usage needs migration, so upgrade handling must be reviewed before merge.

Stored data model
Persistent data-model change detected: vector/embedding metadata: src/channels/plugins/contracts/plugins-core.contract.test.ts, vector/embedding metadata: src/plugins/interactive.test.ts. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🦪 silver shellfish
Patch quality: 🧂 unranked krab
Result: blocked by patch quality or review findings.

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

Rank-up moves:

Refresh the branch against current main and preserve in-flight callback dedupe.
Rebuild rich interaction projection on the current MessagePresentation path.
Wire Teams Action.Submit payloads to the intended handler path or render only submit values current Teams handling supports.

Mantis proof suggestion
A native Telegram Desktop proof would materially verify that semantic controls render and callback payloads remain intact. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis telegram desktop proof: verify that a semantic interactive reply with a select fallback renders usable Telegram inline buttons and callback payloads remain intact.

Risk before merge

[P1] Merging this as-is would expand the public plugin SDK/runtime surface while the PR body declares a non-backward-compatible migration away from older channel-shaped helpers.
[P1] The PR head can duplicate callback side effects because duplicate callback IDs are only peeked before async handler execution and recorded after the handler returns.
[P1] The rich projection path is built on deprecated InteractiveReply instead of the current MessagePresentation shared send contract, creating a second source of truth for actions, limits, and fallbacks.
[P1] Teams Adaptive Card submits produced by the PR are not wired to the new plugin interaction handler path in current Teams invoke handling; clicks would be serialized as message text instead.
[P1] Live multi-channel transport proof is still needed after correctness fixes because the change affects visible Telegram, Discord, Slack, Teams, and Feishu/Lark interaction delivery.

Maintainer options:

Refresh Against Current Contracts (recommended)
Rebase or rebuild the branch so the merge result preserves current-main dedupe, MessagePresentation rendering, and Teams submit routing before final API review.
Approve A Staged SDK Migration
Maintainers can intentionally accept the new lane-oriented public API only with a documented compatibility bridge, migration window, and focused upgrade tests.
Split Until API Direction Settles
If the lane API direction is not ready, pause this draft and land smaller channel projection fixes that already match current owner boundaries.

Next step before merge

[P2] Manual review remains the right path because the blockers are public SDK direction, compatibility policy, current-main correctness fixes, and live multi-channel delivery proof rather than a narrow automated repair.

Security
Cleared: No concrete security or supply-chain concern was found in the inspected SDK/channel source, docs, tests, and generated API baseline changes.

Review findings

[P1] Claim callback dedupe before invoking handlers — src/plugins/interactive.ts:321-325
[P1] Base rich projection on MessagePresentation — src/channels/plugins/outbound/interactive.ts:48-51
[P1] Route Teams submits through the handler path — extensions/msteams/src/outbound.ts:41-49

Review details

Best possible solution:

Refresh or rebuild the branch on current main, preserve in-flight callback dedupe, use MessagePresentation for rich projection, wire Teams submits to an approved handler path, then get maintainer SDK approval and live channel proof.

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

Yes for the review blockers: source inspection shows the PR head delays callback dedupe until after handler completion and renders Teams submit payloads that current main routes as agent text. I did not run live transport proof for this read-only review.

Is this the best way to solve the issue?

No. The lane-oriented direction may be right for the plugin boundary, but this patch is not the best merge shape until it uses current MessagePresentation contracts and preserves dedupe and Teams submit routing.

Full review comments:

[P1] Claim callback dedupe before invoking handlers — src/plugins/interactive.ts:321-325
Current main claims the callback ID while the handler is in flight, but this branch only peeks before the await and records the key afterward. Two concurrent callbacks with the same ID can both enter plugin code before either is marked handled.
Confidence: 0.91
[P1] Base rich projection on MessagePresentation — src/channels/plugins/outbound/interactive.ts:48-51
Current main makes MessagePresentation the canonical rich UI contract and keeps InteractiveReply as deprecated compatibility. Adding exported capability projection over InteractiveReply creates a second source of truth for limits, fallbacks, and actions.
Confidence: 0.87
[P1] Route Teams submits through the handler path — extensions/msteams/src/outbound.ts:41-49
These Teams Action.Submit payloads are rendered with oc/kind/actionId data, but the current Teams invoke path serializes non-poll card submits into agent text rather than dispatching to the new plugin interaction handler.
Confidence: 0.83

Overall correctness: patch is incorrect
Overall confidence: 0.9

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

P2: This is a normal-priority public plugin API and multi-channel delivery refactor with meaningful compatibility risk but no emergency outage signal.
merge-risk: 🚨 compatibility: The PR expands public plugin SDK/runtime surface and declares migration away from older channel-shaped interaction helpers.
merge-risk: 🚨 message-delivery: The PR changes callback dedupe, lane routing, rich/fallback projection, and Teams/Telegram/Discord/Slack/Feishu delivery behavior.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦪 silver shellfish and patch quality is 🧂 unranked krab.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The external-contributor proof gate does not apply to this maintainer-authored draft, though live multi-channel proof remains a merge-readiness risk after correctness fixes.
mantis: telegram-visible-proof: Mantis should capture Telegram visible proof. The PR changes Telegram-visible interactive button/select projection, which can be demonstrated in a short Telegram Desktop recording after correctness fixes.

Evidence reviewed

PR surface:

Source +1435, Tests +669, Docs +938, Generated +90. Total +3132 across 52 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	29	1476	41	+1435
Tests	12	672	3	+669
Docs	9	948	10	+938
Config	0	0	0	0
Generated	2	204	114	+90
Other	0	0	0	0
Total	52	3300	168	+3132

What I checked:

Live PR state requires maintainer handling: Live GitHub state shows the PR is open, draft, authored by a repository member, and labeled maintainer; cleanup policy keeps maintainer-authored or protected-label PRs open for explicit maintainer judgment.
Root review policy applied: Root policy treats plugin APIs and channel delivery surfaces as compatibility-sensitive and requires whole-surface review across plugin SDK, channel delivery, and sibling surfaces. (AGENTS.md:31, c5afa92c1f8a)
Plugin SDK policy applied: The scoped Plugin SDK guide identifies src/plugin-sdk as the public contract between plugins and core, so this PR's SDK exports need compatibility review. (src/plugin-sdk/AGENTS.md:3, c5afa92c1f8a)
Channel policy applied: The scoped channel guide requires extension-facing channel surfaces to flow through typed SDK contracts and notes that shared channel changes affect the full channel set. (src/channels/AGENTS.md:21, c5afa92c1f8a)
Current main does not already implement the central lane API: Searching current main for the new lane API symbols produced no matches, so the central requested feature is not obsolete on main. (c5afa92c1f8a)
PR expands public plugin API surface: The PR head adds PluginLaneRef, PluginActorRef, lane/sender command context fields, and generic PluginInteractionHandlerRegistration, which are public plugin-facing contracts. (src/plugins/types.ts:1488, 0c63ae859368)

Likely related people:

huntharo: Authored all four commits in this lane-oriented branch and also authored prior merged plugin interactive callback state work in the same area. (role: feature owner and prior plugin-boundary contributor; confidence: high; commits: 4114231a8c39, 0c63ae859368, 65594f972c2c; files: src/plugins/types.ts, src/plugins/interactive.ts, src/plugins/runtime/types-channel.ts)
vincentkoc: Recent history on src/plugins/interactive.ts includes the current-main serialized callback dedupe behavior and related interactive registry work. (role: recent adjacent contributor; confidence: high; commits: d1e3ed374398, 2e1ec9653c37, 0caafa587f80; files: src/plugins/interactive.ts, src/interactive/payload.ts, src/channels/plugins/outbound/interactive.ts)
BradGroux: Authored and merged the current Teams Adaptive Card Action.Submit invoke handling that this PR's new Teams card payloads must interoperate with. (role: adjacent Teams submit-path contributor; confidence: medium; commits: 06c6ff6670cd; files: extensions/msteams/src/monitor-handler.ts, extensions/msteams/src/adaptive-card-submit.ts, extensions/msteams/src/monitor-handler.adaptive-card.test.ts)
Peter Steinberger: Sampled history for the plugin interactive path shows multiple broad refactors around plugin runtime singletons, namespace helpers, and dispatch adapters. (role: broad adjacent plugin runtime contributor; confidence: medium; commits: 7e3f345ee934, f095bbd7b0c6, 39634088712e; files: src/plugins/interactive.ts, src/plugins/interactive-dispatch-adapters.ts, src/plugins)

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.

clawsweeper · 2026-05-21T19:09:19Z

ClawSweeper PR egg

🥚 Incubating: this PR egg is tucked into the review nest.

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

huntharo added 3 commits April 2, 2026 17:06

Plugins: add lane-oriented channel runtime

4114231

Docs: document lane-oriented plugin channels

ca26f4f

Docs: add lane-oriented channel interface plan

dba535f

Plugins: share rich reply projection across channels

0c63ae8

Aierklk mentioned this pull request Apr 3, 2026

[Bug] Feishu plugin not discovered in v2026.4.2 — unknown channel id: feishu #60196

Closed

huntharo mentioned this pull request Apr 6, 2026

feat(plugin): add Feishu channel support for Codex App Server pwrdrvr/openclaw-codex-app-server#82

Closed

BradGroux mentioned this pull request Apr 29, 2026

WORKING: All Microsoft Issues and PRs (refresh) #74163

Draft

clawsweeper Bot added the rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. label May 21, 2026

This was referenced Jun 11, 2026

Flaky tests on Windows/WSL: timeouts and ENOENT in pi-tools workspace-paths & safe-bins #7057

Open

feat(gateway): add OpenAI-compatible /v1/audio/speech endpoint #91644

Closed

feat(msteams): Teams voice (CVI) + chat + governance integration #92081

Closed

clawsweeper Bot temporarily deployed to qa-live-shared June 14, 2026 11:12 Inactive

clawsweeper Bot removed the rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. label Jun 15, 2026

clawsweeper Bot temporarily deployed to qa-live-shared June 23, 2026 03:09 Inactive

github-actions Bot mentioned this pull request Jun 23, 2026

🦞 OpenClaw 生态日报 2026-06-23 litang9/big_model_radar#110

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor(plugins): add lane-oriented channel interface#59986

refactor(plugins): add lane-oriented channel interface#59986
huntharo wants to merge 4 commits into
openclaw:mainfrom
huntharo:codex/host-owned-channel-interface

huntharo commented Apr 3, 2026

Uh oh!

clawsweeper Bot commented May 21, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

huntharo commented Apr 3, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Root Cause / Regression History (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

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

Uh oh!

Uh oh!

clawsweeper Bot commented May 21, 2026

Hatch command

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented May 21, 2026 •

edited

Loading