feat(diagnostics): add outbound delivery lifecycle events

[vincentkoc]

Summary

• add message.delivery.started, message.delivery.completed, and message.delivery.error diagnostic events at the shared outbound delivery seam
• export delivery attempts as openclaw.message.delivery.started metrics, openclaw.message.delivery.duration_ms histograms, and openclaw.message.delivery spans
• update stability snapshots, logging docs, changelog, SDK API baseline, and focused tests

Privacy / Cardinality

• delivery events include channel, deliveryKind, optional diagnostic sessionKey, duration/result count, and bounded error category
• OTEL export keeps only low-cardinality attrs: channel, delivery kind, outcome, error category, and result count
• intentionally omits body text, recipient, room/conversation id, account id, message id, raw channel result, phone/email, and media paths

Context

• continues the OTEL plan from feat(diagnostics-otel): unify end-to-end tracing #70424 without moving OTEL SDK imports into core

Validation

• pnpm docs:list
• pnpm test src/infra/outbound/deliver.test.ts extensions/diagnostics-otel/src/service.test.ts src/logging/diagnostic.test.ts
• pnpm plugin-sdk:api:check
• pnpm check:changed after expanding the worktree with gwt sparse full
• after final rebase: targeted tests + pnpm plugin-sdk:api:check

[greptile-apps]

Greptile Summary

This PR adds three new diagnostic events (message.delivery.started, message.delivery.completed, message.delivery.error) at the shared outbound delivery seam in deliver.ts, exports them as OTEL counters, histograms, and spans in the diagnostics-otel extension, and updates docs, stability snapshots, and tests accordingly. The implementation is well-structured, follows established patterns in the codebase, and deliberately omits high-cardinality identifiers (message body, recipient, room ID, media paths) from diagnostic payloads.

Confidence Score: 5/5

Safe to merge — changes are additive, well-tested, and consistent with established patterns in the codebase.

No P0 or P1 issues found. The implementation correctly uses guard flags (deliveryStarted/deliveryFinished) to prevent duplicate or missing diagnostic events, follows the same spanWithDuration + span.end(evt.ts) pattern used by all other OTEL event handlers, and the privacy controls (no body text, recipient, room ID, or media path in spans/metrics) are verified by targeted assertions in the tests.

No files require special attention.

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into feat/otel-deliv..." | Re-trigger Greptile}

[aisle-research-bot]

🔒 Aisle Security Analysis

We found 1 potential security issue(s) in this PR:

#	Severity	Title
1	🟡 Medium	Diagnostic message delivery events expose sessionKey/policyKey to plugin SDK listeners

1. 🟡 Diagnostic message delivery events expose sessionKey/policyKey to plugin SDK listeners

Property	Value
Severity	Medium
CWE	CWE-201
Location	src/infra/outbound/deliver.ts:374-405

Description

The new outbound delivery diagnostics emit message.delivery.* events that can include sessionKey derived from mirror.sessionKey, session.key, or session.policyKey.

Because the plugin SDK publicly exports onDiagnosticEvent, any installed plugin can subscribe to these diagnostic events and read the sessionKey value.

• Input/source: params.mirror.sessionKey, params.session.key, or params.session.policyKey
• Propagation: attached verbatim to diagnostic payloads via emitDiagnosticEvent({ ..., sessionKey })
• Sink/exposure: onDiagnosticEvent is exported on the public plugin SDK surface, enabling third-party plugins to receive the full diagnostic event payload.

Vulnerable code (new behavior):

return params.mirror?.sessionKey ?? params.session?.key ?? params.session?.policyKey;
...
emitDiagnosticEvent({
  type: "message.delivery.started",
  channel: params.channel,
  deliveryKind: params.deliveryKind,
  ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
});

While the bundled OTEL exporter and stability snapshots currently avoid exporting sessionKey, this is still a data exposure to any diagnostic listener (including third-party plugins) that consumes DiagnosticEventPayload directly.

Recommendation

Avoid exposing stable per-user/session identifiers to untrusted diagnostic listeners.

Options:

1. Do not include sessionKey in onDiagnosticEvent payloads (keep it only for internal listeners) by splitting the event bus into internal vs public, or by stripping sensitive fields before dispatch to public listeners.

2. Hash/anonymize the session identifier for diagnostics (rotating salt) so it remains useful for correlation but cannot be used as an identifier outside the process.

Example (strip before public listeners):

export function onDiagnosticEvent(listener: (evt: DiagnosticEventPayload) => void): () => void {
  return onInternalDiagnosticEvent((event) => {
    if (event.type === "log.record") return;

    ​// Remove sensitive identifiers from public plugin surface
    const { sessionKey, sessionId, ...rest } = event as any;
    listener(rest);
  });
}

Also consider removing session.policyKey from diagnostic correlation entirely if it may represent an authorization/policy secret.

---

Analyzed PR: #71471 at commit 5f990d9

_{Last updated on: 2026-04-25T08:20:49Z}