Chat v2: Channels

[FredKSchott]

RFC

First-Party Channels: @flue/channels for Slack, Discord, and GitHub

What a channel is

A channel is a package module that owns the boilerplate of connecting one platform to a Flue app:

1. Verified ingress — a Fetch-compatible handler that does signature verification, platform handshakes (Slack URL challenge, Discord PING), ack-deadline handling, and retry/delivery-id surfacing. You mount it in app.ts with one line.
2. Typed platform-native events — handlers you register to decide which agent, which instance id, which input — and then you call dispatch(). Routing stays in your code; the channel never auto-routes into agents.
3. Outbound capabilities — a platform client plus tool factories that produce pre-scoped agent tools (slack.tools.replyInThread(ref)). Trusted code binds the destination; the model only picks content.

Critically, a channel is plain code built on public primitives (dispatch, defineTool, Fetch, Web Crypto). No defineChannel runtime abstraction, no channels/ discovery, no /channels/* mounting, no generic emit/on event bus — the things removed in dc6f6a5 stay removed. The "hooks for building your own channel" are the primitives themselves plus a small shared Channel interface (essentially { fetch(request): Promise<Response> }, with a reserved slot for future lifecycle). Someone wiring up Chat SDK is just building a channel this same way; Chat SDK remains a documented alternative.

What it looks like (Slack sketch)

// src/channels/slack.ts — plain module, no framework discovery
import { createSlackChannel } from '@flue/channels/slack';
import { dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';

export const slack = createSlackChannel({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
  botToken: process.env.SLACK_BOT_TOKEN!,
});

slack.on('app_mention', async (event) => {
  await dispatch(assistant, {
    id: slack.conversationKey(event),  // stable "team:channel:thread" key
    input: { type: 'slack.app_mention', text: event.text, eventId: event.eventId },
  });
});

// src/app.ts
app.mount('/slack', slack.fetch);      // verified ingress, one line

// src/agents/assistant.ts
export default createAgent(({ id }) => ({
  tools: [slack.tools.replyInThread(slack.parseConversationKey(id))],
}));

Note slack.on(...) is not the old emitter mistake: the old defineChannel was a generic framework emitter where users wrote both sides. Here the events are owned and typed by the provider package — normal SDK design (Octokit webhooks work this way). The durable boundary remains dispatch().

Packaging

One package, @flue/channels, with per-provider subpath exports (@flue/channels/github, /slack, /discord):

• All three v1 channels need zero runtime npm dependencies — HMAC-SHA256 (GitHub, Slack) and Ed25519 (Discord) via Web Crypto on both Workers and Node; outbound APIs are plain fetch. Payload typings are type-only dev dependencies.
• Subpath exports keep unused providers out of user bundles; one install, no per-provider package sprawl; slots into the future flue umbrella package as one dependency.
• Kept out of @flue/runtime to preserve the layering proof: if first-party channels needed private runtime hooks, third parties couldn't build their own. v1 requires zero runtime/CLI changes.

v1 scope: HTTP ingress only — and why

Slack Socket Mode and the Discord Gateway are persistent WebSocket connections your server opens outbound to receive events without a public URL. They require a long-lived process — fundamentally incompatible with request-scoped Workers, and they'd need a new Node-only start/stop lifecycle in Flue. Deferred. v1 channels are HTTP-only, identical on Node and Cloudflare:

Channel	v1 (HTTP) covers	Deferred (long-lived)
@flue/channels/github	Full webhook surface (this is everything GitHub has)	—
@flue/channels/slack	Events API (mentions, messages, threads), interactivity payloads, 3s-ack handling	Socket Mode (mainly a local-dev convenience)
@flue/channels/discord	Interactions only: slash commands, buttons/components, signature + PING, immediate-ack replies	Gateway — required for reacting to plain messages; deferred-response editing

Consequences accepted explicitly:

• Discord v1 = a slash-command/interaction bot, not a "reads the room" bot. That's the Worker-friendly subset and still genuinely useful.
• Local dev needs a tunnel (cloudflared/ngrok) since platforms must reach your webhook. Documented; Socket Mode later improves this.

The shared Channel interface reserves start?/stop? so a future Node lifecycle slots in without redesign.

Replies, and per-event capability tokens

Replies are per-channel, platform-native tools — no universal reply/thread abstraction. Cross-channel consistency is structural, not semantic: every channel configures, mounts, registers events, and exposes tool factories the same way; only the vocabulary is platform-specific.

One investigated finding shapes the Discord design: per-event capability tokens (Discord's 15-minute interaction token, Slack's interactivity response_url) cannot cleanly reach tool execution today — tools receive only model-supplied arguments, and dispatch input isn't exposed to the initializer or tool context. Channel-side persistence wouldn't fix it (on Cloudflare, ingress runs in the Worker while tools run in the agent's Durable Object). So:

• Discord v1 acks interactions immediately and replies via bot-token tools.postMessage(channelRef) — no per-event capability needed.
• The right long-term fix is a small runtime enhancement exposing the current operation's dispatch input to tool execution (the runtime already carries it internally). That's a general-purpose feature, deferred as an explicit follow-up with Discord deferred-response editing and Slack response_url as motivating cases.

Channels also hold no server-side state in v1 and do not use Flue's persistence layer — that layer is intentionally internal (sessions, queues, streams) with no app-facing storage API. OAuth installations, gateway resume state, and dedup stores arrive only with their already-deferred features.

Interactive cards / HITL

All three platforms share a "post actionable thing → receive structured action event" loop (Slack Block Kit, Discord components, GitHub comment commands). A shared approval-card abstraction is plausible but out of scope for v1 — kept as a design constraint: event/tool shapes must allow a shared layer to compile down to them later. A design-validation sketch (approve/reject card on Slack + Discord) runs last, before first publish, so any API-shape corrections are free.

Build order and runtime impact

GitHub first (simplest, validates the contract) → Slack (ack deadlines, threads, richest reply tools) → Discord (hardest, interaction semantics) → docs + card-sketch validation → release.

Runtime/CLI changes required: none. First work item: delete the dead packages/connectors/ deprecation stub. v1 is single-workspace token config; multi-workspace OAuth is out of scope but not blocked by the config shape.

Click to expand this summary

Note: Sharing this from my agent. These plan files are all local, but not required reading to understand this plan. Anything important is restated.

Status and scope

This plan replaces plans/2026-05-24-optional-authored-channels-direct-sdk-integrations-and-channel-hardening.md and supersedes the channel portions of plans/resource-routes-stateful-channels-and-global-dispatch.md and plans/stateful-channels-agent-listeners-and-global-dispatch.md. The framework has changed materially since those documents were written:

• The authored-channel runtime concept was removed entirely in dc6f6a5 ("refactor: remove channels concept"): defineChannel(...), channels/* discovery, /channels/:name/* mounting, channel docs, and both channel examples are gone.
• dispatch(...) survived and is the supported external-input primitive: dispatch(agent, { id, input }) / dispatch({ agent, id, input }) from @flue/runtime, with durable admission on Cloudflare and on Node when a db.ts persistence adapter is configured.
• Named sessions were removed (f5f2928); dispatched input lands in the instance's default session. The agent instance id is now the conversation-identity surface.
• WebSocket/SSE transports were replaced by the Durable Streams protocol; agents/workflows export only optional route middleware.
• The canonical integration pattern is documented (apps/docs/.../guide/chat.md, examples/chat-sdk/): application-owned webhook route → dispatch() with a thread-derived instance id → replies through explicit agent tools scoped by trusted code.

This plan defines what first-party channel support should be, given that baseline.

Lessons carried forward

The removed defineChannel was a generic in-process event emitter (emit/on) plus a mounted Hono app. It abstracted the easy part (calling a function in the same build) while skipping every hard part (verification, ack deadlines, outbound APIs, retries), and its { invoked, errors } aggregation made it easy to acknowledge webhooks whose work had been lost. Its removal was correct, and this plan does not reintroduce it.

The durable boundary in Flue is dispatch(), not an event bus. Everything between the provider and dispatch() is ordinary application code; the value of a first-party channel is owning the provider-specific parts of that code, not inventing new framework semantics.

What a channel is

A channel is a provider integration module that owns the boilerplate of connecting one platform to a Flue application:

1. Verified ingress — a Fetch-compatible handler covering signature verification, platform handshakes (Slack URL verification, Discord PING), ack-deadline behavior, and retry/delivery-id surfacing. The user mounts it in app.ts with one line.
2. Typed provider-native events — handlers the user registers to decide which agent, which instance id, and which input — and then call dispatch(). Routing into agents always remains explicit user code; a channel never auto-routes.
3. Outbound capabilities — a provider API client plus tool factories that produce pre-scoped agent tools (e.g. slack.tools.replyInThread(ref)). Trusted code binds the destination; the model only chooses content.

Critically, a channel is plain code built on public primitives (dispatch, defineTool, Fetch, Web Crypto). v1 requires zero changes to @flue/runtime or @flue/cli. The "hooks for building your own channel" are the existing primitives plus a small shared contract type. A user wiring up Chat SDK, or any provider we do not cover, builds their channel exactly the way ours are built.

Packaging

One package: @flue/channels, with per-provider subpath exports:

@flue/channels           — shared contract types and ingress utilities
@flue/channels/github
@flue/channels/slack
@flue/channels/discord

Decision rationale:

• Zero runtime npm dependencies are achievable for all v1 channels. GitHub and Slack verification is HMAC-SHA256; Discord verification is Ed25519; both are available through Web Crypto on Workers and Node ≥ 22 (the repo already requires Node ≥ 22.18). Outbound provider APIs are plain fetch + JSON. Provider payload typings come from type-only dev dependencies or vendored types, which ship no code.
• Subpath exports keep unused providers out of user bundles, so one install does not ship Discord code to Slack-only users.
• A single package avoids per-provider package sprawl and slots cleanly into the planned flue umbrella package as one dependency.
• Keeping channels out of @flue/runtime preserves the layering proof: if first-party channels needed private runtime hooks, third parties could not build their own. Independent versioning also decouples provider-API churn from runtime releases.

Naming note: the term "connector" is already used by the flue add <name> instruction-scaffolding flow, so "channel" does not collide. The old transport-manifest naming conflict is resolved (channels: was renamed transports: in the runtime manifest). A flue add slack-style scaffold that writes the channel module and app.ts mount on top of @flue/channels is a natural follow-up, out of scope here.

Cleanup item: packages/connectors/ is a private, unreferenced deprecation stub (package.json + README only) left behind when flue add replaced it. Delete it at the start of this work.

Public API design

Shared contract (@flue/channels)

/** Implemented by every channel. Mountable anywhere a Fetch handler fits. */
export interface Channel {
	/** Verified provider ingress. Mount under one base path. */
	fetch(request: Request): Promise<Response>;
	// Reserved, not implemented in v1:
	// start?(ctx: ChannelStartContext): Promise<void>;
	// stop?(): Promise<void>;
}

