Refactoring del ciclo di vita dei messaggi

• Le primitive core dovrebbero essere ricevere e inviare, non rispondere.
• Una risposta è solo una relazione su un messaggio in uscita.
• Un turno è una convenienza di elaborazione in ingresso, non il proprietario della consegna.
• L’invio deve essere basato sul contesto: begin, rendering, anteprima o stream, invio finale, commit, fail.
• Anche la ricezione deve essere basata sul contesto: normalizzazione, deduplica, routing, registrazione, dispatch, ack della piattaforma, fail.
• L’SDK pubblico dei Plugin dovrebbe ridursi a una piccola superficie unica per l’uscita dei canali.

​

Problemi

• Gli adapter in ingresso semplici usano runtime.channel.inbound.run.
• Gli adapter ricchi usano runtime.channel.inbound.runPreparedReply.
• Gli helper legacy usano dispatchInboundReplyWithBase, recordInboundSessionAndDispatchReply, helper per payload di risposta, suddivisione delle risposte in chunk, riferimenti di risposta e helper runtime in uscita.
• Lo streaming delle anteprime vive in dispatcher specifici del canale.
• La durevolezza della consegna finale viene aggiunta attorno 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 la riproduzione.
• Semantiche condivise di anteprima, modifica, stream, finalizzazione, retry, recupero e ricevuta.
• Una piccola superficie SDK per Plugin che i Plugin di terze parti possano imparare e mantenere.
• Compatibilità per i chiamanti di compatibilità delle risposte in ingresso esistenti durante la migrazione.
• Punti di estensione chiari per nuove capacità di canale.
• Nessun ramo specifico della piattaforma nel core.
• Nessun messaggio di canale token-delta. Lo streaming dei canali resta consegna di anteprima, modifica, append o blocco completato del messaggio.
• Metadati strutturati di origine OpenClaw per output operativi/di sistema, in modo che i fallimenti visibili del Gateway non rientrino nelle stanze condivise abilitate ai bot come nuovi prompt.

​

Non obiettivi

• Non forzare ogni canale esistente sulla consegna durevole dei messaggi nella prima fase.
• Non forzare ogni canale nello stesso comportamento di trasporto nativo.
• Non insegnare al core topic Telegram, stream nativi Slack, redazioni Matrix, card Feishu, voce QQ o 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 recuperi 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 inclusi 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 di blocchi, avanzamento degli strumenti, approvazioni, direttive multimediali, 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;
};

​

Destinazione

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 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 in modo che lo stesso evento non venga recuperato di nuovo. 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 riconsegna.
• Ricevuta visibile all’utente: comportamento opzionale di lettura/stato/digitazione; mai un confine di durevolezza.

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 nuovo dopo che l’anteprima diventa obsoleta.
• Invio Discord più anteprima modificabile, annullamento su media/errore/risposta esplicita.
• Stream nativo Slack o anteprima bozza a seconda della 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’adapter

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

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 degli stream bozza

​

Relazione con l’inbound del canale

channel.inbound.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.inbound.run e dispatchChannelInboundReply usano il callback di consegna del canale a meno che quel canale non fornisca esplicitamente un oggetto policy/opzioni durevole sottoposto ad audit.
• channel.inbound.runPreparedReply 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 consegna generica durevole prima del callback deliver o reply fornito dal chiamante.

