Núcleo de turnos do canal

O kernel de turnos de canal é a máquina de estados de entrada compartilhada que transforma um evento de plataforma normalizado em um turno do agente. Os plugins de canal fornecem os fatos da plataforma e o callback de entrega. O núcleo é responsável pela orquestração: ingestão, classificação, pré-verificação, resolução, autorização, montagem, registro, despacho e finalização.

Use isto quando seu plugin estiver no caminho crítico de mensagens recebidas. Para eventos que não são mensagens (comandos slash, modais, interações de botões, eventos de ciclo de vida, reações, estado de voz), mantenha-os locais ao plugin. O kernel só é responsável por eventos que podem se tornar um turno de texto do agente.

Por que um kernel compartilhado

Plugins de canal repetem o mesmo fluxo de entrada: normalizar, rotear, bloquear, criar um contexto, registrar metadados de sessão, despachar o turno do agente, finalizar o estado de entrega. Sem um kernel compartilhado, uma alteração em bloqueio por menção, respostas visíveis apenas para ferramentas, metadados de sessão, histórico pendente ou finalização de despacho precisa ser aplicada por canal.

O kernel mantém quatro conceitos deliberadamente separados:

• ConversationFacts: de onde veio a mensagem
• RouteFacts: qual agente e sessão devem processá-la
• ReplyPlanFacts: para onde as respostas visíveis devem ir
• MessageFacts: qual corpo e contexto suplementar o agente deve ver

DMs do Slack, tópicos do Telegram, threads do Matrix e sessões de tópicos do Feishu distinguem todos estes na prática. Tratá-los como um único identificador causa divergência ao longo do tempo.

Ciclo de vida dos estágios

O kernel executa o mesmo pipeline fixo independentemente do canal:

1. ingest -- o adaptador converte um evento bruto da plataforma em NormalizedTurnInput
2. classify -- o adaptador declara se este evento pode iniciar um turno do agente
3. preflight -- o adaptador faz deduplicação, autoeco, hidratação, debounce, descriptografia, preenchimento parcial de fatos
4. resolve -- o adaptador retorna um turno totalmente montado (rota, plano de resposta, mensagem, entrega)
5. authorize -- políticas de DM, grupo, menção e comando aplicadas aos fatos montados
6. assemble -- FinalizedMsgContext criado a partir dos fatos via buildContext
7. record -- metadados de sessão de entrada e última rota persistidos
8. dispatch -- turno do agente executado por meio do despachante de blocos em buffer
9. finalize -- onFinalize do adaptador é executado mesmo em erro de despacho

Cada estágio emite um evento de log estruturado quando um callback log é fornecido. Consulte Observabilidade.

Tipos de admissão

O kernel não lança erro quando um turno é bloqueado. Ele retorna um ChannelTurnAdmission:

A admissão pode vir de classify (a classe do evento disse que ele não pode iniciar um turno), de preflight (deduplicação, autoeco, menção ausente com registro de histórico) ou do próprio resolveTurn.

Pontos de entrada

O runtime expõe três pontos de entrada preferenciais para que adaptadores possam aderir no nível que corresponde ao canal.

runtime.channel.turn.run(...)             // adapter-driven full pipelineruntime.channel.turn.runAssembled(...)    // already-built context + delivery adapterruntime.channel.turn.runPrepared(...)     // channel owns dispatch; kernel runs record + finalizeruntime.channel.turn.buildContext(...)    // pure facts to FinalizedMsgContext mapping

Dois helpers de runtime mais antigos continuam disponíveis para compatibilidade com o Plugin SDK:

runtime.channel.turn.runResolved(...)      // deprecated compatibility alias; prefer runruntime.channel.turn.dispatchAssembled(...) // deprecated compatibility alias; prefer runAssembled

run

Use quando seu canal puder expressar seu fluxo de entrada como um ChannelTurnAdapter<TRaw>. O adaptador tem callbacks para ingest, classify opcional, preflight opcional, resolveTurn obrigatório e onFinalize opcional.

await runtime.channel.turn.run({  channel: "tlon",  accountId,  raw: platformEvent,  adapter: {    ingest(raw) {      return {        id: raw.messageId,        timestamp: raw.timestamp,        rawText: raw.body,        textForAgent: raw.body,      };    },    classify(input) {      return { kind: "message", canStartAgentTurn: input.rawText.length > 0 };    },    async preflight(input, eventClass) {      if (await isDuplicate(input.id)) {        return { admission: { kind: "drop", reason: "dedupe" } };      }      return {};    },    resolveTurn(input) {      return buildAssembledTurn(input);    },    onFinalize(result) {      clearPendingGroupHistory(result);    },  },});

run é o formato certo quando o canal tem uma pequena lógica de adaptador e se beneficia de ser responsável pelo ciclo de vida por meio de hooks.

runAssembled

Use quando o canal já tiver resolvido o roteamento, criado um FinalizedMsgContext, e só precisar do registro compartilhado, pipeline de resposta, despacho e ordem de finalização. Este é o formato preferido para caminhos de entrada empacotados simples que, caso contrário, repetiriam boilerplate de createChannelMessageReplyPipeline(...) e runPrepared(...).