The root subpath also exports the small ingress utilities our providers share and third-party channel authors need: timing-safe comparison, HMAC-SHA256 signing/verification helpers, and an Ed25519 verification helper. Nothing else: no event-bus, no registry, no mounting framework.

Mounting uses Hono's existing fetch-mounting support; no Flue routing changes:

// src/app.ts
app.mount('/slack', slack.fetch);
app.route('/', flue());

Authoring pattern

A channel instance is created in a plain module (no framework discovery), imported by app.ts for mounting and by agent modules for tool factories:

// src/channels/slack.ts — plain module
import { createSlackChannel } from '@flue/channels/slack';
import { dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';

export const slack = createSlackChannel({
	signingSecret: process.env.SLACK_SIGNING_SECRET!,
	botToken: process.env.SLACK_BOT_TOKEN!,
});

slack.on('app_mention', async (event) => {
	await dispatch(assistant, {
		id: slack.conversationKey(event), // "T123:C456:1717971234.0012"
		input: {
			type: 'slack.app_mention',
			text: event.text,
			user: event.user,
			eventId: event.eventId, // provider delivery id for idempotency
		},
	});
});

// src/agents/assistant.ts
import { createAgent } from '@flue/runtime';
import { slack } from '../channels/slack.ts';

export default createAgent(({ id }) => ({
	model: 'anthropic/claude-haiku-4-5',
	instructions: 'Reply in the current Slack thread when a response is appropriate.',
	tools: [slack.tools.replyInThread(slack.parseConversationKey(id))],
}));

slack.on(...) is not the removed emitter pattern: events are owned and typed by the provider package (the way Octokit webhooks or Chat SDK handlers work), not declared by users on both sides of a generic bus. The durable boundary remains dispatch().

Event handling and acknowledgement semantics

Handlers run inline within the ingress request; the provider response depends on handler outcome:

• A request that fails verification returns 401 without invoking handlers.
• A handler that throws (including a rejected dispatch()) produces a provider-visible failure (500) so the provider retries. A channel must never acknowledge a delivery whose required work was not admitted.
• Events with no registered handler are acknowledged successfully.
• Provider delivery identifiers (GitHub X-GitHub-Delivery, Slack event_id + X-Slack-Retry-Num, Discord interaction id) are surfaced on every event so applications can implement idempotency; retries after partial success can duplicate dispatched input, and dispatched input should carry the delivery id.

dispatch() is admission-only and fast, so inline handling fits Slack's 3-second ack deadline; channels do not need background-ack machinery in v1.

Conversation identity

Each channel defines a stable, parseable conversation key and helpers in both directions:

• channel.conversationKey(event) → string suitable as an agent instance id (e.g. Slack team:channel:threadTs, Discord guild:channel, GitHub owner/repo#issue).
• channel.parseConversationKey(id) → typed destination ref accepted by tool factories.

This makes the documented "thread as instance id" convention concrete without forcing it: applications with account- or repo-level identity can use their own ids and construct destination refs explicitly. Tool factories accept refs, never raw model-chosen strings, preserving the rule that trusted code selects outbound destinations.

Outbound tools and clients

Outbound capabilities are platform-native; there is no universal reply/thread/message abstraction. Cross-channel consistency is structural, not semantic: every channel configures, mounts, registers events, and exposes tools.* factories the same way; only the vocabulary is provider-specific.

Each provider exposes:

• channel.client — a thin typed fetch-based API client for the operations our tools need, with an escape hatch for arbitrary authenticated calls. Users may ignore it and use official SDKs.
• channel.tools.* — factories returning defineTool(...) values pre-bound to a destination ref and the channel's credentials.

Configuration

Factories take explicit config values. Module-scope creation with process.env works on Node and on Workers with nodejs_compat env population; the docs note this requirement. Config resolution is lazy (validated at first use, not at import) so module-scope channel creation does not crash builds or cold starts that never receive provider traffic. v1 is single-workspace/single-app token configuration; OAuth installation/multi-tenant flows are out of scope but must not be blocked by the config shape (config fields that would become per-installation lookups — bot tokens — are isolated from config fields that are app-global — signing secrets).

Provider scope (v1: HTTP ingress only)

Slack Socket Mode and the Discord Gateway are persistent WebSocket connections a server opens outbound. They require a long-lived process, are incompatible with request-scoped Workers, and would need a new Node-only start/stop lifecycle in Flue. They are deferred; the Channel interface reserves start/stop so a future Node lifecycle slots in without redesign. v1 channels are HTTP-only and behave identically on Node and Cloudflare.

Channel	v1 (HTTP) covers	Deferred (long-lived transport)
@flue/channels/github	Full webhook surface — this is everything GitHub has	—
@flue/channels/slack	Events API (mentions, messages, threads), interactivity payloads, URL verification, 3s ack, retry headers	Socket Mode (primarily a local-dev convenience)
@flue/channels/discord	Interactions only: slash commands, components/buttons, modals; Ed25519 verification; PING/PONG; deferred-response flow	Gateway — required to observe plain channel messages

Consequences accepted explicitly:

• Discord v1 is a slash-command/interaction bot, not a bot that reacts to ordinary messages. That is the Worker-compatible subset and is genuinely useful.
• Local development requires a tunnel (cloudflared, ngrok) so providers can reach the webhook. Documentation covers this; Socket Mode later improves the local story.

Provider-specific design notes

GitHub (build first; simplest, validates the contract):

• HMAC-SHA256 verification of X-Hub-Signature-256; typed on('issues.opened', ...)-style events using type-only payload typings.
• tools.commentOnIssue(ref), tools.addLabels(ref) as initial factories; client covers issue/PR comment and label endpoints.

Slack (second; richest conversational surface):

• Events API endpoint plus interactivity endpoint behind one fetch; URL-verification challenge handled internally; signature verification with 5-minute timestamp window.
• Events surface eventId, retryNum, team/channel/thread refs. conversationKey uses team:channel:thread_ts (falling back to the message ts as thread root).
• tools.replyInThread(ref), tools.addReaction(ref) initially; client wraps chat.postMessage, reactions.add.

Discord (third; hardest, stress-tests the capability-binding pattern):

• Ed25519 request verification; PING→PONG handled internally.
• Interaction handlers must produce an interaction response within 3 seconds. The intended agent pattern: the handler returns a deferred response (type 5) and dispatches; the agent replies through tools.followUp(interactionRef), where the interaction token travels inside the dispatched input. Tokens expire after 15 minutes, so channels also provide tools.postMessage(channelRef) via the bot token for slow replies.
• This flow is the proof that per-event capabilities (the token) can ride through dispatch() input into pre-scoped tools without new runtime support. If it cannot be expressed cleanly, that is a finding to bring back to design, not to patch with runtime hooks.

Interactive cards / human-in-the-loop (design constraint, not deliverable)

All three platforms share a loop: post an actionable element (Slack Block Kit, Discord components, GitHub comment commands) → receive a structured action event → resume work. A shared "card"/approval abstraction is plausibly valuable for human-in-the-loop flows but is out of scope for v1.

Design constraint now: each channel's interaction events and "post message with actions" tools must be shaped so a shared layer could later compile down to them — i.e., action events carry a stable application-chosen action id and structured values, and posting tools accept provider-native component payloads rather than only plain text.

Validation exercise, ordered last before release: sketch (on paper, against the built APIs) an approve/reject approval card on Slack and Discord. If the sketch reveals API-shape problems, fix them before the first publish, while breaking changes are free.

Non-goals

• No defineChannel-style runtime abstraction, generic emit/on event bus, channels/* discovery, or /channels/:name/* framework mounting.
• No universal cross-provider message/reply/thread schema.
• No automatic routing of provider events into agents; dispatch() calls are always explicit user code.
• No long-lived transports (Socket Mode, Discord Gateway) or runtime lifecycle hooks in v1.
• No OAuth installation / multi-workspace lifecycle in v1.
• No built-in dispatch deduplication from provider delivery ids; channels surface the ids, applications own idempotency.
• No requirement that integrations use @flue/channels; custom routes + dispatch() and third-party SDKs (including Chat SDK) remain fully supported and documented.

Implementation plan

Phase 0: Repo preparation and shared contract

1. Delete the deprecated packages/connectors/ stub.
2. Create packages/channels/ (@flue/channels) following existing package conventions (tsdown build, vitest, subpath exports map, Node ≥ 22.18 engine).
3. Implement the root subpath: Channel interface, timing-safe compare, HMAC-SHA256 helpers, Ed25519 verify helper.
4. Tests for the crypto utilities against known vectors, on Node and in the Workers integration harness.

Phase 1: GitHub channel

1. createGitHubChannel({ webhookSecret, token? }) with verified fetch, typed events, delivery-id surfacing, handler-failure → 500 semantics.
2. conversationKey/parseConversationKey for repo/issue refs; client and initial tool factories (commentOnIssue, addLabels).
3. Example: examples/github-channel/ — webhook → dispatch → agent replies with a comment tool; runnable on Node and Cloudflare.
4. Contract-level tests (see test plan).

Phase 2: Slack channel

1. createSlackChannel({ signingSecret, botToken }): events + interactivity ingress, URL verification, timestamp-window signature checks, retry-header surfacing.
2. Conversation keys, client (chat.postMessage, reactions.add), tool factories (replyInThread, addReaction).
3. Update or extend the chat docs/example so the Slack channel is the primary first-party path and Chat SDK remains the documented alternative.

Phase 3: Discord channel

1. createDiscordChannel({ publicKey, applicationId, botToken }): Ed25519 verification, PING handling, typed command/component/modal handlers returning interaction responses, deferred-response support.
2. Interaction refs (including token + expiry) designed to travel through dispatched input; tools.followUp(interactionRef) and tools.postMessage(channelRef).
3. Example demonstrating the defer → dispatch → follow-up flow end to end.

Phase 4: Docs, design validation, release

1. Docs: a "Channels" guide (what channels are, mounting, identity keys, ack/retry/idempotency, Node vs Workers parity, tunnel-based local dev), per-provider reference pages, and a "build your own channel" page showing the contract and utilities (with Chat SDK as a worked example of a custom channel).
2. Revise guide/chat.md to position first-party channels, Chat SDK, and bare routes + dispatch() as the three supported styles.
3. Run the approval-card design validation exercise (Slack + Discord sketch); apply any API-shape corrections.
4. Release @flue/channels via the standard release flow.

Test plan

Design tests from the channel's observable contract (ingress request in, dispatch admission + provider response out; tool invocation in, provider API request out), using a narrow fetch-transport fixture for outbound calls and the runtime's real test harness for dispatch where practical.

1. A correctly signed provider request invokes the registered handler and is acknowledged per provider semantics.
2. A request with a bad or missing signature is rejected (401) without invoking handlers.
3. A handler that throws (or whose dispatch() rejects) yields a provider-visible failure response.
4. An event with no registered handler is acknowledged successfully.
5. Delivery identifiers are present on events and can be carried into dispatched input.
6. Slack: URL-verification challenge round-trips; stale-timestamp requests are rejected; retry headers surface.
7. Discord: PING→PONG; a command handler can return a deferred response; an interaction ref serialized through dispatch input drives followUp correctly, including token-expiry signaling.
8. Tool factories produce tools whose execution issues the expected authenticated provider API request and never accept model-supplied destinations.
9. At least one channel's ingress runs under the Cloudflare integration test config to prove Workers parity (Web Crypto paths especially Ed25519).

Decision log

Decision	Choice
Runtime abstraction for inbound events	None; app route → channel ingress → explicit dispatch()
Packaging	Single @flue/channels package, per-provider subpaths, zero runtime deps
Runtime/CLI changes in v1	None
Providers and order	GitHub → Slack → Discord
Long-lived transports (Socket Mode, Gateway)	Deferred; Channel reserves start/stop
Reply path	Per-channel platform-native tool factories; no universal abstraction
Cards/HITL	Out of scope; design constraint + pre-release validation sketch
Multi-workspace OAuth installs	Out of scope; config shape must not block it
Chat SDK	Remains a supported, documented alternative built on the same hooks

Completion criteria

• packages/connectors/ is removed.
• @flue/channels ships GitHub, Slack, and Discord channels meeting the test plan, working on Node and Cloudflare targets with no @flue/runtime/@flue/cli changes.
• Examples demonstrate webhook → dispatch → tool-based reply for each provider, including Discord's deferred-interaction flow.
• Docs present first-party channels, custom routes + dispatch(), and third-party SDKs as supported styles, with ack/retry/idempotency and local-dev tunnel guidance.
• The approval-card validation sketch has been performed and any resulting API corrections applied before first publish.