@lunora/testing 1.0.0-alpha.5 → 1.0.0-alpha.50

package/dist/index.d.mts

@@ -1,17 +1,127 @@
+import { AgentMessageRow, AgentRunInput, AgentGenerateResult, AgentRunResult, AgentDefinition } from '@lunora/agent';
 import { ScheduledJob, RegisteredAction, RegisteredMutation, RegisteredQuery, ArgsValidator, InferArgs, ActionCtx, MutationCtx, QueryCtx, TableDefinition, Schema } from '@lunora/server';
 export { type InboxOptions, type WaitForMailOptions, extractLink, listCapturedMail, waitForMail } from '@lunora/mail/testing';
+/** A thread message as the in-memory runtime stores it (superset of {@link AgentMessageRow}). */
+interface HarnessMessage extends AgentMessageRow {
+  messageKey: string;
+  threadKey: string;
+}
+/** A thread record as the in-memory runtime stores it. */
+interface HarnessThread {
+  agent: string;
+  error?: string;
+  instanceId?: string;
+  key: string;
+  messageCount: number;
+  owner?: string;
+  status: string;
+  title?: string;
+  usage?: unknown;
+}
+/** One recorded function dispatch the loop made through `ctx.run`. */
+interface HarnessDispatch {
+  args: Record<string, unknown> | undefined;
+  path: string;
+}
+/** Extra function-dispatch handler layered over the built-in `agents:*` runtime double. */
+type HarnessFunction = (args?: Record<string, unknown>) => unknown;
+interface AgentHarnessOptions {
+  /**
+   * Worker `env` bindings visible to tool `execute` and a dynamic
+   * `instructions` thunk. Default `{ LUNORA_TEST: true }`.
+   */
+  env?: Record<string, unknown>;
+  /**
+   * The agent's `lunora/agents.ts` export name — used for thread attribution
+   * and to derive the child-agent `AGENT_*` bindings a sub-agent tool targets.
+   * Default `"agent"`.
+   */
+  exportName?: string;
+  /**
+   * Stub the app functions a tool's `execute` (or the agent's `memory.source`)
+   * dispatches through `ctx.run`, keyed by function path (`"weather:lookup"`).
+   * A handler layered here shadows the built-in `agents:*` runtime double for
+   * that path. An unstubbed non-`agents:*` dispatch throws, so a missing stub
+   * fails loudly rather than silently returning `undefined`.
+   */
+  functions?: Record<string, HarnessFunction>;
+  /**
+   * Scripted model decisions, one {@link AgentGenerateResult} per LLM turn —
+   * the default script for {@link AgentHarness.run}. A terminal turn has an
+   * empty `toolCalls`; a tool-calling turn lists the calls the loop then runs
+   * against the agent's own tools. Override per run via `run(..., { script })`.
+   */
+  script: AgentGenerateResult[];
+}
+/** Per-run overrides for {@link AgentHarness.run}. */
+interface AgentRunOverrides {
+  /** The workflow instance id for this run (default: an auto-incrementing `wf-N`). */
+  instanceId?: string;
+  /** The model script for THIS run, replacing the harness default. */
+  script?: AgentGenerateResult[];
+}
+interface AgentHarness {
+  /**
+   * Every function dispatch the loop has made through `ctx.run`, in order —
+   * both the `agents:*` runtime calls and the tool/memory app dispatches. Use
+   * it to assert a tool called the function you expected with the args you
+   * expected.
+   */
+  readonly dispatches: ReadonlyArray<HarnessDispatch>;
+  /** The persisted messages of a thread, ordered by `seq`. */
+  messages: (threadKey: string) => AgentMessageRow[];
+  /**
+   * Drive one durable agent run to completion against the in-memory journal +
+   * runtime double, returning the loop's {@link AgentRunResult}. Reuse the same
+   * `threadKey` across calls to continue a conversation (the persisted history
+   * carries over); each call runs under a fresh instance id, modelling a
+   * distinct workflow instance.
+   */
+  run: (params: AgentRunInput, overrides?: AgentRunOverrides) => Promise<AgentRunResult>;
+  /** The stored thread record (status, error, instanceId, usage, …), or `undefined` before its first run. */
+  thread: (threadKey: string) => HarnessThread | undefined;
+}
+/**
+ * A unit-test harness for a `defineAgent` tool-loop that runs WITHOUT a real
+ * model or network. It drives {@link runAgentLoop} over the agent's own
+ * `AgentGenerate` seam — the model is a script of per-turn decisions, tool calls
+ * run the agent's real `execute` functions inside an in-memory durable-step
+ * journal, and thread/message persistence goes through an in-memory `agents:*`
+ * runtime double. Mock any function a tool (or the agent's memory) dispatches
+ * through the `functions` option.
+ *
+ * ```ts
+ * const harness = agentHarness(support, {
+ *     script: [toolCallTurn("c1", "lookup", { id: "o_1" }), finalTurn("It shipped.")],
+ *     functions: { "orders:lookup": () => ({ status: "shipped" }) },
+ * });
+ * const result = await harness.run({ input: "where is my order?", threadKey: "t1" });
+ * expect(result.text).toBe("It shipped.");
+ * expect(harness.messages("t1").at(-1)?.content).toBe("It shipped.");
+ * ```
+ *
+ * The harness deliberately does NOT model the concurrency guard or a
+ * human-in-the-loop approval pause — it is for exercising an agent's tools and
+ * turn logic, not the durable orchestration itself (that is covered inside
+ * `@lunora/agent`).
+ */
+declare const agentHarness: (agent: AgentDefinition, options: AgentHarnessOptions) => AgentHarness;
+/** A terminal (final-answer) turn — no tool calls. */
+declare const finalTurn: (text: string, extra?: Partial<AgentGenerateResult>) => AgentGenerateResult;
+/** A single-tool-call turn: the loop runs the named tool with `input`. */
+declare const toolCallTurn: (id: string, name: string, input: unknown, text?: string) => AgentGenerateResult;
 /** A pending job entry in the fake scheduler queue. */
 interface FakeScheduledJob extends ScheduledJob {
   /** The args the job was scheduled with. */
   args: Record<string, unknown>;
 }
 /**
-* A single scheduled-job failure captured during an `advance()` / `runPending()`
-* sweep. Production's scheduler isolates per-job failures (one bad job does not
-* abort the rest), so the fake scheduler does the same — but, being a test
-* harness, it never swallows the error: every failure is recorded here so tests
-* can still assert on it.
-*/
+ * A single scheduled-job failure captured during an `advance()` / `runPending()`
+ * sweep. Production's scheduler isolates per-job failures (one bad job does not
+ * abort the rest), so the fake scheduler does the same — but, being a test
+ * harness, it never swallows the error: every failure is recorded here so tests
+ * can still assert on it.
+ */
 interface ScheduledJobFailure {
   /** The args the job was dispatched with. */
   args: Record<string, unknown>;
@@ -23,94 +133,85 @@ interface ScheduledJobFailure {
   id: string;
 }
 /**
-* Controls exposed on the test harness for the fake in-memory scheduler.
-* Access via `harness.scheduler`.
-*/
+ * Controls exposed on the test harness for the fake in-memory scheduler.
+ * Access via `harness.scheduler`.
+ */
 interface FakeSchedulerControls {
   /**
-  * Advance the virtual clock by `ms` milliseconds, executing all jobs whose
-  * `scheduledFor` timestamp is now at or before the new virtual "now". Jobs
-  * are dispatched in `scheduledFor` order (oldest first). Newly queued jobs
-  * (scheduled by an executed job during the advance) are NOT re-evaluated in
-  * the same advance call — callers should advance again if needed.
-  *
-  * Per-job failures are isolated (matching production): a job that throws does
-  * NOT prevent the remaining due jobs from running. After every due job has
-  * run, the failures are surfaced — they are recorded on
-  * {@link FakeSchedulerControls.failures} and, by default, re-thrown so a test
-  * still sees the error. A single failure is re-thrown verbatim; multiple
-  * failures are aggregated into an `AggregateError`. Pass
-  * `{ throwOnError: false }` to suppress the re-throw and inspect
-  * {@link FakeSchedulerControls.failures} (and the returned count) instead.
-  *
-  * Returns the number of jobs that were executed (including failed ones).
-  */
+   * Advance the virtual clock by `ms` milliseconds, executing all jobs whose
+   * `scheduledFor` timestamp is now at or before the new virtual "now". Jobs
+   * are dispatched in `scheduledFor` order (oldest first). Newly queued jobs
+   * (scheduled by an executed job during the advance) are NOT re-evaluated in
+   * the same advance call — callers should advance again if needed.
+   *
+   * Per-job failures are isolated (matching production): a job that throws does
+   * NOT prevent the remaining due jobs from running. After every due job has
+   * run, the failures are surfaced — they are recorded on
+   * {@link FakeSchedulerControls.failures} and, by default, re-thrown so a test
+   * still sees the error. A single failure is re-thrown verbatim; multiple
+   * failures are aggregated into an `AggregateError`. Pass
+   * `{ throwOnError: false }` to suppress the re-throw and inspect
+   * {@link FakeSchedulerControls.failures} (and the returned count) instead.
+   *
+   * Returns the number of jobs that were executed (including failed ones).
+   */
   advance: (ms: number, options?: SweepOptions) => Promise<number>;
   /**
-  * All scheduled-job failures captured so far, in execution order, across
-  * every `advance()` / `runPending()` call on this harness. Always available,
-  * even when `throwOnError: false` suppressed the re-throw. The list is a
-  * snapshot — mutating it does not affect the scheduler.
-  */
+   * All scheduled-job failures captured so far, in execution order, across
+   * every `advance()` / `runPending()` call on this harness. Always available,
+   * even when `throwOnError: false` suppressed the re-throw. The list is a
+   * snapshot — mutating it does not affect the scheduler.
+   */
   failures: () => ScheduledJobFailure[];
   /**
-  * List all pending jobs (those not yet executed or cancelled) in the order
-  * they were enqueued.
-  */
+   * List all pending jobs (those not yet executed or cancelled) in the order
+   * they were enqueued.
+   */
   list: () => FakeScheduledJob[];
   /**
-  * Execute all currently pending jobs regardless of their `scheduledFor`
-  * time. Equivalent to advancing to `Infinity`. Returns the number of jobs
-  * executed (including failed ones).
-  *
-  * Failure isolation and surfacing match {@link FakeSchedulerControls.advance}:
-  * one failing job does not abort the rest, and failures are recorded on
-  * {@link FakeSchedulerControls.failures} and re-thrown unless
-  * `{ throwOnError: false }` is passed.
-  */
+   * Execute all currently pending jobs regardless of their `scheduledFor`
+   * time. Equivalent to advancing to `Infinity`. Returns the number of jobs
+   * executed (including failed ones).
+   *
+   * Failure isolation and surfacing match {@link FakeSchedulerControls.advance}:
+   * one failing job does not abort the rest, and failures are recorded on
+   * {@link FakeSchedulerControls.failures} and re-thrown unless
+   * `{ throwOnError: false }` is passed.
+   */
   runPending: (options?: SweepOptions) => Promise<number>;
 }
 /** Options controlling how an `advance()` / `runPending()` sweep surfaces failures. */
 interface SweepOptions {
   /**
-  * When `true` (the default), failures encountered during the sweep are
-  * re-thrown after every due job has run — a single failure verbatim, multiple
-  * as an `AggregateError`. When `false`, the sweep resolves normally and
-  * failures are observable only via {@link FakeSchedulerControls.failures}.
-  */
+   * When `true` (the default), failures encountered during the sweep are
+   * re-thrown after every due job has run — a single failure verbatim, multiple
+   * as an `AggregateError`. When `false`, the sweep resolves normally and
+   * failures are observable only via {@link FakeSchedulerControls.failures}.
+   */
   throwOnError?: boolean;
 }
 /**
-* Top-level dispatch for a scheduled job — wired by the harness. Unlike the
-* `runInternal` closure used by `ctx.run*` composition (which rides whatever
-* transaction span is already open), a scheduled job is a fresh top-level entry:
-* production dispatches it back to the Worker as its own RPC, so a scheduled
-* `mutation` runs inside its own BEGIN/COMMIT span and notifies subscription
-* listeners on success. The harness supplies a callback that reproduces those
-* semantics (mutations wrapped + notified; actions run unwrapped).
-*/
-/**
-* The schema value produced by `@lunora/server`'s `defineSchema`. Accepted
-* structurally; internally it is handed to `@lunora/do`'s `runShardMigrations` /
-* `createShardCtxDb`, whose `SchemaLike` is the same shape declared in the DO
-* package — the two are structurally compatible at runtime (only their
-* independently-declared trigger nesting drifts at the type level), so the
-* boundary cast below is sound.
-*/
+ * The schema value produced by `@lunora/server`'s `defineSchema`. Accepted
+ * structurally; internally it is handed to `@lunora/do`'s `runShardMigrations` /
+ * `createShardCtxDb`, whose `SchemaLike` is the same shape declared in the DO
+ * package — the two are structurally compatible at runtime (only their
+ * independently-declared trigger nesting drifts at the type level), so the
+ * boundary cast below is sound.
+ */
 type TestSchema = Schema<Record<string, TableDefinition>>;
 /**
-* A user-supplied identity, surfaced to handlers via `ctx.auth`. `userId` is the
-* subject the handler reads from `ctx.auth.userId`; any additional fields are
-* returned verbatim from `ctx.auth.getIdentity()` (mirroring a decoded JWT).
-*/
+ * A user-supplied identity, surfaced to handlers via `ctx.auth`. `userId` is the
+ * subject the handler reads from `ctx.auth.userId`; any additional fields are
+ * returned verbatim from `ctx.auth.getIdentity()` (mirroring a decoded JWT).
+ */
 interface TestIdentity extends Record<string, unknown> {
   userId?: null | string;
 }
 /**
-* An async iterable/iterator returned by {@link TestHarness.subscribe}.
-* Guarantees `return()` is always defined (unlike the optional `AsyncIterator.return`),
-* so callers can always unsubscribe without a `?.` guard.
-*/
+ * An async iterable/iterator returned by {@link TestHarness.subscribe}.
+ * Guarantees `return()` is always defined (unlike the optional `AsyncIterator.return`),
+ * so callers can always unsubscribe without a `?.` guard.
+ */
 interface TestSubscription<R> extends AsyncIterable<R> {
   next: () => Promise<IteratorResult<R, R>>;
   return: () => Promise<IteratorResult<R, R>>;
@@ -120,75 +221,88 @@ type InlineQueryFunction<R> = (context: QueryCtx) => Promise<R> | R;
 type InlineMutationFunction<R> = (context: MutationCtx) => Promise<R> | R;
 type InlineActionFunction<R> = (context: ActionCtx) => Promise<R> | R;
 /**
-* A map from function path strings (e.g. `"messages:send"`) to their
-* registered function objects. Used by the fake scheduler to resolve
-* `ctx.scheduler.runAfter(delay, "messages:send", args)` → handler invocation.
-*
-* Only mutations and actions can be scheduled in production; queries passed
-* here will be accepted but produce a console.warn at dispatch time.
-*
-* The value type uses `any` because `RegisteredFunction` is contravariant in its
-* args type parameter — a `RegisteredMutation` with concrete args is not assignable
-* to `RegisteredMutation` with `ArgsValidator` at the type level even though at
-* runtime it is sound (the fake scheduler passes `Record&lt;string, unknown>` to
-* `handler` and ignores the return value).
-*/
+ * A map from function path strings (e.g. `"messages:send"`) to their
+ * registered function objects. Used by the fake scheduler to resolve
+ * `ctx.scheduler.runAfter(delay, "messages:send", args)` → handler invocation.
+ *
+ * Only mutations and actions can be scheduled in production; queries passed
+ * here will be accepted but produce a console.warn at dispatch time.
+ *
+ * The value type uses `any` because `RegisteredFunction` is contravariant in its
+ * args type parameter — a `RegisteredMutation` with concrete args is not assignable
+ * to `RegisteredMutation` with `ArgsValidator` at the type level even though at
+ * runtime it is sound (the fake scheduler passes `Record&lt;string, unknown>` to
+ * `handler` and ignores the return value).
+ */
 type FunctionRegistry = Record<string, RegisteredAction<any, any> | RegisteredMutation<any, any> | RegisteredQuery<any, any>>;
 /**
-* Options accepted by {@link lunoraTest}.
-*
-* All options are optional — `lunoraTest(schema)` preserves v1 behaviour with
-* clearly-throwing stubs for unsupported surfaces.
-*/
+ * Options accepted by {@link lunoraTest}.
+ *
+ * All options are optional — `lunoraTest(schema)` preserves v1 behaviour with
+ * clearly-throwing stubs for unsupported surfaces.
+ */
 interface LunoraTestOptions {
   /**
-  * Injectable `fetch` implementation for action contexts. When provided,
-  * `ctx.fetch` in every `action` (and `withIdentity` views) resolves to this
-  * function rather than throwing the "not available in v1" stub.
-  *
-  * Pass `vi.fn()` or any `typeof globalThis.fetch` compatible implementation.
-  * @example
-  * ```ts
-  * const fakeFetch = vi.fn().mockResolvedValue(Response.json({ ok: true }));
-  * const t = lunoraTest(schema, { fetch: fakeFetch });
-  * ```
-  */
+   * Injectable `ctx.env` for every context (query / mutation / action). When
+   * provided, handlers that read `ctx.env.SOME_KEY` (the validated `defineEnv`
+   * surface) see this object. Left unset it stays `undefined` — matching the
+   * optional `ctx.env?` field, so graceful `ctx.env?.KEY` access still yields
+   * `undefined` rather than throwing. Not a throwing stub for exactly that
+   * reason: `env` is designed to be legitimately absent.
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, { env: { STRIPE_KEY: "sk_test_…" } });
+   * ```
+   */
+  env?: Record<string, unknown>;
+  /**
+   * Injectable `fetch` implementation for action contexts. When provided,
+   * `ctx.fetch` in every `action` (and `withIdentity` views) resolves to this
+   * function rather than throwing the "not available in v1" stub.
+   *
+   * Pass `vi.fn()` or any `typeof globalThis.fetch` compatible implementation.
+   * @example
+   * ```ts
+   * const fakeFetch = vi.fn().mockResolvedValue(Response.json({ ok: true }));
+   * const t = lunoraTest(schema, { fetch: fakeFetch });
+   * ```
+   */
   fetch?: typeof globalThis.fetch;
   /**
-  * Function registry for the fake in-memory scheduler. Maps a
-  * `functionPath` string (the value passed as the second argument to
-  * `ctx.scheduler.runAfter` / `ctx.scheduler.runAt`) to the corresponding
-  * registered function object.
-  *
-  * Only required if your handlers schedule work. Scheduled jobs for paths
-  * NOT listed here produce a `console.warn` at dispatch time (matching prod
-  * behaviour for unknown paths).
-  * @example
-  * ```ts
-  * const t = lunoraTest(schema, {
-  *   functions: { "messages:send": sendMutation },
-  * });
-  * ```
-  */
+   * Function registry for the fake in-memory scheduler. Maps a
+   * `functionPath` string (the value passed as the second argument to
+   * `ctx.scheduler.runAfter` / `ctx.scheduler.runAt`) to the corresponding
+   * registered function object.
+   *
+   * Only required if your handlers schedule work. Scheduled jobs for paths
+   * NOT listed here produce a `console.warn` at dispatch time (matching prod
+   * behaviour for unknown paths).
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, {
+   *   functions: { "messages:send": sendMutation },
+   * });
+   * ```
+   */
   functions?: FunctionRegistry;
   /**
-  * Fixed value for `ctx.now` (epoch ms) in every context. Production captures
-  * `Date.now()` once per execution; in tests a fixed `now` makes time-dependent
-  * handlers deterministic. Defaults to the wall clock at harness creation.
-  * @example
-  * ```ts
-  * const t = lunoraTest(schema, { now: 1_700_000_000_000 });
-  * ```
-  */
+   * Fixed value for `ctx.now` (epoch ms) in every context. Production captures
+   * `Date.now()` once per execution; in tests a fixed `now` makes time-dependent
+   * handlers deterministic. Defaults to the wall clock at harness creation.
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, { now: 1_700_000_000_000 });
+   * ```
+   */
   now?: number;
 }
 /**
-* The in-memory test harness returned by {@link lunoraTest}. Mirrors the first
-* five methods of Convex's `convexTest`: `query` / `mutation` / `action` / `run`
-* / `withIdentity`. All five share one in-memory `node:sqlite` backend, so a
-* write from one method is visible to a read from another (including across a
-* `withIdentity` scope).
-*/
+ * The in-memory test harness returned by {@link lunoraTest}. Mirrors the first
+ * five methods of Convex's `convexTest`: `query` / `mutation` / `action` / `run`
+ * / `withIdentity`. All five share one in-memory `node:sqlite` backend, so a
+ * write from one method is visible to a read from another (including across a
+ * `withIdentity` scope).
+ */
 interface TestHarness {
   /** Run a registered `action` (or an inline `async (context) => …`) against the harness. */
   action: {
@@ -210,41 +324,41 @@ interface TestHarness {
   /** Direct db access at mutation-level (read + write), mirroring `convexTest`'s `run`. */
   run: <R>(function_: InlineMutationFunction<R>) => Promise<R>;
   /**
-  * Controls for the fake in-memory scheduler. Always present; scheduler
-  * jobs only execute when you call `advance(ms)` or `runPending()`.
-  *
-  * - `list()` — snapshot of all pending jobs (enqueue order).
-  * - `advance(ms)` — tick the virtual clock forward by `ms` ms, executing every job
-  * whose `scheduledFor` is now at or below virtual now.
-  * - `runPending()` — execute all currently pending jobs regardless of their scheduled time.
-  *
-  * Scheduled jobs run through the same `runInternal` dispatch as
-  * `ctx.runMutation`, so they share the harness SQLite database.
-  */
+   * Controls for the fake in-memory scheduler. Always present; scheduler
+   * jobs only execute when you call `advance(ms)` or `runPending()`.
+   *
+   * - `list()` — snapshot of all pending jobs (enqueue order).
+   * - `advance(ms)` — tick the virtual clock forward by `ms` ms, executing every job
+   * whose `scheduledFor` is now at or below virtual now.
+   * - `runPending()` — execute all currently pending jobs regardless of their scheduled time.
+   *
+   * Scheduled jobs run through the same `runInternal` dispatch as
+   * `ctx.runMutation`, so they share the harness SQLite database.
+   */
   scheduler: FakeSchedulerControls;
   /**
-  * Subscribe to a registered query (or inline query function) and receive
-  * an async iterable of snapshots. The first value is emitted immediately
-  * (the current query result). Subsequent values are emitted after each
-  * `mutation` / `run` call on this harness completes.
-  *
-  * Subscriptions are table-agnostic — any mutation triggers a re-evaluation.
-  * This matches the harness's single-writer model and keeps the implementation
-  * free of DO machinery.
-  * @example
-  * ```ts
-  * const sub = t.subscribe(list, {});
-  * const first = await sub.next(); // current result
-  * await t.mutation(send, { author: "ada", body: "hi" });
-  * const second = await sub.next(); // updated result
-  * await sub.return(); // unsubscribe
-  * ```
-  *
-  * The iterable is lazy — it never buffers more than one pending result.
-  * If you do not consume fast enough and multiple mutations fire, the next
-  * `next()` call will reflect the most-recent state (intermediate snapshots
-  * are coalesced).
-  */
+   * Subscribe to a registered query (or inline query function) and receive
+   * an async iterable of snapshots. The first value is emitted immediately
+   * (the current query result). Subsequent values are emitted after each
+   * `mutation` / `run` call on this harness completes.
+   *
+   * Subscriptions are table-agnostic — any mutation triggers a re-evaluation.
+   * This matches the harness's single-writer model and keeps the implementation
+   * free of DO machinery.
+   * @example
+   * ```ts
+   * const sub = t.subscribe(list, {});
+   * const first = await sub.next(); // current result
+   * await t.mutation(send, { author: "ada", body: "hi" });
+   * const second = await sub.next(); // updated result
+   * await sub.return(); // unsubscribe
+   * ```
+   *
+   * The iterable is lazy — it never buffers more than one pending result.
+   * If you do not consume fast enough and multiple mutations fire, the next
+   * `next()` call will reflect the most-recent state (intermediate snapshots
+   * are coalesced).
+   */
   subscribe: {
     <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>): TestSubscription<R>;
     <R>(inline: InlineQueryFunction<R>): TestSubscription<R>;
@@ -253,23 +367,97 @@ interface TestHarness {
   withIdentity: (identity: TestIdentity) => TestHarness;
 }
 /**
-* Spin up an in-memory Lunora function harness for `schema`.
-*
-* `lunoraTest(schema)` runs the migrations against a fresh `node:sqlite`
-* database, builds the same `ctx.db` writer the real Durable Object builds (via
-* `@lunora/do`'s `createShardCtxDb`), and returns a harness whose `query` /
-* `mutation` / `action` / `run` execute a registered function's `handler`
-* directly — no Durable Object, no `wrangler`, no network.
-*
-* **v1 surfaces now supported:**
-*
-* - `ctx.fetch` (actions): inject a custom `fetch` via `options.fetch`.
-* - `ctx.scheduler` (mutations + actions): fully functional fake with virtual clock;
-* control via `harness.scheduler.advance(ms)` / `runPending()` / `list()`.
-* - `harness.subscribe(query, args)`: async iterable that re-emits after mutations.
-*
-* **v1 stubs (still throwing):** `ctx.storage`, `ctx.vectors`, `ctx.workflows`.
-* These are clearly documented follow-ups.
-*/
+ * Spin up an in-memory Lunora function harness for `schema`.
+ *
+ * `lunoraTest(schema)` runs the migrations against a fresh `node:sqlite`
+ * database, builds the same `ctx.db` writer the real Durable Object builds (via
+ * `@lunora/do`'s `createShardCtxDb`), and returns a harness whose `query` /
+ * `mutation` / `action` / `run` execute a registered function's `handler`
+ * directly — no Durable Object, no `wrangler`, no network.
+ *
+ * **v1 surfaces now supported:**
+ *
+ * - `ctx.env` (all contexts): inject the validated env via `options.env`; unset it
+ * stays `undefined`, matching the optional `ctx.env?` field.
+ * - `ctx.fetch` (actions): inject a custom `fetch` via `options.fetch`.
+ * - `ctx.scheduler` (mutations + actions): fully functional fake with virtual clock;
+ * control via `harness.scheduler.advance(ms)` / `runPending()` / `list()`.
+ * - `harness.subscribe(query, args)`: async iterable that re-emits after mutations.
+ *
+ * **v1 stubs (still throwing):** `ctx.storage`, `ctx.vectors`, `ctx.workflows`.
+ * These are clearly documented follow-ups.
+ */
 declare const lunoraTest: (schema: TestSchema, options?: LunoraTestOptions) => TestHarness;
-export { type FakeScheduledJob, type FakeSchedulerControls, type FunctionRegistry, type LunoraTestOptions, type ScheduledJobFailure, type SweepOptions, type TestHarness, type TestIdentity, type TestSubscription, lunoraTest };
+/** One sample handed to a {@link Scorer}. */
+interface ScorerSample {
+  /** The reference/gold answer, when the scorer compares against one. */
+  expected?: string;
+  /** The prompt/input that produced the output (for LLM-judge context). */
+  input?: string;
+  /** Arbitrary per-sample metadata carried through. */
+  metadata?: Record<string, unknown>;
+  /** The model/agent output under test. */
+  output: string;
+}
+/** A scorer's verdict: a `[0, 1]` score and an optional human-readable reason. */
+interface ScoreResult {
+  reason?: string;
+  score: number;
+}
+/** A named scorer — returns a `[0, 1]` score (or a {@link ScoreResult}) for a sample. */
+interface Scorer {
+  name: string;
+  score: (sample: ScorerSample) => Promise<ScoreResult | number> | ScoreResult | number;
+}
+/** One dataset case: an input and its optional gold answer/metadata. */
+interface EvalCase {
+  expected?: string;
+  input: string;
+  metadata?: Record<string, unknown>;
+}
+/** The per-case eval result: the produced output plus each scorer's verdict and the mean. */
+interface EvalItemResult {
+  average: number;
+  input: string;
+  output: string;
+  scores: Record<string, ScoreResult>;
+}
+/** The whole eval run: per-case results plus the mean of their averages. */
+interface EvalResult {
+  average: number;
+  items: EvalItemResult[];
+}
+/** Score 1 if the output contains `needle` (case-insensitive unless `caseSensitive`). */
+declare const containsScorer: (needle: string, options?: {
+  caseSensitive?: boolean;
+}) => Scorer;
+/** Score 1 when `pattern` matches the output. */
+declare const regexScorer: (pattern: RegExp, name?: string) => Scorer;
+/** Score 1 when the trimmed output exactly equals the trimmed `expected`. */
+declare const exactMatchScorer: () => Scorer;
+/** Score the fraction of `keywords` (case-insensitive) present in the output. */
+declare const keywordScorer: (keywords: ReadonlyArray<string>) => Scorer;
+/**
+ * An LLM-as-judge scorer. `judge` is INJECTED — a `(prompt) => Promise&lt;string>`
+ * you wire to your model (e.g. via `ctx.ai` / `generateText`), so this module
+ * stays model-agnostic and the judge is mockable in tests. It returns the model's
+ * numeric verdict (`[0, 1]`) plus its reason.
+ */
+declare const llmScorer: (options: {
+  criteria: string;
+  judge: (prompt: string) => Promise<string>;
+  name?: string;
+}) => Scorer;
+/** Run every scorer over one sample (concurrently) → each verdict keyed by name + their mean. */
+declare const scoreSample: (sample: ScorerSample, scorers: ReadonlyArray<Scorer>) => Promise<{
+  average: number;
+  scores: Record<string, ScoreResult>;
+}>;
+/**
+ * Run a dataset through `produce` (e.g. an `agentHarness.run` wrapper returning
+ * the output text) and score each output with `scorers`. Cases run concurrently;
+ * give each its own thread/key inside `produce` if the producer is stateful.
+ * Returns per-case results plus the mean of their averages.
+ */
+declare const evaluate: (cases: ReadonlyArray<EvalCase>, produce: (input: string) => Promise<string> | string, scorers: ReadonlyArray<Scorer>) => Promise<EvalResult>;
+export { type AgentHarness, type AgentHarnessOptions, type AgentRunOverrides, type EvalCase, type EvalItemResult, type EvalResult, type FakeScheduledJob, type FakeSchedulerControls, type FunctionRegistry, type HarnessDispatch, type HarnessMessage, type HarnessThread, type LunoraTestOptions, type ScheduledJobFailure, type ScoreResult, type Scorer, type ScorerSample, type SweepOptions, type TestHarness, type TestIdentity, type TestSubscription, agentHarness, containsScorer, evaluate, exactMatchScorer, finalTurn, keywordScorer, llmScorer, lunoraTest, regexScorer, scoreSample, toolCallTurn };