await runtime.channel.turn.runAssembled({  cfg,  channel: "irc",  accountId,  agentId: route.agentId,  routeSessionKey: route.sessionKey,  storePath,  ctxPayload,  recordInboundSession: runtime.channel.session.recordInboundSession,  dispatchReplyWithBufferedBlockDispatcher:    runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher,  delivery: {    deliver: async (payload) => {      await sendPlatformReply(payload);    },    onError: (err, info) => {      runtime.error?.(`reply ${info.kind} failed: ${String(err)}`);    },  },});

Escolha runAssembled em vez de runPrepared quando o único comportamento de despacho próprio do canal for a entrega final do payload, mais digitação opcional, opções de resposta, entrega durável ou registro de erros.

runPrepared

Use quando o canal tiver um despachante local complexo com pré-visualizações, novas tentativas, edições ou bootstrap de thread que deve continuar sob responsabilidade do canal. O kernel ainda registra a sessão de entrada antes do despacho e expõe um DispatchedChannelTurnResult uniforme.

const { dispatchResult } = await runtime.channel.turn.runPrepared({  channel: "matrix",  accountId,  routeSessionKey,  storePath,  ctxPayload,  recordInboundSession,  record: {    onRecordError,    updateLastRoute,  },  onPreDispatchFailure: async (err) => {    await stopStatusReactions();  },  runDispatch: async () => {    return await runMatrixOwnedDispatcher();  },});

Canais ricos (Matrix, Mattermost, Microsoft Teams, Feishu, QQ Bot) usam runPrepared porque seu despachante orquestra comportamento específico da plataforma que o kernel não deve conhecer.

buildContext

Uma função pura que mapeia pacotes de fatos para FinalizedMsgContext. Use-a quando seu canal implementar manualmente parte do pipeline, mas quiser um formato de contexto consistente.

const ctxPayload = runtime.channel.turn.buildContext({  channel: "googlechat",  accountId,  messageId,  timestamp,  from,  sender,  conversation,  route,  reply,  message,  access,  media,  supplemental,});

buildContext também é útil dentro de callbacks resolveTurn ao montar um turno para run.

Tipos de fatos

Os fatos que o kernel consome do seu adaptador são independentes de plataforma. Traduza objetos da plataforma para estes formatos antes de entregá-los ao kernel.

NormalizedTurnInput

ChannelEventClass

SenderFacts

ConversationFacts

RouteFacts

ReplyPlanFacts

AccessFacts

AccessFacts carrega os booleanos de que a etapa de autorização precisa. A correspondência de identidade fica no canal: o kernel consome apenas o resultado.

MessageFacts

SupplementalContextFacts

O contexto suplementar cobre contexto de citação, encaminhamento e inicialização de thread. O kernel aplica a política contextVisibility configurada. O adaptador de canal fornece apenas fatos e sinalizadores senderAllowed para que a política entre canais permaneça consistente.

InboundMediaFacts

Mídia é estruturada como fatos. Download da plataforma, autenticação, política de SSRF, regras de CDN e descriptografia permanecem locais ao canal. O kernel mapeia fatos para MediaPath, MediaUrl, MediaType, MediaPaths, MediaUrls, MediaTypes e MediaTranscribedIndexes.

Contrato do adaptador

Para run completo, o formato do adaptador é:

type ChannelTurnAdapter&lt;TRaw&gt; = {  ingest(raw: TRaw): Promise&lt;NormalizedTurnInput | null&gt; | NormalizedTurnInput | null;  classify?(input: NormalizedTurnInput): Promise&lt;ChannelEventClass&gt; | ChannelEventClass;  preflight?(    input: NormalizedTurnInput,    eventClass: ChannelEventClass,  ): Promise&lt;PreflightFacts | ChannelTurnAdmission | null | undefined&gt;;  resolveTurn(    input: NormalizedTurnInput,    eventClass: ChannelEventClass,    preflight: PreflightFacts,  ): Promise&lt;ChannelTurnResolved&gt; | ChannelTurnResolved;  onFinalize?(result: ChannelTurnResult): Promise<void> | void;};

resolveTurn retorna um ChannelTurnResolved, que é um AssembledChannelTurn com um tipo de admissão opcional. Retornar { admission: { kind: "observeOnly" } } executa o turno sem produzir saída visível. O adaptador ainda é responsável pelo callback de entrega; ele apenas se torna um no-op para esse turno.

onFinalize é executado em todos os resultados, incluindo erros de despacho. Use-o para limpar o histórico de grupo pendente, remover reações de confirmação, interromper indicadores de status e descarregar o estado local.

Adaptador de entrega

O kernel não chama a plataforma diretamente. O canal entrega ao kernel um ChannelTurnDeliveryAdapter:

type ChannelTurnDeliveryAdapter = {  deliver(payload: ReplyPayload, info: ChannelDeliveryInfo): Promise<ChannelDeliveryResult | void>;  onError?(err: unknown, info: { kind: string }): void;  durable?: false | DurableInboundReplyDeliveryOptions;}; type ChannelDeliveryResult = {  messageIds?: string[];  receipt?: MessageReceipt;  threadId?: string;  replyToId?: string;  visibleReplySent?: boolean;};

