Threads 7: Rename the thread controller

[FranciscoMoretti]

Summary

• rename the imperative controller from ThreadChat to Thread
• rename createThreadChat to createThread and ThreadChatOptions to ThreadInit
• make useThread({ thread }) match the ownership model introduced by the next PR

This is a behavior-free refactor that isolates terminology changes from the external-state architecture.

Summary by Sourcery

Rename the core thread controller and associated React hook interfaces to use the Thread terminology without changing behavior.

Enhancements:

• Rename the imperative thread controller from ThreadChat to Thread and adjust exports accordingly.
• Update useThread to accept a thread instance instead of chat, aligning the hook ownership model with external thread engines.
• Rename initialization types and factory helpers from ThreadChatOptions/createThreadChat to ThreadInit/createThread for clearer API semantics.

Documentation:

• Update the thread package architecture documentation to describe the engine as Thread instead of ThreadChat, including ownership and state descriptions.

Tests:

• Rename and update thread-related tests to use the new Thread terminology and validate the unchanged behavior of the refactored APIs.

---

Summary by cubic

Renamed the thread controller to Thread and updated the React hook to accept { thread }. Clarified useThread identity rules; no behavior changes.

• Refactors

  • ThreadChat -> Thread, createThreadChat -> createThread.
  • ThreadChatOptions -> ThreadInit.
  • Internal ThreadChatState -> ThreadRunState.
  • Updated exports, docs, and tests to new names.
  • Documented identity lifetime: the same Thread is retained; changing the external thread or a defined id replaces the controller (including tree and active runs).

• Migration

  • Instantiate new Thread() instead of new ThreadChat().
  • Use createThread(...) instead of createThreadChat(...).
  • Call useThread({ thread }) instead of useThread({ chat }).
  • Replace ThreadChatOptions with ThreadInit.

^{Written for commit 9b89d72. Summary will update on new commits.}

Summary by CodeRabbit

• Breaking Changes
  • Renamed the primary API from ThreadChat to Thread.
  • Renamed createThreadChat to createThread.
  • Renamed ThreadChatOptions to ThreadInit.
  • Updated useThread to accept a thread instance (replacing chat), with snapshot/status typings now aligning to Thread.
• Documentation
  • Refreshed architecture terminology and ownership boundaries to use Thread concepts.
• Tests
  • Updated smoke and unit tests to target the new Thread API.

Stack

1. Threads 7: Rename the thread controller #261 👈 current
2. Threads 8: Add externally owned thread state #262
3. Threads 10: Store ordered thread snapshots in ChatJS #240
4. Threads 11: Mount useThread in ChatJS #241
5. Threads 12: Add branch navigation and retry #242
6. Threads 13: Isolate branch stream lifecycles #243
7. Threads 14: Stream follow-up parallel responses #244
8. Threads 15: Add cancellable request gates #263
9. Threads 16: Gate first-message parallel runs #245
10. Threads 17: Stop newly provisioned thread runs #246
11. Threads 18: Show parallel response lifecycle states #247
12. Threads 19: Publish installable thread sources #248
13. Threads 20: Add the thread playground model #249
14. Threads 21: Add the interactive thread playground #250
15. Threads 22: Publish the threads product page #251
16. Threads 23: Add the value-first package guide #252
17. Threads 24: Document ChatJS threaded behavior #253
18. Threads 25: Prepare the thread package release #254

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
chat-js-docs	Ready	Preview, Comment	Jul 27, 2026 5:52pm
chat-js-site	Ready	Preview, Comment	Jul 27, 2026 5:52pm
sparka	Ready	Preview, Comment	Jul 27, 2026 5:52pm

[sourcery-ai]

Reviewer's Guide

Refactors the thread package to rename the core imperative controller from ThreadChat to Thread, align types and factory functions with the new name, and update useThread’s ownership model and tests/documentation accordingly without changing runtime behavior.

File-Level Changes