• La consegna finale durevole restituisce uno stato discriminato. handled_visible e handled_no_send sono terminali; unsupported e not_applicable possono ripiegare sulla consegna di proprietà del canale; failed propaga l’errore di invio.
• La consegna finale durevole generica è controllata dalle capacità dell’adapter, come consegna silenziosa, conservazione del target di risposta, conservazione della citazione nativa e hook di invio dei messaggi. La parità mancante dovrebbe scegliere la consegna di proprietà del canale, non un invio generico che modifica il comportamento visibile all’utente.
• Gli invii durevoli 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’adapter 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’adapter 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 durevole.
• La consegna di fallback gestisce ogni payload proiettato, non solo il primo.
• La consegna durevole di fallback 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 eco dopo un invio riuscito. Gli invii finali durevoli 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 durevole generica non deve aggirare questi effetti; spostarli negli adapter di rendering/invio/finalizzazione di Tlon oppure mantenere Tlon sul percorso di proprietà del canale.
• Discord e altri dispatcher preparati possiedono già il comportamento di consegna diretta e anteprima. Non sono coperti da una garanzia durevole del turno assemblato finché i loro dispatcher preparati non instradano esplicitamente i finali attraverso 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, 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 di proprietà del canale finché tali semantiche non sono rappresentate dall’adapter di invio e verificate dai test.
• Gli helper Direct-DM 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 echi della stanza scritti dal bot e contrassegnati devono essere eliminati prima dell’autorizzazione allowBots. I canali non devono implementarlo con filtri di prefisso sul testo visibile, salvo come breve misura di emergenza; il contratto durevole è costituito da metadati di origine strutturati.

​

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’adapter potrebbe aver completato l’I/O della piattaforma ma prima del commit della ricevuta diventa unknown_after_send, a meno che l’adapter possa dimostrare che l’operazione sulla piattaforma non è avvenuta.

​

Mappatura dei canali

​

Piano di migrazione

​

Fase 1: dominio interno dei messaggi

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

​

Fase 2: core di invio durevole

• Sposta la coda in uscita esistente dalla durabilità dei payload di risposta agli intenti durevoli di invio messaggio.
• Consenti a un intento di invio durevole di trasportare un array di payload proiettato o un piano batch, non solo un payload di risposta.
• Conserva il comportamento di recupero della coda corrente tramite conversione di compatibilità.
• Fai chiamare messages.send da deliverOutboundPayloads.
• Rendi la durabilità dell’invio finale il comportamento predefinito e fallisci in modo chiuso quando l’intento durevole non può essere scritto nel nuovo ciclo di vita dei messaggi, dopo che l’adattatore dichiara la sicurezza di replay. Durante questa fase, i percorsi esistenti di runner inbound e compatibilità SDK restano direct-send per impostazione predefinita.
• Registra le ricevute in modo coerente.
• Restituisci ricevute e risultati di consegna al chiamante dispatcher originale invece di trattare l’invio durevole come effetto collaterale terminale.
• Persiste l’origine del messaggio attraverso gli intenti di invio durevoli, così recupero, replay e invii a blocchi conservano la provenienza operativa OpenClaw.

​

Fase 3: bridge inbound del canale

• Reimplementa channel.inbound.run e dispatchChannelInboundReply sopra messages.receive e messages.send.
• Mantieni stabili i tipi di fatto correnti.
• Mantieni il comportamento legacy per impostazione predefinita. Un canale assembled-turn diventa durevole solo quando il suo adattatore aderisce esplicitamente con una policy di durabilità sicura per replay.
• Mantieni durable: false come via di fuga di compatibilità per i percorsi che finalizzano modifiche native e non possono ancora eseguire replay in modo sicuro, ma non affidarti ai marcatori false per proteggere canali non migrati.
• Rendi predefinita la durabilità assembled-turn solo nel nuovo ciclo di vita dei messaggi, dopo che la mappatura del canale prova che il percorso di invio generico conserva la vecchia semantica di consegna del canale.

​

Fase 4: bridge del dispatcher preparato

• Sostituisci deliverDurableInboundReplyPayload con un bridge del contesto di invio.
• Mantieni il vecchio helper come wrapper.
• Esegui prima il porting di Telegram, WhatsApp, Slack, Signal, iMessage e Discord perché hanno già lavoro sui finali durevoli o percorsi di invio più semplici.
• Considera ogni dispatcher preparato come non coperto finché non opta esplicitamente per il contesto di invio. La documentazione e le voci del changelog devono dire “turni di canale assemblati” o nominare i percorsi di canale migrati invece di affermare che tutte le risposte finali automatiche sono coperte.
• Mantieni il comportamento di recordInboundSessionAndDispatchReply, degli helper per DM diretti e di helper pubblici di compatibilità simili. Potranno esporre in seguito un opt-in esplicito al contesto di invio, ma non devono tentare automaticamente una consegna durevole generica prima del callback di consegna di proprietà del chiamante.

