Support StandardSchema + StandardJSONSchema for result instead of only Valibot

[kerkzhan]

Problem

Internally, Flue calls toJsonSchema from Valibot's library (@valibot/to-json-schema). This forces the consumer to install Valibot as a dependency in their project even if they have an existing validation lib.

Suggestion

I think Flue should allow users to use any validation library they want by implementing the StandardJSONSchema & StandardSchema interface for the result object instead.

Benefits

• flue/sdk reduces 2 runtime deps.
• Allows users to use any lib that uses Standard Schema / Standard JSON Schema. They can reuse their existing validation lib, no extra dependency.

Breaking Changes

• Existing Valibot users will encounter errors on upgrade. They need to install @valibot/to-json-schema in their own project and explicitly call toStandardJsonSchema in their agent.

---

If this is a welcome change, I'd be happy to look into it and create a PR.

PS: Loving Flue so far! Super clean abstractions, I think a framework for building agents is exactly what is needed now.

[stainlu]

i like the Standard Schema direction, but i’d avoid making this a breaking migration if possible.

maybe result can accept:

• current Valibot schemas
• Standard Schema
• Standard JSON Schema

then Flue normalizes internally before result extraction. that keeps existing users working while opening the door for zod/arktype/effect/etc.

the important thing imo is not removing Valibot immediately, but making result a framework boundary instead of a Valibot-only boundary.

[FredKSchott]

In your suggestion, are you solving for how types are read from the passed schema, and then transmitted to result? How does result get proper types if we are calling toStandardJsonSchema() outside of the agent, and passing JSON Schema to the skill call?

Curious to see an API that would work if you think you've got one.

The context is that:

• Valibot supports serializing to JSON schema as a built-in: https://valibot.dev/guides/json-schema/
• Zod doesn't support this. Don't know about all of the others but I don't think Standard Schema does out of the box either.
• The problem is that you need to be able to pass the TypeScript schema object (ex: valibot schema) to get the rich types, but then you need to handle it internally, meaning calling valibot's toJsonSchema() internally inside of Flue.

FWIW I don't mind saying "Flue type-enforced skill/prompt calls requires Valibot". This is fairly common for a solution to pick a single validation schema library if it can't find a way to make it pluggable. But I'd ofc love it to be pluggable if it doesn't harm the current DX.

[kerkzhan]

@stainlu Yeah it makes sense to maintain compat for now since adoption rate is growing and we don't want to kill the momentum.

@FredKSchott Regarding Zod, I believe as of version 4.2, the schema output of zod satisfies StandardJsonSchema out the box.

The DX wouldn't change at all if we opt for compat like what @stainlu suggested:

Today

const r = await session.prompt('...', {
  result: v.object({ translation: v.string() }),
});

Option 1: Compat - DX unchanged

// Valibot - Flue internally normalizes for Valibot, see Flue internals section
const r = await session.prompt('...', {
  result: v.object({ translation: v.string() }),
});

// Zod 4.2 already satisfies the Standard interface
const r = await session.prompt('...', {
  result: z.object({ translation: z.string() }),
});

Option 2: No compat (breaking change Valibot only)

// Zod, ArkType (identical to Option 1)
const r = await session.prompt('...', {
  result: z.object({ translation: z.string() }),
});

// Valibot, Zod Mini, Zod 3 - user wraps once
// (helper usually shipped with the lib or a community package)
const r = await session.prompt('...', {
  result: toStandardJsonSchema(v.object({ translation: v.string() })),
});

Flue internals

Internally Flue would do something like this for Option 1 (Compat):

const std = schema['~standard'];

// Zod v4+, ArkType
if (typeof std.jsonSchema?.input === 'function') {
  return std.jsonSchema.input({ target: 'draft-07' });
}

// Compat: auto-wrap bare Valibot schemas
if (std.vendor === 'valibot') {
  const { toStandardJsonSchema } = await import('@valibot/to-json-schema');
  return toStandardJsonSchema(schema)['~standard'].jsonSchema.input({ target: 'draft-07' });
}

To re-iterate, the DX should remain exactly the same if we opt for Option 1 (Compat). Just need an extra if check for Valibot.

As for the types, I haven't dug in the codebase too deeply, but at first glance we'd just do a quick replace of v.InferOutput<S> with StandardSchemaV1.InferOutput<S> and so on so forth for other Valibot types.

What do you think?

[stainlu]

yeah i think @kerkzhan's Option 1 is the right direction.

i checked the Flue path a bit more. one thing i would add: this probably should not be only a quick type replacement, because current result is doing a few Valibot-specific things:

• v.InferOutput<S> for return type
• toJsonSchema(schema) for prompt instructions
• v.safeParse(schema, value) for validation
• schema.type to decide whether to JSON.parse() the result block

so imo the useful internal primitive is still a normalized result codec:

type NormalizedResult<T> = {
  jsonSchema: Record<string, unknown>;
  parse(value: unknown): Promise<T> | T;
};

then normalizeResult(result) handles:

1. Standard Schema + Standard JSON Schema: use ~standard.validate() + ~standard.jsonSchema.input({ target: "draft-07" })
2. bare Valibot compat: wrap with toStandardJsonSchema() or keep the existing toJsonSchema() path
3. later escape hatch: explicit { jsonSchema, parse }

that keeps the public DX simple:

result: v.object({ ... })
result: z.object({ ... })

but keeps Flue internals honest.

small codebase-specific thing: once result is not Valibot-only, parsing the extracted block should probably key off the normalized JSON Schema / result codec, not schema.type. otherwise Zod/ArkType/etc won't have the same path, and primitives/transforms get weird.

so yes to compat, but i would make the PR a normalization-layer PR first. then adapters become small and the current Valibot DX remains untouched.

[kerkzhan]

Thanks for opening the PR @stainlu , was going to get to it once I got home from work but you beat me to it hahah

I left some comments on the PR but they are mostly non-blocking.

Standard Schema + Standard JSON Schema: use ~standard.validate() + ~standard.jsonSchema.input({ target: "draft-07" })
bare Valibot compat: wrap with toStandardJsonSchema() or keep the existing toJsonSchema() path

Yeap that sounds good. I think either way is fine for the Valibot compat, depends on how much API surface we want to modify.

later escape hatch: explicit { jsonSchema, parse }

Tbh, I'm not convinced and would push back a little on this. I think being StandardJSONSchema compliant is the perfect balance of pluggable and strict. Flue should be pluggable enough that any well supported schema lib works but strict enough that we don't support arbitrary userland code. Flue is meant to be a framework after all.

I'm concerned about users passing a jsonSchema that doesn't match what their parse method validates against. I'm not sure how we can enforce that without some insane Typescript gymnastics.