deliver é chamado uma vez por fragmento de resposta em buffer. Durante a migração do ciclo de vida de mensagens, a entrega de turnos de canal montados pertence ao canal por padrão: um campo durable omitido significa que o kernel deve chamar deliver diretamente e não deve rotear pela entrega de saída genérica. Defina durable somente depois que o canal tiver sido auditado para comprovar que o caminho de envio genérico preserva o comportamento de entrega antigo, incluindo destinos de resposta/thread, manipulação de mídia, caches de mensagens enviadas/eco próprio, limpeza de status e IDs de mensagem retornados. durable: false continua sendo uma grafia de compatibilidade para "usar o callback pertencente ao canal", mas canais não migrados não devem precisar adicioná-la. Retorne IDs de mensagem da plataforma quando o canal os tiver para que o dispatcher possa preservar âncoras de thread e editar fragmentos posteriores; caminhos de entrega mais novos também devem retornar receipt para que recuperação, finalização de prévia e supressão de duplicatas possam deixar de depender de messageIds. Para turnos somente de observação, retorne { visibleReplySent: false } ou use createNoopChannelTurnDeliveryAdapter().

Canais que usam runPrepared com um dispatcher totalmente pertencente ao canal não têm um ChannelTurnDeliveryAdapter. Esses dispatchers não são duráveis por padrão. Eles devem manter o caminho de entrega direto até optarem explicitamente pelo novo contexto de envio com um destino completo, adaptador seguro para repetição, contrato de recibo e hooks de efeitos colaterais do canal.

Helpers públicos de compatibilidade como recordInboundSessionAndDispatchReply, dispatchInboundReplyWithBase e helpers de DM direta devem preservar comportamento durante a migração. Eles não devem chamar entrega durável genérica antes de callbacks deliver ou reply pertencentes ao chamador.

Opções de registro

A etapa de registro envolve recordInboundSession. A maioria dos canais pode usar os padrões. Substitua via record:

record: {  groupResolution,  createIfMissing: true,  updateLastRoute,  onRecordError: (err) => log.warn("record failed", err),  trackSessionMetaTask: (task) => pendingTasks.push(task),}

O dispatcher aguarda a etapa de registro. Se o registro lançar erro, o kernel executa onPreDispatchFailure (quando fornecido a runPrepared) e relança.

Observabilidade

Cada etapa emite um evento estruturado quando um callback log é fornecido:

await runtime.channel.turn.run({  channel: "twitch",  accountId,  raw,  adapter,  log: (event) => {    runtime.log?.debug?.(`turn.${event.stage}:${event.event}`, {      channel: event.channel,      accountId: event.accountId,      messageId: event.messageId,      sessionKey: event.sessionKey,      admission: event.admission,      reason: event.reason,    });  },});

Etapas registradas: ingest, classify, preflight, resolve, authorize, assemble, record, dispatch, finalize. Evite registrar corpos brutos; use MessageFacts.preview para prévias curtas redigidas.

O que permanece local ao canal

O kernel é responsável pela orquestração. O canal ainda é responsável por:

• Transportes da plataforma (Gateway, REST, websocket, polling, Webhooks)
• Resolução de identidade e correspondência de nome de exibição
• Comandos nativos, comandos de barra, preenchimento automático, modais, botões, estado de voz
• Renderização de cartões, modais e cartões adaptativos
• Autenticação de mídia, regras de CDN, mídia criptografada, transcrição
• APIs de edição, reação, redação e presença
• Preenchimento retroativo e busca de histórico no lado da plataforma
• Fluxos de pareamento que exigem verificação específica da plataforma

Se dois canais começarem a precisar do mesmo helper para um desses itens, extraia um helper compartilhado do SDK em vez de colocá-lo no kernel.

Estabilidade

runtime.channel.turn.* faz parte da superfície pública de runtime de Plugin. Os tipos de fatos (SenderFacts, ConversationFacts, RouteFacts, ReplyPlanFacts, AccessFacts, MessageFacts, SupplementalContextFacts, InboundMediaFacts) e formatos de admissão (ChannelTurnAdmission, ChannelEventClass) são acessíveis por PluginRuntime a partir de openclaw/plugin-sdk/core.

Regras de compatibilidade retroativa se aplicam: novos campos de fatos são aditivos, tipos de admissão não são renomeados e os nomes dos pontos de entrada permanecem estáveis. Novas necessidades de canal que exigem uma alteração não aditiva devem passar pelo processo de migração do SDK de Plugin.

Relacionados

• Refatoração do ciclo de vida de mensagens para o ciclo de vida planejado de envio/recebimento/ao vivo que envolverá este kernel
• Criando plugins de canal para o contrato mais amplo de Plugin de canal
• Helpers de runtime de Plugin para outras superfícies runtime.*
• Internos de Plugin para pipeline de carregamento e mecânica do registro