Refactoring del ciclo di vita dei messaggi

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Le primitive core dovrebbero essere receive e send, non reply.
• Una risposta è solo una relazione su un messaggio in uscita.
• Un turno è una comodità per l’elaborazione in ingresso, non il proprietario della consegna.
• L’invio deve essere basato sul contesto: begin, render, anteprima o stream, invio finale, commit, fail.
• Anche la ricezione deve essere basata sul contesto: normalizza, deduplica, instrada, registra, dispatch, ack della piattaforma, fail.
• L’SDK pubblico dei Plugin dovrebbe ridursi a una piccola superficie per i messaggi di canale.

​

Problemi

• Gli adapter semplici in ingresso usano runtime.channel.turn.run.
• Gli adapter ricchi usano runtime.channel.turn.runPrepared.
• Gli helper legacy usano dispatchInboundReplyWithBase, recordInboundSessionAndDispatchReply, helper per payload di risposta, suddivisione in chunk delle risposte, riferimenti di risposta e helper runtime in uscita.
• Lo streaming di anteprima vive in dispatcher specifici del canale.
• La durabilità della consegna finale viene aggiunta intorno ai percorsi esistenti dei payload di risposta.

Telegram polling update acked
  -> assistant final text exists
  -> process restarts before sendMessage succeeds
  -> final response is lost

​

Obiettivi

• Un unico ciclo di vita core per tutti i percorsi di ricezione e invio dei messaggi di canale.
• Invii finali durevoli per impostazione predefinita nel nuovo ciclo di vita dei messaggi dopo che un adapter dichiara un comportamento sicuro per il replay.
• Semantiche condivise di anteprima, modifica, stream, finalizzazione, retry, recupero e ricevuta.
• Una piccola superficie SDK dei Plugin che i plugin di terze parti possano imparare e mantenere.
• Compatibilità per i chiamanti channel.turn esistenti durante la migrazione.
• Punti di estensione chiari per nuove capability di canale.
• Nessun ramo specifico della piattaforma nel core.
• Nessun messaggio di canale token-delta. Lo streaming di canale rimane consegna di anteprima, modifica, append o blocco completato.
• Metadati strutturati di origine OpenClaw per output operativi/di sistema, così i fallimenti visibili del Gateway non rientrano nelle stanze condivise abilitate ai bot come prompt nuovi.

​

Non obiettivi

• Non rimuovere runtime.channel.turn.* nella prima fase.
• Non forzare ogni canale nello stesso comportamento di trasporto nativo.
• Non insegnare al core i topic di Telegram, gli stream nativi di Slack, le redazioni Matrix, le card Feishu, la voce QQ o le attività Teams.
• Non pubblicare tutti gli helper interni di migrazione come API SDK stabile.
• Non fare in modo che i retry riproducano operazioni di piattaforma non idempotenti completate.

​

Modello di riferimento

• Chat
• Thread
• Channel
• Message
• metodi adapter come postMessage, editMessage, deleteMessage, stream, startTyping e fetch della cronologia
• un adapter di stato per deduplica, lock, code e persistenza

• Intenti di invio in uscita durevoli prima delle chiamate dirette al trasporto.
• Contesti di invio espliciti con begin, commit e fail.
• Contesti di ricezione che conoscono la policy di ack della piattaforma.
• Ricevute che sopravvivono al riavvio e possono guidare modifiche, eliminazioni, recupero e soppressione dei duplicati.
• Un SDK pubblico più piccolo. I plugin in bundle possono usare helper runtime interni, ma i plugin di terze parti dovrebbero vedere una sola API coerente per i messaggi.
• Comportamento specifico degli agenti: sessioni, trascrizioni, streaming a blocchi, avanzamento degli strumenti, approvazioni, direttive media, risposte silenziose e cronologia delle menzioni nei gruppi.

​

Modello core

core.messages.receive(...)
core.messages.send(...)
core.messages.live(...)
core.messages.state(...)

​

Termini dei messaggi

​

Messaggio

