feat(channels): Channels, the capability that serves a conversation's surfaces by cjol · Pull Request #2431 · cloudflare/agents

cjol · 2026-10-01T13:55:44Z

This PR adds Channels, a Lifecycle capability that serves an agent harness's sessions as conversations to every surface that joins them.

Why

The harness owns the transcript and turns. Something has to carry inbound events to it, publish turn and message updates, and stream responses to every surface showing the conversation.
Serving any harness through one interface means an agent connects with one line, Channels.forHarness(harness, { channels }), and no agent-specific bridge.
Responses go through Streams, so they are durable and resumable without a channel-specific stream store. Resume is state-based: on start, Channels watches each known session again, and a run in progress continues its partial message.

Public API Surface

Additive, exported from agents/experimental/channels:

Symbol	Kind	Notes
`Channels`	class	Lifecycle capability; `forHarness`, `receive`, `streams`, `websockets`
`ChannelsOptions`, `ForHarnessOptions`	types	A harness, its channels, and optional shared `Streams` and `WebSockets`
`ChannelsHost`, `ChannelState`	types	What a mounted channel is given, and its per-channel state
`ConversationChannel`	interface	What a surface implementation provides
`GatewayEvent`, `ConversationUpdate`, `ResponseEnding`, `ResponseReadOptions`	types	Events and updates passed between layers

Code Changes

conversations.ts implements Channels. It mounts each ConversationChannel with a host that offers shared WebSockets, the conversation operations, listing and dispatch, and fans updates out to every channel.
harness-conversations.ts maps the harness to conversations. A conversation is a session with the same id, and a turn is one operation. A run is one response, which steers share. Tool results and approval responses reach the harness as tool answers on the turn they answer, and a refused answer leaves the turn waiting.
response.ts (internal) validates chunk order, so a malformed response fails at the writer, not on a surface.
An event that names no conversation joins the harness's default session.
Minor changeset for agents.

changeset-bot · 2026-10-01T13:55:50Z

🦋 Changeset detected

Latest commit: e734256

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Minor
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

devin-ai-integration

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 8 potential issues.

devin-ai-integration · 2026-10-01T13:57:54Z

Streams.list

+    const streaming = await this.#options.streams.list({
+      state: "streaming",
+      // Streams lists 100 by default. A loop until none are left would drop
+      // the cap, but `list()` matches tags exactly, not by prefix, so streams
+      // other capabilities left streaming would come back on every pass.
+      limit: 1000
+    });


🔴 Older responses stay live after restart

If Streams.list returns 1,000 newer live streams, onStart never visits older responses. Their readers tail indefinitely because no producer survives restart.

Learn more

Streams.list orders all streams newest first and enforces the requested limit before any tag filtering here. Startup marks only the returned Channels streams interrupted. Any older Channels stream remains streaming, and readBatches waits for another append or settlement even though its producer was lost on restart.

Example: A Durable Object has 1,000 newer streaming streams from another capability and one older response r1. Startup skips r1; subscribing to it replays stored chunks and then waits forever.

Recommended fix: Add paginated/prefix-filtered enumeration to Streams or otherwise iterate all streaming rows without repeatedly returning unrelated streams, and settle every Channels response before startup finishes.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-01T13:57:55Z

#dispatch

+    await this.#dispatch(
+      event.type !== "approval-response" || "turnId" in event
+        ? event
+        : await this.#withTurn(event, origin),
+      origin
+    );


🟡 Concurrent approvals fail before earlier events finish

When an approval arrives during an earlier event, #withTurn reads the snapshot before that event completes. It rejects instead of waiting for #queues to expose the pending approval.

Learn more

Events are serialized by #dispatch, but a webhook approval with no turn ID resolves its turn before entering that queue. When the prior event is still creating the approval request, its message is missing from the snapshot read by #withTurn. The approval rejects rather than taking effect after the earlier event.

Example: Message e1 starts a turn and is still writing an approval-requested tool part when webhook event e2 approves it. e2 reads the old snapshot and fails, although e1 then finishes saving the approval.

Recommended fix: Enqueue turn resolution and the subsequent onEvent call as one serialized operation for the conversation, retaining the event-ID deduplication behavior.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-01T13:57:57Z

