refactor: centralize inbound supplemental context

[steipete]

Summary

Refactors channel SDK ownership toward the two primary channel families:

• openclaw/plugin-sdk/channel-inbound now owns inbound helper splinters: envelope formatting, location context, inbound roots, inbound logging, and direct-DM dispatch/access helpers.
• openclaw/plugin-sdk/channel-outbound now owns outbound helper splinters: reply options, typing/ack logging, lifecycle helpers, and channel streaming/progress helpers.
• Deprecated compatibility facades were added for old shipped subpaths: channel-envelope, channel-location, channel-inbound-roots, channel-pairing-paths, channel-reply-options-runtime, channel-logging, channel-streaming, direct-dm, direct-dm-access, and test-utils.
• Bundled plugin imports were migrated off the newly deprecated channel helper subpaths.
• Core now hosts the moved streaming and direct-DM implementations under src/channels/*; old public files re-export only for compatibility.
• Remaining bundled direct reply dispatchers now route through core inbound dispatch: Discord/Slack use dispatchChannelInboundReply, ClickClack uses runtime.channel.inbound.dispatchReply, and Matrix/MS Teams helpers no longer mock deprecated prepared replies.
• Deprecated docs were shrunk to compatibility notes instead of long recipes, and runtime.channel.inbound.runPreparedReply is now marked deprecated.
• Kept direct-dm-guard-policy as a narrow live seam after review showed Nostr startup should not import broad channel-inbound just to construct pre-crypto guard policy.
• Audited provider one-offs and did not collapse provider-selection-runtime or provider-auth-result; no cleaner replacement without worse ownership or build topology.
• Rebased on current origin/main (42ba297b0a) and migrated the remaining bundled extension test/support imports off deprecated SDK subpaths (command-auth, config-schema, config-types, reply-dedupe, telegram-command-config).
• Added an extension-wide deprecated SDK subpath guard so extension prod/test/support code cannot keep calling old compatibility seams.
• Fixed the shared Node setup fallback on Windows so the Windows CI lane can download and use Node 24 without relying on actions/setup-node.
• Added missing transcripts tool-display metadata from the newer base and regenerated the OpenClawKit display resource for the PR merge ref.
• Trimmed remaining internal test references to deprecated channel turn/message seams and removed stale explicit package-boundary aliases for channel-streaming.

Net LOC vs origin/main: +5442/-5489, net -47.

Verification

Behavior addressed: fewer public channel SDK seams, more channel helper ownership in channel-inbound / channel-outbound, no bundled imports from newly deprecated channel helper subpaths.

Real environment tested: local macOS source checkout.

Exact steps or command run after this patch:

• CI=1 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_TEST_PROJECTS_SERIAL=1 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=.artifacts/vitest-cache/channel-cleanup fnm exec --using v24.15.0 node scripts/run-vitest.mjs run extensions/feishu/src/bot.broadcast.test.ts extensions/feishu/src/bot.test.ts extensions/feishu/src/comment-handler.test.ts extensions/mattermost/src/mattermost/monitor.inbound-system-event.test.ts extensions/qa-channel/src/channel.test.ts extensions/zalouser/src/monitor.group-gating.test.ts src/gateway/server-restart-sentinel.test.ts src/plugins/contracts/extension-package-project-boundaries.test.ts
• node --import tsx scripts/tool-display.ts --check
• pnpm tool-display:check
• bash -n .github/actions/setup-pnpm-store-cache/ensure-node.sh
• local helper probes for openclaw_node_download_platform and openclaw_node_version_matches
• CI=1 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_TEST_PROJECTS_SERIAL=1 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=.artifacts/vitest-cache/image-tool-timeout fnm exec --using v24.15.0 node scripts/run-vitest.mjs run src/agents/tools/image-tool.test.ts --testNamePattern "iMessage account attachment roots|iMessage wildcard attachment roots"
• git diff --check
• node scripts/check-deprecated-api-usage.mjs
• pnpm check:deprecated-jsdoc
• pnpm plugin-sdk:api:check
• pnpm check:test-types
• CI=1 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_TEST_PROJECTS_SERIAL=1 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=.artifacts/vitest-cache/channel-refactor-touched fnm exec --using v24.15.0 node scripts/run-vitest.mjs run ... (22 touched extension files, 353 tests)
• node scripts/run-vitest.mjs run extensions/whatsapp/src/auto-reply.web-auto-reply.last-route.test.ts extensions/imessage/src/channel-inbound-roots.contract.test.ts
• node scripts/run-vitest.mjs run src/plugin-sdk/channel-streaming.test.ts extensions/slack/src/monitor/message-handler/dispatch.preview-fallback.test.ts src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts src/plugins/contracts/plugin-sdk-subpaths.test.ts
• node scripts/run-vitest.mjs run src/plugin-sdk/direct-dm.test.ts extensions/nostr/src/nostr-bus.inbound.test.ts extensions/nostr/src/channel.inbound.test.ts src/plugins/contracts/plugin-sdk-subpaths.test.ts
• node scripts/run-vitest.mjs run src/plugin-sdk/provider-auth-result.test.ts src/plugin-sdk/provider-auth-runtime.test.ts
• node scripts/run-vitest.mjs extensions/clickclack/src/inbound.test.ts src/plugin-sdk/inbound-reply-dispatch.test.ts extensions/discord/src/monitor/message-handler.process.test.ts extensions/slack/src/monitor/message-handler/dispatch.preview-fallback.test.ts extensions/matrix/src/matrix/monitor/handler.test.ts extensions/msteams/src/monitor-handler/message-handler.authz.test.ts
• extension production scan for deprecated channel message/turn/prepared reply imports and calls
• node scripts/check-deprecated-api-usage.mjs --rule=extension-plugin-sdk-compat-subpaths
• exact extension import scan for deprecated SDK subpaths returned no matches
• NODE_OPTIONS=--max-old-space-size=12288 pnpm build
• env -u OPENCLAW_TESTBOX pnpm check:changed
• .agents/skills/autoreview/scripts/autoreview --mode local

Evidence after fix: all listed commands passed after the final accepted review fix; final autoreview reported no accepted/actionable findings.

Observed result after fix: deprecated usage guard rejects the newly deprecated public subpaths, bundled extension code no longer calls deprecated SDK/channel compatibility seams, and current branch LOC remains net negative.

What was not tested: live external channel roundtrips; this change is SDK topology/import ownership plus unit/build/changed-gate proof.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed May 27, 2026, 4:13 AM ET / 08:13 UTC.

Summary
The PR centralizes channel inbound/outbound SDK helper ownership, adds channel-outbound, keeps deprecated compatibility facades, migrates bundled channel imports, updates docs/tests/tool metadata, and changes the Windows Node fallback helper.

Reproducibility: yes. for the review finding by source inspection: the mock exposes the production runResolved type but aliases it to the raw inbound runner, whose implementation reads params.adapter. I did not run tests because this review is read-only.

Review metrics: 2 noteworthy metrics.

• Public SDK export surface: 1 added package export. Adding openclaw/plugin-sdk/channel-outbound changes the public plugin API surface and needs compatibility review before merge.
• Automation helper surface: 1 CI action helper changed. The PR changes the shared Node fallback script, so maintainers should confirm the Windows automation behavior is intentional and in scope.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦐 gold shrimp
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:

• Fix the runtime.channel.turn.runResolved mock wrapper and add a focused regression test.
• Add redacted live terminal/log output or a linked artifact from at least one affected real channel/runtime path after the patch.

Proof guidance:
Needs real behavior proof before merge: The PR body lists local tests, checks, build output, and source inspection, but it explicitly says live external channel roundtrips were not tested; add redacted live output, logs, a recording, or a linked artifact, then update the PR body to trigger re-review or ask a maintainer for @clawsweeper re-review.

Mantis proof suggestion
A Telegram Desktop proof would give maintainers real transport evidence for a broad channel refactor that unit tests cannot fully cover. A maintainer can ask Mantis to capture proof by posting a new PR comment that starts with the OpenClaw Mantis account mention, followed by:

telegram desktop proof: verify a Telegram message reply still dispatches once, preserves reply context, and finalizes the visible response after this channel SDK refactor.

Risk before merge

• Merging now can leave the public test runtime mock inconsistent with the deprecated-but-supported plugin runtime API, hiding failures in plugin tests that still use runtime.channel.turn.runResolved.
• The PR reshapes public plugin SDK imports and deprecates many channel helper subpaths, so external plugin compatibility depends on the preserved aliases and API baseline proof being correct.
• The branch touches many channel dispatch/reply paths, including Telegram-visible surfaces, but the PR body says live external channel roundtrips were not tested.
• The Windows Node fallback helper changes CI automation behavior and downloads/extracts Node differently on Windows, so maintainer review should confirm that automation change belongs in this refactor.

Maintainer options:

1. Fix the mock adapter before merge (recommended)
   Update the test runtime mock so deprecated runtime.channel.turn.runResolved accepts the same { input, resolveTurn } shape as production and add a focused regression test.
2. Add real channel proof
   Before maintainer sign-off, add redacted live terminal/log output, a recording, or a linked artifact from an affected real channel path after this patch.
3. Accept the SDK and CI scope deliberately
   Maintainers may intentionally accept the public SDK reshaping and Windows Node helper change after reviewing compatibility aliases, package export changes, and CI evidence.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Fix `src/plugin-sdk/test-helpers/plugin-runtime-mock.ts` so `runtime.channel.turn.runResolved` mirrors production `runResolvedChannelTurn` instead of aliasing to the raw inbound runner, and add a focused regression test for the deprecated runResolved shape.

Next step before merge
The remaining concrete code blocker is a narrow test-helper compatibility repair that automation can attempt; real behavior proof and SDK scope remain maintainer/contributor gates.

Security
Cleared: No concrete security or supply-chain regression was found in the current merge diff; package metadata and the CI helper still need normal maintainer review.

Review findings

• [P2] Preserve runResolved mock behavior — src/plugin-sdk/test-helpers/plugin-runtime-mock.ts:734-735

Review details

Best possible solution:

Fix the mock compatibility regression, add redacted live proof for at least one affected real channel path, and have maintainers explicitly review the public SDK compatibility and CI-helper scope before merge.

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

Yes for the review finding by source inspection: the mock exposes the production runResolved type but aliases it to the raw inbound runner, whose implementation reads params.adapter. I did not run tests because this review is read-only.

Is this the best way to solve the issue?

No, not yet; the SDK refactor preserves the deprecated runtime alias in production, but the test helper should mirror that alias instead of casting the wrong mock shape.

Full review comments:

• [P2] Preserve runResolved mock behavior — src/plugin-sdk/test-helpers/plugin-runtime-mock.ts:734-735
PluginRuntimeChannel.turn.runResolved is still typed as production runResolvedChannelTurn, which accepts { input, resolveTurn }, but the mock now aliases it to runChannelTurnMock; that mock immediately reads params.adapter.ingest, so tests using the deprecated-but-supported runtime.channel.turn.runResolved(...) path will throw or diverge from production. Add a small adapter wrapper here, matching runResolvedChannelTurn, instead of casting the raw inbound mock.
  Confidence: 0.91

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 7e702bb43d0a.

Label changes

Label changes:

• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.

Label justifications:

• P2: This is a normal-priority but broad plugin SDK/channel refactor with compatibility-sensitive public API changes and one concrete repair needed.
• merge-risk: 🚨 compatibility: The PR renames and deprecates public plugin SDK/runtime channel surfaces while relying on compatibility facades for existing plugins.
• merge-risk: 🚨 message-delivery: The PR changes shared inbound reply dispatch and multiple bundled channel delivery paths, so a missed regression could affect visible message delivery.
• merge-risk: 🚨 automation: The PR changes the shared Node setup fallback used by CI, including Windows download/extraction behavior.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists local tests, checks, build output, and source inspection, but it explicitly says live external channel roundtrips were not tested; add redacted live output, logs, a recording, or a linked artifact, then update the PR body to trigger re-review or ask a maintainer for @clawsweeper re-review.
• mantis: telegram-visible-proof: Mantis should capture Telegram visible proof. The PR touches Telegram reply/context and outbound channel paths, and a short Telegram Desktop or live lane proof would materially demonstrate that visible chat behavior still works.

Evidence reviewed

Acceptance criteria:

• node scripts/run-vitest.mjs src/plugin-sdk/test-helpers/plugin-runtime-mock.test.ts

What I checked:

• Repository policy applied: Root AGENTS.md and relevant scoped guides for extensions, plugin SDK, channels, plugins, gateway, docs, and scripts were read; their SDK compatibility, channel proof, and protected-label guidance affects this review. (AGENTS.md:20, 7e702bb43d0a)
• Protected maintainer handling: The provided live GitHub context shows the PR is open and carries the protected maintainer label, so this workflow should not close it automatically.
• Production runResolved contract: The PR head keeps PluginRuntimeChannel.turn.runResolved typed as production runResolvedChannelTurn, whose contract accepts { input, resolveTurn }. (src/plugins/runtime/types-channel.ts:192, 5ac45fc7b498)
• Production adapter behavior: runResolvedChannelTurn adapts { input, resolveTurn } into the raw inbound runner by constructing an adapter object before calling runChannelTurn. (src/channels/turn/kernel.ts:768, 5ac45fc7b498)
• Mock regression: The test runtime mock aliases deprecated turn.runResolved directly to runChannelTurnMock, while that mock reads params.adapter.ingest, so callers using the production { input, resolveTurn } shape diverge or throw. (src/plugin-sdk/test-helpers/plugin-runtime-mock.ts:734, 5ac45fc7b498)
• Telegram proof context: The maintainer note says Telegram behavior PRs that touch transport, callbacks, authorization, or reply context need real Telegram proof over synthetic-only validation. (.agents/maintainer-notes/telegram.md:37, 7e702bb43d0a)

Likely related people:

• steipete: Shortlog and history show heavy recent work across plugin SDK, runtime, and channel seam files, including prior main commits on plugin SDK/channel boundary refactors beyond this PR. (role: recent area contributor; confidence: high; commits: f11589b311c5, 625fd5b3e3e2, f59d0eac687f; files: src/plugin-sdk, src/plugins/runtime, src/channels/turn)
• Dallin Romney: Current-main blame/history for the existing plugin SDK/test-helper baseline and production runResolvedChannelTurn path points to commit 780bc79 before the PR rewrites the mock alias. (role: recent adjacent owner; confidence: medium; commits: 780bc791470c; files: src/plugin-sdk/test-helpers/plugin-runtime-mock.ts, src/channels/turn/kernel.ts, src/plugin-sdk/channel-inbound.ts)
• vincentkoc: Recent main history shows repeated runtime contract and plugin SDK type-surface refactors in the same ownership area. (role: adjacent runtime contract contributor; confidence: medium; commits: 97d1b88e3faa, aa78a0c00e5f, d90c8db49144; files: src/plugins/runtime, src/plugin-sdk)

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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 813f2f174d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve Signal quote metadata when quoted text is empty

Guarding SupplementalContext on entry.replyToBody drops quote context whenever the quoted message has no text (for example, media-only quotes), even if replyToSender is available and visibility allowed. Before this change, sender/quote metadata was still forwarded in that case via the legacy fields; now those turns lose quote context entirely, which regresses prompt context for Signal replies to non-text messages.

Useful? React with 👍 / 👎.

[clawsweeper]

ClawSweeper PR egg

🎁 Pass real behavior proof to wake the egg and unlock a hatchable treat.

Where did the egg go?

• The egg game starts only after the PR passes the real-behavior proof check.
• Before that, no creature or rarity is rolled. The treat waits for real proof.
• This is still just collectible flavor: proof affects review readiness, not creature quality.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 18417ae00f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve quote sender metadata when quote text is empty

Fresh evidence in this commit: supplemental.quote is now only populated when entry.replyToBody is truthy, so replies to media-only/empty-text Signal messages lose ReplyToSender/quote context entirely even when sender visibility is allowed. This is a behavior regression from the previous path, which still forwarded quote metadata without requiring quote text, and it weakens prompt context for common non-text reply targets.

Useful? React with 👍 / 👎.

[steipete]

Verification before landing:

• PR head: d31a93c
• Local: git diff --check HEAD
• Local: pnpm plugin-sdk:api:check
• Local: pnpm check:test-types
• Local: pnpm lint --threads=8
• Local: node scripts/run-vitest.mjs src/channels/inbound-event/context.test.ts
• Local: node scripts/run-vitest.mjs extensions/googlechat/src/monitor.test.ts
• GitHub: CI run 26499622741 passed, including check-lint after the final test await cleanup.
• GitHub: CodeQL, CodeQL Critical Quality, OpenGrep PR Diff, Workflow Sanity, TUI PTY, Dependency Change Awareness, and Real behavior proof all passed for d31a93c.