type ChannelMessage = {
  id: string;
  channel: string;
  accountId?: string;
  direction: "inbound" | "outbound";
  target: MessageTarget;
  sender?: MessageActor;
  body?: MessageBody;
  attachments?: MessageAttachment[];
  relation?: MessageRelation;
  origin?: MessageOrigin;
  timestamp?: number;
  raw?: unknown;
};

​

Target

type MessageTarget = {
  kind: "direct" | "group" | "channel" | "thread";
  id: string;
  label?: string;
  spaceId?: string;
  parentId?: string;
  threadId?: string;
  nativeChannelId?: string;
};

​

Relazione

type MessageRelation =
  | {
      kind: "reply";
      inboundMessageId?: string;
      replyToId?: string;
      threadId?: string;
      quote?: MessageQuote;
    }
  | {
      kind: "followup";
      sessionKey?: string;
      previousMessageId?: string;
    }
  | {
      kind: "broadcast";
      reason?: string;
    }
  | {
      kind: "system";
      reason:
        | "approval"
        | "task"
        | "hook"
        | "cron"
        | "subagent"
        | "message_tool"
        | "cli"
        | "control_ui"
        | "automation"
        | "error";
    };

​

Origine

type MessageOrigin =
  | {
      source: "openclaw";
      schemaVersion: 1;
      kind: "gateway_failure";
      code: "agent_failed_before_reply" | "missing_api_key" | "model_login_expired";
      echoPolicy: "drop_bot_room_echo";
    }
  | {
      source: "user" | "external_bot" | "platform" | "unknown";
    };

​

Ricevuta

type MessageReceipt = {
  primaryPlatformMessageId?: string;
  platformMessageIds: string[];
  parts: MessageReceiptPart[];
  threadId?: string;
  replyToId?: string;
  editToken?: string;
  deleteToken?: string;
  url?: string;
  sentAt: number;
  raw?: unknown;
};

type MessageReceiptPart = {
  platformMessageId: string;
  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
  index: number;
  threadId?: string;
  replyToId?: string;
  editToken?: string;
  deleteToken?: string;
  url?: string;
  raw?: unknown;
};

​

Contesto di ricezione

type MessageReceiveContext = {
  id: string;
  channel: string;
  accountId?: string;
  input: ChannelMessage;
  ack: ReceiveAckController;
  route: MessageRouteController;
  session: MessageSessionController;
  log: MessageLifecycleLogger;

  dedupe(): Promise<ReceiveDedupeResult>;
  resolve(): Promise<ResolvedInboundMessage>;
  record(resolved: ResolvedInboundMessage): Promise<RecordResult>;
  dispatch(recorded: RecordResult): Promise<DispatchResult>;
  commit(result: DispatchResult): Promise<void>;
  fail(error: unknown): Promise<void>;
};

platform event
  -> begin receive context
  -> normalize
  -> classify
  -> dedupe and self-echo gate
  -> route and authorize
  -> record inbound session metadata
  -> dispatch agent run
  -> durable outbound sends happen through send context
  -> commit receive
  -> ack platform when policy allows

• Ack di trasporto: comunica al Webhook o al socket della piattaforma che OpenClaw ha accettato l’envelope dell’evento. Alcune piattaforme lo richiedono prima del dispatch.
• Ack dell’offset di polling: avanza un cursore così lo stesso evento non viene recuperato di nuovo. Questo non deve avanzare oltre lavoro che non può essere recuperato.
• Ack del record in ingresso: conferma che OpenClaw ha persistito metadati in ingresso sufficienti per deduplicare e instradare una redelivery.
• Ricevuta visibile all’utente: comportamento facoltativo di lettura/stato/typing; mai un confine di durabilità.

function shouldDropOpenClawEcho(params: {
  origin?: MessageOrigin;
  isBotAuthor: boolean;
  isRoomish: boolean;
}): boolean {
  return (
    params.isBotAuthor &&
    params.isRoomish &&
    params.origin?.source === "openclaw" &&
    params.origin.kind === "gateway_failure" &&
    params.origin.echoPolicy === "drop_bot_room_echo"
  );
}

type ReceiveAckPolicy =
  | { kind: "immediate"; reason: "webhook-timeout" | "platform-contract" }
  | { kind: "after-record" }
  | { kind: "after-durable-send" }
  | { kind: "manual" };

​