​

Fase 5: ciclo di vita live unificato

• Costruisci messages.live con due adattatori di prova:
  • Telegram per invio, modifica e invio finale obsoleto.
  • Matrix per finalizzazione della bozza e fallback di redazione.
• Poi migra Discord, Slack, Mattermost, Teams, QQ Bot e Feishu.
• Elimina il codice duplicato di finalizzazione dell’anteprima solo dopo che ogni canale ha test di parità.

​

Fase 6: SDK pubblico

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

​

Fase 7: tutti i mittenti

• notifiche di Cron e Heartbeat
• completamenti di 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: rimuovere la compatibilità con nomi basati sui turni

• Mantieni i wrapper con nomi inbound/message come finestra di compatibilità.
• Pubblica note di migrazione.
• Esegui i test di compatibilità dell’SDK dei Plugin contro i vecchi import.
• Rimuovi o nascondi 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 recupero degli intenti di invio durevoli.
• Riutilizzo della chiave di idempotenza e soppressione dei duplicati.
• Commit delle ricevute e salto del replay.
• Recupero di unknown_after_send che riconcilia prima del replay quando un adattatore supporta la riconciliazione.
• Criterio di classificazione degli errori.
• Sequenziamento della policy di ack in ricezione.
• Mappatura delle relazioni per invii di risposta, followup, sistema e broadcast.
• Factory dell’origine per errori del Gateway e predicato shouldDropOpenClawEcho.
• Preservazione dell’origine attraverso normalizzazione del payload, suddivisione in chunk, serializzazione della coda durevole e recupero.

• L’adattatore semplice channel.inbound.run continua a registrare e inviare.
• La consegna legacy degli eventi assemblati non diventa durevole a meno che il canale non opti esplicitamente.
• Il bridge channel.inbound.runPreparedReply continua a registrare e finalizzare.
• Gli helper pubblici di compatibilità chiamano per impostazione predefinita i callback di consegna di proprietà del chiamante e non eseguono invii generici prima di tali callback.
• La consegna durevole di fallback riproduce l’intero array di payload proiettato dopo il riavvio e non può lasciare non registrati i payload successivi dopo un crash anticipato.
• La consegna durevole degli eventi assemblati restituisce gli ID dei messaggi della piattaforma al dispatcher bufferizzato.
• Gli hook di consegna personalizzati continuano a restituire gli ID dei messaggi della piattaforma quando la consegna durevole è disabilitata o non disponibile.
• La risposta finale sopravvive al riavvio tra il completamento dell’assistente e l’invio alla piattaforma.
• La bozza di anteprima viene finalizzata in loco quando consentito.
• La bozza di anteprima viene annullata o redatta quando media/errore/destinazione della risposta non corrispondente richiedono la consegna normale.
• Lo streaming a blocchi e lo streaming di anteprima non consegnano entrambi lo stesso testo.
• I media trasmessi in streaming in anticipo non vengono duplicati nella consegna finale.