+  /** Recent events by key, each with the outcome repeats receive. */
+  readonly #seen = new Map<string, Promise<void>>();


🔍 Accepted events replay after eviction

#seen is not durable. After an object restart, retrying an accepted event calls onEvent again and can repeat its effects.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-01T13:57:58Z

+    const ending = await streams.status(responseId);
+    return ending?.state === "errored" ? "interrupted" : "ended";


🔍 Reset can disguise response deletion

If reset deletes a response during a read, the final status is null and readResponse returns ended. Surfaces can mistake deletion for completion.

Was this helpful? React with 👍 or 👎 to provide feedback.

agent-think · 2026-10-01T13:59:20Z

🟢 agents import sizes: 1 entry point changed, no growth

	Entry point	Exports	Largest gzip change	Size now
🆕	`agents/experimental/channels`	1 new	—	8.3 KiB

Changed exports (1)

	Import	Gzip change	Size now
🆕	`agents/experimental/channels#Channels`	—	8.3 KiB

How this works

Each runtime export is bundled on its own, minified, and gzipped. Changes smaller than 100 B, or smaller than 1% and 1 KiB, are ignored. Growth over 10% or 5 KiB is marked 🔴. This report is informational and does not fail CI. The workflow artifact contains every measurement.

_{Compared dc1a5c45 → e7342565 · workflow run · reported by agent-think[bot]}

pkg-pr-new · 2026-10-01T14:43:49Z

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2431

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2431

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2431

hono-agents

npm i https://pkg.pr.new/hono-agents@2431

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2431

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2431

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2431

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2431

commit: e734256

devin-ai-integration

Devin Review found 4 new potential issues.

devin-ai-integration · 2026-10-02T17:40:24Z

HarnessConversations

+  async #reset(conversationId: string): Promise<void> {
+    const streams = this.streams;
+    const tag = TAG_PREFIX + conversationId;
+    for (;;) {
+      const batch = await streams.list({ tag });
+      if (batch.length === 0) break;
+      for (const { streamId, state } of batch) {
+        if (state === "streaming") (await streams.open(streamId)).close();
+        await streams.delete(streamId);
+      }
+    }
+    // Events accepted before the reset may be sent again to rebuild it.
+    const prefix = JSON.stringify([conversationId]).slice(0, -1) + ",";
+    for (const key of this.#seen.keys()) {
+      if (key.startsWith(prefix)) this.#seen.delete(key);
+    }
+    await this.#publish(conversationId, { type: "reset" });


🔴 Reset retains turns from old context

After a session reset, #reset leaves durable turn and alias records intact. Snapshots show old awaiting-input turns, and reused operation IDs can inherit stale statuses.

Learn more

A reset starts a new session context, but Channels stores turn and alias records separately from response streams. HarnessConversations reads those records for snapshots and new operations. Deleting streams and the in-memory deduplication entries leaves the prior context's turn records available. A later operation with a reused ID can inherit a settled record, so the new run is not reported correctly.

Example: A session has turn op-1 awaiting a tool result. Resetting clears the harness transcript, but a fresh snapshot still includes op-1; resending op-1 in the new context does not create a new queued turn.

Recommended fix: Clear both channels:harness:turn: and channels:harness:alias: records scoped to this session when processing the reset event, before publishing the reset update. Keep the deletion scoped to one conversation.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-02T17:40:25Z

#settle

+          await this.#save(conversationId, {
+            turnId: operationId,
+            startedBy: operationId,
+            messageId: operationId,
+            status: "queued"
+          });


🔴 Harness message IDs lose turn outcomes

When a harness submission uses a distinct messageId, #operation records its operation ID as the message ID. #settle then misses its assistant messages and marks unanswered tool calls completed.

Learn more

The shared harness accepts a caller-specified messageId independent of its operation ID. Its queued status contains only the operation ID, so the turn record created here cannot identify the submitted user's message. #settle locates the user message using turn.messageId and collects subsequent assistant messages. With a different ID it finds none, so a pending tool call is reported as completed instead of awaiting input.

