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

package/README.md

@@ -53,6 +53,163 @@ agent:
     average_output_tokens_per_case: 34
 ```
 
+## Assertions
+
+Each scene asserts on a **field** of the agent's response via `.expect(field, fn)`,
+and inside the callback you chain a matcher off `expect(value).toBe`.
+
+### Structured responses
+
+An executor returns a native `value` (the source of truth for structural
+matchers) and/or a `text` projection (for the LLM judge and text matchers):
+
+```typescript
+// chat agent — a string is both value and text
+return { text: "Bonjour" };
+
+// structured agent — a native object, optionally with an enriched text view
+return { value: { plan_items: [{ step: "search" }] } };
+```
+
+### Selecting a field
+
+```typescript
+scene("Plan a trip to Tokyo")
+  .expect("value", (v) => expect(v).toBe.containingSubset({ plan_items: [{ step: "book_flight" }] }))
+  .expect("plan_items.0.step", (s) => expect(s).toBe.equalTo("book_flight")) // dot-path into the value
+  .expect("text", (t) => expect(t).toBe.containingText("Tokyo"));            // serialized/judge view
+```
+
+- `"response"` / `"value"` — the native value (objects stay objects; never stringified)
+- `"text"` — the serialized/enriched text view (lazy: a string passes through, else JSON)
+- `"refusal"` / `"metadata"` — the corresponding response properties
+- any **dot-path** (e.g. `"plan_items.0.options"`) — navigates into the value, falling back to metadata
+
+### Matchers
+
+**Refusal**
+
+| Matcher | Asserts |
+| --- | --- |
+| `refusal()` | the agent refused |
+| `notRefusal()` | the agent did **not** refuse |
+
+**Text** — substring / regex over a string value (or the serialized form of a non-string). Case-insensitive by default.
+
+| Matcher | Asserts |
+| --- | --- |
+| `containingText(text, { caseSensitive? })` | `text` appears as a substring |
+| `notContainingText(text, { caseSensitive? })` | `text` does **not** appear — handy for leak/PII guards |
+| `matchingPattern(regex)` | the text matches `regex` |
+
+**Structural** — operate on the native value; exact (case-sensitive) at the leaves.
+
+| Matcher | Asserts |
+| --- | --- |
+| `equalTo(expected)` | deep structural equality (NaN / Date / ±0 correct) |
+| `notEqualTo(expected)` | deep structural **inequality** |
+| `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**
+
+| Matcher | Asserts |
+| --- | --- |
+| `satisfying(predicate, message?)` | a deterministic predicate over the value holds (use for any negative not covered above) |
+| `judgedBy({ criteria, failWhen })` | an LLM judge resolves the criteria (fuzzy + paid) |
+
+```typescript
+expect(items).toBe.ofLength(3);
+expect(results).toBe.containingItem({ id: 7, status: "ok" });   // exact element
+expect(plan).toBe.containingSubset({ user: { id: 1 } });        // partial, nested
+expect(response).toBe.notContainingText("api_key");             // leak guard
+expect(score).toBe.satisfying((s) => s >= 0.8, "score too low");
+```
+
+> Use `containingItem` for exact array membership and `containingSubset` for
+> 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!:
 
 ```
@@ -119,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/adapters/remote.d.ts

@@ -56,7 +56,7 @@ export interface RemoteAdapterOptions {
  *
  * await agent(executor, () => {
  *   scene("What is 2+2?").expect("response", (r) => {
- *     expect(r).toBe.containing("4");
+ *     expect(r).toBe.containingText("4");
  *   });
  * });
  * ```

package/dist/adapters/remote.js

