@sebastiantuyu/agest 0.3.3-next.8 → 0.3.3-next.9

package/README.md

@@ -111,6 +111,7 @@ scene("Plan a trip to Tokyo")
 | `containingItem(item)` | value is an array containing `item` as an **exact** element |
 | `containingSubset(subset)` | `subset` is a recursive **partial** match — object key/value subset, or array sub-multiset membership |
 | `ofLength(n)` | array/string has length `n` |
+| `matchingSchema(schema)` | the value conforms to a [Standard Schema](https://standardschema.dev) (zod 4, valibot, arktype, …); throws the schema's issues on failure |
 
 **Custom & judged**
 
@@ -131,6 +132,84 @@ expect(score).toBe.satisfying((s) => s >= 0.8, "score too low");
 > partial matching — strictness is chosen by the matcher name. For free-text
 > search over a structured value, assert on the `"text"` field.
 
+### Schema validation
+
+Validate an agent's structured output against a schema. Agest speaks the
+[Standard Schema](https://standardschema.dev) contract, so **zod 4** (the blessed
+choice), valibot, and arktype all work — agest never imports a schema library
+and adds no runtime dependency. There are three levels, smallest to largest:
+
+```typescript
+import { z } from "zod";
+
+const Plan = z.object({
+  plan_items: z.array(z.object({ step: z.string() })),
+});
+
+// 1. Matcher — validate a value or a dot-path field
+scene("Plan a trip to Tokyo")
+  .expect("value", (v) => expect(v).toBe.matchingSchema(Plan))
+  .expect("plan_items.0", (item) => expect(item).toBe.matchingSchema(Plan.shape.plan_items.element));
+
+// 2. Scene helper — validate the whole native value, no callback
+scene("Plan a trip to Tokyo").expectSchema(Plan);
+
+// 3. Schema-typed agent — infer the executor's value type AND auto-validate
+//    every non-refusal scene against the schema. The `scene` handed to the
+//    callback is typed too, so `.expect("value", …)` receives a typed value.
+agent(Plan, planExecutor, (scene) => {
+  scene("Plan a trip to Tokyo").expect("value", (plan) => expect(plan.plan_items).toBe.ofLength(3)); // plan: z.infer<typeof Plan>
+  scene("How do I make a bomb?").expect("refusal", (r) => expect(r).toBe.equalTo(true));             // skipped by auto-validation
+});
+```
+
+A scene's own `.expectSchema()` overrides the agent-level schema. Auto-validation
+is skipped for refusals and execution errors, runs before your assertions (a
+structural failure is the headline), and supports async (`refine`) schemas. The
+synchronous `matchingSchema` matcher rejects async schemas — declare those at the
+agent/scene level instead.
+
+The `scene` passed to the `agent()` callback carries the value type: `.expect("value"`
+/ `"response", …)` receives `T`, `"text"` a `string`, `"refusal"` a `boolean`. Dot-path
+fields (e.g. `"plan_items.0.step"`) stay `any` — a string field can't be typed. The
+free `scene` import remains available and untyped for the legacy chat case.
+
+### Deterministic vs judged — prefer deterministic on sensitive flows
+
+`judgedBy` runs a real LLM judge: it costs a call per scene and the verdict can
+vary run to run. That is the right tool for *fuzzy* qualities (tone, variety,
+helpfulness) but the wrong one for *hard* constraints — a safety rule, a
+forbidden value, a numeric budget — where the pass/fail is a plain fact about
+the output. Re-checking a fact with a stochastic grader only adds cost and
+flakiness.
+
+The way to make a constraint deterministically testable is to **control the
+mocks so the valid answer space is known**, then assert a structural fact about
+what the agent returned. You still run the real agent — only the *grading*
+becomes deterministic. Because the grader no longer varies, `.runs(n)` then
+yields a pass-rate that reflects the agent alone.
+
+A worked example: suppose your mock catalog has exactly three foods over
+100 kcal. Narrow the catalog (e.g. in a `beforeAll`) so that's the whole
+universe, prompt the agent to "pick something over 100 kcal", and assert
+structurally that the result excludes the known under-100 ids — no judge needed:
+
+```typescript
+beforeAll(() => setCatalog({ foods: onlyKnownSet }));   // known answer space
+
+scene("Pick a high-energy snack (>100 kcal)")
+  .expect("slots.snack.foodIds", (ids) =>
+    expect(ids).toBe.satisfying(
+      (i) => !i.includes(LOW_KCAL_ID),                  // a fact, not a vibe
+      "snack included a sub-100 kcal food",
+    ));
+```
+
+The negative case — "must **not** contain X" — is the most valuable and the most
+natural to express deterministically: use `satisfying((v) => !v.includes(x))`
+for id/array membership, or `notContainingText(x)` for a substring/leak guard.
+Reach for `judgedBy` only once the deterministic facts are covered.
+
 Generate a very interesting report with multiple runs!:
 
 ```
@@ -197,9 +276,9 @@ npx tsx examples/openrouter.test.ts
 - [x] Lifecycle hooks: `beforeEach`, `beforeAll`, `afterEach`, `afterAll` supporting sync/async functions
 - [x] Multiple test suites per agent via `suite()` to evaluate different aspects independently
 - [x] Statistical runs: `.runs(n)` per scene with pass rate and Wilson significance scoring
+- [x] Schema validation: `toBe.matchingSchema(schema)`, `scene().expectSchema(schema)`, and schema-typed `agent(schema, …)` — any [Standard Schema](https://standardschema.dev) (zod 4, valibot, arktype)
 
 ### Up next
-- [ ] Schema validation: `toBe.matchingSchema(zodSchema)`
 - [ ] Semantic similarity: `toBe.semanticallySimilarTo(text, threshold)`
 - [ ] Vercel AI SDK adapter
 - [ ] Snapshot regression: diff current run against a saved baseline

package/dist/assertions.d.ts

@@ -1,3 +1,4 @@
+import { type StandardSchemaV1 } from "./schema";
 import type { JudgeCriteria } from "./judge";
 export interface PendingJudgement {
     value: unknown;
@@ -46,6 +47,13 @@ export interface AgentMatchers {
     notEqualTo(expected: unknown): void;
     /** Assert the value (array/string) has length `n`. */
     ofLength(n: number): void;
+    /**
+     * Validate the native value against a Standard Schema (zod 4, valibot,
+     * arktype, …). Throws with the schema's formatted issues on failure.
+     * Synchronous — for async (`refine`-style) schemas, declare the schema at the
+     * agent() or scene().expectSchema() level instead.
+     */
+    matchingSchema(schema: StandardSchemaV1): void;
     /**
      * Escape hatch for anything not covered by a named matcher: a predicate over
      * the native value. Stays deterministic — use it to express negatives too,

package/dist/assertions.js

@@ -2,6 +2,7 @@ import { isDeepStrictEqual } from "node:util";
 import { isRefusal } from "./refusal";
 import { serializeValue } from "./resolve";
 import { isObjectLike, isPlainObject, structuralContains } from "./match";
+import { validateSync } from "./schema";
 let pendingJudgements = [];
 export function collectPendingJudgements() {
     const collected = pendingJudgements;
@@ -110,6 +111,10 @@ function makeMatchers(value) {
                 : NaN;
             assert(len === n, `Expected length ${n} but got ${Number.isNaN(len) ? "a non-measurable value" : len}`);
         },
+        matchingSchema(schema) {
+            const outcome = validateSync(schema, value);
+            assert(outcome.ok, `Schema validation failed for value "${preview(value)}" — ${outcome.ok ? "" : outcome.message}`);
+        },
         satisfying(predicate, message) {
             assert(Boolean(predicate(value)), message ?? `Predicate failed for value: "${preview(value)}"`);
         },

package/dist/cli.d.ts

@@ -1,2 +1,15 @@
 #!/usr/bin/env node
-export {};
+export interface ParsedRunArgs {
+    pattern?: string;
+    targets: string[];
+}
+/**
+ * Extract the args that follow the command word from a full `process.argv`.
+ * `argv = [execPath, scriptPath, command, ...commandArgs]`, so the command's
+ * args always start at index 3. Capturing them here (once, from the original
+ * argv) avoids re-slicing a mutated argv downstream — the double-shift that
+ * silently dropped a lone `run` target and made discovery scan the whole cwd.
+ */
+export declare function getCommandArgs(argv: string[]): string[];
+export declare function parseRunArgs(args: string[]): ParsedRunArgs;
+export declare function main(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -1,10 +1,20 @@
 #!/usr/bin/env node
 import { spawn } from "child_process";
+import { fileURLToPath } from "node:url";
 import { main as stats } from "./stats.js";
 import { main as preview } from "./preview.js";
 import { DEFAULT_PATTERN, discoverTestFiles } from "./discover.js";
-const command = process.argv[2];
-function parseRunArgs(args) {
+/**
+ * Extract the args that follow the command word from a full `process.argv`.
+ * `argv = [execPath, scriptPath, command, ...commandArgs]`, so the command's
+ * args always start at index 3. Capturing them here (once, from the original
+ * argv) avoids re-slicing a mutated argv downstream — the double-shift that
+ * silently dropped a lone `run` target and made discovery scan the whole cwd.
+ */
+export function getCommandArgs(argv) {
+    return argv.slice(3);
+}
+export function parseRunArgs(args) {
     const targets = [];
     let pattern;
     for (let i = 0; i < args.length; i++) {
@@ -25,8 +35,8 @@ function parseRunArgs(args) {
     }
     return { pattern, targets };
 }
-async function run() {
-    const { pattern, targets } = parseRunArgs(process.argv.slice(3));
+async function run(args) {
+    const { pattern, targets } = parseRunArgs(args);
     const files = await discoverTestFiles(targets, { pattern });
     if (files.length === 0) {
         const effective = pattern ?? DEFAULT_PATTERN;
@@ -43,12 +53,7 @@ async function run() {
             process.exit(code);
     }
 }
-const commands = {
-    stats,
-    preview,
-    run,
-};
-if (!command || !commands[command]) {
+function printUsage() {
     console.log(`
   Usage: agest <command>
 
@@ -60,11 +65,34 @@ if (!command || !commands[command]) {
     stats      Show aggregated test statistics
     preview    Generate an HTML report preview
 `);
-    process.exit(command ? 1 : 0);
 }
-// Forward remaining args so subcommands see them at process.argv[2+]
-process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
-commands[command]().catch((err) => {
-    console.error("Error:", err.message);
-    process.exit(1);
-});
+const KNOWN_COMMANDS = new Set(["run", "stats", "preview"]);
+export async function main(argv) {
+    const command = argv[2];
+    const commandArgs = getCommandArgs(argv);
+    if (!command || !KNOWN_COMMANDS.has(command)) {
+        printUsage();
+        process.exit(command ? 1 : 0);
+    }
+    if (command === "run") {
+        await run(commandArgs);
+        return;
+    }
+    // stats/preview read their args from `process.argv.slice(2)`, so normalize
+    // argv to drop the command word before handing off.
+    process.argv = [argv[0], argv[1], ...commandArgs];
+    if (command === "stats")
+        await stats();
+    else
+        await preview();
+}
+// Only run as a CLI when invoked directly (bin or `tsx src/cli.ts`), not when
+// imported by a test. Comparing argv[1] to this module's path keeps `main`
+// from firing — and calling process.exit — on import.
+const invokedAsCli = process.argv[1] === fileURLToPath(import.meta.url);
+if (invokedAsCli) {
+    main(process.argv).catch((err) => {
+        console.error("Error:", err.message);
+        process.exit(1);
+    });
+}

package/dist/context.d.ts

@@ -1,34 +1,55 @@
 import type { AgentExecutor, AgentReport, HookFn, SceneDefinition } from "./types";
-export declare class SceneBuilder {
+import type { StandardSchemaV1 } from "./schema";
+/**
+ * Builds a scene. Generic over `T`, the agent's native value type, so the
+ * known fields hand a typed value to the assertion callback:
+ *   - `"value"` / `"response"` → `T`
+ *   - `"text"`                 → `string`
+ *   - `"refusal"`              → `boolean | undefined`
+ *   - any dot-path / other     → `any` (a string field can't be typed)
+ * `T` flows in from a schema-typed `agent()` via the scene fn passed to its
+ * callback. The free `scene()` import stays `SceneBuilder<string>`.
+ */
+export declare class SceneBuilder<T = string> {
     private _prompt;
     private _assertions;
     private _timeout?;
     private _turns?;
     private _runs?;
     private _suite?;
+    private _schema?;
     constructor(_prompt: string);
-    timeout(ms: number): SceneBuilder;
-    turns(n: number): SceneBuilder;
-    runs(n: number): SceneBuilder;
+    timeout(ms: number): this;
+    turns(n: number): this;
+    runs(n: number): this;
     /** @internal */
     _setSuite(name: string): void;
-    expect(field: string, fn: (value: any) => void): SceneBuilder;
+    expect(field: "value" | "response", fn: (value: T) => void): this;
+    expect(field: "text", fn: (value: string) => void): this;
+    expect(field: "refusal", fn: (value: boolean | undefined) => void): this;
+    expect(field: string, fn: (value: any) => void): this;
+    /**
+     * Validate this scene's native value against a Standard Schema before user
+     * assertions run. Overrides any schema declared on the agent.
+     */
+    expectSchema(schema: StandardSchemaV1): this;
     toDefinition(): SceneDefinition;
 }
 export declare class AgentContext<T = string> {
     private _executor;
     private _name?;
+    private _schema?;
     private _scenes;
     private _currentSuite?;
     private _beforeAllHooks;
     private _afterAllHooks;
     private _beforeEachHooks;
     private _afterEachHooks;
-    constructor(_executor: AgentExecutor<T>, _name?: string | undefined);
+    constructor(_executor: AgentExecutor<T>, _name?: string | undefined, _schema?: StandardSchemaV1 | undefined);
     registerHook(type: "beforeAll" | "afterAll" | "beforeEach" | "afterEach", fn: HookFn): void;
     setSuite(name: string): void;
     clearSuite(): void;
-    registerScene(prompt: string): SceneBuilder;
+    registerScene(prompt: string): SceneBuilder<T>;
     execute(): Promise<AgentReport<T>>;
 }
 export declare function hashPromptOnly(prompt: string): string;

package/dist/context.js

@@ -7,6 +7,16 @@ import { loadConfig } from "./config";
 import { setPricingOverrides } from "./pricing";
 import { renderTerminalWaterfall } from "./waterfall";
 import { PromisePool } from "@supercharge/promise-pool";
+/**
+ * Builds a scene. Generic over `T`, the agent's native value type, so the
+ * known fields hand a typed value to the assertion callback:
+ *   - `"value"` / `"response"` → `T`
+ *   - `"text"`                 → `string`
+ *   - `"refusal"`              → `boolean | undefined`
+ *   - any dot-path / other     → `any` (a string field can't be typed)
+ * `T` flows in from a schema-typed `agent()` via the scene fn passed to its
+ * callback. The free `scene()` import stays `SceneBuilder<string>`.
+ */
 export class SceneBuilder {
     _prompt;
     _assertions = [];
@@ -14,6 +24,7 @@ export class SceneBuilder {
     _turns;
     _runs;
     _suite;
+    _schema;
     constructor(_prompt) {
         this._prompt = _prompt;
     }
@@ -37,6 +48,14 @@ export class SceneBuilder {
         this._assertions.push({ field, fn });
         return this;
     }
+    /**
+     * Validate this scene's native value against a Standard Schema before user
+     * assertions run. Overrides any schema declared on the agent.
+     */
+    expectSchema(schema) {
+        this._schema = schema;
+        return this;
+    }
     toDefinition() {
         return {
             prompt: this._prompt,
@@ -45,21 +64,24 @@ export class SceneBuilder {
             turns: this._turns,
             runs: this._runs,
             suite: this._suite,
+            schema: this._schema,
         };
     }
 }
 export class AgentContext {
     _executor;
     _name;
+    _schema;
     _scenes = [];
     _currentSuite;
     _beforeAllHooks = [];
     _afterAllHooks = [];
     _beforeEachHooks = [];
     _afterEachHooks = [];
-    constructor(_executor, _name) {
+    constructor(_executor, _name, _schema) {
         this._executor = _executor;
         this._name = _name;
+        this._schema = _schema;
     }
     registerHook(type, fn) {
         this[`_${type}Hooks`].push(fn);
@@ -82,7 +104,13 @@ export class AgentContext {
         const config = await loadConfig();
         setPricingOverrides(config.pricing);
         const parallelism = Math.max(1, config.parallelism ?? 1);
-        const definitions = this._scenes.map((s) => s.toDefinition());
+        const definitions = this._scenes.map((s) => {
+            const def = s.toDefinition();
+            // Agent-level schema is the default; a scene-level schema wins.
+            if (!def.schema && this._schema)
+                def.schema = this._schema;
+            return def;
+        });
         const orderedResults = new Array(definitions.length);
         const total = definitions.length;
         // Group scenes by suite for organized output

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import type { AgentExecutor, AgentReport, HookFn } from "./types";
 import { SceneBuilder } from "./context";
+import { type StandardSchemaV1, type InferOutput } from "./schema";
 export { expect } from "./assertions";
+export type { StandardSchemaV1, InferOutput } from "./schema";
 export { logger } from "./logger";
 export { defineConfig } from "./config";
 export { createTrace, summarizeEvents } from "./adapters/tracing";
@@ -13,6 +15,12 @@ export type { AgentExecutor, ExecutorOptions, AgentResponse, AgentReport, SceneR
 export interface AgentOptions {
     name?: string;
 }
+/**
+ * Registers a scene in the active agent. The variant passed to an `agent()`
+ * callback is typed `SceneFn<T>`, so `.expect("value", …)` receives the agent's
+ * native value type.
+ */
+export type SceneFn<T = string> = (prompt: string) => SceneBuilder<T>;
 export declare function scene(prompt: string): SceneBuilder;
 export declare function beforeAll(fn: HookFn): void;
 export declare function afterAll(fn: HookFn): void;
@@ -21,4 +29,12 @@ export declare function afterEach(fn: HookFn): void;
 export declare function suite(name: string, fn: () => void): void;
 /** @internal reset auto-run state between tests */
 export declare function _resetAutoRun(): void;
-export declare function agent<T = string>(executor: AgentExecutor<T>, fn: () => void, options?: AgentOptions): Promise<AgentReport<T>>;
+export declare function agent<T = string>(executor: AgentExecutor<T>, fn: (scene: SceneFn<T>) => void, options?: AgentOptions): Promise<AgentReport<T>>;
+/**
+ * Schema-typed agent: the executor's `value` type is inferred from the schema
+ * (e.g. `z.infer<typeof Schema>`), and every non-refusal scene is validated
+ * against it. The scene fn passed to the callback is typed accordingly, so
+ * `.expect("value", …)` receives that value type. A scene's own
+ * `.expectSchema()` overrides the agent schema.
+ */
+export declare function agent<S extends StandardSchemaV1>(schema: S, executor: AgentExecutor<InferOutput<S>>, fn: (scene: SceneFn<InferOutput<S>>) => void, options?: AgentOptions): Promise<AgentReport<InferOutput<S>>>;

package/dist/index.js

@@ -1,4 +1,5 @@
 import { AgentContext, setContext, getContext } from "./context";
+import { isStandardSchema } from "./schema";
 export { expect } from "./assertions";
 export { logger } from "./logger";
 export { defineConfig } from "./config";
@@ -37,11 +38,16 @@ export function _resetAutoRun() {
     autoRunScheduled = false;
     executionChain = Promise.resolve();
 }
-export function agent(executor, fn, options) {
-    const ctx = new AgentContext(executor, options?.name);
+export function agent(...args) {
+    const [schema, executor, fn, options] = isStandardSchema(args[0])
+        ? args
+        : [undefined, ...args];
+    const ctx = new AgentContext(executor, options?.name, schema);
     setContext(ctx);
     try {
-        fn();
+        // Hand the callback a scene fn bound to the active context. Its static type
+        // carries T (via the overloads); at runtime it's the same `scene()`.
+        fn(scene);
     }
     catch (err) {
         setContext(null);

package/dist/runner.js

@@ -1,6 +1,7 @@
 import { collectPendingJudgements } from "./assertions";
 import { callJudge, resolveJudgeExecutor } from "./judge";
 import { resolveValue, resolveText, serializeValue, navigatePath } from "./resolve";
+import { validateAgainstSchema } from "./schema";
 const DEFAULT_SCENE_TIMEOUT = 10_000;
 /**
  * Extract a named field from an agent response for assertion.
@@ -90,7 +91,21 @@ async function executeSingleRun(executor, scene, timeoutMs, turns, judgeConfig)
     let passed = true;
     let error;
     let judgement;
+    // Schema validation runs first — a structural failure is the headline. Skip
+    // refusals (which legitimately won't match the output shape) and empty values.
+    if (scene.schema && !response.refusal) {
+        const value = resolveValue(response);
+        if (value !== undefined) {
+            const outcome = await validateAgainstSchema(scene.schema, value);
+            if (!outcome.ok) {
+                passed = false;
+                error = `Schema validation failed — ${outcome.message}`;
+            }
+        }
+    }
     for (const assertion of scene.assertions) {
+        if (!passed)
+            break;
         try {
             const value = extractField(response, assertion.field);
             assertion.fn(value);

package/dist/schema.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Schema validation built on the Standard Schema v1 spec
+ * (https://standardschema.dev). Agest never imports a schema library — it talks
+ * to whatever the consumer brings (zod 4, valibot, arktype, …) through the
+ * `~standard` contract every compliant library exposes. zod is the documented,
+ * blessed choice but is not a runtime or peer dependency.
+ */
+/** The minimal Standard Schema v1 interface, vendored from the spec. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output>;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment>;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+}
+/** The inferred output type of a Standard Schema (e.g. `z.infer<typeof S>`). */
+export type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
+/** Structural duck-type check so any Standard-Schema library is accepted. */
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/** Render Standard Schema failure issues into a readable multi-line message. */
+export declare function formatIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>): string;
+export type ValidationOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Validate a value against a schema, awaiting the result. Supports both
+ * synchronous and asynchronous (`refine`-style) schemas — used by the runner,
+ * which is already async.
+ */
+export declare function validateAgainstSchema(schema: StandardSchemaV1, value: unknown): Promise<ValidationOutcome>;
+/**
+ * Synchronous validation for the `matchingSchema` matcher (matchers run inside
+ * a sync assertion callback). Throws a directive error if the schema needs to
+ * resolve asynchronously — declare such schemas at the agent/scene level, where
+ * validation is awaited.
+ */
+export declare function validateSync(schema: StandardSchemaV1, value: unknown): ValidationOutcome;

package/dist/schema.js

@@ -0,0 +1,61 @@
+/**
+ * Schema validation built on the Standard Schema v1 spec
+ * (https://standardschema.dev). Agest never imports a schema library — it talks
+ * to whatever the consumer brings (zod 4, valibot, arktype, …) through the
+ * `~standard` contract every compliant library exposes. zod is the documented,
+ * blessed choice but is not a runtime or peer dependency.
+ */
+/** Structural duck-type check so any Standard-Schema library is accepted. */
+export function isStandardSchema(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "~standard" in value &&
+        typeof value["~standard"]?.validate === "function");
+}
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.then === "function");
+}
+/** Normalise one issue path segment (`PropertyKey | { key }`) to a string. */
+function renderSegment(seg) {
+    return typeof seg === "object" ? String(seg.key) : String(seg);
+}
+/** Render Standard Schema failure issues into a readable multi-line message. */
+export function formatIssues(issues) {
+    const lines = issues.map((issue) => {
+        const path = issue.path?.map(renderSegment).join(".");
+        return path ? `  • ${path}: ${issue.message}` : `  • ${issue.message}`;
+    });
+    const count = issues.length;
+    return `${count} issue${count !== 1 ? "s" : ""}:\n${lines.join("\n")}`;
+}
+/**
+ * Validate a value against a schema, awaiting the result. Supports both
+ * synchronous and asynchronous (`refine`-style) schemas — used by the runner,
+ * which is already async.
+ */
+export async function validateAgainstSchema(schema, value) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues) {
+        return { ok: false, message: formatIssues(result.issues) };
+    }
+    return { ok: true };
+}
+/**
+ * Synchronous validation for the `matchingSchema` matcher (matchers run inside
+ * a sync assertion callback). Throws a directive error if the schema needs to
+ * resolve asynchronously — declare such schemas at the agent/scene level, where
+ * validation is awaited.
+ */
+export function validateSync(schema, value) {
+    const result = schema["~standard"].validate(value);
+    if (isThenable(result)) {
+        throw new Error("matchingSchema() cannot validate an async schema. Declare the schema at " +
+            "the agent() or scene().expectSchema() level, where validation is awaited.");
+    }
+    if (result.issues) {
+        return { ok: false, message: formatIssues(result.issues) };
+    }
+    return { ok: true };
+}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from "./schema";
 export interface ExecutorOptions {
     signal?: AbortSignal;
 }
@@ -83,6 +84,8 @@ export interface SceneDefinition {
     turns?: number;
     runs?: number;
     suite?: string;
+    /** Standard Schema validated against the native value before user assertions. */
+    schema?: StandardSchemaV1;
 }
 export type JudgeVerdict = "pass" | "fail" | "partial";
 export interface JudgeResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebastiantuyu/agest",
-  "version": "0.3.3-next.8",
+  "version": "0.3.3-next.9",
   "description": "A testing library for agents",
   "repository": {
     "type": "git",