Contesto di invio

type MessageSendContext = {
  id: string;
  channel: string;
  accountId?: string;
  message: ChannelMessage;
  intent: DurableSendIntent;
  attempt: number;
  signal: AbortSignal;
  previousReceipt?: MessageReceipt;
  preview?: LiveMessageState;
  log: MessageLifecycleLogger;

  render(): Promise<RenderedMessageBatch>;
  previewUpdate(rendered: RenderedMessageBatch): Promise<LiveMessageState>;
  send(rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  edit(receipt: MessageReceipt, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  delete(receipt: MessageReceipt): Promise<void>;
  commit(receipt: MessageReceipt): Promise<void>;
  fail(error: unknown): Promise<void>;
};

await core.messages.withSendContext(message, async (ctx) => {
  const rendered = await ctx.render();

  if (ctx.preview?.canFinalizeInPlace) {
    return await ctx.edit(ctx.preview.receipt, rendered);
  }

  return await ctx.send(rendered);
});

begin durable intent
  -> render
  -> optional preview/edit/stream work
  -> mark sending
  -> final platform send or final edit
  -> mark committing with raw receipt
  -> commit receipt
  -> ack durable intent
  -> fail durable intent on classified failure

type MessageDurabilityPolicy = "required" | "best_effort" | "disabled";

type RenderedMessageBatch = {
  units: RenderedMessageUnit[];
  atomicity: "all_or_retry_remaining" | "best_effort_parts";
  idempotencyKey: string;
};

type RenderedMessageUnit = {
  index: number;
  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
  payload: unknown;
  required: boolean;
};

​

Contesto live

type MessageLiveAdapter = {
  begin?(ctx: MessageSendContext): Promise<LiveMessageState>;
  update?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    update: LiveMessageUpdate,
  ): Promise<LiveMessageState>;
  finalize?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    final: RenderedMessageBatch,
  ): Promise<MessageReceipt>;
  cancel?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    reason: LiveCancelReason,
  ): Promise<void>;
};

type LiveMessageState = {
  mode: "partial" | "block" | "progress" | "native";
  receipt?: MessageReceipt;
  visibleSince?: number;
  canFinalizeInPlace: boolean;
  lastRenderedHash?: string;
  staleAfterMs?: number;
};

• Invio Telegram più anteprima modificabile, con finale fresco dopo che l’età dell’anteprima diventa obsoleta.
• Invio Discord più anteprima modificabile, annullamento su media/errore/risposta esplicita.
• Stream nativo Slack o anteprima bozza in base alla forma del thread.
• Finalizzazione del post bozza Mattermost.
• Finalizzazione dell’evento bozza Matrix o redazione in caso di mancata corrispondenza.
• Stream di avanzamento nativo Teams.
• Stream QQ Bot o fallback accumulato.

​

Superficie dell’adattatore

import { defineChannelMessageAdapter } from "openclaw/plugin-sdk/channel-message";

type ChannelMessageAdapter = {
  receive?: MessageReceiveAdapter;
  send: MessageSendAdapter;
  live?: MessageLiveAdapter;
  origin?: MessageOriginAdapter;
  render?: MessageRenderAdapter;
  capabilities: MessageCapabilities;
};