Example: A harness client submits operation op-7 with messageId: "user-7"; the model emits an assistant message requesting approval. The resulting turn has no messageIds and reports completed, hiding the approval from the snapshot.

Recommended fix: Provide the real message ID with the harness operation status or associate the operation with the user message event, then persist that ID in the turn before settlement. Check direct harness submissions using custom message IDs in tests.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-02T17:40:26Z

#settle

+      case "cancel": {
+        const turn = this.#turnRecord(conversationId, event.turnId);
+        await link.session.abort(turn?.operation ?? event.turnId);
+        return;


🟡 Awaiting-input turns survive cancellation

When a participant cancels an awaiting-input turn, onEvent aborts its already completed operation. No status transition follows, so the turn remains awaiting input.

Learn more

An operation can finish while its assistant message still requests a tool answer. #settle then saves the turn as awaiting-input, while the operation is already done. Cancel passes the saved operation ID to the harness's abort method, which stops operations, but no later event is guaranteed for a completed operation. The durable turn therefore stays open in snapshots.

Example: Operation op-1 finishes after requesting approval and its turn is awaiting input. A cancel of op-1 calls abort("op-1") after it has finished; the snapshot still lists the approval turn.

Recommended fix: For an awaiting-input turn, explicitly persist and publish an aborted turn after canceling the relevant work. Preserve normal harness-driven abort handling for queued and running operations.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-02T17:40:28Z

@@ -1,4 +1,5 @@
 export * from "./channel";
+export * from "./conversations";


🔍 Public API description names the former entry point

The description calls this additive under agents/channels, but the exported entry point is agents/experimental/channels. Align the release-facing description with the migration.

Was this helpful? React with 👍 or 👎 to provide feedback.

… surfaces This PR adds `Channels`, a Lifecycle capability that serves an agent harness's sessions as conversations to every surface that joins them. ## Why - The harness owns the transcript and turns. Something has to carry inbound events to it, publish turn and message updates, and stream responses to every surface showing the conversation. - Serving any harness through one interface means an agent connects with one line, `Channels.forHarness(harness, { channels })`, and no agent-specific bridge. - Responses go through `Streams`, so they are durable and resumable without a channel-specific stream store. Resume is state-based: on start, Channels watches each known session again, and a run in progress continues its partial message. ## Public API Surface Additive, exported from `agents/experimental/channels`: | Symbol | Kind | Notes | | --- | --- | --- | | `Channels` | class | Lifecycle capability; `forHarness`, `receive`, `streams`, `websockets` | | `ChannelsOptions`, `ForHarnessOptions` | types | A harness, its channels, and optional shared `Streams` and `WebSockets` | | `ChannelsHost`, `ChannelState` | types | What a mounted channel is given, and its per-channel state | | `ConversationChannel` | interface | What a surface implementation provides | | `GatewayEvent`, `ConversationUpdate`, `ResponseEnding`, `ResponseReadOptions` | types | Events and updates passed between layers | ## Code Changes - `conversations.ts` implements `Channels`. It mounts each `ConversationChannel` with a host that offers shared WebSockets, the conversation operations, listing and dispatch, and fans updates out to every channel. - `harness-conversations.ts` maps the harness to conversations. A conversation is a session with the same id, and a turn is one operation. A run is one response, which steers share. Tool results and approval responses reach the harness as tool answers on the turn they answer, and a refused answer leaves the turn waiting. - `response.ts` (internal) validates chunk order, so a malformed response fails at the writer, not on a surface. - An event that names no conversation joins the harness's default session. - Minor changeset for `agents`.

## pnpm-workspace.yaml (default) ## Dependency Updates | Package | From | To | Type | | --- | --- | --- | --- | | `agents` | 0.26.0 | 0.27.0 | minor | ## Release Notes <details> <summary><b>agents</b> (0.26.0 → 0.27.0)</summary> This release adds four new experimental harnesses and a `web_search` tool, and reorganizes the experimental Channels API. - **New experimental harnesses:** `AiSdkHarness`, `ThinkHarness`, `ContainerHarness` (which runs Claude Code or Codex in a Container) and `OpenCodeHarness`, all with the same shape as `PiHarness`. - **New `agents/websearch`:** a `web_search` tool over Cloudflare's Web Search API for pi, the AI SDK and TanStack AI. - **Channels moved to `agents/experimental/channels`:** Channels is being rebuilt around conversations and turns, and the old `agents/channels` entry point has been removed. The new API includes `ChannelGateway`, the Web Channel and its client, an AI SDK chat transport, and a new `npx agents tui` terminal client. - **Fixes:** Streams, Tasks, `useAgentChat` reconnects, `WebChannelClient`, MCP credential cleanup on `removeServer()`, and x402 with MCP SDK v2. ### Minor Changes - [#2434](cloudflare/agents#2434) [`0ebeae5`](cloudflare/agents@0ebeae5) Thanks [@cjol](https://github.com/cjol)! - Add `AiSdkHarness` from the new `agents/harness/ai-sdk` entry point, which runs each message with `streamText` and keeps sessions and transcripts in the Durable Object, so `Channels.forHarness` can serve an AI SDK model. The same entry point exports the AI SDK message conversions it is built on and `createSendMessageTool`, an AI SDK tool that sends a message to a surface through the gateway. - [#2431](cloudflare/agents#2431) [`6393265`](cloudflare/agents@6393265) Thanks [@cjol](https://github.com/cjol)! - Add `Channels` to `agents/experimental/channels`: a Lifecycle capability that serves an agent harness's sessions as conversations to every surface that joins them, with durable, resumable responses on `Streams`. Connect a harness with `Channels.forHarness(harness, { channel …[full notes](https://github.com/cloudflare/agents/releases/tag/agents%400.27.0) </details> --- *This PR was auto-generated by [catalog-update-action](https://github.com/brandhaug/catalog-update-action).* Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

cjol added this pull request to stack #2440 October 1, 2026 13:56

devin-ai-integration Bot reviewed Oct 1, 2026

View reviewed changes

cjol force-pushed the channels/03-core branch 2 times, most recently from 717ffe7 to 34b446d Compare October 1, 2026 14:27

cjol force-pushed the channels/03-core branch 2 times, most recently from e1d0658 to c0fa1ec Compare October 2, 2026 11:08

cjol removed this pull request from stack #2440 October 2, 2026 17:37

cjol force-pushed the channels/03-core branch from c0fa1ec to 5f61d09 Compare October 2, 2026 17:37

cjol added this pull request to stack #2460 October 2, 2026 17:39

devin-ai-integration Bot reviewed Oct 2, 2026

View reviewed changes

cjol force-pushed the channels/03-core branch from 5f61d09 to e734256 Compare October 2, 2026 18:20

cjol merged commit 6393265 into main Oct 2, 2026
16 of 30 checks passed

cjol deleted the channels/03-core branch October 2, 2026 19:20

github-actions Bot mentioned this pull request Oct 2, 2026

Version Packages #2461

Merged

brandhaug mentioned this pull request Oct 10, 2026

chore(deps): bump agents from 0.26.0 to 0.27.0 brandhaug/b2b-saas-starter#669

Merged

		/** Recent events by key, each with the outcome repeats receive. */
		readonly #seen = new Map<string, Promise<void>>();

		const ending = await streams.status(responseId);
		return ending?.state === "errored" ? "interrupted" : "ended";

		@@ -1,4 +1,5 @@
		export * from "./channel";
		export * from "./conversations";

Conversation

cjol commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Public API Surface

Code Changes

Uh oh!

changeset-bot Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

devin-ai-integration Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devin-ai-integration Bot Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

agent-think Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 agents import sizes: 1 entry point changed, no growth

Uh oh!

pkg-pr-new Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cjol commented Oct 1, 2026 •

edited

Loading

changeset-bot Bot commented Oct 1, 2026 •

edited

Loading

devin-ai-integration Bot left a comment •

edited

Loading

devin-ai-integration Bot Oct 1, 2026 •

edited

Loading

devin-ai-integration Bot Oct 1, 2026 •

edited

Loading

devin-ai-integration Bot Oct 1, 2026 •

edited

Loading

devin-ai-integration Bot Oct 1, 2026 •

edited

Loading

agent-think Bot commented Oct 1, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 1, 2026 •

edited

Loading