PR #63596: fix(gateway): canonicalize outbound message send semantics

• Repository: openclaw/openclaw
• Author: HOYALIM
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63596

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: direct message.send and gateway send did not share one canonical outbound contract. A message_sending hook cancellation surfaced as an implicit empty result in one path and as No delivery result in another.
• Why it matters: blocked sends were not auditable or semantically consistent across CLI and gateway entrypoints, and gateway send still duplicated core delivery interpretation.
• What changed: introduced an explicit delivery-layer blocked status, routed canonical direct-send results through sendResolvedDirectMessage(), and aligned gateway send plus CLI formatting to use the same success-vs-blocked outcome semantics.
• What did NOT change (scope boundary): no protocol schema changes, no new gateway methods, and no broad outbound refactor outside message.send/gateway send semantics.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #63011
• Related #61373
• This PR fixes a bug or regression

Root Cause (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: gateway send interpreted raw delivery output independently instead of consuming the same canonical outbound send result used by direct message.send.
• Missing detection / guardrail: the delivery layer exposed only results[], so blocked sends were inferred heuristically and gateway-specific tests did not enforce a shared blocked contract.
• Contributing context (if known): deliverOutboundPayloads() treats message_sending cancellation as a skipped payload rather than an exception, which made empty-result handling drift between entrypoints.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch 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/infra/outbound/deliver.test.ts
  • src/infra/outbound/message.test.ts
  • src/gateway/server-methods/send.test.ts
  • src/commands/message-format.test.ts
• Scenario the test should lock in: message_sending cancellation yields an explicit blocked producer signal, direct message.send returns a blocked result, gateway send maps that to a structured invalid request response, and CLI output shows blocked guidance instead of a fake success.
• Why this is the smallest reliable guardrail: the behavior spans the delivery producer, the canonical direct-send wrapper, the gateway consumer, and the CLI formatter; these four tests cover each seam directly.
• Existing test that already covers this (if any): src/infra/outbound/deliver.test.ts -t "short-circuits lower-priority message_sending hooks after cancel=true" already covered the hook-cancel baseline but not the explicit producer contract.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Blocked outbound sends now surface consistently: direct CLI message.send prints 🚫 Send blocked ..., and gateway send returns an explicit structured blocked error instead of No delivery result.

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:
CLI message.send -> sendMessage -> deliverOutboundPayloads -> [] => implicit/ambiguous
Gateway send     -> deliverOutboundPayloads -> [] => "No delivery result"

After:
Producer (deliver) -> { results, blockedByHook }
Canonical send     -> { result | blocked }
Gateway/CLI        -> consume the same canonical outcome

Security Impact (required)

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

Repro + Verification

Environment

• OS: macOS (local dev)
• Runtime/container: Node 22 + pnpm
• Model/provider: N/A
• Integration/channel (if any): direct CLI message.send and gateway send
• Relevant config (redacted): hook-enabled outbound delivery with message_sending cancel path

Steps

1. Trigger an outbound message.send path where a message_sending hook cancels delivery.
2. Trigger the gateway send path for the same blocked-delivery scenario.
3. Observe the returned outcome / CLI output.

Expected

• Delivery producer reports an explicit blocked signal.
• Direct message.send returns a blocked result instead of silently producing result: undefined.
• Gateway send returns a structured blocked error instead of No delivery result.
• CLI blocked sends show explicit blocked guidance.

Actual

• Targeted tests and manual CLI verification confirmed all three surfaces now share consistent blocked-send semantics.

Evidence

Attach at least one:

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

Trace/log snippets:

• 🚫 Send blocked via Telegram. blocked by message_sending hook

Human Verification (required)

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

• Verified scenarios:
  • pnpm test -- src/infra/outbound/message.test.ts src/gateway/server-methods/send.test.ts src/commands/message-format.test.ts
  • pnpm test -- src/infra/outbound/deliver.test.ts -t "short-circuits lower-priority message_sending hooks after cancel=true"
  • pnpm test -- src/infra/outbound/deliver.test.ts -t "reports explicit blockedByHook when message_sending cancels delivery"
  • manual CLI formatter check printing 🚫 Send blocked via Telegram. blocked by message_sending hook
• Edge cases checked:
  • blocked-by-hook direct send keeps agentId/sessionKey/requestId
  • gateway blocked send returns a structured invalid request error instead of No delivery result
  • successful sends still keep existing success payload formatting and tests
• What you did not verify:
  • full pnpm check as a clean branch-local gate, because latest origin/main still has unrelated pre-existing failures in extensions/msteams and src/agents/skills*

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

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

• Risk: any other future caller that bypasses sendMessage() and reads raw results[] directly could still drift semantically.
  • Mitigation: this PR makes the producer contract explicit and keeps gateway + direct send on the shared canonical wrapper; follow-up call sites can adopt the same status-aware helper incrementally.
• Risk: CLI/gateway now treat blocked sends as explicit outcomes, which may surface user-facing behavior differences in scripts that previously tolerated ambiguous success output.
  • Mitigation: the new behavior is more truthful and is covered by focused regression tests.

Changed files

• extensions/memory-wiki/index.test.ts (modified, +3/-0)
• src/commands/message-format.test.ts (added, +28/-0)
• src/commands/message-format.ts (modified, +37/-2)
• src/gateway/server-methods/send.test.ts (modified, +72/-26)
• src/gateway/server-methods/send.ts (modified, +49/-7)
• src/infra/outbound/deliver.test.ts (modified, +33/-1)
• src/infra/outbound/deliver.ts (modified, +20/-4)
• src/infra/outbound/message.test.ts (modified, +38/-0)
• src/infra/outbound/message.ts (modified, +114/-24)
• src/infra/outbound/target-resolver.test.ts (modified, +8/-0)
• src/plugins/contracts/boundary-invariants.test.ts (modified, +1/-0)
• test/extension-test-boundary.test.ts (modified, +1/-0)
• test/helpers/plugins/public-artifacts.ts (modified, +1/-0)