feat(core)!: extract zod from @ag-ui/core, ship @ag-ui/core/schemas subpath#1637
Open
AlemTuzlak wants to merge 43 commits into
Open
feat(core)!: extract zod from @ag-ui/core, ship @ag-ui/core/schemas subpath#1637AlemTuzlak wants to merge 43 commits into
AlemTuzlak wants to merge 43 commits into
Conversation
…ests - Reject array inputs in defaultEventValidator (typeof [] === 'object' footgun) - Treat empty issues[] as success in fromStandardSchema (Standard Schema compliance) - Add tests for fromStandardSchema and array rejection
zod's .min(1) is a runtime-only check; it does not produce a non-empty tuple type at the inference level. The static type was too narrow. Adds direct equality assertions for both RunFinishedSuccessOutcome and RunFinishedInterruptOutcome to catch any future regression.
Replace schema.parse()-based factory helpers with plain object construction. Inline the three coercion behaviors previously supplied by Zod schemas: - TEXT_MESSAGE_START: role defaults to "assistant" when omitted - ACTIVITY_SNAPSHOT: replace defaults to true when omitted - RUN_FINISHED: outcome:null/undefined normalized to field omission Add explicit guard in createRunFinishedInterruptEvent to throw on empty interrupts array, preserving the .min(1) validation previously done by Zod.
…ument strip limitation
…interface BREAKING CHANGE: `@ag-ui/core` no longer exports any `*Schema` constants. zod is no longer used to define types. Consumers using runtime validation should use the `AgentValidator` interface or write their own schemas with the validation library of their choice.
…erance Replaces coverage from the deleted backwards-compatibility.test.ts: the protocol contract is that AG-UI events tolerate unknown future fields, and the new validator must continue to accept them.
The package no longer uses zod for type definitions, schema validation, or any other purpose. Consumers needing runtime schema validation should plug in their own AgentValidator implementation.
@ag-ui/core no longer exports *Schema constants. Three external consumers (adk-middleware, TypeScript SDK README, and core README example) now use type-only imports or locally-defined validation instead.
…r architecture The Event Schemas section described the deleted zod schemas. Replace with guidance for defaultEventValidator + Standard Schema customization. Also tighten the multimodal example to use import type for UserMessage.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Python Preview PackagesVersion
Install with uvAdd the TestPyPI index to your [[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = trueThen install the packages you need: # Core SDK
uv add 'ag-ui-protocol==0.0.0.dev1784161336' --index testpypi
# Integrations (each already depends on the matching ag-ui-protocol preview)
uv add 'ag-ui-langgraph==0.0.0.dev1784161336' --index testpypi
uv add 'ag-ui-crewai==0.0.0.dev1784161336' --index testpypi
# NOTE: ag-ui-agent-spec depends on pyagentspec (git-only, not on PyPI).
# You will need to install pyagentspec separately from its git repo.
uv add 'ag-ui-agent-spec==0.0.0.dev1784161336' --index testpypi
uv add 'ag_ui_adk==0.0.0.dev1784161336' --index testpypi
uv add 'ag_ui_strands==0.0.0.dev1784161336' --index testpypiInstall with pippip install \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
ag-ui-protocol==0.0.0.dev1784161336
Commit: ad18446 |
The *-static.ts files were a migration scaffold used to prove static types matched z.infer types via expectTypeOf assertions. After zod was removed, the scaffolding became dead-end indirection. Move the type definitions directly into types.ts / events.ts / capabilities.ts where they belong and delete the static files.
…tValidator - Schemas come back at a new opt-in subpath; zod becomes an optional peer dependency so consumers control the version (the original v3/v4 conflict fix). - defaultEventValidator removed; @ag-ui/client and @ag-ui/proto default to zodValidator from the subpath, preserving prior runtime-validation behavior. - adk-middleware reverts its local validator and imports AgentCapabilitiesSchema from @ag-ui/core/schemas. - BinaryInputContent runtime check rewritten as .refine() (loses precise error path; boolean check unchanged). - CHANGELOG and docs updated to reflect the actual final architecture.
- zodValidator uses Standard Schema (zod 3.24+); the peer range was too permissive (3.22.4 would crash at import). - Add types conditions to exports map so node16/nodenext module resolution can locate .d.ts files for both entries.
tombeckenham
added a commit
to TanStack/ai
that referenced
this pull request
Jun 10, 2026
…520) @ag-ui/core@0.0.x infers its public types from Zod 3 schemas and carries zod ^3.22 as a hard runtime dependency, dragging Zod 3 into every consumer's tree and type graph. Apps on Zod 4 (e.g. @hookform/resolvers@5) hit zod/v4/core version-mismatch errors (TS2769) when their lockfile resolves the resolver's zod/v4 import to the Zod 3 shim. @ag-ui/core@0.1.0 makes the main entry type-only with zero runtime deps and moves schemas to an opt-in /schemas subpath (zod ^3.24 || ^4 optional peer). This change: - bumps @ag-ui/core to ^0.1.0 - loads RunAgentInputSchema lazily from @ag-ui/core/schemas inside chatParamsFromRequestBody, typed against a local structural interface so zod never appears in this package's compilation or public .d.ts - declares zod (^3.24.0 || ^4.0.0) as an optional peer dependency — only server code calling chatParamsFromRequest* needs zod installed; calling without it rejects with an actionable AGUIError Verified against a packed build: a zod-4 + @hookform/resolvers@5 consumer gets exactly one zod in its tree and tsc --noEmit passes with skipLibCheck: false; a zod-free consumer imports @tanstack/ai fine. Blocked on the @ag-ui/core@0.1.0 npm release (ag-ui-protocol/ag-ui#1637, conflict resolution in ag-ui-protocol/ag-ui#1918). Lockfile to be regenerated once published. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4 tasks
…-core # Conflicts: # pnpm-lock.yaml # sdks/typescript/packages/core/package.json
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
The endpoint validation handler imported RunAgentInputSchema from the bare @ag-ui/core entry, which no longer exports *Schema constants after the 0.1.0 schema-subpath split. At runtime the symbol was undefined, so safeParse() threw and the endpoint returned 500 instead of 400/200 — breaking 10 endpoint-validation tests after merging main.
This was referenced Jun 26, 2026
This PR is scoped to the zod-extraction minor (0.1.0). The deprecated-event removals (THINKING, BinaryInputContent) are split into a stacked major PR.
AlemTuzlak
force-pushed
the
alem/extract-zod-from-core
branch
from
ff08448 to
47a2602
Compare
Brings the zod-extraction branch up to current main (206 commits) so #1637 is mergeable again. Only one semantic conflict, in core/src/events.ts. main's sole core change since this branch last merged main (Jun 24) was 2fa33a0 "fix(core): accept null parentMessageId on tool-call events", which edited the zod schemas that this branch relocated from events.ts to schemas.ts. Resolved so the fix is preserved rather than dropped: - events.ts: kept the branch's type-only interfaces (the extraction). - schemas.ts: ported the null-acceptance onto ToolCallStartEventSchema and ToolCallChunkEventSchema (.nullable().optional().transform(v => v ?? undefined)). Output type stays `string | undefined`; schema-type-equality still passes. - tool-call-events.test.ts (added by 2fa33a0): repointed schema imports to ../schemas and expressed the input-widening contract via z.input<typeof ToolCallStartEventSchema> (the branch's hand-written *Props type stays string | undefined by design). Verified: core 188, client 499, proto green; tsc --noEmit core; build of core/client/proto/encoder; publint --strict + attw --pack (root and /schemas subpath resolve on node10 / node16 CJS+ESM / bundler). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…surface #1637 makes @ag-ui/core type-only (zod schemas move to the @ag-ui/core/schemas subpath). Because @ag-ui/client does `export * from "@ag-ui/core"`, it transitively stopped re-exporting the schema values — breaking consumers that import `*Schema` / `EventSchemas` from @ag-ui/client: - integrations/mastra interrupt-bridge.test.ts: RunFinishedEventSchema.parse(...) threw "Cannot read properties of undefined (reading 'parse')" — caught by CI. - middlewares/a2a-middleware/src/index.ts: same import in source — a latent runtime `undefined`, not covered by a test. Both usages were added on main after #1637's last migration sweep, so the PR never saw them. Restore the pre-0.1.0 client surface by also re-exporting the schemas subpath. client already depends on zod, so this adds no new coupling and core stays zod-free. Safe as `export *`: core exports only non-Schema names, schemas exports only *Schema / EventSchemas — no collisions. Verified: nx test @ag-ui/{core,client,mastra,a2a-middleware} — core 188, client 499, mastra 300 (was 299 | 1 failed), a2a-middleware green; client builds with no ambiguous re-export. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@ag-ui/coreno longer depends on zod. Upstream consumers were repeatedly hitting v3/v4 dual-installation conflicts because core pinned zod 3.x as a hard runtime dep. This PR:*Schemaexports to a new opt-in subpath:@ag-ui/core/schemas.^3.24.0 || ^4.0.0— consumers pick exactly one zod version.@ag-ui/coreentry type-only (TypeScript types +EventTypeenum +AGUIError+ event factories). Zero runtime dependencies.@ag-ui/clientand@ag-ui/protoimportEventSchemasfrom@ag-ui/core/schemasand callEventSchemas.parse(...)directly, preserving prior runtime-validation behavior with no caller changes.@ag-ui/coreto0.1.0with a CHANGELOG entry.Migration tooling
docs/sdk/js/core/migration-0-1-0.mdx(journey format with decision tree, before/after diffs, FAQ).codemods/0.1.0-schemas-to-subpath.ts(repo root). Splits combined imports, redirects every*Schemaimport to the subpath, preservesimport typesemantics + per-specifier type modifiers, dedupes by(imported, local)so aliased duplicates survive, warns on namespace imports, idempotent. Run via:Breaking change
@ag-ui/coreno longer exports any*Schemaconstants from its main entry. The two existing internal consumers (adk-middleware, README example) have been migrated.Tool.parameters,RunAgentInput.state, andRunAgentInput.forwardedPropsare now optional (?: any) to match what zod'saddQuestionMarksinfers fromz.any()fields. Non-breaking widening (extra| undefinedallowed).Test plan
pnpm -C sdks/typescript/packages/core test— 182/182pnpm -C sdks/typescript/packages/proto test— 92/92pnpm -C sdks/typescript/packages/client test— 482/483 (1 pre-existing Windows-only ESM-loader failure onesm-interop.test.ts, unrelated)pnpm -C integrations/adk-middleware/typescript test— 8/8pnpm -C sdks/typescript build— clean across@ag-ui/core,@ag-ui/client,@ag-ui/proto,@ag-ui/encoder,@ag-ui/adk,@ag-ui/claude-agent-sdknode codemods/test.ts)Notable internal changes
BaseEventinterface gains[k: string]: unknownto match the runtime.passthrough()semantics that the priorz.infertypes provided. This restores compatibility with consumers (notablyclaude-agent-sdk) that pass extra fields likethreadIdon event constructors.BinaryInputContentSchemaruntime check moved fromsuperRefineto.refine()to work cleanly across both zod 3 and zod 4 majors.