Summary

• Adds a deliveryStatus field to the JSON envelope emitted by openclaw agent --json --deliver, so automation can detect delivery failures without parsing log output
• Builds on fix(delivery): track and log silent delivery failures openclaw/openclaw#53961 which adds the underlying delivery tracking and diagnostic logging

Design

The JSON envelope now includes deliveryStatus when --deliver is used:

{
  "payloads": [...],
  "meta": {...},
  "deliveryStatus": {
    "requested": true,
    "attempted": true,
    "succeeded": true
  }
}

succeeded is three-state:

• true — all payloads delivered
• "partial" — some payloads failed under bestEffort mode
• false — nothing delivered

Key design decisions:

• Separate field: deliveryStatus is a new top-level field, not reusing the existing delivery field (which carries channel metadata like messageId)
• Post-delivery emit: JSON is emitted after delivery so it includes the final status. For non-bestEffort throws, JSON is emitted before re-throw so stdout always has structured output
• No-payload runs: Include deliveryStatus: {requested: true, attempted: false, succeeded: false} so automation can distinguish "no delivery requested" from "delivery requested but nothing to send"
• Plain-text suppression: "No reply from agent." is suppressed in JSON mode across all paths

Known limitations

These are inherent to the upstream deliverOutboundPayloads return type and would require upstream changes to address:

• Hook cancellations: A message_sending hook that cancels all payloads returns [], which is indistinguishable from zero delivery results. Currently reported as succeeded: false rather than a distinct "cancelled" outcome.
• Non-bestEffort partial throw: When delivery throws mid-stream after some payloads were already sent, the status reports succeeded: false, error: true even though part of the message reached the channel.

Dependencies

• Requires fix(delivery): track and log silent delivery failures openclaw/openclaw#53961 (delivery status tracking) to be merged first

Test plan

• JSON output includes deliveryStatus on successful delivery
• JSON output includes deliveryStatus on failed delivery
• JSON output omits deliveryStatus when deliver is false
• Plain-text warning suppressed in JSON mode
• No-payload JSON+deliver runs include deliveryStatus
• Local codex review --base upstream/main — clean (2 P2s documented as known limitations above)

Closes openclaw#57730.

🤖 Generated with Claude Code