Channel turn kernel

The channel turn kernel is the shared inbound state machine that turns a normalized platform event into an agent turn. Channel plugins provide the platform facts and the delivery callback. Core owns the orchestration: ingest, classify, preflight, resolve, authorize, assemble, record, dispatch, and finalize.

Use this when your plugin is on the inbound message hot path. For non-message events (slash commands, modals, button interactions, lifecycle events, reactions, voice state), keep them plugin-local. The kernel only owns events that may become an agent text turn.

Why a shared kernel

Channel plugins repeat the same inbound flow: normalize, route, gate, build a context, record session metadata, dispatch the agent turn, finalize delivery state. Without a shared kernel, a change to mention gating, tool-only visible replies, session metadata, pending history, or dispatch finalization has to be applied per channel.

The kernel keeps four concepts deliberately separate:

• text

  Copy

  ConversationFacts
  : where the message came from
• text

  Copy

  RouteFacts
  : which agent and session should process it
• text

  Copy

  ReplyPlanFacts
  : where visible replies should go
• text

  Copy

  MessageFacts
  : what body and supplemental context the agent should see

Slack DMs, Telegram topics, Matrix threads, and Feishu topic sessions all distinguish these in practice. Treating them as one identifier causes drift over time.

Stage lifecycle

The kernel runs the same fixed pipeline regardless of channel:

1. text

   Copy

   ingest
   -- adapter converts a raw platform event into
   text

   Copy

   NormalizedTurnInput
2. text

   Copy

   classify
   -- adapter declares whether this event can start an agent turn
3. text

   Copy

   preflight
   -- adapter does dedupe, self-echo, hydration, debounce, decryption, partial fact prefill
4. text

   Copy

   resolve
   -- adapter returns a fully assembled turn (route, reply plan, message, delivery)
5. text

   Copy

   authorize
   -- DM, group, mention, and command policy applied to the assembled facts
6. text

   Copy

   assemble
   --
   text

   Copy

   FinalizedMsgContext
   built from the facts via
   text

   Copy

   buildContext
7. text

   Copy

   record
   -- inbound session metadata and last route persisted
8. text

   Copy

   dispatch
   -- agent turn executed through the buffered block dispatcher
9. text

   Copy

   finalize
   -- adapter
   text

   Copy

   onFinalize
   runs even on dispatch error

Each stage emits a structured log event when a

callback is supplied. See Observability.

Admission kinds

The kernel does not throw when a turn is gated. It returns a

:

Admission can come from

(event class said it cannot start a turn), from (dedupe, self-echo, missing mention with history record), or from itself.

Entry points

The runtime exposes three preferred entry points so adapters can opt in at the level that matches the channel.

typescript
Copy
runtime.channel.turn.run(...)             // adapter-driven full pipeline
runtime.channel.turn.runPrepared(...)     // channel owns dispatch; kernel runs record + finalize
runtime.channel.turn.buildContext(...)    // pure facts to FinalizedMsgContext mapping

Two older runtime helpers remain available for Plugin SDK compatibility:

typescript
Copy
runtime.channel.turn.runResolved(...)      // deprecated compatibility alias; prefer run
runtime.channel.turn.dispatchAssembled(...) // deprecated compatibility alias; prefer run or runPrepared

run

Use when your channel can express its inbound flow as a

. The adapter has callbacks for , optional , optional , mandatory , and optional .

typescript
Copy
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);
    },
  },
});

is the right shape when the channel has small adapter logic and benefits from owning the lifecycle through hooks.

runPrepared

Use when the channel has a complex local dispatcher with previews, retries, edits, or thread bootstrap that must stay channel-owned. The kernel still records the inbound session before dispatch and surfaces a uniform

.

typescript
Copy
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();
  },
});

Rich channels (Matrix, Mattermost, Microsoft Teams, Feishu, QQ Bot) use

because their dispatcher orchestrates platform-specific behavior the kernel must not learn about.

buildContext

A pure function that maps fact bundles into

. Use it when your channel hand-rolls part of the pipeline but wants consistent context shape.

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

is also useful inside callbacks when assembling a turn for .

Fact types

The facts the kernel consumes from your adapter are platform-agnostic. Translate platform objects into these shapes before handing them to the kernel.

NormalizedTurnInput

ChannelEventClass

SenderFacts

ConversationFacts

RouteFacts

ReplyPlanFacts

AccessFacts

carries the booleans the authorize stage needs. Identity matching stays in the channel: the kernel only consumes the result.

MessageFacts

SupplementalContextFacts

Supplemental context covers quote, forwarded, and thread-bootstrap context. The kernel applies the configured

policy. The channel adapter only provides facts and flags so cross-channel policy stays consistent.

InboundMediaFacts

Media is fact-shaped. Platform download, auth, SSRF policy, CDN rules, and decryption stay channel-local. The kernel maps facts into

, , , , , , and .

Adapter contract

For full

, the adapter shape is:

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

returns a , which is an with an optional admission kind. Returning runs the turn without producing visible output. The adapter still owns the delivery callback; it just becomes a no-op for that turn.

runs on every result, including dispatch errors. Use it to clear pending group history, remove ack reactions, stop status indicators, and flush local state.

Delivery adapter

The kernel does not call the platform directly. The channel hands the kernel a

:

typescript
Copy
type ChannelTurnDeliveryAdapter = {
  deliver(payload: ReplyPayload, info: ChannelDeliveryInfo): Promise<ChannelDeliveryResult | void>;
  onError?(err: unknown, info: { kind: string }): void;
};

type ChannelDeliveryResult = {
  messageIds?: string[];
  threadId?: string;
  replyToId?: string;
  visibleReplySent?: boolean;
};

is called once per buffered reply chunk. Return platform message ids when the channel has them so the dispatcher can preserve thread anchors and edit later chunks. For observe-only turns, return or use .

Record options

The record stage wraps

. Most channels can use the defaults. Override via :

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

The dispatcher waits for the record stage. If record throws, the kernel runs

(when provided to ) and rethrows.

Observability

Each stage emits a structured event when a

callback is supplied:

typescript
Copy
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,
    });
  },
});

Logged stages:

, , , , , , , , . Avoid logging raw bodies; use for short redacted previews.

What stays channel-local

The kernel owns orchestration. The channel still owns:

• Platform transports (gateway, REST, websocket, polling, webhooks)
• Identity resolution and display-name matching
• Native commands, slash commands, autocomplete, modals, buttons, voice state
• Card, modal, and adaptive-card rendering
• Media auth, CDN rules, encrypted media, transcription
• Edit, reaction, redaction, and presence APIs
• Backfill and platform-side history fetch
• Pairing flows that require platform-specific verification

If two channels start needing the same helper for one of these, extract a shared SDK helper instead of pushing it into the kernel.

Stability

is part of the public plugin runtime surface. The fact types (, , , , , , , ) and admission shapes (, ) are reachable through from .

Backward compatibility rules apply: new fact fields are additive, admission kinds are not renamed, and the entry point names stay stable. New channel needs that require a non-additive change must go through the plugin SDK migration process.

Related

• Building channel plugins for the broader channel plugin contract
• Plugin runtime helpers for other
  text

  Copy

  runtime.*
  surfaces
• Plugin internals for load pipeline and registry mechanics