Skip to content

Add compile-time errors for AI SDK v5 patterns and docs#225

Merged
sethconvex merged 4 commits intomainfrom
v5-compat-errors-and-docs
Feb 20, 2026
Merged

Add compile-time errors for AI SDK v5 patterns and docs#225
sethconvex merged 4 commits intomainfrom
v5-compat-errors-and-docs

Conversation

@sethconvex
Copy link
Contributor

@sethconvex sethconvex commented Feb 11, 2026

Summary

  • Add TypeScript compile-time errors when users accidentally use AI SDK v5 patterns with v6:
    • createTool({ args: ... }) → helpful error pointing to inputSchema
    • createTool({ handler: ... }) → helpful error pointing to execute
    • languageModel with v2 spec → error about needing v3
  • Include MIGRATION.md in npm package with step-by-step upgrade instructions
  • Enhance CLAUDE.md with comprehensive AI SDK v6 upgrade guidance
  • Remove TODO comment in deltas.ts (partial tool calls now handled)

Cherry-picked from #217 (commits a81e3e3, 5919965, 74ce289, 6f7009d).

Test plan

  • npm run build passes
  • npm run typecheck passes
  • Using v5 patterns shows helpful compile-time errors

🤖 Generated with Claude Code

@coderabbitai
Copy link

coderabbitai bot commented Feb 11, 2026

Warning

Rate limit exceeded

@sethconvex has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 14 minutes and 3 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch v5-compat-errors-and-docs

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

Comment @coderabbitai help to get the list of available commands and usage tips.

@sethconvex sethconvex changed the title Add compile-time errors for AI SDK v5 patterns Add compile-time errors for AI SDK v5 patterns and docs Feb 11, 2026
@sethconvex sethconvex force-pushed the fix-atomic-stream-finish branch from 3122e0e to fa9cadc Compare February 11, 2026 01:14
@sethconvex sethconvex force-pushed the v5-compat-errors-and-docs branch from 5283806 to f5a0659 Compare February 11, 2026 01:14
@pkg-pr-new
Copy link

pkg-pr-new bot commented Feb 11, 2026

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent@225

commit: b67e265

@sethconvex sethconvex force-pushed the fix-atomic-stream-finish branch from fa9cadc to 462e158 Compare February 20, 2026 06:34
@sethconvex sethconvex force-pushed the v5-compat-errors-and-docs branch from f5a0659 to 251d0c7 Compare February 20, 2026 06:35
@sethconvex sethconvex force-pushed the fix-atomic-stream-finish branch from 462e158 to cf75fc1 Compare February 20, 2026 06:51
@sethconvex sethconvex force-pushed the v5-compat-errors-and-docs branch from 251d0c7 to bdbdde1 Compare February 20, 2026 06:51
@sethconvex sethconvex force-pushed the fix-atomic-stream-finish branch from cf75fc1 to b6894b8 Compare February 20, 2026 06:59
@sethconvex sethconvex force-pushed the v5-compat-errors-and-docs branch 2 times, most recently from 269bb8b to 93fec7b Compare February 20, 2026 07:12
@sethconvex sethconvex force-pushed the fix-atomic-stream-finish branch 2 times, most recently from 34d83da to 15c0ddf Compare February 20, 2026 07:21
@sethconvex sethconvex force-pushed the v5-compat-errors-and-docs branch from 93fec7b to f2b2d4a Compare February 20, 2026 07:22
@sethconvex sethconvex marked this pull request as ready for review February 20, 2026 07:25
Copy link
Contributor Author

sethconvex commented Feb 20, 2026

Merge activity

  • Feb 20, 7:25 AM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Feb 20, 7:28 AM UTC: Graphite rebased this pull request as part of a merge.
  • Feb 20, 7:29 AM UTC: @sethconvex merged this pull request with Graphite.

@sethconvex sethconvex changed the base branch from fix-atomic-stream-finish to graphite-base/225 February 20, 2026 07:26
@sethconvex sethconvex changed the base branch from graphite-base/225 to main February 20, 2026 07:27
sethconvex and others added 4 commits February 20, 2026 07:28
When users upgrade to v0.6.0 with old AI SDK v5 dependencies, TypeScript
now shows helpful error messages pointing to the migration guide:

- languageModel: Shows error if model has specificationVersion "v2" instead of "v3"
- createTool args: Shows "⚠️ 'args' was removed... Rename to 'inputSchema'"
- createTool handler: Shows "⚠️ 'handler' was removed... Rename to 'execute'"

This helps users (and AI assistants) understand what needs to change
before they try to run the code.

Also adds scripts/check-upgrade.js CLI tool for scanning codebases.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add MIGRATION.md to package.json files array so it ships with npm package
- Update compile-time error messages to point to local MIGRATION.md
- Enhance CLAUDE.md with:
  - AI SDK v6 requirement note upfront
  - Compatible sibling packages (@convex-dev/rag@^0.7.0)
  - Type import changes (LanguageModelV2 → V3, EmbeddingModel → EmbeddingModelV3)
  - generateObject mode: "json" removal documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add tool approval flow to Key Patterns architecture section
- Replace upgrade section with detailed AI-friendly guidance including:
  - Detection patterns for v5 code (parameters, handler, textEmbeddingModel)
  - Dependency update commands
  - Before/after transformation examples for tools, embeddings, step limits
  - Verification steps and common issues
  - New v6 features (tool approval, reasoning streaming, token details)
- Remove outdated TODO comment in deltas.ts (partial tool calls now handled)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@sethconvex sethconvex force-pushed the v5-compat-errors-and-docs branch from f2b2d4a to b67e265 Compare February 20, 2026 07:28
@sethconvex sethconvex merged commit a4f2a10 into main Feb 20, 2026
4 checks passed
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.

2 participants