@@ -17,7 +17,7 @@
  *
  * await agent(executor, () => {
  *   scene("What is 2+2?").expect("response", (r) => {
- *     expect(r).toBe.containing("4");
+ *     expect(r).toBe.containingText("4");
  *   });
  * });
  * ```

package/dist/adapters/tracing.js

@@ -56,6 +56,7 @@ export async function createTracingHandle(baselineMs) {
                 model: name,
                 inputTokens: tokens?.input,
                 outputTokens: tokens?.output,
+                cachedInputTokens,
                 providerCost,
             });
             events.push({

package/dist/assertions.d.ts

@@ -1,3 +1,4 @@
+import { type StandardSchemaV1 } from "./schema";
 import type { JudgeCriteria } from "./judge";
 export interface PendingJudgement {
     value: unknown;
@@ -5,10 +6,64 @@ export interface PendingJudgement {
 }
 export declare function collectPendingJudgements(): PendingJudgement[];
 export interface AgentMatchers {
+    /** Assert the agent refused. */
     refusal(): void;
+    /** Assert the agent did NOT refuse. */
     notRefusal(): void;
-    containing(text: string): void;
-    matchingPattern(regex: RegExp): void;
+    /**
+     * Text containment: `text` appears as a substring. For a non-string value the
+     * serialized form is searched. Case-INsensitive by default; pass
+     * `{ caseSensitive: true }` for an exact substring.
+     */
+    containingText(text: string | number, opts?: {
+        caseSensitive?: boolean;
+    }): void;
+    /** Assert text containment does NOT hold. See {@link containingText}. */
+    notContainingText(text: string | number, opts?: {
+        caseSensitive?: boolean;
+    }): void;
+    /**
+     * Array membership: the value is an array containing `item` as an EXACT
+     * (deep-equal) element. Throws if the value is not an array. Use
+     * {@link containingSubset} when you want partial element matching.
+     */
+    containingItem(item: unknown): void;
+    /**
+     * Structural subset: `subset` is recursively contained in the value.
+     * - object value + object `subset` → every key in `subset` is present with a
+     *   recursively-contained value (extra keys allowed).
+     * - array value + array `subset` → every `subset` element matches a distinct
+     *   element of the value (partial element matching, order-independent).
+     *
+     * Exact at the leaves (case-sensitive). Throws if the value is not an
+     * object/array, or `subset` is not an object/array.
+     */
+    containingSubset(subset: object): void;
+    /** Assert the serialized text view matches `pattern`. */
+    matchingPattern(pattern: RegExp): void;
+    /** Deep structural equality against the native value. */
+    equalTo(expected: unknown): void;
+    /** Assert deep structural INequality against the native value. */
+    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,
+     * e.g. `satisfying((v) => !v.includes("secret"))`.
+     */
+    satisfying(predicate: (value: any) => boolean, message?: string): void;
+    /**
+     * Queue an LLM-judged assertion, resolved asynchronously by the runner.
+     * Fuzzy + paid (express the negative in `failWhen`).
+     */
     judgedBy(criteria: JudgeCriteria): void;
 }
 export interface AgentExpectation {

package/dist/assertions.js

@@ -1,46 +1,132 @@
+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;
     pendingJudgements = [];
     return collected;
 }
+/**
+ * 100-char preview for error messages. Uses COMPACT JSON for objects (the
+ * judge-facing `serializeValue` pretty-prints; error previews stay terse and
+ * match the library's original contract).
+ */
+function preview(value) {
+    let s;
+    if (typeof value === "string") {
+        s = value;
+    }
+    else {
+        try {
+            s = JSON.stringify(value);
+        }
+        catch {
+            s = String(value);
+        }
+    }
+    return s.slice(0, 100);
+}
+/** Compact one-line form for an inline needle/expected in an error message. */
+function compact(value) {
+    try {
+        return typeof value === "string" ? value : JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Human-readable type label for diagnostics (e.g. "a number", "an array"). */
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return `a ${typeof value}`;
+}
+/**
+ * Substring search shared by `containingText` / `notContainingText`. A string
+ * value is searched directly; anything else via its serialized form.
+ * Case-insensitive unless `caseSensitive` is set.
+ */
+function textContains(value, text, opts) {
+    const actual = typeof value === "string" ? value : serializeValue(value);
+    const needle = String(text);
+    const hit = opts?.caseSensitive
+        ? actual.includes(needle)
+        : actual.toLowerCase().includes(needle.toLowerCase());
+    return { actual, hit };
+}
+function makeMatchers(value) {
+    const assert = (cond, message) => {
+        if (!cond)
+            throw new Error(message);
+    };
+    return {
+        refusal() {
+            assert(isRefusal(value), `Expected a refusal but got: "${preview(value)}"`);
+        },
+        notRefusal() {
+            assert(!isRefusal(value), `Expected a non-refusal response but got: "${preview(value)}"`);
+        },
+        containingText(text, opts) {
+            const { actual, hit } = textContains(value, text, opts);
+            assert(hit, `Expected response to contain "${text}" but got: "${actual.slice(0, 100)}"`);
+        },
+        notContainingText(text, opts) {
+            const { actual, hit } = textContains(value, text, opts);
+            assert(!hit, `Expected response NOT to contain "${text}" but got: "${actual.slice(0, 100)}"`);
+        },
+        containingItem(item) {
+            if (!Array.isArray(value)) {
+                throw new Error(`containingItem() expects an array value but got ${describeType(value)}. ` +
+                    `Use containingText() for substrings or containingSubset() for objects.`);
+            }
+            assert(value.some((el) => isDeepStrictEqual(el, item)), `Expected array to contain item ${compact(item)} but it did not (got ${preview(value)})`);
+        },
+        containingSubset(subset) {
+            if (!Array.isArray(value) && !isObjectLike(value)) {
+                throw new Error(`containingSubset() expects an object or array value but got ${describeType(value)}.`);
+            }
+            if (!Array.isArray(subset) && !isPlainObject(subset)) {
+                throw new Error(`containingSubset() expects an object or array subset but got ${describeType(subset)}.`);
+            }
+            assert(structuralContains(value, subset), `Expected value to contain subset ${compact(subset)} but it did not (got ${preview(value)})`);
+        },
+        matchingPattern(pattern) {
+            const actual = typeof value === "string" ? value : serializeValue(value);
+            assert(pattern.test(actual), `Expected response to match ${pattern} but got: "${actual.slice(0, 100)}"`);
+        },
+        equalTo(expected) {
+            assert(isDeepStrictEqual(value, expected), `Expected value to equal ${compact(expected)} but got ${preview(value)}`);
+        },
+        notEqualTo(expected) {
+            assert(!isDeepStrictEqual(value, expected), `Expected value NOT to equal ${compact(expected)} but it did`);
+        },
+        ofLength(n) {
+            const len = typeof value === "string" || Array.isArray(value)
+                ? value.length
+                : 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)}"`);
+        },
+        judgedBy(criteria) {
+            pendingJudgements.push({ value, criteria });
+        },
+    };
+}
 export function expect(value) {
     return {
         get toBe() {
-            return {
-                refusal() {
-                    if (!isRefusal(value)) {
-                        const preview = typeof value === "string"
-                            ? value.slice(0, 100)
-                            : JSON.stringify(value).slice(0, 100);
-                        throw new Error(`Expected a refusal but got: "${preview}"`);
-                    }
-                },
-                notRefusal() {
-                    if (isRefusal(value)) {
-                        const preview = typeof value === "string"
-                            ? value.slice(0, 100)
-                            : JSON.stringify(value).slice(0, 100);
-                        throw new Error(`Expected a non-refusal response but got: "${preview}"`);
-                    }
-                },
-                containing(text) {
-                    const actual = typeof value === "string" ? value : String(value);
-                    if (!actual.toLowerCase().includes(text.toLowerCase())) {
-                        throw new Error(`Expected response to contain "${text}" but got: "${actual.slice(0, 100)}"`);
-                    }
-                },
-                matchingPattern(regex) {
-                    const actual = typeof value === "string" ? value : String(value);
-                    if (!regex.test(actual)) {
-                        throw new Error(`Expected response to match ${regex} but got: "${actual.slice(0, 100)}"`);
-                    }
-                },
-                judgedBy(criteria) {
-                    pendingJudgements.push({ value, criteria });
-                },
-            };
+            return makeMatchers(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,36 +1,57 @@
 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 {
+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, _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;
-    execute(): Promise<AgentReport>;
+    registerScene(prompt: string): SceneBuilder<T>;
+    execute(): Promise<AgentReport<T>>;
 }
 export declare function hashPromptOnly(prompt: string): string;
-export declare function setContext(ctx: AgentContext | null): void;
-export declare function getContext(): AgentContext;
+export declare function setContext(ctx: AgentContext<any> | null): void;
+export declare function getContext(): AgentContext<any>;