Skip to content

docs(design): the chat turn core RFC after the stack - #2903

Open
mattzcarey wants to merge 7 commits into
refactor/turn-core-review-fixesfrom
refactor/turn-core-rfc
Open

mattzcarey wants to merge 7 commits into
refactor/turn-core-review-fixesfrom
refactor/turn-core-rfc

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Brings design/rfc-chat-turn-core.md and design/chat-shared-layer.md up to date with the turn-core stack (#2873, #2870, #2876, #2881, #2874, #2872, #2918 and the review fixes). Docs only.

The RFC still described Phase 1 and part of Phase 2, and five PRs had each numbered their differences from D13. It now has:

  • Phases 2 and 4 as implemented, with the before-turn repair and the request context that turned up on the way.
  • One differences table, D1 to D100, with no collisions. D55 to D58 are what the end-to-end probe found, D59 to D80 what the reviews, the probes and mutation testing found, D81 to D86 durable admission of queued requests (feat(chat): requests waiting in the queue survive an isolate reset #2918), D87 to D93 the second review pass, and D94 to D100 the third.
  • "Known gaps": what is still wrong after the stack, each with the row it belongs to.
  • "Still different": what each class still does itself, including Retry-After for AIChatAgent.
  • "What the providers do": the probe results that back the transcript rules.

chat-shared-layer.md lists the new core files and what each owns. test-coverage-matrix.md gets a row for the turn core.

pnpm run check's format step passes. No code changes, so no tests ran.


Devin Review

@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 4047c4a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 1 potential issue.

Devin Review

Comment thread design/rfc-chat-turn-core.md Outdated
# RFC: one turn core for `AIChatAgent` and `Think`

Status: accepted. Phase 1 and the client-request part of Phase 2 are implemented. The rest of Phase 2 and Phases 3 to 5 are the plan.
Status: accepted. Phases 1, 2 and 4 are implemented, with the before-turn repair and the request context that turned up on the way. Phases 3 and 5 are the plan.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Accepted decision snapshot replaced by progress

The accepted ChatTurns RFC now folds later implementation outcomes into its original decision record. The RFC workflow reserves post-decision updates for living design documents. Contributors lose the distinction between accepted choices and subsequent implementation changes.

Learn more

The base revision already marks this RFC accepted. This update changes its status narrative, replaces the differences table, and revises the final decision to incorporate work completed afterward. The RFC workflow separates immutable decisions from living implementation records.

Example: D11 and D12 were recorded as unresolved follow-up work; the replacement table presents their later implementation outcomes inside the same accepted snapshot.

Recommended fix: Preserve the accepted RFC and put the consolidated implementation status, differences table, remaining gaps, and verification details in the existing shared-layer design record. Link that living record to the original RFC for historical rationale.

Devin Review


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

@mattzcarey
mattzcarey added this pull request to stack #2869 November 18, 2026 15:07
@mattzcarey
mattzcarey force-pushed the refactor/turn-core-rfc branch 2 times, most recently from 25d3191 to 0996da1 Compare November 18, 2026 22:29
@mattzcarey
mattzcarey force-pushed the refactor/turn-core-rfc branch 2 times, most recently from 1127989 to 66b0289 Compare November 20, 2026 10:52
@pkg-pr-new

pkg-pr-new Bot commented Nov 20, 2026

Copy link
Copy Markdown

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: 66b0289

@agent-think

agent-think Bot commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

🔴 agents import sizes: 1 entry point over threshold

Entry point Exports Largest gzip change Size now
🔴 agents/chat 6 resized, 8 new up to +1 KiB (+10.45%) 11.1 KiB
Changed exports (14)
Import Gzip change Size now
🔴 agents/chat#ChatTurns +1 KiB (+10.45%) 11.1 KiB
🟡 agents/chat#ChatRecoveryEngine +664 B (+6.81%) 10.2 KiB
🟡 agents/chat#AgentToolRuns +301 B (+4.72%) 6.5 KiB
🟡 agents/chat#ChatTurnFibers +162 B (+4.79%) 3.5 KiB
🟡 agents/chat#broadcastTransition +113 B (+3.12%) 3.6 KiB
🆕 agents/chat#ChatAdmissions — 3.2 KiB
🆕 agents/chat#createChatAdmissionStore — 3.1 KiB
🆕 agents/chat#chatRecoveryNames — 3 KiB
🆕 agents/chat#takeAtFirstContent — 2.7 KiB
🆕 agents/chat#ChatRecoverySupersededError — 2.6 KiB
🆕 agents/chat#chunkCarriesContent — 2.6 KiB
🆕 agents/chat#CHAT_ADMISSIONS_TABLE — 2.6 KiB
🆕 agents/chat#CHAT_ADMISSION_TTL_MS — 2.6 KiB
🟢 agents/chat#runContinuationTurn -142 B (-3.37%) 4 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 7314bb0d → 66b02896 · workflow run · reported by agent-think[bot]

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 3 new potential issues.

Devin Review

Comment thread packages/agents/src/chat/admissions.ts Resolved
Comment thread packages/agents/src/chat/chat-turns.ts Resolved
Comment thread packages/agents/src/chat/chat-turns.ts Resolved
@mattzcarey
mattzcarey removed this pull request from stack #2869 November 20, 2026 12:09
@mattzcarey
mattzcarey changed the base branch from refactor/turn-core-repair to refactor/turn-core-review-fixes November 20, 2026 12:10
@mattzcarey
mattzcarey changed the base branch from refactor/turn-core-review-fixes to main November 20, 2026 12:10
@mattzcarey
mattzcarey changed the base branch from main to refactor/turn-core-review-fixes November 20, 2026 12:12
@mattzcarey
mattzcarey added this pull request to stack #2923 November 20, 2026 12:12
@mattzcarey
mattzcarey force-pushed the refactor/turn-core-rfc branch from 66b0289 to 4047c4a Compare November 20, 2026 13:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant