- Structured OpenClaw-origin metadata for operational/system output so visible

gateway failures do not re-enter shared bot-enabled rooms as fresh prompts.

## Non Goals

## Non goals

- Do not remove `runtime.channel.turn.*` in the first phase.

- Do not force every channel into the same native transport behavior.

- Do not publish all internal migration helpers as stable SDK API.

- Do not make retries replay completed non-idempotent platform operations.

## Reference Model

## Reference model

Vercel Chat has a good public mental model:

`thread.post()` style promises are not enough for OpenClaw. They hide the

transaction boundary that decides whether a send is recoverable.

## Core Model

## Core model

The new domain should live under an internal core namespace such as

`src/channels/message/*`.

`state` owns durable intent storage, receipts, idempotency, recovery, locks, and

dedupe.

## Message Terms

## Message terms

### Message

text, media plus text, voice plus text, and card fallbacks must preserve all

platform ids while still exposing a primary id for threading and later edits.

## Receive Context

## Receive context

Receiving should not be a bare helper call. The core needs a context that knows

dedupe, routing, session recording, and platform ack policy.

watermark. Webhook platforms may need immediate HTTP ack, but they still need

inbound dedupe and durable outbound send intents because webhooks can redeliver.

## Send Context

## Send context

Sending is also context based:

which units already have receipts and either replay only missing units or mark

the batch `unknown_after_send` until the adapter reconciles it.

## Live Context

## Live context

Preview, edit, progress, and stream behavior should be one opt-in lifecycle.

- Teams native progress stream.

- QQ Bot stream or accumulated fallback.

## Adapter Surface

## Adapter surface

The public SDK target should be one subpath:

};

```

## Public SDK Reduction

## Public SDK reduction

The new public surface should absorb or deprecate these conceptual areas:

subpaths while migrating. Public docs should steer plugin authors to

`plugin-sdk/channel-message` once it exists.

## Relationship To Channel Turn

## Relationship to channel turn

`runtime.channel.turn.*` should stay during migration.

published SDK migration path and contract tests proving old plugins still work

or fail with a clear version error.

## Compatibility Guardrails

## Compatibility guardrails

During migration, generic durable delivery is opt-in for any channel whose

existing delivery callback has side effects beyond "send this payload".

Channels must not implement this with visible-text prefix filters except as a

short emergency stopgap; the durable contract is structured origin metadata.

## Internal Storage

## Internal storage

The durable queue should store message send intents, not reply payloads.

The queue should keep enough identity to replay through the same account,

thread, target, formatting policy, and media rules after restart.

## Failure Classes

## Failure classes

Channel adapters classify transport failures into closed categories:

commit becomes `unknown_after_send` unless the adapter can prove the platform

operation did not happen.

## Channel Mapping

## Channel mapping

| Channel | Target migration |

| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| Zalo | Simple receive plus send adapter. |

| Zalo Personal | Simple receive plus send adapter. |

## Migration Plan

## Migration plan

### Phase 1: Internal Message Domain

- Remove or hide old internal helpers only after no bundled plugin needs them

and third-party contracts have a stable replacement.

## Test Plan

## Test plan

Unit tests:

- Live or qa-channel smoke for at least one edit-capable channel and one

simple send-only channel before removing compatibility wrappers.

## Open Questions

## Open questions

- Whether Telegram should eventually replace the grammY runner source with a

fully durable polling source that can control platform-level redelivery, not

- Which channels have native origin metadata, which need persisted outbound

registries, and which cannot offer reliable cross-bot echo suppression.

## Acceptance Criteria

## Acceptance criteria

- Every bundled message channel sends final visible output through

`messages.send`.