Skip to content

feat: support Standard Schema tool validators - #793

Open
LukasParke wants to merge 5 commits into
mainfrom
agent/standard-schema-support
Open

feat: support Standard Schema tool validators#793
LukasParke wants to merge 5 commits into
mainfrom
agent/standard-schema-support

Conversation

@LukasParke

@LukasParke LukasParke commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

What changed

  • accept any Standard Schema v1 validator for tool inputSchema, outputSchema, and eventSchema
  • infer validator input/output types with StandardSchemaV1.InferInput and InferOutput, while preserving the existing Zod inference and synchronous validation overloads
  • validate non-Zod schemas through schema['~standard'].validate(...), including asynchronous validators and normalized Standard Schema issues
  • generate provider JSON Schema through Zod, the Standard JSON Schema v1 trait, or explicit inputJsonSchema
  • preserve recursive stripping of ~-prefixed JSON Schema metadata
  • document and demonstrate Valibot usage

Why

The tool system was hard-wired to Zod even though Valibot, ArkType, Effect Schema, and other validators expose the shared Standard Schema v1 interface. Supporting that interface removes validator lock-in while keeping existing Zod tools unchanged.

Design decisions

JSON Schema

Provider JSON Schema follows a three-tier chain:

  1. Zod fast path: Zod schemas continue through z4.toJSONSchema(..., { target: 'draft-7' }), including Zod versions that predate the companion trait.
  2. Standard JSON Schema v1: non-Zod schemas implementing ~standard.jsonSchema.input convert with the draft-07 target. Converter failures fall through to the explicit fallback.
  3. Explicit inputJsonSchema: callers can provide the wire schema directly. This is required when neither automatic path applies and overrides the Standard JSON Schema trait when supplied.

The Standard JSON Schema trait is supported by Zod 4.2+, ArkType 2.1.28+, Zod Mini, VineJS, and Sury. Valibot adds it with toStandardJsonSchema() from @valibot/to-json-schema.

Only input schemas need provider JSON Schema because output and event schemas are local runtime validators. Every generated or explicit schema is sanitized before being sent downstream.

Compatibility

  • Zod remains a direct dependency and the preferred fast path.
  • Existing Zod tool() definitions need no changes.
  • Existing validateToolInput / validateToolOutput calls with Zod remain synchronous and continue throwing ZodError.
  • Context schemas remain Zod-only; this PR is limited to tool input/output/event schemas.

Test coverage

  • Zod conversion and synchronous validation regression coverage
  • Valibot type inference and regular tool input/output validation
  • normalized Standard Schema issue paths and readable error messages
  • asynchronous Standard Schema validation
  • Standard JSON Schema trait conversion through Valibot's toStandardJsonSchema()
  • explicit JSON Schema fallback when trait conversion throws
  • explicit inputJsonSchema override precedence
  • JSON Schema ~ metadata sanitization
  • generator event/output validation
  • missing conversion strategy error

Verification

  • pnpm build
  • pnpm typecheck
  • pnpm lint
  • pnpm test — 201 tests passed, type errors: 0
  • pnpm test:e2e attempted during the initial implementation; 3 model-list tests passed and 22 API-backed tests failed because the configured OpenRouter credential returned 401 User not found

@LukasParke
LukasParke marked this pull request as ready for review August 11, 2026 23:02

@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: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

Open in Devin Review

- convertToolsToAPIFormat: check inputJsonSchema before the Zod fast path
  so the explicit escape hatch always wins
- StandardSchemaError: stringify symbol path segments so JSON.stringify
  and formatToolExecutionError no longer crash or emit null paths
- tool<TShared>() overload: require inputJsonSchema for plain Standard
  Schema v1 validators via a non-inferred union config (explicit type
  arguments disable inference for remaining type parameters)

Add regression tests for all three.
devin-ai-integration[bot]

This comment was marked as resolved.

InferToolOutput matched a required outputSchema property, but regular
and manual tools declare it optional, so their result types collapsed
to unknown (Devin Review finding on PR #793). Match the property as
optional and filter non-schema values instead.

Add tests/unit/tool-types.test-d.ts: vitest typecheck only covers
*.test-d.ts files, so the expectTypeOf assertions in .test.ts files
were never typechecked.
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