type MessageSendAdapter = {
  send(ctx: MessageSendContext, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  edit?(
    ctx: MessageSendContext,
    receipt: MessageReceipt,
    rendered: RenderedMessageBatch,
  ): Promise<MessageReceipt>;
  delete?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
  classifyError?(ctx: MessageSendContext, error: unknown): DeliveryFailureKind;
  reconcileUnknownSend?(ctx: MessageSendContext): Promise<MessageReceipt | null>;
  afterSendSuccess?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
  afterCommit?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
};

type MessageReceiveAdapter<TRaw = unknown> = {
  normalize(raw: TRaw, ctx: MessageNormalizeContext): Promise<ChannelMessage>;
  classify?(message: ChannelMessage): Promise<MessageEventClass>;
  preflight?(message: ChannelMessage, event: MessageEventClass): Promise<MessagePreflightResult>;
  ackPolicy?(message: ChannelMessage, event: MessageEventClass): ReceiveAckPolicy;
};

type MessageOriginAdapter<TRaw = unknown, TNative = unknown> = {
  encode?(origin: MessageOrigin): TNative | undefined;
  decode?(raw: TRaw): MessageOrigin | undefined;
};

type MessageCapabilities = {
  text: { maxLength?: number; chunking?: boolean };
  attachments?: {
    upload: boolean;
    remoteUrl: boolean;
    voice?: boolean;
  };
  threads?: {
    reply: boolean;
    topic?: boolean;
    nativeThread?: boolean;
  };
  live?: {
    edit: boolean;
    delete: boolean;
    nativeStream?: boolean;
    progress?: boolean;
  };
  delivery?: {
    idempotencyKey?: boolean;
    retryAfter?: boolean;
    receiptRequired?: boolean;
  };
};

​

Riduzione dell’SDK pubblico

• reply-runtime
• reply-dispatch-runtime
• reply-reference
• reply-chunking
• reply-payload
• inbound-reply-dispatch
• channel-reply-pipeline
• la maggior parte degli usi pubblici di outbound-runtime
• helper ad hoc per il ciclo di vita dello stream bozza

​

Relazione con il turno del canale

channel.turn.run
  -> messages.receive context
  -> session dispatch
  -> messages.send context for visible output

channel-owned dispatcher
  -> messages.receive record/finalize bridge
  -> messages.live for preview/progress
  -> messages.send for final delivery

​

Guardrail di compatibilità

• channel.turn.run e dispatchAssembledChannelTurn usano il callback di consegna del canale a meno che quel canale non fornisca esplicitamente un oggetto policy/opzioni durevole revisionato.
• channel.turn.runPrepared resta di proprietà del canale finché il dispatcher preparato non chiama esplicitamente il contesto di invio.
• Gli helper pubblici di compatibilità come recordInboundSessionAndDispatchReply, dispatchInboundReplyWithBase e gli helper direct-DM non iniettano mai una consegna generica durevole prima del callback deliver o reply fornito dal chiamante.

• La consegna finale persistente restituisce uno stato discriminato. handled_visible e handled_no_send sono terminali; unsupported e not_applicable possono ripiegare sulla consegna gestita dal canale; failed propaga l’errore di invio.
• La consegna finale persistente generica è vincolata dalle capacità dell’adattatore, come consegna silenziosa, conservazione del target di risposta, conservazione delle citazioni native e hook di invio dei messaggi. La parità mancante dovrebbe scegliere la consegna gestita dal canale, non un invio generico che modifica il comportamento visibile all’utente.
• Gli invii persistenti basati su coda espongono un riferimento all’intento di consegna. I campi di sessione pendingFinalDelivery* esistenti possono trasportare l’id dell’intento durante la transizione; lo stato finale è uno store MessageSendIntent invece di testo di risposta congelato più campi di contesto ad hoc.

• L’adattatore di invio generico esegue lo stesso comportamento di rendering e trasporto del vecchio percorso diretto.
• Gli effetti collaterali locali successivi all’invio sono preservati tramite il contesto di invio.
• L’adattatore restituisce ricevute o risultati di consegna con tutti gli id dei messaggi della piattaforma.
• I percorsi del dispatcher preparato chiamano il nuovo contesto di invio oppure restano documentati come esterni alla garanzia persistente.
• La consegna di fallback gestisce ogni payload proiettato, non solo il primo.
• La consegna di fallback persistente registra l’intero array di payload proiettati come un unico intento riproducibile o piano batch.

• La consegna del monitor iMessage registra i messaggi inviati in una cache echo dopo un invio riuscito. Gli invii finali persistenti devono comunque popolare quella cache, altrimenti OpenClaw può reingerire le proprie risposte finali come messaggi utente in ingresso.
• Tlon aggiunge una firma opzionale del modello e registra i thread partecipati dopo le risposte di gruppo. La consegna persistente generica non deve aggirare questi effetti; spostali negli adattatori di rendering/invio/finalizzazione di Tlon oppure mantieni Tlon sul percorso gestito dal canale.
• Discord e altri dispatcher preparati possiedono già il comportamento di consegna diretta e anteprima. Non sono coperti da una garanzia persistente del turno assemblato finché i loro dispatcher preparati non instradano esplicitamente le finali tramite il contesto di invio.
• La consegna di fallback silenziosa di Telegram deve consegnare l’intero array di payload proiettati. Una scorciatoia a payload singolo può eliminare payload di fallback aggiuntivi dopo la proiezione.
• LINE, BlueBubbles, Zalo, Nostr e altri percorsi assemblati/helper esistenti possono avere gestione dei token di risposta, proxy dei media, cache dei messaggi inviati, pulizia di caricamento/stato o target solo callback. Restano sulla consegna gestita dal canale finché queste semantiche non sono rappresentate dall’adattatore di invio e verificate dai test.
• Gli helper per DM diretti possono avere una callback di risposta che è l’unico target di trasporto corretto. L’outbound generico non deve dedurre da OriginatingTo o To e saltare quella callback.
• L’output di errore del Gateway OpenClaw deve restare visibile agli esseri umani, ma gli echo di stanze taggati e generati da bot devono essere scartati prima dell’autorizzazione allowBots. I canali non devono implementarlo con filtri su prefissi di testo visibile, se non come breve misura di emergenza; il contratto persistente è metadati strutturati sull’origine.

​

Archiviazione interna

type DurableSendIntent = {
  id: string;
  idempotencyKey: string;
  channel: string;
  accountId?: string;
  message: ChannelMessage;
  batch?: RenderedMessageBatch;
  liveState?: LiveMessageState;
  status:
    | "pending"
    | "sending"
    | "committing"
    | "unknown_after_send"
    | "sent"
    | "failed"
    | "cancelled";
  attempt: number;
  nextAttemptAt?: number;
  receipt?: MessageReceipt;
  partialReceipt?: MessageReceipt;
  failure?: DeliveryFailure;
  createdAt: number;
  updatedAt: number;
};

load pending or sending intents
  -> acquire idempotency lock
  -> skip if receipt already committed
  -> reconstruct send context
  -> render if needed
  -> reconcile unknown_after_send if needed
  -> call adapter send/edit/finalize
  -> commit receipt, mark unknown_after_send, or schedule retry

​

Classi di errore

type DeliveryFailureKind =
  | "transient"
  | "rate_limit"
  | "auth"
  | "permission"
  | "not_found"
  | "invalid_payload"
  | "conflict"
  | "cancelled"
  | "unknown";

• Ritentare transient e rate_limit.
• Non ritentare invalid_payload a meno che esista un fallback di rendering.
• Non ritentare auth o permission finché la configurazione non cambia.
• Per not_found, consentire alla finalizzazione live di ripiegare dalla modifica a un nuovo invio quando il canale dichiara che è sicuro.
• Per conflict, usare le regole di ricevuta/idempotenza per decidere se il messaggio esiste già.
• Qualsiasi errore dopo che l’adattatore potrebbe aver completato l’I/O della piattaforma ma prima del commit della ricevuta diventa unknown_after_send, a meno che l’adattatore non possa dimostrare che l’operazione della piattaforma non è avvenuta.

​

Mappatura dei canali

​

Piano di migrazione

​

Fase 1: Dominio messaggi interno

• Aggiungere tipi src/channels/message/* per messaggi, target, relazioni, origini, ricevute, capacità, intent durevoli, contesto di ricezione, contesto di invio, contesto live e classi di errore.
• Aggiungere origin?: MessageOrigin al tipo di payload del bridge di migrazione usato dalla consegna delle risposte corrente, poi spostare quel campo in ChannelMessage e nei tipi di messaggio renderizzati man mano che il refactor sostituisce i payload di risposta.
• Mantenerlo interno finché adattatori e test non confermano la forma.
• Aggiungere unit test puri per transizioni di stato e serializzazione.

​

Fase 2: Core di invio durevole

• Spostare la coda in uscita esistente dalla durabilità dei payload di risposta agli intent di invio messaggi durevoli.
• Consentire a un intent di invio durevole di trasportare un array di payload proiettato o un piano batch, non soltanto un payload di risposta.
• Preservare il comportamento attuale di ripristino della coda tramite conversione di compatibilità.
• Fare in modo che deliverOutboundPayloads chiami messages.send.
• Rendere la durabilità dell’invio finale il default e fallire in modo chiuso quando l’intent durevole non può essere scritto nel nuovo ciclo di vita del messaggio, dopo che l’adattatore dichiara la sicurezza di replay. I percorsi esistenti di compatibilità channel-turn e SDK restano direct-send per default durante questa fase.
• Registrare le ricevute in modo coerente.
• Restituire ricevute e risultati di consegna al chiamante originale del dispatcher invece di trattare l’invio durevole come un effetto collaterale terminale.
• Persistire l’origine del messaggio attraverso gli intent di invio durevoli affinché ripristino, replay e invii a chunk preservino la provenienza operativa di OpenClaw.

​

Fase 3: Bridge di Channel Turn

• Reimplementare channel.turn.run e dispatchAssembledChannelTurn sopra messages.receive e messages.send.
• Mantenere stabili i tipi di fact correnti.
• Mantenere per default il comportamento legacy. Un canale assembled-turn diventa durevole solo quando il suo adattatore vi aderisce esplicitamente con una policy di durabilità replay-safe.
• Mantenere durable: false come via di fuga di compatibilità per percorsi che finalizzano modifiche native e non possono ancora effettuare replay in sicurezza, ma non fare affidamento sui marker false per proteggere i canali non migrati.
• Impostare per default la durabilità assembled-turn solo nel nuovo ciclo di vita dei messaggi, dopo che la mappatura del canale dimostra che il percorso di invio generico preserva la vecchia semantica di consegna del canale.

​

Fase 4: Bridge del Dispatcher preparato

• Sostituire deliverDurableInboundReplyPayload con un bridge di contesto di invio.
• Mantenere il vecchio helper come wrapper.
• Effettuare prima il porting di Telegram, WhatsApp, Slack, Signal, iMessage e Discord perché hanno già lavoro su final durable o percorsi di invio più semplici.
• Considerare ogni dispatcher preparato come non coperto finché non opta esplicitamente per il contesto di invio. La documentazione e le voci del changelog devono dire “assembled channel turns” o nominare i percorsi dei canali migrati invece di dichiarare tutte le risposte finali automatiche.
• Mantenere recordInboundSessionAndDispatchReply, gli helper direct-DM e helper pubblici di compatibilità simili preservandone il comportamento. Potranno esporre in seguito un opt-in esplicito al contesto di invio, ma non devono tentare automaticamente una delivery durable generica prima della callback di delivery posseduta dal chiamante.

​

Fase 5: ciclo di vita live unificato

• Creare messages.live con due adapter di prova:
  • Telegram per invio più modifica più invio finale obsoleto.
  • Matrix per finalizzazione della bozza più fallback di redazione.
• Quindi migrare Discord, Slack, Mattermost, Teams, QQ Bot e Feishu.
• Eliminare il codice duplicato di finalizzazione della preview solo dopo che ogni canale ha test di parità.

​

Fase 6: SDK pubblico

• Aggiungere openclaw/plugin-sdk/channel-message.
• Documentarlo come API preferita per i Plugin di canale.
• Aggiornare export del pacchetto, inventario degli entrypoint, baseline API generate e documentazione dell’SDK dei Plugin.
• Includere MessageOrigin, hook di codifica/decodifica dell’origine e il predicato condiviso shouldDropOpenClawEcho nella superficie SDK channel-message.
• Mantenere wrapper di compatibilità per i vecchi sottopercorsi.
• Contrassegnare gli helper SDK con nome reply come deprecati nella documentazione dopo la migrazione dei plugin inclusi.

​

Fase 7: tutti i mittenti

• notifiche Cron e Heartbeat
• completamenti dei task
• risultati degli hook
• prompt di approvazione e risultati di approvazione
• invii dello strumento messaggi
• annunci di completamento dei subagent
• invii espliciti da CLI o Control UI
• percorsi di automazione/broadcast

​

Fase 8: deprecare Turn

• Mantenere channel.turn come wrapper per almeno una finestra di compatibilità.
• Pubblicare note di migrazione.
• Eseguire i test di compatibilità dell’SDK dei Plugin contro i vecchi import.
• Rimuovere o nascondere i vecchi helper interni solo dopo che nessun plugin incluso ne ha più bisogno e i contratti di terze parti hanno un sostituto stabile.

​

Piano di test

• Serializzazione e recovery dell’intent di invio durable.
• Riutilizzo della chiave di idempotenza e soppressione dei duplicati.
• Commit della ricevuta e salto del replay.
• Recovery unknown_after_send che riconcilia prima del replay quando un adapter supporta la riconciliazione.
• Criterio di classificazione degli errori.
• Sequenziamento del criterio di ack in ricezione.
• Mappatura delle relazioni per invii reply, followup, system e broadcast.
• Factory di origine per errore del Gateway e predicato shouldDropOpenClawEcho.
• Conservazione dell’origine attraverso normalizzazione del payload, chunking, serializzazione della coda durable e recovery.

• L’adapter semplice channel.turn.run registra e invia ancora.
• La delivery legacy assembled-turn non diventa durable a meno che il canale non opti esplicitamente per farlo.
• Il bridge channel.turn.runPrepared registra e finalizza ancora.
• Gli helper pubblici di compatibilità chiamano per impostazione predefinita le callback di delivery possedute dal chiamante e non eseguono un invio generico prima di tali callback.
• La delivery fallback durable riproduce l’intero array di payload proiettati dopo il riavvio e non può lasciare i payload successivi non registrati dopo un crash iniziale.
• La delivery durable assembled-turn restituisce gli id dei messaggi della piattaforma al dispatcher bufferizzato.
• Gli hook di delivery personalizzati restituiscono ancora gli id dei messaggi della piattaforma quando la delivery durable è disabilitata o non disponibile.
• La risposta finale sopravvive a un riavvio tra il completamento dell’assistente e l’invio alla piattaforma.
• La bozza di preview viene finalizzata in place quando consentito.
• La bozza di preview viene annullata o redatta quando una mancata corrispondenza di media/errore/ target della reply richiede una delivery normale.
• Lo streaming a blocchi e lo streaming preview non consegnano entrambi lo stesso testo.
• I media trasmessi in streaming in anticipo non vengono duplicati nella delivery finale.

• Reply in topic Telegram con ack di polling ritardato fino al watermark completed sicuro del contesto di ricezione.
• Recovery del polling Telegram per aggiornamenti accettati ma non consegnati coperta dal modello persistito dell’offset safe-completed.
• La preview obsoleta di Telegram invia un finale nuovo e pulisce la preview.
• Il fallback silenzioso di Telegram invia ogni payload fallback proiettato.
• La durabilità del fallback silenzioso di Telegram registra atomicamente l’intero array fallback proiettato, non un singolo intent durable a payload singolo per ogni iterazione del ciclo.
• Annullamento preview Discord su media/errore/reply esplicita.
• I finali del dispatcher preparato di Discord passano attraverso il contesto di invio prima che documentazione o changelog dichiarino la durabilità delle final-reply di Discord.
• Gli invii final durable di iMessage popolano la cache echo dei messaggi inviati del monitor.
• I percorsi di delivery legacy LINE, BlueBubbles, Zalo e Nostr non vengono bypassati da un invio durable generico finché non esistono i relativi test di parità adapter.
• La delivery callback Direct-DM/Nostr resta autorevole a meno che non venga migrata esplicitamente a un target messaggio completo e a un adapter di invio replay-safe.
• I messaggi Slack di errore del gateway OpenClaw taggati restano visibili in outbound, gli echo bot-room taggati vengono eliminati prima di allowBots e i messaggi bot non taggati con lo stesso testo visibile seguono ancora la normale autorizzazione bot.
• Fallback dello stream nativo Slack a preview di bozza nei DM di primo livello.
• Finalizzazione preview Matrix e fallback di redazione.
• Gli echo stanza da account bot configurati per errori gateway OpenClaw taggati in Matrix vengono eliminati prima della gestione di allowBots.
• Gli audit della cascata di errori gateway in stanze condivise Discord e Google Chat coprono le modalità allowBots prima di dichiarare protezione generica lì.
• Finalizzazione bozza Mattermost e fallback con nuovo invio.
• Finalizzazione del progresso nativo Teams.
• Soppressione del finale duplicato Feishu.
• Fallback su timeout dell’accumulatore QQ Bot.
• Gli invii final durable Tlon preservano il rendering model-signature e il tracciamento dei thread partecipati.
• Invii finali durable semplici per WhatsApp, Signal, iMessage, Google Chat, LINE, IRC, Nostr, Nextcloud Talk, Synology Chat, Tlon, Twitch, Zalo e Zalo Personal.

• File Vitest mirati durante lo sviluppo.
• pnpm check:changed in Testbox per l’intera superficie modificata.
• pnpm check più ampio in Testbox prima di effettuare il landing del refactor completo o dopo modifiche a SDK/export pubblici.
• Smoke live o qa-channel per almeno un canale con capacità di modifica e un canale semplice solo-invio prima di rimuovere i wrapper di compatibilità.

​

Questioni aperte

• Se Telegram debba eventualmente sostituire la sorgente runner grammY con una sorgente di polling completamente durable che possa controllare la redelivery a livello piattaforma, non solo il watermark di riavvio persistito di OpenClaw.
• Se lo stato durable della preview live debba essere archiviato nello stesso record di coda dell’intent di invio finale o in uno store live-state fratello.
• Per quanto tempo i wrapper di compatibilità restano documentati dopo la pubblicazione di plugin-sdk/channel-message.
• Se i plugin di terze parti debbano implementare direttamente gli adapter di ricezione o fornire solo hook normalize/send/live tramite defineChannelMessageAdapter.
• Quali campi delle ricevute siano sicuri da esporre nell’SDK pubblico rispetto allo stato runtime interno.
• Se effetti collaterali come cache self-echo e marker di thread partecipati debbano essere modellati come hook di contesto di invio, step finalize posseduti dall’adapter o subscriber alle ricevute.
• Quali canali abbiano metadati di origine nativi, quali necessitino di registry outbound persistiti e quali non possano offrire soppressione affidabile degli echo cross-bot.

​

Criteri di accettazione

• Ogni canale messaggi incluso invia l’output finale visibile tramite messages.send.
• Ogni canale messaggi inbound entra tramite messages.receive o un wrapper di compatibilità documentato.
• Ogni canale preview/edit/stream usa messages.live per stato bozza e finalizzazione.
• channel.turn è solo un wrapper.
• Gli helper SDK con nome reply sono export di compatibilità, non il percorso raccomandato.
• La recovery durable può riprodurre gli invii finali pendenti dopo un riavvio senza perdere la risposta finale o duplicare invii già committati; gli invii il cui esito sulla piattaforma è sconosciuto vengono riconciliati prima del replay o documentati come at-least-once per quell’adapter.
• Gli invii final durable falliscono chiusi quando l’intent durable non può essere scritto, a meno che un chiamante non abbia selezionato esplicitamente una modalità non durable documentata.
• Gli helper di compatibilità legacy channel-turn e SDK usano per impostazione predefinita la delivery diretta posseduta dal canale; l’invio durable generico è solo opt-in esplicito.
• Le ricevute preservano tutti gli id dei messaggi della piattaforma per delivery multi-parte e un id primario per praticità di threading/modifica.
• I wrapper durable preservano gli effetti collaterali locali al canale prima di sostituire le callback di delivery diretta.
• I dispatcher preparati non vengono conteggiati come durable finché il loro percorso di delivery finale non usa esplicitamente il contesto di invio.
• La delivery fallback gestisce ogni payload proiettato.
• La delivery fallback durable registra ogni payload proiettato in un unico intent o batch plan riproducibile.
• L’output di errore gateway originato da OpenClaw è visibile agli esseri umani, ma gli echo stanza scritti da bot taggati vengono eliminati prima dell’autorizzazione bot sui canali che dichiarano supporto per il contratto di origine.
• La documentazione spiega invio, ricezione, live, stato, ricevute, relazioni, criterio di errore, migrazione e copertura dei test.

​

Correlati

• Messaggi
• Streaming e chunking
• Bozze di progresso
• Criterio di retry
• Kernel di channel turn