chore(ai-sdk): support AI SDK v7 and test the full peer range

[StuBehan]

Carries @ybidois's #378 forward with the fixes needed to get it green, plus CI to keep the widened range honest. Their commits are preserved as-is; supersedes #378, which can be closed when this merges.

What #378 does

Widens the optional ai peer from >=5.0.108 <7.0.0 to >=5.0.108 <8.0.0 so consumers can use AI SDK v7, and replaces the stale maxSteps in the README/example with stopWhen: stepCountIs(...). That doc fix is worth having on its own — maxSteps was removed in AI SDK v5, so the snippet was broken across the entire existing peer range.

What this PR adds on top

1. README indentation — a code fence had moved from tabs to spaces, which failed lint:oxfmt and was the only thing making #378 red.

2. Reverted the src/tool.ts change.#378 added a second _executionOptions: unknown parameter to the execute implementation to satisfy v7's ToolExecutionOptions. It isn't needed — a 1-arg function is still assignable to v7's 2-arg ToolExecuteFunction, and the suite type-checks clean against ai@7.0.47 without it. With this reverted, this PR contains zero production-code change, which is what the compatibility claim should imply.

3. Made the test call sites version-agnostic. This is the substantive one. #378 added context: undefined to the two direct execute calls in src/tool.test.ts, which made the suite type-check only against v7:

ai	#378	this PR
5.0.108	2 type errors	pass
6.0.7	2 type errors	pass
7.0.47	pass	pass

The two shapes are mutually exclusive across majors:

• v5/v6 — ToolCallOptions has no context, so the excess-property check rejects the object literal.
• v7 — context is required on ToolExecutionOptions<CONTEXT>, andTool became a union (FunctionTool | DynamicTool | ProviderDefinedTool | ProviderExecutedTool). Because it's a union, overload resolution collapses and the error surfaces on the args line rather than the options line, as Argument of type '{ id: string; }' is not assignable to parameter of type 'never'.

So a directly-typed call site can only ever satisfy one major. The tests now go through an executeAISDKTool helper that calls execute via a plain signature, which holds across all three.

Worth knowing for the consumer-facing side: AISDKToolDefinition is exported publicly as Tool & { execution?: ToolExecution }, so under v7 it becomes a union too, and anyone calling tool.execute?.(args, opts) directly hits the same collapse. The tests were the canary, not a special case.

4. CI over the rest of the range.build-and-test only ever proves whatever the dev catalog pins, so before this the "v5–v7" claim had nothing behind it. New ai-peer-range job runs the suite (including the vitest typecheck) against the lower half of the range. Verified it actually bites: re-running the v5 leg against #378's original call sites fails with exit 1 and 2 type errors.

Verification

Full suite plus typecheck against each major, using the repo's own TypeScript 5.9.3:

ai	result
5.0.108	627 passed, no type errors
6.0.7	627 passed, no type errors
7.0.47 (catalog)	642 passed, no type errors (full pnpm test)

Also green: pnpm build, publint (no issues), oxfmt --check on every changed file.

Separately confirmed against all three majors: stepCountIs is exported by v5/v6/v7 (v7 aliases it to isStepCount), JSONSchema7 is still exported by ai, and ai@7's engines really is >=22, so the Node 22+ note is accurate. Keeping engines.node at >=20.19.6 is right, since ai is an optional peer.

Known limitation

The matrix pins exact versions rather than using ^5/^6. Newer patches in both lines resolve transitive packages that this repo's trustPolicy: no-downgrade rejects — ai@5.0.228 and ai@6.0.246 both fail to install on undici@5.29.0. Ranged matrix entries would therefore fail CI for supply-chain-policy reasons unrelated to the code under test. The tradeoff is that the matrix won't catch a break introduced in a newer v5/v6 patch. Loosening trustPolicyExclude to allow ranges felt like the wrong call to smuggle into a compatibility PR; happy to do it separately if we'd rather have the coverage.

Two smaller notes, neither addressed here:

• examples/package.json uses ai: catalog:peer, so the examples workspace floats to the newest v7 while the root pins ^7.0.47.
• typescript reaches node_modules/.bin only as a transitive dep. If that ever stops being hoisted, vitest's typecheck fails to spawn tsc — it exits non-zero, so it won't pass silently, but the message (spawn tsc ENOENT next to "Type Errors: no errors") is confusing enough to be worth knowing.

---

Summary by cubic

Expanded the optional ai peer to >=5.0.108 <8.0.0 to support AI SDK v7 and updated examples to use stopWhen: stepCountIs(...). Added CI to cover v5–v7 and a type-level check to ensure toAISDK() tools are valid for generateText; no production code changes.

• Dependencies

  • Updated ai peer to >=5.0.108 <8.0.0 (v7 requires Node.js 22+).
  • Dev catalog now uses ai@7.0.47 and @ai-sdk/openai@4.0.27.

• Refactors

  • Added ai-peer-range CI job to run type-checked tests on ai@5.0.108, ai@6.0.7, and ai@7.0.0; asserts the resolved ai version and installs with --filter ..
  • Made tests version-agnostic with executeAISDKTool; added a d.ts assertion that toAISDK() output is accepted as generateText tools across v5–v7; updated docs/examples to stopWhen: stepCountIs(3), noted v5–v7 support, and that ToolLoopAgent needs v6+.`

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/StackOneHQ/stackone-ai-node/@stackone/ai@379

commit: a59349c

[Copilot]

Pull request overview

Updates the package to officially support Vercel AI SDK v7 within the optional ai peer range, while keeping the test suite type-checking and running cleanly across v5/v6/v7 and adding CI coverage for the widened peer range.

Changes:

• Widen ai optional peer range to >=5.0.108 <8.0.0 and update dev catalog/lockfile to ai@7.0.47 and @ai-sdk/openai@4.0.27.
• Make direct AI SDK tool execute calls in tests version-agnostic via an executeAISDKTool helper to avoid cross-major type incompatibilities.
• Update docs/examples to use stopWhen: stepCountIs(...) and document the Node.js 22+ requirement for AI SDK v7; add an ai-peer-range CI job to validate lower majors.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/tool.test.ts	Adds an untyped execution helper and routes direct execute calls through it to type-check across AI SDK majors.
README.md	Fixes AI SDK example snippet (stopWhen: stepCountIs(...)) and notes v5–v7 support + Node 22+ for v7.
pnpm-workspace.yaml	Updates dev catalog pins to AI SDK v7 and widens the optional peer range for ai.
pnpm-lock.yaml	Refreshes lockfile to reflect updated AI SDK / provider dependencies.
examples/README.md	Notes AI SDK v5–v7 compatibility and Node 22+ requirement for v7 in the example description.
examples/ai-sdk-integration.ts	Updates header comment to reflect v5–v7 compatibility and stepCountIs availability/aliasing.
.github/workflows/ci.yaml	Adds ai-peer-range matrix job to run tests/typecheck against pinned v5/v6 versions.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

All reported issues were addressed across 7 files

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

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

<sub>Requires human review: Widening the public ai peer range to v7 is a compatibility-contract decision, and the PR admits the exported AISDKToolDefinition.execute type still collapses under v7; the tests dodge that with a cast rather than proving the public type works. A maintainer should sign off on claiming v7 support.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: Widening the public ai peer range to include v7 is a consumer-facing compatibility commitment and expands the supported audience; a human should approve that product/contract decision even though tests and CI verify the change.

Re-trigger cubic</sub>

[ybidois]

Thanks again @StuBehan! Any timeframe for the change to be released on NPM? 🙌