Change	Details	Files
Rename the imperative thread controller from ThreadChat to Thread and update its construction API.	Rename ThreadChat class to Thread while preserving its interface and behavior. Rename createThreadChat factory to createThread and adjust implementation to construct Thread. Update internal state class name from ThreadChatState to ThreadRunState to match terminology. Change type ThreadChatOptions to ThreadInit and update constructor and field typings.	packages/thread/src/thread-chat.ts packages/thread/src/thread.ts packages/thread/src/types.ts packages/thread/src/ai-sdk-run-chat.ts packages/thread/src/index.ts
Update useThread hook to use the new Thread terminology and external ownership model.	Replace imports and usages of ThreadChat with Thread in the hook. Rename ThreadChatOptions references to ThreadInit in hook options and callback types. Rename helper functions and option discriminators from chat to thread (e.g., hasSuppliedThread, useThreadSnapshot, useThreadField). Adjust external ownership so useThread accepts a supplied Thread instance via the thread option instead of chat.	packages/thread/src/use-thread.ts
Align documentation with new Thread naming and ownership semantics.	Update ARCHITECTURE.md to describe Thread instead of ThreadChat as the observable chat engine. Adapt examples to use createThread and Thread, and clarify hook ownership with threadRef and external Thread instances. Rename sections and narrative references from ThreadChat State/identity/concurrency/etc. to Thread. Fix minor wording around internal state class (ThreadRunState) and transport behavior to use new names.	packages/thread/ARCHITECTURE.md
Rename tests and type-check helpers to target Thread instead of ThreadChat and validate the new API surface.	Rename thread-chat.test.ts to thread.test.ts and update all usages and describe blocks from ThreadChat to Thread. Update use-thread tests to construct and pass Thread instances via the thread option and adjust test descriptions accordingly. Change type-level tests to use external Thread instances and updated option names. Ensure package smoke test imports Thread/createThread from the public API and asserts no legacy ThreadChat symbol is present in the built React entrypoint. Update ai-sdk-run-chat tests to reflect the renamed ThreadRunState and thread id label.	packages/thread/test/thread-chat.test.ts packages/thread/test/thread.test.ts packages/thread/test/use-thread.test.ts packages/thread/test/use-thread-types.ts packages/thread/test/package-smoke.test.ts packages/thread/test/ai-sdk-run-chat.test.ts

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR renames the thread runtime from ThreadChat to Thread, replaces ThreadChatOptions with ThreadInit, updates useThread to manage Thread instances, renames internal run state, refreshes exports and architecture documentation, and updates related tests.

Changes

Thread API migration

Layer / File(s)	Summary
Thread runtime contracts and exports packages/thread/src/types.ts, packages/thread/src/thread.ts, packages/thread/src/index.ts, packages/thread/src/ai-sdk-run-chat.ts	The public class, factory, initialization type, exports, host contract, and internal run state use Thread and ThreadInit terminology.
useThread ownership and subscriptions packages/thread/src/use-thread.ts	useThread accepts external Thread instances or ThreadInit options, subscribes to Thread snapshots, and routes helpers through the thread instance.
Thread and hook compatibility validation packages/thread/test/*	Tests now construct Thread and validate exports, external-thread hook usage, resume behavior, routing, concurrency, and existing run scenarios.
Architecture ownership documentation packages/thread/ARCHITECTURE.md	Architecture terminology describes Thread ownership, identity, subscriptions, runs, transport selection, restoration, tool routing, and concurrency.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• FranciscoMoretti/chat-js#220: Introduced the earlier ThreadChat runtime and option exports that this PR renames.
• FranciscoMoretti/chat-js#239: Introduced the useThread hook surface that this PR updates to use Thread.
• FranciscoMoretti/chat-js#236: Added the AI SDK run adapter internals whose option and state wiring are renamed here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main change: renaming the thread controller and related API surface.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/threads-v2-07-controller-rename

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[greptile-apps]

Greptile Summary

Renames the thread controller API without changing its runtime behavior.

• Replaces ThreadChat, createThreadChat, and ThreadChatOptions with Thread, createThread, and ThreadInit.
• Updates useThread to accept an external controller through { thread }.
• Aligns internal names, tests, package exports, and architecture documentation with the new terminology.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/thread/src/thread.ts	Renames the controller, initialization type, and factory while preserving the existing implementation.
packages/thread/src/use-thread.ts	Renames the external controller option and consistently updates subscriptions, helpers, and controller selection.
packages/thread/src/index.ts	Updates the package's public runtime and type exports to the renamed API.
packages/thread/src/types.ts	Renames the public controller initialization type without changing its shape.
packages/thread/src/ai-sdk-run-chat.ts	Aligns internal host types and state terminology with the renamed controller API.

_{Reviews (2): Last reviewed commit: "docs(thread): clarify controller identit..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/thread/ARCHITECTURE.md`:
- Around line 113-115: Update the Thread lifetime statement in the useThread
documentation to qualify stability by its identity inputs: the retained instance
remains unchanged only while options.id and any supplied external thread stay
the same. State that changing either input can replace the Thread, including its
tree and active runs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a675807d-969a-4145-8ed7-90a8624e79f5

📥 Commits

Reviewing files that changed from the base of the PR and between 3116998 and d73a83e.

📒 Files selected for processing (11)

• packages/thread/ARCHITECTURE.md
• packages/thread/src/ai-sdk-run-chat.ts
• packages/thread/src/index.ts
• packages/thread/src/thread.ts
• packages/thread/src/types.ts
• packages/thread/src/use-thread.ts
• packages/thread/test/ai-sdk-run-chat.test.ts
• packages/thread/test/package-smoke.test.ts
• packages/thread/test/thread.test.ts
• packages/thread/test/use-thread-types.ts
• packages/thread/test/use-thread.test.ts

[cubic-dev-ai]

All reported issues were addressed across 11 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>