• Risposta a topic Telegram con ack del polling ritardato fino al watermark completato sicuro del contesto di ricezione.
• Recupero del polling Telegram per aggiornamenti accettati ma non consegnati coperto dal modello persistito di offset safe-completed.
• L’anteprima obsoleta di Telegram invia un finale nuovo e pulisce l’anteprima.
• Il fallback silenzioso di Telegram invia ogni payload di fallback proiettato.
• La persistenza del fallback silenzioso di Telegram registra atomicamente l’intero array di fallback proiettato, non un singolo intento durevole con un solo payload per iterazione del ciclo.
• Annullamento dell’anteprima Discord su media/errore/risposta esplicita.
• I finali dei dispatcher preparati di Discord passano attraverso il contesto di invio prima che documentazione o changelog affermino la durabilità della risposta finale di Discord.
• Gli invii finali durevoli di iMessage popolano la cache degli echo dei messaggi inviati del monitor.
• I percorsi di consegna legacy di LINE, Zalo e Nostr non vengono bypassati dall’invio durevole generico finché non esistono test di parità dei loro adattatori.
• La consegna tramite callback Direct-DM/Nostr rimane autorevole salvo migrazione esplicita a una destinazione messaggio completa e a un adattatore di invio sicuro per il replay.
• I messaggi di errore del Gateway OpenClaw taggati in Slack restano visibili in outbound, gli echo taggati delle bot-room vengono scartati prima di allowBots, e i messaggi bot non taggati con lo stesso testo visibile seguono comunque la normale autorizzazione dei bot.
• Fallback dello stream nativo Slack alla bozza di anteprima nei DM di primo livello.
• Finalizzazione dell’anteprima Matrix e fallback di redazione.
• Gli echo di stanza di errori del Gateway OpenClaw taggati in Matrix provenienti da account bot configurati vengono scartati prima della gestione di allowBots.
• Gli audit della cascata di errori del Gateway in stanze condivise per Discord e Google Chat coprono le modalità allowBots prima di dichiarare protezione generica in quei canali.
• Finalizzazione della bozza Mattermost e fallback con nuovo invio.
• Finalizzazione del progresso nativo Teams.
• Soppressione dei finali duplicati Feishu.
• Fallback per timeout dell’accumulatore QQ Bot.
• Gli invii finali durevoli Tlon preservano il rendering della firma del modello e il tracciamento dei thread partecipati.
• Invii finali durevoli 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 atterrare il refactor completo o dopo modifiche a SDK/export pubblici.
• Smoke live o qa-channel per almeno un canale capace di modifica e un canale semplice solo invio prima di rimuovere i wrapper di compatibilità.

​

Domande aperte

• Se Telegram debba eventualmente sostituire la sorgente del runner grammY con una sorgente di polling completamente durevole che possa controllare la riconsegna a livello piattaforma, non solo il watermark di riavvio persistito di OpenClaw.
• Se lo stato di anteprima live durevole debba essere archiviato nello stesso record di coda dell’intento di invio finale o in uno store live-state fratello.
• Per quanto tempo i wrapper di compatibilità restino documentati dopo la pubblicazione di plugin-sdk/channel-outbound.
• Se i Plugin di terze parti debbano implementare direttamente adattatori 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 interno del runtime.
• Se effetti collaterali come cache degli echo propri e marker dei thread partecipati debbano essere modellati come hook del contesto di invio, passaggi di finalizzazione di proprietà dell’adattatore o sottoscrittori di ricevute.
• Quali canali abbiano metadati di origine nativi, quali richiedano registri outbound persistiti e quali non possano offrire una 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 di anteprima/modifica/stream usa messages.live per stato bozza e finalizzazione.
• channel.inbound è solo un wrapper.
• Gli helper SDK con nome reply sono export di compatibilità, non il percorso consigliato.
• Il recupero durevole può riprodurre invii finali pendenti dopo il 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’adattatore.
• Gli invii finali durevoli falliscono in modo chiuso quando l’intento durevole non può essere scritto, a meno che un chiamante non abbia selezionato esplicitamente una modalità non durevole documentata.
• Gli helper di compatibilità legacy dell’SDK usano per impostazione predefinita la consegna diretta di proprietà del canale; l’invio durevole generico è solo opt-in esplicito.
• Le ricevute preservano tutti gli ID dei messaggi della piattaforma per consegne multi-parte e un ID primario per comodità di threading/modifica.
• I wrapper durevoli preservano gli effetti collaterali locali del canale prima di sostituire i callback di consegna diretta.
• I dispatcher preparati non sono conteggiati come durevoli finché il loro percorso di consegna finale non usa esplicitamente il contesto di invio.
• La consegna di fallback gestisce ogni payload proiettato.
• La consegna durevole di fallback registra ogni payload proiettato in un unico intento riproducibile o piano batch.
• L’output di errore del Gateway originato da OpenClaw è visibile agli umani, ma gli echo di stanza taggati e scritti da bot vengono scartati prima dell’autorizzazione dei bot sui canali che dichiarano supporto per il contratto di origine.
• La documentazione spiega invio, ricezione, live, stato, ricevute, relazioni, policy di errore, migrazione e copertura dei test.

​

Correlati

• Messaggi
• Streaming e chunking
• Bozze di progresso
• Policy di retry
• API inbound dei canali